@anvpx/motion 0.0.0-stage → 0.1.1

package/shared/themes/warm-light.json

@@ -0,0 +1,368 @@
+{
+  "$description": "warm: cream and terracotta with serif headings and static film grain (light), DTCG format",
+  "color": {
+    "$type": "color",
+    "bg": {
+      "$value": "#fbf3e6"
+    },
+    "bgEnd": {
+      "$value": "#f2e3ca"
+    },
+    "glow": {
+      "$value": "#f4dcbd"
+    },
+    "glow2": {
+      "$value": "#f1e4c4"
+    },
+    "surface": {
+      "$value": "#f6ebd8"
+    },
+    "card": {
+      "$value": "#fffaf1"
+    },
+    "divider": {
+      "$value": "#dcc6a5"
+    },
+    "accentSoft": {
+      "$value": "#f6dcc9"
+    },
+    "fg": {
+      "$value": "#2b1a12"
+    },
+    "muted": {
+      "$value": "#664f40"
+    },
+    "accent": {
+      "$value": "#963a14"
+    },
+    "accent2": {
+      "$value": "#566530"
+    },
+    "onAccent": {
+      "$value": "#ffffff"
+    },
+    "onAccent2": {
+      "$value": "#ffffff"
+    },
+    "deep": {
+      "$value": "#5a2a16"
+    },
+    "deepEnd": {
+      "$value": "#3a190c"
+    },
+    "onDeep": {
+      "$value": "#fff7ea"
+    },
+    "onDeepMuted": {
+      "$value": "#ecd2ba"
+    }
+  },
+  "chart": {
+    "1": {
+      "$value": "#963a14"
+    },
+    "2": {
+      "$value": "#566530"
+    },
+    "3": {
+      "$value": "#2f5f7a"
+    },
+    "4": {
+      "$value": "#8a5a00"
+    },
+    "5": {
+      "$value": "#7a3a5a"
+    },
+    "6": {
+      "$value": "#2a7a6a"
+    },
+    "7": {
+      "$value": "#b4263a"
+    },
+    "8": {
+      "$value": "#5a4a3e"
+    },
+    "$type": "color"
+  },
+  "font": {
+    "$type": "fontFamily",
+    "sans": {
+      "$value": ["Inter", "system-ui", "sans-serif"]
+    },
+    "display": {
+      "$value": ["Source Serif 4", "Georgia", "serif"]
+    },
+    "mono": {
+      "$value": ["ui-monospace", "SFMono-Regular", "Menlo", "Consolas", "monospace"]
+    }
+  },
+  "fontSize": {
+    "$type": "dimension",
+    "sm": {
+      "$value": "28px"
+    },
+    "md": {
+      "$value": "32px"
+    },
+    "lg": {
+      "$value": "50px"
+    },
+    "xl": {
+      "$value": "76px"
+    },
+    "title": {
+      "$value": "104px"
+    },
+    "display": {
+      "$value": "136px"
+    },
+    "heroSm": {
+      "$value": "168px"
+    },
+    "heroMd": {
+      "$value": "248px"
+    },
+    "hero": {
+      "$value": "364px"
+    }
+  },
+  "spacing": {
+    "$type": "dimension",
+    "xs": {
+      "$value": "4px"
+    },
+    "sm": {
+      "$value": "8px"
+    },
+    "md": {
+      "$value": "16px"
+    },
+    "lg": {
+      "$value": "32px"
+    },
+    "xl": {
+      "$value": "64px"
+    },
+    "xxl": {
+      "$value": "100px"
+    }
+  },
+  "radius": {
+    "$type": "dimension",
+    "sm": {
+      "$value": "6px"
+    },
+    "md": {
+      "$value": "12px"
+    },
+    "lg": {
+      "$value": "20px"
+    },
+    "xl": {
+      "$value": "32px"
+    },
+    "full": {
+      "$value": "9999px"
+    }
+  },
+  "opacity": {
+    "$type": "number",
+    "subtle": {
+      "$value": 0.7
+    },
+    "medium": {
+      "$value": 0.85
+    },
+    "full": {
+      "$value": 1
+    }
+  },
+  "duration": {
+    "$type": "duration",
+    "fast": {
+      "$value": "300ms"
+    },
+    "base": {
+      "$value": "600ms"
+    },
+    "slow": {
+      "$value": "1200ms"
+    }
+  },
+  "status": {
+    "$type": "color",
+    "good": {
+      "$value": "#17803f"
+    },
+    "warn": {
+      "$value": "#a45a00"
+    },
+    "bad": {
+      "$value": "#b4232f"
+    }
+  },
+  "stroke": {
+    "$type": "dimension",
+    "card": {
+      "$value": "0px"
+    },
+    "icon": {
+      "$value": "1.75px"
+    }
+  },
+  "numeric": {
+    "mode": {
+      "$type": "string",
+      "$value": "proportional"
+    }
+  },
+  "shadow": {
+    "mode": {
+      "$type": "string",
+      "$value": "soft"
+    },
+    "color": {
+      "$type": "color",
+      "$value": "#2b1a12"
+    }
+  },
+  "grain": {
+    "opacity": {
+      "$type": "number",
+      "$value": 0.06
+    }
+  },
+  "$extensions": {
+    "motion-kit": {
+      "family": "warm",
+      "mode": "light",
+      "pair": "warm-dark",
+      "textPairs": [
+        {
+          "fg": "fg",
+          "bg": "bg"
+        },
+        {
+          "fg": "fg",
+          "bg": "bgEnd"
+        },
+        {
+          "fg": "fg",
+          "bg": "glow"
+        },
+        {
+          "fg": "fg",
+          "bg": "glow2"
+        },
+        {
+          "fg": "fg",
+          "bg": "surface"
+        },
+        {
+          "fg": "fg",
+          "bg": "card"
+        },
+        {
+          "fg": "fg",
+          "bg": "accentSoft"
+        },
+        {
+          "fg": "muted",
+          "bg": "bg"
+        },
+        {
+          "fg": "muted",
+          "bg": "bgEnd"
+        },
+        {
+          "fg": "muted",
+          "bg": "glow"
+        },
+        {
+          "fg": "muted",
+          "bg": "glow2"
+        },
+        {
+          "fg": "muted",
+          "bg": "surface"
+        },
+        {
+          "fg": "muted",
+          "bg": "card"
+        },
+        {
+          "fg": "muted",
+          "bg": "accentSoft"
+        },
+        {
+          "fg": "accent",
+          "bg": "bg"
+        },
+        {
+          "fg": "accent",
+          "bg": "bgEnd"
+        },
+        {
+          "fg": "accent",
+          "bg": "glow"
+        },
+        {
+          "fg": "accent",
+          "bg": "glow2"
+        },
+        {
+          "fg": "accent",
+          "bg": "surface"
+        },
+        {
+          "fg": "accent",
+          "bg": "card"
+        },
+        {
+          "fg": "accent",
+          "bg": "accentSoft"
+        },
+        {
+          "fg": "accent2",
+          "bg": "bg"
+        },
+        {
+          "fg": "accent2",
+          "bg": "bgEnd"
+        },
+        {
+          "fg": "accent2",
+          "bg": "surface"
+        },
+        {
+          "fg": "accent2",
+          "bg": "card"
+        },
+        {
+          "fg": "onAccent",
+          "bg": "accent"
+        },
+        {
+          "fg": "onAccent2",
+          "bg": "accent2"
+        },
+        {
+          "fg": "onDeep",
+          "bg": "deep"
+        },
+        {
+          "fg": "onDeep",
+          "bg": "deepEnd"
+        },
+        {
+          "fg": "onDeepMuted",
+          "bg": "deep"
+        },
+        {
+          "fg": "onDeepMuted",
+          "bg": "deepEnd"
+        }
+      ]
+    }
+  }
+}

package/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/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/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/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/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.