@aicopycoders/exodus 2026.10.2100 → 2026.10.2300-beta.1

package/assets/docs/PIPELINES.md

@@ -268,6 +268,7 @@ Then:
   exodus video voices <runId> [--set <who>=<voiceId>] [--clear <who>] [--from <f>] [--json]  who speaks, with whose voice
   exodus video approve <runId> [--json]                                approve the storyboard, or the uploaded cut
   exodus video retry-frame <runId> --node <nodeId> --scene <n> [--note "<t>"] [--json]  redo one still at the pixel gate
+  exodus video broll <runId> [add --line <id> | move --scene <n> --line <id> | remove --scene <n>] [--note "<t>"] [--json]  direct a B-roll run's shots at the storyboard
   exodus video status <runId> [--json]                                 the park and each scene's clip/voice/picture
   exodus video pull <runId> --out <dir> [--json]                       every piece + manifest.json
   exodus video retry-clip <runId> --scene <n> [--node <nodeId>] [--note "<t>"] [--json]  redo one clip at the final watch

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

@@ -128,8 +128,10 @@ CLI words it the way the run page does. On their own brands they can:
 
 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
+`status --rejected-draft`, `retry-clip`, `revoice`, `broll`, and the start flags
 `--video-model`, `--voice`, `--voice-path` and `--director`.
+`--broll` works for whoever B-roll is switched on for, beta testers included,
+but nothing open to them changes the shots the app plans (see "B-roll").
 - 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
