Architecture Dashboard

Generate architecture-dashboard.html at the project root (or a user-specified path): a dependency-free, offline HTML page with

• Graph — layered left-to-right node-link diagram of components (auto-layout, pan/zoom, click a node for its detail panel, search box, type legend, light/dark theme)
• Schemas — catalog of the data files/structures flowing between components
• Prompts — every LLM/image/video prompt used per pipeline step, full text, copyable
• Guide — conventions, extension points ("how to add X"), and gotchas for coding

The page is rendered from template.html in this skill directory; you only produce a JSON architecture model and inject it with build.py. Do not hand-write the HTML.

Step 1 — Investigate the codebase

Budget the investigation to repo size; for large repos fan out Explore agents. You must find:

1. Entry points & components — executables/scripts/services/CLIs, key modules, build or pipeline stages. Read the README/CLAUDE.md first; they often name the pipeline.
2. Relationships — who calls/reads/writes/submits-to whom. Follow the data: a JSON manifest written by script A and read by script B is an edge A → manifest → B.
3. Data schemas — for each manifest/config/API payload, record actual field names and types by reading a real sample (head a large file, don't load it all).
4. Prompts — search broadly: grep -ril "prompt" plus *.txt/*.md in prompt-ish dirs, string literals passed to LLM/gen-AI APIs, system prompts in code. Capture the FULL text of the representative/final prompt per step (not every historical version — pick the one the README or manifest marks as selected/latest, and say which you picked). Note the model/ service each prompt targets.
5. External services — APIs, endpoints, env vars/credentials required.

Prefer precision over volume: 10–40 nodes. Merge trivia (one node per pipeline stage, not per file); every node must earn its place by helping someone code against the project.

Step 2 — Write the architecture model JSON

Write arch-data.json to the scratchpad. Shape (all string fields plain text, no HTML):

{
  "project": {
    "name": "…", "description": "1–2 sentences", "root": "/abs/path",
    "generatedAt": "2026-07-11",
    "stats": [{"label": "Pipeline stages", "value": "5"}, …]        // 3–6 headline tiles
  },
  "nodes": [{
    "id": "kebab-id", "label": "Short name", 
    "type": "script|data|prompt|asset|external|config|ui|other",     // aliases: module→script, service/api→external, manifest/store→data
    "group": "Pipeline stage or subsystem",                          // optional
    "summary": "one line — shows in tooltip and card",
    "detail": "a paragraph of what it does and how (plain text)",    // optional
    "files": [{"path": "rel/path.py", "lines": "114-236", "role": "entry point"}],
    "inputs":  [{"name": "prompt file", "format": "txt", "schema": "free text; @image_N refs", "from": "where it comes from"}],
    "outputs": [{"name": "task.json",  "format": "json", "schema": "{taskId, submit}", "to": "who consumes it"}],
    "prompts": [{"name": "…", "file": "rel/path.txt", "model": "service/model it targets",
                 "purpose": "what this prompt achieves", "text": "FULL prompt text"}],
    "notes": "guidance for someone coding against this component"    // optional
  }],
  "edges": [{"from": "id", "to": "id", "label": "submits prompt + refs", "kind": "data|call|reference"}],
  "schemas": [{
    "name": "selected-clips.json", "file": "rel/path", "description": "…",
    "fields": [{"name": "clipId", "type": "string", "description": "…"}],
    "example": "verbatim trimmed sample"                              // optional
  }],
  "guide": {
    "conventions": ["short imperative statements of how this repo does things"],
    "extensionPoints": [{"title": "Add a new pipeline step", "how": "concrete steps", "files": ["paths to touch"]}],
    "gotchas": ["things that will bite a new contributor"]
  }
}

Rules:

• Edge from/to must match node ids; the renderer drops dangling edges silently — check yours.
• The graph is layered by edge direction (sources left, sinks right). Model the pipeline as a DAG where possible; cycles are tolerated (back-edges detected) but read worse.
• Keep prompt text verbatim and complete — that's the point of the Prompts tab.
• Put file paths RELATIVE to project.root.

Step 3 — Build and verify

python3 <this-skill-dir>/build.py --data <scratchpad>/arch-data.json --out <project-root>/architecture-dashboard.html

build.py validates the model (unknown node types, dangling edges, missing ids → hard error), escapes </ for safe <script> embedding, and injects into template.html.

Verify: run node --check is NOT needed (template is pre-checked); instead open the file (open <out> on macOS) and confirm with the user, or render/screenshot if browser tooling is available. If a build error names a dangling edge or bad type, fix the JSON, not the template.

Design notes (already baked into template.html — don't re-derive)

Colors follow the dataviz skill's validated reference palette (categorical slots in fixed order; node text in ink tokens, never series color; legend always present; dark mode uses the palette's selected dark steps, not an auto-flip). If you edit the template's colors, re-run the dataviz validator.