explainer-video 0.0.0-stage → 0.4.0

package/skills/craft-video-align/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: craft-video-align
+description: Measure per-word and per-line timings for one video's narration, so scene beats can be anchored to the words they illustrate. Stage 4b of explainer-video-from-coursework.
+---
+
+# craft-video-align — word and line timings
+
+> Part of the `explainer-video-from-coursework` pipeline — **stage 4b of 8**, between
+> audio (4) and scene (5).
+>
+> The pipeline's tools and scene hosts live in the sibling `explainer-video-from-coursework` skill: run them as `node ../explainer-video-from-coursework/tools/<tool>.mjs`, resolved against this skill's folder. Run from the **scratch root** — the directory holding `out/`, which Stage 0 fixes (default: beside your notes) — so every `out/<name>/…` path in this stage resolves.
+
+> **Timing.** Bracket the stage with the stamp pair so the series accrues a per-video audit;
+> `end` must run before the stage counts as done (see *Timing* in the main skill):
+>
+> ```bash
+> node ../explainer-video-from-coursework/tools/stamp.mjs begin --out out/<name> --video <NN> --stage 4b
+> node ../explainer-video-from-coursework/tools/stamp.mjs end   --out out/<name> --video <NN> --stage 4b
+> ```
+
+**Prerequisites:** `out/<name>/<NN>/narration/<key>.wav` and `timeline.json` — both
+final once the audio stage exits.
+
+```bash
+node ../explainer-video-from-coursework/tools/align.mjs --script out/<name>/scripts/<NN>-*.json \
+                        --work out/<name>/<NN>
+```
+
+## Why this stage exists
+
+The audio stage measures each **segment**. Everything *inside* a segment was left to
+guesswork, and a guess is where sync dies: on the module-07 pilot the "April" reveal
+fired at 6.6s while the words "In April" begin at 12.6s — a 6-second error that every
+check passed, because no check could see the narration's shape.
+
+This stage measures the narration's shape. It emits the span of every **line**
+(sentence) of the script, in audio time, so the scene stage can bind a beat to a line
+instead of inventing a number.
+
+## What it does
+
+Transcribe the **whole narration track in one request** with `gemini-3.5-transcribe`
+(requesting `wordTimestamp`), cut the returned words into segments using the measured
+`timeline.json` boundaries, align each segment's words back onto that segment's script
+words, then compute each line's span from the aligned words.
+
+**Why one request, not one per segment.** The model is capped at **100 requests/day
+per project per model**, the Batch API is not supported for it, and the cap is per
+project — so it cannot be spread across keys. Per-segment alignment spent ~30 requests
+on a 13-minute video (≈3 videos/day); a whole-track pass spends **one**.
+
+The model allows 30 minutes per request *when word timestamps are enabled*, so a track
+longer than that is cut at **segment boundaries** into multiple passes (never
+mid-sentence). `--per-segment` keeps the old path as a fallback, and is chosen
+automatically when only a few segments are missing. Already-cached segments are never
+re-requested, so a full pass only fills what is absent and cannot overwrite good
+measurements with worse ones.
+
+On HTTP 429 the run **exits 3** rather than falling back — a daily-cap failure would
+fail identically for every segment, so cascading would just burn the run.
+
+**The alignment step is not optional.** The transcriber is not a faithful echo — it
+rewrites punctuation and applies inverse text normalisation. Measured on real
+narration it returned "In March, it pushes…" (inserted comma), "spends **40** minutes"
+(we wrote *forty*), "**failed**" (we wrote *fail*), and merged two sentences into one.
+So the transcript never decides a boundary: **our punctuation decides boundaries, the
+aligned words supply times.**
+
+**Word offsets can contain outliers.** One plan returned "A delta" at 3.7s in a
+sentence whose neighbours were at 12.4s and 14.2s. Offsets are forced monotonic and
+non-overlapping (`clampMonotonic`), which pulls an early outlier to the end of the
+previous word — within a word or two of the truth. Repairs are reported.
+
+## Outputs
+
+- `narration/<key>.words.json` — per segment: every word with its offsets, the script
+  index it maps to, and a cache stamp (wav size+mtime, text hash). Re-runs are free
+  until the audio or the script text changes.
+- `lines.json` — per video: for every segment, each line's `{ line, text, start, end }`
+  plus `lead` and the window bounds.
+
+**Line times are relative to the narration WAV.** A scene renders in window time,
+which starts `lead` seconds earlier, so the conversion is:
+
+```
+beat time (scene) = line.start + lead
+```
+
+`lines.json` records `lead` per segment so nothing has to assume 0.6.
+
+## Done when
+
+`align` exits **0** and prints `✓ N segment(s) · M lines · written`. Any error means a
+line could not be placed in the audio (usually a garbled transcript) — re-run with
+`--force` for that segment, and if it persists treat the segment's narration as the
+thing to fix.
+
+Two things to watch in the report:
+
+- **`only NN% of script words aligned`** — below `--min-match` (default 0.8) the
+  transcript probably diverged; the line spans may still be right, but check them.
+- **`NN word offset(s) came back out of order and were clamped`** — expected
+  occasionally; a large number suggests the audio and the script text disagree.
+
+## Maintenance
+
+> If you modify this file, or the user asks to change this stage, tell the user that the
+> main `explainer-video-from-coursework` skill's **"Stage 4b — /align"** section must be
+> reconciled to match, and name that section in your reply.

