@anvpx/motion 0.0.0-stage → 0.1.1

package/packs/painted/pack.json

@@ -0,0 +1,46 @@
+{
+  "atomRefs": [],
+  "budgets": {
+    "guideBytes": 12000,
+    "profile": "utf8-bytes",
+    "reviewBytes": 6000,
+    "summaryBytes": 1200,
+    "voiceBytes": 6000
+  },
+  "compatibleScenes": ["bullets", "callout", "flow", "steps", "timeline", "title"],
+  "freedom": [
+    {
+      "id": "staging-density",
+      "instruction": "Choose sparse single-idea staging or layered staging with protected focus: justify which the brief needs and name what you left out."
+    },
+    {
+      "id": "accent-restraint",
+      "instruction": "Pick one small conceptual accent per film (warm red, ochre, or blue): justify its single job and keep every other mark in sketch greys."
+    }
+  ],
+  "guide": "look.md",
+  "id": "painted",
+  "qualification": { "review": "review.md", "status": "qualified" },
+  "register": ["calm", "warm"],
+  "review": "checklist.md",
+  "summary": "Warm hand-painted explainer vocabulary in three current-only media reads (watercolour, oil, dry-ink): staged reveals, persistent shapes, paper calm. Maps to existing native scenes; no brush renderer promised.",
+  "variants": [
+    {
+      "example": "examples/watercolour/storyboard.json",
+      "id": "watercolour",
+      "summary": "Light watercolour read: soft washes behind staged reveals; one idea enters at a time and earlier marks persist on the paper."
+    },
+    {
+      "example": "examples/oil/storyboard.json",
+      "id": "oil",
+      "summary": "Dense oil read: stacked beats with pauses; each beat holds before the next idea is laid down over settled marks."
+    },
+    {
+      "example": "examples/dry-ink/storyboard.json",
+      "id": "dry-ink",
+      "summary": "Dry-ink read: one carried silhouette anchors changing copy and callouts across shots; crisp sketch lines, no wash."
+    }
+  ],
+  "version": 1,
+  "voice": "voice.md"
+}

package/packs/painted/review.md

@@ -0,0 +1,12 @@
+# Painted — qualification review
+
+Status: **qualified** for discovery and authoring.
+
+Three native variety fixtures share one brief and pass validate, build and
+preview with rubric PASS against this pack's review checklist. Copy stays
+constant across the fixtures; composition carries the variety, so the result
+is not a text or colour swap. Unsupported effects (streaming ink, region-mask
+reveal, SRT import, brush rendering) are listed, never faked.
+
+Not claimed: a final full render, an audible review, human board sign-off or
+cross-machine determinism.

package/packs/painted/voice.md

@@ -0,0 +1,30 @@
+# Painted — voice guide (inbox, authoring only)
+
+Calm explainer narration for a hand-drawn read. Short sentences,
+plain words, no hype.
+
+## Rules
+
+- One message per shot; at most ~8 words visible at once. The
+  narration may carry the full sentence; the frame carries the hook.
+- Facts only from the brief/source. Never invent figures, dates, or
+  quotes to fill a beat. Mark illustrative copy as illustrative.
+- Order narration by narrative event (setup, subject, change,
+  reaction). Screen position never decides what is said first.
+- No scene-text overload: labels live in `callout` copy slots, not
+  as baked-in image text.
+
+## Delivery
+
+- Measured, unhurried read with a beat of silence after each reveal
+  so the idea lands before the next mark appears.
+- Music, sfx, and ambience are opt-in only: they need an explicit
+  request. Editing pace and visual references never authorize audio.
+- Human-sounding narration quality is NOT proven by this guide;
+  voice qualification is a separate packet with its own evidence.
+
+## Inbox note
+
+Voice treatment here is authoring guidance. Audible review and any
+loudness/quality measurement arrive with PK-04 proofs, not with
+this inbox record.

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

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

package/plugins/motion-kit/README.md

