@heart-of-gold/toolkit 0.1.33 → 0.1.35

package/.claude-plugin/marketplace.json

@@ -15,19 +15,19 @@
       "name": "deep-thought",
       "source": "./plugins/deep-thought",
       "description": "The Answer Computer — reasoning tools for brainstorming, planning, and deep thinking",
-      "version": "0.2.3"
+      "version": "0.2.5"
     },
     {
       "name": "marvin",
       "source": "./plugins/marvin",
       "description": "The Paranoid Android — quality tools for code review, knowledge compounding, and work execution",
-      "version": "0.3.3"
+      "version": "0.3.5"
     },
     {
       "name": "babel-fish",
       "source": "./plugins/babel-fish",
       "description": "Universal Translator — media generation tools for audio, image, and video content",
-      "version": "0.2.1"
+      "version": "0.2.3"
     },
     {
       "name": "quellis",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heart-of-gold/toolkit",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "type": "module",
   "description": "Cross-platform installer for Heart of Gold skills — works with Codex, OpenCode, Pi, Claude Code, and more",
   "bin": {
@@ -11,6 +11,7 @@
     "check:security": "python3 scripts/check-security-regressions.py",
     "check:compat": "python3 scripts/check-harness-compatibility.py",
     "test:pi-guided": "node --test tests/pi-guided-workflows.test.mjs",
+    "test:visualize": "node --test tests/visualize-smart-render.test.mjs",
     "prepublishOnly": "npm run check:publish-safety && npm run check:compat"
   },
   "dependencies": {

package/plugins/babel-fish/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "babel-fish",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Universal Translator — media generation tools for audio, image, video, and visualization",
   "author": {
     "name": "ondrej-svec",

package/plugins/babel-fish/skills/visualize/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: visualize
 description: >
-  Render mind maps and tree visualizations from markdown. Prefer shareable HTML first for brainstorms, plans,
-  architecture docs, and other structured workflow artifacts when share-html infrastructure is configured;
-  otherwise fall back to terminal output for quick local inspection. Works on markdown files or any structured
-  content. Triggers: visualize, mindmap, mind map, show me the structure, draw a map.
+  Create shareable HTML visual artifacts from markdown, plans, architecture docs, brainstorms, and other structured
+  content. Prefer browser-viewable HTML first when it will materially improve clarity or sharing; otherwise fall back
+  to terminal rendering. Triggers: visualize, mindmap, mind map, show me the structure, draw a map, make this clear,
+  make this visual.
 allowed-tools:
   - Read
   - Bash
@@ -14,31 +14,205 @@ allowed-tools:
 
 # Visualize — Babel Fish
 
-Translating structured text into spatial understanding. Because walls of text hide structure that pictures reveal.
+Translating structured text into spatial understanding. The job is not to "turn markdown into HTML." The job is to create a visual artifact that helps a human understand the material faster.
+
+## Mission
+
+Create one clear, polished, shareable visual artifact that:
+- matches the user's actual need
+- feels intentionally designed, not markdown restyled in boxes
+- summarizes before detailing
+- uses browser HTML as the primary medium for substantial artifacts
+- falls back to terminal rendering only when that is the better fit
 
 ## Boundaries
 
 - MAY: read files, generate terminal mind maps, generate temporary HTML artifacts, run renderer/share scripts via bash
 - MAY NOT: modify project files, create persistent files outside temp/output artifacts, install unrelated packages
 
-## The Renderer
+## Core Principle
+
+Do **not** mirror the source document structure one-to-one unless the user explicitly wants a document view.
+
+Instead:
+1. understand the source
+2. decide what the artifact is trying to communicate
+3. choose the visual form that best serves that goal
+4. compress and reshape the content into a stronger visual story
+5. keep raw/source detail secondary or collapsible when possible
+
+HTML should feel like:
+- a dashboard
+- an explainer
+- a roadmap
+- an architecture brief
+- a deliberate mind map
+
+Not like:
+- a markdown page with nicer CSS
+
+## Artifact Families
+
+These are guidance categories for the coding agent. They are not rigid parser outputs.
+
+### `outline`
+Use when the user wants:
+- document structure
+- a reading aid
+- a faithful but polished source-oriented view
+- a safe fallback when a richer artifact is not justified
+
+### `roadmap`
+Use when the source is best understood as:
+- phases
+- priorities
+- sequencing
+- workstreams
+- execution flow
+
+### `architecture`
+Use when the source is best understood as:
+- components
+- boundaries
+- integrations
+- decisions
+- responsibilities
+
+### `mindmap`
+Use only when the content is genuinely:
+- concise
+- branchy
+- idea-oriented
+- better understood spatially than sequentially
+
+### `explainer`
+Use when the artifact should help another human quickly understand:
+- the recommendation
+- tradeoffs
+- key decisions
+- what matters and why
+
+### `mockup`
+Use when the user really wants:
+- product/UI concept visualization
+- believable interface framing
+- layout and interaction-oriented representation
+
+## Style Foundations
+
+Apply these defaults unless the user asks for something else:
+
+- calm, high-contrast visual language
+- restrained accent usage
+- strong hierarchy and generous spacing
+- summary-first information architecture
+- progressive disclosure for dense detail
+- cards, panels, lanes, chips, and callouts over markdown-heavy paragraphs
+- readable max-widths for prose
+- sticky navigation only when it helps, never as the dominant element
+- polished but restrained effects; no gimmicky AI-demo chrome
+
+See also:
+- `docs/architecture/visualize-design-rules.md`
+
+## Rules: Do
+
+- Decide the communication goal before choosing the renderer.
+- Prefer shareable HTML for substantial workflow artifacts when `share-html` is configured.
+- Transform the source into a view model in your head before rendering: summary, priorities, risks, dependencies, decisions, outcomes.
+- Lead with a strong first screen: title, one-line mission, key takeaways, and obvious next scan targets.
+- Convert dense content into visual units where appropriate: cards, grouped sections, lanes, side panels, chips, callouts, expandable details.
+- Use `roadmap` or richer execution-oriented views for plans when that improves understanding.
+- Use `architecture` views for system/design-heavy documents.
+- Keep raw source detail available, but secondary.
+- Briefly explain why you chose the visualization mode when sharing the result.
+
+## Rules: Don't
+
+- Do not treat HTML generation as a markdown restyling task.
+- Do not dump long raw paragraphs into large cards as the main UI.
+- Do not let the table of contents dominate the page.
+- Do not force a mind map onto content that is not naturally branch-shaped.
+- Do not use flashy gradients, glass, shadows, or color noise unless they clearly improve hierarchy.
+- Do not silently guess when the visualization choice is materially ambiguous.
+- Do not create multiple competing artifacts unless the user explicitly asks for comparison.
+
+## Expected Behavior
+
+When invoked, behave like a visual editor, not a format converter.
+
+1. Read the source or infer the source from context.
+2. Decide whether the user needs:
+   - structure comprehension
+   - execution clarity
+   - system understanding
+   - stakeholder explanation
+   - UI/product visualization
+3. Choose the best artifact family.
+4. If uncertain, ask one concise question.
+5. Generate one HTML artifact first when browser rendering will help.
+6. Fall back to terminal rendering when browser/share is unavailable or explicitly not wanted.
+
+If the user says "you decide," choose the clearest non-gimmicky artifact, not the fanciest one.
+
+## Uncertainty Protocol
+
+When the best visualization is not clear, do **not** silently guess if the choice would materially affect usefulness.
+
+Ask **one concise question at a time**:
+- state the decision in plain language
+- offer 2-4 explicit options
+- include a recommended option when you have one
+- keep option labels outcome-focused, not renderer-jargon-first
+
+Good pattern:
+- "Which would help most here?"
+- `Roadmap` — show phases, sequencing, and implementation progress
+- `Outline` — show the document structure clearly
+- `Mind map` — show branching ideas and relationships
+- `Architecture view` — show components, boundaries, and decisions
+
+If the harness supports structured choices, use them.
+If not, use a short plain-text question such as:
+
+```text
+I can visualize this a few different ways. Which would be most useful?
+1. Roadmap — phases and tasks
+2. Outline — document structure
+3. Mind map — branching ideas
+4. Architecture view — components and boundaries
+```
+
+If the user does not care or says "you decide," choose the safest useful mode:
+- default to `outline`
+- use `roadmap` for clearly execution-heavy plans
+- use `architecture` for clearly system-design-heavy docs
+- use `mindmap` only when the artifact is genuinely concise and branchy
 
-A Node.js script that converts markdown headings into colored, spatial Unicode mind maps.
+## Renderers
 
-**Location:** `scripts/render-mindmap/index.js` (relative to this skill's directory)
+Visualization has two implementation layers:
+- `scripts/smart-render.js` — renders one HTML artifact using the mode the coding agent chose, with a safe fallback
+- `scripts/render-mindmap/index.js` — specialized mind-map renderer for branchy content
+
+**Locations:**
+- `scripts/smart-render.js`
+- `scripts/render-mindmap/index.js`
+
+To find the smart renderer path:
 
-**To find the script path**, locate it by searching for `render-mindmap/index.js`:
 ```bash
 # Option 1: Use CLAUDE_PLUGIN_ROOT if available
-SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/visualize/scripts/render-mindmap/index.js"
+SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/visualize/scripts/smart-render.js"
 
 # Option 2: Search for it
-SCRIPT=$(find ~/.claude/plugins -path "*/babel-fish/skills/visualize/scripts/render-mindmap/index.js" 2>/dev/null | head -1)
+SCRIPT=$(find ~/.claude/plugins -path "*/babel-fish/skills/visualize/scripts/smart-render.js" 2>/dev/null | head -1)
 ```
 
-**First run:** If `node_modules/` doesn't exist in the renderer directory, run `npm install` there first:
+First run for the mind-map renderer:
+
 ```bash
-RENDER_DIR=$(dirname "$SCRIPT")
+RENDER_DIR=$(dirname "$SCRIPT")/render-mindmap
 if [ ! -d "$RENDER_DIR/node_modules" ]; then
   (cd "$RENDER_DIR" && npm install --silent)
 fi
@@ -47,21 +221,20 @@ fi
 ## Usage
 
 ```bash
-# Render a markdown file in the terminal
-node "$SCRIPT" path/to/file.md
-
-# With options
-node "$SCRIPT" --no-color path/to/file.md    # plain Unicode, no ANSI
-node "$SCRIPT" --width 120 path/to/file.md   # constrain to 120 columns
-node "$SCRIPT" --depth 2 path/to/file.md     # limit tree depth
-node "$SCRIPT" --json path/to/data.json      # JSON tree input
-node "$SCRIPT" --html /tmp/map.html path/to/file.md  # generate HTML mind map
-
-# Pipe markdown
-echo "# Root\n## Branch A\n## Branch B" | node "$SCRIPT"
+# Generate a safe default HTML visualization for a markdown file
+node "$SCRIPT" path/to/file.md --out /tmp/view.html
+
+# Usually the coding agent should choose the mode from context
+node "$SCRIPT" path/to/file.md --mode roadmap --out /tmp/view.html
+node "$SCRIPT" path/to/file.md --mode outline --out /tmp/view.html
+node "$SCRIPT" path/to/file.md --mode architecture --out /tmp/view.html
+node "$SCRIPT" path/to/file.md --mode mindmap --out /tmp/view.html
+
+# Use the specialized mind-map renderer directly when needed
+node "$(dirname "$SCRIPT")/render-mindmap/index.js" --html /tmp/map.html path/to/file.md
 ```
 
-### Shareable HTML flow
+## HTML Share Flow
 
 Use the helper script when the user wants a browser URL and the share server is already configured:
 
@@ -70,152 +243,113 @@ bash scripts/render-and-share.sh path/to/file.md
 ```
 
 This script:
-1. generates an HTML mind map via the existing renderer
-2. locates `share-html/scripts/publish.sh`
-3. publishes the artifact to the configured local share server
-4. prints the publish JSON so you can return the URL
-
-## Rendering Behavior
-
-- **Auto-depth:** If no `--depth` is specified, the renderer tries depths 3, 2, 1 and picks the deepest that fits the terminal width.
-- **Pruning:** Long labels are truncated with `…`. Nodes with many children show the first few plus `+N more`.
-- **Colors** (via ANSI, visible in Claude Code bash output):
-  - Root: bold white on blue
-  - Depth 1: bold cyan
-  - Depth 2: green
-  - Depth 3: yellow
-  - Depth 4+: dim
-
-## Phase 0 — Determine What to Visualize
-
-First decide whether this should be a browser/shareable HTML view or a quick terminal view.
-
-**Prefer browser/shareable HTML first when:**
-- the source is a brainstorm, plan, architecture doc, or other structured workflow artifact
-- the user asks to open it in a browser
-- the user wants to share the result with another person or device
-- the structure is large enough that browser navigation is more useful than terminal rendering
-- `share-html` is configured
-
-**Prefer terminal rendering when:**
-- share-html is not configured
-- the user explicitly wants a quick terminal-only look
-- the environment is SSH-heavy and the browser/share path is not requested
+1. generates one HTML artifact via the smart renderer
+2. uses the mode the coding agent chose (or the renderer's safe default)
+3. locates `share-html/scripts/publish.sh`
+4. publishes the artifact to the configured local share server
+5. prints the publish result so you can return the URL
 
-When invoked as `/visualize [path]`:
+### Recommended share flow
 
-**If a file path is provided:**
-1. Read the file
-2. If it looks like a brainstorm, plan, architecture doc, or the user asked for browser viewing, try the shareable HTML path first
-3. Otherwise render it directly with the mind map renderer
-
-**If no path is provided:**
-1. Check if there's a recent brainstorm or plan document in the conversation context
-2. If yes: use that document's path
-3. If no: summarize the current conversation topic into a markdown structure with headings, write it to a temp file, then render
+1. Verify or assume the input markdown is ready.
+2. Choose the mode from context.
+3. Run:
+   ```bash
+   bash scripts/render-and-share.sh --mode <chosen-mode> --url-only [file]
+   ```
+4. Read the returned URL from stdout.
+5. Return that URL to the user as the primary result.
+6. Briefly explain what was published and why this mode was chosen.
 
-**If the user says "visualize this" or "show me a mind map":**
-1. Look at what was just discussed or created
-2. Generate an appropriate markdown structure
-3. Render it
+If publishing fails because the share server is not configured, say so clearly and fall back to terminal rendering unless the user wants to stop and run `share-server-setup` first.
 
-## Phase 1 — Render or Share
+## Terminal Rendering
 
-### Path A — Terminal rendering
+Use terminal rendering when:
+- share-html is not configured
+- the user explicitly wants terminal-only output
+- a quick local structural check is more useful than a browser view
 
-**IMPORTANT: Output the mind map in the assistant response text, NOT as raw bash tool output.**
+**IMPORTANT:** Output the mind map in the assistant response text, not as raw bash tool output.
 
 Many harness bash panels truncate long output and wrap wide content, breaking alignment. Instead:
 
-1. Locate the renderer script (see above)
-2. Ensure dependencies are installed
+1. Locate the renderer script.
+2. Ensure dependencies are installed.
 3. Run the renderer with `--no-color`, redirect to a temp file:
    ```bash
    node "$SCRIPT" --no-color [file] > /tmp/mindmap-result.txt 2>&1
    ```
-4. Read `/tmp/mindmap-result.txt`
-5. Output the contents inside a markdown fenced code block in your response text
-6. Clean up: `rm -f /tmp/mindmap-result.txt`
-
-The default mode is **vertical layout** — boxes on main branches, compact leaves, ~40 chars wide.
-
-### Path B — Shareable HTML
-
-For brainstorms, plans, architecture docs, and other structured workflow artifacts, prefer this path first when `share-html` is configured.
-
-1. Verify or assume the input markdown is ready
-2. Run:
+4. Read `/tmp/mindmap-result.txt`.
+5. Output the contents inside a fenced code block.
+6. Clean up:
    ```bash
-   bash scripts/render-and-share.sh --url-only [file]
+   rm -f /tmp/mindmap-result.txt
    ```
-3. Read the returned URL from stdout
-4. Return that URL to the user as the primary result
-5. Briefly explain what was published
-
-If you need more detail for debugging, you may run the helper without `--url-only` and inspect the returned JSON.
-
-If publishing fails because the share server is not configured, say so clearly and fall back to terminal rendering unless the user wants to stop and run `share-server-setup` first.
 
-**For shell usage** (not through assistant panels): terminal rendering can use ANSI colors, or `--horizontal` for the wide spatial layout.
-
-## Phase 2 — Offer Next Steps
-
-After rendering or sharing, briefly note:
-- for terminal mode: "Use `--depth N` to see more/less detail"
-- for terminal mode: "Use `--width N` to fit a different terminal size"
-- for shared HTML: return the final browser URL as the main result and say whether it is local-only or publicly reachable on the user's tailnet
-- if publishing failed due to missing share infrastructure: suggest `share-server-setup`
-- if the source was a brainstorm/plan/architecture doc, offer to continue the workflow (e.g., proceed to `/plan`, `/work`, or implementation)
+The default mode is vertical layout — boxes on main branches, compact leaves, about 40 chars wide.
+
+## Required Output Structure
+
+For substantial HTML artifacts, prefer this structure:
+- strong title + one-line framing
+- summary layer first
+- main visual body second
+- dense details compressed or collapsible
+- source-faithful appendix only if needed
+
+### Plan-oriented artifact target shape
+- title + mission
+- key stats or scope summary
+- priorities / phases / workstreams
+- dependencies / risks / acceptance gates
+- expandable detail or appendix
+
+### Architecture-oriented artifact target shape
+- title + system framing
+- major components / boundaries / integrations
+- key decisions and tradeoffs
+- risks / assumptions
+- supporting detail below
+
+### Explainer target shape
+- title + recommendation
+- why this matters
+- options / comparison / decision
+- what happens next
+- supporting source detail below
+
+## Quality Gates
+
+Before returning a shared HTML result, check mentally:
+- Does the first screen explain the artifact in under 10 seconds?
+- Does this feel designed, not like markdown with nicer CSS?
+- Is hierarchy obvious?
+- Is summary ahead of detail?
+- Are dense sections compressed into meaningful visual units?
+- Is the chosen mode actually appropriate for the content?
+- If this is a plan, does it foreground execution rather than document order?
+- If this is a brainstorm, is it actually branch-shaped enough for a mind map?
+
+If the answer to several of these is no, reconsider the mode or ask the user.
 
 ## Input Formats
 
 ### Markdown (primary)
-Standard markdown with `#` headings defining hierarchy:
-```markdown
-# Root Topic
-## Branch A
-- Detail 1
-- Detail 2
-## Branch B
-### Sub-branch
-- Detail 3
-```
+Standard markdown with `#` headings defining hierarchy.
 
 ### JSON
-Tree structure with `label` and `children`:
-```json
-{
-  "label": "Root",
-  "children": [
-    { "label": "Branch A", "children": [] },
-    { "label": "Branch B", "children": [
-      { "label": "Sub-branch", "children": [] }
-    ]}
-  ]
-}
-```
-
-## Generating Structure from Context
-
-When visualizing conversation context (no file path), create a markdown structure that captures:
-
-**For brainstorm content:**
-- Root = topic
-- Branches = key decisions or themes
-- Leaves = specific choices or details
+Tree structure with `label` and `children`.
 
-**For plan content:**
-- Root = project name
-- Branches = phases
-- Leaves = tasks within each phase
+## Generating Structure From Context
 
-**For general discussion:**
-- Root = main topic
-- Branches = subtopics discussed
-- Leaves = key points or conclusions
+When visualizing conversation context with no file path:
+- brainstorms: root = topic, branches = key themes, leaves = concrete ideas
+- plans: root = project, branches = priorities/phases, leaves = tasks
+- general discussion: root = main topic, branches = subtopics, leaves = key takeaways
 
 Write the generated markdown to `/tmp/mindmap-XXXXXX.md`, render it, then clean up.
 
 ## What Makes This Babel Fish
 
-The Babel Fish translates between languages. This skill translates between *modalities* — from linear text to spatial structure, and now from private working docs to shareable browser views. It makes the invisible visible: the hierarchy, the relationships, the gaps that only show up when you see the shape of the thinking.
+The Babel Fish translates between languages. This skill translates between modalities — from linear text to spatial understanding, and from private working notes to clear shareable browser artifacts.

package/plugins/babel-fish/skills/visualize/scripts/render-and-share.sh

@@ -3,11 +3,12 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 RENDER_DIR="$SCRIPT_DIR/render-mindmap"
-RENDER_SCRIPT="$RENDER_DIR/index.js"
+RENDER_SCRIPT="$SCRIPT_DIR/smart-render.js"
 INPUT_PATH=""
 SLUG=""
 TITLE=""
 ALIAS=""
+MODE="auto"
 KEEP_HTML=0
 URL_ONLY=0
 HTML_OUT=""
@@ -15,15 +16,17 @@ TEMP_DIR=""
 
 usage() {
   cat <<'EOF'
-Usage: render-and-share.sh <markdown-file> [--slug STEM] [--title TITLE] [--alias ALIAS] [--html-out PATH] [--keep-html] [--url-only]
+Usage: render-and-share.sh <markdown-file> [--mode MODE] [--slug STEM] [--title TITLE] [--alias ALIAS] [--html-out PATH] [--keep-html] [--url-only]
 
-Generate an HTML mind map from a markdown file, publish it via share-html, and print the publish JSON.
+Generate a polished HTML visualization from a markdown file, publish it via share-html, and print the publish JSON.
+Use --mode to force a renderer (mindmap, outline, roadmap, architecture, mockup, explainer).
 Use --url-only to print only the final browser URL.
 EOF
 }
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
+    --mode) MODE="$2"; shift 2 ;;
     --slug) SLUG="$2"; shift 2 ;;
     --title) TITLE="$2"; shift 2 ;;
     --alias) ALIAS="$2"; shift 2 ;;
@@ -75,7 +78,7 @@ cleanup() {
 }
 trap cleanup EXIT
 
-node "$RENDER_SCRIPT" --html "$HTML_OUT" "$INPUT_PATH" >/dev/null
+node "$RENDER_SCRIPT" "$INPUT_PATH" --mode "$MODE" --out "$HTML_OUT" >/dev/null
 
 find_share_publish_script() {
   local candidates=(

package/plugins/babel-fish/skills/visualize/scripts/smart-render.js

@@ -0,0 +1,563 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+function parseArgs(args) {
+  const opts = { file: null, out: null, mode: 'auto' };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--out' && i + 1 < args.length) opts.out = args[++i];
+    else if (arg === '--mode' && i + 1 < args.length) opts.mode = args[++i];
+    else if (!arg.startsWith('-')) opts.file = arg;
+  }
+  return opts;
+}
+
+function parseDocument(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  let i = 0;
+  const frontmatter = {};
+  if (lines[0]?.trim() === '---') {
+    i = 1;
+    for (; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (line === '---') { i++; break; }
+      const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+      if (match) frontmatter[match[1]] = match[2].replace(/^"|"$/g, '');
+    }
+  }
+
+  const sections = [];
+  let current = null;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    const heading = line.match(/^(#{1,6})\s+(.+)$/);
+    if (heading) {
+      current = { level: heading[1].length, title: heading[2].trim(), lines: [] };
+      sections.push(current);
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  return { frontmatter, sections, raw: markdown };
+}
+
+function textFromLines(lines) {
+  return lines.join('\n').trim();
+}
+
+function normalizeWhitespace(text) {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+function firstParagraph(lines) {
+  const blocks = textFromLines(lines).split(/\n\s*\n/).map((b) => b.trim()).filter(Boolean);
+  return blocks[0] || '';
+}
+
+function splitBlocks(lines) {
+  return textFromLines(lines).split(/\n\s*\n/).map((b) => b.trim()).filter(Boolean);
+}
+
+function classifyMode(_filePath, _doc, preferredMode) {
+  if (preferredMode && preferredMode !== 'auto') return preferredMode;
+  return 'outline';
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function slugify(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+function renderShell({ title, eyebrow, summary, nav, content, badge = '' }) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(title)}</title>
+<style>
+:root {
+  --bg: #09111f;
+  --bg-2: #0f1a31;
+  --panel: rgba(255,255,255,0.06);
+  --panel-strong: rgba(255,255,255,0.1);
+  --panel-soft: rgba(255,255,255,0.04);
+  --text: #eef2ff;
+  --muted: #b8c0d9;
+  --muted-2: #93a0bf;
+  --border: rgba(255,255,255,0.11);
+  --accent: #7c9cff;
+  --accent-2: #80e0d0;
+  --success: #86efac;
+  --warn: #fbbf24;
+  --danger: #fca5a5;
+  --shadow: 0 24px 80px rgba(0,0,0,0.34);
+  --radius-xl: 28px;
+  --radius-lg: 22px;
+  --radius-md: 16px;
+}
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+html { color-scheme: dark; }
+body {
+  background:
+    radial-gradient(circle at top left, rgba(124,156,255,0.18), transparent 32%),
+    radial-gradient(circle at top right, rgba(128,224,208,0.12), transparent 24%),
+    linear-gradient(180deg, var(--bg-2) 0%, var(--bg) 100%);
+  color: var(--text);
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  line-height: 1.55;
+}
+main { max-width: 1480px; margin: 0 auto; padding: 36px 22px 84px; }
+.hero {
+  display: grid;
+  gap: 18px;
+  padding: 28px;
+  border-radius: 32px;
+  background: linear-gradient(180deg, rgba(255,255,255,0.08), rgba(255,255,255,0.04));
+  border: 1px solid rgba(255,255,255,0.14);
+  box-shadow: var(--shadow);
+  margin-bottom: 24px;
+}
+.eyebrow { color: var(--accent-2); text-transform: uppercase; letter-spacing: 0.16em; font-size: 12px; font-weight: 700; }
+.hero h1 { margin: 0; font-size: clamp(34px, 4vw, 62px); line-height: 1.02; text-wrap: balance; }
+.hero p { margin: 0; max-width: 78ch; color: var(--muted); font-size: 17px; }
+.hero-row { display: flex; flex-wrap: wrap; gap: 12px; align-items: center; }
+.badge, .pill {
+  display: inline-flex; align-items: center; gap: 8px; width: fit-content;
+  padding: 8px 12px; border-radius: 999px; border: 1px solid rgba(255,255,255,0.14);
+  background: rgba(255,255,255,0.06); color: #dce5ff; font-size: 13px;
+}
+.page {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(260px, 320px);
+  gap: 24px;
+  align-items: start;
+}
+main > nav, .rail {
+  position: sticky;
+  top: 16px;
+  align-self: start;
+  display: grid;
+  gap: 14px;
+}
+.panel {
+  padding: 18px;
+  border-radius: var(--radius-lg);
+  background: var(--panel);
+  border: 1px solid var(--border);
+  box-shadow: var(--shadow);
+  backdrop-filter: blur(14px);
+}
+.panel h2, .panel h3 { margin: 0 0 10px; }
+.panel h2 { font-size: 15px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.1em; }
+.nav-links { display: grid; gap: 8px; }
+.nav-links a {
+  display: block; padding: 10px 12px; color: var(--text); text-decoration: none;
+  border-radius: 12px; background: rgba(255,255,255,0.02);
+}
+.nav-links a:hover { background: rgba(255,255,255,0.07); }
+.section {
+  margin-bottom: 20px; padding: 24px; border-radius: var(--radius-xl);
+  background: var(--panel); border: 1px solid var(--border); box-shadow: var(--shadow);
+  backdrop-filter: blur(16px);
+}
+.section h2 { margin: 0 0 14px; font-size: clamp(22px, 2vw, 32px); text-wrap: balance; }
+.section h3 { margin: 0 0 10px; font-size: 18px; }
+.section p, .section li, .section td, .section th { color: var(--muted); font-size: 15px; }
+.section ul { margin: 0; padding-left: 18px; }
+.summary-grid, .stats-grid, .aside-grid, .card-grid, .lane-grid, .dependency-grid { display: grid; gap: 16px; }
+.summary-grid, .stats-grid { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+.card-grid.cols-2, .aside-grid, .dependency-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+.card, .stat, .task-card, .lane, .detail-card, .mini-card {
+  padding: 18px; border-radius: var(--radius-md); background: var(--panel-soft); border: 1px solid var(--border);
+}
+.stat .label, .mini-card .label, .task-meta, .kicker {
+  font-size: 12px; text-transform: uppercase; letter-spacing: 0.11em; color: var(--accent-2);
+}
+.stat .value { margin-top: 8px; font-size: 28px; font-weight: 700; color: var(--text); }
+.stat .hint, .mini-card p { margin: 8px 0 0; color: var(--muted-2); font-size: 13px; }
+.card p, .task-card p, .lane p { margin: 0; }
+.kicker { margin-bottom: 8px; }
+.lane-grid { grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); align-items: start; }
+.lane {
+  padding: 20px;
+  background: linear-gradient(180deg, rgba(255,255,255,0.06), rgba(255,255,255,0.035));
+}
+.lane h3 { margin: 0 0 4px; font-size: 22px; }
+.lane .lane-copy { color: var(--muted-2); margin-bottom: 14px; }
+.stack { display: grid; gap: 12px; }
+.task-card {
+  background: rgba(7, 14, 27, 0.44);
+}
+.task-head { display: flex; gap: 10px; align-items: flex-start; justify-content: space-between; margin-bottom: 10px; }
+.task-id {
+  display: inline-flex; align-items: center; justify-content: center; min-width: 42px;
+  padding: 6px 10px; border-radius: 999px; background: rgba(124,156,255,0.18);
+  color: #dbe5ff; font-weight: 700; font-size: 13px;
+}
+.task-title { margin: 0; font-size: 16px; line-height: 1.35; }
+.task-body { color: var(--muted); font-size: 14px; }
+.chip-row { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 12px; }
+.dependency-row { display: flex; flex-wrap: wrap; gap: 10px; margin-top: 12px; }
+.dependency-pill {
+  display: inline-flex; align-items: center; gap: 10px; padding: 10px 12px; border-radius: 14px;
+  background: rgba(255,255,255,0.05); border: 1px solid rgba(255,255,255,0.08); color: var(--text); font-size: 13px;
+}
+.dependency-pill .arrow { color: var(--accent-2); font-weight: 700; }
+.chip {
+  display: inline-flex; align-items: center; gap: 6px; padding: 6px 10px; border-radius: 999px;
+  background: rgba(255,255,255,0.06); border: 1px solid rgba(255,255,255,0.08); color: var(--muted-2); font-size: 12px;
+}
+.chip.warn { color: #ffd88d; border-color: rgba(251,191,36,0.22); background: rgba(251,191,36,0.08); }
+.chip.good { color: #c7ffd7; border-color: rgba(134,239,172,0.24); background: rgba(134,239,172,0.08); }
+.chip.danger { color: #ffd1d1; border-color: rgba(252,165,165,0.24); background: rgba(252,165,165,0.09); }
+.callout {
+  padding: 18px; border-radius: var(--radius-md); background: rgba(124,156,255,0.09);
+  border: 1px solid rgba(124,156,255,0.18);
+}
+.callout strong { display: block; margin-bottom: 8px; }
+.details { margin-top: 14px; }
+.details summary {
+  cursor: pointer; list-style: none; color: var(--text); font-weight: 600;
+}
+.details summary::-webkit-details-marker { display: none; }
+.details .detail-body { margin-top: 12px; color: var(--muted); font-size: 14px; }
+.raw {
+  white-space: pre-wrap; background: rgba(0,0,0,0.24); padding: 16px; border-radius: 14px; border: 1px solid var(--border);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; color: #d8e1fb;
+}
+.metric-list { display: grid; gap: 12px; }
+.metric-list .mini-card { padding: 14px 16px; }
+.metric-list .value { margin-top: 6px; font-size: 15px; color: var(--text); font-weight: 600; }
+@media (max-width: 1080px) {
+  .page { grid-template-columns: 1fr; }
+  main > nav, .rail { position: static; }
+  .summary-grid, .stats-grid, .card-grid.cols-2, .aside-grid { grid-template-columns: 1fr 1fr; }
+}
+@media (max-width: 720px) {
+  main { padding: 20px 14px 60px; }
+  .hero, .section { padding: 20px; }
+  .summary-grid, .stats-grid, .card-grid.cols-2, .aside-grid { grid-template-columns: 1fr; }
+}
+</style>
+</head>
+<body>
+<main>
+  <section class="hero">
+    <div class="eyebrow">${escapeHtml(eyebrow)}</div>
+    <h1>${escapeHtml(title)}</h1>
+    <p>${escapeHtml(summary || 'Shareable HTML artifact generated by Heart of Gold Visualize.')}</p>
+    <div class="hero-row">
+      ${badge ? `<div class="badge">${escapeHtml(badge)}</div>` : ''}
+    </div>
+  </section>
+  <div class="page">
+    <section>${content}</section>
+    <aside class="rail">${nav}</aside>
+  </div>
+</main>
+</body>
+</html>`;
+}
+
+function renderListBlock(block) {
+  const items = block.split(/\n/).map((line) => line.match(/^\s*[-*]\s+(.+)$/)?.[1]).filter(Boolean);
+  if (!items.length) return null;
+  return `<ul>${items.map((item) => `<li>${escapeHtml(item)}</li>`).join('')}</ul>`;
+}
+
+function renderOutline(doc, title, eyebrow, badge) {
+  const nav = `
+    <div class="panel"><h2>View</h2><div class="metric-list"><div class="mini-card"><div class="label">Mode</div><div class="value">Structured outline</div><p>Safe default when the agent does not force a richer artifact family.</p></div></div></div>
+    <div class="panel"><h2>Sections</h2><div class="nav-links">${doc.sections.map((s, i) => `<a href="#section-${i}">${escapeHtml(s.title)}</a>`).join('')}</div></div>`;
+  const content = doc.sections.map((section, i) => {
+    const blocks = splitBlocks(section.lines).map((block) => renderListBlock(block) || `<p>${escapeHtml(block)}</p>`).join('');
+    return `<article id="section-${i}" class="section"><div class="kicker">Structured View</div><h2>${escapeHtml(section.title)}</h2>${blocks || '<p>No details captured.</p>'}</article>`;
+  }).join('');
+  return renderShell({ title, eyebrow, summary: firstParagraph(doc.sections[0]?.lines || []), nav, content, badge });
+}
+
+function parseTaskSection(section) {
+  const source = textFromLines(section.lines);
+  if (!source) return [];
+  const regex = /- \[( |x)\]\s+\*\*([^*]+)\*\*\s*([\s\S]*?)(?=(?:\s+- \[(?: |x)\]\s+\*\*)|$)/g;
+  const tasks = [];
+  let match;
+  while ((match = regex.exec(source))) {
+    const done = match[1].toLowerCase() === 'x';
+    const bold = normalizeWhitespace(match[2]);
+    const detail = normalizeWhitespace(match[3] || '');
+    const idMatch = bold.match(/^([A-Z][A-Z0-9-]*)\.\s*(.+)$/);
+    const id = idMatch ? idMatch[1] : null;
+    const title = idMatch ? idMatch[2] : bold;
+    const depMatch = detail.match(/\*\*\[depends on ([^\]]+)\]\*\*/i);
+    const parallel = /\*\*\[parallel(?: with [^\]]+)?\]\*\*/i.test(detail);
+    const notInAcceptance = /not in this plan'?s acceptance/i.test(detail);
+    tasks.push({
+      done,
+      id,
+      title,
+      detail,
+      dependency: depMatch ? depMatch[1] : null,
+      parallel,
+      deferred: notInAcceptance,
+    });
+  }
+  return tasks;
+}
+
+function compactDetail(detail) {
+  return detail
+    .replace(/\*\*\[parallel(?: with [^\]]+)?\]\*\*/ig, '')
+    .replace(/\*\*\[depends on ([^\]]+)\]\*\*/ig, 'Depends on $1.')
+    .replace(/\*\*/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function inferTaskIdFromDependency(value) {
+  const match = String(value).match(/([A-Z][A-Z0-9-]*)/);
+  return match ? match[1] : value;
+}
+
+function extractPlanModel(doc) {
+  const byTitle = new Map(doc.sections.map((s) => [s.title.toLowerCase(), s]));
+  const find = (name) => byTitle.get(name.toLowerCase());
+  const prioritySections = doc.sections.filter((s) => /^(P\d+|Deferred)/.test(s.title));
+  const workstreams = prioritySections.map((section) => ({
+    title: section.title,
+    summary: firstParagraph(section.lines),
+    tasks: parseTaskSection(section),
+  }));
+
+  const tasks = workstreams.flatMap((lane) => lane.tasks.map((task) => ({ ...task, lane: lane.title })));
+  const dependencies = tasks.filter((t) => t.dependency).map((t) => ({
+    from: inferTaskIdFromDependency(t.dependency),
+    to: t.id || t.title,
+    lane: t.lane,
+  }));
+  const risksText = firstParagraph(find('Risk Analysis')?.lines || []);
+  const acceptanceText = firstParagraph(find('Acceptance Criteria')?.lines || []);
+  const constraintsText = firstParagraph(find('Constraints and Boundaries')?.lines || []);
+  const proposedSolution = firstParagraph(find('Proposed Solution')?.lines || []);
+  const scope = firstParagraph(find('Scope and Non-Goals')?.lines || []);
+  const rationale = firstParagraph(find('Decision Rationale')?.lines || []);
+
+  return {
+    mission: firstParagraph(doc.sections[0]?.lines || []),
+    problem: firstParagraph(find('Problem Statement')?.lines || []),
+    targetEndState: firstParagraph(find('Target End State')?.lines || []),
+    proposedSolution,
+    scope,
+    rationale,
+    risksText,
+    acceptanceText,
+    constraintsText,
+    workstreams,
+    tasks,
+    dependencies,
+    dependencyCount: dependencies.length,
+    parallelCount: tasks.filter((t) => t.parallel).length,
+    deferredCount: tasks.filter((t) => t.deferred).length,
+  };
+}
+
+function renderTaskCard(task) {
+  const chips = [];
+  chips.push(`<span class="chip ${task.done ? 'good' : 'warn'}">${task.done ? 'Done' : 'Planned'}</span>`);
+  if (task.dependency) chips.push(`<span class="chip">Depends on ${escapeHtml(task.dependency)}</span>`);
+  if (task.parallel) chips.push('<span class="chip good">Parallel</span>');
+  if (task.deferred) chips.push('<span class="chip danger">Deferred</span>');
+  const detail = compactDetail(task.detail);
+  const short = detail.slice(0, 220) + (detail.length > 220 ? '…' : '');
+  return `<article class="task-card">
+    <div class="task-head">
+      <div>
+        <div class="task-meta">${escapeHtml(task.lane || 'Task')}</div>
+        <h4 class="task-title">${task.id ? `<span class="task-id">${escapeHtml(task.id)}</span> ` : ''}${escapeHtml(task.title)}</h4>
+      </div>
+    </div>
+    ${short ? `<p class="task-body">${escapeHtml(short)}</p>` : ''}
+    <div class="chip-row">${chips.join('')}</div>
+    ${detail.length > 220 ? `<details class="details"><summary>Show Full Task Detail</summary><div class="detail-body">${escapeHtml(detail)}</div></details>` : ''}
+  </article>`;
+}
+
+function renderRoadmap(doc, title, badge) {
+  const model = extractPlanModel(doc);
+  const nav = `
+    <div class="panel">
+      <h2>Execution Snapshot</h2>
+      <div class="metric-list">
+        <div class="mini-card"><div class="label">Mode</div><div class="value">Plan dashboard</div><p>Optimized for execution clarity rather than markdown fidelity.</p></div>
+        <div class="mini-card"><div class="label">Workstreams</div><div class="value">${model.workstreams.length}</div></div>
+        <div class="mini-card"><div class="label">Tasks</div><div class="value">${model.tasks.length}</div></div>
+        <div class="mini-card"><div class="label">Dependencies</div><div class="value">${model.dependencyCount}</div></div>
+      </div>
+    </div>
+    <div class="panel">
+      <h2>Jump</h2>
+      <div class="nav-links">
+        <a href="#summary">Summary</a>
+        <a href="#workstreams">Priority Lanes</a>
+        <a href="#acceptance">Acceptance & Risks</a>
+        <a href="#appendix">Source Appendix</a>
+      </div>
+    </div>
+    <div class="panel">
+      <h2>Decision</h2>
+      <p>${escapeHtml(model.rationale || 'Execution-first plan view selected to foreground phases, tasks, and dependencies.')}</p>
+    </div>`;
+
+  const heroStats = [
+    ['Workstreams', model.workstreams.length, 'Priority lanes in this plan'],
+    ['Tasks', model.tasks.length, 'Tracked implementation actions'],
+    ['Parallel', model.parallelCount, 'Tasks marked as parallelizable'],
+    ['Deferred', model.deferredCount, 'Explicitly out of this pass'],
+  ];
+
+  const topTasks = model.tasks.slice(0, 4).map(renderTaskCard).join('');
+  const dependencyHtml = model.dependencies.length
+    ? model.dependencies.slice(0, 10).map((dep) => `<div class="dependency-pill"><span>${escapeHtml(dep.from)}</span><span class="arrow">→</span><span>${escapeHtml(dep.to)}</span><span class="chip">${escapeHtml(dep.lane)}</span></div>`).join('')
+    : '<div class="card"><p>No explicit dependencies extracted.</p></div>';
+  const laneHtml = model.workstreams.map((lane) => {
+    const laneId = slugify(lane.title);
+    const intro = lane.summary || `${lane.tasks.length} task${lane.tasks.length === 1 ? '' : 's'} in this lane.`;
+    return `<section class="lane" id="lane-${laneId}">
+      <div class="kicker">Priority Lane</div>
+      <h3>${escapeHtml(lane.title)}</h3>
+      <p class="lane-copy">${escapeHtml(intro)}</p>
+      <div class="stack">${lane.tasks.length ? lane.tasks.map(renderTaskCard).join('') : '<div class="task-card"><p class="task-body">No parsed tasks found. See appendix for source detail.</p></div>'}</div>
+    </section>`;
+  }).join('');
+
+  const appendixSections = doc.sections.map((section, i) => {
+    const raw = textFromLines(section.lines);
+    const snippet = raw.length > 1400 ? `${raw.slice(0, 1400)}\n…` : raw;
+    return `<article class="detail-card">
+      <div class="kicker">Source Section</div>
+      <h3>${escapeHtml(section.title)}</h3>
+      <p>${escapeHtml(firstParagraph(section.lines) || 'No summary captured.')}</p>
+      <details class="details"><summary>Show Source Detail</summary><div class="detail-body"><div class="raw">${escapeHtml(snippet || 'No detail captured.')}</div></div></details>
+    </article>`;
+  }).join('');
+
+  const content = `
+    <article class="section" id="summary">
+      <div class="kicker">Plan Dashboard</div>
+      <h2>Execution Summary</h2>
+      <div class="callout"><strong>Mission</strong>${escapeHtml(model.mission || 'No summary captured.')}</div>
+      <div class="summary-grid" style="margin-top:16px;">
+        ${heroStats.map(([label, value, hint]) => `<div class="stat"><div class="label">${escapeHtml(label)}</div><div class="value">${escapeHtml(value)}</div><div class="hint">${escapeHtml(hint)}</div></div>`).join('')}
+      </div>
+      <div class="aside-grid" style="margin-top:16px;">
+        <div class="card"><div class="kicker">Problem</div><h3>Why This Exists</h3><p>${escapeHtml(model.problem || 'See source document for full problem framing.')}</p></div>
+        <div class="card"><div class="kicker">Target</div><h3>What Good Looks Like</h3><p>${escapeHtml(model.targetEndState || 'See source document for target end state.')}</p></div>
+      </div>
+    </article>
+
+    <article class="section">
+      <div class="kicker">Plan Strategy</div>
+      <h2>Scope, Approach & Key Moves</h2>
+      <div class="card-grid cols-2">
+        <div class="card"><div class="kicker">Scope</div><p>${escapeHtml(model.scope || 'See source document for scope detail.')}</p></div>
+        <div class="card"><div class="kicker">Approach</div><p>${escapeHtml(model.proposedSolution || 'See source document for solution framing.')}</p></div>
+      </div>
+    </article>
+
+    <article class="section" id="workstreams">
+      <div class="kicker">Priority Lanes</div>
+      <h2>Workstreams & Tasks</h2>
+      <p>The plan is shown as priority lanes so execution order, task grouping, and dependency shape are visible without reading the full markdown in sequence.</p>
+      <div class="lane-grid" style="margin-top:16px;">${laneHtml}</div>
+    </article>
+
+    <article class="section">
+      <div class="kicker">Immediate Scan</div>
+      <h2>Representative Tasks</h2>
+      <div class="card-grid cols-2">${topTasks || '<div class="card"><p>No tasks captured.</p></div>'}</div>
+    </article>
+
+    <article class="section">
+      <div class="kicker">Dependency Shape</div>
+      <h2>Key Sequencing</h2>
+      <p>Dependencies are surfaced explicitly here so the execution order is visible without reading task prose.</p>
+      <div class="dependency-row">${dependencyHtml}</div>
+    </article>
+
+    <article class="section" id="acceptance">
+      <div class="kicker">Execution Guardrails</div>
+      <h2>Acceptance, Risks & Constraints</h2>
+      <div class="card-grid cols-2">
+        <div class="card"><div class="kicker">Acceptance Gates</div><p>${escapeHtml(model.acceptanceText || 'See source markdown for explicit acceptance criteria.')}</p></div>
+        <div class="card"><div class="kicker">Primary Risk</div><p>${escapeHtml(model.risksText || 'No risk summary extracted.')}</p></div>
+        <div class="card"><div class="kicker">Constraint</div><p>${escapeHtml(model.constraintsText || 'No constraint summary extracted.')}</p></div>
+        <div class="card"><div class="kicker">Decision Rationale</div><p>${escapeHtml(model.rationale || 'No rationale summary extracted.')}</p></div>
+      </div>
+    </article>
+
+    <article class="section" id="appendix">
+      <div class="kicker">Source Appendix</div>
+      <h2>Source Detail</h2>
+      <p>The raw plan remains canonical. This appendix keeps source detail available without letting markdown dominate the primary reading path.</p>
+      <div class="stack" style="margin-top:16px;">${appendixSections}</div>
+    </article>`;
+
+  return renderShell({ title, eyebrow: 'Plan Dashboard', summary: model.mission, nav, content, badge });
+}
+
+function renderArchitecture(doc, title, badge) {
+  const nav = `
+    <div class="panel"><h2>View</h2><div class="metric-list"><div class="mini-card"><div class="label">Mode</div><div class="value">Architecture brief</div><p>Focused on boundaries, sections, and key decisions.</p></div></div></div>
+    <div class="panel"><h2>Sections</h2><div class="nav-links">${doc.sections.map((s, i) => `<a href="#section-${i}">${escapeHtml(s.title)}</a>`).join('')}</div></div>`;
+  const cards = doc.sections.slice(0, 6).map((section) => `<div class="card"><div class="kicker">${escapeHtml(section.title)}</div><p>${escapeHtml(firstParagraph(section.lines) || 'See source markdown for detail.')}</p></div>`).join('');
+  const detail = doc.sections.map((section, i) => `<article id="section-${i}" class="section"><div class="kicker">Architecture Section</div><h2>${escapeHtml(section.title)}</h2><p>${escapeHtml(firstParagraph(section.lines) || 'See source markdown for detail.')}</p></article>`).join('');
+  const content = `<article class="section"><div class="kicker">Architecture View</div><h2>System Overview</h2><div class="card-grid cols-2">${cards}</div></article>${detail}`;
+  return renderShell({ title, eyebrow: 'Architecture View', summary: firstParagraph(doc.sections[0]?.lines || []), nav, content, badge });
+}
+
+function renderMindmap(filePath, outFile) {
+  const script = join(dirname(new URL(import.meta.url).pathname), 'render-mindmap', 'index.js');
+  execFileSync('node', [script, '--html', outFile, filePath], { stdio: 'ignore' });
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (!opts.file || !opts.out) {
+    console.error('Usage: smart-render.js <file.md> --out <file.html> [--mode auto|mindmap|outline|roadmap|architecture|mockup|explainer]');
+    process.exit(1);
+  }
+  const markdown = readFileSync(opts.file, 'utf8');
+  const doc = parseDocument(markdown);
+  const mode = classifyMode(opts.file, doc, opts.mode);
+  const title = doc.frontmatter.title || doc.sections[0]?.title || basename(opts.file);
+  const badge = opts.mode && opts.mode !== 'auto'
+    ? `Mode: ${mode}`
+    : 'Mode: outline (safe default — agent may override)';
+
+  if (mode === 'mindmap') {
+    renderMindmap(opts.file, opts.out);
+    return;
+  }
+
+  const html = mode === 'roadmap'
+    ? renderRoadmap(doc, title, badge)
+    : mode === 'architecture'
+      ? renderArchitecture(doc, title, badge)
+      : renderOutline(doc, title, 'Structured View', badge);
+  writeFileSync(opts.out, html, 'utf8');
+}
+
+main();

package/plugins/deep-thought/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "deep-thought",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "The Answer Computer — reasoning tools for brainstorming, planning, architecture design, and deep thinking",
   "author": {
     "name": "ondrej-svec",

package/plugins/marvin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "marvin",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "The Paranoid Android — quality tools for code review, knowledge compounding, and work execution",
   "author": {
     "name": "ondrej-svec",