package/skills/craft-video-assemble/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: craft-video-assemble
+description: Assemble one video from its segments — render each window silent, concatenate, mux the narration once, and verify. Stage 8 of explainer-video-from-coursework.
+---
+
+# craft-video-assemble — the finished video
+
+> Part of the `explainer-video-from-coursework` pipeline — **stage 8 of 8**. The
+> **orchestrator** over the render stage.
+>
+> The pipeline's tools and scene hosts live in the sibling `explainer-video-from-coursework` skill: run them as `node ../explainer-video-from-coursework/tools/<tool>.mjs`, resolved against this skill's folder. Run from the **scratch root** — the directory holding `out/`, which Stage 0 fixes (default: beside your notes) — so every `out/<name>/…` path in this stage resolves.
+
+> **Timing.** Bracket the stage with the stamp pair so the series accrues a per-video audit;
+> `end` must run before the stage counts as done (see *Timing* in the main skill):
+>
+> ```bash
+> node ../explainer-video-from-coursework/tools/stamp.mjs begin --out out/<name> --video <NN> --stage 8
+> node ../explainer-video-from-coursework/tools/stamp.mjs end   --out out/<name> --video <NN> --stage 8
+> ```
+
+**Prerequisites:** the script, `out/<name>/<NN>/timeline.json`, `manifest.json`, and
+`narration.wav`; on the machine, `ffmpeg` + headless Chromium (see `SETUP.md`).
+
+> A `[setup]` / `Playwright cache not found` failure means ffmpeg or Chromium is absent —
+> relay the matching `SETUP.md` step to the user and re-run.
+
+```bash
+node ../explainer-video-from-coursework/tools/assemble.mjs --script out/<name>/scripts/<NN>-*.json \
+                        --work out/<name>/<NN> --name <output> \
+                        --dest <destination> [--port 9333]
+```
+
+`--port` (default 9333) is forwarded to every per-segment `render.mjs`, so **two videos can
+assemble concurrently** when each is given its own port — one port per concurrent agent.
+The run aborts before segment one if the port is already listening, because a shared CDP
+port does not fail cleanly: the second assembly attaches to the first browser's page and
+encodes the *other* video's scene under its own filename, exit 0. Verified — byte-identical
+frames from the wrong video. This is what lets a per-video agent own stage 8 end to end.
+
+Per segment: render its own window through its own host + config, **silent** — parts
+are silent on purpose, because muxing narration onto each would restart the whole track
+at every boundary. Then concatenate (`-c copy`), mux the single measured narration
+track **once**, and verify. `--only <key>` renders a single segment, for a smoke test.
+
+Asserts: every segment has a timeline window **and** a `manifest.json` entry · the
+windows tile the timeline with no gaps · the finished audio matches the narration at
+**sample level**.
+
+**Done when:** the run exits **0** and prints `[done] …<output>.mp4` with `audio ok`.
+The MP4 is copied into the video's own folder, `--dest/<NN>-<slug>/`, alongside the
+`description.md` and `captions.srt` that publish wrote.
+
+<!-- sync:codeflow-publish-render -->
+**Code-flow videos only.** A code-flow video's plan, `plan.json` or `plan.enriched.json`, carries
+`"kind": "codebase"`, and its `forms` are `overview`, `flow` and `core`. A coursework plan has no `kind`; nothing
+in this block applies to its videos. A code-flow video adds these rules at stages 6–8:
+
+- **Render.** A code segment renders through `src/scene-code.html?scene=<key>`. Pass `--work out/<name>/<NN>` so
+  the host reads that video's `timeline.js`; `assemble` passes it for every segment.
+- **Chapters.** Write each chapter title from that chapter's narration, as for any video.
+- **Upload title.** The `youtubeTitle` names the flow in the viewer's terms, such as what a request does or what
+  a command runs. Never use a module path.
+<!-- /sync:codeflow-publish-render -->
+
+## Maintenance
+
+> If you modify this file, or the user asks to change this stage, tell the user that the
+> main `explainer-video-from-coursework` skill's **"Stage 8 — /assemble"** section must be
+> reconciled to match, and name that section in your reply.

