Skip to content

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

docs(skill): picture books that run as written, models the user picks, course options apart

yzr6205f82c06f3
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.md
index 5b90da4..959aab8 100644
--- a/.claude/skills/papermorph/SKILL.md
+++ b/.claude/skills/papermorph/SKILL.md
@@ -7,9 +7,9 @@ description: Make or edit animated, narrated, interactive web books from referen
Each chapter is a short animated lesson film: the picture carries the explanation, the narration says it, and quick checks and practice happen inside the picture. Good means **alive** (things act and change with weight and timing), **composed** (each moment reads as one picture, text beside what it names), **true** (motion, labels and numbers agree at every moment) and **smooth** (it plays without stutter, Firefox included). Technically a chapter is one 1600×900 SVG stage plus a player; **beats** pair narration clips with timed actions.
-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).
+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), [courses.md](references/courses.md) (options for course books).
-**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.
+**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 and team work the same; a film is reviewed in rounds as [stories.md](references/stories.md#review-rounds) describes, and [site.md](references/site.md#a-picture-book) starts its 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.
@@ -19,8 +19,6 @@ Follow the pipeline forward, entering at the requested stage for existing work.
books/<book>/
book.pdf, sections.json source and page map (private)
pages/chNN/text.md, *.png extracted reference material (private)
- refs.json optional: cited works with verified DOI/ISBN/URL (scripts/refs.py)
- items/chNN.items.json optional: a reviewed choice-question bank per chapter (scripts/items.py)
style.json the agreed style every chapter anchors to (assets/templates/style.json)
chapters.md chapter map and status
chapters/chNN.md storyboard, errata, feedback
@@ -30,41 +28,41 @@ content/<book>/chNN/ narration.<lang>.json and TTS cache
tools/<book>/ tests and evidence scripts
site/<book>/ the static book (only this is delivered)
index.html, unit-art.js cover + contents, unit sketches
- refs.js optional: the cited works, built by scripts/refs.py
lib/engine.*, volume.*, the engine (player, cover/contents, unit headers), copied into the book by
contents.*, units.* scripts/engine.py
lib/book.css this book's engine settings and style overrides
lib/*.js, img/ the book's element library and images
chNN/index.html, audio/<lang>/ a lesson, its beat MP3s + timings.js
- chNN/items.js built choice questions (scripts/items.py), when the chapter has a bank
```
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`), api.crossref.org and openlibrary.org for a book with citations, and Playwright browsers (`uv run --with playwright playwright install chromium firefox`; where Playwright's Chromium does not run, set `CHROME` to an installed Chrome, Chromium, Brave or Edge). Preview: `python3 SKILL/scripts/serve.py 8765 site` (no browser caching).
+`SKILL` means this skill's absolute folder; `<book>` is the book slug, `<lang>` its primary language code. Needs: `uv`, `ffmpeg`/`ffprobe`, Edge TTS network access (or Kokoro, local: `uv run --python 3.12 --with kokoro`), github.com for `engine.py` when the repository's `engine/` folder is not at hand, and Playwright browsers (`uv run --with playwright playwright install chromium firefox`; where Playwright's Chromium does not run, set `CHROME` to an installed Chrome, Chromium, Brave or Edge). Preview: `python3 SKILL/scripts/serve.py 8765 site` (no browser caching).
## Pipeline
Start with intake whenever `books/<book>/style.json` does not exist yet; reuse answers and approvals already given.
-1. **Split.** Run `uv run --with pymupdf SKILL/scripts/outline.py books/<book>/book.pdf`; use `--level N -o books/<book>/sections.json` at chapter depth. For a PDF without usable chapter bookmarks, inspect `split_pages.py … --pages 1-12 --out books/<book>/pages`, then write the map from its contents (schema: `outline.py --help`). Extract chapter text with `split_pages.py … --sections books/<book>/sections.json --out books/<book>/pages --text-only`.
-2. **Intake.** Follow [intake.md](references/intake.md): find the PDF with the user, say what the book is, agree on one chapter to try and a tier, settle the look the way that tier needs, and write `style.json`.
-3. **Initialize.** Follow [site.md](references/site.md#start-a-book-folder); build agreed shared components once into the book's library ([assets.md](references/assets.md)) and list them in `style.json`.
-4. **Pilot.** Make the chosen chapter through the chapter loop and deliver it for the user's judgement. Fold their feedback into `style.json` and record the chapter under `approved`.
-5. **Remaining chapters and finish**, when the user wants the whole book: write `chapters.md`, produce chapters sequentially (see *Context*), complete cover text, contents and unit sketches using [site.md](references/site.md). Deliver the static book folder, its entry URL for local preview and any unresolved issues. For an LMS, package it as SCORM ([site.md](references/site.md#scorm-package-optional)).
+1. **Intake** ([intake.md](references/intake.md)), a short conversation: find the PDF with the user (a story goes to [stories.md](references/stories.md)), split it, say what the book is, agree on one chapter to try and a tier, start the book folder, settle the look the way that tier needs, agree which model does which step, and write `style.json`.
+ - Split: `uv run --with pymupdf SKILL/scripts/outline.py books/<book>/book.pdf`; use `--level N -o books/<book>/sections.json` at chapter depth. For a PDF without usable chapter bookmarks, inspect `split_pages.py … --pages 1-12 --out books/<book>/pages`, then write the map from its contents (schema: `outline.py --help`). Extract chapter text with `split_pages.py … --sections books/<book>/sections.json --out books/<book>/pages --text-only`.
+ - Start the book folder with [site.md](references/site.md#start-a-book-folder) before showing the user any frames; build agreed shared components once into the book's library ([assets.md](references/assets.md)) and list them in `style.json`.
+2. **Pilot.** Make the chosen chapter through the chapter loop and deliver it for the user's judgement. Fold their feedback into `style.json` and record the chapter under `approved`.
+3. **Remaining chapters and finish**, when the user wants the whole book: write `chapters.md`, produce chapters sequentially (see *Context*), complete cover text, contents and unit sketches using [site.md](references/site.md). Deliver the static book folder, its entry URL for local preview and any unresolved issues.
+
+A course book may also want verified citation links, a reviewed question bank or a SCORM package for an LMS; offer them only when the book calls for them ([courses.md](references/courses.md)).
## Chapter loop
-1. **Read** this chapter's `pages/chNN/text.md`; render pages with `split_pages.py … --only chNN` when diagrams or missing text need images. Choose the ideas, examples and sections to teach. In a book that cites its sources (an option for academic books, chosen at intake), add the works the chapter names to `refs.json` and run `refs.py lookup`, `verify` and `build` ([authoring.md](references/authoring.md#citations)).
+1. **Read** this chapter's `pages/chNN/text.md`; render pages with `split_pages.py … --only chNN` when diagrams or missing text need images. Choose the ideas, examples and sections to teach.
2. **Beats and narration**: list beats in `chapters/chNN.md` with what each says and which word triggers which action ([authoring.md](references/authoring.md)). Write `content/<book>/chNN/narration.<lang>.json`, then `uv run --with edge-tts SKILL/scripts/tts.py content/<book>/chNN/narration.<lang>.json site/<book>/chNN/audio/<lang>` (for `"engine": "kokoro"`: `uv run --python 3.12 --with kokoro …`).
3. **Storyboard, layout first**: in the real page, place everything for one to three key moments per beat, real elements at their real sizes, no motion yet. Capture them into one sheet with `strip.py` and give each frame one line: what it says and where the eye goes. That sheet is the storyboard. Note what the chapter needs beyond the library: draw it, or add it to the image requests.
-4. **Motion**: add the motion, the camera and the questions (choice questions may come from an item bank via `mcq()`, [authoring.md](references/authoring.md#choice-questions-from-an-item-bank)); API and replay invariants are in [engine.md](references/engine.md).
+4. **Motion**: add the motion, the camera and the questions; API and replay invariants are in [engine.md](references/engine.md).
5. **Delivery pass**: watch your output in motion and judge it as a viewer would, against the storyboard; then run the checks in [review.md](references/review.md). Correct what you find, recheck, deliver; report unresolved problems.
6. **Register**: add the chapter to the contents (`units` in `Contents.book` in `index.html`), set the previous chapter's `CHAPTER.next`, update `chapters.md` and `chapters/chNN.md`. Promote new shared decisions and recurring elements to `style.json` and the library. The coordinator owns this step when using subagents.
## Context
-- Keep intake and the pilot in the main conversation. Afterwards, when subagents are available, coordinate each chapter as a team: a fresh worker per step of the chapter loop, each on the cheapest model that does that step well, chapters one after another ([team.md](references/team.md)). Without subagents, run the same loop in the current agent with file-based state.
+- Keep intake and the pilot in the main conversation. Afterwards, when subagents are available, coordinate each chapter as a team: a fresh worker per step of the chapter loop, each on the model the user chose for that step (`models` in `style.json`), chapters one after another ([team.md](references/team.md)). Without subagents, run the same loop in the current agent with file-based state.
- A worker needs little besides this Skill and `style.json`: the user's words, the look, the approved chapters to watch and read, the element library. A brief adds the chapter, its pages, the step's inputs and outputs and any current user request. Workers reply in a few lines; the coordinator registers the chapter.
- Read only the reference needed for the current step. Use the engine API and inspect individual functions when needed; copy assets rather than reading their full source as instructions.
- Keep `style.json` current and short. Chapter status, errata and historical feedback stay in `chapters.md` and `chapters/chNN.md`.
diff --git a/.claude/skills/papermorph/assets/templates/chapter.html b/.claude/skills/papermorph/assets/templates/chapter.html
index 7778b11..ee19d31 100644
--- a/.claude/skills/papermorph/assets/templates/chapter.html
+++ b/.claude/skills/papermorph/assets/templates/chapter.html
@@ -17,7 +17,7 @@
// A starting skeleton, not a design. Replace every beat; keep the shape: intro, lesson beats with
// quick checks between them, a summary, full-screen practice, finish. Beat ids match narration.en.json.
// <html lang> sets the interface text, language the audio folder: keep both, and the timings path above, in the book's language.
-const CHAPTER = { number: 1, title: 'CHAPTER TITLE', minutes: 8, language: 'en', refs: [] }; // match the audio folder; set next once the next chapter exists; refs: REFS keys to list on the finish card besides those drawn with cite()
+const CHAPTER = { number: 1, title: 'CHAPTER TITLE', minutes: 8, language: 'en' }; // match the audio folder; set next once the next chapter exists
/* ---------- chapter drawing helpers ---------- */
const mline = (p, parts, x, y, t0, fill = COL.chalk, size = 48, anchor = 'middle') => { const e = M(p, [].concat(parts), { x, y, size, fill, anchor, o: 0 }); show(e, t0); return e; };
diff --git a/.claude/skills/papermorph/assets/templates/picture-book/series.html b/.claude/skills/papermorph/assets/templates/picture-book/series.html
new file mode 100644
index 0000000..4ad45d7
--- /dev/null
+++ b/.claude/skills/papermorph/assets/templates/picture-book/series.html
@@ -0,0 +1,61 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SERIES TITLE</title>
+<meta name="description" content="One line about the series.">
+<link rel="stylesheet" href="lib/book.css"><!-- only for --progress-key, if the book sets one -->
+<!-- A picture book's cover and episode list. A starting point, not a design: give it the book's own look. -->
+<style>
+ :root { --ink: #2f2418; --soft: #6b5a46; --paper: #fbf5e8; --card: #fffaf0; --line: #e4d6bb; --accent: #2f5aa8;
+ --ui: "Avenir Next", "Segoe UI", "Helvetica Neue", Arial, sans-serif; --serif: "Iowan Old Style", Palatino, Georgia, serif; color-scheme: light; }
+ * { box-sizing: border-box; }
+ body { margin: 0; background: var(--paper); color: var(--ink); font: 18px/1.6 var(--ui); }
+ header { display: grid; grid-template-columns: minmax(0, 1.1fr) minmax(0, 1fr); gap: 40px; align-items: center; max-width: 1180px; margin: 0 auto; padding: 48px 24px 24px; }
+ header img { width: 100%; height: auto; border-radius: 10px; box-shadow: 0 14px 40px #4a33182e; }
+ h1 { margin: 0 0 8px; font: 700 clamp(34px, 4.6vw, 56px)/1.05 var(--serif); }
+ .lede { font-size: 20px; color: var(--soft); }
+ main { max-width: 1000px; margin: 0 auto; padding: 8px 24px 80px; }
+ .episodes { list-style: none; padding: 0; margin: 18px 0; display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; }
+ .episodes a { display: flex; flex-direction: column; height: 100%; background: var(--card); border: 1px solid var(--line); border-radius: 10px;
+ overflow: hidden; color: var(--ink); text-decoration: none; transition: border-color .15s, transform .15s; }
+ .episodes a:hover, .episodes a:focus-visible { border-color: var(--accent); transform: translateY(-2px); }
+ .episodes img { display: block; width: 100%; height: auto; aspect-ratio: 16 / 9; object-fit: cover; }
+ .episodes small { margin: 12px 16px 0; color: var(--soft); font-size: 13px; font-weight: 600; letter-spacing: .03em; text-transform: uppercase; }
+ .episodes b { margin: 2px 16px 4px; font: 700 21px/1.25 var(--serif); }
+ .episodes span { margin: 0 16px 16px; color: var(--soft); font-size: 15px; line-height: 1.5; }
+ .watched small::after { content: " · ✓ watched"; color: var(--accent); }
+ @media (max-width: 760px) { header { grid-template-columns: 1fr; padding-top: 28px; } .episodes { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<header>
+ <img src="img/cover.webp" width="1400" height="788" alt="Describe the cover still.">
+ <div>
+ <h1>SERIES TITLE</h1>
+ <p class="lede">One or two sentences: what these films are and who they are for.</p>
+ </div>
+</header>
+<main>
+ <ul class="episodes" id="episodes"></ul>
+</main>
+<script>
+'use strict';
+// One entry per finished episode, in order: its folder, title, a still (16:9) with alt text, and one line.
+const EPISODES = [
+ { ch: 'ch01', title: 'EPISODE TITLE', minutes: 2, still: 'img/still-ch01.webp', alt: 'Describe the still.', line: 'One line about the episode.' },
+];
+// The player records finished episodes under the same key as here (engine progress(): lib/book.css --progress-key,
+// else this folder's path).
+const key = getComputedStyle(document.documentElement).getPropertyValue('--progress-key').trim().replace(/^["']|["']$/g, '')
+ || 'animebook:progress:' + new URL('.', location.href).pathname;
+let done = [];
+try { done = JSON.parse(localStorage.getItem(key) || '{}').done || []; } catch {}
+const esc = s => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+document.getElementById('episodes').innerHTML = EPISODES.map((e, i) => `<li${done.includes(+e.ch.slice(2)) ? ' class="watched"' : ''}>
+ <a href="${e.ch}/"><img src="${esc(e.still)}" alt="${esc(e.alt)}" loading="lazy">
+ <small>Episode ${i + 1} · ${e.minutes} minutes</small><b>${esc(e.title)}</b><span>${esc(e.line)}</span></a></li>`).join('');
+</script>
+</body>
+</html>
diff --git a/.claude/skills/papermorph/assets/templates/picture-book/style.json b/.claude/skills/papermorph/assets/templates/picture-book/style.json
new file mode 100644
index 0000000..ef18004
--- /dev/null
+++ b/.claude/skills/papermorph/assets/templates/picture-book/style.json
@@ -0,0 +1,22 @@
+{
+ "schema": 1,
+ "tier": "picture",
+ "book": { "title": "Series title", "slug": "jokes", "language": "en", "readers": "families, all ages", "pilot": "ch01" },
+ "words": [
+ "The user's own words about the story and the look, verbatim.",
+ "ch01 feedback: later words that changed the bar, with the episode they came from."
+ ],
+ "look": "Whatever the user chose: for example paper puppets in front of sets painted as torn-paper collage, warm light",
+ "voice": {
+ "engine": "edge",
+ "narrator": { "voice": "en-US-AndrewMultilingualNeural", "rate": "-4%" },
+ "cast": { "Bo": { "voice": "en-US-AnaNeural", "rate": "+0%" }, "Clerk": { "voice": "ja-JP-NanamiNeural", "rate": "+0%", "subtitles": "en" } }
+ },
+ "illustration": {
+ "sets": "painted by an image model, puppets and anything that moves in code",
+ "budget": "under $1 of pictures per episode",
+ "cast": [{ "name": "Bo", "look": "round face, school uniform", "file": "site/jokes/lib/cast.js" }]
+ },
+ "models": { "script": "claude-opus-5-5", "kit": "claude-opus-5-5", "scenes": "claude-sonnet-5-5", "sound": "claude-haiku-5-5", "director": "claude-opus-5-5", "reviewers": "claude-sonnet-5-5" },
+ "approved": [{ "chapter": "ch01", "why": "set-up before the punchline; a close-up on whoever speaks" }]
+}
diff --git a/.claude/skills/papermorph/assets/templates/style.json b/.claude/skills/papermorph/assets/templates/style.json
index 951a2ca..a96c7e7 100644
--- a/.claude/skills/papermorph/assets/templates/style.json
+++ b/.claude/skills/papermorph/assets/templates/style.json
@@ -15,6 +15,7 @@
"voice": { "engine": "edge", "voice": "en-US-AndrewMultilingualNeural", "rate": "-4%" },
"pacing": { "minutes": [6, 10], "checks": "one or two quick checks inside the lesson, practice at the end" },
"engine": { "source": "DozenTwelve/Papermorph", "ref": "main" },
+ "models": { "extract": "claude-haiku-5-5", "narration": "claude-sonnet-5-5", "picture": "claude-opus-5-5", "checks": "claude-haiku-5-5", "review": "claude-sonnet-5-5", "rework": "claude-opus-5-5", "register": "claude-haiku-5-5" },
"scenes": {
"art": "pixel scenes on a dark board, characters about a third of the stage tall",
"cast": [{ "name": "Mia", "look": "short hair, red jacket", "file": "site/physics/img/mia.png" }],
diff --git a/.claude/skills/papermorph/references/authoring.md b/.claude/skills/papermorph/references/authoring.md
index ab21f61..51567bd 100644
--- a/.claude/skills/papermorph/references/authoring.md
+++ b/.claude/skills/papermorph/references/authoring.md
@@ -45,7 +45,7 @@ Pick the type that lets the student act on the picture itself whenever possible
| Type | Use for |
| --- | --- |
-| `choice` / `mcq` | One answer from a few options, each wrong option with its own explanation; `mcq(id)` takes it from the chapter's item bank |
+| `choice` | One answer from a few options, each wrong option with its own explanation (from a reviewed item bank: `mcq`, [courses.md](courses.md)) |
| `blanks` | Typed numbers inside an expression; fractions and mixed numbers accepted; `test` judges a whole row (answers in any order) |
| `grid` | Several items, each classified (yes/no, which category, true/false) |
| `tap` / `tapEls` / `pickEls` | Click a point on the number line / a token in an expression / any drawn object |
@@ -62,39 +62,8 @@ New types are welcome when the content calls for one; each needs keyboard play (
- Compose the question beat for its card: the picture the question is about stays visible (for example in the top 60 % with a `BAND` card below, or beside a `{x, y, w, cls: 'side'}` card); `SCREEN` for practice.
- Units in typed answers: write the unit as a word after the box (`{ box: '60' }, ' kilograms'`) so it is not set as a math variable.
-### Choice questions from an item bank
-
-A chapter's choice questions can live in a reviewed item bank, `books/<book>/items/chNN.items.json`, instead of inline in the page, so they can be linted, reviewed by a person in a sheet, and approved before release. The bank follows the JSON schema of the [mcq-item-writer](https://github.com/titulartarantula/mcq-item-writer) skill, which writes and lints items against evidence-based item-writing rules (stem with the problem, one best answer, plausible distractors, feedback on every option). Inline `choice` stays fine for a quick check written on the spot.
-
-For a bank used by a page:
-
-- **Ids** keep the book's prefixes: `c-…` for a quick check, `p-…` for practice (the finish card adds them up by prefix).
-- **The card is the screen.** Put the scenario and lead-in in `stem`; no data tables or media (draw the data in the beat and ask about it). Options stay short enough for one line on the card; three options fit a side or band card, four only on a `SCREEN`.
-- **Feedback** on every option, two or three sentences. The engine adds "Correct." / "Not quite.", so don't start with a verdict; `items.py` drops one if present.
-- **Order.** Options show as authored (no shuffle): spread the right answer's position across the chapter.
-
-Build the page's copy after every bank change, and never edit `items.js` by hand:
-
-```sh
-python3 SKILL/scripts/items.py books/<book>/items/chNN.items.json site/<book>/chNN/items.js
-```
-
-The chapter loads `<script src="items.js"></script>` right after `engine.js` and asks with `quiz(TOPR, [mcq('c-attrib')], done)` (engine.md). `items.py` refuses what a card cannot show (multiple-response items, tables, media, no single key) and warns about items not yet marked `approved`.
-
## Content rules
- Follow the agreed chapter scope and order. Verify facts, calculations and answers actually used in the finished lesson; correct or replace source errors and note them in `books/<book>/chapters/chNN.md` for the user.
- Check worked examples as the subject, not only as arithmetic (a push on someone standing on the ground is not the net force).
- Use the notation and rounding in `style.json` (`look.notation`). Record new shared decisions there.
-
-## Citations
-
-An option for books that name other works (an author–year, a quoted study, a book title), usually academic ones; offer it at intake, not by default. Each such work on screen can be a live link to it. Links come from a verified list, never from memory.
-
-1. **List.** Add each cited work to `books/<book>/refs.json`, taking authors, year and full title from the source book's own reference list (`pages/*/text.md`). The key is `surname-surname-year` (`scheper-hughes-lock-1987`); `cite` is the on-screen label (`python3 SKILL/scripts/refs.py --help` lists the entry fields).
-2. **Find.** `python3 SKILL/scripts/refs.py lookup books/<book>/refs.json --write`. It accepts a Crossref DOI only when the year, first author and title all match. For books without a DOI it takes the ISBN of the edition from the cited year (Open Library), which links to its WorldCat record. Decide each `NO CONFIDENT MATCH` by hand: pick the right candidate or a trusted academic page (`url`, e.g. PubMed, JSTOR, ERIC, a university repository). If none exists, keep the citation as plain text and note it in the chapter file.
-3. **Verify.** `python3 SKILL/scripts/refs.py verify books/<book>/refs.json --write` resolves every DOI or ISBN, checks it against the entry, fills in missing metadata and stamps `verified`. Fix every `FAIL`.
-4. **Build.** `python3 SKILL/scripts/refs.py build books/<book>/refs.json site/<book>/refs.js`, and uncomment the `refs.js` line in `index.html` and each chapter: the contents ends with a link to a separate References view that lists every work, and each chapter's finish card lists the sources that chapter cites.
-5. **Draw.** `cite(p, key, { x, y, size, fill, anchor, weight, o: 0 })` draws the label as an underlined link and returns it, ready for `show()`/`tw()` like `T`; `str` overrides the label (e.g. `'(1987)'` after a name drawn separately). Text drawn with `T` or written in a card that matches a work's `cite` label (or one of its `match` strings) becomes a link by itself. Clicking a citation opens the source in a new tab and pauses the lesson; faded-out links take no clicks or Tab focus. A work discussed but not drawn goes in `CHAPTER.refs` so the finish card still lists it.
-
-Draw a citation next to the text it supports rather than inside a long sentence, so the link is a separate target of at least 24 px text height.
diff --git a/.claude/skills/papermorph/references/courses.md b/.claude/skills/papermorph/references/courses.md
new file mode 100644
index 0000000..756e662
--- /dev/null
+++ b/.claude/skills/papermorph/references/courses.md
@@ -0,0 +1,64 @@
+# Course options
+
+Three options for books used in a course, usually at a college: verified citation links, a reviewed bank of choice questions, and a SCORM package for an LMS. None is on by default; offer one at intake only when the book calls for it (it cites other works, its questions must be reviewed before release, or it goes into an LMS), and record the choice in `style.json`.
+
+## Citations
+
+Each work named on screen (an author–year, a quoted study, a book title) can be a live link to it. Links come from a verified list, never from memory.
+
+1. **List.** Add each cited work to `books/<book>/refs.json`, taking authors, year and full title from the source book's own reference list (`pages/*/text.md`). The key is `surname-surname-year` (`scheper-hughes-lock-1987`); `cite` is the on-screen label (`python3 SKILL/scripts/refs.py --help` lists the entry fields).
+2. **Find.** `python3 SKILL/scripts/refs.py lookup books/<book>/refs.json --write`. It accepts a Crossref DOI only when the year, first author and title all match. For books without a DOI it takes the ISBN of the edition from the cited year (Open Library), which links to its WorldCat record. Decide each `NO CONFIDENT MATCH` by hand: pick the right candidate or a trusted academic page (`url`, e.g. PubMed, JSTOR, ERIC, a university repository). If none exists, keep the citation as plain text and note it in the chapter file.
+3. **Verify.** `python3 SKILL/scripts/refs.py verify books/<book>/refs.json --write` resolves every DOI or ISBN, checks it against the entry, fills in missing metadata and stamps `verified`. Fix every `FAIL`.
+4. **Build.** `python3 SKILL/scripts/refs.py build books/<book>/refs.json site/<book>/refs.js`, and uncomment the `refs.js` line in `index.html` and each chapter: the contents ends with a link to a separate References view that lists every work, and each chapter's finish card lists the sources that chapter cites.
+5. **Draw.** `cite(p, key, { x, y, size, fill, anchor, weight, o: 0 })` draws the label as an underlined link and returns it, ready for `show()`/`tw()` like `T`; `str` overrides the label (e.g. `'(1987)'` after a name drawn separately). Text drawn with `T` or written in a card that matches a work's `cite` label (or one of its `match` strings) becomes a link by itself. Clicking a citation opens the source in a new tab and pauses the lesson; faded-out links take no clicks or Tab focus. A work discussed but not drawn goes in `CHAPTER.refs` so the finish card still lists it.
+
+Draw a citation next to the text it supports rather than inside a long sentence, so the link is a separate target of at least 24 px text height.
+
+## Choice questions from an item bank
+
+A chapter's choice questions can live in a reviewed item bank, `books/<book>/items/chNN.items.json`, instead of inline in the page, so they can be linted, reviewed by a person in a sheet, and approved before release. The bank follows the JSON schema of the [mcq-item-writer](https://github.com/titulartarantula/mcq-item-writer) skill, which writes and lints items against evidence-based item-writing rules (stem with the problem, one best answer, plausible distractors, feedback on every option). Inline `choice` stays fine for a quick check written on the spot.
+
+For a bank used by a page:
+
+- **Ids** keep the book's prefixes: `c-…` for a quick check, `p-…` for practice (the finish card adds them up by prefix).
+- **The card is the screen.** Put the scenario and lead-in in `stem`; no data tables or media (draw the data in the beat and ask about it). Options stay short enough for one line on the card; three options fit a side or band card, four only on a `SCREEN`.
+- **Feedback** on every option, two or three sentences. The engine adds "Correct." / "Not quite.", so don't start with a verdict; `items.py` drops one if present.
+- **Order.** Options show as authored (no shuffle): spread the right answer's position across the chapter.
+
+Build the page's copy after every bank change, and never edit `items.js` by hand:
+
+```sh
+python3 SKILL/scripts/items.py books/<book>/items/chNN.items.json site/<book>/chNN/items.js
+```
+
+The chapter loads `<script src="items.js"></script>` right after `engine.js` and asks with `quiz(TOPR, [mcq('c-attrib')], done)` (engine.md). `items.py` refuses what a card cannot show (multiple-response items, tables, media, no single key) and warns about items not yet marked `approved`.
+
+## SCORM package
+
+For a course in an LMS (Canvas, Moodle, Brightspace, Blackboard), package a built book as one SCORM zip:
+
+```sh
+python3 SKILL/scripts/scorm.py site/<book> # SCORM 2004 4th edition, completion only -> dist/<book>-scorm2004.zip
+python3 SKILL/scripts/scorm.py site/<book> --version 1.2 # older LMSs
+python3 SKILL/scripts/scorm.py site/<book> --mastery 80 # also passed/failed at 80 %, once the whole book is finished
+```
+
+`site/<book>/` is not changed; rebuild the zip after changing the book. The LMS launches `launch.html`, which opens one SCORM session and runs the book in a frame, so moving between chapters keeps the session. The build adds `scorm-bridge.js` to the contents page and after `engine.js` in every chapter; it wraps the engine's `progress()` and `finishCard()`, seeds the book's progress from the LMS on each launch (the LMS is the source of truth) and points folder links (`ch02/`) at `index.html`, which many LMS file servers need.
+
+| | SCORM 1.2 | SCORM 2004 |
+|---|---|---|
+| Completion: every chapter's finish card reached | `cmi.core.lesson_status` (`passed`/`failed` with `--mastery`) | `cmi.completion_status`, `cmi.success_status` with `--mastery` |
+| Progress: chapters finished ÷ chapters | — | `cmi.progress_measure` |
+| Score: first-try answers over all quick checks and practice, best attempt per chapter | `cmi.core.score.raw` | `cmi.score.raw`, `cmi.score.scaled` |
+| One objective per chapter (`ch01`, …) with status and score | `cmi.objectives.n.*` | `cmi.objectives.n.*` |
+| Resume (checkmarks, Continue) | `cmi.suspend_data`, `lesson_location` | `cmi.suspend_data`, `cmi.location` |
+
+A chapter counts as finished when its finish card appears, as in the book; a learner can skip there on the step bar, so use `--mastery` when the grade should depend on the answers. Cards that link to another book's folder (`href` in `units`) leave the package and don't work inside an LMS.
+
+Check a package before handing it over: `uv run --with playwright SKILL/assets/scorm/test/check_scorm.py dist/<book>-scorm2004.zip` opens it in `assets/scorm/test/mock-lms.html` (a stand-in LMS that shows every CMI value), opens a chapter through a folder link, reaches its finish card and checks resume. To click through by hand, unzip the package as `pkg/` next to a copy of `mock-lms.html`, run `python3 SKILL/assets/scorm/test/serve.py <folder> 8781` (no folder URLs, like an LMS) and open `http://localhost:8781/mock-lms.html?pkg=pkg&v=2004&reset`; reload without `&reset` to test resume. Before learners use it, upload it to SCORM Cloud (a free account), the usual test of a real LMS. Audio makes up most of a package: check the LMS's upload limit. Canvas grades only the overall result; it doesn't show the per-chapter objectives.
+
+## Checking them
+
+For a chapter with an item bank, lint it with the item writer (`python3 MCQ/scripts/lint_items.py books/<book>/items/chNN.items.json`, where `MCQ` is the mcq-item-writer skill's folder) and fix every error; rebuild `items.js` after any change, then answer one bank question per card position, wrong then right, to see the answered card fit with Continue visible.
+
+For a chapter that cites works, run `python3 SKILL/scripts/refs.py verify books/<book>/refs.json` and rebuild `refs.js` after any `refs.json` change. Every author–year or work title on screen should be a link whose key is verified; look for links that are missing, unreadable or overlapping other targets, and open one per chapter to confirm it lands on the work.
diff --git a/.claude/skills/papermorph/references/engine.md b/.claude/skills/papermorph/references/engine.md
index 9b156c5..8dbd098 100644
--- a/.claude/skills/papermorph/references/engine.md
+++ b/.claude/skills/papermorph/references/engine.md
@@ -1,8 +1,8 @@
# The engine (lib/engine.js, lib/engine.css)
-A chapter page loads the engine and its `audio/<lang>/timings.js`, defines `CHAPTER` (including `language` when different from `en`), drawing helpers, `BEATS` and questions, then calls `boot()`. The engine provides the stage, drawing, timeline, question types, guide and player. Use the code's signatures if they differ from this reference.
+A chapter page loads the engine and its `audio/<lang>/timings.js`, defines `CHAPTER` (including `language` when different from `en`: the audio folder), drawing helpers, `BEATS` and questions, then calls `boot()`. The engine provides the stage, drawing, timeline, question types, guide and player. Use the code's signatures if they differ from this reference. The interface text (buttons, help, cover, finish card) follows `<html lang>`: English, Russian, Chinese and Japanese are in the engine's `TRANSLATIONS`; another language needs a block there.
-Every book keeps a copy of the shared engine in `lib/` (`engine.*`, `volume.*`), so the book runs on its own. The engine is not part of this skill: it lives in the `engine/` folder of the Papermorph repository (or a fork), versioned by tags. `python3 SKILL/scripts/engine.py site` copies it into every book (`--check` lists copies that differ, `--from DIR|OWNER/REPO@REF` picks the source); a book's copy is not edited by hand. An engine bug is fixed at the source, then synced. The book's own settings and style overrides live in `lib/book.css`, imported by `engine.css` and never overwritten: `--math-font` for numbers and formulas, `--progress-key` when the cover uses a key other than the default.
+Every book keeps a copy of the shared engine in `lib/` (`engine.*`, `volume.*`), so the book runs on its own. The engine is not part of this skill: it lives in the `engine/` folder of the Papermorph repository (or a fork). `python3 SKILL/scripts/engine.py site` copies it into every book from the repository's `engine/` when it is at hand, otherwise from GitHub (`--check` lists copies that differ, `--from DIR|OWNER/REPO@REF` picks the source, a tag or commit pins it); a book's copy is not edited by hand. An engine bug is fixed at the source, then synced. The book's own settings and style overrides live in `lib/book.css`, imported by `engine.css` and never overwritten: `--math-font` for numbers and formulas, `--progress-key` when the cover uses a key other than the default.
Many drawing helpers are mathematical because the first book was algebra. Use those that fit; draw the rest in the chapter, and move what several chapters use into the book's element library (`lib/<name>.js`, [assets.md](assets.md)) rather than into the engine copy.
@@ -21,7 +21,7 @@ Many drawing helpers are mathematical because the first book was algebra. Use th
| `G(parent, {x,y,s,r,o})` | group |
| `path(parent, d, attrs, {d:0})` | path; `{d: 0}` makes it ready to be drawn on with `draw()` |
| `T(parent, str, {x,y,size,fill,font,weight,anchor,o})` | text |
-| `cite(parent, key, {str,x,y,size,fill,weight,anchor,o})` | a citation from `REFS` (`../refs.js`), drawn as an underlined link that opens the source in a new tab and listed on the finish card ([authoring.md](authoring.md#citations)) |
+| `cite(parent, key, {str,x,y,size,fill,weight,anchor,o})` | a citation from `REFS` (`../refs.js`, a course option: [courses.md](courses.md)), drawn as an underlined link that opens the source in a new tab and listed on the finish card ([courses.md](courses.md#citations)) |
| `M(parent, parts, {x,y,size,fill,anchor,o,s})` | math with its baseline at y; parts are strings, `F(n,d)` fractions, `R(x, i)` roots (x may be `F(...)`, i the index), `E(exp)` exponents, `TX(tex)` LaTeX (see [LaTeX](#latex)); returns a group with `_w` (width) |
| `mathW(parts, size)` | width of math without drawing it |
| `frac(p, top, bot, x, y, t0, opts)` | built-up fraction whose top and bottom are math parts |
@@ -58,6 +58,8 @@ A book whose formulas need more than `M()` parts (indices, sums, matrices, accen
- Tweens: `tw(e, to, t0, dur, ease)`, `prog(q => …, t0, dur, ease)` for custom motion (arcs, counters, live redraws), `show`, `hide`, `draw`, `pop`, `pulse`, `stream`. Eases: `io`, `out`, `back`, `lin`, `soft`. Continuous motion and cameras: see below.
- A lesson beat ends after its narration and its last tween, then the next starts; an `ask` beat waits for `done()`.
- **Opening lead-in**: if a beat calls `panel()` (before 0.5 s) and nothing appears within 0.8 s, `runBeat` moves the opening group (every tween starting within 1.2 s of the first reveal) to start at 0.4 s. Opt out with `{ lead: false }` in the beat's fourth slot.
+- **`pre`** in the fourth slot (`{ pre: 1.2 }`) runs the picture that many seconds before the narration starts: an action, then the line. Picture books use it on every scene.
+- **The end of a film**: a chapter whose last beat asks nothing (a picture book) is finished when that beat ends: it is marked done and, with `CHAPTER.next`, offers the next chapter (Enter).
- **Seeking replays**: jumping to beat N rebuilds the scene and runs earlier beats instantly. Make `run` deterministic: create objects and schedule tweens through the timeline, with inputs from chapter data and replayed `S` state. Create interactions inside `ask`; use `fx`/`fxp` for answer effects.
- Constants used in a `BEATS` literal are evaluated when it is defined, so define them above `BEATS`. Data used only inside an `ask` closure may sit below.
@@ -91,9 +93,9 @@ Firefox repaints SVG on the main thread and is the slowest common browser for th
quiz(position, [{ id: 'c-mean', prompt: ['Find the mean of ', $m('7, 3, 9'), '.'], build: blanks([...]) }, …], done, 'Quick check')
```
-- Positions: `BAND` (bottom band, y 686–886; long content can push it past the stage, so check it), `TOPR` (top right, ≤ 470 high), `RIGHT`, `SCREEN` (full-screen practice; label `'Chapter practice N of M'`), `SORT_SCREEN`, or any `{x, y, w, cls: 'side'}`.
+- Positions: `BAND` (bottom band, y 686–886; long content can push it past the stage, so check it), `TOPR` (top right, ≤ 470 high), `RIGHT`, `SCREEN` (full-screen practice; the label names the set in the book's language, and the engine appends k of n when a quiz has several questions), `SORT_SCREEN`, or any `{x, y, w, cls: 'side'}`.
- `choice(options, right, why, wrongWhys[], onRight?)` — number keys.
-- `mcq(id, onRight?)` — a whole quiz entry (`{id, prompt, build: choice(...)}`) from the chapter's item bank: `quiz(TOPR, [mcq('c-attrib'), mcq('c-cause')], done)`. Needs `items.js` (built by `scripts/items.py`) loaded after `engine.js`; an unknown id throws.
+- `mcq(id, onRight?)` — (course option, [courses.md](courses.md)) a whole quiz entry (`{id, prompt, build: choice(...)}`) from the chapter's item bank: `quiz(TOPR, [mcq('c-attrib'), mcq('c-cause')], done)`. Needs `items.js` (built by `scripts/items.py`) loaded after `engine.js`; an unknown id throws.
- `blanks(rows)` — rows `{parts: [..., {box: '21'}, ...], why, hint?, fx?, test?}`; accepts −5, 3/4, 2 1/4, 0.75 as exact values; `{box, lowest: true}` demands lowest terms; `test(values)` judges the whole row (e.g. two factors in either order). Tab moves between boxes, Enter checks, Esc leaves a box.
- `grid(rows, cols, {multi, text})` — rows `{parts, ans: [keys], why, fx?}`, cols `[[key, label, colour?, hotkey?]]`; with `text: true` parts are rich text (math via `$m`). ↑/↓ change rows.
- `tap(values, right, why, v => wrongWhy, onRight?)` points on the number line; `tapEls(row, idx, right, …)` tokens of a `tokens` row; `pickEls([{el, box: [x,y,w,h], label}], right, …)` any drawn objects; `pickPoint(P, [x,y], why, (x,y) => wrongWhy, onRight?, test?)` grid points (arrows + Enter or click); `sorter(items, trayXY)` drag into the set diagram (keys 1–6).
@@ -105,9 +107,9 @@ quiz(position, [{ id: 'c-mean', prompt: ['Find the mean of ', $m('7, 3, 9'), '.'
Space play/pause, ←/→ previous/next beat (Shift+←/→ during a question), Home restart, C captions, `<`/`>` speed (0.75–1.5×, remembered), F full screen, ? help. Clicking a step segment jumps to that point of the beat (`seekInto(i, frac)`); the next beat's clip preloads while one plays. `seek(i, play)` rebuilds and jumps; `start(i, play)` begins a beat from the current picture. While audio plays, the beat clock follows `audio.currentTime`. `?beat=N&t=S` in the URL opens a frozen frame for review. With `?review` in the URL, N pauses and asks for a note on the current moment and Shift+N copies the chapter's notes, one line each with the `?beat=N&t=S` that reopens it, so a reviewer can collect notes while watching and hand them over at once. The finish card's Enter opens `CHAPTER.next`, R replays.
-Progress uses the stable legacy key `animebook:progress:<book-path>` (keep it when renaming the project so existing readers retain their progress); the cover template reads the same key. A book can set another key with `--progress-key` in `lib/book.css`; its cover must then read that key. Books served in different folders have separate saved places and completion lists.
+Progress is saved under `animebook:progress:<book-path>`; the cover and a picture book's series page read the same key. A book can set another key with `--progress-key` in `lib/book.css`; its cover must then read that key. Books served in different folders have separate saved places and completion lists.
-Treat saved progress as optional: malformed JSON, `null` or a non-object value starts with empty progress; only an array of positive integer chapter numbers is used for completion. Preserve each existing book's key when applying engine fixes.
+Treat saved progress as optional: malformed JSON, `null` or a non-object value starts with empty progress; only an array of positive integer chapter numbers is used for completion.
Keep `<link rel="expect" href="#bar" blocking="render">` in every chapter's head; without it Chromium may paint before the player exists and cancel the page transition from the contents page.
diff --git a/.claude/skills/papermorph/references/intake.md b/.claude/skills/papermorph/references/intake.md
index 4eb3fe7..feca30b 100644
--- a/.claude/skills/papermorph/references/intake.md
+++ b/.claude/skills/papermorph/references/intake.md
@@ -15,21 +15,25 @@ The conversation should feel light: the user tries one chapter first and decides
Greet briefly as Papermorph. Look for PDFs in the working folder and its subfolders (then the user's Downloads and Desktop if none are found) and ask "Is it this one?", listing up to four candidates. If none are found, offer to search another folder or to take a path. Choose a short slug and place the file at `books/<book>/book.pdf`, a copy or a link.
+When the user brings a story, a joke or a fairy tale instead (or a story book's PDF), it becomes a picture book: go to [stories.md](stories.md), which has its own short intake, and come back here for the models (§5) and `style.json` (§6).
+
## 2. What this book is
-Run the split ([SKILL.md](../SKILL.md#pipeline), step 1) and read the contents, the preface and the `text.md` of two or three chapter openings across the book. Say in two or three sentences what the book is: subject, readers, how it teaches. Then offer a chapter to try: name two or three candidates with one line each on what they would show, recommending one that is representative rather than the gentlest opening (a light introduction can pass while hiding the hard problems). A section of a long chapter is fine.
+Run the split ([SKILL.md](../SKILL.md#pipeline)) and read the contents, the preface and the `text.md` of two or three chapter openings across the book. Say in two or three sentences what the book is: subject, readers, how it teaches. Then offer a chapter to try: name two or three candidates with one line each on what they would show, recommending one that is representative rather than the gentlest opening (a light introduction can pass while hiding the hard problems). A section of a long chapter is fine.
+
+If the book is for a course, notice it here: when it cites other works (author–year citations, named studies), offer links from the works named on screen to their sources; when its questions must be reviewed before release, offer an item bank; when it goes into an LMS, mention the SCORM package. None is on by default ([courses.md](courses.md)).
## 3. Tier
-Offer the animation tiers as reference points. The published books at https://papermorph.diamonddoge.org/ show the first two; link them.
+Offer the animation tiers as reference points; the books at https://papermorph.diamonddoge.org/ show each of them (and the picture books); link them.
+
+1. **Diagrams that change**: symbols, number lines, graphs and shapes built in code, rearranged as the narration explains (the maths books). The lightest; a smaller model can do most steps.
+2. **Illustrated scenes**: characters act out the idea, the camera moves, external images and a storyboard before motion (the science book). Several times the work of tier 1 per chapter, and the picture step wants a strong model.
+3. **Custom**: the user describes what they want; you judge which abilities it needs and say so.
-1. **Diagrams that change**: symbols, number lines, graphs and shapes built in code, rearranged as the narration explains (the maths books). Lightest: about 100k tokens a chapter, works on a smaller model.
-2. **Illustrated scenes**: characters act out the idea, the camera moves, external images and a storyboard before motion (the science book). About 400k tokens a chapter on a large model.
-3. **Picture book**: a short film of paper puppets acting out a story, the sets drawn in code or painted by an image model ([stories.md](stories.md)). For stories, jokes and fairy tales, including a story book's PDF.
-4. **Documentary**: coming, not available yet.
-5. **Custom**: the user describes what they want; you judge which abilities it needs and say so.
+Recommend one from the chapter's content: abstract and procedural ideas fit tier 1 ([diagrams.md](diagrams.md)); physical and narrative ones fit tier 2 ([scenes.md](scenes.md)). Mixing per beat is allowed under any tier.
-When the user brings a story rather than a textbook, go straight to [stories.md](stories.md), which has its own short intake. Otherwise recommend one from the chapter's content: abstract and procedural ideas fit tier 1 ([diagrams.md](diagrams.md)); physical and narrative ones fit tier 2 ([scenes.md](scenes.md)). Mixing per beat is allowed under any tier.
+Then start the book folder ([site.md](site.md#start-a-book-folder)): the look is settled on real frames, so the engine, the chapter page and the voice need to be in place first.
## 4. The look, by tier
@@ -42,15 +46,29 @@ When the user brings a story rather than a textbook, go straight to [stories.md]
**Custom**: ask what the description leaves open, using the closest tier's rounds and options.
-When the book cites other works (author–year citations, named studies), ask whether the works named on screen should link to their sources ([authoring.md](authoring.md#citations)); when its questions must be reviewed before release (a course book), offer an item bank ([authoring.md](authoring.md#choice-questions-from-an-item-bank)). Neither is on by default.
+## 5. Models
+
+Which model does which step is the user's choice. Users run the Skill with different models and providers, and a book can mix them. Show the defaults for the chosen tier as one table, one row per step of the chapter loop ([team.md](team.md#steps)), and ask: keep it (recommended), or change some rows. Any model the user names is fine.
+
+| Step | Tier 1 | Tier 2 | Picture book |
+|---|---|---|---|
+| Extract the chapter (or the story) | small | small | strong (script and storyboard with the user) |
+| Narration and beats | middle | middle | strong (voices, the episode kit) |
+| Picture: storyboard, motion, questions | middle | strong | middle, one worker per scene |
+| Checks | small | small | small (sound effects too) |
+| Review | middle | middle | strong director, middle picture and sound reviewers |
+| Rework | strong | strong | middle, per scene |
+| Register | small | small | small |
+
+**small**, **middle** and **strong** stand for the user's current fast, balanced and most capable models; write the actual model names into `models`. Without subagents one agent does every step on its own model, and the table only records that. The user can change a row at any time; later chapters follow the table as it stands.
-## 5. style.json
+## 6. style.json
Start from [the template](../assets/templates/style.json). Blocks are grouped by ability, not by tier; a tier is just which blocks are present:
| Block | What it holds | Present in |
|---|---|---|
-| `schema`, `tier`, `book` | schema version; `1`, `2` or `"custom"`; title, slug, language, readers, pilot chapter | all |
+| `schema`, `tier`, `book` | schema version; `1`, `2`, `"custom"` or `"picture"`; title, slug, language, readers, pilot chapter | all |
| `words` | the user's own words about the look, verbatim, with later feedback that changed the bar | all |
| `look` | palette, what each colour means, text and maths fonts, notation and rounding | all |
| `voice` | TTS engine (`edge`, or `kokoro` when Edge is unavailable or local audio is wanted), voice, rate | all |
@@ -59,9 +77,12 @@ Start from [the template](../assets/templates/style.json). Blocks are grouped by
| `scenes` | art style, cast, how storyboards are reviewed | tier 2 |
| `components` | shared elements: name, file, what each does | tier 2, tier 1 when the book has some |
| `images` | where images may come from, credit rules | tier 2 |
+| `models` | the model for each step, as agreed in §5 | all |
+| `illustration` | a picture book's look, budget, cast and sets ([stories.md](stories.md#intake-for-a-story)) | picture books |
+| `courses` | the course options chosen ([courses.md](courses.md)) | when chosen |
| `approved` | chapters the user approved and what each shows well | filled as chapters are approved |
-Leave out blocks the tier does not use. Later tiers add their own blocks (for example `illustration` or `footage`) beside these; a reader that meets a block it does not know reads it as plain intent. Increase `schema` only when an existing field changes meaning.
+Leave out blocks the tier does not use. New kinds of book add their own blocks beside these; a reader that meets a block it does not know reads it as plain intent. Increase `schema` only when an existing field changes meaning.
Deliver the pilot with a choice: approve and make the rest of the book (recommended when it is good), approve and stop here, or one of two or three concrete changes you would make yourself. Fold the answer and any feedback into `words` and the affected block, and add an approved chapter to `approved`. Approved chapters are the strongest anchor: later chapters watch and read them as worked examples.
diff --git a/.claude/skills/papermorph/references/painting.md b/.claude/skills/papermorph/references/painting.md
index e8e668b..23d34b2 100644
--- a/.claude/skills/papermorph/references/painting.md
+++ b/.claude/skills/papermorph/references/painting.md
@@ -4,7 +4,7 @@ In the painted look, one question splits the work: **does it move?** Streets, ro
## Choosing the look
-Paint one set two or three ways at the cheapest quality, stand the puppets in each (composite a frame), and let the user choose. In *Joke Collection* the candidates were flat paper like the puppets, warm gouache, and a richer torn-paper collage with light; the user chose the collage: "no need to copy South Park 100%; use the image model as far as it goes while what can move, moves". Keep the chosen picture as the style reference for every later set and prop, and record the style words in `style.json`.
+Paint one set two or three ways at the cheapest quality, stand the puppets in each (composite a frame), and let the user choose. In *Joke Collection* the candidates were flat paper like the puppets, warm gouache, and a richer torn-paper collage with light; the collage was chosen: let the image model carry as much as it can, while everything that can move still moves. Keep the chosen picture as the style reference for every later set and prop, and record the style words in `style.json`.
## Getting the composition you need
@@ -22,9 +22,9 @@ Everything that comes out goes through `painted.py` (manifest `books/<book>/art/
Money is the user's, so the user sets a ceiling and sees every cent:
- `paint.py` takes quality `low` or `medium` only. Try low first: in these books low was often good enough for the final set (about $0.02 a picture; medium about $0.02–0.03; high cost five times as much and, once used in a film, looked the same).
-- Every picture is logged with its cost (`--ledger books/<book>/art/costs.tsv`); before a batch, say how many pictures and what they will cost; after it, report the real balance from the provider, not an estimate. OpenRouter refuses any image request when the balance is under one dollar.
-- Without an OpenRouter account, `paint_openai.py` calls OpenAI's image API directly with the same arguments and ledger (key in `OPENAI_API_KEY`). OpenAI does not return a price, so its ledger lines are estimates: read the real spend from OpenAI's usage page.
-- After every batch, put the pictures on one contact sheet and open it for the user (Finder, the browser), even when working on your own: they like to see each stage.
+- `paint.py` reads the OpenRouter key from `~/.config/openrouter/key` or `$OPENROUTER_API_KEY`. Every picture is logged with its cost (`--ledger books/<book>/art/costs.tsv`; `paint.py --total books/<book>/art/costs.tsv` sums it); before a batch, say how many pictures and what they will cost; after it, report the real balance from the provider (OpenRouter's credits page, or `GET https://openrouter.ai/api/v1/credits` with the key), not an estimate. OpenRouter refuses any image request when the balance is under one dollar.
+- Without an OpenRouter account, `paint_openai.py` calls OpenAI's image API directly with the same arguments and ledger (key in `$OPENAI_API_KEY`, `--env FILE` or `~/.config/papermorph/.env`). OpenAI does not return a price, so its ledger lines are estimates: read the real spend from OpenAI's usage page.
+- After every batch, put the pictures on one contact sheet and open it for the user (Finder, the browser), even when working on your own, so the user sees each stage.
## Credits and licences
diff --git a/.claude/skills/papermorph/references/puppets.md b/.claude/skills/papermorph/references/puppets.md
index 0fc4a59..13ab38e 100644
--- a/.claude/skills/papermorph/references/puppets.md
+++ b/.claude/skills/papermorph/references/puppets.md
@@ -7,7 +7,7 @@ Two cast styles are on the shelf, both on the same `paper.js`: round-headed figu
## What makes it read as stop motion
- **Twelve frames a second, on twos.** `stopClock` samples every movement into steps; the slight jerk is the style, not a defect. Big moves still ease in and out across those steps.
-- **The animator's hand.** Each frame nudges every puppet by a tiny random amount (`jit(frame, k)`, the same nudge for the same frame, so pause, seek and `?beat=N&t=S` show exactly what playback shows), and the picture flickers faintly. Keep it small: at full strength it read as shaking ("抖动有点太剧烈", the user said); a third of a pixel-ish wobble, held for two frames, felt hand-made.
+- **The animator's hand.** Each frame nudges every puppet by a tiny random amount (`jit(frame, k)`, the same nudge for the same frame, so pause, seek and `?beat=N&t=S` show exactly what playback shows), and the picture flickers faintly. Keep it small: at full strength it reads as shaking; a third of a pixel-ish wobble, held for two frames, felt hand-made.
- **Paper you can feel.** Grain, torn edges and a soft drop shadow on every piece (the `#paper` filter), brass pins at the joints, and a soft contact shadow under the feet so a puppet stands on the ground, leaning the way the set's light falls.
- **Replacement, not morphing.** Mouths are swapped shapes timed to the words; a blink is two closed frames; a door opens through a few boards of different widths; a bun bitten is a different picture.
@@ -21,7 +21,7 @@ Two cast styles are on the shelf, both on the same `paper.js`: round-headed figu
## Cameras
-`paperCam(parent, set, view)` is one camera on one set: layers slide with parallax, `to`/`cut` move it on the scene's clock, `soft` swaps in the blurred copy of the set for close-ups, `shake` jolts it, `show(layer, on)` swaps a layer (rain and snow versions of the same street). Several cameras can live in one scene; cut between places by showing one `cam.root` and hiding the others. Close-ups zoom the same set and blur it, so the speaker stays sharp.
+`paperCam(parent, set, view)` is one camera on one set: layers slide with parallax, `to`/`cut` move it on the scene's clock, `soft` swaps in the blurred copy of the set for close-ups, `shake(t0, dur, amp = 10)` jolts it (note the order: the engine's `cam.shake` takes the amplitude first), `show(layer, on)` swaps a layer (rain and snow versions of the same street). Several cameras can live in one scene; cut between places by showing one `cam.root` and hiding the others. Close-ups zoom the same set and blur it, so the speaker stays sharp.
## Performance
diff --git a/.claude/skills/papermorph/references/review.md b/.claude/skills/papermorph/references/review.md
index a0e9840..3380fc7 100644
--- a/.claude/skills/papermorph/references/review.md
+++ b/.claude/skills/papermorph/references/review.md
@@ -26,12 +26,6 @@ uv run --with playwright SKILL/scripts/overlap.py chNN --url http://localhost:87
`shot.py` captures open/end frames of every beat as 4-up sheets and reports console errors. Look for an empty or unrelated opening, text over drawings or clipped at the edge, a card covering what it asks about, leftovers half faded, geometry contradicting its values, shapes inside circles or curves crossing the outline (check thin geometry on the full-size `chNN_bII_T.png`, not only the sheet), text too small at half size or too much at once, and the same idea in different colours. `check_blank.py` reports openings empty for more than a second after speech starts. `overlap.py` samples every beat and lists where an arrow runs through text or two texts collide, with times, so you can look at exactly those frames.
-## Questions and citations
-
-For a chapter with an item bank, lint it with the item writer (`python3 MCQ/scripts/lint_items.py books/<book>/items/chNN.items.json`, where `MCQ` is the mcq-item-writer skill's folder) and fix every error; rebuild `items.js` after any change, then answer one bank question per card position, wrong then right, to see the answered card fit with Continue visible.
-
-For a chapter that cites works, run `python3 SKILL/scripts/refs.py verify books/<book>/refs.json` and rebuild `refs.js` after any `refs.json` change. Every author–year or work title on screen should be a link whose key is verified; look for links that are missing, unreadable or overlapping other targets, and open one per chapter to confirm it lands on the work.
-
## Smoothness
`uv run --with playwright SKILL/scripts/perf.py chNN --url …` measures frame times in Firefox, which repaints SVG on the main thread and is the slowest common browser for these pages; headless Chromium hides paint cost. Look at the worst beats and transitions; the remedies are in [engine.md](engine.md#performance-firefox).
diff --git a/.claude/skills/papermorph/references/scenes.md b/.claude/skills/papermorph/references/scenes.md
index 10d1636..72bd8e2 100644
--- a/.claude/skills/papermorph/references/scenes.md
+++ b/.claude/skills/papermorph/references/scenes.md
@@ -4,7 +4,7 @@ For physical, spatial and narrative ideas: people and things act out the idea, t
## Each moment is one picture
-The subject comes first, large and placed where the eye lands; text is part of the picture and appears beside what it names, as it is said. A layout with a title row, a picture somewhere else and notes in a column feels fragmented ("割裂", the user's word) even when every piece is correct.
+The subject comes first, large and placed where the eye lands; text is part of the picture and appears beside what it names, as it is said. A layout with a title row, a picture somewhere else and notes in a column feels fragmented even when every piece is correct.
Worked example, the push in the science book's chapter 10:
- *Before*: a small pusher and cart at the bottom left, the sentence at the top centre, the word "push" floating far from both, and an arrow above the cart rather than on it. Every piece was right; nothing read as one picture.
@@ -21,7 +21,7 @@ Vary the composition with the content (a close-up, a wide shot, a split screen,
## Actors and actions
-When the narration says someone pushes, throws or jumps, they perform it with weight and timing, and what they handle moves with them. A figure sliding across the ground like a statue reads as a still picture, not an action; the user objected to that strongly.
+When the narration says someone pushes, throws or jumps, they perform it with weight and timing, and what they handle moves with them. A figure sliding across the ground like a statue reads as a still picture, not an action, and viewers notice it at once.
- Drive gait frames from the distance travelled, so the feet keep pace with the ground.
- Keep contact as a shared position: the prop follows the hand position of the current frame; a ball is caught, held and released through it.
- Time poses to narration marks (wind-up before "kick", contact on it), and derive motion constants from the marks when an action must land on a word.
diff --git a/.claude/skills/papermorph/references/site.md b/.claude/skills/papermorph/references/site.md
index 6e9bbd5..f14f26c 100644
--- a/.claude/skills/papermorph/references/site.md
+++ b/.claude/skills/papermorph/references/site.md
@@ -20,25 +20,40 @@ cp "$SKILL/assets/templates/narration.en.json" "content/$BOOK_ID/ch01/narration.
### 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:
+Instead of the block above (not after it). The book's `index.html` is the series page; each episode comes from the picture-book kit, and the empty `baked.js` stands in until `bake_puppets.py` has run:
```sh
+BOOK_ID=jokes
+BOOK_SITE="site/$BOOK_ID"
+BOOK_WORK="books/$BOOK_ID"
PB="$SKILL/assets/templates/picture-book"
-mkdir -p "$BOOK_SITE/img/puppets" "$BOOK_WORK/art" "content/$BOOK_ID/ch01"
+mkdir -p "$BOOK_SITE/lib" "$BOOK_SITE/img/puppets" "$BOOK_SITE/ch01" "$BOOK_WORK/art" "content/$BOOK_ID/ch01" "tools/$BOOK_ID"
python3 "$SKILL/scripts/engine.py" "$BOOK_SITE"
-cp "$SKILL/assets/templates/book.html" "$BOOK_SITE/index.html"
+cp "$PB/series.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/sets.js" "$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"`.
+For a painted look, also `cp "$PB/painted.json" "$BOOK_WORK/art/"` ([painting.md](painting.md)). Then the sound and the pictures, in this order ([sound.md](sound.md), [puppets.md](puppets.md)), with the preview server running on 8765:
+
+```sh
+A="$BOOK_SITE/ch01/audio/en"; N="content/$BOOK_ID/ch01/narration.en.json"
+uv run --with edge-tts python "$SKILL/scripts/tts.py" "$N" "$A"
+python3 "$SKILL/scripts/mouths.py" "$N" "$A"
+python3 "$SKILL/scripts/join.py" "$A" scene1=s01,s02,s02b,s03 --words "$N"
+uv run --with numpy python "$SKILL/scripts/sfx.py" "$BOOK_SITE/ch01/audio/sfx" knock
+uv run --with playwright --with pillow python "$SKILL/scripts/bake_sets.py" "$BOOK_WORK/art/sets.js" "$BOOK_SITE"
+uv run --with playwright --with pillow python "$SKILL/scripts/bake_puppets.py" "$BOOK_SITE" --url "http://localhost:8765/$BOOK_ID/"
+```
+
+Keep these commands in a script beside the book's notes (`tools/$BOOK_ID/audio.sh`) and rerun it after any change to the narration. A painted look paints its sets between `bake_sets.py --ref` and the scenes ([painting.md](painting.md)).
### 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.
+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`, it picks the audio folder). Set `<html lang>` in `index.html` and every chapter to the same language: the player and the contents page take their interface text from it (English, Russian, Chinese and Japanese are built into the engine; other languages fall back to English until a block is added to the engine's `TRANSLATIONS`). Take `voice` and `rate` for each narration file from `style.json`, and translate the template's own visible text (titles, lede, prompts) 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:
@@ -46,18 +61,25 @@ If the book's formulas need LaTeX ([engine.md](engine.md#latex)), add MathJax (w
python3 "$SKILL/scripts/engine.py" "$BOOK_SITE" --latex # lib/mathjax.js; later syncs keep it in step
```
-Each book has its own engine copy (kept in step with `engine.py`, see [engine.md](engine.md)), source materials, narration and optional tests. The engine and cover derive the same progress key from the book's URL folder. Keep existing books on their current paths; their legacy progress remains intact.
+Each book has its own engine copy (kept in step with `engine.py`, see [engine.md](engine.md)), source materials, narration and optional tests. The engine and cover derive the same progress key from the book's URL folder (or `--progress-key` in `lib/book.css`), so moving a book to another folder resets its readers' progress unless the key is set.
-A chapter returns to its book's index. Preserve cover → contents → chapter navigation and the return from contents to cover. The book opens directly at `/<book>/`; it needs no parent index page. Keep existing books' navigation when editing them.
+A chapter returns to its book's index. Preserve cover → contents → chapter navigation and the return from contents to cover. The book opens directly at `/<book>/`; it needs no parent index page.
## Cover and contents (`index.html`)
+A textbook's cover and contents; a picture book uses its series page instead ([stories.md](stories.md#delivering)).
+
One page: no hash or `#book` shows the cover, `#references` the reference list, `#contents` or `#chNN` the contents; a lesson's home button returns to `#chNN`, and the card grows into the lesson frame through a view transition.
- Edit the title, kicker, lede, the faint chalk phrases on the cover (a few formulas or lines from the book), and the `<title>`.
-- The page's script calls `Contents.book({ start, units, hues })` (from the engine's `lib/contents.js`; the shared styles are `lib/contents.css`). `units`: `[unit title, [[chapter title, minutes], …]]`; chapters are numbered in order from `start` (`{ unit: 1, chapter: 1 }`; a book whose scope starts mid-way, e.g. at unit 3, chapter 9, keeps the original numbers). Add a chapter when its lesson is ready; also set the previous chapter's `CHAPTER.next = '../chNN/'`. An optional third entry `{ unit, chapter, sample: true }` renumbers a unit and marks it as a sample, left out of the chapter count. To show different numbers than the folders, add `label` to `start` (`{ unit: 1, chapter: 9, label: 1 }` shows ch09 as 1) and set the same `CHAPTER.label` in each lesson, which its title screen and completion card show. A chapter's own third entry `{ chapter }` changes only the number on its card; `{ href, chapter }` links a card to another book's chapter, outside this book's count and progress (`href` on a unit's entry does it for the whole unit).
+- The page's script calls `Contents.book({ start, units, hues })` (from the engine's `lib/contents.js`; the shared styles are `lib/contents.css`):
+ - `units`: `[unit title, [[chapter title, minutes], …]]`; chapters are numbered in order from `start` (`{ unit: 1, chapter: 1 }`; a book whose scope starts mid-way, e.g. at unit 3, chapter 9, keeps the original numbers).
+ - Add a chapter when its lesson is ready, and set the previous chapter's `CHAPTER.next = '../chNN/'`.
+ - A unit's optional third entry `{ unit, chapter, sample: true }` renumbers it and marks it as a sample, left out of the chapter count.
+ - To show different numbers than the folders, add `label` to `start` (`{ unit: 1, chapter: 9, label: 1 }` shows ch09 as 1) and set the same `CHAPTER.label` in each lesson, which its title screen and completion card show.
+ - A chapter's own third entry `{ chapter }` changes only the number on its card; `{ href, chapter }` links a card to another book's chapter, outside this book's count and progress (`href` on a unit's entry does it for the whole unit).
- `hues`: one colour per unit, cycling.
-- References (only a book that cites works): uncomment the `refs.js` line in `index.html` and in each chapter; the contents then ends with one link to the separate `#references` view, which lists every cited work linked to its DOI or catalogue record; a book without citations shows no link. Rebuild `refs.js` whenever `refs.json` changes ([authoring.md](authoring.md#citations)).
+- A book that cites works gets a `#references` view ([courses.md](courses.md#citations)).
- A book with its own look overrides the tokens of `lib/contents.css` (`--board`, `--chalk`, `--top-bg`, …) in a `<style>` after it, as the template's comment shows; don't copy the stylesheet into the page.
## Unit sketches (`unit-art.js`)
@@ -66,7 +88,7 @@ Give each unit a small sketch of its own ideas, drawn in the unit colour, with o
## Guide character
-Keep the existing infinity guide by default. For an agreed custom guide, adapt `mascotEl` and the cover drawing together, retaining blink, happy hop and wrong-answer tilt states.
+The infinity guide comes with the engine (`mascotEl` in `engine.js`, the cover's in `contents.js`), so a book's copy is replaced at every sync. A custom guide needs a hook in the engine itself; agree it with the user and change the engine at its source.
## Local preview and delivery
@@ -85,27 +107,3 @@ Narration and on-screen text are written in one language first. A second languag
## Video export (optional)
`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)
-
-For a course in an LMS (Canvas/Quercus, Moodle, Brightspace, Blackboard), package a built book as one SCORM zip:
-
-```sh
-python3 SKILL/scripts/scorm.py site/<book> # SCORM 2004 4th edition, completion only -> dist/<book>-scorm2004.zip
-python3 SKILL/scripts/scorm.py site/<book> --version 1.2 # older LMSs
-python3 SKILL/scripts/scorm.py site/<book> --mastery 80 # also passed/failed at 80 %, once the whole book is finished
-```
-
-`site/<book>/` is not changed; rebuild the zip after changing the book. The LMS launches `launch.html`, which opens one SCORM session and runs the book in a frame, so moving between chapters keeps the session. The build adds `scorm-bridge.js` to the contents page and after `engine.js` in every chapter; it wraps the engine's `progress()` and `finishCard()`, seeds the book's progress from the LMS on each launch (the LMS is the source of truth) and points folder links (`ch02/`) at `index.html`, which many LMS file servers need.
-
-| | SCORM 1.2 | SCORM 2004 |
-|---|---|---|
-| Completion: every chapter's finish card reached | `cmi.core.lesson_status` (`passed`/`failed` with `--mastery`) | `cmi.completion_status`, `cmi.success_status` with `--mastery` |
-| Progress: chapters finished ÷ chapters | — | `cmi.progress_measure` |
-| Score: first-try answers over all quick checks and practice, best attempt per chapter | `cmi.core.score.raw` | `cmi.score.raw`, `cmi.score.scaled` |
-| One objective per chapter (`ch01`, …) with status and score | `cmi.objectives.n.*` | `cmi.objectives.n.*` |
-| Resume (checkmarks, Continue) | `cmi.suspend_data`, `lesson_location` | `cmi.suspend_data`, `cmi.location` |
-
-A chapter counts as finished when its finish card appears, as in the book; a learner can skip there on the step bar, so use `--mastery` when the grade should depend on the answers. Cards that link to another book's folder (`href` in `units`) leave the package and don't work inside an LMS.
-
-Check a package before handing it over: `uv run --with playwright SKILL/assets/scorm/test/check_scorm.py dist/<book>-scorm2004.zip` opens it in `assets/scorm/test/mock-lms.html` (a stand-in LMS that shows every CMI value), opens a chapter through a folder link, reaches its finish card and checks resume. To click through by hand, unzip the package as `pkg/` next to a copy of `mock-lms.html`, run `python3 SKILL/assets/scorm/test/serve.py <folder> 8781` (no folder URLs, like an LMS) and open `http://localhost:8781/mock-lms.html?pkg=pkg&v=2004&reset`; reload without `&reset` to test resume. Before learners use it, upload it to SCORM Cloud (a free account), the usual test of a real LMS. Audio makes up most of a package: check the LMS's upload limit. Canvas grades only the overall result; it doesn't show the per-chapter objectives.
diff --git a/.claude/skills/papermorph/references/sound.md b/.claude/skills/papermorph/references/sound.md
index 05460ab..92334c1 100644
--- a/.claude/skills/papermorph/references/sound.md
+++ b/.claude/skills/papermorph/references/sound.md
@@ -1,6 +1,6 @@
# Sound for picture books
-Voices carry the story; everything else sits under them. In early cuts the music and effects were loud enough that the lines got lost ("说话的声音听不见"), and that was the first thing the user noticed.
+Voices carry the story; everything else sits under them. In early cuts the music and effects were loud enough that the lines got lost, and that was the first thing viewers noticed.
## Voices
diff --git a/.claude/skills/papermorph/references/stories.md b/.claude/skills/papermorph/references/stories.md
index 3394e4f..43303a3 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; 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)).
+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 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.
@@ -9,13 +9,22 @@ The craft is in four references: this one (the story and the shots), [puppets.md
The same spirit as [intake.md](intake.md): a light conversation, choices to click, the user's words kept verbatim. What to settle, skipping whatever the telling already settles:
1. **The story itself.** Let the user tell it in their own words and keep that telling in `books/<book>/story.md` untouched. Ask what is true and must stay (a real joke has one real punchline), who the people are, where it happens, what language each person speaks.
-2. **The look.** Two ways, both with paper puppets ([puppets.md](puppets.md)):
- - *Paper, all in code*: sets and props drawn as SVG paper too. No image cost, plainer, very consistent (Little Red Riding Hood).
+2. **The look** is the user's to choose; there is no house style. Paper puppets moved in code ([puppets.md](puppets.md)) are what has worked best so far, so offer them first, in two ways, and welcome any other idea the user has:
- *Painted world, paper actors* (recommended when an image budget is fine): an image model paints the sets and everything that stays still; the puppets and anything that moves stay in code (Joke Collection, under a dollar of pictures per episode). Ask for a budget ceiling and keep to it ([painting.md](painting.md)).
+ - *Paper, all in code*: sets and props drawn as SVG paper too. No image cost, plainer, very consistent (Little Red Riding Hood).
3. **Language and voices**: the narration language, one voice per character ([sound.md](sound.md)).
4. **A series or one film.** A series shares cast, sets and the series page; each episode is a chapter (`chNN`).
-Record the answers in `style.json` (an `illustration` block: the look, the budget, the cast with a line each, the sets) and go on to the script.
+Then agree on the models ([intake.md](intake.md#5-models)) and write `style.json` from [the picture-book example](../assets/templates/picture-book/style.json): `tier: "picture"`, the user's words, the look they chose, a voice for each character, an `illustration` block (the sets, the budget, the cast with a line each), the models, and later the approved episodes. It holds this book's own choices so that its episodes match each other; another book can look entirely different. Then go on to the script.
+
+## The order of work
+
+1. Intake (above), then the script and the storyboard, shown to the user (below).
+2. Start the folder ([site.md](site.md#a-picture-book)).
+3. Sound: voices, mouth shapes, one joined clip per scene with its word times, sound effects ([sound.md](sound.md)).
+4. Sets: sketch them in `sets.js`, bake them, and if the look is painted, paint them from the baked sketches ([painting.md](painting.md)).
+5. The cast and the scenes, one script per scene ([puppets.md](puppets.md)); bake the puppet pieces.
+6. Review rounds (below), then the user's viewing, then registering the episode.
## The script comes first
@@ -25,7 +34,7 @@ What made the difference, from the books:
- **Set up everything the punchline needs.** The first cut of *Breakfast in the Bathroom* had Bo ask "Wanna go eat breakfast… in the bathroom?" out of nowhere; viewers took it literally. It became a joke once the film first showed his two everyday questions, "Breakfast?" every morning at the stall and "Bathroom?" after every class, and then the morning he overslept and came in starving.
- **Show the motive before the line.** Bo's stomach growls; a bun appears in a thought bubble; he glances at the door and a toilet appears beside it; the two bubbles shove each other and merge. Only then does he speak. The audience is ahead of him, which is where comedy happens.
-- **Every event needs a cause the audience has seen.** In *Little Red Riding Hood* the first rescue had a woodcutter from nowhere, Grandma suddenly out of the wardrobe and the wolf flying out of the window "as if Grandma had superpowers" (the user's words). The fix was a chain: the woodcutter chopping wood near the cottage earlier, a cut to Grandma's eye in the wardrobe crack during the questions, the cry for help, Grandma's umbrella on the wolf's head, the woodcutter blocking the door, the window the only way out, and outside, the window still broken.
+- **Every event needs a cause the audience has seen.** In *Little Red Riding Hood* the first rescue had a woodcutter from nowhere, Grandma suddenly out of the wardrobe and the wolf flying out of the window as if Grandma had superpowers. The fix was a chain: the woodcutter chopping wood near the cottage earlier, a cut to Grandma's eye in the wardrobe crack during the questions, the cry for help, Grandma's umbrella on the wolf's head, the woodcutter blocking the door, the window the only way out, and outside, the window still broken.
- **The audience understands what the characters don't.** In *Do You Need a Bag?* the clerk speaks only Japanese and the customer only English: each line is spoken in its own language with subtitles, and a thought bubble shows the mishearing ("…REJI…?" turning into "VEGGIE?"), so the joke works for viewers who speak neither.
- **Keep the user's story.** Tighten the wording, add the small connecting moments a film needs, and list every addition for the user; don't swap their joke for a different one.
@@ -38,10 +47,22 @@ 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.
+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. Someone following stays far enough behind that the delay itself reads; 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.
+## Review rounds
+
+A first cut made in one pass looks like a first cut. What lifts an episode is watching it the way a director would, against the episodes the user already approved, and sending scenes back.
+
+- **Director's view**: contact sheets of the whole episode beside an approved one. Look for story-level causes, not glitches: is every object the joke hangs on given its own shot, is the cause shown before the payoff, are the reactions framed so they read, is the shot density close to the approved episodes', does a silence stay silent? Write a restaging for each scene that needs one: which shots, from where, on which word.
+- **Picture and sound**: frame by frame for faces cut by the edge, popping poses, puppets passing through each other; sound for lines cut short, effects out of step, music over a silence.
+- Restage the scenes from those notes, then look again; two rounds usually settle it.
+
+With subagents the reviewers run in parallel ([team.md](team.md#picture-books)); alone, do the same rounds yourself, one viewpoint at a time, writing each review down before changing anything.
+
## 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`: when an episode's last scene ends, the player marks it watched and offers the next one.
+The episode is a first cut for the user's viewing, not a finished film. Deliver its 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. Once the user approves it, add it to `approved` in `style.json` and to the series page, 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.
+
+The series page is the book's `index.html`, made from [series.html](../assets/templates/picture-book/series.html): one card per episode with a still, its title and a line, and a mark on episodes already watched.
diff --git a/.claude/skills/papermorph/references/team.md b/.claude/skills/papermorph/references/team.md
index 832424e..34e800d 100644
--- a/.claude/skills/papermorph/references/team.md
+++ b/.claude/skills/papermorph/references/team.md
@@ -4,7 +4,7 @@ After the pilot, a chapter can be made by a coordinator handing each step of the
Why this shape: one agent doing a whole chapter carries an ever larger context through every call, and long idle waits make that context expire and get written again; that, more than the model's price, makes a chapter expensive. Small workers that start from the files they need and finish quickly cost far less, and each step can use the cheapest model that does it well. On a physics book this cost about half as much per minute of narration as one strong agent doing everything, at the same quality.
-Models below are named by tier: **small** (fast and cheap; Haiku today), **middle** (Sonnet today), **strong** (Opus today). Pass the tier's current model to the subagent.
+Each step runs on the model the user chose for it (`models` in `style.json`, agreed at intake: [intake.md](intake.md#5-models)). The defaults below are named by strength: **small** (fast and cheap), **middle**, **strong** (the most capable); where `models` is silent, use them and say which model you picked.
## The coordinator
@@ -21,7 +21,7 @@ Start each worker in the background with a short brief: the chapter and its page
4. **Checks — small, report-only**, in parallel with 5: lint, `check_blank.py`, `overlap.py`, `still.py`, `perf.py` in Firefox, and an e2e test adapted from the previous chapter's, in Chromium and Firefox. It reports problems with beat and time and changes only its own test.
5. **Review — middle**, in parallel with 4: watch every beat as [review.md](review.md) describes, against the storyboard and the approved chapters. It fixes small local problems itself and lists larger ones with beat, time and a suggested fix. Its reply opens with the beats it watched; if some are missing, send it back to finish (continuing a worker is cheaper than starting one).
6. **Rework — strong, only for real problems** left by 4 and 5: a brief listing exactly those, re-checked with strips, `still.py`, lint and e2e in both browsers.
-7. **Register — small.** Give it the exact edits: the contents entry, the previous chapter's `CHAPTER.next`, cover or shelf counts, `chapters.md` and the status line in chNN.md. Then lint and e2e.
+7. **Register — small.** Give it the exact edits: the contents entry, the previous chapter's `CHAPTER.next`, chapter counts on the cover, `chapters.md` and the status line in chNN.md. Then lint and e2e.
## Before delivering
@@ -39,6 +39,11 @@ The same shape, split by scene instead of by step. The **strong** coordinator wr
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.
+Review comes in rounds ([stories.md](stories.md#review-rounds) says what to look for):
+
+- **Who**: four report-only reviewers watch the episode against the approved ones: a director (**strong**) for story, comedy, staging and shots; two picture reviewers (**middle**) splitting the scenes; one (**middle**) for sound and runtime.
+- **Reports**: each ranked: scene, beat-clock time, what is wrong as a viewer sees it, a concrete fix. Earlier good reports serve as examples.
+- **Merging**: the coordinator turns 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.
+- **Closing**: 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. Two or three rounds made the best episodes. 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.