npm - creator-editing-studio - Versions diffs - 1.0.20260930 → 1.0.20261002 - Mend

creator-editing-studio 1.0.20260930 → 1.0.20261002

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/package.json +1 -1
package/template/CLAUDE.md +233 -226
package/template/STYLE.md +179 -165
package/template/templates/STYLE.md +179 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "creator-editing-studio",
-  "version": "1.0.20260930",
+  "version": "1.0.20261002",
   "description": "Scaffolds a Creator Editing OS studio — components, scripts and rules for editing video from a plain-English brief.",
   "license": "UNLICENSED",
   "type": "module",

package/template/CLAUDE.md CHANGED Viewed

@@ -48,250 +48,257 @@ Everything else in `src/design/` is the system and should be left alone. If a vi
 a colour or a size that is not in tokens.ts, the answer is to add it to tokens.ts, never to
 type it into a component.
-## Non-negotiables
-1. **No magic numbers.** Durations, curves, springs, staggers, blur come from `src/design/motion.ts`.
-   Colours, fonts, sizes, spacing come from `src/design/tokens.ts`. If a needed token does not
-   exist, add it to the token file (with a comment) instead of inlining a value.
-2. **Timing derives from the spine.** Animation start frames come from word timestamps, beats,
-   or other elements' timings via helpers — never hand-typed frame numbers.
-3. **`npm run check` and `motion-check --scale=2` must pass** before any render is shown to the user.
-4. **Verify visually before claiming done** (see Verification). Never say something "looks good"
-   without having rendered and viewed the frames.
+## Non-negotiables
+1. **No magic numbers.** Durations, curves, springs, staggers, blur come from `src/design/motion.ts`.
+   Colours, fonts, sizes, spacing come from `src/design/tokens.ts`. If a needed token does not
+   exist, add it to the token file (with a comment) instead of inlining a value.
+2. **Timing derives from the spine.** Animation start frames come from word timestamps, beats,
+   or other elements' timings via helpers — never hand-typed frame numbers.
+3. **`npm run check` and `motion-check --scale=2` must pass** before any render is shown to the user.
+4. **Verify visually before claiming done** (see Verification). Never say something "looks good"
+   without having rendered and viewed the frames.
 ---
