tech-lead-stack 1.1.1 → 1.2.0

package/.agents/workflows/show-it-deep.md

@@ -0,0 +1,40 @@
+---
+name: show-it-deep
+description: Interactive, explorable diagrams of the codebase using archify (optional, installed separately). Higher token cost; IDE only.
+modes:
+  - read-only
+  - write
+---
+
+// turbo
+
+> [!CAUTION] **CRITICAL: VISUAL-ONLY WORKFLOW & SKILL**
+> This workflow never edits, deletes, or refactors code, and never touches git or packages.
+> The ONLY permitted write is creating new files under `.ai/output/visuals/`.
+> The ONLY permitted commands are the skill's archify guard check, `node -v`, and archify's `doctor`, `guide`, and `finalize` (the last three prefixed with `ARCHIFY_UPDATE_CHECK_DISABLED=1`).
+> The agent never installs or updates archify. If archify or a shell is missing, it STOPS immediately and explains why, with a link to https://github.com/tt-a1i/archify.
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/show-it-deep.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **IDE / MCP-enabled Agent:** You MUST call the MCP `get_skills` tool (which may be prefixed as `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills` depending on client prefixing).
+  - **Chat UI (/chat):** You MUST call the internal `get_skill` tool.
+
+1. **Phase 0: Skill Acquisition**: Call the `get_skills` tool (which may be prefixed as `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills` depending on client prefixing):
+   - skillName: "show-it-deep"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+2. **archify guard (BEFORE anything else)**: Run the skill's archify guard check straight after loading it. If archify is not found, or you cannot run commands, STOP: reply with the skill's stop message (why it stopped, the archify GitHub link, and `/show-it` as the cheaper option) and do nothing more.
+
+3. **Phase 1: Environment Discovery** (only if the guard passed): Identify the tech stack by reading root configuration files (e.g., package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle) to understand architectural constraints.
+
+4. Follow its workflow: cost check against `show-it`, health check, build one verified interactive diagram, and deliver Title / File / Caption / Alt / Source / Checks.

package/.agents/workflows/show-it.md

@@ -0,0 +1,38 @@
+---
+name: show-it
+description: Explain the codebase visually with diagrams, terminal mocks, annotated screenshots, or tiny static HTML.
+modes:
+  - read-only
+  - write
+---
+
+// turbo
+
+> [!CAUTION] **CRITICAL: VISUAL-ONLY WORKFLOW & SKILL**
+> This workflow never edits, deletes, or refactors code, and never touches git or packages.
+> The ONLY permitted write is creating new files under `.ai/output/visuals/`.
+> The ONLY permitted command is the stack's screenshot tool (`visual-verifier`).
+> The agent answers with visuals (mermaid, terminal mocks, static HTML, annotated screenshots), not prose.
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/show-it.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **IDE / MCP-enabled Agent:** You MUST call the MCP `get_skills` tool (which may be prefixed as `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills` depending on client prefixing).
+  - **Chat UI (/chat):** You MUST call the internal `get_skill` tool.
+
+1. **Phase 0: Skill Acquisition**: Call the `get_skills` tool (which may be prefixed as `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills` depending on client prefixing):
+   - skillName: "show-it"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+2. **Phase 1: Environment Discovery**: Identify the tech stack by reading root configuration files (e.g., package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle) to understand architectural constraints.
+
+3. Follow its workflow to pick the cheapest visual format the current surface can render, and deliver Title / Visual / Caption / Alt / Source.