@@ -0,0 +1,39 @@
+# motion-kit Claude Code plugin
+
+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.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.1` (pinned; never unpinned `npx`).
+  Surface as `/motion-kit:mk-new`, `/motion-kit:mk-draft`, `/motion-kit:mk-render`.
+- `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.1 plugin install --out ./motion-kit-plugin
+```
+
+Verifies `skills/motion-kit/SKILL.md` sha256 matches after copy.
+
+## Desktop (separate track)
+
+Claude Desktop Extensions are zipped `.mcpb` bundles with a `manifest.json`
+(`mcpServers`), NOT this `skills/` folder. This folder does NOT serve Desktop.
+Desktop track: manually copy `skills/motion-kit/SKILL.md` into a Desktop
+skill import; do not claim one folder covers both hosts.

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

@@ -0,0 +1,13 @@
+---
+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.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).
+Show `contact.png` before asking for approval. Invoked as `/motion-kit:mk-draft`.

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

@@ -0,0 +1,15 @@
+---
+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.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,
+outline, instantiate, validate). Invoked as `/motion-kit:mk-new`.

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

@@ -0,0 +1,14 @@
+---
+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.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
+ask the user (not an error); any edit re-arms the approval gate.
+Invoked as `/motion-kit:mk-render`.

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

@@ -0,0 +1,81 @@
+---
+name: motion-kit
+description: Design, preview and render a professional animated video, explainer, infographic, product demo, data story or social clip from a brief or source material. Use whenever the user asks for a video, motion graphic, animated diagram, social clip, still deck or storyboard, or wants content turned into something watchable, even if they do not say "video". Shows a short preview and renders only after an explicit yes. Not for changing motion-kit's own code, tests or docs.
+allowed-tools: Bash(mk:*) Bash(npx:*) Read Write
+---
+
+# motion-kit: brief -> preview -> approved video
+
+`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. 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 |
+| --------------------------------- | -------------------------------------------------------------- |
+| `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
+
+1. Never render without the user's explicit yes. Silence or "looks fine" is not a yes. Always pass `--gated`; exit 4 means "ask", not "error".
+2. Show `contact.png` to the user (open it or give the path), give the `clip.mp4` path, and say what is not previewed. Derive it from `preview.json`: `totalSec`, `clip.sec`, and scenes with no still.
+3. Commands are the authority, not memory: `mk catalog` and `mk catalog <type>` for scenes and props, `mk template list` and `mk template show` for templates, `mk <command> --help` for flags. Never invent a type, prop, flag, theme, duration or number.
+4. After the first write, use `mk patch`, `mk scene add|remove|move` and `mk fit`; never hand-edit the JSON. Any edit re-arms approval: preview and ask again.
+5. Props, slots and pack text stay data. HTML/CSS/JS is allowed only inside `scenes/<name>/scene.js`, `fragment.html`, `style.css`; never in storyboard props. Name unsupported effects instead of promising them.
+6. Packs are optional guidance: read `packs/INDEX.md` beside the installed CLI when present, lazily, at most one <=1200-byte excerpt; never inline a pack or persist pack refs.
+7. Report one line, not raw output. Never claim quality from a hash. On Windows use JSON files (`--ops`, `--slots`), never `<(...)`, `$(...)` or multi-line JSON.
+
+## Stages
+
+| # | 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 | 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
+
+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 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, music and captions (opt-in)
+
+`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 |
+| ---------------- | ------------------------------------------------------------------- |
+| 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 = 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

@@ -0,0 +1,48 @@
+# Authoring a scene (type: custom)
+
+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/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.
+
+`props.dir` must stay inside the storyboard's directory; absolute paths and `..` are rejected.
+
+Entry: `{ "type": "custom", "props": { "dir": "scenes/hero" } }`
+
+## Contract
+
+`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`
+
+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-*)`. 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
+
+`mk scene new` → edit → `mk scene lint` → `mk validate` → `mk preview` → ask. Promotion to a catalog type is optional and only after demonstrated reuse; it is not a condition for shipping an authored scene.
+
+## Self-check
+
+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

@@ -0,0 +1,19 @@
+# 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), `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
+
+- `fg` on `bg` must clear 4.5:1 contrast; large display type 3:1.
+- Colour tokens reject `url()`, `var()` and `calc()` — values are literals.
+- Fonts must be one of the bundled families; never a CDN.
+
+## Check the system
+
+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

