@aicopycoders/exodus 2026.9.1100-beta.0 → 2026.9.1100-beta.1

package/assets/docs/CLAUDE.md

@@ -61,6 +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 Show: start a run from a script, read and approve the storyboard, `npx @aicopycoders/exodus video pull` every piece (per-scene clips, voices, keyframes, word timings, music bed) plus a manifest, cut them with the bundled first-cut script, 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) |
 | **Ads** | `exodus-ads` | Read your own live Meta ads once the account is connected on the dashboard — `npx @aicopycoders/exodus ads list` (sort by cost per result, spend or CTR), `ads show <adId>` (copy, both windows, media links, comment counts), `npx @aicopycoders/exodus comments list` (already commenter-redacted), and `npx @aicopycoders/exodus winners definition` (what this brand means by a winner). Read-only; no Meta login or MCP needed. |

package/assets/docs/PIPELINES.md

@@ -16,6 +16,7 @@ In Claude Code you don't click buttons. You say **"exodus"** plus what you want
 | exodus-meme | Meme Ad Generator — recommend formats, one batched server-side run |
 | exodus-workflow | Run/build saved multi-node workflows, resolve inbox gate/repair parks, continue sessions, fire triggers, read banks + promote winners |
 | exodus-hooks | Read the Scout library of hook cards — composable filters, one-card detail, pattern matches, CSV export (read-only) |
+| exodus-video | Make a video ad from a Show — start, storyboard gate, pull every piece + manifest, first cut, upload, approve (admin-only) |
 | exodus-browse | View History and Surface the Right Run |
 | exodus-drive | Google Drive, Docs, Sheets via the Dashboard's OAuth |
 | exodus-winners | Mine your own Meta ad account for winners (needs the Meta Ads MCP) and import them into Exodus |
@@ -222,6 +223,27 @@ Returns: a table, --json data, or an exported CSV/JSON file
 
 ---
 
+## exodus-video
+
+**What it does:** Makes a video ad from a locked Show, in pieces. The run writes the storyboard, draws a picture per scene, records a voice per scene, renders a clip per scene and composes a music bed, then parks for a cut. The CLI pulls the pieces to a folder with a `manifest.json`, the bundled script makes a plain cut, and the upload attaches it for approval. Admin-only.
+
+```operator-guide
+Commands:
+  exodus video shows [--json]                                          Shows and whether each is ready
+  exodus video start --show <id> --script <file> [--wait] [--json]     start an ad run; --wait parks at the storyboard gate
+  exodus video storyboard <runId> [--json]                             the scene cards
+  exodus video approve <runId> [--json]                                approve the storyboard, or the uploaded cut
+  exodus video flag <runId> --note "<what is wrong>" [--json]          send the storyboard back
+  exodus video status <runId> [--json]                                 the park and each scene's clip/voice/picture
+  exodus video pull <runId> --out <dir> [--json]                       every piece + manifest.json
+  exodus video upload <runId> --file <cut.mp4> [--duration <s>] [--json]   attach the cut (MP4/MOV/WebM, 200 MB)
+Cut:
+  node .claude/skills/exodus-video/scripts/first-cut.mjs <dir> [--skip n,m] [--no-music] [--out f]
+Returns: park lines with the exact next command; pull writes files + manifest.json
+```
+
+---
+
 ## exodus-browse
 
 **What it does:** View past pipeline runs and pull outputs from previous sessions.

package/assets/skills/exodus/SKILL.md

@@ -25,6 +25,7 @@ This skill ROUTES. Read what the user wants, name the destination skill, and han
 | Onboard a new brand / build the primer | `exodus-primer` (with winning ads) or `exodus-foundation` (no ads yet) |
 | List/switch/troubleshoot brands | `exodus-brand` |
 | Read the Scout hook library — "what do my 15×+ hooks have in common", "show me my Spanish on-screen hooks", "why did that reel score 22×", "export my hooks to a spreadsheet" | `exodus-hooks` (read-only; promoting a card is a dashboard act) |
+| Make a video ad, or anything about a Show or a video run — "start a video ad from this script", "is my video run done", "pull the clips and cut them", "upload my cut", "what's wrong with scene 3" (`exodus video`) | `exodus-video` (admin-only on the dashboard; it drives start → storyboard → pull → cut → upload) |
 | See past runs / find an output | `exodus-browse` |
 | Open or create Google Docs/Sheets | `exodus-drive` |
 | Read their OWN live Meta ads and their numbers — "what are my cheapest ads", "where is my spend going", "show me that ad", "what are people saying in the comments on my ads" (`exodus ads` / `exodus comments`) | `exodus-ads` (read-only; already synced by the dashboard, no Meta MCP needed) |

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

