F5 · Documentation system, figures and media tooling

Done 2026-10-26 · commits b2687d8, 0e5b97a and 8d74979, plus the fixes from the second review · spec v0.1, landing page, docs gate, 4 doc agents

What changed

• Spec: the documentation system. Docs are part of the definition of done. depictio's site format is kept, its gaps are closed, writers and reviewers are separate agents, PR bodies carry the docs, and PRs auto-merge.

• Site:

  • a new landing page (hero video, ecosystem and component cards, numbered ideas, the gate figure, a cast, the progress strip);
  • theme colours from the design tokens;
  • this Progress tab, generated by hooks/progress.py;
  • an empty changelog with the block template.

• Tools:

  • tools/diagrams/sketch.py, ported from depictio (MIT) with Spectio glyphs;
  • two figures;
  • tools/media/: generated casts, a screenshot registry, combined terminal and browser captures, a churn guard;
  • tools/docs/check.py, the docs gate.

• Agents and skill:

  • agents doc-writer, doc-reviewer, diagram-artist, media-capture;
  • skill write-docs.

• Repository: the PR template, and docs.yml with the required checks docs-gate and pr-body.

Why

Thomas: the most important part of the loop is that each step is written up and verified, incrementally, in MkDocs. He wants depictio's format, real diagrams rather than boxes, screenshots, videos and casts, and agents that write next to agents that review.

Decision: decision log, 2026-10-26, documentation as part of done.

Evidence

$ python3 tools/docs/check.py --base 7a0b51c     # after the second review set review: approve
mermaid: 4 blocks checked
diagrams: 2 scripts re-run, 4 SVGs compared
media: 15 outputs in the manifest
media budget: 2.64 MB new or changed against 7a0b51c
progress: 7 pages checked
docs gate: 0 failure(s)

• Rendering checks: the landing page was rendered at 1440 × 900 (light and dark) and at 390 × 844, and looked at. There is no horizontal scroll at phone width (scrollWidth = 390).
• Tooling details: see the tooling spike.

Figures and media

The docs steps inside one autopilot tick:

The combined capture made by tools/media/combo.py (24.5 s): the terminal runs the synthetic Snakemake pipeline to its QC gate and resumes it; the browser pane shows the gate review on a design board (an imaging plate QC gate), rendered with fixture names.

Findings and open questions

• The Virgil font's licence is unclear. Excalidraw's page says OFL-1.1 and MIT, while the file says "All rights reserved". The font is kept out of the repository until this is settled (inbox #1).
• The first independent review blocked this page and the landing page (personal data from the design boards in the media, a video over 30 s, a GIF over the media budget, flat nested lists site-wide). Fixed: fixture names substituted before rendering, the video shortened, GIFs generated outside docs/assets/, a hook that nests 2-space lists, and gate checks for video length, GIFs and the per-PR media budget.
• Material for MkDocs reaches end of life on 2027-05-05, according to its own build notice. Zensical is its successor; evaluating the move is part of D6.