@vpxa/aikit 0.1.132 → 0.1.134

package/scaffold/dist/definitions/skills/docs.mjs

@@ -1626,6 +1626,25 @@ Icons appear automatically in step nodes. No configuration needed — the viewer
 3. Order by dependency graph — a step should only reference concepts from prior steps
 4. Aim for 5-12 steps per tour (more → split into multiple tours)
 5. Each step teaches exactly ONE concept
+
+### Interactive C4 Architecture Visualization
+
+For architecture documentation, generate interactive C4 diagrams using the shipped **c4-viewer.html** from the \`c4-architecture\` skill.
+
+**Integration with docs skill:**
+- Architecture docs in \`docs/architecture/\` MUST have interactive HTML companions in \`docs/architecture/interactive/\`
+- Use the \`c4-architecture\` skill to generate C4 viewer HTML — it handles JSON schema, ReactFlow rendering, and ELK auto-layout
+- The \`c4-architecture\` skill provides: zoom/pan, node search, detail panels, drag-to-rearrange, and professional styling
+
+**Workflow:**
+1. During Phase 5 (Domain Docs), identify system-level architecture views
+2. For EACH architecture view (system context, container, component):
+  - Generate C4 JSON data: \`{nodes: [{id, label, type, description, technology}], edges: [{from, to, label}]}\`
+  - Use the \`c4-architecture\` skill to render interactive HTML
+  - Save to \`docs/architecture/interactive/{view-name}.html\`
+3. Cross-reference: link from markdown docs to interactive viewers
+
+**CRITICAL:** NEVER generate architecture HTML from scratch. ALWAYS use the shipped c4-viewer.html via the \`c4-architecture\` skill. Hand-crafted HTML will be inconsistent and unprofessional.
 ## Documentation Generation Prompts
 
 Structured LLM prompt templates for generating high-quality documentation. Each produces strict JSON for consistent, parseable output.
@@ -1785,7 +1804,7 @@ graph({ action: "find_nodes" })                  # Full module graph
 4. Output: layers.json used by tour generation
 \`\`\`
 
-### Phase 4 — Generate Tours (2-phase)
+### Phase 4 — Generate Tours (3-phase)
 \`\`\`
 # Phase 4a: Deterministic ranking
 1. Compute node rankings (in-degree, centrality, layer)
@@ -1794,8 +1813,17 @@ graph({ action: "find_nodes" })                  # Full module graph
 
 # Phase 4b: LLM narrative
 1. Apply Tour Generation Prompt with rankings from 4a
-2. Generate both Mermaid tour diagram AND tour JSON data for shipped viewer
-3. Output: docs/tours/getting-started.md + docs/tours/interactive/
+2. Generate Mermaid tour diagram for markdown docs
+3. Generate tour JSON data matching the shipped viewer schema
+4. Output: docs/tours/{name}.md (markdown with Mermaid diagram)
+
+# Phase 4c: Interactive HTML generation (MANDATORY)
+1. For EACH tour generated in 4b:
+  - Read the shipped tour-viewer.html from assets
+  - Inject the tour JSON into the viewer's data block
+  - Save to docs/tours/interactive/{name}.html
+2. These interactive HTML files are MANDATORY — never skip this step
+3. The result is a professional ReactFlow-based tour with step navigation, code panels, and BFS layout
 \`\`\`
 
 ### Phase 5 — Generate Domain Docs (LLM-assisted)
@@ -1807,13 +1835,33 @@ graph({ action: "find_nodes" })                  # Full module graph
 4. Output: docs/architecture/domains/{domain}.md
 \`\`\`
 
-### Phase 6 — Validate & Cross-Reference
+### Phase 6 — Interactive Architecture HTML (MANDATORY)
+\`\`\`
+# Generate professional interactive C4 viewers for architecture documentation
+1. Identify architecture views from Phase 3 (layers) and Phase 5 (domain analysis):
+  - System Context: overall system boundaries and external actors
+  - Container: major deployable units and their relationships
+  - Component: internal structure of key containers
+2. For EACH architecture view:
+  - Generate C4 JSON data (nodes + edges with types and descriptions)
+  - Use the c4-architecture skill to produce interactive HTML with ELK auto-layout
+  - Save to docs/architecture/interactive/{view-name}.html
+3. Add navigation links:
+  - From docs/architecture/overview.md → link to interactive viewers
+  - From tour steps that reference architecture → link to relevant C4 view
+4. Generate documentation hub:
+  - Use the present tool's docs-browser block type to create a navigable index
+  - Include all markdown docs with status indicators and links to interactive companions
+\`\`\`
+
+### Phase 7 — Validate & Cross-Reference
 \`\`\`
 # Ensure consistency
 1. Check all internal doc links resolve
 2. Verify code references still exist (file:line citations)
 3. Cross-reference tour steps with actual files
 4. check({}) to ensure no build breaks
+5. Verify all interactive HTML files open correctly and contain valid JSON data
 \`\`\`
 
 ### Output Structure

package/scaffold/dist/generated/block-docs.mjs

@@ -1,4 +1,4 @@
-const e="| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `metrics` | Metric cards showing label/value pairs with optional trend and status. | `Array<{ label: string; value: string | number; trend?: string | number; status?: string }>` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `tree` | Hierarchical object or name/children tree rendered recursively. | `{ name: string; children?: unknown[] } | Record<string, unknown>` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |\n| `chart` | Structured chart definition rendered as SVG. | `{ chartType: string; data: Record<string, unknown>[]; xKey: string; yKeys: string[] }` |\n| `timeline` | Timeline entries rendered as a vertical sequence of events. | `Array<{ title: string; description?: string; timestamp?: string; status?: string }>` |\n| `checklist` | Checklist items with boolean checked state. | `Array<{label, checked}> | {items: Array<{label, checked}>}` |\n| `comparison` | Side-by-side comparison columns with titled item lists. | `Array<{title, items}> | {columns: Array<{title, items}>}` |\n| `status-board` | Status categories containing labeled status items. | `Array<{category, items}> | {items: Array<{category, items}>}` |\n| `prompt` | Prompt payload rendered through the prompt display helper. | `unknown` |\n| `progress` | Progress bar with current value and optional maximum. | `{label, value, max?} | {items: Array<{label, value, max?, color?}>}` |\n| `viewer-link` | Styled card linking to a standalone interactive viewer. | `{ viewerType: string; label: string; description?: string; url?: string; icon?: string }` |\n| `docs-browser` | Collapsible file tree with markdown content for documentation browsing. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n| `text` | Plain text content rendered through the markdown parser. | `string` |\n| `heading` | Single heading with configurable level from h1 to h6. | `string` |\n| `paragraph` | Single paragraph rendered inside a p tag. | `string` |\n| `separator` | Horizontal rule used to separate adjacent blocks. | `undefined` |\n| `actions` | Action bar containing button and select action definitions. | `Array<{ type: string; id: string; label: string; variant?: string; options?: Array<string | { label: string; value: string }> }>` |\n\n### Usage Examples\n\n#### `viewer-link`\n\n```typescript\n{\n  type: 'viewer-link',\n  value: {\n    viewerType: 'c4',\n    label: 'Open Interactive C4 Diagram',\n    description: 'Drag, zoom, and pan with ELK auto-layout',\n    icon: '🏗️',\n  },\n}\n```\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```",t=`  - type:"markdown" → value: string
+const e="| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `metrics` | Metric cards showing label/value pairs with optional trend and status. | `Array<{ label: string; value: string | number; trend?: string | number; status?: string }>` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `tree` | Hierarchical object or name/children tree rendered recursively. | `{ name: string; children?: unknown[] } | Record<string, unknown>` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |\n| `chart` | Structured chart definition rendered as SVG. | `{ chartType: string; data: Record<string, unknown>[]; xKey: string; yKeys: string[] }` |\n| `timeline` | Timeline entries rendered as a vertical sequence of events. | `Array<{ title: string; description?: string; timestamp?: string; status?: string }>` |\n| `checklist` | Checklist items with boolean checked state. | `Array<{label, checked}> | {items: Array<{label, checked}>}` |\n| `comparison` | Side-by-side comparison columns with titled item lists. | `Array<{title, items}> | {columns: Array<{title, items}>}` |\n| `status-board` | Status categories containing labeled status items. | `Array<{category, items}> | {items: Array<{category, items}>}` |\n| `prompt` | Prompt payload rendered through the prompt display helper. | `unknown` |\n| `progress` | Progress bar with current value and optional maximum. | `{label, value, max?} | {items: Array<{label, value, max?, color?}>}` |\n| `docs-browser` | Documentation file list with inline content previews for chat-safe rendering. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n| `text` | Plain text content rendered through the markdown parser. | `string` |\n| `heading` | Single heading with configurable level from h1 to h6. | `string` |\n| `paragraph` | Single paragraph rendered inside a p tag. | `string` |\n| `separator` | Horizontal rule used to separate adjacent blocks. | `undefined` |\n| `actions` | Action bar containing button and select action definitions. | `Array<{ type: string; id: string; label: string; variant?: string; options?: Array<string | { label: string; value: string }> }>` |\n\n### Usage Examples\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```",t=`  - type:"markdown" → value: string
   - type:"code" → value: string
   - type:"mermaid" → value: string
   - type:"table" → value: Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }
@@ -13,69 +13,9 @@ const e="| Type | Description | Value Shape |\n|------|-------------|-----------
   - type:"status-board" → value: Array<{category, items}> | {items: Array<{category, items}>}
   - type:"prompt" → value: unknown
   - type:"progress" → value: {label, value, max?} | {items: Array<{label, value, max?, color?}>}
-  - type:"viewer-link" → value: { viewerType: string; label: string; description?: string; url?: string; icon?: string }
   - type:"docs-browser" → value: { files: Array<{ path: string; title?: string; content?: string; status?: "current" | "stale" | "missing" }>; title?: string }
   - type:"text" → value: string
   - type:"heading" → value: string
   - type:"paragraph" → value: string
   - type:"separator" → value: undefined
-  - type:"actions" → value: Array<{ type: string; id: string; label: string; variant?: string; options?: Array<string | { label: string; value: string }> }>`,n={present:"| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `metrics` | Metric cards showing label/value pairs with optional trend and status. | `Array<{ label: string; value: string | number; trend?: string | number; status?: string }>` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `tree` | Hierarchical object or name/children tree rendered recursively. | `{ name: string; children?: unknown[] } | Record<string, unknown>` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |\n| `chart` | Structured chart definition rendered as SVG. | `{ chartType: string; data: Record<string, unknown>[]; xKey: string; yKeys: string[] }` |\n| `timeline` | Timeline entries rendered as a vertical sequence of events. | `Array<{ title: string; description?: string; timestamp?: string; status?: string }>` |\n| `checklist` | Checklist items with boolean checked state. | `Array<{label, checked}> | {items: Array<{label, checked}>}` |\n| `comparison` | Side-by-side comparison columns with titled item lists. | `Array<{title, items}> | {columns: Array<{title, items}>}` |\n| `status-board` | Status categories containing labeled status items. | `Array<{category, items}> | {items: Array<{category, items}>}` |\n| `prompt` | Prompt payload rendered through the prompt display helper. | `unknown` |\n| `progress` | Progress bar with current value and optional maximum. | `{label, value, max?} | {items: Array<{label, value, max?, color?}>}` |\n| `viewer-link` | Styled card linking to a standalone interactive viewer. | `{ viewerType: string; label: string; description?: string; url?: string; icon?: string }` |\n| `docs-browser` | Collapsible file tree with markdown content for documentation browsing. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n\n### Usage Examples\n\n#### `viewer-link`\n\n```typescript\n{\n  type: 'viewer-link',\n  value: {\n    viewerType: 'c4',\n    label: 'Open Interactive C4 Diagram',\n    description: 'Drag, zoom, and pan with ELK auto-layout',\n    icon: '🏗️',\n  },\n}\n```\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```",docs:`| Type | Description | Value Shape |
-|------|-------------|-------------|
-| \`markdown\` | Markdown content rendered with the marked parser. | \`string\` |
-| \`code\` | Formatted code block rendered inside pre/code tags. | \`string\` |
-| \`mermaid\` | Mermaid diagram source rendered in a mermaid pre block. | \`string\` |
-| \`table\` | Tabular data rendered from records or explicit headers and rows. | \`Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }\` |
-| \`cards\` | Card grid for titled items with optional body, badge, and status. | \`Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>\` |
-| \`viewer-link\` | Styled card linking to a standalone interactive viewer. | \`{ viewerType: string; label: string; description?: string; url?: string; icon?: string }\` |
-| \`docs-browser\` | Collapsible file tree with markdown content for documentation browsing. | \`{ files: Array<{ path: string; title?: string; content?: string; status?: "current" | "stale" | "missing" }>; title?: string }\` |
-
-### Usage Examples
-
-#### \`viewer-link\`
-
-\`\`\`typescript
-{
-  type: 'viewer-link',
-  value: {
-    viewerType: 'c4',
-    label: 'Open Interactive C4 Diagram',
-    description: 'Drag, zoom, and pan with ELK auto-layout',
-    icon: '🏗️',
-  },
-}
-\`\`\`
-
-#### \`docs-browser\`
-
-\`\`\`typescript
-{
-  type: 'docs-browser',
-  value: {
-    title: 'Project Docs',
-    files: [
-      { path: 'docs/README.md', title: 'Overview', status: 'current' },
-      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },
-    ],
-  },
-}
-\`\`\``,"c4-architecture":`| Type | Description | Value Shape |
-|------|-------------|-------------|
-| \`mermaid\` | Mermaid diagram source rendered in a mermaid pre block. | \`string\` |
-| \`graph\` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | \`{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }\` |
-| \`viewer-link\` | Styled card linking to a standalone interactive viewer. | \`{ viewerType: string; label: string; description?: string; url?: string; icon?: string }\` |
-
-### Usage Examples
-
-#### \`viewer-link\`
-
-\`\`\`typescript
-{
-  type: 'viewer-link',
-  value: {
-    viewerType: 'c4',
-    label: 'Open Interactive C4 Diagram',
-    description: 'Drag, zoom, and pan with ELK auto-layout',
-    icon: '🏗️',
-  },
-}
-\`\`\``};export{e as ALL_BLOCK_DOCS,n as BLOCK_DOCS_BY_SKILL,t as BLOCK_TYPE_LIST};
+  - type:"actions" → value: Array<{ type: string; id: string; label: string; variant?: string; options?: Array<string | { label: string; value: string }> }>`,n={present:"| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `metrics` | Metric cards showing label/value pairs with optional trend and status. | `Array<{ label: string; value: string | number; trend?: string | number; status?: string }>` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `tree` | Hierarchical object or name/children tree rendered recursively. | `{ name: string; children?: unknown[] } | Record<string, unknown>` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |\n| `chart` | Structured chart definition rendered as SVG. | `{ chartType: string; data: Record<string, unknown>[]; xKey: string; yKeys: string[] }` |\n| `timeline` | Timeline entries rendered as a vertical sequence of events. | `Array<{ title: string; description?: string; timestamp?: string; status?: string }>` |\n| `checklist` | Checklist items with boolean checked state. | `Array<{label, checked}> | {items: Array<{label, checked}>}` |\n| `comparison` | Side-by-side comparison columns with titled item lists. | `Array<{title, items}> | {columns: Array<{title, items}>}` |\n| `status-board` | Status categories containing labeled status items. | `Array<{category, items}> | {items: Array<{category, items}>}` |\n| `prompt` | Prompt payload rendered through the prompt display helper. | `unknown` |\n| `progress` | Progress bar with current value and optional maximum. | `{label, value, max?} | {items: Array<{label, value, max?, color?}>}` |\n| `docs-browser` | Documentation file list with inline content previews for chat-safe rendering. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n\n### Usage Examples\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```",docs:"| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `docs-browser` | Documentation file list with inline content previews for chat-safe rendering. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n\n### Usage Examples\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```","c4-architecture":"| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |"};export{e as ALL_BLOCK_DOCS,n as BLOCK_DOCS_BY_SKILL,t as BLOCK_TYPE_LIST};