@@ -0,0 +1,233 @@
+---
+name: exodus-video
+description: Make a video ad with Exodus from the terminal. Start an ad from a Show, read and approve its storyboard, pull every finished piece (per-scene clips, voice tracks, keyframes, word timings, the music bed) to a folder, cut them into one video, and upload the cut back for approval, all through the `npx @aicopycoders/exodus video` command family. Use it whenever the user has invoked Exodus and wants anything to do with a video ad, a Show, an ad run's clips or storyboard, "pull the pieces", "stitch it together", "make the cut", "upload my cut", or checking on a video run ("exodus, start a video ad from this script", "exodus, is my video run done", "exodus, pull the clips for run X and cut them", "exodus, what's wrong with scene 3", "exodus video status"). Also use it when the user ran an `npx @aicopycoders/exodus video` command or the `exodus` hub skill routed here. Video is admin-only: "video isn't enabled for this key" means either the dashboard user lacks the admin role or the run id is wrong, so check the id and then say so; do not retry. Never claim generic video-editing asks ("edit this mp4", "add captions to my reel") without Exodus context; in shared folders those belong to the user's other tools. Static image ads are `exodus-image`; copy is `exodus-write`.
+---
+
+# Video: make the pieces, cut the ad, hand it back
+
+Exodus makes the PIECES of a video ad, not the finished ad. From a locked Show
+(its cast, rooms and voices, set up on the dashboard) and a script, the run
+writes a storyboard, draws one picture per scene, records one voice track per
+scene, renders one video clip per scene, and composes a music bed. Then it
+parks and waits for a cut. You pull the pieces, cut them into one video with
+ffmpeg, and upload the cut. Approving the cut is what makes it the ad.
+
+Your job in this skill is to drive that loop and to make a sound first cut.
+Editing craft (captions, pacing, b-roll, sound design) is not here yet; a plain,
+correct assembly is the bar.
+
+## Before anything
+
+- `npx @aicopycoders/exodus video --help` is the authoritative flag list. The
+  `video` verb is admin-only and hidden from the top-level `--help`; that is
+  expected, not a broken install.
+- "video isn't enabled for this key" has two causes the CLI cannot tell apart:
+  the dashboard user is not an admin on this brand, or the run id does not
+  exist. Check the id first; if it is right, the user needs the admin role.
+  No flag or retry fixes either.
+- Other failures: `npx @aicopycoders/exodus doctor` first, then follow what it prints.
+- Cutting needs a full `ffmpeg` build with `ffprobe` and the `libx264`
+  encoder on the PATH (`brew install ffmpeg` / `apt install ffmpeg`; the
+  script checks and says so). Check before you pull, so the user is not left
+  with a folder they cannot use.
+- The brand matters: a Show belongs to a brand, so `exodus video shows` lists
+  the active brand's Shows. Wrong list means wrong brand; `exodus brand use <slug>`.
+
+## The loop
+
+Run each line as `npx @aicopycoders/exodus video …`; `exodus` below is shorthand.
+
+```operator-guide
+exodus video shows                                        which Shows are ready
+exodus video start --show <id> --script script.txt --wait  start, wait for the storyboard gate
+exodus video storyboard <runId>                           read the scene cards
+exodus video approve <runId>                              keep going
+exodus video flag <runId> --note "what's wrong"           or send it back
+exodus video status <runId>                               where it is, per scene
+exodus video pull <runId> --out ./ad-<runId>              every piece + manifest.json
+node .claude/skills/exodus-video/scripts/first-cut.mjs ./ad-<runId>   a plain cut (path from the workspace root)
+exodus video upload <runId> --file ./ad-<runId>/cut.mp4   attach it
+exodus video approve <runId>                              make it the ad
+```
+
+Every command takes `--json`. Read `--json` when you need to decide something
+from the output; read the plain form when you are relaying it to the user.
+
+**Where a run can stop.** `start --wait` is silent while it polls, then prints
+the stage lines and the stop in one burst. Five stops, each with the exact next
+command printed under it:
+
+- storyboard gate: needs `approve` or `flag`.
+- final watch: every piece is made; needs `pull`, a cut, and `upload`.
+- paused: a builder checkpoint the CLI cannot resolve; open the run's page.
+- failed: the run's error is printed and the command exits 1; `status` shows
+  how far it got. Tell the user; do not start another run on your own.
+- finished: pull what it made.
+
+`status` prints the same stop lines any time, so an agent that lost the
+`--wait` terminal picks up from `status` alone. `--wait` gives up after 60
+minutes with "Still running after 60 minutes" and exit 0; that is not done,
+so check `status` before treating it as finished. Do not poll `status` in a
+tight loop; a full run is several minutes.
+
+**What costs money.** `start` creates the run and the storyboard. Approving
+the storyboard is the cost gate: it releases the paid rendering of every
+picture, voice and clip. `shows`, `status`, `storyboard` and `pull` are free
+reads; run them as often as you like. Never start a second run to "retry"
+without the user asking; flag the storyboard or tell them what failed instead.
+
+## The script file
+
+Plain text. A `CAST:` block that names the speakers exactly as the Show locked
+them, one line per turn, then a `CTA:` block. Keep each turn near 14 words so
+a clip stays near 6 seconds. If a line does get truncated in its clip, the
+manifest says so (`speech-cutoff`).
+
+```
+CAST:
+THE EYES — a pair of tired cartoon eyeballs who stare at screens all day
+THE SOFTGEL — a cheerful little capsule who knows how to fix that
+
+THE EYES: Ten hours of screens today. Everything looks blurry and dry.
+THE SOFTGEL: That's screen strain. Your eyes are begging for a break.
+
+CTA:
+THE SOFTGEL: Tap below and give your eyes ClearBlink.
+```
+
+## Reading the storyboard gate
+
+`storyboard <runId>` prints one card per scene: who speaks, the line, the
+planned duration, and whether its picture is drawn. Read it for the user, then
+ask one question: approve, or flag with a note. A flag note is read by the
+model that rewrites the storyboard, so make it concrete ("scene 2 should be a
+close-up of the softgel, not the eyes"). Do not approve on the user's behalf
+unless they told you to run the whole loop unattended.
+
+## What `pull` writes, and what the manifest means
+
+`pull` writes a flat folder and a `manifest.json` that indexes it. The manifest
+is the data you decide from; the filenames are its values. Scene numbers are
+the run's own (they start at 1; scene 0 in `status` is the reference still).
+
+```
+storyboard.json          scene text, order, planned durations, cast looks
+reference.<ext>          the reference still the pictures were drawn from
+scene-NN.keyframe.<ext>  the picture for scene NN
+scene-NN.voice.<ext>     the voice track for scene NN, when one was delivered
+                         (a Show whose voices live inside the clips delivers none)
+scene-NN.<ext>           the clip for scene NN, usually .mp4, voice included
+scene-NN.words.json      [{w, s, e}] word timings inside that clip, for captions
+music.<ext>              the music bed, composed to the clips' total length
+manifest.json            the index below
+```
+
+`manifest.json`:
+
+```
+runId, pulledAt, dashboardUrl        the run and its page
+storyboard, reference, music         filenames, or null when not delivered
+scenes[]                             one per scene, in order
+  sceneIndex, durationSec            the run's number and the clip's real length
+  clip, voice, keyframe, words       filenames, or null
+  clipStatus                         done | failed | running | pending | missing
+  error                              why the clip failed, when it did
+  flagged, findings[]                QC verdict: {check, code, severity: fail|warn, detail}
+  qc                                 {verdict, attempts} from the renderer
+failed[]                             files that did not download: {file, url, error}
+```
+
+How to read it before cutting:
+
+- `clipStatus: "done"` and a `clip` filename: the scene is cuttable.
+- `flagged: true` is a warning, not a block. The clip was delivered anyway; the
+  findings say what the QC model saw (`wrong-character`, `eyeline-off`,
+  `set-drift`, `speech-cutoff`, `framing-off`). Tell the user which scenes are
+  flagged and why, and let them decide whether to keep, trim, or drop each one.
+  A `speech-cutoff` on the CTA scene is the one to worry about; the ad's last
+  words are missing.
+- `clipStatus: "failed"` or `"missing"` with a `keyframe`: `durationSec` is
+  null (it comes from the clip), but the scene can still hold its place as a
+  still picture for the length of its voice track, or the storyboard's planned
+  duration when there is no voice. The first-cut script does this by itself.
+- `clipStatus: "running"` or `"pending"`: pull again later. `status` says when
+  the run parks at the final watch, which means nothing is still rendering.
+- `failed[]` non-empty: run the same `pull` again. It fetches every file again
+  and overwrites, so nothing is lost; the new manifest says what still failed.
+
+## Making the first cut
+
+Use the bundled script. It reads the manifest, puts every A-roll scene in order
+as the spine, lays each cutaway over the spine at the moment its line is spoken,
+normalizes everything to 1080x1920 at 24 fps, fills a silent clip with the
+scene's voice track, lays the music bed underneath at a low level, and writes one
+MP4 with faststart for upload. The path is from the workspace root; from a brand
+subfolder, prefix `../`:
+
+```
+node .claude/skills/exodus-video/scripts/first-cut.mjs ./ad-<runId>
+node .claude/skills/exodus-video/scripts/first-cut.mjs ./ad-<runId> --skip 2,5 --no-music --out ./v2.mp4
+```
+
+It prints what went in, what was left out and why, and the upload command.
+Reach for raw ffmpeg only when the user wants something the script does not do
+(a trim, a reorder, a different aspect). When you do, keep the script's output
+contract: H.264 + AAC in an MP4, an even-sized frame, `-movflags +faststart`.
+
+### The word times that come out with the cut
+
+Nothing burns captions into the video. Captions belong in post, in whatever tool
+the editor uses, so the script hands those tools the timings instead. Beside the
+MP4 it writes two files named from the same basename. `cut.words.json` is every
+spoken word of the finished ad with its start and end in seconds. `cut.srt` is
+the same words grouped into short subtitle lines. `--out v2.mp4` names them
+`v2.words.json` and `v2.srt`.
+
+The times are on the finished ad's timeline, so a word's time is where you hear
+it in the MP4. Cutaways contribute nothing, because their audio never plays. A
+scene that came with no word times leaves a gap, and the report names it. When no
+scene delivered word times the script writes neither file and says so. Tell the
+user the two files exist and that they are what the editor imports for captions.
+
+### Where a cutaway lands
+
+The storyboard marks some scenes `kind: "cutaway"` and gives each one a
+`cueLineId`, the script line the cutaway belongs to. A cutaway is a picture-only
+takeover. It replaces the picture for its own length while the spoken track
+underneath keeps running, so it never takes a place in the running order and
+never adds audio. That is why the cut is as long as the A-roll scenes alone. A
+cutaway is cut short where the next cutaway starts or where the ad ends, and
+the report says so.
+
+The script places each cutaway at the real time its cued line is spoken. It
+finds the A-roll scene whose `lineIds` hold the cue line, counts the words of
+the lines spoken before it in that scene, and reads that word's start time out
+of `scene-NN.words.json`. When the scene has no word times, it falls back to a
+proportion, the share of the scene's words that come before the cue line scaled
+to the scene's real length. The proportion is an estimate and can land a beat
+early or late, so the report names which of the two methods placed each cutaway.
+
+A cutaway whose cue line is spoken by no scene in the cut cannot be placed, so
+the script leaves it out and says so. Skipping the A-roll scene that speaks the
+cue line does that, and so does a storyboard that never claims the line.
+
+Before uploading, look at what you made: `ffprobe -v error -show_entries
+format=duration -of default=nw=1:nk=1 cut.mp4` should be close to the sum of
+the scene durations you kept. A cut that is a few seconds long when five clips
+went in means a filter dropped inputs; do not upload it.
+
+## Uploading and approving
+
+`upload <runId> --file cut.mp4` accepts MP4, MOV or WebM up to 200 MB. It reads
+the length off the file (MP4 headers, or ffprobe for the rest); when it cannot,
+it says so and you pass `--duration <sec>`.
+It prints the run's page, where the user can watch the cut, and the approve
+command. Approve only when the user has seen the cut or told you to run
+unattended; `approve` marks the cut as the ad and moves the run to delivery.
+
+## Reporting to the user
+
+Lead with where the run is and what it needs from them. Then, when you pulled
+or cut: how many scenes, which are flagged and why in one line each, what you
+left out, the cut's length, and the exact command or link for the next step.
+Never paste the manifest; summarize it.

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

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+// A plain first cut from a folder written by `exodus video pull`: the A-roll
+// scenes in the manifest's order make the spine, each cutaway lays over the
+// spine at the moment its cued line is spoken, the music bed goes underneath,
+// and one MP4 comes out ready to upload.
+//
+//   node first-cut.mjs <pulled-dir> [--out cut.mp4] [--skip 2,5] [--no-music]
+//
+// A scene with a clip contributes the clip. A clip with no audio stream gets
+// the scene's voice track, or silence. A scene with no clip but a keyframe
+// becomes a still for the length of its voice track, else the storyboard's
+// planned duration, with the voice if one was delivered. --skip drops scenes.
+//
+// After the render it writes the whole ad's word times beside the MP4, as
+// <out>.words.json and <out>.srt, for captioning in post.
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const USAGE = "usage: first-cut.mjs <pulled-dir> [--out cut.mp4] [--skip 2,5] [--no-music]";
+const WIDTH = 1080;
+const HEIGHT = 1920;
+const FPS = 24;
+const norm = (label) =>
+  `[${label}]scale=${WIDTH}:${HEIGHT}:force_original_aspect_ratio=decrease,` +
+  `pad=${WIDTH}:${HEIGHT}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${FPS},format=yuv420p`;
+const stereo = "aresample=48000,aformat=channel_layouts=stereo";
+
+/** The word rule the planner sized every line with (scout models.ts wordCount). */
+export function wordCount(text) {
+  const trimmed = (text ?? "").trim();
+  return trimmed ? trimmed.split(/\s+/).length : 0;
+}
+
+export function lineWordCounts(storyboard) {
+  const counts = new Map();
+  for (const line of storyboard?.script ?? []) {
+    if (typeof line?.lineId === "string") counts.set(line.lineId, wordCount(line.text));
+  }
+  return counts;
+}
+
+const CUTAWAY_KINDS = new Set(["cutaway", "insert"]);
+
+export function scenePlans(storyboard) {
+  const plans = new Map();
+  for (const scene of storyboard?.scenes ?? []) {
+    if (typeof scene?.sceneIndex !== "number") continue;
+    plans.set(scene.sceneIndex, {
+      cutaway: CUTAWAY_KINDS.has(scene.kind),
+      lineIds: Array.isArray(scene.lineIds) ? scene.lineIds : [],
+      cueLineId: typeof scene.cueLineId === "string" ? scene.cueLineId : null,
+      durationSec: typeof scene.durationSec === "number" ? scene.durationSec : null,
+    });
+  }
+  return plans;
+}
+
+export function cueOffsetOnSpine(spine, counts, cueLineId) {
+  for (const seg of spine) {
+    const idx = seg.lineIds.indexOf(cueLineId);
+    if (idx === -1) continue;
+    let precedingWords = 0;
+    for (let i = 0; i < idx; i++) precedingWords += counts.get(seg.lineIds[i]) ?? 0;
+    let totalWords = 0;
+    for (const id of seg.lineIds) totalWords += counts.get(id) ?? 0;
+
+    let within = 0;
+    let method = "proportion";
+    if (seg.words && seg.words.length > 0) {
+      within = Math.max(0, seg.words[Math.min(precedingWords, seg.words.length - 1)]?.s ?? 0);
+      method = "words";
+    } else if (totalWords > 0) {
+      within = (precedingWords / totalWords) * seg.seconds;
+    }
+    within = Math.min(within, seg.seconds);
+    return { startSec: seg.startSec + within, method, spineSceneIndex: seg.sceneIndex };
+  }
+  return null;
+}
+
+export function buildTimeline({ manifest, storyboard, skip, probe, exists, readWords }) {
+  const plans = scenePlans(storyboard);
+  const counts = lineWordCounts(storyboard);
+  const spine = [];
+  const cutaways = [];
+  const waiting = [];
+  const dropped = [];
+  let startSec = 0;
+
+  for (const scene of manifest?.scenes ?? []) {
+    const n = scene.sceneIndex;
+    const plan = plans.get(n) ?? { cutaway: false, lineIds: [], cueLineId: null, durationSec: null };
+    if (skip.has(n)) {
+      dropped.push({ n, reason: `scene ${n}: skipped by --skip` });
+      continue;
+    }
+    const nothing = `nothing to cut with (clip ${scene.clipStatus}${scene.error ? `: ${scene.error}` : ""})`;
+
+    if (plan.cutaway) {
+      if (exists(scene.clip)) {
+        waiting.push({
+          sceneIndex: n, source: "clip", file: scene.clip,
+          seconds: probe(scene.clip).seconds, cueLineId: plan.cueLineId,
+        });
+      } else if (exists(scene.keyframe)) {
+        waiting.push({
+          sceneIndex: n, source: "still", file: scene.keyframe,
+          seconds: plan.durationSec ?? 4, cueLineId: plan.cueLineId,
+        });
+      } else {
+        dropped.push({ n, reason: `cutaway ${n}: ${nothing}` });
+      }
+      continue;
+    }
+
+    if (exists(scene.clip)) {
+      const clip = probe(scene.clip);
+      const voice = clip.hasAudio || !exists(scene.voice) ? null : scene.voice;
+      const flag = scene.flagged ? " (flagged)" : "";
+      const silent = clip.hasAudio ? "" : voice ? `, silent clip + ${voice}` : ", silent clip";
+      spine.push({
+        sceneIndex: n, source: "clip", file: scene.clip, seconds: clip.seconds,
+        hasAudio: clip.hasAudio, voice, startSec, lineIds: plan.lineIds,
+        words: readWords(scene.words), note: `${flag}${silent}`,
+      });
+      startSec += clip.seconds;
+      continue;
+    }
+    if (exists(scene.keyframe)) {
+      const voice = exists(scene.voice) ? scene.voice : null;
+      const seconds = voice ? probe(voice).seconds : (plan.durationSec ?? 4);
+      spine.push({
+        sceneIndex: n, source: "still", file: scene.keyframe, seconds,
+        hasAudio: false, voice, startSec, lineIds: plan.lineIds,
+        words: null,
+        note: `${voice ? ` + ${voice}` : ", silent"} (${seconds.toFixed(1)}s, clip ${scene.clipStatus})`,
+      });
+      startSec += seconds;
+      continue;
+    }
+    dropped.push({ n, reason: `scene ${n}: ${nothing}` });
+  }
+
+  for (const c of waiting) {
+    const cue = c.cueLineId ? cueOffsetOnSpine(spine, counts, c.cueLineId) : null;
+    if (!cue) {
+      const why = c.cueLineId
+        ? `${c.cueLineId} is spoken by no scene in the cut`
+        : "the storyboard names no cue line";
+      dropped.push({ n: c.sceneIndex, reason: `cutaway ${c.sceneIndex}: ${why}` });
+      continue;
+    }
+    cutaways.push({ ...c, startSec: cue.startSec, method: cue.method, spineSceneIndex: cue.spineSceneIndex });
+  }
+  cutaways.sort((a, b) => a.startSec - b.startSec);
+  for (let i = 0; i < cutaways.length; i++) {
+    const c = cutaways[i];
+    const next = cutaways[i + 1];
+    const end = Math.min(startSec, next ? next.startSec : Infinity);
+    if (c.startSec + c.seconds > end) {
+      c.seconds = Math.max(0, end - c.startSec);
+      c.cutShortBy = next && end === next.startSec ? `cutaway ${next.sceneIndex} starts` : "the ad ends";
+    }
+  }
+
+  return {
+    spine,
+    cutaways,
+    left: dropped.sort((a, b) => a.n - b.n).map((d) => d.reason),
+  };
+}
+
+function sec(n) {
+  return (Number.isFinite(n) ? Math.max(0, n) : 0).toFixed(3);
+}
+
+export function buildFfmpegArgs(timeline, { resolve, music, out }) {
+  const inputs = [];
+  let count = 0;
+  const addInput = (...args) => {
+    inputs.push(...args);
+    return count++;
+  };
+  const filters = [];
+  const pairs = [];
+
+  for (const seg of timeline.spine) {
+    const i =
+      seg.source === "clip"
+        ? addInput("-i", resolve(seg.file))
+        : addInput("-loop", "1", "-t", String(seg.seconds), "-i", resolve(seg.file));
+    filters.push(`${norm(`${i}:v`)}[v${i}]`);
+    if (seg.hasAudio) {
+      filters.push(`[${i}:a]${stereo}[a${i}]`);
+    } else if (seg.voice) {
+      const v = addInput("-i", resolve(seg.voice));
+      filters.push(`[${v}:a]${stereo},apad,atrim=0:${seg.seconds}[a${i}]`);
+    } else {
+      filters.push(`anullsrc=r=48000:cl=stereo,atrim=0:${seg.seconds}[a${i}]`);
+    }
+    pairs.push(`[v${i}][a${i}]`);
+  }
+
+  // A clip whose audio ends before its video would otherwise end the whole cut
+  // there under -shortest; padding lets the video decide the length.
+  filters.push(`${pairs.join("")}concat=n=${pairs.length}:v=1:a=1[vcat][voicecat]`);
+  filters.push(`[voicecat]apad[voice]`);
+
+  let videoLabel = "vcat";
+  timeline.cutaways.forEach((c, j) => {
+    const i =
+      c.source === "clip"
+        ? addInput("-i", resolve(c.file))
+        : addInput("-loop", "1", "-t", String(c.seconds), "-i", resolve(c.file));
+    const end = c.startSec + c.seconds;
+    filters.push(
+      `${norm(`${i}:v`)},trim=0:${sec(c.seconds)},setpts=PTS-STARTPTS+${sec(c.startSec)}/TB[cv${j}]`,
+    );
+    // eof_action=pass keeps the spine showing once the cutaway's frames end.
+    filters.push(
+      `[${videoLabel}][cv${j}]overlay=enable=between(t\\,${sec(c.startSec)}\\,${sec(end)}):eof_action=pass[ov${j}]`,
+    );
+    videoLabel = `ov${j}`;
+  });
+
+  let audioLabel = "voice";
+  if (music) {
+    const m = addInput("-stream_loop", "-1", "-i", music);
+    filters.push(`[${m}:a]${stereo},volume=0.18[bed]`);
+    filters.push(`[voice][bed]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[mix]`);
+    audioLabel = "mix";
+  }
+
+  return [
+    "-y", "-hide_banner", "-loglevel", "error",
+    ...inputs,
+    "-filter_complex", filters.join(";"),
+    "-map", `[${videoLabel}]`, "-map", `[${audioLabel}]`,
+    "-c:v", "libx264", "-preset", "medium", "-crf", "20", "-r", String(FPS),
+    "-c:a", "aac", "-b:a", "192k",
+    "-movflags", "+faststart", "-shortest",
+    out,
+  ];
+}
+
+export function wordRows(timeline) {
+  const ms = (n) => Math.round(n * 1000) / 1000;
+  const rows = [];
+  for (const seg of timeline.spine) {
+    for (const w of seg.words ?? []) {
+      const text = (w.w ?? "").trim();
+      const start = seg.startSec + w.s;
+      const end = seg.startSec + w.e;
+      if (text && end > start) {
+        rows.push({ text, start: ms(start), end: ms(end), scene: seg.sceneIndex });
+      }
+    }
+  }
+  return rows;
+}
+
+const SRT_MAX_WORDS = 5;
+const SRT_GAP_SEC = 1.0;
+
+export function srtCues(rows) {
+  const cues = [];
+  let cue = [];
+  for (let i = 0; i < rows.length; i++) {
+    cue.push(rows[i]);
+    const next = rows[i + 1];
+    const ends =
+      !next ||
+      /[.!?,;:]$/.test(rows[i].text) ||
+      cue.length >= SRT_MAX_WORDS ||
+      next.scene !== rows[i].scene ||
+      next.start - rows[i].end > SRT_GAP_SEC;
+    if (ends) {
+      cues.push(cue);
+      cue = [];
+    }
+  }
+  return cues;
+}
+
+export function srtTime(seconds) {
+  const ms = Math.max(0, Math.round(seconds * 1000));
+  const pad = (n, width) => String(n).padStart(width, "0");
+  return (
+    `${pad(Math.floor(ms / 3600000), 2)}:${pad(Math.floor(ms / 60000) % 60, 2)}:` +
+    `${pad(Math.floor(ms / 1000) % 60, 2)},${pad(ms % 1000, 3)}`
+  );
+}
+
+export function toSrt(rows) {
+  return srtCues(rows)
+    .map((cue, i) => {
+      const text = cue.map((r) => r.text).join(" ");
+      return `${i + 1}\n${srtTime(cue[0].start)} --> ${srtTime(cue[cue.length - 1].end)}\n${text}\n`;
+    })
+    .join("\n");
+}
+
+export function sidecarPaths(outPath) {
+  const dir = path.dirname(outPath);
+  const base = path.basename(outPath, path.extname(outPath));
+  return { words: path.join(dir, `${base}.words.json`), srt: path.join(dir, `${base}.srt`) };
+}
+
+export function inTheCut(timeline) {
+  const rows = [];
+  for (const seg of timeline.spine) {
+    const label = seg.source === "clip" ? seg.file : `still ${seg.file}`;
+    rows.push({ n: seg.sceneIndex, line: `scene ${seg.sceneIndex}: ${label}${seg.note}` });
+  }
+  for (const c of timeline.cutaways) {
+    const label = c.source === "clip" ? c.file : `still ${c.file}`;
+    const how =
+      c.method === "words"
+        ? "word times"
+        : `proportion: scene ${c.spineSceneIndex} has no word times`;
+    const cut = c.cutShortBy ? `, cut short where ${c.cutShortBy}` : "";
+    rows.push({
+      n: c.sceneIndex,
+      line:
+        `cutaway ${c.sceneIndex}: ${label} at ${c.startSec.toFixed(2)}s for ${c.seconds.toFixed(1)}s, ` +
+        `cued to ${c.cueLineId} in scene ${c.spineSceneIndex} (${how})${cut}`,
+    });
+  }
+  return rows.sort((a, b) => a.n - b.n).map((r) => r.line);
+}
+
+export function noWordTimes(timeline) {
+  const rows = timeline.spine
+    .filter((seg) => !seg.words || seg.words.length === 0)
+    .map((seg) => `scene ${seg.sceneIndex} (no words.json)`);
+  for (const c of timeline.cutaways) rows.push(`scene ${c.sceneIndex} (cutaway)`);
+  return rows;
+}
+
+function fail(code, message) {
+  console.error(message);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const opts = { dir: undefined, out: undefined, skip: new Set(), music: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--out") opts.out = argv[++i];
+    else if (a === "--skip") opts.skip = new Set((argv[++i] ?? "").split(",").filter(Boolean).map(Number));
+    else if (a === "--no-music") opts.music = false;
+    else if (a.startsWith("--")) fail(2, `unknown flag ${a}\n${USAGE}`);
+    else if (opts.dir === undefined) opts.dir = a;
+    else fail(2, `unexpected argument ${a}\n${USAGE}`);
+  }
+  if (!opts.dir) fail(2, USAGE);
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  for (const bin of ["ffmpeg", "ffprobe"]) {
+    if (spawnSync(bin, ["-version"]).status !== 0) {
+      fail(2, `${bin} is not installed. Install ffmpeg (brew install ffmpeg / apt install ffmpeg).`);
+    }
+  }
+  const encoders = spawnSync("ffmpeg", ["-hide_banner", "-encoders"]).stdout?.toString() ?? "";
+  if (!/\blibx264\b/.test(encoders)) {
+    fail(2, "This ffmpeg has no libx264 encoder (H.264). Install a full ffmpeg build: brew install ffmpeg / apt install ffmpeg.");
+  }
+
+  const dir = opts.dir;
+  const manifestPath = path.join(dir, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    fail(2, `${manifestPath} not found. Run: exodus video pull <runId> --out ${dir}`);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const out = path.resolve(opts.out ?? path.join(dir, "cut.mp4"));
+  const here = (file) => path.join(dir, file);
+  const exists = (file) => Boolean(file) && existsSync(here(file));
+
+  const readJson = (file) => {
+    if (!exists(file)) return null;
+    try {
+      return JSON.parse(readFileSync(here(file), "utf8"));
+    } catch {
+      return null;
+    }
+  };
+  const probe = (file) => {
+    const raw = execFileSync("ffprobe", [
+      "-v", "error", "-show_entries", "stream=codec_type:format=duration", "-of", "json", here(file),
+    ]).toString();
+    const info = JSON.parse(raw);
+    return {
+      seconds: Number(info.format?.duration ?? 0),
+      hasAudio: (info.streams ?? []).some((s) => s.codec_type === "audio"),
+    };
+  };
+
+  const storyboard = readJson(manifest.storyboard);
+  if (!storyboard) {
+    console.error(`Warning: ${manifest.storyboard ?? "storyboard.json"} is missing or unreadable, so every scene is cut as A-roll and no cutaway is placed.`);
+  }
+  const timeline = buildTimeline({
+    manifest,
+    storyboard,
+    skip: opts.skip,
+    probe,
+    exists,
+    readWords: (file) => {
+      const rows = readJson(file);
+      return Array.isArray(rows) && rows.length > 0 ? rows : null;
+    },
+  });
+  if (timeline.spine.length === 0) {
+    fail(1, `No scene has a clip or a keyframe. Check: exodus video status ${manifest.runId}`);
+  }
+
+  const music = opts.music && exists(manifest.music) ? manifest.music : null;
+  const ffmpegArgs = buildFfmpegArgs(timeline, {
+    resolve: here,
+    music: music ? here(music) : null,
+    out,
+  });
+  const res = spawnSync("ffmpeg", ffmpegArgs, { stdio: "inherit" });
+  if (res.status !== 0) {
+    const quoted = ffmpegArgs.map((a) => (/[\s\[\];]/.test(a) ? `'${a}'` : a)).join(" ");
+    fail(1, `ffmpeg failed. The command it ran:\n  ffmpeg ${quoted}`);
+  }
+
+  const rows = wordRows(timeline);
+  const sidecars = sidecarPaths(out);
+  if (rows.length > 0) {
+    writeFileSync(sidecars.words, `${JSON.stringify(rows, null, 2)}\n`);
+    writeFileSync(sidecars.srt, toSrt(rows));
+  } else {
+    rmSync(sidecars.words, { force: true });
+    rmSync(sidecars.srt, { force: true });
+  }
+
+  const duration = execFileSync("ffprobe", [
+    "-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", out,
+  ]).toString().trim();
+  console.log(`Wrote ${out} (${Number(duration).toFixed(1)}s, ${WIDTH}x${HEIGHT})`);
+  console.log("In the cut:");
+  for (const line of inTheCut(timeline)) console.log("  " + line);
+  if (timeline.left.length > 0) {
+    console.log("Left out:");
+    for (const line of timeline.left) console.log("  " + line);
+  }
+  if (rows.length > 0) {
+    const scenes = [...new Set(rows.map((r) => r.scene))].join(", ");
+    console.log(
+      `Words: ${rows.length} words from scenes ${scenes} -> ${path.basename(sidecars.words)}, ${path.basename(sidecars.srt)}`,
+    );
+  } else {
+    console.log("Words: none delivered, no caption files written");
+  }
+  const silent = noWordTimes(timeline);
+  if (silent.length > 0) console.log(`No word times: ${silent.join(", ")}`);
+  console.log(`Music bed: ${music ?? "none"}`);
+  console.log(`Upload it: exodus video upload ${manifest.runId} --file ${out}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/package.json

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