@vibeframe/cli 0.108.0 → 0.109.0

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

@@ -85,6 +85,25 @@ export declare function isEpsilonOverlapFinding(finding: LintFinding): boolean;
  * findings pass through unchanged.
  */
 export declare function filterSubCompFalsePositives(findings: LintFinding[], isSubComposition: boolean): LintFinding[];
+/**
+ * VibeFrame-side finding: inner phase clips inside a sub-composition.
+ *
+ * The producer's screenshot render mode does NOT toggle the visibility of
+ * `.clip` elements INSIDE a sub-composition by their `data-start` window —
+ * a scene split into clip phases (0-10s, 10-26s) renders BOTH phases
+ * simultaneously and text stacks on top of itself. Root index.html clips
+ * are unaffected (their windows work); this rule only applies to
+ * sub-composition internals. Phase changes must instead be driven by GSAP
+ * (animate the old phase out with autoAlpha, the new one in) inside
+ * full-window clips.
+ */
+export declare function findInternalPhaseClipFindings(html: string): LintFinding[];
+/**
+ * Append VibeFrame-side findings for sub-composition HTML. Call at every
+ * lint site (batch composer, scene_submit, scene repair, project lint) so
+ * all authoring paths share the exact same contract.
+ */
+export declare function withVibeframeSubCompFindings(findings: LintFinding[], html: string, isSubComposition: boolean): LintFinding[];
 /**
  * Apply mechanical `--fix` rewrites for known-safe finding codes. Returns the
  * (possibly unchanged) HTML and the list of codes that were fixed at least

package/dist/commands/_shared/storyboard-edit.d.ts

@@ -12,6 +12,8 @@ export interface StoryboardValidationResult {
     beats: Beat[];
     issues: StoryboardValidationIssue[];
 }
+/** Beats beyond this render as static, overstuffed scenes. */
+export declare const MAX_RECOMMENDED_BEAT_SEC = 15;
 export declare function validateStoryboardMarkdown(markdown: string): StoryboardValidationResult;
 export declare function getStoryboardBeat(markdown: string, beatId: string): Beat | null;
 export declare function setStoryboardCue(markdown: string, opts: {

package/dist/index.js

@@ -11604,13 +11604,32 @@ async function loadKokoroFactory() {
     const mod = await import("kokoro-js");
     return mod.KokoroTTS;
   } catch (err) {
+    const fallback2 = await loadKokoroFromWorkspace();
+    if (fallback2)
+      return fallback2;
     throw mapKokoroImportError(err);
   }
 }
+async function loadKokoroFromWorkspace(baseDir = process.cwd()) {
+  try {
+    const { readFile: readFile55 } = await import("node:fs/promises");
+    const { join: join29, resolve: resolve85 } = await import("node:path");
+    const { pathToFileURL } = await import("node:url");
+    const pkgDir = resolve85(baseDir, "node_modules", "kokoro-js");
+    const pkg = JSON.parse(await readFile55(join29(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(join29(pkgDir, entry)).href);
+    return mod.KokoroTTS ?? null;
+  } catch {
+    return null;
+  }
+}
 function mapKokoroImportError(err) {
   const code = err instanceof Error && "code" in err ? err.code : void 0;
   if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
-    return new Error("Local Kokoro TTS is unavailable: optional dependency kokoro-js is not installed (its native dependencies may have failed to build on this platform). Install it with `npm i kokoro-js`, or set ELEVENLABS_API_KEY to use the elevenlabs TTS provider instead.");
+    return new Error("Local Kokoro TTS is unavailable: optional dependency kokoro-js is not installed (its native dependencies may have failed to build on this platform). Install it with `npm i kokoro-js` \u2014 run it inside your workspace folder when using the Claude Desktop extension \u2014 or set ELEVENLABS_API_KEY to use the elevenlabs TTS provider instead.");
   }
   return err instanceof Error ? err : new Error(String(err));
 }
@@ -26662,6 +26681,8 @@ imageProvider: openai
 
 Edit these beats before running \`vibe build\`. Each beat starts with
 YAML cues that drive narration, backdrop generation, and timing.
+Pacing: keep beats 6-15 seconds (split longer ones); a 90s video should
+have 6-8 beats, not 3 long ones.
 
 ## Beat hook \u2014 Hook
 
@@ -27778,6 +27799,29 @@ function filterSubCompFalsePositives(findings, isSubComposition) {
   if (!isSubComposition) return noEpsilon;
   return noEpsilon.filter((f) => !SUB_COMP_FALSE_POSITIVES.has(f.code));
 }
+function findInternalPhaseClipFindings(html) {
+  const findings = [];
+  for (const tagMatch of html.matchAll(/<[a-z][a-z0-9-]*\s[^>]*>/gi)) {
+    const tag = tagMatch[0];
+    if (!/class="[^"]*\bclip\b[^"]*"/i.test(tag)) continue;
+    const startAttr = tag.match(/data-start="([^"]+)"/i);
+    if (!startAttr) continue;
+    const start = Number(startAttr[1]);
+    if (!Number.isFinite(start) || start === 0) continue;
+    findings.push({
+      code: "internal_phase_clip_unsupported",
+      severity: "error",
+      message: `Inner .clip has data-start="${startAttr[1]}". The renderer does not toggle internal clip visibility inside sub-compositions, so phased clips render ALL phases at once (overlapping text).`,
+      fixHint: 'Give every inner .clip data-start="0" spanning the full beat, and drive phase changes with GSAP autoAlpha instead (animate the previous phase out, the next one in).',
+      snippet: tag.slice(0, 120)
+    });
+  }
+  return findings;
+}
+function withVibeframeSubCompFindings(findings, html, isSubComposition) {
+  if (!isSubComposition) return findings;
+  return [...findings, ...findInternalPhaseClipFindings(html)];
+}
 function applyMechanicalFixes(html, findings) {
   const fixedCodes = /* @__PURE__ */ new Set();
   let updated = html;
@@ -27823,7 +27867,11 @@ async function runProjectLint(opts) {
       source: "projectDir"
     };
     const raw = runHyperframeLint(prepared);
-    const findings = filterSubCompFalsePositives(raw.findings, isSub);
+    const findings = withVibeframeSubCompFindings(
+      filterSubCompFalsePositives(raw.findings, isSub),
+      html,
+      isSub
+    );
     if (opts.fix && findings.length > 0) {
       const { html: nextHtml, fixedCodes } = applyMechanicalFixes(html, findings);
       if (fixedCodes.length > 0) {
@@ -27833,7 +27881,11 @@ async function runProjectLint(opts) {
         files.push({
           file: rel,
           isSubComposition: isSub,
-          findings: filterSubCompFalsePositives(reLinted.findings, isSub)
+          findings: withVibeframeSubCompFindings(
+            filterSubCompFalsePositives(reLinted.findings, isSub),
+            nextHtml,
+            isSub
+          )
         });
         continue;
       }
@@ -29713,8 +29765,14 @@ ${finalDurationBullet}
   Animate the backdrop/media plane instead; let text enter briefly, then hold
   still at its final CSS position. Continuous transforms on text ancestors can
   create subpixel shimmer in screenshot-captured renders.
-- Timed children inside the composition have \`class="clip"\` plus
-  \`data-start\`, \`data-duration\`, \`data-track-index\`.
+- Inner \`.clip\` elements carry \`data-start\`, \`data-duration\`,
+  \`data-track-index\` \u2014 but **every inner clip MUST be full-window:
+  \`data-start="0"\` spanning the whole beat.** The renderer does NOT toggle
+  internal clip visibility inside sub-compositions, so "phase clips" with a
+  non-zero \`data-start\` render ALL phases at once and text stacks on top of
+  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
   full-frame visual backdrop. The exact path string is
   \`assets/backdrop-${ctx.beat.id}.png\`; do NOT prefix it with \`../\` or \`./\`
@@ -29728,7 +29786,9 @@ ${finalDurationBullet}
   narration.
 - Keep a meaningful visual progression across the full beat duration: line
   tracing, gentle camera drift, staged labels, value cards, or parallax. Avoid
-  a completed static frame holding silently for most of the beat.
+  a completed static frame holding silently for most of the beat. For longer
+  beats, progress through content phases with GSAP autoAlpha (old phase out,
+  new phase in) \u2014 never with inner clip windows.
 - Do not import external font or image URLs. Use the project DESIGN.md font
   choice when explicit; otherwise use \`Inter\`, which is available in the
   deterministic render font map.
@@ -29903,7 +29963,11 @@ function lintBeatHtml(html, beatId) {
     source: "projectDir"
   };
   const raw = runHyperframeLint2(prepared);
-  const findings = filterSubCompFalsePositives(raw.findings, true);
+  const findings = withVibeframeSubCompFindings(
+    filterSubCompFalsePositives(raw.findings, true),
+    html,
+    true
+  );
   return {
     errorCount: findings.filter((f) => f.severity === "error").length,
     warningCount: findings.filter((f) => f.severity === "warning").length,
@@ -30338,7 +30402,8 @@ function buildInstructions(args) {
   lines.push(`2. Read \`DESIGN.md\` for project-specific palette, typography, motion signature.`);
   lines.push(`3. For each beat in the \`beats\` array below, author HTML at \`outputPath\` matching the \`userPrompt\`. The beat \`body\` carries the narrative + visual + animation intent; \`cues\` carries machine-readable per-beat overrides (narration, duration, backdrop, voice).`);
   lines.push(`3b. Use each beat's \`finalDurationSec\` (narration-synced) for \`data-duration\` and timeline anchors when present \u2014 NOT the storyboard \`duration\`, which is only the minimum. Scenes composed at the storyboard duration end early and render black tails.`);
-  lines.push(`3c. If your environment cannot write files (e.g. Claude Desktop / MCP-only hosts), author each beat's HTML and submit it with the \`scene_submit\` tool (beat id + html). It validates with the same Hyperframes lint and writes the file for you; on lint errors it returns the findings without writing \u2014 fix and resubmit.`);
+  lines.push(`3c. Never give inner \`.clip\` elements a non-zero \`data-start\` \u2014 the renderer does not toggle internal clip visibility inside sub-compositions, so phased clips render all phases at once (overlapping text). Use full-window clips and GSAP autoAlpha phase transitions instead. Also keep beats 6-15s; split anything longer in the storyboard first.`);
+  lines.push(`3d. If your environment cannot write files (e.g. Claude Desktop / MCP-only hosts), author each beat's HTML and submit it with the \`scene_submit\` tool (beat id + html). It validates with the same Hyperframes lint and writes the file for you; on lint errors it returns the findings without writing \u2014 fix and resubmit.`);
   if (args.beatCount > 1) {
     lines.push(`4. After authoring all ${args.beatCount} beat(s), run \`vibe scene lint --fix\` to validate. Fix any remaining errors by editing the HTML directly.`);
   } else if (args.filtered) {
@@ -30780,7 +30845,11 @@ function lintHtml(html, rel, isSub) {
     source: "projectDir"
   };
   const raw = runHyperframeLint3(prepared);
-  return filterSubCompFalsePositives(raw.findings, isSub);
+  return withVibeframeSubCompFindings(
+    filterSubCompFalsePositives(raw.findings, isSub),
+    html,
+    isSub
+  );
 }
 function lintFilesToIssues(files) {
   const issues = [];
@@ -44130,6 +44199,16 @@ function validateStoryboardMarkdown(markdown) {
       }
     }
   }