package/scaffold/generated/block-docs.mjs

@@ -1,13 +1,13 @@
 // AUTO-GENERATED - do not edit manually.
 // Source: packages/server/src/tools/present/block-registry.ts
-// Generated at: 2026-05-10T13:32:40.767Z
+// Generated at: 2026-05-10T17:01:50.322Z
 
-export const ALL_BLOCK_DOCS = "| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `metrics` | Metric cards showing label/value pairs with optional trend and status. | `Array<{ label: string; value: string | number; trend?: string | number; status?: string }>` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `tree` | Hierarchical object or name/children tree rendered recursively. | `{ name: string; children?: unknown[] } | Record<string, unknown>` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |\n| `chart` | Structured chart definition rendered as SVG. | `{ chartType: string; data: Record<string, unknown>[]; xKey: string; yKeys: string[] }` |\n| `timeline` | Timeline entries rendered as a vertical sequence of events. | `Array<{ title: string; description?: string; timestamp?: string; status?: string }>` |\n| `checklist` | Checklist items with boolean checked state. | `Array<{label, checked}> | {items: Array<{label, checked}>}` |\n| `comparison` | Side-by-side comparison columns with titled item lists. | `Array<{title, items}> | {columns: Array<{title, items}>}` |\n| `status-board` | Status categories containing labeled status items. | `Array<{category, items}> | {items: Array<{category, items}>}` |\n| `prompt` | Prompt payload rendered through the prompt display helper. | `unknown` |\n| `progress` | Progress bar with current value and optional maximum. | `{label, value, max?} | {items: Array<{label, value, max?, color?}>}` |\n| `viewer-link` | Styled card linking to a standalone interactive viewer. | `{ viewerType: string; label: string; description?: string; url?: string; icon?: string }` |\n| `docs-browser` | Collapsible file tree with markdown content for documentation browsing. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n| `text` | Plain text content rendered through the markdown parser. | `string` |\n| `heading` | Single heading with configurable level from h1 to h6. | `string` |\n| `paragraph` | Single paragraph rendered inside a p tag. | `string` |\n| `separator` | Horizontal rule used to separate adjacent blocks. | `undefined` |\n| `actions` | Action bar containing button and select action definitions. | `Array<{ type: string; id: string; label: string; variant?: string; options?: Array<string | { label: string; value: string }> }>` |\n\n### Usage Examples\n\n#### `viewer-link`\n\n```typescript\n{\n  type: 'viewer-link',\n  value: {\n    viewerType: 'c4',\n    label: 'Open Interactive C4 Diagram',\n    description: 'Drag, zoom, and pan with ELK auto-layout',\n    icon: '🏗️',\n  },\n}\n```\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```";
+export const ALL_BLOCK_DOCS = "| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `metrics` | Metric cards showing label/value pairs with optional trend and status. | `Array<{ label: string; value: string | number; trend?: string | number; status?: string }>` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `tree` | Hierarchical object or name/children tree rendered recursively. | `{ name: string; children?: unknown[] } | Record<string, unknown>` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |\n| `chart` | Structured chart definition rendered as SVG. | `{ chartType: string; data: Record<string, unknown>[]; xKey: string; yKeys: string[] }` |\n| `timeline` | Timeline entries rendered as a vertical sequence of events. | `Array<{ title: string; description?: string; timestamp?: string; status?: string }>` |\n| `checklist` | Checklist items with boolean checked state. | `Array<{label, checked}> | {items: Array<{label, checked}>}` |\n| `comparison` | Side-by-side comparison columns with titled item lists. | `Array<{title, items}> | {columns: Array<{title, items}>}` |\n| `status-board` | Status categories containing labeled status items. | `Array<{category, items}> | {items: Array<{category, items}>}` |\n| `prompt` | Prompt payload rendered through the prompt display helper. | `unknown` |\n| `progress` | Progress bar with current value and optional maximum. | `{label, value, max?} | {items: Array<{label, value, max?, color?}>}` |\n| `docs-browser` | Documentation file list with inline content previews for chat-safe rendering. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n| `text` | Plain text content rendered through the markdown parser. | `string` |\n| `heading` | Single heading with configurable level from h1 to h6. | `string` |\n| `paragraph` | Single paragraph rendered inside a p tag. | `string` |\n| `separator` | Horizontal rule used to separate adjacent blocks. | `undefined` |\n| `actions` | Action bar containing button and select action definitions. | `Array<{ type: string; id: string; label: string; variant?: string; options?: Array<string | { label: string; value: string }> }>` |\n\n### Usage Examples\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```";
 
