@anvpx/motion 0.0.0-stage → 0.1.1

package/plugins/motion-kit/skills/motion-kit/references/outline.md

@@ -0,0 +1,34 @@
+# Outline for the user (stage 4)
+
+Send at most 200 words, including divergence, then wait for "go" or edits unless
+the user already authorized proceeding (for example, "just do it"). Use the
+constraints already supplied; the outline is a proposal, not a questionnaire.
+Propose one direction and keep the alternative to one line; do not offer a menu
+of templates, styles or knowledge choices.
+
+```text
+Plan: <title>
+Audience: <who> | Length: ~<N> s | Aspect: <aspect>
+Idea: <the visual argument and intended viewer effect>
+Visual system: <composition, type, color/material and motion decisions + why>
+Sound: <silence/voice/music/effects and their role>
+Route: <direct/authored/template or mixed; why it realizes this idea>
+Alternative: <a materially different approach + when it would serve better>
+Beats:
+1. <message + what the viewer sees change>
+2. <message + the visual/narrative turn>
+3. <how the idea resolves>
+Divergence: <meaningful differences from available prior work, or justified continuity>
+Assumed/unresolved: <defaults, sourced-number gaps, capability or rights questions>
+Go, or what should change?
+```
+
+Beat count follows the argument and duration, not this example. Name scene types
+only after capability mapping: `mk catalog <type>` for native components,
+`authoring-scene.md` for original compositions, `mk template show <t>/<bp>` only
+when a template is useful. Show how a design serves the brief rather than naming
+a preset as its explanation. If recent work is unavailable, say so.
+
+Direction approval authorizes drafting. Only explicit approval of the actual
+preview authorizes full render, with the same assets/audio/mix inputs. With no
+interactive user, return the outline and chosen route; never self-approve.

package/plugins/motion-kit/skills/motion-kit/references/patching.md

