creator-editing-studio 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "creator-editing-studio",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "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

@@ -48,257 +48,264 @@ 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.
+- **Your style decisions:** *(empty on purpose — this fills in as you make them)*
+
+  When something gets settled about how your videos look, write it here as one line. Where
+  captions sit in a card layout. Whether headlines take the accent colour or the ink. What a
+  corner tag does when the video returns to full screen. This file is read first every
+  session, so a decision recorded here is one you never have to make twice, and the studio
+  stops asking.
+
+  Do not fill this with defaults copied from somewhere else. An empty section produces
+  questions; a borrowed one produces someone else's videos.
+
+  The one rule here that is not a preference: 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 is not in the set. Use a neutral icon and ask for the official file.
+- **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.
+- **The matte is built automatically from ordinary footage.** No green screen, and never ask the
+  user for one — most people have never shot against green and do not know the term. Segment the
+  subject per frame, then **temporally smooth the alpha**, which is not optional: a per-frame matte
+  shimmers along the edge, and type sitting against a head is exactly where that shows. Finish with
+  spill-free cleanup: ~0.5px choke, 0.5–1px feather.
+- **Quality is worst where it is most visible:** flyaway hair, motion blur, and a hand crossing in
+  front of the text. The light wrap below hides a good deal of it. If a shot simply will not hold,
+  say so and move the text rather than shipping a halo.
+- **If the user happens to have a background-free or green version, prefer it** — chroma keying
+  still beats automatic matting on hair. Use it **only for the alpha** and take the subject's colour
+  from the original, so no green ever reaches the edges. Verify the pair first: identical duration,
+  fps, resolution and frame count, subject aligned on the same frame (one frame out makes a ghost).
+  This is an upgrade for people who already work that way, never a requirement.
+- **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.
-   - **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.
-
+## 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:** build the matte from the footage automatically, or validate a supplied cutout (see above). Only needed for shots that want text behind the subject.
+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/requirements.txt

@@ -1,17 +1,23 @@
-# The Python half of the studio: transcription, word alignment, cut detection,
-# green-screen cutouts and colour grading.
-#
-#   python -m venv .venv
-#   .venv/bin/pip install -r requirements.txt        (Windows: .venv\Scripts\pip)
-#
-# Python 3.11 or 3.12. Not 3.13+ — WhisperX's dependencies do not support it yet, and the
-# failure is a wall of build errors rather than a clear message.
-#
-# certifi is not optional on macOS: torch downloads the alignment model with urllib, which
-# on a python.org build has no root certificates at all.
-
-whisperx==3.8.6
-torch>=2.2
-numpy>=1.26
-Pillow>=10.0
-certifi>=2024.2.2
+# The Python half of the studio: transcription, word alignment, cut detection,
+# green-screen cutouts and colour grading.
+#
+#   python -m venv .venv
+#   .venv/bin/pip install -r requirements.txt        (Windows: .venv\Scripts\pip)
+#
+# Python 3.11 or 3.12. Not 3.13+ — WhisperX's dependencies do not support it yet, and the
+# failure is a wall of build errors rather than a clear message.
+#
+# certifi is not optional on macOS: torch downloads the alignment model with urllib, which
+# on a python.org build has no root certificates at all.
+
+whisperx==3.8.6
+# BiRefNet, for cutting the subject out of ordinary footage so text can sit behind them.
+# MIT licensed and self-hosted: nothing uploads, and there is no per-video cost.
+transformers>=4.44
+timm>=1.0
+einops>=0.8
+kornia>=0.7
+torch>=2.2
+numpy>=1.26
+Pillow>=10.0
+certifi>=2024.2.2

package/template/scripts/make_cutout.py

