@milenyumai/film-kit 2.2.0 → 2.3.0

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

@@ -8,7 +8,24 @@ function getModelDisplayName(model) {
 function getKlingPresetDisplay(model, klingPreset) {
     return model === "kling-3.0" ? klingPreset : "n/a (Kling-only)";
 }
-function buildSeedanceProfile(active) {
+function isSeedanceStoryboardReference(config) {
+    return config.model === "seedance-2.0"
+        && config.referenceMode === "storyboard-reference"
+        && config.storyboardReferenceMode.enabled;
+}
+function buildReferenceModeSummary(config) {
+    if (!isSeedanceStoryboardReference(config)) {
+        return `- Reference mode: \`${config.referenceMode}\`
+- Start/end frame chaining contract: active`;
+    }
+    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
+- Provider reference tokens: generated character sheet tokens first, generated shot storyboard token next
+- Start/end frame chaining contract: disabled for Seedance storyboard-reference`;
+}
+function buildSeedanceProfile(active, storyboardReferenceActive, maxStoryboardPhases) {
     return `## Seedance 2.0 Rules${active ? " (ACTIVE)" : " (Reference)"}
 
 ### Capability Mindset
@@ -17,12 +34,13 @@ Seedance 2.0 responds best when you assign **explicit multimodal control roles**
 - videos lock motion grammar, body action, or vocal tone
 - audio references guide music or ambience behavior
 - text explains only the evolution and interaction between those materials
+- provider image tokens use \`@Image1\`, \`@Image2\`, ...; legacy lowercase \`@image1\`, \`@image2\`, ... remain accepted aliases in Film-Kit text
 
 ### Core Prompt Grammar
-- Name the role of each asset directly with \`@image1\`, \`@video1\`, and \`@audio1\`
+- Name the role of each asset directly with \`@Image1\`, \`@video1\`, and \`@audio1\`
 - For long clips, use timeline segmentation: \`0-3s: ... / 3-6s: ... / 6-10s: ...\`
 - Replace abstract emotion labels with visible acting cues: eyes, breath, shoulders, hands, mouth
-- If the clip must stay unbroken, close with: \`No scene cuts throughout, one continuous shot.\`
+- If the clip must stay unbroken, close with: \`No scene cuts throughout, one continuous shot.\`; do not apply this to planned storyboard phase transitions
 - For extensions, specify only the newly generated seconds and begin from the exact last-frame state
 
 ### Reference Binding Strategy
@@ -37,6 +55,14 @@ Seedance 2.0 responds best when you assign **explicit multimodal control roles**
 - Use continuous-shot language for location traversals instead of hidden cut logic
 - Escalate speed and intensity explicitly; do not compress several beats into one vague sentence
 - For complex clips, prefer timeline segments over overloaded paragraphs
+${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
+- 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`
+        : ""}
 
 ### Video Extension Rules
 - Use extension syntax like \`Extend @video1 by 5s\`
@@ -51,7 +77,7 @@ Seedance 2.0 responds best when you assign **explicit multimodal control roles**
 
 ### Failure Recovery
 - Camera motion mismatch: say \`completely reference all camera movement effects from @video1\`
-- Character drift: say \`maintain character appearance exactly consistent with @image1\` and add more angles
+- Character drift: say \`maintain character appearance exactly consistent with @Image1\` and add more angles
 - Extension seam feels off: describe the original last frame before the new action begins
 - Flat acting: replace general mood words with visible facial/body behavior
 
@@ -68,7 +94,7 @@ Seedance 2.0 responds best when you assign **explicit multimodal control roles**
 
 **Template A — Multimodal Continuous Shot**
 \`\`\`
-Use @image1 as the first frame. Reference camera movement from @video1 and atmosphere from @audio1.
+Use @Image1 as the first frame. Reference camera movement from @video1 and atmosphere from @audio1.
 One continuous tracking shot from location A through location B into location C.
 0-3s: establish subject, scale, and path.
 3-6s: introduce one major action or environmental shift.
@@ -78,7 +104,7 @@ No scene cuts throughout, one continuous shot.
 
 **Template B — Performance Beat**
 \`\`\`
-Maintain character appearance exactly consistent with @image1.
+Maintain character appearance exactly consistent with @Image1.
 0-2s: eyes shift, breath shortens, fingers tighten around the prop.
 2-4s: camera pushes closer as the line is delivered in a restrained voice.
 4-6s: expression softens, shoulders lower, and the scene returns to calm.
@@ -121,7 +147,7 @@ const MULTI_CODEX_AGENTS = [
     ["dialogue-auditor", "dialogue_auditor", "Audit dialogue tone, voiceCast binding, SFX accuracy, and audio direction completeness."],
     ["character-consistency-auditor", "character_consistency_auditor", "Audit character description consistency and anonymous identity stability."],
     ["color-continuity-auditor", "color_continuity_auditor", "Audit lighting direction and color temperature consistency across same-scene shots."],
-    ["semantic-auditor", "semantic_auditor", "Audit visual_world, perspective, shadows, scale, reflections, physics, anatomy, context, and chained ILK reuse."],
+    ["semantic-auditor", "semantic_auditor", "Audit visual_world, perspective, shadows, scale, reflections, physics, anatomy, context, and continuity contracts."],
     ["pacing-auditor", "pacing_auditor", "Audit shot sequence rhythm, tempo variety, and dramatic arc alignment."],
     ["delivery-editor", "delivery_editor", "Audit final package completeness, report dependencies, and delivery readiness."]
 ];
@@ -136,10 +162,12 @@ ${leadDirectorNote}
 Keep outputs under ${config.outputDir} unless the user explicitly changes the output contract.
 For worktree runs, if node_modules or build outputs are missing and package.json exists, bootstrap with npm install and npm run build before package commands.`);
 }