@@ -0,0 +1,50 @@
+# Edit by command (stage 9, validation fixes, structure and length)
+
+Never rewrite `storyboard.json` by hand. Every edit is a command that validates the result and writes atomically; an invalid result is never written (the pointer errors are printed, exit 2). Any edit changes the approval hash: preview again and ask again.
+
+| Need                                | Command                                                                                                      |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Change wording, duration, a setting | `mk patch sb.json --ops fixes.json` (portable), or `--op '<json>'` in PowerShell 7                           |
+| Several changes at once             | `mk patch sb.json --ops fixes.json` (a JSON array of ops; `--op` may follow it)                              |
+| Add a scene                         | `mk scene add sb.json bullets --after intro --set title="Three things" --set 'items=["A","B"]' --duration 8` |
+| Remove or reorder a scene           | `mk scene remove sb.json <id>`, `mk scene move sb.json <id> --after <id>` (or `--first`)                     |
+| Make it longer or shorter           | `mk fit sb.json --seconds 40`                                                                                |
+
+`--op` with inline JSON works in PowerShell 7 because single quotes preserve it; under `cmd.exe` it is unreliable. Use `--ops fixes.json` for anything portable or multi-line.
+
+## mk patch
+
+RFC 6902 subset: `add`, `replace`, `remove`, `move` (`from`, `path`), `test`. Paths are JSON Pointers (`/scenes/0/props/title`); `-` appends to an array; `~1` is `/` and `~0` is `~`. Ops apply in order to a copy; the first op that cannot apply stops the patch and is named by index.
+
+- A path into a missing parent fails with `parent "/scenes/9" does not exist`; `replace`/`remove` of a missing target fails with `target "..." does not exist`. Use `add` to create a key.
+- `__proto__`, `constructor`, `prototype` and command-shaped keys (`command`, `argv`, `shell`, `filter`, `executable`, `env`) are refused in paths and values.
+- The result goes through the full validator and lint. Output is at most 3 lines: `patch ok | 2 ops | changed /a, /b`, then `scenes 5 | total 25s | 0 errors, 1 warnings`, plus the first warning.
+- Several changes that are only valid together (a longer text and a longer duration) belong in one patch.
+
+Feedback to change, smallest first:
+
+| Feedback        | Change                                                                                                               |
+| --------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Wording         | `replace` the text under `/scenes/<i>/props/...`                                                                     |
+| Pacing          | `replace` `/scenes/<i>/duration` (seconds; lint enforces reading time and minimum hold), or `mk fit` for the whole   |
+| Look            | re-run `mk new` with another `--style`, or set `shot`, `move`, `ease`, `transition` on a scene (enums: `mk catalog`) |
+| Structure       | `mk scene add`, `remove` or `move`; overlays keep `over` pointing at an existing base scene id                       |
+| Colours / brand | `themes/brand.json` and `meta.theme` (`free-storyboard.md`, `authoring-style.md`)                                    |
+
+## mk scene
+
+- `add <type>` inserts a scene built from the catalog's minimal example (`mk catalog <type>` shows it). `--id` (default `<type>-<n>`), `--after <id>` (default: at the end), `--set k=v` (top-level prop; JSON when it parses, so `n=3`, `items=["a","b"]`, otherwise text; repeatable), `--duration <s>` (default: auto from the text).
+- Overlay types (`lower-third`, `bug`, `progress`, `countdown`, `chapter`) need `--over <base scene id>`; `--offset <s>` is seconds into it, and the duration defaults to 3.
+- Nested prop edits, or props the example does not show, go through `mk patch` afterwards.
+- Output is one line: `scene add ok | bullets-1 (bullets) at 3/6 | total 33s | 0 errors, 0 warnings`.
+
+## mk fit
+
+`mk fit sb.json --seconds N` scales every base scene by one common factor so the total is N. The total is printed by `mk patch`, `mk fit`, `mk scene add` and `mk preview`; `mk validate` reports errors and warnings, not duration. Each scene stays inside its range: from the template's `pacing.json` (smallest to largest seconds for that scene type across short, standard and long), never under its reading time (3 words per second) or the 2 s minimum hold. Overlays scale with the scene they cover. It is deterministic and prints before and after on two lines.
+
+- A typical blueprint stretches or shrinks by about 1.4x. From 25 s to 50 s is out of range: add scenes first (about one per 7 s), then `mk fit`.
+- A refusal says why and writes nothing: `N s is over the X s these scenes can stretch to` means add scenes; `N s is under the X s these scenes need; reading time floors: <id> needs >= 8s to read (22 words)` means cut that scene's text or raise N.
+- Without template provenance (`.mk/<name>/template.json`) the range is the floor up to 1.5x the current length.
+- Run it after the structure is final; adding or removing a scene afterwards changes the total again.
+
+Re-preview shows the same pack layout; compare against what the user already approved and tell them only what changed. Max 3 feedback rounds, then summarise the options and ask the user to choose.

package/plugins/motion-kit/skills/motion-kit/references/patterns.md