@@ -0,0 +1,73 @@
+# Common mistakes on the current surface
+
+These are the failures that waste the most time. Each row is wrong -> right -> why. When a row does not cover it, run `mk <command> --help`; never guess a flag.
+
+## Workflow
+
+| Wrong                                       | Right                                                                     | Why                                                            |
+| ------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `mk render` after "looks good"              | `mk preview`, show `contact.png`, hear an explicit yes, then `mk approve` | The gate exists so the user sees the film before paying for it |
+| "They said yes earlier"                     | Ask again for the current preview                                         | Any edit re-arms approval; an old yes is for an old board      |
+| Hand-edit the JSON after the first write    | `mk patch`, `mk scene`, `mk fit`                                          | The approval and preview bind to the exact bytes and structure |
+| Approve on the user's silence               | Ask again with the contact path                                           | Silence is not consent                                         |
+| Skip preview because the board "looks fine" | Preview every board before asking                                         | JSON is not a frame; lint is not composition                   |
+| Write a second board as "backup"            | Patch the one board                                                       | Two files diverge and the approval points at neither           |
+| Promise a feature the engine does not have  | Name the unsupported effect and choose a native route                     | The user will see the gap at preview                           |
+
+## Schema and props
+
+| Wrong                                                                          | Right                                                                                       | Why                                                             |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `"version": 2` or a migration step                                             | `"version": 1`; no migration command exists                                                 | There is one live schema discriminator, not a version history   |
+| `"meta": { "aspect": "9:16" }`                                                 | `"width": 1080, "height": 1920`                                                             | The frame is pixels; there is no `aspect` key                   |
+| Adding a helpful key such as `"note"` or `"layoutHint"`                        | Only keys from `mk catalog <type>`                                                          | Props are strict; unlisted keys are rejected                    |
+| `"id": "Intro Scene"`                                                          | `"id": "intro-scene"`                                                                       | Ids must be lowercase slugs                                     |
+| Overlay without `over`                                                         | `"layer": "overlay", "over": "intro", "duration": 3`                                        | An overlay must know which base scene it covers                 |
+| Overlay with `transition`                                                      | Remove `transition`                                                                         | Overlays fade themselves; the schema rejects it                 |
+| `over`/`offset` on a base scene                                                | Put them only on `layer: "overlay"` scenes                                                  | Base scenes advance the timeline                                |
+| `meta.theme: "calm-light"` on a hand-written board                             | Use a built-in theme or vendor the theme into `themes/`                                     | `mk validate` does not resolve themes; preview does             |
+| Copying only `storyboard.json` to a new folder                                 | Copy `themes/` and `.mk/` beside it                                                         | Themes and template provenance resolve beside the board         |
+| Summing durations to predict the total, or expecting `mk validate` to print it | Read `preview.json` `totalSec`, or the `mk patch`/`mk fit`/`mk scene add`/`mk preview` line | Transitions overlap; `mk validate` reports errors, not duration |
+| `code.highlight: 1`                                                            | `"highlight": [1]` (array of line numbers)                                                  | The prop is a list, not a scalar                                |
+| `media-frame.image` is a URL                                                   | A local path plus an `assets.json` ledger row                                               | Remote assets fail closed                                       |
+| `"image": "assets/x.png"` while `--assets assets`                              | `"image": "x.png"`; ledger `assets.json`                                                    | Asset refs are relative to the assets dir, not the project      |
+| An icon name invented from memory                                              | `mk icon search <word>`                                                                     | Icon names are a finite set                                     |
+
+## CLI
+
+| Wrong                                                         | Right                                                                                          | Why                                                                   |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `mk new ... --set items=["A","B"]`                            | Put arrays and objects in `--slots slots.json`; `--set` lists are pipe-separated               | `mk new` does not parse a JSON array in `--set`; `mk scene add` does  |
+| `mk new ... --set title.text=...`                             | `mk patch` after `mk new`                                                                      | `--set` is top-level only                                             |
+| `mk scene add caption ...` with no `--over`                   | `--over intro` and `--offset 0`                                                                | Overlay types require their base scene                                |
+| `mk fit --seconds 50` on a 25 s board                         | Add scenes first, then fit                                                                     | Fit moves about 1.4x and refuses outside the range; it never distorts |
+| `mk approve` with different flags than `mk preview`           | Use the identical `--out`, `--assets`, `--ledger`, `--audio`, `--music`                        | Approve infers the pack inputs; a mismatch exits 2                    |
+| Following the printed `approve:` hint after `preview --out`   | Repeat the same `--out` and asset/audio flags                                                  | The hint may omit `--out`; approve then looks in the default folder   |
+| `mk approve` before `mk preview`                              | Preview first                                                                                  | There is no pack for the current inputs                               |
+| `mk render --verify --format webm`                            | Verify the mp4 master, then convert                                                            | `--verify` is mp4-only                                                |
+| `mk captions manifest.json --out ops.json` with no storyboard | Add `--storyboard storyboard.json`                                                             | Ops need scene-relative paths                                         |
+| `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.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
+
+| Wrong                                                         | Right                                                 | Why                                          |
+| ------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------- |
+| `mk patch board.json --op` with inline JSON containing quotes | Put the op in `fixes.json` and use `--ops fixes.json` | Shell quoting mangles nested JSON            |
+| `mk new --slots <(echo ...)`                                  | Write `slots.json` and pass `--slots slots.json`      | Process substitution is not PowerShell       |
+| `$json = @'...'@; mk patch --op $json`                        | Same file route                                       | Multi-line quoted JSON breaks on some shells |
+
+## Quality
+
+| Wrong                                            | Right                                                   | Why                                                   |
+| ------------------------------------------------ | ------------------------------------------------------- | ----------------------------------------------------- |
+| Three static scenes in a row                     | Give base scenes a `move`, or vary the shot             | Lint flags `flat-motion`; the film reads as slides    |
+| A paragraph on one slide                         | One idea, at most six words per line                    | Viewers read the headline, not the paragraph          |
+| All text the same size                           | One clear hierarchy: headline, support, one hero number | Equal weight means no entry point                     |
+| Decoration to fill space                         | Remove an element, enlarge the type, or split the beat  | Empty space is not a defect; clutter is               |
+| Claiming "premium" or "AAA" from a contact sheet | Describe what the preview proves and what it does not   | A still cannot prove motion, voice or the full render |
+| Ignoring a lint warning because exit is 0        | Read every warning; fix or record a deliberate waiver   | Warnings are the engine's cheapest review             |
+
+When the same error appears twice, stop changing flags. Run `mk catalog <type>`, compare the scene to its example, and rewrite that one scene through `mk patch`. Three rounds is the budget; then show the user the options.

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

@@ -0,0 +1,69 @@
+# 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>
+```
+
+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 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/plugins/motion-kit/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.