-function buildCodexImageSkill(workflowFile, outputDir) {
+function buildCodexImageSkill(workflowFile, config) {
+    const outputDir = config.outputDir;
+    const storyboardReferenceActive = isSeedanceStoryboardReference(config);
     return `---
 name: film-kit-codex-images
-description: Optional Codex-native still image phase for Film-Kit Multi. Use after successful prompt generation when the user wants to create or iteratively edit accepted ILK FRAME and SON FRAME images inside Codex. Never auto-start; offer it only after all required reports pass and the user confirms.
+description: Optional Codex-native still image phase for Film-Kit Multi. Use after successful prompt generation when the user wants ${storyboardReferenceActive ? "optional character sheet or generated storyboard still prep" : "to create or iteratively edit accepted ILK FRAME and SON FRAME images"} inside Codex. Never auto-start; offer it only after all required reports pass and the user confirms.
 ---
 
 # Film-Kit Codex Images
@@ -162,20 +190,27 @@ This skill is for **Codex only**. It adds a still-image phase after Film-Kit pro
 ## Core Behavior
 - Use Codex's built-in image generation/editing flow.
 - If a local image file must be edited, first bring it into the conversation context, then edit it.
-- Generate \`ILK FRAME\` from the accepted shot prompt plus references.
+${storyboardReferenceActive
+        ? `- Storyboard-reference mode does not require \`ILK FRAME\` / \`SON FRAME\` assets.
+- If the user asks for still prep, create or edit character sheet images and generated shot storyboard images from the accepted GPT Image 2 prompts while preserving the shot \`STORYBOARD PLAN\`.
+- Keep generated still metadata under \`${outputDir}/codex-images/manifest.json\` and do not convert storyboard-reference shots back into start/end frame chaining.`
+        : `- Generate \`ILK FRAME\` from the accepted shot prompt plus references.
 - Generate \`SON FRAME\` by iterating from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
-- For chained shots, default the next shot's \`ILK FRAME\` to the previously accepted \`SON FRAME\` unless the user explicitly requests a fresh start.
+- For chained shots, default the next shot's \`ILK FRAME\` to the previously accepted \`SON FRAME\` unless the user explicitly requests a fresh start.`}
 - After every image, ask the user to accept it or request a targeted edit.
 
 ## Output Contract
 - Save accepted stills under \`${outputDir}/codex-images/SHOTNN/\`
-- Canonical files: \`ilk-frame.png\`, \`son-frame.png\`
-- Iterations use sibling versioned filenames such as \`ilk-frame-v2.png\` and \`son-frame-v3.png\`
+${storyboardReferenceActive
+        ? "- Canonical files are optional role-specific references such as `character-sheet.png` and `shot-storyboard.png` when requested"
+        : "- Canonical files: `ilk-frame.png`, `son-frame.png`\n- Iterations use sibling versioned filenames such as `ilk-frame-v2.png` and `son-frame-v3.png`"}
 - Keep \`${outputDir}/codex-images/manifest.json\` updated
 - Keep \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` updated
 `;
 }
-function buildCodexImagesWorkflow(outputDir) {
+function buildCodexImagesWorkflow(config) {
+    const outputDir = config.outputDir;
+    const storyboardReferenceActive = isSeedanceStoryboardReference(config);
     return `---
 description: Optional Codex-native still image phase for Film-Kit Multi output
 ---
@@ -198,30 +233,37 @@ description: Optional Codex-native still image phase for Film-Kit Multi output
 \`\`\`text
 ${outputDir}/codex-images/
 ├── SHOTNN/
-│   ├── ilk-frame.png
+${storyboardReferenceActive
+        ? "│   ├── character-reference.png\n│   └── storyboard-reference.png"
+        : `│   ├── ilk-frame.png
 │   ├── ilk-frame-v2.png
 │   ├── son-frame.png
-│   └── son-frame-v3.png
+│   └── son-frame-v3.png`}
 ├── manifest.json
 └── ../reports/CODEX-IMAGE-REPORT.md
 \`\`\`
 
 ## Flow
 1. Process shots sequentially unless the user explicitly requests a different order.
-2. For a fresh shot, generate \`ILK FRAME\` from the accepted still prompt plus references.
+${storyboardReferenceActive
+        ? `2. For storyboard-reference projects, do not require start/end frame stills.
+3. If the user requests still prep, create or edit character identity references and storyboard planning references.
+4. Preserve \`STORYBOARD PLAN\` role separation: identity stills cannot inherit storyboard character design, and storyboard stills cannot override identity/wardrobe/props.
+5. Update \`${outputDir}/codex-images/manifest.json\` and \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` after each accepted reference.`
+        : `2. For a fresh shot, generate \`ILK FRAME\` from the accepted still prompt plus references.
 3. Show the result and ask the user to accept it or request a targeted edit.
 4. Save the accepted start image as \`ilk-frame.png\`; keep previous attempts as versioned siblings.
 5. Generate \`SON FRAME\` by editing from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
 6. Show the result and ask the user to accept it or request a targeted edit.
 7. Save the accepted end image as \`son-frame.png\`; keep previous attempts as versioned siblings.
-8. If the next shot is chained, default its \`ILK FRAME\` to the accepted previous \`SON FRAME\` unless the user explicitly asks for a fresh start.
-9. Update \`${outputDir}/codex-images/manifest.json\` and \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` after each accepted image.
+8. If the next shot is chained, default its \`ILK FRAME\` to the accepted previous \`SON FRAME\` unless the user explicitly asks for a fresh start.`}
+${storyboardReferenceActive ? "" : `9. Update \`${outputDir}/codex-images/manifest.json\` and \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` after each accepted image.`}
 
 ## Hard Rules
 - Never auto-start this workflow.
-- V1 covers only main-shot \`ILK FRAME\` and \`SON FRAME\`.
+- ${storyboardReferenceActive ? "Storyboard-reference mode covers optional reference still prep only; it does not introduce ILK/SON requirements." : "V1 covers only main-shot `ILK FRAME` and `SON FRAME`."}
 - Do not generate coverage stills or video here.
-- Preserve chain continuity unless the user explicitly requests a reset.
+- Preserve ${storyboardReferenceActive ? "storyboard handoff continuity" : "chain continuity"} unless the user explicitly requests a reset.
 `;
 }
 /**
@@ -230,6 +272,7 @@ ${outputDir}/codex-images/
  */
 export function buildMultiProjectFiles(config) {
     const files = {};
+    const storyboardReferenceActive = isSeedanceStoryboardReference(config);
     // Runtime model profile file is generated from selected model options.
     files[".agent/model-profile.md"] = buildModelProfile(config);
     files["CLAUDE.md"] = buildClaudeRoot(config);
@@ -266,6 +309,15 @@ export function buildMultiProjectFiles(config) {
 2. Create \`${config.outputDir}/_index.md\`
 3. Create \`${config.outputDir}/team-plan.json\` with:
    - model target and preset
+   - \`project.reference_mode\`: \`${storyboardReferenceActive ? "storyboard-reference" : config.referenceMode}\`
+   - \`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.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"}
    - \`project.estimated_runtime_seconds\`
    - \`shot_sizing.method\` and global rationale
    - \`shot_sizing.min_functional_shots\`
@@ -277,7 +329,7 @@ export function buildMultiProjectFiles(config) {
    - voice defaults (\`voice_design.single_active_speaker_required\`, \`music_default\`, \`subtitles_default\`)
    - shot-level speaker binding map under \`shots\`
    - shot count and batch map
-   - chain bridges per batch boundary
+   - ${storyboardReferenceActive ? "storyboard handoff notes per shot and per batch boundary" : "chain bridges per batch boundary"}
    - teammate assignments
    - validation gates
    - recovery policy
@@ -296,11 +348,12 @@ BATCH ID: B[NN]
 BATCH RANGE: SHOT[X] through SHOT[Y]
 OUTPUT DIR: ${config.outputDir}/shots/
 REPORT FILE: ${config.outputDir}/reports/BATCH-REPORT-B[NN].md
-CHAIN ENTRY FRAME: [exact frame description]
+${storyboardReferenceActive ? "STORYBOARD ENTRY HANDOFF: [visual_world-aligned opening state and prior-shot action handoff]" : "CHAIN ENTRY FRAME: [exact frame description]"}
 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.` : ""}
 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.
@@ -330,7 +383,7 @@ VOICE CONTRACT: Reuse ${config.outputDir}/team-plan.json -> \`voiceCast\` and ke
    - dialogue-auditor for dialogue tone, \`voiceCast\` binding, SFX scene match, and audio direction checks
    - character-consistency-auditor for character description drift and anonymous identity checks
    - color-continuity-auditor for lighting direction and color temperature consistency checks
-   - semantic-auditor for visual_world, perspective/geometry, shadow vector, scale, reflections, physics/anatomy, foreground/background coherence, contextual contradiction, targeted avoid terms, and chained ILK exact reuse
+   - semantic-auditor for visual_world, perspective/geometry, shadow vector, scale, reflections, physics/anatomy, foreground/background coherence, contextual contradiction, targeted avoid terms, and ${storyboardReferenceActive ? "storyboard-reference handoff continuity" : "chained ILK exact reuse"}
    - pacing-auditor for shot sequence rhythm, tempo variety, and dramatic arc alignment checks
    **Phase C — Delivery gate (must run last, depends on all other reports):**
    - delivery-editor for final package audit
@@ -357,14 +410,24 @@ VOICE CONTRACT: Reuse ${config.outputDir}/team-plan.json -> \`voiceCast\` and ke
 - Model: \`${config.model}\`
 - Model display: ${getModelDisplayName(config.model)}
 - Kling preset: \`${getKlingPresetDisplay(config.model, config.klingPreset)}\`
+- Reference mode: \`${storyboardReferenceActive ? "storyboard-reference" : config.referenceMode}\`
 - Kling transition mode: Start+End (when model is kling-3.0)
 - Kling professional blocks: \`[CHARACTER / SUBJECT CONSISTENCY]\` through \`[NEGATIVE PROMPT]\` (when model is kling-3.0)
 - Kling multi-shot mode: single-transition by default; custom storyboard only for 2-4 meaningful phases, max 4 custom shots (when model is kling-3.0)
+${storyboardReferenceActive ? `- Seedance storyboard-reference mode: \`INPUT ASSET ROLES\`, \`REFERENCE ASSET REQUIREMENTS\`, \`GPT IMAGE 2 STORYBOARD PROMPT\`, \`STORYBOARD PLAN\`, and timeline phases are mandatory; \`ILK FRAME\` / \`SON FRAME\` are not required` : ""}
 
 ## Shot File Format (SHOTNN.md)
