@anvpx/motion 0.1.0 → 0.1.1

package/CATALOG.md

@@ -31,7 +31,7 @@ code | base | Code or terminal text typed or revealed line by line, with highlig
 kpi-grid | base | 2-6 headline numbers side by side, each with label, unit, change and trend arrow (good=down when a fall is good); values count up. | items
 chart | base | Animated bar, line or donut chart for ranking, trend or share, with values shown and an optional highlight. | kind
 table | base | Small data table or ranked list (2-5 columns, 2-8 rows) with row-by-row reveal and one optional highlighted row. | columns,rows
-scene3d | base | WebGL diorama (vendored three.js): post, light, material, environment presets; flat 2D canvas fallback without WebGL. 3D output is machine+GPU stable, not portable. | -
+scene3d | base | WebGL diorama (vendored three.js): post, light, material, environment presets; model presets knot|gem|sphere|torus; flat 2D canvas fallback without WebGL. 3D output is machine+GPU stable, not portable. | -
 sticker | base | Pop-comic sticker slam: 1-5 short phrases slam in with outline type, tilt and a starburst; for hooks, myth-vs-fact and punchy shorts. | words
 waveform | base | Audio waveform from precomputed peaks: bars rise as the playhead sweeps; for voice agents, podcasts and narrated reports. Peaks are storyboard data, never decoded audio. | peaks
 Detail: `mk catalog <type>`. Props are strict; unlisted keys are rejected.
