Chapters / segmenting: emit chapter markers from per-step manifest

[jbrecht]

Source: instructional-designer pedagogy review, docs/reviews/2026-06-13-pedagogy-review.md (Part 2, item #1 — rated High impact / High feasibility, "do this first").

User story

As a tutorial author, I want my rendered video to carry chapter navigation so learners can self-pace and jump to the part they need — the segmenting principle, the strongest and cheapest multimedia-learning win available to this tool.

Why this is cheap

The timing manifest already carries first-class per-step boundaries — ManifestStep has id, narration, startMs, endMs (packages/core/src/types.ts:188-203). Chapters are a new consumer of data that already exists, not new instrumentation. Post-stage filters live in packages/core/src/post/ and already emit sidecar artifacts (SRT via post/subtitles.ts).

Scope

1. MP4 chapter markers — write chapters into the output container (ffmpeg metadata / -map_metadata chapter file built from manifest step boundaries). Default chapter title = step narration (or a derived short label); see grouping below.
2. WebVTT chapters sidecar (<id>.chapters.vtt) for web players.
3. YouTube-style timestamp list printed to stdout / written to a <id>.chapters.txt for paste-into-description.
4. Optional author grouping (stretch): allow steps to be grouped into named sections so chapters map to concepts, not individual clicks — e.g. a section?: string field on Step, or a chapter('name', [...steps]) grouping helper. Without grouping, fall back to one chapter per step (or per non-empty-narration step).

Acceptance criteria

• Rendering produces MP4 chapter markers viewable in QuickTime/VLC at correct timestamps derived from manifest startMs.
• A .chapters.vtt sidecar is written alongside the MP4.
• A copy-pasteable timestamp list is available (stdout and/or .chapters.txt).
• Behavior is opt-in or sensibly defaulted; documented in docs/getting-started.md and docs/writing-tutorials.md.
• Silent / very-short steps don't produce noise chapters (define a rule, e.g. skip empty-narration steps or merge into the prior chapter).
• If author grouping ships, it's documented and validated in validateTutorial() (packages/core/src/spec.ts).

Open decision (for maintainer)

One chapter per step vs. author-defined section grouping for the first cut. Recommend shipping per-step chapters first (zero new authoring surface) and adding grouping as a fast follow.