@@ -0,0 +1,55 @@
+# Patterns — the decisions a strong model makes for you
+
+Historical heuristics attributed to 2,462 works / 585 prompts (source-tree learning record, not shipped). That corpus and its quality/correlation claims are not independently qualified here. Load for a relevant design question; test suggestions against `direction.md` and the craft cards.
+
+Tags: **[A]** tool diagnostic to review · **[B]** optional hypothesis · **[C]** judgement. Inspect actual validation severity and preserve required native contracts; artistic heuristics are not universal engine rules.
+
+## Say values, not adjectives
+
+- **[B]** Make implementation decisions concrete: hex for colour, px for spacing, seconds or ms for duration, BPM when tempo matters. Values make a design reproducible; no measured correlation with quality is established here, and rationale still matters.
+- **[B]** Name the habits that would weaken this idea and why. This gives more actionable guidance than praise alone; it is not evidence that prohibition always improves a result.
+- **[B]** Keep the brief focused on decisions. The historical source suggests roughly 1,000 characters; use the length needed to preserve facts and resolve ambiguity rather than a universal quota.
+
+## Length
+
+- **[B]** A 24 s sketch is one compact starting point. The source reports 53 % under 40 s and 23 % under 20 s in its selected work; those unqualified proportions do not establish the right duration for a new brief.
+- **[B]** Try 3-6 beats with clear jobs for a compact explanation. A long take or a larger sequence can fit a different argument; scene count is not capped by this heuristic.
+
+## Six sections, in order
+
+`inputs` → `direction` → `structure` → `build` → `gotchas` → `start`
+
+This is an optional organization pattern: `inputs` asks for missing audience, length, aspect, brand and source data. `direction` records the visual argument and its reasons, with exclusions where useful. `structure` is the beat map. `build` is `seek(t)` only. `gotchas` names what will look wrong here. `start` shows the outline and stops at the user gate.
+
+## Habits to question
+
+Full list: `slop.md`.
+
+bouncy easing · particle bursts · glows · gradients on chrome · mismatched icon strokes · unchosen dead time · template look · crowded lines · stock-photo hands. Each can be purposeful in context; examine fit instead of applying a blanket visual ban.
+
+## Rhythm
+
+- **[B]** At 120 BPM in 4/4 a bar is 2 s, so 24 s is 12 bars (`mk fit --bpm 120 --bars 12`). This is an arithmetic example, not a required tempo; speech, silence or slow cinema may need a different rhythm.
+- **[A]** Review `flat-motion` diagnostics against the intended action and hold. Deliberate stillness can be the right beat.
+- **[A]** A run of static scenes can trigger `flat-motion`. Inspect reading load and intent before adding a `move`; gratuitous camera travel does not improve a deliberate rest.
+- **[A]** Review `hold-after-accent` and its suggested ≥ 3 s hold against the actual accent, reading and narration; inspect the validator's real severity rather than treating the number as a taste law.
+
+## Motion
+
+- **[B]** The source's median 10-frame move (0.33 s) and oversize decelerating entry suggest one energetic vocabulary. Try a slower move or growth from zero when distance, material or emergence calls for it.
+- **[B]** Coherent easing can connect a sequence. Multiple families or springs can express contrasting materials or actions when the direction explains the difference.
+- **[A]** Review `linear-ease` diagnostics. A meter, mechanical action, progress, countdown or chart may warrant constant speed; inspect actual supported props and severity.
+- **[B]** The source suggests motion-led cuts every 0.3-2.3 s and 0.6-1.4 s end holds. Cuts on rest, long holds and other tempos can serve the brief; preview reading and closure rather than adopting these ranges automatically.
+- **[C]** If it loops, the last frame equals the first — cursor included.
+
+## Before the full render
+
+- **[A]** One still per beat: `mk still storyboard.json --at <beats>`. Fix cramped or off-grid frames there, never after.
+
+## Self-check before `mk validate`
+
+1. Can a viewer repeat the point after one viewing?
+2. Do the accents establish a clear hierarchy? Multiple accents may encode meaningful groups; one is not a universal limit.
+3. Does every number have a source?
+4. Does anything move without a reason?
+5. Does the last frame land, or just stop?

package/plugins/motion-kit/skills/motion-kit/references/quality-bar.md