package/skills/craft-video-audio/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: craft-video-audio
+description: Synthesize narration and build the measured timeline for one video. Stage 4 of explainer-video-from-coursework — the one-shot TTS primitive.
+---
+
+# craft-video-audio — TTS and the measured timeline
+
+> Part of the `explainer-video-from-coursework` pipeline — **stage 4 of 8**. This is the
+> **primitive**: it builds audio once and stops. This skill itself never loops.
+>
+> The scene stage may re-invoke it, but **padding is not the expected path any more**.
+> Beat dwells are measured from the narration (stage 4b), so a shortfall now means the
+> scene over-asked — the fix is to widen the beat's line range, not to insert silence.
+> Only if a visual genuinely needs more screen time than its words take is a `pad`
+> justified; see stage 5's over-ask ladder.
+>
+> The pipeline's tools and scene hosts live in the sibling `explainer-video-from-coursework` skill: run them as `node ../explainer-video-from-coursework/tools/<tool>.mjs`, resolved against this skill's folder. Run from the **scratch root** — the directory holding `out/`, which Stage 0 fixes (default: beside your notes) — so every `out/<name>/…` path in this stage resolves.
+
+> **Timing.** Bracket the stage with the stamp pair so the series accrues a per-video audit;
+> `end` must run before the stage counts as done (see *Timing* in the main skill):
+>
+> ```bash
+> node ../explainer-video-from-coursework/tools/stamp.mjs begin --out out/<name> --video <NN> --stage 4
+> node ../explainer-video-from-coursework/tools/stamp.mjs end   --out out/<name> --video <NN> --stage 4
+> ```
+
+**Prerequisites:** `out/<name>/scripts/<NN>-*.json` from the script stage; on the machine, the Gemini key in the OS secret store (see `SETUP.md`).
+
+> A `No API key found` failure means the key isn't in the OS secret store — relay the
+> matching `SETUP.md` step to the user and re-run.
+
+```bash
+node ../explainer-video-from-coursework/tools/build-audio.mjs --script out/<name>/scripts/<NN>-*.json \
+                           --out out/<name>/<NN> --voice Aoede
+```
+
+Writes `narration/<seg>.wav`, `narration.wav`, `timeline.json`, and `timeline.js` into
+the per-video work dir. This is **the only network stage** — it spends the Gemini TTS
+key.
+
+Next: **stage 4b (`/align`)** measures the words *inside* each of those windows —
+`node ../explainer-video-from-coursework/tools/align.mjs --script out/<name>/scripts/<NN>-*.json --work out/<name>/<NN>`.
+Without it, scene beats have nothing measured to anchor to.
+
+**Done when:** the run exits **0** and prints one window per segment, ending in
+`[out] …/timeline.json`.
+
+- **Durations are measured, not estimated** — each WAV is measured with `ffprobe`; the
+  plan's `Min` was a guardrail, this is the real number later stages bind to.
+- **The cache is text-keyed** — `narration/<key>.src` stores the exact spoken text, so a
+  re-run after a wording tweak costs 0 calls. It does **not** cover `--voice`, `style`,
+  or `--model`: change one and the old audio is silently reused. Pass `--force` to
+  re-synthesize.
+
+## Maintenance
+
+> If you modify this file, or the user asks to change this stage, tell the user that the
+> main `explainer-video-from-coursework` skill's **"Stage 4 — /audio"** section must be
+> reconciled to match, and name that section in your reply.

