@anvpx/motion 0.0.0-stage → 0.1.0

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
+
+From 2,462 works / 585 prompts (source-tree learning record, not shipped). Load only when the catalog does not settle it.
+
+Tags: **[A]** lint · **[B]** default · **[C]** judgement; prefer A.
+
+## Say values, not adjectives
+
+- **[B]** Name the number: hex for colour, px for spacing, ms for duration, BPM for tempo. Exact values are the strongest measured correlate of a strong result; prose is not.
+- **[B]** Replace praise with prohibition. A banned list outperforms "make it beautiful".
+- **[B]** Keep the brief near 1,000 characters. Longer guidance did not score better.
+
+## Length
+
+- **[B]** 24 s default. 53 % of strong work is under 40 s, 23 % under 20 s.
+- **[B]** 3-6 scenes, one idea each. Two ideas means split.
+
+## Six sections, in order
+
+`inputs` → `direction` → `structure` → `build` → `gotchas` → `start`
+
+`inputs` asks once for audience, length, aspect, brand, source data. `direction` is one sentence plus the banned list. `structure` is the beat map. `build` is `seek(t)` only. `gotchas` names what will look wrong here. `start` shows the outline and stops.
+
+## Banned by default
+
+Full list: `slop.md`.
+
+bouncy easing · particle bursts · glows · gradients on chrome · mismatched icon strokes · dead time · template look · more than 6 words per line · stock-photo hands
+
+## Rhythm
+
+- **[B]** 120 BPM. At 4/4 a bar is 2 s, so 24 s is 12 bars. `mk fit --bpm 120 --bars 12` sets it.
+- **[A]** Something changes every beat, or the hold is deliberate (`flat-motion`).
+- **[A]** No three static scenes in a row (`flat-motion`): give each scene a `move` (`push-in`, `pan-l`, `orbit`).
+- **[A]** An accented scene holds ≥ 3 s (`hold-after-accent`).
+
+## Motion
+
+- **[B]** Median move 10 frames (0.33 s); enter by decelerating from oversize, never from zero.
+- **[B]** One easing family per video; springs only for direct manipulation.
+- **[A]** No linear ease except progress, countdown, chart (`linear-ease`).
+- **[B]** Cuts land on motion, not rest, every 0.3-2.3 s. End hold 0.6-1.4 s.
+- **[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. One accent per scene?
+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. You are the reviewer between the engine and the user, so look at the frames instead of 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. Shrink one still to phone width (about 390 px). If the headline or the diagram dies there, it dies for half the audience.
+4. Compare the first and last still. The opening must earn attention; the close must land, not merely stop.
+5. If `clip.mp4` exists, sample the start, middle and end of two transitions. Check for dead time and for cuts that land on rest.
+6. Read `preview.json` for the scene list, still timings, lint items and estimate. Note what the pack does not show: voice, motion between stills, and scenes without a still. If the clip was skipped, say that only stills are available.
+
+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   | One message per scene      | You can state the scene's point in one sentence; two points means two scenes                                                 |
+| 2   | A hook in the first second | The first still already has a subject, not a logo and a wait                                                                 |
+| 3   | Hierarchy                  | One headline, one support level, at most one hero number; the eye knows where to start                                       |
+| 4   | Legibility                 | Headline roughly 7-11% of frame height (9% typical), support 5-7%; no clipped or overlapping text                            |
+| 5   | Line length                | At most about six words per line; no paragraph set as a slide                                                                |
+| 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   | Restraint                  | One accent per scene; decoration that does not carry meaning is removed                                                      |
+| 8   | Motion with a purpose      | Every base scene has a reason to move; no three flat static scenes in a row                                                  |
+| 9   | Rhythm                     | Short-form cuts about every 0.3-2.3 s; longer scenes still change something; end hold about 0.6-1.4 s                        |
+| 10  | Truth                      | Every number has a source; no invented stat, logo, quote or customer                                                         |
+
+Numeric values are defaults, not laws. Break one when the brief earns it, and say why in the outline. At 360 px frame width, body x-height should stay at least 12 px and body leading at least 1.5; check the phone-width still, not only the 1080p one.
+
+## 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 five rows: message, hierarchy, craft, motion, sound. Fix every 1 before asking. If the average is below 3, improve the weakest row instead of adding decoration. If you score a 2, name the weakness in the ask; do not hide it behind "polished".
+
+## Fix in this order
+
+1. Broken or untrue: clipping, overlap, invented data, unreadable contrast.
+2. The idea: two messages in one scene, or no message at all.
+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: only after the picture works silent.
+
+## 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,38 @@
+# What never ships
+
+Distilled from a skill built on 53 frame-measured professional moments and an autopsy of rejected AI films. Every item below is a default nobody decided. Delete it; do not justify it.
+
+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.
+
+## Delete on sight
+
+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.**
+
+## Measured laws
+
+- Median move **10 frames (0.33 s)**; entries put the travel in the first 4-8 frames.
+- **Land decelerates, leave accelerates**; at most one spring per film.
+- **Almost nothing fades:** 3,392 transform entries against 584 opacity fades.
+- **Arrival decelerates from oversize** (a logo crashes in from ~3.5x); nothing grows from zero.
+- **No dead frame:** a held frame keeps one living thing.
+- **Cuts every 0.3-2.3 s, on motion**, never on rest.
+- **End hold 0.6-1.4 s**, and the ending gets smaller.
+
+## Type sizes, as a fraction of frame height
+
+Headline 7-11 % (9 typical) · support 5-7 % · hero number 22-29 %, spent once · wordmark 0.22-0.38 of width.
+
+## Fix order when it looks wrong
+
+broken or untrue → the idea → connections between beats → hierarchy and scale → timing → surface → sound.