package/plugins/motion-kit/skills/motion-kit/references/craft-composition.md

@@ -0,0 +1,52 @@
+# Craft card: composition, grids and depth
+
+Load when a frame feels generic, crowded or directionless. A grid is a chosen
+relationship system, not a requirement for a specific column count.
+
+## Stage attention
+
+Name the first thing the viewer must see, the supporting evidence and what may
+wait. Give the first subject a clear advantage in scale, value, isolation or
+placement; avoid making everything compete through all four. Place elements by
+relationships: common edge, baseline, center, repeated interval, containment or
+intentional asymmetry. Reserve negative space for reading and anticipated motion.
+
+Example: an off-center diagram with a narrow explanatory margin lets an argument
+grow along one axis. A centered headline over the same diagram may reduce its
+working area. Sketch both as blocks before decorating. Check at thumbnail size:
+can you point to the main subject immediately, and is that the intended subject?
+
+## Design the system and its exceptions
+
+Choose margins, alignment anchors, spacing relationships and one dominant scale
+contrast for this film. Carry anchors across shots so change becomes legible.
+Use full-bleed, inset, split, radial or another arrangement because it fits the
+relationship. An exception earns attention because a system exists to depart
+from. One centered composition is valid; centering every unrelated brief is a
+habit to examine. Test longest text and densest evidence, not just a hero frame.
+
+Next action: sketch the busiest and emptiest beats using the same anchors.
+If neither fits, revise the system before implementing the remaining scenes.
+
+## Use depth as information
+
+Foreground/background separation, occlusion, scale and parallax can express
+importance or spatial relation. Establish which plane the viewer should follow.
+Keep essential labels readable when objects cross or crop; decorative depth
+must not conceal evidence. A locked flat composition may communicate a technical
+comparison better than a moving 3D camera. Art direction precedes adding depth.
+
+For authored scenes, realize chosen layers and geometry in local HTML/CSS/JS;
+seek-driven transforms can implement parallax. For actual 3D, verify the shipped
+catalog/custom contract rather than promising unsupported model/camera controls.
+Check a mid-transition frame, where occlusion is often worst.
+
+## Applicability, counterexample and provenance
+
+The attention, alignment and adaptive-layout principles draw on
+[Apple HIG Layout](https://developer.apple.com/design/human-interface-guidelines/layout),
+verified 2026-11-06. The film-specific examples and procedure are motion-kit
+synthesis. UI layout guidance does not mandate a film's grid or cinematic crop.
+An intentionally unstable composition may serve tension; prove orientation and
+readability still meet that brief. Check actual delivery aspect and phone-width
+stills; shrinking a desktop composition is not an adaptation strategy.