package/skills/craft-video-enrich/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: craft-video-enrich
+description: Retitle and curate the videos in an explainer-video plan — write enrichment.json and merge it. Stage 2 of explainer-video-from-coursework; run it alone to retitle an existing plan.
+---
+
+# craft-video-enrich — retitle and curate
+
+> Part of the `explainer-video-from-coursework` pipeline — **stage 2 of 8**, the second
+> once-per-series stage. Self-contained: it operates on an existing `plan.json`. For a
+> full run, use the main skill instead.
+>
+> The pipeline's tools and scene hosts live in the sibling `explainer-video-from-coursework` skill: run them as `node ../explainer-video-from-coursework/tools/<tool>.mjs`, resolved against this skill's folder. Run from the **scratch root** — the directory holding `out/`, which Stage 0 fixes (default: beside your notes) — so every `out/<name>/…` path in this stage resolves.
+
+**Prerequisites:** `out/<name>/plan.json` from the plan stage.
+
+The agent writes `out/<name>/enrichment.json` — one entry per video — then validates
+and merges:
+
+```bash
+node ../explainer-video-from-coursework/tools/apply-enrichment.mjs --plan out/<name>/plan.json \
+                                --enrichment out/<name>/enrichment.json
+```
+
+Writes `plan.enriched.json` and `plan.enriched.md`.
+
+**Done when:** the run exits **0** (no validation problems), `plan.enriched.md` shows
+the final video list, **and that full list has been shown to the user** — every
+surviving video plus the removals with their reasons. Never summarise it into a sample:
+`apply-enrichment` prints the whole table, and the whole table is what gets reviewed.
+
+**Title contract.** The planner's titles are placeholders. Replace each with a real
+title: descriptive, **unique**, written for a human scrolling YouTube — never a
+directory slug. Title from the content, not the name: read the source at the video's
+`sectionSpans` before naming it. The tool rejects empty titles, `Part N` placeholders,
+ellipses, slugs, and duplicates.
+
+**Curation.** The planner cannot tell an overview page from real content, so it plans
+both — the agent decides. An entry may carry `skip: true` or `mergeInto: <index>`, both
+requiring a `why`. Every skip/merge lands in `plan.removed` with its reason and
+sections, so coverage stays auditable.
+
+## Maintenance
+
+> If you modify this file, or the user asks to change this stage, tell the user that the
+> main `explainer-video-from-coursework` skill's **"Stage 2 — /enrich"** section must be
+> reconciled to match, and name that section in your reply.