@@ -158,13 +160,18 @@ 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 <kind> --style <look> [--direction "…"] [--frame pov] [--pacing <jump-cuts|long-take|montage>] [--voice-path <path>] [--video-model <id>] [--voice native] [--music] [--one-shot] [--director] [--stop-at-script] [--rewrite-to-fit] [--wait]
+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] [--broll] [--one-shot] [--director] [--stop-at-script] [--rewrite-to-fit] [--wait]
                                                           start from a script and the kinds the server offers.
                                                           The file can be a plain transcript, a draft or a
                                                           description: the server tidies it (see "The script
                                                           file"). --stop-at-script prints the tidied or
                                                           written script and starts nothing.
                                                           No music bed unless you pass --music.
+                                                          --broll cuts away to B-roll shots, for
+                                                          accounts with B-roll switched on. At the
+                                                          storyboard, `video broll` adds, moves or
+                                                          removes a shot (see "Reading the storyboard
+                                                          gate").
                                                           --frame pov (conversation conceits) and --pacing
                                                           (presenter conceits) change the shots; a conceit
                                                           that can't follow one refuses it.
@@ -193,6 +200,11 @@ exodus video voices <runId> --set <character>=<voiceId>   give a character a voi
 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 broll <runId>                                B-roll run: the shots, and the script lines by id
+exodus video broll add <runId> --line <id> [--note "…"]   plan a new B-roll shot on that line
+exodus video broll move <runId> --scene <n> --line <id> [--note "…"]
+                                                          move B-roll scene n to another line
+exodus video broll remove <runId> --scene <n>             take B-roll scene n out
 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 "…"] [--voice-first]
@@ -225,7 +237,11 @@ under it:
 
 - storyboard gate: needs `approve`. When the stop block prints a `Redo one
   frame:` line with a node id, one still can be redone first with `retry-frame`;
-  a gate parked before the stills are drawn has nothing to redraw.
+  a gate parked before the stills are drawn has nothing to redraw. When the run
+  has B-roll (`storyboard` ends with a `change the B-roll shots:` line), offer
+  to add a shot on a line with a note, move one, or remove one with `video
+  broll`. An add or a move takes about a minute and redraws the pictures, so
+  wait for it to finish before you approve.
 - final watch: every piece is made; needs `pull`, a cut, and `upload`. Once a
   cut is uploaded the stop block leads with `approve` instead, and `status
   --json` says which state it is in (`stop.cutAttached`, plus the same next-step
@@ -580,9 +596,65 @@ changing the workflow. Approving is what releases the voices and the clips — t
 expensive part — so do not approve a storyboard you have just told the user is
 wrong.
 
+**When the run has B-roll.** The storyboard ends with `change the B-roll shots:
+exodus video broll <runId>`. Run that: it lists each B-roll shot (its scene
+number, the line it sits on, the words it covers and its seconds) and every
+script line with its id. Tell the user which lines have a shot, then offer three
+changes:
+
+- add a shot on a line, with a note on what it should show:
+  `exodus video broll add <runId> --line <id> --note "what it shows"`
+- move a shot to another line:
+  `exodus video broll move <runId> --scene <n> --line <id>`, with an optional
+  `--note`
+- remove a shot: `exodus video broll remove <runId> --scene <n>`
+
+An add or a move plans the shot on a worker. It takes about a minute, and then
+the storyboard pictures are redrawn. A remove saves at once and also redraws the
+pictures. While a shot is being planned, `video broll` says so and the server
+refuses another change. Run `video broll <runId>` again until it no longer says
+it is planning, then read the storyboard again before you ask about approving.
+If it says the last change didn't work, pass its sentence to the user as it
+came. Do not approve while a shot is still being planned.
+
 Do not approve on the user's behalf unless they told you to run the whole loop
 unattended.
 
+## B-roll
+
+B-roll is a short shot the picture cuts away to while the speaker's voice keeps
+going: the product, how it works inside the body, a result, a proof. Most top
+ads use it. A run makes none unless it was started with `--broll`, and only an
+account with B-roll switched on can pass it. The choice is fixed when the run
+starts; it cannot be turned on afterwards.
+
+**When to start with `--broll`.** Offer it whenever the script talks about
+something a picture could show: the product, the mechanism, a before and after,
+a number or a result. Leave it off when the user wants nothing but the person
+talking. The app plans the shots and decides how many; it may plan few or none.
+To direct the shots, start Guided (the default). `--one-shot` approves its own
+storyboard, so nobody gets to change the B-roll.
+
+**Reviewing and directing it.** At the storyboard gate, `video broll` lists the
+shots and the lines, and adds, moves or removes one (see "Reading the
+storyboard gate"). That is admin-only: a beta tester sees the shots in the
+storyboard and can approve it, or stop the run on the video's page, but cannot
+change them. A note on an add or a move says what the
+shot should show, in one or two plain sentences ("close on the jar lid
+twisting off", "the cream sinking into the skin, seen from inside"). Keep it
+under 500 characters.
+
+**The look.** A stylized ad (claymation, Pixar, anime, any animated style)
+keeps its own look in every B-roll shot and goes closer or inside the body
+instead. It changes look only when a note asks for a different one. A realistic, live-action ad may use any look a shot needs: a clean 3D
+medical render, an animated diagram, a stock-footage look. Pass the user's
+wish in the note; the app keeps or drops it by this rule.
+
+**A shot that fails.** The app first tries a new idea for the shot, then a still
+picture with a slow zoom. If both fail it leaves the shot out and the speaker
+stays on screen. An admin's `pull` names those scenes and lists them under `dropped` in the
+manifest. They have no clip, so cut with `--skip <those numbers>`.
+
 ## Giving the characters voices
 
 By default a workflow run's characters have no voice of their own. A character
@@ -834,6 +906,10 @@ pendingRedo[]                        scene numbers the app is redoing right
                                      because the file on the run is the take
                                      being replaced: run `exodus video wait`,
                                      then pull again
+dropped[]                            B-roll scene numbers the app left out
+                                     after a new idea and a still both failed.
+                                     They have no clip on purpose: cut with
+                                     `--skip` and stay on the speaker
 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
@@ -1160,7 +1236,10 @@ Read these out of `storyboard.json` before you build anything, in any tool:
   at the moment that script line is spoken, taking no audio and no place in the
   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`.
+  out of that scene's `words.json`. A B-roll cutaway (one with `broll`) starts
+  on the first word of `broll.covers` instead and holds through its last word,
+  0.8 s to 4 s; a shot planned longer than 4 s (a talking character) holds at
+  least `broll.plannedSec`.
 - **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),

package/assets/skills/exodus-video/scripts/first-cut.mjs

@@ -5,7 +5,8 @@
 // bed go underneath, and one MP4 comes out ready to upload. A reaction
 // cutaway is the exception: it is its own short beat in the spine right after
 // its cued line ends, heard with its own sound while the speaker is silent,
-// fading in across any quiet start and out rather than stopping dead.
+// fading in across any quiet start and out rather than stopping dead. A B-roll
+// cutaway lays over just the words it covers, from the first to the last.
 //
 //   node first-cut.mjs <pulled-dir> [--out cut.mp4] [--skip 2,5] [--no-music] [--still-fill]
 //
@@ -110,6 +111,13 @@ export const JOIN_LEAD_SAME_SPEAKER_SEC = 0.1;
 export const JOIN_LEAD_NEW_SPEAKER_SEC = 0.25;
 /** The gap a cut keeps from an extra heard sound it leaves out (#2541). */
 const EXTRA_CLEARANCE_SEC = 0.05;
+/**
+ * A B-roll shot holds over the words it covers (#3912), but never shorter than
+ * the eye needs to read it nor so long it drags; a shot planned past the
+ * longest hold (a talking character) keeps its planned length.
+ */
+export const BROLL_MIN_HOLD_SEC = 0.8;
+export const BROLL_MAX_HOLD_SEC = 4;
 
 /** The word rule the planner sized every line with (scout models.ts wordCount). */
 export function wordCount(text) {
@@ -685,6 +693,10 @@ export function scenePlans(storyboard) {
       durationSec: typeof scene.durationSec === "number" ? scene.durationSec : null,
       actionTailSec: typeof scene.actionTailSec === "number" && scene.actionTailSec > 0 ? scene.actionTailSec : 0,
       actionLeadSec: typeof scene.actionLeadSec === "number" && scene.actionLeadSec > 0 ? scene.actionLeadSec : 0,
+      broll:
+        hasText(scene.broll?.covers) && Number.isFinite(scene.broll?.plannedSec) && scene.broll.plannedSec > 0
+          ? { covers: scene.broll.covers, plannedSec: scene.broll.plannedSec }
+          : null,
     });
   }
   return plans;
@@ -709,25 +721,45 @@ export function fitNarration({ clipSeconds, spokenEndSec, airSec, actionTailSec
   return { seconds: target, holdSec: target - clipSeconds, trimmedBy: 0 };
 }
 
+/** Where a segment's cue line sits among its words, or null when the segment does not speak it. */
+function lineInSegment(seg, counts, cueLineId) {
+  const idx = seg.lineIds.indexOf(cueLineId);
+  if (idx === -1) return null;
+  let before = 0;
+  let total = 0;
+  seg.lineIds.forEach((id, i) => {
+    const n = counts.get(id) ?? 0;
+    total += n;
+    if (i < idx) before += n;
+  });
+  return { idx, before, words: counts.get(cueLineId) ?? 0, total };
+}
+
+/**
+ * When the segment's word number `i` starts (edge "s") or ends ("e"), in
+ * seconds into the segment: from its word times, else its share of the words.
+ */
+function wordTimeInSegment(seg, i, total, edge) {
+  let at = 0;
+  if (seg.words && seg.words.length > 0) {
+    at = Math.max(0, seg.words[Math.min(Math.max(i, 0), seg.words.length - 1)]?.[edge] ?? 0);
+  } else if (total > 0) {
+    at = ((edge === "e" ? i + 1 : i) / total) * seg.seconds;
+  }
+  return Math.min(at, seg.seconds);
+}
+
+const timesFrom = (seg) => (seg.words && seg.words.length > 0 ? "words" : "proportion");
+
 export function cueOffsetOnSpine(spine, counts, cueLineId) {
   for (const seg of spine) {
-    const idx = seg.lineIds.indexOf(cueLineId);
-    if (idx === -1) continue;
-    let precedingWords = 0;
-    for (let i = 0; i < idx; i++) precedingWords += counts.get(seg.lineIds[i]) ?? 0;
-    let totalWords = 0;
-    for (const id of seg.lineIds) totalWords += counts.get(id) ?? 0;
-
-    let within = 0;
-    let method = "proportion";
-    if (seg.words && seg.words.length > 0) {
-      within = Math.max(0, seg.words[Math.min(precedingWords, seg.words.length - 1)]?.s ?? 0);
-      method = "words";
-    } else if (totalWords > 0) {
-      within = (precedingWords / totalWords) * seg.seconds;
-    }
-    within = Math.min(within, seg.seconds);
-    return { startSec: seg.startSec + within, method, spineSceneIndex: seg.sceneIndex };
+    const line = lineInSegment(seg, counts, cueLineId);
+    if (!line) continue;
+    return {
+      startSec: seg.startSec + wordTimeInSegment(seg, line.before, line.total, "s"),
+      method: timesFrom(seg),
+      spineSceneIndex: seg.sceneIndex,
+    };
   }
   return null;
 }
@@ -738,21 +770,83 @@ export function cueOffsetOnSpine(spine, counts, cueLineId) {
  * where the segment does.
  */
 export function cueEndInSegment(seg, counts, cueLineId) {
+  const line = lineInSegment(seg, counts, cueLineId);
+  if (!line) return null;
+  if (line.idx === seg.lineIds.length - 1) return seg.seconds;
+  const through = line.before + line.words;
+  if (seg.words && seg.words.length > 0) return wordTimeInSegment(seg, through - 1, line.total, "e");
+  return line.total > 0 ? (through / line.total) * seg.seconds : seg.seconds;
+}
+
+/** The sub-words of a text the way scout contract.ts brollCoversLine splits them. */
+const coverParts = (text) => String(text ?? "").toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+
+/**
+ * The first and last of `words` that hold the covered words, or null. Matched
+ * on sub-words as the contract does, so "proven answer" is found in
+ * "clinically-proven answer" and starts on "clinically-proven".
+ */
+function coveredRun(words, covers) {
+  const parts = words.flatMap((word, i) => coverParts(word).map((part) => ({ part, i })));
+  const want = coverParts(covers);
+  if (want.length === 0) return null;
+  for (let k = 0; k + want.length <= parts.length; k++) {
+    if (want.every((w, j) => parts[k + j].part === w)) {
+      return { first: parts[k].i, last: parts[k + want.length - 1].i };
+    }
+  }
+  return null;
+}
+
+/**
+ * When the covered words are heard, in seconds into the segment, read by
+ * aligning the script to the transcript: "$29" is heard as three words, so the
+ * script's word count points at the wrong one (#3912). Null when the segment
+ * has no word times or the script does not align.
+ */
+function heardCovers(seg, texts, cueLineId, covers) {
+  if (!seg.words || seg.words.length === 0) return null;
+  const lines = seg.lineIds.map((id) => scriptWords(texts.get(id)));
   const idx = seg.lineIds.indexOf(cueLineId);
-  if (idx === -1) return null;
-  if (idx === seg.lineIds.length - 1) return seg.seconds;
-  let through = 0;
-  let totalWords = 0;
-  seg.lineIds.forEach((id, i) => {
-    const n = counts.get(id) ?? 0;
-    totalWords += n;
-    if (i <= idx) through += n;
-  });
-  if (seg.words && seg.words.length > 0) {
-    const last = seg.words[Math.min(Math.max(through - 1, 0), seg.words.length - 1)];
-    return Math.min(Math.max(0, last?.e ?? 0), seg.seconds);
+  const run = coveredRun(lines[idx], covers);
+  const aligned = run ? alignScript(seg.words, lines.flat()) : null;
+  if (!aligned) return null;
+  const offset = lines.slice(0, idx).reduce((n, words) => n + words.length, 0);
+  const { expected, heard, heardTokenOf, heardWordOf } = aligned;
+  const first = expected.lastSourceIndex.findIndex((i) => i >= offset + run.first);
+  const last = expected.sourceIndex.findLastIndex((i) => i <= offset + run.last);
+  if (first === -1 || last < first) return null;
+  const at = (i, edge) => Math.min(Math.max(0, seg.words[i]?.[edge] ?? 0), seg.seconds);
+  return { startSec: at(heardWordOf[first], "s"), endSec: at(heard.lastSourceIndex[heardTokenOf[last]], "e") };
+}
+
+/**
+ * #3912: a B-roll shot's place in its segment. It starts on the first word it
+ * covers and holds through the last, between BROLL_MIN_HOLD_SEC and
+ * BROLL_MAX_HOLD_SEC, or for its planned length when that runs longer than the
+ * cap. Covered words the line does not say leave it at the line's start for
+ * its planned length. `texts` maps each line id to its script text. Null when
+ * the segment does not speak the cue line.
+ */
+export function brollWindow(seg, counts, cueLineId, texts, broll) {
+  const line = lineInSegment(seg, counts, cueLineId);
+  if (!line) return null;
+  const method = timesFrom(seg);
+  const run = coveredRun((texts.get(cueLineId) ?? "").trim().split(/\s+/), broll.covers);
+  if (!run) {
+    return {
+      startSec: wordTimeInSegment(seg, line.before, line.total, "s"),
+      holdSec: broll.plannedSec, method, found: false,
+    };
   }
-  return totalWords > 0 ? (through / totalWords) * seg.seconds : seg.seconds;
+  const heard = heardCovers(seg, texts, cueLineId, broll.covers);
+  const startSec = heard?.startSec ?? wordTimeInSegment(seg, line.before + run.first, line.total, "s");
+  const endSec = heard?.endSec ?? wordTimeInSegment(seg, line.before + run.last, line.total, "e");
+  const span = Math.max(0, endSec - startSec);
+  const holdSec = broll.plannedSec > BROLL_MAX_HOLD_SEC
+    ? Math.max(span, broll.plannedSec)
+    : Math.min(Math.max(span, BROLL_MIN_HOLD_SEC), BROLL_MAX_HOLD_SEC);
+  return { startSec, holdSec, method, found: true };
 }
 
 /**
@@ -976,7 +1070,9 @@ export function buildTimeline({
     const nothing = `nothing to cut with (clip ${scene.clipStatus}${scene.error ? `: ${scene.error}` : ""})`;
 
     if (plan.cutaway) {
-      const cue = { cueLineId: plan.cueLineId, reaction: plan.cutawayType === "reaction" };
+      const cue = {
+        cueLineId: plan.cueLineId, reaction: plan.cutawayType === "reaction", broll: plan.broll ?? null,
+      };
       if (exists(scene.clip)) {
         const clip = probe(scene.clip);
         waiting.push({
@@ -1124,13 +1220,25 @@ export function buildTimeline({
     if (seg.reaction?.tail) seg.reaction.tail.atSec = spine[k + 1].startSec;
   });
 
+  const lineTexts = new Map([...scriptLines].map(([id, line]) => [id, line?.text]));
   for (const c of waiting.filter((w) => !w.reaction)) {
     const cue = c.cueLineId ? cueOffsetOnSpine(spine, counts, c.cueLineId) : null;
     if (!cue) {
       dropped.push({ n: c.sceneIndex, reason: `cutaway ${c.sceneIndex}: ${noCue(c)}` });
       continue;
     }
-    cutaways.push({ ...c, startSec: cue.startSec, method: cue.method, spineSceneIndex: cue.spineSceneIndex });
+    const placed = { ...c, startSec: cue.startSec, method: cue.method, spineSceneIndex: cue.spineSceneIndex };
+    const seg = c.broll ? spine.find((s) => s.lineIds.includes(c.cueLineId)) : null;
+    const win = seg
+      ? brollWindow(seg, counts, c.cueLineId, lineTexts, c.broll)
+      : null;
+    if (win) {
+      placed.startSec = seg.startSec + win.startSec;
+      placed.method = win.method;
+      placed.seconds = c.source === "clip" ? Math.min(win.holdSec, c.seconds) : win.holdSec;
+      placed.coversFound = win.found;
+    }
+    cutaways.push(placed);
   }
   cutaways.sort((a, b) => a.startSec - b.startSec);
   const beats = spine.filter((seg) => seg.reaction);
@@ -1429,11 +1537,16 @@ export function inTheCut(timeline) {
         ? "word times"
         : `proportion: scene ${c.spineSceneIndex} has no word times`;
     const cut = c.cutShortBy ? `, cut short where ${c.cutShortBy}` : "";
+    const covers = !c.broll
+      ? ""
+      : c.coversFound
+        ? `, B-roll covering "${c.broll.covers}"`
+        : `, B-roll: "${c.broll.covers}" is not in the line, so it starts with the line for its planned ${c.broll.plannedSec}s`;
     rows.push({
       n: c.sceneIndex,
       line:
         `cutaway ${c.sceneIndex}: ${label} at ${c.startSec.toFixed(2)}s for ${c.seconds.toFixed(1)}s, ` +
-        `cued to ${c.cueLineId} in scene ${c.spineSceneIndex} (${how})${cut}`,
+        `cued to ${c.cueLineId} in scene ${c.spineSceneIndex} (${how})${covers}${cut}`,
     });
   }
   return rows.sort((a, b) => a.n - b.n).map((r) => r.line);

package/dist/commands/video.d.ts

@@ -400,6 +400,7 @@ export interface VideoManifest {
     musicBed: MusicBedState;
     musicHeardScenes: number[];
     pendingRedo: number[];
+    dropped: number[];
     cast: ManifestCastRef[];
     narration: {
         file: string;
@@ -455,6 +456,7 @@ export interface ScriptStartOptions {
     music?: boolean;
     reviewStoryboard?: true;
     director?: true;
+    broll?: true;
     shots?: RunShots;
     stopAtScript?: true;
     rewriteToFit?: true;
@@ -505,6 +507,34 @@ export declare function approveFlow(runId: string, opts: {
 }, deps: VideoDeps): Promise<FlowResult>;
 export declare function flagFlow(runId: string, note: string, json: boolean, deps: VideoDeps): Promise<FlowResult>;
 export declare function retryFrameFlow(runId: string, nodeId: string | undefined, sceneIndex: number, note: string | undefined, json: boolean, deps: VideoDeps): Promise<FlowResult>;
+export declare const BROLL_EDIT_STALE_MS: number;
+export type BrollEditAsk = {
+    op: "add";
+    lineId: string;
+    note?: string;
+} | {
+    op: "move";
+    sceneIndex: number;
+    lineId: string;
+    note?: string;
+} | {
+    op: "remove";
+    sceneIndex: number;
+};
+export type BrollCommand = {
+    kind: "list";
+    runId: string;
+} | {
+    kind: "edit";
+    runId: string;
+    edit: BrollEditAsk;
+} | {
+    kind: "usage";
+    line: string;
+};
+export declare function planBrollCommand(rest: readonly string[], flags: Record<string, string | boolean>): BrollCommand;
+export declare function brollFlow(runId: string, json: boolean, deps: VideoDeps): Promise<FlowResult>;
+export declare function brollEditFlow(runId: string, edit: BrollEditAsk, json: boolean, deps: VideoDeps): Promise<FlowResult>;
 export type ClipRedoPlan = {
     ok: true;
     nodeId: string;

package/dist/commands/video.js

@@ -74,6 +74,11 @@ The whole loop, in order:
      here only when its checks find a problem.
      exodus video retry-frame <runId> --node <nodeId> --scene <n>
        Redo ONE still at the pixel gate. Neighbours stay. The gate holds.
+     exodus video broll <runId>
+       On a run started with --broll: the B-roll shots and the script lines.
+       Add a shot on a line, move one, or remove one while the storyboard
+       waits. An add or a move takes about a minute and redraws the pictures,
+       so wait for it before you approve.
 
   7. exodus video status <runId>
      Where the run is and how each scene's clip turned out. If the storyboard
@@ -115,13 +120,17 @@ Usage:
   exodus video storyboard <runId> [--json]
   exodus video approve <runId> [--approve-stale-cut] [--json]
   exodus video retry-frame <runId> [--node <nodeId>] --scene <n> [--note "..."] [--json]
+  exodus video broll <runId> [--json]
+  exodus video broll add <runId> --line <id> [--note "..."] [--json]
+  exodus video broll move <runId> --scene <n> --line <id> [--note "..."] [--json]
+  exodus video broll remove <runId> --scene <n> [--json]
   exodus video retry-clip <runId> --scene <n> [--node <nodeId>] [--note "..."] [--voice-first] [--json]
   exodus video revoice <runId> (--scene <n> | --all) [--node <nodeId>] [--json]
   exodus video voices <runId> [--set <character>=<voice>] [--clear <character>] [--from <file.json>] [--json]
   exodus video voices [<runId>] --catalog [--json]
   exodus video pull <runId> --out <dir> [--json]
   exodus video upload <runId> --file <cut.mp4> [--duration <sec>] [--json]
-  exodus video start --script <file> --conceit <kind> --style <look> [--direction "<note>"] [--frame pov] [--pacing <jump-cuts|long-take|montage>] [--voice-path <path>] [--video-model <id>] [--voice <native|voice-first>] [--music] [--one-shot] [--director] [--wait] [--json]
+  exodus video start --script <file> --conceit <kind> --style <look> [--direction "<note>"] [--frame pov] [--pacing <jump-cuts|long-take|montage>] [--voice-path <path>] [--video-model <id>] [--voice <native|voice-first>] [--music] [--broll] [--one-shot] [--director] [--wait] [--json]
   exodus video director <runId> <on|off|follow> [--json]
 
 Options:
@@ -129,13 +138,17 @@ Options:
   --file <cut.mp4>     Your finished cut (upload). MP4, MOV or WebM, up to 200MB
   --duration <sec>     How long your cut is, in seconds. Only needed when the
                        length can't be read off the file itself
-  --note "<text>"      How to steer one redo (retry-frame, retry-clip)
+  --note "<text>"      How to steer one redo (retry-frame, retry-clip), or
+                       what a B-roll shot should show (broll add, broll move)
+  --line <id>          The script line a B-roll shot goes on (broll add,
+                       broll move). exodus video broll <runId> lists the ids
   --node <nodeId>      Which scene-frames node holds the still (retry-frame;
                        admins pass it, beta testers leave it off).
                        Which video step holds the clip, when a scene has one on
                        more than one step (retry-clip, revoice)
   --scene <n>          Which scene to redo. One scene only, a whole number
-                       (retry-frame, retry-clip, revoice)
+                       (retry-frame, retry-clip, revoice). Which B-roll shot
+                       to move or remove (broll move, broll remove)
   --all                Every finished clip that kept the video model's voice
                        (revoice)
   --voice-first        Record the scene's line in the character's own voice,
@@ -194,6 +207,8 @@ Options:
   --music              Put a music bed under the ad (start). An ad has no music
                        unless you ask for it here
   --no-music           Leave the music bed off (start), which it already is
+  --broll              Cut away to B-roll shots in the ad (start, with
+                       --conceit). Only for accounts with B-roll switched on
   --one-shot           Make the whole video with no stop (start, with
                        --conceit). The app approves its own storyboard when
                        its checks pass and goes straight on to the clips,
@@ -219,7 +234,8 @@ status, storyboard, approve (the storyboard), voices, retry-frame --scene <n> (r
 picture while the storyboard waits), pull (the finished video, each scene's
 clip and voice, and the music) and upload. These stay admin-only:
 start --video-model / --voice / --voice-path / --director, director,
-status --rejected-draft, retry-clip and revoice.
+status --rejected-draft, retry-clip, revoice and broll. start --broll works
+for whoever B-roll is switched on for.
 If a command answers "video isn't enabled for this key", the run id is wrong,
 the command is admin-only, or video isn't switched on for your dashboard user.
 
@@ -230,6 +246,8 @@ Examples:
   exodus video storyboard run_123
   exodus video approve run_123
   exodus video retry-frame run_123 --node frames-1 --scene 2
+  exodus video broll run_123
+  exodus video broll add run_123 --line L4 --note "close on the jar lid"
   exodus video retry-clip run_123 --scene 3 --note "keep the handshake in frame"
   exodus video retry-clip run_123 --scene 3 --voice-first
   exodus video revoice run_123 --all
@@ -253,6 +271,7 @@ const REJECTED_DRAFT_NOT_ON_THIS_SERVER = "This Exodus server does not keep reje
     "with the next server update.";
 const STORYBOARD_PATH = "/api/v2/video/storyboard";
 const FLAG_PATH = "/api/v2/video/storyboard/flag";
+const BROLL_PATH = "/api/v2/video/storyboard/broll";
 const APPROVE_PATH = "/api/v2/workflow/approve";
 const SCENE_RETRY_PATH = "/api/v2/workflow/scene/retry";
 const SCENE_REVOICE_PATH = "/api/v2/workflow/scene/revoice";
@@ -370,7 +389,7 @@ export const defaultDeps = {
 };
 export const VIDEO_NOT_FOUND_MESSAGE = "video isn't enabled for this key\n" +
     "One of three things: that run id doesn't exist on this brand, this command is for admins only " +
-    "(director, status --rejected-draft, retry-clip, revoice), or video isn't " +
+    "(director, status --rejected-draft, retry-clip, revoice, broll), or video isn't " +
     "switched on for your dashboard user on this brand. Check the id first, then ask Brad.";
 export function videoApiError(res) {
     const behind = missingRouteLine(res, "exodus video");
@@ -1137,6 +1156,10 @@ export function planPull(run, items, opts) {
                 .filter((scene) => scene.findings.some((f) => f.code === MUSIC_HEARD_CODE))
                 .map((scene) => scene.sceneIndex),
             pendingRedo,
+            dropped: [...clipItemByScene.values()]
+                .filter((item) => item.status === "rejected")
+                .map((item) => item.sceneIndex)
+                .sort((a, b) => a - b),
             cast,
             narration: narrationDownload
                 ? { file: narrationDownload.file, timing: "narration.json" }
@@ -1450,6 +1473,14 @@ export function planVideoStart(flags, occurrences) {
         };
     }
     const director = directorFlags.length > 0;
+    const brollFlags = occurrences.filter((o) => o.flag === "broll");
+    if (brollFlags.some((o) => o.value !== undefined && !o.value.startsWith("--"))) {
+        return {
+            kind: "usage",
+            line: "--broll takes no value. Leave it off to start without B-roll.",
+        };
+    }
+    const broll = brollFlags.length > 0;
     const stopFlags = occurrences.filter((o) => o.flag === "stop-at-script");
     if (stopFlags.some((o) => o.value !== undefined && !o.value.startsWith("--"))) {
         return {
@@ -1484,6 +1515,12 @@ export function planVideoStart(flags, occurrences) {
             line: "--director works with --conceit, not --show.",
         };
     }
+    if (showId && broll) {
+        return {
+            kind: "usage",
+            line: "--broll works with --conceit, not --show.",
+        };
+    }
     if (showId && (frameFlag.value || pacingFlag.value)) {
         return {
             kind: "usage",
@@ -1550,6 +1587,8 @@ export function planVideoStart(flags, occurrences) {
         opts.reviewStoryboard = true;
     if (director)
         opts.director = true;
+    if (broll)
+        opts.broll = true;
     if (stopAtScript)
         opts.stopAtScript = true;
     if (rewriteToFit)
@@ -1841,6 +1880,7 @@ export async function startScriptFlow(opts, deps) {
         ...(opts.music === true ? { music: true } : {}),
         ...(opts.reviewStoryboard ? { reviewStoryboard: true } : {}),
         ...(opts.director ? { director: true } : {}),
+        ...(opts.broll ? { broll: true } : {}),
         ...(opts.shots ? { shots: opts.shots } : {}),
         ...(opts.stopAtScript ? { stopAtScript: true } : {}),
         ...(opts.rewriteToFit ? { rewriteToFit: true } : {}),
@@ -2019,6 +2059,7 @@ const ITEM_STATUS_WORD = {
     running: "working",
     idle: "waiting",
     skipped: "skipped",
+    rejected: "left out",
 };
 function itemWord(item) {
     if (!item)
@@ -2373,6 +2414,9 @@ export async function storyboardFlow(runId, json, deps) {
     if (cards.framesNodeId) {
         lines.push(`redo one frame: exodus video retry-frame ${runId} --node ${cards.framesNodeId} --scene <n>`);
     }
+    if (cards.broll === true) {
+        lines.push(`change the B-roll shots: exodus video broll ${runId}`);
+    }
     return { code: 0, lines };
 }
 function sceneCardLines(scene) {
@@ -2506,6 +2550,152 @@ export async function retryFrameFlow(runId, nodeId, sceneIndex, note, json, deps
         ],
     };
 }
+export const BROLL_EDIT_STALE_MS = 10 * 60 * 1000;
+const BROLL_OPS = ["add", "move", "remove"];
+export function planBrollCommand(rest, flags) {
+    const op = BROLL_OPS.find((o) => o === rest[0]);
+    if (!op) {
+        if (!rest[0])
+            return { kind: "usage", line: "video broll needs a run id: exodus video broll <runId>" };
+        return { kind: "list", runId: rest[0] };
+    }
+    const runId = rest[1];
+    if (!runId) {
+        return { kind: "usage", line: `video broll ${op} needs a run id: exodus video broll ${op} <runId>` };
+    }
+    const lineId = nonBlank(flagString(flags, "line"))?.trim();
+    const note = nonBlank(flagString(flags, "note"))?.trim();
+    const sceneRaw = flagString(flags, "scene");
+    const sceneIndex = sceneRaw === undefined ? undefined : Number(sceneRaw);
+    if (sceneIndex !== undefined && !(Number.isInteger(sceneIndex) && sceneIndex >= 1)) {
+        return { kind: "usage", line: `video broll ${op} --scene must be a scene number, not "${sceneRaw}".` };
+    }
+    const withNote = note ? { note } : {};
+    if (op === "add") {
+        if (!lineId) {
+            return { kind: "usage", line: "video broll add needs --line <id>, the script line the shot goes on." };
+        }
+        return { kind: "edit", runId, edit: { op, lineId, ...withNote } };
+    }
+    if (sceneIndex === undefined) {
+        return {
+            kind: "usage",
+            line: `video broll ${op} needs --scene <n>, the B-roll shot to ${op}.`,
+        };
+    }
+    if (op === "remove") {
+        if (note)
+            return { kind: "usage", line: "video broll remove takes no --note." };
+        return { kind: "edit", runId, edit: { op, sceneIndex } };
+    }
+    if (!lineId) {
+        return { kind: "usage", line: "video broll move needs --line <id>, the script line to move the shot to." };
+    }
+    return { kind: "edit", runId, edit: { op, sceneIndex, lineId, ...withNote } };
+}
+function seconds(value) {
+    return `${Number(value.toFixed(1))}s`;
+}
+function brollEditLines(edit, now) {
+    if (!edit || edit.landed)
+        return [];
+    const asked = edit.op === "move"
+        ? `moving B-roll scene ${edit.sceneIndex} to line ${edit.lineId}`
+        : `a new B-roll shot on line ${edit.lineId}`;
+    if (edit.error !== undefined) {
+        return [`The last B-roll change (${asked}) didn't work: ${edit.error}`];
+    }
+    if (now - edit.requestedAt >= BROLL_EDIT_STALE_MS) {
+        return [`The last B-roll change (${asked}) never finished. You can ask for it again.`];
+    }
+    return [
+        `Planning now: ${asked}. It takes about a minute, then the storyboard pictures are redrawn.`,
+        "Wait for it to finish before you change another shot or approve the storyboard.",
+    ];
+}
+export async function brollFlow(runId, json, deps) {
+    const res = await deps.get(`${STORYBOARD_PATH}?runId=${encodeURIComponent(runId)}`);
+    if (!res.ok)
+        return errorResult(res, json);
+    if (customerAnswer(res.data)) {
+        return adminOnlyResult("Changing the B-roll from the CLI isn't open to this key.", json);
+    }
+    const gate = res.data;
+    if (gate.broll !== true) {
+        if (json)
+            return { code: 0, lines: [JSON.stringify({ runId, broll: false })] };
+        return { code: 0, lines: ["This video was made without B-roll, so there are no B-roll shots to change."] };
+    }
+    const shots = gate.brollShots ?? [];
+    const scriptLines = gate.scriptLines ?? [];
+    const edit = gate.brollEdit ?? null;
+    const now = deps.now();
+    const planning = !!edit && edit.error === undefined && !edit.landed && now - edit.requestedAt < BROLL_EDIT_STALE_MS;
+    if (json) {
+        return {
+            code: 0,
+            lines: [JSON.stringify({ runId, broll: true, planning, brollEdit: edit, brollShots: shots, scriptLines })],
+        };
+    }
+    if (scriptLines.length === 0) {
+        return {
+            code: 0,
+            lines: [
+                "The storyboard isn't finished yet, so there are no B-roll shots to change yet.",
+                `Check where it is: exodus video status ${runId}`,
+            ],
+        };
+    }
+    const lines = brollEditLines(edit, now);
+    if (lines.length > 0)
+        lines.push("");
+    lines.push("B-roll shots");
+    if (shots.length === 0)
+        lines.push("  None yet.");
+    for (const shot of shots) {
+        lines.push(`  Scene ${shot.sceneIndex}, on line ${shot.lineId}, ${seconds(shot.plannedSec)}: "${shot.covers}"`);
+    }
+    lines.push("", "Script lines (pick one by its id)");
+    for (const line of scriptLines) {
+        lines.push(`  ${line.lineId}  ${line.speakerId ?? "narrator"}: ${line.text}`);
+    }
+    lines.push("");
+    if (planning) {
+        lines.push(`Check again: exodus video broll ${runId}`);
+    }
+    else {
+        lines.push(`Add a shot:    exodus video broll add ${runId} --line <id> --note "what it shows"`, `Move a shot:   exodus video broll move ${runId} --scene <n> --line <id>`, `Remove a shot: exodus video broll remove ${runId} --scene <n>`);
+    }
+    return { code: 0, lines };
+}
+export async function brollEditFlow(runId, edit, json, deps) {
+    const res = await deps.post(BROLL_PATH, { runId, ...edit });
+    if (!res.ok)
+        return errorResult(res, json);
+    if (json)
+        return { code: 0, lines: [JSON.stringify({ runId, ...res.data })] };
+    if (edit.op === "remove") {
+        return {
+            code: 0,
+            lines: [
+                `B-roll scene ${edit.sceneIndex} is gone. The storyboard pictures will be redrawn.`,
+                `See them: exodus video storyboard ${runId}`,
+            ],
+        };
+    }
+    return {
+        code: 0,
+        lines: [
+            edit.op === "add"
+                ? `Planning a B-roll shot on line ${edit.lineId}.`
+                : `Moving B-roll scene ${edit.sceneIndex} to line ${edit.lineId}.`,
+            "It takes about a minute. Then the storyboard pictures are redrawn.",
+            "Wait for it to finish before you approve the storyboard.",
+            `Check on it: exodus video broll ${runId}`,
+            `See the pictures: exodus video storyboard ${runId}`,
+        ],
+    };
+}
 const UPLOADED_CUT_WARNING = "The cut you already uploaded will not include the new clip. If this redo replaces the clip, " +
     "exodus video approve stops until you pull the pieces again, re-cut and upload again, " +
     "or pass --approve-stale-cut to deliver the cut you uploaded as it is.";
@@ -3194,6 +3384,9 @@ export async function pullFlow(runId, dir, json, deps) {
         `Every piece is indexed in ${path.join(dir, "manifest.json")} — scene numbers there are the run's own.`,
         ...musicLines(plan.manifest),
     ];
+    if (plan.manifest.dropped.length > 0) {
+        lines.push("", `B-roll left out on purpose (no clip; the edit stays on the speaker): scene${plan.manifest.dropped.length === 1 ? "" : "s"} ${plan.manifest.dropped.join(", ")}. Cut with --skip ${plan.manifest.dropped.join(",")}.`);
+    }
     for (const sceneIndex of plan.manifest.pendingRedo) {
         lines.push("", `Scene ${sceneIndex} is being redone right now; its file will change. Run \`exodus video wait ${runId}\`, then pull again.`);
     }
@@ -3541,6 +3734,7 @@ const VALUE_FLAGS = new Set([
     "duration",
     "node",
     "scene",
+    "line",
     "set",
     "clear",
     "from",
@@ -3599,6 +3793,14 @@ export async function run(flags, occurrences) {
             usage(started.lines[0] ?? "");
         return printResult(started);
     }
+    if (sub === "broll") {
+        const plan = planBrollCommand(rest, flags);
+        if (plan.kind === "usage")
+            usage(plan.line);
+        if (plan.kind === "list")
+            return printResult(await brollFlow(plan.runId, json, defaultDeps));
+        return printResult(await brollEditFlow(plan.runId, plan.edit, json, defaultDeps));
+    }
     const runId = rest[0];
     const needsRunId = [
         "status",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicopycoders/exodus",
-  "version": "2026.10.2100",
+  "version": "2026.10.2300-beta.1",
   "description": "CLI + Claude Code skills for the Copycoders Exodus ad pipeline",
   "repository": {
     "type": "git",