@@ -0,0 +1,61 @@
+# Quality bar: what to check before you ask
+
+The engine proves structure: schema, props, timing, lint, hashes. It cannot prove that the film is clear or worth watching. Review against `direction.md` and its intended viewer effect, using `craft-critique.md` for the evidence and revision method, and `critique-repair.md` for a time-located finding and its recheck. Look at actual frames rather than trusting the exit code.
+
+## Inspect in this order
+
+1. Open `<pack>/contact.png` at full size. Use the sheet for sequence and consistency, never for legibility.
+2. Open each still at delivery size (`stills/`). Check the busiest and the emptiest frame, not only the hero.
+3. Inspect a still at the intended small-screen size (about 390 px is one useful phone-width check). If the headline or diagram cannot be read, adapt its grouping/scale for that delivery condition.
+4. Compare the first and last still. The opening must earn attention; the close must land, not merely stop.
+5. Watch available motion at normal speed, then inspect the start, middle and settle of the hardest action and two transitions. Compare their timing with the intended beat table; stills alone cannot prove motion.
+6. Listen to actual audible output when sound is in scope. Read `preview.json` for coverage, scene/still timings, lint and estimate. Record reviewed ranges and unpreviewed scenes, motion or audio. If the clip was skipped, say that only stills are available; never score unheard sound as passing.
+
+If you cannot see images, say so. Read `preview.json`, ask the user to open the pack, and do not claim you inspected it.
+
+## Ten checks
+
+| #   | Check                 | Pass looks like                                                                                                              |
+| --- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Visual argument       | Each beat advances a clear intention; a continuous authored scene may contain several related beats                          |
+| 2   | Opening               | Attention has a deliberate subject; speed and restraint fit the intended channel and tone                                    |
+| 3   | Hierarchy             | The eye knows where to start; information roles have purposeful differences in scale, weight or placement                    |
+| 4   | Legibility            | Essential words and evidence remain readable at delivery size through the actual motion; no clipping/accidental overlap      |
+| 5   | Line breaks           | Breaks preserve meaning and rhythm; longest real copy fits without squeezing it into an unreadable block                     |
+| 6   | Contrast              | Text survives the theme; AA is the floor, not the target; the accent also survives grayscale/CVD or carries a second channel |
+| 7   | Art direction         | Color/material/type choices reinforce the concept; useful complexity is distinguished from decorative habit                  |
+| 8   | Motion with a purpose | Movement or stillness serves meaning; staging, continuity, overlap and rest make the important change legible                |
+| 9   | Rhythm                | Orientation, change and reading holds fit the actual message, narration and sound; cuts have narrative reasons               |
+| 10  | Truth                 | Every number has a source; no invented stat, logo, quote or customer                                                         |
+
+Use measurements as local checks, not universal aesthetic laws. Inspect real reading conditions, aspect/crop and platform overlays. Name the reference principle and purposeful divergence; do not turn a reference film into a layout to copy.
+
+## Score the preview
+
+Use a 1-5 local rubric; it is a conversation aid, not an industry benchmark.
+
+| Score | Meaning                                                       |
+| ----- | ------------------------------------------------------------- |
+| 1     | Placeholder: wrong, unreadable, or visibly broken             |
+| 2     | Works but generic; the point is present, the craft is not     |
+| 3     | Clear and competent; a viewer gets it once                    |
+| 4     | Deliberate: hierarchy, rhythm and surface reinforce the point |
+| 5     | Distinctive: the treatment is inseparable from the message    |
+
+Score reviewed dimensions: message, hierarchy, craft, motion, sound. Mark unreviewed or inapplicable dimensions N/A and explain; a still cannot establish a motion score, and unheard audio cannot establish a sound score. Fix every known 1 before asking. Improve the weakest observed dimension rather than adding decoration. Name any 2 and missing review evidence in the ask; the local score is not a professional-quality certification.
+
+## Fix in this order
+
+1. Broken or untrue: clipping, overlap, invented data, unreadable contrast.
+2. The idea: no clear intention, competing attention, or a relationship the viewer cannot infer.
+3. Structure: the beat order, a missing setup, a close that does not land.
+4. Hierarchy and scale: type too small, too many equal weights, a hero number spent twice.
+5. Timing: dead holds, cuts on rest, a scene that ends before it is read.
+6. Surface: colour, texture, decoration, effects.
+7. Sound: plan it with the direction and review it with picture; fix intelligibility and timing before decorative effects.
+
+## When it still looks weak
+
+Try one move at a time, then re-preview: shorten the copy, enlarge the headline, remove one element, split the beat, change the theme, or add a purposeful camera move. Do not add glow, particles or gradients to compensate for a weak composition.
+
+Never call a preview "final", "premium" or "AAA". Say what the preview shows, what it does not, and what the render will add.

package/plugins/motion-kit/skills/motion-kit/references/review.md

