# Authoring a tutorial

> **Retired — the subsystem is gone (2026-09-03).** The choreographer
> (`src/choreography/`), the tutorial reader, library and player
> (`src/tutorial/`), the Learn segment and the shipped `.bwx` walkthroughs
> were all deleted: reaching a professional finish on a synthesized
> depiction was more work than the feature was worth. R55's "a document step
> lands in sight" survives on a far smaller derivation — `src/spotlight.rs`
> unions the footprints of the entities a commit's ops name, aims the camera
> at that region and rings it. Kept as the record of what was tried.

*(Rewritten at choreographer-playbook step 7·12. The KDL level format,
its script grammar, the recorded-input pipeline, and `xtask tutorial
init|golden` this document used to describe were deleted at 7·10–7·11;
the historical description lives in git history and the format record in
`docs/kdl-format.md`.)*

A tutorial is an ordinary `.bwx` container. Its commit log *is* the demo:
the choreographer synthesizes each commit's animation at playback time
(`docs/choreographer-playbook.md`), so there is no tutorial format, no
scaffold command, and nothing that can drift from the editor — a tutorial
is made by **editing a document with notes on**.

## How

1. Create a document (File ▸ New) and build the demo by performing it:
   every gesture you make is a commit, and each commit is what plays back,
   depicted by the choreography rules (L0) with a ghost cursor miming the
   gesture your commit label names (L1).
2. **Narrate with notes.** A `note` record (D17) is authored text in the
   log: narration notes speak over the step they precede, and a
   `Chapter`-display note opens a section — chapters are the units a
   player lists, searches, and jumps to, and each chapter's duration is
   the sum of its commits' synthesized timelines.
3. Anchor a note to an entity (uuid + rev + optional rect) when the words
   point at something on the canvas.
4. **Say what it teaches with a tag.** A `teaches/<tool>` tag (D18) on the
   rev whose commit that tool made declares what the tutorial is about —
   `teaches/new-block`, `teaches/route`, `teaches/select`, the spellings
   [`ToolName::command_name`] gives the seven tools a command can arm. One
   tag per taught tool; a tag names a rev, so the rev that used the tool is
   the one that carries it. This is what the selection overlay's
   *Walkthrough* entry (R15) and the tool cluster's ring match against.
5. Undo works on notes exactly as on edits — a note is part of the
   document's story, and taking it back removes it (contrast tags, which
   are *about* history and stay out of the undo stack — which is why what a
   tutorial teaches is a tag and its narration is a note).

**All of a tutorial's metadata lives in its own log.** The user's ruling
(2026-09-02): *"Include any meta information about the tutorial in the log
of the tutorial."* So: what it teaches is a tag, its chapters and narration
are notes, and its display title is the diagram's own name — the name the
top bar would show if you opened it. There is no sidecar, no filename
convention beyond the one every diagram already has, and no record kind
that exists only for tutorials.

The shipped tutorials live in `fixtures/tutorials/*.bwx` — three
containers converted from the old levels at 7·9, each proven equal to the
old replay goldens at conversion time and re-proven on every ci run:
`blockworx verify`-grade replay, the final-frame oracle per commit, and
the head against the container's own integrity stamp.

Their `teaches/` tags were appended by
`tutorial::reader::tests::every_shipped_tutorial_says_what_it_teaches`,
which checks them on every run and *writes* them under
`BLOCKWORX_TAG_TUTORIALS=1 cargo test --lib every_shipped_tutorial_says` —
the deleted converter's own `BLOCKWORX_CONVERT_TUTORIALS` precedent. It is
idempotent (a container that already carries its tag is left alone) and it
appends through the ordinary `Store::tag` door, so `document.json` and every
existing line of `log.jsonl` are untouched: a tag folds nothing and spends
no rev.

## Reading one

`tutorial::reader::Tutorial` is the substrate/UI contract:
`open(root)` (a read-only store open that never takes the writer's lock),
`chapters()` (title, rev, duration), `timeline(rev)` (the synthesized
animation), `narration(rev)` (the note standing at that rev, undo-aware),
`teaches()` (the tools its tags name) and `document(rev)` (the fold a
timeline is depicted against). The player UI consumes exactly this surface
and nothing deeper.