-- Main shot contains: \`ILK FRAME\` (or \`İLK FRAME\`), \`SON FRAME\`, \`AUDIO PLAN\`, \`VIDEO\` (or \`VİDEO\`)
+${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
+- \`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`
+        : `- Main shot contains: \`ILK FRAME\` (or \`İLK FRAME\`), \`SON FRAME\`, \`AUDIO PLAN\`, \`VIDEO\` (or \`VİDEO\`)
 - \`ILK FRAME\` section MUST include a fenced code block, even when chained
-- Chained shots: code block must contain only \`Use SHOT[prev]_END as exact first frame\`; any new visual prompt requires \`CHAIN BREAK\`
+- Chained shots: code block must contain only \`Use SHOT[prev]_END as exact first frame\`; any new visual prompt requires \`CHAIN BREAK\``}
 - Every prompt must align to \`${config.outputDir}/team-plan.json -> visual_world\` for perspective/geometry, shadow vector, scale, reflection, physics, anatomy risk, foreground/background coherence, and contextual contradiction checks
 - Coverage section contains 2-3 sub-shots in the same file
 - Every prompt includes an Avoid line
@@ -375,7 +438,7 @@ VOICE CONTRACT: Reuse ${config.outputDir}/team-plan.json -> \`voiceCast\` and ke
 - ONE FILE PER SHOT
 - No separate coverage files
 - Coverage is standalone (not chained)
-- Main shots are chained: SHOT[N]_END -> SHOT[N+1]_START
+- ${storyboardReferenceActive ? "Main-shot continuity uses shared visual_world plus storyboard handoff notes, character lock, camera direction, lighting, and action progression" : "Main shots are chained: SHOT[N]_END -> SHOT[N+1]_START"}
 
 ## Batch Report Contract
 Each shot teammate must write a report file:
@@ -383,8 +446,8 @@ Each shot teammate must write a report file:
 # BATCH REPORT | B[NN]
 - batch_range: SHOT[X]-SHOT[Y]
 - files_written: [SHOTXX.md, ...]
-- chain_entry_used: [text]
-- chain_exit_frame: [text]
+- ${storyboardReferenceActive ? "storyboard_entry_handoff" : "chain_entry_used"}: [text]
+- ${storyboardReferenceActive ? "storyboard_exit_handoff" : "chain_exit_frame"}: [text]
 - continuity_status: pass/fail
 - safety_status: pass/fail
 - voice_design_status: pass/fail
@@ -445,7 +508,7 @@ Specialist reports must use explicit non-contradictory status fields:
 - overall_status: pass/fail
 - visual_world_status: pass/fail
 - reference_drift_status: pass/fail
-- start_end_contract_status: pass/fail
+- ${storyboardReferenceActive ? "storyboard_reference_status" : "start_end_contract_status"}: pass/fail
 - perspective_geometry_status: pass/fail
 - shadow_vector_status: pass/fail
 - scale_depth_status: pass/fail
@@ -453,7 +516,7 @@ Specialist reports must use explicit non-contradictory status fields:
 - anatomy_physics_status: pass/fail
 - foreground_background_status: pass/fail
 - contextual_contradiction_status: pass/fail
-- chained_ilk_frame_status: pass/fail
+- ${storyboardReferenceActive ? "storyboard_handoff_status" : "chained_ilk_frame_status"}: pass/fail
 - avoid_terms_status: pass/fail
 - blockers: [none or list]
 
@@ -481,7 +544,7 @@ Specialist reports must use explicit non-contradictory status fields:
 - Include all task-specific context needed (no hidden assumptions)
 - Never rely on prior lead conversation history carrying over
 - Reference exact file paths for input/output
-- Include chain entry frame description (minimum 40 words)
+- Include ${storyboardReferenceActive ? "storyboard entry handoff and shared visual_world summary" : "chain entry frame description (minimum 40 words)"}
 - Declare batch ID and exact shot range
 - Require report file path under \`${config.outputDir}/reports/\`
 - Pass required \`speakerKey\` / \`voiceCast\` context from \`${config.outputDir}/team-plan.json\`
@@ -489,7 +552,7 @@ Specialist reports must use explicit non-contradictory status fields:
 
 ### Teammate -> Lead Messages
 - Confirm report file path written
-- Include chain exit frame description
+- Include ${storyboardReferenceActive ? "storyboard exit handoff description" : "chain exit frame description"}
 - Include issue list and blockers
 - Confirm safety and coverage checks
 
@@ -500,7 +563,7 @@ Specialist reports must use explicit non-contradictory status fields:
 - dialogue-auditor scans all shot files for dialogue tone consistency, \`voiceCast\` binding, SFX scene match, audio direction completeness, and single-active-speaker compliance
 - character-consistency-auditor scans all shot files for character description drift and anonymous identity stability
 - color-continuity-auditor scans all shot files for lighting direction and color temperature consistency within same-scene shots
-- semantic-auditor scans all shot files for visual_world, perspective/geometry, shadow vector, scale, reflections, physics/anatomy, foreground/background coherence, contextual contradiction, chained ILK exact reuse, and targeted avoid terms
+- semantic-auditor scans all shot files for visual_world, perspective/geometry, shadow vector, scale, reflections, physics/anatomy, foreground/background coherence, contextual contradiction, ${storyboardReferenceActive ? "storyboard handoff continuity" : "chained ILK exact reuse"}, and targeted avoid terms
 - pacing-auditor scans all shot files for rhythm monotony, dramatic arc mismatches, and transition variety
 - delivery-editor audits completeness and final delivery gates
 - Required specialist reports: CONTINUITY-REPORT.md, SAFETY-REPORT.md, STABILITY-REPORT.md, DIALOGUE-REPORT.md, CHARACTER-REPORT.md, COLOR-REPORT.md, SEMANTIC-REPORT.md, PACING-REPORT.md, DELIVERY-REPORT.md
@@ -533,7 +596,7 @@ Use this playbook when a teammate fails or a quality gate fails.
 - Chain continuity break between batches
 - Safety failures not resolved in place
 - Broken \`voiceCast\` / \`activeSpeakerKey\` binding
-- Broken \`visual_world\`, semantic consistency failure, or chained ILK block with competing visual prompt
+- Broken \`visual_world\`, semantic consistency failure, or ${storyboardReferenceActive ? "storyboard handoff contradiction" : "chained ILK block with competing visual prompt"}
 
 ## Impacted Range Definition
 - **Impacted range** = the failed batch + adjacent batch boundaries (one shot before, one shot after)
@@ -563,8 +626,8 @@ Use this playbook when a teammate fails or a quality gate fails.
     for (const [roleFile, name, description] of MULTI_CODEX_AGENTS) {
         files[`.codex/agents/${roleFile}.toml`] = buildMultiCodexAgent(roleFile, name, description, config);
     }
-    files[".agents/skills/film-kit-codex-images/SKILL.md"] = buildCodexImageSkill(".agent/workflows/codex-images-multi.md", config.outputDir);
-    files[".agent/workflows/codex-images-multi.md"] = buildCodexImagesWorkflow(config.outputDir);
+    files[".agents/skills/film-kit-codex-images/SKILL.md"] = buildCodexImageSkill(".agent/workflows/codex-images-multi.md", config);
+    files[".agent/workflows/codex-images-multi.md"] = buildCodexImagesWorkflow(config);
     if (config.includeAgentsMd) {
         files["AGENTS.md"] = `# Film-Kit Multi - Agent Teams Contract
 
