@vpxa/aikit 0.1.121 → 0.1.122

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.121",
+  "version": "0.1.122",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",

package/scaffold/dist/definitions/skills.mjs

@@ -4082,6 +4082,93 @@ C4Deployment
   Rel(api, db, "Reads/writes", "JDBC")
 \`\`\`
 
+## Layer Architecture Diagrams
+
+Layer diagrams show how modules group into architectural layers and expose cross-layer dependencies - especially violations (upward or skip-layer calls).
+
+### Layer Map Diagram
+
+Use Mermaid \`graph TD\` with subgraphs. Each layer is a subgraph, color-coded:
+
+| Layer | Color | Stroke |
+|-------|-------|--------|
+| Presentation | \`#0e1a27\` fill | \`#22d3ee\` |
+| Business / Domain | \`#0e1a27\` fill | \`#34d399\` |
+| Data / Persistence | \`#0e1a27\` fill | \`#a78bfa\` |
+| Infrastructure | \`#0e1a27\` fill | \`#fbbf24\` |
+| Cross-cutting | \`#0e1a27\` fill | \`#fb923c\` |
+
+**Example:**
+
+\`\`\`mermaid
+graph TD
+  subgraph Presentation["Presentation Layer"]
+    style Presentation fill:#0e1a27,stroke:#22d3ee
+    Pages["pages/"]
+    Components["components/"]
+  end
+  subgraph Business["Business Layer"]
+    style Business fill:#0e1a27,stroke:#34d399
+    Services["services/"]
+    UseCases["use-cases/"]
+  end
+  subgraph Data["Data Layer"]
+    style Data fill:#0e1a27,stroke:#a78bfa
+    Repos["repositories/"]
+    Models["models/"]
+  end
+
+  Pages --> Services
+  Services --> Repos
+  Components -.->|violation| Models
+\`\`\`
+
+**Violation highlighting**: Use dotted lines with \`|violation|\` labels for cross-layer violations (e.g., Presentation accessing Data directly). Optionally use \`linkStyle\` with \`stroke:red,stroke-dasharray:5\` for emphasis.
+
+### Layer Detection Workflow
+
+1. \`analyze({ aspect: "structure", path: "." })\` - get directory tree
+2. Detect framework (see Framework Layer Heuristics below)
+3. Apply directory-to-layer mapping based on framework heuristics
+4. \`analyze({ aspect: "dependencies", path: "." })\` - get import graph
+5. Identify cross-layer dependencies - flag violations
+6. Generate Mermaid diagram with subgraphs
+
+### Generic Layer Patterns
+
+When no framework is detected, use these directory heuristics:
+
+| Directory Pattern | Layer |
+|-------------------|-------|
+| \`pages/\`, \`views/\`, \`screens/\`, \`ui/\`, \`components/\` | Presentation |
+| \`services/\`, \`use-cases/\`, \`domain/\`, \`logic/\`, \`core/\` | Business |
+| \`models/\`, \`entities/\`, \`repositories/\`, \`db/\`, \`data/\` | Data |
+| \`infra/\`, \`config/\`, \`deploy/\`, \`docker/\`, \`k8s/\` | Infrastructure |
+| \`middleware/\`, \`utils/\`, \`shared/\`, \`common/\`, \`lib/\` | Cross-cutting |
+
+### Framework Layer Heuristics
+
+Detect the framework from \`package.json\`, \`go.mod\`, \`requirements.txt\`, etc., then apply framework-specific layer assignments:
+
+| Framework | Detection | Layer Assignments |
+|-----------|-----------|-------------------|
+| React / Next.js | \`react-dom\` or \`next\` in deps | \`pages/\` -> Presentation, \`components/\` -> Presentation, \`hooks/\` -> Business, \`api/\` -> Backend, \`lib/\` -> Shared |
+| Vue | \`vue\` in deps | \`views/\` -> Presentation, \`components/\` -> Presentation, \`composables/\` -> Business, \`stores/\` -> State |
+| Express | \`express\` in deps | \`routes/\` -> API, \`controllers/\` -> Business, \`middleware/\` -> Cross-cutting, \`models/\` -> Data, \`services/\` -> Business |
+| Go / Gin | \`gin-gonic\` in go.mod | \`cmd/\` -> Entry, \`internal/\` -> Business, \`pkg/\` -> Shared, \`handlers/\` -> API, \`middleware/\` -> Cross-cutting |
+| Django | \`django\` in requirements | \`views.py\` -> API, \`models.py\` -> Data, \`serializers.py\` -> Transform, \`urls.py\` -> Routing, \`services/\` -> Business |
+| Flask | \`flask\` in requirements | \`routes/\` -> API, \`models/\` -> Data, \`services/\` -> Business, \`blueprints/\` -> Modular |
+| Spring Boot | \`spring-boot\` in pom/gradle | \`controllers/\` -> API, \`services/\` -> Business, \`repositories/\` -> Data, \`entities/\` -> Domain |
+| Rails | \`rails\` in Gemfile | \`controllers/\` -> API, \`models/\` -> Data, \`services/\` -> Business, \`views/\` -> Presentation |
+
+**Workflow for framework-aware layer diagrams:**
+
+1. Detect framework from manifest files (\`package.json\`, \`go.mod\`, etc.)
+2. Look up the framework's layer assignment table above
+3. Map each source directory to its assigned layer
+4. Generate the Layer Map Diagram using the mapped subgraphs
+5. Flag any imports that cross more than one layer boundary as violations
+
 ## HTML/SVG Format
 
 For HTML/SVG output, use the design system and template from the references.
@@ -4283,6 +4370,313 @@ Write architecture documentation to \`docs/architecture/\` with naming conventio
 | Developers | All levels as needed |
 | DevOps | Container + Deployment |
 
+## Interactive Architecture Diagrams (React Flow)
+
+When HTML output is requested and the architecture is complex (>10 nodes, multiple layers, or interactive exploration needed), generate a standalone HTML file using React Flow via CDN. This produces zoomable, pannable, collapsible diagrams superior to static SVG.
+
+### Standalone HTML Template
+
+\`\`\`html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8"/>
+  <title>{{DIAGRAM_TITLE}} — C4 Architecture</title>
+  <script src="https://unpkg.com/react@18/umd/react.production.min.js"><\/script>
+  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"><\/script>
+  <script src="https://unpkg.com/@xyflow/react@12/dist/umd/index.js"><\/script>
+  <script src="https://unpkg.com/elkjs@0.9/lib/elk.bundled.js"><\/script>
+  <link rel="stylesheet" href="https://unpkg.com/@xyflow/react@12/dist/style.css"/>
+  <style>
+    body { margin: 0; font-family: system-ui, sans-serif; }
+    .react-flow { width: 100vw; height: 100vh; }
+    .c4-node { padding: 12px 16px; border-radius: 8px; border: 2px solid; min-width: 160px; }
+    .c4-node-label { font-weight: 600; font-size: 14px; }
+    .c4-node-tech { font-size: 11px; opacity: 0.7; margin-top: 4px; }
+    .c4-node-desc { font-size: 12px; margin-top: 6px; max-width: 200px; }
+    .c4-boundary { border: 2px dashed #64748b; border-radius: 12px; padding: 24px; background: rgba(100,116,139,0.05); }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+  <script>
+    // Node data — replace with generated architecture
+    const nodes = {{NODES_JSON}};
+    const edges = {{EDGES_JSON}};
+    // ELK layout then render — see layout section below
+  <\/script>
+</body>
+</html>
+\`\`\`
+
+### Custom Node Types by C4 Category
+
+\`\`\`javascript
+const nodeTypes = {
+  person:    { shape: 'circle',  color: '#60a5fa', icon: '👤' },
+  system:    { shape: 'rect-lg', color: '#a78bfa', border: 'solid' },
+  container: { shape: 'rect-md', color: '#34d399', border: 'solid' },
+  component: { shape: 'rect-sm', color: '#22d3ee', border: 'solid' },
+  boundary:  { shape: 'group',   color: '#64748b', border: 'dashed' },
+  database:  { shape: 'cylinder', color: '#a78bfa', icon: '🗄️' },
+  queue:     { shape: 'rect-md', color: '#fb923c', icon: '📨' },
+  external:  { shape: 'rect-md', color: '#94a3b8', border: 'dotted' },
+};
+// Category colors match HTML/SVG design system above
+\`\`\`
+
+### ELK.js Hierarchical Layout
+
+\`\`\`javascript
+const elkOptions = {
+  'elk.algorithm': 'layered',
+  'elk.direction': 'DOWN',                           // TOP → BOTTOM for C4
+  'elk.spacing.nodeNode': '50',
+  'elk.layered.spacing.nodeNodeBetweenLayers': '80',
+  'elk.edgeRouting': 'ORTHOGONAL',
+  'elk.layered.crossingMinimization.strategy': 'LAYER_SWEEP',
+  'elk.hierarchyHandling': 'INCLUDE_CHILDREN',       // for boundaries/groups
+};
+
+async function layoutWithElk(nodes, edges) {
+  const elk = new ELK();
+  const graph = {
+    id: 'root',
+    children: nodes.map(n => ({
+      id: n.id, width: n.width || 200, height: n.height || 80,
+      ...(n.parentNode && { parentId: n.parentNode }),
+    })),
+    edges: edges.map(e => ({ id: e.id, sources: [e.source], targets: [e.target] })),
+  };
+  const layout = await elk.layout(graph, { layoutOptions: elkOptions });
+  return layout.children.map(child => ({
+    ...nodes.find(n => n.id === child.id),
+    position: { x: child.x, y: child.y },
+  }));
+}
+\`\`\`
+
+### SVG Export from React Flow
+
+When static SVG is needed from an interactive diagram (for embedding in markdown docs or printing):
+
+\`\`\`javascript
+function exportToSVG(nodes, edges, options = {}) {
+  const { padding = 20, fontSize = 12 } = options;
+  const bounds = computeBoundingBox(nodes, padding);
+  const svgParts = [
+    \\\`<svg xmlns="http://www.w3.org/2000/svg" viewBox="\${bounds.viewBox}">\\\`,
+    '<defs><marker id="arrow" markerWidth="10" markerHeight="7" refX="10" refY="3.5" orient="auto"><polygon points="0 0, 10 3.5, 0 7" fill="#64748b"/></marker></defs>',
+  ];
+  // Render boundary groups first (back layer)
+  nodes.filter(n => n.type === 'boundary').forEach(n => {
+    svgParts.push(\\\`<rect x="\${n.position.x}" y="\${n.position.y}" width="\${n.width}" height="\${n.height}" rx="12" fill="none" stroke="#64748b" stroke-dasharray="8 4" stroke-width="2"/>\\\`);
+    svgParts.push(\\\`<text x="\${n.position.x + 12}" y="\${n.position.y + 20}" font-size="13" fill="#64748b">\${n.data.label}</text>\\\`);
+  });
+  // Render edges
+  edges.forEach(e => {
+    const source = nodes.find(n => n.id === e.source);
+    const target = nodes.find(n => n.id === e.target);
+    svgParts.push(\\\`<line x1="\${source.position.x + source.width/2}" y1="\${source.position.y + source.height}" x2="\${target.position.x + target.width/2}" y2="\${target.position.y}" stroke="#64748b" stroke-width="1.5" marker-end="url(#arrow)"/>\\\`);
+    if (e.label) svgParts.push(\\\`<text x="\${(source.position.x + target.position.x)/2 + 60}" y="\${(source.position.y + target.position.y)/2 + 40}" font-size="11" fill="#94a3b8">\${e.label}</text>\\\`);
+  });
+  // Render nodes
+  nodes.filter(n => n.type !== 'boundary').forEach(n => {
+    const color = nodeTypes[n.type]?.color || '#64748b';
+    svgParts.push(\\\`<rect x="\${n.position.x}" y="\${n.position.y}" width="\${n.width || 200}" height="\${n.height || 80}" rx="8" fill="\${color}22" stroke="\${color}" stroke-width="2"/>\\\`);
+    svgParts.push(\\\`<text x="\${n.position.x + 12}" y="\${n.position.y + 24}" font-size="\${fontSize}" font-weight="600" fill="#e2e8f0">\${n.data.label}</text>\\\`);
+    if (n.data.technology) svgParts.push(\\\`<text x="\${n.position.x + 12}" y="\${n.position.y + 42}" font-size="11" fill="#94a3b8">[\${n.data.technology}]</text>\\\`);
+    if (n.data.description) svgParts.push(\\\`<text x="\${n.position.x + 12}" y="\${n.position.y + 60}" font-size="11" fill="#cbd5e1">\${n.data.description}</text>\\\`);
+  });
+  svgParts.push('</svg>');
+  return svgParts.join('\\n');
+}
+\`\`\`
+
+### When to Use React Flow vs Static SVG
+
+| Scenario | Output | Rationale |
+|----------|--------|-----------|
+| >10 components | React Flow HTML | Needs zoom/pan for readability |
+| Multi-layer (≥3 layers) | React Flow HTML | ELK layout handles crossing minimization |
+| Exploration/onboarding | React Flow HTML | Interactive collapse/expand aids learning |
+| Markdown embedding | Static SVG export | Inline in \`.md\` files |
+| Print/PDF | Static SVG export | Fixed layout, no JS needed |
+| Simple (≤5 components) | Static SVG directly | Overhead of React Flow unnecessary |
+| CI/automated docs | Static SVG export | Deterministic, no browser needed |
+
+## Architecture Generation Prompts
+
+Structured LLM prompt templates for generating high-quality architecture documentation. Each prompt produces strict JSON output that feeds into diagram generation.
+
+### Layer Detection Prompt
+
+\`\`\`
+You are a software architecture analyst. Given the following list of file paths from a codebase, identify the architectural layers present.
+
+**File paths:**
+{{FILE_PATHS}}
+
+**Framework context (if detected):**
+{{FRAMEWORK_CONTEXT}}
+
+**Instructions:**
+- Identify 3-7 distinct architectural layers
+- Each layer must have a clear single responsibility
+- Assign file path glob patterns to each layer
+- If a file doesn't fit any layer, assign it to "Core" or "Shared"
+
+**Respond ONLY with a JSON object in this exact format, no additional text:**
+{
+  "layers": [
+    {
+      "id": "layer-id-slug",
+      "name": "Human Readable Name",
+      "description": "Single sentence describing layer responsibility",
+      "filePatterns": ["src/api/**", "src/routes/**"],
+      "color": "#hex-color"
+    }
+  ],
+  "unmatched": ["paths/that/dont/fit/**"]
+}
+\`\`\`
+
+### Component Analysis Prompt
+
+\`\`\`
+You are a software architecture analyst. Analyze this source file and extract its architectural role.
+
+**File:** {{FILE_PATH}}
+**Content:**
+{{FILE_CONTENT}}
+
+**Project context:**
+{{PROJECT_SUMMARY}}
+
+**Respond ONLY with a JSON object:**
+{
+  "summary": "One sentence: what this file does",
+  "technology": "Primary technology/framework used",
+  "category": "frontend|backend|data|infrastructure|messaging|security|external|monitoring",
+  "layer": "Which architectural layer this belongs to",
+  "dependencies": ["module-ids this file imports from"],
+  "exposes": ["exported functions/classes/types"],
+  "complexity": "low|medium|high",
+  "c4Type": "container|component"
+}
+\`\`\`
+
+### Architecture Synthesis Prompt
+
+\`\`\`
+You are a C4 architecture diagram generator. Given analyzed components, their relationships, and layer assignments, produce a complete C4 diagram specification.
+
+**Components:**
+{{COMPONENTS_JSON}}
+
+**Relationships (import edges):**
+{{EDGES_JSON}}
+
+**Layers:**
+{{LAYERS_JSON}}
+
+**Diagram level:** {{LEVEL}} (context|container|component)
+
+**Instructions:**
+- Group components into their layers as boundaries
+- Identify the most important relationships (max 3 per component)
+- Label relationships with the interaction type (calls, subscribes, reads, writes)
+- External systems go outside all boundaries
+- Users/actors are Person type
+
+**Respond ONLY with a JSON object:**
+{
+  "title": "Diagram title",
+  "nodes": [
+    { "id": "unique-id", "type": "person|system|container|component|boundary|database|queue|external", "label": "Display Name", "technology": "Tech stack", "description": "Brief desc", "parent": "boundary-id-or-null", "layer": "layer-id" }
+  ],
+  "edges": [
+    { "id": "edge-id", "source": "node-id", "target": "node-id", "label": "Relationship description", "style": "solid|dashed|dotted" }
+  ],
+  "layoutHints": { "direction": "DOWN|RIGHT", "groupByLayer": true }
+}
+\`\`\`
+
+### Framework Context Addendum Pattern
+
+When a framework is detected, inject its addendum into the Layer Detection and Component Analysis prompts:
+
+\`\`\`markdown
+## {{FRAMEWORK}} Framework Addendum
+(Injected into architecture prompts when {{FRAMEWORK}} is detected)
+
+### Canonical File Roles
+
+| Path Pattern | Role | C4 Type |
+|---|---|---|
+| {{pattern}} | {{role}} | {{type}} |
+
+### Architectural Layers
+
+| Layer ID | Layer Name | What Goes Here |
+|---|---|---|
+| {{layer_id}} | {{name}} | {{description}} |
+
+### Edge Patterns
+- {{pattern 1: e.g., "pages/ → api/ via fetch/tRPC"}}
+- {{pattern 2: e.g., "services/ → repositories/ for data access"}}
+\`\`\`
+
+**Addendum examples to create per framework:**
+- \`next.js\`: pages/app router → API routes → services → DB
+- \`express\`: routes → controllers → services → models
+- \`react-spa\`: pages → components → hooks → api-client → store
+- \`nestjs\`: modules → controllers → providers → entities
+- \`django\`: urls → views → serializers → models → managers
+
+## Architecture Documentation Pipeline
+
+When generating comprehensive architecture documentation, orchestrate this phased approach:
+
+### Phase 1 — Scan (deterministic, no LLM)
+\`\`\`
+analyze({ aspect: "structure", path: "." })        # Directory tree
+analyze({ aspect: "dependencies", path: "." })     # Import graph
+analyze({ aspect: "entry_points", path: "." })     # Entry points (0 in-degree)
+graph({ action: "stats" })                         # Graph size for complexity estimate
+\`\`\`
+
+### Phase 2 — Classify (LLM-assisted)
+1. Apply **Layer Detection Prompt** with file paths from Phase 1
+2. Detect framework from package.json/config files
+3. Inject **Framework Addendum** for detected framework
+4. Apply **Component Analysis Prompt** to key files (entry points + high fan-in nodes)
+5. Output: \`layers.json\`, \`components.json\`
+
+### Phase 3 — Synthesize (LLM-assisted)
+1. Apply **Architecture Synthesis Prompt** per C4 level:
+   - System Context: external actors + top-level system boundary
+   - Containers: runtime units (services, DBs, queues, frontends)
+   - Components: internal modules within each container
+2. Generate BOTH output formats:
+   - **Mermaid** for \`docs/architecture/*.md\` files
+   - **React Flow HTML** for interactive exploration
+3. Output: diagram specs per level
+
+### Phase 4 — Layout & Render
+1. Apply ELK.js layout to React Flow nodes
+2. Generate static SVG exports for markdown embedding
+3. Write files:
+   - \`docs/architecture/c4-context.md\` (Mermaid)
+   - \`docs/architecture/c4-containers.md\` (Mermaid)
+   - \`docs/architecture/interactive/\` (HTML files)
+
+### Phase 5 — Validate
+\`\`\`
+check({})                                          # Typecheck (if TS)
+blast_radius({ files: ["docs/architecture/**"] })  # Verify scope
+\`\`\`
+
 ## References
 
 - [references/c4-syntax.md](references/c4-syntax.md) - Complete Mermaid C4 syntax
@@ -5692,6 +6086,503 @@ Document implementation patterns for:
 - **Tools**: \`analyze({ aspect: "entry_points", ... })\` + \`analyze({ aspect: "patterns", ... })\`
 - **Output**: \`docs/guides/contributing.md\` or \`docs/architecture/overview.md\` extension section
 
+## Guided Tour Generation
+
+Generate dependency-ordered codebase walkthroughs that teach the system through its natural reading order. Tours live in \`docs/tours/\`.
+
+### Algorithm
+
+1. \`analyze({ aspect: "entry_points", path: "." })\` — find tour start points (0 in-degree modules)
+2. \`graph({ action: "find_nodes", name_pattern: "src" })\` — get all module nodes
+3. \`graph({ action: "neighbors", node_id: "<entry>", direction: "outgoing" })\` — build dependency graph
+4. Topological sort on import edges — determine reading order
+5. Group by depth/layer — create logical tour steps
+6. Batch ≤ 3 related files per step — keep each step focused
+7. Append concept/cross-cutting nodes as final steps
+
+### Tour Step Format
+
+Each step in a tour:
+
+\`\`\`markdown
+## Step {order}: {title}
+
+{description — what the reader will understand after this step}
+
+**Files:**
+- \`{file1}\` — {role}
+- \`{file2}\` — {role}
+
+**Key concepts:** {comma-separated concepts introduced here}
+**Depends on:** Steps {list of prerequisite step numbers}
+\`\`\`
+
+### Tour Generation Workflow
+
+1. Run the algorithm above to produce ordered step list
+2. For each step, use \`compact({ path, query: "purpose and public API" })\` to extract key info
+3. Write tour as \`docs/tours/{topic}.md\`
+4. Generate \`docs/tours/index.md\` linking all tours with descriptions
+
+### Tour Index Template (\`docs/tours/index.md\`)
+
+\`\`\`markdown
+# Codebase Tours
+
+Guided walkthroughs ordered by dependency — read them in sequence to understand the system.
+
+| Tour | Description | Steps | Audience |
+|------|-------------|-------|----------|
+| [Architecture](./architecture.md) | System structure and layers | N | New team members |
+| [Data Flow](./data-flow.md) | How data moves through the system | N | Backend developers |
+| [Feature: {name}](./feature-{name}.md) | End-to-end feature trace | N | Feature developers |
+\`\`\`
+
+### Directory Convention
+
+\`\`\`
+docs/
+└── tours/
+  ├── index.md              # Tour listing with descriptions
+  ├── architecture.md       # System structure tour
+  ├── data-flow.md          # Data pipeline tour
+  └── feature-{name}.md    # Feature-specific tours
+\`\`\`
+
+## Business Domain Documentation
+
+Document the business domain as a three-level hierarchy: **Domain → Flow → Step**. This captures what the system does in business terms, separate from its technical architecture.
+
+### Hierarchy
+
+- **Domain**: A bounded business context (e.g., "Authentication", "Billing", "Inventory")
+- **Flow**: A business process within a domain (e.g., "User Login", "Invoice Generation")
+- **Step**: An atomic action within a flow (e.g., "Validate Credentials", "Generate PDF")
+
+### Domain Discovery Workflow
+
+1. \`analyze({ aspect: "structure", path: "." })\` — identify top-level domain boundaries (directories, modules)
+2. \`analyze({ aspect: "entry_points", path: "." })\` — detect flow entry types (HTTP, CLI, event, cron, manual)
+3. \`trace({ start: "<entry-point>", direction: "forward" })\` — map each flow's step sequence
+4. \`graph({ action: "neighbors", node_id: "<domain-module>", direction: "both" })\` — find cross-domain interactions
+
+### Domain Template (\`docs/architecture/domains/{domain-name}.md\`)
+
+\`\`\`markdown
+# Domain: {Name}
+
+## Overview
+{What this domain handles in business terms}
+
+## Entry Points
+
+| Entry | Type | Trigger |
+|-------|------|---------|
+| \`{endpoint/command}\` | {http/cli/event/cron/manual} | {what triggers it} |
+
+## Entities
+- **{Entity}**: {description + key attributes}
+
+## Business Rules
+- {rule 1 — e.g., "Passwords must be hashed before storage"}
+- {rule 2}
+
+## Flows
+
+### {Flow Name}
+{What this flow accomplishes}
+
+**Steps:**
+1. {Step 1} — \`{file:function}\` — {what happens}
+2. {Step 2} — \`{file:function}\` — {what happens}
+3. {Step 3} — \`{file:function}\` — {what happens}
+
+### {Flow Name 2}
+...
+
+## Cross-Domain Interactions
+
+| This Domain | Direction | Other Domain | Mechanism |
+|-------------|-----------|--------------|-----------|
+| {current} | → calls | {other} | {API/event/import} |
+| {other} | → notifies | {current} | {event/callback} |
+\`\`\`
+
+### Directory Convention
+
+\`\`\`
+docs/
+└── architecture/
+  └── domains/
+    ├── authentication.md
+    ├── billing.md
+    └── inventory.md
+\`\`\`
+
+## Interactive Tour Visualization (React Flow)
+
+When HTML output is requested for tours or onboarding guides, generate a standalone React Flow HTML file showing the codebase tour as an interactive graph. Nodes represent files/modules, edges show dependencies AND tour progression order.
+
+### Tour Graph HTML Template
+
+\`\`\`html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8"/>
+  <title>{{TOUR_TITLE}} — Codebase Tour</title>
+  <script src="https://unpkg.com/react@18/umd/react.production.min.js"><\/script>
+  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"><\/script>
+  <script src="https://unpkg.com/@xyflow/react@12/dist/umd/index.js"><\/script>
+  <script src="https://unpkg.com/elkjs@0.9/lib/elk.bundled.js"><\/script>
+  <link rel="stylesheet" href="https://unpkg.com/@xyflow/react@12/dist/style.css"/>
+  <style>
+    body { margin: 0; font-family: system-ui, sans-serif; background: #0f172a; color: #e2e8f0; }
+    .react-flow { width: 100vw; height: 100vh; }
+    .tour-node { padding: 12px 16px; border-radius: 8px; border: 2px solid; min-width: 180px; cursor: pointer; transition: all 0.2s; }
+    .tour-node:hover { transform: scale(1.05); box-shadow: 0 4px 12px rgba(0,0,0,0.3); }
+    .tour-node.active { border-color: #22d3ee; box-shadow: 0 0 20px rgba(34,211,238,0.3); }
+    .tour-node.visited { opacity: 0.7; }
+    .tour-node.upcoming { opacity: 0.5; }
+    .step-number { position: absolute; top: -10px; left: -10px; width: 24px; height: 24px; border-radius: 50%; background: #22d3ee; color: #0f172a; font-size: 12px; font-weight: 700; display: flex; align-items: center; justify-content: center; }
+    .tour-panel { position: fixed; bottom: 20px; left: 50%; transform: translateX(-50%); background: #1e293b; border: 1px solid #334155; border-radius: 12px; padding: 16px 24px; max-width: 600px; z-index: 10; }
+    .tour-panel h3 { margin: 0 0 8px; color: #22d3ee; }
+    .tour-panel p { margin: 0; font-size: 14px; line-height: 1.5; }
+    .tour-nav { margin-top: 12px; display: flex; gap: 8px; }
+    .tour-nav button { padding: 6px 16px; border-radius: 6px; border: 1px solid #475569; background: #334155; color: #e2e8f0; cursor: pointer; }
+    .tour-nav button:hover { background: #475569; }
+    .tour-nav button.primary { background: #22d3ee; color: #0f172a; border: none; }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+  <script>
+    const tourSteps = {{TOUR_STEPS_JSON}};
+    const nodes = {{NODES_JSON}};
+    const edges = {{EDGES_JSON}};
+    // Tour logic: highlight active step, show explanation panel, navigate prev/next
+  <\/script>
+</body>
+</html>
+\`\`\`
+
+### Tour Node Types
+
+\`\`\`javascript
+const tourNodeTypes = {
+  entryPoint:  { color: '#22d3ee', icon: '🚀', label: 'Entry Point' },
+  core:        { color: '#34d399', icon: '⚙️', label: 'Core Module' },
+  utility:     { color: '#a78bfa', icon: '🔧', label: 'Utility' },
+  config:      { color: '#fbbf24', icon: '⚙️', label: 'Configuration' },
+  test:        { color: '#fb923c', icon: '🧪', label: 'Test' },
+  external:    { color: '#94a3b8', icon: '📦', label: 'External Dep' },
+};
+\`\`\`
+
+### Tour Edge Types
+
+\`\`\`javascript
+const tourEdgeTypes = {
+  dependency: { style: 'solid', color: '#475569', animated: false },     // import relationship
+  tourPath:   { style: 'solid', color: '#22d3ee', animated: true },      // tour progression
+  dataFlow:   { style: 'dashed', color: '#34d399', animated: false },    // data movement
+};
+\`\`\`
+
+### Tour Step Metadata
+
+Each tour step node carries:
+\`\`\`json
+{
+  "id": "step-1",
+  "file": "src/index.ts",
+  "title": "Application Entry Point",
+  "explanation": "This is where the app bootstraps...",
+  "learnsConcept": "Dependency injection setup",
+  "stepNumber": 1,
+  "layer": "entry",
+  "linesOfInterest": [12, 45, 78],
+  "duration": "2 min"
+}
+\`\`\`
+
+### SVG Export for Markdown Embedding
+
+Same pattern as c4-architecture SVG export — iterate tour nodes and edges, generate static SVG showing tour path with numbered steps. Embed in \`docs/tours/*.md\` files.
+
+## Documentation Generation Prompts
+
+Structured LLM prompt templates for generating high-quality documentation. Each produces strict JSON for consistent, parseable output.
+
+### Tour Generation Prompt (2-Phase)
+
+**Phase 1** is deterministic (no LLM needed):
+\`\`\`
+# Deterministic Tour Ranking (run BEFORE LLM)
+1. graph({ action: "find_nodes" }) → get all module nodes
+2. Compute for each node:
+   - in_degree (how many import it) → "importance"
+   - out_degree (how many it imports) → "complexity"
+   - centrality = in_degree / (in_degree + out_degree)
+3. Rank by: entry_points FIRST, then by centrality DESC
+4. Group by layer (from layer detection)
+5. Topological sort within each layer
+6. Output: ordered node list with rankings
+\`\`\`
+
+**Phase 2** uses LLM with Phase 1 results as context:
+\`\`\`
+You are a developer onboarding guide. Given a ranked list of codebase modules with their relationships, generate a guided tour that teaches the system through progressive understanding.
+
+**Module rankings (from static analysis):**
+{{RANKED_MODULES_JSON}}
+
+**Dependency graph (edges):**
+{{EDGES_JSON}}
+
+**Detected layers:**
+{{LAYERS_JSON}}
+
+**Instructions:**
+- Create 8-15 tour steps (adjust to codebase size)
+- Start with entry points and high-level orchestration
+- Progress to increasingly detailed/specialized modules
+- Each step should teach ONE concept
+- Group related files into single steps (max 3 files per step)
+- End with cross-cutting concerns and extension points
+- Include estimated reading time per step
+
+**Respond ONLY with a JSON object:**
+{
+  "title": "Tour title",
+  "description": "One sentence overview",
+  "estimatedTime": "30 min",
+  "steps": [
+    {
+      "stepNumber": 1,
+      "title": "Step title — concept learned",
+      "files": ["src/index.ts"],
+      "explanation": "2-3 sentences explaining what this teaches",
+      "learnsConcept": "Single concept name",
+      "prerequisites": [],
+      "linesOfInterest": { "src/index.ts": [12, 45] },
+      "duration": "2 min"
+    }
+  ]
+}
+\`\`\`
+
+### File Documentation Prompt
+
+\`\`\`
+You are a technical writer. Document this source file for developer reference.
+
+**File:** {{FILE_PATH}}
+**Content:**
+{{FILE_CONTENT}}
+
+**Module's role in architecture:** {{MODULE_ROLE}}
+**Layer:** {{LAYER}}
+
+**Respond ONLY with a JSON object:**
+{
+  "title": "Module name — one-line purpose",
+  "overview": "2-3 sentence description of what this module does and why it exists",
+  "publicAPI": [
+    { "name": "functionName", "signature": "typed signature", "description": "what it does", "example": "brief usage" }
+  ],
+  "dependencies": [
+    { "module": "import path", "purpose": "why this dependency" }
+  ],
+  "patterns": ["Pattern names used (e.g., Factory, Observer, Middleware)"],
+  "gotchas": ["Non-obvious behaviors or edge cases"],
+  "relatedModules": ["paths to related files for cross-reference"]
+}
+\`\`\`
+
+### Domain Documentation Prompt
+
+\`\`\`
+You are a domain-driven design analyst. Given files belonging to a business domain, document the domain model.
+
+**Domain:** {{DOMAIN_NAME}}
+**Files in this domain:**
+{{FILE_LIST}}
+
+**Key file contents (summarized):**
+{{FILE_SUMMARIES}}
+
+**Cross-domain relationships:**
+{{CROSS_DOMAIN_EDGES}}
+
+**Respond ONLY with a JSON object:**
+{
+  "domain": "Domain name",
+  "description": "What business capability this domain handles",
+  "ubiquitousLanguage": [
+    { "term": "Term", "definition": "What it means in this context" }
+  ],
+  "entities": [
+    { "name": "Entity", "description": "Role", "keyAttributes": ["attr1", "attr2"] }
+  ],
+  "businessRules": [
+    "Rule 1 description",
+    "Rule 2 description"
+  ],
+  "flows": [
+    { "name": "Flow name", "steps": ["Step 1 → file:fn", "Step 2 → file:fn"], "trigger": "What initiates this" }
+  ],
+  "crossDomainInteractions": [
+    { "direction": "outgoing|incoming", "otherDomain": "Name", "mechanism": "API/event/import", "purpose": "Why" }
+  ]
+}
+\`\`\`
+
+## Documentation Generation Pipeline
+
+Orchestrate comprehensive documentation generation using a phased approach (inspired by multi-agent pipeline patterns).
+
+### Phase 1 — Inventory (deterministic)
+\`\`\`
+# Scan existing docs and detect staleness
+find({ glob: "docs/**/*.md" })                    # Current doc inventory
+git_context({ include_diff: true })               # Recent changes
+blast_radius({ files: changedFiles })             # What docs might be stale
+\`\`\`
+
+### Phase 2 — Analyze (deterministic + LLM)
+\`\`\`
+# Identify documentation gaps
+analyze({ aspect: "structure" })                  # All modules
+analyze({ aspect: "entry_points" })              # Tour starting points
+graph({ action: "find_nodes" })                  # Full module graph
+# For each undocumented module: apply File Documentation Prompt
+# For each domain cluster: apply Domain Documentation Prompt
+\`\`\`
+
+### Phase 3 — Detect Layers (LLM-assisted)
+\`\`\`
+# Classify architecture for tour and domain docs
+1. Collect all file paths from structure analysis
+2. Apply Layer Detection Prompt (from c4-architecture skill)
+3. Inject Framework Addendum for detected framework
+4. Output: layers.json used by tour generation
+\`\`\`
+
+### Phase 4 — Generate Tours (2-phase)
+\`\`\`
+# Phase 4a: Deterministic ranking
+1. Compute node rankings (in-degree, centrality, layer)
+2. Topological sort within layers
+3. Identify tour start points (entry_points with 0 in-degree)
+
+# Phase 4b: LLM narrative
+1. Apply Tour Generation Prompt with rankings from 4a
+2. Generate both Mermaid tour diagram AND React Flow HTML
+3. Output: docs/tours/getting-started.md + docs/tours/interactive/
+\`\`\`
+
+### Phase 5 — Generate Domain Docs (LLM-assisted)
+\`\`\`
+# For each detected domain/bounded context:
+1. Identify files belonging to domain (from layer/cluster analysis)
+2. compact() key files for context
+3. Apply Domain Documentation Prompt
+4. Output: docs/architecture/domains/{domain}.md
+\`\`\`
+
+### Phase 6 — 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
+\`\`\`
+
+### Output Structure
+\`\`\`
+docs/
+├── tours/
+│   ├── getting-started.md          # Primary tour (Mermaid diagrams)
+│   ├── advanced-internals.md       # Deep-dive tour
+│   └── interactive/
+│       ├── getting-started.html    # React Flow interactive tour
+│       └── advanced-internals.html
+├── architecture/
+│   ├── c4-context.md
+│   ├── c4-containers.md
+│   ├── interactive/
+│   │   ├── overview.html           # React Flow architecture
+│   │   └── per-service.html
+│   └── domains/
+│       ├── authentication.md
+│       └── billing.md
+├── reference/
+│   └── modules/                    # Per-module API docs
+└── guides/
+    └── contributing.md
+\`\`\`
+
+## Framework Context Injection
+
+When generating documentation for a specific framework, inject framework-specific conventions into LLM prompts to improve generation quality:
+
+### Detection
+\`\`\`
+# Auto-detect framework from project files:
+- package.json → "next", "react", "express", "nestjs", "@angular/core"
+- requirements.txt → "django", "flask", "fastapi"
+- go.mod → "gin", "fiber", "echo"
+- Cargo.toml → "actix-web", "axum", "rocket"
+\`\`\`
+
+### Addendum Format
+\`\`\`markdown
+## {{FRAMEWORK}} Documentation Addendum
+(Injected into documentation prompts when {{FRAMEWORK}} is detected)
+
+### Canonical Documentation Structure
+
+| Path Pattern | Doc Type | Template |
+|---|---|---|
+| {{src_pattern}} | {{doc_type}} | {{which template to use}} |
+
+### Tour Conventions
+
+- Tour starts at: {{entry_point_pattern}}
+- Key learning progression: {{progression}}
+- Framework-specific concepts to teach: {{concepts}}
+
+### Domain Conventions
+
+- Where domains live: {{domain_path_pattern}}
+- How domains are bounded: {{boundary_mechanism}}
+\`\`\`
+
+### Example: Next.js Addendum
+\`\`\`
+## Next.js Documentation Addendum
+
+### Canonical Documentation Structure
+| Path Pattern | Doc Type | Template |
+|---|---|---|
+| app/layout.tsx | Architecture | Root layout, providers, theme |
+| app/**/page.tsx | Feature docs | Page-level feature documentation |
+| app/api/** | API Reference | Endpoint documentation |
+| lib/** | Reference | Utility/service documentation |
+| components/** | Component docs | Props, usage examples, variants |
+
+### Tour Conventions
+- Tour starts at: app/layout.tsx (root) → app/page.tsx (home)
+- Key progression: Layout → Pages → API Routes → Lib → Components
+- Framework concepts: App Router, Server Components, Server Actions, Middleware
+
+### Domain Conventions
+- Domains live in: app/(domain)/ or features/(domain)/
+- Bounded by: Route groups or feature folders
+\`\`\`
+
 ## Rules for the \`_docs-sync\` Epilogue Step
 
 When this skill is loaded during the \`_docs-sync\` epilogue: