@vibeframe/cli 0.112.1 → 0.113.2

package/dist/tools/manifest/index.js

@@ -191,8 +191,8 @@ var init_api_keys = __esm({
       envVar: "OPENAI_API_KEY",
       label: "OpenAI",
       showInSetup: true,
-      setupDescription: "gpt-image-2 image gen ($, default since v0.56), Whisper transcribe, Agent",
-      envExampleComment: "OpenAI API Key (Whisper transcription, gpt-image-2 \u2014 default text-to-image since v0.56)",
+      setupDescription: "gpt-image-2 image gen ($, default since v0.56), gpt-4o-mini-tts narration, Whisper transcribe, Agent",
+      envExampleComment: "OpenAI API Key (Whisper transcription, gpt-4o-mini-tts narration, gpt-image-2 \u2014 default text-to-image since v0.56)",
       envExampleUrl: "https://platform.openai.com/api-keys",
       keyFormat: { prefix: /^sk-/, example: "sk-..." }
     });
@@ -2299,8 +2299,8 @@ var init_openai = __esm({
       id: "openai",
       label: "OpenAI",
       apiKey: "openai",
-      kinds: ["llm", "image", "transcription"],
-      resolverPriority: { image: 1 },
+      kinds: ["llm", "image", "transcription", "speech"],
+      resolverPriority: { image: 1, speech: 2 },
       commandsUnlocked: [
         "agent -p openai",
         "generate image -p openai",
@@ -4722,16 +4722,19 @@ var init_elevenlabs = __esm({
 });
 
 // ../ai-providers/dist/kokoro/KokoroProvider.js
-async function loadKokoroFactory() {
+async function loadKokoroRuntime() {
   if (factoryOverride)
-    return factoryOverride;
+    return { factory: factoryOverride, device: "cpu" };
   try {
     const mod = await import("kokoro-js");
-    return mod.KokoroTTS;
+    return { factory: mod.KokoroTTS, device: "cpu" };
   } catch (err) {
-    const fallback2 = await loadKokoroFromWorkspace();
-    if (fallback2)
-      return fallback2;
+    const workspace = await loadKokoroFromWorkspace();
+    if (workspace)
+      return { factory: workspace, device: "cpu" };
+    const bundled = await loadBundledKokoroRuntime();
+    if (bundled)
+      return bundled;
     throw mapKokoroImportError(err);
   }
 }
@@ -4751,10 +4754,51 @@ async function loadKokoroFromWorkspace(baseDir = process.cwd()) {
     return null;
   }
 }
+async function loadBundledKokoroRuntime(runtimeDir = process.env.VIBE_KOKORO_RUNTIME) {
+  const base = runtimeDir?.trim();
+  if (!base)
+    return null;
+  try {
+    const { readFile: readFile45, writeFile: writeFile51, mkdir: mkdir26 } = await import("node:fs/promises");
+    const { join: join27, resolve: resolve66 } = await import("node:path");
+    const { pathToFileURL } = await import("node:url");
+    const { homedir: homedir6 } = await import("node:os");
+    const transformersDir = resolve66(base, "node_modules", "@huggingface", "transformers");
+    const ortDistDir = resolve66(base, "node_modules", "onnxruntime-web", "dist");
+    const transformers = await import(pathToFileURL(join27(transformersDir, "dist", "transformers.web.js")).href);
+    const cacheRoot = join27(homedir6(), ".cache", "vibeframe", "models");
+    transformers.env.allowLocalModels = false;
+    transformers.env.useCustomCache = true;
+    transformers.env.customCache = {
+      async match(key) {
+        try {
+          return new Response(await readFile45(join27(cacheRoot, encodeURIComponent(String(key)))));
+        } catch {
+          return void 0;
+        }
+      },
+      async put(key, response) {
+        try {
+          const buf = Buffer.from(await response.arrayBuffer());
+          await mkdir26(cacheRoot, { recursive: true });
+          await writeFile51(join27(cacheRoot, encodeURIComponent(String(key))), buf);
+        } catch {
+        }
+      }
+    };
+    transformers.env.backends.onnx.wasm.wasmPaths = pathToFileURL(ortDistDir + "/").href;
+    const factory = await loadKokoroFromWorkspace(base);
+    if (!factory)
+      return null;
+    return { factory, device: "cpu" };
+  } catch {
+    return null;
+  }
+}
 function mapKokoroImportError(err) {
   const code = err instanceof Error && "code" in err ? err.code : void 0;
   if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
-    return new Error("Local Kokoro TTS is unavailable: optional dependency kokoro-js is not installed (its native dependencies may have failed to build on this platform). Install it with `npm i kokoro-js` \u2014 run it inside your workspace folder when using the Claude Desktop extension \u2014 or set ELEVENLABS_API_KEY to use the elevenlabs TTS provider instead.");
+    return new Error("Local Kokoro TTS is unavailable: kokoro-js could not be loaded from the npm install, the workspace node_modules, or the bundled extension runtime. Set OPENAI_API_KEY or ELEVENLABS_API_KEY to use a cloud voice instead (ttsProvider: openai / elevenlabs), or install the engine locally with `npm i kokoro-js` in your workspace folder.");
   }
   return err instanceof Error ? err : new Error(String(err));
 }
@@ -4762,10 +4806,12 @@ function loadModel(progress) {
   if (modelPromise)
     return modelPromise;
   modelPromise = (async () => {
-    const factory = await loadKokoroFactory();
-    return factory.from_pretrained(KOKORO_MODEL_ID, {
+    const runtime = await loadKokoroRuntime();
+    const override = process.env.VIBE_ONNX_DEVICE;
+    const device = override === "cpu" || override === "wasm" ? override : runtime.device;
+    return runtime.factory.from_pretrained(KOKORO_MODEL_ID, {
       dtype: "q8",
-      device: "cpu",
+      device,
       progress_callback: progress ? (raw) => progress(normaliseEvent(raw)) : void 0
     });
   })().catch((err) => {
@@ -4849,7 +4895,7 @@ var init_kokoro = __esm({
       label: "Kokoro (local)",
       apiKey: null,
       kinds: ["speech"],
-      resolverPriority: { speech: 2 }
+      resolverPriority: { speech: 3 }
     });
   }
 });
@@ -5121,12 +5167,119 @@ var init_openai_image = __esm({
   }
 });
 
+// ../ai-providers/dist/openai-tts/OpenAiTtsProvider.js
+var OPENAI_TTS_VOICES, DEFAULT_VOICE, DEFAULT_MODEL2, TTS_429_MAX_RETRIES2, TTS_429_RETRY_DELAY_MS2, OpenAiTtsProvider, openaiTtsProvider;
+var init_OpenAiTtsProvider = __esm({
+  "../ai-providers/dist/openai-tts/OpenAiTtsProvider.js"() {
+    "use strict";
+    OPENAI_TTS_VOICES = [
+      "alloy",
+      "ash",
+      "ballad",
+      "cedar",
+      "coral",
+      "echo",
+      "fable",
+      "marin",
+      "nova",
+      "onyx",
+      "sage",
+      "shimmer",
+      "verse"
+    ];
+    DEFAULT_VOICE = "marin";
+    DEFAULT_MODEL2 = "gpt-4o-mini-tts";
+    TTS_429_MAX_RETRIES2 = 1;
+    TTS_429_RETRY_DELAY_MS2 = 2e3;
+    OpenAiTtsProvider = class {
+      constructor() {
+        this.id = "openai";
+        this.name = "OpenAI TTS";
+        this.description = "OpenAI cloud text-to-speech (gpt-4o-mini-tts)";
+        this.capabilities = ["text-to-speech"];
+        this.isAvailable = true;
+        this.baseUrl = "https://api.openai.com/v1";
+      }
+      async initialize(config2) {
+        this.apiKey = config2.apiKey;
+        if (config2.baseUrl) {
+          this.baseUrl = config2.baseUrl;
+        }
+      }
+      isConfigured() {
+        return !!this.apiKey;
+      }
+      async textToSpeech(text, options = {}) {
+        if (!this.apiKey) {
+          return { success: false, error: "OpenAI API key not configured" };
+        }
+        const voice = (options.voice ?? DEFAULT_VOICE).toLowerCase();
+        if (!OPENAI_TTS_VOICES.includes(voice)) {
+          return {
+            success: false,
+            error: `Unknown OpenAI voice "${options.voice}". Available voices: ${OPENAI_TTS_VOICES.join(", ")}.`
+          };
+        }
+        try {
+          let response;
+          for (let attempt = 0; ; attempt++) {
+            response = await fetch(`${this.baseUrl}/audio/speech`, {
+              method: "POST",
+              headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json"
+              },
+              body: JSON.stringify({
+                model: options.model ?? DEFAULT_MODEL2,
+                input: text,
+                voice,
+                response_format: "mp3",
+                ...options.speed !== void 0 && { speed: options.speed },
+                ...options.instructions !== void 0 && { instructions: options.instructions }
+              })
+            });
+            if (response.status === 429 && attempt < TTS_429_MAX_RETRIES2) {
+              await new Promise((resolveDelay) => setTimeout(resolveDelay, TTS_429_RETRY_DELAY_MS2 * (attempt + 1)));
+              continue;
+            }
+            break;
+          }
+          if (!response.ok) {
+            const error = await response.text();
+            return { success: false, error: `OpenAI TTS failed: ${error}` };
+          }
+          const arrayBuffer = await response.arrayBuffer();
+          return {
+            success: true,
+            audioBuffer: Buffer.from(arrayBuffer),
+            characterCount: text.length
+          };
+        } catch (error) {
+          return {
+            success: false,
+            error: error instanceof Error ? error.message : "Unknown error"
+          };
+        }
+      }
+    };
+    openaiTtsProvider = new OpenAiTtsProvider();
+  }
+});
+
+// ../ai-providers/dist/openai-tts/index.js
+var init_openai_tts = __esm({
+  "../ai-providers/dist/openai-tts/index.js"() {
+    "use strict";
+    init_OpenAiTtsProvider();
+  }
+});
+
 // ../ai-providers/dist/runway/RunwayProvider.js
-var DEFAULT_MODEL2, RunwayProvider, runwayProvider;
+var DEFAULT_MODEL3, RunwayProvider, runwayProvider;
 var init_RunwayProvider = __esm({
   "../ai-providers/dist/runway/RunwayProvider.js"() {
     "use strict";
-    DEFAULT_MODEL2 = "gen4.5";
+    DEFAULT_MODEL3 = "gen4.5";
     RunwayProvider = class _RunwayProvider {
       constructor() {
         this.id = "runway";
@@ -5169,7 +5322,7 @@ var init_RunwayProvider = __esm({
             "1:1": "960:960"
           };
           const apiRatio = ratioMap[options?.aspectRatio || "16:9"] || "1280:720";
-          const model = options?.model || DEFAULT_MODEL2;
+          const model = options?.model || DEFAULT_MODEL3;
           if (!options?.referenceImage && model !== "gen4.5") {
             return {
               id: "",
@@ -5431,11 +5584,11 @@ var init_runway = __esm({
 
 // ../ai-providers/dist/kling/KlingProvider.js
 import { createHmac } from "node:crypto";
-var DEFAULT_MODEL3, STD_MODE_MODELS, KlingProvider, klingProvider;
+var DEFAULT_MODEL4, STD_MODE_MODELS, KlingProvider, klingProvider;
 var init_KlingProvider = __esm({
   "../ai-providers/dist/kling/KlingProvider.js"() {
     "use strict";
-    DEFAULT_MODEL3 = "kling-v2-5-turbo";
+    DEFAULT_MODEL4 = "kling-v2-5-turbo";
     STD_MODE_MODELS = ["kling-v2-5-turbo", "kling-v2-6", "kling-v3", "kling-v3-omni"];
     KlingProvider = class {
       constructor() {
@@ -5498,7 +5651,7 @@ var init_KlingProvider = __esm({
         }
         try {
           const token = this.generateToken();
-          const model = options?.model || DEFAULT_MODEL3;
+          const model = options?.model || DEFAULT_MODEL4;
           let mode = options?.mode || "std";
           if (!STD_MODE_MODELS.includes(model) && mode === "std") {
             mode = "pro";
@@ -5869,11 +6022,11 @@ var init_kling = __esm({
 });
 
 // ../ai-providers/dist/grok/GrokProvider.js
-var DEFAULT_MODEL4, GrokProvider, grokProvider;
+var DEFAULT_MODEL5, GrokProvider, grokProvider;
 var init_GrokProvider = __esm({
   "../ai-providers/dist/grok/GrokProvider.js"() {
     "use strict";
-    DEFAULT_MODEL4 = "grok-imagine-video";
+    DEFAULT_MODEL5 = "grok-imagine-video";
     GrokProvider = class {
       constructor() {
         this.id = "grok";
@@ -6040,7 +6193,7 @@ var init_GrokProvider = __esm({
         try {
           const duration = Math.round(Math.min(15, Math.max(1, options?.duration || 5)));
           const body = {
-            model: DEFAULT_MODEL4,
+            model: DEFAULT_MODEL5,
             prompt: prompt3,
             duration,
             aspect_ratio: options?.aspectRatio || "16:9"
@@ -10306,6 +10459,19 @@ var require_src = __commonJS({
 });
 
 // ../ai-providers/dist/fal/FalProvider.js
+function estimateSeedanceVideoCostUsd(opts) {
+  const shortSide = SEEDANCE_SHORT_SIDE[opts.resolution ?? "720p"] ?? 720;
+  const [a, b] = (opts.aspectRatio ?? "16:9").split(":").map(Number);
+  const ratioFactor = a > 0 && b > 0 ? Math.max(a, b) / Math.min(a, b) : 16 / 9;
+  const longSide = Math.round(shortSide * ratioFactor);
+  const tokensPerSecond = shortSide * longSide * 24 / 1024;
+  let usdPerSecond = tokensPerSecond / 1e3 * SEEDANCE_USD_PER_1K_TOKENS;
+  if (opts.fast && shortSide <= 720)
+    usdPerSecond *= SEEDANCE_FAST_FACTOR;
+  if (opts.hasVideoReference)
+    usdPerSecond *= SEEDANCE_VIDEO_REF_FACTOR;
+  return Number((usdPerSecond * Math.max(0, opts.durationSec)).toFixed(2));
+}
 function formatFalError(error) {
   if (!(error instanceof Error))
     return String(error);
@@ -10415,7 +10581,7 @@ function normaliseDuration(value) {
     return "auto";
   return Math.max(4, Math.min(15, Math.round(value)));
 }
-var import_client, ENDPOINT_TEXT_TO_VIDEO, ENDPOINT_IMAGE_TO_VIDEO, ENDPOINT_REFERENCE_TO_VIDEO, DEFAULT_VARIANT, VALID_RESOLUTIONS, VALID_ASPECTS, FalProvider, falProvider;
+var import_client, ENDPOINT_TEXT_TO_VIDEO, ENDPOINT_IMAGE_TO_VIDEO, ENDPOINT_REFERENCE_TO_VIDEO, DEFAULT_VARIANT, VALID_RESOLUTIONS, VALID_ASPECTS, SEEDANCE_USD_PER_1K_TOKENS, SEEDANCE_FAST_FACTOR, SEEDANCE_VIDEO_REF_FACTOR, SEEDANCE_SHORT_SIDE, FalProvider, falProvider;
 var init_FalProvider = __esm({
   "../ai-providers/dist/fal/FalProvider.js"() {
     "use strict";
@@ -10435,6 +10601,10 @@ var init_FalProvider = __esm({
     DEFAULT_VARIANT = "seedance-2.0";
     VALID_RESOLUTIONS = ["480p", "720p", "1080p"];
     VALID_ASPECTS = ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16", "auto"];
+    SEEDANCE_USD_PER_1K_TOKENS = 0.014;
+    SEEDANCE_FAST_FACTOR = 0.8;
+    SEEDANCE_VIDEO_REF_FACTOR = 0.6;
+    SEEDANCE_SHORT_SIDE = { "480p": 480, "720p": 720, "1080p": 1080 };
     FalProvider = class {
       constructor() {
         this.id = "seedance";
@@ -11247,9 +11417,11 @@ __export(dist_exports2, {
   KOKORO_MODEL_ID: () => KOKORO_MODEL_ID,
   KlingProvider: () => KlingProvider,
   KokoroProvider: () => KokoroProvider,
+  OPENAI_TTS_VOICES: () => OPENAI_TTS_VOICES,
   OllamaProvider: () => OllamaProvider,
   OpenAIImageProvider: () => OpenAIImageProvider,
   OpenAIProvider: () => OpenAIProvider,
+  OpenAiTtsProvider: () => OpenAiTtsProvider,
   ReplicateProvider: () => ReplicateProvider,
   RunwayProvider: () => RunwayProvider,
   WhisperProvider: () => WhisperProvider,
@@ -11257,6 +11429,7 @@ __export(dist_exports2, {
   defineApiKey: () => defineApiKey,
   defineProvider: () => defineProvider,
   elevenLabsProvider: () => elevenLabsProvider,
+  estimateSeedanceVideoCostUsd: () => estimateSeedanceVideoCostUsd,
   falProvider: () => falProvider,
   geminiProvider: () => geminiProvider,
   getAllApiKeys: () => getAllApiKeys,
@@ -11273,9 +11446,12 @@ __export(dist_exports2, {
   isGeminiTextModelAlias: () => isGeminiTextModelAlias,
   klingProvider: () => klingProvider,
   kokoroProvider: () => kokoroProvider,
+  loadBundledKokoroRuntime: () => loadBundledKokoroRuntime,
+  loadKokoroFromWorkspace: () => loadKokoroFromWorkspace,
   ollamaProvider: () => ollamaProvider,
   openaiImageProvider: () => openaiImageProvider,
   openaiProvider: () => openaiProvider,
+  openaiTtsProvider: () => openaiTtsProvider,
   providerRegistry: () => providerRegistry,
   replicateProvider: () => replicateProvider,
   resolveGeminiTextModel: () => resolveGeminiTextModel,
@@ -11298,6 +11474,7 @@ var init_dist2 = __esm({
     init_elevenlabs();
     init_kokoro();
     init_openai_image();
+    init_openai_tts();
     init_runway();
     init_kling();
     init_grok();
@@ -24059,7 +24236,534 @@ var init_build_asset_metadata = __esm({
   }
 });
 
+// src/commands/_shared/review-report.ts
+import { writeFile as writeFile6 } from "node:fs/promises";
+import { join as join2, resolve as resolve5 } from "node:path";
+function statusFromIssues(issues) {
+  if (issues.some((issue) => issue.severity === "error")) return "fail";
+  if (issues.some((issue) => issue.severity === "warning")) return "warn";
+  return "pass";
+}
+function scoreIssues(issues) {
+  let score = 100;
+  for (const issue of issues) {
+    if (issue.severity === "error") score -= 25;
+    else if (issue.severity === "warning") score -= 8;
+    else score -= 2;
+  }
+  return Math.max(0, Math.min(100, score));
+}
+function uniqueRetryWith(items) {
+  return [
+    ...new Set(items.filter((item) => typeof item === "string" && item.length > 0))
+  ];
+}
+function commandReviewAction(command, opts) {
+  const classified = classifyReviewCommand(command);
+  return stripUndefined({
+    id: actionId("command", command),
+    kind: "command",
+    label: opts.label ?? command,
+    command,
+    fixOwner: opts.fixOwner ?? classified.fixOwner,
+    costTier: opts.costTier ?? classified.costTier,
+    safeToAutoRun: opts.safeToAutoRun ?? classified.safeToAutoRun,
+    requiresConfirmation: opts.requiresConfirmation ?? classified.requiresConfirmation,
+    reason: opts.reason,
+    sourceIssueCodes: uniqueStrings(opts.sourceIssueCodes ?? [])
+  });
+}
+function agentReviewAction(opts) {
+  return stripUndefined({
+    id: actionId("agent", opts.agentPrompt),
+    kind: "agent",
+    label: opts.label,
+    agentPrompt: opts.agentPrompt,
+    fixOwner: "host-agent",
+    costTier: "unknown",
+    safeToAutoRun: false,
+    requiresConfirmation: false,
+    reason: opts.reason,
+    sourceIssueCodes: uniqueStrings(opts.sourceIssueCodes ?? [])
+  });
+}
+function manualReviewAction(opts) {
+  return stripUndefined({
+    id: actionId("manual", opts.label),
+    kind: "manual",
+    label: opts.label,
+    fixOwner: opts.fixOwner ?? "host-agent",
+    costTier: "unknown",
+    safeToAutoRun: false,
+    requiresConfirmation: false,
+    reason: opts.reason,
+    sourceIssueCodes: uniqueStrings(opts.sourceIssueCodes ?? [])
+  });
+}
+function reviewActionsFromRetryWith(retryWith, sourceIssueCodes = []) {
+  return normalizeReviewActions(
+    retryWith.map((item) => {
+      if (/^codex\s+/i.test(item)) {
+        return agentReviewAction({
+          label: "Ask the host agent to fix review issues",
+          agentPrompt: item,
+          reason: "The review report contains host-agent-owned issues.",
+          sourceIssueCodes
+        });
+      }
+      return commandReviewAction(item, {
+        reason: "Backward-compatible retryWith command.",
+        sourceIssueCodes
+      });
+    })
+  );
+}
+function normalizeReviewActions(actions) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const action of actions) {
+    const key = [action.kind, action.command ?? action.agentPrompt ?? action.label].join("\0");
+    const existing = merged.get(key);
+    if (!existing) {
+      merged.set(key, {
+        ...action,
+        sourceIssueCodes: uniqueStrings(action.sourceIssueCodes ?? [])
+      });
+      continue;
+    }
+    merged.set(key, {
+      ...existing,
+      safeToAutoRun: existing.safeToAutoRun && action.safeToAutoRun,
+      requiresConfirmation: existing.requiresConfirmation || action.requiresConfirmation,
+      sourceIssueCodes: uniqueStrings([
+        ...existing.sourceIssueCodes ?? [],
+        ...action.sourceIssueCodes ?? []
+      ])
+    });
+  }
+  return [...merged.values()].map(
+    (action) => stripUndefined({
+      ...action,
+      sourceIssueCodes: action.sourceIssueCodes && action.sourceIssueCodes.length > 0 ? action.sourceIssueCodes : void 0
+    })
+  );
+}
+function deriveNextReviewActions(opts) {
+  return normalizeReviewActions([
+    ...opts.issues.flatMap((issue) => issue.actions ?? []),
+    ...reviewActionsFromRetryWith(opts.retryWith)
+  ]);
+}
+function fixOwnerForIssue(issue) {
+  if (issue.fixOwner) return issue.fixOwner;
+  if (issue.code.startsWith("AI_REVIEW_")) return "host-agent";
+  if (issue.code.startsWith("STORYBOARD_")) return "host-agent";
+  if (issue.code === "PROJECT_NOT_FOUND" || issue.code === "MISSING_STORYBOARD" || issue.code === "BEAT_NOT_FOUND" || issue.code === "MISSING_DESIGN") {
+    return "host-agent";
+  }
+  return "vibe";
+}
+function normalizeReviewIssues(issues, opts) {
+  const fallbackOwner = typeof opts === "string" ? opts : opts?.fallbackOwner;
+  const projectDir = typeof opts === "string" ? void 0 : opts?.projectDir;
+  return issues.map((issue) => {
+    const normalized = {
+      ...issue,
+      fixOwner: issue.fixOwner ?? fallbackOwner ?? fixOwnerForIssue(issue)
+    };
+    const actions = normalizeReviewActions([
+      ...issue.actions ?? [],
+      ...projectDir ? defaultActionsForIssue(normalized, projectDir) : []
+    ]);
+    return stripUndefined({
+      ...normalized,
+      actions: actions.length > 0 ? actions : void 0
+    });
+  });
+}
+function summarizeReviewIssues(issues) {
+  const normalized = normalizeReviewIssues(issues);
+  return {
+    issueCount: normalized.length,
+    errorCount: normalized.filter((issue) => issue.severity === "error").length,
+    warningCount: normalized.filter((issue) => issue.severity === "warning").length,
+    infoCount: normalized.filter((issue) => issue.severity === "info").length,
+    fixOwners: {
+      vibe: normalized.filter((issue) => issue.fixOwner === "vibe").length,
+      hostAgent: normalized.filter((issue) => issue.fixOwner === "host-agent").length
+    }
+  };
+}
+function buildReviewReport(opts) {
+  const retryWith = uniqueRetryWith(opts.retryWith);
+  const issues = normalizeReviewIssues(opts.issues, {
+    projectDir: opts.project,
+    retryWith
+  });
+  return stripUndefined({
+    schemaVersion: "1",
+    kind: "review",
+    project: resolve5(opts.project),
+    mode: opts.mode,
+    beat: opts.beat,
+    status: opts.status,
+    score: opts.score,
+    issues,
+    summary: summarizeReviewIssues(issues),
+    nextActions: deriveNextReviewActions({ issues, retryWith, projectDir: opts.project }),
+    retryWith,
+    sourceReports: opts.sourceReports ?? [],
+    reportPath: opts.reportPath
+  });
+}
+function defaultReviewReportPath(projectDir) {
+  return join2(resolve5(projectDir), "review-report.json");
+}
+async function writeReviewReport(path2, report) {
+  await writeFile6(path2, JSON.stringify(report, null, 2) + "\n", "utf-8");
+}
+function stripUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0));
+}
+function defaultActionsForIssue(issue, projectDir) {
+  const code = issue.code;
+  const beat = issue.beatId ?? issue.scene;
+  const beatFlag = beat ? ` --beat ${beat}` : "";
+  const sourceIssueCodes = [code];
+  if (code === "PROJECT_NOT_FOUND" || code === "MISSING_STORYBOARD") {
+    return [
+      commandReviewAction(`vibe init ${projectDir} --from "<brief>" --json`, {
+        label: "Initialize the project from a brief",
+        fixOwner: "host-agent",
+        reason: "The project cannot be inspected until the core project files exist.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "MISSING_DESIGN" || code === "DESIGN_PLACEHOLDER_FIELD") {
+    return [
+      manualReviewAction({
+        label: "Create or complete DESIGN.md",
+        reason: "Visual direction needs host-agent or human input before VibeFrame can repair it.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "BEAT_NOT_FOUND" || code.startsWith("STORYBOARD_")) {
+    const actions = [
+      commandReviewAction(`vibe storyboard validate ${projectDir} --json`, {
+        label: "Validate the storyboard",
+        fixOwner: "host-agent",
+        reason: "The storyboard issue needs structured validation before editing.",
+        sourceIssueCodes
+      })
+    ];
+    if (code === "STORYBOARD_PLACEHOLDER_CUE") {
+      actions.push(
+        commandReviewAction(
+          `vibe storyboard revise ${projectDir} --from "<make cues concrete>" --dry-run --json`,
+          {
+            label: "Preview a storyboard revision",
+            fixOwner: "host-agent",
+            reason: "Placeholder cues should be revised into concrete video intent.",
+            sourceIssueCodes
+          }
+        )
+      );
+    }
+    return actions;
+  }
+  if (code === "MISSING_ROOT_COMPOSITION" || code === "ROOT_SYNC_CHECK_FAILED") {
+    return [
+      commandReviewAction(`vibe build ${projectDir} --stage sync --json`, {
+        label: "Sync the project root composition",
+        reason: "The root composition is missing or could not be verified.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code.startsWith("ROOT_")) {
+    return issue.fixOwner === "host-agent" ? [
+      agentReviewAction({
+        label: "Repair the root composition shell",
+        agentPrompt: "Fix host-agent-owned root composition issues from review-report.json",
+        reason: "The root composition cannot be repaired deterministically.",
+        sourceIssueCodes
+      })
+    ] : [
+      commandReviewAction(`vibe scene repair ${projectDir} --json`, {
+        label: "Repair deterministic scene/root issues",
+        reason: "The root composition has deterministic sync issues.",
+        sourceIssueCodes
+      }),
+      commandReviewAction(`vibe build ${projectDir} --stage sync --json`, {
+        label: "Resync root composition after repair",
+        reason: "The root composition should be synced after deterministic repair.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "MISSING_COMPOSITION") {
+    return [
+      commandReviewAction(`vibe build ${projectDir}${beatFlag} --stage compose --json`, {
+        label: beat ? `Compose beat ${beat}` : "Compose missing scenes",
+        reason: "Missing scene compositions must be generated or authored before render.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "MISSING_BUILD_REPORT") {
+    return [
+      commandReviewAction(`vibe build ${projectDir} --dry-run --json`, {
+        label: "Preview the build plan",
+        reason: "A dry-run build report is needed before choosing a paid or mutating build step.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "BUILD_REPORT_BEAT_MISSING") {
+    return [
+      commandReviewAction(`vibe build ${projectDir}${beatFlag} --stage sync --json`, {
+        label: beat ? `Sync build report for beat ${beat}` : "Sync the build report",
+        reason: "The build report does not include the inspected beat.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "MALFORMED_BUILD_REPORT") {
+    return [
+      commandReviewAction(`vibe build ${projectDir} --json`, {
+        label: "Regenerate the build report",
+        reason: "The existing build report cannot be parsed.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "MISSING_REPORTED_ASSET" || code === "STALE_ASSET" || code === "UNKNOWN_ASSET_FRESHNESS") {
+    return [
+      commandReviewAction(`vibe build ${projectDir}${beatFlag} --stage assets --force --json`, {
+        label: beat ? `Regenerate assets for beat ${beat}` : "Regenerate stale or missing assets",
+        reason: "Asset generation may call providers, so the host should confirm first.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "MUSIC_CUE_NOT_READY") {
+    return [
+      commandReviewAction(`vibe build ${projectDir}${beatFlag} --stage assets --json`, {
+        label: beat ? `Generate music for beat ${beat}` : "Generate missing music assets",
+        reason: "Music generation may call providers, so the host should confirm first.",
+        sourceIssueCodes
+      }),
+      commandReviewAction(`vibe build ${projectDir} --stage sync --json`, {
+        label: "Sync music into the root composition",
+        reason: "Generated music needs root composition wiring.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code.startsWith("SCENE_LINT_")) {
+    return [
+      commandReviewAction(`vibe scene repair ${projectDir} --json`, {
+        label: "Repair deterministic scene lint issues",
+        reason: "Scene lint reported an issue VibeFrame may be able to repair mechanically.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "RENDER_NOT_FOUND" || code === "EMPTY_RENDER") {
+    return [
+      commandReviewAction(
+        beat ? `vibe render ${projectDir} --beat ${beat} --json` : `vibe render ${projectDir} --json`,
+        {
+          label: beat ? `Render beat ${beat}` : "Render the project",
+          reason: "A render file is required before render inspection can pass.",
+          sourceIssueCodes
+        }
+      )
+    ];
+  }
+  if (code === "NO_AUDIO_STREAM" || code === "DURATION_DRIFT") {
+    return [
+      commandReviewAction(`vibe build ${projectDir}${beatFlag} --stage sync --json`, {
+        label: beat ? `Sync timing/audio for beat ${beat}` : "Sync timing and audio wiring",
+        reason: "The render output no longer matches synced project state.",
+        sourceIssueCodes
+      }),
+      commandReviewAction(
+        beat ? `vibe render ${projectDir} --beat ${beat} --json` : `vibe render ${projectDir} --json`,
+        {
+          label: beat ? `Rerender beat ${beat}` : "Rerender the project",
+          reason: "The render should be regenerated after sync repair.",
+          sourceIssueCodes
+        }
+      )
+    ];
+  }
+  if (code === "BLACK_FRAME_SEGMENT") {
+    return issue.fixOwner === "host-agent" ? [
+      agentReviewAction({
+        label: beat ? `Fix black frames in beat ${beat}` : "Fix black frame segment",
+        agentPrompt: "Fix black-frame issues from review-report.json, then rerender.",
+        reason: "The issue likely needs scene, storyboard, or visual cue changes.",
+        sourceIssueCodes
+      })
+    ] : [
+      commandReviewAction(`vibe scene repair ${projectDir} --json`, {
+        label: "Repair deterministic scene timing",
+        reason: "Black frames outside a specific beat may be recoverable with scene repair.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "STATIC_FRAME_SEGMENT") {
+    return [
+      agentReviewAction({
+        label: beat ? `Add motion to beat ${beat}` : "Fix static visual hold",
+        agentPrompt: "Fix static-frame issues from review-report.json, then rerender.",
+        reason: "Static segments usually need creative scene, storyboard, or asset changes.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "LONG_SILENCE") {
+    return issue.fixOwner === "host-agent" ? [
+      agentReviewAction({
+        label: beat ? `Fix long silence in beat ${beat}` : "Fix long silence",
+        agentPrompt: "Fix long-silence issues from review-report.json, then rerender.",
+        reason: "The beat duration, narration, or music cue needs host-agent judgment.",
+        sourceIssueCodes
+      })
+    ] : [
+      commandReviewAction(`vibe build ${projectDir}${beatFlag} --stage sync --json`, {
+        label: beat ? `Sync audio for beat ${beat}` : "Sync audio wiring",
+        reason: "The silence may be caused by stale narration or music wiring.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code.startsWith("AI_REVIEW_")) {
+    return [
+      agentReviewAction({
+        label: "Fix AI review findings",
+        agentPrompt: "Fix host-agent-owned AI review issues from review-report.json, then rerender.",
+        reason: "AI review findings require storyboard, design, or composition judgment.",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "FFPROBE_UNAVAILABLE" || code === "FFMPEG_UNAVAILABLE") {
+    return [
+      manualReviewAction({
+        label: "Install FFmpeg and rerun inspection",
+        reason: "Local media inspection depends on ffmpeg/ffprobe being available.",
+        fixOwner: "host-agent",
+        sourceIssueCodes
+      })
+    ];
+  }
+  if (code === "FFPROBE_FAILED" || code === "NO_VIDEO_STREAM") {
+    return [
+      commandReviewAction(
+        beat ? `vibe render ${projectDir} --beat ${beat} --json` : `vibe render ${projectDir} --json`,
+        {
+          label: beat ? `Rerender beat ${beat}` : "Rerender the project",
+          reason: "The rendered media could not be probed as a valid video.",
+          sourceIssueCodes
+        }
+      )
+    ];
+  }
+  if (code === "ASPECT_MISMATCH") {
+    return [
+      manualReviewAction({
+        label: "Check project aspect and render settings",
+        reason: "Aspect mismatches can come from either config intent or render settings.",
+        fixOwner: issue.fixOwner,
+        sourceIssueCodes
+      })
+    ];
+  }
+  return [];
+}
+function classifyReviewCommand(command) {
+  const lower = command.trim().toLowerCase();
+  if (lower.startsWith("vibe status ")) return safe("free");
+  if (lower.startsWith("vibe scene repair")) return safe("free");
+  if (lower.startsWith("vibe storyboard validate") || lower.startsWith("vibe storyboard get") || lower.startsWith("vibe storyboard list")) {
+    return safe("free", "host-agent");
+  }
+  if (lower.startsWith("vibe inspect project")) return safe("free");
+  if (lower.startsWith("vibe inspect render")) {
+    if (lower.includes("--ai")) return unsafe("low");
+    return safe("free");
+  }
+  if (lower.startsWith("vibe render ")) return safe("free");
+  if (lower.startsWith("vibe build ")) {
+    if (lower.includes("--dry-run")) return safe("free");
+    if (lower.includes("--stage sync") || lower.includes("--stage render")) return safe("free");
+    return unsafe("unknown");
+  }
+  if (lower.startsWith("vibe generate video") || lower.startsWith("vibe edit fill-gaps") || lower.startsWith("vibe remix ")) {
+    return unsafe("very-high");
+  }
+  if (lower.startsWith("vibe storyboard revise")) return unsafe("unknown", "host-agent");
+  return unsafe("unknown");
+}
+function safe(costTier, fixOwner = "vibe") {
+  return { fixOwner, costTier, safeToAutoRun: true, requiresConfirmation: false };
+}
+function unsafe(costTier, fixOwner = "vibe") {
+  return { fixOwner, costTier, safeToAutoRun: false, requiresConfirmation: true };
+}
+function actionId(kind, value) {
+  const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 80);
+  return `${kind}:${slug || "action"}`;
+}
+function uniqueStrings(items) {
+  return [
+    ...new Set(items.filter((item) => typeof item === "string" && item.length > 0))
+  ];
+}
+var init_review_report = __esm({
+  "src/commands/_shared/review-report.ts"() {
+    "use strict";
+  }
+});
+
 // src/commands/_shared/storyboard-parse.ts
+function resolveCharacters(frontmatter) {
+  const pool = frontmatter?.characters;
+  if (!pool || typeof pool !== "object") return [];
+  const resolved = [];
+  for (const [name, spec] of Object.entries(pool)) {
+    if (typeof spec === "string") {
+      const prompt3 = spec.trim();
+      if (prompt3) resolved.push({ name, prompt: prompt3 });
+      continue;
+    }
+    if (spec && typeof spec === "object") {
+      const image = typeof spec.image === "string" ? spec.image.trim() : "";
+      if (image) {
+        resolved.push({ name, imagePath: image });
+        continue;
+      }
+      const description = typeof spec.description === "string" ? spec.description.trim() : "";
+      if (description) resolved.push({ name, prompt: description });
+    }
+  }
+  return resolved;
+}
+function beatCharacterNames(cues) {
+  const raw = cues?.characters;
+  if (typeof raw === "string") {
+    const name = raw.trim();
+    return name ? [name] : [];
+  }
+  if (Array.isArray(raw)) {
+    return raw.filter((v) => typeof v === "string" && v.trim().length > 0).map((v) => v.trim());
+  }
+  return [];
+}
 function parseStoryboard(md) {
   const normalized = md.replace(/\r\n/g, "\n");
   const { frontmatter, remaining } = extractProjectFrontmatter(normalized);
@@ -24172,28 +24876,28 @@ var init_storyboard_parse = __esm({
 // src/commands/_shared/status-jobs.ts
 import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
 import { existsSync as existsSync2, statSync } from "node:fs";
-import { copyFile, mkdir as mkdir3, readFile as readFile4, readdir, stat, writeFile as writeFile6 } from "node:fs/promises";
-import { dirname as dirname3, join as join2, parse as parse2, relative, resolve as resolve5 } from "node:path";
+import { copyFile, mkdir as mkdir3, readFile as readFile4, readdir, stat, writeFile as writeFile7 } from "node:fs/promises";
+import { dirname as dirname3, join as join3, parse as parse2, relative, resolve as resolve6 } from "node:path";
 function isLocalJob(record) {
   return record.jobType === "build" || record.jobType === "render";
 }
 function findProjectRoot(start = process.cwd()) {
-  let dir = resolve5(start);
+  let dir = resolve6(start);
   try {
     if (existsSync2(dir) && statSync(dir).isFile()) dir = dirname3(dir);
   } catch {
   }
   for (; ; ) {
-    if (existsSync2(join2(dir, "vibe.config.json")) || existsSync2(join2(dir, "STORYBOARD.md"))) {
+    if (existsSync2(join3(dir, "vibe.config.json")) || existsSync2(join3(dir, "STORYBOARD.md"))) {
       return dir;
     }
     const parent = dirname3(dir);
-    if (parent === dir) return resolve5(start);
+    if (parent === dir) return resolve6(start);
     dir = parent;
   }
 }
 function jobsDir(projectDir) {
-  return join2(resolve5(projectDir), ".vibeframe", "jobs");
+  return join3(resolve6(projectDir), ".vibeframe", "jobs");
 }
 function normalizeJobStatus(status) {
   const value = String(status ?? "").toLowerCase();
@@ -24207,10 +24911,10 @@ function normalizeJobStatus(status) {
 }
 function createJobRecord(opts) {
   const now = opts.now ?? /* @__PURE__ */ new Date();
-  const projectDir = resolve5(
+  const projectDir = resolve6(
     opts.projectDir ?? findProjectRoot(opts.workingDirectory ?? process.cwd())
   );
-  const workingDirectory = resolve5(opts.workingDirectory ?? process.cwd());
+  const workingDirectory = resolve6(opts.workingDirectory ?? process.cwd());
   const id = opts.id ?? makeJobId(opts.providerTaskId, now);
   const base = {
     schemaVersion: "1",
@@ -24245,7 +24949,7 @@ function createJobRecord(opts) {
     message: opts.message
   };
   base.retryWith = retryWithForJob(base);
-  return stripUndefined(base);
+  return stripUndefined2(base);
 }
 async function createAndWriteJobRecord(opts) {
   const record = createJobRecord(opts);
@@ -24255,15 +24959,15 @@ async function createAndWriteJobRecord(opts) {
 async function writeJobRecord(record) {
   const dir = jobsDir(record.projectDir);
   await mkdir3(dir, { recursive: true });
-  await writeFile6(
+  await writeFile7(
     jobRecordPath(record.id, record.projectDir),
-    JSON.stringify(stripUndefined(record), null, 2) + "\n",
+    JSON.stringify(stripUndefined2(record), null, 2) + "\n",
     "utf-8"
   );
 }
 async function readJobRecord(jobId, projectDir) {
   const id = normalizeJobId(jobId);
-  const project = resolve5(projectDir ?? findProjectRoot());
+  const project = resolve6(projectDir ?? findProjectRoot());
   const path2 = jobRecordPath(id, project);
   if (!existsSync2(path2)) return null;
   return parseJobRecord(await readFile4(path2, "utf-8"));
@@ -24276,7 +24980,7 @@ async function listJobRecords(projectDir) {
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
     try {
-      const parsed = parseJobRecord(await readFile4(join2(dir, entry.name), "utf-8"));
+      const parsed = parseJobRecord(await readFile4(join3(dir, entry.name), "utf-8"));
       if (parsed) records.push(parsed);
     } catch {
     }
@@ -24370,9 +25074,9 @@ async function refreshLocalJobRecord(record, opts) {
     const heartbeatAge = record.heartbeatAt ? Date.now() - new Date(record.heartbeatAt).getTime() : Number.POSITIVE_INFINITY;
     const orphaned = !isPidAlive(record.pid) || heartbeatAge > LOCAL_JOB_ORPHAN_AFTER_MS;
     if (orphaned) {
-      const hint = `The process that ran this ${record.jobType} job is gone. Check ${join2(record.projectDir, record.jobType === "render" ? "render-report.json" : "build-report.json")} \u2014 the work may have completed before the process exited.`;
+      const hint = `The process that ran this ${record.jobType} job is gone. Check ${join3(record.projectDir, record.jobType === "render" ? "render-report.json" : "build-report.json")} \u2014 the work may have completed before the process exited.`;
       warnings.push(hint);
-      updated = stripUndefined({
+      updated = stripUndefined2({
         ...record,
         status: "unknown",
         error: record.error ?? hint,
@@ -24389,7 +25093,7 @@ async function refreshLocalJobRecord(record, opts) {
   });
 }
 async function inspectProjectStatus(projectDirArg, opts = {}) {
-  const project = resolve5(projectDirArg);
+  const project = resolve6(projectDirArg);
   const warnings = [];
   let records = await listJobRecords(project);
   if (opts.refresh) {
@@ -24419,6 +25123,10 @@ async function inspectProjectStatus(projectDirArg, opts = {}) {
     ...review?.retryWith ?? [],
     ...workflow.retryWith
   ];
+  const nextActions = normalizeReviewActions([
+    ...review?.nextActions ?? [],
+    ...reviewActionsFromRetryWith([...build?.retryWith ?? [], ...workflow.retryWith])
+  ]);
   return {
     schemaVersion: "1",
     kind: "project",
@@ -24430,11 +25138,12 @@ async function inspectProjectStatus(projectDirArg, opts = {}) {
     review,
     jobs,
     warnings,
+    nextActions,
     retryWith: unique(retryWith)
   };
 }
 function summarizeJob(record) {
-  return stripUndefined({
+  return stripUndefined2({
     id: record.id,
     jobType: record.jobType,
     status: record.status,
@@ -24458,7 +25167,7 @@ function retryWithForJob(record) {
   ]);
 }
 function makeJobStatusResult(record, opts) {
-  return stripUndefined({
+  return stripUndefined2({
     schemaVersion: "1",
     kind: "job",
     id: record.id,
@@ -24482,7 +25191,7 @@ function jobProgress(record) {
   if (record.status === "completed" || record.status === "failed" || record.status === "cancelled") {
     if (record.progress === void 0 && !record.providerStatus) return void 0;
   }
-  return stripUndefined({
+  return stripUndefined2({
     percent: record.progress,
     phase: record.stage ?? record.providerStatus ?? statusPhase(record.status),
     providerStatus: record.providerStatus ?? record.message
@@ -24492,7 +25201,7 @@ function jobResult(record) {
   if (!record.resultUrl && !record.outputPath && !record.cachePath && !record.error && !record.resultPayload) {
     return null;
   }
-  return stripUndefined({
+  return stripUndefined2({
     url: record.resultUrl,
     outputPath: record.outputPath,
     cachePath: record.cachePath,
@@ -24528,7 +25237,7 @@ function normalizeJobId(jobId) {
   return id;
 }
 function jobRecordPath(jobId, projectDir) {
-  return join2(jobsDir(projectDir), `${normalizeJobId(jobId)}.json`);
+  return join3(jobsDir(projectDir), `${normalizeJobId(jobId)}.json`);
 }
 function parseJobRecord(raw) {
   const parsed = JSON.parse(raw);
@@ -24553,11 +25262,11 @@ function updateRecordFromProvider(record, result) {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   next.retryWith = retryWithForJob(next);
-  return stripUndefined(next);
+  return stripUndefined2(next);
 }
 function resolveRefreshOutput(record, opts) {
-  if (opts.output) return resolve5(opts.workingDirectory ?? process.cwd(), opts.output);
-  return record.outputPath ? resolve5(record.outputPath) : void 0;
+  if (opts.output) return resolve6(opts.workingDirectory ?? process.cwd(), opts.output);
+  return record.outputPath ? resolve6(record.outputPath) : void 0;
 }
 function liveSupport(record) {
   if (record.jobType === "generate-video" && (record.provider === "grok" || record.provider === "runway" || record.provider === "kling" || record.provider === "veo")) {
@@ -24582,7 +25291,7 @@ async function downloadUrl(url, outputPath) {
   if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`);
   const buffer = Buffer.from(await response.arrayBuffer());
   await mkdir3(dirname3(outputPath), { recursive: true });
-  await writeFile6(outputPath, buffer);
+  await writeFile7(outputPath, buffer);
   return outputPath;
 }
 async function maybeCacheOutput(record) {
@@ -24614,7 +25323,7 @@ async function maybeWriteCompletedAssetMetadata(record) {
   }
 }
 async function refreshBuildReportFromJobs(projectDir, records) {
-  const reportPath = join2(projectDir, "build-report.json");
+  const reportPath = join3(projectDir, "build-report.json");
   const report = await readJson(reportPath);
   if (!report || !Array.isArray(report.beats)) return;
   let changed = false;
@@ -24642,7 +25351,7 @@ async function refreshBuildReportFromJobs(projectDir, records) {
       if (kind === "music" && record.assetOptions && typeof record.assetOptions.duration === "number") {
         nested.durationSec = record.assetOptions.duration;
       }
-      beatRecord[kind] = stripUndefined(nested);
+      beatRecord[kind] = stripUndefined2(nested);
       beatRecord[`${kind}Path`] = outputPath;
       beatRecord[`${kind}Status`] = "generated";
       beatRecord[`${kind}JobId`] = record.id;
@@ -24662,17 +25371,17 @@ async function refreshBuildReportFromJobs(projectDir, records) {
   }
   if (!changed) return;
   try {
-    await writeFile6(reportPath, JSON.stringify(stripUndefined(report), null, 2) + "\n", "utf-8");
+    await writeFile7(reportPath, JSON.stringify(stripUndefined2(report), null, 2) + "\n", "utf-8");
   } catch {
   }
 }
 async function readBuildSummary(projectDir) {
-  const reportPath = join2(projectDir, "build-report.json");
+  const reportPath = join3(projectDir, "build-report.json");
   const report = await readJson(reportPath);
   if (!report) return null;
   const info = await statOrNull(reportPath);
   const beatSummary = projectBeatReadinessFromUnknown(report.beatSummary);
-  return stripUndefined({
+  return stripUndefined2({
     reportPath,
     kind: typeof report.kind === "string" ? report.kind : void 0,
     success: typeof report.success === "boolean" ? report.success : void 0,
@@ -24690,7 +25399,7 @@ async function readBuildSummary(projectDir) {
   });
 }
 async function readReviewSummary(projectDir) {
-  const reportPath = join2(projectDir, "review-report.json");
+  const reportPath = join3(projectDir, "review-report.json");
   const report = await readJson(reportPath);
   if (!report) return null;
   const info = await statOrNull(reportPath);
@@ -24698,7 +25407,7 @@ async function readReviewSummary(projectDir) {
   const summary = report.summary && typeof report.summary === "object" ? report.summary : {};
   const fixOwners = summary.fixOwners && typeof summary.fixOwners === "object" ? summary.fixOwners : {};
   const computedFixOwners = countIssueFixOwners(issues);
-  return stripUndefined({
+  return stripUndefined2({
     reportPath,
     kind: typeof report.kind === "string" ? report.kind : void 0,
     mode: typeof report.mode === "string" ? report.mode : void 0,
@@ -24723,9 +25432,44 @@ async function readReviewSummary(projectDir) {
     },
     sourceReports: stringArray(report.sourceReports),
     updatedAt: info?.mtime.toISOString(),
+    nextActions: reviewActionsFromUnknown(report.nextActions),
     retryWith: stringArray(report.retryWith)
   });
 }
+function reviewActionsFromUnknown(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (!item || typeof item !== "object") return [];
+    const record = item;
+    const kind = stringEnum(record.kind, ["command", "agent", "manual"]);
+    const fixOwner = stringEnum(record.fixOwner, ["vibe", "host-agent"]);
+    const costTier = stringEnum(record.costTier, [
+      "free",
+      "low",
+      "high",
+      "very-high",
+      "unknown"
+    ]);
+    if (!kind || !fixOwner || !costTier || typeof record.id !== "string" || typeof record.label !== "string" || typeof record.safeToAutoRun !== "boolean" || typeof record.requiresConfirmation !== "boolean" || typeof record.reason !== "string") {
+      return [];
+    }
+    return [
+      stripUndefined2({
+        id: record.id,
+        kind,
+        label: record.label,
+        command: typeof record.command === "string" ? record.command : void 0,
+        agentPrompt: typeof record.agentPrompt === "string" ? record.agentPrompt : void 0,
+        fixOwner,
+        costTier,
+        safeToAutoRun: record.safeToAutoRun,
+        requiresConfirmation: record.requiresConfirmation,
+        reason: record.reason,
+        sourceIssueCodes: stringArray(record.sourceIssueCodes)
+      })
+    ];
+  });
+}
 function summarizeJobs(records) {
   return {
     total: records.length,
@@ -24744,7 +25488,7 @@ async function readProjectBeatReadiness(projectDir, build, records) {
     if (fromBeats) return fromBeats;
     if (build.beats) return augmentBeatReadinessFromJobs(build.beats, records, report?.jobs);
   }
-  const storyboardPath = join2(projectDir, "STORYBOARD.md");
+  const storyboardPath = join3(projectDir, "STORYBOARD.md");
   if (!existsSync2(storyboardPath)) {
     return { total: 0, assetsReady: 0, compositionsReady: 0, needsAuthor: [] };
   }
@@ -24753,7 +25497,7 @@ async function readProjectBeatReadiness(projectDir, build, records) {
     const needsAuthor = [];
     let compositionsReady = 0;
     for (const beat of parsed.beats) {
-      if (existsSync2(join2(projectDir, "compositions", `scene-${beat.id}.html`))) {
+      if (existsSync2(join3(projectDir, "compositions", `scene-${beat.id}.html`))) {
         compositionsReady += 1;
       } else {
         needsAuthor.push(beat.id);
@@ -24771,7 +25515,7 @@ async function readProjectBeatReadiness(projectDir, build, records) {
 }
 function deriveProjectWorkflow(opts) {
   const retryWith = [];
-  const hasStoryboard = existsSync2(join2(opts.project, "STORYBOARD.md"));
+  const hasStoryboard = existsSync2(join3(opts.project, "STORYBOARD.md"));
   if (!hasStoryboard && !opts.build) {
     retryWith.push(`vibe init ${opts.project} --from "<brief>" --json`);
     return { status: "empty", currentStage: "init", retryWith };
@@ -24867,7 +25611,7 @@ function beatReadinessFromBuildBeats(projectDir, beats, records = [], reportJobs
     if (buildBeatAssetsReady(record) || (id ? buildBeatJobsReady(id, records, reportJobs) : false))
       assetsReady += 1;
     const compositionPath = typeof record.compositionPath === "string" ? record.compositionPath : id ? `compositions/scene-${id}.html` : void 0;
-    if (compositionPath && existsSync2(resolve5(projectDir, compositionPath))) {
+    if (compositionPath && existsSync2(resolve6(projectDir, compositionPath))) {
       compositionsReady += 1;
     } else if (id) {
       needsAuthor.push(id);
@@ -24937,6 +25681,9 @@ function numberOr(fallback2, value) {
 function stringArray(value) {
   return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.length > 0) : [];
 }
+function stringEnum(value, allowed) {
+  return typeof value === "string" && allowed.includes(value) ? value : void 0;
+}
 function isActiveStatus(status) {
   return status === "queued" || status === "running";
 }
@@ -24966,7 +25713,7 @@ function assetKindForJob(record) {
   return void 0;
 }
 function projectRelativePath(projectDir, path2) {
-  const rel = relative(resolve5(projectDir), resolve5(path2));
+  const rel = relative(resolve6(projectDir), resolve6(path2));
   if (!rel || rel.startsWith("..")) return path2;
   return rel.replace(/\\/g, "/");
 }
@@ -24984,7 +25731,7 @@ async function statOrNull(path2) {
     return null;
   }
 }
-function stripUndefined(value) {
+function stripUndefined2(value) {
   return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0));
 }
 function unique(items) {
@@ -25002,6 +25749,7 @@ var init_status_jobs = __esm({
     init_ai_video();
     init_music_status();
     init_build_asset_metadata();
+    init_review_report();
     init_storyboard_parse();
     LOCAL_JOB_ORPHAN_AFTER_MS = 9e4;
   }
@@ -25010,7 +25758,7 @@ var init_status_jobs = __esm({
 // src/commands/_shared/project-config.ts
 import { existsSync as existsSync3 } from "node:fs";
 import { readFile as readFile5 } from "node:fs/promises";
-import { resolve as resolve6 } from "node:path";
+import { resolve as resolve7 } from "node:path";
 function defaultProjectConfig(opts) {
   return {
     schemaVersion: "1",
@@ -25061,9 +25809,9 @@ function projectConfigJson(opts) {
   return JSON.stringify(defaultProjectConfig(opts), null, 2) + "\n";
 }
 async function readProjectConfig(projectDir) {
-  const dir = resolve6(projectDir);
-  const canonicalPath = resolve6(dir, VIBE_CONFIG_FILENAME);
-  const legacyPath = resolve6(dir, LEGACY_VIBE_PROJECT_FILENAME);
+  const dir = resolve7(projectDir);
+  const canonicalPath = resolve7(dir, VIBE_CONFIG_FILENAME);
+  const legacyPath = resolve7(dir, LEGACY_VIBE_PROJECT_FILENAME);
   if (existsSync3(canonicalPath)) {
     try {
       const raw = await readFile5(canonicalPath, "utf-8");
@@ -25126,8 +25874,8 @@ var init_project_config = __esm({
 });
 
 // src/commands/_shared/scene-project.ts
-import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile7, access as access3 } from "node:fs/promises";
-import { resolve as resolve7, basename as basename2 } from "node:path";
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile8, access as access3 } from "node:fs/promises";
+import { resolve as resolve8, basename as basename2 } from "node:path";
 function aspectToDims(aspect) {
   return ASPECT_DIMS[aspect];
 }
@@ -25425,6 +26173,43 @@ vibe host setup all --write # write project/app config
 vibe host doctor all --json # verify readiness
 \`\`\`
 
+## Native host goal loop
+
+For long-running work, use Codex Goal mode, Claude Code \`/goal\`, or the
+host's equivalent as the outer loop. VibeFrame should not run a competing
+project-level goal loop; it provides \`--json\` commands, dry runs, cost caps,
+\`build-report.json\`, \`review-report.json\`, \`nextActions\`, \`safeToAutoRun\`,
+\`requiresConfirmation\`, \`fixOwner\`, deterministic repair, and render
+inspection for the host agent to reason over.
+
+Copy-paste examples:
+
+\`\`\`text
+/goal Build this VibeFrame project into renders/final.mp4. Use --json for every
+vibe command, run --dry-run before paid operations, use --max-cost 5 for builds
+unless the user sets another budget, read build-report.json and
+review-report.json before deciding the next action, prefer nextActions before
+guessing, run only safeToAutoRun:true actions automatically, and ask before
+requiresConfirmation:true actions. Treat retryWith as the compatibility
+fallback, fixOwner:"vibe" as CLI repair work, and fixOwner:"host-agent" as
+STORYBOARD.md, DESIGN.md, or composition edits.
+Stop only when renders/final.mp4 exists, duration and aspect ratio match the
+brief, inspect render --cheap has no errors, any AI review score is >= 90 when AI review is requested, and every
+remaining host-agent issue is fixed, accepted with rationale, or reported as
+blocked.
+\`\`\`
+
+\`\`\`text
+/goal Finish this VibeFrame render using Claude Code goal mode as the outer
+loop. Use vibe context/schema when unsure, --json everywhere, dry-run before
+paid operations, budget cap via --max-cost 5, nextActions before guessing,
+build-report.json/review-report.json as loop state, and safeToAutoRun,
+requiresConfirmation, and fixOwner to decide between vibe scene repair and
+host-agent edits. Stop only after final MP4,
+target duration/aspect ratio, clean render inspection, any AI review score >= 90 when AI review is requested, and
+no unresolved unacknowledged host-agent issues.
+\`\`\`
+
 ## Skills \u2014 USE THESE FIRST
 
 @SKILL.md
@@ -25528,35 +26313,35 @@ tmp/
 `;
 }
 function describeSceneScaffold(opts) {
-  const dir = resolve7(opts.dir);
+  const dir = resolve8(opts.dir);
   const profile = opts.profile ?? "full";
   const groups = {
     authoring: [
-      resolve7(dir, "STORYBOARD.md"),
-      resolve7(dir, "DESIGN.md"),
-      resolve7(dir, VIBE_CONFIG_FILENAME),
-      resolve7(dir, "vibe.project.yaml"),
-      resolve7(dir, ".gitignore")
+      resolve8(dir, "STORYBOARD.md"),
+      resolve8(dir, "DESIGN.md"),
+      resolve8(dir, VIBE_CONFIG_FILENAME),
+      resolve8(dir, "vibe.project.yaml"),
+      resolve8(dir, ".gitignore")
     ],
     render: [],
     agent: []
   };
   if (profile === "full") {
     groups.render = [
-      resolve7(dir, "index.html"),
-      resolve7(dir, "compositions"),
-      resolve7(dir, "assets"),
-      resolve7(dir, "renders"),
-      resolve7(dir, "hyperframes.json"),
-      resolve7(dir, "meta.json")
+      resolve8(dir, "index.html"),
+      resolve8(dir, "compositions"),
+      resolve8(dir, "assets"),
+      resolve8(dir, "renders"),
+      resolve8(dir, "hyperframes.json"),
+      resolve8(dir, "meta.json")
     ];
   }
   if (profile === "agent" || profile === "full") {
     groups.agent = [
-      resolve7(dir, "AGENTS.md"),
-      resolve7(dir, "SKILL.md"),
-      resolve7(dir, "references"),
-      resolve7(dir, "CLAUDE.md")
+      resolve8(dir, "AGENTS.md"),
+      resolve8(dir, "SKILL.md"),
+      resolve8(dir, "references"),
+      resolve8(dir, "CLAUDE.md")
     ];
   }
   return groups;
@@ -25570,7 +26355,7 @@ async function pathExists(p) {
   }
 }
 async function scaffoldSceneProject(opts) {
-  const dir = resolve7(opts.dir);
+  const dir = resolve8(opts.dir);
   const name = opts.name ?? basename2(dir);
   const aspect = opts.aspect ?? "16:9";
   const duration = opts.duration ?? 10;
@@ -25578,103 +26363,103 @@ async function scaffoldSceneProject(opts) {
   const profile = opts.profile ?? "full";
   await mkdir4(dir, { recursive: true });
   if (profile === "full") {
-    await mkdir4(resolve7(dir, "compositions"), { recursive: true });
-    await mkdir4(resolve7(dir, "assets"), { recursive: true });
-    await mkdir4(resolve7(dir, "renders"), { recursive: true });
+    await mkdir4(resolve8(dir, "compositions"), { recursive: true });
+    await mkdir4(resolve8(dir, "assets"), { recursive: true });
+    await mkdir4(resolve8(dir, "renders"), { recursive: true });
   }
   const created = [];
   const skipped2 = [];
   const merged = [];
   if (profile === "full") {
-    const hfPath = resolve7(dir, "hyperframes.json");
+    const hfPath = resolve8(dir, "hyperframes.json");
     const hfDefaults = buildHyperframesConfig();
     if (await pathExists(hfPath)) {
       const existingRaw = await readFile6(hfPath, "utf-8");
       const existing = JSON.parse(existingRaw);
       const mergedConfig = mergeHyperframesConfig(existing, hfDefaults);
-      await writeFile7(hfPath, JSON.stringify(mergedConfig, null, 2) + "\n", "utf-8");
+      await writeFile8(hfPath, JSON.stringify(mergedConfig, null, 2) + "\n", "utf-8");
       merged.push(hfPath);
     } else {
-      await writeFile7(hfPath, JSON.stringify(hfDefaults, null, 2) + "\n", "utf-8");
+      await writeFile8(hfPath, JSON.stringify(hfDefaults, null, 2) + "\n", "utf-8");
       created.push(hfPath);
     }
-    const metaPath = resolve7(dir, "meta.json");
+    const metaPath = resolve8(dir, "meta.json");
     if (await pathExists(metaPath)) {
       skipped2.push(metaPath);
     } else {
-      await writeFile7(
+      await writeFile8(
         metaPath,
         JSON.stringify(buildHyperframesMeta(name, now), null, 2) + "\n",
         "utf-8"
       );
       created.push(metaPath);
     }
-    const rootPath = resolve7(dir, "index.html");
+    const rootPath = resolve8(dir, "index.html");
     if (await pathExists(rootPath)) {
       skipped2.push(rootPath);
     } else {
-      await writeFile7(rootPath, buildEmptyRootHtml({ aspect, duration }), "utf-8");
+      await writeFile8(rootPath, buildEmptyRootHtml({ aspect, duration }), "utf-8");
       created.push(rootPath);
     }
   }
-  const vibeConfigJsonPath = resolve7(dir, VIBE_CONFIG_FILENAME);
+  const vibeConfigJsonPath = resolve8(dir, VIBE_CONFIG_FILENAME);
   if (await pathExists(vibeConfigJsonPath)) {
     skipped2.push(vibeConfigJsonPath);
   } else {
-    await writeFile7(vibeConfigJsonPath, projectConfigJson({ name, aspect }), "utf-8");
+    await writeFile8(vibeConfigJsonPath, projectConfigJson({ name, aspect }), "utf-8");
     created.push(vibeConfigJsonPath);
   }
-  const vibePath = resolve7(dir, "vibe.project.yaml");
+  const vibePath = resolve8(dir, "vibe.project.yaml");
   if (await pathExists(vibePath)) {
     skipped2.push(vibePath);
   } else {
     const cfg = { ...defaultVibeProjectConfig(name), aspect };
-    await writeFile7(vibePath, (0, import_yaml4.stringify)(cfg), "utf-8");
+    await writeFile8(vibePath, (0, import_yaml4.stringify)(cfg), "utf-8");
     created.push(vibePath);
   }
   if (profile === "agent" || profile === "full") {
-    const agentsPath = resolve7(dir, "AGENTS.md");
+    const agentsPath = resolve8(dir, "AGENTS.md");
     if (await pathExists(agentsPath)) {
       skipped2.push(agentsPath);
     } else {
-      await writeFile7(agentsPath, buildProjectAgentsMd(name), "utf-8");
+      await writeFile8(agentsPath, buildProjectAgentsMd(name), "utf-8");
       created.push(agentsPath);
     }
-    const claudePath = resolve7(dir, "CLAUDE.md");
+    const claudePath = resolve8(dir, "CLAUDE.md");
     if (await pathExists(claudePath)) {
       const existing = await readFile6(claudePath, "utf-8");
       if (existing.includes("@AGENTS.md")) {
         skipped2.push(claudePath);
       } else {
-        await writeFile7(claudePath, `@AGENTS.md
+        await writeFile8(claudePath, `@AGENTS.md
 
 ${existing}`, "utf-8");
         merged.push(claudePath);
       }
     } else {
-      await writeFile7(claudePath, buildProjectClaudeMd(name), "utf-8");
+      await writeFile8(claudePath, buildProjectClaudeMd(name), "utf-8");
       created.push(claudePath);
     }
   }
-  const designPath = resolve7(dir, "DESIGN.md");
+  const designPath = resolve8(dir, "DESIGN.md");
   if (await pathExists(designPath)) {
     skipped2.push(designPath);
   } else {
-    await writeFile7(designPath, buildDesignMd({ name, style: opts.visualStyle }), "utf-8");
+    await writeFile8(designPath, buildDesignMd({ name, style: opts.visualStyle }), "utf-8");
     created.push(designPath);
   }
-  const storyboardPath = resolve7(dir, "STORYBOARD.md");
+  const storyboardPath = resolve8(dir, "STORYBOARD.md");
   if (await pathExists(storyboardPath)) {
     skipped2.push(storyboardPath);
   } else {
-    await writeFile7(storyboardPath, buildStoryboardMd(name, duration), "utf-8");
+    await writeFile8(storyboardPath, buildStoryboardMd(name, duration), "utf-8");
     created.push(storyboardPath);
   }
-  const gitignorePath = resolve7(dir, ".gitignore");
+  const gitignorePath = resolve8(dir, ".gitignore");
   if (await pathExists(gitignorePath)) {
     skipped2.push(gitignorePath);
   } else {
-    await writeFile7(gitignorePath, buildSceneGitignore(), "utf-8");
+    await writeFile8(gitignorePath, buildSceneGitignore(), "utf-8");
     created.push(gitignorePath);
   }
   return { created, skipped: skipped2, merged, groups: describeSceneScaffold({ dir, profile }) };
@@ -28713,10 +29498,22 @@ var init_esm = __esm({
 
 // src/commands/_shared/tts-resolve.ts
 async function resolveTtsProvider(preferred = "auto") {
-  const choice = preferred === "auto" ? await getConfiguredApiKey("ELEVENLABS_API_KEY") ? "elevenlabs" : "kokoro" : preferred;
+  let choice = preferred;
+  if (choice === "auto") {
+    if (await getConfiguredApiKey("ELEVENLABS_API_KEY")) {
+      choice = "elevenlabs";
+    } else if (await getConfiguredApiKey("OPENAI_API_KEY")) {
+      choice = "openai";
+    } else {
+      choice = "kokoro";
+    }
+  }
   if (choice === "elevenlabs") {
     return buildElevenLabs();
   }
+  if (choice === "openai") {
+    return buildOpenAi();
+  }
   return buildKokoro();
 }
 async function buildElevenLabs() {
@@ -28732,6 +29529,19 @@ async function buildElevenLabs() {
   });
   return { provider: "elevenlabs", audioExtension: "mp3", call };
 }
+async function buildOpenAi() {
+  const key = await getApiKey("OPENAI_API_KEY", "OpenAI");
+  if (!key) {
+    throw new TtsKeyMissingError("openai");
+  }
+  const provider = new OpenAiTtsProvider();
+  await provider.initialize({ apiKey: key });
+  const call = async (text, opts) => provider.textToSpeech(text, {
+    voice: opts?.voice,
+    speed: opts?.speed
+  });
+  return { provider: "openai", audioExtension: "mp3", call };
+}
 async function buildKokoro() {
   const provider = new KokoroProvider();
   await provider.initialize({});
@@ -28744,11 +29554,11 @@ async function buildKokoro() {
 }
 function parseTtsProviderName(value) {
   if (!value) return "auto";
-  if (value === "auto" || value === "elevenlabs" || value === "kokoro") {
+  if (value === "auto" || value === "elevenlabs" || value === "openai" || value === "kokoro") {
     return value;
   }
   throw new Error(
-    `Invalid --tts: ${value}. Valid: auto, elevenlabs, kokoro.`
+    `Invalid --tts: ${value}. Valid: auto, elevenlabs, openai, kokoro.`
   );
 }
 var TtsKeyMissingError;
@@ -28760,7 +29570,7 @@ var init_tts_resolve = __esm({
     TtsKeyMissingError = class extends Error {
       constructor(provider) {
         super(
-          provider === "elevenlabs" ? "ElevenLabs API key required (ELEVENLABS_API_KEY). Run 'vibe setup', set ELEVENLABS_API_KEY in .env, or pass --tts kokoro for local synthesis." : `Provider ${provider} is unavailable.`
+          provider === "elevenlabs" ? "ElevenLabs API key required (ELEVENLABS_API_KEY). Run 'vibe setup', set ELEVENLABS_API_KEY in .env, or pass --tts kokoro for local synthesis." : provider === "openai" ? "OpenAI API key required (OPENAI_API_KEY). Run 'vibe setup', set OPENAI_API_KEY in .env, or pass --tts kokoro for local synthesis." : `Provider ${provider} is unavailable.`
         );
         this.provider = provider;
         this.name = "TtsKeyMissingError";
@@ -28806,17 +29616,17 @@ var init_cost_tier = __esm({
 });
 
 // src/commands/_shared/scene-lint.ts
-import { readdir as readdir2, readFile as readFile7, writeFile as writeFile8, stat as stat2 } from "node:fs/promises";
+import { readdir as readdir2, readFile as readFile7, writeFile as writeFile9, stat as stat2 } from "node:fs/promises";
 import { existsSync as existsSync4 } from "node:fs";
-import { resolve as resolve8, relative as relative2, join as join3 } from "node:path";
+import { resolve as resolve9, relative as relative2, join as join4 } from "node:path";
 import {
   runHyperframeLint
 } from "@hyperframes/producer";
 async function discoverSceneFiles(opts) {
-  const projectDir = resolve8(opts.projectDir);
-  const rootAbs = resolve8(projectDir, opts.rootRel ?? "index.html");
+  const projectDir = resolve9(opts.projectDir);
+  const rootAbs = resolve9(projectDir, opts.rootRel ?? "index.html");
   const root = existsSync4(rootAbs) ? rootAbs : null;
-  const compsDir = resolve8(projectDir, "compositions");
+  const compsDir = resolve9(projectDir, "compositions");
   const subs = [];
   if (existsSync4(compsDir)) {
     await collectHtmlRecursive(compsDir, subs);
@@ -28827,7 +29637,7 @@ async function discoverSceneFiles(opts) {
 async function collectHtmlRecursive(dir, into) {
   const entries = await readdir2(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const full = join3(dir, entry.name);
+    const full = join4(dir, entry.name);
     if (entry.isDirectory()) {
       await collectHtmlRecursive(full, into);
     } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".html")) {
@@ -28902,7 +29712,7 @@ function addClipClassToTimedElements(html) {
   });
 }
 async function runProjectLint(opts) {
-  const projectDir = resolve8(opts.projectDir);
+  const projectDir = resolve9(opts.projectDir);
   const { root, subs } = await discoverSceneFiles({ projectDir, rootRel: opts.rootRel });
   const files = [];
   const fixed = [];
@@ -28926,7 +29736,7 @@ async function runProjectLint(opts) {
     if (opts.fix && findings.length > 0) {
       const { html: nextHtml, fixedCodes } = applyMechanicalFixes(html, findings);
       if (fixedCodes.length > 0) {
-        await writeFile8(abs, nextHtml, "utf-8");
+        await writeFile9(abs, nextHtml, "utf-8");
         fixed.push({ file: rel, codes: fixedCodes });
         const reLinted = runHyperframeLint({ ...prepared, html: nextHtml });
         files.push({
@@ -28963,7 +29773,7 @@ async function runProjectLint(opts) {
   };
 }
 async function rootExists(projectDir, rootRel = "index.html") {
-  const abs = resolve8(projectDir, rootRel);
+  const abs = resolve9(projectDir, rootRel);
   try {
     const s = await stat2(abs);
     return s.isFile();
@@ -28986,7 +29796,7 @@ var init_scene_lint = __esm({
 // src/utils/agent-host-detect.ts
 import { existsSync as existsSync5 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 function detectAgentHosts(env2 = process.env) {
   const home = homedir3();
   return [
@@ -29046,7 +29856,7 @@ function detectAgentHosts(env2 = process.env) {
     }
     const configDirRel = HOST_CONFIG_DIRS[host.id];
     if (configDirRel) {
-      const path2 = join4(home, configDirRel);
+      const path2 = join5(home, configDirRel);
       if (existsSync5(path2)) {
         signals2.push({ kind: "configDir", path: path2 });
       }
@@ -29071,8 +29881,8 @@ function isOnPath(binary, env2) {
   const sep2 = process.platform === "win32" ? ";" : ":";
   for (const dir of path2.split(sep2)) {
     if (!dir) continue;
-    if (existsSync5(join4(dir, binary))) return true;
-    if (process.platform === "win32" && existsSync5(join4(dir, `${binary}.exe`))) return true;
+    if (existsSync5(join5(dir, binary))) return true;
+    if (process.platform === "win32" && existsSync5(join5(dir, `${binary}.exe`))) return true;
   }
   return false;
 }
@@ -29909,11 +30719,11 @@ Avoid transitions that create visible repeating geometric patterns \u2014 grids
 
 // src/commands/_shared/hf-skill-bundle/bundle.ts
 import { readFileSync as readFileSync2, existsSync as existsSync6, statSync as statSync2 } from "node:fs";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 import { homedir as homedir4 } from "node:os";
 import { createHash as createHash3 } from "node:crypto";
 function installedSkillPath() {
-  const candidate = join5(homedir4(), ".claude", "skills", "hyperframes");
+  const candidate = join6(homedir4(), ".claude", "skills", "hyperframes");
   if (!existsSync6(candidate)) return null;
   if (!statSync2(candidate).isDirectory()) return null;
   return candidate;
@@ -29933,11 +30743,11 @@ function buildVendored() {
 }
 function buildInstalled(skillRoot) {
   const installedPaths = {
-    "hyperframes/SKILL.md": join5(skillRoot, "SKILL.md"),
-    "hyperframes/house-style.md": join5(skillRoot, "house-style.md"),
-    "hyperframes/motion-principles.md": join5(skillRoot, "references", "motion-principles.md"),
-    "hyperframes/typography.md": join5(skillRoot, "references", "typography.md"),
-    "hyperframes/transitions.md": join5(skillRoot, "references", "transitions.md")
+    "hyperframes/SKILL.md": join6(skillRoot, "SKILL.md"),
+    "hyperframes/house-style.md": join6(skillRoot, "house-style.md"),
+    "hyperframes/motion-principles.md": join6(skillRoot, "references", "motion-principles.md"),
+    "hyperframes/typography.md": join6(skillRoot, "references", "typography.md"),
+    "hyperframes/transitions.md": join6(skillRoot, "references", "transitions.md")
   };
   const sections = [];
   for (const [label, path2] of Object.entries(installedPaths)) {
@@ -29991,12 +30801,12 @@ var init_bundle = __esm({
 
 // src/commands/_shared/root-sync.ts
 import { existsSync as existsSync8 } from "node:fs";
-import { readFile as readFile8, writeFile as writeFile10 } from "node:fs/promises";
-import { join as join7, resolve as resolve10 } from "node:path";
+import { readFile as readFile8, writeFile as writeFile11 } from "node:fs/promises";
+import { join as join8, resolve as resolve11 } from "node:path";
 async function createRootSyncPlan(opts) {
-  const projectDir = resolve10(opts.projectDir);
+  const projectDir = resolve11(opts.projectDir);
   const rootRel = opts.rootRel ?? "index.html";
-  const rootPath = resolve10(projectDir, rootRel);
+  const rootPath = resolve11(projectDir, rootRel);
   if (!existsSync8(rootPath)) {
     return { rootPath, rootRel, exists: false, changed: false, fixCodes: [], issues: [] };
   }
@@ -30054,12 +30864,12 @@ async function createProjectRootSyncPlan(opts) {
 }
 async function syncRootComposition(opts) {
   const plan = await createRootSyncPlan(opts);
-  if (plan.nextHtml) await writeFile10(plan.rootPath, plan.nextHtml, "utf-8");
+  if (plan.nextHtml) await writeFile11(plan.rootPath, plan.nextHtml, "utf-8");
   return plan;
 }
 async function loadProjectRootSyncBeats(projectDir) {
-  const root = resolve10(projectDir);
-  const storyboardPath = join7(root, "STORYBOARD.md");
+  const root = resolve11(projectDir);
+  const storyboardPath = join8(root, "STORYBOARD.md");
   if (!existsSync8(storyboardPath)) return [];
   const parsed = parseStoryboard(await readFile8(storyboardPath, "utf-8"));
   const reportBeats = await readBuildReportBeats(root);
@@ -30128,14 +30938,14 @@ async function resolveSyncedBeatDuration(opts) {
   if (!opts.narrationPath) return Number((reported ?? storyboardMin).toFixed(2));
   const probe = opts.probeAudioDuration ?? getAudioDuration;
   try {
-    const audioDuration = await probe(join7(opts.projectDir, opts.narrationPath));
+    const audioDuration = await probe(join8(opts.projectDir, opts.narrationPath));
     return Number(Math.max(storyboardMin, reported ?? 0, audioDuration + 0.5).toFixed(2));
   } catch {
     return Number(Math.max(storyboardMin, reported ?? 0).toFixed(2));
   }
 }
 async function resolveProjectBeatDurations(projectDir) {
-  const root = resolve10(projectDir);
+  const root = resolve11(projectDir);
   const beats = await loadProjectRootSyncBeats(root);
   const durations = /* @__PURE__ */ new Map();
   for (const beat of beats) {
@@ -30266,7 +31076,7 @@ function hasExpectedAudioRef(html, ref) {
   return ref.volume === void 0 || tag.includes(`data-volume="${ref.volume}"`);
 }
 async function readBuildReportBeats(projectDir) {
-  const reportPath = join7(projectDir, "build-report.json");
+  const reportPath = join8(projectDir, "build-report.json");
   if (!existsSync8(reportPath)) return [];
   try {
     const report = JSON.parse(await readFile8(reportPath, "utf-8"));
@@ -30276,7 +31086,7 @@ async function readBuildReportBeats(projectDir) {
   }
 }
 function firstExisting(projectDir, rels) {
-  return rels.find((rel) => existsSync8(join7(projectDir, rel)));
+  return rels.find((rel) => existsSync8(join8(projectDir, rel)));
 }
 function stringOrUndefined(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
@@ -30387,8 +31197,8 @@ import OpenAI from "openai";
 import { GoogleGenerativeAI } from "@google/generative-ai";
 import { createHash as createHash4 } from "node:crypto";
 import { existsSync as existsSync9, mkdirSync } from "node:fs";
-import { mkdir as mkdir6, readFile as readFile9, writeFile as writeFile11 } from "node:fs/promises";
-import { dirname as dirname5, join as join8, resolve as resolve11 } from "node:path";
+import { mkdir as mkdir6, readFile as readFile9, writeFile as writeFile12 } from "node:fs/promises";
+import { dirname as dirname5, join as join9, resolve as resolve12 } from "node:path";
 import { runHyperframeLint as runHyperframeLint2 } from "@hyperframes/producer";
 function buildSystemPrompt(ctx) {
   return `You are a Hyperframes composition author. The skill content below
@@ -30482,7 +31292,15 @@ ${finalDurationBullet}
   itself. For multi-phase beats, drive phase changes with GSAP \`autoAlpha\`
   inside full-window clips: animate phase A out (\`autoAlpha: 0\`), then
   phase B in, on the same timeline.
-- If \`assets/backdrop-${ctx.beat.id}.png\` exists, use that local file as the
+- If \`assets/video-${ctx.beat.id}.mp4\` exists, it is an AI-generated clip for
+  this beat \u2014 use it as the FULL-FRAME visual and prefer it over any backdrop
+  image or CSS. Put one full-bleed \`<video>\` inside a full-window \`.clip\`:
+  \`<video src="assets/video-${ctx.beat.id}.mp4" data-start="0" data-duration="${BEAT_DURATION}" data-media-start="0" muted playsinline style="width:100%;height:100%;object-fit:cover"></video>\`
+  Use the exact path (no \`./\` or \`../\`). The framework seeks the clip to each
+  timeline frame, so do NOT add transform tweens to the \`<video>\` or its
+  ancestors; layer text/motion graphics on top instead.
+- If \`assets/backdrop-${ctx.beat.id}.png\` exists (and no video clip above),
+  use that local file as the
   full-frame visual backdrop. The exact path string is
   \`assets/backdrop-${ctx.beat.id}.png\`; do NOT prefix it with \`../\` or \`./\`
   because fragments are mounted from the project root.
@@ -30589,7 +31407,7 @@ function computeCacheKey(parts) {
   return createHash4("sha256").update(parts.provider).update("\u241E").update(parts.model).update("\u241E").update(parts.systemPrompt).update("\u241E").update(parts.userPrompt).digest("hex");
 }
 function defaultCacheDir() {
-  return join8(USER_CACHE_DIR, "compose-scenes");
+  return join9(USER_CACHE_DIR, "compose-scenes");
 }
 function extractHtml(responseText) {
   const fenced = responseText.match(/```html\s*\n([\s\S]*?)\n```/);
@@ -30613,7 +31431,7 @@ async function composeBeatHtml(ctx, overrides) {
     model: settings.model
   });
   const cacheDir = ctx.cacheDir ?? defaultCacheDir();
-  const cachePath = join8(cacheDir, `${cacheKey}.html`);
+  const cachePath = join9(cacheDir, `${cacheKey}.html`);
   if (existsSync9(cachePath)) {
     const html2 = await readFile9(cachePath, "utf-8");
     return { html: html2, cached: true, cacheKey, model: settings.model, provider: ctx.provider };
@@ -30649,7 +31467,7 @@ async function composeBeatHtml(ctx, overrides) {
   const html = extractHtml(result.text);
   try {
     mkdirSync(cacheDir, { recursive: true });
-    await writeFile11(cachePath, html, "utf-8");
+    await writeFile12(cachePath, html, "utf-8");
   } catch {
   }
   const costUsd = result.inputTokens / 1e6 * settings.costPerMTokIn + result.outputTokens / 1e6 * settings.costPerMTokOut;
@@ -30748,9 +31566,9 @@ async function resolveComposerConfigAware(explicit, cwd) {
   return resolveComposer();
 }
 async function executeComposeScenesWithSkills(params, outputDir, overrides) {
-  const projectRoot = params.project ? resolve11(outputDir, params.project) : resolve11(outputDir);
-  const designPath = resolve11(projectRoot, params.design ?? "DESIGN.md");
-  const storyboardPath = resolve11(projectRoot, params.storyboard ?? "STORYBOARD.md");
+  const projectRoot = params.project ? resolve12(outputDir, params.project) : resolve12(outputDir);
+  const designPath = resolve12(projectRoot, params.design ?? "DESIGN.md");
+  const storyboardPath = resolve12(projectRoot, params.storyboard ?? "STORYBOARD.md");
   if (!existsSync9(designPath)) {
     return { success: false, error: `DESIGN.md not found at ${designPath}` };
   }
@@ -30778,7 +31596,7 @@ async function executeComposeScenesWithSkills(params, outputDir, overrides) {
     provider = params.composer ?? "claude";
     apiKey = "";
   }
-  const compositionsDir = join8(projectRoot, "compositions");
+  const compositionsDir = join9(projectRoot, "compositions");
   await mkdir6(compositionsDir, { recursive: true });
   let finalDurations = /* @__PURE__ */ new Map();
   try {
@@ -30806,9 +31624,9 @@ async function executeComposeScenesWithSkills(params, outputDir, overrides) {
           },
           overrides
         );
-        const compositionPath = join8(compositionsDir, `scene-${beat.id}.html`);
+        const compositionPath = join9(compositionsDir, `scene-${beat.id}.html`);
         await mkdir6(dirname5(compositionPath), { recursive: true });
-        await writeFile11(compositionPath, result.html, "utf-8");
+        await writeFile12(compositionPath, result.html, "utf-8");
         if (result.cached) {
           onProgress({
             type: "beat-cached",
@@ -31007,13 +31825,13 @@ var init_compose_scenes_skills = __esm({
 // src/commands/_shared/compose-prompts.ts
 import { existsSync as existsSync10 } from "node:fs";
 import { readFile as readFile10 } from "node:fs/promises";
-import { join as join9, relative as relative4, resolve as resolve12 } from "node:path";
+import { join as join10, relative as relative4, resolve as resolve13 } from "node:path";
 async function getComposePrompts(opts) {
-  const projectDir = resolve12(opts.projectDir);
-  const designPath = join9(projectDir, "DESIGN.md");
-  const storyboardPath = join9(projectDir, "STORYBOARD.md");
-  const skillPath = join9(projectDir, "SKILL.md");
-  const compositionsDir = join9(projectDir, "compositions");
+  const projectDir = resolve13(opts.projectDir);
+  const designPath = join10(projectDir, "DESIGN.md");
+  const storyboardPath = join10(projectDir, "STORYBOARD.md");
+  const skillPath = join10(projectDir, "SKILL.md");
+  const compositionsDir = join10(projectDir, "compositions");
   const warnings = [];
   const baseError = (msg) => ({
     success: false,
@@ -31062,7 +31880,7 @@ async function getComposePrompts(opts) {
   } catch {
   }
   const result = beats.map((beat) => {
-    const outputPathAbs = join9(compositionsDir, `scene-${beat.id}.html`);
+    const outputPathAbs = join10(compositionsDir, `scene-${beat.id}.html`);
     const outputPathRel = relative4(projectDir, outputPathAbs);
     const finalDurationSec = finalDurations.get(beat.id);
     const userPrompt = buildUserPrompt({
@@ -31136,7 +31954,7 @@ var init_compose_prompts = __esm({
 // src/commands/_shared/sub-comp-duration-sync.ts
 import { existsSync as existsSync12 } from "node:fs";
 import { readFile as readFile12 } from "node:fs/promises";
-import { join as join11, resolve as resolve14 } from "node:path";
+import { join as join12, resolve as resolve15 } from "node:path";
 function syncSubCompositionDurationHtml(html, beatId, newDurationSec, fileRel) {
   const compositionId = `scene-${beatId}`;
   const file = fileRel ?? `compositions/${compositionId}.html`;
@@ -31224,11 +32042,11 @@ function rewriteTimelineConst(html, oldDurationSec, newDurationSec) {
   return { html, rewritten: false, needsManualFix };
 }
 async function createSubCompDurationSyncPlans(opts) {
-  const projectDir = resolve14(opts.projectDir);
+  const projectDir = resolve15(opts.projectDir);
   const results = [];
   for (const beat of opts.beats) {
     const fileRel = `compositions/scene-${beat.id}.html`;
-    const filePath = join11(projectDir, fileRel);
+    const filePath = join12(projectDir, fileRel);
     if (!existsSync12(filePath)) continue;
     const newDurationSec = await resolveSyncedBeatDuration({
       projectDir,
@@ -31259,88 +32077,6 @@ var init_sub_comp_duration_sync = __esm({
   }
 });
 
-// src/commands/_shared/review-report.ts
-import { writeFile as writeFile13 } from "node:fs/promises";
-import { join as join12, resolve as resolve15 } from "node:path";
-function statusFromIssues(issues) {
-  if (issues.some((issue) => issue.severity === "error")) return "fail";
-  if (issues.some((issue) => issue.severity === "warning")) return "warn";
-  return "pass";
-}
-function scoreIssues(issues) {
-  let score = 100;
-  for (const issue of issues) {
-    if (issue.severity === "error") score -= 25;
-    else if (issue.severity === "warning") score -= 8;
-    else score -= 2;
-  }
-  return Math.max(0, Math.min(100, score));
-}
-function uniqueRetryWith(items) {
-  return [
-    ...new Set(items.filter((item) => typeof item === "string" && item.length > 0))
-  ];
-}
-function fixOwnerForIssue(issue) {
-  if (issue.fixOwner) return issue.fixOwner;
-  if (issue.code.startsWith("AI_REVIEW_")) return "host-agent";
-  if (issue.code.startsWith("STORYBOARD_")) return "host-agent";
-  if (issue.code === "PROJECT_NOT_FOUND" || issue.code === "MISSING_STORYBOARD" || issue.code === "BEAT_NOT_FOUND" || issue.code === "MISSING_DESIGN") {
-    return "host-agent";
-  }
-  return "vibe";
-}
-function normalizeReviewIssues(issues, fallbackOwner) {
-  return issues.map((issue) => ({
-    ...issue,
-    fixOwner: issue.fixOwner ?? fallbackOwner ?? fixOwnerForIssue(issue)
-  }));
-}
-function summarizeReviewIssues(issues) {
-  const normalized = normalizeReviewIssues(issues);
-  return {
-    issueCount: normalized.length,
-    errorCount: normalized.filter((issue) => issue.severity === "error").length,
-    warningCount: normalized.filter((issue) => issue.severity === "warning").length,
-    infoCount: normalized.filter((issue) => issue.severity === "info").length,
-    fixOwners: {
-      vibe: normalized.filter((issue) => issue.fixOwner === "vibe").length,
-      hostAgent: normalized.filter((issue) => issue.fixOwner === "host-agent").length
-    }
-  };
-}
-function buildReviewReport(opts) {
-  const issues = normalizeReviewIssues(opts.issues);
-  return stripUndefined2({
-    schemaVersion: "1",
-    kind: "review",
-    project: resolve15(opts.project),
-    mode: opts.mode,
-    beat: opts.beat,
-    status: opts.status,
-    score: opts.score,
-    issues,
-    summary: summarizeReviewIssues(issues),
-    retryWith: uniqueRetryWith(opts.retryWith),
-    sourceReports: opts.sourceReports ?? [],
-    reportPath: opts.reportPath
-  });
-}
-function defaultReviewReportPath(projectDir) {
-  return join12(resolve15(projectDir), "review-report.json");
-}
-async function writeReviewReport(path2, report) {
-  await writeFile13(path2, JSON.stringify(report, null, 2) + "\n", "utf-8");
-}
-function stripUndefined2(value) {
-  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0));
-}
-var init_review_report = __esm({
-  "src/commands/_shared/review-report.ts"() {
-    "use strict";
-  }
-});
-
 // src/commands/_shared/scene-repair.ts
 import { readFile as readFile13, writeFile as writeFile14 } from "node:fs/promises";
 import { relative as relative5, resolve as resolve16 } from "node:path";
@@ -31467,6 +32203,297 @@ var init_scene_repair = __esm({
   }
 });
 
+// src/commands/_shared/storyboard-edit.ts
+function validateStoryboardMarkdown(markdown) {
+  const parsed = parseStoryboard(markdown);
+  const sections = splitBeatSections(markdown);
+  const issues = [];
+  if (parsed.beats.length === 0) {
+    issues.push({
+      severity: "error",
+      code: "NO_BEATS",
+      message: "STORYBOARD.md must contain at least one `## Beat ...` heading."
+    });
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const beat of parsed.beats) {
+    seen.set(beat.id, (seen.get(beat.id) ?? 0) + 1);
+  }
+  for (const [id, count] of seen.entries()) {
+    if (count > 1) {
+      issues.push({
+        severity: "error",
+        code: "DUPLICATE_BEAT_ID",
+        beatId: id,
+        message: `Beat id "${id}" appears ${count} times. Beat ids must be unique.`
+      });
+    }
+  }
+  for (const section of sections) {
+    const cueBlock = readLeadingCueBlock(section.body);
+    if (cueBlock?.error) {
+      issues.push({
+        severity: "error",
+        code: "MALFORMED_CUE_YAML",
+        beatId: section.id,
+        message: `Beat "${section.id}" has malformed YAML cues: ${cueBlock.error}`
+      });
+    }
+  }
+  const characterPool = new Set(
+    Object.keys(
+      parsed.frontmatter?.characters ?? {}
+    )
+  );
+  for (const beat of parsed.beats) {
+    const cues = beat.cues ?? {};
+    for (const [key, value] of Object.entries(cues)) {
+      if (!ALLOWED_CUE_KEYS.has(key)) {
+        issues.push({
+          severity: "warning",
+          code: "UNKNOWN_CUE",
+          beatId: beat.id,
+          message: `Beat "${beat.id}" uses unknown cue "${key}". Supported cues: ${STORYBOARD_CUE_KEYS.join(", ")}.`
+        });
+        continue;
+      }
+      if (key === "characters") {
+        const validShape = typeof value === "string" || Array.isArray(value) && value.every((v) => typeof v === "string");
+        if (!validShape) {
+          issues.push({
+            severity: "error",
+            code: "INVALID_CHARACTERS_VALUE",
+            beatId: beat.id,
+            message: `Beat "${beat.id}" cue "characters" must be a character name or a list of names.`
+          });
+          continue;
+        }
+        for (const name of beatCharacterNames({ characters: value })) {
+          if (!characterPool.has(name)) {
+            issues.push({
+              severity: "warning",
+              code: "UNKNOWN_CHARACTER",
+              beatId: beat.id,
+              message: `Beat "${beat.id}" references character "${name}" not defined in the frontmatter \`characters:\` pool.`
+            });
+          }
+        }
+        continue;
+      }
+      if (key === "duration") {
+        if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+          issues.push({
+            severity: "error",
+            code: "INVALID_DURATION",
+            beatId: beat.id,
+            message: `Beat "${beat.id}" cue "duration" must be a positive number of seconds.`
+          });
+        }
+        continue;
+      }
+      if (STRING_CUE_KEYS.has(key) && typeof value !== "string") {
+        issues.push({
+          severity: "error",
+          code: "INVALID_CUE_VALUE",
+          beatId: beat.id,
+          message: `Beat "${beat.id}" cue "${key}" must be a string.`
+        });
+      }
+    }
+  }
+  for (const beat of parsed.beats) {
+    if (beat.duration !== void 0 && beat.duration > MAX_RECOMMENDED_BEAT_SEC) {
+      issues.push({
+        severity: "warning",
+        code: "BEAT_DURATION_TOO_LONG",
+        beatId: beat.id,
+        message: `Beat "${beat.id}" is ${beat.duration}s \u2014 beats longer than ${MAX_RECOMMENDED_BEAT_SEC}s render static and overstuffed. Split it into 6-15s beats (a 90s video should have 6-8 beats).`
+      });
+    }
+  }
+  return {
+    ok: !issues.some((i) => i.severity === "error"),
+    beats: parsed.beats,
+    issues
+  };
+}
+function getStoryboardBeat(markdown, beatId) {
+  return parseStoryboard(markdown).beats.find((beat) => beat.id === beatId) ?? null;
+}
+function upsertStoryboardBeat(markdown, opts) {
+  const beatId = normalizeBeatId(opts.beatId);
+  const sections = splitBeatSections(markdown);
+  const existing = sections.find((section2) => section2.id === beatId);
+  const cues = storyboardCuesFromInput(opts);
+  if (existing) {
+    let next = markdown;
+    for (const [key, value] of Object.entries(cues)) {
+      next = setStoryboardCue(next, { beatId, key, value });
+    }
+    return { markdown: next, action: "updated" };
+  }
+  const section = buildStoryboardBeatSection({ ...opts, beatId, cues });
+  if (sections.length > 0 && isStarterStoryboard(markdown)) {
+    const global2 = markdown.slice(0, sections[0].start).trimEnd();
+    return {
+      markdown: `${global2}
+
+${section}`,
+      action: "replaced-starter"
+    };
+  }
+  const prefix = markdown.trimEnd();
+  return {
+    markdown: `${prefix}${prefix ? "\n\n" : ""}${section}`,
+    action: "appended"
+  };
+}
+function setStoryboardCue(markdown, opts) {
+  const section = findBeatSection(markdown, opts.beatId);
+  if (!section) {
+    throw new Error(`Beat "${opts.beatId}" not found.`);
+  }
+  if (!ALLOWED_CUE_KEYS.has(opts.key)) {
+    throw new Error(`Unsupported cue "${opts.key}". Supported cues: ${STORYBOARD_CUE_KEYS.join(", ")}.`);
+  }
+  const cue = readLeadingCueBlock(section.body);
+  if (cue?.error) {
+    throw new Error(`Cannot edit malformed YAML cues for beat "${opts.beatId}": ${cue.error}`);
+  }
+  const cues = cue?.value ? { ...cue.value } : {};
+  if (opts.unset) {
+    delete cues[opts.key];
+  } else {
+    cues[opts.key] = normalizeCueValue(opts.key, opts.value);
+  }
+  const remainingBody = cue ? section.body.slice(cue.full.length).replace(/^\s*\n/, "") : section.body.replace(/^\s*\n/, "");
+  const cueBlock = Object.keys(cues).length > 0 ? "```yaml\n" + (0, import_yaml5.stringify)(cues, { lineWidth: 0 }).trimEnd() + "\n```\n\n" : "";
+  const nextBody = cueBlock + remainingBody.trimStart();
+  const nextSection = section.raw.slice(0, section.headingEnd - section.start) + "\n\n" + nextBody.trimEnd() + "\n";
+  return markdown.slice(0, section.start) + nextSection + markdown.slice(section.end);
+}
+function moveStoryboardBeat(markdown, opts) {
+  if (opts.beatId === opts.afterBeatId) return markdown;
+  const sections = splitBeatSections(markdown);
+  const movingIndex = sections.findIndex((section) => section.id === opts.beatId);
+  if (movingIndex === -1) throw new Error(`Beat "${opts.beatId}" not found.`);
+  const afterIndex = sections.findIndex((section) => section.id === opts.afterBeatId);
+  if (afterIndex === -1) throw new Error(`Beat "${opts.afterBeatId}" not found.`);
+  const global2 = sections.length > 0 ? markdown.slice(0, sections[0].start) : markdown;
+  const chunks = sections.map((section) => section.raw);
+  const [moving] = chunks.splice(movingIndex, 1);
+  const adjustedAfterIndex = movingIndex < afterIndex ? afterIndex - 1 : afterIndex;
+  chunks.splice(adjustedAfterIndex + 1, 0, moving);
+  return global2 + normalizeBeatChunks(chunks);
+}
+function normalizeBeatChunks(chunks) {
+  return chunks.map((chunk) => chunk.trim()).filter(Boolean).join("\n\n") + "\n";
+}
+function normalizeBeatId(id) {
+  return deriveBeatId(id);
+}
+function storyboardCuesFromInput(opts) {
+  const cues = {};
+  if (opts.duration !== void 0) cues.duration = opts.duration;
+  if (opts.narration && opts.narration.trim()) cues.narration = opts.narration.trim();
+  if (opts.backdrop && opts.backdrop.trim()) cues.backdrop = opts.backdrop.trim();
+  return cues;
+}
+function buildStoryboardBeatSection(opts) {
+  const title = normalizeTitle(opts.title ?? humanizeBeatId(opts.beatId));
+  const cueBlock = Object.keys(opts.cues).length > 0 ? "```yaml\n" + (0, import_yaml5.stringify)(opts.cues, { lineWidth: 0 }).trimEnd() + "\n```\n\n" : "";
+  const body = opts.body?.trim() || "Scene created with `vibe scene add`. Edit this body if the build flow should recompose it.";
+  return `## Beat ${opts.beatId} - ${title}
+
+${cueBlock}${body.trimEnd()}
+`;
+}
+function normalizeTitle(value) {
+  return value.replace(/\s+/g, " ").trim() || "Scene";
+}
+function humanizeBeatId(id) {
+  return id.split(/[-_]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ") || "Scene";
+}
+function isStarterStoryboard(markdown) {
+  const parsed = parseStoryboard(markdown);
+  if (parsed.beats.length !== 3) return false;
+  const ids = parsed.beats.map((beat) => beat.id);
+  if (ids.join(",") !== "hook,proof,close") return false;
+  return markdown.includes("Introduce the promise in one crisp sentence.") && markdown.includes("Show the mechanism or proof point that makes the promise believable.") && markdown.includes("Close with the action the viewer should remember.");
+}
+function normalizeCueValue(key, value) {
+  if (key === "duration") {
+    const n = typeof value === "number" ? value : Number.parseFloat(String(value ?? ""));
+    if (!Number.isFinite(n) || n <= 0) {
+      throw new Error("Cue duration must be a positive number.");
+    }
+    return n;
+  }
+  if (typeof value !== "string") return value;
+  return value.trim();
+}
+function splitBeatSections(markdown) {
+  const normalized = markdown.replace(/\r\n/g, "\n");
+  const headings = [];
+  HEADING_RE2.lastIndex = 0;
+  let match;
+  while ((match = HEADING_RE2.exec(normalized)) !== null) {
+    headings.push({ start: match.index, end: match.index + match[0].length, line: match[1].trim() });
+  }
+  return headings.map((heading, index) => {
+    const end = index + 1 < headings.length ? headings[index + 1].start : normalized.length;
+    return {
+      id: deriveBeatId(heading.line),
+      heading: heading.line,
+      start: heading.start,
+      headingEnd: heading.end,
+      end,
+      raw: normalized.slice(heading.start, end),
+      body: normalized.slice(heading.end, end).trim()
+    };
+  });
+}
+function findBeatSection(markdown, beatId) {
+  return splitBeatSections(markdown).find((section) => section.id === beatId) ?? null;
+}
+function readLeadingCueBlock(body) {
+  const match = body.match(LEADING_CUE_RE);
+  if (!match) return null;
+  try {
+    const parsed = (0, import_yaml5.parse)(match[2]);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { full: match[0], error: "cue block must parse to a YAML object" };
+    }
+    return { full: match[0], value: parsed };
+  } catch (error) {
+    return { full: match[0], error: error instanceof Error ? error.message : String(error) };
+  }
+}
+var import_yaml5, STORYBOARD_CUE_KEYS, HEADING_RE2, LEADING_CUE_RE, ALLOWED_CUE_KEYS, STRING_CUE_KEYS, MAX_RECOMMENDED_BEAT_SEC;
+var init_storyboard_edit = __esm({
+  "src/commands/_shared/storyboard-edit.ts"() {
+    "use strict";
+    import_yaml5 = __toESM(require_dist2(), 1);
+    init_storyboard_parse();
+    STORYBOARD_CUE_KEYS = [
+      "duration",
+      "narration",
+      "backdrop",
+      "video",
+      "motion",
+      "voice",
+      "music",
+      "asset",
+      "characters"
+    ];
+    HEADING_RE2 = /^##\s+(.+?)\s*$/gm;
+    LEADING_CUE_RE = /^(\s*)```ya?ml\s*\n([\s\S]*?)\n```\s*(?:\n|$)/;
+    ALLOWED_CUE_KEYS = new Set(STORYBOARD_CUE_KEYS);
+    STRING_CUE_KEYS = /* @__PURE__ */ new Set(["narration", "backdrop", "video", "motion", "voice", "music", "asset"]);
+    MAX_RECOMMENDED_BEAT_SEC = 15;
+  }
+});
+
 // src/pipeline/renderers/chrome.ts
 import { existsSync as existsSync14 } from "node:fs";
 import { homedir as homedir5 } from "node:os";
@@ -32383,6 +33410,7 @@ var init_build_asset_reference = __esm({
     EXTENSIONS = {
       narration: [".mp3", ".wav", ".m4a"],
       backdrop: [".png", ".jpg", ".jpeg", ".webp"],
+      character: [".png", ".jpg", ".jpeg", ".webp"],
       video: [".mp4", ".mov", ".webm"],
       music: [".mp3", ".wav", ".m4a"]
     };
@@ -32420,6 +33448,16 @@ function backdropCacheDescriptor(opts) {
     ext: "png"
   });
 }
+function characterCacheDescriptor(opts) {
+  return cacheAssetDescriptor("character", {
+    name: opts.name,
+    cue: opts.cue,
+    provider: opts.provider,
+    quality: opts.quality,
+    size: opts.size,
+    ext: "png"
+  });
+}
 function imageRatioForSize(size) {
   switch (size) {
     case "1024x1024":
@@ -32439,6 +33477,8 @@ function videoCacheDescriptor(opts) {
     provider: opts.provider,
     duration: normalizeVideoDuration(opts.duration),
     ratio: "16:9",
+    // Omit when empty so existing (character-less) clips keep their cache key.
+    characters: opts.characters && opts.characters.length > 0 ? opts.characters : void 0,
     ext: "mp4"
   });
 }
@@ -32491,208 +33531,6 @@ var init_build_backdrop_prompt = __esm({
   }
 });
 
-// src/commands/_shared/storyboard-edit.ts
-function validateStoryboardMarkdown(markdown) {
-  const parsed = parseStoryboard(markdown);
-  const sections = splitBeatSections(markdown);
-  const issues = [];
-  if (parsed.beats.length === 0) {
-    issues.push({
-      severity: "error",
-      code: "NO_BEATS",
-      message: "STORYBOARD.md must contain at least one `## Beat ...` heading."
-    });
-  }
-  const seen = /* @__PURE__ */ new Map();
-  for (const beat of parsed.beats) {
-    seen.set(beat.id, (seen.get(beat.id) ?? 0) + 1);
-  }
-  for (const [id, count] of seen.entries()) {
-    if (count > 1) {
-      issues.push({
-        severity: "error",
-        code: "DUPLICATE_BEAT_ID",
-        beatId: id,
-        message: `Beat id "${id}" appears ${count} times. Beat ids must be unique.`
-      });
-    }
-  }
-  for (const section of sections) {
-    const cueBlock = readLeadingCueBlock(section.body);
-    if (cueBlock?.error) {
-      issues.push({
-        severity: "error",
-        code: "MALFORMED_CUE_YAML",
-        beatId: section.id,
-        message: `Beat "${section.id}" has malformed YAML cues: ${cueBlock.error}`
-      });
-    }
-  }
-  for (const beat of parsed.beats) {
-    const cues = beat.cues ?? {};
-    for (const [key, value] of Object.entries(cues)) {
-      if (!ALLOWED_CUE_KEYS.has(key)) {
-        issues.push({
-          severity: "warning",
-          code: "UNKNOWN_CUE",
-          beatId: beat.id,
-          message: `Beat "${beat.id}" uses unknown cue "${key}". Supported cues: ${STORYBOARD_CUE_KEYS.join(", ")}.`
-        });
-        continue;
-      }
-      if (key === "duration") {
-        if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
-          issues.push({
-            severity: "error",
-            code: "INVALID_DURATION",
-            beatId: beat.id,
-            message: `Beat "${beat.id}" cue "duration" must be a positive number of seconds.`
-          });
-        }
-        continue;
-      }
-      if (STRING_CUE_KEYS.has(key) && typeof value !== "string") {
-        issues.push({
-          severity: "error",
-          code: "INVALID_CUE_VALUE",
-          beatId: beat.id,
-          message: `Beat "${beat.id}" cue "${key}" must be a string.`
-        });
-      }
-    }
-  }
-  for (const beat of parsed.beats) {
-    if (beat.duration !== void 0 && beat.duration > MAX_RECOMMENDED_BEAT_SEC) {
-      issues.push({
-        severity: "warning",
-        code: "BEAT_DURATION_TOO_LONG",
-        beatId: beat.id,
-        message: `Beat "${beat.id}" is ${beat.duration}s \u2014 beats longer than ${MAX_RECOMMENDED_BEAT_SEC}s render static and overstuffed. Split it into 6-15s beats (a 90s video should have 6-8 beats).`
-      });
-    }
-  }
-  return {
-    ok: !issues.some((i) => i.severity === "error"),
-    beats: parsed.beats,
-    issues
-  };
-}
-function getStoryboardBeat(markdown, beatId) {
-  return parseStoryboard(markdown).beats.find((beat) => beat.id === beatId) ?? null;
-}
-function setStoryboardCue(markdown, opts) {
-  const section = findBeatSection(markdown, opts.beatId);
-  if (!section) {
-    throw new Error(`Beat "${opts.beatId}" not found.`);
-  }
-  if (!ALLOWED_CUE_KEYS.has(opts.key)) {
-    throw new Error(`Unsupported cue "${opts.key}". Supported cues: ${STORYBOARD_CUE_KEYS.join(", ")}.`);
-  }
-  const cue = readLeadingCueBlock(section.body);
-  if (cue?.error) {
-    throw new Error(`Cannot edit malformed YAML cues for beat "${opts.beatId}": ${cue.error}`);
-  }
-  const cues = cue?.value ? { ...cue.value } : {};
-  if (opts.unset) {
-    delete cues[opts.key];
-  } else {
-    cues[opts.key] = normalizeCueValue(opts.key, opts.value);
-  }
-  const remainingBody = cue ? section.body.slice(cue.full.length).replace(/^\s*\n/, "") : section.body.replace(/^\s*\n/, "");
-  const cueBlock = Object.keys(cues).length > 0 ? "```yaml\n" + (0, import_yaml5.stringify)(cues, { lineWidth: 0 }).trimEnd() + "\n```\n\n" : "";
-  const nextBody = cueBlock + remainingBody.trimStart();
-  const nextSection = section.raw.slice(0, section.headingEnd - section.start) + "\n\n" + nextBody.trimEnd() + "\n";
-  return markdown.slice(0, section.start) + nextSection + markdown.slice(section.end);
-}
-function moveStoryboardBeat(markdown, opts) {
-  if (opts.beatId === opts.afterBeatId) return markdown;
-  const sections = splitBeatSections(markdown);
-  const movingIndex = sections.findIndex((section) => section.id === opts.beatId);
-  if (movingIndex === -1) throw new Error(`Beat "${opts.beatId}" not found.`);
-  const afterIndex = sections.findIndex((section) => section.id === opts.afterBeatId);
-  if (afterIndex === -1) throw new Error(`Beat "${opts.afterBeatId}" not found.`);
-  const global2 = sections.length > 0 ? markdown.slice(0, sections[0].start) : markdown;
-  const chunks = sections.map((section) => section.raw);
-  const [moving] = chunks.splice(movingIndex, 1);
-  const adjustedAfterIndex = movingIndex < afterIndex ? afterIndex - 1 : afterIndex;
-  chunks.splice(adjustedAfterIndex + 1, 0, moving);
-  return global2 + normalizeBeatChunks(chunks);
-}
-function normalizeBeatChunks(chunks) {
-  return chunks.map((chunk) => chunk.trim()).filter(Boolean).join("\n\n") + "\n";
-}
-function normalizeCueValue(key, value) {
-  if (key === "duration") {
-    const n = typeof value === "number" ? value : Number.parseFloat(String(value ?? ""));
-    if (!Number.isFinite(n) || n <= 0) {
-      throw new Error("Cue duration must be a positive number.");
-    }
-    return n;
-  }
-  if (typeof value !== "string") return value;
-  return value.trim();
-}
-function splitBeatSections(markdown) {
-  const normalized = markdown.replace(/\r\n/g, "\n");
-  const headings = [];
-  HEADING_RE2.lastIndex = 0;
-  let match;
-  while ((match = HEADING_RE2.exec(normalized)) !== null) {
-    headings.push({ start: match.index, end: match.index + match[0].length, line: match[1].trim() });
-  }
-  return headings.map((heading, index) => {
-    const end = index + 1 < headings.length ? headings[index + 1].start : normalized.length;
-    return {
-      id: deriveBeatId(heading.line),
-      heading: heading.line,
-      start: heading.start,
-      headingEnd: heading.end,
-      end,
-      raw: normalized.slice(heading.start, end),
-      body: normalized.slice(heading.end, end).trim()
-    };
-  });
-}
-function findBeatSection(markdown, beatId) {
-  return splitBeatSections(markdown).find((section) => section.id === beatId) ?? null;
-}
-function readLeadingCueBlock(body) {
-  const match = body.match(LEADING_CUE_RE);
-  if (!match) return null;
-  try {
-    const parsed = (0, import_yaml5.parse)(match[2]);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      return { full: match[0], error: "cue block must parse to a YAML object" };
-    }
-    return { full: match[0], value: parsed };
-  } catch (error) {
-    return { full: match[0], error: error instanceof Error ? error.message : String(error) };
-  }
-}
-var import_yaml5, STORYBOARD_CUE_KEYS, HEADING_RE2, LEADING_CUE_RE, ALLOWED_CUE_KEYS, STRING_CUE_KEYS, MAX_RECOMMENDED_BEAT_SEC;
-var init_storyboard_edit = __esm({
-  "src/commands/_shared/storyboard-edit.ts"() {
-    "use strict";
-    import_yaml5 = __toESM(require_dist2(), 1);
-    init_storyboard_parse();
-    STORYBOARD_CUE_KEYS = [
-      "duration",
-      "narration",
-      "backdrop",
-      "video",
-      "motion",
-      "voice",
-      "music",
-      "asset"
-    ];
-    HEADING_RE2 = /^##\s+(.+?)\s*$/gm;
-    LEADING_CUE_RE = /^(\s*)```ya?ml\s*\n([\s\S]*?)\n```\s*(?:\n|$)/;
-    ALLOWED_CUE_KEYS = new Set(STORYBOARD_CUE_KEYS);
-    STRING_CUE_KEYS = /* @__PURE__ */ new Set(["narration", "backdrop", "video", "motion", "voice", "music", "asset"]);
-    MAX_RECOMMENDED_BEAT_SEC = 15;
-  }
-});
-
 // src/commands/_shared/build-plan.ts
 import { existsSync as existsSync17 } from "node:fs";
 import { readFile as readFile17 } from "node:fs/promises";
@@ -32801,13 +33639,13 @@ async function createBuildPlan(opts) {
     const backdropCue = backdropPrompt ?? backdropReference?.raw;
     const videoCue = videoPrompt ?? videoReference?.raw;
     const musicCue = musicPrompt ?? musicReference?.raw;
-    const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : 0;
+    const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : resolved.narration.resolved === "openai" ? OPENAI_NARRATION_COST_USD : 0;
     const narrationCache = narrationText && !narrationReference ? narrationCacheDescriptor({
       beatId: beat.id,
       cue: narrationText,
       provider: resolved.narration.resolved,
       voice,
-      ext: resolved.narration.resolved === "elevenlabs" ? "mp3" : "wav"
+      ext: resolved.narration.resolved === "kokoro" ? "wav" : "mp3"
     }) : null;
     const backdropCache = augmentedBackdropPrompt && !backdropReference ? backdropCacheDescriptor({
       beatId: beat.id,
@@ -32868,7 +33706,11 @@ async function createBuildPlan(opts) {
       reference: videoReference,
       projectDir,
       force: opts.force,
-      cost: VIDEO_COST_USD,
+      cost: resolved.video.resolved === "seedance" || resolved.video.resolved === "fal" ? estimateSeedanceVideoCostUsd({
+        durationSec: normalizeVideoDuration(beat.duration),
+        resolution: "720p",
+        aspectRatio: "16:9"
+      }) : VIDEO_COST_USD,
       active: includeAssets
     }) : null;
     const music = musicCue && !opts.skipMusic ? assetPlan({
@@ -32979,6 +33821,21 @@ async function createBuildPlan(opts) {
       retryWith.push(skipCommand);
     }
   }
+  if (validationOk && includeAssets && !opts.skipVideo) {
+    const referenced = /* @__PURE__ */ new Set();
+    for (const beat of sourceBeats) {
+      for (const name of beatCharacterNames(beat.cues)) referenced.add(name);
+    }
+    if (referenced.size > 0) {
+      const toGenerate = resolveCharacters(parsed.frontmatter).filter(
+        (c) => referenced.has(c.name) && c.prompt && (opts.force || !existsSync17(join15(projectDir, `assets/character-${c.name}.png`)))
+      );
+      if (toGenerate.length > 0) {
+        estimatedCostUsd += toGenerate.length * backdropCostUsd(opts.imageQuality ?? "hd");
+        missing.add("assets");
+      }
+    }
+  }
   return finalizeBuildPlan({
     projectDir,
     config: config2,
@@ -33225,17 +34082,20 @@ function providerInput(opts) {
 async function resolveNarrationProvider(input, projectDir) {
   const requested = input.value.toLowerCase();
   const hasElevenLabs = Boolean(await getApiKeyFromConfig("elevenlabs", { cwd: projectDir }));
-  const resolved = requested === "elevenlabs" ? "elevenlabs" : requested === "kokoro" ? "kokoro" : hasElevenLabs ? "elevenlabs" : "kokoro";
+  const hasOpenAi = Boolean(await getApiKeyFromConfig("openai", { cwd: projectDir }));
+  const resolved = requested === "elevenlabs" ? "elevenlabs" : requested === "openai" ? "openai" : requested === "kokoro" ? "kokoro" : hasElevenLabs ? "elevenlabs" : hasOpenAi ? "openai" : "kokoro";
+  const requiresKey = resolved !== "kokoro";
+  const hasKey = resolved === "elevenlabs" ? hasElevenLabs : resolved === "openai" ? hasOpenAi : true;
   return {
     kind: "narration",
     requested: input.requested,
     resolved,
     source: input.source,
-    requiresKey: resolved === "elevenlabs",
-    configured: resolved !== "elevenlabs" || hasElevenLabs,
-    ...resolved === "elevenlabs" ? { configKey: "elevenlabs" } : {},
-    ...resolved === "elevenlabs" && !hasElevenLabs ? { missingKey: providerEnvVar("elevenlabs") } : {},
-    retryWith: resolved === "elevenlabs" && !hasElevenLabs ? ["vibe setup --full"] : []
+    requiresKey,
+    configured: hasKey,
+    ...requiresKey ? { configKey: resolved } : {},
+    ...requiresKey && !hasKey ? { missingKey: providerEnvVar(resolved) } : {},
+    retryWith: requiresKey && !hasKey ? ["vibe setup --full"] : []
   };
 }
 async function keyedProviderResolution(opts, projectDir) {
@@ -33331,7 +34191,7 @@ function loadPlanEnv(projectDir) {
     dir = dirname9(dir);
   }
 }
-var import_dotenv2, VIDEO_COST_USD, MUSIC_COST_USD, ELEVENLABS_NARRATION_COST_USD, COMPOSE_COST_USD, SUPPORTED_BUILD_IMAGE_PROVIDERS;
+var import_dotenv2, VIDEO_COST_USD, MUSIC_COST_USD, ELEVENLABS_NARRATION_COST_USD, OPENAI_NARRATION_COST_USD, COMPOSE_COST_USD, SUPPORTED_BUILD_IMAGE_PROVIDERS;
 var init_build_plan = __esm({
   "src/commands/_shared/build-plan.ts"() {
     "use strict";
@@ -33340,6 +34200,7 @@ var init_build_plan = __esm({
     init_schema();
     init_build_asset_reference();
     init_build_cache();
+    init_dist2();
     init_build_asset_metadata();
     init_build_backdrop_prompt();
     init_composer_resolve();
@@ -33349,6 +34210,7 @@ var init_build_plan = __esm({
     VIDEO_COST_USD = 5;
     MUSIC_COST_USD = 0.5;
     ELEVENLABS_NARRATION_COST_USD = 0.05;
+    OPENAI_NARRATION_COST_USD = 0.01;
     COMPOSE_COST_USD = 0.06;
     SUPPORTED_BUILD_IMAGE_PROVIDERS = ["openai", "gemini", "grok"];
   }
@@ -33671,7 +34533,7 @@ __export(scene_build_exports, {
   executeSceneBuild: () => executeSceneBuild,
   resolveSceneBuildMode: () => resolveSceneBuildMode
 });
-import { existsSync as existsSync19 } from "node:fs";
+import { existsSync as existsSync19, readFileSync as readFileSync3 } from "node:fs";
 import { copyFile as copyFile3, mkdir as mkdir10, readFile as readFile18, writeFile as writeFile18 } from "node:fs/promises";
 import { dirname as dirname10, join as join16, resolve as resolve25 } from "node:path";
 async function executeSceneBuild(opts) {
@@ -33838,8 +34700,32 @@ async function executeSceneBuild(opts) {
   const voice = opts.voice ?? parsed.frontmatter?.voice;
   let beatOutcomes = collectExistingBeatOutcomes(parsed.beats, projectDir);
   let pendingJobs = [];
+  let characterCostUsd = 0;
   if (shouldRunStage(selectedStage, "assets")) {
     onProgress({ type: "phase-start", phase: "primitives" });
+    const characterPaths = /* @__PURE__ */ new Map();
+    if (!(opts.skipVideo ?? false)) {
+      const referenced = /* @__PURE__ */ new Set();
+      for (const beat of activeBeats) {
+        for (const name of beatCharacterNames(beat.cues)) referenced.add(name);
+      }
+      if (referenced.size > 0) {
+        const charResult = await buildCharacters(
+          resolveCharacters(parsed.frontmatter).filter((c) => referenced.has(c.name)),
+          {
+            projectDir,
+            imageProvider,
+            imageSize: opts.imageSize ?? "1536x1024",
+            imageQuality: opts.imageQuality ?? "hd",
+            force: opts.force ?? false,
+            onProgress
+          }
+        );
+        for (const [name, path2] of charResult.paths) characterPaths.set(name, path2);
+        characterCostUsd = charResult.costUsd;
+        warnings.push(...charResult.failures);
+      }
+    }
     const primitiveResults = await mapWithConcurrency(
       activeBeats,
       BEAT_PRIMITIVES_CONCURRENCY,
@@ -33857,7 +34743,8 @@ async function executeSceneBuild(opts) {
         skipVideo: opts.skipVideo ?? false,
         skipMusic: opts.skipMusic ?? false,
         force: opts.force ?? false,
-        onProgress
+        onProgress,
+        characterPaths
       })
     );
     beatOutcomes = primitiveResults.map((result) => result.outcome);
@@ -33866,10 +34753,7 @@ async function executeSceneBuild(opts) {
       (beat) => beat.narrationStatus === "failed" || beat.backdropStatus === "failed" || beat.videoStatus === "failed" || beat.musicStatus === "failed"
     );
     stageReports.assets.status = assetFailed ? "failed" : pendingJobs.length > 0 ? "pending-jobs" : "done";
-    stageReports.assets.costUsd = estimateActualAssetCost(
-      beatOutcomes,
-      opts.imageQuality ?? "hd"
-    );
+    stageReports.assets.costUsd = estimateActualAssetCost(beatOutcomes, opts.imageQuality ?? "hd") + characterCostUsd;
     stageReports.assets.retryWith = pendingJobs.map(
       (job) => `vibe status job ${job.id} --project ${projectDir} --json`
     );
@@ -34034,6 +34918,18 @@ async function executeSceneBuild(opts) {
     stageReports.compose.status = "skipped";
   }
   if (stageReports.compose.status === "done") {
+    for (const beat of activeBeats) {
+      const videoRel = `assets/video-${beat.id}.mp4`;
+      const compositionAbs = join16(projectDir, "compositions", `scene-${beat.id}.html`);
+      if (!existsSync19(join16(projectDir, videoRel)) || !existsSync19(compositionAbs)) continue;
+      const html = readFileSync3(compositionAbs, "utf-8");
+      if (!html.includes(videoRel)) {
+        warnings.push(
+          `Beat "${beat.id}" has a generated clip (${videoRel}) but its composition does not reference it, so the clip will not appear. Recompose the beat.`
+        );
+        retryWith.push(`vibe build ${projectDir} --beat ${beat.id} --stage compose --force --json`);
+      }
+    }
     const repair = await runBuildSceneRepair(projectDir, "compose", false);
     sceneRepair = mergeSceneRepairSummaries(sceneRepair, repair);
     applySceneRepairToStage(stageReports.compose, repair);
@@ -34454,6 +35350,120 @@ async function dispatchNarration(beat, ctx) {
     freshness: "fresh"
   };
 }
+function characterSheetPrompt(name, description) {
+  return [
+    `Character turnaround reference sheet of an original fictional character named ${name}: ${description}.`,
+    "Show three full-body views side by side on one clean canvas \u2014 front view, side profile, and back view \u2014",
+    "with identical outfit, hairstyle, hair color, and body proportions across all three views.",
+    "Plain light-grey studio background, even neutral lighting, no props.",
+    "Photorealistic digital character, professional concept-art character sheet layout."
+  ].join(" ");
+}
+async function buildCharacters(characters, ctx) {
+  const paths = /* @__PURE__ */ new Map();
+  const failures = [];
+  let costUsd = 0;
+  const size = ctx.imageSize ?? "1536x1024";
+  for (const character of characters) {
+    if (character.imagePath) {
+      if (existsSync19(join16(ctx.projectDir, character.imagePath))) {
+        paths.set(character.name, character.imagePath);
+        ctx.onProgress({ type: "character-cached", name: character.name, path: character.imagePath });
+      } else {
+        const error = `character "${character.name}" image not found: ${character.imagePath}`;
+        failures.push(error);
+        ctx.onProgress({ type: "character-failed", name: character.name, error });
+      }
+      continue;
+    }
+    if (!character.prompt) continue;
+    const prompt3 = characterSheetPrompt(character.name, character.prompt);
+    const rel = `assets/character-${character.name}.png`;
+    const abs = join16(ctx.projectDir, rel);
+    const metadataOptions = { quality: ctx.imageQuality, size };
+    const cache = characterCacheDescriptor({
+      name: character.name,
+      cue: prompt3,
+      provider: ctx.imageProvider,
+      quality: ctx.imageQuality,
+      size
+    });
+    if (existsSync19(abs) && !ctx.force) {
+      const metadata = readAssetMetadata(ctx.projectDir, "character", character.name);
+      if (!metadata || isFreshCanonicalAsset({
+        projectDir: ctx.projectDir,
+        kind: "character",
+        beatId: character.name,
+        cue: prompt3,
+        provider: ctx.imageProvider,
+        options: metadataOptions,
+        cacheKey: cache.key
+      })) {
+        paths.set(character.name, rel);
+        ctx.onProgress({ type: "character-cached", name: character.name, path: rel });
+        continue;
+      }
+    }
+    const cacheAbs = join16(ctx.projectDir, cache.path);
+    if (existsSync19(cacheAbs) && !ctx.force) {
+      await mkdir10(dirname10(abs), { recursive: true });
+      await copyFile3(cacheAbs, abs);
+      await writeAssetMetadata({
+        projectDir: ctx.projectDir,
+        kind: "character",
+        beatId: character.name,
+        cue: prompt3,
+        provider: ctx.imageProvider,
+        options: metadataOptions,
+        cacheKey: cache.key,
+        canonicalPath: rel,
+        cachePath: cache.path
+      });
+      paths.set(character.name, rel);
+      ctx.onProgress({ type: "character-cached", name: character.name, path: rel });
+      continue;
+    }
+    const generated = await generateBackdropImage(
+      prompt3,
+      {
+        projectDir: ctx.projectDir,
+        imageProvider: ctx.imageProvider,
+        imageSize: size,
+        imageQuality: ctx.imageQuality
+      },
+      imageRatioForSize(size)
+    );
+    if (!generated.success) {
+      failures.push(`character "${character.name}": ${generated.error}`);
+      ctx.onProgress({ type: "character-failed", name: character.name, error: generated.error });
+      continue;
+    }
+    await mkdir10(dirname10(abs), { recursive: true });
+    await writeFile18(abs, generated.buffer);
+    await mkdir10(dirname10(cacheAbs), { recursive: true });
+    await writeFile18(cacheAbs, generated.buffer);
+    await writeAssetMetadata({
+      projectDir: ctx.projectDir,
+      kind: "character",
+      beatId: character.name,
+      cue: prompt3,
+      provider: ctx.imageProvider,
+      options: metadataOptions,
+      cacheKey: cache.key,
+      canonicalPath: rel,
+      cachePath: cache.path
+    });
+    costUsd += backdropCostUsd(ctx.imageQuality);
+    paths.set(character.name, rel);
+    ctx.onProgress({
+      type: "character-generated",
+      name: character.name,
+      path: rel,
+      provider: ctx.imageProvider
+    });
+  }
+  return { paths, costUsd: Number(costUsd.toFixed(2)), failures };
+}
 async function dispatchBackdrop(beat, ctx) {
   const reference = assetReferenceForBeat(ctx.projectDir, "backdrop", beat);
   if (reference) return referencePrimitiveOutcome("backdrop", beat, ctx, reference);
@@ -34623,13 +35633,16 @@ async function dispatchVideo(beat, ctx) {
   if (reference) return referencePrimitiveOutcome("video", beat, ctx, reference);
   const prompt3 = stringOrUndefined4(beat.cues?.video);
   if (!prompt3) return { status: "no-cue" };
+  const characterRefsRel = beatCharacterNames(beat.cues).map((name) => ctx.characterPaths?.get(name)).filter((p) => typeof p === "string");
+  const characterRefsAbs = characterRefsRel.map((p) => join16(ctx.projectDir, p));
   const rel = `assets/video-${beat.id}.mp4`;
   const abs = join16(ctx.projectDir, rel);
   const cache = videoCacheDescriptor({
     beatId: beat.id,
     cue: prompt3,
     provider: ctx.videoProvider,
-    duration: normalizeVideoDuration(beat.duration)
+    duration: normalizeVideoDuration(beat.duration),
+    characters: characterRefsRel
   });
   const metadataPath = assetMetadataPath("video", beat.id);
   if (existsSync19(abs) && !ctx.force) {
@@ -34689,6 +35702,7 @@ async function dispatchVideo(beat, ctx) {
     ratio: "16:9",
     output: abs,
     wait: false,
+    refImages: characterRefsAbs.length > 0 ? characterRefsAbs : void 0,
     apiKey: await apiKeyForVideoProvider(ctx.videoProvider, ctx.projectDir)
   });
   if (!result.success || !result.taskId) {
@@ -35057,7 +36071,13 @@ function estimateActualAssetCost(outcomes, imageQuality) {
   for (const outcome of outcomes) {
     if (outcome.narrationStatus === "generated") cost += 0.05;
     if (outcome.backdropStatus === "generated") cost += backdropCostUsd(imageQuality);
-    if (outcome.videoStatus === "generated" || outcome.videoStatus === "pending") cost += 5;
+    if (outcome.videoStatus === "generated" || outcome.videoStatus === "pending") {
+      cost += outcome.videoProvider === "seedance" || outcome.videoProvider === "fal" ? estimateSeedanceVideoCostUsd({
+        durationSec: normalizeVideoDuration(outcome.sceneDurationSec),
+        resolution: "720p",
+        aspectRatio: "16:9"
+      }) : 5;
+    }
     if (outcome.musicStatus === "generated" || outcome.musicStatus === "pending") cost += 0.5;
   }
   return Number(cost.toFixed(2));
@@ -45178,10 +46198,18 @@ Examples:
         options.ratio = "16:9";
       }
       if (options.dryRun) {
+        const costUsd = provider === "seedance" || provider === "fal" ? estimateSeedanceVideoCostUsd({
+          durationSec: Number(options.duration) || 5,
+          resolution: options.resolution,
+          aspectRatio: options.ratio,
+          fast: options.seedanceModel === "fast",
+          hasVideoReference: Boolean(options.refVideos)
+        }) : void 0;
         outputSuccess({
           command: "generate video",
           startedAt,
           dryRun: true,
+          costUsd,
           data: {
             params: {
               prompt: prompt3,
@@ -51379,7 +52407,7 @@ function pickOutputPath(data) {
 }
 
 // src/tools/_shared/elicit.ts
-var NARRATION_CHOICES = ["kokoro", "elevenlabs"];
+var NARRATION_CHOICES = ["kokoro", "openai", "elevenlabs"];
 var BACKDROP_CHOICES = ["skip", "openai"];
 function planBuildElicitation(args) {
   const assetsWillRun = args.stage === void 0 || args.stage === "all" || args.stage === "assets";
@@ -51394,8 +52422,9 @@ function planBuildElicitation(args) {
       description: "Which TTS engine narrates the video?",
       enum: [...NARRATION_CHOICES],
       enumNames: [
-        "Kokoro \u2014 free, runs locally on this machine",
-        "ElevenLabs \u2014 cloud TTS, uses your ElevenLabs credits"
+        "Kokoro \u2014 free, runs on this machine (first use downloads a ~90 MB voice model; slower)",
+        "OpenAI \u2014 fast cloud voice, uses your OpenAI API key (~$0.02 per video)",
+        "ElevenLabs \u2014 premium cloud voices, uses your ElevenLabs credits"
       ]
     };
     required.push("narration");
@@ -51658,6 +52687,9 @@ function clean(text) {
 function humanise(id) {
   return id.split(/[-_]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
+function sceneCompositionId(beatId) {
+  return `scene-${beatId}`;
+}
 function slugifySceneName(name) {
   const normalised = name.normalize("NFKD").replace(/[̀-ͯ]/g, "");
   const slug = normalised.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -51695,10 +52727,16 @@ function fitKineticFontSize(words) {
 function kenBurnsTween(scope, dur, endScale = 1.08) {
   return `tl.fromTo('${scope} .backdrop', { scale: 1.0 }, { scale: ${endScale}, duration: ${dur.toFixed(2)}, ease: 'none' }, 0);`;
 }
+function backdropMotionTweens(scope, dur, hasImage, endScale = 1.08) {
+  const sweep = hasImage ? "" : `
+      tl.fromTo('${scope} .ambient-sweep', { xPercent: -75, opacity: 0.18 }, { xPercent: 75, opacity: 0.62, duration: ${dur.toFixed(2)}, ease: 'sine.inOut' }, 0);`;
+  return `${kenBurnsTween(scope, dur, endScale)}${sweep}`;
+}
 function buildPreset(input) {
   const id = input.id;
   const scope = `[data-composition-id="${id}"]`;
-  const headline = clean(input.headline) || humanise(id);
+  const displayId = input.beatId ?? id;
+  const headline = clean(input.headline) || humanise(displayId);
   const subhead = clean(input.subhead);
   const kicker = clean(input.kicker);
   const dur = input.duration;
@@ -51721,8 +52759,17 @@ function buildPreset(input) {
         position: absolute;
         inset: 0;
         background: radial-gradient(ellipse at center, #1a1a2e 0%, #000 70%);
+        overflow: hidden;
+      }
+      ${scope} .ambient-sweep {
+        position: absolute;
+        inset: -22%;
+        display: block;
+        background: linear-gradient(115deg, rgba(255,255,255,0) 20%, rgba(0,201,255,0.34) 48%, rgba(142,45,226,0.26) 58%, rgba(255,255,255,0) 78%);
+        filter: blur(12px);
+        transform: rotate(8deg);
       }`;
-  const backdropMarkup = `<div class="backdrop"></div>`;
+  const backdropMarkup = hasImage ? `<div class="backdrop"></div>` : `<div class="backdrop"><div class="ambient-sweep"></div></div>`;
   switch (input.preset) {
     case "simple": {
       const transcript = input.transcript;
@@ -51754,7 +52801,7 @@ function buildPreset(input) {
         body: `${backdropMarkup}
     <div class="caption" id="caption">${captionInner}</div>`,
         timeline: `${crossfadeTweens(scope, dur)}
-      ${kenBurnsTween(scope, dur)}
+      ${backdropMotionTweens(scope, dur, hasImage)}
       ${captionTween}`
       };
     }
@@ -51793,12 +52840,12 @@ function buildPreset(input) {
         // scene's own fade-in handles the visual transition. Backdrop
         // Ken-Burns fills what used to be 80% dead static frame.
         timeline: `${crossfadeTweens(scope, dur)}
-      ${kenBurnsTween(scope, dur)}
+      ${backdropMotionTweens(scope, dur, hasImage)}
       tl.from('${scope} #headline', { opacity: 0, scale: 0.92, duration: 0.55, ease: 'power3.out' }, 0.05);`
       };
     }
     case "explainer": {
-      const k = kicker || humanise(id).toUpperCase();
+      const k = kicker || humanise(displayId).toUpperCase();
       const sub = subhead || "";
       const transcript = input.transcript;
       const useWordSync = !!(transcript && transcript.length > 0 && sub);
@@ -51840,7 +52887,7 @@ function buildPreset(input) {
       <div class="subtitle" id="subtitle">${subtitleInner}</div>` : ""}
     </div>`,
         timeline: `${crossfadeTweens(scope, dur)}
-      ${kenBurnsTween(scope, dur)}
+      ${backdropMotionTweens(scope, dur, hasImage)}
       tl.from('${scope} #kicker', { opacity: 0, y: 16, duration: 0.4, ease: 'power2.out' }, 0.1);
       tl.from('${scope} #title', { opacity: 0, y: 60, duration: 0.7, ease: 'power3.out' }, 0.25);
       ${subtitleTween}`
@@ -51881,12 +52928,12 @@ function buildPreset(input) {
         body: `${backdropMarkup}
     <div class="kinetic">${wordSpans}</div>`,
         timeline: `${crossfadeTweens(scope, dur)}
-      ${kenBurnsTween(scope, dur)}
+      ${backdropMotionTweens(scope, dur, hasImage)}
       ${tweens}`
       };
     }
     case "product-shot": {
-      const label = kicker || humanise(id);
+      const label = kicker || humanise(displayId);
       const headlineFontPx = fitFontSize(headline, 72, 40, 50);
       return {
         css: `${scope} {
@@ -51920,7 +52967,7 @@ function buildPreset(input) {
     <div class="product-headline" id="headline">${esc(headline)}</div>${subhead ? `
     <div class="product-sub" id="subhead">${esc(subhead)}</div>` : ""}`,
         timeline: `${crossfadeTweens(scope, dur)}
-      tl.fromTo('${scope} .backdrop', { scale: 1.0 }, { scale: 1.12, duration: ${dur.toFixed(2)}, ease: 'none' }, 0);
+      ${backdropMotionTweens(scope, dur, hasImage, 1.12)}
       tl.from('${scope} #label', { opacity: 0, x: -30, duration: 0.5, ease: 'power3.out' }, 0.2);
       tl.from('${scope} #headline', { opacity: 0, y: 40, duration: 0.6, ease: 'power3.out' }, 0.4);${subhead ? `
       tl.from('${scope} #subhead', { opacity: 0, y: 20, duration: 0.5, ease: 'power3.out' }, 0.65);` : ""}`
@@ -51985,9 +53032,10 @@ function emitSceneHtml(input) {
   if (input.width <= 0 || input.height <= 0) {
     throw new Error(`Invalid canvas dims: ${input.width}x${input.height}`);
   }
-  const id = input.id;
+  const beatId = input.id;
+  const id = sceneCompositionId(beatId);
   const dur = Number(input.duration.toFixed(3));
-  const parts = buildPreset({ ...input, id, duration: dur });
+  const parts = buildPreset({ ...input, id, beatId, duration: dur });
   const audioBlock = input.audioPath ? `
     <audio
       id="narration"
@@ -52003,7 +53051,7 @@ function emitSceneHtml(input) {
     ${lottieLayer.markup}` : "";
   const lottieScript = lottieLayer ? `
     ${lottieLayer.script}` : "";
-  return `<template id="scene-${id}-template">
+  return `<template id="${id}-template">
   <div data-composition-id="${id}" data-start="0" data-duration="${dur}" data-width="${input.width}" data-height="${input.height}">
     <style>
       ${parts.css}
@@ -52039,8 +53087,9 @@ function buildClipReference(opts) {
   const duration = Number(opts.duration.toFixed(3));
   const track = opts.trackIndex ?? 1;
   const src = opts.src ?? `compositions/scene-${opts.id}.html`;
+  const compositionId = sceneCompositionId(opts.id);
   const zIndex = Math.max(1, 1e6 - Math.floor(start * 1e3));
-  return `<div class="clip" data-composition-id="${esc(opts.id)}" data-composition-src="${esc(src)}" data-start="${start}" data-duration="${duration}" data-track-index="${track}" style="z-index: ${zIndex};"></div>`;
+  return `<div class="clip" data-composition-id="${esc(compositionId)}" data-composition-src="${esc(src)}" data-start="${start}" data-duration="${duration}" data-track-index="${track}" style="z-index: ${zIndex};"></div>`;
 }
 function insertClipIntoRoot(rootHtml, clip) {
   const clipDiv = buildClipReference(clip);
@@ -52084,9 +53133,9 @@ init_agent_host_detect();
 // src/commands/_shared/install-skill.ts
 init_bundle_content();
 init_bundle();
-import { mkdir as mkdir5, writeFile as writeFile9 } from "node:fs/promises";
+import { mkdir as mkdir5, writeFile as writeFile10 } from "node:fs/promises";
 import { existsSync as existsSync7 } from "node:fs";
-import { dirname as dirname4, join as join6, relative as relative3, resolve as resolve9 } from "node:path";
+import { dirname as dirname4, join as join7, relative as relative3, resolve as resolve10 } from "node:path";
 function universalFiles() {
   return [
     { relPath: "SKILL.md", content: SKILL_MD },
@@ -52136,7 +53185,7 @@ function selectHostFiles(hosts) {
   return out;
 }
 async function installHyperframesSkill(opts) {
-  const projectDir = resolve9(opts.projectDir);
+  const projectDir = resolve10(opts.projectDir);
   const force = opts.force ?? false;
   const dryRun = opts.dryRun ?? false;
   const files = [...universalFiles(), ...selectHostFiles(opts.hosts)];
@@ -52145,7 +53194,7 @@ async function installHyperframesSkill(opts) {
     await mkdir5(projectDir, { recursive: true });
   }
   for (const file of files) {
-    const absPath = join6(projectDir, file.relPath);
+    const absPath = join7(projectDir, file.relPath);
     const exists = existsSync7(absPath);
     const bytes = Buffer.byteLength(file.content, "utf-8");
     if (exists && !force) {
@@ -52161,7 +53210,7 @@ async function installHyperframesSkill(opts) {
       continue;
     }
     await mkdir5(dirname4(absPath), { recursive: true });
-    await writeFile9(absPath, file.content, "utf-8");
+    await writeFile10(absPath, file.content, "utf-8");
     actions.push({ path: file.relPath, status: "wrote", bytes });
   }
   return {
@@ -52186,10 +53235,10 @@ init_scene_lint();
 init_storyboard_parse();
 init_root_sync();
 import { existsSync as existsSync11 } from "node:fs";
-import { mkdir as mkdir7, readFile as readFile11, writeFile as writeFile12 } from "node:fs/promises";
-import { join as join10, resolve as resolve13 } from "node:path";
+import { mkdir as mkdir7, readFile as readFile11, writeFile as writeFile13 } from "node:fs/promises";
+import { join as join11, resolve as resolve14 } from "node:path";
 async function executeSceneSubmit(opts) {
-  const projectDir = resolve13(opts.projectDir);
+  const projectDir = resolve14(opts.projectDir);
   const beatId = opts.beatId.trim();
   const scenePath = `compositions/scene-${beatId}.html`;
   const base = {
@@ -52201,7 +53250,7 @@ async function executeSceneSubmit(opts) {
     warnings: [],
     retryWith: []
   };
-  const storyboardPath = join10(projectDir, "STORYBOARD.md");
+  const storyboardPath = join11(projectDir, "STORYBOARD.md");
   if (!existsSync11(storyboardPath)) {
     return {
       ...base,
@@ -52279,9 +53328,9 @@ async function executeSceneSubmit(opts) {
   if (opts.validateOnly) {
     return { ...base, success: true };
   }
-  const absPath = join10(projectDir, scenePath);
-  await mkdir7(join10(projectDir, "compositions"), { recursive: true });
-  await writeFile12(absPath, html.endsWith("\n") ? html : `${html}
+  const absPath = join11(projectDir, scenePath);
+  await mkdir7(join11(projectDir, "compositions"), { recursive: true });
+  await writeFile13(absPath, html.endsWith("\n") ? html : `${html}
 `, "utf-8");
   return {
     ...base,
@@ -52296,6 +53345,8 @@ async function executeSceneSubmit(opts) {
 
 // src/commands/scene.ts
 init_scene_repair();
+init_root_sync();
+init_storyboard_edit();
 function validateDuration(value) {
   const n = parseFloat(value);
   if (!Number.isFinite(n) || n <= 0 || n > 3600) {
@@ -52598,11 +53649,14 @@ sceneCommand.command("add").description("Add a new scene to a project: AI narrat
 ).option("-d, --duration <sec>", "Explicit scene duration in seconds (overrides narration audio)").option(
   "--visuals <prompt>",
   "Image prompt \u2014 generates assets/scene-<id>.png via the configured image provider"
-).option("--headline <text>", "Visible headline (defaults to the humanised scene name)").option("--kicker <text>", "Small label above the headline (explainer / product-shot)").option("--insert-into <path>", "Root composition file to update", "index.html").option("--project <dir>", "Project directory", ".").option("--image-provider <name>", "Image provider: gemini, openai", "gemini").option(
+).option("--headline <text>", "Visible headline (defaults to the humanised scene name)").option("--kicker <text>", "Small label above the headline (explainer / product-shot)").option("--insert-into <path>", "Root composition file to update", "index.html").option("--project <dir>", "Project directory", ".").option(
+  "--no-storyboard",
+  "Do not sync STORYBOARD.md; insert this scene directly into the root composition only"
+).option("--image-provider <name>", "Image provider: gemini, openai", "gemini").option(
   "--tts <provider>",
-  "TTS provider: auto, elevenlabs, kokoro (default auto \u2014 picks ElevenLabs when key set, else Kokoro local)",
+  "TTS provider: auto, elevenlabs, openai, kokoro (default auto \u2014 ElevenLabs key > OpenAI key > Kokoro local)",
   "auto"
-).option("--voice <id>", "Voice id (ElevenLabs name/id, or Kokoro id like af_heart, am_michael)").option(
+).option("--voice <id>", "Voice id (ElevenLabs name/id, OpenAI voice like marin, or Kokoro id like af_heart)").option(
   "--no-audio",
   "Skip TTS even when --narration is provided (useful for tests/agent dry runs)"
 ).option("--no-image", "Skip image generation even when --visuals is provided").option(
@@ -52667,6 +53721,7 @@ sceneCommand.command("add").description("Add a new scene to a project: AI narrat
           kicker: options.kicker,
           project: options.project,
           insertInto: options.insertInto,
+          syncStoryboard: options.storyboard !== false,
           imageProvider: options.imageProvider,
           tts,
           audio: options.audio,
@@ -52694,6 +53749,7 @@ sceneCommand.command("add").description("Add a new scene to a project: AI narrat
       kicker: options.kicker,
       projectDir: options.project,
       insertInto: options.insertInto,
+      syncStoryboard: options.storyboard !== false,
       imageProvider: options.imageProvider,
       tts,
       voice: options.voice,
@@ -52733,6 +53789,13 @@ sceneCommand.command("add").description("Add a new scene to a project: AI narrat
     if (result.audioPath) console.log(source_default.green("  +"), result.audioPath);
     if (result.imagePath) console.log(source_default.green("  +"), result.imagePath);
     if (result.transcriptPath) console.log(source_default.green("  +"), result.transcriptPath);
+    if (result.storyboardPath && result.storyboardSynced) {
+      console.log(
+        result.storyboardAction === "updated" ? source_default.yellow("  ~") : source_default.green("  +"),
+        result.storyboardPath,
+        source_default.dim(`(${result.storyboardAction})`)
+      );
+    }
     console.log(source_default.yellow("  ~"), result.rootPath, source_default.dim("(updated)"));
     console.log();
     console.log(source_default.bold.cyan("Composition"));
@@ -52779,6 +53842,21 @@ async function loadVibeProjectConfig(projectDir) {
     }
   };
 }
+function escapeRegExp3(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function readClipStart(rootHtml, beatId) {
+  const compositionId = sceneCompositionId(beatId);
+  const match = rootHtml.match(
+    new RegExp(
+      `<div\\s+class="clip"[^>]*\\bdata-composition-id="${escapeRegExp3(compositionId)}"[^>]*\\bdata-start="([\\d.]+)"`,
+      "i"
+    )
+  );
+  if (!match) return void 0;
+  const start = Number.parseFloat(match[1]);
+  return Number.isFinite(start) ? start : void 0;
+}
 async function resolveNarrationText(value) {
   if (!value) return void 0;
   const looksLikePath = /\.[a-z]{2,4}$/i.test(value) || value.includes("/") || value.includes("\\");
@@ -52805,6 +53883,7 @@ async function executeSceneAdd(opts) {
   const id = slugifySceneName(opts.name);
   const sceneRel = `compositions/scene-${id}.html`;
   const scenePath = resolve17(projectDir, sceneRel);
+  const storyboardAbsPath = resolve17(projectDir, "STORYBOARD.md");
   const errResult = (error) => ({
     success: false,
     id,
@@ -52863,7 +53942,7 @@ async function executeSceneAdd(opts) {
       throw error;
     }
     opts.onProgress?.(
-      resolution.provider === "kokoro" ? "Generating narration with Kokoro (local \u2014 first run downloads ~330MB)..." : "Generating narration with ElevenLabs..."
+      resolution.provider === "kokoro" ? "Generating narration with Kokoro (local \u2014 first run downloads a ~90MB model)..." : resolution.provider === "openai" ? "Generating narration with OpenAI (gpt-4o-mini-tts)..." : "Generating narration with ElevenLabs..."
     );
     const tts = await resolution.call(narrationText, {
       voice: opts.voice,
@@ -53024,6 +54103,27 @@ async function executeSceneAdd(opts) {
     duration = fallback2;
   }
   duration = Number(duration.toFixed(2));
+  let storyboardPath;
+  let storyboardSynced = false;
+  let storyboardAction = "skipped";
+  const shouldSyncStoryboard = opts.syncStoryboard !== false && await pathExists2(storyboardAbsPath);
+  if (shouldSyncStoryboard) {
+    opts.onProgress?.("Syncing STORYBOARD.md...");
+    const before = await readFile14(storyboardAbsPath, "utf-8");
+    const synced = upsertStoryboardBeat(before, {
+      beatId: id,
+      title: opts.headline,
+      duration,
+      narration: narrationText && !opts.skipAudio ? narrationText : void 0,
+      backdrop: opts.visuals && !opts.skipImage ? opts.visuals : void 0
+    });
+    if (synced.markdown !== before) {
+      await writeFile15(storyboardAbsPath, synced.markdown, "utf-8");
+    }
+    storyboardPath = relative6(process.cwd(), storyboardAbsPath) || storyboardAbsPath;
+    storyboardSynced = true;
+    storyboardAction = synced.action;
+  }
   opts.onProgress?.("Emitting scene HTML...");
   const sceneHtml = emitSceneHtml({
     id,
@@ -53042,11 +54142,24 @@ async function executeSceneAdd(opts) {
   await mkdir8(dirname6(scenePath), { recursive: true });
   await writeFile15(scenePath, sceneHtml, "utf-8");
   opts.onProgress?.("Updating root composition...");
-  const start = nextSceneStart(rootHtmlBefore, SCENE_OVERLAP_SECONDS);
-  const existingClipCount = (rootHtmlBefore.match(/<div\s+class="clip"/g) || []).length;
-  const trackIndex = existingClipCount % 2 + 1;
-  const updated = insertClipIntoRoot(rootHtmlBefore, { id, start, duration, trackIndex });
-  await writeFile15(rootPath, updated, "utf-8");
+  let start = 0;
+  if (storyboardSynced) {
+    const syncPlan = await syncRootComposition({
+      projectDir,
+      rootRel,
+      beats: await loadProjectRootSyncBeats(projectDir)
+    });
+    const blockingIssue = syncPlan.issues.find((issue) => issue.severity === "error");
+    if (blockingIssue) return errResult(blockingIssue.message);
+    const rootHtmlAfterSync = await readFile14(rootPath, "utf-8");
+    start = readClipStart(rootHtmlAfterSync, id) ?? 0;
+  } else {
+    start = nextSceneStart(rootHtmlBefore, SCENE_OVERLAP_SECONDS);
+    const existingClipCount = (rootHtmlBefore.match(/<div\s+class="clip"/g) || []).length;
+    const trackIndex = existingClipCount % 2 + 1;
+    const updated = insertClipIntoRoot(rootHtmlBefore, { id, start, duration, trackIndex });
+    await writeFile15(rootPath, updated, "utf-8");
+  }
   const transcriptAbsPath = transcriptRelPath ? resolve17(projectDir, transcriptRelPath) : void 0;
   return {
     success: true,
@@ -53059,6 +54172,9 @@ async function executeSceneAdd(opts) {
     audioPath: audioAbsPath ? relative6(process.cwd(), audioAbsPath) || audioAbsPath : void 0,
     imagePath: imageAbsPath ? relative6(process.cwd(), imageAbsPath) || imageAbsPath : void 0,
     lottiePath: lottieAbsPath ? relative6(process.cwd(), lottieAbsPath) || lottieAbsPath : void 0,
+    storyboardPath,
+    storyboardSynced,
+    storyboardAction,
     transcriptPath: transcriptAbsPath ? relative6(process.cwd(), transcriptAbsPath) || transcriptAbsPath : void 0,
     transcriptWordCount
   };
@@ -53356,6 +54472,9 @@ var sceneAddSchema = external_exports.object({
   kicker: external_exports.string().optional().describe("Small label above the headline (used by 'explainer' and 'product-shot' presets)."),
   projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION),
   insertInto: external_exports.string().optional().describe("Root composition file (relative to projectDir). Default 'index.html'."),
+  syncStoryboard: external_exports.boolean().optional().describe(
+    "Sync STORYBOARD.md when present, then rebuild root refs from it. Default true; set false for root-only insertion."
+  ),
   imageProvider: external_exports.enum(["gemini", "openai"]).optional().describe("Image provider for visuals. Default 'gemini'."),
   voice: external_exports.string().optional().describe("ElevenLabs voice id or name."),
   skipAudio: external_exports.boolean().optional().describe("Skip TTS even if narration is provided."),
@@ -53368,7 +54487,7 @@ var sceneAddTool = defineTool({
   cost: "low",
   title: "Add Scene from Preset",
   annotations: { readOnly: false, openWorld: true },
-  description: "Add a single scene to an existing scene project. Optionally generates narration audio (ElevenLabs) and/or a backdrop image (Gemini/OpenAI), then emits compositions/scene-<id>.html with a paused GSAP timeline and splices a clip reference into the root index.html. Use skipAudio:true and skipImage:true for text-only scenes that need no API calls.",
+  description: "Add a single scene to an existing scene project. Optionally generates narration audio (ElevenLabs) and/or a backdrop image (Gemini/OpenAI), then emits compositions/scene-<id>.html with a paused GSAP timeline. By default, syncs STORYBOARD.md and rebuilds root refs from it; set syncStoryboard:false for root-only insertion. Use skipAudio:true and skipImage:true for text-only scenes that need no API calls.",
   schema: sceneAddSchema,
   async execute(args, ctx) {
     const projectDir = args.projectDir ? resolve26(ctx.workingDirectory, args.projectDir) : ctx.workingDirectory;
@@ -53382,6 +54501,7 @@ var sceneAddTool = defineTool({
       kicker: args.kicker,
       projectDir,
       insertInto: args.insertInto,
+      syncStoryboard: args.syncStoryboard,
       imageProvider: args.imageProvider,
       voice: args.voice,
       skipAudio: args.skipAudio,
@@ -53400,6 +54520,9 @@ var sceneAddTool = defineTool({
     ];
     if (result.audioPath) lines.push(`   audio:    ${result.audioPath}`);
     if (result.imagePath) lines.push(`   image:    ${result.imagePath}`);
+    if (result.storyboardPath && result.storyboardSynced) {
+      lines.push(`   story:    ${result.storyboardPath} (${result.storyboardAction})`);
+    }
     return {
       success: true,
       data: {
@@ -53410,7 +54533,10 @@ var sceneAddTool = defineTool({
         scenePath: result.scenePath,
         rootPath: result.rootPath,
         audioPath: result.audioPath,
-        imagePath: result.imagePath
+        imagePath: result.imagePath,
+        storyboardPath: result.storyboardPath,
+        storyboardSynced: result.storyboardSynced,
+        storyboardAction: result.storyboardAction
       },
       humanLines: lines
     };
@@ -53623,7 +54749,9 @@ var sceneBuildSchema = external_exports.object({
   skipVideo: external_exports.boolean().optional().describe("Skip video generation for every beat (use existing MP4 assets if present)."),
   skipMusic: external_exports.boolean().optional().describe("Skip music generation for every beat (use existing audio assets if present)."),
   skipRender: external_exports.boolean().optional().describe("Stop after compose \u2014 produces compositions/*.html but no final MP4."),
-  ttsProvider: external_exports.enum(["auto", "elevenlabs", "kokoro"]).optional().describe("TTS provider override. Default 'auto'."),
+  ttsProvider: external_exports.enum(["auto", "elevenlabs", "openai", "kokoro"]).optional().describe(
+    "TTS provider override. Default 'auto' (elevenlabs key > openai key > local kokoro)."
+  ),
   voice: external_exports.string().optional().describe("TTS voice id (provider-specific)."),
   imageProvider: external_exports.enum(["openai"]).optional().describe("Image provider for backdrops. Default 'openai' (gpt-image-2)."),
   videoProvider: external_exports.enum(["seedance", "grok", "kling", "runway", "veo"]).optional().describe("Video provider for per-beat video cues. Default seedance."),
@@ -55069,7 +56197,11 @@ async function inspectProject(opts) {
   );
 }
 function makeProjectResult(projectDir, issues, checks, retryWith, beatId) {
-  const normalizedIssues = normalizeReviewIssues(issues);
+  const normalizedRetryWith = uniqueRetryWith(retryWith);
+  const normalizedIssues = normalizeReviewIssues(issues, {
+    projectDir,
+    retryWith: normalizedRetryWith
+  });
   const status = statusFromIssues(normalizedIssues);
   return {
     schemaVersion: "1",
@@ -55081,9 +56213,14 @@ function makeProjectResult(projectDir, issues, checks, retryWith, beatId) {
     score: scoreIssues(normalizedIssues),
     issues: normalizedIssues,
     summary: summarizeReviewIssues(normalizedIssues),
+    nextActions: deriveNextReviewActions({
+      issues: normalizedIssues,
+      retryWith: normalizedRetryWith,
+      projectDir
+    }),
     sourceReports: projectSourceReports(checks),
     checks,
-    retryWith: uniqueRetryWith(retryWith)
+    retryWith: normalizedRetryWith
   };
 }
 function storyboardPlaceholderIssues(storyboard) {
@@ -55635,6 +56772,8 @@ async function inspectRender(opts) {
       severity: "error",
       code: "RENDER_NOT_FOUND",
       message: opts.beatId ? `No rendered video was found for beat "${opts.beatId}". Pass --video or render the beat first.` : "No rendered video was found. Pass --video or render the project first.",
+      beatId: opts.beatId,
+      scene: opts.beatId,
       suggestedFix: opts.beatId ? "Run `vibe render <project> --beat <id> --json`." : "Run `vibe build --stage render --json` or `vibe render --json`."
     });
     retryWith.push(
@@ -55657,6 +56796,8 @@ async function inspectRender(opts) {
       code: "EMPTY_RENDER",
       message: "Rendered video file is empty.",
       file: displayPath(videoPath),
+      beatId: opts.beatId,
+      scene: opts.beatId,
       suggestedFix: opts.beatId ? "Render again with `vibe render --beat <id> --json`." : "Render again with `vibe render --json`."
     });
     retryWith.push(
@@ -55666,6 +56807,8 @@ async function inspectRender(opts) {
   const beatTimings = await beatTimingsFromBuildReport(projectDir, opts.beatId);
   const expectedDurationSec = beatTimings.length > 0 ? Number(beatTimings.reduce((sum, beat) => sum + beat.sceneDurationSec, 0).toFixed(3)) : await expectedDurationFromBuildReport(projectDir, opts.beatId);
   if (expectedDurationSec !== void 0) checks.expectedDurationSec = expectedDurationSec;
+  const expectedAudio = await renderExpectsAudio(projectDir, opts.beatId);
+  checks.expectedAudio = expectedAudio;
   if (!commandExists("ffprobe")) {
     issues.push({
       severity: "error",
@@ -55691,7 +56834,7 @@ async function inspectRender(opts) {
           file: displayPath(videoPath)
         });
       }
-      if (!audioStream) {
+      if (!audioStream && expectedAudio) {
         issues.push({
           severity: "warning",
           code: "NO_AUDIO_STREAM",
@@ -55896,8 +57039,86 @@ async function inspectRender(opts) {
   );
   return maybeWriteRenderReport(projectDir, opts, result);
 }
+async function renderExpectsAudio(projectDir, beatId) {
+  const root = resolve42(projectDir);
+  const rootHtml = await readTextIfExists(join22(root, "index.html"));
+  if (rootHtml && rootHtmlExpectsAudio(rootHtml, beatId)) return true;
+  const buildReport = await readJsonIfExists(join22(root, "build-report.json"));
+  if (buildReportExpectsAudio(buildReport, beatId)) return true;
+  const storyboard = await readTextIfExists(join22(root, "STORYBOARD.md"));
+  if (!storyboard) return false;
+  try {
+    const parsed = parseStoryboard(storyboard);
+    const beats = beatId ? parsed.beats.filter((beat) => beat.id === beatId) : parsed.beats;
+    return beats.some(
+      (beat) => [
+        `assets/narration-${beat.id}.mp3`,
+        `assets/narration-${beat.id}.wav`,
+        `assets/music-${beat.id}.mp3`,
+        `assets/music-${beat.id}.wav`
+      ].some((asset) => existsSync39(join22(root, asset)))
+    );
+  } catch {
+    return false;
+  }
+}
+function rootHtmlExpectsAudio(html, beatId) {
+  const audioTags = html.match(/<audio\b[^>]*>/gi) ?? [];
+  if (!beatId) return audioTags.length > 0;
+  const escaped = escapeRegExp4(beatId);
+  const beatAudioRe = new RegExp(
+    `(id="(?:narration|music)-${escaped}"|src="[^"]*(?:narration|music)-${escaped}\\.(?:mp3|wav)")`,
+    "i"
+  );
+  return audioTags.some((tag) => beatAudioRe.test(tag));
+}
+function buildReportExpectsAudio(report, beatId) {
+  if (!report || typeof report !== "object") return false;
+  const beats = Array.isArray(report.beats) ? report.beats ?? [] : [];
+  const selected = beatId === void 0 ? beats : beats.filter((beat) => {
+    if (!beat || typeof beat !== "object") return false;
+    return beat.id === beatId;
+  });
+  return selected.some((beat) => beatReportExpectsAudio(beat));
+}
+function beatReportExpectsAudio(beat) {
+  if (!beat || typeof beat !== "object") return false;
+  const record = beat;
+  if (typeof record.narrationPath === "string" && record.narrationPath.length > 0) return true;
+  if (typeof record.musicPath === "string" && record.musicPath.length > 0) return true;
+  if (parseOptionalNumber2(record.narrationDurationSec) !== void 0) return true;
+  const narration = record.narration;
+  if (narration && typeof narration === "object") {
+    const n = narration;
+    if (typeof n.path === "string" && n.path.length > 0) return true;
+    if (parseOptionalNumber2(n.durationSec) !== void 0) return true;
+  }
+  const music = record.music;
+  if (music && typeof music === "object") {
+    const m = music;
+    if (typeof m.path === "string" && m.path.length > 0) return true;
+    if (parseOptionalNumber2(m.durationSec) !== void 0) return true;
+  }
+  return false;
+}
+async function readJsonIfExists(path2) {
+  const text = await readTextIfExists(path2);
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function escapeRegExp4(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function makeRenderResult(projectDir, opts, videoPath, issues, checks, retryWith, score) {
-  const normalizedIssues = normalizeReviewIssues(issues);
+  const normalizedRetryWith = uniqueRetryWith(retryWith);
+  const normalizedIssues = normalizeReviewIssues(issues, {
+    projectDir,
+    retryWith: normalizedRetryWith
+  });
   const status = statusFromIssues(normalizedIssues);
   return {
     schemaVersion: "1",
@@ -55910,9 +57131,14 @@ function makeRenderResult(projectDir, opts, videoPath, issues, checks, retryWith
     score,
     issues: normalizedIssues,
     summary: summarizeReviewIssues(normalizedIssues),
+    nextActions: deriveNextReviewActions({
+      issues: normalizedIssues,
+      retryWith: normalizedRetryWith,
+      projectDir
+    }),
     sourceReports: renderSourceReports(projectDir, videoPath, checks),
     checks,
-    retryWith: uniqueRetryWith(retryWith)
+    retryWith: normalizedRetryWith
   };
 }
 async function maybeWriteRenderReport(projectDir, opts, result) {
@@ -57461,7 +58687,7 @@ var planTool = defineTool({
     skipBackdrop: external_exports.boolean().optional().describe("Don't include backdrop image generation in the plan."),
     skipVideo: external_exports.boolean().optional().describe("Don't include video generation in the plan."),
     skipMusic: external_exports.boolean().optional().describe("Don't include music generation in the plan."),
-    ttsProvider: external_exports.enum(["auto", "elevenlabs", "kokoro"]).optional().describe("TTS provider override."),
+    ttsProvider: external_exports.enum(["auto", "elevenlabs", "openai", "kokoro"]).optional().describe("TTS provider override."),
     voice: external_exports.string().optional().describe("Voice id."),
     imageProvider: external_exports.string().optional().describe("Image provider override."),
     imageQuality: external_exports.enum(["standard", "hd"]).optional().describe("Image quality override."),