package/skills/craft-video-plan/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: craft-video-plan
+description: Decompose a coursework notes directory into an explainer-video plan and prove no content-bearing section is dropped. Stage 1 of explainer-video-from-coursework; run it alone to (re)plan a directory.
+---
+
+# craft-video-plan — decompose and prove coverage
+
+> Part of the `explainer-video-from-coursework` pipeline — **stage 1 of 8**, the first of
+> the two once-per-series stages. This skill is self-contained: it plans a directory
+> from scratch. For a full run, use the main skill instead.
+>
+> The pipeline's tools and scene hosts live in the sibling `explainer-video-from-coursework` skill: run them as `node ../explainer-video-from-coursework/tools/<tool>.mjs`, resolved against this skill's folder. Run from the **scratch root** — the directory holding `out/`, defaulting beside your notes — so `out/` scratch lands where Stage 0 said it would and inside a repo's ignore rules.
+
+**Prerequisites:** a directory of markdown notes (`<notesDir>`).
+
+```bash
+node ../explainer-video-from-coursework/tools/planner.mjs <notesDir> --out out/<name> --max-min 25 \
+  [--exclude <notesDir>/videos]
+```
+
+Writes `out/<name>/plan.json` and `out/<name>/plan.md`. No network, no key, safe to
+re-run. Read `plan.md`, not `plan.json`.
+
+> **Exclude a destination that lives inside the source.** `<notesDir>/videos/` is the
+> usual destination, and the planner walks all of `<notesDir>`: a published
+> `description.md` comes back in as a note and turns into a phantom video. Pass
+> `--exclude` for it (repeatable, one per old output folder). The planner warns when
+> it finds `description.md` inputs, because that filename is this pipeline's own
+> output — but the flag is the fix.
+
+> **`--max-min` is part of the plan.** Video indices are keyed by the split, so
+> re-running with a different cap reshuffles them and invalidates any enrichment
+> already written. The planner refuses (exit 4) to overwrite an enriched plan whose
+> model differs; pass `--force` only when you intend to re-enrich from scratch.
+
+**Done when:** the run exits **0**, `plan.md`'s coverage line reads
+`N assigned · M excluded as navigation · 0 orphaned`, **and every planned video has
+been shown to the user** (index, title, length — all of them, no sample and no
+"…and N more"). A non-zero exit, or any orphan, means the plan is incomplete — stop and
+fix it. Never enrich an incomplete plan.
+
+Two facts that shape how the plan is read:
+
+- **The coverage proof is the point.** The planner proves every content-bearing section
+  is assigned to a video or is a navigation heading. `plan.json` also carries
+  `sectionSpans` (each section's `src`, `title`, and 1-based `line`/`endLine`) — the raw
+  material for the next stage.
+- **The `Min` column is a guardrail, not a duration** — a planning estimate
+  (`wpm 153 × expansion 1.10`), not measured audio. Use it to judge boundaries.
+
+Only `.md` files are parsed; non-markdown content is invisible to the planner.
+
+## Maintenance
+
+> If you modify this file, or the user asks to change this stage, tell the user that the
+> main `explainer-video-from-coursework` skill's **"Stage 1 — /plan"** section must be
+> reconciled to match, and name that section in your reply.

package/skills/craft-video-publish/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: craft-video-publish
+description: Generate the upload title, YouTube chapters and English captions for one finished video. Stage 6 of explainer-video-from-coursework.
+---
+
+# craft-video-publish — title, chapters and captions
+
+> Part of the `explainer-video-from-coursework` pipeline — **stage 6 of 8**.
+>
+> The pipeline's tools and scene hosts live in the sibling `explainer-video-from-coursework` skill: run them as `node ../explainer-video-from-coursework/tools/<tool>.mjs`, resolved against this skill's folder. Run from the **scratch root** — the directory holding `out/`, which Stage 0 fixes (default: beside your notes) — so every `out/<name>/…` path in this stage resolves.
+
+> **Timing.** Bracket the stage with the stamp pair so the series accrues a per-video audit;
+> `end` must run before the stage counts as done (see *Timing* in the main skill):
+>
+> ```bash
+> node ../explainer-video-from-coursework/tools/stamp.mjs begin --out out/<name> --video <NN> --stage 6
+> node ../explainer-video-from-coursework/tools/stamp.mjs end   --out out/<name> --video <NN> --stage 6
+> ```
+
+**Prerequisites:** `out/<name>/<NN>/timeline.json` and `narration/<key>.src` — both
+final once the scene stage exits.
+
+The agent writes `out/<name>/<NN>/publish.json` — a `youtubeTitle`, a chapter list
+(`segments` keys + `title`) and a `blurb`. The tool resolves timecodes, validates, and
+emits **three files** into the video's own folder, `--dest/<NN>-<slug>/`: `title.txt`
+(one line, what YouTube shows), `description.md` (the blurb, then the chapter block,
+paste-ready plain text) and `captions.srt`. The folder name is derived from the script's
+`videoIndex` + title — do not pick it by hand.
+
+- **Title** — `title.txt` is the upload title, and it is also the file `upload_yt_video`
+  reads out of that folder, so a missing one is an incomplete upload. It is *not* the
+  same thing as the video's `title`: that one is structural (set at stage 2, it names the
+  folder and must not move); this one is written here because only now does the video
+  exist to be described honestly. Keep it a real search phrase — the subject someone
+  would type — and never promise what the video does not deliver: retention past the
+  first seconds is measured, and a hook the video does not pay off is the one thing that
+  gets actively suppressed.
+
+- **Chapters** — `M:SS Title`, start-time only, one per segment by default; grouping is
+  two keys in one list, and a chapter's time is the first segment's window start.
+  Titles are authored from the narration — never the scene `stageNames` (uppercase,
+  one missing, near-duplicate pairs).
+- **Captions** — one cue per segment, text from `narration/<key>.src` (the exact text
+  the WAV was built from — the audio is the truth, not `script.json`).
+- **Hard checks** — first timecode `0:00` · ≥3 chapters · each ≥10s · ascending · every
+  segment key resolves · titles ≤40 chars, not duplicated/near-duplicated · cues
+  ascend and don't overlap · `youtubeTitle` ≤100 chars, one line.
+- **Soft checks** (warnings, not failures) — title past ~70 chars (mobile truncation) ·
+  all-uppercase · stacked `!!`/`??` · a near-duplicate of a sibling video's title, which
+  buries a series' own parts. The tool can police the shape of a title, never its
+  appeal; that judgement stays yours.
+
+**Chapters need channel eligibility.** They are a YouTube advanced feature: a channel that
+has not qualified for advanced-feature eligibility renders **no** chapters, however valid
+the list — its timestamps still work as jump-to-section links, but the segmented progress
+bar and Google key moments do not appear. Nothing in `description.md` affects this, so
+absent chapters are not a formatting fault: `0:00` (one digit), a `-` after the timecode, a
+blurb above the block and a 2:39 runtime were each verified live on eligible channels, and
+the hard checks above already mirror YouTube's rules.
+
+**Done when:** `publish` exits 0 and both files land in `--dest/<NN>-<slug>/` beside the MP4.
+
+<!-- sync:codeflow-publish-render -->
+**Code-flow videos only.** A code-flow video's plan, `plan.json` or `plan.enriched.json`, carries
+`"kind": "codebase"`, and its `forms` are `overview`, `flow` and `core`. A coursework plan has no `kind`; nothing
+in this block applies to its videos. A code-flow video adds these rules at stages 6–8:
+
+- **Render.** A code segment renders through `src/scene-code.html?scene=<key>`. Pass `--work out/<name>/<NN>` so
+  the host reads that video's `timeline.js`; `assemble` passes it for every segment.
+- **Chapters.** Write each chapter title from that chapter's narration, as for any video.
+- **Upload title.** The `youtubeTitle` names the flow in the viewer's terms, such as what a request does or what
+  a command runs. Never use a module path.
+<!-- /sync:codeflow-publish-render -->
+
+## Maintenance
+
+> If you modify this file, or the user asks to change this stage, tell the user that the
+> main `explainer-video-from-coursework` skill's **"Stage 6 — /publish"** section must be
+> reconciled to match, and name that section in your reply.