@@ -1,68 +1,181 @@
-"""Build a transparent cutout of the subject for a frame range of a paired clip.
-
-Usage (from the project root):
-    python scripts/make_cutout.py <original> <greenscreen> <out_dir> <first_frame> <last_frame>
-
-The green-screen clip is used ONLY for the matte (alpha). Colour comes from the original clip, so no
-green ever reaches the subject's edges. Writes RGBA PNGs named f<frame>.png (absolute source frame
-numbers) so compositions can map composition frames to cutout frames directly.
-"""
-
-import subprocess
-import sys
-from pathlib import Path
-
-import numpy as np
-from PIL import Image
-import sys as _sys, pathlib as _pl
-_sys.path.insert(0, str(_pl.Path(__file__).resolve().parent / 'lib'))
-from media import FFMPEG, FFPROBE  # resolved per platform - never hardcode a tool path
-
-
-
-W, H, FPS = 1920, 1080, 30
-
-
-def read_frames(path: str, first: int, count: int):
-    proc = subprocess.Popen(
-        [FFMPEG, "-v", "error", "-ss", f"{first / FPS:.6f}", "-i", path, "-frames:v", str(count),
-         "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
-        stdout=subprocess.PIPE,
-    )
-    size = W * H * 3
-    for _ in range(count):
-        buf = proc.stdout.read(size)
-        if len(buf) < size:
-            break
-        yield np.frombuffer(buf, np.uint8).reshape(H, W, 3)
-    proc.stdout.close()
-    proc.wait()
-
-
-def matte(green: np.ndarray) -> np.ndarray:
-    """Alpha 0..1 from how green each pixel is, relative to the flat background green."""
-    g = green.astype(np.float32)
-    greenness = g[..., 1] - np.maximum(g[..., 0], g[..., 2])
-    background = np.median(greenness[greenness > 60]) if (greenness > 60).any() else 150.0
-    lo, hi = 0.2 * background, 0.7 * background
-    t = np.clip((greenness - lo) / (hi - lo), 0, 1)
-    alpha = 1 - t * t * (3 - 2 * t)  # smoothstep: soft, stable edge
-    # Choke by 1px so the background never leaks in, then feather lightly.
-    choked = np.minimum.reduce([alpha, np.roll(alpha, 1, 0), np.roll(alpha, -1, 0), np.roll(alpha, 1, 1), np.roll(alpha, -1, 1)])
-    feathered = (choked * 4 + np.roll(choked, 1, 0) + np.roll(choked, -1, 0) + np.roll(choked, 1, 1) + np.roll(choked, -1, 1)) / 8
-    return feathered
-
-
-def main() -> None:
-    original, greenscreen, out_dir, first, last = sys.argv[1], sys.argv[2], Path(sys.argv[3]), int(sys.argv[4]), int(sys.argv[5])
-    out_dir.mkdir(parents=True, exist_ok=True)
-    count = last - first + 1
-    for offset, (rgb, green) in enumerate(zip(read_frames(original, first, count), read_frames(greenscreen, first, count))):
-        alpha = (matte(green) * 255).round().astype(np.uint8)
-        rgba = np.dstack([rgb, alpha])
-        Image.fromarray(rgba, "RGBA").save(out_dir / f"f{first + offset}.png", compress_level=1)
-    print(f"wrote {count} frames to {out_dir}")
-
-
-if __name__ == "__main__":
-    main()
+"""Build a transparent cutout of the subject for a frame range, from ordinary footage.
+
+Usage (from the project root):
+    python scripts/make_cutout.py <video> <out_dir> <first_frame> <last_frame>
+    python scripts/make_cutout.py <video> <out_dir> <first> <last> --alpha-from <clip>
+    python scripts/make_cutout.py <video> <out_dir> <first> <last> --model full
+
+Writes RGBA PNGs named f<frame>.png (absolute source frame numbers), so a composition can map
+composition frames to cutout frames directly.
+
+No green screen. The matte is segmented from the footage itself, because asking a customer to
+shoot against green makes the feature unavailable to almost all of them - most have never done
+it and do not know the term.
+
+--alpha-from stays for the case where a background-free or green copy already exists, which is
+faster and still sharper on hair. It is used ONLY for the alpha; colour always comes from the
+original clip, so no green ever reaches the subject's edges.
+
+Two things decide whether this reads as real rather than pasted on:
+
+  * The alpha is smoothed ACROSS frames. A per-frame matte shimmers along the edge, and type
+    sitting against someone's head is precisely where the eye catches it. A 3-frame median kills
+    single-frame flicker without the lag an average introduces on fast motion.
+  * The edge is choked before it is feathered, so the old background cannot leak into the seam.
+
+It is worst where it is most visible: flyaway hair, motion blur, a hand crossing the text. If a
+shot will not hold, move the text rather than ship a halo.
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+import sys as _sys, pathlib as _pl
+_sys.path.insert(0, str(_pl.Path(__file__).resolve().parent / 'lib'))
+from media import FFMPEG, FFPROBE  # resolved per platform - never hardcode a tool path
+
+MODELS = {"lite": "ZhengPeng7/BiRefNet_lite", "full": "ZhengPeng7/BiRefNet"}
+SEG_SIZE = 1024
+
+
+def probe(path: str):
+    """Real dimensions and frame rate. Never assume 1920x1080 at 30 - vertical phone footage is normal."""
+    out = subprocess.run(
+        [FFPROBE, "-v", "quiet", "-print_format", "json", "-show_streams", "-select_streams", "v:0", path],
+        capture_output=True, text=True, check=True,
+    ).stdout
+    s = json.loads(out)["streams"][0]
+    num, den = (s.get("r_frame_rate") or "30/1").split("/")
+    return int(s["width"]), int(s["height"]), float(num) / float(den or 1)
+
+
+def read_frames(path: str, first: int, count: int, w: int, h: int, fps: float):
+    proc = subprocess.Popen(
+        [FFMPEG, "-v", "error", "-ss", f"{first / fps:.6f}", "-i", path, "-frames:v", str(count),
+         "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+        stdout=subprocess.PIPE,
+    )
+    size = w * h * 3
+    for _ in range(count):
+        buf = proc.stdout.read(size)
+        if len(buf) < size:
+            break
+        yield np.frombuffer(buf, np.uint8).reshape(h, w, 3)
+    proc.stdout.close()
+    proc.wait()
+
+
+def green_matte(green: np.ndarray) -> np.ndarray:
+    """Alpha 0..1 from how green each pixel is, relative to the flat background green."""
+    g = green.astype(np.float32)
+    greenness = g[..., 1] - np.maximum(g[..., 0], g[..., 2])
+    background = np.median(greenness[greenness > 60]) if (greenness > 60).any() else 150.0
+    lo, hi = 0.2 * background, 0.7 * background
+    t = np.clip((greenness - lo) / (hi - lo), 0, 1)
+    return 1 - t * t * (3 - 2 * t)  # smoothstep: soft, stable edge
+
+
+def load_segmenter(which: str):
+    """BiRefNet, lazily. Importing torch costs seconds; do not pay it on the --alpha-from path."""
+    try:
+        import torch
+        from transformers import AutoModelForImageSegmentation
+    except ModuleNotFoundError as exc:
+        print(f"Cannot import {exc.name}. The matting model needs the studio's Python environment.", file=sys.stderr)
+        print("  see what is installed with:  npm run doctor", file=sys.stderr)
+        raise SystemExit(2)
+
+    # trust_remote_code: these repos ship their own model class, which transformers executes.
+    model = AutoModelForImageSegmentation.from_pretrained(MODELS[which], trust_remote_code=True)
+    model.eval()
+    # float32 on CPU: half precision is slower there rather than faster, and can produce NaNs.
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    model.to(device)
+    return torch, model, device
+
+
+def segment(torch, model, device, rgb: np.ndarray) -> np.ndarray:
+    """Alpha 0..1 for one frame, returned at the frame's own resolution."""
+    h, w = rgb.shape[:2]
+    img = Image.fromarray(rgb).resize((SEG_SIZE, SEG_SIZE), Image.BILINEAR)
+    x = np.asarray(img, dtype=np.float32) / 255.0
+    x = (x - np.array([0.485, 0.456, 0.406], np.float32)) / np.array([0.229, 0.224, 0.225], np.float32)
+    t = torch.from_numpy(x).permute(2, 0, 1).unsqueeze(0).to(device)
+    with torch.no_grad():
+        pred = model(t)[-1].sigmoid()[0, 0].cpu().numpy()
+    return np.asarray(Image.fromarray((pred * 255).astype(np.uint8)).resize((w, h), Image.BILINEAR), np.float32) / 255.0
+
+
+def smooth_in_time(alphas):
+    """3-frame median. Removes single-frame flicker without the lag an average would add."""
+    if len(alphas) < 3:
+        return alphas
+    out = [alphas[0]]
+    for i in range(1, len(alphas) - 1):
+        out.append(np.median(np.stack([alphas[i - 1], alphas[i], alphas[i + 1]]), axis=0))
+    out.append(alphas[-1])
+    return out
+
+
+def clean_edge(alpha: np.ndarray) -> np.ndarray:
+    """Choke by a pixel so the old background cannot leak into the seam, then feather lightly."""
+    choked = np.minimum.reduce([alpha, np.roll(alpha, 1, 0), np.roll(alpha, -1, 0), np.roll(alpha, 1, 1), np.roll(alpha, -1, 1)])
+    return (choked * 4 + np.roll(choked, 1, 0) + np.roll(choked, -1, 0) + np.roll(choked, 1, 1) + np.roll(choked, -1, 1)) / 8
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Transparent cutout of the subject, from ordinary footage.")
+    ap.add_argument("video")
+    ap.add_argument("out_dir", type=Path)
+    ap.add_argument("first", type=int)
+    ap.add_argument("last", type=int)
+    ap.add_argument("--alpha-from", default=None,
+                    help="Optional background-free or green copy of the SAME take, used only for the alpha.")
+    ap.add_argument("--model", choices=sorted(MODELS), default="lite",
+                    help="lite is several times faster and good enough for most shots; full is sharper on hair.")
+    args = ap.parse_args()
+
+    w, h, fps = probe(args.video)
+    count = args.last - args.first + 1
+    args.out_dir.mkdir(parents=True, exist_ok=True)
+
+    frames = list(read_frames(args.video, args.first, count, w, h, fps))
+    if not frames:
+        print("No frames read - check the frame range against the clip's length.", file=sys.stderr)
+        raise SystemExit(1)
+
+    if args.alpha_from:
+        aw, ah, afps = probe(args.alpha_from)
+        if (aw, ah) != (w, h) or abs(afps - fps) > 0.01:
+            print(f"The alpha clip does not match: {aw}x{ah}@{afps:.2f} against {w}x{h}@{fps:.2f}.", file=sys.stderr)
+            print("A mismatched pair makes a halo or a ghost. Re-export it to match, or drop --alpha-from.", file=sys.stderr)
+            raise SystemExit(1)
+        print(f"Alpha from the supplied clip, colour from the original - {count} frames.")
+        alphas = [green_matte(g) for g in read_frames(args.alpha_from, args.first, count, w, h, fps)]
+    else:
+        print(f"Segmenting {count} frames at {w}x{h} with BiRefNet ({args.model}).")
+        print("The first run downloads the model. On a CPU expect a second or two per frame.")
+        torch, model, device = load_segmenter(args.model)
+        print(f"Running on {device}.")
+        alphas = []
+        for i, rgb in enumerate(frames):
+            alphas.append(segment(torch, model, device, rgb))
+            if (i + 1) % 10 == 0 or i + 1 == count:
+                print(f"  {i + 1}/{count}", flush=True)
+
+    for i, a in enumerate(smooth_in_time(alphas)):
+        alpha = (clean_edge(a).clip(0, 1) * 255).round().astype(np.uint8)
+        Image.fromarray(np.dstack([frames[i], alpha]), "RGBA").save(
+            args.out_dir / f"f{args.first + i}.png", compress_level=1
+        )
+
+    print(f"wrote {len(alphas)} frames to {args.out_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/template/scripts/refs.mjs

@@ -16,7 +16,12 @@ import {spawnSync} from 'node:child_process';
 import {existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync} from 'node:fs';
 import {basename, extname, join} from 'node:path';
 
-const FFMPEG = 'D:\\Tools\\ffmpeg\\bin\\ffmpeg.exe';
+// Never hardcode a tool path. media.mjs finds the ffmpeg that ships with the studio
+// (ffmpeg-static, pulled in by npm install) before it looks at PATH, which is what lets this
+// run on a machine that has never had ffmpeg installed on it. A hardcoded path failed
+// silently here: the sheets were simply never generated and nothing said why.
+import {FFMPEG} from './lib/media.mjs';
+
 const REF_DIR = 'references';
 const OUT = join('work', 'refs');
 const all = process.argv.includes('--all');

package/template/scripts/stills.mjs

@@ -13,7 +13,10 @@ import {spawnSync} from 'node:child_process';
 import {mkdirSync, rmSync, writeFileSync} from 'node:fs';
 import {join, resolve} from 'node:path';
 
-const FFMPEG = 'D:\\Tools\\ffmpeg\\bin\\ffmpeg.exe';
+// Never hardcode a tool path. media.mjs finds the ffmpeg that ships with the studio
+// (ffmpeg-static, pulled in by npm install) before it looks at PATH, which is what lets this
+// run on a machine that has never had ffmpeg installed on it.
+import {FFMPEG} from './lib/media.mjs';
 
 const args = process.argv.slice(2);
 const id = args.find((a) => !a.startsWith('--'));

package/template/templates/BRIEF.md

@@ -1,88 +1,90 @@
-# Brief: {{name}}
-
-Fill in what you can. Plain words are fine. Leave a line blank if you don't care.
-When done: drop your files in this folder's `footage/` (and `screenshots/`), then run
-`npm run prep -- {{name}}` and start the session with "start {{name}}".
-
-## Basics
-Format: 16:9            <!-- 16:9, 9:16, or both -->
-Language: en            <!-- en, hi, ar ... the language you speak in the video -->
-Talking head file:      <!-- file name in footage/, e.g. —.mp4. Leave blank if there's only one clip. -->
-Green-screen twin:      <!-- e.g. —-GS.mp4 — only if you want text behind you -->
-Length target:          <!-- e.g. 25s, 90s -->
-
-## Script
-<!-- Paste the script exactly as you read it. Numbers as digits: $99, 11 minutes, 3 days. -->
-
-
-## The one thing viewers must remember
-<!-- One sentence. Everything in the edit serves this. -->
-
-
-## Must-have moments
-<!-- By the words you say, not by time. Plain words are fine.
-- When I say "look at this" → my clip shrinks and other creators' clips appear
-- "millions of views" → a counter racing up to 1M+ -->
-
-
-## Moments from references
-<!-- You DON'T need the name of the effect. Clip + time + what you like about it.
-     Format: - clip-file.mp4 mm:ss-mm:ss — what you like (feel words are fine: snappy, floaty, punchy)
-- a-reel-you-like.mp4 00:02-00:04 — the colour screens flipping with each phrase, feels punchy -->
-
-
-## Effects from the library
-<!-- Optional: pick any by name (see the list at the bottom), and say where.
-- colour flip → "different person, different story" -->
-
-
-## B-roll
-<!-- Which clip where, by the words you say. Mark clips you DON'T want used.
-- creators' clips → "all of these people"  -->
-
-
-## Screenshots / things to blur
-<!-- Names, emails, prices, logos that must not be readable. -->
-
-
-## CTA / ending
-<!-- What the viewer should do, and what the last frame shows. -->
-
-
-## Sound
-SFX library: audio/     <!-- put sound effects in this folder's audio/, or say "none" -->
-Music: added by me in Premiere / Instagram     <!-- or a file name in audio/ -->
-
-## Don't want
-<!-- Anything you dislike: e.g. boxes over my footage, huge text, bouncy motion. -->
-
-
----
-
-### Effects library (names you can use)
-| Name | What it looks like |
-|---|---|
-| Text behind me | Big headline sits behind your head (needs the green-screen twin) |
-| Card swap | You shrink into a rounded card, turn into another clip mid-shrink, a row of cards slides in and drifts |
-| Colour flip | Hard cuts to solid accent / ink screens on each phrase; a word rolls into the next and the colours swap |
-| Counter race | A number races up from 0 and lands on a value (e.g. 1,000,000+) |
-| Zoom-through cut | A jump cut hidden by a quick push-in that eases back — used on every cut by default |
-| Gradient CTA | Dark gradient rises from the bottom, small label + big word typed on the VO, then ticked pointers |
-| Browser mockup | Screenshots inside a clean browser window that pans and zooms to the detail |
-| Pointer click | An arrow glides to a spot and clicks, with a ripple |
-| Rolling number | Digits roll from one value to another (e.g. $26.50 → $48.94) |
-| Highlight marker | Accent marker wipes behind a key phrase |
-| Side card | You move into a card beside the graphics (16:9) or below them (9:16) |
-| Headline to pill | A big headline shrinks into a small corner tag that stays on screen |
-| Word-by-word captions | On by default (looks: clean, block, highlight, pop) |
-| Whip pan | Fast blurred pan between two unrelated shots |
-| Push | The next scene pushes the last one out |
-| Mask wipe | A soft-edged wipe reveals the next scene |
-| Match cut | Cut hidden inside a shared shape or movement |
-| Dip | Quick dip through the background colour |
-| Speed ramp | Glide into slow-mo (or speed-up) and back out |
-| Beat cut | Cuts land on the beat of your music |
-| Tighten it | Silence and filler words removed, every join hidden as a punch-in |
-| Cut to the music | Whole edit built off the track: slow intro, faster build, hardest on the drop |
-| Film look | Grain, halation, light leak, gate weave (looks: clean, film, super8, cinema) |
-| Sound pass | Whooshes, impacts and risers placed off the cut list, ducked under the voice |
+# Brief: {{name}}
+
+Fill in what you can. Plain words are fine. Leave a line blank if you don't care.
+When done: drop your files in this folder's `footage/` (and `screenshots/`), then run
+`npm run prep -- {{name}}` and start the session with "start {{name}}".
+
+## Basics
+Format: 16:9            <!-- 16:9, 9:16, or both -->
+Language: en            <!-- en, hi, ar ... the language you speak in the video -->
+Talking head file:      <!-- file name in footage/, e.g. —.mp4. Leave blank if there's only one clip. -->
+Background-free copy:   <!-- Optional. Leave blank. Only fill this in if you already export a
+                             version with the background removed or replaced by flat green; the
+                             cutout is built automatically from your normal footage otherwise. -->
+Length target:          <!-- e.g. 25s, 90s -->
+
+## Script
+<!-- Paste the script exactly as you read it. Numbers as digits: $99, 11 minutes, 3 days. -->
+
+
+## The one thing viewers must remember
+<!-- One sentence. Everything in the edit serves this. -->
+
+
+## Must-have moments
+<!-- By the words you say, not by time. Plain words are fine.
+- When I say "look at this" → my clip shrinks and other creators' clips appear
+- "millions of views" → a counter racing up to 1M+ -->
+
+
+## Moments from references
+<!-- You DON'T need the name of the effect. Clip + time + what you like about it.
+     Format: - clip-file.mp4 mm:ss-mm:ss — what you like (feel words are fine: snappy, floaty, punchy)
+- a-reel-you-like.mp4 00:02-00:04 — the colour screens flipping with each phrase, feels punchy -->
+
+
+## Effects from the library
+<!-- Optional: pick any by name (see the list at the bottom), and say where.
+- colour flip → "different person, different story" -->
+
+
+## B-roll
+<!-- Which clip where, by the words you say. Mark clips you DON'T want used.
+- creators' clips → "all of these people"  -->
+
+
+## Screenshots / things to blur
+<!-- Names, emails, prices, logos that must not be readable. -->
+
+
+## CTA / ending
+<!-- What the viewer should do, and what the last frame shows. -->
+
+
+## Sound
+SFX library: audio/     <!-- put sound effects in this folder's audio/, or say "none" -->
+Music: added by me in Premiere / Instagram     <!-- or a file name in audio/ -->
+
+## Don't want
+<!-- Anything you dislike: e.g. boxes over my footage, huge text, bouncy motion. -->
+
+
+---
+
+### Effects library (names you can use)
+| Name | What it looks like |
+|---|---|
+| Text behind me | Big headline sits behind your head (works from normal footage) |
+| Card swap | You shrink into a rounded card, turn into another clip mid-shrink, a row of cards slides in and drifts |
+| Colour flip | Hard cuts to solid accent / ink screens on each phrase; a word rolls into the next and the colours swap |
+| Counter race | A number races up from 0 and lands on a value (e.g. 1,000,000+) |
+| Zoom-through cut | A jump cut hidden by a quick push-in that eases back — used on every cut by default |
+| Gradient CTA | Dark gradient rises from the bottom, small label + big word typed on the VO, then ticked pointers |
+| Browser mockup | Screenshots inside a clean browser window that pans and zooms to the detail |
+| Pointer click | An arrow glides to a spot and clicks, with a ripple |
+| Rolling number | Digits roll from one value to another (e.g. $26.50 → $48.94) |
+| Highlight marker | Accent marker wipes behind a key phrase |
+| Side card | You move into a card beside the graphics (16:9) or below them (9:16) |
+| Headline to pill | A big headline shrinks into a small corner tag that stays on screen |
+| Word-by-word captions | On by default (looks: clean, block, highlight, pop) |
+| Whip pan | Fast blurred pan between two unrelated shots |
+| Push | The next scene pushes the last one out |
+| Mask wipe | A soft-edged wipe reveals the next scene |
+| Match cut | Cut hidden inside a shared shape or movement |
+| Dip | Quick dip through the background colour |
+| Speed ramp | Glide into slow-mo (or speed-up) and back out |
+| Beat cut | Cuts land on the beat of your music |
+| Tighten it | Silence and filler words removed, every join hidden as a punch-in |
+| Cut to the music | Whole edit built off the track: slow intro, faster build, hardest on the drop |
+| Film look | Grain, halation, light leak, gate weave (looks: clean, film, super8, cinema) |
+| Sound pass | Whooshes, impacts and risers placed off the cut list, ducked under the voice |