Interactive Docs

Interactive project docs

Up to three single self-contained HTML files (inline CSS/JS, images base64-embedded), theme-aware, openable offline in any browser. Each also exports to PDF and Word.

Build in that order: 1 and 2 come from one code-reading pass and are cheap; 3 needs a running app and is the expensive one. Match effort to the ask — if the user wants only one of them, build only that. Confirm scope when unclear (which flows? all three docs?). Verify each file renders before claiming done.

Bundled

Step 0 · Discovery (always first)

Follow references/discovery.md. It classifies the project, inventories the infrastructure, detects whether there's an AI surface at all, and establishes how the database schema is created — which changes the whole seeding section. Write findings straight into arch.json.

The rule everything else rests on: an entry in .env, compose or package.json proves something is deployed, never that it is used. Confirm each edge at its call site. Anything unconfirmed is marked inferred or provisioned-unused — never quietly promoted to fact.

python3 scripts/vendor_mermaid.py     # once per machine

A · Infrastructure doc

1. Fill arch.json — tiers, nodes, edges, lifecycle, containers, storage, external, seeding, security, scaling, deploy. Every field optional; omitted sections don't render. examples/sample-arch.json shows all of them. Rename or drop tiers to match reality — see project-types.md. A tier that exists only to fill the grid is worse than an asymmetric diagram.
2. python3 scripts/build_arch.py arch.json --doc infra
3. Keep every claim tied to a file:line, mark external vs in-cluster, and flag anything provisioned-but-unused.

Seeding is a real from-zero runbook, not a footnote. Establish the schema mechanism first (create_all / migrations / restore from a dump / none) — restore-based setups are common and easy to miss, and getting this wrong makes every later step wrong. Then give copy-pasteable commands in exact order, flag destructive ones, name what to back up, and say how tests get an isolated database.

B · AI workflows doc

Only when the project really calls a model. Full spec in references/ai-workflows.md; diagram mechanics in references/mermaid-recipes.md.

1. Fill arch.json's ai block: workflows (each with its diagrams and a clickable nodes map), prompts, models, context, cost, state_of_play.
2. python3 scripts/build_arch.py arch.json --doc ai

Choose the diagram kind from the workflow's actual shape — this is what makes the doc worth having. Chain → flowchart LR. Agent → flowchart with the loop edge and its real stop condition

• a sequenceDiagram of one turn. RAG → two diagrams (index path, query path). Multi-agent → flowchart with the shared state node. Streaming/async → sequence across client/API/worker/model. Guardrail → flowchart with pass, fail and error branches.

Then make sure these are in it, because they're what readers can't get quickly from the code:

• Where fidelity is lost — truncation budgets, chunk size/overlap, no OCR, top-k with no score floor, history dropped to fit. Give each its own node.
• The step that doesn't exist but a reader will assume does (reranker, retry, fallback model) — draw it dashed and label it. Naming the absent step beats a clean diagram implying completeness.
• Fail-open guardrails. A validator that returns "pass" when its own model call times out means the protection vanishes exactly when it's needed. Look for it deliberately; if present, diagram it.
• What leaves the machine, whether anything is redacted first (usually not — say so), and your own retention: an audit table storing every prompt and completion is often the bigger exposure.
• Cost with the multiplier explicit — a mandatory grading pass doubles spend per request.

C · Interactive user guide

Structure: a left tree of groups → steps, and per step a crumb pill, a "👤 who" badge, progress bar, What-you-do / What-you-see cards, evidence, optional callout, optional spec card, optional free-form body HTML, Prev/Next + arrow keys + theme toggle.

1. Plan the tree — a shared "Start", then one group per flow/area, plus optional "Reference"/"Admin". Give each group a distinct accent color.
2. Capture evidence from the running project into screenshots/. Browser → references/screenshot-capture.md. CLI, mobile, API, data → references/capture-nonweb.md.
3. Write guide.json (shape below), then: python3 scripts/build_guide.py guide.json --shots screenshots --out USER_GUIDE_INTERACTIVE.html
4. Verify — it's JS-driven, so open it in a real browser or over python3 -m http.server; a script-blocking preview shows a blank page.

