@milenyumai/film-kit 2.3.4 → 2.3.5

package/README.md

@@ -183,6 +183,7 @@ npx @milenyumai/film-kit generate-storyboard \
 Outputs:
 
 - `outputs/storyboard-reference-plan.json`
+- `outputs/storyboard-prompt.md`
 - `outputs/reference-prep/CHARACTER-SHEET-*.md`
 - `outputs/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md`
 - `outputs/prompt-bundles/SHOTNN.bundle.json`
@@ -196,8 +197,10 @@ Rules:
 - `@character1` is used once to create a 16:9 character sheet prompt with front, back, side, three-quarter, and face close-up views.
 - GPT Image 2 still prompts use `REFERENCE LOCK`, `Keep same`, `Change only`, and `Avoid` sections so character identity, wardrobe, props, and materials stay immutable unless explicitly changed.
 - Each `SHOTNN.md` includes a professional `GPT IMAGE 2 STORYBOARD PROMPT`; the generated shot storyboard controls composition, blocking, camera, timing, and editorial phase order only.
-- Storyboard prompts use production-board grammar: rough black-and-white pencil panels, strong silhouettes, visible body/camera momentum, and optional color-coded planning annotations. Seedance is instructed to follow the panel order while ignoring arrows, notes, labels, and timestamps in the rendered video.
+- If no external storyboard image exists, Film-Kit still generates the GPT Image 2 storyboard bootstrap prompt and writes it to both `outputs/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md` and the convenience alias `outputs/storyboard-prompt.md`.
+- Storyboard prompts use production-board grammar: 16:9 storyboard sheet, rough black-and-white pencil panels, strong silhouettes, visible body/camera momentum, cinematic camera variety, and optional color-coded planning annotations. Seedance is instructed to follow the panel order while ignoring arrows, notes, labels, and timestamps in the rendered video.
 - Seedance provider-facing tokens map generated character sheets first (`@Image1`, `@Image2`, ...) and the generated shot storyboard next. Legacy lowercase aliases remain documented in runtime text.
+- `SHOTNN.bundle.json` includes `storyboard_creation` metadata with provider, prompt path, alias path, reading order, panel count, Seedance token, annotation policy, and prompt text.
 - Speaking shots must bind `Audio Plan.activeSpeakerKey` back to project-level `voiceCast`; broken voice bindings fail QA.
 - Public-figure, celebrity, likeness, logo, trademark, or brand references in the brief, dialogue metadata, or reference metadata are blocked unless safely anonymized first.
 - Phase budget: 4-6s uses 1-2 phases, 7-10s uses 2-3 phases, and 11-15s uses 3-4 phases.
@@ -216,7 +219,7 @@ CLI flags for direct storyboard bundle generation:
 | `--models` | Comma-separated target models: `veo31`, `seedance-2.0`, `kling-3.0` |
 | `--duration` | Duration in seconds per generated shot. Seedance provider range is 4-15 seconds |
 | `--aspect` | `16:9`, `9:16`, or `1:1` |
-| `--storyboard-panel-count-hint` | Optional total panel/phase hint. 5+ phases are split when overload splitting is enabled |
+| `--storyboard-panel-count-hint` | Optional GPT Image 2 storyboard sheet panel count, `1-12`. This does not by itself split SHOT files |
 | `--max-storyboard-phases` | Upper bound per shot. Default: `4` |
 
 ## CLI

package/build/index.d.ts

