HTML Explainer

Produce one self-contained HTML file that teaches a reader how a real system works, grounded in the repo's actual code.

Outcome spine

Result: a single .html file with inline CSS, JavaScript, and SVG that explains the subject at three depths.
Next consumer: the user and their teammates, opening the file directly in a browser — no server, no build step.
Done: the file exists at the agreed path, scripts/validate_explainer.py exits 0, and the file was delivered/rendered to the user.
Intent: the page is trusted because every code snippet is real. Readers use the path:line bars to jump into the repo.

Two rules that govern everything

verbatim-or-absent — every code snippet is copied verbatim from the repo and labeled with its path:line range, or it does not appear on the page. Never reconstruct code from memory; when abridging, mark the source bar (abridged) and cut whole lines only. If a claim can't be traced to a file, state it as prose without a snippet or drop it.
drill-down contract — the page must work at three depths: glance (the clickable big-picture map + one-paragraph ledes), scan (section summaries, tables, diagrams), descend (expandable panels with the code). Nothing essential may live only at descend depth; nothing bulky may live above it.