@@ -0,0 +1,8 @@
+# Review before asking (stage 8)
+
+- **Continuity table first:** beat | start | length | surface/identity | cue. Flag any surface, palette or identity change you did not choose. A dark closing card from the `outro` type is its own palette, not a theme reset.
+- **Look at the stills at delivery size and at phone width** (390 px or a 9:16 crop). The contact sheet is a map, not a review: dense diagrams are only readable in the still.
+- **Transitions:** sample start, middle and end. A cut is fine; an unexplained morph is not.
+- **Holds:** a settled poster may hold on purpose; a frozen frame may not. Say which one it is.
+- **Record what you did not see** (clip budget, no voice/music, no phone still, no transition sample) in the approval ask.
+- **Never claim what a hash cannot prove:** lint, hashes and exit codes are not quality; a voice-match claim needs approved samples, and a final-render claim needs a final render.

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

@@ -0,0 +1,300 @@
+# Scene recipes: message first, then props
+
+`mk catalog` is the authority: run `mk catalog <type>` before using a type. The snippets below are valid `props` shapes to copy, not limits. Set `duration` and `move` on every base scene; one idea per scene, and two ideas means two scenes. If the catalog does not settle a design question, use `knowledge-routing.md`.
+
+```json
+{ "id": "beat-1", "type": "<type>", "duration": 5, "move": "push-in", "ease": "out", "props": {} }
+```
+
+## Pick by the shape of the message
+
+| The beat is                               | Use                                     | Avoid                                   |
+| ----------------------------------------- | --------------------------------------- | --------------------------------------- |
+| A hook, claim or section opener           | `title`, `poster`, `kinetic`, `sticker` | `bullets` for one claim                 |
+| One number that carries the point         | `stat`                                  | `chart` for a single value              |
+| Two to six numbers at a glance            | `kpi-grid`                              | a wall of `stat` scenes                 |
+| Trend, ranking or share                   | `chart`                                 | `table` when the shape is the message   |
+| Exact values, a small ranked list         | `table`                                 | `chart` for two rows                    |
+| An ordered procedure                      | `steps`                                 | `flow` for a straight sequence          |
+| A system, dependencies or a decision path | `flow`                                  | `timeline` when nothing is dated        |
+| Before/after, two options                 | `compare`                               | two separate `bullets` scenes           |
+| Features, benefits or categories          | `icon-grid`                             | `bullets` with invented icons           |
+| History, roadmap, now/next                | `timeline`                              | `steps` for dates                       |
+| A quotation with attribution              | `quote`                                 | `callout` with a name                   |
+| One rule, formula, definition or warning  | `callout`                               | `bullets` for one sentence              |
+| A real screenshot or photo                | `media-frame`                           | `scene3d` for a real screenshot         |
+| Code, terminal output or a diff           | `code`                                  | plain `bullets`                         |
+| A product or object in 3D                 | `scene3d`                               | `media-frame` when the object must turn |
+| An audio shape                            | `waveform`                              | `chart` for peaks                       |
+| A name, logo, chapter, count or progress  | an overlay                              | a whole base scene for a small chip     |
+| The close                                 | `outro`                                 | a second `title` at the end             |
+
+## Openers
+
+**`title`**: opening or section card; optional kicker and subtitle.
+
+```json
+{
+  "kicker": "Architecture",
+  "title": "How a request reaches the data",
+  "subtitle": "Four services, one public door"
+}
+```
+
+**`hero`**: landing-page hero with `[x]` accents, up to 4 glass tiles.
+
+```json
+{
+  "kicker": "New",
+  "title": "Design at the [speed] of thought",
+  "subtitle": "One line of support",
+  "layout": "bento"
+}
+```
+
+**`poster`**: 1-3 oversized lines; the last line can be outline type.
+
+```json
+{ "lines": ["Make it", "move"], "outline": true, "foot": "A short foot note" }
+```
+
+**`kinetic`**: one word or phrase per beat; use for hooks and rules of three. `emphasis` is the 1-based beat to accent.
+
+```json
+{ "words": ["Plan", "Build", "Ship"], "mode": "slam", "emphasis": 3 }
+```
+
+**`sticker`**: pop-comic slam for myth-vs-fact and punchy shorts.
+
+```json
+{ "words": ["Myth", "Busted"], "burst": true }
+```
+
+## Evidence
+
+**`stat`**: one hero number that counts up.
+
+```json
+{
+  "value": 120,
+  "unit": "ms",
+  "label": "median response",
+  "delta": "-18%",
+  "context": "measured last quarter"
+}
+```
+
+**`kpi-grid`**: 2-6 headline numbers side by side; `trend` is `up|down|flat`, `good` is `up|down`, `trend` needs `delta`, and `good` needs `trend`.
+
+```json
+{
+  "title": "Quarter at a glance",
+  "items": [
+    { "value": "$4.2M", "label": "Revenue", "delta": "+12%", "trend": "up" },
+    {
+      "value": 86,
+      "unit": "%",
+      "label": "Retention",
+      "delta": "-2 pts",
+      "trend": "down",
+      "good": "down"
+    }
+  ]
+}
+```
+
+**`chart`**: bar, line or donut for ranking, trend or share. `bar` and `donut` need `data`; `line` needs `x` and `series`; `highlight` is a 0-based data index.
+
+```json
+{
+  "kind": "bar",
+  "title": "Signups by channel",
+  "unit": "signups",
+  "data": [
+    { "label": "Search", "value": 420 },
+    { "label": "Referral", "value": 310 },
+    { "label": "Social", "value": 190 }
+  ],
+  "highlight": 0
+}
+```
+
+**`table`**: 2-5 columns, 2-8 rows, one highlighted row.
+
+```json
+{
+  "title": "Top regions",
+  "columns": ["Region", "Revenue"],
+  "rows": [["North", "$4.2M"], ["South", "$3.1M"]],
+  "rank": true,
+  "highlight": 0
+}
+```
+
+## Explanation
+
+**`bullets`**: 1-6 short points; marker `dot`, `check`, `cross` or `number`.
+
+```json
+{
+  "title": "Three rules",
+  "items": ["One idea per scene", "Six words per line", "One accent only"],
+  "marker": "check"
+}
+```
+
+**`flow`**: 2-8 nodes and the arrows between them; `direction` is `lr` or `tb`.
+
+```json
+{
+  "direction": "lr",
+  "nodes": [
+    { "id": "client", "label": "Client" },
+    { "id": "api", "label": "API gateway" },
+    { "id": "db", "label": "Database" }
+  ],
+  "edges": [
+    { "from": "client", "to": "api", "label": "request" },
+    { "from": "api", "to": "db", "label": "query" }
+  ]
+}
+```
+
+**`steps`**: ordered path, ladder or stairs; use `ladder` for pricing and levels.
+
+```json
+{
+  "title": "How it works",
+  "layout": "path",
+  "steps": [
+    { "label": "Write", "detail": "One brief" },
+    { "label": "Preview", "detail": "One pack" },
+    { "label": "Render", "detail": "One yes" }
+  ]
+}
+```
+
+**`timeline`**: 2-7 dated items with `done`, `now` or `next`; `orient` is `h` or `v`.
+
+```json
+{
+  "title": "Roadmap",
+  "orient": "h",
+  "items": [
+    { "when": "Q1", "label": "Beta", "state": "done" },
+    { "when": "Q2", "label": "Launch", "state": "now" },
+    { "when": "Q3", "label": "Scale", "state": "next" }
+  ]
+}
+```
+
+**`callout`**: one big statement; `kind` is `formula`, `statement`, `definition`, `warning` or `tip`. Use `formula` for an equation, `statement` for a claim or rule, `definition` for a term, `warning` for a risk, `tip` for advice.
+
+```json
+{ "text": "[Profit] = [Revenue] − [Costs]", "kind": "formula", "label": "The rule" }
+```
+
+**`code`**: up to 14 lines; `+` and `-` prefixes show a diff; `highlight` is an array of 1-based line numbers.
+
+```json
+{
+  "lang": "js",
+  "file": "total.js",
+  "lines": ["const total = price * 2", "- old line", "+ new line"],
+  "highlight": [1]
+}
+```
+
+## Contrast and voice
+
+**`compare`**: two options, 1-5 points each, one winner.
+
+```json
+{
+  "title": "Before and after",
+  "left": { "label": "Before", "points": ["Manual", "Slow"] },
+  "right": { "label": "After", "points": ["Automated", "Fast"] },
+  "winner": "right",
+  "verdict": "Automation wins on repeat work"
+}
+```
+
+**`quote`**: testimonial with attribution; `rating` is 1-5.
+
+```json
+{
+  "quote": "It explained the whole system in twenty seconds.",
+  "name": "Alex Kim",
+  "role": "CTO",
+  "rating": 5
+}
+```
+
+## Visual
+
+**`icon-grid`**: 2-8 icon cards; get names from `mk icon search`.
+
+```json
+{
+  "title": "Why teams switch",
+  "items": [
+    { "icon": "zap", "label": "Fast setup" },
+    { "icon": "shield", "label": "Secure" },
+    { "icon": "globe", "label": "Global" }
+  ]
+}
+```
+
+**`media-frame`**: a real local image, bare or in a browser/phone/laptop frame. Import it, then point `image` at the file relative to `--assets`:
+
+```bash
+mk assets import src/dashboard.png --dir assets --ledger assets.json --licence CC0-1.0 --source-url <url>
+```
+
+```json
+{
+  "image": "dashboard.png",
+  "device": "browser",
+  "title": "The dashboard",
+  "callouts": [{ "x": 30, "y": 40, "label": "Start here" }]
+}
+```
+
+Pass the same `--assets assets --ledger assets.json` to build, preview, approve and render. Up to 3 callouts; `x`/`y` are percentages 0-100; `label` is at most 24 characters.
+
+**`scene3d`**: a WebGL diorama; it falls back to flat 2D without WebGL. 3D output is machine/GPU stable, not portable.
+
+```json
+{ "title": "Orbit", "post": "cinematic", "light": "studio", "material": "metal", "hdri": "studio" }
+```
+
+**`waveform`**: 16-128 precomputed peaks, 0-1; never decode audio into the board.
+
+```json
+{
+  "label": "Intro",
+  "peaks": [0.2, 0.4, 0.6, 0.8, 0.6, 0.4, 0.3, 0.5, 0.7, 0.9, 0.7, 0.5, 0.4, 0.3, 0.2, 0.1]
+}
+```
+
+## Overlays
+
+All overlays need `"layer": "overlay"`, `"over": "<base id>"`, `"duration"` and no `transition`.
+
+| Type          | Props                                                  | Use for                       |
+| ------------- | ------------------------------------------------------ | ----------------------------- |
+| `lower-third` | `{ "name": "Ada Lovelace", "title": "Mathematician" }` | a name plate                  |
+| `bug`         | `{ "text": "ACME", "position": "top-right" }`          | a corner word mark or logo    |
+| `progress`    | `{ "scope": "timeline", "label": "Progress" }`         | a thin progress bar           |
+| `countdown`   | `{ "from": 3, "to": 1 }`                               | a countdown                   |
+| `chapter`     | `{ "number": 1, "label": "How it works" }`             | a numbered chapter chip       |
+| `caption`     | `{ "text": "Automation wins on repeat work." }`        | karaoke or full-text captions |
+
+For `caption`, `words` (voice timings) is better than `text`; `mk captions` builds the overlay ops from a voice manifest.
+
+## Before you write
+
+- `mk catalog <type>` shows the exact fields, limits and a minimal example.
+- `mk catalog` (no type) shows all 28 types and their required fields.
+- One accent per scene, at most six words per line, and preferably no more than two overlays on one base scene; lint warns at three simultaneous overlays.
+- If the message needs two of these shapes, split it into two scenes.

