---
name: training-guide
description: Build an interactive visual course as one self-contained HTML page, one idea per screen. Use to explain or teach a subject visually, step by step.
---

# Training Guide - interactive visual primer

Turn a subject into a self-paced, click-through course: a full-bleed two-column page where a
hand-built diagram sits on the left and one idea's explanation sits on the right, advanced with
Next / Back / arrow keys. It teaches the way a good tutor does - build the machine one piece at a
time, name each term the first time it appears, drop in a trick question to check understanding,
and reveal an analogy on demand.

The engine (design system, stepper, diagram helpers, quiz mechanics) already exists in
`assets/template.html`. **Your whole job is content**: infer the subject, design the teaching
order, and write the `steps` array plus one small diagram function per screen. Do not rebuild the
engine.

## Workflow

1. **Pin the subject and the audience.** Pull it from the conversation - the report, code, or
   topic in play. If genuinely ambiguous, ask one sentence's worth of clarification (subject +
   who's learning + how deep). Otherwise infer and proceed; the user can redirect.

2. **Design the concept ladder before writing any code.** This is the craft. List the ideas in
   dependency order and check the golden rule: **every term a later screen uses must be taught on
   an earlier screen.** If a "gotcha" or finding screen will say `DeploymentVerifier` or `ECDH`,
   there must be an earlier plain screen that introduces it. A good arc is usually:
   *mechanics* (the core moving parts) → *the build* (what it's for / the features) →
   *the machinery* (supporting infrastructure the gotchas will reference) → *where it gets tricky*
   (pitfalls, findings, edge cases). Put a quiz after each act.

3. **Copy the template and fill it in.** Copy `assets/template.html` to a working file (the user's
   Desktop or the scratchpad). Then:
   - Set `CONFIG` (brand, title, legend meanings).
   - Optionally reskin the palette: change the ONE accent colour (`--accent`/`--accent-ink`/
     `--accent-soft`) and the neutrals in the CSS `:root` blocks to suit the subject's world. Keep
     `--warn` and `--danger` semantic-only. Design both light and dark.
   - Replace the example diagram functions with one per concept, built from the `box / wire / lbl /
     seal / svg` helpers (640×300 viewBox). Reuse `dQuiz()` for quiz screens.
   - Replace the `steps` array with your ladder.
   Read `references/authoring.md` for the full helper API, the screen-object schema, layout math,
   and worked examples - read it before writing diagrams so they don't overlap.

4. **Verify before publishing - never ship a lesson you haven't watched run.** Serve the file
   locally (`python3 -m http.server` in its directory) and open it in the browser tool. Check the
   console has no errors, then click through: the first screen, a couple of diagram screens
   (confirm no overlapping labels), a quiz (answer it - correct flags teal, wrong flags red), and
   the last screen. Fix anything, re-verify. Then stop the server.

5. **Publish and hand off.** Publish with the Artifact tool for a shareable URL, and also leave the
   standalone `.html` on the user's Desktop so they have an offline, dependency-free copy. Give
   them the link and a short map of the acts.

## What makes these good (the bar)

- **One idea per screen.** If a screen needs two diagrams to explain, it's two screens.
- **Terms are earned, never dropped cold.** The single most common failure is a later screen using
  vocabulary the course never introduced. Walk the ladder and fix every unexplained term.
- **The reveal is for intuition, not more facts.** The body states the mechanic; the `aha` reveal
  gives the everyday analogy or the "so what". Keep them distinct.
- **Quizzes are traps that teach.** The tempting answer should be the intuitive-but-wrong one; the
  explanation is where the real lesson lands. 2–4 options, exactly one correct.
- **Diagrams show one relationship.** Boxes are things, wires are flow, teal = the good/verified
  path, danger = where it breaks, warn = caution. Don't rainbow it.
- **Length matches the subject.** A tight concept is ~8 screens; a full system with findings is
  ~15–22. Self-paced, so thoroughness is fine - but every screen must earn its place.

## Design system (fixed, so every course feels like one product)

Two-column full-bleed card; diagram left, reading right, controls pinned bottom. Mono for labels
and eyebrows (the "technical ledger" voice), sans for reading. One accent colour carries
highlight/verified; `warn` and `danger` are semantic only. Theme-aware (light/dark) and responsive
(stacks below 900px). All of this is already wired in the template - keep it; reskin only the
accent + neutrals when the subject calls for a different mood.


## What if content has mistakes

If you are certain the content you're tutoring about has some mistake, consult with the user before stamping it into the guide, data correctness is important.