package/skills/craft-video-render/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: craft-video-render
+description: Render one scene config over one time window to an MP4 (or a handful of QA stills). Stage 7 of explainer-video-from-coursework — the render primitive.
+---
+
+# craft-video-render — frames to MP4
+
+> Part of the `explainer-video-from-coursework` pipeline — **stage 7 of 8**. The render
+> **primitive**; the assemble stage drives it per segment. It can also run alone for QA
+> stills during scene authoring.
+>
+> The pipeline's tools and scene hosts live in the sibling `explainer-video-from-coursework` skill: run them as `node ../explainer-video-from-coursework/tools/<tool>.mjs`, resolved against this skill's folder. Run from the **scratch root** — the directory holding `out/`, which Stage 0 fixes (default: beside your notes) — so every `out/<name>/…` path in this stage resolves.
+
+> **Timing.** Bracket the stage with the stamp pair so the series accrues a per-video audit;
+> `end` must run before the stage counts as done (see *Timing* in the main skill):
+>
+> ```bash
+> node ../explainer-video-from-coursework/tools/stamp.mjs begin --out out/<name> --video <NN> --stage 7
+> node ../explainer-video-from-coursework/tools/stamp.mjs end   --out out/<name> --video <NN> --stage 7
+> ```
+
+**Prerequisites:** a scene config and, for windowed renders, `out/<name>/<NN>/timeline.json`; on the machine, `ffmpeg` + headless Chromium (see `SETUP.md`).
+
+> A `[node]` / `[setup]` / `Playwright cache not found` failure means a prerequisite is
+> absent — relay the matching `SETUP.md` step to the user and re-run.
+
+```bash
+node ../explainer-video-from-coursework/tools/render.mjs --scene "src/scene-diagram.html?scene=<name>" \
+                      --range <t0>,<t1> --outdir out/<name>/<NN>/parts --name part-<key>
+```
+
+Renders one scene config over one window — headless Chromium via CDP → PNG sequence →
+ffmpeg H.264. It is not a whole-video renderer: `--scene` takes a single
+`host?scene=<config>`, so a multi-scene video is rendered window by window. A window
+rendered with no `--narration` comes out silent, which is what assembly wants.
+
+**Each distinct frame is captured once** (no flag; it is the only capture path). Because
+`renderAt(t)` is pure, consecutive frames are often byte-identical — 82–99% measured — and
+a screenshot costs ~63 ms, so the loop hashes the serialized `#stage` SVG after each
+`renderAt(t)` and hardlinks the previous PNG when the markup is unchanged. Guards: scenes
+declaring CSS/web animations take the plain capture path from frame 0, and every 30 frames
+a real screenshot is diffed against the frame written (on disagreement it re-captures,
+rewinds since the last audit, and falls back to plain capture). Verified at SSIM 1.000000
+against every-frame renders on two full videos, 3.3×–4.3× faster. Read the closing
+`[dedup]` line — screenshots vs total, reuse %, audit mismatches.
+
+`--shots 6,20,34` renders QA stills instead of a full sequence (stills bypass the dedup
+loop — each is a different instant); `--keep-frames` retains the PNG sequence.
+
+**Done when:** the run exits **0** and prints `[done] …<name>.mp4`.
+
+<!-- sync:codeflow-publish-render -->
+**Code-flow videos only.** A code-flow video's plan, `plan.json` or `plan.enriched.json`, carries
+`"kind": "codebase"`, and its `forms` are `overview`, `flow` and `core`. A coursework plan has no `kind`; nothing
+in this block applies to its videos. A code-flow video adds these rules at stages 6–8:
+
+- **Render.** A code segment renders through `src/scene-code.html?scene=<key>`. Pass `--work out/<name>/<NN>` so
+  the host reads that video's `timeline.js`; `assemble` passes it for every segment.
+- **Chapters.** Write each chapter title from that chapter's narration, as for any video.
+- **Upload title.** The `youtubeTitle` names the flow in the viewer's terms, such as what a request does or what
+  a command runs. Never use a module path.
+<!-- /sync:codeflow-publish-render -->
+
+## Maintenance
+
+> If you modify this file, or the user asks to change this stage, tell the user that the
+> main `explainer-video-from-coursework` skill's **"Stage 7 — /render"** section must be
+> reconciled to match, and name that section in your reply.

