@milenyumai/film-kit 2.2.0 → 2.3.0

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

@@ -1,19 +1,96 @@
 ---
-description: Generate storyboard-reference prompt bundles from character reference, storyboard reference, and video brief
+description: Generate character sheet prompts, per-shot GPT Image 2 storyboard prompts, and model-aware video prompt bundles from character references and a video brief
 ---
 
-# /generate-storyboard
+# /generate-storyboard - Storyboard Reference Video Prompt Mode
 
-Read `.agent/model-profile.md`, `safety-compliance`, `reference-locking`, `storyboard-reference`, `semantic-consistency`, `visual-modes`, `audio-design` when needed, and `prompt-structure`.
+## Preconditions
 
-Flow:
+- Character reference image exists.
+- User brief or scenario text exists.
+- Optional storyboard guide images may exist, but they are not required.
+- `storyboard-reference` mode is explicitly requested or configured.
 
-1. Bind `@character1` as `character_identity`, exact lock.
-2. Bind `@storyboard1` as `storyboard_plan`, staging only.
-3. Interpret storyboard panels: 1 continuous arc, 2-4 internal phases, 5+ split shots.
-4. Build `visual_world`, continuity anchors, and model-specific prompts.
-5. Generate Seedance, Veo, and Kling prompt sections for the requested model subset.
-6. Run QA for reference lock, storyboard role separation, model grammar, avoid line, audio plan, and safety.
-7. Write all outputs under `$OUTPUT_DIR`.
+## Read Order
 
-Fail closed on missing refs, empty brief, public figure likeness, trademark/logo risk, unsafe visual requests, missing avoid line, or invalid Kling block structure.
+1. `.agent/model-profile.md`
+2. `.agent/skills/safety-compliance/SKILL.md`
+3. `.agent/skills/reference-locking/SKILL.md`
+4. `.agent/skills/storyboard-reference/SKILL.md`
+5. `.agent/skills/semantic-consistency/SKILL.md`
+6. `.agent/skills/visual-modes/SKILL.md`
+7. `.agent/skills/audio-design/SKILL.md` when dialogue, SFX, ambience, or voiceover exists
+8. `.agent/skills/prompt-structure/SKILL.md`
+
+## Flow
+
+1. Confirm asset roles:
+   - `@character1`, `@character2`, ...: `character_identity`, exact lock
+   - optional `@storyboard1`, `@storyboard2`, ...: external storyboard guides, staging only
+2. Generate one GPT Image 2 character sheet prompt per character reference:
+   - 16:9 production storyboard sheet
+   - front full body, back full body, left profile, right profile, three-quarter full body, close-up face
+   - 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
+5. Build `visual_world`:
+   - environment
+   - lighting
+   - foreground/midground/background
+   - screen direction
+   - continuity anchors
+6. Generate one GPT Image 2 storyboard prompt per shot:
+   - use character sheets as the only identity source
+   - use optional storyboard guide only for composition, blocking, camera, timing, and rhythm
+   - include previous shot handoff and next shot handoff
+   - preserve shared location, lighting, screen direction, action rhythm, and scene continuity
+7. Build model prompt bundle:
+   - Seedance dynamic image mapping: character sheets first, generated shot storyboard next
+   - Veo visual-planning prompt with full audio direction
+   - Kling block-structured storyboard route
+8. Run QA gates:
+   - reference lock
+   - storyboard role separation
+   - model grammar
+   - avoid/negative prompt
+   - audio plan
+   - safety
+9. Write outputs under `$OUTPUT_DIR`.
+
+## CLI Equivalent
+
+```bash
+npx @milenyumai/film-kit generate-storyboard \
+  --character-ref ./refs/character.png \
+  --brief ./scenario.md \
+  --models veo31,seedance-2.0,kling-3.0 \
+  --duration 8 \
+  --aspect 16:9 \
+  --output-dir ./outputs
+```
+
+Optional external storyboard guide:
+
+```bash
+npx @milenyumai/film-kit generate-storyboard \
+  --character-ref ./refs/character.png \
+  --storyboard-ref ./refs/storyboard-guide.png \
+  --brief ./scenario.md \
+  --models seedance-2.0
+```
+
+## Fail-Closed Rules
+
+- 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.
+- 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.
+- Kling prompt missing required block structure: output is invalid.

package/packages/multi/build/cli.js

