@vibeframe/cli 0.112.1 → 0.113.2

package/dist/index.js

@@ -7066,8 +7066,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-..." }
     });
@@ -9174,8 +9174,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",
@@ -11597,16 +11597,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);
   }
 }
@@ -11626,10 +11629,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: readFile56, writeFile: writeFile61, mkdir: mkdir31 } = await import("node:fs/promises");
+    const { join: join30, resolve: resolve86 } = await import("node:path");
+    const { pathToFileURL } = await import("node:url");
+    const { homedir: homedir8 } = await import("node:os");
+    const transformersDir = resolve86(base, "node_modules", "@huggingface", "transformers");
+    const ortDistDir = resolve86(base, "node_modules", "onnxruntime-web", "dist");
+    const transformers = await import(pathToFileURL(join30(transformersDir, "dist", "transformers.web.js")).href);
+    const cacheRoot = join30(homedir8(), ".cache", "vibeframe", "models");
+    transformers.env.allowLocalModels = false;
+    transformers.env.useCustomCache = true;
+    transformers.env.customCache = {
+      async match(key) {
+        try {
+          return new Response(await readFile56(join30(cacheRoot, encodeURIComponent(String(key)))));
+        } catch {
+          return void 0;
+        }
+      },
+      async put(key, response) {
+        try {
+          const buf = Buffer.from(await response.arrayBuffer());
+          await mkdir31(cacheRoot, { recursive: true });
+          await writeFile61(join30(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));
 }
@@ -11637,10 +11681,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) => {
@@ -11724,7 +11770,7 @@ var init_kokoro = __esm({
       label: "Kokoro (local)",
       apiKey: null,
       kinds: ["speech"],
-      resolverPriority: { speech: 2 }
+      resolverPriority: { speech: 3 }
     });
   }
 });
@@ -11996,12 +12042,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";
@@ -12044,7 +12197,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: "",
@@ -12306,11 +12459,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() {
@@ -12373,7 +12526,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";
@@ -12744,11 +12897,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";
@@ -12915,7 +13068,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"
@@ -17181,6 +17334,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);
@@ -17290,7 +17456,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";
@@ -17310,6 +17476,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";
@@ -18122,9 +18292,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,
@@ -18132,6 +18304,7 @@ __export(dist_exports2, {
   defineApiKey: () => defineApiKey,
   defineProvider: () => defineProvider,
   elevenLabsProvider: () => elevenLabsProvider,
+  estimateSeedanceVideoCostUsd: () => estimateSeedanceVideoCostUsd,
   falProvider: () => falProvider,
   geminiProvider: () => geminiProvider,
   getAllApiKeys: () => getAllApiKeys,
@@ -18148,9 +18321,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,
@@ -18173,6 +18349,7 @@ var init_dist2 = __esm({
     init_elevenlabs();
     init_kokoro();
     init_openai_image();
+    init_openai_tts();
     init_runway();
     init_kling();
     init_grok();
@@ -26347,10 +26524,22 @@ var init_api_key = __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() {
@@ -26366,6 +26555,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({});
@@ -26378,11 +26580,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;
@@ -26394,7 +26596,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";
@@ -26821,6 +27023,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
@@ -27316,6 +27555,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, "");
@@ -27352,10 +27594,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;
@@ -27378,8 +27626,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;
@@ -27411,7 +27668,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}`
       };
     }
@@ -27450,12 +27707,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);
@@ -27497,7 +27754,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}`
@@ -27538,12 +27795,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} {
@@ -27577,7 +27834,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);` : ""}`
@@ -27638,9 +27895,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"
@@ -27656,7 +27914,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}
@@ -27692,8 +27950,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);
@@ -29171,6 +29430,39 @@ var init_install_skill = __esm({
 });
 
 // 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);
@@ -29776,7 +30068,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.
@@ -30694,6 +30994,101 @@ function uniqueRetryWith(items) {
     ...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";
@@ -30703,11 +31098,23 @@ function fixOwnerForIssue(issue) {
   }
   return "vibe";
 }
