@milenyumai/film-kit 2.3.1 → 2.3.2

package/README.md

@@ -126,6 +126,16 @@ Use this mode when the source material is a character reference image plus a bri
 
 Initialize a Seedance storyboard-reference runtime:
 
+```bash
+npx @milenyumai/film-kit init \
+  --preset single \
+  --model seedance-2.0 \
+  --reference-mode storyboard-reference \
+  --max-storyboard-phases 4
+```
+
+For multi-agent storyboard-reference generation:
+
 ```bash
 npx @milenyumai/film-kit init \
   --preset multi \
@@ -177,15 +187,21 @@ Outputs:
 - `outputs/shots/SHOTNN.md`
 - `outputs/reports/STORYBOARD-REFERENCE-QA.md`
 
+In a project initialized with `--reference-mode storyboard-reference`, `/generate` is mode-guarded to use the storyboard-reference workflow. It will not generate start/end frame packages. If no character reference is available through `--character-ref`, an in-context image, or `refs/character.png`, generation stops and asks for one.
+
 Rules:
 
 - `@character1` is used once to create a 16:9 character sheet prompt with front, back, side, three-quarter, and face close-up views.
+- GPT Image 2 still prompts use `REFERENCE LOCK`, `Keep same`, `Change only`, and `Avoid` sections so character identity, wardrobe, props, and materials stay immutable unless explicitly changed.
 - Each `SHOTNN.md` includes a professional `GPT IMAGE 2 STORYBOARD PROMPT`; the generated shot storyboard controls composition, blocking, camera, timing, and editorial phase order only.
 - Storyboard prompts use production-board grammar: rough black-and-white pencil panels, strong silhouettes, visible body/camera momentum, and optional color-coded planning annotations. Seedance is instructed to follow the panel order while ignoring arrows, notes, labels, and timestamps in the rendered video.
 - Seedance provider-facing tokens map generated character sheets first (`@Image1`, `@Image2`, ...) and the generated shot storyboard next. Legacy lowercase aliases remain documented in runtime text.
+- Speaking shots must bind `Audio Plan.activeSpeakerKey` back to project-level `voiceCast`; broken voice bindings fail QA.
+- Public-figure, celebrity, likeness, logo, trademark, or brand references in the brief, dialogue metadata, or reference metadata are blocked unless safely anonymized first.
 - Phase budget: 4-6s uses 1-2 phases, 7-10s uses 2-3 phases, and 11-15s uses 3-4 phases.
 - 5+ storyboard phases are split into multiple `SHOTNN.md` files by default.
 - Multi-phase storyboards use planned phase transitions instead of forcing `No scene cuts throughout, one continuous shot.`
+- Seeing `ILK FRAME`, `İLK FRAME`, or `SON FRAME` in main storyboard-reference shot output means the old start/end runtime leaked in; treat that output as failed and rerun after reinitializing with `--reference-mode storyboard-reference`.
 - Existing start/end workflows stay unchanged and remain the default.
 
 CLI flags for direct storyboard bundle generation:
@@ -435,7 +451,8 @@ Generated specialist and render QA flows now explicitly fail on:
 Studio render QA also records render-level verdicts such as:
 
 - `reference_drift_status`
-- `start_end_contract_status`
+- `start_end_contract_status` in start/end mode
+- `storyboard_reference_status` and `storyboard_handoff_status` in storyboard-reference mode
 
 ## Seedance Runtime Coverage
 

package/build/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { parseCliCommand, renderCliUsage } from "./lib/cli.js";
 import { configureFilmKit } from "./lib/film-kit.js";
-import { buildStoryboardReferencePromptBundles, writeStoryboardReferenceOutputs } from "./lib/storyboard-reference/index.js";
+import { assertStoryboardReferenceBuildPass, buildStoryboardReferencePromptBundles, writeStoryboardReferenceOutputs } from "./lib/storyboard-reference/index.js";
 const args = process.argv.slice(2);
 try {
     const parsed = await parseCliCommand(args, process.cwd());
@@ -15,6 +15,7 @@ try {
         }
         console.log("🎬 Film-Kit: Generating storyboard-reference prompt bundle...\n");
         const buildResult = buildStoryboardReferencePromptBundles(parsed.storyboardRequest);
+        assertStoryboardReferenceBuildPass(buildResult);
         const writeResult = await writeStoryboardReferenceOutputs(buildResult, process.cwd());
         console.log(`✅ Files written: ${writeResult.written.length}`);
         writeResult.written.forEach(file => console.log(`   ${file}`));

package/build/lib/cli.js

@@ -417,6 +417,9 @@ async function parseGenerateStoryboardCommand(args, rootDir) {
     if (!brief) {
         throw new Error("generate-storyboard requires --brief.");
     }
+    if (characterRefs.length === 0) {
+        throw new Error("generate-storyboard requires --character-ref.");
+    }
     const request = {
         mode: "storyboard-reference",
         targetModels,
@@ -524,6 +527,7 @@ generate-storyboard flags:
   --audio-intent       SFX/ambience direction
   --style-intent       Visual style direction
   --storyboard-panel-count-hint  Panel/phase count hint; 5+ panels split into multiple SHOTNN files
+  --max-storyboard-phases  Upper bound per SHOTNN storyboard phase count
 
 Install:
   npm install --save-dev @milenyumai/film-kit

package/build/lib/configure.js

@@ -52,17 +52,73 @@ async function copyContentFiles(rootDir, overwrite, templateVars, targetRoot = "
         const targetRelative = `${targetRoot}/${file.relativePath}`;
         const targetAbsolute = join(rootDir, targetRelative);
         const targetExists = await exists(targetAbsolute);
-        if (targetExists && !overwrite) {
+        const forceModeSensitiveRewrite = templateVars.storyboardReferenceActive && isStoryboardModeSensitiveContent(file.relativePath);
+        if (targetExists && !overwrite && !forceModeSensitiveRewrite) {
             skipped.push(targetRelative);
             continue;
         }
         const rawContent = await readFile(file.absolutePath, "utf8");
-        const content = renderContentTemplate(rawContent, templateVars);
+        const content = renderModeSensitiveContent(file.relativePath, rawContent, templateVars);
         await writeText(targetAbsolute, content);
         written.push(targetRelative);
     }
     return { written, skipped };
 }
+const STORYBOARD_MODE_SENSITIVE_CONTENT = new Set([
+    "workflows/generate.md",
+    "workflows/chain.md",
+    "workflows/safety-check.md",
+    "workflows/finish.md",
+    "workflows/recover.md",
+    "skills/frame-chaining/SKILL.md",
+    "skills/coverage-system/SKILL.md",
+    "skills/prompt-structure/SKILL.md"
+]);
+const STORYBOARD_MODE_SENSITIVE_PROJECT_FILES = new Set([
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".cursorrules",
+    ".cursor/rules/global.mdc",
+    ".claude/CLAUDE.md",
+    ".claude/agents/prompt-engineer.md",
+    ".claude/rules/generate-flow.md",
+    ".claude/rules/output-contract.md",
+    ".github/copilot-instructions.md",
+    ".github/instructions/shotforge.instructions.md",
+    ".agent/skills/shotforge-generate/SKILL.md",
+    ".agents/skills/shotforge-generate/SKILL.md",
+    ".agents/skills/film-kit-codex-images/SKILL.md",
+    ".agent/workflows/codex-images.md",
+    ".codex/agents/prompt-engineer.toml"
+]);
+function isStoryboardModeSensitiveContent(relativePath) {
+    return STORYBOARD_MODE_SENSITIVE_CONTENT.has(relativePath);
+}
+function renderModeSensitiveContent(relativePath, rawContent, vars) {
+    if (!vars.storyboardReferenceActive) {
+        return renderContentTemplate(rawContent, vars);
+    }
+    switch (relativePath) {
+        case "workflows/generate.md":
+            return buildStoryboardGenerateWorkflow(vars);
+        case "workflows/chain.md":
+            return buildStoryboardChainWorkflow(vars);
+        case "workflows/safety-check.md":
+            return buildStoryboardSafetyCheckWorkflow(vars);
+        case "workflows/finish.md":
+            return buildStoryboardFinishWorkflow(vars);
+        case "workflows/recover.md":
+            return buildStoryboardRecoverWorkflow(vars);
+        case "skills/frame-chaining/SKILL.md":
+            return buildStoryboardFrameChainingSkill(vars);
+        case "skills/coverage-system/SKILL.md":
+            return buildStoryboardCoverageSkill(vars);
+        case "skills/prompt-structure/SKILL.md":
+            return buildStoryboardPromptStructureSkill(vars);
+        default:
+            return renderContentTemplate(rawContent, vars);
+    }
+}
 function renderContentTemplate(content, vars) {
     return content
         .replaceAll("$OUTPUT_DIR", vars.outputDir)
@@ -70,8 +126,429 @@ function renderContentTemplate(content, vars) {
         .replaceAll("$MODEL_DISPLAY", vars.modelDisplayName)
         .replaceAll("$MODEL", vars.model)
         .replaceAll("$KLING_PRESET", vars.klingPreset)
+        .replaceAll("$REFERENCE_MODE", vars.referenceMode)
+        .replaceAll("$MAX_STORYBOARD_PHASES", String(vars.maxStoryboardPhases))
         .replaceAll("$ARGUMENTS", "");
 }
+function buildStoryboardGenerateWorkflow(vars) {
+    return `---
+description: Generate storyboard-reference prompt bundles from character references and a brief. Storyboard mode forbids start/end frame output.
+---
+
+# /generate - Storyboard Reference Mode
+
+## Fail-Closed Mode Gate
+
+- Active workflow: \`generate-storyboard\`.
+- Reference mode: \`storyboard-reference\`.
+- Start/end frame generation: disabled.
+- \`/generate\` MUST follow this storyboard-reference workflow. Do not use the legacy start/end shot template.
+- Missing character reference is a blocker. If the user did not provide \`--character-ref\`, an in-context character image, or \`refs/character.png\`, stop and request one.
+- Empty brief is a blocker. Use the active editor markdown first, then \`${vars.scenarioHint}\`.
+- Forbidden in generated \`SHOTNN.md\`: \`ILK FRAME\`, \`İLK FRAME\`, \`SON FRAME\`, \`SHOTNN_START\`, \`SHOTNN_END\`, exact first-frame reuse instructions, and mandatory Start+End transition fields.
+
+## Model Profile
+
+- Read \`.agent/model-profile.md\` before planning.
+- Active model: \`${vars.model}\` (\`${vars.modelDisplayName}\`)
+- Reference mode: \`storyboard-reference\`
+- Max storyboard phases per shot: ${vars.maxStoryboardPhases}
+
+## Required Outputs
+
+\`\`\`text
+${vars.outputDir}/
+├── storyboard-reference-plan.json
+├── reference-prep/
+│   └── CHARACTER-SHEET-*.md
+├── storyboard-prompts/
+│   └── SHOTNN-GPT-IMAGE-2-STORYBOARD.md
+├── prompt-bundles/
+│   └── SHOTNN.bundle.json
+├── shots/
+│   └── SHOTNN.md
+└── reports/
+    └── STORYBOARD-REFERENCE-QA.md
+\`\`\`
+
+## Flow
+
+1. Confirm asset roles:
+   - character references: identity, face, body proportions, wardrobe, accessories, and visible props
+   - optional storyboard guide references: composition, blocking, camera, timing, and action rhythm 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
+   - no labels, text, logos, watermarks, alternate designs, or extra characters
+3. Build \`${vars.outputDir}/storyboard-reference-plan.json\` with:
+   - \`referenceMode: "storyboard-reference"\`
+   - \`storyboardReferenceMode.enabled: true\`
+   - \`maxStoryboardPhases: ${vars.maxStoryboardPhases}\`
+   - \`voiceCast\` when dialogue or narration exists
+   - \`visual_world\` for camera, lens, lighting, scale, reflection, physics, screen direction, and continuity anchors
+4. Split the scenario into shots by dramatic beat. Use this phase budget:
+   - 4-6 seconds: 1-2 phases
+   - 7-10 seconds: 2-3 phases
+   - 11-15 seconds: 3-4 phases
+   - 5+ distinct phases: split into separate \`SHOTNN.md\` files
+5. For each shot, write a GPT Image 2 storyboard prompt:
+   - use character sheets as the only identity source
+   - use optional storyboard guides only for staging and timing
+   - include previous-shot handoff and next-shot handoff
+   - preserve shared \`visual_world\`, lighting, screen direction, and action rhythm
+6. Build model-ready video prompt bundles:
+   - Seedance: character sheet tokens first, generated shot storyboard token next
+   - Veo: visual planning prompt with full audio direction
+   - Kling: block-structured storyboard route, not a mandatory Start+End frame route
+7. Keep coverage inside the same \`SHOTNN.md\`; coverage uses storyboard planning prompts and does not request separate start/end still prompts.
+8. Run QA and write \`${vars.outputDir}/reports/STORYBOARD-REFERENCE-QA.md\`.
+
+## Required SHOTNN.md Sections
+
+Each storyboard-reference shot file must include:
+
+- \`Model Control\`
+- \`Input Asset Roles\`
+- \`Reference Asset Requirements\`
+- \`GPT Image 2 Character Sheet Prompt\` or a link to the generated character sheet prompt
+- \`GPT Image 2 SHOTNN Storyboard Prompt\`
+- \`Storyboard Plan\`
+- \`Audio Plan\`
+- \`${vars.model === "seedance-2.0" ? "Seedance 2.0 Ready Video Prompt" : "Model-Ready Video Prompt"}\`
+- \`Coverage Shots\`
+- \`QA Verdict\`
+
+## QA Verdict
+
+Reject the output if:
+
+- any main shot uses start/end frame sections or exact first-frame reuse instructions
+- character identity is sourced from storyboard drawings, text, panel borders, watermarks, logos, or alternate designs
+- storyboard phases exceed ${vars.maxStoryboardPhases} in one \`SHOTNN.md\`
+- coverage is split into separate files
+- \`storyboard_reference_status\` or \`storyboard_handoff_status\` is fail
+`;
+}
+function buildStoryboardChainWorkflow(vars) {
+    return `---
+description: Continue storyboard-reference projects using storyboard handoff continuity, not start/end frame chaining.
+---
+
+# /chain - Storyboard Reference Continuation
+
+## Mode Gate
+
+- Reference mode: \`storyboard-reference\`.
+- Continue from the previous shot's \`Storyboard Plan\` final handoff.
+- Do not extract or reuse end-frame assets.
+- Do not create \`ILK FRAME\` / \`SON FRAME\` sections.
+
+## Steps
+
+1. Read \`.agent/model-profile.md\`.
+2. Read \`${vars.outputDir}/storyboard-reference-plan.json\` and \`${vars.outputDir}/_index.md\` if present.
+3. Read the last completed \`${vars.outputDir}/shots/SHOTNN.md\`.
+4. Extract:
+   - final storyboard phase
+   - final action state
+   - camera direction and lens family
+   - lighting and screen direction
+   - character identity references
+5. Create the next shot with a matching opening \`Storyboard Plan\` handoff.
+6. Keep coverage in the same shot file.
+7. Update \`${vars.outputDir}/storyboard-reference-plan.json\`, prompt bundles, reports, and index.
+
+## Exit Gate
+
+- \`storyboard_handoff_status: pass\`
+- \`storyboard_reference_status: pass\`
+- no forbidden start/end frame sections
+`;
+}
+function buildStoryboardSafetyCheckWorkflow(vars) {
+    return `---
+description: Validate storyboard-reference outputs, role separation, safety, and handoff continuity.
+---
+
+# /safety-check - Storyboard Reference Validation
+
+## Mode Gate
+
+- Reference mode: \`storyboard-reference\`.
+- Validate storyboard prompt bundles and \`SHOTNN.md\` files.
+- Do not require start/end frame sections, frame reuse text, or Start+End transition fields.
+
+## Checklist
+
+1. Safety and name policy
+   - no real names in visual prompts or summaries
+   - dialogue naming follows \`${vars.outputDir}/storyboard-reference-plan.json\`
+   - public figure, trademark, and unsafe likeness risks are anonymized or blocked
+2. Storyboard-reference format
+   - each shot contains \`Input Asset Roles\`, \`Reference Asset Requirements\`, \`GPT Image 2 SHOTNN Storyboard Prompt\`, \`Storyboard Plan\`, \`Audio Plan\`, model-ready video prompt, coverage, and \`QA Verdict\`
+   - \`GPT Image 2 Character Sheet Prompt\` exists in the shot or \`${vars.outputDir}/reference-prep/\`
+   - no main shot contains \`ILK FRAME\`, \`İLK FRAME\`, \`SON FRAME\`, \`SHOTNN_START\`, \`SHOTNN_END\`, or exact first-frame reuse instructions
+3. Role separation
+   - character sheets control identity, body, wardrobe, accessories, and visible props
+   - generated shot storyboards control composition, blocking, camera, timing, and action rhythm only
+   - storyboard text, borders, logos, watermarks, and alternate designs are never identity sources
+4. Continuity and semantic consistency
+   - \`storyboard-reference-plan.json\` contains \`visual_world\`
+   - each \`Storyboard Plan\` phase aligns with camera, lens, lighting, scale, reflection, physics, and screen direction
+   - shot-to-shot handoff uses storyboard state, not end-frame reuse
+   - phases are capped at ${vars.maxStoryboardPhases}; 5+ distinct phases are split
+5. Audio and coverage
+   - \`voiceCast\` exists when dialogue or narration exists
+   - every speaking video prompt has \`Audio Plan\`
+   - coverage stays in the same \`SHOTNN.md\` and does not request start/end still prompts
+
+## Report Contract
+
+Write \`${vars.outputDir}/reports/STORYBOARD-REFERENCE-QA.md\`:
+
+\`\`\`markdown
+# STORYBOARD REFERENCE QA
+
+- overall_status: pass/fail
+- safety_status: pass/fail
+- visual_name_leak_status: pass/fail
+- dialogue_name_policy_status: pass/fail
+- storyboard_reference_status: pass/fail
+- storyboard_handoff_status: pass/fail
+- role_separation_status: pass/fail
+- visual_world_status: pass/fail
+- audio_plan_status: pass/fail
+- coverage_status: pass/fail
+- forbidden_start_end_status: pass/fail
+- blockers:
+  - none
+
+## Findings
+- [concise list]
+
+## Fixes Applied
+- [concise list or none]
+\`\`\`
+
+Rules:
+- If any field is fail, \`overall_status\` is fail.
+- Do not mark pass while blockers remain.
+`;
+}
+function buildStoryboardFinishWorkflow(vars) {
+    return `---
+description: Finalize storyboard-reference prompt packages after storyboard QA passes.
+---
+
+# /finish - Storyboard Reference Completion
+
+## Mode Gate
+
+- Reference mode: \`storyboard-reference\`.
+- Completion depends on \`${vars.outputDir}/reports/STORYBOARD-REFERENCE-QA.md\`, not start/end frame reports.
+
+## Validate Files
+
+1. \`${vars.outputDir}/storyboard-reference-plan.json\` exists.
+2. \`${vars.outputDir}/reference-prep/\` contains character sheet prompt files.
+3. \`${vars.outputDir}/storyboard-prompts/\` contains per-shot GPT Image 2 storyboard prompts.
+4. \`${vars.outputDir}/prompt-bundles/\` contains model prompt bundles.
+5. Every \`${vars.outputDir}/shots/SHOTNN.md\` contains the required storyboard-reference sections.
+6. Coverage stays in the same \`SHOTNN.md\`.
+7. No generated shot contains forbidden start/end frame sections or exact first-frame reuse instructions.
+8. \`storyboard_reference_status\` and \`storyboard_handoff_status\` are pass.
+
+## Final Summary
+
+Write \`${vars.outputDir}/FINAL-SUMMARY.md\` with:
+
+- total storyboard-reference shots
+- character sheet prompts
+- storyboard prompt files
+- prompt bundles
+- model targets
+- QA status
+- unresolved blockers
+- final verdict
+
+Do not declare completion unless \`STORYBOARD-REFERENCE-QA.md\` is pass.
+`;
+}
+function buildStoryboardRecoverWorkflow(vars) {
+    return `---
+description: Recover storyboard-reference outputs when QA or delivery gates fail.
+---
+
+# /recover - Storyboard Reference Recovery
+
+## Trigger Conditions
+
+- \`STORYBOARD-REFERENCE-QA.md\` is fail or missing
+- character reference is missing
+- \`storyboard-reference-plan.json\` is missing or contradictory
+- any shot is missing required storyboard-reference sections
+- any shot contains forbidden start/end frame sections or exact first-frame reuse instructions
+- storyboard phases exceed ${vars.maxStoryboardPhases}
+- role separation fails
+- storyboard handoff continuity fails
+
+## Steps
+
+1. Identify failed files and fields.
+2. Fix only affected character sheet prompts, storyboard prompts, prompt bundles, or shot files.
+3. Preserve accepted character references and \`visual_world\`.
+4. Split overloaded storyboard phases instead of compressing them.
+5. Remove forbidden start/end frame sections from storyboard-reference shots.
+6. Re-run \`/safety-check\`.
+7. Update \`${vars.outputDir}/_index.md\` and \`${vars.outputDir}/FINAL-SUMMARY.md\` if they exist.
+
+## Exit Criteria
+
+- \`${vars.outputDir}/reports/STORYBOARD-REFERENCE-QA.md\` exists
+- \`overall_status: pass\`
+- \`storyboard_reference_status: pass\`
+- \`storyboard_handoff_status: pass\`
+- \`forbidden_start_end_status: pass\`
+`;
+}
+function buildStoryboardFrameChainingSkill(vars) {
+    return `---
+name: frame-chaining
+description: Storyboard-reference continuity protocol. In this mode, continuity is handled by storyboard handoff notes rather than start/end frame assets.
+---
+
+# Storyboard Handoff Continuity
+
+## Mode Gate
+
+- Reference mode: \`storyboard-reference\`.
+- Start/end frame generation: disabled.
+- Do not create first-frame or last-frame still sections.
+- Do not use exact end-frame-to-first-frame reuse text.
+
+## Core Principle
+
+Every shot's final \`Storyboard Plan\` phase must hand off clearly into the next shot's opening \`Storyboard Plan\` phase.
+
+Continuity is enforced through:
+
+- shared \`${vars.outputDir}/storyboard-reference-plan.json -> visual_world\`
+- character sheet identity locks
+- camera direction and screen direction
+- lighting direction and color temperature
+- action state at the end of one shot and start of the next
+- foreground/midground/background scale and subject placement
+
+## Handoff Fields
+
+Each \`SHOTNN.md\` must include in \`Storyboard Plan\`:
+
+- \`entry_handoff\`: previous shot state or first-shot opening state
+- \`timeline_phases\`: 1-${vars.maxStoryboardPhases} purposeful phases
+- \`exit_handoff\`: final action, camera, lighting, and staging state for the next shot
+- \`continuity_mode\`: \`continuous-shot\` or \`multi-shot-storyboard\`
+
+## Chain Break Equivalent
+
+Use \`storyboard_handoff_reset\` only for:
+
+- location change
+- time jump
+- dream, memory, or flashback
+- deliberate camera-axis reset
+- intentionally discontinuous montage
+
+State the reason and the new \`visual_world\` deltas explicitly.
+`;
+}
+function buildStoryboardCoverageSkill(_vars) {
+    return `---
+name: coverage-system
+description: Storyboard-reference coverage protocol. Coverage remains mandatory inside each SHOTNN.md without separate start/end still prompts.
+---
+
+# Coverage System - Storyboard Reference Mode
+
+## Core Rule
+
+Every main shot still needs 2-3 coverage beats in the same \`SHOTNN.md\`.
+
+## Storyboard Mode Differences
+
+- Coverage does not request separate first-frame or last-frame still prompts.
+- Coverage is planned as editorial support inside the same storyboard-reference package.
+- Coverage must preserve character sheet identity locks and shared \`visual_world\`.
+- Coverage may include reaction, over-the-shoulder, insert, cutaway, extreme close-up, or wide cutaway beats.
+
+## Required Coverage Fields
+
+Each coverage item includes:
+
+- coverage type
+- Turkish summary when the surrounding runtime uses Turkish summaries
+- storyboard planning prompt or concise shot plan
+- model-ready video prompt
+- audio plan when speech, SFX, ambience, or voiceover matters
+- Avoid line
+
+Do not split coverage into separate files.
+`;
+}
+function buildStoryboardPromptStructureSkill(vars) {
+    return `---
+name: prompt-structure
+description: Storyboard-reference prompt structure for GPT Image 2 character sheets, per-shot storyboards, and model-ready video prompts.
+---
+
+# Prompt Structure - Storyboard Reference Mode
+
+## Mode Gate
+
+- Reference mode: \`storyboard-reference\`.
+- Active workflow: \`generate-storyboard\`.
+- Start/end frame generation: disabled.
+- Main shot start/end frame sections are forbidden.
+
+## Required Order
+
+1. Confirm character reference assets.
+2. Generate GPT Image 2 character sheet prompts.
+3. Generate one GPT Image 2 storyboard prompt per shot.
+4. Interpret the storyboard into a \`Storyboard Plan\`.
+5. Generate model-ready video prompt bundles.
+6. Add coverage inside the same \`SHOTNN.md\`.
+7. Run storyboard-reference QA.
+
+## Character Sheet Prompt
+
+- 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
+
+## SHOTNN Storyboard Prompt
+
+- 16:9 GPT Image 2 production storyboard
+- professional rough storyboard style
+- use character sheets as the only identity source
+- use optional storyboard guides only for composition, blocking, camera, timing, and rhythm
+- include entry and exit handoff notes
+- cap timeline phases at ${vars.maxStoryboardPhases}; split 5+ distinct phases
+
+## Model-Ready Video Prompt
+
+- Declare input asset roles before action prose.
+- Character sheet tokens lock identity, body, wardrobe, accessories, and props.
+- Generated shot storyboard token controls composition, blocking, camera direction, timing, and action progression only.
+- Use no-cuts wording only for a true uninterrupted camera move.
+- For multi-phase storyboard shots, describe planned phase transitions directly.
+- Include audio direction and Avoid line.
+
+## Forbidden Output
+
+Do not emit main-shot \`ILK FRAME\`, \`İLK FRAME\`, \`SON FRAME\`, \`SHOTNN_START\`, \`SHOTNN_END\`, or exact first-frame reuse instructions in storyboard-reference mode.
+`;
+}
 function getModelDisplayName(model) {
     if (model === "kling-3.0")
         return "Kling 3.0";
@@ -139,27 +616,26 @@ export async function configureAgents(options = {}) {
     if (copyContent !== undefined)
         merged.copyContent = copyContent;
     const resolved = resolveOptions(merged);
+    const storyboardReferenceActive = resolved.referenceMode === "storyboard-reference" && resolved.storyboardReferenceMode.enabled;
+    const templateVars = {
+        outputDir: resolved.outputDir,
+        scenarioHint: resolved.scenarioHint,
+        model: resolved.model,
+        klingPreset: getKlingPresetDisplay(resolved.model, resolved.klingPreset),
+        modelDisplayName: getModelDisplayName(resolved.model),
+        referenceMode: resolved.referenceMode,
+        storyboardReferenceActive,
+        maxStoryboardPhases: resolved.storyboardReferenceMode.maxStoryboardPhases
+    };
     if (resolved.platforms.includes("claude")) {
         await removeStaleClaudeArtifacts(resolved.rootDir);
     }
     // 1. Copy content files (.agent/ system) if enabled
     const contentResult = resolved.copyContent
-        ? await copyContentFiles(resolved.rootDir, resolved.overwrite, {
-            outputDir: resolved.outputDir,
-            scenarioHint: resolved.scenarioHint,
-            model: resolved.model,
-            klingPreset: getKlingPresetDisplay(resolved.model, resolved.klingPreset),
-            modelDisplayName: getModelDisplayName(resolved.model)
-        })
+        ? await copyContentFiles(resolved.rootDir, resolved.overwrite, templateVars)
         : { written: [], skipped: [] };
     const codexSkillMirrorResult = resolved.copyContent && resolved.platforms.includes("codex")
-        ? await copyContentFiles(resolved.rootDir, resolved.overwrite, {
-            outputDir: resolved.outputDir,
-            scenarioHint: resolved.scenarioHint,
-            model: resolved.model,
-            klingPreset: getKlingPresetDisplay(resolved.model, resolved.klingPreset),
-            modelDisplayName: getModelDisplayName(resolved.model)
-        }, ".agents", true)
+        ? await copyContentFiles(resolved.rootDir, resolved.overwrite, templateVars, ".agents", true)
         : { written: [], skipped: [] };
     // 2. Generate platform-specific config files
     const files = buildProjectFiles(resolved);
@@ -169,7 +645,8 @@ export async function configureAgents(options = {}) {
         const absolutePath = join(resolved.rootDir, relativePath);
         const fileExists = await exists(absolutePath);
         const isRuntimeModelFile = relativePath === ".agent/model-profile.md";
-        if (fileExists && !isRuntimeModelFile && !resolved.overwrite) {
+        const isStoryboardModeSensitiveProjectFile = storyboardReferenceActive && STORYBOARD_MODE_SENSITIVE_PROJECT_FILES.has(relativePath);
+        if (fileExists && !isRuntimeModelFile && !isStoryboardModeSensitiveProjectFile && !resolved.overwrite) {
             skipped.push(relativePath);
             continue;
         }

package/build/lib/defaults.js

@@ -17,7 +17,9 @@ export function normalizeStoryboardReferenceConfig(input, referenceMode) {
         throw new Error("Invalid storyboardReferenceMode.maxStoryboardPhases. Expected a positive integer.");
     }
     return {
-        enabled: input?.enabled ?? referenceMode === "storyboard-reference",
+        enabled: referenceMode === "storyboard-reference"
+            ? true
+            : input?.enabled ?? DEFAULT_STORYBOARD_REFERENCE_CONFIG.enabled,
         maxStoryboardPhases,
         defaultCharacterRefRole: "character_identity",
         defaultStoryboardRefRole: "storyboard_plan",

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

@@ -54,6 +54,12 @@ export class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter {
         const promptText = `${this.formatCharacterRoleLine(input)}
 ${this.formatStoryboardRoleLine(input)}
 
+[REFERENCE ROLES]
+- Identity reference: ${characterTokenText} locks face, hair, body proportions, wardrobe, accessories, visible props, and material continuity.
+- Camera reference: ${storyboardToken} controls composition, camera direction, framing, screen direction, shot order, and lens rhythm only.
+- Action reference: ${storyboardToken} controls blocking, pose logic, timing, action rhythm, phase order, and emotional progression only.
+- Audio reference: use the Audio Plan text below for dialogue, SFX, ambience, and music intent; do not infer audio from storyboard annotations unless explicitly requested.
+
 ${continuityInstruction}
 
 [CORE INTENT]
@@ -119,10 +125,14 @@ Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders,
                 ? hasNoCutsRule
                 : /left-to-right, top-to-bottom/i.test(output.promptText)
                     && /Do not reinterpret actions, poses, camera angles, emotional progression/i.test(output.promptText),
+            separatesReferenceRoles: /Identity reference:/i.test(output.promptText)
+                && /Camera reference:/i.test(output.promptText)
+                && /Action reference:/i.test(output.promptText)
+                && /Audio reference:/i.test(output.promptText),
             blocksStoryboardIdentitySources: /Storyboard text, panel borders, arrows, colored marks, lens notes, watermark, logo, and alternate character design are never identity sources/i.test(output.promptText),
             continuityMode: continuityMode === "continuous-shot"
                 ? hasNoCutsRule
-                : !hasNoCutsRule && /planned storyboard phase transitions/i.test(output.promptText),
+                : !hasNoCutsRule && /storyboard-motivated cuts/i.test(output.promptText),
             musicNone: /Music: NONE/i.test(output.promptText)
         };
         const issues = [