package/skills/craft-video-scene/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: craft-video-scene
+description: Author and iterate the animated visuals for one video's segments. Stage 5 of explainer-video-from-coursework; beats anchor to measured narration lines, not hand-written seconds.
+---
+
+# craft-video-scene — author the visuals
+
+> Part of the `explainer-video-from-coursework` pipeline — **stage 5 of 8**. This is the
+> **orchestrator** over the audio stage: it loops, and it re-invokes `build-audio` when a
+> beat cannot fit. The audio stage itself is one-shot and never loops back.
+>
+> **A shortfall is no longer routine.** Beat dwells default to the measured span of
+> the lines they cover, so `at + min` is inside the window by construction and a
+> line-anchored scene should report none. If `pacing-check` does report one, the scene
+> **over-asked**: widen the beat's `lines` range first, redesign the beat second, and
+> `pad` the segment only as a last resort.
+>
+> If you do pad, line times survive it (a pad widens the window, never the segment
+> WAV) — but *rewriting the narration* invalidates every line time for that segment, so
+> re-run `/audio` → `/align` → `/resolve-beats`. `resolve-beats --script …` enforces
+> that by comparing the text hash `align` recorded.
+>
+> The pipeline's tools and scene hosts live in the sibling `explainer-video-from-coursework` skill: run them as `node ../explainer-video-from-coursework/tools/<tool>.mjs`, resolved against this skill's folder. Run from the **scratch root** — the directory holding `out/`, which Stage 0 fixes (default: beside your notes) — so every `out/<name>/…` path in this stage resolves.
+
+> **Timing.** Bracket the stage with the stamp pair so the series accrues a per-video audit;
+> `end` must run before the stage counts as done (see *Timing* in the main skill):
+>
+> ```bash
+> node ../explainer-video-from-coursework/tools/stamp.mjs begin --out out/<name> --video <NN> --stage 5
+> node ../explainer-video-from-coursework/tools/stamp.mjs end   --out out/<name> --video <NN> --stage 5
+> ```
+
+**Prerequisites:** `out/<name>/<NN>/timeline.json` (from the audio stage) and the
+script for the video; headless Chromium for the `--shots` look (see `SETUP.md`).
+
+> A `Playwright cache not found` failure on the `--shots` render means Chromium is absent —
+> relay the `SETUP.md` step to the user and re-run.
+
+Each segment is a **beat**: narration plus the visual that illustrates it. Author the
+visual as **visual beats** — steps, each with a minimum dwell and an alignment to the
+narration — never as raw seconds.
+
+**Hosts, per segment** (`out/<name>/<NN>/manifest.json`, `key` → `{host, scene}`):
+
+- **`svg`** (`src/scene-svg.html`) — the open lane; expose `renderAt(t, svg, timeline)`
+  plus `SCENE_BEATS`.
+- **`code`** (`src/scene-code.html`) — code walkthroughs.
+- **`diagram`** (`src/scene-diagram.html`) — declarative `nodes`/`edges`/`reveal`/
+  `banners` configs built on `scene-core.js`.
+
+**The beat anchors to a line, never to a second** — declare per segment:
+
+```js
+window.SCENE_BEATS = { beats: [
+  { id: 'march',   line: 1 },                    // index into lines.json for this segment
+  { id: 'caption', lines: [3, 4], hold: true },  // holds across those lines
+]};
+```
+
+`line` indexes that segment's lines in `lines.json` (stage 4b). `lines: [from, to]`
+claims a range, and `hold: true` lets a final beat run to the cut.
+
+**Do not write `at`.** A hand-written second cannot be validated and will not be
+caught: the module-07 pilot shipped `at: 6.6` for a phrase that begins at 12.6s and
+passed every check. `resolve-beats` rejects a beat with `at` but no `line`, and
+rejects a baked `at` that disagrees with the measured onset by more than 60 ms.
+
+```bash
+node ../explainer-video-from-coursework/tools/resolve-beats.mjs --work out/<name>/<NN>
+```
+
+Run this before `pacing-check`: it resolves each `line` to seconds, writes `beats.json`,
+and fails when a line does not exist, beats run out of order, or a narration line has
+no beat (narration playing with nothing changing on screen).
+
+A beat's dwell should be **how long its lines are spoken**. Only add `min` when the
+visual genuinely needs longer than its line — and then reach for a wider `lines` range
+before reaching for `pad` (stage 5's over-ask ladder).
+
+### The loop, expressed as tool invocations
+
+```
+write / edit a scene
+  → node ../explainer-video-from-coursework/tools/pacing-check.mjs --scene out/<name>/<NN>/scenes/<name>.js \
+        --timeline out/<name>/<NN>/timeline.json --segment <key>
+        (a shortfall means the scene over-asked — widen the beat's `lines` range,
+         or redesign the beat. Only then consider a pad.)
+  → last resort, if the visual really needs more screen time than its words take:
+        set `pad` on the script segment and `hold: true` on the beat, then:
+        node ../explainer-video-from-coursework/tools/build-audio.mjs --script out/<name>/scripts/<NN>-*.json \
+              --out out/<name>/<NN> --voice Aoede
+        (free — TTS is text-cached — and it re-tiles the timeline wider)
+        line times stay valid: a pad widens the window, never the segment WAV
+  → if you REWROTE the narration instead (extending it):
+        re-run build-audio, then align.mjs, then resolve-beats.mjs — a new WAV
+        invalidates every line time. resolve-beats --script … catches the omission.
+  → node ../explainer-video-from-coursework/tools/render.mjs --shots 6,20,34 --work out/<name>/<NN> \
+        --scene "src/scene-diagram.html?scene=<name>"
+  → LOOK at the stills      ← the step nothing automates
+  → fix → repeat
+```
+
+The checkers catch timing and structure, never a visual fault — a missing chip, an
+orphaned connector, a wrong colour. Only looking at a rendered frame catches those.
+
+**Done when:** `pacing-check` exits 0 **and** every still has been eyeballed.
+
+## Maintenance
+
+> If you modify this file, or the user asks to change this stage, tell the user that the
+> main `explainer-video-from-coursework` skill's **"Stage 5 — /scene"** section must be
+> reconciled to match, and name that section in your reply.