@anvpx/motion 0.0.0-stage → 0.1.1

package/skills/motion-kit/references/slop.md

@@ -0,0 +1,40 @@
+# What never ships
+
+Historical style heuristics attributed to a skill built on 53 frame-measured moments and rejected AI films. The underlying corpus and measurements are not qualified by this package. Use the observations to question an unchosen habit, not to define a permissible style.
+
+These are style defaults and judgement calls, not engine rules: when the brief earns one of these deliberately, it is allowed — name the exception and its reason in the outline instead of following the list mechanically.
+
+## Examine unchosen defaults
+
+1. **Page chrome:** a name in a corner, counters ("02 / 05"), timecodes, progress bars, corner brackets.
+2. **Deck layouts:** a held left headline, a kicker above a headline, headline-left/device-right.
+3. **Generic UI:** a rounded card with a status dot and "label . value", skeleton bars, invented numbers.
+4. **The name's first association:** stars for a star, a rocket for "launch".
+5. **Invented stats**, stat walls, on-screen disclaimers.
+6. **Slogan copy:** "Not just X. It's Y.", "Unlock", "Meet X", "the future of".
+7. **The house style as default:** a giant cropped word, a colour-flood wipe, a dot becoming the logo.
+8. **A flat swatch ground per scene**, or a small card on a void.
+9. **A pinned object** at the same coordinates through three shots.
+10. **A web-footer ending:** logo + tagline + button + URL.
+11. **Self-certification:** claiming a gate passed without quoting its number.
+12. **A film you did not look at.**
+
+## Historical motion hypotheses
+
+These source-specific observations are starting points for a short, energetic treatment, not measured laws of animation. Their counts and ranges have not been independently reproduced here; preview alternatives against the direction.
+
+- The source reports a median move of **10 frames (0.33 s)** and travel concentrated in the first 4-8 frames. Longer movement may be necessary for distance, weight or reading.
+- Decelerating arrivals and accelerating exits can make a hand-off decisive. Spring count follows material and meaning rather than a per-film quota.
+- The source reports **3,392 transform entries against 584 opacity fades**. That ratio does not disqualify a dissolve, atmospheric fade or a film built around opacity.
+- An oversize arrival (the source's logo example starts around 3.5x) can express force. Growth from zero can instead communicate emergence when that is the intended idea.
+- A living detail can sustain a held frame. Complete stillness and rest can also give information or emotion time to land.
+- The source's **0.3-2.3 s cuts on motion** suit one pacing vocabulary. Cuts on rest, long takes and slow cinema remain valid choices.
+- The source's **0.6-1.4 s end hold** and shrinking ending are options. Reading load, sound and narrative closure determine the actual hold and scale.
+
+## Type sizes, as a fraction of frame height
+
+Optional source examples: headline 7-11 % (9 typical) · support 5-7 % · hero number 22-29 % · wordmark 0.22-0.38 of width. They are not engine limits; choose and preview a hierarchy for the actual words, aspect and viewing conditions.
+
+## Fix order when it looks wrong
+
+broken or untrue → the idea → connections between beats → hierarchy and scale → timing → surface → sound.

package/skills/motion-kit/references/storyboard-json.md

@@ -0,0 +1,121 @@
+# Storyboard JSON: the one file you write
+
+`mk validate` checks schema, scene props, timing and lint. It is strict: an unknown key is an error, not a warning. Read the pointer in the error, fix that one thing, and use `references/patching.md` after the first write.
+
+## Smallest valid shape
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "title": "How a request reaches the data",
+    "width": 1920,
+    "height": 1080,
+    "fps": 30,
+    "theme": "default"
+  },
+  "scenes": [
+    {
+      "id": "intro",
+      "type": "title",
+      "duration": 4,
+      "move": "push-in",
+      "props": { "title": "How a request reaches the data" }
+    },
+    {
+      "id": "end",
+      "type": "outro",
+      "duration": 4,
+      "move": "push-in",
+      "props": { "title": "One public door" }
+    }
+  ]
+}
+```
+
+`version` is literally `1`. There is no version 2 and no migration command; a board with another version is invalid.
+
+## meta
+
+| Key        | Rule                                                                                                                                                                                                      |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`    | required, non-empty                                                                                                                                                                                       |
+| `width`    | pixels; default 1920. There is no `aspect` key: 16:9 = 1920x1080, 9:16 = 1080x1920, 1:1 = 1080x1080                                                                                                       |
+| `height`   | pixels; default 1080                                                                                                                                                                                      |
+| `fps`      | integer; default 30                                                                                                                                                                                       |
+| `theme`    | default `default`. Built-ins: `default`, `dark`, `tech-dark`, `calm-dark`. A template theme must be vendored into `themes/` (a `mk new` project does this; copying only the JSON elsewhere loses it)      |
+| `lang`     | optional language code                                                                                                                                                                                    |
+| `platform` | optional delivery-platform id: `facebook`, `linkedin`, `tiktok`, `youtube`, `podcast`, `reels`, `shorts`, `x`; adds that platform's safe margins. An unknown slug still validates, so pick from this list |
+| `approval` | optional `auto` or `confirm`; absent means auto                                                                                                                                                           |
+
+`mk validate` does not resolve `theme`; `mk build` and `mk preview` do. A board can validate and still fail at preview with `unknown theme "..."`. Check the theme before preview when you wrote the board by hand.
+
+## Scene keys
+
+| Key              | Rule                                                                                      |
+| ---------------- | ----------------------------------------------------------------------------------------- |
+| `id`             | required, unique, lowercase slug (`a-z`, `0-9`, hyphens)                                  |
+| `type`           | required; exactly a name from `mk catalog`                                                |
+| `duration`       | optional positive seconds; omitted = automatic from the text. Lint enforces reading time  |
+| `props`          | required object; strict. Only fields shown by `mk catalog <type>`, unlisted keys rejected |
+| `narration`      | optional spoken text for the voice path                                                   |
+| `words`          | optional voice word timings, normally written by the voice tool                           |
+| `shot`           | optional `wide`, `medium`, `close`, `overhead`                                            |
+| `move`           | optional `static`, `push-in`, `pull-out`, `pan-l`, `pan-r`, `tilt`, `orbit`, `reveal`     |
+| `ease`           | optional `linear`, `in`, `out`, `in-out`, `spring-soft`, `spring-snappy`                  |
+| `transition`     | optional `cut`, `crossfade`, `wipe`, `push`, `zoom-through`; base scenes only             |
+| `focus`          | optional label used by review                                                             |
+| `layer`          | optional `base` or `overlay`; omit for base                                               |
+| `over`, `offset` | overlays only: the base scene id they cover, and seconds into it (default 0)              |
+
+Defaults belong to the renderer; do not invent direction values. `mk catalog` lists prop defaults, not direction defaults.
+
+## Base and overlay
+
+- A base scene advances the timeline. An overlay stacks above it and does not advance it.
+- The overlay types are `lower-third`, `bug`, `progress`, `countdown`, `chapter`, `caption`.
+- Every overlay needs `layer: "overlay"`, `over: "<base id>"` and its own `duration` that fits inside the base scene. It does not take `transition`.
+- `offset` is seconds after the base scene starts.
+- A board with no base scene is invalid.
+- A base scene never takes `over` or `offset`.
+
+## Timing
+
+- Durations are seconds. A base scene's total is its own `duration`; overlays sit inside their base scene.
+- Transitions overlap adjacent base scenes, so the total is not simply the sum of durations. The worked example's four durations (4+6+4+4) plus three crossfades total 16.5 s.
+- `mk validate` reports errors and warnings, not the total. The total is printed by `mk patch`, `mk scene add`, `mk fit` and `mk preview`; use one of those (or read `preview.json`'s `totalSec`).
+- Lint enforces minimum hold and reading time (about 3 words per second of visible text, including the title and lines, not narration). A 6 s scene with only a short list still warns if nothing changes; add a `move`, shorten it, or split it.
+- About one new scene per 7 s is a useful planning number; `mk fit` can move the total only about 1.4x.
+
+## Props
+
+- Use the exact example shape from `mk catalog <type>`. Copy the example's key names, then replace values; do not rename keys or add explanatory fields.
+- Text limits are per field and are hard at validation (`<=70` means 70 characters, not words).
+- `[x]` marks an accent word in types that document it; do not use it as HTML.
+- Icons are names, not URLs: `mk icon search <word>` or `mk icon list [--tag group]`.
+- Images are local paths inside the project, with an `assets.json` ledger row. Remote URLs fail closed. Import with `mk assets import`, then pass the same `--assets` and `--ledger` to build, preview, approve and render; the image path is relative to `--assets`.
+- `highlight` is not uniform: `chart` and `table` use a 0-based item index; `code` uses an array of 1-based line numbers, for example `[1,3]`. The catalog currently prints the code field as a scalar, but the schema and validator require the array.
+- `chart`: `bar` and `donut` need `data`; `line` needs `x` and `series`; `highlight` is 0-based. `kpi-grid`: `trend` (`up|down|flat`) needs `delta`; `good` (`up|down`) needs `trend`.
+- `media-frame.callouts`: `x` and `y` are percentages 0-100, and each `label` is at most 24 characters.
+- An empty required text field is an error. Keep the copy short enough to read at phone width.
+
+## Decode these errors
+
+| Message                                                                    | Fix                                                           |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `unknown key(s): typo -> remove typo (check spelling against the catalog)` | remove the key or `mk catalog <type>` for the real field      |
+| `must be a lowercase slug (a-z, 0-9, hyphens)`                             | rename the scene id                                           |
+| `overlay needs over: <base scene id>`                                      | add `over` pointing at an existing base id                    |
+| `duplicate scene id "x"`                                                   | give every scene a unique id                                  |
+| `unknown theme "x"; use one of: ...` (at build/preview)                    | use a built-in theme, a vendored `themes/x.json`, or `mk new` |
+| `parent "/scenes/9" does not exist` (patch)                                | add the parent first, or use a path that exists               |
+
+## Writing checklist
+
+1. `version` is 1; `meta.title`, `width`, `height`, `fps`, `theme` are present.
+2. Every scene id is unique and a slug; every `type` came from `mk catalog`.
+3. Every base scene has a `move` and a `duration`.
+4. Every overlay has `layer`, `over`, `duration` and no `transition`; it fits its base.
+5. Every prop key came from `mk catalog <type>`; every text is within its limit.
+6. Every image exists locally and has a ledger row.
+7. `mk validate` prints `0 errors`; read warnings, do not ignore them.

package/skills/motion-kit/references/themes.md

@@ -0,0 +1,15 @@
+# Themes and the 3D look
+
+## Themes
+
+The package ships 18 DTCG themes, light and dark: `bold`, `calm`, `data`, `editorial`, `fjord`, `playful`, `pop`, `tech`, `warm`.
+
+`mk new` vendors the theme its blueprint uses under `themes/`. To use another, copy `<installed package>/shared/themes/<name>.json` (and its pair, for paired stills) into `themes/` beside the storyboard, then set `meta.theme` with `mk patch`. There is no `mk theme list`; this is the list.
+
+For luxury or editorial work, `editorial-*` (serif, ink) and `warm-*` (cream, terracotta) read quieter; `bold-*` (amber on violet) and `tech-*` read louder. Name the choice; the theme is part of the approval hash when vendored.
+
+## 3D
+
+`scene3d` is a procedural WebGL diorama, not a GLB importer. `model` selects `knot` (default), `gem` (faceted stone), `sphere` or `torus`; `material` is `clay|gloss|metal|emissive`; `post` is `clean|bloom|cinematic|vintage`; `light`/`hdri` are `studio|sunset|night|soft` / `neutral|studio|sunset|night`.
+
+For a luxury abstract hero, try `model: gem`, `material: metal`, `light: sunset`, `post: cinematic`, `hdri: sunset` on a dark theme. There is no model upload: use it for an abstract form, not a replica of a specific product. Without WebGL it falls back to a flat 2D canvas; say so when that matters.

package/skills/motion-kit/references/troubleshooting.md

@@ -0,0 +1,55 @@
+# Troubleshooting and exit codes
+
+Read the first `E` line, not the whole log. It names a pointer and usually a suggestion. Fix that one thing, re-run, then read the next.
+
+## First response
+
+1. `mk validate` / `mk preview`: read the pointer, compare that scene with `mk catalog <type>`, patch only that scene.
+2. Same error twice: stop changing flags. Rewrite the named scene from its catalog example via `mk patch`, or choose a different type.
+3. Third failure: stop. Tell the user the exact error and the two routes you tried; do not loop.
+4. Never disable lint, raise a limit by editing the output, or hand-edit the JSON to get past a gate.
+
+## Exit codes
+
+| Exit | Meaning                                                                    | Do                                                           |
+| ---- | -------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| 0    | success (warnings allowed)                                                 | continue; read the warnings                                  |
+| 1    | tool, build or render failure                                              | `mk doctor`; read the last lines and `render-log.txt`        |
+| 2    | bad flags, unreadable file, validation errors, no preview for `mk approve` | fix the named pointer; run `mk preview` before approve       |
+| 4    | AWAITING_APPROVAL (`--gated`)                                              | not an error: show the pack, ask, `mk approve` only on a yes |
+| 5    | QA failed (`mk verify`)                                                    | fix the named scene or param, re-render once, then report    |
+| 127  | required program missing                                                   | give the install hint from `mk doctor`; do not retry blindly |
+
+## Named failures
+
+| Symptom                                    | Cause / fix                                                                                                                                                  |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `unknown key(s): typo`                     | prop not in the catalog: remove it or `mk catalog <type>`                                                                                                    |
+| `must be a lowercase slug`                 | scene id has spaces or capitals; rename to `a-z`, `0-9`, hyphens                                                                                             |
+| `overlay needs over: <base scene id>`      | add `"over": "<existing base id>"` and a fitting `duration`                                                                                                  |
+| `duplicate scene id "x"`                   | every id must be unique                                                                                                                                      |
+| `unknown theme "x"; use one of: ...`       | built-in theme, vendored `themes/x.json`, or `mk new`; `mk validate` does not catch this. If the theme is not built-in, preview before calling stage 5 done  |
+| `mk approve` exits 2 after a preview       | the preview used `--out`/`--assets`/`--ledger`/audio flags; repeat those exact flags. The printed `approve:` hint may omit `--out`, so do not trust it alone |
+| `no ledger row` or `no assetsDir`          | run `mk assets import` for each file, then pass the same `--assets d --ledger f` to build/preview/approve/render; `image` is relative to `--assets`          |
+| `parent "/scenes/9" does not exist`        | patch path skips a level; add the parent first or target an existing path                                                                                    |
+| `mk new` slot error (`max 5`, `text<=...`) | shorten or merge; never edit the generated board past the slot limit                                                                                         |
+| `mk fit` refuses "over the X s"            | the scenes cannot stretch that far: `mk scene add`, then fit; never pad or stretch past the range                                                            |
+| `mk approve` exits 2                       | no preview for the current inputs, or a flag differs from preview; re-preview                                                                                |
+| `mk render --gated` exits 4                | no approval or the inputs changed; preview again and ask again                                                                                               |
+| Preview exits 2                            | lint or validation failed; read the still/scene it names                                                                                                     |
+| `verify` exit 5                            | read the report line: streams, duration, fps or frame count; fix the named scene, render once                                                                |
+| `mk captions` asks for `--storyboard`      | ops need scene-relative paths; add the board                                                                                                                 |
+| `mk voice` fails closed                    | Python 3.12 venv or voice extras missing; `mk doctor`; ship silent if unavailable                                                                            |
+| Preview says the clip was skipped          | budget ran out; stills are still valid; offer `--budget-sec`                                                                                                 |
+| `mk state` exits 1                         | an artifact claims more than its inputs prove; fix the overclaim, do not re-preview blindly                                                                  |
+| No vision / cannot open the image          | say so; read `preview.json`; ask the user to open the pack and approve                                                                                       |
+
+## Recover without a rewrite
+
+- Wrong wording or number: `mk patch` replace the leaf.
+- Wrong pacing: `mk patch` replace `duration`, or `mk fit --seconds N`.
+- Wrong structure: `mk scene remove|move|add`, then validate.
+- Wrong look: change the theme or the direction fields, not the copy.
+- Wrong route: restart from `mk new` or `mk scene new`; do not bolt a second route onto a broken board.
+
+After any successful edit the approval is stale. Preview again, then ask.

package/skills/motion-kit/references/voice.md

@@ -0,0 +1,61 @@
+# Voice and captions (opt-in)
+
+The engine renders silent by default. Add narration only when the user asked for it or approved it. Never imply sound that is not in the preview.
+
+## Setup
+
+Needs Python 3.12, espeak-ng and the voice extras; see `references/setup.md`. `mk doctor` prints the voice rows, and missing voice tools never fail the overall exit code. If the venv is missing, say so and ship silent; do not fake timings or substitute a different voice.
+
+## Narration
+
+1. Add `"narration": "..."` to each base scene that speaks. Overlays are skipped. Write the words as they should be spoken, not as slide copy.
+2. **Write numbers as words.** The aligner matches letters; a token with no letters (`01`, `$480`, `1,200`) cannot be aligned and `mk voice` refuses before synthesis. Say "zero one", "four hundred eighty", "twelve hundred". The visual copy can keep digits.
+3. The manifest is a non-overlapping speech sequence. The film keeps each scene's authored duration and places the wav at that scene's start; a scene that ends in silence is normal. Voice never compresses the authored picture.
+4. Keep the words final before synthesis: `mk voice` needs the final script, and a later text edit invalidates the timing.
+5. `mk voice storyboard.json --voice <id>` writes a voice TimingManifest; the stdout line names it. Use a voice the user approved; do not hardcode one silently.
+6. The command preflights the narration against the scene duration and refuses before synthesis when it cannot fit, or when a number is not written out. The silence gate can also refuse words that land inside silence. Fix the script or the scene duration; never edit the manifest to hide it.
+7. `mk qc` gates the manifest plus audio and reports PASS, WARN, FAIL or UNKNOWN. Quote its result; a synthetic file is not human-quality proof.
+
+## Music
+
+Music is opt-in; without `--music` the film is narration-only or silent. The installed package ships:
+
+- `music/bed-full.wav` — a 32 s stereo CC0 ambient bed (use this one).
+- `music/bed.wav` — a 1 s procedural silence placeholder; `--music` rejects it as silent.
+
+Pass the identical bed, volume and licence to `mk preview`, `mk approve` and `mk render`:
+
+```sh
+mk preview storyboard.json --audio .mk/<name>/voice-manifest.json \
+  --music node_modules/@anvpx/motion/music/bed-full.wav --music-volume 0.35 \
+  --music-license node_modules/@anvpx/motion/music/LICENSE-CC0.txt
+```
+
+The bed loops to the narration length and ducks under the voice. Approval binds the bed bytes, volume and licence receipt; any drift exits 4. A visual-only receipt never authorises music.
+
+## Captions
+
+- `mk captions <manifest> --storyboard storyboard.json --out ops.json` turns voice word timings into one karaoke `caption` overlay per narrated scene, already shifted to scene-relative time.
+- Apply the ops with `mk patch storyboard.json --ops ops.json`. Words past the scene duration are omitted and reported; do not silently keep them.
+- Keep each cue readable: about 20 characters/second, at most 2 lines and 42 characters per line. Shorten the text or split the cue rather than shrinking the type.
+- Export subtitles with `--srt file.srt` or `--vtt file.vtt`. Import existing cues with `--from-srt` or `--from-vtt`; import still needs `--storyboard` because the overlays need scene positions.
+- Preview again after adding captions. The approval covers the captions as part of the storyboard.
+
+## Audio and approval
+
+- `mk preview` accepts `--audio <manifest>`; `mk approve` infers it from the pack. Pass the same `--audio` to preview, approve and render.
+- The approval binds the storyboard, themes, assets, ledger, audio manifest and wavs. Any later wav, manifest or scene edit exits 4 at render; preview and ask again.
+- Optional music uses `--music`, `--music-volume` and `--music-license` on all three commands. A visual-only receipt never authorizes audio; narration-only never authorizes music.
+- If the preview clip is silent, say so in the ask. Do not describe the film as narrated until the audible preview exists.
+
+## Failure paths
+
+| Symptom                             | Do                                                                      |
+| ----------------------------------- | ----------------------------------------------------------------------- |
+| `mk voice` not installed / exit 127 | `mk doctor`; give the install hint; ship silent only if the user agrees |
+| token `"01"` has no letters         | write the number as spoken ("zero one"); digits stay in the visual copy |
+| word inside silence                 | rewrite the pause/sentence or lengthen that scene; never edit timings   |
+| narration refused before synthesis  | shorten the words or lengthen that scene; never edit timings            |
+| `mk qc` WARN or UNKNOWN             | report the exact state; do not call it PASS                             |
+| `mk captions` omits words           | tell the user which scene and how many; adjust the script or duration   |
+| render exit 4 after audio work      | the audio inputs drifted from approval; re-preview and re-approve       |

package/skills/motion-kit/references/worked-decisions.md

@@ -0,0 +1,178 @@
+# Worked decisions: what a choice costs
+
+Read this after a provisional direction exists, not before. These are three
+annotated compositions from controlled authoring fixtures. They teach the
+reasoning behind a shot, not a look to copy. Technical validity is not an
+aesthetic verdict; no example was reviewed for professional quality.
+
+## How to use a precedent
+
+For each example, separate the **decision** from the surface. Ask:
+
+1. What question did this composition answer?
+2. What did it reject, and what did that cost?
+3. Which mechanism carries the meaning (crop, route, scale, rhythm, sound)?
+4. What would make the same mechanism wrong for another brief?
+5. What is the smallest native realization, and what evidence would falsify it?
+
+If your brief shares the question but not the audience, channel or tone, keep the
+question and change the answer.
+
+## Example 1 — an invitation, not an announcement
+
+**Brief:** a public-library reading night; about 20 s; 16:9; quiet, adult,
+local. The viewer should feel invited to a room, not sold a program.
+
+**Question:** how can type feel discovered rather than announced?
+
+**Rejected:** title, date, three bullet benefits, logo. It is accurate, but it
+turns the film into a poster with a voice-over; the viewer is told, not drawn in.
+
+**Chosen relationship:** a printed sheet is uncovered from a vertical crop on an
+asymmetric left editorial grid. One large statement, one small mono label, and
+a lot of paper. The reveal follows reading order.
+
+**Why motion serves meaning:** the vertical crop is the invitation; the hold
+after the statement is the pause before someone decides to come. A push-in or
+orbit would add urgency the event does not want. Rest is part of the argument.
+
+**Native realization:** a `custom` scene with a 12-column grid; the statement
+spans columns 1-7 and the meta line sits at 1-4. On each `seek(t)`, derive one
+progress value and assign clip-path and translate from it; never accumulate
+from the previous frame.
+
+```js
+// import { progress } from "../../runtime/compose.js";
+export function createScene(root) {
+  const sheet = root.querySelector(".sheet");
+  return {
+    seek(t) {
+      const p = progress(t, 0.2, 0.9);
+      sheet.style.clipPath = `inset(${(1 - p) * 18}% 0 0 0)`;
+      sheet.style.transform = `translateY(${(1 - p) * 24}px)`;
+    },
+    dispose() {},
+    ready: Promise.resolve(),
+  };
+}
+```
+
+**Inspected evidence:** the pre-reveal frame, the 2 s settle frame, and a
+phone-width crop of the statement. The fixture was reviewed as stills; its sound
+was not synthesized or heard.
+
+**Failure mode:** a reveal under about half a second reads as a glitch, and a
+statement wider than its column measure loses the "uncovered page" reading.
+**Counterexample:** a formal institutional brand may need symmetry and a crest;
+the asymmetry would fight that identity.
+**Adaptation exercise:** move the same brief to late-night radio. Which
+mechanism survives (crop, hold, one statement), and what must change (type,
+colour, sound)?
+
+## Same brief, another concept
+
+For the reading-night brief, a second concept is a single overhead view of a long
+table with one lamp and one empty chair. The type is a small label on the table,
+not a poster; the camera holds, and the only movement is the lamp warming up.
+It answers a different viewer effect (intimacy, not discovery) and would use a
+slow hold with no crop reveal. Neither concept is universally better: the word
+"invitation" and the channel decide. If the client needs programme clarity, the
+poster concept wins; if the event sells atmosphere, the table concept wins. The
+two differ in composition and motion, not palette.
+
+## Example 2 — causality along a route
+
+**Brief:** explain how rain becomes drinking water in about 40 s for teenagers;
+calm voice; visually clear. Facts are supplied; no number may be invented.
+
+**Question:** how do you show a process without a four-step bullet list?
+
+**Rejected:** four labeled stages in equal cards. It is correct and forgettable:
+the viewer reads labels, not causality, and every stage has the same weight.
+
+**Chosen relationship:** three spatial zones (catchment, treatment, reservoir)
+connected by one route. The viewer follows water across the frame; labels
+confirm what the movement already showed.
+
+**Why motion serves meaning:** the path is the causal argument. A label arrives
+after the path reaches its zone, so the viewer sees the connection before
+naming it. A cut between stages would break the continuity the explanation
+depends on.
+
+**Native realization:** a `custom` scene with one SVG path. `getTotalLength`
+and `getPointAtLength` are deterministic; drive a marker and each zone's
+emphasis from one progress value.
+
+```js
+// import { ease, progress } from "../../runtime/compose.js";
+const route = root.querySelector("#route");
+const marker = root.querySelector("#marker");
+const length = route.getTotalLength();
+
+export function createScene() {
+  return {
+    seek(t) {
+      const p = ease("in-out", progress(t, 0.4, 4.2));
+      const point = route.getPointAtLength(p * length);
+      marker.setAttribute("transform", `translate(${point.x} ${point.y})`);
+    },
+    dispose() {},
+    ready: Promise.resolve(),
+  };
+}
+```
+
+**Inspected evidence:** the route midpoint, the first zone's label onset, and
+the final held frame. The fixture was reviewed as stills; no quantitative water
+claim and no audio-quality claim were made.
+
+**Failure mode:** labels that appear before the path arrives let the viewer read
+ahead and stop watching the mechanism; a path that moves too fast to track loses
+the same causality. **Counterexample:** a non-spatial process such as an
+approval workflow may need a timeline or state machine, not a map; forcing it
+onto a route would invent geography.
+**Adaptation exercise:** make a 9:16 version. Stack the zones vertically, keep
+the single route, and decide what the marker does at the crop boundary.
+
+## Example 3 — continuity is a decision, not a failure
+
+**Brief:** episode two of an approved library series. Episode one used the
+crop-reveal editorial system, a warm paper field and a mono label; the client
+wants the series to be recognisable.
+
+**Question:** how do you stay recognisably the same without repeating the first
+composition?
+
+**Chosen relationship:** preserve the identity axes (type scale, palette roles,
+crop-reveal grammar, end card) and change the episode's central relationship
+(a single poster becomes a schedule grid) and its shot order.
+
+**Rejected:** a new palette each episode (breaks recognition), and an identical
+board (the content no longer fits). Consistency is not a lack of ideas; it is a
+chosen constraint.
+
+**Why motion serves meaning:** the same reveal grammar signals "same series";
+the new subject gives the viewer a reason to watch again. The end card is the
+anchor, not a decorative repeat.
+
+**Native realization:** reuse the existing authored scene's grid and motion
+helpers; change the content layer and the relationship, not the identity tokens.
+If the series is a strict brand template, use the template deliberately and say
+so.
+
+**Inspected evidence:** compare fingerprints across narrative, layout, type,
+value/colour, motion, material, tempo and sound. Name which axes are identity
+and which are episode content.
+**Failure mode:** calling a palette swap "a new episode" while the composition
+repeats; or forcing novelty and losing the recognition the client asked for.
+**Counterexample:** a one-off campaign with no prior work should not invent
+continuity it does not have.
+**Adaptation exercise:** list the three axes you would keep for a third episode
+and the three you would change. Explain each in one sentence.
+
+## What these examples do not establish
+
+They are authored technical fixtures, not a measured quality benchmark. They do
+not prove that a weaker model will reproduce the reasoning, that a reviewer will
+prefer the result, or that the same decisions fit another brand. A precedent
+that only changes copy or colour has not answered its question.

package/skills/motion-kit/references/worked-example.md

@@ -0,0 +1,170 @@
+# Worked example: brief to an approved preview
+
+A complete direct-storyboard run. Copy the shape, not the words. The numbers below are the ones this board actually produced.
+
+## Brief
+
+- Topic: how a request reaches the data.
+- Audience: colleagues who know the basics.
+- Length: about 18 s. Aspect: 16:9.
+- Facts: client calls the API gateway; the gateway authenticates; the gateway queries the database; median response last quarter was 120 ms.
+- Route: direct storyboard. No blueprint matched the exact three-service path, and the board is short enough to write.
+
+## Outline (sent before building)
+
+```text
+Plan: How a request reaches the data
+Audience: colleagues who know the basics | Length: ~18 s | Aspect: 16:9
+Route: direct storyboard, theme default - the path is the point
+Scenes:
+1. title - the question
+2. flow - client, gateway, database
+3. caption - the gateway checks every request
+4. stat - 120 ms median
+5. outro - one public door
+Assumed: silent, no brand colours, numbers from the last quarterly report
+Go, or what should change?
+```
+
+## The board
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "title": "How a request reaches the data",
+    "width": 1920,
+    "height": 1080,
+    "fps": 30,
+    "theme": "default"
+  },
+  "scenes": [
+    {
+      "id": "intro",
+      "type": "title",
+      "duration": 4,
+      "move": "push-in",
+      "ease": "out",
+      "props": { "kicker": "Architecture", "title": "How a request reaches the data" }
+    },
+    {
+      "id": "path",
+      "type": "flow",
+      "duration": 6,
+      "move": "push-in",
+      "ease": "out",
+      "transition": "crossfade",
+      "props": {
+        "nodes": [
+          { "id": "client", "label": "Client" },
+          { "id": "api", "label": "API gateway" },
+          { "id": "db", "label": "Database" }
+        ],
+        "edges": [
+          { "from": "client", "to": "api", "label": "request" },
+          { "from": "api", "to": "db", "label": "query" }
+        ]
+      }
+    },
+    {
+      "id": "cap-path",
+      "type": "caption",
+      "layer": "overlay",
+      "over": "path",
+      "offset": 0.2,
+      "duration": 5.5,
+      "props": { "text": "The gateway checks every request." }
+    },
+    {
+      "id": "result",
+      "type": "stat",
+      "duration": 4,
+      "move": "push-in",
+      "ease": "out",
+      "transition": "crossfade",
+      "props": {
+        "value": 120,
+        "unit": "ms",
+        "label": "median response",
+        "context": "measured last quarter"
+      }
+    },
+    {
+      "id": "end",
+      "type": "outro",
+      "duration": 4,
+      "move": "push-in",
+      "ease": "out",
+      "transition": "crossfade",
+      "props": { "title": "One public door, checked every time" }
+    }
+  ]
+}
+```
+
+## Run it
+
+```bash
+mk validate storyboard.json
+# 0 errors, 0 warnings
+
+mk preview storyboard.json
+# preview ok | free storyboard | 4 scenes + 1 overlays 16.5s 1920x1080
+# pack out/storyboard.preview | contact.png 4 stills (+0 paired) clip 6.5s
+# est render ~1m (estimate) | lint 0 err 0 warn | approve: mk approve storyboard.json
+```
+
+Open `out/storyboard.preview/contact.png` and look at all four stills. Then ask. Only after an explicit yes:
+
+```bash
+mk approve storyboard.json --note "the user's exact words"
+mk render storyboard.json --gated --verify
+```
+
+The preview's 6.5 s clip caps each scene and is silent; the 16.5 s total includes three overlapping crossfades, so it is less than the 18 s sum. The final render is the only thing that proves the full duration, sound and motion. It was not run for this example; on a real task it is the step after the user's yes.
+
+## One feedback round
+
+Change the number:
+
+```json
+[{ "op": "replace", "path": "/scenes/3/props/value", "value": 95 }]
+```
+
+```bash
+mk patch storyboard.json --ops fixes.json
+# patch ok | 1 op | changed /scenes/3/props/value
+# scenes 5 | total 16.5s | 0 errors, 0 warnings
+```
+
+Add a closing rule:
+
+```bash
+mk scene add storyboard.json callout --after result --set text="[Fewer] hops, same answer" --duration 4
+# scene add ok | callout-1 (callout) at 5/6 | total 20.5s | 0 errors, 0 warnings
+```
+
+Bring it back to 20 s:
+
+```bash
+mk fit storyboard.json --seconds 20
+# fit ok | 20.5s -> 20s (target 20s) | 5 scenes | fallback range (no template pacing)
+```
+
+Every one of those edits re-arms approval. Preview again and ask again; do not reuse the old yes.
+
+## Ask in three lines
+
+```text
+Preview: 4 base scenes + 1 caption overlay, 16.5 s, silent, 16:9.
+Shown: contact.png and the 6.5 s clip. Not shown: voice, motion between stills, and scenes without a still.
+If this works, say "yes" and I will render; otherwise tell me which frame or line to change.
+```
+
+## What this example teaches
+
+- The base scenes carry the timeline; the caption overlay does not add duration.
+- `move` on every base scene keeps the film out of the flat-static lint.
+- The direct route needs no template, but it does need a theme that resolves (`default` here).
+- Preview is cheap and silent; render is the expensive, gated step.
+- A hash or a lint pass is not a quality review. The stills are.