{
  "title": "MyApp — Interactive Usage Guide",
  "groups": [{"id":"start","label":"Start","sub":"Shared by all flows","color":"#3f47c4"},
             {"id":"flowA","label":"Flow A","sub":"…","color":"#0d7a72"}],
  "pages": [
    {"id":"start-signin","group":"start","step":0,"icon":"◆","title":"Sign in","crumb":"Start",
     "who":"Any user","imgs":["01-login"],"caps":["The sign-in screen"],
     "do":"Enter email + password and <b>Sign in</b>.","see":"A role-based home.",
     "note":"Demo: <code>admin@…</code>","note_kind":"tip"},
    {"id":"flowA-1","group":"flowA","step":1,"icon":"1","title":"Create the thing","crumb":"Flow A",
     "who":"Admin","evidence":[
       {"kind":"image","src":"10-create","cap":"Admin creating it"},
       {"kind":"terminal","title":"$ myapp sync","body":"✔ 42 records","cap":"Real output"},
       {"kind":"code","title":"POST /api/things → 201","lang":"json","body":"{…}","cap":"Response"}],
     "do":"…","see":"…",
     "spec":{"label":"The inputs","Title":"…","Description":"…"},
     "body":"<h3 class='gb-h'>Formula</h3><div class='gb-fx'>score = Σ (x/max)×w</div>"}
  ]
}

step:0 hides the progress bar (reference/non-sequential pages). who becomes the 👤 badge. evidence supports image · terminal · code, so a CLI, API or pipeline guide is first-class rather than screenshot-shaped; imgs/caps still work and are folded in first. note_kind ∈ info|tip|warn. body is raw HTML (gb-h, gb-fx, gb-table helpers).

What makes these guides good

• A shared "Start", then per-flow branches with the SAME step shape, so differences stand out.
• Show who acts. Log in as each role, capture their scoped view, caption each image with the account. Never repurpose a screenshot that contradicts the step — capture the correct state.
• Reuse one worked example / dataset across flows so the numbers stay consistent.
• Explain the math. A Reference page with the real formulas (verified against code) and a worked example earns its place.

Depth & fidelity bar — default to this, don't wait to be asked

• Real captures from the running project, high-DPI, full-page. Desktop viewport (≥1024px), scale:2. Never a viewport-cropped or low-res shot.
• Walk EVERY flow end-to-end — create → configure → generate → publish → the other actor's view → evaluate → finalize → the report. Include public/unauthenticated pages and each state of an object (draft→published→submitted→graded→finalized) as its own step.
• Turn optional features ON and show them really working. Enable flag-gated features in a dev env and capture the real output. For media the UI won't render, extract a real frame (ffmpeg -ss 2 -i file.mp4 -frames:v 1 out.jpg).
• Cut complex dashboards into each section (region capture via html2canvas(document.body, {x,y,width,height,scale:2})) and add a per-metric table: what it is · how it's computed (exact formula) · why it matters — verified against the stats module, not memory.
• Show variants side by side — reading levels, difficulty tiers, per-role views — same item in each variant, quoting the changed text.

D · Export to PDF and Word

Offer both whenever you hand over a doc.

python3 scripts/export_doc.py ARCHITECTURE_INFRASTRUCTURE.html --both
python3 scripts/build_guide.py guide.json --shots screenshots --out guide.flat.html --flat
python3 scripts/export_doc.py guide.flat.html --both

Always export the guide from its --flat build — the interactive file shows one step at a time, so a direct export captures a single page. PDF uses headless Chrome (falls back to weasyprint, wkhtmltopdf); DOCX uses pandoc. Keep the interactive HTML as the primary deliverable.

Shared principles

• Self-contained & offline — inline everything, base64 images, no fetches at view time (html2canvas and mermaid are used at capture/build time, never fetched by the shipped file).
• Theme-aware — light tokens on :root, dark under prefers-color-scheme and [data-theme]; always paint body from a token. Never hard-code a colour inside a diagram node.
• Keep files lean — recompress before building (sips --resampleWidth 1440) so a rich guide is ~5–8 MB. The AI doc carries ~3.4 MB of inlined mermaid; use --mermaid link if size matters more than being self-contained.
• Accuracy over polish — numbers, formulas, ports, models, evidence and "who does what" must match reality. Never fabricate a screenshot, a transcript or a response body.
• Verify before claiming done — open every file in a real browser; confirm diagrams rendered as SVG (mermaid source shown as a code block means it failed to parse) and that clicking a node fills the detail panel.