@anvpx/motion 0.0.0-stage → 0.1.0

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,77 @@
+---
+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.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.
+
+## 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`).
+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/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   | 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 |
+
+## 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.
+
+## 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.
+
+## Voice 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`.
+
+## 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 = the approval hash matches the rendered board, `mk verify` exit 0 is quoted, and you state what was not verified.

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

@@ -0,0 +1,37 @@
+# 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.
+
+## 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.
+
+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`.
+
+## 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-*)`. Hard hexes break on a theme switch. The 5 % safe margin is already applied.
+
+## 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
+
+Same t, same pixels? Theme switch safe? Fits 9:16? Would a catalog type do this with less code?

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

@@ -0,0 +1,17 @@
+# Authoring a style (theme)
+
+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`.
+
+## 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.
+
+## Taste
+
+One accent, one easing family, one type scale. A theme is a constraint: if two colours compete, the scene has no accent.

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.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                             |
+
+## 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,81 @@
+# 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:
+
+```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.
+
+## 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.