@vibeframe/mcp-server 0.113.0 → 0.113.3

package/dist/index.js

@@ -4742,14 +4742,14 @@ async function loadKokoroRuntime() {
 async function loadKokoroFromWorkspace(baseDir = process.cwd()) {
   try {
     const { readFile: readFile46 } = await import("node:fs/promises");
-    const { join: join45, resolve: resolve80 } = await import("node:path");
+    const { join: join44, resolve: resolve80 } = await import("node:path");
     const { pathToFileURL } = await import("node:url");
     const pkgDir = resolve80(baseDir, "node_modules", "kokoro-js");
-    const pkg = JSON.parse(await readFile46(join45(pkgDir, "package.json"), "utf-8"));
+    const pkg = JSON.parse(await readFile46(join44(pkgDir, "package.json"), "utf-8"));
     const entry = pkg.exports?.node?.import ?? pkg.exports?.default ?? pkg.module ?? pkg.main;
     if (!entry)
       return null;
-    const mod = await import(pathToFileURL(join45(pkgDir, entry)).href);
+    const mod = await import(pathToFileURL(join44(pkgDir, entry)).href);
     return mod.KokoroTTS ?? null;
   } catch {
     return null;
@@ -4761,19 +4761,19 @@ async function loadBundledKokoroRuntime(runtimeDir = process.env.VIBE_KOKORO_RUN
     return null;
   try {
     const { readFile: readFile46, writeFile: writeFile53, mkdir: mkdir30 } = await import("node:fs/promises");
-    const { join: join45, resolve: resolve80 } = await import("node:path");
+    const { join: join44, resolve: resolve80 } = await import("node:path");
     const { pathToFileURL } = await import("node:url");
     const { homedir: homedir8 } = await import("node:os");
     const transformersDir = resolve80(base, "node_modules", "@huggingface", "transformers");
     const ortDistDir = resolve80(base, "node_modules", "onnxruntime-web", "dist");
-    const transformers = await import(pathToFileURL(join45(transformersDir, "dist", "transformers.web.js")).href);
-    const cacheRoot = join45(homedir8(), ".cache", "vibeframe", "models");
+    const transformers = await import(pathToFileURL(join44(transformersDir, "dist", "transformers.web.js")).href);
+    const cacheRoot = join44(homedir8(), ".cache", "vibeframe", "models");
     transformers.env.allowLocalModels = false;
     transformers.env.useCustomCache = true;
     transformers.env.customCache = {
       async match(key2) {
         try {
-          return new Response(await readFile46(join45(cacheRoot, encodeURIComponent(String(key2)))));
+          return new Response(await readFile46(join44(cacheRoot, encodeURIComponent(String(key2)))));
         } catch {
           return void 0;
         }
@@ -4782,7 +4782,7 @@ async function loadBundledKokoroRuntime(runtimeDir = process.env.VIBE_KOKORO_RUN
         try {
           const buf = Buffer.from(await response.arrayBuffer());
           await mkdir30(cacheRoot, { recursive: true });
-          await writeFile53(join45(cacheRoot, encodeURIComponent(String(key2))), buf);
+          await writeFile53(join44(cacheRoot, encodeURIComponent(String(key2))), buf);
         } catch {
         }
       }
@@ -10460,6 +10460,19 @@ var require_src = __commonJS({
 });
 
 // ../ai-providers/dist/fal/FalProvider.js
+function estimateSeedanceVideoCostUsd(opts) {
+  const shortSide = SEEDANCE_SHORT_SIDE[opts.resolution ?? "720p"] ?? 720;
+  const [a2, b2] = (opts.aspectRatio ?? "16:9").split(":").map(Number);
+  const ratioFactor = a2 > 0 && b2 > 0 ? Math.max(a2, b2) / Math.min(a2, b2) : 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);
@@ -10569,7 +10582,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";
@@ -10589,6 +10602,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";
@@ -11413,6 +11430,7 @@ __export(dist_exports, {
   defineApiKey: () => defineApiKey,
   defineProvider: () => defineProvider,
   elevenLabsProvider: () => elevenLabsProvider,
+  estimateSeedanceVideoCostUsd: () => estimateSeedanceVideoCostUsd,
   falProvider: () => falProvider,
   geminiProvider: () => geminiProvider,
   getAllApiKeys: () => getAllApiKeys,
@@ -24219,7 +24237,534 @@ var init_build_asset_metadata = __esm({
   }
 });
 
+// ../cli/src/commands/_shared/review-report.ts
+import { writeFile as writeFile6 } from "node:fs/promises";
+import { join as join2, resolve as resolve5 } from "node:path";
+function statusFromIssues(issues) {
+  if (issues.some((issue) => issue.severity === "error")) return "fail";
+  if (issues.some((issue) => issue.severity === "warning")) return "warn";
+  return "pass";
+}
+function scoreIssues(issues) {
+  let score = 100;
+  for (const issue of issues) {
+    if (issue.severity === "error") score -= 25;
+    else if (issue.severity === "warning") score -= 8;
+    else score -= 2;
+  }
+  return Math.max(0, Math.min(100, score));
+}
+function uniqueRetryWith(items) {
+  return [
+    ...new Set(items.filter((item) => typeof item === "string" && item.length > 0))
+  ];
+}
+function commandReviewAction(command3, opts) {
+  const classified = classifyReviewCommand(command3);
+  return stripUndefined({
+    id: actionId("command", command3),
+    kind: "command",
+    label: opts.label ?? command3,
+    command: command3,
+    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 key2 = [action.kind, action.command ?? action.agentPrompt ?? action.label].join("\0");
+    const existing = merged.get(key2);
+    if (!existing) {
+      merged.set(key2, {
+        ...action,
+        sourceIssueCodes: uniqueStrings(action.sourceIssueCodes ?? [])
+      });
+      continue;
+    }
+    merged.set(key2, {
+      ...existing,
+      safeToAutoRun: existing.safeToAutoRun && action.safeToAutoRun,
+      requiresConfirmation: existing.requiresConfirmation || action.requiresConfirmation,
+      sourceIssueCodes: uniqueStrings([
+        ...existing.sourceIssueCodes ?? [],
+        ...action.sourceIssueCodes ?? []
+      ])
+    });
+  }
+  return [...merged.values()].map(
+    (action) => stripUndefined({
+      ...action,
+      sourceIssueCodes: action.sourceIssueCodes && action.sourceIssueCodes.length > 0 ? action.sourceIssueCodes : void 0
+    })
+  );
+}
+function deriveNextReviewActions(opts) {
+  return normalizeReviewActions([
+    ...opts.issues.flatMap((issue) => issue.actions ?? []),
+    ...reviewActionsFromRetryWith(opts.retryWith)
+  ]);
+}
+function fixOwnerForIssue(issue) {
+  if (issue.fixOwner) return issue.fixOwner;
+  if (issue.code.startsWith("AI_REVIEW_")) return "host-agent";
+  if (issue.code.startsWith("STORYBOARD_")) return "host-agent";
+  if (issue.code === "PROJECT_NOT_FOUND" || issue.code === "MISSING_STORYBOARD" || issue.code === "BEAT_NOT_FOUND" || issue.code === "MISSING_DESIGN") {
+    return "host-agent";
+  }
+  return "vibe";
+}
+function normalizeReviewIssues(issues, opts) {
+  const fallbackOwner = typeof opts === "string" ? opts : opts?.fallbackOwner;
+  const projectDir = typeof opts === "string" ? void 0 : opts?.projectDir;
+  return issues.map((issue) => {
+    const normalized = {
+      ...issue,
+      fixOwner: issue.fixOwner ?? fallbackOwner ?? fixOwnerForIssue(issue)
+    };
+    const actions = normalizeReviewActions([
+      ...issue.actions ?? [],
+      ...projectDir ? defaultActionsForIssue(normalized, projectDir) : []
+    ]);
+    return stripUndefined({
+      ...normalized,
+      actions: actions.length > 0 ? actions : void 0
+    });
+  });
+}
+function summarizeReviewIssues(issues) {
+  const normalized = normalizeReviewIssues(issues);
+  return {
+    issueCount: normalized.length,
+    errorCount: normalized.filter((issue) => issue.severity === "error").length,
+    warningCount: normalized.filter((issue) => issue.severity === "warning").length,
+    infoCount: normalized.filter((issue) => issue.severity === "info").length,
+    fixOwners: {
+      vibe: normalized.filter((issue) => issue.fixOwner === "vibe").length,
+      hostAgent: normalized.filter((issue) => issue.fixOwner === "host-agent").length
+    }
+  };
+}
+function buildReviewReport(opts) {
+  const retryWith = uniqueRetryWith(opts.retryWith);
+  const issues = normalizeReviewIssues(opts.issues, {
+    projectDir: opts.project,
+    retryWith
+  });
+  return stripUndefined({
+    schemaVersion: "1",
+    kind: "review",
+    project: resolve5(opts.project),
+    mode: opts.mode,
+    beat: opts.beat,
+    status: opts.status,
+    score: opts.score,
+    issues,
+    summary: summarizeReviewIssues(issues),
+    nextActions: deriveNextReviewActions({ issues, retryWith, projectDir: opts.project }),
+    retryWith,
+    sourceReports: opts.sourceReports ?? [],
+    reportPath: opts.reportPath
+  });
+}
+function defaultReviewReportPath(projectDir) {
+  return join2(resolve5(projectDir), "review-report.json");
+}
+async function writeReviewReport(path14, report) {
+  await writeFile6(path14, JSON.stringify(report, null, 2) + "\n", "utf-8");
+}
+function stripUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, v2]) => v2 !== 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(command3) {
+  const lower = command3.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(kind3, value) {
+  const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 80);
+  return `${kind3}:${slug || "action"}`;
+}
+function uniqueStrings(items) {
+  return [
+    ...new Set(items.filter((item) => typeof item === "string" && item.length > 0))
+  ];
+}
+var init_review_report = __esm({
+  "../cli/src/commands/_shared/review-report.ts"() {
+    "use strict";
+  }
+});
+
 // ../cli/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 raw2 = cues?.characters;
+  if (typeof raw2 === "string") {
+    const name = raw2.trim();
+    return name ? [name] : [];
+  }
+  if (Array.isArray(raw2)) {
+    return raw2.filter((v2) => typeof v2 === "string" && v2.trim().length > 0).map((v2) => v2.trim());
+  }
+  return [];
+}
 function parseStoryboard(md) {
   const normalized = md.replace(/\r\n/g, "\n");
   const { frontmatter, remaining } = extractProjectFrontmatter(normalized);
@@ -24332,28 +24877,28 @@ var init_storyboard_parse = __esm({
 // ../cli/src/commands/_shared/status-jobs.ts
 import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
 import { existsSync as existsSync2, statSync } from "node:fs";
-import { copyFile, mkdir as mkdir3, readFile as readFile4, readdir, stat, writeFile as writeFile6 } from "node:fs/promises";
-import { dirname as dirname3, join as join2, parse as parse2, relative, resolve as resolve5 } from "node:path";
+import { copyFile, mkdir as mkdir3, readFile as readFile4, readdir, stat, writeFile as writeFile7 } from "node:fs/promises";
+import { dirname as dirname3, join as join3, parse as parse2, relative, resolve as resolve6 } from "node:path";
 function isLocalJob(record) {
   return record.jobType === "build" || record.jobType === "render";
 }
 function findProjectRoot(start = process.cwd()) {
-  let dir = resolve5(start);
+  let dir = resolve6(start);
   try {
     if (existsSync2(dir) && statSync(dir).isFile()) dir = dirname3(dir);
   } catch {
   }
   for (; ; ) {
-    if (existsSync2(join2(dir, "vibe.config.json")) || existsSync2(join2(dir, "STORYBOARD.md"))) {
+    if (existsSync2(join3(dir, "vibe.config.json")) || existsSync2(join3(dir, "STORYBOARD.md"))) {
       return dir;
     }
     const parent = dirname3(dir);
-    if (parent === dir) return resolve5(start);
+    if (parent === dir) return resolve6(start);
     dir = parent;
   }
 }
 function jobsDir(projectDir) {
-  return join2(resolve5(projectDir), ".vibeframe", "jobs");
+  return join3(resolve6(projectDir), ".vibeframe", "jobs");
 }
 function normalizeJobStatus(status) {
   const value = String(status ?? "").toLowerCase();
@@ -24367,10 +24912,10 @@ function normalizeJobStatus(status) {
 }
 function createJobRecord(opts) {
   const now = opts.now ?? /* @__PURE__ */ new Date();
-  const projectDir = resolve5(
+  const projectDir = resolve6(
     opts.projectDir ?? findProjectRoot(opts.workingDirectory ?? process.cwd())
   );
-  const workingDirectory = resolve5(opts.workingDirectory ?? process.cwd());
+  const workingDirectory = resolve6(opts.workingDirectory ?? process.cwd());
   const id = opts.id ?? makeJobId(opts.providerTaskId, now);
   const base = {
     schemaVersion: "1",
@@ -24405,7 +24950,7 @@ function createJobRecord(opts) {
     message: opts.message
   };
   base.retryWith = retryWithForJob(base);
-  return stripUndefined(base);
+  return stripUndefined2(base);
 }
 async function createAndWriteJobRecord(opts) {
   const record = createJobRecord(opts);
@@ -24415,15 +24960,15 @@ async function createAndWriteJobRecord(opts) {
 async function writeJobRecord(record) {
   const dir = jobsDir(record.projectDir);
   await mkdir3(dir, { recursive: true });
-  await writeFile6(
+  await writeFile7(
     jobRecordPath(record.id, record.projectDir),
-    JSON.stringify(stripUndefined(record), null, 2) + "\n",
+    JSON.stringify(stripUndefined2(record), null, 2) + "\n",
     "utf-8"
   );
 }
 async function readJobRecord(jobId, projectDir) {
   const id = normalizeJobId(jobId);
-  const project = resolve5(projectDir ?? findProjectRoot());
+  const project = resolve6(projectDir ?? findProjectRoot());
   const path14 = jobRecordPath(id, project);
   if (!existsSync2(path14)) return null;
   return parseJobRecord(await readFile4(path14, "utf-8"));
@@ -24436,7 +24981,7 @@ async function listJobRecords(projectDir) {
   for (const entry of entries2) {
     if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
     try {
-      const parsed = parseJobRecord(await readFile4(join2(dir, entry.name), "utf-8"));
+      const parsed = parseJobRecord(await readFile4(join3(dir, entry.name), "utf-8"));
       if (parsed) records.push(parsed);
     } catch {
     }
@@ -24530,9 +25075,9 @@ async function refreshLocalJobRecord(record, opts) {
     const heartbeatAge = record.heartbeatAt ? Date.now() - new Date(record.heartbeatAt).getTime() : Number.POSITIVE_INFINITY;
     const orphaned = !isPidAlive(record.pid) || heartbeatAge > LOCAL_JOB_ORPHAN_AFTER_MS;
     if (orphaned) {
-      const hint = `The process that ran this ${record.jobType} job is gone. Check ${join2(record.projectDir, record.jobType === "render" ? "render-report.json" : "build-report.json")} \u2014 the work may have completed before the process exited.`;
+      const hint = `The process that ran this ${record.jobType} job is gone. Check ${join3(record.projectDir, record.jobType === "render" ? "render-report.json" : "build-report.json")} \u2014 the work may have completed before the process exited.`;
       warnings.push(hint);
-      updated = stripUndefined({
+      updated = stripUndefined2({
         ...record,
         status: "unknown",
         error: record.error ?? hint,
@@ -24549,7 +25094,7 @@ async function refreshLocalJobRecord(record, opts) {
   });
 }
 async function inspectProjectStatus(projectDirArg, opts = {}) {
-  const project = resolve5(projectDirArg);
+  const project = resolve6(projectDirArg);
   const warnings = [];
   let records = await listJobRecords(project);
   if (opts.refresh) {
@@ -24579,6 +25124,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",
@@ -24590,11 +25139,12 @@ async function inspectProjectStatus(projectDirArg, opts = {}) {
     review,
     jobs,
     warnings,
+    nextActions,
     retryWith: unique(retryWith)
   };
 }
 function summarizeJob(record) {
-  return stripUndefined({
+  return stripUndefined2({
     id: record.id,
     jobType: record.jobType,
     status: record.status,
@@ -24618,7 +25168,7 @@ function retryWithForJob(record) {
   ]);
 }
 function makeJobStatusResult(record, opts) {
-  return stripUndefined({
+  return stripUndefined2({
     schemaVersion: "1",
     kind: "job",
     id: record.id,
@@ -24642,7 +25192,7 @@ function jobProgress(record) {
   if (record.status === "completed" || record.status === "failed" || record.status === "cancelled") {
     if (record.progress === void 0 && !record.providerStatus) return void 0;
   }
-  return stripUndefined({
+  return stripUndefined2({
     percent: record.progress,
     phase: record.stage ?? record.providerStatus ?? statusPhase(record.status),
     providerStatus: record.providerStatus ?? record.message
@@ -24652,7 +25202,7 @@ function jobResult(record) {
   if (!record.resultUrl && !record.outputPath && !record.cachePath && !record.error && !record.resultPayload) {
     return null;
   }
-  return stripUndefined({
+  return stripUndefined2({
     url: record.resultUrl,
     outputPath: record.outputPath,
     cachePath: record.cachePath,
@@ -24688,7 +25238,7 @@ function normalizeJobId(jobId) {
   return id;
 }
 function jobRecordPath(jobId, projectDir) {
-  return join2(jobsDir(projectDir), `${normalizeJobId(jobId)}.json`);
+  return join3(jobsDir(projectDir), `${normalizeJobId(jobId)}.json`);
 }
 function parseJobRecord(raw2) {
   const parsed = JSON.parse(raw2);
@@ -24713,11 +25263,11 @@ function updateRecordFromProvider(record, result) {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   next.retryWith = retryWithForJob(next);
-  return stripUndefined(next);
+  return stripUndefined2(next);
 }
 function resolveRefreshOutput(record, opts) {
-  if (opts.output) return resolve5(opts.workingDirectory ?? process.cwd(), opts.output);
-  return record.outputPath ? resolve5(record.outputPath) : void 0;
+  if (opts.output) return resolve6(opts.workingDirectory ?? process.cwd(), opts.output);
+  return record.outputPath ? resolve6(record.outputPath) : void 0;
 }
 function liveSupport(record) {
   if (record.jobType === "generate-video" && (record.provider === "grok" || record.provider === "runway" || record.provider === "kling" || record.provider === "veo")) {
@@ -24742,7 +25292,7 @@ async function downloadUrl(url, outputPath) {
   if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`);
   const buffer = Buffer.from(await response.arrayBuffer());
   await mkdir3(dirname3(outputPath), { recursive: true });
-  await writeFile6(outputPath, buffer);
+  await writeFile7(outputPath, buffer);
   return outputPath;
 }
 async function maybeCacheOutput(record) {
@@ -24774,7 +25324,7 @@ async function maybeWriteCompletedAssetMetadata(record) {
   }
 }
 async function refreshBuildReportFromJobs(projectDir, records) {
-  const reportPath = join2(projectDir, "build-report.json");
+  const reportPath = join3(projectDir, "build-report.json");
   const report = await readJson(reportPath);
   if (!report || !Array.isArray(report.beats)) return;
   let changed = false;
@@ -24802,7 +25352,7 @@ async function refreshBuildReportFromJobs(projectDir, records) {
       if (kind3 === "music" && record.assetOptions && typeof record.assetOptions.duration === "number") {
         nested.durationSec = record.assetOptions.duration;
       }
-      beatRecord[kind3] = stripUndefined(nested);
+      beatRecord[kind3] = stripUndefined2(nested);
       beatRecord[`${kind3}Path`] = outputPath;
       beatRecord[`${kind3}Status`] = "generated";
       beatRecord[`${kind3}JobId`] = record.id;
@@ -24822,17 +25372,17 @@ async function refreshBuildReportFromJobs(projectDir, records) {
   }
   if (!changed) return;
   try {
-    await writeFile6(reportPath, JSON.stringify(stripUndefined(report), null, 2) + "\n", "utf-8");
+    await writeFile7(reportPath, JSON.stringify(stripUndefined2(report), null, 2) + "\n", "utf-8");
   } catch {
   }
 }
 async function readBuildSummary(projectDir) {
-  const reportPath = join2(projectDir, "build-report.json");
+  const reportPath = join3(projectDir, "build-report.json");
   const report = await readJson(reportPath);
   if (!report) return null;
   const info = await statOrNull(reportPath);
   const beatSummary = projectBeatReadinessFromUnknown(report.beatSummary);
-  return stripUndefined({
+  return stripUndefined2({
     reportPath,
     kind: typeof report.kind === "string" ? report.kind : void 0,
     success: typeof report.success === "boolean" ? report.success : void 0,
@@ -24850,7 +25400,7 @@ async function readBuildSummary(projectDir) {
   });
 }
 async function readReviewSummary(projectDir) {
-  const reportPath = join2(projectDir, "review-report.json");
+  const reportPath = join3(projectDir, "review-report.json");
   const report = await readJson(reportPath);
   if (!report) return null;
   const info = await statOrNull(reportPath);
@@ -24858,7 +25408,7 @@ async function readReviewSummary(projectDir) {
   const summary = report.summary && typeof report.summary === "object" ? report.summary : {};
   const fixOwners = summary.fixOwners && typeof summary.fixOwners === "object" ? summary.fixOwners : {};
   const computedFixOwners = countIssueFixOwners(issues);
-  return stripUndefined({
+  return stripUndefined2({
     reportPath,
     kind: typeof report.kind === "string" ? report.kind : void 0,
     mode: typeof report.mode === "string" ? report.mode : void 0,
@@ -24883,9 +25433,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 kind3 = 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 (!kind3 || !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: kind3,
+        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,
@@ -24904,7 +25489,7 @@ async function readProjectBeatReadiness(projectDir, build, records) {
     if (fromBeats) return fromBeats;
     if (build.beats) return augmentBeatReadinessFromJobs(build.beats, records, report?.jobs);
   }
-  const storyboardPath = join2(projectDir, "STORYBOARD.md");
+  const storyboardPath = join3(projectDir, "STORYBOARD.md");
   if (!existsSync2(storyboardPath)) {
     return { total: 0, assetsReady: 0, compositionsReady: 0, needsAuthor: [] };
   }
@@ -24913,7 +25498,7 @@ async function readProjectBeatReadiness(projectDir, build, records) {
     const needsAuthor = [];
     let compositionsReady = 0;
     for (const beat of parsed.beats) {
-      if (existsSync2(join2(projectDir, "compositions", `scene-${beat.id}.html`))) {
+      if (existsSync2(join3(projectDir, "compositions", `scene-${beat.id}.html`))) {
         compositionsReady += 1;
       } else {
         needsAuthor.push(beat.id);
@@ -24931,7 +25516,7 @@ async function readProjectBeatReadiness(projectDir, build, records) {
 }
 function deriveProjectWorkflow(opts) {
   const retryWith = [];
-  const hasStoryboard = existsSync2(join2(opts.project, "STORYBOARD.md"));
+  const hasStoryboard = existsSync2(join3(opts.project, "STORYBOARD.md"));
   if (!hasStoryboard && !opts.build) {
     retryWith.push(`vibe init ${opts.project} --from "<brief>" --json`);
     return { status: "empty", currentStage: "init", retryWith };
@@ -25027,7 +25612,7 @@ function beatReadinessFromBuildBeats(projectDir, beats, records = [], reportJobs
     if (buildBeatAssetsReady(record) || (id ? buildBeatJobsReady(id, records, reportJobs) : false))
       assetsReady += 1;
     const compositionPath = typeof record.compositionPath === "string" ? record.compositionPath : id ? `compositions/scene-${id}.html` : void 0;
-    if (compositionPath && existsSync2(resolve5(projectDir, compositionPath))) {
+    if (compositionPath && existsSync2(resolve6(projectDir, compositionPath))) {
       compositionsReady += 1;
     } else if (id) {
       needsAuthor.push(id);
@@ -25097,6 +25682,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";
 }
@@ -25126,7 +25714,7 @@ function assetKindForJob(record) {
   return void 0;
 }
 function projectRelativePath(projectDir, path14) {
-  const rel = relative(resolve5(projectDir), resolve5(path14));
+  const rel = relative(resolve6(projectDir), resolve6(path14));
   if (!rel || rel.startsWith("..")) return path14;
   return rel.replace(/\\/g, "/");
 }
@@ -25144,7 +25732,7 @@ async function statOrNull(path14) {
     return null;
   }
 }
-function stripUndefined(value) {
+function stripUndefined2(value) {
   return Object.fromEntries(Object.entries(value).filter(([, v2]) => v2 !== void 0));
 }
 function unique(items) {
@@ -25162,6 +25750,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;
   }
@@ -25170,7 +25759,7 @@ var init_status_jobs = __esm({
 // ../cli/src/commands/_shared/project-config.ts
 import { existsSync as existsSync3 } from "node:fs";
 import { readFile as readFile5 } from "node:fs/promises";
-import { resolve as resolve6 } from "node:path";
+import { resolve as resolve7 } from "node:path";
 function defaultProjectConfig(opts) {
   return {
     schemaVersion: "1",
@@ -25221,9 +25810,9 @@ function projectConfigJson(opts) {
   return JSON.stringify(defaultProjectConfig(opts), null, 2) + "\n";
 }
 async function readProjectConfig(projectDir) {
-  const dir = resolve6(projectDir);
-  const canonicalPath = resolve6(dir, VIBE_CONFIG_FILENAME);
-  const legacyPath = resolve6(dir, LEGACY_VIBE_PROJECT_FILENAME);
+  const dir = resolve7(projectDir);
+  const canonicalPath = resolve7(dir, VIBE_CONFIG_FILENAME);
+  const legacyPath = resolve7(dir, LEGACY_VIBE_PROJECT_FILENAME);
   if (existsSync3(canonicalPath)) {
     try {
       const raw2 = await readFile5(canonicalPath, "utf-8");
@@ -25286,8 +25875,8 @@ var init_project_config = __esm({
 });
 
 // ../cli/src/commands/_shared/scene-project.ts
-import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile7, access as access3 } from "node:fs/promises";
-import { resolve as resolve7, basename as basename2 } from "node:path";
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile8, access as access3 } from "node:fs/promises";
+import { resolve as resolve8, basename as basename2 } from "node:path";
 function aspectToDims(aspect) {
   return ASPECT_DIMS[aspect];
 }
@@ -25585,6 +26174,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
@@ -25688,35 +26314,35 @@ tmp/
 `;
 }
 function describeSceneScaffold(opts) {
-  const dir = resolve7(opts.dir);
+  const dir = resolve8(opts.dir);
   const profile = opts.profile ?? "full";
   const groups = {
     authoring: [
-      resolve7(dir, "STORYBOARD.md"),
-      resolve7(dir, "DESIGN.md"),
-      resolve7(dir, VIBE_CONFIG_FILENAME),
-      resolve7(dir, "vibe.project.yaml"),
-      resolve7(dir, ".gitignore")
+      resolve8(dir, "STORYBOARD.md"),
+      resolve8(dir, "DESIGN.md"),
+      resolve8(dir, VIBE_CONFIG_FILENAME),
+      resolve8(dir, "vibe.project.yaml"),
+      resolve8(dir, ".gitignore")
     ],
     render: [],
     agent: []
   };
   if (profile === "full") {
     groups.render = [
-      resolve7(dir, "index.html"),
-      resolve7(dir, "compositions"),
-      resolve7(dir, "assets"),
-      resolve7(dir, "renders"),
-      resolve7(dir, "hyperframes.json"),
-      resolve7(dir, "meta.json")
+      resolve8(dir, "index.html"),
+      resolve8(dir, "compositions"),
+      resolve8(dir, "assets"),
+      resolve8(dir, "renders"),
+      resolve8(dir, "hyperframes.json"),
+      resolve8(dir, "meta.json")
     ];
   }
   if (profile === "agent" || profile === "full") {
     groups.agent = [
-      resolve7(dir, "AGENTS.md"),
-      resolve7(dir, "SKILL.md"),
-      resolve7(dir, "references"),
-      resolve7(dir, "CLAUDE.md")
+      resolve8(dir, "AGENTS.md"),
+      resolve8(dir, "SKILL.md"),
+      resolve8(dir, "references"),
+      resolve8(dir, "CLAUDE.md")
     ];
   }
   return groups;
@@ -25730,7 +26356,7 @@ async function pathExists(p2) {
   }
 }
 async function scaffoldSceneProject(opts) {
-  const dir = resolve7(opts.dir);
+  const dir = resolve8(opts.dir);
   const name = opts.name ?? basename2(dir);
   const aspect = opts.aspect ?? "16:9";
   const duration = opts.duration ?? 10;
@@ -25738,103 +26364,103 @@ async function scaffoldSceneProject(opts) {
   const profile = opts.profile ?? "full";
   await mkdir4(dir, { recursive: true });
   if (profile === "full") {
-    await mkdir4(resolve7(dir, "compositions"), { recursive: true });
-    await mkdir4(resolve7(dir, "assets"), { recursive: true });
-    await mkdir4(resolve7(dir, "renders"), { recursive: true });
+    await mkdir4(resolve8(dir, "compositions"), { recursive: true });
+    await mkdir4(resolve8(dir, "assets"), { recursive: true });
+    await mkdir4(resolve8(dir, "renders"), { recursive: true });
   }
   const created = [];
   const skipped2 = [];
   const merged = [];
   if (profile === "full") {
-    const hfPath = resolve7(dir, "hyperframes.json");
+    const hfPath = resolve8(dir, "hyperframes.json");
     const hfDefaults = buildHyperframesConfig();
     if (await pathExists(hfPath)) {
       const existingRaw = await readFile6(hfPath, "utf-8");
       const existing = JSON.parse(existingRaw);
       const mergedConfig = mergeHyperframesConfig(existing, hfDefaults);
-      await writeFile7(hfPath, JSON.stringify(mergedConfig, null, 2) + "\n", "utf-8");
+      await writeFile8(hfPath, JSON.stringify(mergedConfig, null, 2) + "\n", "utf-8");
       merged.push(hfPath);
     } else {
-      await writeFile7(hfPath, JSON.stringify(hfDefaults, null, 2) + "\n", "utf-8");
+      await writeFile8(hfPath, JSON.stringify(hfDefaults, null, 2) + "\n", "utf-8");
       created.push(hfPath);
     }
-    const metaPath = resolve7(dir, "meta.json");
+    const metaPath = resolve8(dir, "meta.json");
     if (await pathExists(metaPath)) {
       skipped2.push(metaPath);
     } else {
-      await writeFile7(
+      await writeFile8(
         metaPath,
         JSON.stringify(buildHyperframesMeta(name, now), null, 2) + "\n",
         "utf-8"
       );
       created.push(metaPath);
     }
-    const rootPath = resolve7(dir, "index.html");
+    const rootPath = resolve8(dir, "index.html");
     if (await pathExists(rootPath)) {
       skipped2.push(rootPath);
     } else {
-      await writeFile7(rootPath, buildEmptyRootHtml({ aspect, duration }), "utf-8");
+      await writeFile8(rootPath, buildEmptyRootHtml({ aspect, duration }), "utf-8");
       created.push(rootPath);
     }
   }
-  const vibeConfigJsonPath = resolve7(dir, VIBE_CONFIG_FILENAME);
+  const vibeConfigJsonPath = resolve8(dir, VIBE_CONFIG_FILENAME);
   if (await pathExists(vibeConfigJsonPath)) {
     skipped2.push(vibeConfigJsonPath);
   } else {
-    await writeFile7(vibeConfigJsonPath, projectConfigJson({ name, aspect }), "utf-8");
+    await writeFile8(vibeConfigJsonPath, projectConfigJson({ name, aspect }), "utf-8");
     created.push(vibeConfigJsonPath);
   }
-  const vibePath = resolve7(dir, "vibe.project.yaml");
+  const vibePath = resolve8(dir, "vibe.project.yaml");
   if (await pathExists(vibePath)) {
     skipped2.push(vibePath);
   } else {
     const cfg = { ...defaultVibeProjectConfig(name), aspect };
-    await writeFile7(vibePath, (0, import_yaml4.stringify)(cfg), "utf-8");
+    await writeFile8(vibePath, (0, import_yaml4.stringify)(cfg), "utf-8");
     created.push(vibePath);
   }
   if (profile === "agent" || profile === "full") {
-    const agentsPath = resolve7(dir, "AGENTS.md");
+    const agentsPath = resolve8(dir, "AGENTS.md");
     if (await pathExists(agentsPath)) {
       skipped2.push(agentsPath);
     } else {
-      await writeFile7(agentsPath, buildProjectAgentsMd(name), "utf-8");
+      await writeFile8(agentsPath, buildProjectAgentsMd(name), "utf-8");
       created.push(agentsPath);
     }
-    const claudePath = resolve7(dir, "CLAUDE.md");
+    const claudePath = resolve8(dir, "CLAUDE.md");
     if (await pathExists(claudePath)) {
       const existing = await readFile6(claudePath, "utf-8");
       if (existing.includes("@AGENTS.md")) {
         skipped2.push(claudePath);
       } else {
-        await writeFile7(claudePath, `@AGENTS.md
+        await writeFile8(claudePath, `@AGENTS.md
 
 ${existing}`, "utf-8");
         merged.push(claudePath);
       }
     } else {
-      await writeFile7(claudePath, buildProjectClaudeMd(name), "utf-8");
+      await writeFile8(claudePath, buildProjectClaudeMd(name), "utf-8");
       created.push(claudePath);
     }
   }
-  const designPath = resolve7(dir, "DESIGN.md");
+  const designPath = resolve8(dir, "DESIGN.md");
   if (await pathExists(designPath)) {
     skipped2.push(designPath);
   } else {
-    await writeFile7(designPath, buildDesignMd({ name, style: opts.visualStyle }), "utf-8");
+    await writeFile8(designPath, buildDesignMd({ name, style: opts.visualStyle }), "utf-8");
     created.push(designPath);
   }
-  const storyboardPath = resolve7(dir, "STORYBOARD.md");
+  const storyboardPath = resolve8(dir, "STORYBOARD.md");
   if (await pathExists(storyboardPath)) {
     skipped2.push(storyboardPath);
   } else {
-    await writeFile7(storyboardPath, buildStoryboardMd(name, duration), "utf-8");
+    await writeFile8(storyboardPath, buildStoryboardMd(name, duration), "utf-8");
     created.push(storyboardPath);
   }
-  const gitignorePath = resolve7(dir, ".gitignore");
+  const gitignorePath = resolve8(dir, ".gitignore");
   if (await pathExists(gitignorePath)) {
     skipped2.push(gitignorePath);
   } else {
-    await writeFile7(gitignorePath, buildSceneGitignore(), "utf-8");
+    await writeFile8(gitignorePath, buildSceneGitignore(), "utf-8");
     created.push(gitignorePath);
   }
   return { created, skipped: skipped2, merged, groups: describeSceneScaffold({ dir, profile }) };
@@ -33084,7 +33710,7 @@ var require_util = __commonJS({
       return path14;
     });
     exports.normalize = normalize3;
-    function join45(aRoot, aPath) {
+    function join44(aRoot, aPath) {
       if (aRoot === "") {
         aRoot = ".";
       }
@@ -33116,7 +33742,7 @@ var require_util = __commonJS({
       }
       return joined;
     }
-    exports.join = join45;
+    exports.join = join44;
     exports.isAbsolute = function(aPath) {
       return aPath.charAt(0) === "/" || urlRegexp.test(aPath);
     };
@@ -33330,7 +33956,7 @@ var require_util = __commonJS({
             parsed.path = parsed.path.substring(0, index + 1);
           }
         }
-        sourceURL = join45(urlGenerate(parsed), sourceURL);
+        sourceURL = join44(urlGenerate(parsed), sourceURL);
       }
       return normalize3(sourceURL);
     }
@@ -34770,8 +35396,8 @@ var require_source_map = __commonJS({
 var require_previous_map = __commonJS({
   "../../node_modules/.pnpm/postcss@8.5.6/node_modules/postcss/lib/previous-map.js"(exports, module) {
     "use strict";
-    var { existsSync: existsSync67, readFileSync: readFileSync12 } = __require("fs");
-    var { dirname: dirname33, join: join45 } = __require("path");
+    var { existsSync: existsSync67, readFileSync: readFileSync13 } = __require("fs");
+    var { dirname: dirname33, join: join44 } = __require("path");
     var { SourceMapConsumer, SourceMapGenerator } = require_source_map();
     function fromBase64(str2) {
       if (Buffer) {
@@ -34835,7 +35461,7 @@ var require_previous_map = __commonJS({
         this.root = dirname33(path14);
         if (existsSync67(path14)) {
           this.mapFile = path14;
-          return readFileSync12(path14, "utf-8").toString().trim();
+          return readFileSync13(path14, "utf-8").toString().trim();
         }
       }
       loadMap(file, prev) {
@@ -34869,7 +35495,7 @@ var require_previous_map = __commonJS({
           return this.decodeInline(this.annotation);
         } else if (this.annotation) {
           let map3 = this.annotation;
-          if (file) map3 = join45(dirname33(file), map3);
+          if (file) map3 = join44(dirname33(file), map3);
           return this.loadFile(map3);
         }
       }
@@ -82324,14 +82950,14 @@ var require_re = __commonJS({
       return value;
     };
     var createToken = (name, value, isGlobal) => {
-      const safe = makeSafeRegex(value);
+      const safe2 = makeSafeRegex(value);
       const index = R2++;
       debug9(name, index, value);
       t2[name] = index;
       src[index] = value;
-      safeSrc[index] = safe;
+      safeSrc[index] = safe2;
       re2[index] = new RegExp(value, isGlobal ? "g" : void 0);
-      safeRe[index] = new RegExp(safe, isGlobal ? "g" : void 0);
+      safeRe[index] = new RegExp(safe2, isGlobal ? "g" : void 0);
     };
     createToken("NUMERICIDENTIFIER", "0|[1-9]\\d*");
     createToken("NUMERICIDENTIFIERLOOSE", "\\d+");
@@ -93498,7 +94124,7 @@ var require_util3 = __commonJS({
       return path14;
     }
     exports.normalize = normalize3;
-    function join45(aRoot, aPath) {
+    function join44(aRoot, aPath) {
       if (aRoot === "") {
         aRoot = ".";
       }
@@ -93530,7 +94156,7 @@ var require_util3 = __commonJS({
       }
       return joined;
     }
-    exports.join = join45;
+    exports.join = join44;
     exports.isAbsolute = function(aPath) {
       return aPath.charAt(0) === "/" || urlRegexp.test(aPath);
     };
@@ -93703,7 +94329,7 @@ var require_util3 = __commonJS({
             parsed.path = parsed.path.substring(0, index + 1);
           }
         }
-        sourceURL = join45(urlGenerate(parsed), sourceURL);
+        sourceURL = join44(urlGenerate(parsed), sourceURL);
       }
       return normalize3(sourceURL);
     }
@@ -95505,7 +96131,7 @@ var require_escodegen = __commonJS({
       function noEmptySpace() {
         return space ? space : " ";
       }
-      function join45(left3, right3) {
+      function join44(left3, right3) {
         var leftSource, rightSource, leftCharCode, rightCharCode;
         leftSource = toSourceNodeWhenNeeded(left3).toString();
         if (leftSource.length === 0) {
@@ -95836,8 +96462,8 @@ var require_escodegen = __commonJS({
           } else {
             result.push(that.generateExpression(stmt.left, Precedence.Call, E_TTT));
           }
-          result = join45(result, operator);
-          result = [join45(
+          result = join44(result, operator);
+          result = [join44(
             result,
             that.generateExpression(stmt.right, Precedence.Assignment, E_TTT)
           ), ")"];
@@ -95980,11 +96606,11 @@ var require_escodegen = __commonJS({
           var result, fragment;
           result = ["class"];
           if (stmt.id) {
-            result = join45(result, this.generateExpression(stmt.id, Precedence.Sequence, E_TTT));
+            result = join44(result, this.generateExpression(stmt.id, Precedence.Sequence, E_TTT));
           }
           if (stmt.superClass) {
-            fragment = join45("extends", this.generateExpression(stmt.superClass, Precedence.Unary, E_TTT));
-            result = join45(result, fragment);
+            fragment = join44("extends", this.generateExpression(stmt.superClass, Precedence.Unary, E_TTT));
+            result = join44(result, fragment);
           }
           result.push(space);
           result.push(this.generateStatement(stmt.body, S_TFFT));
@@ -95997,9 +96623,9 @@ var require_escodegen = __commonJS({
           return escapeDirective(stmt.directive) + this.semicolon(flags);
         },
         DoWhileStatement: function(stmt, flags) {
-          var result = join45("do", this.maybeBlock(stmt.body, S_TFFF));
+          var result = join44("do", this.maybeBlock(stmt.body, S_TFFF));
           result = this.maybeBlockSuffix(stmt.body, result);
-          return join45(result, [
+          return join44(result, [
             "while" + space + "(",
             this.generateExpression(stmt.test, Precedence.Sequence, E_TTT),
             ")" + this.semicolon(flags)
@@ -96035,11 +96661,11 @@ var require_escodegen = __commonJS({
         ExportDefaultDeclaration: function(stmt, flags) {
           var result = ["export"], bodyFlags;
           bodyFlags = flags & F_SEMICOLON_OPT ? S_TFFT : S_TFFF;
-          result = join45(result, "default");
+          result = join44(result, "default");
           if (isStatement(stmt.declaration)) {
-            result = join45(result, this.generateStatement(stmt.declaration, bodyFlags));
+            result = join44(result, this.generateStatement(stmt.declaration, bodyFlags));
           } else {
-            result = join45(result, this.generateExpression(stmt.declaration, Precedence.Assignment, E_TTT) + this.semicolon(flags));
+            result = join44(result, this.generateExpression(stmt.declaration, Precedence.Assignment, E_TTT) + this.semicolon(flags));
           }
           return result;
         },
@@ -96047,15 +96673,15 @@ var require_escodegen = __commonJS({
           var result = ["export"], bodyFlags, that = this;
           bodyFlags = flags & F_SEMICOLON_OPT ? S_TFFT : S_TFFF;
           if (stmt.declaration) {
-            return join45(result, this.generateStatement(stmt.declaration, bodyFlags));
+            return join44(result, this.generateStatement(stmt.declaration, bodyFlags));
           }
           if (stmt.specifiers) {
             if (stmt.specifiers.length === 0) {
-              result = join45(result, "{" + space + "}");
+              result = join44(result, "{" + space + "}");
             } else if (stmt.specifiers[0].type === Syntax.ExportBatchSpecifier) {
-              result = join45(result, this.generateExpression(stmt.specifiers[0], Precedence.Sequence, E_TTT));
+              result = join44(result, this.generateExpression(stmt.specifiers[0], Precedence.Sequence, E_TTT));
             } else {
-              result = join45(result, "{");
+              result = join44(result, "{");
               withIndent(function(indent2) {
                 var i2, iz;
                 result.push(newline);
@@ -96073,7 +96699,7 @@ var require_escodegen = __commonJS({
               result.push(base + "}");
             }
             if (stmt.source) {
-              result = join45(result, [
+              result = join44(result, [
                 "from" + space,
                 // ModuleSpecifier
                 this.generateExpression(stmt.source, Precedence.Sequence, E_TTT),
@@ -96161,7 +96787,7 @@ var require_escodegen = __commonJS({
           ];
           cursor = 0;
           if (stmt.specifiers[cursor].type === Syntax.ImportDefaultSpecifier) {
-            result = join45(result, [
+            result = join44(result, [
               this.generateExpression(stmt.specifiers[cursor], Precedence.Sequence, E_TTT)
             ]);
             ++cursor;
@@ -96171,7 +96797,7 @@ var require_escodegen = __commonJS({
               result.push(",");
             }
             if (stmt.specifiers[cursor].type === Syntax.ImportNamespaceSpecifier) {
-              result = join45(result, [
+              result = join44(result, [
                 space,
                 this.generateExpression(stmt.specifiers[cursor], Precedence.Sequence, E_TTT)
               ]);
@@ -96200,7 +96826,7 @@ var require_escodegen = __commonJS({
               }
             }
           }
-          result = join45(result, [
+          result = join44(result, [
             "from" + space,
             // ModuleSpecifier
             this.generateExpression(stmt.source, Precedence.Sequence, E_TTT),
@@ -96254,7 +96880,7 @@ var require_escodegen = __commonJS({
           return result;
         },
         ThrowStatement: function(stmt, flags) {
-          return [join45(
+          return [join44(
             "throw",
             this.generateExpression(stmt.argument, Precedence.Sequence, E_TTT)
           ), this.semicolon(flags)];
@@ -96265,7 +96891,7 @@ var require_escodegen = __commonJS({
           result = this.maybeBlockSuffix(stmt.block, result);
           if (stmt.handlers) {
             for (i2 = 0, iz = stmt.handlers.length; i2 < iz; ++i2) {
-              result = join45(result, this.generateStatement(stmt.handlers[i2], S_TFFF));
+              result = join44(result, this.generateStatement(stmt.handlers[i2], S_TFFF));
               if (stmt.finalizer || i2 + 1 !== iz) {
                 result = this.maybeBlockSuffix(stmt.handlers[i2].body, result);
               }
@@ -96273,7 +96899,7 @@ var require_escodegen = __commonJS({
           } else {
             guardedHandlers = stmt.guardedHandlers || [];
             for (i2 = 0, iz = guardedHandlers.length; i2 < iz; ++i2) {
-              result = join45(result, this.generateStatement(guardedHandlers[i2], S_TFFF));
+              result = join44(result, this.generateStatement(guardedHandlers[i2], S_TFFF));
               if (stmt.finalizer || i2 + 1 !== iz) {
                 result = this.maybeBlockSuffix(guardedHandlers[i2].body, result);
               }
@@ -96281,13 +96907,13 @@ var require_escodegen = __commonJS({
             if (stmt.handler) {
               if (Array.isArray(stmt.handler)) {
                 for (i2 = 0, iz = stmt.handler.length; i2 < iz; ++i2) {
-                  result = join45(result, this.generateStatement(stmt.handler[i2], S_TFFF));
+                  result = join44(result, this.generateStatement(stmt.handler[i2], S_TFFF));
                   if (stmt.finalizer || i2 + 1 !== iz) {
                     result = this.maybeBlockSuffix(stmt.handler[i2].body, result);
                   }
                 }
               } else {
-                result = join45(result, this.generateStatement(stmt.handler, S_TFFF));
+                result = join44(result, this.generateStatement(stmt.handler, S_TFFF));
                 if (stmt.finalizer) {
                   result = this.maybeBlockSuffix(stmt.handler.body, result);
                 }
@@ -96295,7 +96921,7 @@ var require_escodegen = __commonJS({
             }
           }
           if (stmt.finalizer) {
-            result = join45(result, ["finally", this.maybeBlock(stmt.finalizer, S_TFFF)]);
+            result = join44(result, ["finally", this.maybeBlock(stmt.finalizer, S_TFFF)]);
           }
           return result;
         },
@@ -96329,7 +96955,7 @@ var require_escodegen = __commonJS({
           withIndent(function() {
             if (stmt.test) {
               result = [
-                join45("case", that.generateExpression(stmt.test, Precedence.Sequence, E_TTT)),
+                join44("case", that.generateExpression(stmt.test, Precedence.Sequence, E_TTT)),
                 ":"
               ];
             } else {
@@ -96377,9 +97003,9 @@ var require_escodegen = __commonJS({
             result.push(this.maybeBlock(stmt.consequent, S_TFFF));
             result = this.maybeBlockSuffix(stmt.consequent, result);
             if (stmt.alternate.type === Syntax.IfStatement) {
-              result = join45(result, ["else ", this.generateStatement(stmt.alternate, bodyFlags)]);
+              result = join44(result, ["else ", this.generateStatement(stmt.alternate, bodyFlags)]);
             } else {
-              result = join45(result, join45("else", this.maybeBlock(stmt.alternate, bodyFlags)));
+              result = join44(result, join44("else", this.maybeBlock(stmt.alternate, bodyFlags)));
             }
           } else {
             result.push(this.maybeBlock(stmt.consequent, bodyFlags));
@@ -96480,7 +97106,7 @@ var require_escodegen = __commonJS({
         },
         ReturnStatement: function(stmt, flags) {
           if (stmt.argument) {
-            return [join45(
+            return [join44(
               "return",
               this.generateExpression(stmt.argument, Precedence.Sequence, E_TTT)
             ), this.semicolon(flags)];
@@ -96569,14 +97195,14 @@ var require_escodegen = __commonJS({
           if (leftSource.charCodeAt(leftSource.length - 1) === 47 && esutils.code.isIdentifierPartES5(expr.operator.charCodeAt(0))) {
             result = [fragment, noEmptySpace(), expr.operator];
           } else {
-            result = join45(fragment, expr.operator);
+            result = join44(fragment, expr.operator);
           }
           fragment = this.generateExpression(expr.right, rightPrecedence, flags);
           if (expr.operator === "/" && fragment.toString().charAt(0) === "/" || expr.operator.slice(-1) === "<" && fragment.toString().slice(0, 3) === "!--") {
             result.push(noEmptySpace());
             result.push(fragment);
           } else {
-            result = join45(result, fragment);
+            result = join44(result, fragment);
           }
           if (expr.operator === "in" && !(flags & F_ALLOW_IN)) {
             return ["(", result, ")"];
@@ -96616,7 +97242,7 @@ var require_escodegen = __commonJS({
           var result, length, i2, iz, itemFlags;
           length = expr["arguments"].length;
           itemFlags = flags & F_ALLOW_UNPARATH_NEW && !parentheses && length === 0 ? E_TFT : E_TFF;
-          result = join45(
+          result = join44(
             "new",
             this.generateExpression(expr.callee, Precedence.New, itemFlags)
           );
@@ -96666,11 +97292,11 @@ var require_escodegen = __commonJS({
           var result, fragment, rightCharCode, leftSource, leftCharCode;
           fragment = this.generateExpression(expr.argument, Precedence.Unary, E_TTT);
           if (space === "") {
-            result = join45(expr.operator, fragment);
+            result = join44(expr.operator, fragment);
           } else {
             result = [expr.operator];
             if (expr.operator.length > 2) {
-              result = join45(result, fragment);
+              result = join44(result, fragment);
             } else {
               leftSource = toSourceNodeWhenNeeded(result).toString();
               leftCharCode = leftSource.charCodeAt(leftSource.length - 1);
@@ -96693,7 +97319,7 @@ var require_escodegen = __commonJS({
             result = "yield";
           }
           if (expr.argument) {
-            result = join45(
+            result = join44(
               result,
               this.generateExpression(expr.argument, Precedence.Yield, E_TTT)
             );
@@ -96701,7 +97327,7 @@ var require_escodegen = __commonJS({
           return parenthesize(result, Precedence.Yield, precedence);
         },
         AwaitExpression: function(expr, precedence, flags) {
-          var result = join45(
+          var result = join44(
             expr.all ? "await*" : "await",
             this.generateExpression(expr.argument, Precedence.Await, E_TTT)
           );
@@ -96784,11 +97410,11 @@ var require_escodegen = __commonJS({
           var result, fragment;
           result = ["class"];
           if (expr.id) {
-            result = join45(result, this.generateExpression(expr.id, Precedence.Sequence, E_TTT));
+            result = join44(result, this.generateExpression(expr.id, Precedence.Sequence, E_TTT));
           }
           if (expr.superClass) {
-            fragment = join45("extends", this.generateExpression(expr.superClass, Precedence.Unary, E_TTT));
-            result = join45(result, fragment);
+            fragment = join44("extends", this.generateExpression(expr.superClass, Precedence.Unary, E_TTT));
+            result = join44(result, fragment);
           }
           result.push(space);
           result.push(this.generateStatement(expr.body, S_TFFT));
@@ -96803,7 +97429,7 @@ var require_escodegen = __commonJS({
           }
           if (expr.kind === "get" || expr.kind === "set") {
             fragment = [
-              join45(expr.kind, this.generatePropertyKey(expr.key, expr.computed)),
+              join44(expr.kind, this.generatePropertyKey(expr.key, expr.computed)),
               this.generateFunctionBody(expr.value)
             ];
           } else {
@@ -96813,7 +97439,7 @@ var require_escodegen = __commonJS({
               this.generateFunctionBody(expr.value)
             ];
           }
-          return join45(result, fragment);
+          return join44(result, fragment);
         },
         Property: function(expr, precedence, flags) {
           if (expr.kind === "get" || expr.kind === "set") {
@@ -97008,7 +97634,7 @@ var require_escodegen = __commonJS({
               for (i2 = 0, iz = expr.blocks.length; i2 < iz; ++i2) {
                 fragment = that.generateExpression(expr.blocks[i2], Precedence.Sequence, E_TTT);
                 if (i2 > 0 || extra.moz.comprehensionExpressionStartsWithAssignment) {
-                  result = join45(result, fragment);
+                  result = join44(result, fragment);
                 } else {
                   result.push(fragment);
                 }
@@ -97016,13 +97642,13 @@ var require_escodegen = __commonJS({
             });
           }
           if (expr.filter) {
-            result = join45(result, "if" + space);
+            result = join44(result, "if" + space);
             fragment = this.generateExpression(expr.filter, Precedence.Sequence, E_TTT);
-            result = join45(result, ["(", fragment, ")"]);
+            result = join44(result, ["(", fragment, ")"]);
           }
           if (!extra.moz.comprehensionExpressionStartsWithAssignment) {
             fragment = this.generateExpression(expr.body, Precedence.Assignment, E_TTT);
-            result = join45(result, fragment);
+            result = join44(result, fragment);
           }
           result.push(expr.type === Syntax.GeneratorExpression ? ")" : "]");
           return result;
@@ -97038,8 +97664,8 @@ var require_escodegen = __commonJS({
           } else {
             fragment = this.generateExpression(expr.left, Precedence.Call, E_TTT);
           }
-          fragment = join45(fragment, expr.of ? "of" : "in");
-          fragment = join45(fragment, this.generateExpression(expr.right, Precedence.Sequence, E_TTT));
+          fragment = join44(fragment, expr.of ? "of" : "in");
+          fragment = join44(fragment, this.generateExpression(expr.right, Precedence.Sequence, E_TTT));
           return ["for" + space + "(", fragment, ")"];
         },
         SpreadElement: function(expr, precedence, flags) {
@@ -118330,17 +118956,17 @@ var init_cliui = __esm({
 });
 
 // ../../node_modules/.pnpm/escalade@3.2.0/node_modules/escalade/sync/index.mjs
-import { dirname as dirname4, resolve as resolve9 } from "path";
+import { dirname as dirname4, resolve as resolve10 } from "path";
 import { readdirSync, statSync as statSync2 } from "fs";
 function sync_default(start, callback) {
-  let dir = resolve9(".", start);
+  let dir = resolve10(".", start);
   let tmp, stats = statSync2(dir);
   if (!stats.isDirectory()) {
     dir = dirname4(dir);
   }
   while (true) {
     tmp = callback(dir, readdirSync(dir));
-    if (tmp) return resolve9(dir, tmp);
+    if (tmp) return resolve10(dir, tmp);
     dir = dirname4(tmp = dir);
     if (tmp === dir) break;
   }
@@ -119306,7 +119932,7 @@ var init_yargs_parser = __esm({
 
 // ../../node_modules/.pnpm/yargs-parser@21.1.1/node_modules/yargs-parser/build/lib/index.js
 import { format } from "util";
-import { normalize, resolve as resolve10 } from "path";
+import { normalize, resolve as resolve11 } from "path";
 import { readFileSync as readFileSync3 } from "fs";
 var _a3, _b, _c, minNodeVersion, nodeVersion, env2, parser, yargsParser, lib_default;
 var init_lib2 = __esm({
@@ -119329,7 +119955,7 @@ var init_lib2 = __esm({
       },
       format,
       normalize,
-      resolve: resolve10,
+      resolve: resolve11,
       // TODO: figure  out a  way to combine ESM and CJS coverage, such  that
       // we can exercise all the lines below:
       require: (path14) => {
@@ -119396,19 +120022,19 @@ var init_yerror = __esm({
 });
 
 // ../../node_modules/.pnpm/y18n@5.0.8/node_modules/y18n/build/lib/platform-shims/node.js
-import { readFileSync as readFileSync4, statSync as statSync3, writeFile as writeFile8 } from "fs";
+import { readFileSync as readFileSync4, statSync as statSync3, writeFile as writeFile9 } from "fs";
 import { format as format2 } from "util";
-import { resolve as resolve11 } from "path";
+import { resolve as resolve12 } from "path";
 var node_default;
 var init_node = __esm({
   "../../node_modules/.pnpm/y18n@5.0.8/node_modules/y18n/build/lib/platform-shims/node.js"() {
     node_default = {
       fs: {
         readFileSync: readFileSync4,
-        writeFile: writeFile8
+        writeFile: writeFile9
       },
       format: format2,
-      resolve: resolve11,
+      resolve: resolve12,
       exists: (file) => {
         try {
           return statSync3(file).isFile();
@@ -119603,7 +120229,7 @@ import { notStrictEqual, strictEqual } from "assert";
 import { inspect } from "util";
 import { readFileSync as readFileSync5 } from "fs";
 import { fileURLToPath } from "url";
-import { basename as basename3, dirname as dirname5, extname as extname2, relative as relative2, resolve as resolve12 } from "path";
+import { basename as basename3, dirname as dirname5, extname as extname2, relative as relative2, resolve as resolve13 } from "path";
 var REQUIRE_ERROR, REQUIRE_DIRECTORY_ERROR, __dirname2, mainFilename, esm_default;
 var init_esm2 = __esm({
   "../../node_modules/.pnpm/yargs@17.7.2/node_modules/yargs/lib/platform-shims/esm.mjs"() {
@@ -119644,7 +120270,7 @@ var init_esm2 = __esm({
         dirname: dirname5,
         extname: extname2,
         relative: relative2,
-        resolve: resolve12
+        resolve: resolve13
       },
       process: {
         argv: () => process.argv,
@@ -119666,7 +120292,7 @@ var init_esm2 = __esm({
         return [...str2].length;
       },
       y18n: y18n_default({
-        directory: resolve12(__dirname2, "../../../locales"),
+        directory: resolve13(__dirname2, "../../../locales"),
         updateFiles: false
       })
     };
@@ -123441,9 +124067,9 @@ async function getConnectionTransport(options) {
       throw new Error("Could not detect required browser platform");
     }
     const { convertPuppeteerChannelToBrowsersChannel: convertPuppeteerChannelToBrowsersChannel3 } = await Promise.resolve().then(() => (init_LaunchOptions(), LaunchOptions_exports));
-    const { join: join45 } = await import("node:path");
+    const { join: join44 } = await import("node:path");
     const userDataDir = resolveDefaultUserDataDir4(Browser5.CHROME, platform, convertPuppeteerChannelToBrowsersChannel3(options.channel));
-    const portPath = join45(userDataDir, "DevToolsActivePort");
+    const portPath = join44(userDataDir, "DevToolsActivePort");
     try {
       const fileContent = await environment.value.fs.promises.readFile(portPath, "ascii");
       const [rawPort, rawPath] = fileContent.split("\n").map((line) => {
@@ -123766,7 +124392,7 @@ var init_PipeTransport = __esm({
 // ../../node_modules/.pnpm/puppeteer-core@24.41.0/node_modules/puppeteer-core/lib/esm/puppeteer/node/BrowserLauncher.js
 import { existsSync as existsSync5 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 var BrowserLauncher;
 var init_BrowserLauncher = __esm({
   "../../node_modules/.pnpm/puppeteer-core@24.41.0/node_modules/puppeteer-core/lib/esm/puppeteer/node/BrowserLauncher.js"() {
@@ -123886,7 +124512,7 @@ var init_BrowserLauncher = __esm({
           if (logs.includes("Failed to create a ProcessSingleton for your profile directory") || // On Windows we will not get logs due to the singleton process
           // handover. See
           // https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/process_singleton_win.cc;l=46;drc=fc7952f0422b5073515a205a04ec9c3a1ae81658
-          process.platform === "win32" && existsSync5(join4(launchArgs.userDataDir, "lockfile"))) {
+          process.platform === "win32" && existsSync5(join5(launchArgs.userDataDir, "lockfile"))) {
             throw new Error(`The browser is already running for ${launchArgs.userDataDir}. Use a different \`userDataDir\` or stop the running browser first.`);
           }
           if (logs.includes("Missing X server") && options.headless === false) {
@@ -124017,7 +124643,7 @@ var init_BrowserLauncher = __esm({
        * @internal
        */
       getProfilePath() {
-        return join4(this.puppeteer.configuration.temporaryDirectory ?? tmpdir(), `puppeteer_dev_${this.browser}_profile-`);
+        return join5(this.puppeteer.configuration.temporaryDirectory ?? tmpdir(), `puppeteer_dev_${this.browser}_profile-`);
       }
       /**
        * @internal
@@ -292672,7 +293298,7 @@ ${newComment.split("\n").map((c2) => ` * ${c2}`).join("\n")}
             }
           }
           return result;
-          function escapeRegExp3(str2) {
+          function escapeRegExp5(str2) {
             return str2.replace(/[-[\]/{}()*+?.\\^$|]/g, "\\$&");
           }
           function getTodoCommentsRegExp() {
@@ -292680,7 +293306,7 @@ ${newComment.split("\n").map((c2) => ` * ${c2}`).join("\n")}
             const multiLineCommentStart = /(?:\/\*+\s*)/.source;
             const anyNumberOfSpacesAndAsterisksAtStartOfLine = /(?:^(?:\s|\*)*)/.source;
             const preamble = "(" + anyNumberOfSpacesAndAsterisksAtStartOfLine + "|" + singleLineCommentStart + "|" + multiLineCommentStart + ")";
-            const literals = "(?:" + map3(descriptors, (d2) => "(" + escapeRegExp3(d2.text) + ")").join("|") + ")";
+            const literals = "(?:" + map3(descriptors, (d2) => "(" + escapeRegExp5(d2.text) + ")").join("|") + ")";
             const endOfLineOrEndOfComment = /(?:$|\*\/)/.source;
             const messageRemainder = /(?:.*?)/.source;
             const messagePortion = "(" + literals + messageRemainder + ")";
@@ -340513,7 +341139,7 @@ var require_dist15 = __commonJS({
 
 // ../../node_modules/.pnpm/puppeteer@24.41.0_typescript@5.9.3/node_modules/puppeteer/lib/esm/puppeteer/getConfiguration.js
 import { homedir as homedir3 } from "node:os";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 function getBooleanEnvVar(name) {
   const env4 = process.env[name];
   if (env4 === void 0) {
@@ -340593,7 +341219,7 @@ var init_getConfiguration = __esm({
       configuration2.firefox = getBrowserSetting("firefox", configuration2, {
         skipDownload: true
       });
-      configuration2.cacheDirectory = process.env["PUPPETEER_CACHE_DIR"] ?? configuration2.cacheDirectory ?? join5(homedir3(), ".cache", "puppeteer");
+      configuration2.cacheDirectory = process.env["PUPPETEER_CACHE_DIR"] ?? configuration2.cacheDirectory ?? join6(homedir3(), ".cache", "puppeteer");
       configuration2.temporaryDirectory = process.env["PUPPETEER_TMP_DIR"] ?? configuration2.temporaryDirectory;
       configuration2.experiments ??= {};
       return configuration2;
@@ -340921,7 +341547,7 @@ import { readdirSync as readdirSync2, statSync as statSync4 } from "fs";
 import { format as format3 } from "util";
 import { normalize as normalize2, resolve as resolve32 } from "path";
 import { readFileSync as readFileSync22 } from "fs";
-import { readFileSync as readFileSync32, statSync as statSync22, writeFile as writeFile9 } from "fs";
+import { readFileSync as readFileSync32, statSync as statSync22, writeFile as writeFile10 } from "fs";
 import { format as format22 } from "util";
 import { resolve as resolve42 } from "path";
 import { notStrictEqual as notStrictEqual2, strictEqual as strictEqual2 } from "assert";
@@ -340979,7 +341605,7 @@ import { join as join8 } from "path";
 import { spawn as spawn7 } from "child_process";
 import { createWriteStream as createWriteStream22, existsSync as existsSync7, mkdirSync as mkdirSync4 } from "fs";
 import { createHash as createHash3 } from "crypto";
-import { join as join7, extname as extname22 } from "path";
+import { join as join72, extname as extname22 } from "path";
 import { Readable } from "stream";
 import { finished } from "stream/promises";
 import { promises as fs72 } from "fs";
@@ -351067,7 +351693,7 @@ async function downloadToTemp(url, destDir, timeoutMs = 3e5) {
     mkdirSync4(destDir, { recursive: true });
   }
   const filename = getFilenameFromUrl(url);
-  const localPath = join7(destDir, filename);
+  const localPath = join72(destDir, filename);
   if (existsSync7(localPath)) {
     downloadPathCache.set(url, localPath);
     return localPath;
@@ -399082,14 +399708,14 @@ ${sourceUrlComment}
           return value;
         };
         var createToken = (name, value, isGlobal) => {
-          const safe = makeSafeRegex(value);
+          const safe2 = makeSafeRegex(value);
           const index = R2++;
           debug62(name, index, value);
           t2[name] = index;
           src[index] = value;
-          safeSrc[index] = safe;
+          safeSrc[index] = safe2;
           re2[index] = new RegExp(value, isGlobal ? "g" : void 0);
-          safeRe[index] = new RegExp(safe, isGlobal ? "g" : void 0);
+          safeRe[index] = new RegExp(safe2, isGlobal ? "g" : void 0);
         };
         createToken("NUMERICIDENTIFIER", "0|[1-9]\\d*");
         createToken("NUMERICIDENTIFIERLOOSE", "\\d+");
@@ -433316,7 +433942,7 @@ If you think this is a bug, please report it on the Puppeteer issue tracker.`;
         node_default2 = {
           fs: {
             readFileSync: readFileSync32,
-            writeFile: writeFile9
+            writeFile: writeFile10
           },
           format: format22,
           resolve: resolve42,
@@ -450239,14 +450865,14 @@ ${right22.raw}`)
 });
 
 // ../cli/src/commands/_shared/scene-lint.ts
-import { readdir as readdir4, readFile as readFile7, writeFile as writeFile10, stat as stat2 } from "node:fs/promises";
+import { readdir as readdir4, readFile as readFile7, writeFile as writeFile11, stat as stat2 } from "node:fs/promises";
 import { existsSync as existsSync18 } from "node:fs";
-import { resolve as resolve14, relative as relative4, join as join18 } from "node:path";
+import { resolve as resolve15, relative as relative4, join as join18 } from "node:path";
 async function discoverSceneFiles(opts) {
-  const projectDir = resolve14(opts.projectDir);
-  const rootAbs = resolve14(projectDir, opts.rootRel ?? "index.html");
+  const projectDir = resolve15(opts.projectDir);
+  const rootAbs = resolve15(projectDir, opts.rootRel ?? "index.html");
   const root2 = existsSync18(rootAbs) ? rootAbs : null;
-  const compsDir = resolve14(projectDir, "compositions");
+  const compsDir = resolve15(projectDir, "compositions");
   const subs = [];
   if (existsSync18(compsDir)) {
     await collectHtmlRecursive(compsDir, subs);
@@ -450332,7 +450958,7 @@ function addClipClassToTimedElements(html) {
   });
 }
 async function runProjectLint(opts) {
-  const projectDir = resolve14(opts.projectDir);
+  const projectDir = resolve15(opts.projectDir);
   const { root: root2, subs } = await discoverSceneFiles({ projectDir, rootRel: opts.rootRel });
   const files = [];
   const fixed = [];
@@ -450356,7 +450982,7 @@ async function runProjectLint(opts) {
     if (opts.fix && findings.length > 0) {
       const { html: nextHtml, fixedCodes } = applyMechanicalFixes(html, findings);
       if (fixedCodes.length > 0) {
-        await writeFile10(abs, nextHtml, "utf-8");
+        await writeFile11(abs, nextHtml, "utf-8");
         fixed.push({ file: rel, codes: fixedCodes });
         const reLinted = runHyperframeLint({ ...prepared, html: nextHtml });
         files.push({
@@ -450393,7 +451019,7 @@ async function runProjectLint(opts) {
   };
 }
 async function rootExists(projectDir, rootRel = "index.html") {
-  const abs = resolve14(projectDir, rootRel);
+  const abs = resolve15(projectDir, rootRel);
   try {
     const s2 = await stat2(abs);
     return s2.isFile();
@@ -469393,12 +470019,12 @@ var init_dist3 = __esm({
 
 // ../cli/src/commands/_shared/root-sync.ts
 import { existsSync as existsSync23 } from "node:fs";
-import { readFile as readFile8, writeFile as writeFile12 } from "node:fs/promises";
-import { join as join23, resolve as resolve16 } from "node:path";
+import { readFile as readFile8, writeFile as writeFile13 } from "node:fs/promises";
+import { join as join23, resolve as resolve17 } from "node:path";
 async function createRootSyncPlan(opts) {
-  const projectDir = resolve16(opts.projectDir);
+  const projectDir = resolve17(opts.projectDir);
   const rootRel = opts.rootRel ?? "index.html";
-  const rootPath = resolve16(projectDir, rootRel);
+  const rootPath = resolve17(projectDir, rootRel);
   if (!existsSync23(rootPath)) {
     return { rootPath, rootRel, exists: false, changed: false, fixCodes: [], issues: [] };
   }
@@ -469456,11 +470082,11 @@ async function createProjectRootSyncPlan(opts) {
 }
 async function syncRootComposition(opts) {
   const plan = await createRootSyncPlan(opts);
-  if (plan.nextHtml) await writeFile12(plan.rootPath, plan.nextHtml, "utf-8");
+  if (plan.nextHtml) await writeFile13(plan.rootPath, plan.nextHtml, "utf-8");
   return plan;
 }
 async function loadProjectRootSyncBeats(projectDir) {
-  const root2 = resolve16(projectDir);
+  const root2 = resolve17(projectDir);
   const storyboardPath = join23(root2, "STORYBOARD.md");
   if (!existsSync23(storyboardPath)) return [];
   const parsed = parseStoryboard(await readFile8(storyboardPath, "utf-8"));
@@ -469537,7 +470163,7 @@ async function resolveSyncedBeatDuration(opts) {
   }
 }
 async function resolveProjectBeatDurations(projectDir) {
-  const root2 = resolve16(projectDir);
+  const root2 = resolve17(projectDir);
   const beats = await loadProjectRootSyncBeats(root2);
   const durations = /* @__PURE__ */ new Map();
   for (const beat of beats) {
@@ -469786,8 +470412,8 @@ __export(compose_scenes_skills_exports, {
 });
 import { createHash as createHash5 } from "node:crypto";
 import { existsSync as existsSync24, mkdirSync as mkdirSync12 } from "node:fs";
-import { mkdir as mkdir9, readFile as readFile9, writeFile as writeFile13 } from "node:fs/promises";
-import { dirname as dirname13, join as join24, resolve as resolve17 } from "node:path";
+import { mkdir as mkdir9, readFile as readFile9, writeFile as writeFile14 } from "node:fs/promises";
+import { dirname as dirname13, join as join24, resolve as resolve18 } from "node:path";
 function buildSystemPrompt(ctx) {
   return `You are a Hyperframes composition author. The skill content below
 defines the framework rules, motion principles, and quality standards.
@@ -469880,7 +470506,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.
@@ -470047,7 +470681,7 @@ async function composeBeatHtml(ctx, overrides) {
   const html = extractHtml(result.text);
   try {
     mkdirSync12(cacheDir, { recursive: true });
-    await writeFile13(cachePath, html, "utf-8");
+    await writeFile14(cachePath, html, "utf-8");
   } catch {
   }
   const costUsd = result.inputTokens / 1e6 * settings.costPerMTokIn + result.outputTokens / 1e6 * settings.costPerMTokOut;
@@ -470146,9 +470780,9 @@ async function resolveComposerConfigAware(explicit, cwd) {
   return resolveComposer();
 }
 async function executeComposeScenesWithSkills(params, outputDir, overrides) {
-  const projectRoot = params.project ? resolve17(outputDir, params.project) : resolve17(outputDir);
-  const designPath = resolve17(projectRoot, params.design ?? "DESIGN.md");
-  const storyboardPath = resolve17(projectRoot, params.storyboard ?? "STORYBOARD.md");
+  const projectRoot = params.project ? resolve18(outputDir, params.project) : resolve18(outputDir);
+  const designPath = resolve18(projectRoot, params.design ?? "DESIGN.md");
+  const storyboardPath = resolve18(projectRoot, params.storyboard ?? "STORYBOARD.md");
   if (!existsSync24(designPath)) {
     return { success: false, error: `DESIGN.md not found at ${designPath}` };
   }
@@ -470206,7 +470840,7 @@ async function executeComposeScenesWithSkills(params, outputDir, overrides) {
         );
         const compositionPath = join24(compositionsDir, `scene-${beat.id}.html`);
         await mkdir9(dirname13(compositionPath), { recursive: true });
-        await writeFile13(compositionPath, result.html, "utf-8");
+        await writeFile14(compositionPath, result.html, "utf-8");
         if (result.cached) {
           onProgress({
             type: "beat-cached",
@@ -470409,9 +471043,9 @@ var init_compose_scenes_skills = __esm({
 // ../cli/src/commands/_shared/compose-prompts.ts
 import { existsSync as existsSync25 } from "node:fs";
 import { readFile as readFile10 } from "node:fs/promises";
-import { join as join25, relative as relative6, resolve as resolve18 } from "node:path";
+import { join as join25, relative as relative6, resolve as resolve19 } from "node:path";
 async function getComposePrompts(opts) {
-  const projectDir = resolve18(opts.projectDir);
+  const projectDir = resolve19(opts.projectDir);
   const designPath = join25(projectDir, "DESIGN.md");
   const storyboardPath = join25(projectDir, "STORYBOARD.md");
   const skillPath = join25(projectDir, "SKILL.md");
@@ -470538,7 +471172,7 @@ var init_compose_prompts = __esm({
 // ../cli/src/commands/_shared/sub-comp-duration-sync.ts
 import { existsSync as existsSync27 } from "node:fs";
 import { readFile as readFile12 } from "node:fs/promises";
-import { join as join27, resolve as resolve20 } from "node:path";
+import { join as join27, resolve as resolve21 } from "node:path";
 function syncSubCompositionDurationHtml(html, beatId, newDurationSec, fileRel) {
   const compositionId = `scene-${beatId}`;
   const file = fileRel ?? `compositions/${compositionId}.html`;
@@ -470626,7 +471260,7 @@ function rewriteTimelineConst(html, oldDurationSec, newDurationSec) {
   return { html, rewritten: false, needsManualFix };
 }
 async function createSubCompDurationSyncPlans(opts) {
-  const projectDir = resolve20(opts.projectDir);
+  const projectDir = resolve21(opts.projectDir);
   const results = [];
   for (const beat of opts.beats) {
     const fileRel = `compositions/scene-${beat.id}.html`;
@@ -470661,88 +471295,6 @@ var init_sub_comp_duration_sync = __esm({
   }
 });
 
-// ../cli/src/commands/_shared/review-report.ts
-import { writeFile as writeFile15 } from "node:fs/promises";
-import { join as join28, resolve as resolve21 } from "node:path";
-function statusFromIssues(issues) {
-  if (issues.some((issue) => issue.severity === "error")) return "fail";
-  if (issues.some((issue) => issue.severity === "warning")) return "warn";
-  return "pass";
-}
-function scoreIssues(issues) {
-  let score = 100;
-  for (const issue of issues) {
-    if (issue.severity === "error") score -= 25;
-    else if (issue.severity === "warning") score -= 8;
-    else score -= 2;
-  }
-  return Math.max(0, Math.min(100, score));
-}
-function uniqueRetryWith(items) {
-  return [
-    ...new Set(items.filter((item) => typeof item === "string" && item.length > 0))
-  ];
-}
-function fixOwnerForIssue(issue) {
-  if (issue.fixOwner) return issue.fixOwner;
-  if (issue.code.startsWith("AI_REVIEW_")) return "host-agent";
-  if (issue.code.startsWith("STORYBOARD_")) return "host-agent";
-  if (issue.code === "PROJECT_NOT_FOUND" || issue.code === "MISSING_STORYBOARD" || issue.code === "BEAT_NOT_FOUND" || issue.code === "MISSING_DESIGN") {
-    return "host-agent";
-  }
-  return "vibe";
-}
-function normalizeReviewIssues(issues, fallbackOwner) {
-  return issues.map((issue) => ({
-    ...issue,
-    fixOwner: issue.fixOwner ?? fallbackOwner ?? fixOwnerForIssue(issue)
-  }));
-}
-function summarizeReviewIssues(issues) {
-  const normalized = normalizeReviewIssues(issues);
-  return {
-    issueCount: normalized.length,
-    errorCount: normalized.filter((issue) => issue.severity === "error").length,
-    warningCount: normalized.filter((issue) => issue.severity === "warning").length,
-    infoCount: normalized.filter((issue) => issue.severity === "info").length,
-    fixOwners: {
-      vibe: normalized.filter((issue) => issue.fixOwner === "vibe").length,
-      hostAgent: normalized.filter((issue) => issue.fixOwner === "host-agent").length
-    }
-  };
-}
-function buildReviewReport(opts) {
-  const issues = normalizeReviewIssues(opts.issues);
-  return stripUndefined2({
-    schemaVersion: "1",
-    kind: "review",
-    project: resolve21(opts.project),
-    mode: opts.mode,
-    beat: opts.beat,
-    status: opts.status,
-    score: opts.score,
-    issues,
-    summary: summarizeReviewIssues(issues),
-    retryWith: uniqueRetryWith(opts.retryWith),
-    sourceReports: opts.sourceReports ?? [],
-    reportPath: opts.reportPath
-  });
-}
-function defaultReviewReportPath(projectDir) {
-  return join28(resolve21(projectDir), "review-report.json");
-}
-async function writeReviewReport(path14, report) {
-  await writeFile15(path14, JSON.stringify(report, null, 2) + "\n", "utf-8");
-}
-function stripUndefined2(value) {
-  return Object.fromEntries(Object.entries(value).filter(([, v2]) => v2 !== void 0));
-}
-var init_review_report = __esm({
-  "../cli/src/commands/_shared/review-report.ts"() {
-    "use strict";
-  }
-});
-
 // ../cli/src/commands/_shared/scene-repair.ts
 import { readFile as readFile13, writeFile as writeFile16 } from "node:fs/promises";
 import { relative as relative7, resolve as resolve23 } from "node:path";
@@ -470869,16 +471421,308 @@ var init_scene_repair = __esm({
   }
 });
 
+// ../cli/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 [key2, value] of Object.entries(cues)) {
+      if (!ALLOWED_CUE_KEYS.has(key2)) {
+        issues.push({
+          severity: "warning",
+          code: "UNKNOWN_CUE",
+          beatId: beat.id,
+          message: `Beat "${beat.id}" uses unknown cue "${key2}". Supported cues: ${STORYBOARD_CUE_KEYS.join(", ")}.`
+        });
+        continue;
+      }
+      if (key2 === "characters") {
+        const validShape = typeof value === "string" || Array.isArray(value) && value.every((v2) => typeof v2 === "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 (key2 === "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(key2) && typeof value !== "string") {
+        issues.push({
+          severity: "error",
+          code: "INVALID_CUE_VALUE",
+          beatId: beat.id,
+          message: `Beat "${beat.id}" cue "${key2}" 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((i2) => i2.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 [key2, value] of Object.entries(cues)) {
+      next = setStoryboardCue(next, { beatId, key: key2, value });
+    }
+    return { markdown: next, action: "updated" };
+  }
+  const section = buildStoryboardBeatSection({ ...opts, beatId, cues });
+  if (sections.length > 0 && isStarterStoryboard(markdown)) {
+    const global3 = markdown.slice(0, sections[0].start).trimEnd();
+    return {
+      markdown: `${global3}
+
+${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 global3 = 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 global3 + 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(key2, value) {
+  if (key2 === "duration") {
+    const n2 = typeof value === "number" ? value : Number.parseFloat(String(value ?? ""));
+    if (!Number.isFinite(n2) || n2 <= 0) {
+      throw new Error("Cue duration must be a positive number.");
+    }
+    return n2;
+  }
+  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 match2;
+  while ((match2 = HEADING_RE2.exec(normalized)) !== null) {
+    headings.push({ start: match2.index, end: match2.index + match2[0].length, line: match2[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 match2 = body.match(LEADING_CUE_RE);
+  if (!match2) return null;
+  try {
+    const parsed = (0, import_yaml5.parse)(match2[2]);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { full: match2[0], error: "cue block must parse to a YAML object" };
+    }
+    return { full: match2[0], value: parsed };
+  } catch (error) {
+    return { full: match2[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({
+  "../cli/src/commands/_shared/storyboard-edit.ts"() {
+    "use strict";
+    import_yaml5 = __toESM(require_dist3(), 1);
+    init_storyboard_parse();
+    STORYBOARD_CUE_KEYS = [
+      "duration",
+      "narration",
+      "backdrop",
+      "video",
+      "keyframe",
+      "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", "keyframe", "motion", "voice", "music", "asset"]);
+    MAX_RECOMMENDED_BEAT_SEC = 15;
+  }
+});
+
 // ../cli/src/pipeline/renderers/chrome.ts
 import { existsSync as existsSync29 } from "node:fs";
 import { homedir as homedir7 } from "node:os";
-import { join as join29 } from "node:path";
+import { join as join28 } from "node:path";
 function findChrome() {
   const candidates = [
     process.env.HYPERFRAMES_CHROME_PATH,
     process.env.CHROME_PATH,
     // puppeteer auto-downloaded headless shell
-    join29(
+    join28(
       homedir7(),
       ".cache",
       "puppeteer",
@@ -471171,7 +472015,7 @@ __export(scene_render_exports, {
 import { execFile as execFile2 } from "node:child_process";
 import { existsSync as existsSync30 } from "node:fs";
 import { mkdir as mkdir12, readFile as readFile16, stat as stat3, writeFile as writeFile18 } from "node:fs/promises";
-import { resolve as resolve27, relative as relative9, dirname as dirname16, basename as basename7, join as join30, isAbsolute as isAbsolute3 } from "node:path";
+import { resolve as resolve27, relative as relative9, dirname as dirname16, basename as basename7, join as join29, isAbsolute as isAbsolute3 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 function qualityToCrf(quality = "standard") {
   return quality === "draft" ? 28 : quality === "high" ? 18 : 23;
@@ -471259,7 +472103,7 @@ async function executeSceneRender(opts = {}) {
   }
   let autoSyncApplied = false;
   let autoSyncWarning;
-  if (!opts.beatId && existsSync30(join30(projectDir, "STORYBOARD.md"))) {
+  if (!opts.beatId && existsSync30(join29(projectDir, "STORYBOARD.md"))) {
     try {
       const rootPlan = await createProjectRootSyncPlan({ projectDir });
       const subPlans = await createSubCompDurationSyncPlans({
@@ -471436,7 +472280,7 @@ async function safeStat(p2) {
 }
 async function prepareBeatRenderRoot(opts) {
   const root2 = `.vibeframe/tmp/render-beat-${sanitizeFileSegment(opts.beatId)}.html`;
-  const reportPath = join30(opts.projectDir, "build-report.json");
+  const reportPath = join29(opts.projectDir, "build-report.json");
   const retryWith = [
     `vibe build ${opts.projectDir} --beat ${opts.beatId} --stage sync --json`
   ];
@@ -471520,8 +472364,8 @@ async function prepareBeatRenderRoot(opts) {
     durationSec,
     narrationPath
   });
-  await mkdir12(dirname16(join30(opts.projectDir, root2)), { recursive: true });
-  await writeFile18(join30(opts.projectDir, root2), html, "utf-8");
+  await mkdir12(dirname16(join29(opts.projectDir, root2)), { recursive: true });
+  await writeFile18(join29(opts.projectDir, root2), html, "utf-8");
   return {
     success: true,
     root: root2,
@@ -471585,7 +472429,7 @@ function reportedBeatAssetPaths(beat) {
   ]);
 }
 async function writeRenderReport(projectDir, result) {
-  const reportPath = join30(projectDir, "render-report.json");
+  const reportPath = join29(projectDir, "render-report.json");
   try {
     await writeFile18(
       reportPath,
@@ -471782,6 +472626,8 @@ var init_build_asset_reference = __esm({
     EXTENSIONS = {
       narration: [".mp3", ".wav", ".m4a"],
       backdrop: [".png", ".jpg", ".jpeg", ".webp"],
+      character: [".png", ".jpg", ".jpeg", ".webp"],
+      keyframe: [".png", ".jpg", ".jpeg", ".webp"],
       video: [".mp4", ".mov", ".webm"],
       music: [".mp3", ".wav", ".m4a"]
     };
@@ -471819,6 +472665,28 @@ 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 keyframeCacheDescriptor(opts) {
+  return cacheAssetDescriptor("keyframe", {
+    beatId: opts.beatId,
+    cue: opts.cue,
+    provider: opts.provider,
+    quality: opts.quality,
+    size: opts.size,
+    ratio: opts.ratio,
+    characters: opts.characters && opts.characters.length > 0 ? opts.characters : void 0,
+    ext: "png"
+  });
+}
 function imageRatioForSize(size) {
   switch (size) {
     case "1024x1024":
@@ -471838,6 +472706,10 @@ 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,
+    // Omit when absent so existing (non-keyframe) clips keep their cache key.
+    keyframe: opts.keyframe || void 0,
     ext: "mp4"
   });
 }
@@ -471890,212 +472762,10 @@ var init_build_backdrop_prompt = __esm({
   }
 });
 
-// ../cli/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 [key2, value] of Object.entries(cues)) {
-      if (!ALLOWED_CUE_KEYS.has(key2)) {
-        issues.push({
-          severity: "warning",
-          code: "UNKNOWN_CUE",
-          beatId: beat.id,
-          message: `Beat "${beat.id}" uses unknown cue "${key2}". Supported cues: ${STORYBOARD_CUE_KEYS.join(", ")}.`
-        });
-        continue;
-      }
-      if (key2 === "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(key2) && typeof value !== "string") {
-        issues.push({
-          severity: "error",
-          code: "INVALID_CUE_VALUE",
-          beatId: beat.id,
-          message: `Beat "${beat.id}" cue "${key2}" 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((i2) => i2.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 global3 = 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 global3 + normalizeBeatChunks(chunks);
-}
-function normalizeBeatChunks(chunks) {
-  return chunks.map((chunk) => chunk.trim()).filter(Boolean).join("\n\n") + "\n";
-}
-function normalizeCueValue(key2, value) {
-  if (key2 === "duration") {
-    const n2 = typeof value === "number" ? value : Number.parseFloat(String(value ?? ""));
-    if (!Number.isFinite(n2) || n2 <= 0) {
-      throw new Error("Cue duration must be a positive number.");
-    }
-    return n2;
-  }
-  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 match2;
-  while ((match2 = HEADING_RE2.exec(normalized)) !== null) {
-    headings.push({ start: match2.index, end: match2.index + match2[0].length, line: match2[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 match2 = body.match(LEADING_CUE_RE);
-  if (!match2) return null;
-  try {
-    const parsed = (0, import_yaml5.parse)(match2[2]);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      return { full: match2[0], error: "cue block must parse to a YAML object" };
-    }
-    return { full: match2[0], value: parsed };
-  } catch (error) {
-    return { full: match2[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({
-  "../cli/src/commands/_shared/storyboard-edit.ts"() {
-    "use strict";
-    import_yaml5 = __toESM(require_dist3(), 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;
-  }
-});
-
 // ../cli/src/commands/_shared/build-plan.ts
 import { existsSync as existsSync33 } from "node:fs";
 import { readFile as readFile17 } from "node:fs/promises";
-import { dirname as dirname17, join as join31, resolve as resolve29 } from "node:path";
+import { dirname as dirname17, join as join30, resolve as resolve29 } from "node:path";
 function backdropCostUsd(quality) {
   return quality === "hd" ? 0.2 : 0.05;
 }
@@ -472104,7 +472774,7 @@ async function createBuildPlan(opts) {
   loadPlanEnv(projectDir);
   const stage = opts.stage ?? "all";
   const config4 = await readProjectConfig(projectDir);
-  const storyboardPath = join31(projectDir, "STORYBOARD.md");
+  const storyboardPath = join30(projectDir, "STORYBOARD.md");
   const warnings = [];
   const retryWith = [];
   const providerResolution = [];
@@ -472163,7 +472833,7 @@ async function createBuildPlan(opts) {
   const imageQuality = opts.imageQuality ?? config4.config.build.imageQuality ?? "hd";
   const imageSize2 = opts.imageSize ?? config4.config.build.imageSize ?? "1536x1024";
   const imageRatio = imageRatioForSize(imageSize2);
-  const needsComposer = includeCompose && mode !== "agent" && sourceBeats.some((beat) => !existsSync33(join31(projectDir, `compositions/scene-${beat.id}.html`)));
+  const needsComposer = includeCompose && mode !== "agent" && sourceBeats.some((beat) => !existsSync33(join30(projectDir, `compositions/scene-${beat.id}.html`)));
   const resolved = await resolvePlanProviders({
     projectDir,
     config: config4,
@@ -472190,6 +472860,7 @@ async function createBuildPlan(opts) {
     const backdropPrompt = stringOrUndefined3(cue.backdrop);
     const augmentedBackdropPrompt = backdropPrompt ? augmentBackdropPrompt(backdropPrompt) : null;
     const videoPrompt = stringOrUndefined3(cue.video);
+    const keyframePrompt = stringOrUndefined3(cue.keyframe);
     const musicPrompt = stringOrUndefined3(cue.music);
     const genericReference = resolveGenericAssetReference(projectDir, cue.asset);
     const narrationReference = resolveTypedAssetReference(projectDir, "narration", cue.narration);
@@ -472198,7 +472869,7 @@ async function createBuildPlan(opts) {
     const musicReference = resolveTypedAssetReference(projectDir, "music", cue.music) ?? (!musicPrompt && genericReference?.kind === "music" ? genericReference : null);
     const narrationCue = narrationText ?? narrationReference?.raw;
     const backdropCue = backdropPrompt ?? backdropReference?.raw;
-    const videoCue = videoPrompt ?? videoReference?.raw;
+    const videoCue = videoPrompt ?? videoReference?.raw ?? keyframePrompt;
     const musicCue = musicPrompt ?? musicReference?.raw;
     const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : resolved.narration.resolved === "openai" ? OPENAI_NARRATION_COST_USD : 0;
     const narrationCache = narrationText && !narrationReference ? narrationCacheDescriptor({
@@ -472216,11 +472887,12 @@ async function createBuildPlan(opts) {
       size: imageSize2,
       ratio: imageRatio
     }) : null;
-    const videoCache = videoPrompt && !videoReference ? videoCacheDescriptor({
+    const videoCache = (videoPrompt || keyframePrompt) && !videoReference ? videoCacheDescriptor({
       beatId: beat.id,
-      cue: videoPrompt,
+      cue: videoPrompt ?? keyframePrompt,
       provider: resolved.video.resolved,
-      duration: beat.duration
+      duration: beat.duration,
+      keyframe: keyframePrompt
     }) : null;
     const musicCache = musicPrompt && !musicReference ? musicCacheDescriptor({
       beatId: beat.id,
@@ -472267,7 +472939,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({
@@ -472284,7 +472960,7 @@ async function createBuildPlan(opts) {
       active: includeAssets
     }) : null;
     const compositionPath = `compositions/scene-${beat.id}.html`;
-    const compositionExists = existsSync33(join31(projectDir, compositionPath));
+    const compositionExists = existsSync33(join30(projectDir, compositionPath));
     for (const asset of [narration, backdrop, video, music]) {
       if (!asset) continue;
       if (asset.referenceError) {
@@ -472311,6 +472987,12 @@ async function createBuildPlan(opts) {
     if (backdrop?.willGenerate && isSupportedBuildImageProvider(resolved.image.resolved))
       noteProviderNeed(resolved.image, "Backdrop generation");
     if (video?.willGenerate) noteProviderNeed(resolved.video, "Video generation");
+    if (keyframePrompt && video?.willGenerate) {
+      estimatedCostUsd += backdropCostUsd(imageQuality);
+      providers.add(resolved.image.resolved);
+      if (isSupportedBuildImageProvider(resolved.image.resolved))
+        noteProviderNeed(resolved.image, "Keyframe generation");
+    }
     if (music?.willGenerate) noteProviderNeed(resolved.music, "Music generation");
     if (!compositionExists) missing.add("compositions");
     if (includeCompose && !compositionExists && mode !== "agent") {
@@ -472351,7 +473033,7 @@ async function createBuildPlan(opts) {
     }
   }
   const validationOk = !validationIssues.some((issue) => issue.severity === "error");
-  if (!existsSync33(join31(projectDir, config4.config.composition.entry))) {
+  if (!existsSync33(join30(projectDir, config4.config.composition.entry))) {
     missing.add("root-composition");
     if (validationOk) retryWith.push(`vibe build ${projectDir} --stage sync --json`);
   }
@@ -472378,6 +473060,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(
+        (c2) => referenced.has(c2.name) && c2.prompt && (opts.force || !existsSync33(join30(projectDir, `assets/character-${c2.name}.png`)))
+      );
+      if (toGenerate.length > 0) {
+        estimatedCostUsd += toGenerate.length * backdropCostUsd(opts.imageQuality ?? "hd");
+        missing.add("assets");
+      }
+    }
+  }
   return finalizeBuildPlan({
     projectDir,
     config: config4,
@@ -472483,8 +473180,8 @@ function assetPlan(opts) {
       reason: ready ? "referenced-asset" : "invalid-reference"
     };
   }
-  const canonicalExists = existsSync33(join31(opts.projectDir, opts.path));
-  const cacheHit = opts.cache ? existsSync33(join31(opts.projectDir, opts.cache.path)) : false;
+  const canonicalExists = existsSync33(join30(opts.projectDir, opts.path));
+  const cacheHit = opts.cache ? existsSync33(join30(opts.projectDir, opts.cache.path)) : false;
   const freshness = assetFreshnessFromMetadata({
     projectDir: opts.projectDir,
     kind: opts.kind,
@@ -472681,7 +473378,7 @@ async function firstConfiguredComposer(projectDir) {
 }
 function firstExisting2(projectDir, paths) {
   for (const path14 of paths) {
-    if (existsSync33(join31(projectDir, path14))) return path14;
+    if (existsSync33(join30(projectDir, path14))) return path14;
   }
   return null;
 }
@@ -472722,12 +473419,12 @@ function unique3(items) {
   return [...new Set(items.filter((item) => item.length > 0))];
 }
 function loadPlanEnv(projectDir) {
-  (0, import_dotenv2.config)({ path: join31(projectDir, ".env"), quiet: true });
+  (0, import_dotenv2.config)({ path: join30(projectDir, ".env"), quiet: true });
   (0, import_dotenv2.config)({ path: resolve29(process.cwd(), ".env"), quiet: true });
   let dir = process.cwd();
   while (dir !== dirname17(dir)) {
-    if (existsSync33(join31(dir, "pnpm-workspace.yaml"))) {
-      (0, import_dotenv2.config)({ path: join31(dir, ".env"), quiet: true });
+    if (existsSync33(join30(dir, "pnpm-workspace.yaml"))) {
+      (0, import_dotenv2.config)({ path: join30(dir, ".env"), quiet: true });
       return;
     }
     dir = dirname17(dir);
@@ -472742,6 +473439,7 @@ var init_build_plan = __esm({
     init_schema();
     init_build_asset_reference();
     init_build_cache();
+    init_dist();
     init_build_asset_metadata();
     init_build_backdrop_prompt();
     init_composer_resolve();
@@ -473074,9 +473772,9 @@ __export(scene_build_exports, {
   executeSceneBuild: () => executeSceneBuild,
   resolveSceneBuildMode: () => resolveSceneBuildMode
 });
-import { existsSync as existsSync35 } from "node:fs";
+import { existsSync as existsSync35, readFileSync as readFileSync12 } from "node:fs";
 import { copyFile as copyFile4, mkdir as mkdir13, readFile as readFile18, writeFile as writeFile20 } from "node:fs/promises";
-import { dirname as dirname18, join as join33, resolve as resolve33 } from "node:path";
+import { dirname as dirname18, join as join31, resolve as resolve33 } from "node:path";
 async function executeSceneBuild(opts) {
   const startedAt = Date.now();
   const projectDir = resolve33(opts.projectDir);
@@ -473088,7 +473786,7 @@ async function executeSceneBuild(opts) {
   const warnings = [];
   const retryWith = [];
   let sceneRepair = skippedSceneRepairSummary();
-  const storyboardPath = join33(projectDir, "STORYBOARD.md");
+  const storyboardPath = join31(projectDir, "STORYBOARD.md");
   const buildPlan = await createBuildPlan({
     projectDir,
     stage: selectedStage,
@@ -473241,8 +473939,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((c2) => referenced.has(c2.name)),
+          {
+            projectDir,
+            imageProvider,
+            imageSize: opts.imageSize ?? "1536x1024",
+            imageQuality: opts.imageQuality ?? "hd",
+            force: opts.force ?? false,
+            onProgress
+          }
+        );
+        for (const [name, path14] of charResult.paths) characterPaths.set(name, path14);
+        characterCostUsd = charResult.costUsd;
+        warnings.push(...charResult.failures);
+      }
+    }
     const primitiveResults = await mapWithConcurrency(
       activeBeats,
       BEAT_PRIMITIVES_CONCURRENCY,
@@ -473260,7 +473982,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);
@@ -473269,10 +473992,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`
     );
@@ -473348,9 +474068,9 @@ async function executeSceneBuild(opts) {
   let composeData;
   if (shouldRunStage(selectedStage, "compose")) {
     if (mode === "agent") {
-      const compositionsDir = join33(projectDir, "compositions");
+      const compositionsDir = join31(projectDir, "compositions");
       const missingBeats = activeBeats.filter(
-        (b2) => !existsSync35(join33(compositionsDir, `scene-${b2.id}.html`))
+        (b2) => !existsSync35(join31(compositionsDir, `scene-${b2.id}.html`))
       );
       if (missingBeats.length > 0) {
         const plan = await getComposePrompts({ projectDir, beatId: opts.beatId });
@@ -473437,6 +474157,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 = join31(projectDir, "compositions", `scene-${beat.id}.html`);
+      if (!existsSync35(join31(projectDir, videoRel)) || !existsSync35(compositionAbs)) continue;
+      const html = readFileSync12(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);
@@ -473486,7 +474218,7 @@ async function executeSceneBuild(opts) {
     });
   }
   if (shouldRunStage(selectedStage, "sync")) {
-    if (!existsSync35(join33(projectDir, "index.html"))) {
+    if (!existsSync35(join31(projectDir, "index.html"))) {
       await scaffoldSceneProject({
         dir: projectDir,
         name: projectDir.split(/[\\/]/).filter(Boolean).pop(),
@@ -473671,6 +474403,8 @@ async function buildBeatPrimitives(beat, ctx) {
       videoMetadataPath: video.metadataPath,
       videoFreshness: video.freshness,
       videoSourcePath: video.sourcePath,
+      keyframeStatus: video.keyframeStatus,
+      keyframePath: video.keyframePath,
       musicStatus: music.status,
       musicPath: music.path,
       musicJobId: music.job?.id,
@@ -473745,7 +474479,7 @@ async function dispatchNarration(beat, ctx) {
       return {
         status: "cached",
         path: existingRel,
-        durationSec: await safeAudioDuration(join33(ctx.projectDir, existingRel)),
+        durationSec: await safeAudioDuration(join31(ctx.projectDir, existingRel)),
         provider: metadata?.provider,
         cachePath: metadata?.cachePath,
         cacheKey: metadata?.cacheKey,
@@ -473769,9 +474503,9 @@ async function dispatchNarration(beat, ctx) {
     voice,
     ext: resolution.audioExtension
   });
-  const cacheAbs = join33(ctx.projectDir, cache.path);
+  const cacheAbs = join31(ctx.projectDir, cache.path);
   const rel = `assets/narration-${beat.id}.${resolution.audioExtension}`;
-  const abs = join33(ctx.projectDir, rel);
+  const abs = join31(ctx.projectDir, rel);
   if (existingRel && !ctx.force && isFreshCanonicalAsset({
     projectDir: ctx.projectDir,
     kind: "narration",
@@ -473785,7 +474519,7 @@ async function dispatchNarration(beat, ctx) {
     return {
       status: "cached",
       path: existingRel,
-      durationSec: await safeAudioDuration(join33(ctx.projectDir, existingRel)),
+      durationSec: await safeAudioDuration(join31(ctx.projectDir, existingRel)),
       provider: resolution.provider,
       cachePath: cache.path,
       cacheKey: cache.key,
@@ -473857,6 +474591,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 (existsSync35(join31(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 = join31(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 (existsSync35(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 = join31(ctx.projectDir, cache.path);
+    if (existsSync35(cacheAbs) && !ctx.force) {
+      await mkdir13(dirname18(abs), { recursive: true });
+      await copyFile4(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 mkdir13(dirname18(abs), { recursive: true });
+    await writeFile20(abs, generated.buffer);
+    await mkdir13(dirname18(cacheAbs), { recursive: true });
+    await writeFile20(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);
@@ -473864,7 +474712,7 @@ async function dispatchBackdrop(beat, ctx) {
   if (!cue) return { status: "no-cue" };
   const prompt3 = augmentBackdropPrompt(cue);
   const rel = `assets/backdrop-${beat.id}.png`;
-  const abs = join33(ctx.projectDir, rel);
+  const abs = join31(ctx.projectDir, rel);
   const size = ctx.imageSize ?? "1536x1024";
   const ratio = imageRatioForSize(size);
   const metadataOptions = { quality: ctx.imageQuality, size, ratio };
@@ -473900,7 +474748,7 @@ async function dispatchBackdrop(beat, ctx) {
       };
     }
   }
-  const cacheAbs = join33(ctx.projectDir, cache.path);
+  const cacheAbs = join31(ctx.projectDir, cache.path);
   if (existsSync35(cacheAbs) && !ctx.force) {
     await mkdir13(dirname18(abs), { recursive: true });
     await copyFile4(cacheAbs, abs);
@@ -474001,6 +474849,112 @@ async function generateBackdropImage(prompt3, ctx, ratio) {
   });
   return imageBufferFromResult(result);
 }
+async function editKeyframeImage(prompt3, sheetBuffers, ctx, ratio) {
+  loadSceneBuildEnv(ctx.projectDir);
+  const keyInfo = imageProviderKeyInfo(ctx.imageProvider);
+  const apiKey = await getApiKeyFromConfig(keyInfo.configKey, { cwd: ctx.projectDir }) ?? process.env[keyInfo.envVar] ?? "";
+  if (!apiKey) {
+    return {
+      success: false,
+      error: `${keyInfo.envVar} not set \u2014 cannot generate keyframe with ${ctx.imageProvider}`
+    };
+  }
+  if (ctx.imageProvider === "openai") {
+    const provider2 = new OpenAIImageProvider();
+    await provider2.initialize({ apiKey });
+    const result2 = await provider2.editImage(sheetBuffers, prompt3);
+    return imageBufferFromResult(result2);
+  }
+  if (ctx.imageProvider === "gemini") {
+    const provider2 = new GeminiProvider();
+    await provider2.initialize({ apiKey });
+    const result2 = await provider2.editImage(sheetBuffers, prompt3, {
+      model: "flash",
+      aspectRatio: ratio
+    });
+    return imageBufferFromResult(result2);
+  }
+  const provider = new GrokProvider();
+  await provider.initialize({ apiKey });
+  const result = await provider.editImage(sheetBuffers[0], prompt3, { aspectRatio: ratio });
+  return imageBufferFromResult(result);
+}
+async function ensureKeyframe(beat, ctx, keyframeCue, characterRefsRel) {
+  const rel = `assets/keyframe-${beat.id}.png`;
+  const abs = join31(ctx.projectDir, rel);
+  const size = ctx.imageSize ?? "1536x1024";
+  const ratio = imageRatioForSize(size);
+  const metadataOptions = { quality: ctx.imageQuality, size, ratio };
+  const cache = keyframeCacheDescriptor({
+    beatId: beat.id,
+    cue: keyframeCue,
+    provider: ctx.imageProvider,
+    quality: ctx.imageQuality,
+    size,
+    ratio,
+    characters: characterRefsRel
+  });
+  if (existsSync35(abs) && !ctx.force) {
+    const metadata = readAssetMetadata(ctx.projectDir, "keyframe", beat.id);
+    if (!metadata || isFreshCanonicalAsset({
+      projectDir: ctx.projectDir,
+      kind: "keyframe",
+      beatId: beat.id,
+      cue: keyframeCue,
+      provider: ctx.imageProvider,
+      options: metadataOptions,
+      cacheKey: cache.key
+    })) {
+      return { status: "cached", rel };
+    }
+  }
+  const cacheAbs = join31(ctx.projectDir, cache.path);
+  if (existsSync35(cacheAbs) && !ctx.force) {
+    await mkdir13(dirname18(abs), { recursive: true });
+    await copyFile4(cacheAbs, abs);
+    await writeAssetMetadata({
+      projectDir: ctx.projectDir,
+      kind: "keyframe",
+      beatId: beat.id,
+      cue: keyframeCue,
+      provider: ctx.imageProvider,
+      options: metadataOptions,
+      cacheKey: cache.key,
+      canonicalPath: rel,
+      cachePath: cache.path
+    });
+    return { status: "cached", rel };
+  }
+  const sheetBuffers = [];
+  for (const relPath of characterRefsRel) {
+    const sheetAbs = join31(ctx.projectDir, relPath);
+    if (existsSync35(sheetAbs)) sheetBuffers.push(await readFile18(sheetAbs));
+  }
+  const imgCtx = {
+    projectDir: ctx.projectDir,
+    imageProvider: ctx.imageProvider,
+    imageSize: size,
+    imageQuality: ctx.imageQuality
+  };
+  const generated = sheetBuffers.length > 0 ? await editKeyframeImage(keyframeCue, sheetBuffers, imgCtx, ratio) : await generateBackdropImage(keyframeCue, imgCtx, ratio);
+  if (!generated.success) return { status: "failed", error: generated.error };
+  await mkdir13(dirname18(abs), { recursive: true });
+  await writeFile20(abs, generated.buffer);
+  await mkdir13(dirname18(cacheAbs), { recursive: true });
+  await writeFile20(cacheAbs, generated.buffer);
+  await writeAssetMetadata({
+    projectDir: ctx.projectDir,
+    kind: "keyframe",
+    beatId: beat.id,
+    cue: keyframeCue,
+    provider: ctx.imageProvider,
+    options: metadataOptions,
+    cacheKey: cache.key,
+    canonicalPath: rel,
+    cachePath: cache.path
+  });
+  return { status: "generated", rel };
+}
 async function imageBufferFromResult(result) {
   const image = result.images?.[0];
   if (!result.success || !image) {
@@ -474024,15 +474978,22 @@ function imageProviderKeyInfo(provider) {
 async function dispatchVideo(beat, ctx) {
   const reference = assetReferenceForBeat(ctx.projectDir, "video", beat);
   if (reference) return referencePrimitiveOutcome("video", beat, ctx, reference);
-  const prompt3 = stringOrUndefined4(beat.cues?.video);
+  const keyframeCue = stringOrUndefined4(beat.cues?.keyframe);
+  const prompt3 = stringOrUndefined4(beat.cues?.video) ?? keyframeCue;
   if (!prompt3) return { status: "no-cue" };
+  const characterRefsRel = beatCharacterNames(beat.cues).map((name) => ctx.characterPaths?.get(name)).filter((p2) => typeof p2 === "string");
+  const characterRefsAbs = characterRefsRel.map((p2) => join31(ctx.projectDir, p2));
   const rel = `assets/video-${beat.id}.mp4`;
-  const abs = join33(ctx.projectDir, rel);
+  const abs = join31(ctx.projectDir, rel);
   const cache = videoCacheDescriptor({
     beatId: beat.id,
     cue: prompt3,
     provider: ctx.videoProvider,
-    duration: normalizeVideoDuration(beat.duration)
+    duration: normalizeVideoDuration(beat.duration),
+    // Keyframe mode keys the clip to the keyframe prompt; refs feed the keyframe,
+    // not the clip directly.
+    characters: keyframeCue ? void 0 : characterRefsRel,
+    keyframe: keyframeCue
   });
   const metadataPath = assetMetadataPath("video", beat.id);
   if (existsSync35(abs) && !ctx.force) {
@@ -474058,7 +475019,7 @@ async function dispatchVideo(beat, ctx) {
       };
     }
   }
-  const cacheAbs = join33(ctx.projectDir, cache.path);
+  const cacheAbs = join31(ctx.projectDir, cache.path);
   if (existsSync35(cacheAbs) && !ctx.force) {
     await mkdir13(dirname18(abs), { recursive: true });
     await copyFile4(cacheAbs, abs);
@@ -474085,6 +475046,19 @@ async function dispatchVideo(beat, ctx) {
     };
   }
   loadSceneBuildEnv(ctx.projectDir);
+  let keyframeStatus;
+  let keyframeRel;
+  let keyframeImageAbs;
+  if (keyframeCue) {
+    const kf = await ensureKeyframe(beat, ctx, keyframeCue, characterRefsRel);
+    if (kf.status === "failed") {
+      ctx.onProgress({ type: "video-failed", beatId: beat.id, error: kf.error });
+      return { status: "failed", error: kf.error };
+    }
+    keyframeStatus = kf.status;
+    keyframeRel = kf.rel;
+    keyframeImageAbs = join31(ctx.projectDir, kf.rel);
+  }
   const result = await executeVideoGenerate({
     prompt: prompt3,
     provider: ctx.videoProvider,
@@ -474092,6 +475066,10 @@ async function dispatchVideo(beat, ctx) {
     ratio: "16:9",
     output: abs,
     wait: false,
+    // Keyframe mode → single init frame (image-to-video); otherwise character
+    // reference-to-video.
+    image: keyframeImageAbs,
+    refImages: keyframeImageAbs ? void 0 : characterRefsAbs.length > 0 ? characterRefsAbs : void 0,
     apiKey: await apiKeyForVideoProvider(ctx.videoProvider, ctx.projectDir)
   });
   if (!result.success || !result.taskId) {
@@ -474126,14 +475104,16 @@ async function dispatchVideo(beat, ctx) {
       cachePath: cache.path,
       cacheKey: cache.key,
       metadataPath,
-      freshness: "fresh"
+      freshness: "fresh",
+      keyframeStatus,
+      keyframePath: keyframeRel
     };
   }
   const job = await createAndWriteJobRecord({
     jobType: "generate-video",
     provider: result.provider ?? ctx.videoProvider,
     providerTaskId: result.taskId,
-    providerTaskType: "text2video",
+    providerTaskType: keyframeImageAbs ? "image2video" : "text2video",
     status: "running",
     projectDir: ctx.projectDir,
     workingDirectory: ctx.projectDir,
@@ -474158,7 +475138,9 @@ async function dispatchVideo(beat, ctx) {
     provider: job.provider,
     cachePath: cache.path,
     cacheKey: cache.key,
-    metadataPath
+    metadataPath,
+    keyframeStatus,
+    keyframePath: keyframeRel
   };
 }
 async function dispatchMusic(beat, ctx) {
@@ -474167,7 +475149,7 @@ async function dispatchMusic(beat, ctx) {
   const prompt3 = stringOrUndefined4(beat.cues?.music);
   if (!prompt3) return { status: "no-cue" };
   const rel = `assets/music-${beat.id}.mp3`;
-  const abs = join33(ctx.projectDir, rel);
+  const abs = join31(ctx.projectDir, rel);
   const duration = normalizeMusicDuration(beat.duration);
   const cache = musicCacheDescriptor({
     beatId: beat.id,
@@ -474200,7 +475182,7 @@ async function dispatchMusic(beat, ctx) {
       };
     }
   }
-  const cacheAbs = join33(ctx.projectDir, cache.path);
+  const cacheAbs = join31(ctx.projectDir, cache.path);
   if (existsSync35(cacheAbs) && !ctx.force) {
     await mkdir13(dirname18(abs), { recursive: true });
     await copyFile4(cacheAbs, abs);
@@ -474311,12 +475293,12 @@ async function dispatchMusic(beat, ctx) {
   };
 }
 function loadSceneBuildEnv(projectDir) {
-  (0, import_dotenv3.config)({ path: join33(projectDir, ".env"), quiet: true });
+  (0, import_dotenv3.config)({ path: join31(projectDir, ".env"), quiet: true });
   (0, import_dotenv3.config)({ path: resolve33(process.cwd(), ".env"), quiet: true });
   let dir = process.cwd();
   while (dir !== dirname18(dir)) {
-    if (existsSync35(join33(dir, "pnpm-workspace.yaml"))) {
-      (0, import_dotenv3.config)({ path: join33(dir, ".env"), quiet: true });
+    if (existsSync35(join31(dir, "pnpm-workspace.yaml"))) {
+      (0, import_dotenv3.config)({ path: join31(dir, ".env"), quiet: true });
       return;
     }
     dir = dirname18(dir);
@@ -474460,7 +475442,14 @@ 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.keyframeStatus === "generated") cost += backdropCostUsd(imageQuality);
+    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));
@@ -474525,7 +475514,7 @@ function mergeBeatOutcomes(base, updates) {
 }
 function firstExisting3(projectDir, relPaths) {
   for (const rel of relPaths) {
-    if (existsSync35(join33(projectDir, rel))) return rel;
+    if (existsSync35(join31(projectDir, rel))) return rel;
   }
   return null;
 }
@@ -474556,7 +475545,7 @@ async function apiKeyForVideoProvider(provider, projectDir) {
   return getApiKeyFromConfig(providerKey, { cwd: projectDir });
 }
 async function finalizeBuildResult(projectDir, startedAt, result) {
-  const reportPath = join33(projectDir, "build-report.json");
+  const reportPath = join31(projectDir, "build-report.json");
   if (result.stageReports) {
     for (const report of Object.values(result.stageReports)) {
       if (report.status === "pending") report.status = "skipped";
@@ -474715,7 +475704,7 @@ function normalizeReportDuration(value) {
 }
 function buildReportComposition(projectDir, result, beatId) {
   const path14 = `compositions/scene-${beatId}.html`;
-  const exists = existsSync35(join33(projectDir, path14));
+  const exists = existsSync35(join31(projectDir, path14));
   const written = composeWrittenEntry(result, beatId);
   if (written) {
     return {
@@ -474772,7 +475761,7 @@ function summarizeBuildBeats(projectDir, beats) {
   let compositionsReady = 0;
   for (const beat of beats) {
     if (beatAssetsReady(beat)) assetsReady += 1;
-    const compositionPath = join33(projectDir, "compositions", `scene-${beat.beatId}.html`);
+    const compositionPath = join31(projectDir, "compositions", `scene-${beat.beatId}.html`);
     if (existsSync35(compositionPath)) {
       compositionsReady += 1;
     } else {
@@ -475428,7 +476417,7 @@ var init_silence_cut = __esm({
 // ../cli/src/commands/_shared/edit/jump-cut.ts
 import { existsSync as existsSync38 } from "node:fs";
 import { readFile as readFile21, writeFile as writeFile22, mkdir as mkdir14 } from "node:fs/promises";
-import { join as join34 } from "node:path";
+import { join as join33 } from "node:path";
 async function transcribeWithWords(audioPath, apiKey, language) {
   const audioBuffer = await readFile21(audioPath);
   const audioBlob = new Blob([audioBuffer]);
@@ -475508,7 +476497,7 @@ async function executeJumpCut(options) {
   try {
     const tmpDir = `/tmp/vibe_jumpcut_${Date.now()}`;
     await mkdir14(tmpDir, { recursive: true });
-    const audioPath = join34(tmpDir, "audio.wav");
+    const audioPath = join33(tmpDir, "audio.wav");
     try {
       await execSafe(
         "ffmpeg",
@@ -475562,7 +476551,7 @@ async function executeJumpCut(options) {
       const segmentPaths = [];
       for (let i2 = 0; i2 < segments.length; i2++) {
         const seg = segments[i2];
-        const segPath = join34(tmpDir, `seg-${i2.toString().padStart(4, "0")}.ts`);
+        const segPath = join33(tmpDir, `seg-${i2.toString().padStart(4, "0")}.ts`);
         const duration = seg.end - seg.start;
         await execSafe(
           "ffmpeg",
@@ -475585,7 +476574,7 @@ async function executeJumpCut(options) {
         segmentPaths.push(segPath);
       }
       const concatList = segmentPaths.map((p2) => `file '${p2}'`).join("\n");
-      const listPath = join34(tmpDir, "concat.txt");
+      const listPath = join33(tmpDir, "concat.txt");
       await writeFile22(listPath, concatList);
       await execSafe(
         "ffmpeg",
@@ -475693,7 +476682,7 @@ __export(remotion_exports, {
 });
 import { writeFile as writeFile23, mkdir as mkdir15, rm as rm3, copyFile as copyFile5 } from "node:fs/promises";
 import { existsSync as existsSync39 } from "node:fs";
-import { join as join35 } from "node:path";
+import { join as join34 } from "node:path";
 import { tmpdir as tmpdir3 } from "node:os";
 import { createHash as createHash7 } from "node:crypto";
 async function ensureRemotionInstalled() {
@@ -475712,7 +476701,7 @@ async function ensureRemotionInstalled() {
   }
 }
 async function scaffoldRemotionProject(componentCode, componentName, opts) {
-  const dir = join35(tmpdir3(), `vibe_motion_${Date.now()}`);
+  const dir = join34(tmpdir3(), `vibe_motion_${Date.now()}`);
   await mkdir15(dir, { recursive: true });
   const deps = {
     remotion: REMOTION_VERSION,
@@ -475731,7 +476720,7 @@ async function scaffoldRemotionProject(componentCode, componentName, opts) {
     dependencies: deps
   };
   const packageJsonStr = JSON.stringify(packageJson, null, 2);
-  await writeFile23(join35(dir, "package.json"), packageJsonStr);
+  await writeFile23(join34(dir, "package.json"), packageJsonStr);
   const tsconfig = {
     compilerOptions: {
       target: "ES2020",
@@ -475743,8 +476732,8 @@ async function scaffoldRemotionProject(componentCode, componentName, opts) {
       skipLibCheck: true
     }
   };
-  await writeFile23(join35(dir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2));
-  await writeFile23(join35(dir, "Component.tsx"), componentCode);
+  await writeFile23(join34(dir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2));
+  await writeFile23(join34(dir, "Component.tsx"), componentCode);
   const rootCode = `import { registerRoot, Composition } from "remotion";
 import { ${componentName} } from "./Component";
 
@@ -475763,14 +476752,14 @@ const Root = () => {
 
 registerRoot(Root);
 `;
-  await writeFile23(join35(dir, "Root.tsx"), rootCode);
+  await writeFile23(join34(dir, "Root.tsx"), rootCode);
   const depsHash = createHash7("md5").update(packageJsonStr).digest("hex").slice(0, 12);
-  const cacheMarker = join35(REMOTION_CACHE_DIR, `.deps-${depsHash}`);
-  const cachedModules = join35(REMOTION_CACHE_DIR, "node_modules");
+  const cacheMarker = join34(REMOTION_CACHE_DIR, `.deps-${depsHash}`);
+  const cachedModules = join34(REMOTION_CACHE_DIR, "node_modules");
   if (existsSync39(cacheMarker) && existsSync39(cachedModules)) {
     const { symlink } = await import("node:fs/promises");
     try {
-      await symlink(cachedModules, join35(dir, "node_modules"), "dir");
+      await symlink(cachedModules, join34(dir, "node_modules"), "dir");
     } catch {
       await this_npmInstall(dir);
     }
@@ -475778,12 +476767,12 @@ registerRoot(Root);
     await this_npmInstall(dir);
     try {
       await mkdir15(REMOTION_CACHE_DIR, { recursive: true });
-      await writeFile23(join35(REMOTION_CACHE_DIR, "package.json"), packageJsonStr);
-      if (existsSync39(join35(dir, "node_modules"))) {
+      await writeFile23(join34(REMOTION_CACHE_DIR, "package.json"), packageJsonStr);
+      if (existsSync39(join34(dir, "node_modules"))) {
         const { rename: rename7, symlink } = await import("node:fs/promises");
-        await rename7(join35(dir, "node_modules"), cachedModules).catch(() => {
+        await rename7(join34(dir, "node_modules"), cachedModules).catch(() => {
         });
-        await symlink(cachedModules, join35(dir, "node_modules"), "dir").catch(() => {
+        await symlink(cachedModules, join34(dir, "node_modules"), "dir").catch(() => {
         });
         await writeFile23(cacheMarker, depsHash);
       }
@@ -475820,7 +476809,7 @@ async function renderMotion(options) {
     }
   );
   try {
-    const entryPoint = join35(dir, "Root.tsx");
+    const entryPoint = join34(dir, "Root.tsx");
     const { execFile: execFile3 } = await import("node:child_process");
     const { promisify: promisify3 } = await import("node:util");
     const execFileAsync3 = promisify3(execFile3);
@@ -475953,10 +476942,10 @@ async function renderWithEmbeddedImage(options) {
     }
   );
   try {
-    const publicDir = join35(dir, "public");
+    const publicDir = join34(dir, "public");
     await mkdir15(publicDir, { recursive: true });
-    await copyFile5(options.imagePath, join35(publicDir, options.imageFileName));
-    const entryPoint = join35(dir, "Root.tsx");
+    await copyFile5(options.imagePath, join34(publicDir, options.imageFileName));
+    const entryPoint = join34(dir, "Root.tsx");
     const mp4Out = options.outputPath.replace(/\.\w+$/, ".mp4");
     const { execFile: execFileImg } = await import("node:child_process");
     const { promisify: promisifyImg } = await import("node:util");
@@ -476017,10 +477006,10 @@ async function renderWithEmbeddedVideo(options) {
     }
   );
   try {
-    const publicDir = join35(dir, "public");
+    const publicDir = join34(dir, "public");
     await mkdir15(publicDir, { recursive: true });
-    await copyFile5(options.videoPath, join35(publicDir, options.videoFileName));
-    const entryPoint = join35(dir, "Root.tsx");
+    await copyFile5(options.videoPath, join34(publicDir, options.videoFileName));
+    const entryPoint = join34(dir, "Root.tsx");
     const mp4VideoOnly = options.outputPath.replace(/\.\w+$/, "_video_only.mp4");
     const { execFile: execFileVid } = await import("node:child_process");
     const { promisify: promisifyVid } = await import("node:util");
@@ -476436,14 +477425,14 @@ var init_remotion = __esm({
     "use strict";
     init_exec_safe();
     REMOTION_VERSION = "4.0.447";
-    REMOTION_CACHE_DIR = join35(tmpdir3(), "vibe_remotion_cache");
+    REMOTION_CACHE_DIR = join34(tmpdir3(), "vibe_remotion_cache");
   }
 });
 
 // ../cli/src/commands/_shared/edit/caption.ts
 import { existsSync as existsSync40 } from "node:fs";
 import { readFile as readFile22, writeFile as writeFile24, mkdir as mkdir16 } from "node:fs/promises";
-import { dirname as dirname20, basename as basename9, extname as extname7, join as join36 } from "node:path";
+import { dirname as dirname20, basename as basename9, extname as extname7, join as join35 } from "node:path";
 function getCaptionForceStyle(style, fontSize, fontColor, position) {
   const alignment = position === "top" ? 8 : position === "center" ? 5 : 2;
   const marginV = position === "center" ? 0 : 30;
@@ -476490,8 +477479,8 @@ async function executeCaption(options) {
   try {
     const tmpDir = `/tmp/vibe_caption_${Date.now()}`;
     await mkdir16(tmpDir, { recursive: true });
-    const audioPath = join36(tmpDir, "audio.wav");
-    const srtPath = join36(tmpDir, "captions.srt");
+    const audioPath = join35(tmpDir, "audio.wav");
+    const srtPath = join35(tmpDir, "captions.srt");
     try {
       await execSafe(
         "ffmpeg",
@@ -476560,7 +477549,7 @@ async function executeCaption(options) {
         const remotionErr = await ensureRemotionInstalled2();
         if (remotionErr) {
           const outputDir2 = dirname20(outputPath);
-          const outputSrtPath2 = join36(
+          const outputSrtPath2 = join35(
             outputDir2,
             basename9(outputPath, extname7(outputPath)) + ".srt"
           );
@@ -476599,7 +477588,7 @@ SRT saved to: ${outputSrtPath2}` };
         });
         if (!renderResult.success) {
           const outputDir2 = dirname20(outputPath);
-          const outputSrtPath2 = join36(
+          const outputSrtPath2 = join35(
             outputDir2,
             basename9(outputPath, extname7(outputPath)) + ".srt"
           );
@@ -476612,7 +477601,7 @@ SRT saved to: ${outputSrtPath2}`
         }
       }
       const outputDir = dirname20(outputPath);
-      const outputSrtPath = join36(
+      const outputSrtPath = join35(
         outputDir,
         basename9(outputPath, extname7(outputPath)) + ".srt"
       );
@@ -484580,10 +485569,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,
@@ -487033,6 +488030,9 @@ function clean(text) {
 function humanise(id) {
   return id.split(/[-_]+/).filter(Boolean).map((w2) => w2.charAt(0).toUpperCase() + w2.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, "");
@@ -487070,10 +488070,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(input3) {
   const id = input3.id;
   const scope = `[data-composition-id="${id}"]`;
-  const headline = clean(input3.headline) || humanise(id);
+  const displayId = input3.beatId ?? id;
+  const headline = clean(input3.headline) || humanise(displayId);
   const subhead = clean(input3.subhead);
   const kicker = clean(input3.kicker);
   const dur = input3.duration;
@@ -487096,8 +488102,17 @@ function buildPreset(input3) {
         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 (input3.preset) {
     case "simple": {
       const transcript = input3.transcript;
@@ -487129,7 +488144,7 @@ function buildPreset(input3) {
         body: `${backdropMarkup}
     <div class="caption" id="caption">${captionInner}</div>`,
         timeline: `${crossfadeTweens(scope, dur)}
-      ${kenBurnsTween(scope, dur)}
+      ${backdropMotionTweens(scope, dur, hasImage)}
       ${captionTween}`
       };
     }
@@ -487168,12 +488183,12 @@ function buildPreset(input3) {
         // 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 k2 = kicker || humanise(id).toUpperCase();
+      const k2 = kicker || humanise(displayId).toUpperCase();
       const sub = subhead || "";
       const transcript = input3.transcript;
       const useWordSync = !!(transcript && transcript.length > 0 && sub);
@@ -487215,7 +488230,7 @@ function buildPreset(input3) {
       <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}`
@@ -487256,12 +488271,12 @@ function buildPreset(input3) {
         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} {
@@ -487295,7 +488310,7 @@ function buildPreset(input3) {
     <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);` : ""}`
@@ -487360,9 +488375,10 @@ function emitSceneHtml(input3) {
   if (input3.width <= 0 || input3.height <= 0) {
     throw new Error(`Invalid canvas dims: ${input3.width}x${input3.height}`);
   }
-  const id = input3.id;
+  const beatId = input3.id;
+  const id = sceneCompositionId(beatId);
   const dur = Number(input3.duration.toFixed(3));
-  const parts = buildPreset({ ...input3, id, duration: dur });
+  const parts = buildPreset({ ...input3, id, beatId, duration: dur });
   const audioBlock = input3.audioPath ? `
     <audio
       id="narration"
@@ -487378,7 +488394,7 @@ function emitSceneHtml(input3) {
     ${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="${input3.width}" data-height="${input3.height}">
     <style>
       ${parts.css}
@@ -487414,8 +488430,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);
@@ -487459,9 +488476,9 @@ init_agent_host_detect();
 // ../cli/src/commands/_shared/install-skill.ts
 init_bundle_content();
 init_bundle();
-import { mkdir as mkdir8, writeFile as writeFile11 } from "node:fs/promises";
+import { mkdir as mkdir8, writeFile as writeFile12 } from "node:fs/promises";
 import { existsSync as existsSync21 } from "node:fs";
-import { dirname as dirname12, join as join21, relative as relative5, resolve as resolve15 } from "node:path";
+import { dirname as dirname12, join as join21, relative as relative5, resolve as resolve16 } from "node:path";
 function universalFiles() {
   return [
     { relPath: "SKILL.md", content: SKILL_MD },
@@ -487511,7 +488528,7 @@ function selectHostFiles(hosts) {
   return out;
 }
 async function installHyperframesSkill(opts) {
-  const projectDir = resolve15(opts.projectDir);
+  const projectDir = resolve16(opts.projectDir);
   const force = opts.force ?? false;
   const dryRun = opts.dryRun ?? false;
   const files = [...universalFiles(), ...selectHostFiles(opts.hosts)];
@@ -487536,7 +488553,7 @@ async function installHyperframesSkill(opts) {
       continue;
     }
     await mkdir8(dirname12(absPath), { recursive: true });
-    await writeFile11(absPath, file.content, "utf-8");
+    await writeFile12(absPath, file.content, "utf-8");
     actions.push({ path: file.relPath, status: "wrote", bytes });
   }
   return {
@@ -487561,10 +488578,10 @@ init_scene_lint();
 init_storyboard_parse();
 init_root_sync();
 import { existsSync as existsSync26 } from "node:fs";
-import { mkdir as mkdir10, readFile as readFile11, writeFile as writeFile14 } from "node:fs/promises";
-import { join as join26, resolve as resolve19 } from "node:path";
+import { mkdir as mkdir10, readFile as readFile11, writeFile as writeFile15 } from "node:fs/promises";
+import { join as join26, resolve as resolve20 } from "node:path";
 async function executeSceneSubmit(opts) {
-  const projectDir = resolve19(opts.projectDir);
+  const projectDir = resolve20(opts.projectDir);
   const beatId = opts.beatId.trim();
   const scenePath = `compositions/scene-${beatId}.html`;
   const base = {
@@ -487656,7 +488673,7 @@ async function executeSceneSubmit(opts) {
   }
   const absPath = join26(projectDir, scenePath);
   await mkdir10(join26(projectDir, "compositions"), { recursive: true });
-  await writeFile14(absPath, html.endsWith("\n") ? html : `${html}
+  await writeFile15(absPath, html.endsWith("\n") ? html : `${html}
 `, "utf-8");
   return {
     ...base,
@@ -487671,6 +488688,8 @@ async function executeSceneSubmit(opts) {
 
 // ../cli/src/commands/scene.ts
 init_scene_repair();
+init_root_sync();
+init_storyboard_edit();
 function validateDuration(value) {
   const n2 = parseFloat(value);
   if (!Number.isFinite(n2) || n2 <= 0 || n2 > 3600) {
@@ -487973,7 +488992,10 @@ sceneCommand.command("add").description("Add a new scene to a project: AI narrat
 ).option("-d, --duration <sec>", "Explicit scene duration in seconds (overrides narration audio)").option(
   "--visuals <prompt>",
   "Image prompt \u2014 generates assets/scene-<id>.png via the configured image provider"
-).option("--headline <text>", "Visible headline (defaults to the humanised scene name)").option("--kicker <text>", "Small label above the headline (explainer / product-shot)").option("--insert-into <path>", "Root composition file to update", "index.html").option("--project <dir>", "Project directory", ".").option("--image-provider <name>", "Image provider: gemini, openai", "gemini").option(
+).option("--headline <text>", "Visible headline (defaults to the humanised scene name)").option("--kicker <text>", "Small label above the headline (explainer / product-shot)").option("--insert-into <path>", "Root composition file to update", "index.html").option("--project <dir>", "Project directory", ".").option(
+  "--no-storyboard",
+  "Do not sync STORYBOARD.md; insert this scene directly into the root composition only"
+).option("--image-provider <name>", "Image provider: gemini, openai", "gemini").option(
   "--tts <provider>",
   "TTS provider: auto, elevenlabs, openai, kokoro (default auto \u2014 ElevenLabs key > OpenAI key > Kokoro local)",
   "auto"
@@ -488042,6 +489064,7 @@ sceneCommand.command("add").description("Add a new scene to a project: AI narrat
           kicker: options.kicker,
           project: options.project,
           insertInto: options.insertInto,
+          syncStoryboard: options.storyboard !== false,
           imageProvider: options.imageProvider,
           tts,
           audio: options.audio,
@@ -488069,6 +489092,7 @@ sceneCommand.command("add").description("Add a new scene to a project: AI narrat
       kicker: options.kicker,
       projectDir: options.project,
       insertInto: options.insertInto,
+      syncStoryboard: options.storyboard !== false,
       imageProvider: options.imageProvider,
       tts,
       voice: options.voice,
@@ -488108,6 +489132,13 @@ sceneCommand.command("add").description("Add a new scene to a project: AI narrat
     if (result.audioPath) console.log(source_default.green("  +"), result.audioPath);
     if (result.imagePath) console.log(source_default.green("  +"), result.imagePath);
     if (result.transcriptPath) console.log(source_default.green("  +"), result.transcriptPath);
+    if (result.storyboardPath && result.storyboardSynced) {
+      console.log(
+        result.storyboardAction === "updated" ? source_default.yellow("  ~") : source_default.green("  +"),
+        result.storyboardPath,
+        source_default.dim(`(${result.storyboardAction})`)
+      );
+    }
     console.log(source_default.yellow("  ~"), result.rootPath, source_default.dim("(updated)"));
     console.log();
     console.log(source_default.bold.cyan("Composition"));
@@ -488154,6 +489185,21 @@ async function loadVibeProjectConfig(projectDir) {
     }
   };
 }
+function escapeRegExp3(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function readClipStart(rootHtml, beatId) {
+  const compositionId = sceneCompositionId(beatId);
+  const match2 = rootHtml.match(
+    new RegExp(
+      `<div\\s+class="clip"[^>]*\\bdata-composition-id="${escapeRegExp3(compositionId)}"[^>]*\\bdata-start="([\\d.]+)"`,
+      "i"
+    )
+  );
+  if (!match2) return void 0;
+  const start = Number.parseFloat(match2[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("\\");
@@ -488180,6 +489226,7 @@ async function executeSceneAdd(opts) {
   const id = slugifySceneName(opts.name);
   const sceneRel = `compositions/scene-${id}.html`;
   const scenePath = resolve24(projectDir, sceneRel);
+  const storyboardAbsPath = resolve24(projectDir, "STORYBOARD.md");
   const errResult = (error) => ({
     success: false,
     id,
@@ -488399,6 +489446,27 @@ async function executeSceneAdd(opts) {
     duration = fallback2;
   }
   duration = Number(duration.toFixed(2));
+  let storyboardPath;
+  let storyboardSynced = false;
+  let storyboardAction = "skipped";
+  const shouldSyncStoryboard = opts.syncStoryboard !== false && await pathExists2(storyboardAbsPath);
+  if (shouldSyncStoryboard) {
+    opts.onProgress?.("Syncing STORYBOARD.md...");
+    const before2 = await readFile14(storyboardAbsPath, "utf-8");
+    const synced = upsertStoryboardBeat(before2, {
+      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 !== before2) {
+      await writeFile17(storyboardAbsPath, synced.markdown, "utf-8");
+    }
+    storyboardPath = relative8(process.cwd(), storyboardAbsPath) || storyboardAbsPath;
+    storyboardSynced = true;
+    storyboardAction = synced.action;
+  }
   opts.onProgress?.("Emitting scene HTML...");
   const sceneHtml = emitSceneHtml({
     id,
@@ -488417,11 +489485,24 @@ async function executeSceneAdd(opts) {
   await mkdir11(dirname14(scenePath), { recursive: true });
   await writeFile17(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 writeFile17(rootPath, updated, "utf-8");
+  let start = 0;
+  if (storyboardSynced) {
+    const syncPlan = await syncRootComposition({
+      projectDir,
+      rootRel,
+      beats: await loadProjectRootSyncBeats(projectDir)
+    });
+    const blockingIssue = syncPlan.issues.find((issue) => issue.severity === "error");
+    if (blockingIssue) return errResult(blockingIssue.message);
+    const rootHtmlAfterSync = await readFile14(rootPath, "utf-8");
+    start = readClipStart(rootHtmlAfterSync, id) ?? 0;
+  } else {
+    start = nextSceneStart(rootHtmlBefore, SCENE_OVERLAP_SECONDS);
+    const existingClipCount = (rootHtmlBefore.match(/<div\s+class="clip"/g) || []).length;
+    const trackIndex = existingClipCount % 2 + 1;
+    const updated = insertClipIntoRoot(rootHtmlBefore, { id, start, duration, trackIndex });
+    await writeFile17(rootPath, updated, "utf-8");
+  }
   const transcriptAbsPath = transcriptRelPath ? resolve24(projectDir, transcriptRelPath) : void 0;
   return {
     success: true,
@@ -488434,6 +489515,9 @@ async function executeSceneAdd(opts) {
     audioPath: audioAbsPath ? relative8(process.cwd(), audioAbsPath) || audioAbsPath : void 0,
     imagePath: imageAbsPath ? relative8(process.cwd(), imageAbsPath) || imageAbsPath : void 0,
     lottiePath: lottieAbsPath ? relative8(process.cwd(), lottieAbsPath) || lottieAbsPath : void 0,
+    storyboardPath,
+    storyboardSynced,
+    storyboardAction,
     transcriptPath: transcriptAbsPath ? relative8(process.cwd(), transcriptAbsPath) || transcriptAbsPath : void 0,
     transcriptWordCount
   };
@@ -488731,6 +489815,9 @@ var sceneAddSchema = z2.object({
   kicker: z2.string().optional().describe("Small label above the headline (used by 'explainer' and 'product-shot' presets)."),
   projectDir: z2.string().optional().describe(PROJECT_DIR_DESCRIPTION),
   insertInto: z2.string().optional().describe("Root composition file (relative to projectDir). Default 'index.html'."),
+  syncStoryboard: z2.boolean().optional().describe(
+    "Sync STORYBOARD.md when present, then rebuild root refs from it. Default true; set false for root-only insertion."
+  ),
   imageProvider: z2.enum(["gemini", "openai"]).optional().describe("Image provider for visuals. Default 'gemini'."),
   voice: z2.string().optional().describe("ElevenLabs voice id or name."),
   skipAudio: z2.boolean().optional().describe("Skip TTS even if narration is provided."),
@@ -488743,7 +489830,7 @@ var sceneAddTool = defineTool({
   cost: "low",
   title: "Add Scene from Preset",
   annotations: { readOnly: false, openWorld: true },
-  description: "Add a single scene to an existing scene project. Optionally generates narration audio (ElevenLabs) and/or a backdrop image (Gemini/OpenAI), then emits compositions/scene-<id>.html with a paused GSAP timeline and splices a clip reference into the root index.html. Use skipAudio:true and skipImage:true for text-only scenes that need no API calls.",
+  description: "Add a single scene to an existing scene project. Optionally generates narration audio (ElevenLabs) and/or a backdrop image (Gemini/OpenAI), then emits compositions/scene-<id>.html with a paused GSAP timeline. By default, syncs STORYBOARD.md and rebuilds root refs from it; set syncStoryboard:false for root-only insertion. Use skipAudio:true and skipImage:true for text-only scenes that need no API calls.",
   schema: sceneAddSchema,
   async execute(args, ctx) {
     const projectDir = args.projectDir ? resolve34(ctx.workingDirectory, args.projectDir) : ctx.workingDirectory;
@@ -488757,6 +489844,7 @@ var sceneAddTool = defineTool({
       kicker: args.kicker,
       projectDir,
       insertInto: args.insertInto,
+      syncStoryboard: args.syncStoryboard,
       imageProvider: args.imageProvider,
       voice: args.voice,
       skipAudio: args.skipAudio,
@@ -488775,6 +489863,9 @@ var sceneAddTool = defineTool({
     ];
     if (result.audioPath) lines.push(`   audio:    ${result.audioPath}`);
     if (result.imagePath) lines.push(`   image:    ${result.imagePath}`);
+    if (result.storyboardPath && result.storyboardSynced) {
+      lines.push(`   story:    ${result.storyboardPath} (${result.storyboardAction})`);
+    }
     return {
       success: true,
       data: {
@@ -488785,7 +489876,10 @@ var sceneAddTool = defineTool({
         scenePath: result.scenePath,
         rootPath: result.rootPath,
         audioPath: result.audioPath,
-        imagePath: result.imagePath
+        imagePath: result.imagePath,
+        storyboardPath: result.storyboardPath,
+        storyboardSynced: result.storyboardSynced,
+        storyboardAction: result.storyboardAction
       },
       humanLines: lines
     };
@@ -490220,7 +491314,7 @@ init_root_sync();
 init_review_report();
 import { existsSync as existsSync56 } from "node:fs";
 import { readdir as readdir6, readFile as readFile31, stat as stat5 } from "node:fs/promises";
-import { basename as basename14, isAbsolute as isAbsolute7, join as join38, relative as relative13, resolve as resolve50 } from "node:path";
+import { basename as basename14, isAbsolute as isAbsolute7, join as join37, relative as relative13, resolve as resolve50 } from "node:path";
 async function inspectProject(opts) {
   const projectDir = resolve50(opts.projectDir);
   const issues = [];
@@ -490249,12 +491343,12 @@ async function inspectProject(opts) {
     );
   }
   const coreFiles = {
-    storyboard: join38(projectDir, "STORYBOARD.md"),
-    design: join38(projectDir, "DESIGN.md"),
-    config: join38(projectDir, "vibe.config.json"),
-    legacyConfig: join38(projectDir, "vibe.project.yaml"),
-    buildReport: join38(projectDir, "build-report.json"),
-    root: join38(projectDir, "index.html")
+    storyboard: join37(projectDir, "STORYBOARD.md"),
+    design: join37(projectDir, "DESIGN.md"),
+    config: join37(projectDir, "vibe.config.json"),
+    legacyConfig: join37(projectDir, "vibe.project.yaml"),
+    buildReport: join37(projectDir, "build-report.json"),
+    root: join37(projectDir, "index.html")
   };
   for (const [name, path14] of Object.entries(coreFiles)) {
     checks.files[name] = existsSync56(path14);
@@ -490338,7 +491432,7 @@ async function inspectProject(opts) {
     });
     retryWith.push(`vibe build ${projectDir} --stage sync --json`);
   }
-  const compositionsDir = join38(projectDir, "compositions");
+  const compositionsDir = join37(projectDir, "compositions");
   const existingComps = existsSync56(compositionsDir) ? new Set(await listHtmlBasenames(compositionsDir)) : /* @__PURE__ */ new Set();
   checks.compositions.expected = inspectedBeatIds.length;
   for (const beatId of inspectedBeatIds) {
@@ -490346,12 +491440,12 @@ async function inspectProject(opts) {
     if (existingComps.has(file)) {
       checks.compositions.found++;
     } else {
-      checks.compositions.missing.push(join38("compositions", file));
+      checks.compositions.missing.push(join37("compositions", file));
       issues.push({
         severity: "error",
         code: "MISSING_COMPOSITION",
         message: `Composition for beat "${beatId}" is missing.`,
-        file: join38("compositions", file),
+        file: join37("compositions", file),
         scene: beatId,
         beatId,
         suggestedFix: "Run `vibe build --stage compose --json`."
@@ -490413,7 +491507,7 @@ async function inspectProject(opts) {
     try {
       const lint = await runProjectLint({ projectDir });
       const lintFiles = opts.beatId ? lint.files.filter(
-        (file) => file.file === "index.html" || file.file === join38("compositions", `scene-${opts.beatId}.html`)
+        (file) => file.file === "index.html" || file.file === join37("compositions", `scene-${opts.beatId}.html`)
       ) : lint.files;
       const lintCounts = countLintFindings(lintFiles);
       checks.lint = {
@@ -490449,7 +491543,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",
@@ -490461,9 +491559,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) {
@@ -490783,7 +491886,7 @@ init_storyboard_parse();
 init_review_report();
 import { existsSync as existsSync57 } from "node:fs";
 import { readdir as readdir7, readFile as readFile32, stat as stat6 } from "node:fs/promises";
-import { basename as basename15, isAbsolute as isAbsolute8, join as join39, relative as relative14, resolve as resolve51 } from "node:path";
+import { basename as basename15, isAbsolute as isAbsolute8, join as join38, relative as relative14, resolve as resolve51 } from "node:path";
 var VIDEO_EXTENSIONS = /* @__PURE__ */ new Set([".mp4", ".mov", ".webm", ".m4v"]);
 var DEFAULT_AI_MODEL = "flash";
 var BLACK_FRAME_MIN_DURATION_SEC = 1;
@@ -491015,6 +492118,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(
@@ -491037,6 +492142,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(
@@ -491046,6 +492153,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",
@@ -491071,7 +492180,7 @@ async function inspectRender(opts) {
           file: displayPath(videoPath)
         });
       }
-      if (!audioStream) {
+      if (!audioStream && expectedAudio) {
         issues.push({
           severity: "warning",
           code: "NO_AUDIO_STREAM",
@@ -491276,8 +492385,86 @@ async function inspectRender(opts) {
   );
   return maybeWriteRenderReport(projectDir, opts, result);
 }
+async function renderExpectsAudio(projectDir, beatId) {
+  const root2 = resolve51(projectDir);
+  const rootHtml = await readTextIfExists(join38(root2, "index.html"));
+  if (rootHtml && rootHtmlExpectsAudio(rootHtml, beatId)) return true;
+  const buildReport = await readJsonIfExists(join38(root2, "build-report.json"));
+  if (buildReportExpectsAudio(buildReport, beatId)) return true;
+  const storyboard = await readTextIfExists(join38(root2, "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) => existsSync57(join38(root2, asset)))
+    );
+  } catch {
+    return false;
+  }
+}
+function rootHtmlExpectsAudio(html, beatId) {
+  const audioTags = html.match(/<audio\b[^>]*>/gi) ?? [];
+  if (!beatId) return audioTags.length > 0;
+  const escaped = escapeRegExp4(beatId);
+  const beatAudioRe = new RegExp(
+    `(id="(?:narration|music)-${escaped}"|src="[^"]*(?:narration|music)-${escaped}\\.(?:mp3|wav)")`,
+    "i"
+  );
+  return audioTags.some((tag) => beatAudioRe.test(tag));
+}
+function buildReportExpectsAudio(report, beatId) {
+  if (!report || typeof report !== "object") return false;
+  const beats = Array.isArray(report.beats) ? report.beats ?? [] : [];
+  const selected = beatId === void 0 ? beats : beats.filter((beat) => {
+    if (!beat || typeof beat !== "object") return false;
+    return beat.id === beatId;
+  });
+  return selected.some((beat) => beatReportExpectsAudio(beat));
+}
+function beatReportExpectsAudio(beat) {
+  if (!beat || typeof beat !== "object") return false;
+  const record = beat;
+  if (typeof record.narrationPath === "string" && record.narrationPath.length > 0) return true;
+  if (typeof record.musicPath === "string" && record.musicPath.length > 0) return true;
+  if (parseOptionalNumber2(record.narrationDurationSec) !== void 0) return true;
+  const narration = record.narration;
+  if (narration && typeof narration === "object") {
+    const n2 = narration;
+    if (typeof n2.path === "string" && n2.path.length > 0) return true;
+    if (parseOptionalNumber2(n2.durationSec) !== void 0) return true;
+  }
+  const music = record.music;
+  if (music && typeof music === "object") {
+    const m2 = music;
+    if (typeof m2.path === "string" && m2.path.length > 0) return true;
+    if (parseOptionalNumber2(m2.durationSec) !== void 0) return true;
+  }
+  return false;
+}
+async function readJsonIfExists(path14) {
+  const text = await readTextIfExists(path14);
+  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",
@@ -491290,9 +492477,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) {
@@ -491318,8 +492510,8 @@ async function maybeWriteRenderReport(projectDir, opts, result) {
 }
 function renderSourceReports(projectDir, videoPath, checks) {
   const reports = [];
-  if (existsSync57(join39(projectDir, "build-report.json"))) reports.push("build-report.json");
-  if (existsSync57(join39(projectDir, "render-report.json"))) reports.push("render-report.json");
+  if (existsSync57(join38(projectDir, "build-report.json"))) reports.push("build-report.json");
+  if (existsSync57(join38(projectDir, "render-report.json"))) reports.push("render-report.json");
   if (videoPath) reports.push(displayPath(videoPath));
   if (checks.durationSec !== void 0 || checks.width !== void 0 || checks.height !== void 0) {
     reports.push("ffprobe");
@@ -491334,7 +492526,7 @@ async function resolveRenderVideoPath(projectDir, explicit, beatId) {
     const candidate = resolve51(process.cwd(), explicit);
     return existsSync57(candidate) ? candidate : null;
   }
-  const renderReportPath = join39(projectDir, "render-report.json");
+  const renderReportPath = join38(projectDir, "render-report.json");
   if (existsSync57(renderReportPath)) {
     try {
       const report = JSON.parse(await readFile32(renderReportPath, "utf-8"));
@@ -491346,7 +492538,7 @@ async function resolveRenderVideoPath(projectDir, explicit, beatId) {
     } catch {
     }
   }
-  const reportPath = join39(projectDir, "build-report.json");
+  const reportPath = join38(projectDir, "build-report.json");
   if (!beatId && existsSync57(reportPath)) {
     try {
       const report = JSON.parse(await readFile32(reportPath, "utf-8"));
@@ -491355,7 +492547,7 @@ async function resolveRenderVideoPath(projectDir, explicit, beatId) {
     } catch {
     }
   }
-  const rendersDir = join39(projectDir, "renders");
+  const rendersDir = join38(projectDir, "renders");
   if (!existsSync57(rendersDir)) return null;
   const entries2 = await readdir7(rendersDir, { withFileTypes: true });
   const candidates = [];
@@ -491364,7 +492556,7 @@ async function resolveRenderVideoPath(projectDir, explicit, beatId) {
     const ext = entry.name.slice(entry.name.lastIndexOf(".")).toLowerCase();
     if (!VIDEO_EXTENSIONS.has(ext)) continue;
     if (beatId && !entry.name.includes(sanitizeFileSegment2(beatId))) continue;
-    const full = join39(rendersDir, entry.name);
+    const full = join38(rendersDir, entry.name);
     const info = await stat6(full);
     candidates.push({ path: full, mtimeMs: info.mtimeMs });
   }
@@ -491382,11 +492574,11 @@ async function runAiRenderReview(projectDir, videoPath, model) {
   });
 }
 function resolveStoryboardPath(projectDir) {
-  const storyboardPath = join39(projectDir, "STORYBOARD.md");
+  const storyboardPath = join38(projectDir, "STORYBOARD.md");
   return existsSync57(storyboardPath) ? storyboardPath : null;
 }
 async function expectedDurationFromBuildReport(projectDir, beatId) {
-  const reportPath = join39(projectDir, "build-report.json");
+  const reportPath = join38(projectDir, "build-report.json");
   if (!existsSync57(reportPath)) return void 0;
   try {
     const report = JSON.parse(await readFile32(reportPath, "utf-8"));
@@ -491401,7 +492593,7 @@ async function expectedDurationFromBuildReport(projectDir, beatId) {
   }
 }
 async function beatTimingsFromBuildReport(projectDir, beatId) {
-  const reportPath = join39(projectDir, "build-report.json");
+  const reportPath = join38(projectDir, "build-report.json");
   if (!existsSync57(reportPath)) return [];
   try {
     const report = JSON.parse(await readFile32(reportPath, "utf-8"));
@@ -491430,17 +492622,17 @@ async function beatTimingsFromBuildReport(projectDir, beatId) {
 }
 async function buildRenderReviewProjectContext(projectDir) {
   const parts = [];
-  const storyboard = await readTextIfExists(join39(projectDir, "STORYBOARD.md"));
+  const storyboard = await readTextIfExists(join38(projectDir, "STORYBOARD.md"));
   if (storyboard) {
     parts.push(`STORYBOARD.md:
 ${truncateText(storyboard, 4e3)}`);
     parts.push(`Storyboard beat cue summary:
 ${storyboardBeatCueSummary(storyboard)}`);
   }
-  const design = await readTextIfExists(join39(projectDir, "DESIGN.md"));
+  const design = await readTextIfExists(join38(projectDir, "DESIGN.md"));
   if (design) parts.push(`DESIGN.md:
 ${truncateText(design, 4e3)}`);
-  const buildReport = await readTextIfExists(join39(projectDir, "build-report.json"));
+  const buildReport = await readTextIfExists(join38(projectDir, "build-report.json"));
   if (buildReport) parts.push(`build-report.json:
 ${truncateText(buildReport, 6e3)}`);
   const timings = await beatTimingsFromBuildReport(projectDir);
@@ -492299,7 +493491,7 @@ init_storyboard_edit();
 // ../cli/src/commands/_shared/storyboard-revise.ts
 import { existsSync as existsSync59 } from "node:fs";
 import { readFile as readFile35, writeFile as writeFile42 } from "node:fs/promises";
-import { join as join40, resolve as resolve64 } from "node:path";
+import { join as join39, resolve as resolve64 } from "node:path";
 
 // ../cli/src/agent/adapters/index.ts
 init_openai3();
@@ -492346,7 +493538,7 @@ init_storyboard_parse();
 init_storyboard_edit();
 async function executeStoryboardRevision(opts) {
   const projectDir = resolve64(opts.projectDir);
-  const storyboardPath = join40(projectDir, "STORYBOARD.md");
+  const storyboardPath = join39(projectDir, "STORYBOARD.md");
   const retryWith = [`vibe storyboard revise ${projectDir} --from "<request>" --dry-run --json`];
   if (!existsSync59(storyboardPath)) {
     return failureResult({
@@ -492581,8 +493773,8 @@ function diffChangedBeats(before2, after2) {
   return ids.filter((id) => JSON.stringify(beforeBeats.get(id) ?? null) !== JSON.stringify(afterBeats.get(id) ?? null));
 }
 async function readRevisionContext(projectDir) {
-  const designMd = await readOptionalText(join40(projectDir, "DESIGN.md"));
-  const buildReportJson = await readOptionalJsonText(join40(projectDir, "build-report.json"));
+  const designMd = await readOptionalText(join39(projectDir, "DESIGN.md"));
+  const buildReportJson = await readOptionalJsonText(join39(projectDir, "build-report.json"));
   return { designMd, buildReportJson };
 }
 async function readOptionalText(path14) {
@@ -492897,7 +494089,7 @@ var storyboardTools = [
 // ../cli/src/tools/manifest/remix.ts
 import { writeFile as writeFile48 } from "node:fs/promises";
 import { tmpdir as tmpdir6 } from "node:os";
-import { join as join41 } from "node:path";
+import { join as join40 } from "node:path";
 import { z as z8 } from "zod";
 
 // ../cli/src/commands/ai-script-pipeline.ts
@@ -494631,7 +495823,7 @@ var pipelineRunTool = defineTool({
     let resolvedPath = args.pipelinePath;
     let tempPath;
     if (args.pipelineYaml) {
-      tempPath = join41(tmpdir6(), `vibe-mcp-pipeline-${Date.now()}.yaml`);
+      tempPath = join40(tmpdir6(), `vibe-mcp-pipeline-${Date.now()}.yaml`);
       await writeFile48(tempPath, args.pipelineYaml, "utf-8");
       resolvedPath = tempPath;
     }
@@ -495163,7 +496355,7 @@ init_engine();
 init_storyboard_parse();
 import { readdir as readdir8, readFile as readFile42, stat as stat7 } from "node:fs/promises";
 import { existsSync as existsSync65 } from "node:fs";
-import { join as join43, resolve as resolve71 } from "node:path";
+import { join as join41, resolve as resolve71 } from "node:path";
 async function executeProjectList(opts = {}) {
   const workspaceDir = resolve71(opts.workspaceDir ?? ".");
   if (!existsSync65(workspaceDir)) {
@@ -495183,11 +496375,11 @@ async function executeProjectList(opts = {}) {
     if (entry.name === "node_modules") continue;
     if (entry.name.startsWith(".")) continue;
     if (entry.name.startsWith("_")) {
-      archivedCount += await countProjects(join43(workspaceDir, entry.name));
+      archivedCount += await countProjects(join41(workspaceDir, entry.name));
       continue;
     }
-    const projectDir = join43(workspaceDir, entry.name);
-    if (!existsSync65(join43(projectDir, "STORYBOARD.md"))) continue;
+    const projectDir = join41(workspaceDir, entry.name);
+    if (!existsSync65(join41(projectDir, "STORYBOARD.md"))) continue;
     projects.push(await describeProject(entry.name, projectDir));
   }
   projects.sort((a2, b2) => b2.updatedAt.localeCompare(a2.updatedAt));
@@ -495197,7 +496389,7 @@ async function countProjects(dir) {
   try {
     const entries2 = await readdir8(dir, { withFileTypes: true });
     return entries2.filter(
-      (e2) => e2.isDirectory() && existsSync65(join43(dir, e2.name, "STORYBOARD.md"))
+      (e2) => e2.isDirectory() && existsSync65(join41(dir, e2.name, "STORYBOARD.md"))
     ).length;
   } catch {
     return 0;
@@ -495208,7 +496400,7 @@ async function describeProject(name, projectDir) {
   let storyboardDurationSec = 0;
   const timestamps = [];
   try {
-    const storyboardPath = join43(projectDir, "STORYBOARD.md");
+    const storyboardPath = join41(projectDir, "STORYBOARD.md");
     const parsed = parseStoryboard(await readFile42(storyboardPath, "utf-8"));
     beats = parsed.beats.length;
     storyboardDurationSec = Number(
@@ -495220,7 +496412,7 @@ async function describeProject(name, projectDir) {
   let buildStatus;
   let buildUpdatedAt;
   try {
-    const reportPath = join43(projectDir, "build-report.json");
+    const reportPath = join41(projectDir, "build-report.json");
     const report = JSON.parse(await readFile42(reportPath, "utf-8"));
     buildStatus = report.status ?? report.phase;
     buildUpdatedAt = report.updatedAt;
@@ -495229,12 +496421,12 @@ async function describeProject(name, projectDir) {
   }
   let latestRender;
   try {
-    const rendersDir = join43(projectDir, "renders");
+    const rendersDir = join41(projectDir, "renders");
     const files = await readdir8(rendersDir);
     let newest;
     for (const file of files) {
       if (!/\.(mp4|webm|mov)$/i.test(file)) continue;
-      const { mtimeMs } = await stat7(join43(rendersDir, file));
+      const { mtimeMs } = await stat7(join41(rendersDir, file));
       if (!newest || mtimeMs > newest.mtimeMs) newest = { file, mtimeMs };
     }
     if (newest) {
@@ -496245,7 +497437,7 @@ var exportTools = [exportVideoTool];
 
 // ../cli/src/tools/manifest/agent-only.ts
 import { readFile as readFile44, writeFile as writeFile52, readdir as readdir9, stat as stat8, access as access7, unlink as unlink7 } from "node:fs/promises";
-import { resolve as resolve76, join as join44, basename as basename21, extname as extname14 } from "node:path";
+import { resolve as resolve76, join as join43, basename as basename21, extname as extname14 } from "node:path";
 import { z as z13 } from "zod";
 init_engine();
 init_exec_safe();
@@ -496324,7 +497516,7 @@ var fsListTool = defineTool({
       const results = [];
       for (const entry of entries2) {
         if (args.pattern && !matchPattern(entry.name, args.pattern)) continue;
-        const fullPath = join44(absPath, entry.name);
+        const fullPath = join43(absPath, entry.name);
         const stats = await stat8(fullPath);
         if (entry.isDirectory()) {
           results.push(`[DIR]  ${entry.name}/`);
@@ -496437,7 +497629,7 @@ var batchImportTool = defineTool({
       const scanDir = async (dir) => {
         const entries2 = await readdir9(dir, { withFileTypes: true });
         for (const entry of entries2) {
-          const entryPath = join44(dir, entry.name);
+          const entryPath = join43(dir, entry.name);
           if (entry.isDirectory() && recursive) {
             await scanDir(entryPath);
           } else if (entry.isFile()) {
@@ -498507,7 +499699,7 @@ var server2 = new Server(
   {
     name: "vibeframe",
     // Stamped with the package version by build.js at bundle time.
-    version: "0.113.0"
+    version: "0.113.3"
   },
   {
     capabilities: {