@milenyumai/film-kit 2.3.3 → 2.3.5

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.