@@ -636,6 +699,7 @@ Multi-agent parallel generation with shot teammates and specialist validators.
 | visual-modes | \`.agent/skills/visual-modes/SKILL.md\` | ALWAYS |
 | audio-design | \`.agent/skills/audio-design/SKILL.md\` | Dialogue/SFX |
 | prompt-structure | \`.agent/skills/prompt-structure/SKILL.md\` | ALWAYS |
+${storyboardReferenceActive ? "| storyboard-reference | `.agent/skills/storyboard-reference/SKILL.md` | Seedance storyboard-reference mode |\n" : ""}
 
 ## Config
 - Max shot teammates: ${config.maxTeammates}
@@ -644,6 +708,8 @@ Multi-agent parallel generation with shot teammates and specialist validators.
 - Scenario: \`${config.scenarioHint}\`
 - Model: \`${config.model}\` (${getModelDisplayName(config.model)})
 - Kling preset: \`${getKlingPresetDisplay(config.model, config.klingPreset)}\`
+- Reference mode: \`${storyboardReferenceActive ? "storyboard-reference" : config.referenceMode}\`
+${storyboardReferenceActive ? `- Storyboard max phases: ${config.storyboardReferenceMode.maxStoryboardPhases}` : ""}
 `;
     }
     return files;
@@ -680,7 +746,7 @@ Lead-directed parallel generation with Claude Code Agent Teams. Use native proje
 Before ANY work, read ALL skills from \`.agent/skills/\`:
 1. \`safety-compliance/SKILL.md\` - ALWAYS FIRST
 2. \`reference-locking/SKILL.md\` - When reference images provided
-3. \`frame-chaining/SKILL.md\` - ALWAYS (chain entry/exit planning)
+3. \`frame-chaining/SKILL.md\` - ALWAYS (${isSeedanceStoryboardReference(config) ? "start/end reference only; storyboard handoff is active" : "chain entry/exit planning"})
 4. \`director-shot-sizing/SKILL.md\` - Lead planning only; lock target shot count before batch sizing
 5. \`spatial-blocking/SKILL.md\` - When gaze / scale / compositing realism matters
 6. \`semantic-consistency/SKILL.md\` - ALWAYS (visual_world + semantic QA)
@@ -688,6 +754,7 @@ Before ANY work, read ALL skills from \`.agent/skills/\`:
 8. \`visual-modes/SKILL.md\` - ALWAYS (Ultra Realism default)
 9. \`audio-design/SKILL.md\` - When dialogue/SFX needed
 10. \`prompt-structure/SKILL.md\` - ALWAYS (prompt templates)
+${isSeedanceStoryboardReference(config) ? "11. `storyboard-reference/SKILL.md` - Seedance character-sheet + generated storyboard prompt mode" : ""}
 
 ## /generate Contract
 1. Read \`.agent/workflows/generate-multi.md\`
@@ -710,11 +777,11 @@ Before ANY work, read ALL skills from \`.agent/skills/\`:
 - Target shot count must be justified by dramatic units; never inflate or compress arbitrarily
 - ONE FILE PER SHOT: each SHOTNN.md includes main shot + coverage
 - Each teammate owns a disjoint file set; no overlapping shot or report files
-- Image prompt contract: reference-anchored ILK/SON use \`REFERENCE LOCK\` + \`Keep same\` + \`Change only\`; VIDEO >= 120; coverage video >= 70
+- ${isSeedanceStoryboardReference(config) ? "Storyboard prompt contract: generated character sheet tokens lock identity, generated shot storyboard token controls staging only; GPT IMAGE 2 STORYBOARD PROMPT is required; SEEDANCE VIDEO PROMPT >= 120; coverage video >= 70" : "Image prompt contract: reference-anchored ILK/SON use `REFERENCE LOCK` + `Keep same` + `Change only`; VIDEO >= 120; coverage video >= 70"}
 - Specificity floor: lens/framing, lighting, and foreground/midground/background action are mandatory
 - Spatial realism floor: eyeline target, plane map, shared light source, and contact/depth cues are mandatory when relational staging matters
-- Semantic consistency floor: \`visual_world\`, perspective/geometry, shadow vector, scale map, reflections, gravity/contact physics, anatomy risk, foreground/background coherence, contextual contradictions, targeted semantic avoid terms, and chained ILK exact reuse are mandatory
-- Chained ILK/İLK FRAME code block contains only \`Use SHOT[prev]_END as exact first frame\`; any new visual prompt requires CHAIN BREAK
+- ${isSeedanceStoryboardReference(config) ? "Seedance storyboard-reference contract: each SHOTNN.md contains INPUT ASSET ROLES, REFERENCE ASSET REQUIREMENTS, GPT IMAGE 2 STORYBOARD PROMPT, STORYBOARD PLAN, AUDIO PLAN, SEEDANCE VIDEO PROMPT, and coverage; ILK FRAME / SON FRAME are not required" : "Semantic consistency floor: `visual_world`, perspective/geometry, shadow vector, scale map, reflections, gravity/contact physics, anatomy risk, foreground/background coherence, contextual contradictions, targeted semantic avoid terms, and chained ILK exact reuse are mandatory"}
+- ${isSeedanceStoryboardReference(config) ? `Storyboard phases derive from \`${config.outputDir}/team-plan.json -> visual_world\`; continuity uses shot-to-shot storyboard handoff notes, character/reference lock, camera direction, lighting, and action progression` : "Chained ILK/İLK FRAME code block contains only `Use SHOT[prev]_END as exact first frame`; any new visual prompt requires CHAIN BREAK"}
 - Avoid line is mandatory on every prompt
 - Music is NONE by default
 - Duration is 8s default, slow pacing
