@aicopycoders/exodus 2026.10.1200 → 2026.10.1700-beta.1

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

@@ -32,8 +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. 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
+conceit, and a style. The same parks follow: it stops at the storyboard for the
+user's yes, unless it was started with `--one-shot` (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.
@@ -101,9 +101,11 @@ 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
+  `--direction`, `--frame`, `--pacing`, `--music`, `--one-shot`, `--review-storyboard`, `--stop-at-script` 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.
+  link to the video's page, plus what the server did to the script: laid a
+  plain transcript out, or wrote a script from a description (see "The script
+  file"). `--stop-at-script` prints that script and starts nothing.
 - `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.
@@ -156,17 +158,24 @@ 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] [--review-storyboard] [--director] [--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] [--one-shot] [--director] [--stop-at-script] [--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.
                                                           --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.
+                                                          It stops at the storyboard for the user's yes
+                                                          (Guided, the default). --one-shot makes the
+                                                          whole video: 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
+                                                          then only when a check finds a problem, and says
+                                                          why. --review-storyboard is the default and
+                                                          changes nothing.
                                                           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)
@@ -261,14 +270,16 @@ 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 paste-a-script run (`exodus video start --conceit …`) stops at the
+  storyboard for the user's yes by default (Guided). Started with
+  `--one-shot`, it 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. Ask the
+  user before passing `--one-shot`: it spends the whole video in one go.
+  `status` prints "the app checks the storyboard and approves it itself if the
+  checks pass" on a run headed that way. `--review-storyboard` is the default
+  and changes nothing.
 - 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
@@ -341,6 +352,68 @@ things worth knowing before you promise a user anything:
 
 ## The script file
 
+**Pass the user's text as it is.** `exodus video start --script <file> --conceit …`
+takes whatever the user gave you: a plain transcript, a rough draft, lines with
+no names, voice-over labels, a title line, notes, a colon inside a spoken line,
+or just a description of the ad they want. Save it to a file unchanged and start.
+Do not add `CAST:`, `CTA:` or `NAME:` labels by hand, and do not rewrite it into
+the format below first. The server tidies it the same way the dashboard does
+when a person pastes a script, and it never changes a spoken word.
+
+What the CLI prints, and what you tell the user:
+
+- **Already in the format:** it starts as it is. No AI call, nothing printed
+  about the script.
+- **Laid out:** "We laid your script out in the format the video needs.", any
+  speaker label it added (`SPEAKER`, `SPEAKER 1`), a short note on who each
+  person is, and any line it left out as not part of the ad (a title, a stage
+  note, a timestamp). The run has already started. Tell the user about a
+  left-out line in one sentence. `--json` carries the same facts under
+  `tidied` (`setAside`, `added.names`, `added.descriptions`).
+- **Written from a description:** the file only described the ad, so the
+  server wrote a script for it, printed it in full, and started the run on it.
+  Show the user that script. `--json` carries it under `written`.
+- **A question (`SCRIPT_QUESTION`, exit 1, nothing started):** the server
+  can't tell who says a line. The error names the line, and `--json` lists them
+  under `lines`. Ask the user who says it, put the name in front of that line
+  (`SAM: …`), and run the same command again.
+- **Too thin (`SCRIPT_TOO_THIN`, exit 1, nothing started):** the file only
+  described the ad, and there wasn't enough in it to write a script from. The
+  error says what is missing, in the dashboard's words ("There isn't enough
+  here to write a script from. Tell us what the product is."), and `--json`
+  lists the gaps under `missing` (`product`, `speaker`, `what-happens`). Ask
+  the user for what it names, add it to the file, and run the same command
+  again.
+- **Today's refusal (exit 1, nothing started):** the user has no working AI
+  key for the tidy, the AI call failed, or the server could not write a usable
+  script from a description. The answer is the format's own message (for
+  example "Line 1 has no speaker"). Ask the user for more detail about the ad,
+  or for their AI key in Settings, or lay the file out in the format below
+  yourself. A description
+  that reports what someone says ("a guy says it stopped his crash") is
+  sometimes refused this way (#3747): describe the ad without the reported
+  words, or give the lines as a draft, and run it again.
+- **The start refused the tidied script** (for example two speakers for a
+  one-person kind of ad): the notes come first, then the refusal, and `--json`
+  carries the tidied script under `script`. Fix that script and send it. It is
+  already in the format, so it is not tidied or paid for again.
+
+**`--stop-at-script`** prints the script the run would start on and starts
+nothing (exit 0). A question or a description too thin to write from answers
+as above instead (exit 1). Use it when the user wants to read a written or
+laid-out script before anything is spent. To go ahead, save the printed script to a file
+and run the same command with `--script <that file>` and without the flag.
+`--json` answers `{ stoppedAtScript: true, script, tidied?, written? }`.
+
+The tidy spends the user's own AI key, one short call. A Show run (`--show`)
+is not tidied: a Show reads the script as written.
+
+### The exact format (optional)
+
+A file already in this format skips the tidy: no AI call. You never need to
+write it, but use it when you are writing a script from scratch for the user,
+or when the tidy can't run.
+
 Plain text. An optional `DIRECTION:` block may open the file, before `CAST:` or
 the first spoken line. Then a `CAST:` block naming the speakers, one line per
 turn, then a `CTA:` block.
@@ -396,8 +469,9 @@ with an em dash, an en dash, or a hyphen with a space on each side. Keep that
 dash on cast lines. A reader who strips it makes the line fail.
 
 Do not use a long dash in words a character says, or in words shown on screen.
-Synthesised speech reads a long dash oddly, and so does burned-in text. A spoken
-line stays `NAME: what they say`.
+Synthesised speech reads a long dash oddly, and so does burned-in text. In the
+exact format a spoken line is `NAME: what they say`; a file that is not in the
+format is tidied into it.
 
 ### Directing a line
 
@@ -454,8 +528,9 @@ What the reader refuses, with the code `malformed-direction`:
 An unclosed `(` is not refused. It is read as ordinary words, and the voice
 says it. Check every `(` has its `)`.
 
-Both ways in read the file the same way: `exodus video start --script` and
-`exodus workflow run --input <field>=@script.txt`. The second holds only when
+Both ways in read the notes the same way: `exodus video start --script` and
+`exodus workflow run --input <field>=@script.txt`. Only `video start` tidies a
+file that is not in the format; a workflow's Brief must already be in it. The second holds only when
 the script goes straight from a Brief into the Storyboard. In a workflow where a
 bot writes or rewrites the script first, the notes are not read this way, and
 the bot may drop them or leave them in the spoken words.

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

@@ -130,20 +130,143 @@ const wordToken = (word) => String(word ?? "").toLowerCase().replace(/[^\p{L}\p{
 /**
  * #3175: one spoken word a script and a scribe spell differently ("ok", "Okay").
  * #3460: "alright" maps to the scribe's "All right" once its halves are joined.
+ * #3671: the #3558 words that sound the same ("your", "you're") are one spoken
+ * word, as in scout scribe.ts.
  */
 const SAME_WORD_SPELLINGS = new Map([
   ["ok", "okay"],
   ["alright", "allright"],
+  ["youre", "your"],
+  ["theyre", "their"],
+  ["there", "their"],
+  ["too", "to"],
 ]);
 
+/**
+ * #3433: the number reading of scout spokenNumbers.ts, so a script's "$29" and a
+ * scribe's "twenty nine dollars" line up here as they do in the server's cut.
+ * Mirrors numericWords and its tables.
+ */
+const ONES = [
+  "zero", "one", "two", "three", "four", "five", "six", "seven", "eight",
+  "nine", "ten", "eleven", "twelve", "thirteen", "fourteen", "fifteen",
+  "sixteen", "seventeen", "eighteen", "nineteen",
+];
+const TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety"];
+const ORDINAL_ONES = [
+  "zeroth", "first", "second", "third", "fourth", "fifth", "sixth", "seventh",
+  "eighth", "ninth", "tenth", "eleventh", "twelfth", "thirteenth",
+  "fourteenth", "fifteenth", "sixteenth", "seventeenth", "eighteenth",
+  "nineteenth",
+];
+const ORDINAL_TENS = [
+  "", "", "twentieth", "thirtieth", "fortieth", "fiftieth", "sixtieth",
+  "seventieth", "eightieth", "ninetieth",
+];
+const NUMBER_WORDS = new Set([
+  ...ONES,
+  ...TENS.filter(Boolean),
+  "hundred",
+  ...ORDINAL_ONES,
+  ...ORDINAL_TENS.filter(Boolean),
+]);
+
+/** Null from 1000 up: "2026" has no single spoken form, so it stays written on both sides. */
+function cardinalWords(n) {
+  if (!Number.isInteger(n) || n < 0 || n >= 1000) return null;
+  if (n < 20) return [ONES[n]];
+  if (n < 100) {
+    const unit = n % 10;
+    const tens = TENS[Math.floor(n / 10)];
+    return unit === 0 ? [tens] : [tens, ONES[unit]];
+  }
+  const rest = n % 100 === 0 ? [] : (cardinalWords(n % 100) ?? []);
+  return [ONES[Math.floor(n / 100)], "hundred", ...rest];
+}
+
+function ordinalWords(n) {
+  if (!Number.isInteger(n) || n < 0 || n >= 100) return null;
+  if (n < 20) return [ORDINAL_ONES[n]];
+  const unit = n % 10;
+  const tens = Math.floor(n / 10);
+  return unit === 0 ? [ORDINAL_TENS[tens]] : [TENS[tens], ORDINAL_ONES[unit]];
+}
+
+const asInt = (digits) => Number.parseInt(digits.replace(/,/g, ""), 10);
+
+function clockWords(hourDigits, minuteDigits) {
+  const hour = cardinalWords(asInt(hourDigits));
+  if (!hour) return null;
+  if (minuteDigits === undefined) return hour;
+  const minute = asInt(minuteDigits);
+  if (minute === 0) return hour;
+  if (minute < 10) return [...hour, "oh", ONES[minute]];
+  return [...hour, ...(cardinalWords(minute) ?? [])];
+}
+
+/** Spoken words for a written number form ("2:30", "2pm", "20%", "$5.50", "3rd", "1,000"), or null. */
+function numericWords(core) {
+  const time = /^(\d{1,2}):(\d{2})$/.exec(core);
+  if (time) return clockWords(time[1], time[2]);
+
+  const meridiem = /^(\d{1,2})(?::(\d{2}))?([ap])\.?m\.?$/.exec(core);
+  if (meridiem) {
+    const clock = clockWords(meridiem[1], meridiem[2]);
+    return clock ? [...clock, `${meridiem[3]}m`] : null;
+  }
+
+  const percent = /^(\d[\d,]*)%$/.exec(core);
+  if (percent) {
+    const amount = cardinalWords(asInt(percent[1]));
+    return amount ? [...amount, "percent"] : null;
+  }
+
+  const money = /^\$(\d[\d,]*)(?:\.(\d{2}))?$/.exec(core);
+  if (money) {
+    const amount = asInt(money[1]);
+    const dollars = cardinalWords(amount);
+    if (!dollars) return null;
+    const unit = amount === 1 ? "dollar" : "dollars";
+    const cents = money[2] === undefined ? 0 : asInt(money[2]);
+    if (cents === 0) return [...dollars, unit];
+    return [...dollars, unit, ...(cardinalWords(cents) ?? [])];
+  }
+
+  const ordinal = /^(\d+)(?:st|nd|rd|th)$/.exec(core);
+  if (ordinal) return ordinalWords(asInt(ordinal[1]));
+
+  if (/^\d[\d,]*$/.test(core)) return cardinalWords(asInt(core));
+  return null;
+}
+
+/** The spoken tokens of one written word, before SAME_WORD_SPELLINGS; empty for pure punctuation. */
+function spokenForms(word) {
+  const lower = String(word ?? "").toLowerCase();
+  // "twenty-five", "3-pack", "F-150" split; "e-mail" stays whole.
+  if (lower.includes("-")) {
+    const parts = lower.split("-").filter(Boolean);
+    const isNumber = (p) => /\d/.test(p) || NUMBER_WORDS.has(p.replace(/[^a-z]/g, ""));
+    if (parts.length > 1 && parts.some(isNumber)) return parts.flatMap(spokenForms);
+  }
+  // Keep a leading "$" and a trailing "%". They decide how the number is said.
+  const core = lower.replace(/^[^\p{L}\p{N}$]+/u, "").replace(/[^\p{L}\p{N}%]+$/u, "");
+  const numeric = numericWords(core);
+  if (numeric) return numeric;
+  // #3133: a scribe writes a spoken "glowmist dot com" as "Glowmist.com".
+  if (/^[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z]{2,})+$/.test(core)) {
+    return core.split(".").flatMap((part, i) => [...(i ? ["dot"] : []), ...spokenForms(part)]);
+  }
+  const plain = wordToken(core);
+  // "F150" must read the same as "F-150", which the hyphen split above expands.
+  if (/\p{L}/u.test(plain) && /\p{N}/u.test(plain)) {
+    return (plain.match(/\p{L}+|\p{N}+/gu) ?? []).flatMap(spokenForms);
+  }
+  return plain ? [plain] : [];
+}
+
 /** The spoken tokens of one written word; empty for pure punctuation. */
 function spokenWords(word) {
-  const core = String(word ?? "").toLowerCase().replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "");
-  // #3133: a scribe writes a spoken "glowmist dot com" as "Glowmist.com".
-  const parts = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z]{2,})+$/.test(core)
-    ? core.split(".").flatMap((part, i) => (i ? ["dot", part] : [part]))
-    : [core];
-  return parts.map(wordToken).filter(Boolean).map((t) => SAME_WORD_SPELLINGS.get(t) ?? t);
+  return spokenForms(word).map((t) => SAME_WORD_SPELLINGS.get(t) ?? t);
 }
 
 /** { tokens, sourceIndex }: tokens[i] came from written word sourceIndex[i]. */
@@ -561,6 +684,7 @@ export function scenePlans(storyboard) {
       cutawayType: typeof scene.cutawayType === "string" ? scene.cutawayType : null,
       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,
     });
   }
   return plans;
@@ -646,7 +770,9 @@ export function cueEndInSegment(seg, counts, cueLineId) {
  * in order, and a cut stops short of a sound made up before or after the line
  * ("Hmm", "Um"), even at the ad's own edges (#2541). Sounds inside the line stay.
  * A scene the storyboard marks with actionTailSec keeps that long after its last
- * word, so the action it ends on (her setting the mat down, #3199) is seen.
+ * word, so the action it ends on (her setting the mat down, #3199) is seen, and
+ * one marked with actionLeadSec keeps that long before its first word, so the
+ * action it opens on (the dog stepping onto the mat, #3272) is seen.
  */
 function trimJoins(spine, reactionCues, scriptLines) {
   spine.forEach((seg, k) => {
@@ -660,7 +786,7 @@ function trimJoins(spine, reactionCues, scriptLines) {
     const after = span ? seg.words.slice(span.last + 1) : [];
     const firstWord = Math.min(...line.map((w) => w.s));
     const lastWord = Math.max(...line.map((w) => w.e));
-    let inSec = Math.max(0, floorFrame(firstWord - lead));
+    let inSec = Math.max(0, floorFrame(firstWord - Math.max(lead, seg.actionLeadSec ?? 0)));
     if (before.length > 0) {
       const clear = ceilFrame(Math.max(...before.map((w) => w.e)) + EXTRA_CLEARANCE_SEC);
       inSec = Math.max(inSec, Math.min(clear, floorFrame(firstWord)));
@@ -879,6 +1005,7 @@ export function buildTimeline({
         sceneIndex: n, source: "clip", file: scene.clip, clipSeconds: clip.seconds, inSec: 0,
         lineIds: plan.lineIds, firstSpeaker: plan.firstSpeaker, lastSpeaker: plan.lastSpeaker,
         baseShotId: plan.baseShotId ?? null, actionTailSec: plan.actionTailSec ?? 0,
+        actionLeadSec: plan.actionLeadSec ?? 0,
       };
       if (voice && (narrated || !clip.hasAudio)) {
         const voiceSeconds = probe(voice).seconds;

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

@@ -161,7 +161,7 @@ Accepts a workflow id **or** a name. It reports three things:
 
 Fill every required input. For a free-text brief you can compose a **bespoke brief from in-session research** — the winning angle you just worked out, the swipe you analyzed — and pass it inline (`--input brief="..."`) or, if it's long, write it to a project file and pass it with `@file` (see Chain, below). For URL/swipe sources, pass the value the source expects.
 
-**A brief wired straight into a Storyboard is a script, not a prompt.** On a video workflow whose Storyboard takes its `script` port from a Brief node, the text you pass for that brief boards VERBATIM, the same way a Show ad's pasted script does: one speaker per scene, every line rendered once in order, long lines split across clips, narrated lines rendered silent under the voice track. So it must be in the script form the `exodus-video` skill documents (an optional `DIRECTION:` block with no colon in its prose, then an optional `CAST:` block of `NAME — description` lines, then `NAME:` turns, then a `CTA:` block; `NARRATOR:` lines only for Narrated Story and Explainer). A brief that is not a script, or one that does not fit the wired rig's family, is refused at launch with the parser's own message and nothing is spent. Write the script to a file and pass it with `--input script=@script.txt`. A Storyboard fed by a bot is unaffected.
+**A brief wired straight into a Storyboard is a script, not a prompt.** On a video workflow whose Storyboard takes its `script` port from a Brief node, the text you pass for that brief boards VERBATIM, the same way a Show ad's pasted script does: one speaker per scene, every line rendered once in order, long lines split across clips, narrated lines rendered silent under the voice track. So it must be in the script form the `exodus-video` skill documents (an optional `DIRECTION:` block with no colon in its prose, then an optional `CAST:` block of `NAME — description` lines, then `NAME:` turns, then a `CTA:` block; `NARRATOR:` lines only for Narrated Story and Explainer). A brief that is not a script, or one that does not fit the wired rig's family, is refused at launch with the parser's own message and nothing is spent. Write the script to a file and pass it with `--input script=@script.txt`. A Storyboard fed by a bot is unaffected. This path does not tidy: if the user hands you a plain transcript, a rough draft or a description, start it with `exodus video start --script <file> --conceit …` instead, which takes the text as it is and lays it out on the server (see the `exodus-video` skill's "The script file"), or run that with `--stop-at-script` first to get the script in the format for the Brief.
 
 **A saved rig can bring a rulebook with it.** Some saved rigs carry saved format rules: how many speakers the script may have, which checks run on the clips, how the cast is built. Point a Rig box at one of those rigs and the run follows its rules — an ensemble rig seats more speakers than the usual three, a talking-head rig seats one. The start receipt says which rulebook ran:
 

package/dist/commands/video-customer.d.ts

@@ -41,10 +41,22 @@ export interface CustomerRun {
     stopReason: CustomerStopReason | null;
     detailsPath: string | null;
 }
+export interface ScriptTidied {
+    setAside: string[];
+    added: {
+        names: string[];
+        descriptions: {
+            name: string;
+            description: string;
+        }[];
+    };
+}
 export interface CustomerStart {
     view: "customer";
     runId: string;
     dashboardUrl: string;
+    tidied?: ScriptTidied;
+    written?: string;
 }
 export interface CustomerStoryboard {
     view: "customer";

package/dist/commands/video.d.ts

@@ -222,6 +222,7 @@ export interface NodeItem {
         outcome: string;
         label: string;
         reason?: string;
+        voiceFirstBlockedBy?: string[];
         displacedHistory?: {
             title: string;
             lines: string[];
@@ -440,6 +441,7 @@ export interface StartOptions {
     music?: boolean;
     wait: boolean;
     json: boolean;
+    onProgressLine?: (line: string) => void;
 }
 export interface ScriptStartOptions {
     scriptFile: string;
@@ -453,8 +455,10 @@ export interface ScriptStartOptions {
     reviewStoryboard?: true;
     director?: true;
     shots?: RunShots;
+    stopAtScript?: true;
     wait: boolean;
     json: boolean;
+    onProgressLine?: (line: string) => void;
 }
 export type VideoStartPlan = {
     kind: "usage";
@@ -482,6 +486,7 @@ export declare function waitFlow(runId: string, opts: {
     url?: string;
     intervalMs?: number;
     maxPolls?: number;
+    onProgressLine?: (line: string) => void;
 }, deps: VideoDeps): Promise<FlowResult>;
 export declare function statusFlow(runId: string, json: boolean, deps: VideoDeps): Promise<FlowResult>;
 export declare function directorLines(director: RunDirector): string[];
@@ -531,7 +536,7 @@ export interface CastVoiceRow {
         voiceId: string;
         label?: string;
     } | null;
-    voiceFrom?: "own-pin" | "run-default";
+    voiceFrom?: "own-pin" | "planner-pick" | "run-default";
     availability?: {
         state: "available";
         providerName: string;
@@ -542,6 +547,18 @@ export interface CastVoiceRow {
         why: string;
     };
     description?: string;
+    fit?: {
+        note: string;
+        clash: boolean;
+    };
+    catalogPicks?: Array<{
+        voiceId: string;
+        name: string;
+        fit?: {
+            note: string;
+            clash: boolean;
+        };
+    }>;
     spokenScenes: number;
     spokenSeconds: number;
 }
@@ -576,7 +593,18 @@ export type VoiceMap = Record<string, string | {
     label?: string;
 } | null>;
 export declare function parseVoiceFlags(occurrences: FlagOccurrence[], readFile: (path: string) => string): VoiceMap | null;
+export interface CatalogVoiceEntry {
+    voiceId: string;
+    name: string;
+    gender: string;
+    age: string;
+    accent: string;
+    qualities: string[];
+    characterVoice: boolean;
+}
+export declare function voiceCatalogFlow(runId: string | undefined, json: boolean, deps: VideoDeps): Promise<FlowResult>;
 export declare function voicesFlow(runId: string, voices: VoiceMap | null, json: boolean, deps: VideoDeps): Promise<FlowResult>;
+export declare const VOICE_CLASH_HINT: string;
 export declare function voiceSheetLines(sheet: CastVoiceSheet): string[];
 export interface CustomerManifest {
     runId: string;

package/dist/commands/video.js

@@ -14,6 +14,11 @@ function joinedOr(items) {
         return items[0] ?? "";
     return `${items.slice(0, -1).join(", ")} or ${items[items.length - 1]}`;
 }
+function joinedAnd(items) {
+    if (items.length <= 1)
+        return items[0] ?? "";
+    return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
 export function scriptRunPickProblem(options, conceit, style) {
     const keys = options.conceits.map((row) => row.key);
     if (!keys.includes(conceit)) {
@@ -64,6 +69,8 @@ The whole loop, in order:
      and who pays. Add --set to give someone a voice, before any clip is made.
 
   6. exodus video approve <runId>          (looks right — keep going)
+     Guided runs only. A One-shot run approves its own storyboard and stops
+     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.
 
@@ -95,9 +102,9 @@ The whole loop, in order:
 
   10. exodus video upload <runId> --file cut.mp4
       Attaches your cut to the run and prints the page to watch it on. On a
-      One-shot run the upload delivers the ad, so step 11 is not needed.
+      One-shot run the upload delivers the ad and you are done.
 
-  11. exodus video approve <runId>
+  11. Guided runs only: exodus video approve <runId>
       Or click Approve on the page from step 10. If you redid a clip after
       uploading, this stops and says which scenes changed. Upload a fresh cut,
       or add --approve-stale-cut to deliver the cut you already uploaded.
@@ -109,10 +116,11 @@ Usage:
   exodus video retry-frame <runId> [--node <nodeId>] --scene <n> [--note "..."] [--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>=<voiceId>] [--clear <character>] [--from <file.json>] [--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] [--review-storyboard] [--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] [--one-shot] [--director] [--wait] [--json]
   exodus video director <runId> <on|off|follow> [--json]
 
 Options:
@@ -135,15 +143,30 @@ Options:
   --approve-stale-cut  Deliver the cut you uploaded even though a clip changed
                        after you uploaded it (approve). Without it, approving
                        stops and names the scenes that changed
-  --set <who>=<id>     Give a character an ElevenLabs voice (voices). Name the
-                       character by its ID or by the name your script uses.
-                       Repeat it once per character
+  --set <who>=<voice>  Give a character a voice (voices). The voice is a
+                       catalog voice's name, like George, or an ElevenLabs
+                       voice ID. Name the character by its ID or by the name
+                       your script uses. Repeat it once per character
   --clear <who>        Take a character's voice off again (voices). Repeatable
-  --from <file.json>   A file of characters and voice IDs (voices). --set and
-                       --clear win over the same name in the file
+  --from <file.json>   A file of characters and voices, by name or ID (voices).
+                       --set and --clear win over the same name in the file
+  --catalog            List the voices you can pick by name (voices). No run
+                       needed. With a run, also the best few for each
+                       character who speaks
   --rejected-draft     Print the storyboard draft the system turned down
                        (status). It was thrown away — a record only
-  --script <file>      Text file of what the ad says (start)
+  --script <file>      Text file of what the ad says (start). Anything works:
+                       a plain transcript, a rough draft, or a description of
+                       the ad. With --conceit, the server lays it out in the
+                       format the video needs without changing a spoken word,
+                       and says what it did. A description gets a script
+                       written from it, printed, and the run starts on it. If
+                       the server can't tell who says a line, it asks and
+                       starts nothing. If a description is too thin to write
+                       from, it says what is missing and starts nothing
+  --stop-at-script     Print the script the run would start on, and start
+                       nothing (start, with --conceit). To read a written or
+                       laid-out script first; send it back with --script
   --conceit <kind>     Kind of ad (start)
   --style <look>       Look (start)
                        The server lists the kinds and looks it offers. An unknown word prints them.
@@ -163,9 +186,14 @@ 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
+  --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,
+                       which is the part that costs. Without it the run is
+                       Guided: it stops at the storyboard for your yes
   --review-storyboard  Stop at the storyboard so you can approve it yourself
-                       (start, with --conceit). By default the app approves its
-                       own storyboard when its checks pass
+                       (start, with --conceit). This is the default, so the
+                       flag changes nothing. Kept for scripts that pass it
   --director           Turn the trial director on for this ad (start, with
                        --conceit). Admins only. To switch it on or off later:
                        exodus video director <runId> on|off|follow, where
@@ -177,7 +205,8 @@ Options:
 
 Who can use what. Admins get every command here. Beta testers with video
 switched on get these, on their own brands: start (--script, --conceit,
---style, --direction, --frame, --pacing, --music, --review-storyboard),
+--style, --direction, --frame, --pacing, --music, --one-shot,
+--review-storyboard, --stop-at-script),
 status, storyboard, approve (the storyboard), voices, retry-frame --scene <n> (redo one scene's
 picture while the storyboard waits), pull (the finished video, each scene's
 clip and voice, and the music) and upload. These stay admin-only:
@@ -197,7 +226,9 @@ Examples:
   exodus video retry-clip run_123 --scene 3 --voice-first
   exodus video revoice run_123 --all
   exodus video voices run_123
-  exodus video voices run_123 --set C1=abc123voiceid --set "HOST 2=def456voiceid"
+  exodus video voices --catalog
+  exodus video voices run_123 --catalog
+  exodus video voices run_123 --set C1=George --set "HOST 2=def456voiceid"
   exodus video voices run_123 --from voices.json
   exodus video pull run_123 --out ./ad-run_123
   exodus video upload run_123 --file ./cut.mp4
@@ -1276,11 +1307,17 @@ export async function startFlow(opts, deps) {
             lines: opts.json ? [JSON.stringify({ runId, url })] : lines,
         };
     }
-    const waited = await waitFlow(runId, { json: opts.json, url }, deps);
-    return {
-        code: waited.code,
-        lines: opts.json ? waited.lines : [`Started ad run ${runId}`, `Watch it: ${url}`, "", ...waited.lines],
-    };
+    return startedThenWait(runId, [`Started ad run ${runId}`, `Watch it: ${url}`], { ...opts, url }, deps);
+}
+async function startedThenWait(runId, head, opts, deps) {
+    const stream = opts.json ? undefined : opts.onProgressLine;
+    if (stream)
+        for (const line of [...head, ""])
+            stream(line);
+    const waited = await waitFlow(runId, { json: opts.json, url: opts.url, onProgressLine: stream }, deps);
+    if (opts.json || stream)
+        return waited;
+    return { code: waited.code, lines: [...head, "", ...waited.lines] };
 }
 function nonBlank(value) {
     if (value === undefined || value.trim().length === 0)
@@ -1362,13 +1399,32 @@ export function planVideoStart(flags, occurrences) {
         return { kind: "usage", line: pacingFlag.line };
     const videoModel = videoModelFlag.value;
     const voiceMode = voiceFlag.value;
-    const reviewStoryboard = occurrences.some((o) => o.flag === "review-storyboard");
-    if (showId && reviewStoryboard) {
+    const reviewStoryboardFlag = occurrences.some((o) => o.flag === "review-storyboard");
+    const oneShot = occurrences.some((o) => o.flag === "one-shot");
+    if (showId && reviewStoryboardFlag) {
         return {
             kind: "usage",
             line: "--review-storyboard works with --conceit, not --show. A Show's ad always stops at the storyboard for you.",
         };
     }
+    if (showId && oneShot) {
+        return {
+            kind: "usage",
+            line: "--one-shot works with --conceit, not --show. A Show's ad always stops at the storyboard for you.",
+        };
+    }
+    if (oneShot && reviewStoryboardFlag) {
+        return {
+            kind: "usage",
+            line: "Pass --one-shot or --review-storyboard, not both.",
+        };
+    }
+    if (occurrences.some((o) => o.flag === "one-shot" && o.value !== undefined && !o.value.startsWith("--"))) {
+        return {
+            kind: "usage",
+            line: "--one-shot takes no value. Leave it off to stop at the storyboard.",
+        };
+    }
     const directorFlags = occurrences.filter((o) => o.flag === "director");
     if (directorFlags.some((o) => o.value !== undefined && !o.value.startsWith("--"))) {
         return {
@@ -1377,6 +1433,20 @@ export function planVideoStart(flags, occurrences) {
         };
     }
     const director = directorFlags.length > 0;
+    const stopFlags = occurrences.filter((o) => o.flag === "stop-at-script");
+    if (stopFlags.some((o) => o.value !== undefined && !o.value.startsWith("--"))) {
+        return {
+            kind: "usage",
+            line: "--stop-at-script takes no value. Leave it off to start the run.",
+        };
+    }
+    const stopAtScript = stopFlags.length > 0;
+    if (showId && stopAtScript) {
+        return {
+            kind: "usage",
+            line: "--stop-at-script works with --conceit, not --show. A Show's script is read as you wrote it.",
+        };
+    }
     if (showId && director) {
         return {
             kind: "usage",
@@ -1445,10 +1515,12 @@ export function planVideoStart(flags, occurrences) {
         opts.voiceMode = voiceMode;
     if (musicChoice.music !== undefined)
         opts.music = musicChoice.music;
-    if (reviewStoryboard)
+    if (!oneShot)
         opts.reviewStoryboard = true;
     if (director)
         opts.director = true;
+    if (stopAtScript)
+        opts.stopAtScript = true;
     if (frameFlag.value || pacingFlag.value) {
         opts.shots = {
             ...(frameFlag.value ? { frame: frameFlag.value } : {}),
@@ -1502,6 +1574,140 @@ function startedVideoChoice(value) {
         return null;
     return { videoModel: value.videoModel, voiceMode: value.voiceMode };
 }
+function stringsOf(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function isCastNote(value) {
+    return isRecord(value) && typeof value.name === "string" && typeof value.description === "string";
+}
+function scriptTidiedOf(value) {
+    if (!isRecord(value))
+        return null;
+    const added = isRecord(value.added) ? value.added : {};
+    return {
+        setAside: stringsOf(value.setAside),
+        added: {
+            names: stringsOf(added.names),
+            descriptions: Array.isArray(added.descriptions) ? added.descriptions.filter(isCastNote) : [],
+        },
+    };
+}
+function scriptTidiedHead(tidied) {
+    if (!tidied)
+        return [];
+    const { setAside } = tidied;
+    const { names, descriptions } = tidied.added;
+    return [
+        "We laid your script out in the format the video needs. " +
+            (setAside.length === 0
+                ? "Every spoken word is unchanged."
+                : "Every spoken line we kept is word for word what you wrote."),
+        ...(names.length === 1 ? [`We called the person your script doesn't name ${names[0]}.`] : []),
+        ...(names.length > 1 ? [`We called the people your script doesn't name ${joinedAnd(names)}.`] : []),
+        ...(descriptions.length > 0
+            ? [
+                "We added a short note on who each person is. It's never spoken; it only guides the video:",
+                ...descriptions.map(({ name, description }) => `  ${name} — ${description}`),
+            ]
+            : []),
+        ...(setAside.length > 0
+            ? [
+                "We left out these lines because they don't look like part of the ad:",
+                ...setAside.map((line) => `  "${line}"`),
+            ]
+            : []),
+        "",
+    ];
+}
+function scriptWrittenHead(written, started) {
+    if (written === null)
+        return [];
+    return [
+        started
+            ? "Your file described the ad, so we wrote this script from it and started the run on it:"
+            : "Your file described the ad, so we wrote this script from it:",
+        "",
+        ...written.split("\n").map((line) => (line ? `  ${line}` : "")),
+        "",
+    ];
+}
+function writtenOf(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+function scriptNeedsCallerResult(res, json) {
+    const data = res.data;
+    if (!isRecord(data) || !isRecord(data.error))
+        return null;
+    const code = data.error.code;
+    const field = code === "SCRIPT_QUESTION" ? "lines" : code === "SCRIPT_TOO_THIN" ? "missing" : null;
+    if (field === null)
+        return null;
+    const message = formatApiError(res);
+    if (json) {
+        return {
+            code: 1,
+            lines: [
+                JSON.stringify({ ok: false, status: res.status, code, error: message, [field]: stringsOf(data[field]) }),
+            ],
+        };
+    }
+    return { code: 1, lines: [message] };
+}
+function scriptStartRefused(res, json) {
+    const data = isRecord(res.data) ? res.data : {};
+    const tidied = data.tidied === undefined ? null : scriptTidiedOf(data.tidied);
+    const written = writtenOf(data.written);
+    if (!tidied && written === null)
+        return errorResult(res, json);
+    const script = typeof data.script === "string" ? data.script : null;
+    const error = videoApiError(res);
+    return {
+        code: 1,
+        lines: json
+            ? [
+                JSON.stringify({
+                    ok: false,
+                    status: res.status,
+                    error,
+                    ...(tidied ? { tidied } : {}),
+                    ...(written !== null ? { written } : {}),
+                    ...(script !== null ? { script } : {}),
+                }),
+            ]
+            : [...scriptTidiedHead(tidied), ...scriptWrittenHead(written, false), error],
+    };
+}
+function stoppedAtScriptResult(data, json) {
+    const script = typeof data.script === "string" ? data.script : "";
+    const tidied = data.tidied === undefined ? null : scriptTidiedOf(data.tidied);
+    const written = writtenOf(data.written);
+    if (json) {
+        return {
+            code: 0,
+            lines: [
+                JSON.stringify({
+                    stoppedAtScript: true,
+                    script,
+                    ...(tidied ? { tidied } : {}),
+                    ...(written !== null ? { written } : {}),
+                }),
+            ],
+        };
+    }
+    return {
+        code: 0,
+        lines: [
+            ...scriptTidiedHead(tidied),
+            written !== null
+                ? "Your file described the ad, so we wrote this script from it. Nothing has started."
+                : "This is the script the run would start on. Nothing has started.",
+            "",
+            ...script.split("\n").map((line) => (line ? `  ${line}` : "")),
+            "",
+            "To start it, save it to a file and run the same command with --script <that file> and without --stop-at-script.",
+        ],
+    };
+}
 function scriptStartedLines(runId, url, card, video, director) {
     return [
         `Started ad run ${runId}`,
@@ -1518,7 +1724,7 @@ function scriptStartedLines(runId, url, card, video, director) {
         `Watch it: ${url}`,
     ];
 }
-function waitJsonWithCard(waited, card, video) {
+function waitJsonWith(waited, facts) {
     const first = waited.lines[0];
     if (typeof first !== "string")
         return waited;
@@ -1533,7 +1739,7 @@ function waitJsonWithCard(waited, card, video) {
         return waited;
     return {
         code: waited.code,
-        lines: [JSON.stringify({ ...parsed, card, ...(video ? { videoChoice: video } : {}) })],
+        lines: [JSON.stringify({ ...parsed, ...facts })],
     };
 }
 export async function startScriptFlow(opts, deps) {
@@ -1575,9 +1781,13 @@ export async function startScriptFlow(opts, deps) {
         ...(opts.reviewStoryboard ? { reviewStoryboard: true } : {}),
         ...(opts.director ? { director: true } : {}),
         ...(opts.shots ? { shots: opts.shots } : {}),
+        ...(opts.stopAtScript ? { stopAtScript: true } : {}),
     });
     if (!res.ok)
-        return errorResult(res, opts.json);
+        return scriptNeedsCallerResult(res, opts.json) ?? scriptStartRefused(res, opts.json);
+    if (isRecord(res.data) && res.data.stoppedAtScript === true) {
+        return stoppedAtScriptResult(res.data, opts.json);
+    }
     const customerStart = customerAnswer(res.data);
     if (customerStart)
         return customerStartedResult(customerStart, opts, deps);
@@ -1589,12 +1799,22 @@ export async function startScriptFlow(opts, deps) {
     const url = typeof started.url === "string" ? started.url : "";
     const card = isResolvedCard(started.card) ? started.card : null;
     const video = startedVideoChoice(started.videoChoice);
+    const tidied = started.tidied === undefined ? null : scriptTidiedOf(started.tidied);
+    const written = writtenOf(started.written);
+    const facts = {
+        card,
+        ...(video ? { videoChoice: video } : {}),
+        ...(tidied ? { tidied } : {}),
+        ...(written !== null ? { written } : {}),
+    };
+    const head = [...scriptTidiedHead(tidied), ...scriptWrittenHead(written, true)];
     if (!opts.wait) {
         return {
             code: 0,
             lines: opts.json
-                ? [JSON.stringify({ runId, url, card, ...(video ? { videoChoice: video } : {}) })]
+                ? [JSON.stringify({ runId, url, ...facts })]
                 : [
+                    ...head,
                     ...scriptStartedLines(runId, url, card, video, opts.director === true),
                     "",
                     ...(opts.reviewStoryboard
@@ -1607,20 +1827,23 @@ export async function startScriptFlow(opts, deps) {
                 ],
         };
     }
-    const waited = await waitFlow(runId, { json: opts.json, url }, deps);
-    if (opts.json)
-        return waitJsonWithCard(waited, card, video);
-    return {
-        code: waited.code,
-        lines: [...scriptStartedLines(runId, url, card, video, opts.director === true), "", ...waited.lines],
-    };
+    const waited = await startedThenWait(runId, [...head, ...scriptStartedLines(runId, url, card, video, opts.director === true)], { ...opts, url }, deps);
+    return opts.json ? waitJsonWith(waited, facts) : waited;
 }
 async function customerStartedResult(started, opts, deps) {
     const { runId, dashboardUrl } = started;
-    const head = [`Started video ${runId}`, `Watch it: ${dashboardUrl}`];
+    const tidied = started.tidied === undefined ? null : scriptTidiedOf(started.tidied);
+    const written = writtenOf(started.written);
+    const head = [
+        ...scriptTidiedHead(tidied),
+        ...scriptWrittenHead(written, true),
+        `Started video ${runId}`,
+        `Watch it: ${dashboardUrl}`,
+    ];
     if (opts.wait) {
-        const waited = await waitFlow(runId, { json: opts.json, url: dashboardUrl }, deps);
-        return opts.json ? waited : { code: waited.code, lines: [...head, "", ...waited.lines] };
+        const waited = await startedThenWait(runId, head, { ...opts, url: dashboardUrl }, deps);
+        const facts = { ...(tidied ? { tidied } : {}), ...(written !== null ? { written } : {}) };
+        return opts.json && (tidied || written !== null) ? waitJsonWith(waited, facts) : waited;
     }
     if (opts.json)
         return { code: 0, lines: [JSON.stringify(started)] };
@@ -1644,6 +1867,17 @@ export async function waitFlow(runId, opts, deps) {
     const lines = [];
     let lastProgress = null;
     let redoSeen = false;
+    const progress = (line) => {
+        if (line === lastProgress)
+            return;
+        lastProgress = line;
+        if (opts.json)
+            return;
+        if (opts.onProgressLine)
+            opts.onProgressLine(line);
+        else
+            lines.push(line);
+    };
     for (let poll = 0; poll < maxPolls; poll++) {
         if (poll > 0)
             await deps.sleep(interval);
@@ -1656,12 +1890,7 @@ export async function waitFlow(runId, opts, deps) {
         if (customer) {
             const page = customerRunPage(deps.dashboardUrl, runId);
             if (customerStageIsWorking(customer.stage)) {
-                const progress = customerStageLines(customer, page)[0];
-                if (progress !== lastProgress) {
-                    lastProgress = progress;
-                    if (!opts.json)
-                        lines.push(progress);
-                }
+                progress(customerStageLines(customer, page)[0]);
                 continue;
             }
             return {
@@ -1674,14 +1903,9 @@ export async function waitFlow(runId, opts, deps) {
         const run = asVideoRun(res.data);
         const stop = classifyRun(run);
         if (stop.at === "running") {
-            const progress = stop.autoRedoScenes?.length
+            progress(stop.autoRedoScenes?.length
                 ? autoRedoLine(stop.autoRedoScenes, stop.autoRedoReasons)
-                : `Working: ${stageWord(stop.stage)}…`;
-            if (progress !== lastProgress) {
-                lastProgress = progress;
-                if (!opts.json)
-                    lines.push(progress);
-            }
+                : `Working: ${stageWord(stop.stage)}…`);
             continue;
         }
         let items = null;
@@ -1693,12 +1917,7 @@ export async function waitFlow(runId, opts, deps) {
             const redoing = items ? scenesBeingRedone(run, items) : [];
             redoSeen = redoing.length > 0;
             if (redoSeen) {
-                const progress = `Working: redoing scene${redoing.length === 1 ? "" : "s"} ${redoing.join(", ")}…`;
-                if (progress !== lastProgress) {
-                    lastProgress = progress;
-                    if (!opts.json)
-                        lines.push(progress);
-                }
+                progress(`Working: redoing scene${redoing.length === 1 ? "" : "s"} ${redoing.join(", ")}…`);
                 continue;
             }
         }
@@ -1846,6 +2065,10 @@ export async function statusFlow(runId, json, deps) {
             lines.push(`${String(sceneIndex).padEnd(5)}  ${itemWord(row.clip).padEnd(8)}  ${itemWord(row.voiceover).padEnd(8)}  ${itemWord(row.frame)}`);
             if (row.clip?.lastRedo) {
                 lines.push(`       clip: ${redoLine(row.clip.lastRedo)}`);
+                const blocked = row.clip.lastRedo.voiceFirstBlockedBy;
+                if (blocked?.length) {
+                    lines.push(`       clip: asked for voice first, but redone the usual way — ${cantSayNames(blocked)}`);
+                }
                 printDisplacedHistory(lines, row.clip.lastRedo);
             }
             if (row.clip?.lastRedo || row.clip?.flagged) {
@@ -1890,6 +2113,9 @@ export async function statusFlow(runId, json, deps) {
             lines.push("Narration  master take");
         }
     }
+    if (run.nodes.some((n) => n.kind === "storyboard" && n.status === "done")) {
+        lines.push(...(await statusVoiceLines(runId, deps)));
+    }
     lines.push("", hasFinal && stop.at === "finished"
         ? "Final cut: approved and delivered."
         : hasFinal
@@ -2055,7 +2281,7 @@ export async function storyboardFlow(runId, json, deps) {
             if (summary.length > 0) {
                 lines.push("", ...summary);
                 if (canChange) {
-                    lines.push(`set voices with: exodus video voices ${runId} --set <character>=<voiceId>`);
+                    lines.push(`set voices with: exodus video voices ${runId} --set <character>=<voice name or ID>`);
                 }
             }
         }
@@ -2540,8 +2766,8 @@ export function parseVoiceFlags(occurrences, readFile) {
             const raw = valueFor(occurrence);
             const eq = raw.lastIndexOf("=");
             if (eq <= 0 || eq === raw.length - 1) {
-                throw new Error("--set must look like <character>=<voice id>, for example " +
-                    `--set C1=abc123voiceid (got "${raw}").`);
+                throw new Error("--set must look like <character>=<voice>, where the voice is a catalog voice's name " +
+                    `or an ElevenLabs voice ID, for example --set C1=George (got "${raw}").`);
             }
             typed[raw.slice(0, eq).trim()] = raw.slice(eq + 1).trim();
             asked = true;
@@ -2579,6 +2805,57 @@ export function parseVoiceFlags(occurrences, readFile) {
     }
     return { ...merged, ...typed };
 }
+function catalogLines(catalog) {
+    const width = (pick) => Math.max(0, ...catalog.map((voice) => pick(voice).length));
+    const nameWidth = width((voice) => voice.name);
+    const genderWidth = width((voice) => voice.gender);
+    const ageWidth = width((voice) => voice.age);
+    const accentWidth = width((voice) => voice.accent);
+    return [
+        "Voices you can pick by name (ElevenLabs voices every account has)",
+        ...catalog.map((voice) => {
+            const qualities = [...voice.qualities, ...(voice.characterVoice ? ["character voice"] : [])];
+            return (`  ${voice.name.padEnd(nameWidth)}  ${voice.gender.padEnd(genderWidth)}  ` +
+                `${voice.age.padEnd(ageWidth)}  ${voice.accent.padEnd(accentWidth)}  ${qualities.join(", ")}`).trimEnd();
+        }),
+    ];
+}
+function catalogPickLines(cast) {
+    const lines = [];
+    for (const row of cast) {
+        if (!row.catalogPicks || row.catalogPicks.length === 0)
+            continue;
+        const width = Math.max(...row.catalogPicks.map((pick) => pick.name.length));
+        lines.push("", `Best fits for ${row.name} (${row.characterId})`);
+        for (const pick of row.catalogPicks) {
+            lines.push(`  ${pick.name.padEnd(width)}${pick.fit ? `  ${pick.fit.note}` : ""}`.trimEnd());
+        }
+    }
+    return lines;
+}
+export async function voiceCatalogFlow(runId, json, deps) {
+    const query = runId ? `runId=${encodeURIComponent(runId)}&check=none&catalog=1` : "catalog=1";
+    const res = await deps.get(`${VOICES_PATH}?${query}`);
+    if (!res.ok)
+        return errorResult(res, json);
+    const data = (res.data ?? {});
+    if (!Array.isArray(data.catalog)) {
+        return { code: 1, lines: ["This server can't list the voice catalog yet. Voice IDs still work with --set."] };
+    }
+    if (json)
+        return { code: 0, lines: [JSON.stringify({ ok: true, ...data })] };
+    const cast = Array.isArray(data.cast) ? data.cast : [];
+    const set = runId ? `exodus video voices ${runId}` : "exodus video voices <runId>";
+    return {
+        code: 0,
+        lines: [
+            ...catalogLines(data.catalog),
+            ...catalogPickLines(cast),
+            "",
+            `Pick one by name: ${set} --set <character>=<Name>`,
+        ],
+    };
+}
 export async function voicesFlow(runId, voices, json, deps) {
     const res = voices
         ? await deps.post(VOICES_PATH, { runId, voices })
@@ -2613,7 +2890,30 @@ function voiceWords(row) {
     if (!voice)
         return "—";
     const words = voice.label ? `${voice.label} (${voice.voiceId})` : voice.voiceId;
-    return row.voiceFrom === "run-default" ? `${words}, the run's default voice` : words;
+    if (row.voiceFrom === "run-default")
+        return `${words}, the run's default voice`;
+    if (row.voiceFrom === "planner-pick")
+        return `${words}, picked by the planner`;
+    return words;
+}
+function fitWords(row) {
+    return row.fit ? `  — ${row.fit.note}` : "";
+}
+export const VOICE_CLASH_HINT = 'To choose a voice yourself, write "voice: <Name>" on that character\'s CAST line in the script, ' +
+    "or launch with --review-storyboard and change it at the storyboard stop.";
+async function statusVoiceLines(runId, deps) {
+    const res = await deps
+        .get(`${VOICES_PATH}?runId=${encodeURIComponent(runId)}&check=none`)
+        .catch(() => null);
+    if (!res?.ok)
+        return [];
+    const sheet = (res.data ?? {});
+    const cast = Array.isArray(sheet.cast) ? sheet.cast : [];
+    const summary = voiceSummaryLines(cast, []);
+    if (summary.length === 0)
+        return [];
+    const clash = cast.some((row) => row.fit?.clash === true);
+    return ["", ...summary, ...(clash ? [VOICE_CLASH_HINT] : [])];
 }
 function voiceSummaryLines(cast, notices) {
     const rows = cast.filter((row) => row.spokenScenes > 0 || row.voice !== null);
@@ -2621,7 +2921,7 @@ function voiceSummaryLines(cast, notices) {
     const lines = rows.length > 0 ? ["Voices"] : [];
     for (const row of rows) {
         lines.push(row.voice
-            ? `  ${row.name.padEnd(width)}  →  ${voiceWords(row)}  ${availabilityWords(row)}`
+            ? `  ${row.name.padEnd(width)}  →  ${voiceWords(row)}  ${availabilityWords(row)}${fitWords(row)}`
             : `  ${row.name.padEnd(width)}  →  no voice chosen (keeps the generated voice)`);
     }
     for (const notice of notices)
@@ -2639,7 +2939,7 @@ export function voiceSheetLines(sheet) {
         const voice = voiceWords(row);
         lines.push(`  ${row.characterId}  ${row.name}  ${voice}  ${availabilityWords(row)}  ` +
             `speaks in ${row.spokenScenes} scene${row.spokenScenes === 1 ? "" : "s"}, ` +
-            `about ${row.spokenSeconds}s`);
+            `about ${row.spokenSeconds}s${fitWords(row)}`);
         if (row.description)
             lines.push(`      written voice: ${row.description}`);
     }
@@ -3214,9 +3514,11 @@ export async function run(flags, occurrences) {
         const plan = planVideoStart(flags, occurrences);
         if (plan.kind === "usage")
             usage(plan.line);
-        if (plan.kind === "show")
-            return printResult(await startFlow(plan.opts, defaultDeps));
-        const started = await startScriptFlow(plan.opts, defaultDeps);
+        const onProgressLine = (line) => console.log(line);
+        if (plan.kind === "show") {
+            return printResult(await startFlow({ ...plan.opts, onProgressLine }, defaultDeps));
+        }
+        const started = await startScriptFlow({ ...plan.opts, onProgressLine }, defaultDeps);
         if (started.usage)
             usage(started.lines[0] ?? "");
         return printResult(started);
@@ -3235,6 +3537,9 @@ export async function run(flags, occurrences) {
         "upload",
         "director",
     ];
+    if (sub === "voices" && flags["catalog"] !== undefined && flags["catalog"] !== false) {
+        return printResult(await voiceCatalogFlow(runId, json, defaultDeps));
+    }
     if (needsRunId.includes(sub) && !runId) {
         usage(`video ${sub} needs a run id: exodus video ${sub} <runId>`);
     }

package/dist/commands/whoami.js

@@ -1,6 +1,6 @@
 import { apiGet, getApiUrl } from "../lib/client.js";
 import { resolveActiveBrand } from "../lib/layout.js";
-import { auth401Hint } from "../lib/backend-hint.js";
+import { auth401Hint, describeServer } from "../lib/backend-hint.js";
 export const helpText = `
 exodus whoami — show identity and brand context for the current API key
 
@@ -9,6 +9,7 @@ Usage:
 
 Reads EXODUS_API_KEY from your .env (or env var) and asks the dashboard which
 workspace this key is bound to. Prints:
+  • Server (the EXODUS_API_URL host it talks to, and whether that is live or dev)
   • Brand (workspace slug + name)
   • User email + role
   • Whether the brand has full Genesis foundation knowledge filled in
@@ -44,6 +45,7 @@ export async function run() {
             ? `\nactive:     (key default)`
             : "";
     console.log(`
+server:     ${describeServer(getApiUrl())}
 brand:      ${d.workspaceName ?? "—"} (${d.workspaceSlug ?? "—"})
 user:       ${d.userEmail ?? "—"} (${d.userRole ?? "—"})
 key:        ${d.keyPrefix ?? "—"}${activeLine}

package/dist/lib/backend-hint.d.ts

@@ -1,2 +1,3 @@
 export declare function isPlaceholderApiUrl(apiUrl: string): boolean;
+export declare function describeServer(apiUrl: string): string;
 export declare function auth401Hint(apiUrl: string): string;

package/dist/lib/backend-hint.js

@@ -4,13 +4,27 @@ const PLACEHOLDER_MARK = "YOUR-EXODUS-BACKEND";
 export function isPlaceholderApiUrl(apiUrl) {
     return !apiUrl || apiUrl.includes(PLACEHOLDER_MARK);
 }
-export function auth401Hint(apiUrl) {
-    let host = apiUrl || "(no EXODUS_API_URL set)";
+function hostLabel(apiUrl) {
     try {
-        host = new URL(apiUrl).host;
+        return new URL(apiUrl).host;
     }
     catch {
+        return apiUrl || "(no EXODUS_API_URL set)";
     }
+}
+export function describeServer(apiUrl) {
+    const host = hostLabel(apiUrl);
+    if (isConvexHostOf(host, PROD_BACKEND))
+        return `${host} (live, xo.copycoders.ai)`;
+    if (isConvexHostOf(host, DEV_BACKEND))
+        return `${host} (dev, dev.xo.copycoders.ai)`;
+    return host;
+}
+function isConvexHostOf(host, deployment) {
+    return host === `${deployment}.convex.site` || host === `${deployment}.convex.cloud`;
+}
+export function auth401Hint(apiUrl) {
+    const host = hostLabel(apiUrl);
     return [
         `This API key was rejected by ${host} (HTTP 401).`,
         `Keys are environment-bound — this key may belong to the other environment.`,

package/package.json

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