luckiest-co 1.0.31 → 1.0.33

package/skills/luckiest-video-studio/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: luckiest-video-studio
-description: "Make product launch videos, product demos with motion design between the demo shots, and logo motion showcases of a design portfolio, and keep every one editable after it is rendered. Reads the project or portfolio, plans a storyboard, builds motion scenes with HyperFrames, records or places demo footage, renders each scene as its own clip, then hands back an MP4 plus the editable pieces: a storyboard.json that re-renders one scene at a time, a Concat editor project to trim, caption, and export (OpenScreen or Diffusion Studio on request), and optional After Effects compositions. Use for 'make a launch video', 'product demo video', 'demo with motion graphics', 'logo animation', 'logo reveal', 'motion showcase of my work', 'portfolio reel', 'animate my logos', 'brand reel', 'turn my talking-head recording into a reel', 'add graphics over me talking', 'turn this into a video', 'change scene 3 of the video', or 'let me edit the video after'. For AI-generated footage, avatars, and text-to-video models use luckiest-video. For what to post and when use luckiest-social."
+description: "Make product launch videos, product demos with motion design between the demo shots, and logo motion showcases of a design portfolio, and keep every one editable after it is rendered. Reads the project or portfolio, plans a storyboard, builds motion scenes with HyperFrames, records or places demo footage, renders each scene as its own clip, then hands back an MP4 plus the editable pieces: a storyboard.json that re-renders one scene at a time, a review player to edit copy, pin notes on the frame, and send changes back in one prompt (Concat, OpenScreen, or Diffusion Studio on request), and optional After Effects compositions. Use for 'make a launch video', 'product demo video', 'demo with motion graphics', 'logo animation', 'logo reveal', 'motion showcase of my work', 'portfolio reel', 'animate my logos', 'brand reel', 'turn my talking-head recording into a reel', 'add graphics over me talking', 'turn this into a video', 'change scene 3 of the video', or 'let me edit the video after'. For AI-generated footage, avatars, and text-to-video models use luckiest-video. For what to post and when use luckiest-social."
 license: See ATTRIBUTION.md
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
 metadata:
-  version: "1.8.1"
+  version: "1.13.0"
   listing_id: luckiest-video-studio
   author: luckiest
 ---
@@ -13,19 +13,19 @@ metadata:
 
 Short videos that show the real product, with motion design between the demo
 shots, and that stay editable after the render. The editability is the point:
-every run leaves a storyboard, per-scene clips, and a timeline project, not just
+every run leaves a storyboard, per-scene clips, and a review player, not just
 an MP4.
 
 ## Staying current
 
 On activation, call the Luckiest MCP `check_updates` tool with
-`{ listingId: "aff888e4-9ee9-4f73-af08-74d5d09d3c10", installedSemver: "1.8.1" }`. If it returns
+`{ listingId: "aff888e4-9ee9-4f73-af08-74d5d09d3c10", installedSemver: "1.13.0" }`. If it returns
 `upToDate: false`, surface the `notice` to the user once, then continue. Do nothing
 further if `upToDate: true`. Never block on this check; if the tool is unavailable,
 proceed.
 
 When the skill's work is done, call the Luckiest MCP `report_usage` tool once with
-`{ listing_id: "luckiest-video-studio", skill_version: "1.8.1", matched: true, success: <true if the skill completed, false otherwise> }`.
+`{ listing_id: "luckiest-video-studio", skill_version: "1.13.0", matched: true, success: <true if the skill completed, false otherwise> }`.
 Metadata only, never prompt text. Never block on it; if the tool is unavailable,
 skip silently.
 
@@ -37,7 +37,8 @@ skip silently.
    [SECURITY.md](SECURITY.md).
 2. **Show the real thing.** Use the project's actual UI, copy, and logos. Never
    invent numbers, testimonials, or results. Charts use relative sizes until the
-   user gives real figures.
+   user gives real figures. Every number the video shows is listed once in
+   `storyboard.json` `facts` and reads the same in every scene.
 3. **Nothing secret on screen.** Everything read can end up in a public video.
    Never show keys, tokens, `.env` values, customer data, or private URLs.
 4. **Local assets only.** Compositions load files copied into the output folder,
@@ -68,14 +69,15 @@ in `<skill-dir>/assets/sfx/`. Resolve it; never assume an install path.
 |---|---|---|
 | `--mode` | `launch`, `demo`, `logos` | inferred |
 | `--tone` | preset or freeform ([references/tones.md](references/tones.md)) | inferred |
-| `--format` | `landscape`, `vertical`, `square` | `landscape` |
+| `--format` | `landscape`, `vertical`, `square`: the master size scenes are designed at | `landscape` |
+| `--formats` | comma list of `landscape`, `vertical`, `square`: render the same video once per format, one file each | master only |
 | `--duration` | seconds | per mode |
 | `--no-music`, `--no-sfx` | flags | on |
 | `--voice` | flag, Kokoro via HyperFrames | off |
 | `--scene <id>` | re-render one scene of an existing run | none |
 | `--ae` | also build After Effects compositions | off |
 | `--ref <url-or-mp4>` | inspiration video to study first | none |