@@ -732,6 +799,7 @@ Before ANY work, read ALL skills from \`.agent/skills/\`:
 - Scenario source: \`${config.scenarioHint}\`
 - Model: \`${config.model}\` (${getModelDisplayName(config.model)})
 - Kling preset: \`${getKlingPresetDisplay(config.model, config.klingPreset)}\`
+${buildReferenceModeSummary(config)}
 
 ## Claude Code Ops
 - Use \`/memory\` to verify which CLAUDE and rule files are loaded
@@ -753,7 +821,7 @@ This workspace keeps high-level policy in \`CLAUDE.md\` and execution detail in
 6. Use director-shot-sizing to lock target shot count before teammate sizing
 7. Size the team from actual shot count; default to 3-5 teammates, hard cap ${config.maxTeammates}
 8. Remember teammates inherit project context (\`CLAUDE.md\`, MCP, skills) but not the lead chat history
-9. Every spawn prompt must include exact shot range, chain entry, output path, report path, and ownership boundaries
+9. Every spawn prompt must include exact shot range, ${isSeedanceStoryboardReference(config) ? "storyboard entry handoff" : "chain entry"}, output path, report path, and ownership boundaries
 10. Wait for all teammate reports before specialist validation
 11. Do not close while any required report is missing or fail
 
@@ -765,8 +833,8 @@ This workspace keeps high-level policy in \`CLAUDE.md\` and execution detail in
 - Keep top-level \`voiceCast\` in \`${config.outputDir}/team-plan.json\`
 - Keep top-level \`visual_world\` in \`${config.outputDir}/team-plan.json\`
 - Keep \`Audio Plan\` blocks aligned to \`voiceCast\`
-- Image prompt contract, specificity floor, and semantic floor are hard gates, not suggestions
-- Semantic consistency floor is a hard gate, including exact chained ILK reuse and \`visual_world\` alignment
+- ${isSeedanceStoryboardReference(config) ? "Storyboard-reference role separation, specificity floor, and semantic floor are hard gates, not suggestions" : "Image prompt contract, specificity floor, and semantic floor are hard gates, not suggestions"}
+- ${isSeedanceStoryboardReference(config) ? "Semantic consistency floor is a hard gate, including shared visual_world alignment and storyboard handoff continuity" : "Semantic consistency floor is a hard gate, including exact chained ILK reuse and `visual_world` alignment"}
 - Do not let teammates create extra SHOT files beyond the locked batch ranges
 - Spawn prompts must pass spatial and semantic contracts: gaze target, plane map, shared light, contact/depth cues, shadow vector, scale map, reflections, physics, and contextual logic
 
@@ -812,12 +880,14 @@ Own only:
 Never write shot prompts directly. Do not finalize until every required report exists and passes. In Codex, once all required reports pass, offer \`/codex-images\` as an optional still-image phase and wait for explicit user confirmation. Keep top-level \`voiceCast\` and \`visual_world\` in \`${config.outputDir}/team-plan.json\`, lock director-grade shot count before teammate sizing, then enforce spatial, semantic, and voice contracts in teammate assignments.`);
 }
 function buildClaudeShotGeneratorSubagent(config) {
-    return buildClaudeSubagent("shot-generator", "Generate assigned Film-Kit multi batches with strict chaining, coverage, anonymity, and report output.", `Read \`.agent/model-profile.md\`, \`.agent/MASTER.md\`, \`.agent/VOICE-DESIGN.md\`, \`.agent/agents/shot-generator.md\`, and \`.agent/workflows/generate-teammate.md\`.
+    return buildClaudeSubagent("shot-generator", isSeedanceStoryboardReference(config)
+        ? "Generate assigned Seedance storyboard-reference batches with coverage, handoff continuity, anonymity, and report output."
+        : "Generate assigned Film-Kit multi batches with strict chaining, coverage, anonymity, and report output.", `Read \`.agent/model-profile.md\`, \`.agent/MASTER.md\`, \`.agent/VOICE-DESIGN.md\`, \`.agent/agents/shot-generator.md\`, and \`.agent/workflows/generate-teammate.md\`.
 
 Own only assigned shot files under \`${config.outputDir}/shots/\` and one batch report under \`${config.outputDir}/reports/\`.
 
 Hard gates:
-- reference-anchored ILK/SON use \`REFERENCE LOCK\` + \`Keep same\` + \`Change only\`
+- ${isSeedanceStoryboardReference(config) ? "generated character sheet tokens lock identity, wardrobe, accessories, and visible props; generated shot storyboard token controls composition, blocking, camera direction, timing, and action progression only" : "reference-anchored ILK/SON use `REFERENCE LOCK` + `Keep same` + `Change only`"}
 - VIDEO >= 120
 - coverage video >= 70
 - every speaking VIDEO section must include \`Audio Plan\`
@@ -825,7 +895,7 @@ Hard gates:
 - lens/framing, lighting, and FG/MG/BG action must be explicit
 - eyeline target, plane map, shared light source, and contact/depth cues must be explicit when subjects interact
 - semantic consistency must match \`${config.outputDir}/team-plan.json -> visual_world\`
-- chained ILK/İLK FRAME code block must contain only \`Use SHOT[prev]_END as exact first frame\`
+- ${isSeedanceStoryboardReference(config) ? `each SHOTNN.md includes a STORYBOARD PLAN with timeline phases capped at ${config.storyboardReferenceMode.maxStoryboardPhases} and shot-to-shot handoff notes` : "chained ILK/İLK FRAME code block must contain only `Use SHOT[prev]_END as exact first frame`"}
 - Kling default: single-transition first; custom storyboard only when 2-4 phases genuinely earn it, max 4
 
 Do not edit another teammate's files.`);
@@ -873,11 +943,13 @@ Audit all shot files for lighting and color continuity risks: light direction co
 Write only \`${config.outputDir}/reports/COLOR-REPORT.md\`. Apply only low-risk lighting/color fixes inline (align light direction language, normalize color temperature references); otherwise mark the batch for recover.`);
 }
 function buildClaudeSemanticAuditorSubagent(config) {
-    return buildClaudeSubagent("semantic-auditor", "Audit visual_world, perspective, shadows, scale, reflections, physics, anatomy, context, and chained ILK reuse across all generated multi-shot packages.", `Read \`.agent/model-profile.md\`, \`.agent/MASTER.md\`, \`.agent/skills/semantic-consistency/SKILL.md\`, \`.agent/agents/semantic-auditor.md\`, and \`.agent/workflows/safety-check-multi.md\`.
+    return buildClaudeSubagent("semantic-auditor", isSeedanceStoryboardReference(config)
+        ? "Audit visual_world, perspective, shadows, scale, reflections, physics, anatomy, context, and storyboard handoff continuity across all generated multi-shot packages."
+        : "Audit visual_world, perspective, shadows, scale, reflections, physics, anatomy, context, and chained ILK reuse across all generated multi-shot packages.", `Read \`.agent/model-profile.md\`, \`.agent/MASTER.md\`, \`.agent/skills/semantic-consistency/SKILL.md\`, \`.agent/agents/semantic-auditor.md\`, and \`.agent/workflows/safety-check-multi.md\`.
 
-Audit all shot files against \`${config.outputDir}/team-plan.json -> visual_world\`. Verify perspective/geometry, shadow vector, scale/depth, reflection handling, gravity/contact physics, anatomy risk, foreground/background coherence, contextual contradiction handling, targeted semantic avoid terms, and exact chained ILK reuse.
+Audit all shot files against \`${config.outputDir}/team-plan.json -> visual_world\`. Verify perspective/geometry, shadow vector, scale/depth, reflection handling, gravity/contact physics, anatomy risk, foreground/background coherence, contextual contradiction handling, targeted semantic avoid terms, and ${isSeedanceStoryboardReference(config) ? "storyboard-reference phase/handoff continuity" : "exact chained ILK reuse"}.
 
-Write only \`${config.outputDir}/reports/SEMANTIC-REPORT.md\`. Apply only low-risk textual fixes inline; if a chained ILK frame needs new visual content, mark the batch for recover instead of editing it.`);
+Write only \`${config.outputDir}/reports/SEMANTIC-REPORT.md\`. Apply only low-risk textual fixes inline; ${isSeedanceStoryboardReference(config) ? "if storyboard handoff continuity needs structural replanning, mark the batch for recover instead of rewriting neighboring shots." : "if a chained ILK frame needs new visual content, mark the batch for recover instead of editing it."}`);
 }
 function buildClaudePacingAuditorSubagent(config) {
     return buildClaudeSubagent("pacing-auditor", "Audit shot sequence rhythm, tempo variety, and dramatic arc alignment across all generated multi-shot packages.", `Read \`.agent/model-profile.md\`, \`.agent/MASTER.md\`, \`.agent/agents/pacing-auditor.md\`, and \`.agent/workflows/safety-check-multi.md\`.
@@ -902,7 +974,7 @@ description: Film-Kit Multi orchestration for Antigravity Mission Control. Runs
 # Film-Kit Multi - Antigravity Mission Control Skill
 
 ## Goal
-Run the Film-Kit Multi pipeline with maximum throughput while preserving chain continuity and safety.
+Run the Film-Kit Multi pipeline with maximum throughput while preserving ${isSeedanceStoryboardReference(config) ? "storyboard-reference continuity" : "chain continuity"} and safety.
 
 ## System Entry
 1. Read \`.agent/MASTER.md\`
@@ -928,6 +1000,16 @@ Run the Film-Kit Multi pipeline with maximum throughput while preserving chain c
      - \`${config.outputDir}/team-plan.json\`
    - keep top-level \`voiceCast\` in \`${config.outputDir}/team-plan.json\`
    - keep top-level \`visual_world\` in \`${config.outputDir}/team-plan.json\`
+   - set \`project.reference_mode\` to \`${isSeedanceStoryboardReference(config) ? "storyboard-reference" : config.referenceMode}\`
+   - 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.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
+   - include shot-level handoff notes in \`shots[].storyboard_continuity_note\`` : ""}
    - determine minimum functional shots, maximum tasteful shots, and selected target shot count before batch mapping
    - lead never writes SHOT files directly
 2. **Shot Generator tasks (parallel):**
@@ -959,7 +1041,7 @@ Create:
 - ${config.outputDir}/_index.md
 - ${config.outputDir}/team-plan.json
 Use director-shot-sizing to determine minimum functional shots, maximum tasteful shots, and the final target shot count before teammate assignments.
-Then produce teammate assignments only (BATCH ID + SHOT RANGE + CHAIN ENTRY + REPORT PATH).
+Then produce teammate assignments only (BATCH ID + SHOT RANGE + ${isSeedanceStoryboardReference(config) ? "STORYBOARD ENTRY HANDOFF" : "CHAIN ENTRY"} + REPORT PATH).
 Include who looks at what, plane dominance, shared light source, shadow direction, scale map, reflection risk, and physics constraints for difficult interaction shots.
 Do not write SHOT files directly.
 \`\`\`
@@ -975,11 +1057,12 @@ READ FIRST:
 
 BATCH ID: B[NN]
 BATCH RANGE: SHOT[X]-SHOT[Y]
-CHAIN ENTRY FRAME: [exact text from Lead]
+${isSeedanceStoryboardReference(config) ? "STORYBOARD ENTRY HANDOFF: [visual_world-aligned opening state and prior-shot action handoff]" : "CHAIN ENTRY FRAME: [exact text from Lead]"}
 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.` : ""}
 RESPECT LOCKED SHOT COUNT: do not create extra shots outside the assigned range
 
 Generate only assigned SHOT files.
