Skip to content

An AI skill that turns books into animated, narrated, interactive web experiences

docs(skill): align the picture-book references with the tools and episodes 4-7

yzrbc3d635dea68
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.md
index c6d227c..3687595 100644
--- a/.claude/skills/papermorph/SKILL.md
+++ b/.claude/skills/papermorph/SKILL.md
@@ -9,7 +9,7 @@ Each chapter is a short animated lesson film: the picture carries the explanatio
What the picture should be depends on the book and on the user, so the work starts with a conversation ([intake.md](references/intake.md)) that ends in `style.json`, the book's agreed style. Every chapter is made against it. `style.json` fixes the atoms (palette and meanings, fonts, voice, cast, shared components, approved chapters); composition stays free, so how each beat is laid out and choreographed is yours to judge against it and the approved chapters. Then read the reference for the technique in use: [diagrams.md](references/diagrams.md) (symbols and diagrams that change), [scenes.md](references/scenes.md) (illustrated scenes, actors, camera), [assets.md](references/assets.md) (shared components, images, sprites), [authoring.md](references/authoring.md) (chapter shape, narration, questions), [engine.md](references/engine.md), [review.md](references/review.md), [site.md](references/site.md), [team.md](references/team.md) (making chapters with subagents).
-**Picture books** are the same machine pointed at a story: short films of paper puppets in front of sets, drawn in code or painted by an image model, with voices, effects and music. When the user brings a story, a joke or a fairy tale instead of a textbook, follow [stories.md](references/stories.md) (with [puppets.md](references/puppets.md), [painting.md](references/painting.md) and [sound.md](references/sound.md)) in place of the PDF steps; the engine, previews, review, site and team below apply unchanged.
+**Picture books** are the same machine pointed at a story: short films of paper puppets in front of sets, drawn in code or painted by an image model, with voices, effects and music. When the user brings a story, a joke or a fairy tale instead of a textbook, follow [stories.md](references/stories.md) (with [puppets.md](references/puppets.md), [painting.md](references/painting.md) and [sound.md](references/sound.md)) in place of the PDF steps; the engine, previews, review and team below apply unchanged, and [site.md](references/site.md#a-picture-book) starts the book folder.
Follow the pipeline forward, entering at the requested stage for existing work. User requests override defaults. Re-create explanations, examples and drawings; keep source PDFs, page images and extracted text outside the static output folder and out of version control (`.gitignore`: `*.pdf`, `books/*/pages/`). Deliver a self-contained book folder with a cover, contents, chapters and local preview instructions.
@@ -35,7 +35,7 @@ site/<book>/ the static book (only this is delivered)
chNN/index.html, audio/<lang>/ a lesson, its beat MP3s + timings.js
```
-A picture book adds `books/<book>/story.md` (the user's telling, verbatim), `storyboard.md`, `sets.js` (set sketches) and `art/` (generated pictures, `painted.json`, `costs.tsv`); its `site/<book>/lib/` holds the paper kit (`paper.js`, `cast.js`, `shared.js` from `assets/templates/picture-book/`) and `img/` the baked sets, props and puppet pieces; each episode `chNN/` has one script per scene and `audio/<lang>/`, `audio/sfx/`, `audio/bgm/`.
+A picture book adds `books/<book>/story.md` (the user's telling, verbatim), `storyboard.md` and `art/` (`sets.js` with the set sketches, generated pictures, `painted.json`, `costs.tsv`); its `site/<book>/lib/` holds the paper kit (`paper.js`, `cast.js`, `shared.js` from `assets/templates/picture-book/`) and `img/` the baked sets, props and puppet pieces; each episode `chNN/` has one script per scene and `audio/<lang>/`, `audio/sfx/`, `audio/bgm/`.
`SKILL` means this skill's absolute folder; `<book>` is the book slug, `<lang>` its primary language code. Existing books keep their paths. Needs: `uv`, `ffmpeg`/`ffprobe`, Edge TTS network access (or Kokoro, local: `uv run --python 3.12 --with kokoro`) and Playwright browsers (`uv run --with playwright playwright install chromium firefox`). Preview: `python3 SKILL/scripts/serve.py 8765 site` (no browser caching).
diff --git a/.claude/skills/papermorph/references/assets.md b/.claude/skills/papermorph/references/assets.md
index 6a112f3..f1d45be 100644
--- a/.claude/skills/papermorph/references/assets.md
+++ b/.claude/skills/papermorph/references/assets.md
@@ -17,4 +17,4 @@ Laying out a chapter's moments shows what the library lacks: a new prop, a place
- Sprite animation: put a character's frames in one sheet and switch frames by changing a nested `<svg>`'s viewBox; changing an `<image href>` per frame can refetch. Pixel art is drawn at an integer scale with `image-rendering: pixelated` and pre-scaled files.
- One large detailed object (a planet, a map) is cheaper as a single image than as many shapes; see the Firefox notes in [engine.md](engine.md#performance-firefox).
-Image-model generation is not part of the pipeline yet; it will come with picture-book and documentary looks.
+Pictures from an image model (sets and props for picture books, and any other book that agrees a budget) go through `paint.py` and `painted.py`; see [painting.md](painting.md).
diff --git a/.claude/skills/papermorph/references/painting.md b/.claude/skills/papermorph/references/painting.md
index 4d43776..994e7af 100644
--- a/.claude/skills/papermorph/references/painting.md
+++ b/.claude/skills/papermorph/references/painting.md
@@ -8,12 +8,12 @@ Paint one set two or three ways at the cheapest quality, stand the puppets in ea
## Getting the composition you need
-Puppets stand at fixed places, counters must hide the right legs, and cuts must match. The reliable way is to draw the set first as a rough SVG sketch (`bake_sets.py` renders it), then ask the model to repaint *that picture* in the style of the reference: the layout survives, the look changes. Then:
+Puppets stand at fixed places, counters must hide the right legs, and cuts must match. The reliable way is to draw the set first as a rough SVG sketch in `books/<book>/art/sets.js` (`bake_sets.py … --ref books/<book>/art` renders each set as one frame, `ref-<set>.png`), then ask the model to repaint *that picture* in the style of the reference: the layout survives, the look changes. Once a set is painted, `bake_sets.py` leaves it alone unless you name it. Then:
- **Cut-outs for whatever people stand behind.** A counter, a cart, rows of desks, a lectern: paint each as its own picture on a transparent background and place it as a layer (`painted.py`, `cut`).
- **Variants by editing, not redrawing.** Rain and snow versions of a street, a door open and shut, a bun with a bite: edit the one picture, so a cut between versions changes only that.
- **Leave signs blank.** Image models garble text, Chinese and Japanese worst. Paint the banner, the shop sign, the blackboard empty and let `painted.py` write the words on in a real font.
-- **Paint wider than the frame.** Camera shakes and zooms see past the edge; `painted.py` pads full frames.
+- **Paint wider than the frame.** Camera shakes and zooms see past the edge; `painted.py` pads full frames by mirroring their edges, and when something near an edge (a post box) shows twice in a close-up, `"edge": "stretch"` on that layer pads it with its own outermost pixels instead.
Everything that comes out goes through `painted.py` (manifest `books/<book>/art/painted.json`): sets resized to the 1600×900 frame, blurred copies for close-ups, cut-outs placed, words written, props written to `img/props/`. Stand the puppets in a frame and look before going on.
diff --git a/.claude/skills/papermorph/references/puppets.md b/.claude/skills/papermorph/references/puppets.md
index 304ff22..0fc4a59 100644
--- a/.claude/skills/papermorph/references/puppets.md
+++ b/.claude/skills/papermorph/references/puppets.md
@@ -2,7 +2,7 @@
The actors of a picture book are paper puppets drawn in code: pieces of coloured paper pinned at the joints, moved a little each frame, like a cut-out film shot by hand. Because a pose is only a set of numbers, any action the story needs (ducking, swinging an axe, diving through a window, shoving a thought bubble) costs a few lines, never a new drawing, and a puppet looks the same in every shot. The kit is in `assets/templates/picture-book/` (`paper.js`, `cast.js`, `shared.js`, `chapter.html`); copy it into `site/<book>/lib/` and the episode folder.
-Two cast styles are on the shelf, both from the same kit: jointed storybook figures seen mostly in profile (*Little Red Riding Hood*: the wolf, Grandma, the woodcutter) and round-headed figures that face us, in the spirit of South Park (*Joke Collection*). Pick with the user; the second is quicker to build and to act with.
+Two cast styles are on the shelf, both on the same `paper.js`: round-headed figures that face us, in the spirit of South Park (*Joke Collection*), which the kit's `cast.js` builds (add a character by copying an entry of its `SHAPES`), and jointed storybook figures seen mostly in profile (*Little Red Riding Hood*: the wolf, Grandma, the woodcutter), which a book draws itself, a side set and a front set per figure. Pick with the user; the first is quicker to build and to act with.
## What makes it read as stop motion
@@ -14,7 +14,7 @@ Two cast styles are on the shelf, both from the same kit: jointed storybook figu
## Acting
- **Nobody freezes.** Whoever speaks lip-syncs; everyone blinks at their own moments, never in unison; listeners' eyes follow the speaker; reactions get a small head turn or a lid drop. A crowd glances about on its own and turns as one only when something happens (a staggered snap, a frame or two apart).
-- **Turning round is a whole-body swap.** A puppet has a complete side set and a complete front set. A turn squashes the side view, swaps to the whole front figure for the narrowest frames and comes out mirrored. A front head on a side body looked wrong every time.
+- **Turning round.** A round-headed puppet turns by sliding its face across the head (`look`), as South Park does. A profile puppet turns as a whole-body swap: the side view squashes, the whole front figure shows for the narrowest frames, and it comes out mirrored. A front head on a side body looked wrong every time.
- **Feet don't slide.** Walks use a compass step (`walk()`): the planted foot stays put while the hip swings over it; distance is scale. Runs are on twos with a bigger bob.
- **Hands touch what they hold.** A held prop belongs to the hand's piece; when something is handed over, both hands meet it.
- **Things behind things.** A counter, a cart, a desk row or a lectern sits on its own layer between puppets, so the person behind shows from the chest up (`paperCam(…, { after, stages })` puts puppet layers between set layers).
@@ -25,8 +25,8 @@ Two cast styles are on the shelf, both from the same kit: jointed storybook figu
## Performance
-Paper filters are expensive live. Every finished piece is baked to a bitmap: sets with `bake_sets.py` (SVG sketches) or `painted.py` (painted pictures), puppet and prop pieces with `bake_puppets.py`, which seeks every episode to its end so each piece is asked for once and writes `img/puppets/<hash>.webp` with `baked.js`. The parts that change every frame (eyes, mouths, brows, fingers) stay live. In a series every episode's pieces share one folder: `bake_puppets.py` adds new pieces and keeps the others, and `--clean` rebakes every episode before replacing them, so leave the folder to it (a hand-written prune once deleted a published episode's pieces; git brought them back). Rebake after changing any piece; a piece missing from `baked.js` is baked in the browser and costs a stall. Full-frame effects that change every frame (the flicker) live outside the SVG so the picture isn't redrawn each frame.
+Paper filters are expensive live. Every finished piece is baked to a bitmap: sets with `bake_sets.py` (SVG sketches) or `painted.py` (painted pictures), puppet and prop pieces with `bake_puppets.py`, which seeks every episode to its end, in Chromium and in Firefox, so each piece is asked for once, and writes `img/puppets/<hash>.webp` with `baked.js`. The parts that change every frame (eyes, mouths, brows, fingers) stay live. In a series every episode's pieces share one folder: `bake_puppets.py` encodes only pieces it has not baked before and keeps the others, and `--clean` (after changing the paper filter itself) re-encodes them all and removes only what no episode asks for any more, so leave the folder to it (a hand-written prune once deleted a published episode's pieces; git brought them back). Rebake after changing any piece or adding an episode; a piece missing from `baked.js` is baked in the browser and costs a stall, and `shot.py` says how many pieces a chapter still bakes live. Full-frame effects that change every frame (the flicker) live outside the SVG so the picture isn't redrawn each frame.
## Seeing your own work
-The preview server must not cache (`serve.py`). Look at contact sheets that advance the clock the way playback does (`strip.py chNN OUT scene1/0.5`), at full-size frames at the key moments, at the last frame of each scene beside the first of the next, and play the whole episode through once at speed. Some faults appear only in continuous playback (a camera layer shown once and never hidden again), so don't rely on jumps with `?t=` alone.
+The preview server must not cache (`serve.py`). Look at contact sheets that advance the clock the way playback does (`strip.py chNN OUT scene1/0.5 --url http://localhost:8765/<book>/`; times are on the beat clock, so a scene's speech starts at its `pre`, and marks of a joined scene are named `clip.mark`), at full-size frames at the key moments, at the last frame of each scene beside the first of the next, and play the whole episode through once at speed. Some faults appear only in continuous playback (a camera layer shown once and never hidden again), so don't rely on jumps with `?t=` alone.
diff --git a/.claude/skills/papermorph/references/site.md b/.claude/skills/papermorph/references/site.md
index 75a52cc..38c0c5c 100644
--- a/.claude/skills/papermorph/references/site.md
+++ b/.claude/skills/papermorph/references/site.md
@@ -18,6 +18,26 @@ cp "$SKILL/assets/templates/chapter.html" "$BOOK_SITE/ch01/index.html"
cp "$SKILL/assets/templates/narration.en.json" "content/$BOOK_ID/ch01/narration.en.json"
```
+### A picture book
+
+The contents page is the series page (each episode a chapter in `units`); the episode comes from the picture-book kit, and the empty `baked.js` stands in until `bake_puppets.py` has run:
+
+```sh
+PB="$SKILL/assets/templates/picture-book"
+mkdir -p "$BOOK_SITE/img/puppets" "$BOOK_WORK/art" "content/$BOOK_ID/ch01"
+python3 "$SKILL/scripts/engine.py" "$BOOK_SITE"
+cp "$SKILL/assets/templates/book.html" "$BOOK_SITE/index.html"
+cp "$PB"/lib/*.js "$BOOK_SITE/lib/"
+cp "$PB/chapter.html" "$BOOK_SITE/ch01/index.html"; cp "$PB/scene1.js" "$BOOK_SITE/ch01/"
+cp "$PB/sets.js" "$PB/painted.json" "$BOOK_WORK/art/"
+cp "$PB/narration.en.json" "content/$BOOK_ID/ch01/"
+echo 'window.BAKED = {};' > "$BOOK_SITE/img/puppets/baked.js"
+```
+
+Then the sound and the pictures, in this order ([sound.md](sound.md), [puppets.md](puppets.md)): `tts.py`, `mouths.py`, `join.py "$BOOK_SITE/ch01/audio/en" scene1=s01,s02,s02b,s03 --words content/$BOOK_ID/ch01/narration.en.json`, `sfx.py "$BOOK_SITE/ch01/audio/sfx" knock`, `bake_sets.py "$BOOK_WORK/art/sets.js" "$BOOK_SITE"` and, with the preview server up, `bake_puppets.py "$BOOK_SITE"`.
+
+### Every book
+
Use the pilot chapter's number in place of `ch01` when the pilot is not the first chapter. Use the agreed primary language: rename the narration source, load `audio/<lang>/timings.js`, and set `CHAPTER.language` to match (default `en`). Take `voice` and `rate` for each narration file from `style.json`, and translate the template's visible UI text as needed before the pilot.
If the book's formulas need LaTeX ([engine.md](engine.md#latex)), add MathJax (with its license) to `lib/`, and load `../lib/mathjax.js` right after `engine.js` in every chapter:
@@ -63,7 +83,7 @@ Narration and on-screen text are written in one language first. A second languag
## Video export (optional)
-`uv run --with playwright SKILL/scripts/export.py chNN --url http://localhost:8765/<book>/ --out OUT --link <lesson URL>` renders the lesson beats to `OUT/chNN.mp4` (1080p, 30 fps) plus `OUT/chNN.srt` for upload with it. Frames come from seeking the beat clock, so the video matches the page exactly; question beats are left out and the video ends on a card pointing to the interactive lesson. It takes about 1.6× the video's length.
+`uv run --with playwright --with numpy SKILL/scripts/export.py chNN --url http://localhost:8765/<book>/ --out OUT --link <lesson URL>` renders the beats to `OUT/chNN.mp4` (1080p, 30 fps) plus `OUT/chNN.srt` for upload with it. Frames come from seeking the beat clock and the sound is mixed by the page's own rules (each beat's `pre`, and in a picture book its effects and music), so the video matches the page; question beats are left out and a lesson's video ends on a card pointing to the interactive lesson. It takes about 1.6× the video's length. Video files are large (an episode at 1080p is tens of megabytes, more than a static host such as Cloudflare Pages takes per file): upload them to the video site, not into `site/`.
## SCORM package (optional)
diff --git a/.claude/skills/papermorph/references/sound.md b/.claude/skills/papermorph/references/sound.md
index a932d3b..05460ab 100644
--- a/.claude/skills/papermorph/references/sound.md
+++ b/.claude/skills/papermorph/references/sound.md
@@ -6,17 +6,20 @@ Voices carry the story; everything else sits under them. In early cuts the music
- **One voice per character.** List them under `voices` in `narration.<lang>.json` and write each line as `{"speaker": name, "text": …}`; `tts.py` synthesizes every line (Edge voices, with rate and pitch: children were adult voices sped up and pitched up). The narrator is a voice too.
- **Lines in other languages** are spoken in their own language by a native voice (Edge has Japanese, Chinese, Korean and more) and subtitled in the book's language. The caption shows both: the original and the translation in brackets. Write it as the beat's `"sub"`; `tts.py` marks such a line (its voice's locale differs from the narration file's language) so the page shows its subtitle even with captions off, the way films subtitle foreign dialogue.
-- **Mouths** follow the words: `mouths.py` turns each line's word timings into mouth shapes, and `lips(q, scene, pre, line…)` picks the shape for the frame.
-- **One clip per scene.** `join.py` joins a scene's lines into one audio clip with short pauses, and inserts silence where the action needs room (`line@T+S`: S seconds of silence T seconds into the line). Gaps for a held stare, a fly landing, a class turning round belong here, not in rushed animation. Changing a line means `tts.py`, `mouths.py` and `join.py` again.
+- **Mouths** follow the words: `mouths.py` turns each line's word timings into mouth shapes (a Chinese or Japanese line opens and shuts once per character), and `lips(q, scene, pre, line…)` picks the shape for the frame. Edge's word times run about a tenth of a second ahead of the sound; `mouths.py` and `join.py` move mouths and captions that much later and shut the mouth where the clip's sound stops, so a lip flap that leads or trails the voice is worth reporting.
+- **One clip per scene.** `join.py` joins a scene's lines into one audio clip with short pauses, and inserts silence where the action needs room (`line@T+S`: S seconds of silence T seconds into the line, after a word's sound has ended rather than where the next word begins) or after the last line (`name:S`, a stare or a tag). Gaps for a held stare, a fly landing, a class turning round belong here, not in rushed animation. `--words` writes every word's time in the scene clip beside the narration; scene authors time actions against it (the beat clock adds the scene's `pre`).
+- **One script for the whole sound.** Keep the episode's audio steps in one script beside the book's notes (`tools/<book>/audio.sh`) and rerun it after any change: lines replaced by hand, `mouths.py`, level fixes, `join.py` with its holes, any caption edits. One episode's join arguments lived only in a terminal and had to be read back out of `shots.js`.
+- **Levels.** The line the joke hangs on must not be the quietest, voices need pitches apart (a dog at 113 Hz under a 110 Hz narrator read as the same person), and peaks stay under -1 dB. A gain change goes through a limiter (`volume=3dB,alimiter=limit=0.89`) once per synthesized clip, so rerunning the script does not raise it again (remember the clip's checksum).
+- **Sounds a voice makes.** Animal voices that speak (a dog's "Woof!") came out best from an Edge voice shouting the word, trimmed and normalized; synthesized barks lost to them. A whispered "Shh." is shaped pink noise, not Edge's voiced "shh-uh". Write such a clip over the line's MP3 and set its `dur` in `timings.js` before joining.
## Sound effects
-`sfx.py` synthesizes effects (knock, door, bell, chop, bang, bonk, thud, crash, coin, beep, rain, crickets and more) as small MP3s, free and consistent. Keep them soft and natural: the first rain was a high hiss and read as scary; pink noise with patter and taps on umbrellas read as rain. An effect is placed on the scene clock with `sfx(scene, t, name, volume)` and plays at half volume under the voices; it stops when playback pauses. Cut an effect to its shot: a six-second rain under a one-second shot spills into the next.
+`sfx.py` synthesizes effects (knock, door, creak, latch, bell, chop, bang, bonk, thud, clang, crash, coin, beep, rain, wind, room tone, surf, gulls, crickets, steps and more; `--list` names them all) as small MP3s, free and consistent. Keep them soft and natural: the first rain was a high hiss and read as scary; pink noise with patter and taps on umbrellas read as rain. An effect is placed on the scene clock with `sfx(scene, t, name, volume)` and plays at half volume under the voices; a pause holds it and the next scene stops it. Cut an effect to its shot: a six-second rain under a one-second shot spills into the next. A long bed (wind, room tone) is listed in `SFX_BED` with its length, so a seek into the middle joins it part-way; a bed that loops overlaps its seams by about half a second, and room tone runs under the silences too, where its absence is heard first.
## Music
-Music is optional and goes under everything: about 70 % of its own level, ducking to 30 % while anyone speaks, fading in and out over most of a second. Give a scene silence when silence is the joke. Don't let music stop dead in the middle of a scene; carry it to the end or fade it, and bring an earlier theme back when the story returns to an earlier place. Use tracks the book may redistribute (generated for the book, or openly licensed) and credit them.
+Music is optional and goes under everything: about 70 % of its own level, and 30 % for the whole of a scene that has voices (its silent opening and tail too, so it does not swell between lines), fading in and out over most of a second. Give a scene silence when silence is the joke: `window.MUSIC_OFF = { scene: t => … }` fades it out for a stare. Don't let music stop dead in the middle of a scene; carry it to the end or fade it, and bring an earlier theme back when the story returns to an earlier place. Use tracks the book may redistribute (generated for the book, or openly licensed) and credit them.
## Captions
-Picture books turn captions on at a reader's first visit (`chapter.html` does this); the reader's own choice is remembered after that.
+Picture books turn captions on at a reader's first visit (`chapter.html` does this); the reader's own choice is remembered after that. A caption appears when its words are heard and ends at the first real pause after them; a hole inside a sentence keeps its caption up. When that gives away words before they are said (a punchline after a pause), split the caption at the hole in `shots.js`, and hold a punchline's caption into the silence after it; do this in the audio script after `join.py`, so a rerun keeps it.
diff --git a/.claude/skills/papermorph/references/stories.md b/.claude/skills/papermorph/references/stories.md
index 4b4fca7..3394e4f 100644
--- a/.claude/skills/papermorph/references/stories.md
+++ b/.claude/skills/papermorph/references/stories.md
@@ -1,6 +1,6 @@
# Picture books: from a story to an episode
-A picture book is a short animated film, two to four minutes, told by paper puppets in front of sets. It starts from a story rather than a textbook: a fairy tale, a joke, something that happened to the user, or a story book's PDF. The published examples are on the shelf at https://papermorph.diamonddoge.org/: *Little Red Riding Hood* (everything drawn in code) and *Joke Collection* (painted sets, puppets in code; two episodes, one of them made overnight by a fresh session from the user's bedtime telling).
+A picture book is a short animated film, two to four minutes, told by paper puppets in front of sets. It starts from a story rather than a textbook: a fairy tale, a joke, something that happened to the user, or a story book's PDF. The published examples are on the shelf at https://papermorph.diamonddoge.org/: *Little Red Riding Hood* (everything drawn in code) and *Joke Collection* (painted sets, puppets in code; a series of episodes, the first made overnight by a fresh session from the user's bedtime telling, later ones by a coordinator, scene workers and review rounds, see [team.md](team.md#picture-books)).
The craft is in four references: this one (the story and the shots), [puppets.md](puppets.md) (the paper puppets and the stop-motion look), [painting.md](painting.md) (sets and props painted by an image model) and [sound.md](sound.md) (voices, sound effects, music). The engine, the player, previews, checks and the team are the same as for every other book.
@@ -38,8 +38,10 @@ One scene is one beat, with one joined audio clip ([sound.md](sound.md)); cuts i
- an insert to make a detail readable (a coin on the counter, the clock, a face in a door crack);
- held silences: the beat where nobody speaks is often the joke. Blinks, eyes and a tiny head turn carry it.
+Reviewers of the later episodes kept finding the same few things, all about what the viewer can read. Give every object the joke hangs on an insert of its own; the best episodes ran ten to fourteen shots a half minute. Keep whoever is being spoken to in the shot, since the listener's face is half of the line. A follower trails about 240 px behind; people pass in front of or behind each other, never through. A face half cut by the frame edge, or a blink on the frame that carries the joke, reads as a mistake.
+
Everybody in the shot stays alive and stays there: extras blink and glance about in close-ups too (in an early cut the whole class vanished whenever someone spoke). Between places, cut or use a paper-theatre wipe; at the end, a title card.
## Delivering
-Deliver the episode URL with what was made, the final script, the decisions the user should review (every line or moment you added), known problems, and the real cost of pictures. For a series, add the episode to the series page with a still and a line, and set the previous episode's `CHAPTER.next`.
+Deliver the episode URL with what was made, the final script, the decisions the user should review (every line or moment you added), known problems, and the real cost of pictures. For a series, add the episode to the series page with a still and a line, and set the previous episode's `CHAPTER.next`: when an episode's last scene ends, the player marks it watched and offers the next one.
diff --git a/.claude/skills/papermorph/references/team.md b/.claude/skills/papermorph/references/team.md
index 3514832..832424e 100644
--- a/.claude/skills/papermorph/references/team.md
+++ b/.claude/skills/papermorph/references/team.md
@@ -29,4 +29,16 @@ Check the reports against each other (an odd claim is worth one look at the file
## Picture books
-The same shape, split by scene instead of by step: the strong coordinator writes the script with the user, builds what every scene shares (cast, sets and their painting, the episode's helpers, the voices and joined audio), and writes a short brief for scene workers (the kit, the style, how to check, how to reply). Then one **middle** worker per scene, in parallel, each writing only its own `sceneN.js` and checking it with contact sheets; a **small** worker synthesizes the sound effects from recipes; a **middle** worker looks at every scene's contact sheet and reports problems with scene and time, so the coordinator reads a list instead of the pictures; the coordinator reworks or sends back. A fresh session as coordinator matters even more here: contact sheets are large, and a long conversation rereads them at every step. An episode made this way from a bedtime telling, in one night: about 22 million tokens, most of them the coordinator rereading its own context.
+The same shape, split by scene instead of by step. The **strong** coordinator writes the script with the user and builds what every scene shares: cast, sets and their painting, the episode's helpers, the voices and the joined audio with its word times (`join.py --words`). Then it writes one brief for all scene workers:
+
+- the story in a paragraph, and the user's words that set the bar;
+- the episode kit's API, to read and not edit: a scene that needs more from the kit asks the coordinator, so every scene gets the fix;
+- each scene's `pre`, its holes and the word times to cut on;
+- continuity: who stands where, facing whom, in the first and last frame of every scene, so the cuts match;
+- the style, the effects available, how to look at one's own work, and the reply (the shots with their times, the first and last frame).
+
+One **middle** worker per scene, in parallel, writes only its own `sceneN.js` and checks it with contact sheets and full-size frames of its close-ups; a **small** worker synthesizes the sound effects from recipes.
+
+Review comes in rounds, each with four report-only reviewers (**strong** for the director, **middle** for the rest) that watch the episode against the approved ones. The director judges story, comedy, staging and shots. Two picture reviewers split the scenes between them. The fourth reviewer covers sound and runtime. Each writes a ranked report: scene, beat-clock time, what is wrong as a viewer sees it, a concrete fix. Earlier good reports serve as examples. The coordinator merges the reports into one rework list, taking the director's side where reviewers disagree, fixes the kit itself and sends scenes back to their workers. The next round starts by checking which findings were fixed. A last read-only pass counts them as fixed, partly fixed, not fixed or worse. Episodes made with two or three rounds were the best in the series; the rounds come before the user watches, and what the user says then still decides.
+
+A fresh session as coordinator matters even more here: contact sheets are large, and a long conversation rereads them at every step. An episode made in one night from a bedtime telling, before the review rounds existed, took about 22 million tokens, most of them the coordinator rereading its own context.