@@ -5,6 +5,7 @@ const command = args[0];
 const overwrite = args.includes("--overwrite") || args.includes("-f");
 const SUPPORTED_MODELS = ["veo31", "kling-3.0", "seedance-2.0"];
 const SUPPORTED_KLING_PRESETS = ["ultra-realism", "balanced", "custom"];
+const SUPPORTED_REFERENCE_MODES = ["start-end", "storyboard-reference", "hybrid"];
 function parseFlagValue(flag) {
     const exactIndex = args.indexOf(flag);
     if (exactIndex >= 0 && args[exactIndex + 1]) {
@@ -34,11 +35,32 @@ function parseKlingPreset() {
     }
     throw new Error(`Invalid --kling-preset value: ${presetRaw}. Supported: ${SUPPORTED_KLING_PRESETS.join(", ")}`);
 }
+function parseReferenceMode() {
+    const modeRaw = parseFlagValue("--reference-mode");
+    if (!modeRaw)
+        return undefined;
+    if (SUPPORTED_REFERENCE_MODES.includes(modeRaw)) {
+        return modeRaw;
+    }
+    throw new Error(`Invalid --reference-mode value: ${modeRaw}. Supported: ${SUPPORTED_REFERENCE_MODES.join(", ")}`);
+}
+function parsePositiveIntegerFlag(flag) {
+    const raw = parseFlagValue(flag);
+    if (!raw)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`Invalid ${flag} value: ${raw}. Expected a positive integer.`);
+    }
+    return value;
+}
 if (command === "init") {
     console.log("🎬 Film-Kit Multi: Configuring multi-agent team...\n");
     try {
         const model = parseModel();
         const klingPreset = parseKlingPreset();
+        const referenceMode = parseReferenceMode();
+        const maxStoryboardPhases = parsePositiveIntegerFlag("--max-storyboard-phases");
         const configureOptions = {
             rootDir: process.cwd(),
             overwrite
@@ -47,6 +69,21 @@ if (command === "init") {
             configureOptions.model = model;
         if (klingPreset)
             configureOptions.klingPreset = klingPreset;
+        if (referenceMode) {
+            configureOptions.referenceMode = referenceMode;
+            if (referenceMode === "storyboard-reference") {
+                configureOptions.storyboardReferenceMode = {
+                    ...configureOptions.storyboardReferenceMode,
+                    enabled: true
+                };
+            }
+        }
+        if (maxStoryboardPhases !== undefined) {
+            configureOptions.storyboardReferenceMode = {
+                ...configureOptions.storyboardReferenceMode,
+                maxStoryboardPhases
+            };
+        }
         const result = await configureMultiAgents(configureOptions);
         if (result.written.length > 0) {
             console.log(`✅ Files written: ${result.written.length}`);
@@ -77,7 +114,9 @@ This internal CLI exists only for repository development.
 Public usage:
   npx @milenyumai/film-kit init --preset multi
   npx @milenyumai/film-kit init --preset multi --model veo31|kling-3.0|seedance-2.0
+  npx @milenyumai/film-kit init --preset multi --model seedance-2.0 --reference-mode storyboard-reference
   npx @milenyumai/film-kit init --preset multi --model kling-3.0 --kling-preset ultra-realism|balanced|custom
+  npx @milenyumai/film-kit init --preset multi --max-storyboard-phases 4
   npx @milenyumai/film-kit init --preset multi --overwrite
 `);
 }

package/packages/multi/build/index.d.ts

@@ -1,2 +1,2 @@
-export type { KlingPreset, MultiAgentConfigOptions, MultiConfigureResult, SupportedModel } from "./lib/types.js";
+export type { KlingPreset, MultiAgentConfigOptions, MultiConfigureResult, ReferenceMode, StoryboardReferenceConfig, SupportedModel } from "./lib/types.js";
 export { configureMultiAgents } from "./lib/configure.js";

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

@@ -112,6 +112,18 @@ async function copyMultiContent(rootDir, overwrite, templateVars) {
 }
 function renderContentTemplate(content, vars) {
     return content
+        .replaceAll("$REFERENCE_MODE_CONTRACT", vars.referenceModeContract)
+        .replaceAll("$SHOT_FILE_OUTPUT_CONTRACT", vars.shotFileOutputContract)
+        .replaceAll("$CONTINUITY_CONTRACT", vars.continuityContract)
+        .replaceAll("$SEEDANCE_STORYBOARD_CONTRACT", vars.seedanceStoryboardContract)
+        .replaceAll("$SHOT_SELF_CHECK_CONTRACT", vars.selfCheckContract)
+        .replaceAll("$SEMANTIC_AUDIT_CONTRACT", vars.semanticAuditContract)
+        .replaceAll("$SEMANTIC_REFERENCE_MODE_STATUS_FIELD", vars.semanticReferenceModeStatusField)
+        .replaceAll("$SEMANTIC_CONTINUITY_STATUS_FIELD", vars.semanticContinuityStatusField)
+        .replaceAll("$STORYBOARD_REFERENCE_POLICY_JSON", vars.storyboardReferencePolicyJson)
+        .replaceAll("$CHAINED_ILK_FRAME_EXACT_REUSE_REQUIRED", String(vars.chainedIlkFrameExactReuseRequired))
+        .replaceAll("$MAX_STORYBOARD_PHASES", String(vars.maxStoryboardPhases))
+        .replaceAll("$REFERENCE_MODE", vars.referenceMode)
         .replaceAll("$OUTPUT_DIR", vars.outputDir)
         .replaceAll("$SCENARIO_HINT", vars.scenarioHint)
         .replaceAll("$MODEL_DISPLAY", vars.modelDisplayName)
@@ -129,6 +141,178 @@ function getModelDisplayName(model) {
 function getKlingPresetDisplay(model, klingPreset) {
     return model === "kling-3.0" ? klingPreset : "n/a (Kling-only)";
 }
+function isSeedanceStoryboardReference(config) {
+    return config.model === "seedance-2.0"
+        && config.referenceMode === "storyboard-reference"
+        && config.storyboardReferenceMode.enabled;
+}
+function buildStoryboardReferencePolicyJson(config) {
+    if (!isSeedanceStoryboardReference(config)) {
+        return JSON.stringify({
+            enabled: false,
+            continuity_source: "start_end_frame_chain"
+        }, null, 6);
+    }
+    return JSON.stringify({
+        enabled: true,
+        max_storyboard_phases: config.storyboardReferenceMode.maxStoryboardPhases,
+        recommended_phase_budget: {
+            "4-6s": "1-2 storyboard phases",
+            "7-10s": "2-3 storyboard phases",
+            "11-15s": "3-4 storyboard phases",
+            split_at_phase_count: 5,
+            split_target: "separate SHOTNN.md files"
+        },
+        provider_reference_tokens: {
+            character_identities: "@Image1..@ImageN generated character sheets",
+            storyboard_reference: "next @Image token after character sheets (one character -> @Image2, two characters -> @Image3)",
+            legacy_aliases: {
+                character_identities: "@image1..@imageN",
+                storyboard_reference: "matching lowercase next @image token"
+            },
+            video_reference: "@video1",
+            audio_reference: "@audio1"
+        },
+        continuity_mode: {
+            continuous_shot: "use no-cuts wording only for a single uninterrupted camera move",
+            multi_shot_storyboard: "use only planned STORYBOARD PLAN phase transitions; do not add unplanned cuts"
+        },
+        provider_file_limits: {
+            images: 9,
+            videos: 3,
+            audio: 3,
+            total_files: 12,
+            duration_seconds: "4-15"
+        },
+        character_reference_sheets: {
+            enabled: true,
+            provider: "gpt-image-2",
+            generated_once_per_character: true,
+            aspect_ratio: "16:9",
+            required_views: [
+                "front full body",
+                "back full body",
+                "left profile",
+                "right profile",
+                "three-quarter full body",
+                "close-up face"
+            ]
+        },
+        storyboard_prompt_policy: {
+            enabled: true,
+            provider: "gpt-image-2",
+            generated_per_shot: true,
+            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"
+        },
+        material_roles: {
+            "character_sheet_tokens": "identity, face, body proportions, wardrobe, accessories, and visible props",
+            "generated_shot_storyboard_token": "composition, blocking, camera direction, timing, and action progression only"
+        },
+        storyboard_never_identity_source: [
+            "storyboard text",
+            "panel borders",
+            "watermarks",
+            "logos",
+            "alternate character designs"
+        ],
+        continuity_source: "shared visual_world plus shot-to-shot storyboard handoff notes",
+        require_ilk_son_frames: false,
+        shot_handoff_notes_required: true
+    }, null, 6);
+}
+function buildReferenceModeContract(config) {
+    if (!isSeedanceStoryboardReference(config)) {
+        return `Reference mode: \`${config.referenceMode}\` (start/end frame chaining active).
+- Main shots are chained by exact end-frame to first-frame reuse.
+- \`${config.outputDir}/team-plan.json -> visual_world\` still governs perspective, lighting, scale, and identity locks.`;
+    }
+    return `Reference mode: \`storyboard-reference\` (Seedance 2.0 storyboard-supported runtime).
+- Do not require \`ILK FRAME\` / \`SON FRAME\` sections for main shots in this mode.
+- Generate one 16:9 GPT Image 2 character reference sheet prompt per character once, before shot storyboard work.
+- Each \`SHOTNN.md\` must include a \`GPT IMAGE 2 STORYBOARD PROMPT\` and its own \`STORYBOARD PLAN\` with timeline phases derived from one shared \`${config.outputDir}/team-plan.json -> visual_world\`.
+- \`${config.outputDir}/team-plan.json\` must set \`project.reference_mode: "storyboard-reference"\`, \`storyboard_reference.enabled: true\`, \`storyboard_reference.character_reference_sheets\`, \`storyboard_reference.storyboard_prompt_policy\`, \`storyboard_reference.max_storyboard_phases: ${config.storyboardReferenceMode.maxStoryboardPhases}\`, \`storyboard_reference.recommended_phase_budget\`, \`storyboard_reference.provider_reference_tokens\`, \`storyboard_reference.continuity_mode\`, \`storyboard_reference.provider_file_limits\`, and shot-level handoff notes.
+- Duration policy: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases; 5+ distinct phases split into separate \`SHOTNN.md\` files.
+- Continuity is enforced by shared \`visual_world\`, shot-to-shot storyboard handoff notes, character/reference lock, camera direction, lighting, and action progression.`;
+}
+function buildShotFileOutputContract(config) {
+    if (!isSeedanceStoryboardReference(config)) {
+        return `1. main shot blocks: \`ILK FRAME\` (or \`İLK FRAME\`), \`SON FRAME\`, \`AUDIO PLAN\`, \`VIDEO\` (or \`VİDEO\`)
+2. \`ILK/İLK FRAME\` section must always include a fenced code block
+3. if chained, first-frame code block must contain only: \`Use SHOT[prev]_END as exact first frame\`; any new start-frame prompt requires \`CHAIN BREAK\`
+4. 2-3 coverage sub-shots in the same file
+5. image prompt contract (hard requirement):
+   - if references exist, \`ILK FRAME\` and \`SON FRAME\` must use \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`
+   - face/hair/skin/body/wardrobe/accessories/prop design visible in reference are immutable
+   - \`SON FRAME\` must preserve the same visual universe and declare only one major semantic delta
+   - \`VIDEO\`: minimum 120 words
+   - each coverage video prompt: minimum 70 words`;
+    }
+    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
+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
+8. \`SEEDANCE VIDEO PROMPT\`: minimum 120 words; each coverage video prompt: minimum 70 words`;
+}
+function buildContinuityContract(config) {
+    if (!isSeedanceStoryboardReference(config)) {
+        return `- First shot \`ILK FRAME\` / \`İLK FRAME\` must match assigned chain entry.
+- Chained \`ILK FRAME\` / \`İLK FRAME\` code blocks cannot contain a new camera, lens, lighting, action, or composition prompt.
+- Within your batch: \`SHOT[N]_END\` must match \`SHOT[N+1]_START\`.
+- Coverage shots are standalone and not chained.`;
+    }
+    return `- Main-shot continuity uses storyboard handoff text, not start/end frame reuse.
+- First shot \`STORYBOARD PLAN\` must match the assigned continuity entry and shared \`${config.outputDir}/team-plan.json -> visual_world\`.
+- Within your batch, each shot's final timeline phase must hand off clearly into the next shot's opening phase.
+- Coverage shots are standalone and not chained.`;
+}
+function buildSeedanceStoryboardContract(config) {
+    if (!isSeedanceStoryboardReference(config)) {
+        return `- explicit material roles when references exist (\`@Image1\`/\`@image1\`, \`@video1\`, \`@audio1\`)
+- use \`Use @Image1 as the first frame of the scene.\` when first-frame identity lock matters
+- if \`@video1\` is action reference and \`@video2\` is camera reference, say so directly
+- use \`No scene cuts throughout, one continuous shot.\` only for a true uninterrupted camera move
+- use timeline segments only for meaningful internal beats, not decorative micro-actions
+- when continuing a clip, use \`Extend @video1 by [N]s\` rather than rewriting it as a new cut
+- when \`@Image1\`/\`@image1\` locks identity, keep face/body/wardrobe/prop design exact and change only one meaningful beat`;
+    }
+    return `- generate one 16:9 GPT Image 2 character sheet prompt per character once, then use those sheet images as Seedance identity references
+- 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 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
+- 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`;
+}
+function buildSelfCheckContract(config) {
+    if (!isSeedanceStoryboardReference(config)) {
+        return `- each \`ILK/İLK FRAME\` section contains a code block
+- chained \`ILK/İLK FRAME\` code blocks contain only exact reuse text
+- word-count floors pass for all prompts
+- image prompt contract passes for main stills`;
+    }
+    return `- each file contains \`INPUT ASSET ROLES\`, \`REFERENCE ASSET REQUIREMENTS\`, \`GPT IMAGE 2 STORYBOARD PROMPT\`, \`STORYBOARD PLAN\`, \`AUDIO PLAN\`, \`SEEDANCE VIDEO PROMPT\`, and coverage
+- no main shot requires \`ILK FRAME\` or \`SON FRAME\` sections
+- storyboard phases are capped at ${config.storyboardReferenceMode.maxStoryboardPhases} and are not decorative micro-beats
+- role separation passes: identity comes from generated character sheet tokens, staging comes from the generated shot storyboard token`;
+}
+function buildSemanticAuditContract(config) {
+    if (!isSeedanceStoryboardReference(config)) {
+        return `- Start/end pairs keep the declared invariants and change only one major semantic beat unless \`CHAIN BREAK\` is declared.
+- Chained \`ILK/İLK FRAME\` code blocks contain only \`Use SHOT[prev]_END as exact first frame\`; any competing visual prompt is a fail and must become \`CHAIN BREAK\`.`;
+    }
+    return `- Storyboard-reference shots derive every timeline phase from the shared \`team-plan.json -> visual_world\`.
+- Shot-to-shot continuity is expressed through storyboard handoff notes, consistent camera direction, lighting, character lock, and action progression.
+- Main shots do not require start/end frame pairs or chained first-frame reuse text in storyboard-reference mode.`;
+}
 async function removePathIfExists(rootDir, relativePath) {
     const absolutePath = join(rootDir, relativePath);
     if (await exists(absolutePath)) {
@@ -158,6 +342,8 @@ export async function configureMultiAgents(options = {}) {
     const batchSize = options.batchSize ?? fromFile?.batchSize;
     const model = options.model ?? fromFile?.model;
     const klingPreset = options.klingPreset ?? fromFile?.klingPreset;
+    const referenceMode = options.referenceMode ?? fromFile?.referenceMode;
+    const storyboardReferenceMode = options.storyboardReferenceMode ?? fromFile?.storyboardReferenceMode;
     if (outputDir !== undefined)
         merged.outputDir = outputDir;
     if (scenarioHint !== undefined)
@@ -176,13 +362,34 @@ export async function configureMultiAgents(options = {}) {
         merged.model = model;
     if (klingPreset !== undefined)
         merged.klingPreset = klingPreset;
+    if (referenceMode !== undefined)
+        merged.referenceMode = referenceMode;
+    if (storyboardReferenceMode !== undefined)
+        merged.storyboardReferenceMode = storyboardReferenceMode;
     const resolved = resolveMultiOptions(merged);
+    const seedanceStoryboardReference = isSeedanceStoryboardReference(resolved);
     const templateVars = {
         outputDir: resolved.outputDir,
         scenarioHint: resolved.scenarioHint,
         model: resolved.model,
         klingPreset: getKlingPresetDisplay(resolved.model, resolved.klingPreset),
-        modelDisplayName: getModelDisplayName(resolved.model)
+        modelDisplayName: getModelDisplayName(resolved.model),
+        referenceMode: resolved.referenceMode,
+        maxStoryboardPhases: resolved.storyboardReferenceMode.maxStoryboardPhases,
+        chainedIlkFrameExactReuseRequired: !seedanceStoryboardReference,
+        storyboardReferencePolicyJson: buildStoryboardReferencePolicyJson(resolved),
+        referenceModeContract: buildReferenceModeContract(resolved),
+        shotFileOutputContract: buildShotFileOutputContract(resolved),
+        continuityContract: buildContinuityContract(resolved),
+        seedanceStoryboardContract: buildSeedanceStoryboardContract(resolved),
+        selfCheckContract: buildSelfCheckContract(resolved),
+        semanticAuditContract: buildSemanticAuditContract(resolved),
+        semanticReferenceModeStatusField: seedanceStoryboardReference
+            ? "storyboard_reference_status"
+            : "start_end_contract_status",
+        semanticContinuityStatusField: seedanceStoryboardReference
+            ? "storyboard_handoff_status"
+            : "chained_ilk_frame_status"
     };
     await removeStaleClaudeArtifacts(resolved.rootDir);
     // Ensure core Film-Kit system files exist (.agent/MASTER.md + skills).

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

@@ -1,2 +1,4 @@
-import type { MultiAgentConfigOptions, ResolvedMultiConfig } from "./types.js";
+import type { MultiAgentConfigOptions, ReferenceMode, ResolvedMultiConfig, StoryboardReferenceConfig } from "./types.js";
+export declare const DEFAULT_STORYBOARD_REFERENCE_CONFIG: StoryboardReferenceConfig;
+export declare function normalizeStoryboardReferenceConfig(input: Partial<StoryboardReferenceConfig> | undefined, referenceMode: ReferenceMode): StoryboardReferenceConfig;
 export declare function resolveMultiOptions(options: MultiAgentConfigOptions): ResolvedMultiConfig;

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

@@ -1,12 +1,42 @@
 const DEFAULT_MODEL = "veo31";
 const DEFAULT_KLING_PRESET = "ultra-realism";
+const DEFAULT_REFERENCE_MODE = "start-end";
+export const DEFAULT_STORYBOARD_REFERENCE_CONFIG = {
+    enabled: false,
+    maxStoryboardPhases: 4,
+    defaultCharacterRefRole: "character_identity",
+    defaultStoryboardRefRole: "storyboard_plan",
+    generateAllModelPrompts: true,
+    strictReferenceLock: true,
+    splitStoryboardOverload: true
+};
+export function normalizeStoryboardReferenceConfig(input, referenceMode) {
+    const maxStoryboardPhases = input?.maxStoryboardPhases ?? DEFAULT_STORYBOARD_REFERENCE_CONFIG.maxStoryboardPhases;
+    if (!Number.isInteger(maxStoryboardPhases) || maxStoryboardPhases < 1) {
+        throw new Error("Invalid storyboardReferenceMode.maxStoryboardPhases. Expected a positive integer.");
+    }
+    return {
+        enabled: input?.enabled ?? referenceMode === "storyboard-reference",
+        maxStoryboardPhases,
+        defaultCharacterRefRole: "character_identity",
+        defaultStoryboardRefRole: "storyboard_plan",
+        generateAllModelPrompts: input?.generateAllModelPrompts ?? DEFAULT_STORYBOARD_REFERENCE_CONFIG.generateAllModelPrompts,
+        strictReferenceLock: input?.strictReferenceLock ?? DEFAULT_STORYBOARD_REFERENCE_CONFIG.strictReferenceLock,
+        splitStoryboardOverload: input?.splitStoryboardOverload ?? DEFAULT_STORYBOARD_REFERENCE_CONFIG.splitStoryboardOverload
+    };
+}
 export function resolveMultiOptions(options) {
     const warnings = [];
     const model = options.model ?? DEFAULT_MODEL;
     const klingPreset = options.klingPreset ?? DEFAULT_KLING_PRESET;
+    const referenceMode = options.referenceMode ?? DEFAULT_REFERENCE_MODE;
+    const storyboardReferenceMode = normalizeStoryboardReferenceConfig(options.storyboardReferenceMode, referenceMode);
     if (!options.model) {
         warnings.push("Model not specified. Falling back to veo31. In the next major release, --model will be required.");
     }
+    if (referenceMode === "storyboard-reference" && !storyboardReferenceMode.enabled) {
+        warnings.push("referenceMode is storyboard-reference, but storyboardReferenceMode.enabled is false.");
+    }
     return {
         rootDir: options.rootDir ?? process.cwd(),
         outputDir: options.outputDir ?? "./outputs",
@@ -18,6 +48,8 @@ export function resolveMultiOptions(options) {
         batchSize: options.batchSize ?? 4,
         model,
         klingPreset,
+        referenceMode,
+        storyboardReferenceMode,
         warnings
     };
 }