-| `--editor` | `concat`, `openscreen`, `diffusion`, or several for the editing handoff | `concat` |
+| `--editor` | `review`, `concat`, `openscreen`, `diffusion`, or several for the editing handoff | `review` |
 
 If the user asks to change an existing video ("make scene 3 slower", "swap the
 logo in the outro"), skip to **Edit an existing run** below.
@@ -99,7 +101,9 @@ video-studio-output/
   final.mp4           all clips joined, poster baked as frame 0
   poster.jpg
   TIMING.md           every scene with its in/out time and the line it covers
-  concat/             the Concat project (default editor); project.concat.txt holds its path
+  reel.json           what the review player reads (default editor), rewritten on every render
+  qa/review-notes.json  your own notes, pinned in the review player before the user opens it
+  concat/             the Concat project (with --editor concat); project.concat.txt holds its path
   project.openscreen.txt  path to the OpenScreen timeline in ~/Movies/Openscreen/<slug>/ (with --editor openscreen)
   share-copy.txt
 ```
@@ -107,7 +111,8 @@ video-studio-output/
 ## Step 0: Check tools
 
 Confirm `node`, `ffmpeg`, and `ffprobe`. HyperFrames runs via `npx hyperframes`.
-For timeline editing, Concat (`concat-cli` on `PATH`, see
+The default editor, the review player (`luckiest-video-studio-review`), needs
+only `node`. For timeline editing, Concat (`concat-cli` on `PATH`, see
 [references/concat.md](references/concat.md)) is optional. For demo recordings,
 OpenScreen 1.13.0 at `/Applications/Openscreen.app` is optional. Report what is
 missing in one line and continue with what exists: without an editor the run still
@@ -199,6 +204,7 @@ scene before both.
 **Read:** the HyperFrames skills `hyperframes-core`, `hyperframes-animation`,
 `hyperframes-keyframes`, `hyperframes-creative`, `hyperframes-cli`, then
 [references/step-3-compose.md](references/step-3-compose.md),
+[references/lessons.md](references/lessons.md) (traps that cost a debug round),
 [references/audio.md](references/audio.md), and the `luckiest-video-studio-motion`
 sub-skill for easing, duration, origin, and transitions. Read the `luckiest-video-studio-composition` sub-skill for
 focal placement, grids, and white space at each scene's hold frame. Do not enter the `hyperframes` intent
@@ -216,7 +222,13 @@ footage the user supplies; copy it into `demo/`.
 
 Render every scene to `clips/` with `scripts/render-scenes.mjs` (it skips scenes
 whose inputs did not change), join them into `final.mp4`, bake the best frame as
-`poster.jpg` and frame 0, and write `TIMING.md` and `share-copy.txt`.
+`poster.jpg` and frame 0, and write `TIMING.md` and `share-copy.txt`. With
+`--formats`, finish and approve the master first, then add `formats` to the
+storyboard: `render-scenes.mjs --stills` gives one hold-frame sheet per format to
+check (and `qa.mjs safe --stills`) without rendering, and the render reuses the
+master's landscape clips so only the new formats render into `clips/<format>/` and
+`final-<format>.mp4`. Scenes re-lay out by the rules in "Build once, render every
+format" (`step-3-compose.md`), and demo footage is cropped around each scene's `focus`.
 
 Then run the QA gates in `scripts/qa.mjs` on the result (each exits 1 on a fail;
 `node --test scripts/qa.test.mjs` shows each one failing its control):
@@ -227,8 +239,16 @@ node <skill-dir>/scripts/qa.mjs deadframes <output-dir>/final.mp4     # black fr
 node <skill-dir>/scripts/qa.mjs legibility <output-dir>/final.mp4     # nothing readable on screen
 node <skill-dir>/scripts/qa.mjs crossfade  <output-dir>/composition   # full-frame opacity fades
 node <skill-dir>/scripts/qa.mjs motion     <output-dir>/composition   # ease-in entrances, scale 0 cards, short linear moves
+node <skill-dir>/scripts/qa.mjs avsync     <output-dir>/final.mp4 --expect <hero hit times> --duration <s>   # audio present, length right, hits within one frame
+node <skill-dir>/scripts/qa.mjs facts      <output-dir>               # on-screen numbers not in storyboard facts, em dashes on screen
+node <skill-dir>/scripts/qa.mjs loop       <output-dir>/final.mp4     # only for looping pieces: last frame matches the first
+node <skill-dir>/scripts/qa.mjs safe       <output-dir>               # text or logo edges in each format's platform-covered margins
 ```
 
+Skip `avsync` only with `--no-music --no-sfx`. Pass the hero hit times from
+`TIMING.md` to `--expect`. A hit more than one frame off means its audio element's
+`data-start` or the cue time is wrong.
+
 Then run `luckiest-video-studio-composition --review` on the run. It writes
 `qa/composition-review.md` with a verdict per scene. Fix every scene it blocks.
 
@@ -242,6 +262,17 @@ Then run `luckiest-video-studio-motion --review` on the run. It writes
 `qa/motion-review.md` with a verdict per scene. Fix and re-render every scene it
 blocks before the judge.
 
+Then watch the result with `luckiest-video-watcher` in quick mode, local engine
+only, with `--out-dir <output-dir>/qa/watch`. When earlier gates flagged times,
+pass only those with `--timestamps`. It reads frames and the transcript together,
+so it catches what the frame-only reviews miss: captions that differ from the
+voiceover, audio that cuts out, and text clipped at a scene seam. The voiceover
+check needs a transcription backend and is skipped for runs without voiceover.
+With `--formats`, watch the landscape final and the other formats only at
+flagged times. Fix every
+`m:ss` issue it reports. If the watcher is not installed, say so in one line and
+skip this step.
+
 The talk and reel sub-skills add `beatsync`, `tokens`, `presence`, `face`, and `beatgrid`.
 
 **Judge each new version against the last one.** Keep the previous render as
@@ -264,41 +295,50 @@ differences the judge named. Stop at v3, when a version loses, or when only
 changes too small to see are left.
 
 **Gate:** `final.mp4` plays end to end, every scene in `storyboard.json` has a
-clip, the five gates pass or each failure is explained in `TIMING.md`, no scene is
+clip, the seven gates pass or each failure is explained in `TIMING.md`, no scene is
 left blocked in `qa/motion-review.md`, and
 every judge verdict from v2 on is recorded there.
 
 ## Step 5: Hand off for editing
 
-**Read:** [references/concat.md](references/concat.md)
-
-Write the Concat project with `scripts/assemble-concat.mjs <run-dir>`. If
-`concat-cli` is missing, say so in one line and offer `--editor openscreen`. Tell
-the user the three ways to edit, in this order:
+Hand the run folder to the `luckiest-video-studio-review` sub-skill. It writes
+`reel.json`, pins your own review notes, and opens the review player in the
+browser. Tell the user the ways to edit, in this order:
 
-1. **Ask again.** "Change scene 3's headline" edits `storyboard.json` and
+1. **Review player.** Edit (E) to change a scene's copy and colors, N to pin a
+   note on the frame, Approved to lock a scene, then **Send to Claude** and paste
+   the prompt here. See **Edit an existing run** below.
+2. **Ask again.** "Change scene 3's headline" edits `storyboard.json` and
    re-renders only that scene.
-2. **Timeline.** Open the project named in `project.concat.txt` in Concat to trim,
-   reorder, caption, add effects, and export.
-   With `--editor openscreen`, run `scripts/assemble-openscreen.mjs` instead (or as
-   well) for cursor zoom on demo recordings. See
-   [references/openscreen.md](references/openscreen.md).
+3. **Timeline** (on request). With `--editor concat`, run
+   `scripts/assemble-concat.mjs <run-dir>` and open the project named in
+   `project.concat.txt` in Concat to trim, reorder, caption, add effects, and
+   export. See [references/concat.md](references/concat.md). If `concat-cli` is
+   missing, say so in one line.
+   With `--editor openscreen`, run `scripts/assemble-openscreen.mjs` for cursor
+   zoom on demo recordings. See [references/openscreen.md](references/openscreen.md).
    With `--editor diffusion`, run `scripts/assemble-diffusion.mjs <run-dir> --open`:
    logo scenes become native Diffusion Studio scenes with inspector controls. See
    [references/diffusion.md](references/diffusion.md).
-3. **After Effects** (with `--ae`). Hand the run folder to the
+4. **After Effects** (with `--ae`). Hand the run folder to the
    `luckiest-video-studio-ae` sub-skill, which rebuilds motion and logo scenes as
    After Effects precomps through `luckiest-ae-mcp`.
 
 ## Edit an existing run
 
-Read `storyboard.json` from the run folder. Change only the scenes the request
-touches, re-render them with `scripts/render-scenes.mjs --scene <id>`, rejoin
-`final.mp4` and `TIMING.md`, then rerun `scripts/assemble-concat.mjs`. Never
-rebuild untouched scenes. Rerunning it starts a fresh Concat project and keeps the
-old one as `concat-<timestamp>/`, so tell the user where any edits they made in
-Concat now live. With `--editor openscreen` or `diffusion`, rerun
-that editor's script too.
+When the user pastes a prompt from the review player (it starts with "Motion OS
+feedback for"), hand it to `luckiest-video-studio-review`: edits set
+`storyboard.json` values exactly, notes are read against the frame they point at,
+and approved scenes stay untouched.
+
+For any change, read `storyboard.json` from the run folder. Change only the scenes
+the request touches, re-render them with `scripts/render-scenes.mjs --scene <id>`,
+rejoin `final.mp4` and `TIMING.md`, then rerun the review sub-skill's
+`scripts/build-reel.mjs` so the open player loads the new version. Never rebuild untouched scenes. With
+`--editor concat`, rerun `scripts/assemble-concat.mjs` too: it starts a fresh
+Concat project and keeps the old one as `concat-<timestamp>/`, so tell the user
+where any edits they made in Concat now live. With `--editor openscreen` or
+`diffusion`, rerun that editor's script too.
 
 ## Creative laws
 

package/skills/luckiest-video-studio/references/audio.md

@@ -187,22 +187,67 @@ When in doubt, pick fewer cues with better timing. Prefer a coherent sonic palet
 
 ## Timing rules
 
-These rules apply when Hyperframes is implementing the composition and the motion timings are known:
+These rules apply when Hyperframes is implementing the composition and the motion timings are known.
 
-- Align SFX to the **start** of the animation, not the end
-- Entry pop: 0.0–0.1s before the element's first visible frame
-- Transition: at the transition start time
-- Success ding: at the moment the metric/stat is fully visible
-- For staggered elements: usually accent the first, final, or strongest beat; only score every item when that rhythm is intentional and still feels clean
+Each sound has an anchor: the part of it that must land on the frame. Place the
+anchor, not the file start.
+
+| Sound | Anchor | Place it so |
+|---|---|---|
+| Pop, click, key, drop | start | it starts 0.0-0.1s before the element's first visible frame |
+| Whoosh, swoosh | loudest point | its peak sits on the cut, so it starts before the cut |
+| Riser, reverse swell | end | it ends on the hit it leads into |
+| Impact, bell, boom | start | it starts on the hit frame |
+| Success ding | start | the metric or stat is fully visible |
+
+The bundled library has no whooshes or risers. Source them with HyperFrames
+`media-use` (license noted) or use ones the user supplies.
+
+- **Times come from the cue file, never by ear.** Use the scene timings in
+  `storyboard.json` and the beat or drop times from the cue JSON (see Beat and
+  cue sources below).
+- **Layer the big moments.** The hero hit is a swell or riser ending on the frame,
+  an impact starting on it, and a low sub under it. Smaller beats get one sound.
+- **Gain ladder.** UI detail (keys, clicks) 0.25-0.4, transitions (whooshes)
+  0.45-0.6, hits 0.7-0.9. One hero hit per scene owns its moment: drop smaller
+  cues that land within a few frames of it.
+- **Duck the music under the hero hits.** Lower the music bed by about a third
+  for half a second around each hero hit (a short volume tween on the music
+  element), so the hit reads without raising it.
+- **Staggered elements:** usually accent the first, final, or strongest beat;
+  only score every item when that rhythm is intentional and still feels clean.
 
 Composition notation:
 ```
 Scene 2 — Reveal — 3s
-  "Horse Tinder" scales in at 0.3s  →  SFX: impact/impactSoft_medium_001 at 0.2s
-  Tagline fades up at 0.8s          →  (no SFX, let the reveal carry)
-  Transition at 3.0s                →  SFX: interface/drop_001 at 2.9s
+  Riser into the reveal (1.2s long)  →  SFX: ends at 0.3s, so starts at -0.9s (previous scene)
+  "Horse Tinder" scales in at 0.3s   →  SFX: impact/impactSoft_medium_001 at 0.3s, music ducked 0.2-0.7s
+  Tagline fades up at 0.8s           →  (no SFX, let the reveal carry)
+  Cut to scene 3 at 3.0s             →  SFX: whoosh peaking at 3.0s
 ```
 
+### Many cues: one SFX track
+
+Past about 10 cues (typing, card stacks, a dense demo), stop writing one
+`<audio>` element per sound. List the cues in `<output-dir>/audio/sfx_cues.json`
+and mix them into one track:
+
+```bash
+node <skill-dir>/scripts/sfx-cues.mjs <output-dir>/audio/sfx_cues.json --events <output-dir>/composition
+```
+
+Each cue is `{ t, file or kind, align, volume, label }`; `file` is relative to
+`<skill-dir>/assets/sfx/` or absolute for a sourced sound, and `align` is the
+anchor from the table above (`start`, `peak`, or `end`). Scene builders can also
+write `composition/<scene-id>.motion.json` with local event times (`key`, `click`,
+`pop`, `card`, `impact`, `success`, and more), and `slots` in the cue file maps each
+scene to its start (the In column of `TIMING.md`), so every keystroke lands on its
+frame. It writes `audio/sfx.wav` and `audio/sfx-cuesheet.md` (hand the cue sheet
+over in Step 4). Set `"sfx": { "file": "audio/sfx.wav" }` in `storyboard.json`:
+`render-scenes.mjs` mixes it under the joined video, like the music bed. Leave
+those cues out of the scenes' own `<audio>` elements, and check the render with
+`qa.mjs avsync`.
+
 ---
 
 ## Music
@@ -211,6 +256,12 @@ Scene 2 — Reveal — 3s
 
 Ask the user for a music file, or use HyperFrames `media-use` to source one and keep its license note. Match energy to tone: upbeat for `default` and `app-store`, steady and clean for `polished` and `cinematic`, very low volume (0.12-0.18) for `deadpan`. Skip music only when the plan chooses silence or `--no-music` is set.
 
+Land the track, do not just start it. Find the first strong kick or the moment the
+groove enters (the cue JSON's `strongCues`), pick the video moment it should hit
+(the reveal, the title, the cut into the product), and set `music.offset` and
+`music.at` in `storyboard.json` so they meet. `render-scenes.mjs` places it there
+and normalizes the final mix to -14 LUFS.
+
 ### In a composition
 
 After copying files (see Asset paths above), reference them with relative paths from `composition/`:
@@ -219,7 +270,7 @@ After copying files (see Asset paths above), reference them with relative paths
 <audio id="bg-music" data-start="0" data-duration="[total]" data-track-index="10" data-volume="0.35" src="assets/music/<user-track>.mp3"></audio>
 ```
 
-Volume: 0.3-0.4 for normal music beds. Use 0.12-0.22 for deadpan or very restrained parody. Never above 0.5. SFX at 0.55-0.85, with softer values for polished/deadpan.
+Volume: 0.3-0.4 for normal music beds. Use 0.12-0.22 for deadpan or very restrained parody. Never above 0.5. SFX follow the gain ladder in Timing rules, with softer values for polished/deadpan.
 
 If the music file doesn't exist, skip it and notify the user after rendering.
 

package/skills/luckiest-video-studio/references/concat.md

@@ -1,9 +1,10 @@
-# Editing in Concat (`--editor concat`, the default)
+# Editing in Concat (`--editor concat`)
 
 Concat (`jub0t/Concat`, AGPL-3.0) is a free, local video editor for macOS,
 Windows, Linux, and Android, with a scriptable API. Exports have no watermark, it
 needs no account, and the agent can build and export a project without anyone
-clicking. That is why it is the default editor. Use OpenScreen
+clicking. Use it when the user wants a timeline. The review player
+(`luckiest-video-studio-review`) is the default for reviewing a run. Use OpenScreen
 ([openscreen.md](openscreen.md)) for recorded product demos with cursor zoom, and
 Diffusion Studio ([diffusion.md](diffusion.md)) when line-draw logo scenes need to
 stay native and editable.

package/skills/luckiest-video-studio/references/lessons.md

@@ -0,0 +1,44 @@
+# Build lessons
+
+Each of these broke a real HyperFrames build once. Read them before writing a
+scene. The project layout rules are in `step-3-compose.md`; these are the traps
+that layout does not cover.
+
+## Scenes
+
+- **No id inside a scene may equal its host slot's id.** If
+  `compositions/hook.html` has an element `id="scene-hook"` and the root hosts it in
+  `<div id="scene-hook">`, the scene never mounts and nothing errors.
+- **Drive changing state from a tween, not a callback.** For a counter, a typed
+  line, or a canvas, tween a plain clock object from 0
+  (`tl.to(clock, { t: dur, ease: "none", onUpdate: draw }, 0)`) and draw from
+  `clock.t`. `tl.call` fires only when playback crosses it, so a renderer that
+  seeks backward or jumps into the middle shows the wrong state.
+- **Seeded randomness only.** Use a small seeded generator (mulberry32 with a fixed
+  seed) for scatter, noise, and particles. `Math.random()` and `Date` give a
+  different frame on every render, so a one-scene re-render no longer matches.
+- **Shared backgrounds stay in the root.** When `index.html` owns a background
+  that runs across scenes (a sky, grain, a HUD), scenes must be transparent. A
+  scene that paints its own full-frame ground hides it.
+- **Overlap scene hosts for reveals.** When the next scene should reveal itself
+  over the last one, start its host a few tenths of a second before the last one
+  ends. Back-to-back hosts can only hard cut.
+
+## WebGL and three.js
+
+- **Load three.js once, in the root `<head>`**, from `composition/assets/vendor/`.
+  Loading it again inside a scene replaces the global `THREE` and drops add-ons
+  such as `TextGeometry`.
+- **Render WebGL from the timeline.** Create the renderer with
+  `preserveDrawingBuffer: true` and call `renderer.render` from one clock tween's
+  `onUpdate`, never from `requestAnimationFrame`.
+
+## Rendering
+
+- **Check free disk before a long render.** HyperFrames refuses to render with
+  under about 1 GB free, and a long 1080p render wants 3 GB or more. Run
+  `df -h .` first and tell the user if space is short.
+- **Render with fewer workers when other renders are running** (`--workers 2`), or
+  two renders on one machine starve each other and time out.
+- **Use absolute paths in background commands.** A background shell does not keep
+  your working directory.

package/skills/luckiest-video-studio/references/step-2-plan.md

@@ -46,6 +46,13 @@ landing-page-only, write "none — landing-page only" and rely on Key moments in
 - Interpretation: [one sentence on how this affects pacing, writing, visual energy, and restraint]
 
 ## Format: [landscape / vertical / square] — [width]x[height]
+## Also render: [none / vertical / square / landscape]
+Ask which formats the video goes out in when the user names more than one place to
+post it (TikTok and YouTube, Reels and LinkedIn): vertical 1080x1920 for TikTok,
+Reels, and Shorts, square 1080x1080 for feeds, landscape 1920x1080 for YouTube and
+the web. Default is the master format only. Each extra format costs one more render,
+not one more design, and is added to storyboard `formats` only after the master is
+approved (`step-4-deliver.md`, "Other formats (last)").
 ## Duration: [target seconds]
 
 ## Visual identity (from the project)
@@ -178,7 +185,31 @@ If a scene has either of these, commit to it explicitly in the scene description
 
 Hyperframes can implement both patterns well — but only if the plan specifies what's appearing, in what order, and that interaction is being simulated. The plan is the contract.
 
-## Audio planning
+## One shape, never cut (state list)
+
+When the product is a set of UI states (a button that becomes a loader, then a
+player, then a chart), plan the scene as a **state list** instead of a shot list.
+One element carries the whole scene: it morphs size, radius, color, and content
+from state to state, a cursor drives each change with a real click, and nothing
+cuts. Write it in `storyboard.json` as `scenes[].states`:
+
+```json
+"states": [
+  { "t": 0,   "label": "Send invoice", "shape": "button 240x56 r28 #1F1447" },
+  { "t": 0.9, "label": "Sending",      "shape": "loader 56x56 r28",  "cursor": "click" },
+  { "t": 1.6, "label": "Paid $2,860.50", "shape": "card 420x140 r22 #22C55E" },
+  { "t": 3.2, "label": "Send invoice", "shape": "button 240x56 r28 #1F1447" }
+]
+```
+
+- Each state names what the viewer reads and the shape it holds. The move between
+  two states retargets one spring (`Spring.track` from the motion sub-skill), so the
+  element never restarts or stops dead.
+- Hold each state long enough to read it (the reading-time rule below), and let
+  the cursor arrive before the click, never with it.
+- For a loop (a social post, a hero background), the last state equals the first,
+  and `qa.mjs loop` checks that the rendered last frame matches the first.
+
 
 Choose the music direction in the plan. Leave exact SFX file selection and exact timestamps to Hyperframes during composition, because SFX should match the actual visual implementation.
 

package/skills/luckiest-video-studio/references/step-3-compose.md

@@ -14,6 +14,7 @@ Create a short launch-style video for [App Name].
 - Composition directory: `<output-dir>/composition/`
 - Rendered video: `<output-dir>/final.mp4`
 - Format: [landscape / vertical / square] — [width]x[height]
+- Also render: [none / vertical / square / landscape] (storyboard `formats`)
 - Duration: [15-25 seconds]
 
 ## Source Material
@@ -204,6 +205,32 @@ Learned on a real run with HyperFrames 0.8.x:
 - Give every timed element an `id`, or check warns that Studio cannot edit it.
 - Before the full render, check every scene's hold frame in one pass: `hyperframes snapshot . --at <hold1>,<hold2>,... --no-end -o ../qa/holds`, then read `qa/holds/contact-sheet.jpg`.
 
+### Build once, render every format
+
+When the storyboard lists `formats`, `render-scenes.mjs` renders each motion and logo
+scene once per format from a stamped copy. The stamp sets the root `data-width`,
+`data-height`, and `data-format` (`landscape`, `vertical`, `square`) and appends these
+tokens after your styles:
+
+| Token | Value |
+|---|---|
+| `--w`, `--h` | Canvas size in px |
+| `--u` | One hundredth of the short side: 10.8px at all three sizes |
+| `--safe-t`, `--safe-b`, `--safe-l`, `--safe-r` | Safe area per side, from `luckiest-video-studio-composition/references/grids-and-ratios.md`. Vertical is the strictest of TikTok, Reels, and Shorts combined: 288, 672, 119, 194 |
+
+Write every scene so the same HTML lays out at any of the three sizes:
+
+1. Declare the master defaults on `:root` (`--w:1920px;--h:1080px;--u:10.8px;--safe-t:54px;--safe-b:54px;--safe-l:96px;--safe-r:96px` for landscape) so the scene still previews on its own.
+2. `html,body{width:var(--w);height:var(--h)}`. Never write the canvas size in px.
+3. Size type, spacing, strokes, and boxes in `calc(var(--u) * n)`, never raw px. Text that would cross the safe area wraps or shrinks; it never runs into it.
+4. Keep every word, logo, and CTA inside a box inset by the safe tokens: `position:absolute; inset:var(--safe-t) var(--safe-r) var(--safe-b) var(--safe-l)`, plus `margin:auto` and a fixed size to center it in the safe area. Padding on the composition root does not move clip elements, so put the insets on the clips themselves. Vertical's safe area sits high (288 top, 672 bottom), so center there, not on the frame.
+5. Restack with `[data-format=vertical]` and `[data-format=square]` selectors: side-by-side rows become columns, a 12-column grid becomes 6. Never make vertical by cropping a landscape layout.
+6. In vertical, set headline and body type 15 to 25% larger than landscape (`calc(var(--u) * 10)` where landscape uses 8), because the phone shows the whole frame smaller.
+7. Motion distances in GSAP use the same tokens: read them once with `getComputedStyle(document.documentElement).getPropertyValue("--u")` and multiply, so a slide is the same share of the frame in every format.
+8. Check each format's hold frame without rendering: `render-scenes.mjs <run-dir> --stills` writes `stills/<format>/sheet.png` per format, and `qa.mjs safe <run-dir> --stills` fails any text outside the format's safe area. Do this once the master is approved (`step-4-deliver.md`, "Other formats (last)"), not on every iteration.
+
+`templates/logo-line-draw.html` is a worked example.
+
 ---
 
 ## Self-review checklist
@@ -213,6 +240,7 @@ Before moving to delivery, verify:
 - [ ] `<output-dir>/composition-brief.md` exists.
 - [ ] The brief clearly identifies the exact product moments to show.
 - [ ] The composition uses the current Hyperframes workflow, not a hardcoded `luckiest-video-studio` template.
+- [ ] With `formats`, every scene sizes itself with `--w`, `--h`, `--u`, and the safe tokens, and restacks under `[data-format]`; no canvas size in px.
 - [ ] Music file is copied into `<output-dir>/composition/assets/music/`.
 - [ ] At least one visual element subtly reacts to the music (audio-reactive treatment present), or extraction failure is documented.
 - [ ] At least 1 major tween is beat-locked to a strong cue (a `strongCue`, or the highest-`strength` beat from `hyperframes beats`) within ±0.15s, marked `// beat-locked` (or natural timing was chosen for readability).

package/skills/luckiest-video-studio/references/step-4-deliver.md

@@ -43,6 +43,28 @@ For final delivery:
 npx hyperframes render --quality high --output ../final.mp4
 ```
 
+## Other formats (last)
+
+Formats come after the master 16:9 is approved, never during iteration: every format
+multiplies render time. When the plan lists other formats:
+
+1. Render the approved master at delivery quality with `scripts/render-scenes.mjs`
+   (no `formats` yet), so `final.mp4` and `clips/` are done.
+2. Add `formats` to `storyboard.json` (for example `["landscape", "vertical", "square"]`).
+3. Check layouts from stills, not video:
+   `node <skill-dir>/scripts/render-scenes.mjs <run-dir> --stills` writes one hold
+   frame per scene per format to `stills/<format>/` and a `sheet.png` for each.
+   Read the sheets, then run `node <skill-dir>/scripts/qa.mjs safe <run-dir> --stills`.
+   Fix and repeat; each pass costs about 8s per scene per format, not a render.
+4. Render with the same `--quality` as step 1. The landscape clips are reused from
+   the 16:9 render (`reuse` in the log), so only the new formats render.
+5. The `luckiest-video-watcher` pass already ran on the master. Do not watch the new
+   formats end to end: the stills sheets cover their layout, so watch them only at
+   times a gate flagged (`--timestamps`).
+
+A scene's hold frame is `scenes[].hold` seconds into the scene, else 0.5s before
+its cut. Set `hold` on a scene that exits early.
+
 ## Pick the poster frame
 
 The poster is the still shown before the video plays — the first thing anyone sees when it's idle or unplayed. Don't leave it to the raw first frame or an arbitrary timestamp; those land on fades, mid-transitions, blank intro backgrounds, or half-rendered text.
@@ -150,6 +172,7 @@ After this step, `<output-dir>/` should contain:
 ```
 <output-dir>/
   final.mp4                — the rendered video
+  final-<format>.mp4       — one per format instead, when the storyboard lists `formats`
   poster.jpg                — the poster (best frame, for <video poster>)
   plan.md            — the plan and storyboard
   composition-brief.md    — the Hyperframes handoff brief
@@ -162,7 +185,7 @@ After this step, `<output-dir>/` should contain:
 ## Telling the user
 
 After everything is done, tell the user:
-- Where the video is (`<output-dir>/final.mp4`)
+- Where the video is (`<output-dir>/final.mp4`, or each `final-<format>.mp4` and where it is meant to post)
 - Where the share copy is
 - One sentence on what the video does creatively
 - Optionally: offer to re-roll a scene, change tone, or try a different angle

package/skills/luckiest-video-studio/references/storyboard.md

@@ -14,6 +14,7 @@ this file and re-renders only what it touched. Schema:
   "mode": "demo",
   "tone": "polished",
   "format": { "width": 1920, "height": 1080, "fps": 30 },
+  "formats": ["landscape", "vertical", "square"],
   "hyperframes": "0.8.84",
   "music": { "file": "audio/bed.mp3", "volume": 0.3, "license": "user supplied" },
   "scenes": [
@@ -27,16 +28,23 @@ this file and re-renders only what it touched. Schema:
 
 | Field | Meaning |
 |---|---|
-| `format` | Output size and frame rate. Landscape 1920x1080, vertical 1080x1920, square 1080x1080. |
+| `format` | Master size and frame rate. Landscape 1920x1080, vertical 1080x1920, square 1080x1080. Scenes are designed and reviewed at this size. |
+| `formats` | Optional. Render the same scenes once per listed format: `landscape` 1920x1080, `vertical` 1080x1920, `square` 1080x1080, all at `format.fps`. Motion and logo scenes re-lay out for each size (see "Build once, render every format" in `step-3-compose.md`); they are never cropped. Only demo footage is cropped, around `scenes[].focus`. Omit it to render `format` alone. |
 | `hyperframes` | Pinned HyperFrames version so a re-render months later looks the same. |
-| `music` | Optional bed mixed under the joined video, looped and faded out. Licensed files only. |
+| `music` | Optional bed mixed under the joined video, looped and faded out. Licensed files only. `offset` skips into the track and `at` starts it in the video, so a chosen kick lands on a chosen moment: a kick 10.4s into the track on a cut at 3.0s is `"offset": 7.4, "at": 0` or `"offset": 10.4, "at": 3`. |
+| `facts` | Every number, price, and id the video shows, as short phrases: `["3 unpaid invoices, $4,792.44 total", "Tom Becker INV-0039, 5 days late"]`. Write them in Step 2 from the project's real data. `qa.mjs facts` fails any on-screen number with two or more digits, a currency sign, a percent, or an id that no fact contains, and any em dash on screen. Add decorative numbers (a timecode, a year) here too. |
+| `loudness` | Integrated loudness of `final.mp4` in LUFS, default `-14` (the streaming norm), two-pass with a -1.2 dBTP ceiling. `false` skips it. |
+| `sfx` | Optional `{ "file": "audio/sfx.wav", "volume": 1 }` from `scripts/sfx-cues.mjs`, mixed under the joined video at 0 s. Cue times are global, so re-run the mixer after a scene's length changes. |
 | `scenes[].id` | Lowercase and hyphens. Stable: edits refer to scenes by id. |
 | `scenes[].kind` | `motion` (HyperFrames scene), `logo` (HyperFrames logo recipe), `demo` (footage). |
 | `scenes[].composition` | For motion and logo, the sub-composition under `composition/`. Default `compositions/<id>.html`. |
 | `scenes[].source`, `sourceStart` | For demo, the footage file and where to start in it. |
+| `scenes[].focus` | For demo, `{ "x": 0.5, "y": 0.5 }` as fractions of the source frame: the point kept in view when the footage is cropped to a different shape (a 16:9 screen recording in a vertical cut). Set it on the cursor, the face, or the UI the line talks about. |
 | `scenes[].variables` | Copy, colors, and file paths the composition reads. Keep editable values here, not hardcoded in HTML. |
 | `scenes[].assets` | Other files the scene depends on (logo SVG, shared CSS). Changing one re-renders the scene. |
+| `scenes[].states` | For a one-shape morph scene, the state list: `{ t, label, shape, cursor? }` per state, local times. See "One shape, never cut" in `step-2-plan.md`. |
 | `scenes[].line` | One line on what the scene says or shows. Goes into `TIMING.md`. |
+| `scenes[].hold` | Optional. Seconds into the scene where `--stills` captures its hold frame. Default 0.5s before the cut. |
 
 ## Rendering
 
@@ -45,6 +53,7 @@ node <skill-dir>/scripts/render-scenes.mjs <run-dir>                    # render
 node <skill-dir>/scripts/render-scenes.mjs <run-dir> --scene stat       # force one scene
 node <skill-dir>/scripts/render-scenes.mjs <run-dir> --quality draft    # fast pass while iterating
 node <skill-dir>/scripts/render-scenes.mjs <run-dir> --no-join          # clips only
+node <skill-dir>/scripts/render-scenes.mjs <run-dir> --stills           # hold-frame PNGs per format, no render
 ```
 
 The script hashes each scene's JSON, its composition or footage, and its `assets`.
@@ -53,6 +62,16 @@ scenes and leaves the rest as they are. Every clip is normalized to the same siz
 frame rate, and a stereo audio track, so the join is a lossless concat. It writes
 `clips/NN-id.mp4`, `final.mp4`, and `TIMING.md`.
 
+With `formats`, each format gets its own folder and file: `clips/<format>/NN-id.mp4`
+and `final-<format>.mp4`, each with its own cache, so adding a format renders only
+that format. A landscape format reuses the clips of a finished single-format 16:9
+render at the same `--quality`, so adding formats after the master is done renders
+only the new sizes (demo footage re-crops, which is ffmpeg only). For motion and logo scenes it writes a stamped copy of the composition
+next to the original (`compositions/<id>.<format>.html`, root `data-width`,
+`data-height`, and `data-format` set, plus `:root{--w;--h;--u}`), renders it, and
+deletes the copy. A scene that sizes itself with those tokens re-lays out; one
+hardcoded to 1920x1080 px gets clipped, which `qa.mjs` catches.
+
 It runs `hyperframes` when it is on the PATH, otherwise `npx hyperframes@<pinned
 version>`. Before the first `npx` run in a session, tell the user it downloads
 HyperFrames from npm and ask.
@@ -75,4 +94,6 @@ HyperFrames from npm and ask.
 | "Make the demo part shorter" | `duration` or `sourceStart` of that demo scene |
 | "Swap scenes 2 and 4" | Reorder `scenes`; clips are reused and renamed, nothing re-renders |
 | "Different logo in the outro" | Replace the file listed in that scene's `assets` |
-| "Vertical version" | Change `format`; every scene re-renders |
+| "Vertical version" | Add `"vertical"` to `formats`; existing formats keep their clips and only the new one renders |
+| "Square too" | Add `"square"` to `formats` |
+| "The crop cuts off the button" | Move that demo scene's `focus` toward the button, then `--scene <id>` |