+  for (const beat of parsed.beats) {
+    if (beat.duration !== void 0 && beat.duration > MAX_RECOMMENDED_BEAT_SEC) {
+      issues.push({
+        severity: "warning",
+        code: "BEAT_DURATION_TOO_LONG",
+        beatId: beat.id,
+        message: `Beat "${beat.id}" is ${beat.duration}s \u2014 beats longer than ${MAX_RECOMMENDED_BEAT_SEC}s render static and overstuffed. Split it into 6-15s beats (a 90s video should have 6-8 beats).`
+      });
+    }
+  }
   return {
     ok: !issues.some((i) => i.severity === "error"),
     beats: parsed.beats,
@@ -44228,7 +44307,7 @@ function readLeadingCueBlock(body) {
     return { full: match[0], error: error instanceof Error ? error.message : String(error) };
   }
 }
-var import_yaml5, STORYBOARD_CUE_KEYS, HEADING_RE2, LEADING_CUE_RE, ALLOWED_CUE_KEYS, STRING_CUE_KEYS;
+var import_yaml5, STORYBOARD_CUE_KEYS, HEADING_RE2, LEADING_CUE_RE, ALLOWED_CUE_KEYS, STRING_CUE_KEYS, MAX_RECOMMENDED_BEAT_SEC;
 var init_storyboard_edit = __esm({
   "src/commands/_shared/storyboard-edit.ts"() {
     "use strict";
@@ -44248,6 +44327,7 @@ var init_storyboard_edit = __esm({
     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;
   }
 });
 
@@ -59092,7 +59172,8 @@ function revisionMessages(opts) {
     "The JSON object must have: storyboardMd string, summary string, changedBeats string[], warnings string[].",
     "Preserve existing frontmatter, beat ids, cue YAML keys, and useful prose unless the user asks to change structure.",
     "Keep cue YAML valid. Allowed cue keys are duration, narration, backdrop, video, motion, voice, music, asset.",
-    "If a target duration is supplied, every beat must have a positive duration cue and durations must sum to that target."
+    "If a target duration is supplied, every beat must have a positive duration cue and durations must sum to that target.",
+    "Aim for 6-15 seconds per beat and never exceed ~15s \u2014 long beats render as static, overstuffed scenes. A 90-second video should have 6-8 beats."
   ].join("\n");
   const repairBlock = opts.invalidStoryboard ? [
     "The previous revision failed validation. Repair it.",
@@ -72828,7 +72909,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.108.0",
+  version: "0.109.0",
   description: "VibeFrame CLI - agentic video workflow runtime",
   private: false,
   license: "MIT",
@@ -81287,6 +81368,9 @@ providers:
 
 # ${product} - Storyboard
 
+Pacing: keep beats 6-15 seconds. Longer beats render as static, overstuffed
+scenes \u2014 split them instead.
+
 Brief: ${brief}
 
 ${beats.map(renderBeatDraft).join("\n\n")}

package/dist/tools/manifest/index.js

@@ -4729,13 +4729,32 @@ async function loadKokoroFactory() {
     const mod = await import("kokoro-js");
     return mod.KokoroTTS;
   } catch (err) {
+    const fallback2 = await loadKokoroFromWorkspace();
+    if (fallback2)
+      return fallback2;
     throw mapKokoroImportError(err);
   }
 }
+async function loadKokoroFromWorkspace(baseDir = process.cwd()) {
+  try {
+    const { readFile: readFile44 } = await import("node:fs/promises");
+    const { join: join26, resolve: resolve65 } = await import("node:path");
+    const { pathToFileURL } = await import("node:url");
+    const pkgDir = resolve65(baseDir, "node_modules", "kokoro-js");
+    const pkg = JSON.parse(await readFile44(join26(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(join26(pkgDir, entry)).href);
+    return mod.KokoroTTS ?? null;
+  } catch {
+    return null;
+  }
+}
 function mapKokoroImportError(err) {
   const code = err instanceof Error && "code" in err ? err.code : void 0;
   if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
-    return new Error("Local Kokoro TTS is unavailable: optional dependency kokoro-js is not installed (its native dependencies may have failed to build on this platform). Install it with `npm i kokoro-js`, or set ELEVENLABS_API_KEY to use the elevenlabs TTS provider instead.");
+    return new Error("Local Kokoro TTS is unavailable: optional dependency kokoro-js is not installed (its native dependencies may have failed to build on this platform). Install it with `npm i kokoro-js` \u2014 run it inside your workspace folder when using the Claude Desktop extension \u2014 or set ELEVENLABS_API_KEY to use the elevenlabs TTS provider instead.");
   }
   return err instanceof Error ? err : new Error(String(err));
 }
@@ -25266,6 +25285,8 @@ imageProvider: openai
 
 Edit these beats before running \`vibe build\`. Each beat starts with
 YAML cues that drive narration, backdrop generation, and timing.
+Pacing: keep beats 6-15 seconds (split longer ones); a 90s video should
+have 6-8 beats, not 3 long ones.
 
 ## Beat hook \u2014 Hook
 
@@ -28829,6 +28850,29 @@ function filterSubCompFalsePositives(findings, isSubComposition) {
   if (!isSubComposition) return noEpsilon;
   return noEpsilon.filter((f) => !SUB_COMP_FALSE_POSITIVES.has(f.code));
 }
+function findInternalPhaseClipFindings(html) {
+  const findings = [];
+  for (const tagMatch of html.matchAll(/<[a-z][a-z0-9-]*\s[^>]*>/gi)) {
+    const tag = tagMatch[0];
+    if (!/class="[^"]*\bclip\b[^"]*"/i.test(tag)) continue;
+    const startAttr = tag.match(/data-start="([^"]+)"/i);
+    if (!startAttr) continue;
+    const start = Number(startAttr[1]);
+    if (!Number.isFinite(start) || start === 0) continue;
+    findings.push({
+      code: "internal_phase_clip_unsupported",
+      severity: "error",
+      message: `Inner .clip has data-start="${startAttr[1]}". The renderer does not toggle internal clip visibility inside sub-compositions, so phased clips render ALL phases at once (overlapping text).`,
+      fixHint: 'Give every inner .clip data-start="0" spanning the full beat, and drive phase changes with GSAP autoAlpha instead (animate the previous phase out, the next one in).',
+      snippet: tag.slice(0, 120)
+    });
+  }
+  return findings;
+}
+function withVibeframeSubCompFindings(findings, html, isSubComposition) {
+  if (!isSubComposition) return findings;
+  return [...findings, ...findInternalPhaseClipFindings(html)];
+}
 function applyMechanicalFixes(html, findings) {
   const fixedCodes = /* @__PURE__ */ new Set();
   let updated = html;
@@ -28874,7 +28918,11 @@ async function runProjectLint(opts) {
       source: "projectDir"
     };
     const raw = runHyperframeLint(prepared);
-    const findings = filterSubCompFalsePositives(raw.findings, isSub);
+    const findings = withVibeframeSubCompFindings(
+      filterSubCompFalsePositives(raw.findings, isSub),
+      html,
+      isSub
+    );
     if (opts.fix && findings.length > 0) {
       const { html: nextHtml, fixedCodes } = applyMechanicalFixes(html, findings);
       if (fixedCodes.length > 0) {
@@ -28884,7 +28932,11 @@ async function runProjectLint(opts) {
         files.push({
           file: rel,
           isSubComposition: isSub,
-          findings: filterSubCompFalsePositives(reLinted.findings, isSub)
+          findings: withVibeframeSubCompFindings(
+            filterSubCompFalsePositives(reLinted.findings, isSub),
+            nextHtml,
+            isSub
+          )
         });
         continue;
       }
@@ -30419,8 +30471,14 @@ ${finalDurationBullet}
   Animate the backdrop/media plane instead; let text enter briefly, then hold
   still at its final CSS position. Continuous transforms on text ancestors can
   create subpixel shimmer in screenshot-captured renders.
-- Timed children inside the composition have \`class="clip"\` plus
-  \`data-start\`, \`data-duration\`, \`data-track-index\`.
+- Inner \`.clip\` elements carry \`data-start\`, \`data-duration\`,
+  \`data-track-index\` \u2014 but **every inner clip MUST be full-window:
+  \`data-start="0"\` spanning the whole beat.** The renderer does NOT toggle
+  internal clip visibility inside sub-compositions, so "phase clips" with a
+  non-zero \`data-start\` render ALL phases at once and text stacks on top of
+  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
   full-frame visual backdrop. The exact path string is
   \`assets/backdrop-${ctx.beat.id}.png\`; do NOT prefix it with \`../\` or \`./\`
@@ -30434,7 +30492,9 @@ ${finalDurationBullet}
   narration.
 - Keep a meaningful visual progression across the full beat duration: line
   tracing, gentle camera drift, staged labels, value cards, or parallax. Avoid
-  a completed static frame holding silently for most of the beat.
+  a completed static frame holding silently for most of the beat. For longer
+  beats, progress through content phases with GSAP autoAlpha (old phase out,
+  new phase in) \u2014 never with inner clip windows.
 - Do not import external font or image URLs. Use the project DESIGN.md font
   choice when explicit; otherwise use \`Inter\`, which is available in the
   deterministic render font map.
@@ -30609,7 +30669,11 @@ function lintBeatHtml(html, beatId) {
     source: "projectDir"
   };
   const raw = runHyperframeLint2(prepared);
-  const findings = filterSubCompFalsePositives(raw.findings, true);
+  const findings = withVibeframeSubCompFindings(
+    filterSubCompFalsePositives(raw.findings, true),
+    html,
+    true
+  );
   return {
     errorCount: findings.filter((f) => f.severity === "error").length,
     warningCount: findings.filter((f) => f.severity === "warning").length,
@@ -31044,7 +31108,8 @@ function buildInstructions(args) {
   lines.push(`2. Read \`DESIGN.md\` for project-specific palette, typography, motion signature.`);
   lines.push(`3. For each beat in the \`beats\` array below, author HTML at \`outputPath\` matching the \`userPrompt\`. The beat \`body\` carries the narrative + visual + animation intent; \`cues\` carries machine-readable per-beat overrides (narration, duration, backdrop, voice).`);
   lines.push(`3b. Use each beat's \`finalDurationSec\` (narration-synced) for \`data-duration\` and timeline anchors when present \u2014 NOT the storyboard \`duration\`, which is only the minimum. Scenes composed at the storyboard duration end early and render black tails.`);
-  lines.push(`3c. If your environment cannot write files (e.g. Claude Desktop / MCP-only hosts), author each beat's HTML and submit it with the \`scene_submit\` tool (beat id + html). It validates with the same Hyperframes lint and writes the file for you; on lint errors it returns the findings without writing \u2014 fix and resubmit.`);
+  lines.push(`3c. Never give inner \`.clip\` elements a non-zero \`data-start\` \u2014 the renderer does not toggle internal clip visibility inside sub-compositions, so phased clips render all phases at once (overlapping text). Use full-window clips and GSAP autoAlpha phase transitions instead. Also keep beats 6-15s; split anything longer in the storyboard first.`);
+  lines.push(`3d. If your environment cannot write files (e.g. Claude Desktop / MCP-only hosts), author each beat's HTML and submit it with the \`scene_submit\` tool (beat id + html). It validates with the same Hyperframes lint and writes the file for you; on lint errors it returns the findings without writing \u2014 fix and resubmit.`);
   if (args.beatCount > 1) {
     lines.push(`4. After authoring all ${args.beatCount} beat(s), run \`vibe scene lint --fix\` to validate. Fix any remaining errors by editing the HTML directly.`);
   } else if (args.filtered) {
@@ -31367,7 +31432,11 @@ function lintHtml(html, rel, isSub) {
     source: "projectDir"
   };
   const raw = runHyperframeLint3(prepared);
-  return filterSubCompFalsePositives(raw.findings, isSub);
+  return withVibeframeSubCompFindings(
+    filterSubCompFalsePositives(raw.findings, isSub),
+    html,
+    isSub
+  );
 }
 function lintFilesToIssues(files) {
   const issues = [];
@@ -32440,6 +32509,16 @@ function validateStoryboardMarkdown(markdown) {
       }
     }
   }
+  for (const beat of parsed.beats) {
+    if (beat.duration !== void 0 && beat.duration > MAX_RECOMMENDED_BEAT_SEC) {
+      issues.push({
+        severity: "warning",
+        code: "BEAT_DURATION_TOO_LONG",
+        beatId: beat.id,
+        message: `Beat "${beat.id}" is ${beat.duration}s \u2014 beats longer than ${MAX_RECOMMENDED_BEAT_SEC}s render static and overstuffed. Split it into 6-15s beats (a 90s video should have 6-8 beats).`
+      });
+    }
+  }
   return {
     ok: !issues.some((i) => i.severity === "error"),
     beats: parsed.beats,
@@ -32538,7 +32617,7 @@ function readLeadingCueBlock(body) {
     return { full: match[0], error: error instanceof Error ? error.message : String(error) };
   }
 }
-var import_yaml5, STORYBOARD_CUE_KEYS, HEADING_RE2, LEADING_CUE_RE, ALLOWED_CUE_KEYS, STRING_CUE_KEYS;
+var import_yaml5, STORYBOARD_CUE_KEYS, HEADING_RE2, LEADING_CUE_RE, ALLOWED_CUE_KEYS, STRING_CUE_KEYS, MAX_RECOMMENDED_BEAT_SEC;
 var init_storyboard_edit = __esm({
   "src/commands/_shared/storyboard-edit.ts"() {
     "use strict";
@@ -32558,6 +32637,7 @@ var init_storyboard_edit = __esm({
     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;
   }
 });
 
@@ -56751,7 +56831,8 @@ function revisionMessages(opts) {
     "The JSON object must have: storyboardMd string, summary string, changedBeats string[], warnings string[].",
     "Preserve existing frontmatter, beat ids, cue YAML keys, and useful prose unless the user asks to change structure.",
     "Keep cue YAML valid. Allowed cue keys are duration, narration, backdrop, video, motion, voice, music, asset.",
-    "If a target duration is supplied, every beat must have a positive duration cue and durations must sum to that target."
+    "If a target duration is supplied, every beat must have a positive duration cue and durations must sum to that target.",
+    "Aim for 6-15 seconds per beat and never exceed ~15s \u2014 long beats render as static, overstuffed scenes. A 90-second video should have 6-8 beats."
   ].join("\n");
   const repairBlock = opts.invalidStoryboard ? [
     "The previous revision failed validation. Repair it.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/cli",
-  "version": "0.108.0",
+  "version": "0.109.0",
   "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/ai-providers": "0.108.0",
-    "@vibeframe/core": "0.108.0"
+    "@vibeframe/core": "0.109.0",
+    "@vibeframe/ai-providers": "0.109.0"
   },
   "engines": {
     "node": ">=20"