package/plugins/motion-kit/skills/motion-kit/references/setup.md

@@ -0,0 +1,16 @@
+# Setup: voice and consumer install
+
+## Voice (opt-in)
+
+Engine renders silent without voice. For narration, set up the voice venv once:
+
+1. Install Python 3.12 from https://www.python.org/downloads/ (check Add to PATH). `py -3.12 --version` must say 3.12.x (3.14 is too new for TTS wheels).
+2. Install espeak-ng from https://github.com/espeak-ng/espeak-ng/releases (.msi), then `setx PHONEMIZER_ESPEAK_LIBRARY "C:\Program Files\eSpeak NG\libespeak-ng.dll"`.
+3. `py -3.12 -m venv .venv-voice`, then `.venv-voice\Scripts\activate`, then `pip install kokoro==0.9.4 soundfile==0.14.0 faster-whisper==1.2.1`.
+4. `mk doctor` shows `python-venv`/`espeak`/`kokoro`/`faster-whisper` as ok (voice-only rows; they never fail the exit code).
+
+## Consumer install + doctor
+
+Run the installed package; no checkout is needed. Fixes: hyperframes pin 0.8.212; icons `icons.json`; templates `import.meta.url`; fonts woff2 + OFL; bin `dist/main.js`.
+
+`mk doctor` has 18 rows: node, pnpm, ffmpeg, ffprobe, hyperframes, chrome-headless-shell, gpu, python, python-venv, espeak, kokoro, faster-whisper, fonts, icons, templates, bin, catalog, skills. The trailing line counts statuses (for example `17 ok, 1 usable`), not rows. Vendored hint `reinstall @anvpx/motion`. `--fix` only `npx hyperframes browser ensure`; rest hint-only, exits unchanged.