@@ -998,6 +1081,7 @@ If any blocker exists, list exact file and reason.
 - Scenario source: \`${config.scenarioHint}\` (or active file in Antigravity editor)
 - Model: \`${config.model}\` (${getModelDisplayName(config.model)})
 - Kling preset: \`${getKlingPresetDisplay(config.model, config.klingPreset)}\`
+${buildReferenceModeSummary(config)}
 
 ## Output Contract
 - Shot files: \`${config.outputDir}/shots/SHOTNN.md\` (main + coverage in one file)
@@ -1012,20 +1096,20 @@ If any blocker exists, list exact file and reason.
 5. Keep top-level \`visual_world\` in \`${config.outputDir}/team-plan.json\`
 6. Every speaking VIDEO section includes machine-readable \`Audio Plan\`
 7. Keep one active speaker per shot
-8. Main shots are chained (SHOT[N]_END -> SHOT[N+1]_START)
-9. Chained ILK/İLK FRAME code block contains only \`Use SHOT[prev]_END as exact first frame\`
+8. ${isSeedanceStoryboardReference(config) ? "Main-shot continuity uses shared visual_world plus storyboard handoff notes, character lock, camera direction, lighting, and action progression" : "Main shots are chained (SHOT[N]_END -> SHOT[N+1]_START)"}
+9. ${isSeedanceStoryboardReference(config) ? "SHOTNN.md includes INPUT ASSET ROLES, STORYBOARD PLAN, AUDIO PLAN, SEEDANCE VIDEO PROMPT, and coverage" : "Chained ILK/İLK FRAME code block contains only `Use SHOT[prev]_END as exact first frame`"}
 10. Every prompt includes an Avoid line
 11. Video prompts include full audio direction
 12. Music default is NONE
-13. ILK/İLK FRAME section always contains fenced code block
+13. ${isSeedanceStoryboardReference(config) ? "ILK/İLK FRAME and SON FRAME sections are not required in Seedance storyboard-reference mode" : "ILK/İLK FRAME section always contains fenced code block"}
 14. Multi-subject shots must define gaze target, plane map, shared light source, and contact/depth cues
 15. Semantic consistency must define perspective/geometry, shadow vector, scale map, reflections, gravity/contact physics, anatomy risk, foreground/background coherence, and contextual logic
 16. Final shot count must come from director-shot-sizing; do not inflate shot volume for fake pace
 
 ## Quality Floor (Hard Gate)
 Reject and regenerate any shot that fails any item:
-- reference-anchored ILK FRAME missing \`REFERENCE LOCK\`, \`Keep same\`, or \`Change only\`
-- SON FRAME drifts from the same visual universe or changes more than one major beat
+- ${isSeedanceStoryboardReference(config) ? "generated character sheet token and generated shot storyboard token roles are missing or conflated" : "reference-anchored ILK FRAME missing `REFERENCE LOCK`, `Keep same`, or `Change only`"}
+- ${isSeedanceStoryboardReference(config) ? `STORYBOARD PLAN missing timeline phases or exceeding ${config.storyboardReferenceMode.maxStoryboardPhases} phases` : "SON FRAME drifts from the same visual universe or changes more than one major beat"}
 - VIDEO < 120 words
 - any coverage video prompt < 70 words
 - reference-visible face/hair/skin/body/wardrobe/accessories/prop design drift
@@ -1057,6 +1141,7 @@ function buildModelProfile(config) {
 - Target model: \`${config.model}\`
 - Display name: ${getModelDisplayName(config.model)}
 - Kling preset: \`${getKlingPresetDisplay(config.model, config.klingPreset)}\`
+${buildReferenceModeSummary(config)}
 
 ## Active Profile Summary
 ${isKling
@@ -1068,7 +1153,8 @@ ${isKling
             ? `This project is configured for **Seedance 2.0**.
 - Multimodal prompt grammar is active: image + video + audio + text references
 - Timeline segmentation is recommended for 10s+ clips
