explainer-video 0.4.0 → 0.4.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "explainer-video",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Turn structured coursework notes, or a codebase's major code flows, into a narrated, animated explainer-video series.",
   "author": {
     "name": "Akshay Prabhakant"

package/README.md

@@ -15,7 +15,8 @@ content-bearing section is assigned to a video or classified as navigation
 ## The pipeline
 
 Stage 0 (`/inputs`) collects the two things only you can decide — the source
-notes directory, and where the finished videos land.
+notes directory, and where the finished videos land — plus, optionally, the playlist
+name a series is published under (it is never guessed; a series left blank is asked about at 6b).
 
 | # | stage | what it does | cost |
 |---|-------|--------------|------|
@@ -25,6 +26,7 @@ notes directory, and where the finished videos land.
 | 4 | `/audio` | TTS → a measured timeline | **network — spends the Gemini key** |
 | 5 | `/scene` | author the visuals (`diagram` / `code` / `svg`) | free, agent |
 | 6 | `/publish` | YouTube chapters + captions | free — no TTS, no Chromium |
+| 6b | `/thumbnail` | a 1280x720 `thumbnail.png`: one hook over a still from the video's own scenes, plus a `<playlist>-Part X, <title>` label for a series | free — one Chromium screenshot |
 | 7 | `/render` | frames → H.264 MP4 | local CPU |
 | 8 | `/assemble` | per-segment parts → the finished cut | local CPU |
 
@@ -69,7 +71,7 @@ agy plugin install https://github.com/akshayDev17/ai-explainer-video
 ```
 
 All four commands install the **same** npm package — one package, three manifest surfaces,
-one copy of all sixteen skills: the ten video skills, `coursework-author`, the companion
+one copy of all seventeen skills: the eleven video skills, `coursework-author`, the companion
 skill for writing the coursework these videos come from, and the five code-flow skills:
 `explainer-video-from-codebase`, which makes explainer videos of a codebase's major code flows
 (Python, TypeScript / JavaScript, Go, C, C++, or a mix), and its four stage skills. It mines the
@@ -101,9 +103,9 @@ Invoke the skill with the notes directory:
 /explainer-video-from-coursework path/to/your/notes/
 ```
 
-You get one `.mp4` per video, plus `description.md` (blurb and a paste-ready
-chapter block) and `captions.srt`, copied to the destination you chose — by
-default `videos/` beside the source. Scratch stays in a gitignored
+You get one `.mp4` per video, plus `title.txt`, `description.md` (blurb and a
+paste-ready chapter block), `captions.srt` and a `thumbnail.png`, copied to the
+destination you chose — by default `videos/` beside the source. Scratch stays in a gitignored
 `out/<name>/<NN>/`.
 
 For a codebase, invoke the code-flow skill with the repo root instead:
@@ -127,7 +129,7 @@ plugin.json                              Agent Plugins manifest (Codex, Antigrav
 .agents/plugins/                         marketplace.json (Codex)
 cordis.patch.yml + lib/index.js          DSH bundle plugin (serves this package's skills/)
 skills/explainer-video-from-coursework/  the main skill: SKILL.md, tools/, src/, scenes/, SETUP.md
-skills/craft-video-<stage>/              the 9 stage skills, separately invocable
+skills/craft-video-<stage>/              the 10 stage skills, separately invocable
 skills/coursework-author/                the companion skill: authoring the coursework (vendored copy)
 skills/explainer-video-from-codebase/    the code-flow skill: SKILL.md, FLOWS.md, tools/, vendored tree-sitter
 skills/craft-codeflow-<stage>/           its 4 stage skills (mine, flows, plan, scene), separately invocable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explainer-video",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Turn structured coursework notes, or a codebase's major code flows, into a narrated, animated explainer-video series.",
   "type": "module",
   "main": "lib/index.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "explainer-video",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Turn structured coursework notes, or a codebase's major code flows, into a narrated, animated explainer-video series.",
   "author": {
     "name": "Akshay Prabhakant"

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

@@ -48,7 +48,8 @@ windows tile the timeline with no gaps · the finished audio matches the narrati
 
 **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.
+`description.md` and `captions.srt` that publish wrote and the `thumbnail.png` that
+thumbnail (stage 6b) wrote.
 
 <!-- sync:codeflow-publish-render -->
 **Code-flow videos only.** A code-flow video's plan, `plan.json` or `plan.enriched.json`, carries

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

@@ -0,0 +1,168 @@
+---
+name: craft-video-thumbnail
+description: Design the upload thumbnail for one video — a mildly tacky, attractive 1280x720 PNG with one clear hook over a still from the video's own scenes and, for a series, a "<playlist name>-Part X, <title>" label. Stage 6b of explainer-video-from-coursework.
+---
+
+# craft-video-thumbnail — the upload thumbnail
+
+> Part of the `explainer-video-from-coursework` pipeline — **stage 6b of 8**, between
+> publish (6) and render (7). It needs the final upload title (`title.txt`, from stage 6)
+> and the stage-5 scenes, but not the finished MP4, so it runs before the expensive render.
+>
+> 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 6b
+> node ../explainer-video-from-coursework/tools/stamp.mjs end   --out out/<name> --video <NN> --stage 6b
+> ```
+
+**Prerequisites:** `--dest/<NN>-<slug>/title.txt` (stage 6), the video's stage-5 scenes and
+`manifest.json`, `out/<name>/plan.enriched.json`, and the Stage 0 playlist answer; on the
+machine, headless Chromium (see `SETUP.md`) and `ffmpeg` for the phone-size preview.
+
+> A `headless Chromium not found` / `Playwright cache not found` failure means Chromium is
+> absent — relay the `SETUP.md` step to the user and re-run.
+
+The output is `--dest/<NN>-<slug>/thumbnail.png`, beside `title.txt`: a 1280x720 PNG of at
+most 2,000,000 bytes, exactly what `upload_yt_video` picks up. The upload takes
+`thumbnail.png`, `.jpg` or `.jpeg` from the video's folder, PNG or JPG only, refuses a file
+over 2 MB and ignores `thumbnail.svg`. It is rendered from an HTML template by the
+pipeline's own headless Chromium, never by a paid image-generation API.
+
+### The brief
+
+A viewer reads the thumbnail and the title together, in a fraction of a second, usually at
+phone size. Every thumbnail follows the owner's brief:
+
+- **Mildly tacky, attractive.** Loud on purpose: fat outlined type, a hard drop shadow, one
+  bright accent, a tilted sticker. But one hook and one visual, nothing else competing:
+  tacky is the energy, not clutter.
+- **One clear hook.** At most 5 big words (32 characters) that make a viewer want the
+  answer: a tension, a surprise, a stake ("The bug nobody catches", "Your data is lying").
+  It **complements the upload title and never repeats it**: the title says what the video
+  is, the hook says why it is worth the click. Highlight the one word that carries the
+  punch. Never promise what the video does not deliver, the same rule as the title.
+- **Sentence case.** Write the hook and the badge in sentence case: the first word capitalised,
+  the rest lower case except proper nouns, acronyms and product names ("Your data is lying",
+  "Why TypeScript lies"). The template renders text exactly as written, so never type them in
+  all capitals.
+- **High contrast.** White type with a black stroke over a darkened wedge, and one accent
+  colour (default yellow `#FFD400`) picked to stand out against the still, not to match it.
+- **A strong visual from the video itself.** A still rendered from one of this video's own
+  stage-5 scenes, at the beat that shows the idea at its most dramatic (the failure, the
+  reveal, the before and after), cropped with `focus` so its subject sits clear of the hook.
+  Never stock art, never a logo on its own.
+- **Readable at small mobile size.** If the hook cannot be read in the 320x180 preview, it
+  is too long: cut words.
+
+### The series label
+
+When the video belongs to a series or an intended playlist, a band across the top reads
+**`<playlist name>-Part X, <title>`**: the first link of chronology a new viewer sees.
+
+- **The playlist name comes only from the user**: the Stage 0 answer. Never guess it, never
+  default it, never derive it from the notes or the repo. Pass `--standalone`, with no
+  label, only when the plan has one video or the user explicitly said there is no
+  playlist; a blank Stage 0 answer on a series is not that.
+- **Unset for a series means ask.** With neither `--playlist` nor `--standalone`, a plan of
+  more than one video exits **3**. Ask the user whether the series is published as a
+  playlist and under what name, then re-run with `--playlist "<name>"` or `--standalone`.
+- **Part X** is computed by the tool: the video's 1-based position in
+  `plan.enriched.json`'s `videos` list, its index after curation's skips and merges. It is
+  not the raw `videoIndex`, which keeps the gaps curation left.
+- **The title** is the final upload title, read from `title.txt`.
+
+### Pick the still
+
+Choose the beat from the scenes you authored at stage 5, then render that instant:
+
+```bash
+node ../explainer-video-from-coursework/tools/render.mjs --shots <t> --work out/<name>/<NN> \
+     --scene "src/scene-diagram.html?scene=<name>" --shot-dir out/<name>/<NN>/thumbnail
+```
+
+`--shots` takes seconds of video time; pick one inside the segment's window in
+`timeline.json`. Use the segment's own host (`scene-diagram`, `scene-svg` or `scene-code`).
+
+### Write `thumbnail.json`
+
+Write `out/<name>/<NN>/thumbnail.json`:
+
+```json
+{
+  "hook": "The bug nobody catches",
+  "highlight": "nobody",
+  "still": "thumbnail/t000042.png",
+  "focus": { "x": 0.7, "y": 0.45, "zoom": 1.3 },
+  "accent": "#FFD400",
+  "badge": "8 min"
+}
+```
+
+- `hook` (required) — at most 5 words and 32 characters; it must not repeat the upload title.
+- `highlight` (optional) — a word of the hook, or a list of them, drawn in the accent colour.
+- `still` (required) — the PNG from the step above, relative to the work dir.
+- `focus` (optional) — the still's point to keep in view, `x` and `y` as fractions (0–1),
+  and a `zoom` of 1–4. The hook sits on the left, so frame the subject to the right.
+- `accent` (optional) — a hex colour for the highlight, the label band, the badge and the bar.
+- `badge` (optional) — a short tilted sticker, 1–16 characters ("8 min", "Fixed"), in sentence case like the hook.
+
+### Render and check
+
+```bash
+node ../explainer-video-from-coursework/tools/thumbnail.mjs --work out/<name>/<NN> \
+     --script out/<name>/scripts/<NN>-*.json --plan out/<name>/plan.enriched.json \
+     --dest <destination> [--playlist "<name>" | --standalone]
+```
+
+It validates `thumbnail.json`, adds the series label, photographs `src/thumbnail.html` at
+1280x720, checks the PNG and copies it into `--dest/<NN>-<slug>/`. It also writes
+`out/<name>/<NN>/thumbnail.small.png`, a 320x180 copy for the phone-size look. It costs no
+TTS and takes about a second, so iterate freely.
+
+| Exit | Meaning |
+|---|---|
+| 0 | written: `thumbnail.png` in the work dir and in `--dest/<NN>-<slug>/` |
+| 1 | a missing input or prerequisite: no `thumbnail.json`, no `title.txt` (run `/publish` first), a video not in the enriched plan, no Chromium |
+| 2 | a check failed: the hook, the still, the crop, or the PNG (not 1280x720, not a PNG, over 2,000,000 bytes) |
+| 3 | a series with no playlist decision: ask the user, never invent a name |
+
+### Look at it
+
+The tool checks the shape of the thumbnail, never its appeal. **Vision gate:** read
+`thumbnail.png` as an image. If that fails, you are on a text-only model: ask the user
+whether to switch to a vision model or to skip the visual check. Never "look" blind.
+
+Read both `thumbnail.png` and `thumbnail.small.png`, and check:
+
+- the hook reads in the small copy, and the highlighted word is the punch;
+- the hook does not cover the still's subject (move `focus`, or pick another still);
+- the label, when there is one, is whole and names the right part and title;
+- nothing is clipped at an edge, and the accent stands out against the still;
+- it is loud and a little tacky, and still one idea, not a collage.
+
+**Done when:** `thumbnail` exits 0, `thumbnail.png` sits in `--dest/<NN>-<slug>/` beside
+`title.txt`, and both PNGs have been looked at, or the user skipped the visual check.
+
+<!-- sync:codeflow-thumbnail -->
+**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 stage 6b:
+
+- **Hook.** Name the flow in the viewer's terms, such as what a request does, what breaks or what a command runs
+  ("One click, three services"). Never use a module path, a file name or an identifier: `thumbnail` refuses a hook
+  word that is a path (`./x`, `dir/file.ext`, `a/b/c`), lowercase-first camelCase (`getUser`), snake_case, a dotted
+  module path (`pkg.mod.fn`), `::` or a call (`fn()`). Viewer words such as TypeScript, macOS, gRPC, I/O and CI/CD pass.
+- **Still.** Take it from a diagram beat (the overview's system map, a flow's sequence, an eval's hand-off), never
+  from a code panel: a wall of code is unreadable texture at thumbnail size.
+- **Secrets.** Never put a secret or a redacted value on the thumbnail.
+<!-- /sync:codeflow-thumbnail -->
+
+## 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 6b — /thumbnail"** section must be
+> reconciled to match, and name that section in your reply.

package/skills/explainer-video-from-codebase/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: explainer-video-from-codebase
-description: Turn the major code flows of a codebase (Python, TypeScript / TSX, JavaScript, Go, C, C++, or a mix such as a Python backend with a TypeScript frontend) into a narrated explainer-video series. Mine the repo into a grouped code map, rank candidate flows as evidence, optionally trace the test suite in a sandbox, propose the series with a reason per flow for the user to approve, plan the videos under a 25-minute cap, then script, voice, animate (verified code panels and generated flow diagrams), publish, render and assemble each one. Use when the user wants explainer videos of how a codebase works.
+description: Turn the major code flows of a codebase (Python, TypeScript / TSX, JavaScript, Go, C, C++, or a mix such as a Python backend with a TypeScript frontend) into a narrated explainer-video series. Mine the repo into a grouped code map, rank candidate flows as evidence, optionally trace the test suite in a sandbox, propose the series with a reason per flow for the user to approve, plan the videos under a 25-minute cap, then script, voice, animate (verified code panels and generated flow diagrams), publish, design the thumbnail, render and assemble each one. Use when the user wants explainer videos of how a codebase works.
 ---
 
 # explainer-video-from-codebase — mine, propose, approve, plan, then the per-video stages
@@ -14,10 +14,10 @@ scratch root. Stages 1–1c run once over the whole repo:
 - code plans the videos in the coursework plan's shape.
 
 Stages 2–8 are `explainer-video-from-coursework`'s own stages, run on that plan: retitle once, then per video
-write the narration, synthesize the audio, author the visuals, generate the publishing metadata, render and
-assemble. Three places differ for code. Stage 3 adds the code-video rules below, and stages 6–8 add a render and
-a title rule. Stage 5 uses `craft-codeflow-scene`: code panels cut from the repo and diagrams generated from the
-validated flows.
+write the narration, synthesize the audio, author the visuals, generate the publishing metadata, design the
+thumbnail, render and assemble. Four places differ for code. Stage 3 adds the code-video rules below, stages 6–8
+add a render and a title rule, and stage 6b adds a hook and a still rule. Stage 5 uses `craft-codeflow-scene`: code
+panels cut from the repo and diagrams generated from the validated flows.
 
 **Paths.** `<skill>` is this skill's folder and `<coursework>` is the sibling `../explainer-video-from-coursework`,
 both resolved against this skill's folder. The tools self-locate everything else, so they run regardless of cwd.
@@ -35,8 +35,9 @@ the **scratch root** that Stage 0 fixes. The scratch root is always **outside th
 >
 > Each is a complete contract for its stage, top-level under `skills/` so any stage can be re-run alone.
 > Stages 2–4b and 6–8 are the coursework `craft-video-<stage>` skills. Stages 2, 4 and 4b are unchanged for code;
-> `craft-video-script` (stage 3) and `craft-video-publish`, `-render` and `-assemble` (stages 6–8) also carry this
-> file's code-video rules for their stage, in a sync block that opens **Code-flow videos only**. Every
+> `craft-video-script` (stage 3), `craft-video-publish`, `-render` and `-assemble` (stages 6–8) and
+> `craft-video-thumbnail` (stage 6b) also carry this file's code-video rules for their stage, in a sync block that
+> opens **Code-flow videos only**. Every
 > `craft-codeflow-*` skill ends with a **Maintenance** note naming its section here. **If you change a stage, update
 > both files.**
 > `scripts/check-skill-sync.mjs` (CI) fails when they drift:
@@ -111,9 +112,9 @@ what is missing and the install steps from the matching `SETUP.md` section, then
 | 3 | `/script` | per video | `craft-video-script` (its code-flow block, the addendum below) | `script-check` exits 0 (pause rule included) |
 | 4, 4b | `/audio`, `/align` | per video | `craft-video-audio`, `craft-video-align` | unchanged |
 | 5 | `/scene` | per video | **`craft-codeflow-scene`** | `excerpt-check` and `pacing-check` exit 0; the stills looked at |
-| 6–8 | `/publish`, `/render`, `/assemble` | per video | `craft-video-publish`, `-render`, `-assemble` (their code-flow block) | unchanged |
+| 6, 6b, 7, 8 | `/publish`, `/thumbnail`, `/render`, `/assemble` | per video | `craft-video-publish`, `-thumbnail`, `-render`, `-assemble` (their code-flow block) | unchanged; 6b writes `thumbnail.png`, looked at |
 
-## Stage 0 — `/inputs`: repo, destination, scratch
+## Stage 0 — `/inputs`: repo, destination, scratch, playlist
 
 Ask for what the user must decide. If the invocation already names them, skip the question. Ask **together, in
 one prompt, with defaults**, so the user only adjusts and never invents:
@@ -125,6 +126,11 @@ one prompt, with defaults**, so the user only adjusts and never invents:
   folder beside the repo, `<repo>/../<repo name>-videos/`. It must be outside the repo, since the tools refuse to
   write there. A series runs to hundreds of MB of WAV and MP4, so it is worth one line in the prompt. Say
   plainly that the default is fine.
+- **Playlist name** (optional) — the playlist the series is published under, or *none* to say it has no playlist.
+  Stage 6b prints it on every thumbnail as `<playlist name>-Part X, <title>`. It has **no default** and is never
+  guessed, least of all from the repo's name. Carry the answer to stage 6b as `--playlist "<name>"`; pass
+  `--standalone` only when the plan has one video or the user explicitly said there is no playlist. Blank is not
+  *none*: on a plan of more than one video it passes neither flag, so stage 6b exits 3 and you ask.
 
 Note, without asking unless the user raises them, the optional scope flags stage 1 takes:
 
@@ -133,7 +139,8 @@ Note, without asking unless the user raises them, the optional scope flags stage
 - `--group 'glob=prod|test|eval|dev'` for a file the group rules misplace;
 - `--config-root` for config kept outside the repo, such as a deploy repo's Helm values.
 
-Then change to the scratch root once and stay there. Proceed to stage 1 only once all three are set.
+Then change to the scratch root once and stay there. Proceed to stage 1 only once the repo, destination and scratch
+root are set.
 
 ## Stage 1 — `/mine`: code map, candidates, ranking
 
@@ -623,7 +630,8 @@ node <coursework>/tools/stamp.mjs end --out out/<name> --video <NN> --stage 5
 
 ## Stages 6–8 — `/publish`, `/render`, `/assemble`
 
-Run `craft-video-publish`, `craft-video-render` and `craft-video-assemble`, each with its code-flow block:
+Run `craft-video-publish`, then `craft-video-thumbnail` (stage 6b, below), then `craft-video-render` and
+`craft-video-assemble`, each with its code-flow block:
 
 <!-- sync:codeflow-publish-render -->
 **Code-flow videos only.** A code-flow video's plan, `plan.json` or `plan.enriched.json`, carries
@@ -640,6 +648,37 @@ in this block applies to its videos. A code-flow video adds these rules at stage
 **Done when:** each stage's own gate holds, ending in `assemble`'s `[done] …<output>.mp4` with `audio ok`, and
 the assembled frames have been looked at.
 
+## Stage 6b — `/thumbnail`: the code-flow hook
+
+Run `craft-video-thumbnail` after `/publish` and before `/render`: it needs the final upload title (`title.txt`)
+and the stage-5 scenes, not the finished MP4. It writes `<destination>/<NN>-<slug>/thumbnail.png`, a 1280x720 PNG
+of at most 2,000,000 bytes, beside `title.txt`, where `upload_yt_video` picks it up.
+
+```sh
+node <coursework>/tools/thumbnail.mjs --work out/<name>/<NN> --script out/<name>/scripts/<NN>-*.json \
+     --plan out/<name>/plan.enriched.json --dest <destination> [--playlist "<name>" | --standalone]
+```
+
+The brief, the series label and the visual check are the coursework stage's. Part X is the video's 1-based
+position in `plan.enriched.json`'s `videos`, and the playlist name is only ever the user's Stage 0 answer: exit 3
+means a series with no answer, so ask. A code-flow video adds:
+
+<!-- sync:codeflow-thumbnail -->
+**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 stage 6b:
+
+- **Hook.** Name the flow in the viewer's terms, such as what a request does, what breaks or what a command runs
+  ("One click, three services"). Never use a module path, a file name or an identifier: `thumbnail` refuses a hook
+  word that is a path (`./x`, `dir/file.ext`, `a/b/c`), lowercase-first camelCase (`getUser`), snake_case, a dotted
+  module path (`pkg.mod.fn`), `::` or a call (`fn()`). Viewer words such as TypeScript, macOS, gRPC, I/O and CI/CD pass.
+- **Still.** Take it from a diagram beat (the overview's system map, a flow's sequence, an eval's hand-off), never
+  from a code panel: a wall of code is unreadable texture at thumbnail size.
+- **Secrets.** Never put a secret or a redacted value on the thumbnail.
+<!-- /sync:codeflow-thumbnail -->
+
+**Done when:** `thumbnail` exits 0 and `thumbnail.png` and `thumbnail.small.png` have been looked at.
+
 ## Reference
 
 Every artifact's fields are in [`FLOWS.md`](./FLOWS.md):

package/skills/explainer-video-from-coursework/ARCHITECTURE.md

@@ -29,6 +29,8 @@ judgment to a *second* LLM via an API call is strictly worse:
 | audio — TTS | **code** | **Gemini TTS API** ← the only API call in the pipeline |
 | publish config — chapter grouping, titles, blurb | **agent** | none |
 | `publish.mjs` — resolve timecodes, emit chapters/captions, validate | **code** | none |
+| thumbnail config — the hook, the still, the crop | **agent** | none |
+| `thumbnail.mjs` — series label, Chromium screenshot, PNG check | **code** | none |
 | `render.mjs` — Chromium frames, ffmpeg | **code** | none |
 
 Everything except audio runs offline. The planner and the merge/validate step

package/skills/explainer-video-from-coursework/PIPELINE.md

@@ -222,6 +222,27 @@ however valid the list. Its description timestamps still work as jump-to-section
 what is missing is the segmented progress bar and Google key moments. Nothing in
 `description.md` can change this, so absent chapters are not a formatting fault.
 
+### 6b · `/thumbnail` — the upload thumbnail
+
+| | |
+|---|---|
+| **Agent writes** | `out/<name>/<NN>/thumbnail.json` — the `hook` (≤5 words), a `still` rendered from one of the video's own scenes, an optional `focus` crop, `accent` and `badge` |
+| Tool | `tools/thumbnail.mjs` + the host `src/thumbnail.html` |
+| Out | `thumbnail.png` (1280x720, ≤2,000,000 bytes) — copied to `--dest/<NN>-<slug>/` beside `title.txt`; `thumbnail.small.png` (320x180) in the work dir for the phone-size look |
+| Asserts | the hook is ≤5 words / 32 chars and does not repeat the upload title · a code-flow hook names no code · the still exists · the PNG is a real PNG, exactly 1280x720, within the upload's 2 MB · a series has a playlist decision (exit 3 otherwise) |
+| Network | none |
+
+Placed **after** `/publish` because the label carries the final upload title, read from
+`title.txt`, and **before** `/render` because it needs only the stage-5 scenes, not the
+finished MP4. It is one headless-Chromium screenshot of an HTML template, so iterating on
+it is as cheap as stage 6.
+
+For a series, a band reads `<playlist name>-Part X, <title>`, the first link of chronology
+a new viewer sees. The playlist name is only ever the user's Stage 0 answer: the tool has
+no default, and a plan of more than one video with neither `--playlist` nor `--standalone`
+exits 3 so the agent asks. Part X is the video's 1-based position in
+`plan.enriched.json`'s `videos`, after curation, never the raw `videoIndex`.
+
 ### 7 · `/render` — frames to MP4
 
 | | |
@@ -258,6 +279,7 @@ whole track at every segment boundary — a bug this stage used to have.
 | `src/scene-diagram.html` | host; selects the config via `?scene=<name>` |
 | `src/scene-code.js` | code + refactor renderer — code panels, before/after |
 | `src/scene-code.html` | host; selects the config via `?scene=<name>` |
+| `src/thumbnail.html` | stage 6b's 1280x720 thumbnail template; `tools/thumbnail.mjs` passes its config as `?c=<json>` |
 | `<work>/timeline.js` | **generated** by stage 4 into the per-video work dir; browser-loadable measured timeline |
 
 ---
@@ -282,6 +304,10 @@ node tools/pacing-check.mjs --scene out/lld/06/scenes/<name>.js --timeline out/l
 # 6 — publish (agent writes publish.json: chapters + blurb)
 node tools/publish.mjs --work out/lld/06 --script out/lld/scripts/06-*.json --dest <destination>
 
+# 6b — thumbnail (agent renders a still, writes thumbnail.json: hook + still)
+node tools/thumbnail.mjs --work out/lld/06 --script out/lld/scripts/06-*.json \
+     --plan out/lld/plan.enriched.json --dest <destination> --playlist "<name>"
+
 # 7 + 8 — render and assemble
 node tools/assemble.mjs --script out/lld/scripts/06-*.json --work out/lld/06 --name video6-solid
 ```

package/skills/explainer-video-from-coursework/ROADMAP.md

@@ -16,15 +16,15 @@ assemble stages written into `SKILL.md`; video 6 (SOLID) completed end-to-end.
 
 ### The skill
 
-`SKILL.md` — all eight stages (plan, enrich, script, audio, scene, publish, render,
-assemble), each with its command, its `done when` gate, and the visual-check
-protocol (vision gate + the `LOOK` step). Distributed as one plugin of sixteen skills
+`SKILL.md` — every stage (plan, enrich, script, audio, align, scene, publish, thumbnail,
+render, assemble), each with its command, its `done when` gate, and the visual-check
+protocol (vision gate + the `LOOK` step). Distributed as one plugin
 (`plugin.json` + `skills/`) — see §2.3.
 
 ### The stage skills
 
-Eight sibling skills, one per stage, at `skills/craft-video-<stage>/SKILL.md` — top-level
-under `skills/`, so every platform that reads the plugin discovers all nine. Each is a
+One sibling skill per stage, at `skills/craft-video-<stage>/SKILL.md` — top-level
+under `skills/`, so every platform that reads the plugin discovers them all. Each is a
 complete contract for its stage — prerequisites, command, what the agent writes, hard
 checks, `done when` — and each is separately invocable, so one stage can be re-run alone.
 They reach the pipeline's tools as `../explainer-video-from-coursework/tools/<tool>.mjs`,
@@ -50,6 +50,8 @@ source notes
    │            tools/pacing-check.mjs ........ reveal rate + dead air        [code]
    ├─ /publish  agent writes publish.json
    │            tools/publish.mjs ............. chapters + captions           [code]
+   ├─ /thumbnail agent writes thumbnail.json
+   │            tools/thumbnail.mjs ........... 1280x720 PNG + series label   [code]
    ├─ /render   tools/render.mjs .............. Chromium frames + ffmpeg      [code]
    └─ /assemble tools/assemble.mjs ............ per-segment render + concat   [code]
                 tools/verify-audio.mjs ........ sample-level audio match      [code]

package/skills/explainer-video-from-coursework/SERIES.md

@@ -52,6 +52,7 @@ unmeasured — see *Open parameter* at the end.
 {
   "plan": "out/<name>/plan.enriched.json",
   "destination": "videos/",
+  "playlist": "Systems 101",
   "parallel": 2,
   "portBase": 9333,
   "videos": [
@@ -73,6 +74,13 @@ It lives in this file rather than being a flag because a resumed session must no
 different value: `parallel` determines port allocation, and changing it mid-run
 invalidates every port already claimed.
 
+`playlist` is the user's playlist name, verbatim, or `null` only when the user explicitly
+said the series has no playlist. A blank Stage 0 answer is neither: before writing this
+file, the orchestrator asks the user the question stage 6b's exit 3 asks (is the series a
+playlist, and under what name). It is recorded here once so that every per-video agent
+prints the same `<playlist>-Part X, <title>` label on its thumbnail (stage 6b) without
+asking again; it is never guessed or filled in by the orchestrator.
+
 Titles are **not** duplicated here — they live in `plan.enriched.json`, which stays the
 single source of truth for content. Two copies would drift.
 
@@ -88,20 +96,22 @@ single source of truth for content. Two copies would drift.
     "4b": { "done": true, "attempts": 1, "ended_at": "…" },
     "5":  { "done": true, "attempts": 1, "ended_at": "…" },
     "6":  { "done": true, "attempts": 1, "ended_at": "…" },
+    "6b": { "done": true, "attempts": 1, "ended_at": "…" },
     "7":  { "done": true, "attempts": 1, "ended_at": "…" },
     "8":  { "done": false, "attempts": 1, "last_error": null }
   },
   "artefacts": {
     "script": "…", "lines": "…", "beats": "…", "manifest": "…",
     "mp4": "videos/<slug>/<name>.mp4",
-    "description": "videos/<slug>/description.md", "captions": "videos/<slug>/captions.srt"
+    "description": "videos/<slug>/description.md", "captions": "videos/<slug>/captions.srt",
+    "thumbnail": "videos/<slug>/thumbnail.png"
   },
   "render": { "port": 9333, "attempts": 1 },
   "qa": { "stills_checked": true, "beats_audited": 48, "verdict": "accept" }
 }
 ```
 
-`status` ∈ `queued · authoring · audio · aligning · scenes · publishing · rendering ·
+`status` ∈ `queued · authoring · audio · aligning · scenes · publishing · thumbnail · rendering ·
 qa · done · failed · needs-fresh`.
 
 **One writer per file** — that video's agent. Write atomically (temp + `renameSync`).
@@ -146,6 +156,7 @@ Each stage, in order, with its gate:
 | **5** | Author `scenes/` + `manifest.json` + `intent.md`; `resolve-beats`; `pacing-check` per segment | pacing is sound for every segment |
 | **5·QA** | **Stills gate** — `render --shots` at 3–5 mid-segment times on the assigned port, then **look at them** | no collision, no missing heading, nothing cropped |
 | **6** | `publish.json` → `publish` | chapters and cues validate |
+| **6b** | `thumbnail.json` → `thumbnail --playlist "<series.json playlist>"` (or `--standalone` when it is `null`), then **look at it** | exits 0; the full and phone-size PNGs eyeballed |
 | **7–8** | `assemble --dest videos` | exits 0 with `audio ok` |
 
 Then: sample the finished MP4, look, and either accept or fix-and-re-render.

package/skills/explainer-video-from-coursework/SKILL.md

@@ -1,20 +1,20 @@
 ---
 name: explainer-video-from-coursework
-description: Plan an explainer-video series from a directory of coursework notes — decompose into videos (proving nothing is dropped), retitle and curate, write the narration, synthesize the audio, author the visuals, then render and assemble the finished cut. Use when the user wants to turn structured coursework notes into explainer videos.
+description: Plan an explainer-video series from a directory of coursework notes — decompose into videos (proving nothing is dropped), retitle and curate, write the narration, synthesize the audio, author the visuals, design the upload thumbnail, then render and assemble the finished cut. Use when the user wants to turn structured coursework notes into explainer videos.
 ---
 
-# explainer-video-from-coursework — plan, enrich, script, audio, scene, publish, render, assemble
+# explainer-video-from-coursework — plan, enrich, script, audio, scene, publish, thumbnail, render, assemble
 
 Turn a notes directory into a **video series**. Stage 0 gathers the source and the
 destination; stages 1–2 run once over the whole directory and plan the series (the
 planner decomposes and proves completeness; you retitle and curate); stages 3–8 then
 run **once per video** — write the narration, TTS turns it into measured audio, you
-author the visuals, generate the publishing metadata, then render and assemble that
-video's finished cut.
+author the visuals, generate the publishing metadata, design the thumbnail, then render
+and assemble that video's finished cut.
 
 The skill's own files (`tools/`, `src/`, `scenes/`) live in **this skill's folder** — resolve
 `tools/<tool>.mjs` against it; the tools then self-locate everything else, so they run
-regardless of cwd. The eight `craft-video-<stage>` skills sit beside this one under `skills/`.
+regardless of cwd. The `craft-video-<stage>` skills, one per stage, sit beside this one under `skills/`.
 But the work and scratch paths (`out/`, `--work`, `--out`, `<notesDir>`) resolve against the
 **current directory**, so run every command from the **scratch root** — the directory that
 holds `out/`. Stage 0 fixes it once, defaulting beside the source. Never run from the skill's
@@ -72,7 +72,7 @@ section, then re-run.
   run). The series is the full deliverable, but each video is produced
   independently.
 
-## Stage 0 — `/inputs`: source, destination, scratch
+## Stage 0 — `/inputs`: source, destination, scratch, playlist
 
 Ask for what the user must decide; everything else is the skill's. If the invocation
 already names them, skip. Ask **together, one prompt, with defaults** for destination
@@ -82,8 +82,8 @@ and scratch so the user only adjusts, never invents:
   otherwise list candidate directories that contain `.md` files and let them pick.
 - **Destination** — where the finished video(s) land. Default: `videos/` beside the
   source. Each finished video lands in its **own folder** under the destination —
-  `<destination>/<NN>-<slug>/` — holding the `.mp4`, `title.txt`, `description.md`
-  and `captions.srt`. The folder name is derived from the plan's `videoIndex` (the
+  `<destination>/<NN>-<slug>/` — holding the `.mp4`, `title.txt`, `description.md`,
+  `captions.srt` and `thumbnail.png`. The folder name is derived from the plan's `videoIndex` (the
   consumption order) and a slug of the title, so a series sorts into watch order and
   a shared destination can never collide across videos. If the user puts it **inside**
   the source — `<source>/videos/` is a common choice — Stage 1 must `--exclude` it, or
@@ -94,13 +94,19 @@ and scratch so the user only adjusts, never invents:
   Not a throwaway: a series runs to hundreds of MB of WAV and MP4, so it is worth one
   line in the prompt rather than a surprise later. Say plainly that the default is
   fine; the user should not have to think about it.
+- **Playlist name** (optional) — the playlist the series is published under, or *none*
+  to say it has no playlist. Stage 6b prints it on every thumbnail as `<playlist
+  name>-Part X, <title>`. It has **no default** and is never guessed. Carry the answer to
+  stage 6b as `--playlist "<name>"`; pass `--standalone` only when the plan has one video
+  or the user explicitly said there is no playlist. Blank is not *none*: on a plan of
+  more than one video it passes neither flag, so stage 6b exits 3 and you ask.
 
 Then `cd` to the scratch root once and stay there. It is the only cwd that makes the
 `out/<name>/…` paths below resolve. If that root is inside a git work tree, `planner`
 verifies `out/` is ignored and appends a rule when it is not, printing what it changed;
 outside a repo there is nothing to ignore and it stays silent.
 
-Proceed to Stage 1 only once all three are set. After Stage 1, show the plan's own
+Proceed to Stage 1 only once source, destination and scratch root are set. After Stage 1, show the plan's own
 numbers as a free confirmation — *"`<source>` → N markdown files → M videos, landing
 in `<destination>`"* — before Stage 2 and the `Choose the scope` gate spend anything.
 
@@ -651,6 +657,139 @@ sprawl out of watch order.
 node tools/stamp.mjs end --out out/<name> --video <NN> --stage 6
 ```
 
+## Stage 6b — `/thumbnail`: the upload thumbnail
+
+```bash
+node tools/stamp.mjs begin --out out/<name> --video <NN> --stage 6b
+```
+
+
+It sits after `/publish` and before `/render` because it needs the final upload title
+(`title.txt`) and the stage-5 visuals, but not the finished MP4. Like stage 6, it costs no
+TTS, so a thumbnail can be argued with while a fix is still cheap.
+
+The output is `--dest/<NN>-<slug>/thumbnail.png`, beside `title.txt`: a 1280x720 PNG of at
+most 2,000,000 bytes, exactly what `upload_yt_video` picks up. The upload takes
+`thumbnail.png`, `.jpg` or `.jpeg` from the video's folder, PNG or JPG only, refuses a file
+over 2 MB and ignores `thumbnail.svg`. It is rendered from an HTML template
+(`src/thumbnail.html`) by the pipeline's own headless Chromium, never by a paid
+image-generation API.
+
+### The brief
+
+A viewer reads the thumbnail and the title together, in a fraction of a second, usually at
+phone size. Every thumbnail follows the owner's brief:
+
+- **Mildly tacky, attractive.** Loud on purpose: fat outlined type, a hard drop shadow, one
+  bright accent, a tilted sticker. But one hook and one visual, nothing else competing:
+  tacky is the energy, not clutter.
+- **One clear hook.** At most 5 big words (32 characters) that make a viewer want the
+  answer: a tension, a surprise, a stake ("The bug nobody catches", "Your data is lying").
+  It **complements the upload title and never repeats it**: the title says what the video
+  is, the hook says why it is worth the click. Highlight the one word that carries the
+  punch. Never promise what the video does not deliver, the same rule as the title.
+- **Sentence case.** Write the hook and the badge in sentence case: the first word capitalised,
+  the rest lower case except proper nouns, acronyms and product names ("Your data is lying",
+  "Why TypeScript lies"). The template renders text exactly as written, so never type them in
+  all capitals.
+- **High contrast.** White type with a black stroke over a darkened wedge, and one accent
+  colour (default yellow `#FFD400`) picked to stand out against the still, not to match it.
+- **A strong visual from the video itself.** A still rendered from one of this video's own
+  stage-5 scenes, at the beat that shows the idea at its most dramatic (the failure, the
+  reveal, the before and after), cropped with `focus` so its subject sits clear of the hook.
+  Never stock art, never a logo on its own.
+- **Readable at small mobile size.** If the hook cannot be read in the 320x180 preview, it
+  is too long: cut words.
+
+### The series label
+
+When the video belongs to a series or an intended playlist, a band across the top reads
+**`<playlist name>-Part X, <title>`**: the first link of chronology a new viewer sees.
+
+- **The playlist name comes only from the user**: the Stage 0 answer. Never guess it, never
+  default it, never derive it from the notes. Pass `--standalone`, with no label, only
+  when the plan has one video or the user explicitly said there is no playlist; a blank
+  Stage 0 answer on a series is not that.
+- **Unset for a series means ask.** With neither `--playlist` nor `--standalone`, a plan of
+  more than one video exits **3**. Ask the user whether the series is published as a
+  playlist and under what name, then re-run with `--playlist "<name>"` or `--standalone`.
+- **Part X** is computed by the tool: the video's 1-based position in
+  `plan.enriched.json`'s `videos` list, its index after curation's skips and merges. It is
+  not the raw `videoIndex`, which keeps the gaps curation left.
+- **The title** is the final upload title, read from `title.txt`.
+
+### Pick the still, write `thumbnail.json`
+
+Choose the beat from the scenes you authored at stage 5, then render that instant with the
+segment's own host:
+
+```bash
+node tools/render.mjs --shots <t> --work out/<name>/<NN> \
+     --scene "src/scene-diagram.html?scene=<name>" --shot-dir out/<name>/<NN>/thumbnail
+```
+
+Then write `out/<name>/<NN>/thumbnail.json`:
+
+```json
+{
+  "hook": "The bug nobody catches",
+  "highlight": "nobody",
+  "still": "thumbnail/t000042.png",
+  "focus": { "x": 0.7, "y": 0.45, "zoom": 1.3 },
+  "accent": "#FFD400",
+  "badge": "8 min"
+}
+```
+
+- `hook` (required) — at most 5 words and 32 characters; it must not repeat the upload title.
+- `highlight` (optional) — a word of the hook, or a list of them, drawn in the accent colour.
+- `still` (required) — the PNG from the step above, relative to the work dir.
+- `focus` (optional) — the still's point to keep in view, `x` and `y` as fractions (0–1),
+  and a `zoom` of 1–4. The hook sits on the left, so frame the subject to the right.
+- `accent` (optional) — a hex colour for the highlight, the label band, the badge and the bar.
+- `badge` (optional) — a short tilted sticker, 1–16 characters ("8 min", "Fixed"), in sentence case like the hook.
+
+### Render and check
+
+```bash
+node tools/thumbnail.mjs --work out/<name>/<NN> \
+     --script out/<name>/scripts/<NN>-*.json --plan out/<name>/plan.enriched.json \
+     --dest <destination> [--playlist "<name>" | --standalone]
+```
+
+It validates `thumbnail.json`, adds the series label, photographs `src/thumbnail.html` at
+1280x720, checks the PNG and copies it into `--dest/<NN>-<slug>/`. It also writes
+`out/<name>/<NN>/thumbnail.small.png`, a 320x180 copy for the phone-size look.
+
+| Exit | Meaning |
+|---|---|
+| 0 | written: `thumbnail.png` in the work dir and in `--dest/<NN>-<slug>/` |
+| 1 | a missing input or prerequisite: no `thumbnail.json`, no `title.txt` (run `/publish` first), a video not in the enriched plan, no Chromium |
+| 2 | a check failed: the hook, the still, the crop, or the PNG (not 1280x720, not a PNG, over 2,000,000 bytes) |
+| 3 | a series with no playlist decision: ask the user, never invent a name |
+
+### The visual check
+
+The tool checks the shape of the thumbnail, never its appeal. **Vision gate:** read
+`thumbnail.png` as an image. If that fails, you are on a text-only model: ask the user
+whether to switch to a vision model or to skip the visual check. Never "look" blind.
+
+Read both `thumbnail.png` and `thumbnail.small.png`, and check:
+
+- the hook reads in the small copy, and the highlighted word is the punch;
+- the hook does not cover the still's subject (move `focus`, or pick another still);
+- the label, when there is one, is whole and names the right part and title;
+- nothing is clipped at an edge, and the accent stands out against the still;
+- it is loud and a little tacky, and still one idea, not a collage.
+
+**Done when:** `thumbnail` exits 0, `thumbnail.png` sits in `--dest/<NN>-<slug>/` beside
+`title.txt`, and both PNGs have been looked at, or the user skipped the visual check.
+
+
+```bash
+node tools/stamp.mjs end --out out/<name> --video <NN> --stage 6b
+```
+
 ## Stage 7 — `/render`: frames to MP4
 
 ```bash
@@ -739,7 +878,8 @@ video's scene (verified — byte-identical frames, exit 0, a valid MP4 of the wr
 video). This is why the per-video agent can own stage 8 end to end on its own port.
 
 With `--dest`, the finished MP4 lands in `<destination>/<NN>-<slug>/<output>.mp4` —
-the same folder `publish` (stage 6) wrote `description.md` and `captions.srt` into.
+the same folder `publish` (stage 6) wrote `description.md` and `captions.srt` into, and
+`thumbnail` (stage 6b) wrote `thumbnail.png` into.
 
 Per segment: render its own window through its own host + config, **silent** — parts
 are silent on purpose, because muxing narration onto each one would restart the whole

package/skills/explainer-video-from-coursework/src/thumbnail.html

@@ -0,0 +1,119 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Thumbnail host — stage 6b</title>
+<style>
+  html, body { margin:0; padding:0; width:1280px; height:720px; overflow:hidden; background:#0b0b12; }
+  #frame { position:relative; width:1280px; height:720px; overflow:hidden; }
+  /* the still: a frame of the video's own scene, cropped to its strongest part and pushed louder */
+  #still { position:absolute; inset:0; width:1280px; height:720px; object-fit:cover;
+           filter:saturate(1.35) contrast(1.12) brightness(0.9); }
+  /* a dark wedge behind the hook, so white type reads at any size */
+  #shade { position:absolute; inset:0;
+           background:linear-gradient(100deg, rgba(0,0,0,.86) 0%, rgba(0,0,0,.62) 42%, rgba(0,0,0,0) 74%),
+                      linear-gradient(0deg, rgba(0,0,0,.55) 0%, rgba(0,0,0,0) 32%); }
+  #label { position:absolute; left:0; right:0; top:0; padding:14px 40px 16px; box-sizing:border-box;
+           color:#111; font:800 40px/1.12 "Helvetica Neue", Helvetica, Arial, sans-serif;
+           letter-spacing:-0.01em; box-shadow:0 6px 0 rgba(0,0,0,.55); }
+  #hook { position:absolute; left:52px; width:780px; display:flex; flex-direction:column; justify-content:center;
+          transform:rotate(-2.5deg); transform-origin:left center; }
+  #hook .t { margin:0; color:#fff; line-height:0.98; letter-spacing:0.01em;
+             font-family:Impact, Haettenschweiler, "Arial Narrow Bold", "Arial Black", sans-serif; font-weight:900;
+             -webkit-text-stroke:0.085em #000; paint-order:stroke fill; text-shadow:0.06em 0.07em 0 #000;
+             overflow-wrap:normal; word-break:keep-all; }
+  #badge { position:absolute; right:46px; padding:14px 26px; transform:rotate(7deg);
+           color:#111; font:900 44px/1 Impact, Haettenschweiler, "Arial Black", sans-serif;
+           border:6px solid #fff; border-radius:18px; box-shadow:8px 9px 0 #000; }
+  #bar { position:absolute; left:0; right:0; bottom:0; height:16px; }
+</style>
+</head>
+<body>
+<!--
+  Stage 6b's thumbnail host. tools/thumbnail.mjs passes the resolved config as JSON in `?c=`:
+
+    { hook, marked[] (word positions in the hook), label|null, still (file URL), focus {x, y, zoom}, accent, badge|null }
+
+  and photographs the page at 1280x720 with the headless Chromium. Everything is laid out
+  synchronously before the load event, so the screenshot never races the layout.
+-->
+<div id="frame">
+  <img id="still" alt="">
+  <div id="shade"></div>
+  <div id="hook"><p class="t"></p></div>
+  <div id="bar"></div>
+</div>
+<script>
+  var C = JSON.parse(new URLSearchParams(location.search).get('c') || '{}');
+  var frame = document.getElementById('frame');
+  var accent = C.accent || '#FFD400';
+
+  var still = document.getElementById('still');
+  var f = C.focus || {};
+  var zoom = f.zoom || 1;
+  still.style.objectPosition = (100 * (f.x == null ? 0.5 : f.x)) + '% ' + (100 * (f.y == null ? 0.5 : f.y)) + '%';
+  still.style.transformOrigin = still.style.objectPosition;
+  still.style.transform = 'scale(' + zoom + ')';
+  if (C.still) still.src = C.still;
+
+  document.getElementById('bar').style.background = accent;
+
+  // shrink a box's font until nothing overflows its width and its content fits h; returns the size it settled on.
+  // With `text` (an inline child holding the words), the width test is the text's own width against the box's
+  // content width, so the box's side padding stays clear; scrollWidth alone cannot see into the right padding.
+  function fit(el, max, min, h, text) {
+    var lo = min, hi = max;
+    var cs = getComputedStyle(el);
+    var room = el.clientWidth - parseFloat(cs.paddingLeft) - parseFloat(cs.paddingRight);
+    while (hi - lo > 1) {
+      var mid = (lo + hi) >> 1;
+      el.style.fontSize = mid + 'px';
+      var wide = text ? text.getBoundingClientRect().width > room : el.scrollWidth > el.clientWidth;
+      if (!wide && el.scrollHeight <= h) lo = mid; else hi = mid;
+    }
+    el.style.fontSize = lo + 'px';
+    return lo;
+  }
+
+  var y0 = 40;   // where the hook may start: below the label when there is one (never `top`, which is window.top)
+  if (C.label) {
+    var label = document.createElement('div');
+    label.id = 'label';
+    label.style.background = accent;
+    var words = document.createElement('span');
+    words.textContent = C.label;
+    label.appendChild(words);
+    frame.appendChild(label);
+    // one line when it fits at a readable size, else two
+    label.style.whiteSpace = 'nowrap';
+    if (fit(label, 40, 18, 200, words) < 30) { label.style.whiteSpace = "normal"; fit(label, 36, 18, 112, words); }
+    y0 = label.offsetHeight + 34;
+  }
+
+  if (C.badge) {
+    var badge = document.createElement('div');
+    badge.id = 'badge';
+    badge.style.background = accent;
+    badge.style.top = (y0 + 6) + 'px';
+    badge.textContent = C.badge;
+    frame.appendChild(badge);
+  }
+
+  var hook = document.getElementById('hook');
+  var text = hook.querySelector('.t');
+  var marked = C.marked || [];
+  String(C.hook || '').split(' ').forEach(function (word, i) {
+    if (i) text.appendChild(document.createTextNode(' '));
+    var span = document.createElement('span');
+    span.textContent = word;
+    if (marked.indexOf(i) !== -1) span.style.color = accent;
+    text.appendChild(span);
+  });
+  var hookH = 720 - y0 - 64;
+  hook.style.top = y0 + 'px';
+  hook.style.height = hookH + 'px';
+  fit(text, 230, 48, hookH);
+  document.body.setAttribute('data-ready', '1');
+</script>
+</body>
+</html>

package/skills/explainer-video-from-coursework/tools/stamp.mjs

@@ -26,7 +26,7 @@ const argv = process.argv.slice(2);
 const cmd = argv[0];
 const flag = (n, d) => { const i = argv.indexOf('--' + n); return i === -1 ? d : argv[i + 1]; };
 
-const STAGES = new Set(['3', '4', '4b', '5', '6', '7', '8']);
+const STAGES = new Set(['3', '4', '4b', '5', '6', '6b', '7', '8']);
 const outDir = flag('out');
 const video = flag('video');
 const stage = flag('stage');

package/skills/explainer-video-from-coursework/tools/thumbnail.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/* =============================================================================
+   thumbnail.mjs — /thumbnail stage (stage 6b): the upload thumbnail.
+
+   The agent writes out/<name>/<NN>/thumbnail.json (the hook, a still from its own
+   stage-5 scenes, an optional crop, accent and badge); this tool adds the series label,
+   photographs src/thumbnail.html at 1280x720 with the headless Chromium, checks the PNG,
+   and copies it into the video's destination folder beside title.txt:
+
+       --dest/<NN>-<slug>/thumbnail.png   — what upload_yt_video picks up
+
+   The series label reads "<playlist>-Part <X>, <upload title>". The playlist name only
+   ever comes from the user (--playlist); a plan of more than one video with neither
+   --playlist nor --standalone is refused with exit 3, so the agent asks instead of
+   inventing one. Part X is the video's 1-based position in plan.enriched.json's
+   `videos` list (after curation's skips and merges), not its raw videoIndex.
+
+   Usage:
+     node tools/thumbnail.mjs --work out/<name>/<NN> --script out/<name>/scripts/<NN>-*.json \
+                              --plan out/<name>/plan.enriched.json --dest <destination> \
+                              [--playlist "<name>" | --standalone]
+
+   Exit: 0 written · 1 a missing input or prerequisite · 2 the config
+   or the PNG fails a check · 3 a series with no playlist decision (ask the user).
+   ========================================================================== */
+
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { chromiumBinOrExit } from './chromium.mjs';
+import { videoDir } from './naming.mjs';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+export const WIDTH = 1280;
+export const HEIGHT = 720;
+// upload_yt_video refuses a thumbnail over 2 MB; the decimal reading is the stricter one
+export const MAX_BYTES = 2_000_000;
+
+/* ---------------- the PNG ---------------- */
+const PNG_SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+// width and height from the IHDR chunk, or null for anything that is not a PNG
+export function pngInfo(buf) {
+  if (buf.length < 24 || !buf.subarray(0, 8).equals(PNG_SIG) || buf.toString('latin1', 12, 16) !== 'IHDR') return null;
+  return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+
+// every way the file fails what the upload tool and YouTube accept
+export function checkThumbnail(buf) {
+  const problems = [];
+  const info = pngInfo(buf);
+  if (!info) problems.push(/^\xff\xd8\xff/.test(buf.toString('latin1', 0, 3))
+    ? 'it is a JPEG named as a PNG: write a real PNG'
+    : 'not a PNG (no PNG signature and IHDR chunk)');
+  else if (info.width !== WIDTH || info.height !== HEIGHT) problems.push(`it is ${info.width}x${info.height}; a thumbnail is ${WIDTH}x${HEIGHT}`);
+  if (buf.length > MAX_BYTES) problems.push(`it is ${buf.length.toLocaleString('en-US')} bytes; the upload refuses more than ${MAX_BYTES.toLocaleString('en-US')}`);
+  return problems;
+}
+
+/* ---------------- the series label ---------------- */
+// the video's place in the series as produced: its 1-based position among the plan's surviving videos
+export function partOf(plan, videoIndex) {
+  const videos = (plan && plan.videos) || [];
+  const at = videos.findIndex((v) => Number(v.index) === Number(videoIndex));
+  return at === -1 ? null : { part: at + 1, of: videos.length };
+}
+
+export const seriesLabel = (playlist, part, title) => `${playlist}-Part ${part}, ${title}`;
+
+/* ---------------- the config ---------------- */
+const norm = (s) => String(s).toLowerCase().replace(/[^a-z0-9' ]+/g, ' ').replace(/\s+/g, ' ').trim();
+const words = (s) => norm(s).split(' ').filter(Boolean);
+const STOP = new Set(['a', 'an', 'the', 'of', 'to', 'in', 'on', 'and', 'or', 'is', 'it', 'for', 'how', 'why', 'what', 'your', 'you']);
+
+// one hook word as the template compares it: case and punctuation dropped, so "Zero-copy" and "zero-copy!" are one word
+const wordKey = (w) => String(w).toLowerCase().replace(/[^\p{L}\p{N}']/gu, '');
+
+// the positions of the hook's whitespace-separated words that a highlight names; the template colours exactly these
+export function markedWords(hook, highlight) {
+  const keys = new Set([].concat(highlight || []).map(wordKey).filter(Boolean));
+  return hook.split(' ').flatMap((w, i) => (keys.has(wordKey(w)) ? [i] : []));
+}
+
+// a hook word that is code, not the viewer's terms: a path, an identifier, a module path or a call
+const CODE = [
+  (w) => /^\.{1,2}\//.test(w),
+  (w) => w.includes('/') && w.split('/').some((s) => /^[\w-]+\.[A-Za-z][A-Za-z0-9]{0,4}$/.test(s)),
+  (w) => /[A-Za-z_][\w-]*(\/[A-Za-z_][\w-]*){2,}/.test(w),
+  (w) => /^[a-z][a-z0-9]+[A-Z][a-z]/.test(w),
+  (w) => /[A-Za-z0-9]_[A-Za-z0-9]/.test(w),
+  (w) => /^[a-z_]\w*(\.[A-Za-z_]\w*){2,}/.test(w),
+  (w) => /\w::\w/.test(w),
+  (w) => /\w\(\)/.test(w),
+];
+export const codeWords = (hook) => hook.split(' ')
+  .filter((w) => { const bare = w.replace(/^[^\w./]+/, '').replace(/[^\w)]+$/, ''); return CODE.some((is) => is(bare)); });
+
+// { errors, warnings } for thumbnail.json against the upload title; `codebase` adds the code-flow rule
+export function checkConfig(cfg, { title = '', codebase = false } = {}) {
+  const errors = [];
+  const warnings = [];
+  const hook = typeof cfg.hook === 'string' ? cfg.hook.replace(/\s+/g, ' ').trim() : '';
+  if (!hook) errors.push('"hook" is missing: a few big words that make a viewer want the answer');
+  else {
+    const n = hook.split(' ').length;
+    if (n > 5) errors.push(`"hook" is ${n} words; at most 5 read at phone size`);
+    if (hook.length > 32) errors.push(`"hook" is ${hook.length} characters; at most 32 read at phone size`);
+    const h = norm(hook), t = norm(title);
+    if (t && (h === t || ` ${t} `.includes(` ${h} `))) errors.push(`"hook" repeats the upload title ("${title}"); it must add to it, not echo it`);
+    else if (t) {
+      const own = words(hook).filter((w) => !STOP.has(w));
+      const shared = own.filter((w) => words(title).includes(w));
+      if (own.length && shared.length / own.length > 0.5) warnings.push(`"hook" shares most of its words with the upload title (${shared.join(', ')}); a hook that complements the title earns the click`);
+    }
+    if (codebase) {
+      const code = codeWords(hook);
+      if (code.length) errors.push(`"hook" names code (${code.join(', ')}); a code-flow hook names the flow in the viewer's terms, never a module path or an identifier`);
+    }
+    for (const w of [].concat(cfg.highlight || [])) {
+      if (!markedWords(hook, w).length) errors.push(`"highlight" word "${w}" is not in the hook`);
+    }
+  }
+  if (cfg.highlight != null && !Array.isArray(cfg.highlight) && typeof cfg.highlight !== 'string') errors.push('"highlight" is a word of the hook or a list of them');
+  if (typeof cfg.still !== 'string' || !cfg.still.trim()) errors.push('"still" is missing: a PNG rendered from one of this video\'s own stage-5 scenes');
+  if (cfg.focus != null) {
+    const { x = 0.5, y = 0.5, zoom = 1 } = cfg.focus;
+    if (![x, y].every((v) => typeof v === 'number' && v >= 0 && v <= 1)) errors.push('"focus" x and y are fractions of the still, 0 to 1');
+    if (typeof zoom !== 'number' || zoom < 1 || zoom > 4) errors.push('"focus" zoom is 1 to 4');
+  }
+  if (cfg.accent != null && !/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(String(cfg.accent))) errors.push('"accent" is a hex colour such as "#FFD400"');
+  if (cfg.badge != null && (typeof cfg.badge !== 'string' || !cfg.badge.trim() || cfg.badge.length > 16)) errors.push('"badge" is a short sticker, 1 to 16 characters');
+  return { errors, warnings };
+}
+
+/* ---------------- CLI ---------------- */
+function main(argv) {
+  const has = (n) => argv.includes('--' + n);
+  const flag = (n) => { const i = argv.indexOf('--' + n); return i === -1 ? undefined : argv[i + 1]; };
+  const die = (code, msg) => { console.error(`[thumbnail] ${msg}`); process.exit(code); };
+  const readJson = (p, what) => {
+    if (!existsSync(p)) die(1, `no ${what} at ${p}`);
+    try { return JSON.parse(readFileSync(p, 'utf8')); } catch (e) { die(1, `${what} at ${p} is not JSON: ${e.message}`); }
+  };
+  const report = (file, problems) => {
+    if (problems.length) {
+      console.error(`[thumbnail] ✗ ${file}`);
+      for (const p of problems) console.error(`     - ${p}`);
+      process.exit(2);
+    }
+  };
+
+  const WORK = flag('work'), SCRIPT = flag('script'), PLAN = flag('plan'), DEST = flag('dest');
+  if (!WORK || !SCRIPT || !PLAN || !DEST)
+    die(1, 'usage: thumbnail.mjs --work <work-dir> --script <script.json> --plan <plan.enriched.json> --dest <dir> [--playlist "<name>" | --standalone]');
+  const workDir = resolve(WORK);
+  const script = readJson(resolve(SCRIPT), 'script');
+  const plan = readJson(resolve(PLAN), 'enriched plan');
+  const cfg = readJson(join(workDir, 'thumbnail.json'), 'thumbnail.json (write it first: hook + still)');
+
+  const where = partOf(plan, script.videoIndex);
+  if (!where) die(1, `video ${script.videoIndex} is not in ${PLAN}: pass the enriched plan, which lists the videos curation kept`);
+
+  const destDir = join(resolve(DEST), videoDir(script, basename(workDir)));
+  const titleFile = join(destDir, 'title.txt');
+  if (!existsSync(titleFile)) die(1, `no title.txt at ${titleFile}: run /publish (stage 6) first, the thumbnail needs the final upload title`);
+  const title = readFileSync(titleFile, 'utf8').trim();
+
+  /* The playlist name is the user's, never ours: no default, no guess. */
+  const playlist = flag('playlist');
+  if (playlist !== undefined && has('standalone')) die(1, 'pass --playlist or --standalone, not both');
+  if (playlist !== undefined && !String(playlist).trim()) die(1, '--playlist is empty: pass the user\'s playlist name, --standalone if they said there is none, or neither flag to be asked');
+  if (playlist === undefined && !has('standalone') && where.of > 1)
+    die(3, `this plan has ${where.of} videos, so video ${script.videoIndex} looks like part of a series, and no playlist name was given. ` +
+      'Ask the user for the playlist name (or whether it is standalone), then re-run with --playlist "<name>" or --standalone. Never invent one.');
+  const label = playlist === undefined ? null : seriesLabel(String(playlist).trim(), where.part, title);
+
+  const { errors, warnings } = checkConfig(cfg, { title, codebase: plan.kind === 'codebase' });
+  const stillPath = typeof cfg.still === 'string' ? (isAbsolute(cfg.still) ? cfg.still : join(workDir, cfg.still)) : null;
+  if (stillPath && !existsSync(stillPath)) errors.push(`"still" ${cfg.still} does not exist (paths are relative to ${workDir})`);
+  for (const w of warnings) console.log(`  ⚠ ${w}`);
+  report(join(workDir, 'thumbnail.json'), errors);
+
+  /* Photograph the host: everything is laid out before the load event, so --screenshot never races it. */
+  const bin = chromiumBinOrExit('thumbnail');
+  const hook = cfg.hook.replace(/\s+/g, ' ').trim();
+  const config = {
+    hook,
+    marked: markedWords(hook, cfg.highlight),
+    label,
+    still: pathToFileURL(stillPath).href,
+    focus: cfg.focus || null,
+    accent: cfg.accent || null,
+    badge: cfg.badge ? cfg.badge.trim() : null,
+  };
+  const url = pathToFileURL(join(ROOT, 'src', 'thumbnail.html')).href + '?c=' + encodeURIComponent(JSON.stringify(config));
+  const out = join(workDir, 'thumbnail.png');
+  rmSync(out, { force: true });
+  const shot = spawnSync(bin, ['--headless', '--disable-gpu', '--no-sandbox', '--hide-scrollbars',
+    '--force-device-scale-factor=1', '--allow-file-access-from-files', '--disable-lcd-text', '--font-render-hinting=none',
+    `--window-size=${WIDTH},${HEIGHT}`, `--screenshot=${out}`, url], { encoding: 'utf8', timeout: 60_000 });
+  if (!existsSync(out)) die(1, `Chromium wrote no screenshot (exit ${shot.status}${shot.error ? `, ${shot.error.message}` : ''})\n${(shot.stderr || '').trim().split('\n').slice(-5).join('\n')}`);
+  report(out, checkThumbnail(readFileSync(out)));
+
+  /* The phone-size look: YouTube's mobile lists show a thumbnail a few hundred pixels wide. */
+  const small = join(workDir, 'thumbnail.small.png');
+  const scaled = spawnSync('ffmpeg', ['-y', '-v', 'error', '-i', out, '-vf', 'scale=320:180', small], { encoding: 'utf8' });
+  if (scaled.error || scaled.status !== 0) console.log(`  ⚠ no phone-size preview (ffmpeg ${scaled.error ? 'not found' : 'failed'}); look at the full PNG at a small zoom instead`);
+
+  mkdirSync(destDir, { recursive: true });
+  copyFileSync(out, join(destDir, 'thumbnail.png'));
+  for (const other of ['thumbnail.jpg', 'thumbnail.jpeg']) {
+    if (existsSync(join(destDir, other))) console.log(`  ⚠ ${join(destDir, other)} is also there; the upload may pick it instead of thumbnail.png, so remove it`);
+  }
+  console.log(`  hook     : "${config.hook}"`);
+  console.log(`  label    : ${label ? `"${label}"` : '— (standalone video)'}`);
+  console.log(`  still    : ${stillPath}`);
+  console.log(`\n[out] ${out}`);
+  if (existsSync(small)) console.log(`[out] ${small}`);
+  console.log(`[dest] ${join(destDir, 'thumbnail.png')}`);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2));

package/skills/explainer-video-from-coursework/tools/timing-report.mjs

@@ -65,7 +65,7 @@ const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;')
   .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 const fmtDur = (n) => n < 60 ? `${round1(n)}s` : `${Math.floor(n / 60)}m${Math.round(n % 60)}s`;
 
-const STAGE_NAMES = { '3': 'script', '4': 'audio', '4b': 'align', '5': 'scene', '6': 'publish', '7': 'render', '8': 'assemble' };
+const STAGE_NAMES = { '3': 'script', '4': 'audio', '4b': 'align', '5': 'scene', '6': 'publish', '6b': 'thumbnail', '7': 'render', '8': 'assemble' };
 const PALETTE = ['#4f46e5', '#0ea5e9', '#14b8a6', '#f59e0b', '#ef4444', '#8b5cf6',
                  '#ec4899', '#10b981', '#f97316', '#6366f1', '#a855f7', '#22c55e'];