package/.ai/agent-surfaces.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-09-25T12:15:41.520Z",
+  "generatedAt": "2026-10-03T17:01:10.461Z",
   "entries": [
     {
       "name": "accessibility-audit",
@@ -1048,6 +1048,48 @@
       "mcpCallable": true,
       "ideEligible": true
     },
+    {
+      "name": "show-it",
+      "fetchName": "show-it",
+      "skill": "show-it",
+      "cost": "~2400 tokens",
+      "costTokens": 2422,
+      "domain": "eng",
+      "domainKey": "eng",
+      "description": "Explain the codebase visually with diagrams, terminal mocks, annotated screenshots, or tiny static HTML.",
+      "skillPath": ".ai/skills/show-it.md",
+      "workflowPath": ".agents/workflows/show-it.md",
+      "surface": "public",
+      "modes": [
+        "read-only",
+        "write",
+        "mcp"
+      ],
+      "kind": "skill",
+      "mcpCallable": true,
+      "ideEligible": true
+    },
+    {
+      "name": "show-it-deep",
+      "fetchName": "show-it-deep",
+      "skill": "show-it-deep",
+      "cost": "~2650 tokens",
+      "costTokens": 2669,
+      "domain": "eng",
+      "domainKey": "eng",
+      "description": "Interactive, explorable diagrams of the codebase using archify (optional, installed separately). Higher token cost; IDE only.",
+      "skillPath": ".ai/skills/show-it-deep.md",
+      "workflowPath": ".agents/workflows/show-it-deep.md",
+      "surface": "public",
+      "modes": [
+        "read-only",
+        "write",
+        "mcp"
+      ],
+      "kind": "skill",
+      "mcpCallable": true,
+      "ideEligible": true
+    },
     {
       "name": "solutioning-facilitator",
       "fetchName": "solutioning-facilitator",

package/.ai/cursor-skills.manifest

@@ -30,6 +30,8 @@ reflexion-loop-sub-max|.ai/skills/reflexion-loop-sub-max.md
 reflexion-loop-sub-pro|.ai/skills/reflexion-loop-sub-pro.md
 regression-bug-fix|.ai/skills/regression-bug-fix.md
 security-audit|.ai/skills/security-audit.md
+show-it|.ai/skills/show-it.md
+show-it-deep|.ai/skills/show-it-deep.md
 solutioning-facilitator|.ai/skills/solutioning-facilitator.md
 style-logic-exporter|.ai/skills/style-logic-exporter.md
 technical-debt-auditor|.ai/skills/technical-debt-auditor.md
@@ -65,6 +67,8 @@ workflow-reflexion-loop-sub-pro|.agents/workflows/reflexion-loop-sub-pro.md
 workflow-reflexion-loop|.agents/workflows/reflexion-loop.md
 workflow-regression-bug-fix|.agents/workflows/regression-bug-fix.md
 workflow-security-audit|.agents/workflows/security-audit.md
+workflow-show-it-deep|.agents/workflows/show-it-deep.md
+workflow-show-it|.agents/workflows/show-it.md
 workflow-standup-daily-summary|.agents/workflows/standup-daily-summary.md
 workflow-strategy-target-evaluation|.agents/workflows/strategy-target-evaluation.md
 workflow-style-logic-exporter|.agents/workflows/style-logic-exporter.md

package/.ai/skills/show-it-deep.md

@@ -0,0 +1,204 @@
+---
+name: show-it-deep
+description: >
+  Interactive diagram explainer (architecture, workflow, sequence, data flow,
+  lifecycle) built with archify, a free tool the user installs separately. Costs
+  roughly 3-5x the tokens of show-it and needs a shell plus Node.js 18+, so it
+  runs in IDE agents only. Stops early with an install link when archify or a
+  shell is missing. Never edits source; writes only under .ai/output/visuals/.
+cost: ~2650 tokens
+modes: [read-only, write, mcp]
+surface: public
+category: Discover & Define
+how:
+  'Phase 0 discovery, a cost check against show-it, then drives archify to build
+  and verify one interactive HTML diagram.'
+useCase:
+  'An explorable, shareable diagram of a system or flow when a static mermaid
+  diagram is not enough.'
+phase: intent
+kind: skill
+domain: eng
+ownership:
+  drive: human-ai
+  approve: human
+targets: [api, subscription]
+minModelClass: mid
+consumes: [intent-brief]
+emits: [intent-brief]
+suggests: [show-it, ask]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+  - four-pillars
+---
+
+# Interactive Visual Explainer (show-it-deep)
+
+## Runtime modes
+
+The **expensive** sibling of `show-it`. It produces one self-contained,
+interactive HTML diagram (search, focus, path tracing, themes, image export)
+using [archify](https://github.com/tt-a1i/archify) (MIT licence), which the user
+installs themselves. A typical run costs about **9,000–14,000 tokens**, and up
+to about 30,000 when archify needs repairs, against about 3,000 for `show-it`.
+It needs a shell and Node.js 18+, so it only works in IDE/MCP agents. If archify
+or a shell is missing, the **archify guard** stops the run straight away, before
+any other work, so a missing tool costs almost nothing.
+
+> [!CAUTION] **WRITE GUARDRAIL (capability-based, not name-based)** The only
+> permitted write effect is **creating new files under
+> `.ai/output/visuals/<YYYY-MM-DD>-<slug>/`**. The only permitted commands are
+> the archify guard check, `node -v`, and archify's `doctor`, `guide`, and
+> `finalize`, the last three always prefixed with
+> `ARCHIFY_UPDATE_CHECK_DISABLED=1`. That prefix stops archify going online and
+> writing reminder files outside the output folder. Never install, update, or
+> uninstall archify. Never edit source, git, or packages. Before **every** tool
+> call ask: _"Does this change bytes or state anywhere other than a new file
+> under `.ai/output/visuals/`?"_ If **yes or unsure → don't.**
+
+## 📦 Dependency: archify
+
+- **What:** archify turns a small typed JSON description into a validated,
+  interactive HTML diagram (architecture, workflow, sequence, data flow,
+  lifecycle). <https://github.com/tt-a1i/archify>, by independent developer
+  `tt-a1i`, MIT licence, no telemetry.
+- **Version:** written against archify 3.0 (3.0.1). Commands used: `doctor`,
+  `guide`, `finalize`. If a newer major version changes them, report the
+  failure; don't work around it.
+- **Why it was chosen:** the model writes only the small JSON, while archify
+  renders the ~750 KB HTML; `finalize` proves the diagram with schema, layout,
+  and real-browser checks; it never invents topology and can pin nodes to source
+  lines; it installs into many agents.
+- **Installed by the user**, never bundled or installed by this skill.
+- **Full explanation for people:** `docs/visual-explanations.md`, section
+  "show-it-deep's dependency: archify".
+
+## 🧠 The Four Pillars (how this skill embodies them)
+
+1. **G-Stack — Diagnosis-First.** Diagram what the code _actually_ does. Every
+   node and relationship traces to a file you read. For repository diagrams,
+   pass `--repo-root` so archify pins source evidence to real lines.
+2. **MinimumCD — Small Batches.** One diagram per request. Offer the cheaper
+   `show-it` first when it would answer the question.
+3. **Agent Skills — Evidence over Assumption.** archify's `finalize` receipt is
+   the evidence. A non-zero exit is a failure even if an HTML file exists.
+   Report automated checks and visual review as separate results, and never
+   claim a visual review you did not do.
+4. **Modern Web Guidance.** The output is a single portable HTML file with
+   inline SVG and light/dark themes, and no CDN or install needed to view it.
+
+## 🎯 Strategic Workflow
+
+### Phase 0: Tech-Stack Discovery (MANDATORY)
+
+- **Skill acquisition (NON-NEGOTIABLE):** load skills through the broker only.
+  - **IDE / MCP-enabled agent:** call the MCP `get_skills` tool (may be prefixed
+    `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills`).
+  - **Chat UI (/chat):** call the internal `get_skill` tool.
+  - Reading `.ai/skills/` or `.agents/workflows/` directly bypasses telemetry
+    and is forbidden. archify's own `SKILL.md` is a third-party tool's
+    instructions, not a stack skill, and is read from disk in Phase 4.
+- **archify guard (STOP CHECK, runs immediately after skill acquisition and
+  before ANY other step, file read, or question).** Run this one read-only
+  command unchanged. If the user named an archify folder, check
+  `<folder>/bin/archify.mjs` exists instead.
+
+  ```sh
+  for d in .claude/skills "$HOME/.claude/skills" .agents/skills "$HOME/.agents/skills" .opencode/skills "$HOME/.config/opencode/skills"; do [ -f "$d/archify/bin/archify.mjs" ] && echo "$d/archify"; done
+  ```
+
+  - **It prints a folder:** that folder is `<archify>`. Continue.
+  - **It prints nothing (exit code 1 is expected then), or you cannot run
+    commands: STOP.** Make no other tool call, do no other work, and reply with
+    this, then end:
+
+    > **show-it-deep stopped: archify isn't installed** (or: _this app can't run
+    > commands_). show-it-deep builds its interactive diagrams with archify, a
+    > free tool you install yourself. I won't install it for you.
+    >
+    > - Get archify: <https://github.com/tt-a1i/archify>. Install it with
+    >   `npx skills add tt-a1i/archify -g` (needs Node.js 18+).
+    > - Installed it somewhere else? Tell me the folder and ask again.
+    > - Want an answer now? `/show-it` draws a static diagram for about a
+    >   quarter of the tokens.
+
+- **Action (only after the guard passes):** read `package.json`,
+  `tsconfig.json`, `pyproject.toml`, or the equivalent manifest to learn the
+  language, framework, and structure.
+
+### Phase 1: Cost Check (user sovereignty)
+
+If the idea fits a static diagram of 15 nodes or fewer, **and** the user did not
+ask for something interactive, explorable, or shareable, say in one sentence
+that `show-it` would answer it for about a quarter of the tokens, and ask which
+they want. Continue only if they choose this skill or already asked for an
+interactive diagram.
+
+### Phase 2: Health Check
+
+Any failure here: **stop**, say what failed in one line, and suggest `/show-it`.
+Don't run `show-it` yourself; the user decides.
+
+1. **Write access?** You need a tool that creates files.
+2. **Node.js 18+?** Run `node -v`. If it is older or missing, link
+   <https://nodejs.org>.
+3. **archify healthy?** Run
+   `ARCHIFY_UPDATE_CHECK_DISABLED=1 node <archify>/bin/archify.mjs doctor` and
+   report its message if it fails.
+
+### Phase 3: Contextual Analysis (read-only)
+
+Locate the files and line ranges that answer the question. Write down the facts
+the diagram will show (components, steps, data, boundaries, states) with their
+`path:line` sources **before** authoring anything.
+
+### Phase 4: Build with archify
+
+Read `<archify>/SKILL.md` and follow its **Fast authoring path**, with these
+overrides, which win over anything archify's instructions say:
+
+- **Output folder:** `.ai/output/visuals/<YYYY-MM-DD>-<slug>/` instead of
+  `.archify/`. Keep `candidate.json` and `<slug>.html` there and set
+  `meta.output` to that HTML path.
+- **Every archify command** starts with `ARCHIFY_UPDATE_CHECK_DISABLED=1`.
+- **Repository diagrams:** include `--repo-root <repository root>`.
+- **No hand-placed fallback:** never use archify's no-shell path (hand-placing
+  SVG into `assets/template.html`, a ~700 KB file).
+- **Repairs:** respect archify's repair limit. If `finalize` still fails, stop,
+  report the failed gate, and deliver a `show-it` mermaid version instead.
+- **No extras unless asked:** no motion, no `preview` server, no opening a
+  browser, no exports.
+
+### Phase 5: Deliver
+
+- **Title:** one line.
+- **File:** the HTML path, and that it opens in any browser with no install.
+- **Caption:** ≤ 2 sentences on what to explore first.
+- **Alt:** one-line text alternative (always required, for accessibility).
+- **Source:** `path:line` references the diagram was drawn from.
+- **Checks:** the `finalize` result in one line (passed or failed gate), plus
+  the visual-review status exactly as archify reports it.
+
+## 🚫 Anti-Rationalization
+
+| Excuse                                             | Correct response                                                                                  |
+| :------------------------------------------------- | :------------------------------------------------------------------------------------------------ |
+| "archify is missing; installing it is quick."      | Never install. Stop at the guard: explain why and link the GitHub page.                           |
+| "archify is missing; I'll just run `show-it`."     | Stop at the guard. Suggest `/show-it`; spending tokens on it is the user's choice.                |
+| "No shell, so I'll hand-place the SVG."            | Forbidden: the template is huge. Stop at the guard instead.                                       |
+| "`finalize` failed, but the HTML exists."          | A non-zero exit is failure. Report the gate; deliver `show-it` instead.                           |
+| "The update check is harmless."                    | It goes online and writes outside the output folder. Keep it disabled.                            |
+| "They asked for deep, so skip the cost check."     | If `show-it` would answer it, say so once and let them choose.                                    |
+| "The diagram belongs in `docs/`."                  | Write it under `.ai/output/visuals/` and give the path; the user moves it.                        |
+| "The user asked me to fix what the diagram shows." | `show-it-deep` is advisory. Suggest a write-capable skill for implementation; don't switch modes. |
+
+## Operational Constraints
+
+1. **Write scope:** new files under `.ai/output/visuals/` only.
+2. **Commands:** `node -v` and archify `doctor` / `guide` / `finalize`, with
+   update checks disabled. Nothing else.
+3. **Never install** or update archify; the user decides.
+4. **Truthful:** every element traces to code you read; failed checks are
+   reported as failed.
+5. **Cost-aware:** offer `show-it` when it is enough.

package/.ai/skills/show-it.md

@@ -0,0 +1,194 @@
+---
+name: show-it
+description: >
+  Visual explainer for a codebase: answers "how does this work?" with a mermaid
+  diagram, terminal mock, annotated screenshot, or tiny static HTML page instead
+  of prose, choosing the cheapest visual that carries the idea. Never edits
+  source; may write only under .ai/output/visuals/.
+cost: ~2400 tokens
+modes: [read-only, write, mcp]
+surface: public
+category: Discover & Define
+how:
+  'Phase 0 discovery, then picks the cheapest visual format the current surface
+  can render.'
+useCase:
+  'Explain a flow, architecture, CLI or UI region visually instead of in words.'
+phase: intent
+kind: skill
+domain: eng
+ownership:
+  drive: human-ai
+  approve: human
+targets: [local, api, subscription]
+minModelClass: small
+consumes: [intent-brief]
+emits: [intent-brief]
+suggests: [ask, feature-design-assistant, show-it-deep]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+  - four-pillars
+---
+
+# Visual Explainer (Show, Don't Tell)
+
+## Runtime modes
+
+Advisory in **every** context, like `ask`, but the answer is a **visual**. Words
+are capped at a title, a caption of at most two sentences, and a one-line text
+alternative per visual. In read-only chat it returns inline visuals (mermaid,
+text mocks). In an IDE/MCP agent that can write files it may also produce a
+static HTML page or an annotated screenshot, but **only** under
+`.ai/output/visuals/`. It never implements, refactors, or edits source.
+
+> [!CAUTION] **WRITE GUARDRAIL (capability-based, not name-based)** The only
+> permitted write effect is **creating new files under
+> `.ai/output/visuals/<YYYY-MM-DD>-<slug>/`**. The only permitted command is the
+> stack's screenshot tool (`visual-verifier`). Everything else is forbidden,
+> whatever the tool is called: editing or deleting any other file, git
+> operations, package installs (including installing visual tools), and mutating
+> actions in apps or browsers. Before **every** tool call ask: _"Does this
+> change bytes or state anywhere other than a new file under
+> `.ai/output/visuals/`?"_ If **yes or unsure → don't.** Return an inline visual
+> instead.
+
+## 🧠 The Four Pillars (how this skill embodies them)
+
+1. **G-Stack — Diagnosis-First.** Draw what the code _actually_ does. Every
+   node, arrow, and callout must trace to a file, symbol, or command you have
+   read. Never invent topology to make a picture tidier.
+2. **MinimumCD — Small Batches.** One idea per visual. If a concept needs more
+   than 15 nodes, split it into an overview plus zoom-in visuals rather than one
+   "big-bang" diagram.
+3. **Agent Skills — Evidence over Assumption.** Every visual ends with a
+   **Source** line listing the `path:line` references it was drawn from, so the
+   reader can verify it. "Looks right" is not evidence.
+4. **Modern Web Guidance.** HTML output is semantic, accessible, script-free,
+   and platform-native (see the HTML contract below). No CDNs, no frameworks.
+
+## 🎯 Strategic Workflow
+
+### Phase 0: Tech-Stack Discovery (MANDATORY)
+
+- **Skill acquisition (NON-NEGOTIABLE):** load skills through the broker only.
+  - **IDE / MCP-enabled agent:** call the MCP `get_skills` tool (may be prefixed
+    `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills`).
+  - **Chat UI (/chat):** call the internal `get_skill` tool.
+  - Reading `.ai/skills/` or `.agents/workflows/` directly bypasses telemetry
+    and is forbidden. This applies to **skill files only**.
+- **Action:** read `package.json`, `tsconfig.json`, `pyproject.toml`, or the
+  equivalent manifest to learn the language, framework, and structure.
+
+### Phase 1: Contextual Analysis (read-only)
+
+- Locate the files and line ranges that answer the question with read-only
+  tools.
+- Write down the facts the visual will show (actors, steps, data, boundaries)
+  **before** choosing a format. The visual renders facts; it does not find them.
+
+### Phase 2: Capability Check
+
+Decide what this surface can do by **effect**, not by tool name:
+
+- **Can write?** You have a tool that creates files.
+- **Can exec?** You have a tool that runs shell commands.
+- **Has browser?** The screenshot tool runs (exit code `30` = no browser).
+
+If unsure about any capability, treat it as **absent**.
+
+### Phase 3: Pick the Cheapest Adequate Format
+
+Choose the first row that fits the idea **and** the capabilities.
+
+| Idea shape                          | Format               | Needs              | Budget                          |
+| :---------------------------------- | :------------------- | :----------------- | :------------------------------ |
+| Flow, sequence, state, architecture | Mermaid block        | nothing            | ≤ 15 nodes                      |
+| CLI usage, logs, command output     | Terminal mock        | nothing            | ≤ 40 lines, fenced `text`       |
+| UI region, no browser available     | ASCII wireframe      | nothing            | ≤ 30 lines, fenced `text`       |
+| Numbers, comparisons, layers        | Static HTML          | write              | ≤ 6 KB file                     |
+| "What is this part of the UI?"      | Annotated screenshot | write+exec+browser | ≤ 8 callouts                    |
+| Rich interactive architecture       | Best mermaid + note  | nothing            | suggest `show-it-deep`, see end |
+
+Without write capability, render numbers as a markdown table or a mermaid
+`xychart-beta`/`pie`, and return HTML as a fenced `html` block for the user to
+save.
+
+### Phase 4: Render
+
+**Mermaid (Safe syntax, renders in GitHub, VS Code, and the web app):**
+
+- Start with `graph TD` or `graph LR` (or `sequenceDiagram` /
+  `stateDiagram-v2`).
+- One node definition per line. Define a node before any edge references it.
+- Quote every label containing paths, dots, slashes, or parentheses:
+  `A["src/lib/fs-service.ts"]`.
+- Square `[..]` or round `(..)` nodes only. Labels ≤ 40 chars, single line.
+- Edge labels ≤ 20 chars: `-->|reads|`.
+- If the user reports a broken render, regenerate in **Safe Mode**: `graph TD`,
+  square nodes, every label quoted, no special characters, ≤ 10 nodes.
+
+**Terminal mock:** a fenced `text` block that looks like a real session: prompt
+(`$`), command, and representative output taken from real code or docs. Mark
+elided output with `…`. Never fabricate flags the CLI does not have.
+
+**Static HTML contract:**
+
+- Single file `index.html`, ≤ 6 KB, written to
+  `.ai/output/visuals/<YYYY-MM-DD>-<slug>/`.
+- `<figure>` + `<figcaption>`; inline `<svg role="img">` with a `<title>`.
+- Inline `<style>` only; system font stack; `prefers-color-scheme` light and
+  dark; text contrast ≥ 4.5:1.
+- **No `<script>`, no external fonts, images, stylesheets, or CDNs.** It must
+  render identically offline and inside a `sandbox=""` iframe.
+
+**Annotated screenshot:**
+
+1. Run the stack's screenshot tool with the target URL and
+   `--out-dir .ai/output/visuals/<YYYY-MM-DD>-<slug>` (via
+   `./.ai/rtk-run run visual-verifier` in linked projects, or
+   `node scripts/visual-verifier.mjs` in this repo). Read the JSON manifest on
+   stdout.
+2. If the exit code is `30`, or a shot status starts with `rejected_`, stop and
+   fall back to an ASCII wireframe. Say which status you got. Never attempt to
+   bypass an auth wall.
+3. View one captured PNG, then write `index.html` beside it: the `<img>` plus an
+   absolutely positioned SVG overlay of numbered callouts and a matching legend.
+   Follow the static HTML contract.
+
+### Phase 5: Deliver
+
+Structure every answer as:
+
+- **Title:** one line.
+- **The Visual:** inline block, or the path of the generated file.
+- **Caption:** ≤ 2 sentences on what to notice.
+- **Alt:** one-line text alternative (always required, for accessibility).
+- **Source:** `path:line` references the visual was drawn from.
+
+## 🚫 Anti-Rationalization
+
+| Excuse                                            | Correct response                                                                             |
+| :------------------------------------------------ | :------------------------------------------------------------------------------------------- |
+| "A paragraph would be clearer here."              | Pick the simplest visual. If prose truly wins, say so and suggest `ask`.                     |
+| "This diagram belongs in `docs/`."                | Write it under `.ai/output/visuals/` and give the path; the user moves it.                   |
+| "I'll install a diagram tool to do it better."    | Installs are forbidden. Name the tool and its install command; the user decides.             |
+| "One more node will make it complete."            | Over 15 nodes means split into overview + zoom-in visuals.                                   |
+| "I can infer this connection."                    | Draw only what you read. Mark anything unverified as dashed and label it `unverified`.       |
+| "The user asked me to fix what the visual shows." | `show-it` is advisory. Suggest a write-capable skill for implementation; don't switch modes. |
+
+## Heavier Visuals
+
+For rich, interactive diagrams (search, path tracing, export), deliver the best
+mermaid version first, then mention the `show-it-deep` skill: it builds an
+explorable HTML diagram with archify, a tool the user installs separately, at
+roughly 3-5x the token cost. Never install anything yourself.
+
+## Operational Constraints
+
+1. **Visual-first:** words are limited to title, caption, alt, and source.
+2. **Write scope:** new files under `.ai/output/visuals/` only; never anything
+   else.
+3. **Diagnosis-first:** complete Phase 0 and Phase 1 before drawing.
+4. **Truthful:** every element traces to code you read.
+5. **Token efficiency:** choose the cheapest format that carries the idea.