-function normalizeReviewIssues(issues, fallbackOwner) {
-  return issues.map((issue) => ({
-    ...issue,
-    fixOwner: issue.fixOwner ?? fallbackOwner ?? fixOwnerForIssue(issue)
-  }));
+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);
@@ -30723,7 +31130,11 @@ function summarizeReviewIssues(issues) {
   };
 }
 function buildReviewReport(opts) {
-  const issues = normalizeReviewIssues(opts.issues);
+  const retryWith = uniqueRetryWith(opts.retryWith);
+  const issues = normalizeReviewIssues(opts.issues, {
+    projectDir: opts.project,
+    retryWith
+  });
   return stripUndefined({
     schemaVersion: "1",
     kind: "review",
@@ -30734,7 +31145,8 @@ function buildReviewReport(opts) {
     score: opts.score,
     issues,
     summary: summarizeReviewIssues(issues),
-    retryWith: uniqueRetryWith(opts.retryWith),
+    nextActions: deriveNextReviewActions({ issues, retryWith, projectDir: opts.project }),
+    retryWith,
     sourceReports: opts.sourceReports ?? [],
     reportPath: opts.reportPath
   });
@@ -30748,6 +31160,306 @@ async function writeReviewReport(path2, report) {
 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";
@@ -30880,6 +31592,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/commands/scene.ts
 import { resolve as resolve17, relative as relative6, dirname as dirname4 } from "node:path";
 import { mkdir as mkdir7, readFile as readFile13, writeFile as writeFile12, access as access5, copyFile } from "node:fs/promises";
@@ -30929,6 +31932,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("\\");
@@ -30955,6 +31973,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,
@@ -31013,7 +32032,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,
@@ -31174,6 +32193,27 @@ async function executeSceneAdd(opts) {
     duration = fallback2;
   }
   duration = Number(duration.toFixed(2));
+  let storyboardPath2;
+  let storyboardSynced = false;
+  let storyboardAction = "skipped";
+  const shouldSyncStoryboard = opts.syncStoryboard !== false && await pathExists2(storyboardAbsPath);
+  if (shouldSyncStoryboard) {
+    opts.onProgress?.("Syncing STORYBOARD.md...");
+    const before = await readFile13(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 writeFile12(storyboardAbsPath, synced.markdown, "utf-8");
+    }
+    storyboardPath2 = relative6(process.cwd(), storyboardAbsPath) || storyboardAbsPath;
+    storyboardSynced = true;
+    storyboardAction = synced.action;
+  }
   opts.onProgress?.("Emitting scene HTML...");
   const sceneHtml = emitSceneHtml({
     id,
@@ -31192,11 +32232,24 @@ async function executeSceneAdd(opts) {
   await mkdir7(dirname4(scenePath), { recursive: true });
   await writeFile12(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 writeFile12(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 readFile13(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 writeFile12(rootPath, updated, "utf-8");
+  }
   const transcriptAbsPath = transcriptRelPath ? resolve17(projectDir, transcriptRelPath) : void 0;
   return {
     success: true,
@@ -31209,6 +32262,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: storyboardPath2,
+    storyboardSynced,
+    storyboardAction,
     transcriptPath: transcriptAbsPath ? relative6(process.cwd(), transcriptAbsPath) || transcriptAbsPath : void 0,
     transcriptWordCount
   };
@@ -31250,6 +32306,8 @@ var init_scene = __esm({
     init_compose_prompts();
     init_scene_submit();
     init_scene_repair();
+    init_root_sync();
+    init_storyboard_edit();
     sceneCommand = new Command("scene").description(
       "Lower-level scene authoring (add, lint, list-styles). For project flow use `vibe init` / `vibe build` / `vibe render`."
     ).addHelpText(
@@ -31534,11 +32592,14 @@ Run 'vibe schema scene.<command>' for structured parameter info.`
     ).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(
@@ -31603,6 +32664,7 @@ Run 'vibe schema scene.<command>' for structured parameter info.`
               kicker: options.kicker,
               project: options.project,
               insertInto: options.insertInto,
+              syncStoryboard: options.storyboard !== false,
               imageProvider: options.imageProvider,
               tts,
               audio: options.audio,
@@ -31630,6 +32692,7 @@ Run 'vibe schema scene.<command>' for structured parameter info.`
           kicker: options.kicker,
           projectDir: options.project,
           insertInto: options.insertInto,
+          syncStoryboard: options.storyboard !== false,
           imageProvider: options.imageProvider,
           tts,
           voice: options.voice,
@@ -31669,6 +32732,13 @@ Run 'vibe schema scene.<command>' for structured parameter info.`
         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"));
@@ -35477,6 +36547,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",
@@ -35488,6 +36562,7 @@ async function inspectProjectStatus(projectDirArg, opts = {}) {
     review,
     jobs,
     warnings,
+    nextActions,
     retryWith: unique(retryWith)
   };
 }
@@ -35781,9 +36856,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,
@@ -35995,6 +37105,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";
 }
@@ -36060,6 +37173,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;
   }
@@ -38941,10 +40055,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,
@@ -44132,208 +45254,6 @@ var init_ai_review = __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/scene-inspect.ts
 import { existsSync as existsSync34 } from "node:fs";
 import { readdir as readdir4, readFile as readFile29, stat as stat5 } from "node:fs/promises";
@@ -44566,7 +45486,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",
@@ -44578,9 +45502,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) {
@@ -45122,6 +46051,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(
@@ -45144,6 +46075,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(
@@ -45153,6 +46086,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",
@@ -45178,7 +46113,7 @@ async function inspectRender(opts) {
           file: displayPath(videoPath)
         });
       }
-      if (!audioStream) {
+      if (!audioStream && expectedAudio) {
         issues.push({
           severity: "warning",
           code: "NO_AUDIO_STREAM",
@@ -45383,8 +46318,86 @@ async function inspectRender(opts) {
   );
   return maybeWriteRenderReport(projectDir, opts, result);
 }
+async function renderExpectsAudio(projectDir, beatId) {
+  const root = resolve43(projectDir);
+  const rootHtml = await readTextIfExists(join19(root, "index.html"));
+  if (rootHtml && rootHtmlExpectsAudio(rootHtml, beatId)) return true;
+  const buildReport = await readJsonIfExists(join19(root, "build-report.json"));
+  if (buildReportExpectsAudio(buildReport, beatId)) return true;
+  const storyboard = await readTextIfExists(join19(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) => existsSync35(join19(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 (parseOptionalNumber(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 (parseOptionalNumber(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 (parseOptionalNumber(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",
@@ -45397,9 +46410,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) {
@@ -59403,6 +60421,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"]
     };
@@ -59440,6 +60459,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":
@@ -59459,6 +60488,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"
   });
 }
@@ -59619,13 +60650,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,
@@ -59686,7 +60717,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({
@@ -59797,6 +60832,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 || !existsSync47(join23(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,
@@ -60043,17 +61093,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) {
@@ -60149,7 +61202,7 @@ function loadPlanEnv(projectDir) {
     dir = dirname21(dir);
   }
 }
-var import_dotenv3, VIDEO_COST_USD, MUSIC_COST_USD, ELEVENLABS_NARRATION_COST_USD, COMPOSE_COST_USD, SUPPORTED_BUILD_IMAGE_PROVIDERS;
+var import_dotenv3, 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";
@@ -60158,6 +61211,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();
@@ -60167,6 +61221,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"];
   }
@@ -60984,7 +62039,7 @@ __export(scene_build_exports, {
   executeSceneBuild: () => executeSceneBuild,
   resolveSceneBuildMode: () => resolveSceneBuildMode
 });
-import { existsSync as existsSync49 } from "node:fs";
+import { existsSync as existsSync49, readFileSync as readFileSync3 } from "node:fs";
 import { copyFile as copyFile5, mkdir as mkdir26, readFile as readFile46, writeFile as writeFile50 } from "node:fs/promises";
 import { dirname as dirname24, join as join25, resolve as resolve65 } from "node:path";
 async function executeSceneBuild(opts) {
@@ -61151,8 +62206,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,
@@ -61170,7 +62249,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);
@@ -61179,10 +62259,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`
     );
@@ -61347,6 +62424,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 = join25(projectDir, "compositions", `scene-${beat.id}.html`);
+      if (!existsSync49(join25(projectDir, videoRel)) || !existsSync49(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);
@@ -61767,6 +62856,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 (existsSync49(join25(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 = join25(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 (existsSync49(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 = join25(ctx.projectDir, cache.path);
+    if (existsSync49(cacheAbs) && !ctx.force) {
+      await mkdir26(dirname24(abs), { recursive: true });
+      await copyFile5(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 mkdir26(dirname24(abs), { recursive: true });
+    await writeFile50(abs, generated.buffer);
+    await mkdir26(dirname24(cacheAbs), { recursive: true });
+    await writeFile50(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);
@@ -61936,13 +63139,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) => join25(ctx.projectDir, p));
   const rel = `assets/video-${beat.id}.mp4`;
   const abs = join25(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 (existsSync49(abs) && !ctx.force) {
@@ -62002,6 +63208,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) {
@@ -62370,7 +63577,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));
@@ -67930,8 +69143,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");
@@ -67987,7 +69201,7 @@ var NARRATION_CHOICES, BACKDROP_CHOICES;
 var init_elicit = __esm({
   "src/tools/_shared/elicit.ts"() {
     "use strict";
-    NARRATION_CHOICES = ["kokoro", "elevenlabs"];
+    NARRATION_CHOICES = ["kokoro", "openai", "elevenlabs"];
     BACKDROP_CHOICES = ["skip", "openai"];
   }
 });
@@ -68266,6 +69480,9 @@ var init_scene2 = __esm({
       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."),
@@ -68278,7 +69495,7 @@ var init_scene2 = __esm({
       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 ? resolve75(ctx.workingDirectory, args.projectDir) : ctx.workingDirectory;
@@ -68292,6 +69509,7 @@ var init_scene2 = __esm({
           kicker: args.kicker,
           projectDir,
           insertInto: args.insertInto,
+          syncStoryboard: args.syncStoryboard,
           imageProvider: args.imageProvider,
           voice: args.voice,
           skipAudio: args.skipAudio,
@@ -68310,6 +69528,9 @@ var init_scene2 = __esm({
         ];
         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: {
@@ -68320,7 +69541,10 @@ var init_scene2 = __esm({
             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
         };
@@ -68465,7 +69689,9 @@ var init_scene2 = __esm({
       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."),
@@ -70320,7 +71546,7 @@ var init_storyboard2 = __esm({
         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."),
@@ -73436,7 +74662,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.112.1",
+  version: "0.113.2",
   description: "VibeFrame CLI - agentic video workflow runtime",
   private: false,
   license: "MIT",
@@ -73501,7 +74727,7 @@ var package_default = {
     lint: "eslint --ext .ts,.tsx src/",
     test: "vitest run",
     "test:watch": "vitest",
-    pretest: "node build.js",
+    pretest: "pnpm --dir ../core build && pnpm --dir ../ai-providers build && node build.js",
     prepublishOnly: "node build.js"
   },
   dependencies: {
@@ -82019,13 +83245,13 @@ function titleizeProjectName(name) {
   return name.split(/[-_\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ") || "Video";
 }
 function describeTheme(brief, product) {
-  const cleaned = brief.replace(/\b\d+[- ]?second\b/gi, "").replace(new RegExp(`\\bfor\\s+${escapeRegExp3(product)}\\b`, "i"), "").replace(/\blaunch video\b/gi, "launch story").replace(/\s+/g, " ").trim();
+  const cleaned = brief.replace(/\b\d+[- ]?second\b/gi, "").replace(new RegExp(`\\bfor\\s+${escapeRegExp5(product)}\\b`, "i"), "").replace(/\blaunch video\b/gi, "launch story").replace(/\s+/g, " ").trim();
   return cleaned || "focused product story";
 }
 function isMountainSunriseBrief(brief) {
   return /\b(mountain|ridge|sunrise|fog|peak)\b/i.test(brief);
 }
-function escapeRegExp3(value) {
+function escapeRegExp5(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
@@ -82068,6 +83294,7 @@ function hostDefinitions(_projectDir = process.cwd()) {
       configKind: "codex-toml",
       notes: [
         "Codex reads AGENTS.md and can also load project-scoped .codex/config.toml after the project is trusted.",
+        "Use Codex /goal as the outer loop for long-running VibeFrame projects; vibe supplies JSON reports, nextActions classified by cost/safety (prefer these), retryWith as a compatibility fallback, and repair commands.",
         "Keep provider/auth keys in VibeFrame config or environment, not in project-local Codex config."
       ]
     },
@@ -82080,6 +83307,7 @@ function hostDefinitions(_projectDir = process.cwd()) {
       configKind: "mcp-json",
       notes: [
         "Claude Code can drive vibe directly through shell plus AGENTS.md/CLAUDE.md.",
+        "Use Claude Code /goal as the outer loop for long-running VibeFrame projects; vibe supplies JSON reports, nextActions classified by cost/safety (prefer these), retryWith as a compatibility fallback, and repair commands.",
         "The MCP entry is optional and gives Claude Code a typed tool surface."
       ]
     },
@@ -82154,7 +83382,15 @@ async function planHostSetup(host, projectDir, opts) {
       status: opts.write ? "would-merge" : "would-write",
       reason: opts.write ? "dry run" : "snippet only; pass --write to modify"
     });
-    return { host, snippet, command: host.id === "claude-code" ? claudeCodeAddCommand() : void 0, configPath, files, warnings, nextSteps };
+    return {
+      host,
+      snippet,
+      command: host.id === "claude-code" ? claudeCodeAddCommand() : void 0,
+      configPath,
+      files,
+      warnings,
+      nextSteps
+    };
   }
   try {
     const action = host.configKind === "codex-toml" ? await mergeCodexToml(configPath, { force: opts.force === true }) : await mergeMcpJson(configPath, {
@@ -82166,7 +83402,15 @@ async function planHostSetup(host, projectDir, opts) {
   } catch (error) {
     warnings.push(error instanceof Error ? error.message : String(error));
   }
-  return { host, snippet, command: host.id === "claude-code" ? claudeCodeAddCommand() : void 0, configPath, files, warnings, nextSteps };
+  return {
+    host,
+    snippet,
+    command: host.id === "claude-code" ? claudeCodeAddCommand() : void 0,
+    configPath,
+    files,
+    warnings,
+    nextSteps
+  };
 }
 async function inspectHost(host, projectDir) {
   const configPath = host.configPath(projectDir);
@@ -82210,7 +83454,9 @@ async function mergeMcpJson(configPath, opts) {
     try {
       root = raw.trim() ? JSON.parse(raw) : {};
     } catch (error) {
-      throw new Error(`Invalid JSON in ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(
+        `Invalid JSON in ${configPath}: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
   }
   const mcpServers = typeof root.mcpServers === "object" && root.mcpServers !== null && !Array.isArray(root.mcpServers) ? root.mcpServers : {};
@@ -82223,10 +83469,18 @@ async function mergeMcpJson(configPath, opts) {
       };
       await mkdir23(dirname19(configPath), { recursive: true });
       if (exists && opts.backup) {
-        await writeFile45(`${configPath}.bak-${timestamp()}`, await readFile39(configPath, "utf-8"), "utf-8");
+        await writeFile45(
+          `${configPath}.bak-${timestamp()}`,
+          await readFile39(configPath, "utf-8"),
+          "utf-8"
+        );
       }
       await writeFile45(configPath, JSON.stringify(root, null, 2) + "\n", "utf-8");
-      return { path: configPath, status: "merged", reason: "anchored existing default vibeframe MCP server" };
+      return {
+        path: configPath,
+        status: "merged",
+        reason: "anchored existing default vibeframe MCP server"
+      };
     }
     return {
       path: configPath,
@@ -82237,7 +83491,11 @@ async function mergeMcpJson(configPath, opts) {
   root.mcpServers = { ...mcpServers, vibeframe: opts.server };
   await mkdir23(dirname19(configPath), { recursive: true });
   if (exists && opts.backup) {
-    await writeFile45(`${configPath}.bak-${timestamp()}`, await readFile39(configPath, "utf-8"), "utf-8");
+    await writeFile45(
+      `${configPath}.bak-${timestamp()}`,
+      await readFile39(configPath, "utf-8"),
+      "utf-8"
+    );
   }
   await writeFile45(configPath, JSON.stringify(root, null, 2) + "\n", "utf-8");
   return { path: configPath, status: exists ? "merged" : "wrote" };
@@ -82248,16 +83506,22 @@ async function mergeCodexToml(configPath, opts) {
 ${CODEX_MCP_BLOCK}${CODEX_MANAGED_END}`;
   if (!exists) {
     await mkdir23(dirname19(configPath), { recursive: true });
-    await writeFile45(configPath, `#:schema https://developers.openai.com/codex/config-schema.json
+    await writeFile45(
+      configPath,
+      `#:schema https://developers.openai.com/codex/config-schema.json
 
 ${block}
-`, "utf-8");
+`,
+      "utf-8"
+    );
     return { path: configPath, status: "wrote" };
   }
   const raw = await readFile39(configPath, "utf-8");
   if (raw.includes(CODEX_MANAGED_START)) {
     const updated = raw.replace(
-      new RegExp(`${escapeRegExp4(CODEX_MANAGED_START)}[\\s\\S]*?${escapeRegExp4(CODEX_MANAGED_END)}`),
+      new RegExp(
+        `${escapeRegExp6(CODEX_MANAGED_START)}[\\s\\S]*?${escapeRegExp6(CODEX_MANAGED_END)}`
+      ),
       block
     );
     await writeFile45(configPath, ensureTrailingNewline(updated), "utf-8");
@@ -82291,7 +83555,8 @@ function hasVibeframeMcpServer(value) {
 function readVibeframeMcpServer(value) {
   if (!value || typeof value !== "object") return null;
   const root = value;
-  if (!root.mcpServers || typeof root.mcpServers !== "object" || Array.isArray(root.mcpServers)) return null;
+  if (!root.mcpServers || typeof root.mcpServers !== "object" || Array.isArray(root.mcpServers))
+    return null;
   const server = root.mcpServers.vibeframe;
   if (!server || typeof server !== "object" || Array.isArray(server)) return null;
   return server;
@@ -82302,7 +83567,9 @@ function isAnchoredClaudeDesktopServer(server) {
     return server.args[0] === "-lc" && typeof server.args[1] === "string" && server.args[1].includes("exec npx -y @vibeframe/mcp-server");
   }
   if (server.command === "cmd.exe" && Array.isArray(server.args)) {
-    return server.args.some((arg) => typeof arg === "string" && arg.includes("npx -y @vibeframe/mcp-server"));
+    return server.args.some(
+      (arg) => typeof arg === "string" && arg.includes("npx -y @vibeframe/mcp-server")
+    );
   }
   return false;
 }
@@ -82319,13 +83586,15 @@ function hostNextSteps(host) {
   if (host.id === "codex") {
     return [
       "Trust the project in Codex so .codex/config.toml is loaded.",
-      "Run /mcp in Codex to confirm the vibeframe server is connected."
+      "Run /mcp in Codex to confirm the vibeframe server is connected.",
+      "Use /goal with the project AGENTS.md stop rules for long-running video builds."
     ];
   }
   if (host.id === "claude-code") {
     return [
       "Restart Claude Code or run /mcp to approve the project-scoped server.",
-      "Use AGENTS.md/CLAUDE.md for shell-driven vibe workflows."
+      "Use AGENTS.md/CLAUDE.md for shell-driven vibe workflows.",
+      "Use /goal with the project AGENTS.md stop rules for long-running video builds."
     ];
   }
   if (host.id === "claude-desktop") {
@@ -82339,7 +83608,11 @@ function claudeDesktopConfigPath() {
     return join21(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
   }
   if (process.platform === "win32") {
-    return join21(process.env.APPDATA ?? join21(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+    return join21(
+      process.env.APPDATA ?? join21(home, "AppData", "Roaming"),
+      "Claude",
+      "claude_desktop_config.json"
+    );
   }
   return join21(home, ".config", "Claude", "claude_desktop_config.json");
 }
@@ -82350,7 +83623,7 @@ function ensureTrailingNewline(value) {
   return value.endsWith("\n") ? value : `${value}
 `;
 }
-function escapeRegExp4(value) {
+function escapeRegExp6(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function shellQuote(value) {
@@ -82542,6 +83815,45 @@ Default setup is snippet-only; use \`--write\` when you want VibeFrame to merge
 the generated config. Keep provider keys in \`.vibeframe/config.yaml\`, user
 config, or env files \u2014 not in app host config.
 
+## Native host goal loop
+
+For long-running work, use Codex Goal mode, Claude Code \`/goal\`, Cursor, or
+another host-native goal feature as the outer loop. VibeFrame should not own a
+competing project-level goal runner. It provides \`--json\` commands, dry runs,
+budget caps, \`build-report.json\`, \`review-report.json\`, \`nextActions\`,
+\`safeToAutoRun\`, \`requiresConfirmation\`, \`fixOwner\`, deterministic repair,
+and render inspection for the host agent to decide what to do next.
+
+Copy-paste Codex:
+
+\`\`\`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 gives 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, target duration and aspect ratio are
+met, 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.
+\`\`\`
+
+Copy-paste Claude Code:
+
+\`\`\`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.
+\`\`\`
+
 ### Composition rules (scene HTML)
 
 \`vibe init\` installs local composition rules into your project. The
@@ -83439,13 +84751,13 @@ init_output();
 import { resolve as resolve61 } from "node:path";
 var VALID_STAGES = ["assets", "compose", "sync", "render", "all"];
 var VALID_MODES = ["agent", "batch", "auto"];
-var VALID_TTS_PROVIDERS = ["auto", "elevenlabs", "kokoro"];
+var VALID_TTS_PROVIDERS = ["auto", "elevenlabs", "openai", "kokoro"];
 var VALID_IMAGE_PROVIDERS = ["openai", "gemini", "grok"];
 var VALID_VIDEO_PROVIDERS = ["seedance", "grok", "kling", "runway", "veo"];
 var VALID_MUSIC_PROVIDERS = ["elevenlabs", "replicate"];
 var VALID_COMPOSERS = ["claude", "openai", "gemini"];
 var VALID_IMAGE_QUALITIES = ["standard", "hd"];
-var planCommand = new Command("plan").description("Read STORYBOARD.md and show build plan, costs, missing cues, and provider needs").argument("[project-dir]", "Video project directory", ".").option("--stage <stage>", `Stage to plan: ${VALID_STAGES.join("|")}`, "all").option("--beat <id>", "Restrict the plan to one beat").option("--mode <mode>", "Build mode: agent|batch|auto", "auto").option("--skip-narration", "Don't include narration generation in the plan").option("--skip-backdrop", "Don't include backdrop image generation in the plan").option("--skip-video", "Don't include video generation in the plan").option("--skip-music", "Don't include music generation in the plan").option("--tts <provider>", "TTS provider: auto|elevenlabs|kokoro").option("--voice <id>", "Voice id").option("--image-provider <name>", `Image provider: ${VALID_IMAGE_PROVIDERS.join("|")}`).option("--video-provider <name>", `Video provider: ${VALID_VIDEO_PROVIDERS.join("|")}`).option("--music-provider <name>", `Music provider: ${VALID_MUSIC_PROVIDERS.join("|")}`).option("--quality <q>", "Image quality: standard|hd").option("--image-size <s>", "Image size: 1024x1024|1536x1024|1024x1536").option("--composer <provider>", "Batch composer: claude|openai|gemini").option("--force", "Plan regeneration even when outputs already exist").option("--max-cost <usd>", "Fail if estimated cost exceeds this USD cap").action(async (projectDirArg, options) => {
+var planCommand = new Command("plan").description("Read STORYBOARD.md and show build plan, costs, missing cues, and provider needs").argument("[project-dir]", "Video project directory", ".").option("--stage <stage>", `Stage to plan: ${VALID_STAGES.join("|")}`, "all").option("--beat <id>", "Restrict the plan to one beat").option("--mode <mode>", "Build mode: agent|batch|auto", "auto").option("--skip-narration", "Don't include narration generation in the plan").option("--skip-backdrop", "Don't include backdrop image generation in the plan").option("--skip-video", "Don't include video generation in the plan").option("--skip-music", "Don't include music generation in the plan").option("--tts <provider>", "TTS provider: auto|elevenlabs|openai|kokoro").option("--voice <id>", "Voice id").option("--image-provider <name>", `Image provider: ${VALID_IMAGE_PROVIDERS.join("|")}`).option("--video-provider <name>", `Video provider: ${VALID_VIDEO_PROVIDERS.join("|")}`).option("--music-provider <name>", `Music provider: ${VALID_MUSIC_PROVIDERS.join("|")}`).option("--quality <q>", "Image quality: standard|hd").option("--image-size <s>", "Image size: 1024x1024|1536x1024|1024x1536").option("--composer <provider>", "Batch composer: claude|openai|gemini").option("--force", "Plan regeneration even when outputs already exist").option("--max-cost <usd>", "Fail if estimated cost exceeds this USD cap").action(async (projectDirArg, options) => {
   const startedAt = Date.now();
   const stage = String(options.stage ?? "all");
   if (!VALID_STAGES.includes(stage)) {
@@ -83630,13 +84942,13 @@ init_build_plan();
 init_storyboard_parse();
 init_output();
 import { resolve as resolve66, join as join26 } from "node:path";
-import { readFileSync as readFileSync3, existsSync as existsSync50 } from "node:fs";
+import { readFileSync as readFileSync4, existsSync as existsSync50 } from "node:fs";
 var VALID_MODES2 = ["agent", "batch", "auto"];
 var VALID_STAGES2 = ["assets", "compose", "sync", "render", "all"];
 var VALID_IMAGE_PROVIDERS2 = ["openai", "gemini", "grok"];
 var VALID_VIDEO_PROVIDERS2 = ["seedance", "grok", "kling", "runway", "veo"];
 var VALID_MUSIC_PROVIDERS2 = ["elevenlabs", "replicate"];
-var buildCommand = new Command("build").description("Build a VibeFrame video project from STORYBOARD.md").argument("[project-dir]", "Video project directory", ".").option("--stage <stage>", `Build stage: ${VALID_STAGES2.join("|")}`, "all").option("--beat <id>", "Restrict asset/compose work to one beat id").option("--mode <mode>", "Build mode: agent|batch|auto", "auto").option("--effort <level>", "Compose effort tier (batch mode only): low|medium|high", "medium").option("--composer <provider>", "Batch composer: claude|openai|gemini").option("--max-cost <usd>", "Fail before provider spend when estimated cost exceeds this USD cap").option("--skip-narration", "Don't dispatch TTS even when beats declare narration cues").option("--skip-backdrop", "Don't dispatch image-gen even when beats declare backdrop cues").option("--skip-video", "Don't dispatch video generation even when beats declare video cues").option("--skip-music", "Don't dispatch music generation even when beats declare music cues").option("--skip-render", "Compose only \u2014 don't render to MP4").option("--tts <provider>", "TTS provider: auto|elevenlabs|kokoro").option("--voice <id>", "Voice id").option("--image-provider <name>", `Image provider: ${VALID_IMAGE_PROVIDERS2.join("|")}`).option("--video-provider <name>", `Video provider: ${VALID_VIDEO_PROVIDERS2.join("|")}`).option("--music-provider <name>", `Music provider: ${VALID_MUSIC_PROVIDERS2.join("|")}`).option("--quality <q>", "Image quality: standard|hd", "hd").option("--image-size <s>", "Image size: 1024x1024|1536x1024|1024x1536", "1536x1024").option("--force", "Re-dispatch primitives even when assets already exist").option("--dry-run", "Preview parameters without dispatching").addHelpText(
+var buildCommand = new Command("build").description("Build a VibeFrame video project from STORYBOARD.md").argument("[project-dir]", "Video project directory", ".").option("--stage <stage>", `Build stage: ${VALID_STAGES2.join("|")}`, "all").option("--beat <id>", "Restrict asset/compose work to one beat id").option("--mode <mode>", "Build mode: agent|batch|auto", "auto").option("--effort <level>", "Compose effort tier (batch mode only): low|medium|high", "medium").option("--composer <provider>", "Batch composer: claude|openai|gemini").option("--max-cost <usd>", "Fail before provider spend when estimated cost exceeds this USD cap").option("--skip-narration", "Don't dispatch TTS even when beats declare narration cues").option("--skip-backdrop", "Don't dispatch image-gen even when beats declare backdrop cues").option("--skip-video", "Don't dispatch video generation even when beats declare video cues").option("--skip-music", "Don't dispatch music generation even when beats declare music cues").option("--skip-render", "Compose only \u2014 don't render to MP4").option("--tts <provider>", "TTS provider: auto|elevenlabs|openai|kokoro").option("--voice <id>", "Voice id").option("--image-provider <name>", `Image provider: ${VALID_IMAGE_PROVIDERS2.join("|")}`).option("--video-provider <name>", `Video provider: ${VALID_VIDEO_PROVIDERS2.join("|")}`).option("--music-provider <name>", `Music provider: ${VALID_MUSIC_PROVIDERS2.join("|")}`).option("--quality <q>", "Image quality: standard|hd", "hd").option("--image-size <s>", "Image size: 1024x1024|1536x1024|1024x1536", "1536x1024").option("--force", "Re-dispatch primitives even when assets already exist").option("--dry-run", "Preview parameters without dispatching").addHelpText(
   "after",
   `
 Examples:
@@ -83997,7 +85309,7 @@ function estimateBuildCost(params) {
   if (!existsSync50(storyboardPath2)) return null;
   let beats = 0;
   try {
-    const md = readFileSync3(storyboardPath2, "utf-8");
+    const md = readFileSync4(storyboardPath2, "utf-8");
     beats = parseStoryboard(md).beats.length;
   } catch {
     return null;
@@ -84381,6 +85693,18 @@ function printProjectStatus(result) {
   console.log(`  Build:     ${result.build ? formatBuild(result.build) : source_default.dim("no build-report.json")}`);
   console.log(`  Review:    ${result.review ? formatReview(result.review) : source_default.dim("no review-report.json")}`);
   console.log(`  Jobs:      ${result.jobs.total} total, ${result.jobs.active} active, ${result.jobs.failed} failed`);
+  if (result.nextActions.length > 0) {
+    console.log();
+    console.log(source_default.bold("Next actions"));
+    for (const action of result.nextActions.slice(0, 5)) {
+      console.log(formatNextAction(action));
+      if (action.command) console.log(source_default.dim(`      ${action.command}`));
+      if (action.agentPrompt) console.log(source_default.dim(`      ${action.agentPrompt}`));
+    }
+    if (result.nextActions.length > 5) {
+      console.log(source_default.dim(`  ... ${result.nextActions.length - 5} more`));
+    }
+  }
   if (result.jobs.latest.length > 0) {
     console.log();
     for (const job of result.jobs.latest.slice(0, 5)) {
@@ -84401,6 +85725,10 @@ function formatReview(review) {
   const status = review.status ?? "unknown";
   return `${formatStatus(status)} score ${review.score ?? "-"} (${review.issueCount} issue${review.issueCount === 1 ? "" : "s"})`;
 }
+function formatNextAction(action) {
+  const badge = action.safeToAutoRun ? "auto" : action.requiresConfirmation ? "confirm" : action.kind;
+  return `  ${source_default.dim(`[${badge}]`)} ${action.label}`;
+}
 function formatStatus(status) {
   if (status === "completed" || status === "pass") return source_default.green(status);
   if (status === "failed" || status === "fail") return source_default.red(status);
@@ -85407,6 +86735,8 @@ var contextCommand = new Command("context").description("Print CLI context/guide
     product: "vibeframe",
     sourceOfTruth: ["STORYBOARD.md", "DESIGN.md", "vibe.config.json"],
     preferredFlow: [
+      "native Codex Goal mode or Claude Code /goal owns persistence, iteration, and stop decisions",
+      "vibe context/schema for command discovery",
       "storyboard revise after init when the brief changes",
       "storyboard validate",
       "plan",
@@ -85421,6 +86751,19 @@ var contextCommand = new Command("context").description("Print CLI context/guide
       "inspect render --ai when needed",
       "status project when async jobs are involved"
     ],
+    nativeGoalContract: {
+      owner: "host-native goal mode (Codex /goal, Claude Code /goal, Cursor or other host equivalent)",
+      vibeRole: "video-specific commands, JSON reports, cost gates, deterministic repair, render inspection, nextActions, and retryWith compatibility hints",
+      canonicalLoop: "native host goal -> vibe context/schema -> plan dry-run -> build with budget -> status polling -> inspect project -> render -> inspect render -> repair/edit using nextActions/fixOwner -> repeat",
+      stopRules: [
+        "final MP4 exists at the requested output path",
+        "duration and aspect ratio match the brief or explicitly accepted constraints",
+        "inspect render --cheap reports no errors",
+        "any AI review score meets the goal threshold, commonly >= 90, when AI review is requested",
+        "all fixOwner:vibe issues have been repaired or are blocked with evidence",
+        "all fixOwner:host-agent issues are fixed, intentionally accepted with a written reason, or reported as blocked"
+      ]
+    },
     mentalModel: {
       storyboard: "intent layer; edit or mutate beat cues here",
       scene: "generated artifact layer; lint/repair composition HTML here"
@@ -85454,7 +86797,8 @@ var contextCommand = new Command("context").description("Print CLI context/guide
     reviewReportContract: {
       kind: "review",
       modes: ["project", "render"],
-      fields: ["status", "score", "issues", "summary", "sourceReports", "retryWith"],
+      fields: ["status", "score", "issues", "summary", "sourceReports", "nextActions", "retryWith"],
+      recovery: "prefer nextActions (classified by costTier/safeToAutoRun/requiresConfirmation/fixOwner); retryWith is the compatibility fallback",
       issueFixOwner: {
         vibe: "deterministic CLI recovery",
         "host-agent": "storyboard/design/composition edits the host agent should make"
@@ -85462,7 +86806,7 @@ var contextCommand = new Command("context").description("Print CLI context/guide
     },
     machineStatusContract: {
       buildReport: "kind/status/currentStage/beatSummary/jobs/sceneRepair/stageReports/warnings/retryWith plus beat timing and nested per-beat asset metadata",
-      projectStatus: "kind/status/currentStage/beats/jobs.latest/build/review/warnings/retryWith",
+      projectStatus: "kind/status/currentStage/beats/jobs.latest/build/review/warnings/nextActions/retryWith (nextActions is populated for every workflow state, not only when a review report exists)",
       reviewSummary: "review.mode/issueCount/errorCount/warningCount/infoCount/fixOwners/sourceReports/retryWith"
     },
     productSurfaceContract: {
@@ -85545,12 +86889,13 @@ render. Repair failures return \`code:"SCENE_REPAIR_FAILED"\` with
 render with \`currentStage:"assets"\` and \`code:"ASSET_REFERENCE_INVALID"\`,
 \`code:"MISSING_API_KEY"\`, or \`code:"ASSET_GENERATION_FAILED"\`.
 \`build-report.json\` includes \`sceneRepair\`, and \`status project\` carries
-review issue counts, \`fixOwners\`, \`sourceReports\`, and
-\`review.retryWith\`.
+review issue counts, \`fixOwners\`, \`sourceReports\`, top-level
+\`nextActions\` (populated for every workflow state), and \`retryWith\`.
+Prefer \`nextActions\` and treat \`retryWith\` as the compatibility fallback.
 
 \`review-report.json\` is written by \`inspect project\` and \`inspect render\`
 as \`kind:"review"\` with \`mode:"project"|"render"\`, \`summary\`,
-\`sourceReports\`, \`retryWith\`, and issue-level
+\`sourceReports\`, \`nextActions\`, \`retryWith\`, and issue-level
 \`fixOwner:"vibe"|"host-agent"\`.
 \`inspect render --cheap\` checks duration drift, audio presence, black frames,
 long silence, and static-frame holds. Static or semantic beat issues are
@@ -85572,6 +86917,8 @@ Use 'vibe schema --list --surface public' for the small product surface.
 Use 'vibe schema <command> --json' to get parameter schemas.
 Use 'vibe doctor --json' to check configured API keys.
 Use '--dry-run --json' before any mutating/costly operation.
+Use native Codex Goal mode or Claude Code /goal as the outer loop; VibeFrame provides JSON reports, retryWith, fixOwner, cost gates, and render inspection for that host loop.
+Stop only when the final MP4 exists, target duration/aspect ratio are met, inspect render has no errors, any AI review score meets the goal threshold when AI review is requested, and every host-agent issue is fixed, accepted with rationale, or reported blocked.
 
 Cost tiers: Free (schema/context/doctor/detect/status/plan/storyboard validate/inspect project/render --cheap, deterministic edits) | Low (generate narration/sound-effect/music, audio transcribe, inspect media, optional AI review) | High (generate image/motion, edit image/reframe/grade/speed-ramp) | Very High (generate video, edit fill-gaps, remix highlights/auto-shorts, build with generated assets)