@@ -275,7 +275,7 @@ props: {"title":"Top regions","columns":["Region","Revenue"],"rows":[["North","$
 ```
 
 ```
-scene3d (base): WebGL diorama (vendored three.js): post, light, material, environment presets; flat 2D canvas fallback without WebGL. 3D output is machine+GPU stable, not portable.
+scene3d (base): WebGL diorama (vendored three.js): post, light, material, environment presets; model presets knot|gem|sphere|torus; flat 2D canvas fallback without WebGL. 3D output is machine+GPU stable, not portable.
   title     text<=60
   caption   text<=140
   model     text

package/README.md

@@ -3,13 +3,13 @@
 **Storyboard JSON in, animated video out.** motion-kit turns a small, validated document into an explainer, infographic or social clip and renders it locally with HyperFrames. Free and open source: no metering, no watermark, no account, no cloud.
 
 ```
-brief ──► storyboard.json ──► validate ──► preview ──► approve ──► render --gated
-          (small, diffable)   (schema+lint)  (contact sheet, stills, clip)
+brief ──► direction ──► storyboard.json ──► validate ──► preview ──► approve ──► render --gated
+          (design)      (small, diffable)   (schema+lint)  (contact sheet, stills, clip)
 ```
 
 ## Why it is different
 
-- **The artifact is a document, not a program.** A storyboard is diffable, reviewable and patchable JSON, roughly 100–200 tokens per scene. Any LLM can write it; no React, no timeline code, no model output compiled into your video.
+- **A small production document with room for original design.** Storyboards are diffable, reviewable and patchable JSON. Use catalog components where they fit, or author deterministic HTML/CSS/JS scenes for original compositions through the same build and approval path.
 - **Deterministic by construction.** Every scene is a pure function of time (`seek(t)`): no frame-rate clock, no unseeded randomness. Same-machine drafts are byte-identical.
 - **A real approval gate.** `mk preview` writes a review pack, `mk approve` records the user's yes, and `mk render --gated` refuses with exit 4 until the recorded approval matches the current inputs. Any edit re-arms it.
 - **Local and offline.** Rendering, linting, contact sheets and voice run on your machine. Confidential decks stay on disk.
@@ -25,12 +25,13 @@ Optional voice needs Python 3.12 plus Kokoro/faster-whisper; `mk doctor` tells y
 ## Quickstart
 
 ```sh
-npx -y @anvpx/motion@0.1.0 doctor
+npx -y @anvpx/motion@0.1.1 doctor
 
 # Optional: make the rest shorter
-alias mk="npx -y @anvpx/motion@0.1.0"        # bash/zsh
-function mk { npx -y @anvpx/motion@0.1.0 @args }   # PowerShell
+alias mk="npx -y @anvpx/motion@0.1.1"        # bash/zsh
+function mk { npx -y @anvpx/motion@0.1.1 @args }   # PowerShell
 
+# Optional template-assisted example, after deciding the visual direction:
 mk template list --for "how our pricing works"
 mk new explain/architecture --demo --out storyboard.json   # --demo = example copy; --set k=v for yours
 mk validate storyboard.json
@@ -56,7 +57,7 @@ mk render storyboard.json --gated --verify
 
 ## How authoring works
 
-An agent picks the cheapest route that fits the brief: a template-assembled storyboard, a direct storyboard, or an authored custom scene when the catalog genuinely lacks the shot. The protocol lives in the skill (`skills/motion-kit/SKILL.md`) and in `docs/AGENT-WORKFLOW.md`. Users never write storyboards; the agent designs, shows a preview, and renders only after an explicit yes.
+The agent first develops a visual argument in an authoring-only `direction.md`: concept, composition, typography, color, motion, sound and intended divergence from relevant prior work. It loads focused craft guidance for unresolved decisions, then chooses template-assisted, direct or authored realization by fit. Templates help repeat a brand system; authored scenes can carry the whole film when the brief calls for it. There is no template-exhaustion requirement or custom-scene quota. The protocol lives in the skill (`skills/motion-kit/SKILL.md`) and in `docs/AGENT-WORKFLOW.md`. Users never write storyboards; the agent designs, shows a preview, and renders only after an explicit yes.
 
 Claude Code users can install the bundled plugin with `mk plugin install`.
 
@@ -81,7 +82,8 @@ mk preview  →  user reviews contact.png / stills / clip  →  mk approve  →
 
 ```sh
 pnpm install
-pnpm build      # tsc -b plus staged runtime assets
+pnpm build      # tsc -b, runtime assets, generated package payloads
+pnpm scaffold:check  # fail if a generated copy drifted from its source
 pnpm check      # typecheck + lint
 pnpm test       # unit tests
 pnpm test:integration   # needs Chrome

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anvpx/motion",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Storyboard JSON to animated video, rendered locally with HyperFrames: the mk CLI plus the full pipeline.",
   "license": "MIT",
   "author": "anvpx",
@@ -55,14 +55,14 @@
     "@fontsource/jetbrains-mono": "5.3.0",
     "@fontsource/source-serif-4": "5.3.1",
     "@fontsource/space-grotesk": "5.3.0",
-    "@anvpx/motion-assets": "0.1.0",
-    "@anvpx/motion-audio": "0.1.0",
-    "@anvpx/motion-build": "0.1.0",
-    "@anvpx/motion-cli": "0.1.0",
-    "@anvpx/motion-scenes": "0.1.0",
-    "@anvpx/motion-schema": "0.1.0",
-    "@anvpx/motion-templates": "0.1.0",
-    "@anvpx/motion-themes": "0.1.0",
+    "@anvpx/motion-assets": "0.1.1",
+    "@anvpx/motion-audio": "0.1.1",
+    "@anvpx/motion-build": "0.1.1",
+    "@anvpx/motion-cli": "0.1.1",
+    "@anvpx/motion-scenes": "0.1.1",
+    "@anvpx/motion-schema": "0.1.1",
+    "@anvpx/motion-templates": "0.1.1",
+    "@anvpx/motion-themes": "0.1.1",
     "hyperframes": "0.8.212",
     "postprocessing": "6.39.5",
     "three": "0.186.0",

package/plugins/motion-kit/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "description": "Brief-to-approved video via the pinned motion-kit CLI: storyboard, preview, gated render.",
   "name": "motion-kit",
-  "version": "0.1.0"
+  "version": "0.1.1"
 }

package/plugins/motion-kit/README.md

@@ -2,23 +2,31 @@
 
 Plugin root: `plugins/motion-kit/` (chosen over a top-level `motion-kit-plugin/`
 folder name used by the plugin packaging convention;
-`npx -y @anvpx/motion@0.1.0 plugin install` copies this exact folder).
+`npx -y @anvpx/motion@0.1.1 plugin install` copies this exact folder).
 
 ## Layout
 
 - `.claude-plugin/plugin.json` — manifest (`name`, `version`, `description` only;
   version tracks `@anvpx/motion`).
 - `commands/mk-new.md`, `mk-draft.md`, `mk-render.md` — thin wrappers. Every step
-  calls `npx -y @anvpx/motion@0.1.0` (pinned; never unpinned `npx`).
+  calls `npx -y @anvpx/motion@0.1.1` (pinned; never unpinned `npx`).
   Surface as `/motion-kit:mk-new`, `/motion-kit:mk-draft`, `/motion-kit:mk-render`.
-- `skills/motion-kit/SKILL.md` — byte-identical copy of `skills/motion-kit/SKILL.md`.
-- `skills/motion-kit/references/` — the same lazy references, so every
-  `references/*.md` link in the skill resolves after install.
+- `skills/motion-kit/SKILL.md` — generated from the canonical skill by the
+  scaffold; do not edit it here.
+- `skills/motion-kit/references/` — generated from the canonical reference set,
+  so every `references/*.md` link resolves after install.
+
+## Source ownership
+
+The plugin's `.claude-plugin/`, `commands/` and this README are hand-maintained.
+The `skills/motion-kit/` tree is generated. Edit the canonical skill and run
+`pnpm scaffold`; `pnpm scaffold:check` fails on drift. The same scaffold
+generates the core package's `skills/` and `plugins/` trees.
 
 ## Install
 
 ```bash
-npx -y @anvpx/motion@0.1.0 plugin install --out ./motion-kit-plugin
+npx -y @anvpx/motion@0.1.1 plugin install --out ./motion-kit-plugin
 ```
 
 Verifies `skills/motion-kit/SKILL.md` sha256 matches after copy.

package/plugins/motion-kit/commands/mk-draft.md

@@ -5,8 +5,8 @@ description: Preview a motion-kit storyboard (stills, contact sheet, draft clip)
 Run the pinned CLI for every step; never use an unpinned invocation.
 
 ```bash
-npx -y @anvpx/motion@0.1.0 preview storyboard.json
-npx -y @anvpx/motion@0.1.0 approve storyboard.json --note "<user words>"
+npx -y @anvpx/motion@0.1.1 preview storyboard.json
+npx -y @anvpx/motion@0.1.1 approve storyboard.json --note "<user words>"
 ```
 
 Follow `skills/motion-kit/SKILL.md` stages 7-8 (preview, show + approve).

package/plugins/motion-kit/commands/mk-new.md

@@ -5,10 +5,10 @@ description: Start a motion-kit video (intake, brief, template pick, storyboard)
 Run the pinned CLI for every step; never use an unpinned invocation.
 
 ```bash
-npx -y @anvpx/motion@0.1.0 template list --for "<one-line brief>"
-npx -y @anvpx/motion@0.1.0 template show <template>/<blueprint>
-npx -y @anvpx/motion@0.1.0 new <template>/<blueprint> --set k=v ... --out storyboard.json
-npx -y @anvpx/motion@0.1.0 validate storyboard.json
+npx -y @anvpx/motion@0.1.1 template list --for "<one-line brief>"
+npx -y @anvpx/motion@0.1.1 template show <template>/<blueprint>
+npx -y @anvpx/motion@0.1.1 new <template>/<blueprint> --set k=v ... --out storyboard.json
+npx -y @anvpx/motion@0.1.1 validate storyboard.json
 ```
 
 Follow `skills/motion-kit/SKILL.md` stages 1-6 (intake, brief, pick template,

package/plugins/motion-kit/commands/mk-render.md

@@ -5,8 +5,8 @@ description: Gated render of an approved motion-kit storyboard with verify
 Run the pinned CLI for every step; never use an unpinned invocation.
 
 ```bash
-npx -y @anvpx/motion@0.1.0 render storyboard.json --gated --verify
-npx -y @anvpx/motion@0.1.0 verify out/final.mp4 --storyboard storyboard.json
+npx -y @anvpx/motion@0.1.1 render storyboard.json --gated --verify
+npx -y @anvpx/motion@0.1.1 verify out/final.mp4 --storyboard storyboard.json
 ```
 
 Follow `skills/motion-kit/SKILL.md` stages 9-10 (patch, render). Exit 4 means

package/plugins/motion-kit/skills/motion-kit/SKILL.md

@@ -6,27 +6,31 @@ allowed-tools: Bash(mk:*) Bash(npx:*) Read Write
 
 # motion-kit: brief -> preview -> approved video
 
-`mk` = `npx -y @anvpx/motion@0.1.0`; alias it once per shell, or use the npx prefix in its place. The user describes the outcome; you author one storyboard JSON, show a short preview, and render only after an explicit yes.
+`mk` = `npx -y @anvpx/motion@0.1.1`; alias it once per shell, or use the npx prefix in its place. The user describes the outcome; you author one storyboard JSON, show a short preview, and render only after an explicit yes.
 
 ## Start here
 
 1. `mk doctor` once; optional voice rows may be missing, required rows are not.
-2. Ask <=3 questions (audience, length, must-have); default the rest (`references/intake.md`).
-3. `brief.md`: <= 8 facts, every number sourced, then the content pack (`references/content-pack.md`); send a <= 200-word outline and wait for "go" (`references/outline.md`).
+2. Extract supplied facts and constraints; ask only material gaps (max 3, with defaults). A complete brief is not a questionnaire (`references/intake.md`).
+3. `brief.md`: <= 8 facts, every number sourced. Design `direction.md` before choosing scenes (`references/direction.md`); resolve one craft question at a time (`references/knowledge-routing.md`). Send a <= 200-word outline and wait for "go" (`references/outline.md`).
 4. Pick a route (below), instantiate, then `mk validate` until 0 errors. If `meta.theme` is not built-in (`default`, `dark`, `tech-dark`, `calm-dark`) and `themes/<name>.json` is absent, preview before calling this done. Storyboard-only request: stop here.
 5. `mk preview`; open the printed `pack .../contact.png`; ask. On yes only: `mk approve ...`, then `mk render ... --gated --verify`.
 
 ## Read when
 
-| File                              | Read when                                                      |
+| File | Read when |
 | --------------------------------- | -------------------------------------------------------------- |
-| `references/worked-example.md`    | first build; the complete loop and output shapes               |
-| `references/free-storyboard.md`   | direct route: shape and write the board                        |
-| `references/storyboard-json.md`   | field shapes, overlays, assets, or decoding a validation error |
-| `references/scene-recipes.md`     | choose a type for a beat and copy its prop shape               |
-| `references/patching.md`          | any edit after the first write, or a patch flag refusal        |
-| `references/quality-bar.md`       | judging the preview and what to say before asking              |
-| `references/common-mistakes.md`   | a command refuses, or a flag or field is in doubt              |
+| `references/direction.md` | invent the visual argument before choosing a realization route |
+| `references/knowledge-routing.md` | one unresolved craft or technical decision; lazy craft-card index |
+| `references/content-pack.md` | organize creative intent, beats, asset rights, audio and sourced facts |
+| `references/themes.md` | theme or 3D look |
+| `references/worked-example.md` | first build; the complete loop and output shapes |
+| `references/free-storyboard.md` | direct route: shape and write the board |
+| `references/storyboard-json.md` | field shapes, overlays, assets, or decoding a validation error |
+| `references/scene-recipes.md` | choose a type for a beat and copy its prop shape |
+| `references/patching.md` | any edit after the first write, or a patch flag refusal |
+| `references/quality-bar.md` | judging the preview and what to say before asking |
+| `references/common-mistakes.md` | a command refuses, or a flag or field is in doubt |
 
 ## Rules
 
@@ -40,38 +44,38 @@ allowed-tools: Bash(mk:*) Bash(npx:*) Read Write
 
 ## Stages
 
-| #   | Stage          | Do                                                                                                                                                                                               | Done when                 |
+| # | Stage | Do | Done when |
 | --- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
-| 1   | Intake         | topic, audience, length, channel, brand, tone; max 3 questions (`references/intake.md`)                                                                                                          | 5-line note               |
-| 2   | Brief          | <= 8 facts, <= 3 sourced numbers, one arc; `brief.md`                                                                                                                                            | numbers sourced           |
-| 3   | Route          | `mk template list --for`; `mk template show` once each, max 2; `references/scene-recipes.md` for beat shapes. The ranker is keyword overlap, so read the description and not-for line; name route + reason | route chosen              |
-| 4   | Outline        | <= 200 words (`references/outline.md`); stop for "go" unless "just do it"                                                                                                                        | user confirms             |
-| 5   | Instantiate    | template: `mk new <t>/<bp> ...`; direct: `references/free-storyboard.md`; authored: `mk scene new` (`references/authoring-scene.md`); assets: `mk assets import` + `--assets`/`--ledger`                     | 0 errors; build exit 0    |
-| 6   | Fix            | smallest `mk patch`; max 3 rounds; same error twice: `mk catalog <type>` + `references/troubleshooting.md`; unknown theme: built-in or `themes/<name>.json`                                        | 0 errors, warnings read   |
-| 7   | Preview        | `mk preview` (<= 90 s; add `--assets d --ledger f` when used); read stdout + `preview.json`; `references/quality-bar.md`                                                                          | pack exists               |
-| 8   | Show + approve | contact + clip + 3-line summary + derived coverage; ask. On yes: `mk approve ... --note "<their words>"` (repeat the preview's `--out`/assets/audio flags)                                  | explicit yes recorded     |
-| 9   | Patch          | smallest change; back to 6-7; max 3 rounds, then offer options                                                                                                                                   | approval matches file     |
-| 10  | Render         | mp4: `mk render ... --gated --verify`; webm/mov/gif/png-sequence: `--format ... --gated`, omit `--verify` (mp4-only); add `--assets`/`--ledger`, `--resolution`, `--fps`                            | mp4: verify 0; other: output exists |
+| 1 | Intake | topic, audience, length, channel, brand, tone; max 3 questions (`references/intake.md`) | 5-line note |
+| 2 | Brief | <= 8 facts, <= 3 sourced numbers, one arc; `brief.md` | numbers sourced |
+| 3 | Direction | `references/direction.md`: concept, composition, type, motion, sound and divergence; then choose realization. Template lookup is optional, after design | direction + route justified |
+| 4 | Outline | <= 200 words (`references/outline.md`); stop for "go" unless "just do it" | user confirms |
+| 5 | Instantiate | template: `mk new <t>/<bp> ...`; direct: `references/free-storyboard.md`; authored: `mk scene new` (`references/authoring-scene.md`); assets: `mk assets import` + `--assets`/`--ledger` | 0 errors; build exit 0 |
+| 6 | Fix | smallest `mk patch`; max 3 rounds; same error twice: `mk catalog <type>` + `references/troubleshooting.md`; unknown theme: built-in or `themes/<name>.json` | 0 errors, warnings read |
+| 7 | Preview | `mk preview` (<= 90 s; add `--assets d --ledger f` when used); read stdout + `preview.json`; `references/quality-bar.md` | pack exists |
+| 8 | Show + approve | contact + clip + 3-line summary + derived coverage; ask. On yes: `mk approve ... --note "<their words>"` (repeat the preview's `--out`/assets/audio flags) | explicit yes recorded |
+| 9 | Patch | smallest change; back to 6-7; max 3 rounds, then offer options | approval matches file |
+| 10 | Render | mp4: `mk render ... --gated --verify`; webm/mov/gif/png-sequence: `--format ... --gated`, omit `--verify` (mp4-only); add `--assets`/`--ledger`, `--resolution`, `--fps` | mp4: verify 0; other: output exists |
 
 ## Choosing a route
 
-Template-assisted (`mk template list` -> `mk new`), direct storyboard (`references/free-storyboard.md`) and authored scene (`mk scene new`) are co-equal starts; pick by fit, not exhaustion. Use direct when the brief is clearer as JSON than any blueprint; use authored when the visual needs code. There is no per-video cap; an authored scene costs 1-3k tokens against ~120 for a catalog type. Never stretch a wrong blueprint, truncate a required fact to fit a slot, or refuse an authored scene. Name the route.
+Design first, then choose template (`mk template list` -> `mk new`), direct (`references/free-storyboard.md`) or authored (`mk scene new`, `references/authoring-scene.md`) by fit. Templates help repeat a brand system; direct boards compose catalog components; authored scenes create original layouts and motion. Mix routes when useful. No per-video cap or template-exhaustion prerequisite. The catalog defines supported props, not the visual idea. Name the route and its limitations.
 
 ## How long should it be
 
-Use the user's length, else 45 s. Seconds: title 3-5, stat 4-6, bullets/flow 6-11, outro 3-5. `mk fit --seconds N` moves a board only about 1.4x; 25 s to 50 s needs more scenes first (`mk scene add`, about one per 7 s), then fit.
+Use the user's length, else propose 45 s. Budget orientation, meaningful change and readable rest against real copy/narration; scene count follows the argument. `mk fit --seconds N` adjusts timing, not narrative depth. Add or reshape beats with `mk scene add` when stretching would create dead time.
 
-## Voice and captions (opt-in)
+## Voice, music and captions (opt-in)
 
-`mk voice` -> `mk captions` -> `mk patch --ops`; the same `--audio` goes to preview, approve and render. Setup and failure paths: `references/voice.md`.
+`mk voice` -> `mk captions` -> `mk patch --ops`; same `--audio` for preview, approve and render. Write numbers as words (`01` -> "zero one"). Music is opt-in; use `music/bed-full.wav`, not the silent `music/bed.wav`. Details: `references/voice.md`.
 
 ## Failures
 
-| Symptom          | Do                                                                  |
+| Symptom | Do |
 | ---------------- | ------------------------------------------------------------------- |
-| exit 4           | not an error: stage 8                                               |
-| exit 5           | fix the named scene, re-render once, then report                    |
-| same error twice | stop patching; `mk catalog <type>` and rewrite that scene           |
-| anything else    | `references/common-mistakes.md`, then `references/troubleshooting.md` |
+| exit 4 | not an error: stage 8 |
+| exit 5 | fix the named scene, re-render once, then report |
+| same error twice | stop patching; `mk catalog <type>` and rewrite that scene |
+| anything else | `references/common-mistakes.md`, then `references/troubleshooting.md` |
 
-Done = the approval hash matches the rendered board, `mk verify` exit 0 is quoted, and you state what was not verified.
+Done = approval hash matches, `mk verify` exit 0 is quoted, and unverified parts are named.

package/plugins/motion-kit/skills/motion-kit/references/authoring-scene.md

@@ -1,12 +1,12 @@
 # Authoring a scene (type: custom)
 
-A co-equal route, chosen when the visual the brief needs is not in the catalog and code expresses it more directly than a stack of catalog types. There is no per-video cap. The real costs, measured where available: ~1-3k tokens per authored scene against ~120 for a catalog type, no incremental cache (the cache key does not cover authored bytes), and review of the emitted files. Use it when the brief earns it; never to avoid learning a type.
+A first-class route for original composition and motion. Start from the visual argument in `direction.md`, then use code when it expresses that idea well. There is no per-video cap or requirement to exhaust catalog/template options. Native and authored scenes can share a storyboard. Review the emitted files and test deterministic seek; do not promise a supported mechanism until its actual contract is checked.
 
 ## Files
 
 `scenes/<name>/scene.js` (exports `createScene`), `fragment.html` (no `<script>`, no `on*=`), `style.css` (optional; `#scene-root` is rewritten). The scaffold also writes `notes.md`; that is documentation, not part of the picture. These three code files are the only place HTML/CSS/JS is authored; storyboard props, template slots and pack instructions stay data.
 
-The scaffold's `scene.js` imports `../../runtime/mount.js` and calls `mountTimeline`; the build supplies that runtime. Keep the import and the exported `createScene` signature; replace the body, the fragment and the CSS with your scene. Do not copy runtime code into the scene.
+The scaffold's `scene.js` imports `../../runtime/compose.js`; the build supplies that runtime. Replace its markup, CSS and motion with the direction's original composition while keeping the exported `createScene` contract. The starter demonstrates time-driven state, not a required title layout. Older scenes using `../../runtime/mount.js` and `mountTimeline` remain supported. Do not copy runtime implementations into the scene.
 
 A relative helper such as `./lib/format.js` is part of the scene: it must stay inside the scene directory (no `../`, no absolute or remote path), and it is emitted beside `scene.js`, linted with the scene and included in the approval hash. A helper-only edit re-arms the gate like any other scene edit.
 
@@ -18,6 +18,17 @@ Entry: `{ "type": "custom", "props": { "dir": "scenes/hero" } }`
 
 `createScene(root, config, ctx)` → `{ seek(t), dispose(), ready }`. `seek(t)` is a pure function of t. Start from `mk scene new hero`.
 
+## Small motion vocabulary, open composition
+
+Import only the helpers you use from `../../runtime/compose.js`:
+
+- `progress(t, start, duration)`: clamped 0..1; duration zero makes a cut at `t >= start`. Inputs must be finite, duration nonnegative.
+- `interpolate(from, to, amount)`: numeric interpolation; an eased amount may overshoot.
+- `stagger(index, step, start = 0)`: onset for a nonnegative integer index; a negative step reverses order.
+- `ease(name, amount)` and `clamp01(amount)`: existing easing vocabulary (`linear`, `in`, `out`, `in-out`, `spring-soft`, `spring-snappy`).
+
+Example: `const p = ease('out', progress(t, 0, 0.8));` then set an element's opacity and transform from `p` on every seek. The time values are illustrative, not pacing rules. Author your own layers, grids, masks, type lockups and relationships in HTML/CSS/JS; helpers impose no layout or visual style. Assign every animated property before onset, during action and after settle; never accumulate deltas from a prior seek. Initialize the scene state and release listeners/resources or temporary styles in `dispose`.
+
 ## Fails lint
 
 clocks (`Date.now`, `performance.now`, `new Date()`) · timers · `requestAnimationFrame` · `Math.random` · network/workers · `window.` · CSS `animation`/`transition`/`@keyframes`
@@ -26,7 +37,7 @@ A CSS animation runs on the browser clock, not `seek(t)`.
 
 ## Draw with tokens
 
-`var(--mk-color-bg)`, `var(--mk-color-fg)`, `var(--mk-color-accent)`, `var(--mk-font-*)`. Hard hexes break on a theme switch. The 5 % safe margin is already applied.
+`var(--mk-color-bg)`, `var(--mk-color-fg)`, `var(--mk-color-accent)`, `var(--mk-font-*)`. Theme tokens support consistent art direction; authored geometry and motion remain yours. Hard hexes need deliberate theme-switch review. Inspect actual safe margins and delivery crop in preview rather than assuming a decorative full-bleed element makes text safe.
 
 ## Loop
 
@@ -34,4 +45,4 @@ A CSS animation runs on the browser clock, not `seek(t)`.
 
 ## Self-check
 
-Same t, same pixels? Theme switch safe? Fits 9:16? Would a catalog type do this with less code?
+Seek A -> B -> A and compare state/pixels. Then seek in reverse order and outside the action interval. Theme switch safe? Fits the intended aspect, longest copy and busiest beat? Does the composition realize the direction? Could shared helpers reduce repeated mechanics without fixing the design? Static proof does not establish motion or sound quality.

package/plugins/motion-kit/skills/motion-kit/references/authoring-style.md

@@ -1,10 +1,12 @@
-# Authoring a style (theme)
+# Authoring theme tokens within a direction
+
+A theme supplies palette/font tokens, not the whole visual system. Design composition, typography behavior, motion and sound in `direction.md`; use `craft-color.md` and `craft-type.md` for those decisions. A recolor of the same layout is useful brand adaptation, but is not by itself a new art direction.
 
 A theme is DTCG JSON. Copy the nearest vendored family from `shared/themes/` inside the installed `@anvpx/motion` package and change values only — renaming tokens breaks scenes.
 
 ## Tokens that matter
 
-`color.bg` and `color.bgEnd` (the page gradient; keep them close), `color.fg`, `color.accent` and `color.accent2` (once per scene), `color.card`, `color.divider`, `color.glow`, `font.sans`, `font.mono`, `radius`.
+`color.bg` and `color.bgEnd` (the page gradient), `color.fg`, `color.accent`, `color.accent2`, `color.card`, `color.divider`, `color.glow`, `font.sans`, `font.mono`, `radius`. Assign roles from the direction and check contrast over every actual background state; token names do not require a gradient, glow or card motif in an authored composition.
 
 ## Enforced by the build
 
@@ -12,6 +14,6 @@ A theme is DTCG JSON. Copy the nearest vendored family from `shared/themes/` ins
 - Colour tokens reject `url()`, `var()` and `calc()` — values are literals.
 - Fonts must be one of the bundled families; never a CDN.
 
-## Taste
+## Check the system
 
-One accent, one easing family, one type scale. A theme is a constraint: if two colours compete, the scene has no accent.
+Keep hierarchy and semantic roles coherent. One accent or type family can be a strong choice; multiple categories or contrasting roles may need more. State the reason, then preview representative frames at delivery size. Native scene compositions stay fixed unless their props expose controls; use the authored route for original geometry and behavior. Preview, approve and render must resolve the same vendored theme bytes.

package/plugins/motion-kit/skills/motion-kit/references/common-mistakes.md

@@ -49,7 +49,7 @@ These are the failures that waste the most time. Each row is wrong -> right -> w
 | `mk assets import logo.png --dir assets`                      | Add `--licence MIT --source-url <url>`                                                         | Every imported asset needs provenance                                 |
 | `mk voice` on a machine with no venv                          | `mk doctor`; install Python 3.12 + the voice extras, or ship silent                            | Voice is opt-in and fails closed                                      |
 | `mk patch` path into a missing parent                         | Add the parent first, or target an existing path                                               | Patch stops at the first op that cannot apply                         |
-| `npx -y @anvpx/motion@0.1.0` returns 404                      | stop: the pinned package is unpublished; use a local checkout/tarball only if the user has one | no working bootstrap exists until release                             |
+| `npx -y @anvpx/motion@0.1.1` returns 404                      | stop: the pinned package is unpublished; use a local checkout/tarball only if the user has one | no working bootstrap exists until release                             |
 
 ## Windows
 

package/plugins/motion-kit/skills/motion-kit/references/content-pack.md

@@ -1,81 +1,69 @@
-# Content pack (before any storyboard)
-
-No storyboard until every item below is sourced or marked "placeholder".
-The pack is five lists; detail them with the user, then build.
-
-## 1. Style (Style choice, not fact)
-
-Name the look in 8 words or less (e.g. "dark tech keynote"),
-plus 3 numbered rules and 3 banned template-look items
-(no glow, no decor gradients, no bounce-everything).
-Name the route you chose (template-assisted, direct storyboard or authored scene).
-When style is a real choice, name one non-default style + why,
-and one alternative. Packs are optional guidance only:
-read the pack index lazily (`packs/INDEX.md` beside the installed CLI), never inline a pack,
-
-## Style menu (after lanshu, MIT; looks only, engines never)
-
-Twelve looks with native mappings; write and voice the narration to
-fit the chosen look. No native scene exists for pen writing, paper
-folds, comic stickers, chalk, or clay — those rows say closest.
-
-| Look            | Native mapping                    | Best for                     | Arc (look plus way of telling) |
-| --------------- | --------------------------------- | ---------------------------- | ------------------------------ |
-| Editorial paper | calm-light title flow callout     | serious, premium, business   | claim, proof, consequence      |
-| Tech HUD        | dark flow stat                    | AI, infra, systems           | problem, mechanism, result     |
-| Notebook        | closest: steps plus callout       | step-by-step teaching        | numbered steps, then a recap   |
-| Paper pop-up    | closest: media-frame layers       | warm stories, processes      | before, the turn, after        |
-| Pop comic       | closest: kinetic slam             | punchy shorts, myth vs fact  | myth, correction, slam         |
-| Cinematic 3D    | scene3d one-take                  | flagship, launches           | reveal, orbit, resolve         |
-| Drafting sheet  | dark flow plus footnote callout   | technical deep dives         | spec, derivation, check        |
-| Chalkboard      | closest: kinetic plus recap outro | beginners, memory recaps     | question, example, rule        |
-| Clay town       | closest: scene3d diorama          | analogies for non-experts    | analogy, walkthrough, takeaway |
-| Derivation      | flow built step by step           | principles, algorithms       | given, transform, result       |
-| Casefile        | timeline plus callout evidence    | post-mortems, incidents      | incident, evidence, finding    |
-| Sitcom          | kinetic plus lower-third          | abstract terms for newcomers | setup, confusion, resolution   |
-
-The arc column is a beat order, not a formula: it suggests how to sequence
-the scenes, and the storyboard still has to earn the result on the contact
-sheet. No measured quality claim is attached to any row. Never persist pack
-refs in storyboards.
-
-## 2. Patterns (from the CLI, never from memory)
-
-Scene and overlay picks come from `mk catalog` output only.
-One new visual idea per scene; a hook in the first second;
-karaoke captions (`caption` overlay) on every narrated scene,
-words taken from the voice manifest shifted to scene-relative times.
-Name unsupported effects instead of promising them.
-
-## 3. UI (vendored pixels only)
-
-Screenshots and images live inside the project (remote refs fail
-closed at preview). Import each file instead of hand-writing the ledger:
+# Content pack: evidence and creative intent
+
+Before a storyboard, separate facts from design choices. Keep five short lists;
+source claims and assets or mark them "placeholder". Develop the direction
+yourself using the brief; ask only questions that change it, within intake's
+three-question limit.
+
+## 1. Direction (a design choice, not a fact)
+
+Use `direction.md` to invent a visual argument and record composition, type,
+color/material, motion and sound choices with reasons. Explore an alternative
+whose visual mechanism is meaningfully different. A look name is a useful label
+after these decisions, not a menu to choose from. Describe what differs from
+available recent work and what deliberately stays consistent.
+
+Teach yourself the next missing decision through `knowledge-routing.md`.
+Templates, patterns and qualified packs are optional references. Borrow a
+principle when useful; build an original system when the brief calls for it.
+Choose template/direct/authored realization after direction. No finished style
+list defines the creative space.
+
+## 2. Beats (meaning before components)
+
+For each beat, write the message, what changes on screen and why the next beat
+follows. Give attention a clear subject; introduce information at a readable
+pace. A hook can be a question, surprising relationship or sustained observation,
+not necessarily a loud first-second effect.
+
+Then map to supported components using `mk catalog`, or to original authored
+HTML/CSS/JS through `authoring-scene.md`. Catalog layouts are components, not a
+mandatory scene sequence. Choose caption treatment for reading conditions;
+caption words/timing come from the voice manifest, shifted to scene-relative
+times. Name unsupported mechanisms and investigate instead of promising them.
+
+## 3. Assets and UI (local files with rights)
+
+Screenshots and images live inside the project; remote references fail closed
+at preview. Import each file rather than hand-writing the ledger:
 
 ```bash
 mk assets import src/dashboard.png --dir assets --ledger assets.json --licence CC0-1.0 --source-url <url>
 ```
 
-The row is `path`, `sourceUrl`, `licence`, `attribution`, `sha256`; the
-prop points at the file relative to `--assets` (`"image": "dashboard.png"`).
-The ledger is the file you passed; if `--ledger` is omitted it defaults to
-`<dir>/assets.json`. Preview, approve and render repeat the same
-`--assets d --ledger f`.
-No screenshot and none available: rebuild the screen by hand per
-`references/faux-ui.md` (faux-UI rules after stageshow).
-
-## 4. Sounds (approved words, licensed bed)
-
-Voice: one voice id + narration text per base scene, user-approved;
-narration sets scene durations, so words are final before voice.
-Narration is the clock: the evidence is an ASR round-trip of the final
-audio against that script, not a listen-through; fix a mismatch before
-any scene timing is set.
-Bed: one wav + license file + volume; a scored bed matches the
-timeline length so nothing loops audibly. Same `--audio`, `--music`,
-`--music-volume`, `--music-license` on preview, approve and render.
+Use the actual license and source. The row contains `path`, `sourceUrl`,
+`licence`, `attribution`, `sha256`; props reference files relative to
+`--assets` (`"image": "dashboard.png"`). The ledger defaults to
+`<dir>/assets.json` when `--ledger` is omitted. Preview, approve and render
+repeat the same `--assets d --ledger f`. With no usable screenshot, build
+truthful faux UI per `faux-ui.md`; do not imply it is a real product capture.
+
+## 4. Sound (intent, then verified audio)
+
+Choose silence, narration, music and effects for their narrative roles
+(`craft-sound.md`); none is mandatory. For voice, record voice id and approved
+script per base scene before synthesis. Check final audio against that script;
+ASR is useful mismatch evidence, listening checks pronunciation and intent.
+Neither proves the other. Time picture/captions against the actual waveform.
+
+For a bed, record local file, actual license, intended level and edit/loop plan.
+Repeat the same `--audio`, `--music`, `--music-volume`,
+`--music-license` on audible preview, approve and render. Use supported CLI
+flags only; a sound-design plan does not add new effect/mix controls.
+See `voice.md` for the concrete audio contract.
 
 ## 5. Facts (sourced or placeholder)
 
-At most 8 facts and 3 numbers, each with a source. Anything missing
-is written "placeholder" in the outline, never invented.
+At most eight facts and three numbers, with units and sources. Missing information
+stays "placeholder" in the outline. Style preferences are not evidence for factual
+claims, and an attractive composition cannot repair an unsupported number.