-export const BLOCK_TYPE_LIST = "  - type:\"markdown\" → value: string\n  - type:\"code\" → value: string\n  - type:\"mermaid\" → value: string\n  - type:\"table\" → value: Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }\n  - type:\"metrics\" → value: Array<{ label: string; value: string | number; trend?: string | number; status?: string }>\n  - type:\"cards\" → value: Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>\n  - type:\"tree\" → value: { name: string; children?: unknown[] } | Record<string, unknown>\n  - type:\"graph\" → value: { nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }\n  - type:\"chart\" → value: { chartType: string; data: Record<string, unknown>[]; xKey: string; yKeys: string[] }\n  - type:\"timeline\" → value: Array<{ title: string; description?: string; timestamp?: string; status?: string }>\n  - type:\"checklist\" → value: Array<{label, checked}> | {items: Array<{label, checked}>}\n  - type:\"comparison\" → value: Array<{title, items}> | {columns: Array<{title, items}>}\n  - type:\"status-board\" → value: Array<{category, items}> | {items: Array<{category, items}>}\n  - type:\"prompt\" → value: unknown\n  - type:\"progress\" → value: {label, value, max?} | {items: Array<{label, value, max?, color?}>}\n  - type:\"viewer-link\" → value: { viewerType: string; label: string; description?: string; url?: string; icon?: string }\n  - type:\"docs-browser\" → value: { files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }\n  - type:\"text\" → value: string\n  - type:\"heading\" → value: string\n  - type:\"paragraph\" → value: string\n  - type:\"separator\" → value: undefined\n  - type:\"actions\" → value: Array<{ type: string; id: string; label: string; variant?: string; options?: Array<string | { label: string; value: string }> }>";
+export const BLOCK_TYPE_LIST = "  - type:\"markdown\" → value: string\n  - type:\"code\" → value: string\n  - type:\"mermaid\" → value: string\n  - type:\"table\" → value: Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }\n  - type:\"metrics\" → value: Array<{ label: string; value: string | number; trend?: string | number; status?: string }>\n  - type:\"cards\" → value: Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>\n  - type:\"tree\" → value: { name: string; children?: unknown[] } | Record<string, unknown>\n  - type:\"graph\" → value: { nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }\n  - type:\"chart\" → value: { chartType: string; data: Record<string, unknown>[]; xKey: string; yKeys: string[] }\n  - type:\"timeline\" → value: Array<{ title: string; description?: string; timestamp?: string; status?: string }>\n  - type:\"checklist\" → value: Array<{label, checked}> | {items: Array<{label, checked}>}\n  - type:\"comparison\" → value: Array<{title, items}> | {columns: Array<{title, items}>}\n  - type:\"status-board\" → value: Array<{category, items}> | {items: Array<{category, items}>}\n  - type:\"prompt\" → value: unknown\n  - type:\"progress\" → value: {label, value, max?} | {items: Array<{label, value, max?, color?}>}\n  - type:\"docs-browser\" → value: { files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }\n  - type:\"text\" → value: string\n  - type:\"heading\" → value: string\n  - type:\"paragraph\" → value: string\n  - type:\"separator\" → value: undefined\n  - type:\"actions\" → value: Array<{ type: string; id: string; label: string; variant?: string; options?: Array<string | { label: string; value: string }> }>";
 
 export const BLOCK_DOCS_BY_SKILL = {
-  "present": "| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `metrics` | Metric cards showing label/value pairs with optional trend and status. | `Array<{ label: string; value: string | number; trend?: string | number; status?: string }>` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `tree` | Hierarchical object or name/children tree rendered recursively. | `{ name: string; children?: unknown[] } | Record<string, unknown>` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |\n| `chart` | Structured chart definition rendered as SVG. | `{ chartType: string; data: Record<string, unknown>[]; xKey: string; yKeys: string[] }` |\n| `timeline` | Timeline entries rendered as a vertical sequence of events. | `Array<{ title: string; description?: string; timestamp?: string; status?: string }>` |\n| `checklist` | Checklist items with boolean checked state. | `Array<{label, checked}> | {items: Array<{label, checked}>}` |\n| `comparison` | Side-by-side comparison columns with titled item lists. | `Array<{title, items}> | {columns: Array<{title, items}>}` |\n| `status-board` | Status categories containing labeled status items. | `Array<{category, items}> | {items: Array<{category, items}>}` |\n| `prompt` | Prompt payload rendered through the prompt display helper. | `unknown` |\n| `progress` | Progress bar with current value and optional maximum. | `{label, value, max?} | {items: Array<{label, value, max?, color?}>}` |\n| `viewer-link` | Styled card linking to a standalone interactive viewer. | `{ viewerType: string; label: string; description?: string; url?: string; icon?: string }` |\n| `docs-browser` | Collapsible file tree with markdown content for documentation browsing. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n\n### Usage Examples\n\n#### `viewer-link`\n\n```typescript\n{\n  type: 'viewer-link',\n  value: {\n    viewerType: 'c4',\n    label: 'Open Interactive C4 Diagram',\n    description: 'Drag, zoom, and pan with ELK auto-layout',\n    icon: '🏗️',\n  },\n}\n```\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```",
-  "docs": "| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `viewer-link` | Styled card linking to a standalone interactive viewer. | `{ viewerType: string; label: string; description?: string; url?: string; icon?: string }` |\n| `docs-browser` | Collapsible file tree with markdown content for documentation browsing. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n\n### Usage Examples\n\n#### `viewer-link`\n\n```typescript\n{\n  type: 'viewer-link',\n  value: {\n    viewerType: 'c4',\n    label: 'Open Interactive C4 Diagram',\n    description: 'Drag, zoom, and pan with ELK auto-layout',\n    icon: '🏗️',\n  },\n}\n```\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```",
-  "c4-architecture": "| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |\n| `viewer-link` | Styled card linking to a standalone interactive viewer. | `{ viewerType: string; label: string; description?: string; url?: string; icon?: string }` |\n\n### Usage Examples\n\n#### `viewer-link`\n\n```typescript\n{\n  type: 'viewer-link',\n  value: {\n    viewerType: 'c4',\n    label: 'Open Interactive C4 Diagram',\n    description: 'Drag, zoom, and pan with ELK auto-layout',\n    icon: '🏗️',\n  },\n}\n```"
+  "present": "| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `metrics` | Metric cards showing label/value pairs with optional trend and status. | `Array<{ label: string; value: string | number; trend?: string | number; status?: string }>` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `tree` | Hierarchical object or name/children tree rendered recursively. | `{ name: string; children?: unknown[] } | Record<string, unknown>` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |\n| `chart` | Structured chart definition rendered as SVG. | `{ chartType: string; data: Record<string, unknown>[]; xKey: string; yKeys: string[] }` |\n| `timeline` | Timeline entries rendered as a vertical sequence of events. | `Array<{ title: string; description?: string; timestamp?: string; status?: string }>` |\n| `checklist` | Checklist items with boolean checked state. | `Array<{label, checked}> | {items: Array<{label, checked}>}` |\n| `comparison` | Side-by-side comparison columns with titled item lists. | `Array<{title, items}> | {columns: Array<{title, items}>}` |\n| `status-board` | Status categories containing labeled status items. | `Array<{category, items}> | {items: Array<{category, items}>}` |\n| `prompt` | Prompt payload rendered through the prompt display helper. | `unknown` |\n| `progress` | Progress bar with current value and optional maximum. | `{label, value, max?} | {items: Array<{label, value, max?, color?}>}` |\n| `docs-browser` | Documentation file list with inline content previews for chat-safe rendering. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n\n### Usage Examples\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```",
+  "docs": "| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `docs-browser` | Documentation file list with inline content previews for chat-safe rendering. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n\n### Usage Examples\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```",
+  "c4-architecture": "| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |"
 };