RFC: --quick mode with static renderer + fallback [DO NOT MERGE]

README.md

@@ -63,6 +63,21 @@ The skill ships with five prompt templates:
 | `/project-recap` | Mental model snapshot for context-switching back to a project |
 | `/fact-check` | Verify accuracy of a review page or plan doc against actual code |
 
+### `--quick` mode (preserves default behavior)
+
+Default behavior is unchanged: full one-shot HTML generation.
+
+When you add `--quick` to `/generate-web-diagram`, the skill uses a static renderer pipeline:
+1. Model emits compact JSON spec
+2. `quick/render-architecture.mjs` assembles HTML
+3. If quick render fails, it falls back to the original full-generation path
+
+Example:
+
+```
+/generate-web-diagram --quick architecture overview of our rpc layer
+```
+
 `/diff-review` is probably the most useful. Run it with no arguments to diff against `main`, or pass any git ref:
 
 ```

SKILL.md

@@ -14,6 +14,17 @@ Generate self-contained HTML files for technical diagrams, visualizations, and d
 
 **Proactive table rendering.** When you're about to present tabular data as an ASCII box-drawing table in the terminal (comparisons, audits, feature matrices, status reports, any structured rows/columns), generate an HTML page instead. The threshold: if the table has 4+ rows or 3+ columns, it belongs in the browser. Don't wait for the user to ask — render it as HTML automatically and tell them the file path. You can still include a brief text summary in the chat, but the table itself should be the HTML page.
 
+## Quick Mode (`--quick`)
+
+Default behavior remains the original full-HTML mechanism. Only use quick mode when the user explicitly includes `--quick`.
+
+Quick mode uses the static renderer at `./quick/render-architecture.mjs`:
+- Model outputs a compact JSON spec (see `./quick/README.md`)
+- Renderer assembles final HTML with reusable CSS/components
+- Faster and cheaper than regenerating full CSS/HTML every run
+
+**Fallback rule (mandatory):** if quick rendering fails, or if the request is not a good fit for the architecture schema, immediately fall back to the original full-HTML workflow in this skill.
+
 ## Workflow
 
 ### 1. Think (5 seconds, not 5 minutes)

prompts/diff-review.md

@@ -3,6 +3,26 @@ description: Generate a visual HTML diff review — before/after architecture co
 ---
 Load the visual-explainer skill, then generate a comprehensive visual diff review as a self-contained HTML page.
 
+## Quick Mode (`--quick`)
+
+Preserve original behavior by default. Only use quick mode if the user includes `--quick`.
+
+If `--quick` is present:
+1. Remove `--quick` from args.
+2. Read `./quick/README.md`.
+3. Build a compact **JSON spec** for the quick architecture renderer that summarizes the diff:
+   - title/subtitle describe the diff scope
+   - gateway cards = changed modules / entry points
+   - pipeline steps = detection, analysis, verification, output
+   - database cards = files/state touched
+   - outputs = good/bad/risks and follow-ups
+   - include KPIs and legend when possible
+4. Save spec to `/tmp/ve-quick-diff-<timestamp>.json`.
+5. Render with:
+   - `node $HOME/.pi/agent/skills/visual-explainer/quick/render-architecture.mjs /tmp/ve-quick-diff-<timestamp>.json ~/.agent/diagrams/<descriptive-name>-diff-quick.html`
+6. Open the resulting HTML and report path.
+7. If quick render fails, or if the request needs full rich diff semantics that don’t fit quick schema, fall back immediately to the full workflow below.
+
 Follow the visual-explainer skill workflow. Read the reference template, CSS patterns, and mermaid theming references before generating. Use a GitHub-diff-inspired aesthetic with red/green before/after panels, but vary fonts and palette from previous diagrams.
 
 **Scope detection** — determine what to diff based on `$1`:

prompts/generate-web-diagram.md

@@ -3,6 +3,21 @@ description: Generate a beautiful standalone HTML diagram and open it in the bro
 ---
 Load the visual-explainer skill, then generate an HTML diagram for: $@
 
+## Quick Mode (`--quick`)
+
+Preserve the original mechanism by default. Only enter quick mode when the user includes the literal `--quick` flag in `$@`.
+
+If `--quick` is present, do this first:
+1. Remove `--quick` from the request text.
+2. Read `./quick/README.md` for the JSON schema and optional rich fields.
+3. Generate a **JSON spec** (not HTML) for the architecture renderer and save it to `/tmp/ve-quick-<timestamp>.json`.
+4. Render HTML using:
+   - `node $HOME/.pi/agent/skills/visual-explainer/quick/render-architecture.mjs /tmp/ve-quick-<timestamp>.json ~/.agent/diagrams/<descriptive-name>-quick.html`
+5. If render succeeds, open the generated HTML in the browser and report the path.
+6. If render fails OR the request is not a good fit for the architecture schema, automatically fall back to the original full HTML generation workflow below.
+
+Without `--quick` (or after fallback), run the original mechanism unchanged.
+
 Follow the visual-explainer skill workflow. Read the reference template and CSS patterns before generating. Pick a distinctive aesthetic that fits the content — vary fonts, palette, and layout style from previous diagrams.
 
 If `surf` CLI is available (`which surf`), consider generating an AI illustration via `surf gemini --generate-image` when an image would genuinely enhance the page — a hero banner, conceptual illustration, or educational diagram that Mermaid can't express. Match the image style to the page's palette. Embed as base64 data URI. See css-patterns.md "Generated Images" for container styles. Skip images when the topic is purely structural or data-driven.

prompts/plan-review.md

@@ -3,6 +3,26 @@ description: Generate a visual HTML plan review — current codebase state vs. p
 ---
 Load the visual-explainer skill, then generate a comprehensive visual plan review as a self-contained HTML page, comparing the current codebase against a proposed implementation plan.
 
+## Quick Mode (`--quick`)
+
+Preserve original behavior by default. Only use quick mode if the user includes `--quick`.
+
+If `--quick` is present:
+1. Remove `--quick` from args.
+2. Read `./quick/README.md`.
+3. Build a compact **JSON spec** for the quick architecture renderer that summarizes plan-vs-code status:
+   - title/subtitle summarize plan scope and confidence
+   - gateway cards = current-state modules and planned touchpoints
+   - pipeline steps = plan parse, code cross-check, gap detection, risk synthesis
+   - database cards = files/config/tests/docs impacted
+   - outputs = matches, gaps, risks, and recommendations
+   - include KPIs and legend
+4. Save spec to `/tmp/ve-quick-plan-<timestamp>.json`.
+5. Render with:
+   - `node $HOME/.pi/agent/skills/visual-explainer/quick/render-architecture.mjs /tmp/ve-quick-plan-<timestamp>.json ~/.agent/diagrams/<descriptive-name>-plan-quick.html`
+6. Open the resulting HTML and report path.
+7. If quick render fails, or if the request requires full plan-review depth beyond quick schema, fall back immediately to the full workflow below.
+
 Follow the visual-explainer skill workflow. Read the reference template, CSS patterns, and mermaid theming references before generating. Use a blueprint/editorial aesthetic with current-state vs. planned-state panels, but vary fonts and palette from previous diagrams.
 
 **Inputs:**

prompts/project-recap.md

@@ -3,6 +3,26 @@ description: Generate a visual HTML project recap — rebuild mental model of a
 ---
 Load the visual-explainer skill, then generate a comprehensive visual project recap as a self-contained HTML page.
 
+## Quick Mode (`--quick`)
+
+Preserve original behavior by default. Only use quick mode if the user includes `--quick`.
+
+If `--quick` is present:
+1. Remove `--quick` from args.
+2. Read `./quick/README.md`.
+3. Build a compact **JSON spec** for the quick architecture renderer that summarizes current project state:
+   - title/subtitle = project and time window
+   - gateway cards = major modules/entry points
+   - pipeline steps = recent activity flow and current execution path
+   - database cards = durable state, logs, and knowledge stores
+   - outputs = what is working, in progress, risky, and next steps
+   - include KPIs and legend
+4. Save spec to `/tmp/ve-quick-recap-<timestamp>.json`.
+5. Render with:
+   - `node $HOME/.pi/agent/skills/visual-explainer/quick/render-architecture.mjs /tmp/ve-quick-recap-<timestamp>.json ~/.agent/diagrams/<descriptive-name>-recap-quick.html`
+6. Open the resulting HTML and report path.
+7. If quick render fails, or if the request needs full recap depth beyond quick schema, fall back immediately to the full workflow below.
+
 Follow the visual-explainer skill workflow. Read the reference template, CSS patterns, and mermaid theming references before generating. Use a warm editorial or paper/ink aesthetic with muted blues and greens, but vary fonts and palette from previous diagrams.
 
 **Time window** — determine the recency window from `$1`:

quick/README.md

@@ -0,0 +1,112 @@
+# static-assembler prototype
+
+A lightweight rendering pipeline for visual-explainer architecture pages.
+
+## Goal
+
+Move repetitive CSS/HTML scaffolding out of the LLM output. The LLM emits a compact JSON spec; this renderer produces the final self-contained HTML.
+
+## Usage
+
+```bash
+node render-architecture.mjs spec.json out.html
+```
+
+## Spec shape
+
+All new fields are **optional** — existing specs work unchanged.
+
+```json
+{
+  "title": "Rho System Architecture",
+  "subtitle": "worker orchestration and memory pipelines",
+  "theme": "terracotta",
+
+  "kpis": [
+    { "value": "41s", "label": "Avg render time", "tone": "green", "delta": "↓75% vs v1" },
+    { "value": "880", "label": "LLM tokens out",  "tone": "teal",  "delta": "↓89% vs v1" },
+    { "value": "5",   "label": "Benchmark runs",  "tone": "accent" }
+  ],
+
+  "legend": [
+    { "label": "no-llm", "tone": "teal" },
+    { "label": "llm",    "tone": "green" },
+    { "label": "db",     "tone": "accent" }
+  ],
+
+  "inputLabel": "Input Sources",
+  "inputSources": [
+    { "icon": "🖥️", "label": "Terminal" },
+    { "icon": "📨", "label": "Email" }
+  ],
+
+  "gateway": {
+    "label": "Gateway Layer",
+    "cards": [
+      {
+        "title": "CLI Router",
+        "desc": "Dispatches user tasks to skills and tools.",
+        "tags": ["fish shell", "tmux"]
+      }
+    ]
+  },
+
+  "pipeline": {
+    "label": "Processing Pipeline",
+    "steps": [
+      { "name": "Parse",   "detail": "Intent extraction",       "kind": "no-llm" },
+      { "name": "Reason",  "detail": "LLM planning",            "kind": "llm" },
+      { "name": "Persist", "detail": "Write `brain.jsonl`",     "kind": "db" }
+    ]
+  },
+
+  "database": {
+    "label": "Storage Layer",
+    "cards": [
+      {
+        "title": "brain.jsonl",
+        "desc": "Durable memories and tasks",
+        "tags": ["JSONL", "append-only"]
+      }
+    ]
+  },
+
+  "outputs": [
+    {
+      "label": "User Surfaces",
+      "blurb": "Everything the user sees or hears directly.",
+      "items": ["CLI", "HTML diagrams", "notifications"]
+    },
+    { "label": "Automation",   "items": ["heartbeats", "reminders", "subagents"] },
+    { "label": "Observability","items": ["logs", "metrics", "artifacts"] }
+  ],
+
+  "calloutTitle": "Invariant",
+  "callout": "All automation should remain deterministic and verifiable.",
+  "generatedAt": "2026-02-26T00:00:00Z"
+}
+```
+
+### Optional rich fields
+
+| Field | Type | Where | Description |
+|---|---|---|---|
+| `kpis` | `[{value, label, tone?, delta?}]` | top-level | KPI strip rendered under subtitle |
+| `legend` | `[{label, tone}]` | top-level | Compact badge row (e.g. pipeline kind key) |
+| `gateway.cards[].tags` | `string[]` | gateway/database cards | Pill badges shown below desc |
+| `database.cards[].tags` | `string[]` | gateway/database cards | Pill badges shown below desc |
+| `outputs[].blurb` | `string` | output sections | Short paragraph under section label |
+
+### Inline code formatting
+
+Wrap text in backticks in any textual field (`desc`, `detail`, `blurb`, `callout`, `items[]`) to produce styled `<code>` spans. HTML is safely escaped before conversion — no XSS risk.
+
+Example: `"detail": "Writes to \`brain.jsonl\`"` → renders as `<code>brain.jsonl</code>`.
+
+## Themes
+
+`theme` supports:
+- `terracotta`
+- `teal`
+- `rose`
+- `blueprint`