git:20261020.a2baa6b to git:20261020.69a2bbb

+ description: Default for building ANY artifact or artefact page or multi-page artifact site (design doc, proposal, explainer, roadmap, plan, review, report, comparison, investigation) with light theme, clean FigJam-style SVG diagrams chosen per reader question (architecture delta, coverage matrix, dependency graph, story map, timeline, Wardley map, sankey, waterfall, line chart, treemap, fishbone and the rest of the catalog), wide tables with filters and highlighted key columns and rows, interactive diagrams (hover focus, badge and legend linking, step-through, zoom and pan), bleed-width repo maps, deeper engineering pages, detailed isometric figures through the anatomy skill, full-screen diagrams, and for sites an index, top nav, per-page section list and Previous / Next links. Use whenever the user asks to create, build, update or publish an artifact/artefact or an HTML page or site to share, or says "make an artefact", "explain with diagrams", "design artifact", "proposal page", "roadmap page", "multi-page artifact", "explain this repo architecture", "more detailed diagram", "isometric diagram". For a full codebase field guide with interview questions use codebase-explorer instead.

+ ## References (load when the step needs them)

+

+ | File | Load when |

+ |---|---|

+ | `references/choosing-diagrams.md` | choosing any figure (step 2) |

+ | `references/highlighting.md` | writing the body and tables (step 3) |

+ | `references/engineering.md` | the page is about software: design, repo, migration, incident, review |

+ | `references/interactive.md` | adding node focus or step-through to a figure |

+ | `references/detailed-figures.md` | the user wants more detail, isometric, 3D or a "real object" figure (anatomy skill) |

+ | `references/style-guide.md` | tokens, fonts, figure sizes |

+ | `references/checklist.md` | before publishing (step 8) |

+ | `../../diagram-types/technical/repo-map/README.md` | drawing a repo map with `scripts/repo_map.py` |

+

+ - **Diagrams get the room.** Inline figures run up to 1180px wide; `"size": "bleed"` takes nearly the whole window for repo maps and dense architecture (`references/style-guide.md`).

+ - **Highlight the point.** One `<mark>` per section for the sentence that matters, `b.k` for key terms, `.metric` for numbers that matter, callouts for risks and decisions; every table marks its deciding column (`th.key`) or rows (`tr.key`) (`references/highlighting.md`).

+ - **Interactive, never required.** Figures link badges and legends to the drawing, focus a part and its neighbours on hover (`data-node` / `data-edge`), step through `data-step` groups, and zoom and pan full screen. Tables with 6 or more rows get a filter box, sortable headers and column selects. The static page stays complete (`references/interactive.md`).

+ - **Engineering depth.** For software subjects, explain what exists, how it runs, where it lives in the code, what breaks and how we know it works, with real paths and detailed figure walkthroughs; build with `--kind engineering` (`references/engineering.md`).

+ - **Wide tables with small margins.** Page up to `min(1480px, 100% - 40px)`, 16 to 20px side gutters, prose about 75ch. Each table sits in `.tablewrap` (scrolls sideways in its own box; sticky header when long). Columns sized by content.

+ - status chips: `<span class="pill ok|next|todo|ill">`, callouts: `.tldr`, `.note`, `.callout warn|risk|ok`, cards: `.cards > .card`, two columns: `.grid2`

+ - highlights: `<mark>`, `<b class="k">`, `<span class="metric">`; table marks: `th.key`, `th.num`, `th[data-filter]`, `tr.key|good|bad|dim`

+ 4. **Draw diagrams** as `svg/KEY.svg` (repo maps: write a spec and run `scripts/repo_map.py spec.json > svg/KEY.svg`; detailed or isometric objects: build with the anatomy skill per `references/detailed-figures.md`), starting from the chosen type's `example.svg` in the repo's `diagram-types/` folder (anatomy in its README). Follow `../codebase-explorer/references/diagram-guide.md` and the budgets and connector rules in `references/choosing-diagrams.md`: one idea per figure, at most 9 primary nodes, 3 bands and 12 connectors (over budget: split into an overview and a detail), at least 32 units of clear margin inside the viewBox on every side, fewer and larger labels, accent on 1 or 2 elements, orthogonal connectors, every action arrow labelled with a verb, 12px minimum text, ids prefixed with the key, numbered badges that match a legend, no hex colors, no style or script tags. Structure diagrams follow the neutral colour rule above.

+ 6. **Describe figures** in `figs.json`: `{"KEY": {"type": "<catalog slug>", "why": "<reader question>", "title": "...", "caption": "...", "badges": [...], "legend": [["--cl1-f", "label"], ["line dash", "vendored"]], "size": "bleed"}}`. `size` is optional: `wide` fills the text column (timelines), `bleed` nearly the window (repo maps default to it). A badge can be a string or `{"t": "name", "d": "what happens here", "file": "path"}`, which renders a detailed walkthrough under the figure; engineering pages use the detailed form. An anatomy figure is `{"type": "anatomy", "src": "anatomy/x-light.html", "height": 620, ...}`.

+ 7. **Build** one page: `python3 scripts/build.py --title "Page Name" --body body.html --svg svg --figs figs.json --out page.html [--kind engineering]`. It fails if a `{{fig:KEY}}` has no entry or a `type` is not in the catalog, warns when `why` is missing, every figure has the same type, nothing is highlighted, a wide table has no key column or row, or (engineering) the page lacks failure modes, verification, real paths or detailed badges, and replaces any stray em or en dash.

+ 8. **Run the checklist** (`references/checklist.md`) and **look once** at the whole page (headless Chrome screenshot, or the Artifact preview) and fix what is visibly broken. For a site, look at `index.html` and at least one page: `../codebase-explorer/scripts/render.sh --page site/index.html /tmp/index.png`.