package/plugins/motion-kit/skills/motion-kit/references/slop.md

@@ -0,0 +1,40 @@
+# What never ships
+
+Historical style heuristics attributed to a skill built on 53 frame-measured moments and rejected AI films. The underlying corpus and measurements are not qualified by this package. Use the observations to question an unchosen habit, not to define a permissible style.
+
+These are style defaults and judgement calls, not engine rules: when the brief earns one of these deliberately, it is allowed — name the exception and its reason in the outline instead of following the list mechanically.
+
+## Examine unchosen defaults
+
+1. **Page chrome:** a name in a corner, counters ("02 / 05"), timecodes, progress bars, corner brackets.
+2. **Deck layouts:** a held left headline, a kicker above a headline, headline-left/device-right.
+3. **Generic UI:** a rounded card with a status dot and "label . value", skeleton bars, invented numbers.
+4. **The name's first association:** stars for a star, a rocket for "launch".
+5. **Invented stats**, stat walls, on-screen disclaimers.
+6. **Slogan copy:** "Not just X. It's Y.", "Unlock", "Meet X", "the future of".
+7. **The house style as default:** a giant cropped word, a colour-flood wipe, a dot becoming the logo.
+8. **A flat swatch ground per scene**, or a small card on a void.
+9. **A pinned object** at the same coordinates through three shots.
+10. **A web-footer ending:** logo + tagline + button + URL.
+11. **Self-certification:** claiming a gate passed without quoting its number.
+12. **A film you did not look at.**
+
+## Historical motion hypotheses
+
+These source-specific observations are starting points for a short, energetic treatment, not measured laws of animation. Their counts and ranges have not been independently reproduced here; preview alternatives against the direction.
+
+- The source reports a median move of **10 frames (0.33 s)** and travel concentrated in the first 4-8 frames. Longer movement may be necessary for distance, weight or reading.
+- Decelerating arrivals and accelerating exits can make a hand-off decisive. Spring count follows material and meaning rather than a per-film quota.
+- The source reports **3,392 transform entries against 584 opacity fades**. That ratio does not disqualify a dissolve, atmospheric fade or a film built around opacity.
+- An oversize arrival (the source's logo example starts around 3.5x) can express force. Growth from zero can instead communicate emergence when that is the intended idea.
+- A living detail can sustain a held frame. Complete stillness and rest can also give information or emotion time to land.
+- The source's **0.3-2.3 s cuts on motion** suit one pacing vocabulary. Cuts on rest, long takes and slow cinema remain valid choices.
+- The source's **0.6-1.4 s end hold** and shrinking ending are options. Reading load, sound and narrative closure determine the actual hold and scale.
+
+## Type sizes, as a fraction of frame height
+
+Optional source examples: headline 7-11 % (9 typical) · support 5-7 % · hero number 22-29 % · wordmark 0.22-0.38 of width. They are not engine limits; choose and preview a hierarchy for the actual words, aspect and viewing conditions.
+
+## Fix order when it looks wrong
+
+broken or untrue → the idea → connections between beats → hierarchy and scale → timing → surface → sound.