@@ -4,4 +4,4 @@ export { buildStoryboardReferencePromptBundles, normalizeVideoPromptRequest, ren
 export { assertModelAllowed, getModel, getModelAdapterKey, getModelDisplayName, getReplacementModel, isActiveModelId, isDeprecatedModelId, isImageModelId, isKnownModelId, isModelSupportedByPreset, isRemovedModelId, isVideoModelId, listActiveModels, listActiveVideoModelIds, listImageModels, listModels, listModelsForPreset, listModelsForReferenceMode, listRunnableVideoModelIds, listRunnableVideoModels, listVideoModels, requireModel, validateModelAllowed } from "./lib/model-registry/index.js";
 export type { AgentConfigOptions, ConfigureFilmKitResult, ConfigureResult, FilmKitConfigFile, FilmKitConfigOptions, FilmKitPreset, GptImageFormat, GptImageQuality, GptImageSize, HybridAspectRatio, KlingPreset, NanoBananaImageSize, ReferenceMode, StoryboardReferenceConfig, SupportedModel, SupportedPlatform } from "./lib/types.js";
 export type { ActiveModelId, AudioModelId, DeprecatedModelId, ImageModelId, KnownModelId, ModelAdapterKey, ModelAllowedContext, ModelAllowedResult, ModelCapabilities, ModelLifecycleStatus, ModelModality, ModelRegistryEntry, MultimodalModelId, RemovedModelId, VideoModelId } from "./lib/model-registry/index.js";
-export type { CharacterReferenceSheetPrompt, ModelPromptOutput, ModelRouteMetadata, PromptBundle, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, SeedanceContinuityMode, ShotHandoffNote, StoryboardImagePrompt, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoPromptRequest } from "./lib/storyboard-reference/index.js";
+export type { CharacterReferenceSheetPrompt, ModelPromptOutput, ModelRouteMetadata, PromptBundle, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, SeedanceContinuityMode, ShotHandoffNote, StoryboardCreationMetadata, StoryboardImagePrompt, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoPromptRequest } from "./lib/storyboard-reference/index.js";

package/build/lib/cli.js

@@ -542,7 +542,7 @@ generate-storyboard flags:
   --dialogue           Repeatable "Speaker: exact line" value
   --audio-intent       SFX/ambience direction
   --style-intent       Visual style direction
-  --storyboard-panel-count-hint  Panel/phase count hint; 5+ panels split into multiple SHOTNN files
+  --storyboard-panel-count-hint  GPT Image 2 storyboard sheet panel count, 1-12; does not split SHOT files by itself
   --max-storyboard-phases  Upper bound per SHOTNN storyboard phase count
 
 Install:

package/build/lib/configure.js

@@ -160,6 +160,7 @@ description: Generate storyboard-reference prompt bundles from character referen
 \`\`\`text
 ${vars.outputDir}/
 ├── storyboard-reference-plan.json
+├── storyboard-prompt.md
 ├── reference-prep/
 │   └── CHARACTER-SHEET-*.md
 ├── storyboard-prompts/
@@ -187,18 +188,21 @@ ${vars.outputDir}/
    - \`maxStoryboardPhases: ${vars.maxStoryboardPhases}\`
    - \`voiceCast\` when dialogue or narration exists
    - \`visual_world\` for camera, lens, lighting, scale, reflection, physics, screen direction, and continuity anchors
-4. Split the scenario into shots by dramatic beat. Use this phase budget:
+4. Split the scenario into shots by dramatic beat. Use this video phase budget:
    - 4-6 seconds: 1-2 phases
    - 7-10 seconds: 2-3 phases
    - 11-15 seconds: 3-4 phases
-   - 5+ distinct phases: split into separate \`SHOTNN.md\` files
+   - 5+ distinct real video phases, scene changes, or location/action blocks: split into separate \`SHOTNN.md\` files
+   - GPT Image 2 storyboard sheets may use 1-12 panels; 5-12 storyboard sheet panels alone do not force a split
 5. For each shot, write a GPT Image 2 storyboard prompt:
    - use character sheets as the only identity source
    - use optional storyboard guides only for staging and timing
+   - use raw black-and-white rough pencil storyboard panels, strong silhouettes, visible motion, cinematic camera variety, and color-coded planning annotations
    - include previous-shot handoff and next-shot handoff
    - preserve shared \`visual_world\`, lighting, screen direction, and action rhythm
 6. Build model-ready video prompt bundles:
    - Seedance: character sheet tokens first, generated shot storyboard token next
+   - Seedance: follow storyboard panels left-to-right/top-to-bottom as visual/action/camera source, but never render arrows, labels, annotations, timestamps, or panel borders
    - Veo: visual planning prompt with full audio direction
    - Kling: block-structured storyboard route, not a mandatory Start+End frame route
 7. Keep coverage inside the same \`SHOTNN.md\`; coverage uses storyboard planning prompts and does not request separate start/end still prompts.
@@ -351,13 +355,14 @@ description: Finalize storyboard-reference prompt packages after storyboard QA p
 ## Validate Files
 
 1. \`${vars.outputDir}/storyboard-reference-plan.json\` exists.
-2. \`${vars.outputDir}/reference-prep/\` contains character sheet prompt files.
-3. \`${vars.outputDir}/storyboard-prompts/\` contains per-shot GPT Image 2 storyboard prompts.
-4. \`${vars.outputDir}/prompt-bundles/\` contains model prompt bundles.
-5. Every \`${vars.outputDir}/shots/SHOTNN.md\` contains the required storyboard-reference sections.
-6. Coverage stays in the same \`SHOTNN.md\`.
-7. No generated shot contains forbidden start/end frame sections or exact first-frame reuse instructions.
-8. \`storyboard_reference_status\` and \`storyboard_handoff_status\` are pass.
+2. \`${vars.outputDir}/storyboard-prompt.md\` exists as the storyboard bootstrap alias.
+3. \`${vars.outputDir}/reference-prep/\` contains character sheet prompt files.
+4. \`${vars.outputDir}/storyboard-prompts/\` contains per-shot GPT Image 2 storyboard prompts.
+5. \`${vars.outputDir}/prompt-bundles/\` contains model prompt bundles with \`storyboard_creation\` metadata.
+6. Every \`${vars.outputDir}/shots/SHOTNN.md\` contains the required storyboard-reference sections.
+7. Coverage stays in the same \`SHOTNN.md\`.
+8. No generated shot contains forbidden start/end frame sections or exact first-frame reuse instructions.
+9. \`storyboard_reference_status\` and \`storyboard_handoff_status\` are pass.
 
 ## Final Summary
 

package/build/lib/storyboard-reference/adapters/seedance20.js

@@ -47,8 +47,8 @@ export class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter {
         const storyboardEntry = this.getMappingEntries(input, "storyboard_plan")[0];
         const storyboardToken = storyboardEntry?.token ?? "@Image2";
         const continuityInstruction = input.continuityMode === "continuous-shot"
-            ? "No scene cuts throughout, one continuous shot."
-            : `Follow the generated storyboard panels in ${storyboardToken} left-to-right, top-to-bottom as the exact visual beat order. Do not reinterpret actions, poses, camera angles, emotional progression, frame variety, or the final pose. Compress the planned sequence into the full duration as concise motion snapshots; use only storyboard-motivated cuts, match cuts, whip transitions, or camera moves, and do not add unplanned cuts, extra scene jumps, or new locations.`;
+            ? `Use the generated storyboard reference ${storyboardToken} as the complete visual, action, camera, and choreography source for this ${input.request.durationSeconds}-second video. Follow the single storyboard beat exactly. No scene cuts throughout, one continuous shot.`
+            : `Use the generated storyboard reference ${storyboardToken} as the complete visual, action, camera, and choreography source for this ${input.request.durationSeconds}-second video. Follow all ${input.storyboardImagePrompt.panelCount} beats sequentially from left-to-right, top-to-bottom as the exact visual beat order. Do not reinterpret actions, poses, camera angles, emotional progression, frame variety, movement logic, shot order, or the final pose. Compress the full ${input.storyboardImagePrompt.panelCount}-beat sequence into the full duration as fast readable motion snapshots, not full-length actions. Use urgent rhythm, storyboard-motivated cuts, quick cuts, match cuts, whip transitions, or motivated camera moves only when the storyboard supports them. Do not add unplanned cuts, extra scene jumps, duplicate performers, or new locations.`;
         const characterEntries = this.getMappingEntries(input, "character_identity");
         const characterTokenText = characterEntries.map(entry => entry.token).join(", ") || "@Image1";
         const promptText = `${this.formatCharacterRoleLine(input)}
@@ -69,13 +69,13 @@ ${input.request.brief}
 ${formatPhaseLines(input.interpretation.phases)}
 
 [GPT IMAGE 2 STORYBOARD SOURCE]
-Use the generated storyboard image from ${input.storyboardImagePrompt.outputPath} as ${storyboardToken}. It has ${input.storyboardImagePrompt.panelCount} panel(s), follows the shot handoff, and is not an identity source. Treat colored arrows, panel labels, and lens notes as planning annotations only; never render arrows, notes, labels, timestamps, or storyboard text into the video.
+Use the generated storyboard image from ${input.storyboardImagePrompt.outputPath} as ${storyboardToken}. It has ${input.storyboardImagePrompt.panelCount} panel(s), follows the shot handoff, and is not an identity source. Treat colored arrows, panel labels, lens notes, and framing marks as planning annotations only; never render arrows, annotation marks, notes, labels, timestamps, panel borders, or storyboard text into the video.
 
 [CAMERA]
 ${input.interpretation.cameraPlan.framing}, ${input.interpretation.cameraPlan.movement}, ${input.interpretation.cameraPlan.lens}, ${input.interpretation.cameraPlan.stabilization}. Preserve ${input.interpretation.cameraPlan.screenDirection}.
 
 [PERFORMANCE]
-Visible acting stays concrete and restrained: gaze, breathing, posture, hand behavior, and facial tension evolve from the brief without changing identity.
+Keep the same performer identity from ${characterTokenText}; do not duplicate the character. Visible performance must include breath, mouth movement when dialogue or singing is present, body strain, fabric motion, floor or prop contact, and emotional escalation while preserving exact identity. Acting stays concrete and physically grounded: gaze, breathing, posture, hand behavior, and facial tension evolve from the brief without changing wardrobe or body design.
 
 [AUDIO]
 Dialogue: ${buildDialogueTranscript(input)}.
@@ -86,7 +86,7 @@ Music: NONE.
 [CONTINUITY]
 Identity reference stays locked to ${characterTokenText}. Storyboard ${storyboardToken} controls staging, shot order, pose logic, camera variety, emotional progression, and visual rhythm only. Character design, wardrobe, accessories, and visible props cannot be inherited from the storyboard. Storyboard text, panel borders, arrows, colored marks, lens notes, watermark, logo, and alternate character design are never identity sources and must not appear in the rendered video.
 
-Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders, colored arrows, annotation marks, lens notes, timestamps, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps.`;
+Avoid: identity drift, face drift, outfit drift, duplicated performer, storyboard text, annotations, panel borders, colored arrows, annotation marks, lens notes, timestamps, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps. No text, no annotations, no timestamps, no watermark.`;
         const output = {
             model: this.model,
             displayName: getDisplayName(this.model),

package/build/lib/storyboard-reference/index.d.ts

@@ -4,4 +4,4 @@ export { resolveAssetRoles } from "./asset-role-resolver.js";
 export { interpretStoryboard } from "./storyboard-interpreter.js";
 export { renderShotMarkdown, writeStoryboardReferenceOutputs } from "./output-writer.js";
 export { assertSafeStoryboardReferenceRequest, assertStoryboardReferenceBuildPass, validateModelPromptOutput, validatePromptBundle, validateResolvedAssetRoles } from "./validators.js";
-export type { AdapterInput, AudioPlan, CameraPlan, CharacterReferenceSheetPrompt, ContinuityAnchors, DialogueLine, ModelPromptOutput, ModelPromptQa, ModelRouteMetadata, NormalizedVideoPromptRequest, PromptBundle, PromptBundleQa, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, ReferenceAssetRole, ReferenceLockStrength, ResolvedAssetRoles, SeedanceContinuityMode, ShotHandoffNote, StoryboardImagePrompt, StoryboardInterpretation, StoryboardPhase, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePlan, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoModelPromptAdapter, VideoPromptRequest, VisualWorld, VoiceCastEntry } from "./types.js";
+export type { AdapterInput, AudioPlan, CameraPlan, CharacterReferenceSheetPrompt, ContinuityAnchors, DialogueLine, ModelPromptOutput, ModelPromptQa, ModelRouteMetadata, NormalizedVideoPromptRequest, PromptBundle, PromptBundleQa, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, ReferenceAssetRole, ReferenceLockStrength, ResolvedAssetRoles, SeedanceContinuityMode, ShotHandoffNote, StoryboardCreationMetadata, StoryboardImagePrompt, StoryboardInterpretation, StoryboardPhase, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePlan, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoModelPromptAdapter, VideoPromptRequest, VisualWorld, VoiceCastEntry } from "./types.js";

package/build/lib/storyboard-reference/output-writer.js

@@ -169,6 +169,9 @@ ${bundle.storyboardImagePrompt.promptText}
 \`\`\`
 `;
 }
+function renderStoryboardPromptAlias(result) {
+    return result.bundles.map(renderStoryboardPromptFile).join("\n---\n\n");
+}
 function renderQaReport(result) {
     const models = result.request.targetModels.join(", ");
     const rows = result.bundles
@@ -219,6 +222,7 @@ export async function writeStoryboardReferenceOutputs(result, rootDir = process.
     const written = [];
     const planPath = join(outputRoot, "storyboard-reference-plan.json");
     const projectInfoPath = join(outputRoot, "project-info.md");
+    const storyboardPromptAliasPath = join(outputRoot, "storyboard-prompt.md");
     const qaPath = join(outputRoot, "reports", "STORYBOARD-REFERENCE-QA.md");
     await writeText(planPath, `${JSON.stringify(result.plan, null, 2)}\n`);
     written.push(planPath);
@@ -234,6 +238,8 @@ export async function writeStoryboardReferenceOutputs(result, rootDir = process.
 - Safety context: ${result.request.safetyContext}
 `);
     written.push(projectInfoPath);
+    await writeText(storyboardPromptAliasPath, renderStoryboardPromptAlias(result));
+    written.push(storyboardPromptAliasPath);
     for (const prompt of result.characterReferenceSheetPrompts) {
         const promptPath = resolve(rootDir, prompt.outputPath);
         await writeText(promptPath, renderCharacterSheetPrompt(prompt));

package/build/lib/storyboard-reference/prompt-bundle-builder.js

@@ -42,10 +42,16 @@ function resolvePromptAdapter(model) {
     }
     return adapter;
 }
-function getStoryboardPanelCount(request, phaseBudget) {
-    return request.storyboardPanelCountHint
-        ?? request.shotCountHint
-        ?? phaseBudget.recommendedMaxPhases;
+const MAX_STORYBOARD_SHEET_PANELS = 12;
+function getStoryboardSheetPanelCount(request, phaseBudget) {
+    const panelCount = request.storyboardPanelCountHint ?? phaseBudget.recommendedMaxPhases;
+    if (panelCount > MAX_STORYBOARD_SHEET_PANELS) {
+        throw new Error(`Invalid storyboardPanelCountHint. Expected 1-${MAX_STORYBOARD_SHEET_PANELS} panels for one GPT Image 2 storyboard sheet.`);
+    }
+    return panelCount;
+}
+function getVideoPhaseCount(request, phaseBudget) {
+    return request.shotCountHint ?? phaseBudget.recommendedMaxPhases;
 }
 function buildShotId(index) {
     return `SHOT${String(index + 1).padStart(2, "0")}`;
@@ -172,37 +178,37 @@ function buildStoryboardImagePrompt(input) {
         ? `Use external storyboard guide tokens ${assets.storyboards.map(storyboard => storyboard.token).join(", ")} only for composition, blocking, camera direction, timing, and action rhythm.`
         : "No external storyboard guide is required; infer the board from the screenplay brief, continuity notes, and visual world.";
     const phaseDirection = interpretation.phases
-        .map(phase => `Panel ${phase.index}: ${phase.job}; ${phase.subjectAction}; camera behavior: ${phase.cameraBehavior}; background behavior: ${phase.backgroundBehavior}.`)
+        .map(phase => `Phase ${phase.index}: ${phase.job}; ${phase.subjectAction}; camera behavior: ${phase.cameraBehavior}; background behavior: ${phase.backgroundBehavior}.`)
         .join(" ");
     const continuityStyle = interpretation.phases.length <= 1
         ? "Because this is a single uninterrupted beat, show one decisive action moment with a clear entry pose, motion direction, and final body intention inside the same panel."
-        : "Read panels left-to-right, top-to-bottom as a planned visual beat sequence. Each panel must show a distinct body pose, camera size/angle, movement logic, and emotional escalation, not decorative micro-poses.";
+        : `Read panels left-to-right, top-to-bottom as a planned visual beat sequence. Create ${input.storyboardSheetPanelCount} distinct beat snapshot${input.storyboardSheetPanelCount === 1 ? "" : "s"} distributed across the video phases. Each panel must show a distinct body pose, camera size/angle, movement logic, and emotional escalation, not decorative micro-poses.`;
     return {
         shotId,
         outputPath: `${request.outputDir}/storyboard-prompts/${shotId}-GPT-IMAGE-2-STORYBOARD.md`,
         provider: "gpt-image-2",
         aspectRatio: "16:9",
-        panelCount: interpretation.panelCount,
+        panelCount: input.storyboardSheetPanelCount,
         style: "professional-production-storyboard",
         characterSheetIds,
         externalStoryboardGuideIds,
         previousShotHandoff: input.previousShotHandoff,
         nextShotHandoff: input.nextShotHandoff,
-        promptText: `REFERENCE LOCK: Use the generated character sheet reference${characterReferenceSheetPrompts.length === 1 ? "" : "s"} (${sheetRefs}) as the only source for character identity, face, hair, body proportions, wardrobe, accessories, material behavior, and visible props.
+        promptText: `REFERENCE LOCK: Use the generated character sheet reference${characterReferenceSheetPrompts.length === 1 ? "" : "s"} (${sheetRefs}) as the only source for character identity, face, hair, skin texture, body proportions, wardrobe, accessories, material behavior, and visible props.
 
 Keep same: every character identity detail from the character sheet${characterReferenceSheetPrompts.length === 1 ? "" : "s"}, the declared visual world, screen direction, environmental continuity, lighting direction, prop continuity, and shot handoff logic. Storyboard text, arrows, labels, panel borders, watermarks, logos, and alternate character designs are never identity sources.
 
-Change only: create a professional 16:9 production storyboard page for ${shotId} with exactly ${interpretation.panelCount} cinematic panel${interpretation.panelCount === 1 ? "" : "s"}. The storyboard controls composition, blocking, camera direction, timing, phase order, action rhythm, and emotional progression only. ${externalGuideText}
+Change only: create a raw cinematic storyboard sheet for ${shotId}. 16:9 storyboard sheet, exactly ${input.storyboardSheetPanelCount} cinematic panel${input.storyboardSheetPanelCount === 1 ? "" : "s"}. The storyboard controls composition, blocking, camera direction, timing, phase order, action rhythm, and emotional progression only. ${externalGuideText}
 
-Storyboard drawing style: raw contemporary film storyboard, black-and-white rough pencil linework for the artwork only, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished choreography-previsualization feel, not polished concept art or final render.
+Storyboard drawing style: raw contemporary film storyboard with black-and-white rough pencil linework. The actual storyboard drawings must be black-and-white only: rough pencil lines, minimal detail, fast gesture drawing energy, simple anatomy construction, strong silhouette readability, lightweight unfinished choreography previs, not polished concept art or final render.
 
 Panel direction: ${continuityStyle} The scene brief is: ${request.brief} Previous handoff: ${input.previousShotHandoff}. Next handoff: ${input.nextShotHandoff}. Planned panel actions: ${phaseDirection}
 
-Camera and staging: show ${interpretation.cameraPlan.framing}, ${interpretation.cameraPlan.movement}, ${interpretation.cameraPlan.lens}; preserve ${interpretation.cameraPlan.screenDirection}. Use cinematic camera variety only when motivated by the beat: handheld energy, push-in, orbit, overhead, low angle, side silhouette, insert, aggressive close-up, long-lens compression, or extreme negative space. Maintain the same environment, lighting, atmosphere, foreground, midground, and background continuity: ${interpretation.visualWorld.environment}; ${interpretation.visualWorld.lighting}; ${interpretation.visualWorld.foreground}; ${interpretation.visualWorld.midground}; ${interpretation.visualWorld.background}; ${interpretation.visualWorld.atmosphere}.
+Camera and staging: show ${interpretation.cameraPlan.framing}, ${interpretation.cameraPlan.movement}, ${interpretation.cameraPlan.lens}; preserve ${interpretation.cameraPlan.screenDirection}. Use cinematic arthouse camerawork with handheld energy, whip pans, orbit movement, overhead shots, low angles, side silhouettes, aggressive close-ups, long lens compression, inserts, and extreme negative space whenever motivated by the beat. Maintain the same environment, lighting, atmosphere, foreground, midground, and background continuity: ${interpretation.visualWorld.environment}; ${interpretation.visualWorld.lighting}; ${interpretation.visualWorld.foreground}; ${interpretation.visualWorld.midground}; ${interpretation.visualWorld.background}; ${interpretation.visualWorld.atmosphere}.
 
 Annotation color system: red arrows for body movement, blue arrows for camera movement, green marks for framing/composition, orange marks for lighting direction, purple marks for vocal or emotional emphasis when relevant, black text only for very short lens notes and panel labels. No timestamps.
 
-Every panel must contain visible momentum or clear behavioral change: gaze shift, breath, weight transfer, contact with ground/prop, fabric motion, hand tension, or a readable pose transition. Keep the location minimal and readable.
+Every panel must contain visible momentum. Every panel must contain visible motion, strong body momentum, or clear behavioral change: gaze shift, breath, weight transfer, contact with ground/prop, fabric motion, hand tension, floor contact, hair or clothing motion, or a readable pose transition. Avoid static standing poses unless explicitly required by the beat. Keep the location minimal and readable. End with one overwhelming final readable movement pose or composition that preserves the shot's emotional endpoint.
 
 Avoid: identity drift, face drift, hair drift, wardrobe drift, prop drift, material drift, alternate character design, static standing poses unless explicitly required by the beat, timestamps, long text notes, storyboard text becoming scene text, new characters, new locations, logos, watermarks, decorative borders, broken perspective, impossible contact or weight, inconsistent screen direction, inconsistent light direction, photorealistic final-render polish, cartoon style, anime style, CGI look, unsafe public-figure likeness, trademarked branding.`
     };
@@ -291,6 +297,45 @@ function buildProviderReferenceTokens(providerAssetMapping) {
         audioReference: "@audio1"
     };
 }
+function buildStoryboardCreationMetadata(request, storyboardImagePrompt, providerAssetMapping) {
+    const storyboardEntry = Object.values(providerAssetMapping)
+        .find(entry => entry.role === "storyboard_plan");
+    return {
+        provider: "gpt-image-2",
+        prompt_path: storyboardImagePrompt.outputPath,
+        alias_path: `${request.outputDir}/storyboard-prompt.md`,
+        source_mode: storyboardImagePrompt.externalStoryboardGuideIds.length > 0
+            ? "generated-with-external-guide"
+            : "generated",
+        panel_count: storyboardImagePrompt.panelCount,
+        reading_order: "left-to-right, top-to-bottom",
+        character_sheet_ids: storyboardImagePrompt.characterSheetIds,
+        external_storyboard_guide_ids: storyboardImagePrompt.externalStoryboardGuideIds,
+        seedance_token: storyboardEntry?.token ?? "@Image2",
+        annotation_policy: {
+            rendered_in_video: false,
+            color_system: {
+                red: "body movement",
+                blue: "camera movement",
+                green: "framing / composition",
+                orange: "lighting direction",
+                purple: "vocal / emotional emphasis",
+                black: "short lens notes and panel labels"
+            },
+            forbidden_in_video: [
+                "arrows",
+                "annotation marks",
+                "lens notes",
+                "panel labels",
+                "timestamps",
+                "panel borders",
+                "watermark",
+                "logo"
+            ]
+        },
+        prompt_text: storyboardImagePrompt.promptText
+    };
+}
 function buildStoryboardReferencePolicy(request, phaseBudget, providerFileLimits, bundles, providerReferenceTokens, maxPhases, splitRequired) {
     const continuityModes = Array.from(new Set(bundles.map(bundle => bundle.continuityMode)));
     return {
@@ -325,9 +370,9 @@ function buildStoryboardReferencePolicy(request, phaseBudget, providerFileLimits
                 provider: "gpt-image-2",
                 generated_per_shot: true,
                 aspect_ratio: "16:9",
-                max_panels_per_shot: maxPhases,
+                max_panels_per_shot: MAX_STORYBOARD_SHEET_PANELS,
                 panel_budget: phaseBudget.policy,
-                professional_prompt_target_words: "160-240 words per shot storyboard prompt"
+                professional_prompt_target_words: "240-420 words per shot storyboard prompt"
             },
             role_separation: {
                 character_identity: `${providerReferenceTokens.characterIdentities.join(", ")} control identity, face, hair, body proportions, wardrobe, accessories, and visible props.`,
@@ -376,15 +421,16 @@ export function buildStoryboardReferencePromptBundles(input) {
     const voiceCast = buildVoiceCast(request);
     const phaseBudget = buildStoryboardPhaseBudget(request.durationSeconds, request.storyboardReferenceMode.maxStoryboardPhases);
     const providerFileLimits = buildProviderFileLimitReport(request, characterReferenceSheetPrompts.length + 1);
-    const panelCount = getStoryboardPanelCount(request, phaseBudget);
+    const storyboardSheetPanelCount = getStoryboardSheetPanelCount(request, phaseBudget);
+    const videoPhaseCount = getVideoPhaseCount(request, phaseBudget);
     const maxPhases = phaseBudget.effectiveMaxStoryboardPhases;
-    const splitRequired = panelCount > maxPhases;
+    const splitRequired = videoPhaseCount > maxPhases;
     if (splitRequired && !request.storyboardReferenceMode.splitStoryboardOverload) {
-        throw new Error(`Storyboard has ${panelCount} phases, which exceeds maxStoryboardPhases=${maxPhases}. Enable splitStoryboardOverload or split the storyboard manually.`);
+        throw new Error(`Storyboard has ${videoPhaseCount} video phases, which exceeds maxStoryboardPhases=${maxPhases}. Enable splitStoryboardOverload or split the storyboard manually.`);
     }
     const phaseCounts = splitRequired && request.storyboardReferenceMode.splitStoryboardOverload
-        ? getSplitPhaseCounts(panelCount, maxPhases)
-        : [Math.min(panelCount, maxPhases)];
+        ? getSplitPhaseCounts(videoPhaseCount, maxPhases)
+        : [Math.min(videoPhaseCount, maxPhases)];
     const generatedAt = new Date().toISOString();
     const bundles = [];
     let previousShotHandoff = "Project opening: start from the screenplay's first visual beat.";
@@ -402,11 +448,13 @@ export function buildStoryboardReferencePromptBundles(input) {
             assets,
             shotId,
             interpretation,
+            storyboardSheetPanelCount,
             characterReferenceSheetPrompts,
             previousShotHandoff,
             nextShotHandoff: handoffNote.exitHandoff
         });
         const providerAssetMapping = buildProviderAssetMapping(assets, characterReferenceSheetPrompts, storyboardImagePrompt);
+        const storyboard_creation = buildStoryboardCreationMetadata(request, storyboardImagePrompt, providerAssetMapping);
         const referenceAssetRequirements = buildReferenceAssetRequirements(providerAssetMapping);
         const modelPrompts = buildModelPrompts(request, {
             assets,
@@ -431,6 +479,7 @@ export function buildStoryboardReferencePromptBundles(input) {
             providerFileLimits,
             handoffNote,
             storyboardImagePrompt,
+            storyboard_creation,
             referenceAssetRequirements,
             providerAssetMapping,
             qa: { verdict: "pass", checks: {}, issues: [], splitRequired },

package/build/lib/storyboard-reference/types.d.ts

@@ -135,6 +135,30 @@ export interface StoryboardImagePrompt {
     nextShotHandoff: string;
     promptText: string;
 }
+export interface StoryboardCreationMetadata {
+    provider: "gpt-image-2";
+    prompt_path: string;
+    alias_path: string;
+    source_mode: "generated" | "generated-with-external-guide";
+    panel_count: number;
+    reading_order: "left-to-right, top-to-bottom";
+    character_sheet_ids: string[];
+    external_storyboard_guide_ids: string[];
+    seedance_token: string;
+    annotation_policy: {
+        rendered_in_video: false;
+        color_system: {
+            red: "body movement";
+            blue: "camera movement";
+            green: "framing / composition";
+            orange: "lighting direction";
+            purple: "vocal / emotional emphasis";
+            black: "short lens notes and panel labels";
+        };
+        forbidden_in_video: string[];
+    };
+    prompt_text: string;
+}
 export type ProviderAssetMappingRole = "character_identity" | "storyboard_plan" | "style_reference" | "camera_reference" | "action_reference" | "prop_reference";
 export interface ProviderAssetMappingEntry {
     token: string;
@@ -254,6 +278,7 @@ export interface PromptBundle {
     providerFileLimits: ProviderFileLimitReport;
     handoffNote: ShotHandoffNote;
     storyboardImagePrompt: StoryboardImagePrompt;
+    storyboard_creation: StoryboardCreationMetadata;
     referenceAssetRequirements: ReferenceAssetRequirement[];
     providerAssetMapping: Record<string, ProviderAssetMappingEntry>;
     qa: PromptBundleQa;

package/build/lib/storyboard-reference/validators.js

@@ -113,6 +113,10 @@ export function validatePromptBundle(bundle, assets, voiceCast = []) {
         hasCharacterReference: assets.characters.length >= 1,
         hasStoryboardReference: assets.storyboards.length >= 1 || Boolean(bundle.storyboardImagePrompt),
         hasStoryboardImagePrompt: Boolean(bundle.storyboardImagePrompt?.promptText.trim()),
+        hasStoryboardCreationMetadata: Boolean(bundle.storyboard_creation?.prompt_text.trim())
+            && bundle.storyboard_creation?.prompt_path === bundle.storyboardImagePrompt.outputPath
+            && bundle.storyboard_creation?.panel_count === bundle.storyboardImagePrompt.panelCount
+            && bundle.storyboard_creation?.annotation_policy.rendered_in_video === false,
         storyboardPromptHasReferenceLockStructure: hasGptImageStillPromptContract(bundle.storyboardImagePrompt?.promptText ?? ""),
         hasAvoidLineEverywhere: Object.values(bundle.modelPrompts).every(output => Boolean(output) && hasAvoidOrNegativePrompt(output.promptText)),
         storyboardPromptHasAvoidLine: hasAvoidOrNegativePrompt(bundle.storyboardImagePrompt?.promptText ?? ""),

package/build/lib/templates.js

@@ -35,7 +35,7 @@ function buildStoryboardPlatformGuard(config) {
 - Do not generate main-shot \`ILK FRAME\`, \`İLK FRAME\`, or \`SON FRAME\` sections.
 - Do not use exact first-frame reuse instructions, \`SHOTNN_START\`, \`SHOTNN_END\`, or mandatory Start+End transition fields.
 - If no character reference is available through the user, an in-context image, \`--character-ref\`, or \`refs/character.png\`, stop and request one.
-- Required storyboard outputs: \`${config.outputDir}/storyboard-reference-plan.json\`, \`${config.outputDir}/reference-prep/\`, \`${config.outputDir}/storyboard-prompts/\`, \`${config.outputDir}/prompt-bundles/\`, \`${config.outputDir}/shots/SHOTNN.md\`, and \`${config.outputDir}/reports/STORYBOARD-REFERENCE-QA.md\`.
+- Required storyboard outputs: \`${config.outputDir}/storyboard-reference-plan.json\`, \`${config.outputDir}/storyboard-prompt.md\`, \`${config.outputDir}/reference-prep/\`, \`${config.outputDir}/storyboard-prompts/\`, \`${config.outputDir}/prompt-bundles/\`, \`${config.outputDir}/shots/SHOTNN.md\`, and \`${config.outputDir}/reports/STORYBOARD-REFERENCE-QA.md\`.
 `;
 }
 function buildSeedanceProfile(active, storyboardReferenceActive = false, maxStoryboardPhases = 4) {

package/content/skills/storyboard-reference/SKILL.md

@@ -13,7 +13,7 @@ Use this skill when the user provides:
 - a video brief or scenario text
 - optional external storyboard guide images
 
-The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. The generated shot storyboard is the staging reference for the final video model prompt.
+The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. If no external storyboard image is supplied, this generated prompt is the mandatory storyboard bootstrap step. The generated shot storyboard is the staging reference for the final video model prompt.
 
 ## Reference Prep
 
@@ -36,9 +36,10 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
-- hard cap: max 4 panels/phases per shot unless the configured project cap is lower
-- split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
+- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
+- hard cap: max 4 video phases per shot unless the configured project cap is lower
+- split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
 - storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
 - annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
@@ -108,6 +109,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
+- storyboard_creation metadata in `SHOTNN.bundle.json`
 - audio plan
 - prompt bundle for requested models
 - QA verdict
@@ -116,6 +118,7 @@ Generated files:
 
 ```text
 $OUTPUT_DIR/storyboard-reference-plan.json
+$OUTPUT_DIR/storyboard-prompt.md
 $OUTPUT_DIR/reference-prep/CHARACTER-SHEET-*.md
 $OUTPUT_DIR/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md
 $OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json

package/content/workflows/generate-storyboard.md

@@ -33,11 +33,12 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - exact identity, wardrobe, accessories, and visible props
    - no labels, text, logos, watermarks, alternate designs, or extra characters
 3. Confirm target models: `veo31`, `seedance-2.0`, `kling-3.0`, or a user-provided subset.
-4. Select shot storyboard panel budget:
-   - 4-6 seconds: 1-2 panels/phases
-   - 7-10 seconds: 2-3 panels/phases
-   - 11-15 seconds: 3-4 panels/phases
-   - 5+ distinct phases: split into multiple `SHOTNN.md` files
+4. Select video phase budget and storyboard sheet panel count:
+   - 4-6 seconds: 1-2 video phases
+   - 7-10 seconds: 2-3 video phases
+   - 11-15 seconds: 3-4 video phases
+   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
    - lighting
@@ -89,7 +90,7 @@ npx @milenyumai/film-kit generate-storyboard \
 - Missing character reference: stop and request a valid reference.
 - Empty brief: stop and request a brief.
 - Public figure / real-person likeness / trademark risk: stop or safely anonymize before prompt generation.
-- 5+ storyboard phases: do not compress into one prompt; split shots.
+- 5+ real video phases: do not compress into one prompt; split shots. 5-12 storyboard sheet panels alone do not force a split.
 - Missing GPT Image 2 character sheet prompt: output is invalid.
 - Missing GPT Image 2 per-shot storyboard prompt: output is invalid.
 - Missing `Avoid` / negative prompt: output is invalid.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milenyumai/film-kit",
-  "version": "2.3.4",
+  "version": "2.3.5",
   "description": "Single-package Film-Kit distribution with preset-driven cinematic runtime setup for OpenAI Codex App, Claude Code, Cursor, Copilot, and Antigravity.",
   "type": "module",
   "main": "./build/index.js",

package/packages/gpt-image-smart/content/skills/storyboard-reference/SKILL.md

@@ -13,7 +13,7 @@ Use this skill when the user provides:
 - a video brief or scenario text
 - optional external storyboard guide images
 
-The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. The generated shot storyboard is the staging reference for the final video model prompt.
+The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. If no external storyboard image is supplied, this generated prompt is the mandatory storyboard bootstrap step. The generated shot storyboard is the staging reference for the final video model prompt.
 
 ## Reference Prep
 
@@ -36,9 +36,10 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
-- hard cap: max 4 panels/phases per shot unless the configured project cap is lower
-- split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
+- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
+- hard cap: max 4 video phases per shot unless the configured project cap is lower
+- split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
 - storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
 - annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
@@ -108,6 +109,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
+- storyboard_creation metadata in `SHOTNN.bundle.json`
 - audio plan
 - prompt bundle for requested models
 - QA verdict
@@ -116,6 +118,7 @@ Generated files:
 
 ```text
 $OUTPUT_DIR/storyboard-reference-plan.json
+$OUTPUT_DIR/storyboard-prompt.md
 $OUTPUT_DIR/reference-prep/CHARACTER-SHEET-*.md
 $OUTPUT_DIR/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md
 $OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json

package/packages/gpt-image-smart/content/workflows/generate-storyboard.md

@@ -33,11 +33,12 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - exact identity, wardrobe, accessories, and visible props
    - no labels, text, logos, watermarks, alternate designs, or extra characters
 3. Confirm target models: `veo31`, `seedance-2.0`, `kling-3.0`, or a user-provided subset.
-4. Select shot storyboard panel budget:
-   - 4-6 seconds: 1-2 panels/phases
-   - 7-10 seconds: 2-3 panels/phases
-   - 11-15 seconds: 3-4 panels/phases
-   - 5+ distinct phases: split into multiple `SHOTNN.md` files
+4. Select video phase budget and storyboard sheet panel count:
+   - 4-6 seconds: 1-2 video phases
+   - 7-10 seconds: 2-3 video phases
+   - 11-15 seconds: 3-4 video phases
+   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
    - lighting
@@ -89,7 +90,7 @@ npx @milenyumai/film-kit generate-storyboard \
 - Missing character reference: stop and request a valid reference.
 - Empty brief: stop and request a brief.
 - Public figure / real-person likeness / trademark risk: stop or safely anonymize before prompt generation.
-- 5+ storyboard phases: do not compress into one prompt; split shots.
+- 5+ real video phases: do not compress into one prompt; split shots. 5-12 storyboard sheet panels alone do not force a split.
 - Missing GPT Image 2 character sheet prompt: output is invalid.
 - Missing GPT Image 2 per-shot storyboard prompt: output is invalid.
 - Missing `Avoid` / negative prompt: output is invalid.

package/packages/hybrid/content/skills/storyboard-reference/SKILL.md

@@ -13,7 +13,7 @@ Use this skill when the user provides:
 - a video brief or scenario text
 - optional external storyboard guide images
 
-The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. The generated shot storyboard is the staging reference for the final video model prompt.
+The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. If no external storyboard image is supplied, this generated prompt is the mandatory storyboard bootstrap step. The generated shot storyboard is the staging reference for the final video model prompt.
 
 ## Reference Prep
 
@@ -36,9 +36,10 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
-- hard cap: max 4 panels/phases per shot unless the configured project cap is lower
-- split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
+- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
+- hard cap: max 4 video phases per shot unless the configured project cap is lower
+- split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
 - storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
 - annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
@@ -108,6 +109,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
+- storyboard_creation metadata in `SHOTNN.bundle.json`
 - audio plan
 - prompt bundle for requested models
 - QA verdict
@@ -116,6 +118,7 @@ Generated files:
 
 ```text
 $OUTPUT_DIR/storyboard-reference-plan.json
+$OUTPUT_DIR/storyboard-prompt.md
 $OUTPUT_DIR/reference-prep/CHARACTER-SHEET-*.md
 $OUTPUT_DIR/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md
 $OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json

package/packages/hybrid/content/workflows/generate-storyboard.md

@@ -33,11 +33,12 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - exact identity, wardrobe, accessories, and visible props
    - no labels, text, logos, watermarks, alternate designs, or extra characters
 3. Confirm target models: `veo31`, `seedance-2.0`, `kling-3.0`, or a user-provided subset.
-4. Select shot storyboard panel budget:
-   - 4-6 seconds: 1-2 panels/phases
-   - 7-10 seconds: 2-3 panels/phases
-   - 11-15 seconds: 3-4 panels/phases
-   - 5+ distinct phases: split into multiple `SHOTNN.md` files
+4. Select video phase budget and storyboard sheet panel count:
+   - 4-6 seconds: 1-2 video phases
+   - 7-10 seconds: 2-3 video phases
+   - 11-15 seconds: 3-4 video phases
+   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
    - lighting
@@ -89,7 +90,7 @@ npx @milenyumai/film-kit generate-storyboard \
 - Missing character reference: stop and request a valid reference.
 - Empty brief: stop and request a brief.
 - Public figure / real-person likeness / trademark risk: stop or safely anonymize before prompt generation.
-- 5+ storyboard phases: do not compress into one prompt; split shots.
+- 5+ real video phases: do not compress into one prompt; split shots. 5-12 storyboard sheet panels alone do not force a split.
 - Missing GPT Image 2 character sheet prompt: output is invalid.
 - Missing GPT Image 2 per-shot storyboard prompt: output is invalid.
 - Missing `Avoid` / negative prompt: output is invalid.

package/packages/hybrid-smart/content/skills/storyboard-reference/SKILL.md

@@ -13,7 +13,7 @@ Use this skill when the user provides:
 - a video brief or scenario text
 - optional external storyboard guide images
 
-The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. The generated shot storyboard is the staging reference for the final video model prompt.
+The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. If no external storyboard image is supplied, this generated prompt is the mandatory storyboard bootstrap step. The generated shot storyboard is the staging reference for the final video model prompt.
 
 ## Reference Prep
 
@@ -36,9 +36,10 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
-- hard cap: max 4 panels/phases per shot unless the configured project cap is lower
-- split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
+- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
+- hard cap: max 4 video phases per shot unless the configured project cap is lower
+- split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
 - storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
 - annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
@@ -108,6 +109,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
+- storyboard_creation metadata in `SHOTNN.bundle.json`
 - audio plan
 - prompt bundle for requested models
 - QA verdict
@@ -116,6 +118,7 @@ Generated files:
 
 ```text
 $OUTPUT_DIR/storyboard-reference-plan.json
+$OUTPUT_DIR/storyboard-prompt.md
 $OUTPUT_DIR/reference-prep/CHARACTER-SHEET-*.md
 $OUTPUT_DIR/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md
 $OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json

package/packages/hybrid-smart/content/workflows/generate-storyboard.md

@@ -33,11 +33,12 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - exact identity, wardrobe, accessories, and visible props
    - no labels, text, logos, watermarks, alternate designs, or extra characters
 3. Confirm target models: `veo31`, `seedance-2.0`, `kling-3.0`, or a user-provided subset.
-4. Select shot storyboard panel budget:
-   - 4-6 seconds: 1-2 panels/phases
-   - 7-10 seconds: 2-3 panels/phases
-   - 11-15 seconds: 3-4 panels/phases
-   - 5+ distinct phases: split into multiple `SHOTNN.md` files
+4. Select video phase budget and storyboard sheet panel count:
+   - 4-6 seconds: 1-2 video phases
+   - 7-10 seconds: 2-3 video phases
+   - 11-15 seconds: 3-4 video phases
+   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
    - lighting
@@ -89,7 +90,7 @@ npx @milenyumai/film-kit generate-storyboard \
 - Missing character reference: stop and request a valid reference.
 - Empty brief: stop and request a brief.
 - Public figure / real-person likeness / trademark risk: stop or safely anonymize before prompt generation.
-- 5+ storyboard phases: do not compress into one prompt; split shots.
+- 5+ real video phases: do not compress into one prompt; split shots. 5-12 storyboard sheet panels alone do not force a split.
 - Missing GPT Image 2 character sheet prompt: output is invalid.
 - Missing GPT Image 2 per-shot storyboard prompt: output is invalid.
 - Missing `Avoid` / negative prompt: output is invalid.

package/packages/multi/build/lib/configure.js

@@ -205,7 +205,7 @@ function buildStoryboardReferencePolicyJson(config) {
             aspect_ratio: "16:9",
             panel_budget: "4-6s: 1-2, 7-10s: 2-3, 11-15s: 3-4",
             max_panels_per_shot: config.storyboardReferenceMode.maxStoryboardPhases,
-            target_words: "160-240 words per shot storyboard prompt"
+            target_words: "240-420 words per shot storyboard prompt"
         },
         material_roles: {
             "character_sheet_tokens": "identity, face, body proportions, wardrobe, accessories, and visible props",
@@ -253,7 +253,7 @@ function buildShotFileOutputContract(config) {
     return `1. main shot blocks: \`MODEL CONTROL\`, \`INPUT ASSET ROLES\`, \`REFERENCE ASSET REQUIREMENTS\`, \`GPT IMAGE 2 STORYBOARD PROMPT\`, \`STORYBOARD PLAN\`, \`AUDIO PLAN\`, \`SEEDANCE VIDEO PROMPT\`, and coverage
 2. \`INPUT ASSET ROLES\` must declare generated character sheet tokens (\`@Image1...\`, legacy \`@image1...\`) as identity/wardrobe/props only
 3. \`INPUT ASSET ROLES\` must declare the generated shot storyboard token (next \`@Image\` after character sheets, legacy lowercase alias such as \`@image2\` for one character) as composition/blocking/camera/timing only
-4. \`GPT IMAGE 2 STORYBOARD PROMPT\` must be 16:9, professional production storyboard style, 160-240 words, and use character sheets as the only identity source
+4. \`GPT IMAGE 2 STORYBOARD PROMPT\` must be 16:9, professional production storyboard style, 240-420 words, use character sheets as the only identity source, and may use 1-12 storyboard sheet panels without forcing SHOT split
 5. \`STORYBOARD PLAN\` must include timeline phases for this shot, capped at ${config.storyboardReferenceMode.maxStoryboardPhases} phases
 6. every phase must derive from the shared \`team-plan.json -> visual_world\` and include its handoff from the previous shot and handoff to the next shot
 7. 2-3 coverage sub-shots stay in the same file
@@ -285,9 +285,9 @@ function buildSeedanceStoryboardContract(config) {
 - declare character sheet tokens (\`@Image1...\`, legacy \`@image1...\`) as identity, face, body proportions, wardrobe, accessories, and visible props
 - declare the generated shot storyboard token (next \`@Image\` after character sheets, legacy lowercase alias such as \`@image2\` for one character) as composition, blocking, camera direction, timing, and action progression only
 - never let storyboard text, panel borders, watermark, logo, alternate character design, or storyboard character design override the identity reference
-- write one \`GPT IMAGE 2 STORYBOARD PROMPT\` per shot before the Seedance prompt; it must be 16:9, professional, 160-240 words, and continuity-aware
+- write one \`GPT IMAGE 2 STORYBOARD PROMPT\` per shot before the Seedance prompt; it must be 16:9, professional, 240-420 words, continuity-aware, and written as the storyboard bootstrap prompt when no external storyboard image exists
 - write per-shot timeline phases under \`STORYBOARD PLAN\`, capped at ${config.storyboardReferenceMode.maxStoryboardPhases} phases
-- follow duration budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases; split 5+ phases into separate \`SHOTNN.md\` files
+- follow video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases; split 5+ real video phases, scene changes, or location/action blocks into separate \`SHOTNN.md\` files; 5-12 storyboard sheet panels alone do not force a split
 - use \`No scene cuts throughout, one continuous shot.\` only when that shot's storyboard plan is a single uninterrupted camera move
 - for multi-phase storyboard shots, describe the planned phase changes directly instead of forcing continuous-shot wording
 - when continuing a source clip, use \`Extend @video1 by [N]s\` and still preserve storyboard handoff continuity`;

package/packages/multi/build/lib/templates.js

@@ -21,7 +21,7 @@ function buildReferenceModeSummary(config) {
     return `- Reference mode: \`storyboard-reference\`
 - Storyboard reference mode: enabled
 - Max storyboard phases per shot: ${config.storyboardReferenceMode.maxStoryboardPhases}
-- Recommended phase budget: 4-6s = 1-2, 7-10s = 2-3, 11-15s = 3-4; split 5+ phases
+- Recommended video phase budget: 4-6s = 1-2, 7-10s = 2-3, 11-15s = 3-4; split 5+ real video phases, not 5-12 storyboard sheet panels
 - Provider reference tokens: generated character sheet tokens first, generated shot storyboard token next
 - Start/end frame chaining contract: disabled for Seedance storyboard-reference`;
 }
@@ -58,7 +58,7 @@ Seedance 2.0 responds best when you assign **explicit multimodal control roles**
 ${storyboardReferenceActive
         ? `- Storyboard-reference mode is active: generate one 16:9 GPT Image 2 character sheet prompt per character first; those sheet images lock identity/wardrobe/props
 - Each SHOTNN.md includes a GPT IMAGE 2 STORYBOARD PROMPT plus a per-shot STORYBOARD PLAN; the generated storyboard token controls only composition, blocking, camera direction, timing, and action progression
-- Duration budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases; split 5+ phases into separate SHOTNN.md files
+- Duration budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases; split 5+ real video phases into separate SHOTNN.md files, while 5-12 storyboard sheet panels may remain one shot
 - Storyboard text, panel borders, watermark, logo, and alternate character design are never identity sources
 - Do not require ILK FRAME / SON FRAME sections or exact first-frame reuse text in Seedance storyboard-reference mode
 - Use "No scene cuts throughout, one continuous shot." only when the shot's storyboard plan is actually one uninterrupted camera move`
@@ -313,8 +313,8 @@ export function buildMultiProjectFiles(config) {
    - \`storyboard_reference.enabled\`: ${storyboardReferenceActive ? "true" : "false"}
    - \`storyboard_reference.max_storyboard_phases\`: ${config.storyboardReferenceMode.maxStoryboardPhases}
    - \`storyboard_reference.character_reference_sheets\`: ${storyboardReferenceActive ? "GPT Image 2, 16:9, generated once per character" : "n/a"}
-   - \`storyboard_reference.storyboard_prompt_policy\`: ${storyboardReferenceActive ? "GPT Image 2, 16:9, generated per shot, 160-240 words" : "n/a"}
-   - \`storyboard_reference.recommended_phase_budget\`: ${storyboardReferenceActive ? "`4-6s: 1-2`, `7-10s: 2-3`, `11-15s: 3-4`, split 5+ phases" : "n/a"}
+   - \`storyboard_reference.storyboard_prompt_policy\`: ${storyboardReferenceActive ? "GPT Image 2, 16:9, generated per shot, 240-420 words, 1-12 sheet panels" : "n/a"}
+   - \`storyboard_reference.recommended_phase_budget\`: ${storyboardReferenceActive ? "`4-6s: 1-2`, `7-10s: 2-3`, `11-15s: 3-4`, split 5+ real video phases" : "n/a"}
    - \`storyboard_reference.provider_reference_tokens\`: ${storyboardReferenceActive ? "generated character sheet tokens first; generated shot storyboard token next" : "n/a"}
    - \`storyboard_reference.continuity_mode\`: ${storyboardReferenceActive ? "`continuous-shot` or `multi-shot-storyboard`" : "n/a"}
    - \`storyboard_reference.provider_file_limits\`: ${storyboardReferenceActive ? "9 images, 3 videos, 3 audio, 12 total files, 4-15s duration" : "n/a"}
@@ -353,7 +353,7 @@ SPATIAL PRIORITY: [who looks at what, which plane dominates, shared light source
 SEMANTIC WORLD: [camera height, lens family, horizon/vanishing logic, camera movement strategy, light source, shadow direction, scale map, reflection risk, physics constraints]
 RESPECT LOCKED SHOT COUNT: Do not create any shot outside SHOT[X]-SHOT[Y]
 KLING DEFAULT: single-transition first; custom storyboard only for 2-4 meaningful phases, max 4
-${storyboardReferenceActive ? `SEEDANCE STORYBOARD-REFERENCE: Each SHOTNN.md includes INPUT ASSET ROLES, REFERENCE ASSET REQUIREMENTS, GPT IMAGE 2 STORYBOARD PROMPT, STORYBOARD PLAN, AUDIO PLAN, SEEDANCE VIDEO PROMPT, and coverage. Do not require ILK FRAME / SON FRAME. Max storyboard phases per shot: ${config.storyboardReferenceMode.maxStoryboardPhases}. Character sheet tokens lock identity; generated shot storyboard token controls staging only.` : ""}
+${storyboardReferenceActive ? `SEEDANCE STORYBOARD-REFERENCE: Each SHOTNN.md includes INPUT ASSET ROLES, REFERENCE ASSET REQUIREMENTS, GPT IMAGE 2 STORYBOARD PROMPT, STORYBOARD PLAN, AUDIO PLAN, SEEDANCE VIDEO PROMPT, and coverage. Do not require ILK FRAME / SON FRAME. Max video phases per shot: ${config.storyboardReferenceMode.maxStoryboardPhases}. Character sheet tokens lock identity; generated shot storyboard token controls staging only and may contain up to 12 sheet panels.` : ""}
 ONE FILE PER SHOT: Each SHOTNN.md contains main shot + all coverage.
 FILE OWNERSHIP: Write only your assigned SHOT files and your own batch report.
 VOICE CONTRACT: Reuse ${config.outputDir}/team-plan.json -> \`voiceCast\` and keep one active speaker per shot.
@@ -421,7 +421,7 @@ ${storyboardReferenceActive
         ? `- Main shot contains: \`MODEL CONTROL\`, \`INPUT ASSET ROLES\`, \`REFERENCE ASSET REQUIREMENTS\`, \`GPT IMAGE 2 STORYBOARD PROMPT\`, \`STORYBOARD PLAN\`, \`AUDIO PLAN\`, \`SEEDANCE VIDEO PROMPT\`, and coverage
 - \`INPUT ASSET ROLES\` declares generated character sheet tokens (\`@Image1...\`, legacy \`@image1...\`) as identity/wardrobe/props
 - \`INPUT ASSET ROLES\` declares generated shot storyboard token (next \`@Image\`, legacy lowercase alias such as \`@image2\` for one character) as composition/blocking/camera/timing only
-- \`GPT IMAGE 2 STORYBOARD PROMPT\` is 16:9, 160-240 words, professional storyboard style, and uses character sheets as the only identity source
+- \`GPT IMAGE 2 STORYBOARD PROMPT\` is 16:9, 240-420 words, professional storyboard style, supports 1-12 sheet panels, and uses character sheets as the only identity source
 - \`STORYBOARD PLAN\` includes per-shot timeline phases capped at ${config.storyboardReferenceMode.maxStoryboardPhases}
 - Shot storyboard plans must derive from one shared \`${config.outputDir}/team-plan.json -> visual_world\`
 - Do not require \`ILK FRAME\` / \`SON FRAME\` assets or exact first-frame reuse text in this mode`
@@ -1004,8 +1004,8 @@ Run the Film-Kit Multi pipeline with maximum throughput while preserving ${isSee
    - set \`storyboard_reference.enabled\` to ${isSeedanceStoryboardReference(config) ? "true" : "false"}
 ${isSeedanceStoryboardReference(config) ? `   - set \`storyboard_reference.max_storyboard_phases\` to ${config.storyboardReferenceMode.maxStoryboardPhases}
    - set \`storyboard_reference.character_reference_sheets\` to GPT Image 2, 16:9, generated once per character
-   - set \`storyboard_reference.storyboard_prompt_policy\` to GPT Image 2, 16:9, generated per shot, 160-240 words
-   - set \`storyboard_reference.recommended_phase_budget\` to 4-6s=1-2, 7-10s=2-3, 11-15s=3-4, split 5+
+   - set \`storyboard_reference.storyboard_prompt_policy\` to GPT Image 2, 16:9, generated per shot, 240-420 words, 1-12 sheet panels
+   - set \`storyboard_reference.recommended_phase_budget\` to 4-6s=1-2, 7-10s=2-3, 11-15s=3-4, split 5+ real video phases
    - set \`storyboard_reference.provider_reference_tokens\` to generated character sheet tokens first and generated shot storyboard token next
    - set \`storyboard_reference.continuity_mode\` per shot as continuous-shot or multi-shot-storyboard
    - set \`storyboard_reference.provider_file_limits\` to 9 images, 3 videos, 3 audio, 12 total files, 4-15s duration
@@ -1062,7 +1062,7 @@ OUTPUT DIR: ${config.outputDir}/shots/
 REPORT FILE: ${config.outputDir}/reports/BATCH-REPORT-B[NN].md
 SPATIAL PRIORITY: [who looks at what, which plane dominates, shared light source]
 SEMANTIC WORLD: [camera height, lens family, horizon/vanishing logic, camera movement strategy, light source, shadow direction, scale map, reflection risk, physics constraints]
-${isSeedanceStoryboardReference(config) ? `SEEDANCE STORYBOARD-REFERENCE: Declare generated character sheet tokens (@Image1..., legacy @image1...) for identity and the generated shot storyboard token (next @Image, legacy lowercase alias such as @image2 for one character) for staging only. Include GPT IMAGE 2 STORYBOARD PROMPT and per-shot STORYBOARD PLAN phases, max ${config.storyboardReferenceMode.maxStoryboardPhases}. Do not require ILK FRAME / SON FRAME.` : ""}
+${isSeedanceStoryboardReference(config) ? `SEEDANCE STORYBOARD-REFERENCE: Declare generated character sheet tokens (@Image1..., legacy @image1...) for identity and the generated shot storyboard token (next @Image, legacy lowercase alias such as @image2 for one character) for staging only. Include GPT IMAGE 2 STORYBOARD PROMPT with 1-12 sheet panels and per-shot STORYBOARD PLAN phases, max ${config.storyboardReferenceMode.maxStoryboardPhases}. Do not require ILK FRAME / SON FRAME.` : ""}
 RESPECT LOCKED SHOT COUNT: do not create extra shots outside the assigned range
 
 Generate only assigned SHOT files.

package/packages/multi/content/skills/storyboard-reference/SKILL.md

@@ -13,7 +13,7 @@ Use this skill when the user provides:
 - a video brief or scenario text
 - optional external storyboard guide images
 
-The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. The generated shot storyboard is the staging reference for the final video model prompt.
+The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. If no external storyboard image is supplied, this generated prompt is the mandatory storyboard bootstrap step. The generated shot storyboard is the staging reference for the final video model prompt.
 
 ## Reference Prep
 
@@ -36,9 +36,10 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
-- hard cap: max 4 panels/phases per shot unless the configured project cap is lower
-- split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
+- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
+- hard cap: max 4 video phases per shot unless the configured project cap is lower
+- split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
 - storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
 - annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
@@ -108,6 +109,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
+- storyboard_creation metadata in `SHOTNN.bundle.json`
 - audio plan
 - prompt bundle for requested models
 - QA verdict
@@ -116,6 +118,7 @@ Generated files:
 
 ```text
 $OUTPUT_DIR/storyboard-reference-plan.json
+$OUTPUT_DIR/storyboard-prompt.md
 $OUTPUT_DIR/reference-prep/CHARACTER-SHEET-*.md
 $OUTPUT_DIR/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md
 $OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json

package/packages/multi/content/workflows/generate-storyboard.md

@@ -33,11 +33,12 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - exact identity, wardrobe, accessories, and visible props
    - no labels, text, logos, watermarks, alternate designs, or extra characters
 3. Confirm target models: `veo31`, `seedance-2.0`, `kling-3.0`, or a user-provided subset.
-4. Select shot storyboard panel budget:
-   - 4-6 seconds: 1-2 panels/phases
-   - 7-10 seconds: 2-3 panels/phases
-   - 11-15 seconds: 3-4 panels/phases
-   - 5+ distinct phases: split into multiple `SHOTNN.md` files
+4. Select video phase budget and storyboard sheet panel count:
+   - 4-6 seconds: 1-2 video phases
+   - 7-10 seconds: 2-3 video phases
+   - 11-15 seconds: 3-4 video phases
+   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
    - lighting
@@ -89,7 +90,7 @@ npx @milenyumai/film-kit generate-storyboard \
 - Missing character reference: stop and request a valid reference.
 - Empty brief: stop and request a brief.
 - Public figure / real-person likeness / trademark risk: stop or safely anonymize before prompt generation.
-- 5+ storyboard phases: do not compress into one prompt; split shots.
+- 5+ real video phases: do not compress into one prompt; split shots. 5-12 storyboard sheet panels alone do not force a split.
 - Missing GPT Image 2 character sheet prompt: output is invalid.
 - Missing GPT Image 2 per-shot storyboard prompt: output is invalid.
 - Missing `Avoid` / negative prompt: output is invalid.

package/packages/studio/content/skills/storyboard-reference/SKILL.md

@@ -13,7 +13,7 @@ Use this skill when the user provides:
 - a video brief or scenario text
 - optional external storyboard guide images
 
-The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. The generated shot storyboard is the staging reference for the final video model prompt.
+The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. If no external storyboard image is supplied, this generated prompt is the mandatory storyboard bootstrap step. The generated shot storyboard is the staging reference for the final video model prompt.
 
 ## Reference Prep
 
@@ -36,9 +36,10 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
-- hard cap: max 4 panels/phases per shot unless the configured project cap is lower
-- split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
+- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
+- hard cap: max 4 video phases per shot unless the configured project cap is lower
+- split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
 - storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
 - annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
@@ -108,6 +109,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
+- storyboard_creation metadata in `SHOTNN.bundle.json`
 - audio plan
 - prompt bundle for requested models
 - QA verdict
@@ -116,6 +118,7 @@ Generated files:
 
 ```text
 $OUTPUT_DIR/storyboard-reference-plan.json
+$OUTPUT_DIR/storyboard-prompt.md
 $OUTPUT_DIR/reference-prep/CHARACTER-SHEET-*.md
 $OUTPUT_DIR/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md
 $OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json

package/packages/studio/content/workflows/generate-storyboard.md

@@ -33,11 +33,12 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - exact identity, wardrobe, accessories, and visible props
    - no labels, text, logos, watermarks, alternate designs, or extra characters
 3. Confirm target models: `veo31`, `seedance-2.0`, `kling-3.0`, or a user-provided subset.
-4. Select shot storyboard panel budget:
-   - 4-6 seconds: 1-2 panels/phases
-   - 7-10 seconds: 2-3 panels/phases
-   - 11-15 seconds: 3-4 panels/phases
-   - 5+ distinct phases: split into multiple `SHOTNN.md` files
+4. Select video phase budget and storyboard sheet panel count:
+   - 4-6 seconds: 1-2 video phases
+   - 7-10 seconds: 2-3 video phases
+   - 11-15 seconds: 3-4 video phases
+   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
    - lighting
@@ -89,7 +90,7 @@ npx @milenyumai/film-kit generate-storyboard \
 - Missing character reference: stop and request a valid reference.
 - Empty brief: stop and request a brief.
 - Public figure / real-person likeness / trademark risk: stop or safely anonymize before prompt generation.
-- 5+ storyboard phases: do not compress into one prompt; split shots.
+- 5+ real video phases: do not compress into one prompt; split shots. 5-12 storyboard sheet panels alone do not force a split.
 - Missing GPT Image 2 character sheet prompt: output is invalid.
 - Missing GPT Image 2 per-shot storyboard prompt: output is invalid.
 - Missing `Avoid` / negative prompt: output is invalid.