# training-guide

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.

- **Kind:** skill
- **Source:** https://github.com/forefy/.context
- **Page:** https://forefy.com/skills/d5e589e1-172e-4ac1-b9f8-0e86b93e629e
- **API (JSON + files):** https://forefy.com/api/asr/d5e589e1-172e-4ac1-b9f8-0e86b93e629e

---

## SKILL.md

---
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.

## assets

```

```

## assets/template.html

```

```

## references

```

```

## references/authoring.md

# Authoring reference - diagrams, screens, and layout

Read this before writing diagram functions. Everything here is already loaded by the engine in
`assets/template.html`; you only call it.

## Table of contents
- [The canvas](#the-canvas)
- [Helper API](#helper-api)
- [Screen object schema](#screen-object-schema)
- [Layout math (avoiding overlap)](#layout-math)
- [Worked example: one act](#worked-example)
- [Common mistakes](#common-mistakes)

## The canvas

Every diagram is a function returning `svg(inner)`. The viewBox is **640 wide × 300 tall**. Keep
content inside **x: 20–620, y: 30–270**. The right column holds the prose, so the diagram carries
*structure*, not sentences - short mono labels only.

Animate assembly with staggered `delay` (seconds). Left-to-right, ~0.15–0.3s apart, reads as the
idea building. The engine replays animations on every step change.

## Helper API

```js
svg(inner)                         // wrap your inner markup; adds arrowhead <defs>
box(x,y,w,h,label,sub,opts)        // rounded actor box. opts:{stroke,fill,tc,delay}
wire(x1,y1,x2,y2,opts)             // connector. opts:{color,marker:'ar'|'arA'|'arD',cls:'draw'|'flow',delay,w}
lbl(x,y,text,opts)                 // free label. opts:{color,anchor:'start'|'middle'|'end',fs,fw,delay}
seal(cx,cy,r,broken,delay)         // wax-seal glyph: check (broken=false) or crack (broken=true)
dQuiz()                            // ready-made "?" motif for quiz screens
```

Colour shortcuts available inside diagram functions: `A` (accent), `AI` (accent-ink, for text on
accent fills), `AS` (accent-soft fill), `H` (hairline), `P2` (panel-2 fill), `INK`, `MU` (muted),
`D` (danger), `W` (warn).

Conventions that keep the visual language consistent:
- **Accent** (`A`/`AS`/`AI`) = the good path, the verified/sealed/correct thing, the subject of the screen.
- **Danger** (`D`) = where it breaks, the attack, the wrong branch. Use `marker:'arD'` + often a dashed wire (`stroke-dasharray`) for an "attack" arrow, and `seal(...,true,...)` for "it shatters".
- **Warn** (`W`) = caution / "can only do the mild bad thing".
- **Neutral** (`P2`/`H`/`MU`) = ordinary actors and plumbing.
- Wires into an accent target use `marker:'arA'`; ordinary wires use `'ar'`.

Raw SVG is fine too when a helper doesn't fit (nested cards, lists, dials) - copy the `<g class="pop" style="animation-delay:Xs">…</g>` and `<text>` patterns from the examples. Use HTML entities, not literal Unicode (`&rarr;`, `&mdash;`, `&#10003;`, `&#8734;`), so the file stays charset-independent.

## Screen object schema

```js
// concept / feature / gotcha (default kind)
{ ey:'CONCEPT 1', eyt:'Topic', tag:'foundation'|'', chip:{label:'KEY',tone:'accent'|'warn'|'danger'},
  svg:dSomething, title:'A plain claim', body:'HTML…', aha:'the analogy', revealLabel:'reveal the intuition' }

// quiz
{ type:'quiz', ey:'GUT-CHECK', eyt:'Did it land?', tag:'trick question', svg:dQuiz,
  q:'Question?', opts:[{t:'wrong'},{t:'wrong'},{t:'right',correct:true}], explain:'why' }
```

- `ey` / `eyt`: eyebrow label + topic (top-left). Use `ey` to signal the act: `CONCEPT n`,
  `FEATURE`, `UNDER THE HOOD`, `DEEP DIVE`, `GUT-CHECK`, `RECAP`.
- `tag` vs `chip`: use `tag` for a muted top-right subtitle; use `chip` when a screen carries a
  labelled weight (`{label:'MEDIUM',tone:'warn'}` for a severity, `{label:'KEY',tone:'accent'}` for
  a takeaway). `chip` wins if both are present.
- `body`: HTML. `<span class="k">term</span>` for first-use jargon (renders as a mono chip),
  `<b>` for emphasis, `<br><br>` to separate beats (the body is a div, so block content is fine).
- `aha`: the reveal. Analogy or "so what", **not** more mechanics.
- `revealLabel`: button text. Default `reveal the intuition`; use `the fix`, `the takeaway`,
  `why it matters` to fit the screen.

## Layout math

The engine's box/label sizes are tuned for `font-size` 14 (box label), 10.5 (sublabel), 11 (free
label). To place things without collisions:

- A `box(x,y,w,h,...)`'s center is `(x+w/2, y+h/2)`; its label sits there, sublabel `+14` below.
- A horizontal wire between two boxes: `wire(x1+w1, cy, x2, cy)` where `cy` is the shared center y.
- Reserve the bottom band **y 240–270** for a one-line caption via `lbl(320, 255, '…')`.
- Three boxes across fit comfortably at widths ~120–150 with ~60px gaps: e.g. x = 40, 240, 460.
- A stacked pair of boxes (two lanes) at y = 78 and y = 176 leaves room for a caption at 262.
- Text you place with `lbl` is not measured - keep labels short (≤ ~28 chars) and give annotations
  their own clear region (above, below, or to the side of the drawing), never on top of a wire.

If a diagram feels crowded, it's two screens. Split it.

## Worked example

A three-screen act (concept → gotcha → quiz) for an imaginary "message queue" subject:

```js
function dQueue(){
  var i='';
  i+=box(30,124,120,54,'Producer','sends jobs',{delay:0});
  i+=wire(150,151,214,151,{delay:.3,color:A,marker:'arA'});
  i+=box(214,116,150,70,'Queue','holds in order',{stroke:A,fill:AS,tc:AI,delay:.4});
  i+=wire(364,151,428,151,{delay:.7,marker:'ar'});
  i+=box(428,124,150,54,'Worker','does the job',{delay:.8});
  i+=lbl(320,252,'work is buffered, not dropped',{color:MU,fs:11,delay:1.1});
  return svg(i);
}
function dPoison(){
  var i='';
  i+=box(214,116,150,70,'Queue',null,{stroke:A,fill:AS,tc:AI,delay:0});
  i+=wire(364,151,428,151,{delay:.3,color:D,marker:'arD'});
  i+=box(428,124,150,54,'Worker','crashes on it',{stroke:D,fill:'var(--danger-soft)',tc:D,delay:.5});
  i+=wire(428,124,289,116,{delay:.9,color:D,marker:'arD'}); // back to the queue
  i+=lbl(320,252,'a poison message loops forever',{color:D,fs:11,delay:1.2});
  return svg(i);
}

var steps=[
  {ey:'CONCEPT 1',eyt:'The queue',tag:'foundation',svg:dQueue,
   title:'A queue buffers work between producer and worker',
   body:'A <span class="k">producer</span> drops jobs onto a <span class="k">queue</span>; a <span class="k">worker</span> pulls them off in order. If the worker is slow, jobs wait instead of vanishing.',
   aha:'Like a <b>ticket spike</b> at a diner: orders pile in order, the cook works them one at a time, nothing gets lost in a rush.'},
  {ey:'DEEP DIVE',eyt:'Poison messages',chip:{label:'GOTCHA',tone:'warn'},svg:dPoison,
   title:'One bad message can jam the whole line',
   body:'If a job makes the worker crash, most queues put it <b>back</b> to retry &mdash; so it crashes the next worker too. That is a <span class="k">poison message</span>.',
   aha:'The fix is a <b>dead-letter queue</b>: after N failures, shunt the job aside so the line keeps moving.', revealLabel:'the fix'},
  {type:'quiz',ey:'GUT-CHECK',eyt:'Did it land?',tag:'trick question',svg:dQuiz,
   q:'Your workers keep crashing in a loop. What is the most likely cause?',
   opts:[{t:'The queue is too small'},{t:'A single poison message being retried',correct:true},{t:'Too many producers'}],
   explain:'A size limit drops or blocks new work; too many producers just fills the queue. A crash <b>loop</b> is the signature of one bad message being retried forever &mdash; the case for a dead-letter queue.'}
];
```

## Common mistakes

- **Cold terms.** A gotcha screen naming something the course never taught. Walk the ladder; every
  `<span class="k">…</span>` in a later screen should have first appeared, unhurried, on an earlier one.
- **Overlapping labels.** Two `lbl`/`box` texts sharing space. Give annotations their own band; if
  it's tight, split the screen. Always verify visually in the browser before publishing.
- **The reveal repeats the body.** The reveal must add the analogy or the payoff, not restate facts.
- **Rainbow diagrams.** More than ~3 colours reads as noise. Accent + neutral + one semantic.
- **Literal Unicode.** Use HTML entities so the file renders regardless of charset.
- **Shipping unverified.** Always serve it, open it, click a quiz, and read the console before publishing.