@vibeframe/cli 0.113.0 → 0.113.2

package/dist/index.js

@@ -17334,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);
@@ -17443,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";
@@ -17463,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";
@@ -18287,6 +18304,7 @@ __export(dist_exports2, {
   defineApiKey: () => defineApiKey,
   defineProvider: () => defineProvider,
   elevenLabsProvider: () => elevenLabsProvider,
+  estimateSeedanceVideoCostUsd: () => estimateSeedanceVideoCostUsd,
   falProvider: () => falProvider,
   geminiProvider: () => geminiProvider,
   getAllApiKeys: () => getAllApiKeys,
@@ -27005,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
@@ -27500,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, "");
@@ -27536,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;
@@ -27562,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;
@@ -27595,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}`
       };
     }
@@ -27634,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);
@@ -27681,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}`
@@ -27722,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} {
@@ -27761,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);` : ""}`
@@ -27822,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"
@@ -27840,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}
@@ -27876,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);
@@ -29355,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);
@@ -29960,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.
@@ -30878,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";
@@ -30887,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);
@@ -30907,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",
@@ -30918,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
   });
@@ -30932,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";
@@ -31064,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";
@@ -31113,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("\\");
@@ -31139,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,
@@ -31358,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,
@@ -31376,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,
@@ -31393,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
   };
@@ -31434,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(
@@ -31718,7 +32592,10 @@ 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, openai, kokoro (default auto \u2014 ElevenLabs key > OpenAI key > Kokoro local)",
       "auto"
@@ -31787,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,
@@ -31814,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,
@@ -31853,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"));
@@ -35661,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",
@@ -35672,6 +36562,7 @@ async function inspectProjectStatus(projectDirArg, opts = {}) {
     review,
     jobs,
     warnings,
+    nextActions,
     retryWith: unique(retryWith)
   };
 }
@@ -35965,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,
@@ -36179,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";
 }
@@ -36244,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;
   }
@@ -39125,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,
@@ -44316,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";
@@ -44750,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",
@@ -44762,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) {
@@ -45306,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(
@@ -45328,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(
@@ -45337,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",
@@ -45362,7 +46113,7 @@ async function inspectRender(opts) {
           file: displayPath(videoPath)
         });
       }
-      if (!audioStream) {
+      if (!audioStream && expectedAudio) {
         issues.push({
           severity: "warning",
           code: "NO_AUDIO_STREAM",
@@ -45567,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",
@@ -45581,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) {
@@ -59587,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"]
     };
@@ -59624,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":
@@ -59643,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"
   });
 }
@@ -59870,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({
@@ -59981,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,
@@ -60345,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();
@@ -61172,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) {
@@ -61339,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,
@@ -61358,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);
@@ -61367,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`
     );
@@ -61535,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);
@@ -61955,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);
@@ -62124,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) {
@@ -62190,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) {
@@ -62558,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));
@@ -68455,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."),
@@ -68467,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;
@@ -68481,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,
@@ -68499,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: {
@@ -68509,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
         };
@@ -73627,7 +74662,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.113.0",
+  version: "0.113.2",
   description: "VibeFrame CLI - agentic video workflow runtime",
   private: false,
   license: "MIT",
@@ -73692,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: {
@@ -82210,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, "\\$&");
 }
 
@@ -82259,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."
       ]
     },
@@ -82271,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."
       ]
     },
@@ -82345,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, {
@@ -82357,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);
@@ -82401,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 : {};
@@ -82414,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,
@@ -82428,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" };
@@ -82439,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");
@@ -82482,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;
@@ -82493,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;
 }
@@ -82510,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") {
@@ -82530,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");
 }
@@ -82541,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) {
@@ -82733,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
@@ -83821,7 +84942,7 @@ 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"];
@@ -84188,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;
@@ -84572,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)) {
@@ -84592,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);
@@ -85598,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",
@@ -85612,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"
@@ -85645,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"
@@ -85653,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: {
@@ -85736,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
@@ -85763,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)