@aicopycoders/exodus 2026.9.2000-beta.9 → 2026.10.1200-beta.1

package/assets/docs/CLAUDE.md

@@ -83,6 +83,7 @@ These are not pipelines. They are Luke's methods written as skills, so the think
 | `find-competitors` | Who is actually strong in a niche, on Meta first and Amazon second. Ranked competitor sheet and a watch list. Optional scripts for Atria and the Meta Ad Library via Apify (each needs its own key; they bill per result and say the plan back before spending). |
 | `patterns-and-gaps` | What repeats and matters across own ads, competitor ads, organic content, and research, read layer by layer, and the three kinds of gap. |
 | `anatomy-of-ads` | The parts list of an ad (Messaging × Creative). Write a brief, dissect any ad into the same parts, tag a batch so patterns can be counted. Also the vocabulary the other skills use. |
+| `swipe` | Swipe a winning ad for the active brand at one of three closeness levels (1 same scene, 2 new scene same beats, 3 same bones new drama). Gathers the ad, product, and level, then calls the `swipe-narrative-agent` Genesis bot (needs `GENESIS_API_KEY` plus a provider key). |
 | `copy-instincts` | See, Attract, Make. Run on a draft that already exists (hook, ad, mechanism paragraph) to take it from good to great. |
 | `bot-builder` | Build a custom bot the way Luke and Mario build the Genesis bots (SEAK), and put it where it runs: an Exodus workflow Prompt node, a Genesis bot, or a skill. |
 | `remember-that` | Bank one reaction mid-session ("remember that", "never do X") into `STANDARDS.md`, and push approved winning lines to the matching Exodus bank. |

package/assets/skills/exodus-primer/SKILL.md

@@ -52,7 +52,7 @@ Cheap, one query. It tells you whether this brand already has a primer.
 - **✗ Not ready** — no primer yet. Proceed to Step 1.
 - **✓ Ready** — a primer is already saved. **Don't rebuild blind.** Surface it and offer the lighter moves first:
   - `npx @aicopycoders/exodus primer show` — print the saved primer so the user can see what's there.