-## The 12 motion laws
-1. **No linear easing** — except constant-velocity loops/scrolls (mark with `// motion-ok`).
-2. **Entrances ease-out (`EASE.out`), exits ease-in (`EASE.in`), on-screen A-to-B moves ease-in-out (`EASE.inOut`).**
-3. **Exits are faster than entrances** — `EXIT_RATIO` (0.65). Use `exitFrames()`.
-4. **Max 2–3 animated properties per element.** No fade + scale + rotate + blur together.
-5. **Never opacity alone.** Pair with 8–24px travel or scale >= 0.94. Opacity completes at
-   `OPACITY_LEAD` (60%) of the transform.
-6. **Never scale from below 0.9.** Text scaling from zero is the #1 AI-edit tell.
-7. **Blur-in capped at 12px**, fully resolved before the transform ends.
-8. **Groups always stagger** (`STAGGER.tight/normal/dramatic`). Never simultaneous.
-9. **Distance couples to duration sub-linearly** (`travelFrames()`), never linearly.
-10. **Anything that moves fast is motion-blurred** (see Smoothness system). No hard edge may jump
-    across the frame unblurred.
-11. **Readable hold:** text stays fully visible >= `readFrames(text)` (min 0.9s, +55ms/word).
-12. **Continuity:** every transition inherits the outgoing motion (see below).
-### Continuity (what makes it feel connected, not cut together)
-- **Shared elements never re-enter.** If an element exists across two beats, `morph()` its
-  position/size/radius between layouts; never exit and re-animate it. (TransitionTest: the
-  eyebrow dot stays on screen and grows into the next card's icon tile.)
-- **Velocity handoff.** An exit toward a direction is answered by an entrance continuing that
-  direction — `handoff(exitTo)`.
-- **Overlap, never gap.** The next beat starts before the previous one settles —
-  `nextBeatAt(prevSettled)`.
-- **One camera over cuts.** Lay scenes out on one canvas and glide a camera between them
-  (`src/lib/camera.ts`) instead of hard-cutting between unrelated layouts. Content that should
-  stay put during a move (shared elements) lives in screen space, outside the camera.
-- **Nothing is cut off.** Compute exit start times backward from the end so the slowest,
-  most-staggered exit completes on or before the last frame.
-- **Sound glues cuts.** Whooshes start `TRANSITION.sfxLeadMs` before a visual change and tail
-  `sfxTailMs` after.
+## The 12 motion laws
+1. **No linear easing** — except constant-velocity loops/scrolls (mark with `// motion-ok`).
+2. **Entrances ease-out (`EASE.out`), exits ease-in (`EASE.in`), on-screen A-to-B moves ease-in-out (`EASE.inOut`).**
+3. **Exits are faster than entrances** — `EXIT_RATIO` (0.65). Use `exitFrames()`.
+4. **Max 2–3 animated properties per element.** No fade + scale + rotate + blur together.
+5. **Never opacity alone.** Pair with 8–24px travel or scale >= 0.94. Opacity completes at
+   `OPACITY_LEAD` (60%) of the transform.
+6. **Never scale from below 0.9.** Text scaling from zero is the #1 AI-edit tell.
+7. **Blur-in capped at 12px**, fully resolved before the transform ends.
+8. **Groups always stagger** (`STAGGER.tight/normal/dramatic`). Never simultaneous.
+9. **Distance couples to duration sub-linearly** (`travelFrames()`), never linearly.
+10. **Anything that moves fast is motion-blurred** (see Smoothness system). No hard edge may jump
+    across the frame unblurred.
+11. **Readable hold:** text stays fully visible >= `readFrames(text)` (min 0.9s, +55ms/word).
+12. **Continuity:** every transition inherits the outgoing motion (see below).
+### Continuity (what makes it feel connected, not cut together)
+- **Shared elements never re-enter.** If an element exists across two beats, `morph()` its
+  position/size/radius between layouts; never exit and re-animate it. (TransitionTest: the
+  eyebrow dot stays on screen and grows into the next card's icon tile.)
+- **Velocity handoff.** An exit toward a direction is answered by an entrance continuing that
+  direction — `handoff(exitTo)`.
+- **Overlap, never gap.** The next beat starts before the previous one settles —
+  `nextBeatAt(prevSettled)`.
+- **One camera over cuts.** Lay scenes out on one canvas and glide a camera between them
+  (`src/lib/camera.ts`) instead of hard-cutting between unrelated layouts. Content that should
+  stay put during a move (shared elements) lives in screen space, outside the camera.
+- **Nothing is cut off.** Compute exit start times backward from the end so the slowest,
+  most-staggered exit completes on or before the last frame.
+- **Sound glues cuts.** Whooshes start `TRANSITION.sfxLeadMs` before a visual change and tail
+  `sfxTailMs` after.
 ---
-## Smoothness system (every one of these was a real defect found by motion-check)
-- **Use the components, not raw transforms.** `<Presence>`, `<MaskReveal>`, `<HighlightMark>`,
-  `<RollingNumber>` add velocity motion blur automatically. Anything else that moves wraps its
-  moving element in `<VelocityBlur vx vy>` with `perFrame()` velocities.
-- **Velocity motion blur** (`VelocityBlur`): directional blur sized to this frame's movement with
-  a 180-degree shutter; fades to zero as the element settles. Near-free to render.
-- **Wipes** use `wipeMask(p, perFrame(...))`: the leading edge softens with speed. Never wipe with
-  a hard `clipPath` edge.
-- **Camera moves**: wrap the camera canvas in a full-frame `VelocityBlur` with `bleed={0}` and
-  `overflow: hidden`, velocity from `cameraShot` (see TransitionTest).
-- **Zooms / rotations** (not translations): use `<MotionBlur active>` (temporal sampling, centred
-  on the frame so toggling it never shifts timing). It costs 10x render time while active —
-  enable only during the move. Never use `@remotion/motion-blur`'s `CameraMotionBlur`: it samples
-  ahead of the frame, so switching it on/off causes a timing hitch.
-- **Counters roll, never tick.** Use `<RollingNumber>`. A counting number changes glyphs in single
-  frames as it slows, which motion-check flags as pops.
-- **Never `will-change`.** It makes each parallel render tab cache text at a different sub-pixel
-  position, so settled elements flicker between 4 versions. (Lint enforces this.)
-- **Screen recordings used as b-roll usually scroll in steps** (they judder). Use a still frame with a
-  smooth `ScreenView` pan instead, and blur names on the still.
-- **Presence `dur` sets entrance AND exit length.** `dur="instant"` makes exits last 3 frames (a snap) —
-  for containers that only fade in, use at least `"base"`.
-- **Final renders are supersampled at `--scale=2`**, then downscaled to 1080x1920. At 1x, Chrome
-  snaps text to whole pixels, so the slow tail of every ease-out steps ("move 1px, hold, move 1px")
-  and motion-check reports stutters. Run motion-check with the same `--scale`.
-- **Frame rate:** match the footage. If footage is 60fps, build at 60 — per-frame jumps halve.
-  All tokens are in ms, so compositions work at either rate.
+## Smoothness system (every one of these was a real defect found by motion-check)
+- **Use the components, not raw transforms.** `<Presence>`, `<MaskReveal>`, `<HighlightMark>`,
+  `<RollingNumber>` add velocity motion blur automatically. Anything else that moves wraps its
+  moving element in `<VelocityBlur vx vy>` with `perFrame()` velocities.
+- **Velocity motion blur** (`VelocityBlur`): directional blur sized to this frame's movement with
+  a 180-degree shutter; fades to zero as the element settles. Near-free to render.
+- **Wipes** use `wipeMask(p, perFrame(...))`: the leading edge softens with speed. Never wipe with
+  a hard `clipPath` edge.
+- **Camera moves**: wrap the camera canvas in a full-frame `VelocityBlur` with `bleed={0}` and
+  `overflow: hidden`, velocity from `cameraShot` (see TransitionTest).
+- **Zooms / rotations** (not translations): use `<MotionBlur active>` (temporal sampling, centred
+  on the frame so toggling it never shifts timing). It costs 10x render time while active —
+  enable only during the move. Never use `@remotion/motion-blur`'s `CameraMotionBlur`: it samples
+  ahead of the frame, so switching it on/off causes a timing hitch.
+- **Counters roll, never tick.** Use `<RollingNumber>`. A counting number changes glyphs in single
+  frames as it slows, which motion-check flags as pops.
+- **Never `will-change`.** It makes each parallel render tab cache text at a different sub-pixel
+  position, so settled elements flicker between 4 versions. (Lint enforces this.)
+- **Screen recordings used as b-roll usually scroll in steps** (they judder). Use a still frame with a
+  smooth `ScreenView` pan instead, and blur names on the still.
+- **Presence `dur` sets entrance AND exit length.** `dur="instant"` makes exits last 3 frames (a snap) —
+  for containers that only fade in, use at least `"base"`.
+- **Final renders are supersampled at `--scale=2`**, then downscaled to 1080x1920. At 1x, Chrome
+  snaps text to whole pixels, so the slow tail of every ease-out steps ("move 1px, hold, move 1px")
+  and motion-check reports stutters. Run motion-check with the same `--scale`.
+- **Frame rate:** match the footage. If footage is 60fps, build at 60 — per-frame jumps halve.
+  All tokens are in ms, so compositions work at either rate.
 ---
-## Design rules
-**Read `STYLE.md` before any design decision.** It is the house style (type scale, layout, motion,
-sound, approved and rejected beats) and wins over anything below or in a reference. Update it
-whenever the user approves or rejects something.
-- Everything visual comes from `src/design/tokens.ts`, which is yours to define.
-- **Brand essentials:** your display typeface only, at every weight (headlines/stats 800). One accent: accent
-  `your accent` on ink and cream/white. No blue, no purple, no serif. Signature emphasis is the accent
-  marker behind the key phrase — use `<HighlightMark>`; don't invent other emphasis styles.
-  Headlines are short two-part fragments with the payoff highlighted. Numbers are shown raw and
-  bold ("$1.3M", "11x") and roll in. Eyebrows are uppercase pills with a accent-ringed dot.
-  Radii are generous, shadows soft, buttons/badges pills.
-- Secondary text uses `COLOR.fgSecondary`; `COLOR.fgMuted` fails contrast on cream — decoration only.
-- **User style decisions (first project):**
-  - Captions are **crisp white** (`CAPTION` token, tight + soft dark shadow). Never ink text with a light glow.
-    Over the cream background white is invisible, so in card layouts captions go **inside the video
-    card's bottom edge** on the card's dark scrim (`StageState.scrim`).
-  - Big headline text is **accent with a glow** (`HeroBlock` / `HeroTag`, `heroGlow()`).
-  - Pointer is a **solid accent arrow** like the reference (`Cursor`), ~68px.
-  - Brand logos are **real full-colour logos** (`LogoIcon`, SVG Logos CC0 via `src/design/logos.json` —
-    extract only the icons used). Never approximate a logo that isn't in the set; use a neutral
-    icon and ask for the official file (Klaviyo is missing).
-  - A corner tag (e.g. "11 MINUTES" pill) is removed when the video returns full screen.
-- **Text behind the subject must stay readable:** the head covers only the lower ~20–30% of the
-  headline. Head height changes shot to shot (leaning forward lifts it ~80px) — check a still of
-  EVERY hero moment and raise the block (`top`; put labels above as `eyebrow`) where needed.
-- Keep accent highlights away from the accent background glow so they don't disappear into it.
-- Stats use proportional figures, not tabular (tabular makes "11" look gappy in your display typeface).
-- **Web design systems do not map 1:1 to video.** Keep colour, font families/weights, type-scale
-  ratios, radii, spacing rhythm, iconography and imagery style — but rescale sizes for a
-  1080-wide frame viewed on a phone (body roughly 40–48px, not 16px). Web UI components mostly
-  do not apply.
-- Respect safe zones: `LAYOUT.safeTop` / `LAYOUT.safeBottom` for Reels/Shorts UI.
-- Text contrast >= 4.5:1 against whatever is behind it, including over footage.
-- Draw graphics in code (SVG/CSS) so every part can animate. Use flat images only for things
-  that must be real (logos, screenshots, photos). Avoid AI-generated imagery for anything the
-  viewer is meant to look at.
-- Icons: SVG drawn in code or an installed icon library, never image files.
+## Design rules
+**Read `STYLE.md` before any design decision.** It is the house style (type scale, layout, motion,
+sound, approved and rejected beats) and wins over anything below or in a reference. Update it
+whenever the user approves or rejects something.
+- Everything visual comes from `src/design/tokens.ts`, which is yours to define.
+- **Brand essentials:** your display typeface only, at every weight (headlines/stats 800). One accent: accent
+  `your accent` on ink and cream/white. No blue, no purple, no serif. Signature emphasis is the accent
+  marker behind the key phrase — use `<HighlightMark>`; don't invent other emphasis styles.
+  Headlines are short two-part fragments with the payoff highlighted. Numbers are shown raw and
+  bold ("$1.3M", "11x") and roll in. Eyebrows are uppercase pills with a accent-ringed dot.
+  Radii are generous, shadows soft, buttons/badges pills.
+- Secondary text uses `COLOR.fgSecondary`; `COLOR.fgMuted` fails contrast on cream — decoration only.
+- **User style decisions (first project):**
+  - Captions are **crisp white** (`CAPTION` token, tight + soft dark shadow). Never ink text with a light glow.
+    Over the cream background white is invisible, so in card layouts captions go **inside the video
+    card's bottom edge** on the card's dark scrim (`StageState.scrim`).
+  - Big headline text is **accent with a glow** (`HeroBlock` / `HeroTag`, `heroGlow()`).
+  - Pointer is a **solid accent arrow** like the reference (`Cursor`), ~68px.
+  - Brand logos are **real full-colour logos** (`LogoIcon`, SVG Logos CC0 via `src/design/logos.json` —
+    extract only the icons used). Never approximate a logo that isn't in the set; use a neutral
+    icon and ask for the official file (Klaviyo is missing).
+  - A corner tag (e.g. "11 MINUTES" pill) is removed when the video returns full screen.
+- **Text behind the subject must stay readable:** the head covers only the lower ~20–30% of the
+  headline. Head height changes shot to shot (leaning forward lifts it ~80px) — check a still of
+  EVERY hero moment and raise the block (`top`; put labels above as `eyebrow`) where needed.
+- Keep accent highlights away from the accent background glow so they don't disappear into it.
+- Stats use proportional figures, not tabular (tabular makes "11" look gappy in your display typeface).
+- **Web design systems do not map 1:1 to video.** Keep colour, font families/weights, type-scale
+  ratios, radii, spacing rhythm, iconography and imagery style — but rescale sizes for a
+  1080-wide frame viewed on a phone (body roughly 40–48px, not 16px). Web UI components mostly
+  do not apply.
+- Respect safe zones: `LAYOUT.safeTop` / `LAYOUT.safeBottom` for Reels/Shorts UI.
+- Text contrast >= 4.5:1 against whatever is behind it, including over footage.
+- Draw graphics in code (SVG/CSS) so every part can animate. Use flat images only for things
+  that must be real (logos, screenshots, photos). Avoid AI-generated imagery for anything the
+  viewer is meant to look at.
+- Icons: SVG drawn in code or an installed icon library, never image files.
 ---
-## Compositing: text behind the subject
-Layer order, bottom to top:
-```
-background plate (designed, or the original footage)
-  text / graphics          <- 1–3px blur to sit on the background's focal plane
-    subject cutout         <- same clip, frame-aligned
-      light wrap           <- blurred background screened onto the subject's inner edge, 15–30%
-        grain + grade      <- applied over everything so layers share one look
-```
-- **The cutout must come from the same clip as its background plate**, frame-aligned. Never
-  combine a cutout from one take with footage from another.
-- **Green screen:** key once to a transparent intermediate in `work/` (not per render). Clean up
-  with spill suppression, ~0.5px choke, 0.5–1px feather. Temporal smoothing on the alpha
-  prevents edge flicker.
-- **Paired clips (the user's standard delivery):** Video 1 = original; Video 2 = the same clip with the
-  background replaced by flat green. Use Video 2 **only to build the matte (alpha)** and take the
-  subject's colour from Video 1 — this removes green fringe/spill entirely, because the subject pixels
-  never touched green. Before building, verify the pair: identical duration, fps, resolution and
-  frame count, and that the subject lines up on the same frame (a 1-frame offset makes a halo or ghost).
-  Any VFR conform must be applied identically to both. If the background-removal tool can export real
-  transparency, that is even better than green.
-- **Supplied cutouts** must have real transparency (ProRes 4444, WebM with alpha, or PNG sequence).
-  An MP4 cannot hold transparency — if one arrives, stop and tell the user.
-- Play transparent video with `<OffthreadVideo transparent src={staticFile(...)} />`.
-- Text behind a moving subject gets 0.85–0.95x counter-parallax; static text reads as a sticker.
-- Text should animate in while already partly occluded, not appear fully and then get covered.
-- Pull text colour toward the footage's black/white points; pure white over graded footage looks
-  pasted on.
+## Compositing: text behind the subject
+Layer order, bottom to top:
+```
+background plate (designed, or the original footage)
+  text / graphics          <- 1–3px blur to sit on the background's focal plane
+    subject cutout         <- same clip, frame-aligned
+      light wrap           <- blurred background screened onto the subject's inner edge, 15–30%
+        grain + grade      <- applied over everything so layers share one look
+```
+- **The cutout must come from the same clip as its background plate**, frame-aligned. Never
+  combine a cutout from one take with footage from another.
+- **Green screen:** key once to a transparent intermediate in `work/` (not per render). Clean up
+  with spill suppression, ~0.5px choke, 0.5–1px feather. Temporal smoothing on the alpha
+  prevents edge flicker.
+- **Paired clips (the user's standard delivery):** Video 1 = original; Video 2 = the same clip with the
+  background replaced by flat green. Use Video 2 **only to build the matte (alpha)** and take the
+  subject's colour from Video 1 — this removes green fringe/spill entirely, because the subject pixels
+  never touched green. Before building, verify the pair: identical duration, fps, resolution and
+  frame count, and that the subject lines up on the same frame (a 1-frame offset makes a halo or ghost).
+  Any VFR conform must be applied identically to both. If the background-removal tool can export real
+  transparency, that is even better than green.
+- **Supplied cutouts** must have real transparency (ProRes 4444, WebM with alpha, or PNG sequence).
+  An MP4 cannot hold transparency — if one arrives, stop and tell the user.
+- Play transparent video with `<OffthreadVideo transparent src={staticFile(...)} />`.
+- Text behind a moving subject gets 0.85–0.95x counter-parallax; static text reads as a sticker.
+- Text should animate in while already partly occluded, not appear fully and then get covered.
+- Pull text colour toward the footage's black/white points; pure white over graded footage looks
+  pasted on.
 ---
-## Per-video pipeline
-1. **Ingest:** probe every clip (fps, resolution, colour, alpha).
-   - **Phone footage is usually variable frame rate (VFR).** Conform it to constant frame rate
-     with ffmpeg before use, or it stutters and drifts out of sync in Remotion.
-   - Conform everything to one fps. Never mix frame rates.
-2. **Spine:** word-level timings + music beats -> `work/<video>/spine.json`.
-   Cut pauses/filler from word gaps. All animation timing reads from the spine.
-   - If the user supplies a script or SRT, it is the **text truth** (spelling, names, brand words):
-     force-align that exact text to the audio with WhisperX's aligner. Never use SRT timings
-     directly — they are line-level and padded for readability, not word-accurate.
-   - With no script, transcribe with WhisperX, then show the transcript for correction before building.
-3. **Cutouts:** key green screen or validate supplied cutouts (see above).
-4. **Beat sheet:** from the script and the user's marked punch lines, write a short plan — which
-   moment gets which treatment — and confirm with the user before building.
-5. **Build** in `src/compositions/<Video>.tsx` from components + helpers + tokens only.
-6. **Verify** (below), then show the user.
-7. **Sound:** the user adds SFX and music themselves. Deliver a cue list (timestamps of every
-   transition and hit, with suggested whoosh start = `TRANSITION.sfxLeadMs` before the change) so
-   they can place sounds quickly. Render without music unless asked.
-8. **Render** at `--scale=2`, downscaled to 1080x1920 unless told otherwise.
+## Per-video pipeline
+1. **Ingest:** probe every clip (fps, resolution, colour, alpha).
+   - **Phone footage is usually variable frame rate (VFR).** Conform it to constant frame rate
+     with ffmpeg before use, or it stutters and drifts out of sync in Remotion.
+   - Conform everything to one fps. Never mix frame rates.
+2. **Spine:** word-level timings + music beats -> `work/<video>/spine.json`.
+   Cut pauses/filler from word gaps. All animation timing reads from the spine.
+   - If the user supplies a script or SRT, it is the **text truth** (spelling, names, brand words):
+     force-align that exact text to the audio with WhisperX's aligner. Never use SRT timings
+     directly — they are line-level and padded for readability, not word-accurate.
+   - With no script, transcribe with WhisperX, then show the transcript for correction before building.
+3. **Cutouts:** key green screen or validate supplied cutouts (see above).
+4. **Beat sheet:** from the script and the user's marked punch lines, write a short plan — which
+   moment gets which treatment — and confirm with the user before building.
+   - **Read their saved references first** (`editing_os_references`). They are the whole reason
+     the edit should look like theirs rather than like the defaults, and a plan written without
+     them is a plan written for anybody. Say which reference each decision came from, so the
+     user can see their own taste being applied and correct it when it is being misread.
+   - Where references are silent, the defaults in STYLE.md apply. Where references and defaults
+     disagree, the reference wins — it is a real preference, and the default is only a sensible
+     starting point.
+5. **Build** in `src/compositions/<Video>.tsx` from components + helpers + tokens only.
+6. **Verify** (below), then show the user.
+7. **Sound:** the user adds SFX and music themselves. Deliver a cue list (timestamps of every
+   transition and hit, with suggested whoosh start = `TRANSITION.sfxLeadMs` before the change) so
+   they can place sounds quickly. Render without music unless asked.
+8. **Render** at `--scale=2`, downscaled to 1080x1920 unless told otherwise.
 ---
-## Audio standard (audio is half the reel — the user will not accept a bad mix)
-What went wrong on an early video: the voice itself was bit-for-bit intact (measured against the source),
-but 2.3–3.5s whoosh files and a 2.4s riser kept playing UNDER the speech, which made the voice sound
-wrong. Claude cannot hear, so the mix must be engineered and measured, never guessed.
-1. **The voice is never touched.** Render the picture `--muted`. The voice in every deliverable is the
-   original recording's audio (stream-copied, or at most one encode), plus only a single gain change.
-   No limiter, no dynamic normaliser (ffmpeg `loudnorm` single-pass pumps), no repeated AAC encodes.
-2. **Sound effects are short and placed in gaps.** Trim every SFX to what the motion needs (whoosh
-   0.4–0.8s, hits 0.3–0.6s) with a 60–120ms fade-out. Nothing longer than ~0.8s may sit under a spoken
-   word unless it is at least 24 dB under the voice. Risers go in pauses, not under speech.
-3. **Duck SFX under the voice**: mix with ffmpeg `sidechaincompress` keyed from the voice (SFX drop
-   ~6 dB while a word is spoken), and high-pass whooshes/impacts around 120–150 Hz so they don't muddy it.
-4. **Measure before delivering** (the window scan in the project folder used `f32le` PCM from ffmpeg):
-   voice-vs-mix difference per 0.5s window — any window where SFX energy is within 12 dB of the
-   voice while a word is spoken gets fixed. Final: -14 LUFS integrated, true peak <= -1 dBTP, one
-   AAC encode at 256k.
-5. **Always also deliver stems + a cue sheet**: `voice.wav`, `sfx.wav` (the placed, trimmed SFX bus),
-   and `SFX-CUES.txt` with numbered, timecoded SFX files — so the user can rebalance in Premiere in
-   minutes. Picture-only MP4 alongside.
-6. The user picks and judges sounds by ear; Claude says plainly that it cannot hear and asks for
-   timecoded audio notes on the first draft.
+## Audio standard (audio is half the reel — the user will not accept a bad mix)
+What went wrong on an early video: the voice itself was bit-for-bit intact (measured against the source),
+but 2.3–3.5s whoosh files and a 2.4s riser kept playing UNDER the speech, which made the voice sound
+wrong. Claude cannot hear, so the mix must be engineered and measured, never guessed.
+1. **The voice is never touched.** Render the picture `--muted`. The voice in every deliverable is the
+   original recording's audio (stream-copied, or at most one encode), plus only a single gain change.
+   No limiter, no dynamic normaliser (ffmpeg `loudnorm` single-pass pumps), no repeated AAC encodes.
+2. **Sound effects are short and placed in gaps.** Trim every SFX to what the motion needs (whoosh
+   0.4–0.8s, hits 0.3–0.6s) with a 60–120ms fade-out. Nothing longer than ~0.8s may sit under a spoken
+   word unless it is at least 24 dB under the voice. Risers go in pauses, not under speech.
+3. **Duck SFX under the voice**: mix with ffmpeg `sidechaincompress` keyed from the voice (SFX drop
+   ~6 dB while a word is spoken), and high-pass whooshes/impacts around 120–150 Hz so they don't muddy it.
+4. **Measure before delivering** (the window scan in the project folder used `f32le` PCM from ffmpeg):
+   voice-vs-mix difference per 0.5s window — any window where SFX energy is within 12 dB of the
+   voice while a word is spoken gets fixed. Final: -14 LUFS integrated, true peak <= -1 dBTP, one
+   AAC encode at 256k.
+5. **Always also deliver stems + a cue sheet**: `voice.wav`, `sfx.wav` (the placed, trimmed SFX bus),
+   and `SFX-CUES.txt` with numbered, timecoded SFX files — so the user can rebalance in Premiere in
+   minutes. Picture-only MP4 alongside.
+6. The user picks and judges sounds by ear; Claude says plainly that it cannot hear and asks for
+   timecoded audio notes on the first draft.
 ---
-## Verification (required before saying anything is done)
-Claude cannot watch video. Quality is checked with frames and maths, and the user makes the
-final call at playback speed. Be explicit about that when reporting.
-1. `npm run check` passes.
-2. `npm run motion-check -- <Comp> --scale=2` reports **no POP, CUT or STUTTER**. Allow intentional
-   cuts with `--allow=<frame>`. For each FAST warning, render that frame and confirm the moving
-   edge is blurred. Read the motion timeline for dead air and rhythm.
-3. Render stills and **look at them**: first frame, each element mid-entrance, peak-speed frames
-   (blur visible), fully settled (crisp), mid-exit, and the **last frame** (clean).
-4. Check: no text collides with the subject's face, safe zones respected, contrast holds,
-   no clipped descenders (g, p, y, commas) in masked text.
-5. Report what was verified and what still needs the user's eyes at full speed.
+## Verification (required before saying anything is done)
+Claude cannot watch video. Quality is checked with frames and maths, and the user makes the
+final call at playback speed. Be explicit about that when reporting.
+1. `npm run check` passes.
+2. `npm run motion-check -- <Comp> --scale=2` reports **no POP, CUT or STUTTER**. Allow intentional
+   cuts with `--allow=<frame>`. For each FAST warning, render that frame and confirm the moving
+   edge is blurred. Read the motion timeline for dead air and rhythm.
+3. Render stills and **look at them**: first frame, each element mid-entrance, peak-speed frames
+   (blur visible), fully settled (crisp), mid-exit, and the **last frame** (clean).
+4. Check: no text collides with the subject's face, safe zones respected, contrast holds,
+   no clipped descenders (g, p, y, commas) in masked text.
+5. Report what was verified and what still needs the user's eyes at full speed.
 ---
-## Remotion gotchas
-- Never use CSS `transition`/`animation` — drive everything from `useCurrentFrame()`.
-- Never use `Math.random()` — use `random(seed)` from `remotion`.
-- Never use `will-change` (render-tab flicker, see Smoothness system).
-- **`<Presence>` owns its element's `transform` and `opacity`.** Any extra transform (centring with
-  `translateX(-50%)`) or opacity (fading content) passed in `style` is silently overwritten — put it
-  on an inner wrapper. This bug appeared twice in the first project (off-centre tag, labels that
-  never faded).
-- em-based spacing (gaps, padding) resolves against the element's own font-size: set `fontSize`
-  on the container, or word gaps collapse.
-- Masked text needs travel > 100% and container padding, or descenders stay visible.
-- Load fonts through `@remotion/fonts` (brand your display typeface is local in `assets/fonts/`) so renders wait for them.
+## Remotion gotchas
+- Never use CSS `transition`/`animation` — drive everything from `useCurrentFrame()`.
+- Never use `Math.random()` — use `random(seed)` from `remotion`.
+- Never use `will-change` (render-tab flicker, see Smoothness system).
+- **`<Presence>` owns its element's `transform` and `opacity`.** Any extra transform (centring with
+  `translateX(-50%)`) or opacity (fading content) passed in `style` is silently overwritten — put it
+  on an inner wrapper. This bug appeared twice in the first project (off-centre tag, labels that
+  never faded).
+- em-based spacing (gaps, padding) resolves against the element's own font-size: set `fontSize`
+  on the container, or word gaps collapse.
+- Masked text needs travel > 100% and container padding, or descenders stay visible.
+- Load fonts through `@remotion/fonts` (brand your display typeface is local in `assets/fonts/`) so renders wait for them.
 ---
-## Feedback format from the user
-Notes arrive as timecode + specific issue ("0:14 title lands 3 frames late, bounce too strong").
-Translate each note into token or timing changes; if a note conflicts with a law, say so and ask.
+## Feedback format from the user
+Notes arrive as timecode + specific issue ("0:14 title lands 3 frames late, bounce too strong").
+Translate each note into token or timing changes; if a note conflicts with a law, say so and ask.
 ---
 ## What is already installed

package/template/STYLE.md CHANGED Viewed

@@ -1,165 +1,179 @@
-<!-- This is YOUR style guide. It starts as craft rules that hold for any brand; as you
-     approve and reject things, write them down here so every future video inherits the
-     decision instead of re-litigating it. -->
-# House style
-The look and feel every edit must have. Built from the user's own decisions on real videos. CLAUDE.md says *how* to build; this file says *what it must look,
-move and sound like*. When a decision here conflicts with a reference, this file wins unless the
-user says otherwise. Add to it whenever the user approves or rejects something.
-The user has a design background: judge every frame as a designer would. **Clean, calm, intentional —
-never a video that looks stitched together.**
----
-## 1. Identity
-- **Brand:** Your own design system, defined in `src/design/tokens.ts`.
-- **Type:** your display typeface only. Weight 800 for headlines, numbers and hero words; 600–700 for labels and pointers.
-- **Colour:** your accent colour, ink, cream/white. No other accent colours.
-  - On footage: accent text with the soft accent glow (`heroGlow()`).
-  - On cream: ink text; emphasis with the accent marker (`HighlightMark`).
-  - Solid screens: accent background with ink text, or ink background with accent text.
-## 2. Type scale (restrained — oversized text was rejected as "not aesthetic")
-| Role | 16:9 (1920x1080) | 9:16 (1080x1920) | Notes |
-|---|---|---|---|
-| Hero word (one per beat: STOP, FIRST) | 200–320px | 130–220px | Only one hero on screen at a time |
-| Headline (SAME SCRIPT, DIFFERENT PERSON, REINVENT) | ~116px | ~100px | Tracking -0.03em |
-| Big number (counter, stat) | ~170px | ~150px | Tabular digits while counting |
-| Label (VIEWS, COMMENT, THE WHEEL, eyebrows) | ~40px | ~32px | Uppercase, tracking 0.14em, weight 600 |
-| Pointer / list item | ~42px | ~36px | Accent check icon ~40px |
-| Captions | 46px | 42px | Crisp white, bold, soft dark shadow |
-If a word needs to be bigger than this to feel important, the layout is wrong, not the size.
-## 3. Layout
-- **The speaker stays full screen by default.** No rounded boxes or frames around the talking head
-  just to make room ("looks very off"). A card is only allowed as a *transition* (the card swap).
-- Put text in the clear space the shot gives you (sky, trees, empty wall), or **behind the subject**
-  when a green-screen twin exists. Check where the head goes on every jump cut.
-- The head may cover at most the lower ~20–30% of a word behind it, and the word must still read.
-- Captions live in one consistent zone per layout, over a dark area. They hide while the same words
-  are on screen as a graphic, and never linger into the next scene.
-- Graphics are made of type, numbers, real screenshots and real clips. **No decorative gimmicks**
-  (a glowing wheel behind the speaker was rejected as a "weird vibe").
-## 4. Motion
-- The 12 motion laws in CLAUDE.md, always. Smooth, eased, motion-blurred, nothing pops.
-- **Jump cuts: zoom through them** (Stage `cutZoom`). The same settle when footage returns after a
-  full-screen graphic. Never a jittery snap.
-- **Hard cuts only as a deliberate burst** (colour flip): a few beats of solid screens synced to the
-  phrases and sound, then back to smooth. Everything else morphs from one state to the next.
-- **Cover anything off-camera** (reading from an iPad, looking away) with a graphic or a cut.
-- Counters only go up and start from 0 — no grey placeholder digits.
-## 5. Sound (audio is half the reel)
-- The voice is never processed — see the Audio standard in CLAUDE.md.
-- Sound effects are short (whoosh 0.4–0.8s, hits 0.3–0.6s), faded, and sit in the gaps between words.
-- Every new visual gets its own fitting sound; don't reuse a sound that belonged to a different look.
-- Subtle beats loud: cinematic impacts on text were "way too impactful". Whooshes on big moves must
-  still be clearly audible.
-- Always hand over voice + SFX stems and a numbered, timecoded SFX folder with a cue sheet.
-## 5b. Colour (the look is shot, then graded)
-Target look (user's references, Sep 2026): warm golden light, olive-yellow greens, soft contrast,
-creamy skin, shallow depth of field — sunlit / window-lit.
-- **~80% of this look comes from the shoot**: golden hour or a single side window, the sun or light
-  behind/beside the subject, a warm/green background 3+ m away, a fast lens (EF 50mm f/1.8 at f/2–2.8),
-  white balance fixed (Daylight 5200K outdoors — never Auto, it removes the gold).
-- Canon 200D: Neutral picture style (sharpness 0–1, contrast -2, saturation -1), 25fps + 1/50 under
-  50Hz lighting (flicker), 30fps + 1/60 outdoors, ISO 100–400, expose skin bright but unclipped.
-- **Automated LUT grading (`scripts/grade.py`) is a starting point only** and only when the footage's
-  light already resembles the reference. On mismatched footage (overcast rooftop vs sunlit refs) the
-  user judged it "very bad, nowhere near". Never present an auto-grade as a match; judge colour by
-  the user's eye, not by Claude's thumbnails. Final grading: DaVinci Resolve / Lumetri, shot by shot,
-  reference on split screen.
-- Ask for a 20s test clip at the planned location/time before a graded shoot; check exposure,
-  clipping, white balance and flicker numerically.
-## 5c. Transitions and caption looks (presets)
-Named in `src/design/presets.ts`. Ask for them by name in a brief.
-| Transition | When |
-|---|---|
-| whipPan | Between unrelated shots. Never twice in a row. |
-| push | Moving forward through a list or sequence. |
-| maskWipe | Calm reveal. Pairs with a soft sound. |
-| colourFlip | A burst on a phrase. Two or three, then back to smooth. |
-| matchCut | Only when both shots share a shape or direction. |
-| dip | Changing subject without drama. |
-| Caption look | When |
-|---|---|
-| clean | Default. Works over almost anything. |
-| block | Busy or bright footage, where white alone gets lost. |
-| highlight | Keeps the eye on the word being said. |
-| pop | Fast edits. Not over heavy motion. |
-Speed ramps: eased only (`npm run ramp`), never a hard speed switch. Below 0.4x needs 50fps+ footage.
-## 5d. Film looks (overlays)
-Named in `src/design/overlays.ts`, applied with `<FilmOverlay look="film">`. Reference
-composition: `FilmTest`. The test is that the footage looks richer, never that it looks
-filtered — if a viewer can name the effect, it is too strong.
-| Look | When |
-|---|---|
-| none | Graphics, screen recordings, anything with text as the subject. |
-| clean | Default for talking head. Just enough grain to stop flat areas banding. |
-| film | B-roll and travel. The one to reach for first. |
-| super8 | Memory / nostalgia moments only. Never a whole video. |
-| cinema | A held, wide, quiet shot. Bars plus bloom, nothing that moves. |
-Three things that were measured, and must not be quietly undone:
-- Grain composites **normally**, not with `overlay`. On cream and ink there are no midtones,
-  and overlay grain measured 0.000 stddev on a flat area — the layer did nothing at all.
-- Grain is paid for in black level (blacks measured 18 → 25 at `medium`). Turn it up per shot
-  with the `grain` prop when a nostalgia moment is worth milkier blacks; never raise the default.
-- Halation blooms **highlights only** — the plate is crushed to black before it is blurred and
-  screened back, so the darks come through untouched. Without the crush a cream-heavy frame
-  blooms end to end and the blacks lift to brown.
-Grain reseeds every frame. Holding a seed makes the frame byte-identical to the last one, which
-motion-check reports as a STUTTER, so a grainy video would fail its own verification gate.
-## 6. Approved beats (the effects library)
-Names match `templates/BRIEF.md`. "Source" is where the user approved it.
-| Beat | What it is | Source |
-|---|---|---|
-| Text behind me | Headline behind the head (green-screen twin) | — |
-| Card swap | Speaker shrinks into a card, becomes a creator clip mid-shrink, a row of clips slides in and drifts while the voice continues | approved as "perfect" |
-| Colour flip | Solid accent/ink screens per phrase; a word rolls into the next and the colours swap | — |
-| Counter race | Number races from 0 and lands (1,000,000+), then footage slams back | — |
-| Zoom-through cut | Push-in through every jump cut | — |
-| Gradient CTA | Bottom gradient, small label + big typed word, then ticked pointers after it leaves | — |
-| Browser mockup | Screenshots in a clean browser window, panned and zoomed | — |
-| Pointer click | Solid accent arrow glides and clicks with a ripple | — |
-| Rolling number | Digits roll between values | — |
-| Headline to pill | Big headline shrinks into a corner tag; removed when back to full screen | — |
-| Word-by-word captions | Default | both |
-## 7. Rejected (don't do these again)
-| What | Why | Video |
-|---|---|---|
-| Rounded card around the talking head at the end | "looks very off" | — |
-| Glowing wheel graphic behind the speaker | "weird vibe" | — |
-| Footage behind the colour-flip screens | "loses the impact" | — |
-| Text at 190–280px | "way too big, not aesthetic" | — |
-| Big cinematic impact on the hook word | "way too impactful" | — |
-| Grey placeholder digits in a counter | "not coming out nicely" | — |
-| Long whoosh / riser tails under speech | made the voice sound wrong | — |
-| Black text with a white glow for captions | replaced by crisp white | — |
+<!-- This is YOUR style guide, and it starts deliberately half-empty.
+     Parts 1 to 6 are craft standards: things that hold for any brand, most of them
+     measured rather than argued. Leave them alone until you have a reason not to, and
+     your edits will come out clean rather than random.
+     Parts 7 and 8 are yours and begin blank. Every time you approve or reject something,
+     write it down there. That is the half that makes edits look like YOURS instead of
+     merely competent, and it is the half nobody can hand you. -->
+# House style
+What every edit must look, move and sound like. `CLAUDE.md` says *how* to build; this
+file says *what it must come out like*.
+When this file and a reference disagree, this file wins unless you say otherwise.
+---
+## 1. Your identity
+Everything visual comes from `src/design/tokens.ts`. That file is the single source of
+your typeface, your colours, your spacing and your type scale — change it there and every
+video changes with it. Never hard-code a colour or a font family into a composition.
+- **Type:** one display typeface. Heavy weights for headlines, numbers and hero words;
+  medium for labels and pointers.
+- **Colour:** one accent, plus ink and a light ground. Resist a second accent — two
+  accents read as a template, one reads as a brand.
+- On footage: accent text, with a soft glow so it survives a busy frame.
+- On a light ground: ink text, with the accent used only to mark the word that matters.
+## 2. Type scale
+Sizes are a starting ladder, not a law. What matters is that you keep to *a* ladder.
+| Role | 16:9 (1920x1080) | 9:16 (1080x1920) | Notes |
+|---|---|---|---|
+| Hero word | 200–320px | 130–220px | One on screen at a time, never two |
+| Headline | ~116px | ~100px | Tight tracking, around -0.03em |
+| Big number | ~170px | ~150px | Tabular digits while a counter runs |
+| Label / eyebrow | ~40px | ~32px | Uppercase, open tracking, ~0.14em |
+| Pointer / list item | ~42px | ~36px | |
+| Captions | 46px | 42px | Crisp white, bold, soft dark shadow |
+**If a word needs to be bigger than the ladder to feel important, the layout is wrong,
+not the size.** Oversized type is the most common way an edit starts looking amateur.
+## 3. Layout
+- **The speaker stays full screen by default.** Rounded cards and frames around a talking
+  head make the edit look assembled rather than shot. A card is fine as a *transition*,
+  not as a container.
+- Put text in the clear space the shot already gives you: sky, a wall, out-of-focus
+  background. Check where the head lands on every cut before committing a position.
+- Captions live in one consistent zone per layout, over a dark area. They hide while the
+  same words are on screen as a graphic, and never linger into the next scene.
+- Graphics are built from type, numbers, real screenshots and real footage. Decorative
+  shapes that mean nothing age badly and read as filler.
+## 4. Motion
+- The motion laws in `CLAUDE.md`, always. Eased, motion-blurred, nothing pops into place.
+- **Zoom through jump cuts.** A small push on the cut hides the join; a hard snap exposes it.
+- **Hard cuts only as a deliberate burst** — a few beats of solid colour synced to the
+  words, then back to smooth. Everything else morphs from one state to the next.
+- Cover anything off-camera — reading, looking away, a fumble — with a graphic or a cut.
+- Counters start at zero and only go up. No grey placeholder digits.
+- Vary your shot lengths. Cutting everything to the same duration is the clearest sign
+  an edit was made by a machine rather than by someone making decisions.
+## 5. Sound (half the reel)
+- **The voice is never processed.** No reverb, no heavy compression, no "enhancement".
+- Sound effects are short — whooshes 0.4–0.8s, hits 0.3–0.6s — faded, and placed in the
+  gaps between words rather than under them.
+- Every new visual gets its own fitting sound. Reusing a sound that belonged to a
+  different look is the audio version of a template.
+- **Subtle beats loud.** Big cinematic impacts on text almost always read as too much.
+- Hand over voice and SFX stems plus a timecoded cue sheet with every delivery.
+## 6. Colour, film looks and presets
+**Most of a look comes from the shoot, not the grade.** Golden hour or one good window,
+light behind or beside the subject, background well behind the subject, white balance
+fixed rather than auto. Automated grading is a starting point and only when the footage's
+light already resembles the reference — on mismatched light it will look wrong, and you
+should trust your eye over any automatic match.
+| Transition | When |
+|---|---|
+| whipPan | Between unrelated shots. Never twice in a row. |
+| push | Moving forward through a list or a sequence. |
+| maskWipe | A calm reveal. Pairs with a soft sound. |
+| colourFlip | A burst on a phrase. Two or three, then back to smooth. |
+| matchCut | Only when both shots share a shape or a direction. |
+| dip | Changing subject without drama. |
+| Caption look | When |
+|---|---|
+| clean | Default. Works over almost anything. |
+| block | Busy or bright footage, where white alone gets lost. |
+| highlight | Keeps the eye on the word being spoken. |
+| pop | Fast edits. Not over heavy motion. |
+| Film look | When |
+|---|---|
+| none | Graphics, screen recordings, anything where text is the subject. |
+| clean | Default for a talking head. Enough grain to stop flat areas banding. |
+| film | B-roll and travel. The one to reach for first. |
+| super8 | Memory and nostalgia moments only. Never a whole video. |
+| cinema | A held, wide, quiet shot. |
+**Three things here were measured, not guessed. Do not quietly undo them:**
+- Grain composites **normally**, not with `overlay`. On flat cream or flat ink there are
+  no midtones, and overlay grain measures 0.000 stddev — the layer does nothing at all.
+- Grain is paid for in black level — blacks lift measurably at medium strength. Raise it
+  per shot when a nostalgia moment is worth milkier blacks; never raise the default.
+- Halation blooms **highlights only**. The plate is crushed to black before it is blurred
+  and screened back. Without that crush, a bright frame blooms end to end and the blacks
+  go brown.
+Speed ramps are eased, never a hard speed switch. Below 0.4x needs 50fps or higher source
+footage — you cannot rescue slow motion that was not shot for it.
+---
+## 7. Where these defaults end and you begin
+The sections above are **defaults**: a starting point tuned so that a video made on day one,
+before you have told the system anything, comes out clean rather than embarrassing. Captions
+sit at a readable size with a measured shadow, cuts are eased, grain is restrained, the voice
+is untouched.
+Defaults are also the reason an edit can come out *anonymous*. They are what everybody gets.
+Three things move an edit from the default toward yours, in increasing order of power:
+**1. Your tokens.** `src/design/tokens.ts` carries your typeface, your colours, your scale.
+This makes an edit *yours to look at* immediately.
+**2. Your references.** Saved moments from edits you admire, each with a timecode and a note
+on what you like about that exact moment. These are read before the plan for every video, and
+they beat the defaults wherever the two disagree — a default is a guess that suits everyone,
+a reference is a fact about you.
+Roughly: **none** gives you clean and forgettable. **Three** is enough to spot a pattern.
+**Seven or eight** is enough to tell a preference from a coincidence, and it is where edits
+start looking authored.
+**3. This file, as it fills up.** Sections 8 and 9 are the part no default can supply and no
+competitor can copy, because they are a record of decisions only you have made. Every entry
+narrows the next edit toward what you actually want.
+Nothing here learns on its own. It gets better because the brief gets richer — so the ten
+minutes spent writing down why you rejected something is the highest-return ten minutes
+available to you.
+---
+## 8. Approved (your effects library)
+<!-- Empty on purpose. When something works, write it down here: what it is, and where
+     you approved it. Next time you can ask for it by name instead of describing it
+     again, and every future video inherits the decision. -->
+| Beat | What it is | Where you approved it |
+|---|---|---|
+| | | |
+## 9. Rejected (don't do these again)
+<!-- This table is worth more than the one above. A list of things you have ruled out is
+     the fastest way to stop an edit drifting back toward generic, because it removes
+     options rather than adding them. Add a line every time you say "not that". -->
+| What | Why | Where |
+|---|---|---|
+| | | |

package/template/templates/STYLE.md ADDED Viewed

@@ -0,0 +1,179 @@
+<!-- This is YOUR style guide, and it starts deliberately half-empty.
+     Parts 1 to 6 are craft standards: things that hold for any brand, most of them
+     measured rather than argued. Leave them alone until you have a reason not to, and
+     your edits will come out clean rather than random.
+     Parts 7 and 8 are yours and begin blank. Every time you approve or reject something,
+     write it down there. That is the half that makes edits look like YOURS instead of
+     merely competent, and it is the half nobody can hand you. -->
+# House style
+What every edit must look, move and sound like. `CLAUDE.md` says *how* to build; this
+file says *what it must come out like*.
+When this file and a reference disagree, this file wins unless you say otherwise.
+---
+## 1. Your identity
+Everything visual comes from `src/design/tokens.ts`. That file is the single source of
+your typeface, your colours, your spacing and your type scale — change it there and every
+video changes with it. Never hard-code a colour or a font family into a composition.
+- **Type:** one display typeface. Heavy weights for headlines, numbers and hero words;
+  medium for labels and pointers.
+- **Colour:** one accent, plus ink and a light ground. Resist a second accent — two
+  accents read as a template, one reads as a brand.
+- On footage: accent text, with a soft glow so it survives a busy frame.
+- On a light ground: ink text, with the accent used only to mark the word that matters.
+## 2. Type scale
+Sizes are a starting ladder, not a law. What matters is that you keep to *a* ladder.
+| Role | 16:9 (1920x1080) | 9:16 (1080x1920) | Notes |
+|---|---|---|---|
+| Hero word | 200–320px | 130–220px | One on screen at a time, never two |
+| Headline | ~116px | ~100px | Tight tracking, around -0.03em |
+| Big number | ~170px | ~150px | Tabular digits while a counter runs |
+| Label / eyebrow | ~40px | ~32px | Uppercase, open tracking, ~0.14em |
+| Pointer / list item | ~42px | ~36px | |
+| Captions | 46px | 42px | Crisp white, bold, soft dark shadow |
+**If a word needs to be bigger than the ladder to feel important, the layout is wrong,
+not the size.** Oversized type is the most common way an edit starts looking amateur.
+## 3. Layout
+- **The speaker stays full screen by default.** Rounded cards and frames around a talking
+  head make the edit look assembled rather than shot. A card is fine as a *transition*,
+  not as a container.
+- Put text in the clear space the shot already gives you: sky, a wall, out-of-focus
+  background. Check where the head lands on every cut before committing a position.
+- Captions live in one consistent zone per layout, over a dark area. They hide while the
+  same words are on screen as a graphic, and never linger into the next scene.
+- Graphics are built from type, numbers, real screenshots and real footage. Decorative
+  shapes that mean nothing age badly and read as filler.
+## 4. Motion
+- The motion laws in `CLAUDE.md`, always. Eased, motion-blurred, nothing pops into place.
+- **Zoom through jump cuts.** A small push on the cut hides the join; a hard snap exposes it.
+- **Hard cuts only as a deliberate burst** — a few beats of solid colour synced to the
+  words, then back to smooth. Everything else morphs from one state to the next.
+- Cover anything off-camera — reading, looking away, a fumble — with a graphic or a cut.
+- Counters start at zero and only go up. No grey placeholder digits.
+- Vary your shot lengths. Cutting everything to the same duration is the clearest sign
+  an edit was made by a machine rather than by someone making decisions.
+## 5. Sound (half the reel)
+- **The voice is never processed.** No reverb, no heavy compression, no "enhancement".
+- Sound effects are short — whooshes 0.4–0.8s, hits 0.3–0.6s — faded, and placed in the
+  gaps between words rather than under them.
+- Every new visual gets its own fitting sound. Reusing a sound that belonged to a
+  different look is the audio version of a template.
+- **Subtle beats loud.** Big cinematic impacts on text almost always read as too much.
+- Hand over voice and SFX stems plus a timecoded cue sheet with every delivery.
+## 6. Colour, film looks and presets
+**Most of a look comes from the shoot, not the grade.** Golden hour or one good window,
+light behind or beside the subject, background well behind the subject, white balance
+fixed rather than auto. Automated grading is a starting point and only when the footage's
+light already resembles the reference — on mismatched light it will look wrong, and you
+should trust your eye over any automatic match.
+| Transition | When |
+|---|---|
+| whipPan | Between unrelated shots. Never twice in a row. |
+| push | Moving forward through a list or a sequence. |
+| maskWipe | A calm reveal. Pairs with a soft sound. |
+| colourFlip | A burst on a phrase. Two or three, then back to smooth. |
+| matchCut | Only when both shots share a shape or a direction. |
+| dip | Changing subject without drama. |
+| Caption look | When |
+|---|---|
+| clean | Default. Works over almost anything. |
+| block | Busy or bright footage, where white alone gets lost. |
+| highlight | Keeps the eye on the word being spoken. |
+| pop | Fast edits. Not over heavy motion. |
+| Film look | When |
+|---|---|
+| none | Graphics, screen recordings, anything where text is the subject. |
+| clean | Default for a talking head. Enough grain to stop flat areas banding. |
+| film | B-roll and travel. The one to reach for first. |
+| super8 | Memory and nostalgia moments only. Never a whole video. |
+| cinema | A held, wide, quiet shot. |
+**Three things here were measured, not guessed. Do not quietly undo them:**
+- Grain composites **normally**, not with `overlay`. On flat cream or flat ink there are
+  no midtones, and overlay grain measures 0.000 stddev — the layer does nothing at all.
+- Grain is paid for in black level — blacks lift measurably at medium strength. Raise it
+  per shot when a nostalgia moment is worth milkier blacks; never raise the default.
+- Halation blooms **highlights only**. The plate is crushed to black before it is blurred
+  and screened back. Without that crush, a bright frame blooms end to end and the blacks
+  go brown.
+Speed ramps are eased, never a hard speed switch. Below 0.4x needs 50fps or higher source
+footage — you cannot rescue slow motion that was not shot for it.
+---
+## 7. Where these defaults end and you begin
+The sections above are **defaults**: a starting point tuned so that a video made on day one,
+before you have told the system anything, comes out clean rather than embarrassing. Captions
+sit at a readable size with a measured shadow, cuts are eased, grain is restrained, the voice
+is untouched.
+Defaults are also the reason an edit can come out *anonymous*. They are what everybody gets.
+Three things move an edit from the default toward yours, in increasing order of power:
+**1. Your tokens.** `src/design/tokens.ts` carries your typeface, your colours, your scale.
+This makes an edit *yours to look at* immediately.
+**2. Your references.** Saved moments from edits you admire, each with a timecode and a note
+on what you like about that exact moment. These are read before the plan for every video, and
+they beat the defaults wherever the two disagree — a default is a guess that suits everyone,
+a reference is a fact about you.
+Roughly: **none** gives you clean and forgettable. **Three** is enough to spot a pattern.
+**Seven or eight** is enough to tell a preference from a coincidence, and it is where edits
+start looking authored.
+**3. This file, as it fills up.** Sections 8 and 9 are the part no default can supply and no
+competitor can copy, because they are a record of decisions only you have made. Every entry
+narrows the next edit toward what you actually want.
+Nothing here learns on its own. It gets better because the brief gets richer — so the ten
+minutes spent writing down why you rejected something is the highest-return ten minutes
+available to you.
+---
+## 8. Approved (your effects library)
+<!-- Empty on purpose. When something works, write it down here: what it is, and where
+     you approved it. Next time you can ask for it by name instead of describing it
+     again, and every future video inherits the decision. -->
+| Beat | What it is | Where you approved it |
+|---|---|---|
+| | | |
+## 9. Rejected (don't do these again)
+<!-- This table is worth more than the one above. A list of things you have ruled out is
+     the fastest way to stop an edit drifting back toward generic, because it removes
+     options rather than adding them. Add a line every time you say "not that". -->
+| What | Why | Where |
+|---|---|---|
+| | | |