@prestyj/cli 5.28.1 → 5.29.0

package/assets/motion/references/build-sheet.md

@@ -0,0 +1,206 @@
+# Build sheet
+
+Everything needed to write a composition with the move kit and to score it,
+in one place. It is the complete public surface: you do not need to open
+`moves.js`, `score-synth.mjs` or any helper's `--help` to use them.
+
+## Move kit (`window.GGMotionKit`)
+
+Install with `<node> "<motion bin>/library.mjs" kit <project>`, load
+`assets/kit/moves.js` after GSAP, then `const kit = window.GGMotionKit;`.
+Every move adds tweens to `tl` from time `at` and returns the time of its key
+moment, so the next move can start from it. Options are all optional; the
+value after `=` is the default.
+
+### Arrivals
+
+| Call                         | Options                                                                                                       | Returns                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `liftWords(tl, el, at, o)`   | `stagger=0.07`, `spring="snappy"`, `duration`, `from=115` (start yPercent)                                    | when the last word has mostly risen |
+| `dropLetters(tl, el, at, o)` | `height=260`, `fall=0.38`, `stagger=0.05`, `squash=0.24`, `spring="bouncy"`                                   | the last landing                    |
+| `reveal(tl, el, at, o)`      | `from="bottom"` (top, bottom, left, right), `duration=0.8`, `ease="snap"`                                     | end                                 |
+| `typewrite(tl, el, at, o)`   | `text` (default the element's text), `cps=22`, `jitter=0.4`, `seed=11`, `caret="▍"` or `false`, `caretHold=0` | when typing ends                    |
+| `tick(tl, path, at, o)`      | `duration=0.34`, `ease="snap"` (an SVG path)                                                                  | end                                 |
+| `pop(tl, el, at, o)`         | `from=0.3` (start scale), `spring="bouncy"`                                                                   | when it reads as arrived            |
+| `stamp(tl, el, at, o)`       | `duration=0.2`, `rotate=-4`, `from=2.4`                                                                       | the contact                         |
+
+### Handoffs
+
+| Call                               | Options                                                                                                              | Returns               |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| `reshape(tl, el, at, to, o)`       | `to` is `{ x, y, w, h, r }` or an element; `duration=0.85`, `ease="travel"`, or `spring`                             | when the change reads |
+| `openFrom(tl, stage, at, o)`       | `x`, `y` (default the centre), `width=1920`, `height=1080`, `from=0`, `duration=0.9`, `ease="travel"`                | end                   |
+| `diveThrough(tl, layer, at, o)`    | `x=960`, `y=540`, `zoom=16`, `duration=1`, `ease="drop"`, `next` (element shown at the end)                          | end                   |
+| `converge(tl, els, at, target, o)` | `target` is `{ x, y }`; `duration=0.85`, `stagger=0.05`, `bow=0.28`, `shrink=0.12`, `seed=5`, `ease="drop"`, `space` | the last arrival      |
+
+`converge` and `hop` own the element's transform: wrap an element to also
+pop or move it.
+
+**What each move animates**, so two moves on one element never fight:
+`liftWords` yPercent of its word spans; `dropLetters` y, scaleX, scaleY and
+opacity of its letters; `reveal` and `openFrom` clip-path; `tick`
+stroke-dashoffset; `pop` scale and opacity; `stamp` scale, rotation and
+opacity; `reshape` left, top, width, height and border-radius (position the
+element absolutely); `diveThrough` the layer's scale and the `next`
+element's visibility; `knock` rotation; `impact` the shake layer's x and
+rotation; `converge`, `hop` and `cursorPath` write `style.transform`
+directly. `typewrite` changes only the text.
+
+### Contact
+
+| Call                    | Options                                                                                                    | Returns          |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- |
+| `hop(tl, el, at, o)`    | `height=140`, `duration=0.5` (air time), `squash=0.2`                                                      | the landing      |
+| `impact(tl, at, o)`     | `shake` (a layer, not the camera world), `amount=16`, `duration=0.6`, `split: [left, right]`, `spread=140` | `at`             |
+| `knock(tl, els, at, o)` | `push=48`, `gap=0.11`, `tilt=7`, `axis="x"` or `"y"`                                                       | the last contact |
+
+### Camera
+
+`const cam = kit.camera(tl, world, keys, o)` drives `world`, a layer holding
+the whole scene in world pixels. It returns `{ plan, at(t), toScreen(t, x, y) }`.
+Make `world` an absolutely positioned element at left 0, top 0 (any size;
+place scenes inside it at their world coordinates). The camera owns its
+transform and sets its transform-origin to 0 0: never animate `world`
+yourself; move things inside it. A key's `x, y` is the world point shown at
+the centre of the frame, so `{ x: 960, y: 540, zoom: 1 }` shows the first
+1920 × 1080 of the world unchanged.
+
+- **Keys**: `[{ x, y, zoom=1, rotate=0 }, { at, x, y, zoom, rotate, move, duration }, ...]`.
+  The first key is the start. `move` is a curve name (`whip` by default,
+  `glide` for slow pushes, `cut` for a jump); `duration=0.9`.
+- **Options**: `width=1920`, `height=1080`, `duration` (default the last move),
+  `lead` (seconds each move starts early), `handheld: { amp=6, rotate=0.2, rate=0.5, seed=7 }`,
+  `rests: [[from, to], ...]` (exactly still there), `shakes: [{ at, amount=14, decay=9 }]`,
+  `layers: [{ el, depth }]` (0 pinned, 0.5 far, 1 the world, above 1 near).
+- Pure helpers: `cameraAt(plan, t, o)`, `atDepth(cam, depth)`, `toScreen(cam, x, y)`.
+
+### Deep zoom, light, texture
+
+| Call                                | Options                                                                                                                                                                                                                                              | Returns                     |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| `deepZoom(tl, world, at, o)`        | `anchor={x,y}` (world point, default the centre), `from=1`, `to=100` (any factor, up to about 1000), `screenFrom`, `screenTo` (where the anchor sits on screen; default the centre), `duration=3`, `ease="glide"`, `width`, `height`                 | end                         |
+| `lightGround(tl, el, at, o)`        | `rise=0.9`, `hold=0.6`, `drain=0.9`, `x`, `y` (default below the frame), `reach=1.15`, `color` (an `r, g, b` string), `ease="glide"`; on a canvas it paints, on other elements it sets `--light`, `--light-r`, `--light-x`, `--light-y` (with units) | the flood                   |
+| `rings(tl, el, at, o)`              | `count=4`, `duration=1.2`, `stagger=0.14`, `x`, `y` (default the centre), `ease="snap"`; reveals `el` (the next scene) through expanding rings                                                                                                       | fully shown                 |
+| `silk(tl, canvas, at, duration, o)` | `colors` (two or more hex), `seed=1`, `speed=0.08`, `scale=2.2`, `warp=1.2`, `cols=64`, `rows`                                                                                                                                                       | end                         |
+| `belt(tl, items, at, o)`            | `speed=240` (px/s), `stop` (timeline time it comes to rest), `spacing=360`, `axis="x"`, `direction=-1`, `rampIn=0.6`, `rampOut=0.9`, `origin`, `wrap`                                                                                                | `{ stop, at(t), clock(t) }` |
+| `brushStroke(tl, canvas, at, o)`    | `path` (SVG path) or `points`, `width=28`, `bristles=48`, `dryness=0.65`, `color`, `duration=0.8`, `seed=3`, `ease`                                                                                                                                  | when the brush lifts        |
+| `grain(el, o)`                      | `amount=0.05`, `seed=9`, `size=128`; a fixed overlay so dark gradients do not band; identical on every frame                                                                                                                                         | the tile's data URL         |
+
+### Print look (riso, screen print)
+
+| Call                             | Options                                                                                                                                                                                                                 | Returns              |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| `printInk(el, o)`                | `offset={x:0,y:0}` (fixed misregistration), `cell=7` (halftone spacing px), `angle=15`, `amount=0.86` (ink coverage), `rough=0.18`, `seed=3`; sets multiply blending and a halftone mask, so overlapping inks overprint | the tile's data URL  |
+| `misregister(tl, layers, at, o)` | `distance=26` px (or `from: [{x,y}, ...]`, one per layer), `seed=11`, `spring="soft"` or `ease` with `duration=0.8`, `apart=false` (true drifts apart instead of settling)                                              | when the inks settle |
+| `paperTexture(el, o)`            | `size=256`, `amount=0.06`, `tint="#fdf8ee"`, `fibres=160`, `seed=5`; identical on every frame                                                                                                                           | the tile's data URL  |
+
+Give each ink its own layer (one flat colour per layer, e.g. fluorescent pink
+and blue), lay them over paper, and let them settle into register on the beat.
+`printInk` uses the element's `mask-image` and `translate`. Pure helpers:
+`halftoneTile`, `misregisterAt`, `paperTile`.
+
+`deepZoom` owns `world`'s transform like the camera does: a dive or pull-out
+keeps its anchor exactly where it is keyed on screen at any depth. Pure
+helpers: `deepZoomAt`, `lightLevel`, `ringsAt`, `silkField`, `beltAt`,
+`grainTile`.
+
+### Cursor
+
+`const { end, presses } = kit.cursorPath(tl, cursor, at, stops, o)`. Stops are
+`{ x, y }` or `{ el }`, each with optional `click: true`, `hold=0.15` and
+`duration`. Options: `speed=1500` (px/s), `press=0.09`, `release=0.26`,
+`bow=0.12`, `tip=[6, 4]` (the hotspot), `space`. Script each pressed state and
+its sound from `presses`.
+
+### Sound
+
+`kit.cue(tl, at, sfx, { gain=1, x, pan, send, name })` marks a sound where the
+event happens. `x` is the object's screen x and pans with it; `pan` (-1..1)
+overrides it; `send` (0..1) is its distance. Then run
+`<node> "<motion bin>/cues.mjs" <project>`.
+
+### Timing and helpers
+
+- **Springs** (`spring` options): `snappy`, `bouncy`, `soft`, `heavy`, `whip`.
+  `kit.springEase(name)` gives a GSAP ease; `kit.settleTime(name)` gives its length.
+- **Curves** (`ease` and `move`): `snap`, `drop`, `glide`, `travel`, `whip`,
+  `settle`, `bounce`, `firm`, `cut`.
+- `drive(tl, at, duration, draw)`: calls `draw(localTime)` every frame, seeks
+  included; draw anything (counters, canvas, SVG) as a pure function of time.
+- `split(el, "words" | "chars", { mask })` returns spans; `centerOf(el, space)`
+  and `rectOf(el, space)` measure layout without transforms; `rng(seed)` and
+  `noise(seed, t)` are seeded.
+
+## Score (`score.json` for `score-synth.mjs`)
+
+Run `<node> "<motion bin>/score-synth.mjs" score.json assets/audio`. It writes
+`music.wav`, `sfx.wav` and `tempo-map.json` (beats, bars, hits, merges,
+balance) in under a second.
+
+```json
+{
+  "bpm": 84,
+  "duration": 24,
+  "seed": 3,
+  "style": "lofi",
+  "key": "F",
+  "scale": "major",
+  "chords": ["Fmaj7", "Em7", "Dm7", "Cmaj7"],
+  "sections": [
+    { "name": "intro", "from": 0, "energy": 0.3 },
+    { "name": "groove", "from": 2.9, "energy": 0.7 }
+  ],
+  "hits": [
+    { "t": 3.0, "sfx": "tap" },
+    { "beat": 8, "sfx": "chime" },
+    { "bar": 4, "sfx": "impact" }
+  ],
+  "cues": "cues.json",
+  "room": "room",
+  "duck": 0.55,
+  "ending": "resolve",
+  "air": true,
+  "music": true
+}
+```
+
+- **bpm** 40–220; **duration** in seconds; **seed** any integer.
+- **style**: `pulse` (four on the floor), `cinematic` (swells and low hits),
+  `minimal` (sparse keys), `lofi` (swung eighths, dusty keys, round bass,
+  soft kit, vinyl and tape wobble).
+- **key** and **scale** (`major` or `minor`) pick default chords; `chords`
+  overrides them.
+- **sections**: energy 0–1 brings parts in. In `lofi`: keys and vinyl alone
+  below 0.25, kick and snare from 0.25, hats from 0.4, the full kit from 0.5.
+- **hits**: `t` (seconds), `beat` or `bar`, `sfx`, optional `gain` (0–2),
+  `pan`, `send`, `name`. Sounds: `tap`, `press`, `knock`, `chime`, `thud`,
+  `plip`, `paper`, `breath`, `click`, `tick`, `snap`, `pop`, `glitch`,
+  `whoosh`, `whoosh-short`, `riser`, `swell`, `impact`, `sub-drop`, `sting`,
+  `shimmer`, `typing`.
+- **cues**: the file `cues.mjs` exported; its hits and camera air join these.
+- **room**: `none`, `booth`, `room`, `hall`. **duck**: music level under the
+  heaviest hit (1 = none). **ending**: `resolve` or `cut`. **air**: camera air
+  on or off. **music**: false for effects only.
+
+## Licensed or supplied music
+
+To cut a track the user supplies to the picture instead of synthesising one:
+`<node> "<motion bin>/music-fit.mjs" <track> --duration <s> [--land <trackTime>@<filmTime>] [--out assets/audio]`.
+It finds the tempo and downbeats, cuts whole bars on downbeats with short
+crossfades so the length is exact, lands the chosen downbeat (`--land`, snapped
+to the nearest one) on a film time, and writes `music.wav` plus
+`music-fit.json` with the downbeats in film time. Put hits on those downbeats.
+Constant tempo and 4/4 only.
+
+## Tall frame (1080 × 1920)
+
+Fill the frame and go big. The feeds cover only a bar over the top 138 px, a
+caption over the bottom 422 px and buttons over the right 179 px from y 840
+down; keep words out from under those.
+
+## Render
+
+| Step            | Command                                                                                                                              |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Final with blur | `<node> "<motion bin>/motion-blur.mjs" <project> renders/<name>-v1.mp4` (the one render, at feed loudness; run it in the background) |
+| Stills          | `<node> "<motion bin>/hyperframes.mjs" snapshot <project> --at 1,4,8,12 --describe false` (several at once)                          |

package/assets/motion/references/runtime/determinism-rules.md

@@ -15,7 +15,7 @@ For GSAP:
 - **Do not** call `tl.play()` for render-critical motion.
 - **Do not** create empty tweens only to set duration; use `data-duration` on the clip instead.
 
-Use the adjacent `gsap.md`, `gsap-timeline-and-labels.md` and `gsap-easing-and-stagger.md` for GSAP mechanics. These technical references do not choose the design; the video's plan in `frame.md` does.
+Use the adjacent `gsap.md`, `gsap-timeline-and-labels.md` and `gsap-easing-and-stagger.md` for GSAP mechanics. These technical references do not choose the design.
 
 ## Determinism Rules
 

package/assets/motion/references/runtime/gsap-easing-and-stagger.md

@@ -6,19 +6,19 @@ Built-in eases: `power1`, `power2`, `power3`, `power4`, `back`, `bounce`, `circ`
 
 Each has `.in`, `.out`, `.inOut` variants.
 
-| Ease                                       | Use for                                                                                                 |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| `power1.out`, `power2.out`                 | Gentle motion for secondary elements (a caption fade, a small shift). NOT the entrance default.         |
-| `power3.out` (house default), `power4.out` | The standard long-tail settle. Entrances, title cards, hero reveals.                                    |
-| `sine.inOut`                               | Long, slow, calm motion. Crossfades, ambient drift.                                                     |
-| `back.out(1.7)`                            | Overshoot then settle. A chosen register (playful, physical), never a default.                          |
-| `elastic.out(1, 0.3)`                      | Springy bounce. Same register rule; prefer a baked spring (see Spring Eases below).                     |
-| `expo.inOut`                               | Snappy, dramatic. Quick transitions between hero scenes.                                                |
-| `none` (linear)                            | Camera moves with timed counterpoint, mechanical motion.                                                |
+| Ease                                       | Use for                                                                                         |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `power1.out`, `power2.out`                 | Gentle motion for secondary elements (a caption fade, a small shift). NOT the entrance default. |
+| `power3.out` (house default), `power4.out` | The standard long-tail settle. Entrances, title cards, hero reveals.                            |
+| `sine.inOut`                               | Long, slow, calm motion. Crossfades, ambient drift.                                             |
+| `back.out(1.7)`                            | Overshoot then settle. A chosen register (playful, physical), never a default.                  |
+| `elastic.out(1, 0.3)`                      | Springy bounce. Same register rule; prefer a baked spring (see Spring Eases below).             |
+| `expo.inOut`                               | Snappy, dramatic. Quick transitions between hero scenes.                                        |
+| `none` (linear)                            | Camera moves with timed counterpoint, mechanical motion.                                        |
 
 Pick `.out` for entrances, `.in` for exits, `.inOut` for symmetric moves and continuous motion.
 
-**Smooth by default, bounce by choice** — the same rule as the Motion section of [`motion-language.md`](../motion-language.md): entrances default to `power3.out` or the baked critically-damped spring (see Spring Eases below); overshoot eases (`back` / `elastic` / `bounce`, or an underdamped spring) are a register the brief chooses for playful or physical work, never the house style.
+**Smooth by default, bounce by choice**: entrances default to `power3.out` or the baked critically-damped spring (see Spring Eases below); overshoot eases (`back` / `elastic` / `bounce`, or an underdamped spring) are a register the brief chooses for playful or physical work, never the house style.
 
 ## Easing Vocabulary (character & mood)
 
@@ -26,18 +26,18 @@ Easings are tone of voice: a video that only whispers is boring; one that varies
 
 The full palette by character (each family has `.in`, `.out`, `.inOut` variants):
 
-| Family               | Character                                                                    | Typical use                                                                                                                                  |
-| -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `power1`–`power4`    | Gentle (1) to aggressive (4) acceleration curves                             | General purpose. **power3 is the house workhorse**; power2 for gentle secondary motion, power4 for dramatic snaps                            |
+| Family               | Character                                                                    | Typical use                                                                                                                                   |
+| -------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `power1`–`power4`    | Gentle (1) to aggressive (4) acceleration curves                             | General purpose. **power3 is the house workhorse**; power2 for gentle secondary motion, power4 for dramatic snaps                             |
 | `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | Chosen register only (playful, physical), never a default. Keep N ≤ 2; prefer a baked spring at ζ 0.6–0.7 (physical settle, see Spring Eases) |
-| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | Same register rule; the baked spring (below) is the physical version                                                                         |
-| `bounce`             | Ball-drop bouncing                                                           | Physical-comedy register only (something literally dropping)                                                                                 |
-| `expo`               | Extreme acceleration curve (much steeper than power4)                        | Premium/luxury reveals, dramatic entrances                                                                                                   |
-| `sine`               | Smooth, organic, no hard edges                                               | Ambient float, breathing, Ken Burns, anything that loops. `.inOut` for yoyo motion                                                           |
-| `circ`               | Circular acceleration (starts very fast, ends very gentle or vice versa)     | Camera moves, scene transitions, orbital motion                                                                                              |
-| `steps(N)`           | Discrete N-step jumps, no interpolation                                      | Typing effects, cursor blink, counter ticks, retro/digital aesthetics                                                                        |
+| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | Same register rule; the baked spring (below) is the physical version                                                                          |
+| `bounce`             | Ball-drop bouncing                                                           | Physical-comedy register only (something literally dropping)                                                                                  |
+| `expo`               | Extreme acceleration curve (much steeper than power4)                        | Premium/luxury reveals, dramatic entrances                                                                                                    |
+| `sine`               | Smooth, organic, no hard edges                                               | Ambient float, breathing, Nolan Burns, anything that loops. `.inOut` for yoyo motion                                                            |
+| `circ`               | Circular acceleration (starts very fast, ends very gentle or vice versa)     | Camera moves, scene transitions, orbital motion                                                                                               |
+| `steps(N)`           | Discrete N-step jumps, no interpolation                                      | Typing effects, cursor blink, counter ticks, retro/digital aesthetics                                                                         |
 
-**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical — but bouncy is a register, not an emphasis tool; reach for it only when the brief's register is playful or physical. The register recorded in `frame.md` should guide which character fits — not a formula.
+**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical — but bouncy is a register, not an emphasis tool; reach for it only when the brief's register is playful or physical. The video's register should guide which character fits — not a formula.
 
 ## Defaults
 
@@ -116,17 +116,17 @@ tl.fromTo(
 );
 ```
 
-| dampingFraction   | overshoot       | register                                                                                                                                           |
-| ----------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **1.0 (default)** | none (monotone) | The house settle — the exact curve `power3.out` approximates. Product / enterprise / serious tone.                                                 |
-| 0.80–0.85         | ~1–1.5%         | "Alive, not bouncy" — the iOS system default register. The overshoot is felt, not seen.                                                            |
+| dampingFraction   | overshoot       | register                                                                                                                                               |
+| ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **1.0 (default)** | none (monotone) | The house settle — the exact curve `power3.out` approximates. Product / enterprise / serious tone.                                                     |
+| 0.80–0.85         | ~1–1.5%         | "Alive, not bouncy" — the iOS system default register. The overshoot is felt, not seen.                                                                |
 | 0.60–0.70         | ~5–10%          | Playful register, by choice (same rule as `back.out`, which this replaces — a spring's second-order settle reads physical where `back` reads cartoon). |
-| < 0.55            | > 12%           | Don't. Cartoon-wobble territory.                                                                                                                   |
+| < 0.55            | > 12%           | Don't. Cartoon-wobble territory.                                                                                                                       |
 
-| response  | duration (ζ=1) | feel                                                         |
-| --------- | -------------- | ------------------------------------------------------------ |
-| 0.25–0.35 | 0.37–0.51s     | tight snap — chips, small UI                                 |
-| 0.35–0.50 | 0.51–0.74s     | standard entrance                                            |
+| response  | duration (ζ=1) | feel                                                                                                                |
+| --------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
+| 0.25–0.35 | 0.37–0.51s     | tight snap — chips, small UI                                                                                        |
+| 0.35–0.50 | 0.51–0.74s     | standard entrance                                                                                                   |
 | 0.50–0.70 | 0.74–1.03s     | weighted hero landing — when the shot opens on it, start it early so the subject is seen within about half a second |
 
 Craft notes:

package/assets/motion/references/runtime/inputs-and-assets.md

@@ -1,8 +1,7 @@
 # GG runtime inputs and assets
 
-This is implementation support, not a creative workflow. The video's plan in
-`frame.md` sets the design. Bind approved text, fonts, colours, logos and media
-without adding a second look-selection process.
+This is implementation support, not a creative workflow. Bind approved text,
+fonts, colours, logos and media without adding a second look-selection process.
 
 `hf` in these references is shorthand for the exact bundled launcher command
 in the system prompt; expand it, never run bare `hf` or `npx hyperframes`.
@@ -14,10 +13,9 @@ package installs, cloud rendering or publishing without explicit permission.
 - Keep original captures/uploads in `sources/`; use local `assets/` for the
   files consumed by the composition. Never overwrite originals or finished renders.
 - A reusable kit lives at `brand-kits/<slug>/Motion.md` in the Motion workspace.
-  Keep it read-only for ordinary video work. Record the selected kit and permitted
-  bindings in `frame.md`; preserve legacy briefs rather than duplicating plans.
-- Record fit, crop and in-point choices in `frame.md`. A longer title or a
-  different aspect ratio calls for a deliberate layout adjustment, not a silent
+  Keep it read-only for ordinary video work; preserve legacy briefs rather than
+  duplicating plans.
+- A longer title or a different aspect ratio calls for a deliberate layout adjustment, not a silent
   crop.
 - Root output duration is a static composition contract. If an input changes
   the duration, update the authored root explicitly; a runtime variable cannot
@@ -55,8 +53,5 @@ Preserve credits, cue maps and SFX analysis. Copy only used
 assets into the video project. The plan or user determines whether
 sound belongs in the video; do not automatically add music or hits.
 
-Use `motion_check` once on the current render as specified by `video-qa`; it
-runs the media helpers and returns images for this agent to inspect. Do not
-repeat its checks as a separate checklist. Request permission before
-installing missing FFmpeg/browser software; a detector setup failure does not
-justify skipping validation. Never upload user files to resolve a local blocker.
+Request permission before installing missing FFmpeg/browser software. Never
+upload user files to resolve a local blocker.

package/assets/motion/references/runtime/lint-validate-inspect.md

@@ -1,6 +1,6 @@
 # lint, check, snapshot
 
-Motion's `motion_check` tool already runs `check`, including lint, runtime, layout and contrast, and returns rendered images. Do not run the commands below as additional delivery gates. Use them only for targeted debugging of a concrete failure. `snapshot` captures still frames and zoomed crops; `validate`, `inspect` and `layout` are deprecated because `check` covers them.
+Motion does not run these as delivery gates. Use them only for targeted debugging of a concrete failure. `snapshot` captures still frames and zoomed crops; `validate`, `inspect` and `layout` are deprecated because `check` covers them.
 
 ## Discipline (motion-heavy work)
 
@@ -9,7 +9,7 @@ For a concrete problem during authoring or editing:
 - Use `lint` for a static-code failure or `check --snapshots` for runtime/layout evidence, not both by default.
 - Look at the returned images before changing the animation: a diagnostic must not become an alternative art direction.
 - Treat layout errors as defects unless a snapshot proves the layering is intentional, in which case mark it with `data-layout-allow-overflow` / `data-layout-allow-overlap` / `data-layout-allow-occlusion` / `data-layout-allow-caption-zone` (caption band only).
-- Existing meaningful motion assertions may remain, but GG does not require a new `*.motion.json` sidecar for every video. Use rendered-pixel checks and the `video-qa` evidence process for liveness, especially for canvas/WebGL. No detector or screenshot proves playback was watched.
+- Existing meaningful motion assertions may remain, but EZ does not require a new `*.motion.json` sidecar for every video. Use stills of the render for liveness, especially for canvas/WebGL. No detector or screenshot proves playback was watched.
 
 ## lint
 
@@ -68,7 +68,7 @@ hf check --frame-check     # media (img/svg/video/canvas) out-of-frame detection
 
 `--caption-zone` takes fractional band geometry (`x0/y0/x1/y1` required, 0-1 fractions of the composition's own canvas, portrait included) with optional `severity` and comma-separated `seek` fractions; it flags a text element's DOM box (`getBoundingClientRect`) that overlaps the band. Waive intentional lower-third copy with `data-layout-allow-caption-zone` on the element or its nearest wrapper (see Escape hatches). `--frame-check` reports media elements breaching the canvas beyond `max(120px, 6% of the min canvas dimension)`.
 
-**Fixing contrast errors** — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold). The finding's `suggestedColor` already picks the nearest compliant color in the right direction (brighten on dark backgrounds, darken on light); apply an allowed correction, or resolve a conflict with locked source/brand colours before changing them. Recheck the changed output through `motion_check`; do not duplicate the full diagnostic checklist.
+**Fixing contrast errors** — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold). The finding's `suggestedColor` already picks the nearest compliant color in the right direction (brighten on dark backgrounds, darken on light); apply an allowed correction, or resolve a conflict with locked source/brand colours before changing them. Look at a still of the changed moment; do not run the full diagnostic checklist.
 
 ## Motion verification (`*.motion.json` sidecar)
 

package/assets/motion/references/runtime/minimal-composition.md

@@ -72,4 +72,4 @@ This pattern is **standalone** (top-level `index.html`) — no `<template>` wrap
 
 For phone-first video, set the viewport meta to `width=1080, height=1920`, give the root `data-width="1080"` and `data-height="1920"`, and render with the matching size (`--resolution portrait`). Everything else stays the same.
 
-Size type against the frame's width, not its height: a 96 px headline that suits a 1920 px-wide frame takes over half the width of a 1080 px one, so check that the longest word fits. When the video will play in a feed (Reels, TikTok, Shorts), keep text, logos and key subjects out of the areas the app covers. Meta asks for the top 14%, the bottom 35% and 6% on each side to stay clear (about 270 px, 670 px and 65 px at 1080×1920); TikTok covers a similar band at the bottom and a column of buttons on the right.
+Size type against the frame's width, not its height: a 96 px headline that suits a 1920 px-wide frame takes over half the width of a 1080 px one, so check that the longest word fits. When the video will play in a feed (Instagram, TikTok, YouTube Shorts), keep words out from under the apps' own bar, caption and buttons: on 1080×1920, the top 138 px, the bottom 422 px and the right 179 px from y 840 down.

package/assets/motion/references/runtime/preview-render.md

@@ -57,7 +57,7 @@ Failure modes:
 
 | Code                       | Meaning                                                                    |
 | -------------------------- | -------------------------------------------------------------------------- |
-| `preview-not-running`      | Start Studio first with `hf preview --background`.            |
+| `preview-not-running`      | Start Studio first with `hf preview --background`.                         |
 | `ambiguous-preview-server` | Multiple matching Studio servers are open; rerun with one listed `--port`. |
 | `preview-port-mismatch`    | The requested `--port` is not one of the matching Studio servers.          |
 | `no-selection`             | Studio is open, but the user has not selected an element yet.              |
@@ -99,7 +99,7 @@ Validation runs before any server boots, so an invalid value exits cleanly witho
 
 ## render
 
-> A clear video request authorizes a new, versioned local render. Preview is available when useful, not a mandatory approval checkpoint. Ask only for unresolved inputs, material choices or permission to overwrite an existing export; check the result once through `motion_check`.
+> A clear video request authorizes a new, versioned local render. Preview is available when useful, not a mandatory approval checkpoint. Ask only for unresolved inputs, material choices or permission to overwrite an existing export. The final render screens itself for harmful flashing.
 
 ```bash
 hf render                                # standard MP4 from cwd
@@ -153,4 +153,4 @@ hf render --docker                       # byte-identical
 Keep renders and diagnostics local. Feedback submission, issue filing, publishing
 and cloud rendering are not automatic completion steps. They require explicit
 user authorization; do not send source files, private assets or logs upstream.
-Use GG's `reveal.mjs` to select the delivered local file.
+Use EZ's `reveal.mjs` to select the delivered local file.

package/assets/motion/skills/app-walkthrough/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: app-walkthrough
+description: Job skill for showing how an app or product is used, step by step, on rebuilt real screens. Adds walkthrough questions, the screen-rebuild method, moves and pitfalls. Load once, before asking.
+---
+
+# App walkthrough
+
+A walkthrough is the product in use: open it, do the task, get the
+result. Build it as the `motion` skill describes; this page adds what is
+specific to walkthroughs.
+
+## Ask (on the motion skill's single card)
+
+- "Which task should the video walk through?" Offer the two or three tasks the
+  prompt or screenshots suggest, plus "Let EZ Motion choose".
+- "Where will people mostly watch this?" (from the `motion` skill).
+- "Should it have music?" (from the `motion` skill).
+- "Which idea should we go with?" Pitches below, recommended marked, plus "Let
+  EZ Motion choose".
+
+Without screenshots, end with one plain line: "Send me a screenshot of each
+step of that task, in order. Phone photos of the screen are fine." Do not ask
+for a shot list.
+
+## Rebuild the screens
+
+Rebuild each screen as HTML at the screenshot's own size, with its states
+scripted, its text big enough to read, one close-up per step and a cursor that
+presses. Start from the `screen-replica-steps` piece. Hide account names,
+emails and anything private. Data on screen comes from
+their screenshots or files, never invented.
+
+## Ideas that suit walkthroughs
+
+- **Follow the hand.** One continuous camera that rides the cursor from step to
+  step; each click opens the next framing.
+- **The request becomes the result.** The thing the user types or picks grows
+  into what the app gives back.
+- **The app's own transition.** Use the app's real sheet, drawer or page
+  animation as the handoff between steps.
+- **Before the tap, after the tap.** Each step is a held "before" frame, one
+  press, and the change it causes.
+
+## Beats that work
+
+- Open on the moment that matters most (the result), then rewind to how it is
+  done, or open straight on the first step with the cursor already moving.
+- One step per beat, with a close-up on the control being used.
+- Hold still on the result long enough to read it. That is the rest.
+- End on the app's name or icon and where to get it.
+
+## Moves
+
+`kit.cursorPath` with press and release; `kit.camera` following the cursor;
+`kit.typewrite` for typed input; `kit.tick` for completed steps;
+`kit.reshape` from the pressed control into the result. Pieces:
+`screen-replica-steps`, `request-to-result`, `cursor-click`, `phone-frame`,
+`browser-window`, `camera-rig`.
+
+## Pitfalls
+
+- Screenshots placed flat and slid around. Rebuild them.
+- Whole screens shown small: text unreadable at phone size.
+- The cursor teleporting, or changes happening without a click.
+- Steps of equal length with no rest on the result.
+- Made-up names, numbers or results.

package/assets/motion/skills/before-after/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: before-after
+description: Job skill for a before-and-after video, showing life without the product, then with it. Adds before/after questions, idea patterns, moves and pitfalls. Load once, before asking.
+---
+
+# Before and after
+
+The viewer should feel the difference, not read it. Build it as the `motion`
+skill describes; this page adds what is specific to comparisons.
+
+## Ask (on the motion skill's single card)
+
+- "What's the annoying part of life without it?" Offer two or three guesses
+  from the prompt, plus "Let EZ Motion choose".
+- "Where will people mostly watch this?" (from the `motion` skill).
+- "Should it have music?" (from the `motion` skill).
+- "Which idea should we go with?" Pitches below, plus "Let EZ Motion choose".
+
+## Ideas that suit comparisons
+
+- **The same task, twice, side by side.** Both halves start together; the
+  "before" side keeps getting interrupted while the "after" side simply
+  finishes. Then the losing half falls away.
+- **One drawing, broken and whole.** A shape or line is drawn twice: broken up
+  by the problem on one side, unbroken on the other. The whole one becomes the
+  logo.
+- **Rewind.** Play the messy version, rewind it in one motion, and play it
+  again with the product.
+
+The comparison must use one measure the viewer can see (time, steps, mess),
+shown on both sides in the same way.
+
+## Beats that work
+
+- Set up both sides in one frame so the comparison is fair.
+- Let the problem build, quickening, on the "before" side.
+- A held breath when the "after" side finishes: a real, still rest.
+- The winning side's result carries into the name.
+
+## Moves
+
+`kit.impact` for interruptions; `kit.camera` with a local shake on one side
+only; `kit.openFrom` from the finished result; `kit.converge` into the logo.
+Pieces: `before-after-split`, `open-from-subject`, `gather-to-logo`,
+`camera-rig`.
+
+## Pitfalls
+
+- Two separate scenes, before then after, with a cut between. Show them
+  together, or carry one into the other.
+- An unfair comparison: different tasks or different measures on each side.
+- Captions that state the difference instead of showing it.
+- Invented statistics about the improvement.

package/assets/motion/skills/brand-kit/SKILL.md

@@ -16,10 +16,9 @@ Do not overwrite a reusable kit while editing a video.
    inspect existing kits and the user's supplied sources before asking a question.
 2. Map identity to the video's palette roles, type roles, logo and media.
    Preserve required product names, taglines and assets.
-3. Record the selected kit and bindings in the video's `frame.md`.
 
-The kit's colours, fonts and motion personality feed the plan: they replace
-the motion-language defaults and set its palette, type and register. Required
+The kit's colours, fonts and motion personality replace any default and set
+the video's palette, type and feel. Required
 identity outranks taste; if it conflicts with a requested treatment, resolve
 that actual choice with the user instead of silently changing the font, logo or
 colours.
@@ -36,6 +35,7 @@ do not fabricate a logo or claim a guessed font was found on the website.
 
 Create a reusable kit only when requested or needed for the user's brand
 workflow. Preserve the established `Motion.md` YAML frontmatter contract:
+
 - `name`, `kit` (lowercase kebab-case slug), `source` (origin and capture date).
 - `colors`: known `bg`, `surface`, `text`, `text-muted`, `primary`, `accent` roles.
 - `typography`: evidenced `display`, `body`, `mono` entries with family, weight,

package/assets/motion/skills/dev-tool-video/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: dev-tool-video
+description: Job skill for a video about a developer tool: a CLI, API, library, SDK or editor plugin. Adds questions, terminal and code moves, ideas and pitfalls. Load once, before asking.
+---
+
+# Developer tool video
+
+Developers trust what they can see running. Build it as the `motion` skill
+describes; this page adds what is specific to developer tools.
+
+## Ask (on the motion skill's single card)
+
+- "What's the one command or line of code that shows it best?" Offer the
+  README's quick-start as recommended, plus "Let EZ Motion choose".
+- "Where will people mostly watch this?" (from the `motion` skill).
+- "Should it have music?" (from the `motion` skill).
+- "Which idea should we go with?" Pitches below, plus "Let EZ Motion choose".
+
+Read the repository or docs directly: the README, real commands, real output
+and the real logo. Never run the repository's scripts.
+
+## Ideas that suit developer tools
+
+- **One command, the whole story.** The command types, the output streams, and
+  the result it produced grows out of the last line.
+- **The diff.** The code before, a few lines change, and the effect appears
+  beside it.
+- **The pipe.** Input flows through the tool as one shape and comes out
+  transformed; the camera follows the shape.
+
+## Beats that work
+
+- Start typing in the first second. Developers skim.
+- Type at a human but quick pace; let output arrive in real-looking chunks,
+  not all at once.
+- Close-up on the line that matters, then pull back to the result.
+- End on the install command and the name, held still.
+
+## Moves
+
+`kit.typewrite` for commands and code; `kit.tick` for passing steps;
+`kit.reshape` from the output line into the result; `kit.camera` for close-ups
+on a line. Pieces: `request-to-result`, `scale-dive`, `morph-carry`,
+`camera-rig`.
+
+## Look
+
+A terminal or editor look from the tool's own brand or the user's theme, with a
+monospaced face from the bundled fonts; real syntax colours, readable at phone
+size (zoom in on the relevant lines rather than showing the whole file).
+
+## Pitfalls
+
+- Fake commands, flags or output. Use the real ones from the docs.
+- Code too small to read.
+- Walls of text with no visible cause and effect.
+- Matrix-style rain, glitch effects or hacker clichés.