-  - Rebuild only if the user explicitly wants to replace it (they've got better winning ads, the product changed). A rebuild *replaces* the existing primer.
+  - Rebuild only if the user explicitly wants a newer one (they've got better winning ads, the product changed). A rebuild adds a new primer and makes it your default; the old one stays in your list.
 
 This follows the same "check first, don't re-ask" discipline as the `exodus-foundation` skill. Use the status result to decide what to do — don't open by asking the user where they want to start.
 
@@ -67,11 +67,16 @@ WHO IT'S FOR:
 OFFER / PRICE (optional):
 PROOF / NUMBERS (optional):
 
-WINNING ADS (paste 10, full copy; fewer is OK — tell me if you have none):
---- Ad 1: …
---- Ad 2: …
+WINNING ADS (paste 10, full copy; fewer is OK — tell me if you have none).
+Paste each ad on the lines under its "--- Ad N:" line, and leave that line as it is:
+--- Ad 1:
+(ad 1, full copy)
+--- Ad 2:
+(ad 2, full copy)
 ```
 
+Leave nothing after "Ad 1:" — no name or title. The builder names every ad itself, and text on that line would have to be guessed as either a name or the ad's first line.
+
 State plainly that the product facts matter as much as the ads — the winning ads frequently don't name the product, and you will **not** invent it. If the user says they have *no* winning ads, stop here and jump to the **No-Ads Branch** below; don't push them to manufacture examples.
 
 ### Step 2 — Assemble the submission
@@ -86,7 +91,7 @@ npx @aicopycoders/exodus primer --file state/primer-submission.md --yes
 
 The build reads every ad and writes the full module taxonomy. **The `--yes` is load-bearing in Claude Code:** without it, the final "accept & save" prompt silently no-ops in the non-TTY shell and the primer is never saved (the symptom that forced a `printf 'a\n' |` hack before this flag existed). With `--yes`, the command builds and saves in one shot and prints the same `✓ saved` / `✓ ready` output.
 
-If a primer already exists, `--yes` rebuilds in place (replaces it) rather than prompting — which is what you want when the user has explicitly asked to rebuild.
+If a primer already exists, `--yes` builds and saves without prompting — which is what you want when the user has explicitly asked to rebuild. It adds a new primer and makes it your default; the old one stays in your list.
 
 ### Step 4 — Verify
 

package/assets/skills/exodus-video/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: exodus-video
-description: Make a video ad with Exodus from the terminal. The main path is script-first: run a saved video workflow with `npx @aicopycoders/exodus workflow run`. You read and approve the storyboard, pull every finished piece (per-scene clips, the narration track and per-scene voice, keyframes, cast identity stills, word timings, the music bed) into a folder with `exodus video pull`, and upload a finished cut for approval. Exodus makes the pieces; the cut is made outside it, in whatever editor the user wants — this skill hands over the pieces and the facts about them, it does not prescribe an editor. Use it whenever the user has invoked Exodus and wants anything to do with a video ad, an ad run's clips or storyboard, "pull the pieces", "stitch it together", "make the cut", "upload my cut", or checking on a video run ("exodus, make a video ad from this script", "exodus, is my video run done", "exodus, pull the clips for run X and cut them", "exodus, what's wrong with scene 3", "exodus video status"). Also use it when the user ran an `npx @aicopycoders/exodus video` command or the `exodus` hub skill routed here. Video is admin-only: "video isn't enabled for this key" means either the dashboard user lacks the admin role or the run id is wrong, so check the id and then say so; do not retry. Never claim generic video-editing asks ("edit this mp4", "add captions to my reel") without Exodus context; in shared folders those belong to the user's other tools. Running or authoring workflows generally is `exodus-workflow`; static image ads are `exodus-image`; copy is `exodus-write`.
+description: Make a video ad with Exodus from the terminal. The main path is script-first: run a saved video workflow with `npx @aicopycoders/exodus workflow run`. You read and approve the storyboard, pull every finished piece (per-scene clips, the narration track and per-scene voice, keyframes, cast identity stills, word timings, the music bed) into a folder with `exodus video pull`, and upload a finished cut for approval. Exodus makes the pieces; the cut is made outside it, in whatever editor the user wants — this skill hands over the pieces and the facts about them, it does not prescribe an editor. Use it whenever the user has invoked Exodus and wants anything to do with a video ad, an ad run's clips or storyboard, "pull the pieces", "stitch it together", "make the cut", "upload my cut", or checking on a video run ("exodus, make a video ad from this script", "exodus, is my video run done", "exodus, pull the clips for run X and cut them", "exodus, what's wrong with scene 3", "exodus video status"). Also use it when the user ran an `npx @aicopycoders/exodus video` command or the `exodus` hub skill routed here. Admins get every video command; beta testers with video switched on get start, status, storyboard, approve, voices, retry-frame, pull and upload on their own brands (see "Beta testers"). "video isn't enabled for this key" means the run id is wrong, the command is admin-only, or video isn't switched on for that dashboard user, so check the id and then say so; do not retry. Never claim generic video-editing asks ("edit this mp4", "add captions to my reel") without Exodus context; in shared folders those belong to the user's other tools. Running or authoring workflows generally is `exodus-workflow`; static image ads are `exodus-image`; copy is `exodus-write`.
 ---
 
 # Video: make the pieces, cut the ad, hand it back
@@ -32,7 +32,8 @@ workflow run`. From there the same nodes render, `video status` reads the run,
 `video pull` writes the folder, and `video upload` and `approve` finish it.
 
 A Show is no longer required. `exodus video start` starts from a script, a
-conceit, and a style, and the same parks follow. The full line is under
+conceit, and a style. The same parks follow, except that the app approves the
+storyboard itself when its checks pass (see "What costs money"). The full line is under
 "Starting a run". An optional `--direction` note is whole-ad rules, and that
 note cannot contain a colon. "The script file" shows the right form and the
 wrong one.
@@ -45,17 +46,57 @@ family (`familyTree.ts`). Those family names stay the code's names.
 ## Before anything
 
 - `npx @aicopycoders/exodus video --help` and `workflow --help` are the
-  authoritative flag lists. The `video` verb is admin-only and hidden from the
-  top-level `--help`; that is expected, not a broken install.
-- **Video is admin-only**, and says so two different ways.
-  - "video isn't enabled for this key", from a `video` verb, has two causes the
-    CLI cannot tell apart: the user is not an admin on this brand, or the run id
-    does not exist. Check the id first; if it is right, they need the admin role.
+  authoritative flag lists. The `video` verb is hidden from the top-level
+  `--help` because most members can't use it; that is expected, not a broken
+  install.
+- **Who can use video.** Admins get everything in this file. A beta tester
+  (video switched on for their dashboard user) gets a smaller set on their own
+  brands, listed under "Beta testers" below. Two refusals:
+  - "video isn't enabled for this key", from a `video` verb, has three causes
+    the CLI cannot tell apart: the run id does not exist on this brand, the
+    command is admin-only, or video isn't switched on for this user. Check the
+    id first, then check the command against "Beta testers".
   - "Video workflows aren't available on your account. Ask an admin if you need
-    video.", from `workflow run`, is unambiguous — `startRun` refuses any graph
-    containing a video node for a non-admin (`convex/workflows.ts:6471`).
+    video.", from `workflow run`, is unambiguous. `startRun` refuses any graph
+    containing a video node for a non-admin, beta testers included. A beta
+    tester starts with `exodus video start` instead.
 
   No flag or retry fixes either one.
+
+## Beta testers
+
+A beta tester's key gets the same video the dashboard's Video page makes, and
+never how it is made. Every answer to them says `"view": "customer"`, and the
+CLI words it the way the run page does. On their own brands they can:
+
+- `video start --script <file> --conceit <key> --style <slug>` with
+  `--direction`, `--frame`, `--pacing`, `--music`, `--review-storyboard` and `--wait`. Any other start
+  flag is refused with one sentence naming it. The answer is the run id and the
+  link to the video's page.
+- `video status <runId>`: where the video is, in plain words (waiting in line,
+  planning, drawing, storyboard ready for review, filming, ready with its link,
+  or stopped and why). `--json` prints the server's answer as it came.
+- `video storyboard <runId>`: each scene's line and picture, while the
+  storyboard waits for review.
+- `video approve <runId>`: approves the storyboard. Nothing else.
+- `video voices <runId>`: who speaks, their current voice, and the voices on
+  the tester's own ElevenLabs account. `--set <character>=<voiceId>` picks one,
+  until the storyboard is approved.
+- `video retry-frame <runId> --scene <n>`: redraws one scene's picture while
+  the storyboard waits. No `--node`; the server finds the step.
+- `video pull <runId> --out <dir>`: the finished video (`video.<ext>`), each
+  scene's clip (`scene-NN.<ext>`) and voice (`scene-NN.voice.<ext>`), and the
+  music (`music.<ext>`), with a `manifest.json` holding only `runId`,
+  `pulledAt`, `dashboardUrl`, `scenes` (`index`, `clip`, `voice`), `music` and
+  `video`. A file that did not download is `null` there. Nothing else in "The
+  handover" below applies to them.
+- `video upload <runId> --file <cut>`: attaches their cut and prints the page
+  to watch it on.
+
+Admin-only, answered "video isn't enabled for this key" (or, for retry-clip and
+revoice, a sentence saying they are for admins): `director`,
+`status --rejected-draft`, `retry-clip`, `revoice`, and the start flags
+`--video-model`, `--voice`, `--voice-path` and `--director`.
 - Other failures: `npx @aicopycoders/exodus doctor` first, then follow what it prints.
 - `ffprobe` on the PATH lets `upload` read the cut's length by itself. Without
   it, `upload` falls back to parsing an MP4's own header, and for anything else
@@ -84,8 +125,23 @@ exodus workflow run <workflowId|name> --input <field>=@script.txt --voices @voic
 exodus workflow run <workflowId|name> --input <field>=@script.txt --voice-treatment @voice-treatment.json --wait
                                                           same, with the video model speaking voices you WROTE
 exodus video status <runId>                               where it is, per scene
-exodus video start --script <file> --conceit <podcast|ugc|stage|street|personification> --style <slug> [--direction "…"] [--voice-path <path>] [--no-music] [--wait]
-                                                          start from a script, a conceit and a look
+exodus video start --script <file> --conceit <kind> --style <look> [--direction "…"] [--frame pov] [--pacing <jump-cuts|long-take|montage>] [--voice-path <path>] [--video-model <id>] [--voice native] [--music] [--review-storyboard] [--director] [--wait]
+                                                          start from a script and the kinds the server offers.
+                                                          No music bed unless you pass --music.
+                                                          --frame pov (conversation conceits) and --pacing
+                                                          (presenter conceits) change the shots; a conceit
+                                                          that can't follow one refuses it.
+                                                          The app approves its own storyboard when its
+                                                          checks pass and goes straight on to the clips,
+                                                          which is the part that costs. It stops at the
+                                                          gate only when a check finds a problem, and says
+                                                          why. --review-storyboard always stops there.
+                                                          Each conceit has its own video model and voice;
+                                                          --video-model / --voice override them for one run.
+                                                          --director turns the trial director on (admins only)
+exodus video director <runId> on|off|follow               the trial director for one run (admins only);
+                                                          follow = the brand's own setting. status shows
+                                                          what it is doing and its last three notes
 ```
 
 **From the storyboard on.**
@@ -96,9 +152,10 @@ exodus video voices <runId>                               who speaks and with wh
 exodus video voices <runId> --set <character>=<voiceId>   give a character a voice
 exodus video approve <runId>                              keep going
 exodus video retry-frame <runId> --node <nodeId> --scene <n>  redo one still at the pixel gate
+                                                          (a beta tester leaves --node off)
 exodus video status <runId>                               where it is, per scene
 exodus video pull <runId> --out ./ad-<runId>              every piece + manifest.json
-exodus video retry-clip <runId> --scene <n> [--node <nodeId>] [--note "…"]
+exodus video retry-clip <runId> --scene <n> [--node <nodeId>] [--note "…"] [--voice-first]
                                                           redo one clip at the final watch
 exodus video revoice <runId> --all | --scene <n>          redo only the voice; no new video
                                                           … make the cut (your choice of tool)
@@ -135,7 +192,11 @@ under it:
   lines under `guidance`). It is also
   the one park where a finished clip can be redone, with `retry-clip`. A run
   only reaches this park if its video node sets `finalWatch: true` — otherwise
-  it skips straight to finished.
+  it skips straight to finished. If a scene has no clip, the stop block names
+  it instead (`stop.missingScenes` in `--json`) and approval is refused until
+  it has one. A scene whose picture the video service refused needs
+  `retry-frame --note` before `retry-clip`; the clip redo alone resends the
+  refused picture.
 - paused: a builder checkpoint neither video verb resolves —
   `exodus workflow checkpoint <runId>` is the verb for that one.
 - failed: `status` shows how far it got, and a `--wait` that was running exits
@@ -162,18 +223,31 @@ minutes with "Still running after 60 minutes" and exit 0; that is not done, so
 check `status` before treating it as finished. Do not poll `status` in a tight
 loop; a full run is several minutes.
 
-**What costs money.** Starting the run writes the storyboard and then draws the
-reference, cast and scene pictures, and only then pauses. Each picture is a few
-cents and each scene draws a few to choose from: about 25 cents on a small test,
-and it can approach a dollar on a longer ad. Approving releases the expensive
-part: the voices and the clips. So a run that has not paused yet is already
-spending a little, and a run still drawing pictures is healthy. `exodus workflow
-status` and `exodus video status` both print "This run will pause for your
-approval once the frames are ready" on a run that is headed for the gate. Do not
-cancel it because the pause has not arrived. `workflow list`, `workflow describe`, `video status`,
-`storyboard` and `pull` are free reads; run them as often as you like. Never
-start a second run to "retry" without the user asking; tell them what failed
-instead.
+**What costs money.** Every run writes the storyboard first and then draws the
+reference, cast and scene pictures. Each picture is a few cents and each scene
+draws a few to choose from: about 25 cents on a small test, and it can approach
+a dollar on a longer ad. The expensive part comes after the storyboard: the
+voices and the clips. What happens at that point depends on how the run
+started.
+
+- A paste-a-script run (`exodus video start --conceit …`) checks its own
+  storyboard once the pictures are drawn. When every check passes, the app
+  approves the storyboard itself and goes straight on to the voices and the
+  clips, with no stop. It stops for the user only when a check finds a problem,
+  and the stop block says why in plain words. Started with
+  `--review-storyboard`, it always stops at the storyboard instead. `status`
+  prints "the app checks the storyboard and approves it itself if the checks
+  pass" on a run headed that way.
+- A Show run (`video start --show`) and a saved workflow run (`workflow run`)
+  still pause at the storyboard for approval. Approving is what releases the
+  voices and the clips. `status` prints "This run will pause for your approval
+  once the frames are ready" on a run headed for that pause.
+
+Either way, a run still drawing pictures is healthy and already spending a
+little. Do not cancel it because nothing has happened yet. `workflow list`,
+`workflow describe`, `video status`, `storyboard` and `pull` are free reads; run
+them as often as you like. Never start a second run to "retry" without the user
+asking; tell them what failed instead.
 
 **`--auto-approve` does not cover either video gate.** It releases Checkpoint
 boxes only (`convex/workflows.ts:7266` keys on `pauseReason === "checkpoint"`),
@@ -185,8 +259,8 @@ on its own.
 ## What the CLI can and cannot do
 
 Verified against the CLI and the server, not assumed. Everything here is
-admin-gated on top. Five things worth knowing before you promise a user
-anything:
+about the admin tools; a beta tester has only what "Beta testers" lists. Five
+things worth knowing before you promise a user anything:
 
 - **A workflow only stops for your cut if its video node asks to.** `finalWatch`
   defaults to `false` (`convex/lib/workflow/catalog.ts:780`), and the run only
@@ -558,6 +632,20 @@ manifest.json            the index below
 runId, pulledAt, dashboardUrl        the run and the page that opens it:
                                      /workflows/<workflowId>/runs/<runId>
 storyboard, reference, music         filenames, or null when not delivered
+musicBed                             on | off | unknown — whether the RUN has a
+                                     music bed, which is not the same question
+                                     as the `music` filename above. "unknown" is
+                                     a run made before the run carried the
+                                     answer; it is not "off"
+musicHeardScenes[]                   scene numbers whose clip came back with
+                                     music the video model baked in. A run with
+                                     the bed off can still list scenes here, and
+                                     those are the ones to listen to
+pendingRedo[]                        scene numbers the app is redoing right
+                                     now. Their clip and words are left out,
+                                     because the file on the run is the take
+                                     being replaced: run `exodus video wait`,
+                                     then pull again
 narration                            { file, timing }, or null on a per-scene run
 cast[]                               one per identity still
   characterId, name                  from the run's cast lock; null for an
@@ -590,6 +678,9 @@ scenes[]                             one per scene, in order
                                      on record when the voice pass replaced the
                                      clip with a new file; null when the clip IS
                                      that file, or there is no clip
+  voiceMode                          "voice-first" when the clip was redone voice
+                                     first (its line recorded, then the clip made
+                                     to match it); null otherwise
 provenance                           which saved rulebook this run followed:
                                      {format: {via, nodeId, rigId, rigName,
                                      rulesFrom, specVersion}}. Absent when the
@@ -612,9 +703,12 @@ depends on the scene; see "Which scenes carry their voice where" below.
 terms. `script[]` is the ad's spoken words in order — `{lineId, speakerId, text}`,
 with `speakerId: null` meaning narrator VO. Each scene carries `sceneIndex`,
 `durationSec`, `dialogue[]`, `voText`, `notes`, and `lineIds` (the script lines
-that scene renders). A scene with `kind: "cutaway"` carries `cueLineId` instead:
-it is a picture-only takeover of the frame while the spoken track underneath
-keeps running, so it adds no audio and takes no place in the running order. The
+that scene renders). A scene with `kind: "cutaway"` carries `cueLineId` and a
+`cutawayType` instead. Most cutaways are a picture-only takeover of the frame
+while the spoken track underneath keeps running, so they add no audio and take
+no place in the running order. A `cutawayType: "reaction"` cutaway is the room
+reacting out loud to its cue line: it is its own short beat after that line,
+heard with its own sound while the speaker is silent. The
 envelope also carries `overlays[]` (each with a `cueLineId` and a `placement`)
 and `audio` (`roomTone`, `music`, `sfxCues[]`) — the planner's notes on what
 should sit on top. The image and motion prompts (`framePrompt`, `videoPrompt`,
@@ -734,6 +828,7 @@ is no second run, no new storyboard and no re-render of anything else.
 exodus video retry-clip <runId> --scene 3
 exodus video retry-clip <runId> --scene 3 --note "keep both hands in frame on the handshake"
 exodus video retry-clip <runId> --scene 3 --node video-2
+exodus video retry-clip <runId> --scene 3 --voice-first
 ```
 
 `--node` is only needed when a run has clips for that scene on two video steps;
@@ -756,7 +851,17 @@ revoiced and trimmed the same way, with fresh findings and fresh word timings.
 scene's motion prompt only (`withRedoDirection`,
 `scout/src/trigger/workflow-scene-retry.ts`); the spoken line still comes from
 the approved storyboard. Asking for different words in a note will not change
-them. If the words are wrong, that is a new run.
+them. If the script's words are wrong, that is a new run.
+
+**`--voice-first` fixes a clip that said its line wrong** (#2299). It is for a
+clip whose findings include `speech-mismatch`, `speech-repeat`,
+`speech-after-line`, `speech-extra-words` or `speech-long-pause`. The scene's line is recorded in each
+speaker's pinned ElevenLabs voice, and MiniMax (`minimax-h3/reference-to-video`)
+makes the clip to match the recording. Only that clip changes; the word check
+and the other checks still run on it. It needs an ElevenLabs key and a voice for
+every speaker in the scene, and it is refused for a scene with no spoken line.
+The clip then reads `clip: redone voice first` in `status`, carries
+`voiceMode: "voice-first"` in the manifest, and is listed in the `pull` summary.
 
 **A redo whose take fails the checks keeps the original clip.** On a finished
 clip the row stays `done` with the ORIGINAL take and only its findings are
@@ -868,8 +973,19 @@ Read these out of `storyboard.json` before you build anything, in any tool:
   running order. To find the moment, locate the A-roll scene whose `lineIds`
   contain the cue line, then read the start time of the first word of that line
   out of that scene's `words.json`.
+- **Reactions.** A cutaway with `cutawayType: "reaction"` is the exception. Do
+  not lay it over the speech. Put it into the running order as its own beat
+  right after its cue line ends, play its own sound (the audience laughing),
+  keep it to about 1.5 s, then carry on with the speaker. Nobody talks during
+  it. When more lines follow the cue line in the same scene, cut that scene
+  where the cue line's last word ends in its `words.json` and put the reaction
+  between the two halves.
 - **Overlays and SFX.** `overlays[]` and `audio.sfxCues[]` are cued the same
   way, by `cueLineId`. Nothing renders them for you.
+- **Jump cuts.** When `manifest.json` has `shots.pacing: "jump-cuts"`, every
+  scene was filmed from the same framing on purpose. Punch in about 15% on
+  every other cut between one speaker's scenes, so each cut visibly moves in
+  or out. The bundled script does this for you.
 - **Captions.** Nothing is burned into any clip. Captions belong in post; the
   word timings are what an editor imports to build them.
 
@@ -879,36 +995,76 @@ State this to the user before you run it, so they know what the cut does with
 the pieces:
 
 - **It cuts the picture to the voice, and never the other way round.** A
-  narrated scene's segment runs exactly as long as that scene's voice track plus
-  a beat of air. A clip that runs longer is trimmed; a clip that runs shorter
-  holds its last frame for the difference. The narration is never sped up,
-  slowed down or cut short, so every scene plays at the speed it was recorded,
-  and the word times are handed on as they were measured.
+  narrated scene's segment runs to the narrator's last word plus a beat of air:
+  about 0.25 s before the next scene, 0.5 s when it ends the ad. The last word
+  comes from the voice track's own word timings; when the scene has none, the
+  end of the voice file stands in for it. A clip that runs longer is trimmed; a
+  clip that runs shorter holds its last frame for the difference. The narration
+  is never sped up or slowed down, so every scene plays at the speed it was
+  recorded, and the word times are handed on as they were measured. The voice
+  file is cut only in the silence after its last word, never inside a word.
+- **It closes the dead air at the joins.** A clip that plays its own dialogue
+  keeps about 0.15 s after its last word and about 0.1 s before its first (0.25 s
+  when a different speaker answers), read from its `words.json`, so one clip
+  runs into the next like one conversation. It only ever shortens a clip's
+  silence and never cuts into a word. The ad's first clip also opens about 0.1 s
+  before its first word, so a hum a clip makes before anyone speaks is not the
+  first thing heard. The clip that ends the ad keeps about 0.5 s after its last
+  word, the same beat a narrator line gets there, or longer when the storyboard
+  marks an action after the line. A narrated scene, a still and a reaction beat
+  keep their length.
+- **It shortens long pauses between sentences inside one clip.** A silence over
+  0.6 s between two sentences is cut down to about 0.5 s, picture and sound
+  together, unless the script writes the pause in (an ellipsis or a dash), a
+  direction asks for one, or a reaction's laugh follows the line.
+- **It fades the audience reaction in and out.** A reaction beat fades in
+  across any quiet start before its laugh (a generated laugh clip can hum
+  there). When a line follows, the picture moves on early and the laugh's own
+  remaining sound plays on under that line, quieter and fading out: up to
+  0.75 s, and the beat keeps at least 1 s of picture (a 1.5 s clip shows 1 s
+  and carries its last 0.5 s). A beat that ends the ad, or has under 0.4 s to
+  carry, fades out over its last 0.4 s instead.
 - **It ignores the continuous master.** It reads only `scene-NN.voice` files;
   it never opens `narration.mp3` or `manifest.narration`. A tool that lays the
   master down whole and cuts the pictures to it keeps the read intact.
-- Otherwise: A-roll in manifest order as the spine, each cutaway laid over the
-  spine at its cued word (falling back to a proportional estimate when the scene
-  has no word times, and saying which method it used), a narrated scene's voice
+- Otherwise: A-roll in manifest order as the spine, each reaction put in as its
+  own beat of at most 1.5 s right after its cue line with its own sound, each
+  other cutaway laid over the spine at its cued word (falling back to a
+  proportional estimate when the scene has no word times, and saying which
+  method it used), a narrated scene's voice
   replacing whatever the clip recorded, a dialogue scene keeping its performed
-  line, a clip-less scene becoming a still, everything normalized to 1080×1920
+  line, everything normalized to 1080×1920
   at 24 fps and −16 LUFS per segment, a generated room-tone bed under the whole
   ad, and the music bed underneath at low level. Output is H.264 + AAC in an MP4
   with `-movflags +faststart`.
-- Flags: `--out <file>`, `--skip 2,5`, `--no-music`. It prints what went in,
-  what was left out and why, and the upload command.
+- **It stops when a scene has no clip.** A scene the storyboard plans that is
+  still being made, never started, or failed stops the cut, which names each
+  one. Wait for the clip and pull again, leave the scene out with `--skip`, or
+  pass `--still-fill` to hold that scene's keyframe on screen instead: under its
+  voice track if it has one, else silent for its planned length. The still is
+  only ever made when asked for, because a run of them reads as a broken ad.
+- Flags: `--out <file>`, `--skip 2,5`, `--no-music`, `--still-fill`. It prints what went in,
+  what was left out and why, and the upload command. When a clip hums or
+  clicks where nobody speaks at an edge the cut plays, it lists each one under
+  "Sound at the edges" with its time in the cut. That is a warning to listen
+  there; the cut is made anyway.
 - Beside the MP4 it writes `cut.words.json` (every spoken word of the finished
   ad with its start and end) and `cut.srt` (the same words grouped into subtitle
   lines), named from the `--out` basename. Those times are on the finished ad's
   timeline, each scene's own word times offset by where that scene starts in the
-  cut and otherwise unaltered. Scenes with no word times leave
+  cut, less any lead-in trimmed at the join, and otherwise unaltered. Scenes with no word times leave
   gaps and are named in the report; when no scene delivered any, neither file is
-  written. These sidecars are the script's own output — another tool will not
-  produce them.
+  written. It always writes `cut.scenes.json` too: where each scene plays in the
+  cut, one `{scene, startSec, seconds}` entry per placement. `exodus video
+  upload` sends `cut.scenes.json` and `cut.words.json` with the cut when they
+  sit beside it, so the customer's edit list shows each scene's time on screen
+  and their editor folder gets the captions. These sidecars are the script's own
+  output — another tool will not produce them.
 
 Before uploading anything, from any tool, check what you made:
 `ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 cut.mp4`
-should be close to the sum of the scene durations you kept. A cut that is a few
+should be close to the sum of the scene durations you kept (the bundled
+script's cut runs somewhat shorter, by the silence it trimmed at the joins). A cut that is a few
 seconds long when five clips went in means a filter dropped inputs; do not
 upload it.
 

package/assets/skills/exodus-video/scripts/first-cut.d.mts

@@ -0,0 +1,44 @@
+// #2988: the types of the exports the Trigger worker calls. The script is
+// plain JS so the CLI can run it with `node` and no build.
+
+export class FirstCutError extends Error {
+  constructor(code: 1 | 2, message: string);
+  readonly code: 1 | 2;
+}
+
+export interface FirstCutOptions {
+  /** A folder written by `exodus video pull`. */
+  dir: string;
+  /** Defaults to <dir>/cut.mp4. */
+  out?: string;
+  skip?: Set<number>;
+  /** The music bed, when the pull has one. Defaults to on, as the CLI does. */
+  music?: boolean;
+  /** #3365: hold a scene's keyframe where it has no clip, instead of refusing. Defaults to off. */
+  stillFill?: boolean;
+}
+
+export interface FirstCut {
+  out: string;
+  durationSec: number;
+  /** The music file the cut used, or null. */
+  music: string | null;
+  timeline: { spine: Array<{ sceneIndex: number }>; left: string[] };
+}
+
+export function firstCut(options: FirstCutOptions): FirstCut;
+
+/** #3365: the scenes the cut cannot be made without, by number. */
+export function scenesWithNoClip(options: {
+  manifest: { scenes?: Array<{ sceneIndex: number; clip: string | null }> } | null;
+  storyboard: unknown;
+  skip: Set<number>;
+  exists?: (file: string | null) => boolean;
+}): number[];
+
+/** #3424: the sentence-gap cut, which scout's scribe.ts sentenceGapCuts mirrors. */
+export function sentenceGapCuts(
+  words: Array<{ w: string; s: number; e: number }>,
+  lines: Array<{ text: string; asksPause: boolean; cuesBeat: boolean }>,
+  levels?: { windowSec: number; db: number[] } | null,
+): Array<{ s: number; e: number; after: string; gap: number; kept: number; sound: boolean }>;