@anvpx/motion 0.1.0 → 0.1.1

package/plugins/motion-kit/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/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/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/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/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/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.

package/skills/motion-kit/references/craft-color.md

@@ -0,0 +1,50 @@
+# Craft card: color, light and material
+
+Load when a theme recolor is being mistaken for a new art direction, accents
+compete or texture obscures evidence. Color choices must serve a relationship.
+
+## Start with values and roles
+
+Describe the frame in light/dark masses before choosing hue. Establish the field,
+primary subject, supporting information and signal color. Give accents semantic
+jobs; a shared color can connect evidence across shots. Test without color so a
+distinction does not depend only on hue. Several accents may be useful when the
+data needs categories; justify and label them instead of enforcing one accent
+as an aesthetic law. Inspect contrast over the actual background, including its
+brightest and darkest moving regions.
+
+Example: a warm signal moving through a cool network marks causality. Recoloring
+every node on every shot erases that meaning. Next action: label each color's
+job; remove or merge roles the viewer cannot explain.
+
+## Write a color and light arc
+
+Sketch the opening, turning point and ending as simple value/color fields.
+Keep continuity where the argument continues; change the field when a shift
+has meaning. Light can isolate form, reveal surface or connect spaces. Choose
+direction, contrast and softness for that purpose; naming a cinematic light does
+not create renderer support. Map to actual catalog/custom capabilities and test.
+Flat graphic work can have a strong light/value structure without simulating 3D.
+
+Example: evidence gradually occupies a quiet field until the final relationship
+is visible. A dramatic dark-to-light change is one possible argument, not an
+ending every film should repeat. Compare those three frames without copy.
+
+## Treat texture as material, not repair
+
+Choose paper, grain, glass, metal, a clean field or another surface because it
+supports subject and tone. Test at final scale and during motion; fine texture
+can shimmer or interfere with type. Add surface only after hierarchy works.
+Record rights/provenance for actual texture assets; a descriptive reference is
+not permission to ship its pixels. A theme sets tokens; original composition,
+light and material behavior belong in native or authored scene realization.
+
+## Applicability, counterexample and provenance
+
+Contrast and non-color cues draw on
+[WCAG 2.2](https://www.w3.org/TR/WCAG22/), verified 2026-11-06.
+The value-script, light and material procedure is motion-kit craft synthesis,
+not a licensed visual-style collection or tested quality guarantee. An ambient
+art film may intentionally soften subject/background separation; essential
+information still needs a readable presentation. Check: grayscale hierarchy,
+actual motion, phone-width text and the intended narrative color relationship.