@milenyumai/film-kit 2.3.4 → 2.3.6

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,11 @@ 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 default to a 12-panel 16:9 production-board sheet: white paper, rough black-and-white pencil drawings, strong silhouettes, visible body/camera momentum, cinematic camera variety, and color-coded planning annotations only. Hard negatives block photorealistic stills, full-color rendered panels, concept-art strips, CGI, anime, and polished illustration.
+- Seedance treats the generated storyboard token as the complete visual/action/camera/choreography source, follows all beats left-to-right/top-to-bottom, and ignores arrows, labels, notes, page headers, timestamps, panel borders, and other annotations 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, style contract, default panel count, reading order, panel count, forbidden visual modes, 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 +220,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`. Default: `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.d.ts

@@ -10,6 +10,7 @@ export declare class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter
     private getMappingEntries;
     private formatCharacterRoleLine;
     private formatStoryboardRoleLine;
+    private hasDanceOrSingingIntent;
     buildPrompt(input: AdapterInput): ModelPromptOutput;
     validate(output: ModelPromptOutput): ModelPromptQa;
 }

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

@@ -40,24 +40,37 @@ export class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter {
         const storyboardEntry = this.getMappingEntries(input, "storyboard_plan")[0];
         const token = storyboardEntry?.token ?? "@Image2";
         const alias = storyboardEntry?.legacyAlias;
-        return `Use ${token} as the shot storyboard reference for composition, blocking, camera direction, timing, action rhythm, and phase order only. Do not copy storyboard text, labels, panel borders, watermarks, logos, or alternate character design from ${token}.${alias ? ` Legacy alias: ${alias}.` : ""}`;
+        return `Use ${token} as the shot storyboard reference and generated storyboard reference image: the complete visual/action/camera/choreography source for beat order, composition, blocking, camera direction, timing, action rhythm, framing variety, and final pose only. Do not copy storyboard text, labels, notes, arrows, panel borders, page headers, watermarks, logos, or alternate character design from ${token}.${alias ? ` Legacy alias: ${alias}.` : ""}`;
+    }
+    hasDanceOrSingingIntent(input) {
+        const combined = [
+            input.request.brief,
+            input.request.audioIntent,
+            input.request.styleIntent,
+            ...input.request.dialogue.map(line => `${line.speaker}: ${line.text}`)
+        ].join(" ").toLowerCase();
+        return /dance|dancing|choreograph|sing|singing|song|vocal|sarki|sark|soyl|dans/.test(combined);
     }
     buildPrompt(input) {
         const audioPlan = buildAudioPlan(input);
         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/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 within one uninterrupted camera move. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose. Compress the full ${input.storyboardImagePrompt.panelCount}-beat sequence into the requested duration as fast readable motion snapshots, not full-length actions. No scene cuts throughout, one continuous shot.`
+            : `Use the generated storyboard reference ${storyboardToken} as the complete visual/action/camera/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 pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose. Compress the full ${input.storyboardImagePrompt.panelCount}-beat sequence into the requested 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 performanceEmphasis = this.hasDanceOrSingingIntent(input)
+            ? "\nFor singing or dance briefs: continuous live singing must show visible breath, synchronized mouth movement, body strain, fabric motion, grounded footwork, floor contact, and phrase-level physical effort across the full movement."
+            : "";
         const promptText = `${this.formatCharacterRoleLine(input)}
 ${this.formatStoryboardRoleLine(input)}
 
 [REFERENCE ROLES]
 - Identity reference: ${characterTokenText} locks face, hair, body proportions, wardrobe, accessories, visible props, and material continuity.
-- Camera reference: ${storyboardToken} controls composition, camera direction, framing, screen direction, shot order, and lens rhythm only.
-- Action reference: ${storyboardToken} controls blocking, pose logic, timing, action rhythm, phase order, and emotional progression only.
+- Storyboard reference image: ${storyboardToken} is the complete visual/action/camera/choreography source.
+- Camera reference: ${storyboardToken} controls composition, camera direction, framing, screen direction, shot order, framing variety, and lens rhythm only.
+- Action reference: ${storyboardToken} controls blocking, pose logic, timing, action rhythm, phase order, choreography, and emotional progression only.
 - Audio reference: use the Audio Plan text below for dialogue, SFX, ambience, and music intent; do not infer audio from storyboard annotations unless explicitly requested.
 
 ${continuityInstruction}
@@ -69,13 +82,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, framing marks, and page headers as planning annotations only; never render storyboard annotations, arrows, labels, notes, timestamps, page headers, 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.${performanceEmphasis}
 
 [AUDIO]
 Dialogue: ${buildDialogueTranscript(input)}.
@@ -84,9 +97,9 @@ Ambience: ${audioPlan.ambience.join(", ")}.
 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.
+Identity reference stays locked to ${characterTokenText}. Storyboard ${storyboardToken} controls staging, shot order, pose logic, camera variety, framing variety, emotional progression, choreography, final pose, 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, page headers, 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, labels, notes, page headers, timestamps, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps. No text, no annotations, no labels, no notes, no timestamps, no page headers, no watermark.`;
         const output = {
             model: this.model,
             displayName: getDisplayName(this.model),
@@ -123,13 +136,16 @@ Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders,
             usesStoryboardToken: output.promptText.includes(storyboardToken) && /shot storyboard reference/i.test(output.promptText),
             followsStoryboardOrder: continuityMode === "continuous-shot"
                 ? hasNoCutsRule
+                    && /Follow all \d+ beats sequentially from left-to-right, top-to-bottom/i.test(output.promptText)
+                    && /Do not reinterpret pose, action, camera angle, emotional progression/i.test(output.promptText)
                 : /left-to-right, top-to-bottom/i.test(output.promptText)
-                    && /Do not reinterpret actions, poses, camera angles, emotional progression/i.test(output.promptText),
+                    && /Do not reinterpret pose, action, camera angle, emotional progression/i.test(output.promptText),
             separatesReferenceRoles: /Identity reference:/i.test(output.promptText)
+                && /Storyboard reference image:/i.test(output.promptText)
                 && /Camera reference:/i.test(output.promptText)
                 && /Action reference:/i.test(output.promptText)
                 && /Audio reference:/i.test(output.promptText),
-            blocksStoryboardIdentitySources: /Storyboard text, panel borders, arrows, colored marks, lens notes, watermark, logo, and alternate character design are never identity sources/i.test(output.promptText),
+            blocksStoryboardIdentitySources: /Storyboard text, panel borders, arrows, colored marks, lens notes, page headers, watermark, logo, and alternate character design are never identity sources/i.test(output.promptText),
             continuityMode: continuityMode === "continuous-shot"
                 ? hasNoCutsRule
                 : !hasNoCutsRule && /storyboard-motivated cuts/i.test(output.promptText),

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,17 @@ function resolvePromptAdapter(model) {
     }
     return adapter;
 }
-function getStoryboardPanelCount(request, phaseBudget) {
-    return request.storyboardPanelCountHint
-        ?? request.shotCountHint
-        ?? phaseBudget.recommendedMaxPhases;
+const MAX_STORYBOARD_SHEET_PANELS = 12;
+const DEFAULT_STORYBOARD_SHEET_PANELS = 12;
+function getStoryboardSheetPanelCount(request) {
+    const panelCount = request.storyboardPanelCountHint ?? DEFAULT_STORYBOARD_SHEET_PANELS;
+    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 +179,46 @@ 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 panelLabel = input.storyboardSheetPanelCount === 1
+        ? "1 cinematic panel"
+        : `${input.storyboardSheetPanelCount} cinematic panels`;
     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.";
+        ? `Because this is a single uninterrupted beat, still create ${panelLabel} as sequential motion snapshots of one continuous camera move. Each panel must clarify entry pose, motion direction, body mechanics, camera shift, and final body intention without implying separate scenes.`
+        : `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,
-        style: "professional-production-storyboard",
+        panelCount: input.storyboardSheetPanelCount,
+        style: "raw-pencil-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: `HARD NEGATIVE STORYBOARD STYLE LOCK:
+Do not create photorealistic cinematic stills.
+Do not create full-color rendered panels.
+Do not create concept art, movie frames, underwater/color-grade panels, 3D render, anime, CGI, or polished illustration.
+Only annotation arrows/marks may use color; all storyboard artwork remains black pencil on white paper.
+
+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 ${shotId} storyboard focused on intense physical movement and clear cinematic action from this scene: ${request.brief}. White paper production layout. 16:9 storyboard sheet, ${panelLabel}. Use exactly ${panelLabel}. 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 production storyboard with black-and-white rough pencil linework. Actual storyboard drawings must be black and white only. Use 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 +307,54 @@ 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,
+        default_panel_count: DEFAULT_STORYBOARD_SHEET_PANELS,
+        style_contract: "raw-pencil-production-storyboard",
+        forbidden_visual_modes: [
+            "photorealistic stills",
+            "full-color panels",
+            "concept-art strip",
+            "CGI render"
+        ],
+        annotation_colors_allowed: true,
+        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 +389,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 +440,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);
+    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 +467,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 +498,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

@@ -128,13 +128,46 @@ export interface StoryboardImagePrompt {
     provider: "gpt-image-2";
     aspectRatio: "16:9";
     panelCount: number;
-    style: "professional-production-storyboard";
+    style: "raw-pencil-production-storyboard";
     characterSheetIds: string[];
     externalStoryboardGuideIds: string[];
     previousShotHandoff: string;
     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;
+    default_panel_count: 12;
+    style_contract: "raw-pencil-production-storyboard";
+    forbidden_visual_modes: [
+        "photorealistic stills",
+        "full-color panels",
+        "concept-art strip",
+        "CGI render"
+    ];
+    annotation_colors_allowed: true;
+    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 +287,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,15 @@ 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_text === bundle.storyboardImagePrompt.promptText
+            && bundle.storyboard_creation?.prompt_path === bundle.storyboardImagePrompt.outputPath
+            && bundle.storyboard_creation?.panel_count === bundle.storyboardImagePrompt.panelCount
+            && bundle.storyboard_creation?.default_panel_count === 12
+            && bundle.storyboard_creation?.style_contract === "raw-pencil-production-storyboard"
+            && bundle.storyboard_creation?.forbidden_visual_modes.includes("photorealistic stills")
+            && bundle.storyboard_creation?.annotation_colors_allowed === true
+            && 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,11 +36,13 @@ 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 is 12 cinematic panels in one GPT Image 2 storyboard sheet; an explicit storyboard panel hint may request 1-12 panels
+- 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
+- storyboard art grammar: white paper 16:9 production storyboard sheet, actual drawings black and white only, rough pencil lines, minimal detail, fast gesture drawing energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- hard negative style lock: do not create photorealistic cinematic stills, full-color rendered panels, concept art, movie frames, underwater/color-grade panels, 3D render, anime, CGI, or polished illustration
 - 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
 - continuity: include previous shot handoff, next shot handoff, shared `visual_world`, screen direction, lighting, and action rhythm
 
@@ -75,9 +77,10 @@ Seedance 2.0:
 - Map character sheet images to `@Image1`, `@Image2`, ... with legacy aliases `@image1`, `@image2`, ...
 - Map the generated shot storyboard to the next image token, for example one character means `@Image2`, two characters means `@Image3`.
 - Character image tokens control identity, face, body proportions, wardrobe, accessories, and visible props.
-- The storyboard token controls composition, blocking, camera direction, timing, action rhythm, and phase order only.
-- Follow generated storyboard panels left-to-right, top-to-bottom. Do not reinterpret the action, pose logic, camera angle, emotional progression, frame variety, or final pose.
-- Treat storyboard arrows, labels, lens notes, and colored marks as planning annotations only; never render them into the video.
+- The storyboard token is the complete visual/action/camera/choreography source and controls composition, blocking, camera direction, timing, action rhythm, framing variety, final pose, and phase order only.
+- Follow all storyboard beats left-to-right, top-to-bottom. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose.
+- Compress the full 12-beat default storyboard sheet into the requested duration as readable motion snapshots while preserving the duration-aware video phase budget.
+- Treat storyboard arrows, labels, notes, lens notes, page headers, panel borders, and colored marks as planning annotations only; never render them into the video.
 - Use explicit timeline phases when the storyboard has multiple beats.
 - Use `No scene cuts throughout, one continuous shot` only for a true single uninterrupted camera move.
 - For multi-phase storyboard prompts, use only the planned phase transitions and do not add unplanned cuts.
@@ -108,6 +111,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 +120,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