-- One continuous shot and video-extension syntax are available`
+- One continuous shot and video-extension syntax are available
+${isSeedanceStoryboardReference(config) ? "- Storyboard-reference mode is active: per-shot STORYBOARD PLAN sections replace start/end frame chaining" : ""}`
             : `This project is configured for **Google Flow + Veo 3.1**.
 - Prompt Flow order is mandatory
 - Frame chaining and coverage contracts are active
@@ -1106,7 +1192,7 @@ When generating video from a reference image:
 
 ---
 
-${buildSeedanceProfile(isSeedance)}
+${buildSeedanceProfile(isSeedance, isSeedanceStoryboardReference(config), config.storyboardReferenceMode.maxStoryboardPhases)}
 
 ---
 

package/packages/multi/build/lib/types.d.ts

@@ -1,5 +1,15 @@
 export type SupportedModel = "veo31" | "kling-3.0" | "seedance-2.0";
 export type KlingPreset = "ultra-realism" | "balanced" | "custom";
+export type ReferenceMode = "start-end" | "storyboard-reference" | "hybrid";
+export interface StoryboardReferenceConfig {
+    enabled: boolean;
+    maxStoryboardPhases: number;
+    defaultCharacterRefRole: "character_identity";
+    defaultStoryboardRefRole: "storyboard_plan";
+    generateAllModelPrompts: boolean;
+    strictReferenceLock: boolean;
+    splitStoryboardOverload: boolean;
+}
 export interface MultiAgentConfigOptions {
     /** Root directory of the project. Defaults to process.cwd() */
     rootDir?: string;
@@ -21,6 +31,10 @@ export interface MultiAgentConfigOptions {
     model?: SupportedModel;
     /** Kling quality preset. Defaults to ultra-realism for kling-3.0. */
     klingPreset?: KlingPreset;
+    /** Reference strategy. Defaults to start-end. */
+    referenceMode?: ReferenceMode;
+    /** Storyboard-reference behavior when referenceMode is storyboard-reference. */
+    storyboardReferenceMode?: Partial<StoryboardReferenceConfig>;
 }
 export interface ResolvedMultiConfig {
     rootDir: string;
@@ -33,6 +47,8 @@ export interface ResolvedMultiConfig {
     batchSize: number;
     model: SupportedModel;
     klingPreset: KlingPreset;
+    referenceMode: ReferenceMode;
+    storyboardReferenceMode: StoryboardReferenceConfig;
     warnings: string[];
 }
 export interface MultiConfigureResult {