@milenyumai/film-kit 2.3.1 → 2.3.3

package/build/lib/templates.js

@@ -8,7 +8,37 @@ function getModelDisplayName(model) {
 function getKlingPresetDisplay(model, klingPreset) {
     return model === "kling-3.0" ? klingPreset : "n/a (Kling-only)";
 }
-function buildSeedanceProfile(active) {
+function isStoryboardReference(config) {
+    return config.referenceMode === "storyboard-reference" && Boolean(config.storyboardReferenceMode?.enabled);
+}
+function buildReferenceModeSummary(config) {
+    const referenceMode = config.referenceMode ?? "start-end";
+    if (!isStoryboardReference(config)) {
+        return `- Reference mode: \`${referenceMode}\`
+- Start/end frame generation: enabled
+- Active workflow: \`generate\``;
+    }
+    return `- Reference mode: \`storyboard-reference\`
+- Storyboard reference mode: enabled
+- Max storyboard phases per shot: ${config.storyboardReferenceMode?.maxStoryboardPhases ?? 4}
+- Start/end frame generation: disabled
+- Active workflow: \`generate-storyboard\`
+- \`ILK FRAME\` / \`İLK FRAME\` / \`SON FRAME\` sections are forbidden in storyboard-reference mode`;
+}
+function buildStoryboardPlatformGuard(config) {
+    if (!isStoryboardReference(config)) {
+        return "";
+    }
+    return `
+## Storyboard-Reference Mode Guard
+- Reference mode is \`storyboard-reference\`; \`/generate\` must follow \`.agent/workflows/generate.md\`, which is rendered as the storyboard workflow for this project.
+- Do not generate main-shot \`ILK FRAME\`, \`İLK FRAME\`, or \`SON FRAME\` sections.
+- Do not use exact first-frame reuse instructions, \`SHOTNN_START\`, \`SHOTNN_END\`, or mandatory Start+End transition fields.
+- If no character reference is available through the user, an in-context image, \`--character-ref\`, or \`refs/character.png\`, stop and request one.
+- Required storyboard outputs: \`${config.outputDir}/storyboard-reference-plan.json\`, \`${config.outputDir}/reference-prep/\`, \`${config.outputDir}/storyboard-prompts/\`, \`${config.outputDir}/prompt-bundles/\`, \`${config.outputDir}/shots/SHOTNN.md\`, and \`${config.outputDir}/reports/STORYBOARD-REFERENCE-QA.md\`.
+`;
+}
+function buildSeedanceProfile(active, storyboardReferenceActive = false, maxStoryboardPhases = 4) {
     return `## Seedance 2.0 Rules${active ? " (ACTIVE)" : " (Reference)"}
 
 ### Capability Mindset
@@ -40,6 +70,10 @@ Seedance 2.0 is strongest when prompting treats the model as a **multimodal shot
 - Storyboard phase budget: 4-6s uses 1-2 phases, 7-10s uses 2-3 phases, 11-15s uses at most 4 phases; split 5+ meaningful phases into separate SHOTNN.md files
 - Storyboard role separation: \`@Image1\` / \`@image1\` locks identity, face, body proportions, wardrobe, accessories, and visible props; \`@Image2\` / \`@image2\` controls composition, blocking, camera direction, timing, and action rhythm only
 - Storyboard text, panel borders, watermark, logo, and alternate character designs are never identity sources
+${storyboardReferenceActive
+        ? `- Storyboard-reference project gate is active: generate GPT Image 2 character sheets and per-shot storyboards first; do not ask for main-shot start/end frame sections
+- Cap per-shot storyboard phases at ${maxStoryboardPhases}; split 5+ meaningful phases into separate SHOTNN.md files`
+        : ""}
 
 ### Video Extension Rules
 - Extension syntax should start from the existing clip: \`Extend @video1 by 5s\`
@@ -116,10 +150,12 @@ model_reasoning_effort = "high"
 developer_instructions = ${tomlString(developerInstructions)}
 `;
 }
-function buildCodexImageSkill(workflowFile, outputDir) {
+function buildCodexImageSkill(workflowFile, config) {
+    const outputDir = config.outputDir;
+    const storyboardReferenceActive = isStoryboardReference(config);
     return `---
 name: film-kit-codex-images
-description: Optional Codex-native still image phase for Film-Kit. 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 after /generate and wait for user confirmation.
+description: Optional Codex-native still phase for Film-Kit. Use after successful prompt generation when the user wants ${storyboardReferenceActive ? "optional character sheet or storyboard still prep" : "to create or iteratively edit accepted ILK FRAME and SON FRAME images"} inside Codex. Never auto-start; offer it after /generate and wait for user confirmation.
 ---
 
 # Film-Kit Codex Images
@@ -141,20 +177,28 @@ 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.
+- Preserve role separation: character sheets lock identity; shot storyboard images guide staging only.
+- 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 = isStoryboardReference(config);
     return `---
 description: Optional Codex-native still image phase for Film-Kit single-agent output
 ---
@@ -175,30 +219,37 @@ description: Optional Codex-native still image phase for Film-Kit single-agent o
 \`\`\`text
 ${outputDir}/codex-images/
 ├── SHOTNN/
-│   ├── ilk-frame.png
+${storyboardReferenceActive
+        ? "│   ├── character-sheet.png\n│   └── shot-storyboard.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. Ask which shot range to process. Default to sequential order.
-2. For a fresh shot, generate \`ILK FRAME\` from the accepted 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 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.
+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.
 `;
 }
 export function buildProjectFiles(config) {
@@ -232,12 +283,14 @@ export function buildProjectFiles(config) {
         files[".codex/config.toml"] = buildCodexConfig();
         files[".codex/agents/prompt-engineer.toml"] = buildCodexAgentToml("prompt_engineer", "Film-Kit prompt engineer for single-agent cinematic shot generation, repair, and delivery QA.", `Read AGENTS.md first, then .agent/model-profile.md, .agent/MASTER.md, .agent/VOICE-DESIGN.md, .agent/agents/prompt-engineer.md, and the requested .agent/workflows/*.md file before acting.
 Use .agents/skills for Codex App skill discovery; .agent remains the Film-Kit legacy runtime source.
-When /generate finishes successfully inside Codex, always offer /codex-images as an optional still-image phase. Never auto-start it.
+${isStoryboardReference(config)
+            ? "When /generate is requested, treat it as storyboard-reference generation: require a character reference, follow .agent/workflows/generate.md, and do not create ILK FRAME / SON FRAME sections. Offer /codex-images only as optional reference still prep after QA passes."
+            : "When /generate finishes successfully inside Codex, always offer /codex-images as an optional still-image phase. Never auto-start it."}
 When /generate-storyboard is requested, use .agent/workflows/generate-storyboard.md and .agent/skills/storyboard-reference/SKILL.md; do not require start/end frames.
 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 running package commands.`);
-        files[".agents/skills/film-kit-codex-images/SKILL.md"] = buildCodexImageSkill(".agent/workflows/codex-images.md", config.outputDir);
-        files[".agent/workflows/codex-images.md"] = buildCodexImagesWorkflow(config.outputDir);
+        files[".agents/skills/film-kit-codex-images/SKILL.md"] = buildCodexImageSkill(".agent/workflows/codex-images.md", config);
+        files[".agent/workflows/codex-images.md"] = buildCodexImagesWorkflow(config);
         if (config.platforms.includes("antigravity")) {
             files[".agents/skills/shotforge-generate/SKILL.md"] = buildAntigravitySkill(config);
         }
@@ -318,8 +371,24 @@ When the user asks \`/generate-storyboard\`, use character reference + storyboar
 - If there is an active/selected markdown file in editor, use that first.
 - Target model: \`${config.model}\` (${getModelDisplayName(config.model)})
 - Kling preset: \`${getKlingPresetDisplay(config.model, config.klingPreset)}\`
+${buildReferenceModeSummary(config)}
+${buildStoryboardPlatformGuard(config)}
 
 ## Output Contract
+${isStoryboardReference(config)
+        ? `In storyboard-reference mode, each \`SHOTNN.md\` contains storyboard prompt package sections only:
+- Input Asset Roles
+- Reference Asset Requirements
+- GPT Image 2 Character Sheet Prompt
+- GPT Image 2 SHOTNN Storyboard Prompt
+- Storyboard Plan
+- Audio Plan
+- ${config.model === "seedance-2.0" ? "Seedance 2.0 Ready Video Prompt" : "Model-Ready Video Prompt"}
+- Coverage Shots
+- QA Verdict
+
+Do not use the start/end frame output contract in this mode.`
+        : `
 Each \`SHOTNN.md\` is a **single file** containing ALL shot details:
 - 🔗 Chain status (FIRST / CHAINED / CHAIN BREAK)
 - İLK FRAME (start frame image prompt — compact reference-first still contract)
@@ -329,12 +398,13 @@ Each \`SHOTNN.md\` is a **single file** containing ALL shot details:
 - COVERAGE SHOTS (2-3 coverage shots within same file — compact stills + detailed coverage video when needed)
 - 🇹🇷 Turkish summary for each section
 - Avoid line on EVERY prompt
+`}
 
 ## Critical Rules
 - **AUTO-ANONYMOUS:** Replace ALL real person names with physical descriptions automatically
 - **Name Policy:** Visual prompts must stay anonymous. Dialogue naming follows \`shot-plan.json\` policy.
 - **AUTO-SAFETY:** Proactively reframe content that may trigger safety filters
-- **Frame Chaining:** Last frame of SHOT[N] = First frame of SHOT[N+1]
+- **Continuity:** ${isStoryboardReference(config) ? "Storyboard handoff continuity replaces start/end frame chaining" : "Last frame of SHOT[N] = First frame of SHOT[N+1]"}
 - **Semantic Consistency:** \`shot-plan.json.visual_world\` is canonical for perspective, named camera movement strategy, shadow vector, scale, reflection, physics, and seed strategy
 - **Coverage Mandatory:** Every main shot includes 2-3 coverage sub-shots in same file
 - **Voice Design:** \`shot-plan.json\` keeps top-level \`voiceCast\`; every speaking VIDEO section keeps \`Audio Plan\`
@@ -346,6 +416,8 @@ Each \`SHOTNN.md\` is a **single file** containing ALL shot details:
 function buildCursorLegacyRules(config) {
     return `# Film-Kit Rules — Hollywood Standard Cinematic Prompt Engineering
 # ${getModelDisplayName(config.model)} | ALL GENRES SUPPORTED
+${buildReferenceModeSummary(config)}
+${buildStoryboardPlatformGuard(config)}
 
 ## CRITICAL: SKILL LOADING PROTOCOL
 Before generating ANY prompts, read the appropriate skill files from .agent/skills/:
@@ -374,10 +446,10 @@ Read .agent/VOICE-DESIGN.md when dialogue, narrator VO, or reusable speaker iden
 6. Music: NONE by default. User must explicitly request.
 7. EVERY prompt must have an Avoid line. No exceptions.
 8. Coverage shots mandatory (2-3 per main shot, included in same file; stills stay compact, coverage videos stay detailed).
-9. Frame chaining: Last frame of SHOT[N] = First frame of SHOT[N+1].
+9. Continuity: ${isStoryboardReference(config) ? "storyboard handoff continuity; do not use start/end frame chaining." : "Last frame of SHOT[N] = First frame of SHOT[N+1]."}
 10. Semantic consistency: \`${config.outputDir}/shot-plan.json\` must include \`visual_world\`; prompts must align camera, named movement strategy, light/shadow vector, scale, reflections, physics, anatomy risk, and contextual logic.
-11. ILK/İLK FRAME section must contain a code block even for chained shots.
-12. Chained ILK/İLK FRAME code blocks must contain only: \`Use SHOT[prev]_END as exact first frame\`; any new visual prompt is a CHAIN BREAK.
+11. ${isStoryboardReference(config) ? "Storyboard-reference SHOTNN.md files must contain Input Asset Roles, Reference Asset Requirements, GPT Image 2 storyboard prompt, Storyboard Plan, Audio Plan, model-ready video prompt, coverage, and QA Verdict." : "ILK/İLK FRAME section must contain a code block even for chained shots."}
+12. ${isStoryboardReference(config) ? "ILK/İLK FRAME and SON FRAME sections are forbidden in storyboard-reference mode." : "Chained ILK/İLK FRAME code blocks must contain only: `Use SHOT[prev]_END as exact first frame`; any new visual prompt is a CHAIN BREAK."}
 13. ONE FILE PER SHOT: Each SHOTNN.md contains main shot + all coverage shots.
 14. Keep top-level \`voiceCast\` in ${config.outputDir}/shot-plan.json and \`Audio Plan\` in every speaking VIDEO section.
 15. Storyboard-reference mode: character ref locks identity; storyboard ref controls staging/camera/timing only; 5+ phases split.
@@ -407,6 +479,8 @@ alwaysApply: true
 ---
 
 # Film-Kit — Hollywood Standard Prompt Engineering
+${buildReferenceModeSummary(config)}
+${buildStoryboardPlatformGuard(config)}
 
 ## Entry Point
 Read \`.agent/MASTER.md\` for complete production ruleset.
@@ -439,13 +513,13 @@ All skills at: \`.agent/skills/[name]/SKILL.md\`
 - \`shot-plan.json\` stores top-level \`visual_world\` for camera/lens/camera-movement/light/shadow/scale/reflection/physics/seed strategy
 - Every speaking VIDEO section includes \`Audio Plan\`
 - AUTO-SAFETY: Proactively reframe sensitive content
-- Frame chaining: Last frame SHOT[N] = First frame SHOT[N+1]
-- Chained ILK/İLK FRAME code block contains only \`Use SHOT[prev]_END as exact first frame\`; any new visual prompt requires CHAIN BREAK
+- Continuity: ${isStoryboardReference(config) ? "storyboard handoff continuity; start/end frame chaining is disabled" : "Last frame SHOT[N] = First frame SHOT[N+1]"}
+- ${isStoryboardReference(config) ? "Main-shot ILK/İLK FRAME and SON FRAME sections are forbidden in storyboard-reference mode" : "Chained ILK/İLK FRAME code block contains only `Use SHOT[prev]_END as exact first frame`; any new visual prompt requires CHAIN BREAK"}
 - Coverage: 2-3 sub-shots per main shot (same file; compact stills, detailed coverage videos)
 - Avoid line: MANDATORY on every prompt
 - Music: NONE by default
 - Duration: 8s default, slow burn pacing
-- ILK/İLK FRAME section always contains a code block
+- ${isStoryboardReference(config) ? "Required storyboard sections: Input Asset Roles, Reference Asset Requirements, GPT Image 2 storyboard prompt, Storyboard Plan, Audio Plan, model-ready video prompt, Coverage, QA Verdict" : "ILK/İLK FRAME section always contains a code block"}
 - ONE FILE PER SHOT: SHOTNN.md contains everything
 
 ## Output
@@ -464,6 +538,8 @@ function buildClaudeRoot(config) {
 
 ## Workspace Mode
 Single-agent shot package generation. Claude Code may use the native \`prompt-engineer\` subagent for focused drafting or repair, but planning and delivery stay in one session.
+${buildReferenceModeSummary(config)}
+${buildStoryboardPlatformGuard(config)}
 
 ## Mandatory Read Order
 1. \`.agent/model-profile.md\`
@@ -512,9 +588,9 @@ Before generating ANY prompts, read skills from \`.agent/skills/\`:
 7. **Avoid line:** MANDATORY on every prompt (image, video, coverage).
 8. **Coverage:** 2-3 sub-shots within same SHOTNN.md file, min 70 words each.
 9. **Voice Design:** keep project-level \`voiceCast\` in \`${config.outputDir}/shot-plan.json\` and per-shot \`Audio Plan\` in each VIDEO section.
-10. **ILK/İLK FRAME:** Always include a fenced code block, even when chained.
-11. **Chained ILK/İLK FRAME:** code block contains only \`Use SHOT[prev]_END as exact first frame\`; any new visual prompt requires CHAIN BREAK.
-12. **Image Prompt Contract:** reference-anchored ILK/SON use \`REFERENCE LOCK\` + \`Keep same\` + \`Change only\`; VIDEO >= 120; coverage video >= 70.
+10. **Continuity:** ${isStoryboardReference(config) ? "Use storyboard handoff continuity; do not create start/end frame sections." : "Always include a fenced ILK/İLK FRAME code block, even when chained."}
+11. **Chained ILK/İLK FRAME:** ${isStoryboardReference(config) ? "Forbidden in storyboard-reference mode." : "code block contains only `Use SHOT[prev]_END as exact first frame`; any new visual prompt requires CHAIN BREAK."}
+12. **Image Prompt Contract:** ${isStoryboardReference(config) ? "GPT Image 2 character sheets lock identity; per-shot storyboard prompts control staging only; VIDEO >= 120; coverage video >= 70." : "reference-anchored ILK/SON use `REFERENCE LOCK` + `Keep same` + `Change only`; VIDEO >= 120; coverage video >= 70."}
 13. **Specificity Floor:** lens/framing, lighting, and foreground/midground/background action are mandatory.
 14. **Spatial Realism Floor:** eyeline target, plane map, shared light source, and contact/depth cues are mandatory when relational staging matters.
 15. **Semantic Consistency Floor:** \`visual_world\`, perspective/geometry, shadow vector, scale map, reflections, gravity/contact physics, anatomy risk, foreground/background coherence, contextual contradictions, and targeted semantic avoid terms are mandatory.
@@ -541,6 +617,8 @@ function buildClaudeLocal(config) {
     return `# Local Claude Project Rules — Film-Kit Core
 
 This workspace keeps high-level policy in \`CLAUDE.md\` and operational detail in \`.claude/rules/\`.
+${buildReferenceModeSummary(config)}
+${buildStoryboardPlatformGuard(config)}
 
 ## Before Any Generation or Repair
 1. Read \`.agent/model-profile.md\`
@@ -576,6 +654,8 @@ description: Generate and repair Film-Kit single-agent shot packages with strict
 ---
 
 Use the Film-Kit core runtime.
+${buildReferenceModeSummary(config)}
+${buildStoryboardPlatformGuard(config)}
 
 ## Read First
 1. \`.agent/model-profile.md\`
@@ -611,6 +691,8 @@ function buildClaudeRuleGenerateFlow(config) {
 Read \`.agent/workflows/generate.md\` for the complete generation workflow.
 Read \`.agent/model-profile.md\` for active model constraints.
 If using the native Claude subagent, read \`.claude/agents/prompt-engineer.md\` and give it an explicit shot range or repair target.
+${buildReferenceModeSummary(config)}
+${buildStoryboardPlatformGuard(config)}
 
 ## Quick Reference
 1. **Scenario Analysis:**
@@ -662,6 +744,8 @@ Input source: \`${config.scenarioHint}\` or active editor file.
 }
 function buildClaudeRuleOutputContract(config) {
     return `# Output Contract — Film-Kit
+${buildReferenceModeSummary(config)}
+${buildStoryboardPlatformGuard(config)}
 
 ## Required Files
 - \`${config.outputDir}/project-info.md\` — Characters, settings, emotional arc mapping, tension levels
@@ -886,6 +970,8 @@ function buildClaudeSettingsLocal() {
 function buildCopilotInstructions(config) {
     return `# Film-Kit — Copilot Instructions
 ## Hollywood Standard Cinematic Prompt Engineering for ${getModelDisplayName(config.model)}
+${buildReferenceModeSummary(config)}
+${buildStoryboardPlatformGuard(config)}
 
 ### System Entry Point
 Read \`.agent/MASTER.md\` for the complete production ruleset.
@@ -926,8 +1012,8 @@ Before generating ANY prompts, read skills from \`.agent/skills/\`:
 - **AUTO-ANONYMOUS:** Replace ALL real names with physical descriptions
 - **Name Policy:** Dialogue naming follows \`${config.outputDir}/shot-plan.json\` policy
 - **AUTO-SAFETY:** Proactively reframe sensitive content
-- **Frame Chaining:** Last frame of SHOT[N] = First frame of SHOT[N+1]
-- **Chain Hardening:** chained ILK/İLK FRAME code block contains only \`Use SHOT[prev]_END as exact first frame\`
+- **Continuity:** ${isStoryboardReference(config) ? "Storyboard handoff continuity replaces start/end frame chaining" : "Last frame of SHOT[N] = First frame of SHOT[N+1]"}
+- **Chain Hardening:** ${isStoryboardReference(config) ? "ILK/İLK FRAME and SON FRAME sections are forbidden in storyboard-reference mode" : "chained ILK/İLK FRAME code block contains only `Use SHOT[prev]_END as exact first frame`"}
 - **Coverage:** 2-3 sub-shots per main shot (in same file; stills compact, coverage videos detailed)
 - **Spatial Realism:** eyeline targets, shared light, depth scale, and anti-cutout staging must agree when subjects share frame
 - **Semantic Consistency:** \`visual_world\` controls perspective/geometry, shadow vector, scale map, reflections, physics, anatomy risk, background coherence, and contextual contradictions
@@ -937,7 +1023,7 @@ Before generating ANY prompts, read skills from \`.agent/skills/\`:
 - **Storyboard Reference:** character ref identity wins; storyboard ref cannot redesign wardrobe, face, props, or copy text/logos
 - **Duration:** 8s default, slow burn pacing
 - **Language:** Prompts in English, dialogue preserved
-- **ILK/İLK FRAME:** keep fenced code block even when chained
+- **Shot Format:** ${isStoryboardReference(config) ? "use storyboard-reference sections and QA Verdict; do not emit start/end frame sections" : "keep ILK/İLK FRAME fenced code block even when chained"}
 - **ONE FILE PER SHOT:** SHOTNN.md contains main shot + all coverage
 
 ### Other Workflows
@@ -958,6 +1044,8 @@ function buildCopilotScopedInstructions(config) {
 applyTo: "**/*.md"
 ---
 # Film-Kit Scoped Instructions
+${buildReferenceModeSummary(config)}
+${buildStoryboardPlatformGuard(config)}
 
 When request is /generate, follow the Film-Kit Hollywood production system:
 1. Read \`.agent/workflows/generate.md\` for full procedure
@@ -987,6 +1075,8 @@ This skill is part of the Film-Kit prompt engineering system.
 Read \`.agent/MASTER.md\` for the complete production ruleset (690+ rules).
 Read \`.agent/VOICE-DESIGN.md\` for project-level \`voiceCast\` and shot-level \`audioPlan\`.
 Read \`.agent/model-profile.md\` first for active model constraints.
+${buildReferenceModeSummary(config)}
+${buildStoryboardPlatformGuard(config)}
 
 ## Skill Loading Protocol
 Before generating ANY prompts, read these skills:
@@ -1031,23 +1121,27 @@ Before generating ANY prompts, read these skills:
 1. **AUTO-ANONYMOUS:** Replace ALL real person names with physical descriptions
 2. **Name Policy:** Dialogue naming follows \`${config.outputDir}/shot-plan.json\` policy
 3. **AUTO-SAFETY:** Proactively reframe sensitive content
-4. **Frame Chaining:** Last frame of SHOT[N] becomes first frame of SHOT[N+1]
+4. **Continuity:** ${isStoryboardReference(config) ? "Storyboard handoff continuity replaces start/end frame chaining" : "Last frame of SHOT[N] becomes first frame of SHOT[N+1]"}
 5. **Coverage Mandatory:** 2-3 sub-shots per main shot (in same file; stills compact, coverage videos detailed)
 6. **Avoid Line:** MANDATORY on every prompt (image + video + coverage)
 7. **Voice Design:** keep \`voiceCast\` in \`${config.outputDir}/shot-plan.json\` and \`Audio Plan\` in every speaking VIDEO section
 8. **Music: NONE** by default
 9. **Ultra Realism** default visual mode
 10. **8s duration** default, slow burn pacing
-11. **ILK/İLK FRAME:** always keep fenced code block
-12. **Chained ILK/İLK FRAME:** code block contains only \`Use SHOT[prev]_END as exact first frame\`; any new visual prompt is CHAIN BREAK
+11. **Shot Format:** ${isStoryboardReference(config) ? "Use storyboard-reference sections; main-shot ILK/İLK FRAME and SON FRAME sections are forbidden" : "ILK/İLK FRAME always keeps a fenced code block"}
+12. **Chain Hardening:** ${isStoryboardReference(config) ? "Exact first-frame reuse text is forbidden in storyboard-reference mode" : "Chained ILK/İLK FRAME code block contains only `Use SHOT[prev]_END as exact first frame`; any new visual prompt is CHAIN BREAK"}
 13. **ONE FILE PER SHOT:** SHOTNN.md contains main shot + all coverage
 14. **Relational Realism:** preserve eyeline targets, shared light, depth scale, and anti-cutout staging when multiple subjects share frame
 15. **Semantic Consistency:** preserve \`visual_world\` perspective, shadow vector, scale map, reflections, gravity/contact physics, anatomy risk, foreground/background coherence, and contextual logic
 
 ## Quality Floor (Hard Gate)
 Reject and regenerate any shot that fails:
-- 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
+${isStoryboardReference(config)
+        ? `- missing \`Input Asset Roles\`, \`Reference Asset Requirements\`, \`GPT Image 2 SHOTNN Storyboard Prompt\`, \`Storyboard Plan\`, \`Audio Plan\`, model-ready video prompt, coverage, or \`QA Verdict\`
+- missing character sheet prompt or role separation between character identity and storyboard staging
+- forbidden main-shot start/end frame sections appear in storyboard-reference mode`
+        : `- 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`}
 - VIDEO < 120 words
 - any coverage video prompt < 70 words
 - reference-visible face/hair/skin/body/wardrobe/accessories/prop design drift
@@ -1077,6 +1171,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
@@ -1094,6 +1189,19 @@ ${isKling
 - Frame chaining and coverage contracts are active
 - Default pacing: 8s slow burn`}
 
+${isStoryboardReference(config)
+        ? `
+## Storyboard-Reference Hard Gate
+
+- \`/generate\` must behave as \`/generate-storyboard\`; do not use the legacy start/end shot workflow.
+- A character reference is required before shot generation. If no in-context character image, \`--character-ref\`, or \`refs/character.png\` is available, stop and request one.
+- Required shot sections: \`Input Asset Roles\`, \`Reference Asset Requirements\`, \`GPT Image 2 Character Sheet Prompt\`, \`GPT Image 2 SHOTNN Storyboard Prompt\`, \`Storyboard Plan\`, \`Audio Plan\`, \`Seedance 2.0 Ready Video Prompt\` or model-ready equivalent, \`Coverage Shots\`, and \`QA Verdict\`.
+- Forbidden main-shot sections/text: \`ILK FRAME\`, \`İLK FRAME\`, \`SON FRAME\`, \`SHOTNN_START\`, \`SHOTNN_END\`, exact first-frame reuse instructions, and mandatory Start+End transition fields.
+- Frame chaining is replaced by storyboard handoff continuity: the final \`Storyboard Plan\` phase of SHOT[N] must hand off into the opening phase of SHOT[N+1].
+- Safety and semantic reports must use \`storyboard_reference_status\` and \`storyboard_handoff_status\`, not start/end contract fields.
+`
+        : ""}
+
 ---
 
 ## Veo 3.1 Rules${config.model === "veo31" ? " (ACTIVE)" : " (Reference)"}
@@ -1126,7 +1234,7 @@ When generating video from a reference image:
 
 ---
 
-${buildSeedanceProfile(isSeedance)}
+${buildSeedanceProfile(isSeedance, isStoryboardReference(config), config.storyboardReferenceMode?.maxStoryboardPhases ?? 4)}
 
 ---
 

package/content/workflows/generate-storyboard.md

@@ -94,3 +94,19 @@ npx @milenyumai/film-kit generate-storyboard \
 - 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.
+- Main-shot `ILK FRAME`, `İLK FRAME`, `SON FRAME`, `SHOTNN_START`, `SHOTNN_END`, exact first-frame reuse instructions, or mandatory Start+End transition fields: output is invalid in storyboard-reference mode.
+
+## Required SHOTNN.md Sections
+
+Every 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`
+- `Seedance 2.0 Ready Video Prompt` or model-ready equivalent
+- `Coverage Shots`
+- `QA Verdict`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milenyumai/film-kit",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "description": "Single-package Film-Kit distribution with preset-driven cinematic runtime setup for OpenAI Codex App, Claude Code, Cursor, Copilot, and Antigravity.",
   "type": "module",
   "main": "./build/index.js",
@@ -44,6 +44,7 @@
     "build:presets": "npm --prefix packages/multi run build && npm --prefix packages/hybrid run build && npm --prefix packages/hybrid-smart run build && npm --prefix packages/gpt-image-smart run build && npm --prefix packages/studio run build",
     "dev:setup": "tsx src/postinstall.ts",
     "postinstall": "node -e \"import('./build/postinstall.js').then(m=>m.runPostinstall()).catch(()=>{})\"",
+    "release:check": "npm run typecheck && npm test && npm run build && npm publish --access public --dry-run",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json --noEmit"

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

@@ -67,17 +67,17 @@ function getBaseContentDirCandidates() {
     return candidates;
 }
 /**
- * Best-effort candidates for locating @milenyumai/film-kit-multi content directory.
+ * Best-effort candidates for locating the internal multi preset content directory.
  * 1) Monorepo/dev layout (packages/multi/content)
- * 2) Installed package layout resolved from dependency
+ * 2) Installed single-package layout (node_modules/@milenyumai/film-kit/packages/multi/content)
  */
 function getMultiContentDirCandidates() {
     const candidates = [];
     candidates.push(join(__dirname, "..", "..", "..", "multi", "content"));
     try {
         const require = createRequire(import.meta.url);
-        const multiPkgJson = require.resolve("@milenyumai/film-kit-multi/package.json");
-        candidates.push(join(dirname(multiPkgJson), "content"));
+        const basePkgJson = require.resolve("@milenyumai/film-kit/package.json");
+        candidates.push(join(dirname(basePkgJson), "packages", "multi", "content"));
     }
     catch {
         // Dependency may be unavailable in some local contexts.