@aicopycoders/exodus 2026.9.1900-beta.1 → 2026.9.1900-beta.2

package/assets/docs/CLAUDE.md

@@ -61,7 +61,7 @@ These are the **Exodus** pipelines — the automatic system that drives the Gene
 | **Meme** | `exodus-meme` | Meme ads — recommends formats for a brief, then one batched run renders AI-image and classic Imgflip-template memes server-side. |
 | **Workflow** | `exodus-workflow` | Run and build saved multi-node workflow automations from the CLI, resolve checkpoint/repair parks from the inbox, continue bot sessions, fire triggers, and read banks or promote winners. |
 | **Hooks** | `exodus-hooks` | Read the Scout library — the hook cards captured from Instagram outliers. Compose filters (score, lane, validation status, language, hook type, recency), inspect one card, find cards sharing a hook pattern, export to CSV. Read-only. |
-| **Video** | `exodus-video` | Make a video ad from a script. Main path: run a saved video workflow (`npx @aicopycoders/exodus workflow run`, no Show); starting from a Show (`video start --show`) is the other way in. Then read and approve the storyboard, `npx @aicopycoders/exodus video pull` every piece (per-scene clips, narration and per-scene voice, keyframes, cast stills, word timings, music bed) plus a manifest, cut them in whatever editor you use (a bundled script is one option), upload the cut and approve it. Admin-only. |
+| **Video** | `exodus-video` | Make a video ad from a script. Main path: run a saved video workflow (`npx @aicopycoders/exodus workflow run`, no Show); starting from a Show (`video start --show`) is the other way in. Choose the voices as the run starts: `--voices` gives each speaker an ElevenLabs voice, `--voice-treatment` says how the voices are made (including having the video model speak a voice you wrote). Then read and approve the storyboard, `npx @aicopycoders/exodus video pull` every piece (per-scene clips, narration and per-scene voice, keyframes, cast stills, word timings, music bed) plus a manifest, cut them in whatever editor you use (a bundled script is one option), upload the cut and approve it. Admin-only. |
 | **Browse** | `exodus-browse` | View history and retrieve past outputs |
 | **Drive** | `exodus-drive` | Read/write Google Docs, Sheets, and Drive files via `npx @aicopycoders/exodus drive` (uses the dashboard's Google OAuth — no local CLI) |
 | **Swipe / Mining** | (no skill; CLI only) | The competitor watch list behind the Mining page: `npx @aicopycoders/exodus swipe brands list`, `swipe brands bulk-import <csv>` (checks each brand and starts collecting its ads), `swipe brands add "<Name>" --fb <pageId>` (adds one brand and starts checking it the same way), `swipe run` / `swipe mine`. There is no `competitors` verb. |

package/assets/docs/PIPELINES.md

@@ -215,6 +215,13 @@ Representative commands:
   exodus session list | show | chat
   exodus bank list | show <key> | promote <key>
 Every workflow/session/bank verb takes --json — that output is the machine API.
+
+A video workflow whose Rig box points at a rig with saved format rules follows
+them — how many speakers the script may have, which checks run, how the cast is
+built. The start receipt and `workflow status` name the rulebook and its version;
+`video pull` writes the same facts into manifest.json. Every Rig box in the
+workflow has to point at the same saved rig, or the launch refuses and nothing
+is spent.
 ```
 
 ---
@@ -247,10 +254,14 @@ Returns: a table, --json data, or an exported CSV/JSON file
 
 **What it does:** Makes a video ad from a script, in pieces. Main path is a saved video workflow with no Show (`exodus workflow run <name> --input <field>=@script.txt`); a locked Show (`exodus video start --show`) is the other way in and is the only route with `video flag`. On the workflow route the run stops for your cut only if its video node sets `finalWatch: true` (defaults to off — check with `exodus workflow export`, not `describe`), and video gates are approved with `exodus video approve`, not `workflow checkpoint approve`. Either way the run writes the storyboard, draws a picture per scene, records the voice, renders a clip per scene and generates a music bed, then parks for a cut. The CLI pulls the pieces to a folder with a `manifest.json`; you cut them in whatever editor you use; the upload attaches the cut for approval. Admin-only.
 
+**Voices, on the workflow route.** Two separate choices, both made when the run starts and both refused before the run is created if anything is wrong, so a mistake costs nothing. `--voices @voices.json` says WHICH ElevenLabs voice each speaker gets, keyed by the names the script uses (`HOST 1`) — the same file `exodus video voices <run> --from` reads at the review, so one file per brand serves both moments. `--voice-treatment` says HOW the voices are made: a name on its own for a way of working that plays a voice you picked, or a `voice-treatment.json` shaped `{"path": "...", "describe": {"HOST 1": "Dry, tired baritone."}}` for the ways where the video model speaks the CAST's lines itself in voices you WROTE. A written voice needs one description per speaker, and it cannot be changed at the storyboard review — that is what the flag at launch is for. The two never combine: written voices plus `--voices` is refused, because those ElevenLabs voices would be paid for and never heard. A written voice covers the CAST's lines only: a narrated scene is still recorded by ElevenLabs on the member's own key, so a script with `NARRATOR:` turns still needs the key and still costs ElevenLabs money. Ways of working beyond the two shipped ones are switched on only on the test stack while they are being tried out.
+
 ```operator-guide
 Start (workflow route, no Show):
   exodus workflow list / describe <name>                               find it and see what it needs
   exodus workflow run <workflowId|name> --input <field>=@script.txt [--wait]   start it; --wait stops at the storyboard gate
+  exodus workflow run <workflowId|name> --input <field>=@script.txt --voices @voices.json   ... and give each speaker an ElevenLabs voice up front
+  exodus workflow run <workflowId|name> --input <field>=@script.txt --voice-treatment @voice-treatment.json   ... or have the video model speak voices you WROTE
 Start (Show route):
   exodus video shows [--json]                                          Shows and whether each is ready
   exodus video start --show <id> --script <file> [--wait] [--json]     start an ad run; --wait stops at the storyboard gate

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

@@ -77,6 +77,8 @@ exodus workflow run <workflowId|name> --input <field>=@script.txt --wait
                                                           start, stop at the storyboard gate
 exodus workflow run <workflowId|name> --input <field>=@script.txt --voices @voices.json --wait
                                                           same, with the brand's voices already chosen
+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
 ```
 
@@ -256,6 +258,13 @@ CTA:
 THE SOFTGEL: Tap below and give your eyes ClearBlink.
 ```
 
+**How many speakers you may have depends on the rig.** Three by default. A rig
+that carries saved format rules sets its own number: an ensemble rig seats more,
+a talking-head rig seats one. Over the number, the launch refuses before
+anything is spent and says both figures ("4 speakers — this format supports 3").
+The rulebook the run followed is on the start receipt, on `workflow status`, and
+in `manifest.json` under `provenance`.
+
 ## Reading the storyboard gate
 
 `storyboard <runId>` prints one card per scene on both routes: who speaks, the
@@ -357,6 +366,88 @@ written by a bot is refused with a pointer at the review-time command, because
 nobody knows the speaker names yet. When the storyboard arrives, the voices are
 already set and `exodus video voices <runId>` shows them.
 
+**Choosing how the voices are made.** `--voice-treatment` on `workflow run` says
+HOW a run makes its voices, and it is the only door on the workflow route. Two
+kinds of answer.
+
+A name on its own picks a way of working that plays a voice you already have,
+and still pairs with `--voices`:
+
+```
+exodus workflow run "Podcast Ad" --input script=@script.txt \
+  --voice-treatment lipsync-retarget --voices @voices.json
+```
+
+The other kind has the video model speak the CAST's lines itself, in voices you
+WRITE. Those take a `voice-treatment.json`, which is the whole request body:
+
+```json
+{
+  "path": "native-prompt",
+  "describe": {
+    "BUDGET": "Dry, tired middle-aged baritone. Slight rasp. Deadpan, unhurried.",
+    "PIGGY BANK": "Bright quick alto, a little smug, crisp consonants."
+  }
+}
+```
+
+```
+exodus workflow run "Podcast Ad" --input script=@script.txt \
+  --voice-treatment @voice-treatment.json
+```
+
+Every speaker in the script needs a description. One left out gets a voice the
+model invents afresh on every clip, and that drift only shows up once the clips
+are paid for, so the launch refuses instead.
+
+**The narration is not part of this.** A describing treatment changes how the
+CAST's lines are voiced. A scene with narration (`voText`) is still recorded by
+ElevenLabs on the member's own key by the Voiceover step, exactly as it always
+was — so a run with `NARRATOR:` turns still needs an ElevenLabs key, and still
+costs ElevenLabs money. `exodus video voices <runId>` says which of the two
+shapes a run is, and only claims nothing is sent to ElevenLabs when nothing is.
+
+**What refuses, all before the run is created, so nothing is spent.**
+
+- A treatment name that does not exist. The message lists the ones that do.
+- A describing treatment with a speaker undescribed, a speaker the script does
+  not have, the same speaker described twice, or an empty description.
+- Written voices plus `--voices`. The video model owns the voice on those runs,
+  so the ElevenLabs voices would be paid for and never heard.
+- Descriptions on a treatment that plays voices you picked instead.
+- A workflow whose script is written by a bot. Nobody knows the speaker names
+  yet, so there is nothing to describe.
+- A workflow with no Video step, a Video step whose model cannot do what was
+  asked, or a Video step with nothing wired into its voiceover port when the
+  treatment needs one.
+- No Google AI key on the account, for the treatment that renders through
+  Google directly.
+- A rig that shows every line on screen as text. No clip speaks, so there is no
+  voice to treat.
+
+**Still being tested.** Everything beyond the two shipped ways of working is
+switched on only on the test stack while it is being tried out. On the live
+stack those names refuse by name, and the message says which two to use
+instead. That is a property of the stack, not of the workflow, so the same
+saved workflow behaves differently on each — and a retry asks again rather than
+copying, so a run retried after a treatment was switched off refuses.
+
+**A sub-workflow chooses none of this.** When a Call box runs another workflow
+inside this one, the child run carries no voice treatment: it renders the
+shipped default, whatever the parent was started with. A treatment is a choice a
+person made at a keyboard for one run, and nobody made it for the sub-workflow.
+
+**Written voices cannot be changed at the review.** They are chosen when the run
+starts. `exodus video voices <runId>` on a described run names the treatment and
+prints each written voice, and says plainly that `--voice-treatment` at launch is
+what changes them. Do not tell anyone to create a Show for this, and do not set a
+voice path in node config — neither is a door.
+
+**Where it shows up afterwards.** The launch receipt and `exodus workflow status`
+both print one line naming the treatment and the speakers who got a written
+voice. `manifest.json` from `exodus video pull` carries the same under
+`provenance.voice`, and each cast entry carries its `voiceDescription`.
+
 **The JSON receipt** (`--json`), the same shape for reading and for setting:
 
 ```
@@ -365,12 +456,15 @@ runId
 changed[]             the characters whose voice actually moved (set only)
 canChange             false once the run has left the storyboard review
 whyNot                why, in one sentence, when canChange is false
+treatment.path        which way of making voices this run froze, or null
+treatment.kind        "performance-then-conversion" or "render-owns-voice"
 cast[]                one per character
   characterId, name
   voice               { voiceId, label }: the voice this character's clips are
                       converted to. null only when they have no voice of their
                       own AND the run has no default voice
   voiceFrom           "own-pin" or "run-default"; absent when voice is null
+  description         the WRITTEN voice, when the run was given one
   availability        { state: "available" | "missing" | "not-checked", … }
   spokenScenes        how many scenes this character speaks in
   spokenSeconds       those scenes' planned seconds — what ElevenLabs bills on
@@ -456,6 +550,15 @@ scenes[]                             one per scene, in order
                                      on record when the voice pass replaced the
                                      clip with a new file; null when the clip IS
                                      that file, or there is no clip
+provenance                           which saved rulebook this run followed:
+                                     {format: {via, nodeId, rigId, rigName,
+                                     rulesFrom, specVersion}}. Absent when the
+                                     run followed none. `nodeId` is the Rig box
+                                     that chose it (absent on a Show ad, which
+                                     has no box); `rulesFrom` names the rig the
+                                     rules were borrowed from when the picked
+                                     rig is a copy. Names, ids and a version
+                                     only — never the rules themselves
 failed[]                             files that did not download: {file, url, error}
 ```
 
@@ -504,13 +607,16 @@ own ElevenLabs render.
 **Which scenes carry their voice where.** A scene whose storyboard entry has a
 non-empty `voText` is a narrator scene: its clip is rendered silent and the
 voice arrives as a separate track. A scene with on-camera `dialogue[]` has the
-speech inside the clip — under the default voice path the video model's invented
-voice is then replaced, in place, with the cast member's pinned ElevenLabs voice
-(that is `revoiced: true`). Other voice paths leave the render owning its own
-audio, e.g. lip-sync retargeting a VO track onto the video. The path is frozen
-on the run — `--voice-path` on `video start` sets it on a Show run, the node
-config sets it on a workflow run. Read `wordsFrom` and `revoiced` per scene
-rather than assuming.
+speech inside the clip — under the default voice treatment the video model's
+invented voice is then replaced, in place, with the cast member's pinned
+ElevenLabs voice (that is `revoiced: true`). Other treatments leave the render
+owning its own audio, e.g. lip-sync retargeting a VO track onto the video. The
+treatment is frozen on the run when it starts, and there are exactly two doors
+that set one: `--voice-path` on `video start` for a Show run, and
+`--voice-treatment` on `workflow run` for a workflow run (see **Choosing how the
+voices are made**). Node config is never a door — nothing on the canvas sets a
+voice treatment, and a run that was given none renders the default. Read
+`wordsFrom` and `revoiced` per scene rather than assuming.
 
 **Word timings** (`scene-NN.words.json`). Seconds from the start of the file
 `wordsFrom` names, always. `wordsFrom: "clip"` is an ElevenLabs Scribe

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

@@ -8,7 +8,7 @@ Core — discover & run:
   exodus workflow list [--json]                              List the brand's saved workflows
   exodus workflow describe <workflowId|name> [--json]        Inputs, prerequisites, outputs
   exodus workflow bots [--category <cat>] [--slug <slug>] [--json]   Bot catalog / one bot's spec
-  exodus workflow run <workflowId|name> [--input key=value ...] [--fill <name>] [--auto-approve] [--wait] [--out <dir>] [--json]   Run it
+  exodus workflow run <workflowId|name> [--input key=value ...] [--fill <name>] [--voices <json|@file>] [--voice-treatment <name|json|@file>] [--auto-approve] [--wait] [--out <dir>] [--json]   Run it
   exodus workflow status [--id <runId>] [--out <dir>] [--json]   Poll a run / read its outputs (no --id → the brand's 25 newest runs + their ids)
   exodus workflow cancel <runId> [--reason "..."] [--json]   Stop a run that hasn't finished — queued, running, or parked
   exodus workflow export <workflowId|name> [--version <n>] [--out <file>] [--json]   Dump the contract (YAML)
@@ -51,6 +51,24 @@ Flag notes that add agent-level guidance (everything else is in --help):
                        earlier upload is relayed as-is. Accepted: image PNG/JPEG/
                        WebP/GIF ≤15MB, video MP4/MOV/WebM ≤200MB, audio MP3/M4A/
                        WAV/OGG ≤50MB, document PDF/TXT/MD/DOC/DOCX ≤25MB.
+  --voices <v>         (run, video workflows) Give each speaker in the script an
+                       ElevenLabs voice from the moment the run starts, instead
+                       of at the storyboard review. A JSON object keyed by the
+                       names the SCRIPT uses ("HOST 1"), or @path to a file
+                       holding one — the same voices.json "exodus video voices
+                       <run> --from" reads, so a brand keeps one file for both.
+  --voice-treatment <v>  (run, video workflows) Say HOW the run makes its voices.
+                       A name on its own picks a way of working that plays a
+                       voice you already have (and still takes --voices); a JSON
+                       object, or @path to one, shaped {"path": "...",
+                       "describe": {"HOST 1": "..."}} has the video model speak
+                       the lines itself in a voice you WROTE, one description per
+                       speaker. Written voices and --voices are refused together:
+                       the ElevenLabs voices would be paid for and never heard.
+                       Chosen at launch only — the storyboard review can show a
+                       written voice but cannot change it. Anything the run could
+                       not do stops the launch before the run exists. The full
+                       flow is in the exodus-video skill.
   --auto-approve       (run) Send this ONE run off unattended: every Checkpoint it
                        reaches is approved for you, exactly as it stands, and the
                        run records that nobody looked. Without it a Checkpoint
@@ -145,6 +163,20 @@ Fill every required input. For a free-text brief you can compose a **bespoke bri
 
 **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 `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 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:
+
+```
+Format rules: Ensemble Talking Head, version ensemble-e1-provisional-2026-07 (from the "rig_1" Rig box).
+```
+
+`workflow status` says the same line later, and `video pull` writes the same facts into `manifest.json` under `provenance`. Nothing prints the rules themselves — they are the house's, not the brand's — only whose they were and which version ran.
+
+Three things to know before you wire one:
+
+- **One run, one rulebook.** If any Rig box's rig carries rules, every Rig box in the workflow has to point at that same saved rig. A second box on a different rig, or a box with its knobs set in place, refuses the launch with a sentence naming every box. Nothing is spent.
+- **Some rulebooks aren't released yet.** A rig that is still being built refuses a member's launch and names itself. Only an admin can start a run on one. Duplicating that rig doesn't get around it — the copy still reads the original's rules, so the answer is the same.
+- **The rig's video model is advice, not a change.** When the rig is normally filmed with a different video model than the one your Video step is set to, the receipt says so in one line and the run uses YOUR setting. Change the Video step yourself if you want the rig's.
+
 For an **`asset` (file) input, pass the path to a local file** and the CLI does the uploading for you — mint, push the bytes, register, then start the run with the stored asset:
 
 ```bash

package/dist/commands/video.d.ts

@@ -1,5 +1,6 @@
 import { type ApiResponse } from "../lib/client.js";
 import type { FlagOccurrence } from "../lib/args.js";
+import { type RunProvenance } from "./workflow.js";
 export declare const helpText: string;
 export declare const VOICES_PATH = "/api/v2/video/voices";
 export interface ClipWord {
@@ -100,6 +101,7 @@ export interface VideoRun {
     pausedNodeId?: string;
     nodes: VideoRunNode[];
     castLock?: PullCastLock | null;
+    provenance?: RunProvenance;
     workflowId?: string;
     moduleOwned?: boolean;
 }
@@ -225,6 +227,7 @@ export interface ManifestCastRef {
     error: string | null;
     voiceId: string | null;
     voiceLabel: string | null;
+    voiceDescription: string | null;
 }
 export interface VideoManifest {
     runId: string;
@@ -240,6 +243,7 @@ export interface VideoManifest {
     } | null;
     scenes: ManifestScene[];
     failed: PullFailure[];
+    provenance?: RunProvenance;
 }
 export declare const CAST_LEDGER_BASE = 910000;
 export interface PullPlan {
@@ -314,6 +318,7 @@ export interface CastVoiceRow {
         state: "not-checked";
         why: string;
     };
+    description?: string;
     spokenScenes: number;
     spokenSeconds: number;
 }
@@ -327,6 +332,9 @@ export interface CastVoiceSheet {
         label?: string;
     } | null;
     treatment: {
+        kind?: string;
+        path?: string | null;
+        usesElevenLabs?: boolean;
         summary: string;
         provider: string;
         model: string;

package/dist/commands/video.js

@@ -407,10 +407,15 @@ function castVoicePins(artifact) {
     for (const member of cast) {
         const characterId = typeof member.characterId === "string" ? member.characterId.trim() : "";
         const voiceId = typeof member.voiceId === "string" ? member.voiceId.trim() : "";
-        if (!characterId || !voiceId)
+        const description = typeof member.voiceDescription === "string" ? member.voiceDescription.trim() : "";
+        if (!characterId || (!voiceId && !description))
             continue;
         const label = typeof member.voiceLabel === "string" ? member.voiceLabel.trim() : "";
-        pins.set(characterId, { voiceId, voiceLabel: label ? label : null });
+        pins.set(characterId, {
+            voiceId: voiceId ? voiceId : null,
+            voiceLabel: voiceId && label ? label : null,
+            voiceDescription: description ? description : null,
+        });
     }
     return pins;
 }
@@ -487,6 +492,7 @@ function planCastRefs(run, items, pins) {
             error: row.error,
             voiceId: pin?.voiceId ?? null,
             voiceLabel: pin?.voiceLabel ?? null,
+            voiceDescription: pin?.voiceDescription ?? null,
         });
         if (file && row.url)
             downloads.push({ file, url: row.url });
@@ -701,6 +707,9 @@ export function planPull(run, items, opts) {
                 : null,
             scenes,
             failed: [],
+            ...(run.provenance?.format || run.provenance?.voice
+                ? { provenance: run.provenance }
+                : {}),
         },
     };
 }
@@ -1500,7 +1509,7 @@ export async function voicesFlow(runId, voices, json, deps) {
 }
 function availabilityWords(row) {
     if (!row.voice)
-        return "no voice yet";
+        return row.description ? "voice written below" : "no voice yet";
     switch (row.availability?.state) {
         case "available":
             return "ElevenLabs has it";
@@ -1534,12 +1543,17 @@ function voiceSummaryLines(cast, notices) {
 }
 export function voiceSheetLines(sheet) {
     const lines = [`Voices for run ${sheet.runId}`];
+    if (typeof sheet.treatment.path === "string" && sheet.treatment.path !== "") {
+        lines.push(`  Treatment: ${sheet.treatment.path}`);
+    }
     if (sheet.cast.length === 0)
         lines.push("  Nobody is in this ad yet.");
     for (const row of sheet.cast) {
         const voice = voiceWords(row);
         lines.push(`  ${row.characterId}  ${row.name}  ${voice}  ${availabilityWords(row)}  ` +
             `speaks in ${row.spokenScenes} scenes, about ${row.spokenSeconds}s`);
+        if (row.description)
+            lines.push(`      written voice: ${row.description}`);
     }
     if (sheet.narrator) {
         const label = sheet.narrator.label ? `${sheet.narrator.label} ` : "";
@@ -1551,9 +1565,16 @@ export function voiceSheetLines(sheet) {
             : "Nothing changed — those voices were already set. Pictures and script were not touched.");
     }
     lines.push(`How voices are applied: ${sheet.treatment.summary}${sheet.treatment.speedChange ? "" : " No speed change."}`);
-    lines.push(`Cost: billed to your own ElevenLabs key. ${sheet.treatment.costNote} ` +
-        `About ${sheet.treatment.usage.seconds} seconds of speech across ` +
-        `${sheet.treatment.usage.clips} clips will be converted.`);
+    const rendersOwnVoice = sheet.treatment.kind === "render-owns-voice";
+    if (!rendersOwnVoice || sheet.treatment.usesElevenLabs === undefined) {
+        lines.push(`Cost: billed to your own ElevenLabs key. ${sheet.treatment.costNote} ` +
+            `About ${sheet.treatment.usage.seconds} seconds of speech across ` +
+            `${sheet.treatment.usage.clips} clips will be converted.`);
+    }
+    else if (sheet.treatment.usesElevenLabs) {
+        lines.push("Cost: the narration on this run is voiced by ElevenLabs and billed to your own key. " +
+            `${sheet.treatment.costNote} The clips themselves are not converted.`);
+    }
     for (const notice of sheet.notices)
         lines.push(notice);
     lines.push(sheet.canChange

package/dist/commands/workflow.d.ts

@@ -290,6 +290,11 @@ export interface WorkflowRunOutput {
     durationSec?: number;
     sceneIndex?: number;
     final?: boolean;
+    words?: Array<{
+        w: string;
+        s: number;
+        e: number;
+    }>;
     frames?: Array<{
         sceneIndex: number;
         imageUrl?: string;
@@ -347,6 +352,36 @@ export interface WorkflowPendingSlot {
     value?: string;
     hint?: string;
 }
+export interface RunFormatProvenance {
+    via: "show" | "rig-node";
+    nodeId?: string;
+    rigId: string;
+    rigName: string;
+    rulesFrom?: {
+        rigId: string;
+        rigName: string;
+    };
+    specVersion: string | null;
+}
+export type VoicePath = "sts-revoice" | "lipsync-retarget" | "native-prompt" | "omni-audio-ids" | "gemini-direct";
+export type RunVoiceProvenance = {
+    source: "show";
+    path: VoicePath;
+} | {
+    source: "launch";
+    path: VoicePath;
+    descriptions: {
+        speaker: string;
+        description: string;
+    }[];
+} | {
+    source: "unreadable";
+};
+export interface RunProvenance {
+    format: RunFormatProvenance | null;
+    voice: RunVoiceProvenance | null;
+}
+export declare function formatRulesLine(provenance: unknown): string | undefined;
 export interface WorkflowRun {
     _id: string;
     workflowId: string;
@@ -372,6 +407,7 @@ export interface WorkflowRun {
         nodeId: string;
         approvedAt: number;
     }[];
+    provenance?: RunProvenance;
 }
 export type WorkflowRunProjection = Omit<WorkflowRun, "nodes"> & {
     nodes?: never;
@@ -410,6 +446,7 @@ interface RunFlowOptions {
     autoApprove?: boolean;
     imageRigOverrides?: Record<string, unknown>;
     voices?: VoiceMap;
+    voiceTreatment?: VoiceTreatmentBody;
     wait: boolean;
     json: boolean;
     out?: string;
@@ -431,6 +468,11 @@ export declare function rejectTerminalFlag(occurrences: FlagOccurrence[]): void;
 export declare function parseAutoApproveFlag(args: string[]): boolean;
 export declare function parseRigOverridesFlag(occurrences: FlagOccurrence[], readFile?: (path: string) => string): Record<string, unknown> | undefined;
 export declare function parseVoicesFlag(occurrences: FlagOccurrence[], readFile?: (path: string) => string): VoiceMap | undefined;
+export interface VoiceTreatmentBody {
+    path: string;
+    describe?: Record<string, string>;
+}
+export declare function parseVoiceTreatmentFlag(occurrences: FlagOccurrence[], readFile?: (path: string) => string): VoiceTreatmentBody | undefined;
 export declare function parseFillFlag(occurrences: FlagOccurrence[]): string | undefined;
 export declare function formatWorkflowList(workflows: WorkflowListItem[]): string;
 export declare function formatRecentRuns(runs: WorkflowRunProjection[]): string;
@@ -464,6 +506,7 @@ export declare function botsFlow(opts: {
     slug?: string;
     json: boolean;
 }, deps: WorkflowRunDeps): Promise<FlowResult>;
+export declare function voiceTreatmentLine(provenance: unknown): string | undefined;
 export declare function runFlow(workflowRef: string, opts: RunFlowOptions, deps: WorkflowRunDeps): Promise<FlowResult>;
 export declare function statusFlow(opts: {
     id?: string;

package/dist/commands/workflow.js

@@ -20,7 +20,7 @@ Usage:
   exodus workflow templates [list] [--json]
   exodus workflow templates export <key> [--out <file>] [--json]
   exodus workflow schema [--kind <kind>] [--face <face>] [--json]
-  exodus workflow run <workflowId|name> [--fill <name>] [--input key=value ...] [--input <fileField>=<path> ...] [--rig-overrides <json|@file>] [--voices <json|@voices.json>] [--auto-approve] [--wait] [--out <dir>] [--json]
+  exodus workflow run <workflowId|name> [--fill <name>] [--input key=value ...] [--input <fileField>=<path> ...] [--rig-overrides <json|@file>] [--voices <json|@voices.json>] [--voice-treatment <name|json|@file>] [--auto-approve] [--wait] [--out <dir>] [--json]
   exodus workflow status [--json]
   exodus workflow status --id <runId> [--out <dir>] [--json]
   exodus workflow cancel <runId> [--reason "..."] [--json]
@@ -102,6 +102,29 @@ Flags:
                          <run>" at the storyboard review instead. Voice ids
                          belong to the brand's own folder — never put them in a
                          shared workflow or template.
+  --voice-treatment <v>  (run) Say HOW this run makes its voices. Two kinds of
+                         answer. A name on its own picks a way of working that
+                         uses voices you already have:
+                           --voice-treatment sts-revoice
+                           --voice-treatment lipsync-retarget --voices @voices.json
+                         The other kind has the video model speak the lines
+                         itself, in a voice you WRITE instead of one you pick.
+                         Those need a description for every speaker in your
+                         script, so they take a JSON object, or @path to a .json
+                         file holding one:
+                           --voice-treatment @voice-treatment.json
+                           --voice-treatment '{"path":"native-prompt","describe":{"HOST 1":"Dry, tired baritone."}}'
+                         Written voices and --voices are never used together:
+                         the video model owns the voice on those runs, so
+                         ElevenLabs voices would be paid for and never heard,
+                         and asking for both stops the launch. Anything the run
+                         could not actually do — a treatment this stack has not
+                         switched on, a Video step on a model that cannot do it,
+                         a missing key, a rig that shows every line as on-screen
+                         text — stops the launch before the run is created, and
+                         the message says which. Descriptions are chosen HERE,
+                         at the start: "exodus video voices <run>" shows them at
+                         the review but cannot change them.
   --auto-approve         (run) Deliberately unattended launch: every Checkpoint
                          box this run stops at is approved automatically, with
                          whatever it was holding left exactly as it is, and the
@@ -194,6 +217,7 @@ Examples:
   exodus workflow run "Product Shots" --rig-overrides '{"rig_1":{"lines":{"line_1":{"count":3}}}}'
   exodus workflow run "Product Shots" --rig-overrides @rig.json --wait
   exodus workflow run "Podcast Ad" --input script=@script.txt --voices @voices.json --wait
+  exodus workflow run "Podcast Ad" --input script=@script.txt --voice-treatment @voice-treatment.json --wait
   exodus workflow run "Launch Flow" --wait --out ./deliverables
   exodus workflow status                      # recent runs + their ids
   exodus workflow status --id wr_123
@@ -268,6 +292,20 @@ Notes:
   no speaker names to key on at the start, so it is refused with a pointer at
   the review-time command. Keep voice ids in the brand's own folder, never in a
   shared workflow or template. (#1846)
+  "workflow run --voice-treatment" says HOW a run makes its voices. Some ways of
+  working play a voice you picked (that is today's behaviour, and it still takes
+  --voices); others have the video model speak the CAST's lines itself, in voices
+  you describe in words. A described voice needs one description per speaker,
+  because a speaker nobody described gets a voice the model invents afresh on
+  every clip, and the drift only shows up once the clips are paid for. Written
+  voices and --voices are refused together, since the ElevenLabs voices would
+  never be heard. Everything the run could not do — a way of working this stack
+  has not switched on, a Video step whose model cannot do it, a missing key, a
+  rig that shows every line as on-screen text — stops the launch before the run
+  is created. The ways of working beyond the two shipped ones are switched on
+  only on the test stack while they are being tried out, so a live run refuses
+  them by name. Both the launch receipt and "workflow status" say which way a
+  run took, and "exodus video voices <run>" shows each written voice. (#1869)
   workflow triggers are addressed by 1-based position — a trigger carries no id,
   so the CLI reads the live list from the export contract and sends a fingerprint
   of the trigger's fields as the guard; a concurrent edit fails loud rather than
@@ -310,6 +348,24 @@ Notes:
   ids it wants). The "gate" verbs retired in 2.0 along with the Gate node — the
   command now prints a pointer at "checkpoint" and exits 1.
 `.trim();
+export function formatRulesLine(provenance) {
+    const format = provenance?.format;
+    if (!format || typeof format !== "object")
+        return undefined;
+    const { rigName, specVersion, nodeId, rulesFrom } = format;
+    if (typeof rigName !== "string" || rigName === "")
+        return undefined;
+    const version = typeof specVersion === "string" && specVersion !== ""
+        ? `, version ${specVersion}`
+        : "";
+    const where = typeof nodeId === "string" && nodeId !== ""
+        ? ` (from the "${nodeId}" Rig box)`
+        : " (from the Show's rig)";
+    const borrowed = rulesFrom && typeof rulesFrom.rigName === "string"
+        ? ` The rules come from "${rulesFrom.rigName}".`
+        : "";
+    return `Format rules: ${rigName}${version}${where}.${borrowed}`;
+}
 const LIST_PATH = "/api/v2/workflows";
 const RUN_PATH = "/api/v2/workflows/run";
 const STATUS_PATH = "/api/v2/workflow";
@@ -354,6 +410,7 @@ const VALUE_FLAGS = new Set([
     "reject",
     "rig-overrides",
     "voices",
+    "voice-treatment",
     "note",
 ]);
 function defaultMkdirp(dir) {
@@ -976,6 +1033,57 @@ export function parseVoicesFlag(occurrences, readFile) {
     }
     return parsed;
 }
+export function parseVoiceTreatmentFlag(occurrences, readFile) {
+    const usage = "--voice-treatment requires a treatment name, JSON, or @path/to/voice-treatment.json";
+    let raw;
+    for (const { flag, value } of occurrences) {
+        if (flag !== "voice-treatment")
+            continue;
+        if (value === undefined || value.startsWith("--"))
+            throw new Error(usage);
+        raw = value;
+    }
+    if (raw === undefined)
+        return undefined;
+    let text = raw.trim();
+    if (!text)
+        throw new Error(usage);
+    let fromFile = false;
+    if (text.startsWith("@@")) {
+        text = text.slice(1);
+    }
+    else if (text.startsWith("@")) {
+        const filePath = text.slice(1);
+        if (!filePath) {
+            throw new Error("--voice-treatment @<file> needs a file path after \"@\"");
+        }
+        if (!readFile) {
+            throw new Error(`--voice-treatment: cannot load @${filePath} here (no file access)`);
+        }
+        try {
+            text = readFile(filePath);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`--voice-treatment: could not read file "${filePath}": ${msg}`);
+        }
+        fromFile = true;
+    }
+    if (!fromFile && !text.startsWith("{"))
+        return { path: text };
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`--voice-treatment is not valid JSON: ${msg}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error('--voice-treatment must be a treatment name, or a JSON object like {"path":"native-prompt","describe":{"HOST 1":"..."}}');
+    }
+    return parsed;
+}
 export function parseFillFlag(occurrences) {
     let name;
     for (const { flag, value } of occurrences) {
@@ -1095,6 +1203,12 @@ export function formatWorkflowRun(run) {
     lines.push(`status:       ${runVerdict(run)}${counts ? ` (${counts})` : ""}`);
     if (run.isTerminal)
         lines.push("terminal:     yes");
+    const rulesLine = formatRulesLine(run.provenance);
+    if (rulesLine)
+        lines.push(rulesLine);
+    const treatmentLine = voiceTreatmentLine(run.provenance);
+    if (treatmentLine)
+        lines.push(treatmentLine);
     if (run.error)
         lines.push(`error:        ${run.error}`);
     if (Object.keys(run.inputs ?? {}).length > 0) {
@@ -1786,6 +1900,23 @@ function launchVoicesLine(attached) {
     }
     return said.length > 0 ? `Voices: ${said.join(", ")}` : undefined;
 }
+export function voiceTreatmentLine(provenance) {
+    const voice = provenance?.voice;
+    if (!voice || typeof voice !== "object")
+        return undefined;
+    if (voice.source === "unreadable") {
+        return ("Voice treatment: the setting saved when this run started cannot be read, so no " +
+            "clip will be made. Start the run again.");
+    }
+    const path = voice.path;
+    if (typeof path !== "string" || path === "")
+        return undefined;
+    const where = voice.source === "show" ? "from its Show" : "chosen at launch";
+    const described = voice.source === "launch" && Array.isArray(voice.descriptions) && voice.descriptions.length > 0
+        ? `. Written voices: ${voice.descriptions.map((d) => d.speaker).join(", ")}`
+        : "";
+    return `Voice treatment: ${path} (${where})${described}`;
+}
 export async function runFlow(workflowRef, opts, deps) {
     let workflowId;
     try {
@@ -1829,6 +1960,7 @@ export async function runFlow(workflowRef, opts, deps) {
         ...(opts.autoApprove === true ? { autoApprove: true } : {}),
         ...(opts.imageRigOverrides ? { imageRigOverrides: opts.imageRigOverrides } : {}),
         ...(opts.voices ? { voices: opts.voices } : {}),
+        ...(opts.voiceTreatment ? { voiceTreatment: opts.voiceTreatment } : {}),
         launchedVia: "cli",
     };
     const start = await deps.post(RUN_PATH, body);
@@ -1843,6 +1975,12 @@ export async function runFlow(workflowRef, opts, deps) {
     if (opts.json && !opts.wait)
         return { code: 0, lines: [JSON.stringify(base)] };
     const voicesLine = launchVoicesLine(data?.launchVoices);
+    const provenance = { format: data?.format ?? null, voice: data?.voice ?? null };
+    const rulesLine = formatRulesLine(provenance);
+    const treatmentLine = voiceTreatmentLine(provenance);
+    const advisories = Array.isArray(data?.advisories)
+        ? data.advisories.filter((line) => typeof line === "string")
+        : [];
     const lines = opts.json
         ? []
         : [
@@ -1850,7 +1988,10 @@ export async function runFlow(workflowRef, opts, deps) {
             "Workflow run started.",
             `runId:        ${data.runId}`,
             `triggerRunId: ${data.triggerRunId}`,
+            ...(rulesLine ? [rulesLine] : []),
+            ...advisories,
             ...(voicesLine ? [voicesLine] : []),
+            ...(treatmentLine ? [treatmentLine] : []),
             `Poll: exodus workflow status --id ${data.runId}`,
         ];
     if (!opts.wait) {
@@ -2957,7 +3098,7 @@ export async function run(flags, occurrences) {
         const workflowRef = rest[0];
         if (!workflowRef) {
             console.error("Error: workflow run requires <workflowId|name>.");
-            console.log("Usage: exodus workflow run <workflowId|name> [--fill <name>] [--input key=value ...] [--input <fileField>=./path/to/file ...] [--rig-overrides <json|@file>] [--voices <json|@voices.json>] [--auto-approve] [--wait] [--json]");
+            console.log("Usage: exodus workflow run <workflowId|name> [--fill <name>] [--input key=value ...] [--input <fileField>=./path/to/file ...] [--rig-overrides <json|@file>] [--voices <json|@voices.json>] [--voice-treatment <name|json|@file>] [--auto-approve] [--wait] [--json]");
             process.exit(1);
         }
         let inputs;
@@ -2965,6 +3106,7 @@ export async function run(flags, occurrences) {
         let autoApprove;
         let imageRigOverrides;
         let voices;
+        let voiceTreatment;
         try {
             inputs = parseRawInputFlags(occurrences);
             rejectTerminalFlag(occurrences);
@@ -2972,6 +3114,7 @@ export async function run(flags, occurrences) {
             autoApprove = parseAutoApproveFlag(process.argv.slice(3));
             imageRigOverrides = parseRigOverridesFlag(occurrences, defaultDeps.readFile);
             voices = parseVoicesFlag(occurrences, defaultDeps.readFile);
+            voiceTreatment = parseVoiceTreatmentFlag(occurrences, defaultDeps.readFile);
         }
         catch (e) {
             console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
@@ -2983,6 +3126,7 @@ export async function run(flags, occurrences) {
             autoApprove,
             imageRigOverrides,
             voices,
+            voiceTreatment,
             wait: flags["wait"] === true,
             json,
             out: flagString(flags, "out"),

package/package.json

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