@vibeframe/cli 0.113.3 → 0.113.5

package/dist/commands/_shared/build-plan.d.ts

@@ -15,6 +15,7 @@ export interface BuildPlanBeat {
     assets: {
         narration: AssetPlan | null;
         backdrop: AssetPlan | null;
+        keyframe: AssetPlan | null;
         video: AssetPlan | null;
         music: AssetPlan | null;
     };
@@ -93,6 +94,7 @@ export interface CreateBuildPlanOptions {
     skipNarration?: boolean;
     skipBackdrop?: boolean;
     skipVideo?: boolean;
+    skipKeyframe?: boolean;
     skipMusic?: boolean;
     ttsProvider?: string;
     voice?: string;

package/dist/commands/_shared/scene-build.d.ts

@@ -81,6 +81,23 @@ export type SceneBuildProgressEvent = {
     type: "backdrop-skipped";
     beatId: string;
     reason: string;
+} | {
+    type: "keyframe-cached";
+    beatId: string;
+    path: string;
+} | {
+    type: "keyframe-generated";
+    beatId: string;
+    path: string;
+    provider: string;
+} | {
+    type: "keyframe-failed";
+    beatId: string;
+    error: string;
+} | {
+    type: "keyframe-skipped";
+    beatId: string;
+    reason: string;
 } | {
     type: "video-cached";
     beatId: string;
@@ -233,6 +250,8 @@ export interface SceneBuildOptions {
     musicProvider?: BuildMusicProvider;
     /** Skip AI video generation even when beats declare video cues. */
     skipVideo?: boolean;
+    /** Skip keyframe-still generation even when beats declare keyframe cues. */
+    skipKeyframe?: boolean;
     /** Skip music generation even when beats declare music cues. */
     skipMusic?: boolean;
     /** OpenAI image quality — see `vibe generate image --quality`. */

package/dist/index.js

@@ -60690,6 +60690,14 @@ async function createBuildPlan(opts) {
       duration: beat.duration,
       keyframe: keyframePrompt
     }) : null;
+    const keyframeCache = keyframePrompt ? keyframeCacheDescriptor({
+      beatId: beat.id,
+      cue: keyframePrompt,
+      provider: resolved.image.resolved,
+      quality: imageQuality,
+      size: imageSize2,
+      ratio: imageRatio
+    }) : null;
     const musicCache = musicPrompt && !musicReference ? musicCacheDescriptor({
       beatId: beat.id,
       cue: musicPrompt,
@@ -60725,6 +60733,19 @@ async function createBuildPlan(opts) {
       cost: backdropCostUsd(imageQuality),
       active: includeAssets
     }) : null;
+    const keyframe = keyframePrompt && !opts.skipKeyframe ? assetPlan({
+      kind: "keyframe",
+      beatId: beat.id,
+      cue: keyframePrompt,
+      provider: resolved.image.resolved,
+      path: `assets/keyframe-${beat.id}.png`,
+      cache: keyframeCache,
+      reference: null,
+      projectDir,
+      force: opts.force,
+      cost: backdropCostUsd(imageQuality),
+      active: includeAssets
+    }) : null;
     const video = videoCue && !opts.skipVideo ? assetPlan({
       kind: "video",
       beatId: beat.id,
@@ -60757,7 +60778,7 @@ async function createBuildPlan(opts) {
     }) : null;
     const compositionPath = `compositions/scene-${beat.id}.html`;
     const compositionExists = existsSync47(join23(projectDir, compositionPath));
-    for (const asset of [narration, backdrop, video, music]) {
+    for (const asset of [narration, backdrop, keyframe, video, music]) {
       if (!asset) continue;
       if (asset.referenceError) {
         missing.add("assets");
@@ -60782,13 +60803,9 @@ async function createBuildPlan(opts) {
     if (narration?.willGenerate) noteProviderNeed(resolved.narration, "Narration");
     if (backdrop?.willGenerate && isSupportedBuildImageProvider(resolved.image.resolved))
       noteProviderNeed(resolved.image, "Backdrop generation");
+    if (keyframe?.willGenerate && isSupportedBuildImageProvider(resolved.image.resolved))
+      noteProviderNeed(resolved.image, "Keyframe 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") {
@@ -60801,7 +60818,7 @@ async function createBuildPlan(opts) {
       heading: beat.heading,
       durationSec: beat.duration ?? null,
       cues: cue,
-      assets: { narration, backdrop, video, music },
+      assets: { narration, backdrop, keyframe, video, music },
       composition: {
         path: compositionPath,
         exists: compositionExists
@@ -61017,6 +61034,7 @@ function providerResolutionsForPlan(resolved, beats, opts, includeAssets) {
   return [
     includeAssets && !opts.skipNarration && needsProvider("narration") ? resolved.narration : null,
     includeAssets && !opts.skipBackdrop && needsProvider("backdrop") ? resolved.image : null,
+    includeAssets && !opts.skipKeyframe && needsProvider("keyframe") ? resolved.image : null,
     includeAssets && !opts.skipVideo && needsProvider("video") ? resolved.video : null,
     includeAssets && !opts.skipMusic && needsProvider("music") ? resolved.music : null,
     resolved.composer ?? null
@@ -62072,10 +62090,17 @@ async function executeSceneBuild(opts) {
   const onProgress = opts.onProgress ?? (() => {
   });
   const mode = resolveSceneBuildMode(opts);
-  const selectedStage = opts.stage ?? (opts.skipRender ? "sync" : "all");
+  let selectedStage = opts.stage ?? (opts.skipRender ? "sync" : "all");
+  const skipVideoStopsRender = (opts.skipVideo ?? false) && (selectedStage === "all" || selectedStage === "render");
+  if (skipVideoStopsRender) selectedStage = "sync";
   const stageReports = createEmptyStageReports();
   const warnings = [];
   const retryWith = [];
+  if (skipVideoStopsRender) {
+    warnings.push(
+      "--skip-video: skipped render (no clips to capture). Review assets/keyframe-*.png, then build without --skip-video to animate them."
+    );
+  }
   let sceneRepair = skippedSceneRepairSummary();
   const storyboardPath2 = join25(projectDir, "STORYBOARD.md");
   const buildPlan = await createBuildPlan({
@@ -62086,6 +62111,7 @@ async function executeSceneBuild(opts) {
     skipNarration: opts.skipNarration,
     skipBackdrop: opts.skipBackdrop,
     skipVideo: opts.skipVideo,
+    skipKeyframe: opts.skipKeyframe,
     skipMusic: opts.skipMusic,
     ttsProvider: opts.ttsProvider,
     voice: opts.voice,
@@ -62234,7 +62260,7 @@ async function executeSceneBuild(opts) {
   if (shouldRunStage(selectedStage, "assets")) {
     onProgress({ type: "phase-start", phase: "primitives" });
     const characterPaths = /* @__PURE__ */ new Map();
-    if (!(opts.skipVideo ?? false)) {
+    if (!((opts.skipVideo ?? false) && (opts.skipKeyframe ?? false))) {
       const referenced = /* @__PURE__ */ new Set();
       for (const beat of activeBeats) {
         for (const name of beatCharacterNames(beat.cues)) referenced.add(name);
@@ -62271,6 +62297,7 @@ async function executeSceneBuild(opts) {
         skipNarration: opts.skipNarration ?? false,
         skipBackdrop: opts.skipBackdrop ?? false,
         skipVideo: opts.skipVideo ?? false,
+        skipKeyframe: opts.skipKeyframe ?? false,
         skipMusic: opts.skipMusic ?? false,
         force: opts.force ?? false,
         onProgress,
@@ -62647,10 +62674,11 @@ async function executeSceneBuild(opts) {
   });
 }
 async function buildBeatPrimitives(beat, ctx) {
+  const keyframe = ctx.skipKeyframe ? await skipped("keyframe", beat.id, "--skip-keyframe", ctx) : await dispatchKeyframe(beat, ctx);
   const [narration, backdrop, video, music] = await Promise.all([
     ctx.skipNarration ? skipped("narration", beat.id, "--skip-narration", ctx) : dispatchNarration(beat, ctx),
     ctx.skipBackdrop ? skipped("backdrop", beat.id, "--skip-backdrop", ctx) : dispatchBackdrop(beat, ctx),
-    ctx.skipVideo ? skipped("video", beat.id, "--skip-video", ctx) : dispatchVideo(beat, ctx),
+    ctx.skipVideo ? skipped("video", beat.id, "--skip-video", ctx) : dispatchVideo(beat, ctx, keyframe),
     ctx.skipMusic ? skipped("music", beat.id, "--skip-music", ctx) : dispatchMusic(beat, ctx)
   ]);
   return {
@@ -62694,8 +62722,8 @@ async function buildBeatPrimitives(beat, ctx) {
       videoMetadataPath: video.metadataPath,
       videoFreshness: video.freshness,
       videoSourcePath: video.sourcePath,
-      keyframeStatus: video.keyframeStatus,
-      keyframePath: video.keyframePath,
+      keyframeStatus: keyframe.status,
+      keyframePath: keyframe.path,
       musicStatus: music.status,
       musicPath: music.path,
       musicJobId: music.job?.id,
@@ -63266,7 +63294,21 @@ function imageProviderKeyInfo(provider) {
   if (provider === "grok") return { configKey: "xai", envVar: "XAI_API_KEY" };
   return { configKey: "openai", envVar: "OPENAI_API_KEY" };
 }
-async function dispatchVideo(beat, ctx) {
+async function dispatchKeyframe(beat, ctx) {
+  const keyframeCue = stringOrUndefined4(beat.cues?.keyframe);
+  if (!keyframeCue) return { status: "no-cue" };
+  const characterRefsRel = beatCharacterNames(beat.cues).map((name) => ctx.characterPaths?.get(name)).filter((p) => typeof p === "string");
+  const kf = await ensureKeyframe(beat, ctx, keyframeCue, characterRefsRel);
+  if (kf.status === "failed") {
+    ctx.onProgress({ type: "keyframe-failed", beatId: beat.id, error: kf.error });
+    return { status: "failed", error: kf.error };
+  }
+  ctx.onProgress(
+    kf.status === "cached" ? { type: "keyframe-cached", beatId: beat.id, path: kf.rel } : { type: "keyframe-generated", beatId: beat.id, path: kf.rel, provider: ctx.imageProvider }
+  );
+  return { status: kf.status, path: kf.rel, provider: ctx.imageProvider };
+}
+async function dispatchVideo(beat, ctx, keyframe) {
   const reference = assetReferenceForBeat(ctx.projectDir, "video", beat);
   if (reference) return referencePrimitiveOutcome("video", beat, ctx, reference);
   const keyframeCue = stringOrUndefined4(beat.cues?.keyframe);
@@ -63336,20 +63378,14 @@ async function dispatchVideo(beat, ctx) {
       freshness: "fresh"
     };
   }
-  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 = join25(ctx.projectDir, kf.rel);
+  const keyframeImageRel = keyframeCue && (keyframe.status === "generated" || keyframe.status === "cached") ? keyframe.path : void 0;
+  if (keyframeCue && !keyframeImageRel) {
+    const reason = keyframe.status === "failed" ? `keyframe unavailable: ${keyframe.error ?? "generation failed"}` : "keyframe not generated (build without --skip-keyframe first)";
+    ctx.onProgress({ type: "video-skipped", beatId: beat.id, reason });
+    return { status: "skipped" };
   }
+  const keyframeImageAbs = keyframeImageRel ? join25(ctx.projectDir, keyframeImageRel) : void 0;
+  loadSceneBuildEnv(ctx.projectDir);
   const result = await executeVideoGenerate({
     prompt: prompt3,
     provider: ctx.videoProvider,
@@ -63395,9 +63431,7 @@ async function dispatchVideo(beat, ctx) {
       cachePath: cache.path,
       cacheKey: cache.key,
       metadataPath,
-      freshness: "fresh",
-      keyframeStatus,
-      keyframePath: keyframeRel
+      freshness: "fresh"
     };
   }
   const job = await createAndWriteJobRecord({
@@ -63429,9 +63463,7 @@ async function dispatchVideo(beat, ctx) {
     provider: job.provider,
     cachePath: cache.path,
     cacheKey: cache.key,
-    metadataPath,
-    keyframeStatus,
-    keyframePath: keyframeRel
+    metadataPath
   };
 }
 async function dispatchMusic(beat, ctx) {
@@ -74819,7 +74851,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.113.3",
+  version: "0.113.5",
   description: "VibeFrame CLI - agentic video workflow runtime",
   private: false,
   license: "MIT",
@@ -85105,7 +85137,10 @@ var VALID_STAGES2 = ["assets", "compose", "sync", "render", "all"];
 var VALID_IMAGE_PROVIDERS2 = ["openai", "gemini", "grok"];
 var VALID_VIDEO_PROVIDERS2 = ["seedance", "grok", "kling", "runway", "veo"];
 var VALID_MUSIC_PROVIDERS2 = ["elevenlabs", "replicate"];
-var buildCommand = new Command("build").description("Build a VibeFrame video project from STORYBOARD.md").argument("[project-dir]", "Video project directory", ".").option("--stage <stage>", `Build stage: ${VALID_STAGES2.join("|")}`, "all").option("--beat <id>", "Restrict asset/compose work to one beat id").option("--mode <mode>", "Build mode: agent|batch|auto", "auto").option("--effort <level>", "Compose effort tier (batch mode only): low|medium|high", "medium").option("--composer <provider>", "Batch composer: claude|openai|gemini").option("--max-cost <usd>", "Fail before provider spend when estimated cost exceeds this USD cap").option("--skip-narration", "Don't dispatch TTS even when beats declare narration cues").option("--skip-backdrop", "Don't dispatch image-gen even when beats declare backdrop cues").option("--skip-video", "Don't dispatch video generation even when beats declare video cues").option("--skip-music", "Don't dispatch music generation even when beats declare music cues").option("--skip-render", "Compose only \u2014 don't render to MP4").option("--tts <provider>", "TTS provider: auto|elevenlabs|openai|kokoro").option("--voice <id>", "Voice id").option("--image-provider <name>", `Image provider: ${VALID_IMAGE_PROVIDERS2.join("|")}`).option("--video-provider <name>", `Video provider: ${VALID_VIDEO_PROVIDERS2.join("|")}`).option("--music-provider <name>", `Music provider: ${VALID_MUSIC_PROVIDERS2.join("|")}`).option("--quality <q>", "Image quality: standard|hd", "hd").option("--image-size <s>", "Image size: 1024x1024|1536x1024|1024x1536", "1536x1024").option("--force", "Re-dispatch primitives even when assets already exist").option("--dry-run", "Preview parameters without dispatching").addHelpText(
+var buildCommand = new Command("build").description("Build a VibeFrame video project from STORYBOARD.md").argument("[project-dir]", "Video project directory", ".").option("--stage <stage>", `Build stage: ${VALID_STAGES2.join("|")}`, "all").option("--beat <id>", "Restrict asset/compose work to one beat id").option("--mode <mode>", "Build mode: agent|batch|auto", "auto").option("--effort <level>", "Compose effort tier (batch mode only): low|medium|high", "medium").option("--composer <provider>", "Batch composer: claude|openai|gemini").option("--max-cost <usd>", "Fail before provider spend when estimated cost exceeds this USD cap").option("--skip-narration", "Don't dispatch TTS even when beats declare narration cues").option("--skip-backdrop", "Don't dispatch image-gen even when beats declare backdrop cues").option("--skip-video", "Don't dispatch video generation even when beats declare video cues").option(
+  "--skip-keyframe",
+  "Don't generate keyframe stills (review keyframes first with --skip-video, then build)"
+).option("--skip-music", "Don't dispatch music generation even when beats declare music cues").option("--skip-render", "Compose only \u2014 don't render to MP4").option("--tts <provider>", "TTS provider: auto|elevenlabs|openai|kokoro").option("--voice <id>", "Voice id").option("--image-provider <name>", `Image provider: ${VALID_IMAGE_PROVIDERS2.join("|")}`).option("--video-provider <name>", `Video provider: ${VALID_VIDEO_PROVIDERS2.join("|")}`).option("--music-provider <name>", `Music provider: ${VALID_MUSIC_PROVIDERS2.join("|")}`).option("--quality <q>", "Image quality: standard|hd", "hd").option("--image-size <s>", "Image size: 1024x1024|1536x1024|1024x1536", "1536x1024").option("--force", "Re-dispatch primitives even when assets already exist").option("--dry-run", "Preview parameters without dispatching").addHelpText(
   "after",
   `
 Examples:
@@ -85164,6 +85199,7 @@ Advanced equivalent: \`vibe scene build\`.`
     skipNarration: options.skipNarration ?? false,
     skipBackdrop: options.skipBackdrop ?? false,
     skipVideo: options.skipVideo ?? false,
+    skipKeyframe: options.skipKeyframe ?? false,
     skipMusic: options.skipMusic ?? false,
     skipRender: options.skipRender ?? false,
     ttsProvider: options.tts,
@@ -85184,6 +85220,7 @@ Advanced equivalent: \`vibe scene build\`.`
       skipNarration: options.skipNarration,
       skipBackdrop: options.skipBackdrop,
       skipVideo: options.skipVideo,
+      skipKeyframe: options.skipKeyframe,
       skipMusic: options.skipMusic,
       ttsProvider: options.tts,
       voice: options.voice,
@@ -85274,6 +85311,7 @@ Advanced equivalent: \`vibe scene build\`.`
     skipNarration: options.skipNarration,
     skipBackdrop: options.skipBackdrop,
     skipVideo: options.skipVideo,
+    skipKeyframe: options.skipKeyframe,
     skipMusic: options.skipMusic,
     skipRender: options.skipRender,
     ttsProvider: options.tts,

package/dist/tools/manifest/index.js

@@ -33679,6 +33679,14 @@ async function createBuildPlan(opts) {
       duration: beat.duration,
       keyframe: keyframePrompt
     }) : null;
+    const keyframeCache = keyframePrompt ? keyframeCacheDescriptor({
+      beatId: beat.id,
+      cue: keyframePrompt,
+      provider: resolved.image.resolved,
+      quality: imageQuality,
+      size: imageSize2,
+      ratio: imageRatio
+    }) : null;
     const musicCache = musicPrompt && !musicReference ? musicCacheDescriptor({
       beatId: beat.id,
       cue: musicPrompt,
@@ -33714,6 +33722,19 @@ async function createBuildPlan(opts) {
       cost: backdropCostUsd(imageQuality),
       active: includeAssets
     }) : null;
+    const keyframe = keyframePrompt && !opts.skipKeyframe ? assetPlan({
+      kind: "keyframe",
+      beatId: beat.id,
+      cue: keyframePrompt,
+      provider: resolved.image.resolved,
+      path: `assets/keyframe-${beat.id}.png`,
+      cache: keyframeCache,
+      reference: null,
+      projectDir,
+      force: opts.force,
+      cost: backdropCostUsd(imageQuality),
+      active: includeAssets
+    }) : null;
     const video = videoCue && !opts.skipVideo ? assetPlan({
       kind: "video",
       beatId: beat.id,
@@ -33746,7 +33767,7 @@ async function createBuildPlan(opts) {
     }) : null;
     const compositionPath = `compositions/scene-${beat.id}.html`;
     const compositionExists = existsSync17(join15(projectDir, compositionPath));
-    for (const asset of [narration, backdrop, video, music]) {
+    for (const asset of [narration, backdrop, keyframe, video, music]) {
       if (!asset) continue;
       if (asset.referenceError) {
         missing.add("assets");
@@ -33771,13 +33792,9 @@ async function createBuildPlan(opts) {
     if (narration?.willGenerate) noteProviderNeed(resolved.narration, "Narration");
     if (backdrop?.willGenerate && isSupportedBuildImageProvider(resolved.image.resolved))
       noteProviderNeed(resolved.image, "Backdrop generation");
+    if (keyframe?.willGenerate && isSupportedBuildImageProvider(resolved.image.resolved))
+      noteProviderNeed(resolved.image, "Keyframe 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") {
@@ -33790,7 +33807,7 @@ async function createBuildPlan(opts) {
       heading: beat.heading,
       durationSec: beat.duration ?? null,
       cues: cue,
-      assets: { narration, backdrop, video, music },
+      assets: { narration, backdrop, keyframe, video, music },
       composition: {
         path: compositionPath,
         exists: compositionExists
@@ -34006,6 +34023,7 @@ function providerResolutionsForPlan(resolved, beats, opts, includeAssets) {
   return [
     includeAssets && !opts.skipNarration && needsProvider("narration") ? resolved.narration : null,
     includeAssets && !opts.skipBackdrop && needsProvider("backdrop") ? resolved.image : null,
+    includeAssets && !opts.skipKeyframe && needsProvider("keyframe") ? resolved.image : null,
     includeAssets && !opts.skipVideo && needsProvider("video") ? resolved.video : null,
     includeAssets && !opts.skipMusic && needsProvider("music") ? resolved.music : null,
     resolved.composer ?? null
@@ -34566,10 +34584,17 @@ async function executeSceneBuild(opts) {
   const onProgress = opts.onProgress ?? (() => {
   });
   const mode = resolveSceneBuildMode(opts);
-  const selectedStage = opts.stage ?? (opts.skipRender ? "sync" : "all");
+  let selectedStage = opts.stage ?? (opts.skipRender ? "sync" : "all");
+  const skipVideoStopsRender = (opts.skipVideo ?? false) && (selectedStage === "all" || selectedStage === "render");
+  if (skipVideoStopsRender) selectedStage = "sync";
   const stageReports = createEmptyStageReports();
   const warnings = [];
   const retryWith = [];
+  if (skipVideoStopsRender) {
+    warnings.push(
+      "--skip-video: skipped render (no clips to capture). Review assets/keyframe-*.png, then build without --skip-video to animate them."
+    );
+  }
   let sceneRepair = skippedSceneRepairSummary();
   const storyboardPath = join16(projectDir, "STORYBOARD.md");
   const buildPlan = await createBuildPlan({
@@ -34580,6 +34605,7 @@ async function executeSceneBuild(opts) {
     skipNarration: opts.skipNarration,
     skipBackdrop: opts.skipBackdrop,
     skipVideo: opts.skipVideo,
+    skipKeyframe: opts.skipKeyframe,
     skipMusic: opts.skipMusic,
     ttsProvider: opts.ttsProvider,
     voice: opts.voice,
@@ -34728,7 +34754,7 @@ async function executeSceneBuild(opts) {
   if (shouldRunStage(selectedStage, "assets")) {
     onProgress({ type: "phase-start", phase: "primitives" });
     const characterPaths = /* @__PURE__ */ new Map();
-    if (!(opts.skipVideo ?? false)) {
+    if (!((opts.skipVideo ?? false) && (opts.skipKeyframe ?? false))) {
       const referenced = /* @__PURE__ */ new Set();
       for (const beat of activeBeats) {
         for (const name of beatCharacterNames(beat.cues)) referenced.add(name);
@@ -34765,6 +34791,7 @@ async function executeSceneBuild(opts) {
         skipNarration: opts.skipNarration ?? false,
         skipBackdrop: opts.skipBackdrop ?? false,
         skipVideo: opts.skipVideo ?? false,
+        skipKeyframe: opts.skipKeyframe ?? false,
         skipMusic: opts.skipMusic ?? false,
         force: opts.force ?? false,
         onProgress,
@@ -35141,10 +35168,11 @@ async function executeSceneBuild(opts) {
   });
 }
 async function buildBeatPrimitives(beat, ctx) {
+  const keyframe = ctx.skipKeyframe ? await skipped("keyframe", beat.id, "--skip-keyframe", ctx) : await dispatchKeyframe(beat, ctx);
   const [narration, backdrop, video, music] = await Promise.all([
     ctx.skipNarration ? skipped("narration", beat.id, "--skip-narration", ctx) : dispatchNarration(beat, ctx),
     ctx.skipBackdrop ? skipped("backdrop", beat.id, "--skip-backdrop", ctx) : dispatchBackdrop(beat, ctx),
-    ctx.skipVideo ? skipped("video", beat.id, "--skip-video", ctx) : dispatchVideo(beat, ctx),
+    ctx.skipVideo ? skipped("video", beat.id, "--skip-video", ctx) : dispatchVideo(beat, ctx, keyframe),
     ctx.skipMusic ? skipped("music", beat.id, "--skip-music", ctx) : dispatchMusic(beat, ctx)
   ]);
   return {
@@ -35188,8 +35216,8 @@ async function buildBeatPrimitives(beat, ctx) {
       videoMetadataPath: video.metadataPath,
       videoFreshness: video.freshness,
       videoSourcePath: video.sourcePath,
-      keyframeStatus: video.keyframeStatus,
-      keyframePath: video.keyframePath,
+      keyframeStatus: keyframe.status,
+      keyframePath: keyframe.path,
       musicStatus: music.status,
       musicPath: music.path,
       musicJobId: music.job?.id,
@@ -35760,7 +35788,21 @@ function imageProviderKeyInfo(provider) {
   if (provider === "grok") return { configKey: "xai", envVar: "XAI_API_KEY" };
   return { configKey: "openai", envVar: "OPENAI_API_KEY" };
 }
-async function dispatchVideo(beat, ctx) {
+async function dispatchKeyframe(beat, ctx) {
+  const keyframeCue = stringOrUndefined4(beat.cues?.keyframe);
+  if (!keyframeCue) return { status: "no-cue" };
+  const characterRefsRel = beatCharacterNames(beat.cues).map((name) => ctx.characterPaths?.get(name)).filter((p) => typeof p === "string");
+  const kf = await ensureKeyframe(beat, ctx, keyframeCue, characterRefsRel);
+  if (kf.status === "failed") {
+    ctx.onProgress({ type: "keyframe-failed", beatId: beat.id, error: kf.error });
+    return { status: "failed", error: kf.error };
+  }
+  ctx.onProgress(
+    kf.status === "cached" ? { type: "keyframe-cached", beatId: beat.id, path: kf.rel } : { type: "keyframe-generated", beatId: beat.id, path: kf.rel, provider: ctx.imageProvider }
+  );
+  return { status: kf.status, path: kf.rel, provider: ctx.imageProvider };
+}
+async function dispatchVideo(beat, ctx, keyframe) {
   const reference = assetReferenceForBeat(ctx.projectDir, "video", beat);
   if (reference) return referencePrimitiveOutcome("video", beat, ctx, reference);
   const keyframeCue = stringOrUndefined4(beat.cues?.keyframe);
@@ -35830,20 +35872,14 @@ async function dispatchVideo(beat, ctx) {
       freshness: "fresh"
     };
   }
-  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 = join16(ctx.projectDir, kf.rel);
+  const keyframeImageRel = keyframeCue && (keyframe.status === "generated" || keyframe.status === "cached") ? keyframe.path : void 0;
+  if (keyframeCue && !keyframeImageRel) {
+    const reason = keyframe.status === "failed" ? `keyframe unavailable: ${keyframe.error ?? "generation failed"}` : "keyframe not generated (build without --skip-keyframe first)";
+    ctx.onProgress({ type: "video-skipped", beatId: beat.id, reason });
+    return { status: "skipped" };
   }
+  const keyframeImageAbs = keyframeImageRel ? join16(ctx.projectDir, keyframeImageRel) : void 0;
+  loadSceneBuildEnv(ctx.projectDir);
   const result = await executeVideoGenerate({
     prompt: prompt3,
     provider: ctx.videoProvider,
@@ -35889,9 +35925,7 @@ async function dispatchVideo(beat, ctx) {
       cachePath: cache.path,
       cacheKey: cache.key,
       metadataPath,
-      freshness: "fresh",
-      keyframeStatus,
-      keyframePath: keyframeRel
+      freshness: "fresh"
     };
   }
   const job = await createAndWriteJobRecord({
@@ -35923,9 +35957,7 @@ async function dispatchVideo(beat, ctx) {
     provider: job.provider,
     cachePath: cache.path,
     cacheKey: cache.key,
-    metadataPath,
-    keyframeStatus,
-    keyframePath: keyframeRel
+    metadataPath
   };
 }
 async function dispatchMusic(beat, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/cli",
-  "version": "0.113.3",
+  "version": "0.113.5",
   "description": "VibeFrame CLI - agentic video workflow runtime",
   "private": false,
   "license": "MIT",
@@ -83,8 +83,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/core": "0.113.3",
-    "@vibeframe/ai-providers": "0.113.3"
+    "@vibeframe/ai-providers": "0.113.5",
+    "@vibeframe/core": "0.113.5"
   },
   "engines": {
     "node": ">=20"