@milenyumai/film-kit 2.2.1 → 2.3.1

package/build/lib/storyboard-reference/validators.js

@@ -29,9 +29,6 @@ export function validateResolvedAssetRoles(assets) {
     if (assets.characters.length === 0) {
         issues.push("Missing character identity reference.");
     }
-    if (assets.storyboards.length === 0) {
-        issues.push("Missing storyboard planning reference.");
-    }
     for (const character of assets.characters) {
         if (character.asset.role !== "character_identity") {
             issues.push(`${character.token} must use role character_identity.`);
@@ -71,10 +68,10 @@ export function validatePromptBundle(bundle, assets) {
         .flatMap(output => output?.qa.issues ?? []);
     const checks = {
         hasCharacterReference: assets.characters.length >= 1,
-        hasStoryboardReference: assets.storyboards.length >= 1,
+        hasStoryboardReference: assets.storyboards.length >= 1 || Boolean(bundle.storyboardImagePrompt),
         hasAvoidLineEverywhere: Object.values(bundle.modelPrompts).every(output => Boolean(output?.qa.checks.hasAvoidLine ?? output?.qa.checks.hasAvoidOrNegative)),
         modelGrammarPasses: Object.values(bundle.modelPrompts).every(output => output?.qa.verdict === "pass"),
-        storyboardDoesNotOverrideIdentity: Object.values(bundle.modelPrompts).every(output => /storyboard.*staging|storyboard.*planning|storyboard.*composition|Storyboard @image2 controls staging/i.test(output?.promptText ?? "")),
+        storyboardDoesNotOverrideIdentity: Object.values(bundle.modelPrompts).every(output => /storyboard.*staging|storyboard.*planning|storyboard.*composition|storyboard.*only/i.test(output?.promptText ?? "")),
         audioPlanPresent: Object.values(bundle.modelPrompts).every(output => Boolean(output?.audioPlan))
     };
     const failedChecks = Object.entries(checks)

package/build/lib/templates.js

@@ -14,14 +14,15 @@ function buildSeedanceProfile(active) {
 ### Capability Mindset
 Seedance 2.0 is strongest when prompting treats the model as a **multimodal shot compositor**:
 - image + video + audio + text can be combined in one request
-- reference assets are assigned explicit roles with \`@image1\`, \`@video1\`, \`@audio1\`
+- reference assets are assigned explicit roles with provider tokens such as \`@Image1\`, \`@Image2\`, \`@video1\`, \`@audio1\`
+- legacy lowercase aliases \`@image1\` and \`@image2\` may appear in older Film-Kit notes; bind them to \`@Image1\` and \`@Image2\`
 - prompt language should describe **what each reference controls**, not dump adjectives
 
 ### Core Prompt Grammar
-- Use reference roles explicitly: \`Use @image1 as the first frame\`, \`reference camera movement from @video1\`, \`background music references @audio1\`
+- Use reference roles explicitly: \`Use @Image1 as the first frame\`, \`reference camera movement from @video1\`, \`background music references @audio1\`
 - For long clips (10s+), segment time directly in prompt: \`0-3s: ... / 3-6s: ... / 6-10s: ...\`
 - Write visible action and emotion concretely: gestures, gaze shifts, breathing, mouth tension, hand behavior
-- If the clip must remain unbroken, end the instruction with: \`No scene cuts throughout, one continuous shot.\`
+- If the clip must remain unbroken, end the instruction with: \`No scene cuts throughout, one continuous shot.\`; do not apply that line to planned multi-phase storyboard cuts
 - For extensions, state the new generated length, not cumulative duration
 
 ### Reference Binding Strategy
@@ -36,6 +37,9 @@ Seedance 2.0 is strongest when prompting treats the model as a **multimodal shot
 - Use one continuous shot language when moving through multiple spaces without cuts
 - Speed changes should be explicit: build from calm to fast rather than saying "dynamic"
 - If a shot spans several phases, prefer timeline segments over vague "then many things happen" language
+- 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
 
 ### Video Extension Rules
 - Extension syntax should start from the existing clip: \`Extend @video1 by 5s\`
@@ -51,7 +55,7 @@ Seedance 2.0 is strongest when prompting treats the model as a **multimodal shot
 
 ### Failure Recovery
 - Camera motion not matching reference: say \`completely reference all camera movement effects from @video1\`
-- Character drift: add \`maintain character appearance exactly consistent with @image1\` and provide multi-angle stills
+- Character drift: add \`maintain character appearance exactly consistent with @Image1\` and provide multi-angle stills
 - Extension seam feels wrong: start the extension prompt from the original last-frame state before new action
 - Emotional acting feels flat: replace abstract mood labels with visible facial and body behavior
 
@@ -68,7 +72,7 @@ Seedance 2.0 is strongest when prompting treats the model as a **multimodal shot
 
 **Template A — Multimodal Continuous Shot**
 \`\`\`
-Use @image1 as the first frame. Reference camera movement from @video1 and background atmosphere from @audio1.
+Use @Image1 as the first frame. Reference camera movement from @video1 and background atmosphere from @audio1.
 Subjective forward-moving tracking shot through location A, then into location B, then arriving at location C.
 0-3s: establish the subject and moving camera path.
 3-6s: escalate the action with one clear environmental change.
@@ -78,7 +82,7 @@ No scene cuts throughout, one continuous shot.
 
 **Template B — Precise Performance Beat**
 \`\`\`
-Maintain character appearance exactly consistent with @image1.
+Maintain character appearance exactly consistent with @Image1.
 0-2s: eyes shift left, breath shortens, fingers tighten on the prop.
 2-4s: camera pushes closer while the character turns and delivers the line in a restrained voice.
 4-6s: expression softens, shoulders drop, the background returns to calm.

package/content/ARCHITECTURE.md

@@ -27,7 +27,7 @@ Modular system consisting of:
 ├── skills/
 │   ├── safety-compliance/   # Platform safety & celebrity ban
 │   ├── reference-locking/   # Reference image system
-│   ├── storyboard-reference/ # Character ref + storyboard ref prompt bundles
+│   ├── storyboard-reference/ # Character sheet + generated storyboard prompt bundles
 │   ├── frame-chaining/      # Shot continuity protocol
 │   ├── coverage-system/     # Mandatory coverage shots (NEW)
 │   ├── spatial-blocking/    # Eyeline, depth, scale, compositing realism
@@ -60,7 +60,7 @@ Modular system consisting of:
 |-------|-------------|
 | `safety-compliance` | **Platform safety**, celebrity name prohibition, AUTO-ANONYMOUS (otomatik anonimleştirme), AUTO-SAFETY, safe framing, content restrictions |
 | `reference-locking` | **Reference image enforcement**, EXACTLY language, repeat protocol |
-| `storyboard-reference` | **Character reference + storyboard reference mode**, role separation, phase cap, model-aware prompt bundles |
+| `storyboard-reference` | **Character reference sheet + generated storyboard mode**, role separation, phase cap, model-aware prompt bundles |
 | `frame-chaining` | **Shot continuity**, last frame → first frame chaining, scene transition protocol (fade, dissolve, match cut) |
 | `coverage-system` | **Mandatory coverage shots** (Reaction, OTS, Insert, Cutaway, ECU, Wide) + L-cut/J-cut + 30° kuralı + **180° kuralı** + eyeline match + matching action + multi-character blocking |
 | `spatial-blocking` | **Relational realism**: eyeline targeting, plane mapping, body orientation, shared lighting, depth/scale integration, anti-cutout / anti-miniature cues |
@@ -76,7 +76,7 @@ Modular system consisting of:
 | Command | Description |
 |---------|-------------|
 | `/generate` | Generate shots and SAVE TO FILES |
-| `/generate-storyboard` | Generate storyboard-reference model prompt bundles without start/end frame generation |
+| `/generate-storyboard` | Generate character sheet prompts, per-shot storyboard prompts, and storyboard-reference model prompt bundles without start/end frame generation |
 | `/chain` | Continue from last shot file |
 | `/safety-check` | Validate prompts before delivery |
 | `/recover` | Recover failed safety/delivery gates |
@@ -95,7 +95,7 @@ User Scenario → Agent Activated → Read model-profile → Load Required Skill
                                        ↓
                             safety-compliance (ALWAYS)
                             reference-locking (if refs provided)
-                            storyboard-reference (if character ref + storyboard ref mode)
+                            storyboard-reference (if character ref + brief mode)
                             frame-chaining (ALWAYS)
                             spatial-blocking (when gaze/depth/scale realism matters)
                             semantic-consistency (ALWAYS - visual_world + physics gate)

package/content/MASTER.md

@@ -24,7 +24,7 @@ Scenario Received → Check for elements:
     │
     ├── Celebrity/Public Figure mentioned? → READ safety-compliance/SKILL.md
     ├── Reference images provided? → READ reference-locking/SKILL.md
-    ├── Character ref + storyboard ref + brief? → READ storyboard-reference/SKILL.md
+    ├── Character ref + brief, optional storyboard guide? → READ storyboard-reference/SKILL.md
     ├── Multiple shots? → READ frame-chaining/SKILL.md (ALWAYS)
     ├── Multi-subject / gaze / depth realism? → READ spatial-blocking/SKILL.md
     ├── ALWAYS READ → semantic-consistency/SKILL.md (visual_world + semantic QA)
@@ -44,7 +44,7 @@ Scenario Received → Check for elements:
 | **BATCH** | "3 sahne", "5 shots" | Generate N shots sequentially |
 | **CHAIN CONTINUE** | "devam et", "continue" | Use previous END frame as START |
 | **CHAIN BREAK** | New location/time/character | Declare CHAIN BREAK, new START |
-| **STORYBOARD REFERENCE** | character reference + storyboard reference + brief | Use `/generate-storyboard`; produce model-aware prompt bundles without start/end frames |
+| **STORYBOARD REFERENCE** | character reference + brief, optional storyboard guide | Use `/generate-storyboard`; produce character sheet prompts, per-shot storyboard prompts, and model-aware prompt bundles without start/end frames |
 | **SAFETY CHECK** | /safety-check | Validate all prompts before delivery |
 
 ---

package/content/RULES.md

@@ -23,7 +23,7 @@ Film/Video request detected → Activate prompt-engineer agent
         ├── model-profile (ALWAYS FIRST)
         ├── safety-compliance (ALWAYS)
         ├── reference-locking (if refs provided)
-        ├── storyboard-reference (if character ref + storyboard ref + brief)
+        ├── storyboard-reference (if character ref + brief, optional storyboard guide)
         ├── frame-chaining (ALWAYS for multi-shot)
         ├── semantic-consistency (ALWAYS for visual_world + physics)
         ├── coverage-system (ALWAYS - mandatory)
@@ -38,7 +38,7 @@ Film/Video request detected → Activate prompt-engineer agent
 |-------|------|--------------|
 | Safety & Celebrity Ban | `.agent/skills/safety-compliance/SKILL.md` | ALWAYS |
 | Reference Locking | `.agent/skills/reference-locking/SKILL.md` | When refs provided |
-| Storyboard Reference | `.agent/skills/storyboard-reference/SKILL.md` | Character ref + storyboard ref + brief |
+| Storyboard Reference | `.agent/skills/storyboard-reference/SKILL.md` | Character ref + brief, optional storyboard guide |
 | Frame Chaining | `.agent/skills/frame-chaining/SKILL.md` | Multi-shot projects |
 | Semantic Consistency | `.agent/skills/semantic-consistency/SKILL.md` | ALWAYS |
 | Coverage System | `.agent/skills/coverage-system/SKILL.md` | ALWAYS (mandatory) |
@@ -55,7 +55,7 @@ Film/Video request detected → Activate prompt-engineer agent
 | **Film/Video prompt** | "sahne", "shot", "scene", "film" | Activate prompt-engineer |
 | **Single shot** | "bir sahne", "one shot" | Generate 1 shot |
 | **Batch generation** | "3 shot", "5 sahne" | Generate N shots |
-| **Storyboard-reference** | character ref + storyboard ref + brief, `/generate-storyboard` | Generate model-aware prompt bundles without start/end frames |
+| **Storyboard-reference** | character ref + brief, optional storyboard guide, `/generate-storyboard` | Generate character sheet prompts, shot storyboard prompts, and model-aware prompt bundles without start/end frames |
 | **Continue** | "devam et", "continue" | Chain from previous |
 | **Safety check** | /safety-check | Validate prompts |
 | **Recover** | /recover | Recover failed safety/delivery gates |
@@ -105,7 +105,7 @@ When references provided:
 
 ### Storyboard Reference Mode
 
-When the user provides a character reference image, storyboard reference image, and brief, treat `@character1` as identity lock and `@storyboard1` as staging/camera/timing plan only. Do not generate or require start/end frames in this mode. Do not let storyboard character design override the character reference. If the storyboard has 5+ distinct phases, split into multiple `SHOTNN.md` files.
+When the user provides a character reference image and brief, generate one 16:9 GPT Image 2 character sheet prompt per character first, then one GPT Image 2 storyboard prompt per shot. Character sheets lock identity; generated shot storyboards control staging/camera/timing only. Optional `@storyboard1` guide images are staging references only. Do not require start/end frames in this mode. If a shot needs 5+ distinct phases, split into multiple `SHOTNN.md` files.
 
 ### 🎬 Pacing Rules (SLOW BURN)
 

package/content/agents/prompt-engineer.md

@@ -30,7 +30,7 @@ You are a senior Technical Prompt Engineer specialized in model-aware cinematic
 1. **Generate technically precise, copyable shot files**
 2. **ENFORCE mandatory frame chaining for seamless visual continuity (CRITICAL)**
 3. **LOCK all characters/objects to user-provided reference images (CRITICAL)**
-4. **Support storyboard-reference mode:** character ref locks identity, storyboard ref controls staging/camera/timing only
+4. **Support storyboard-reference mode:** generated character sheets lock identity, generated shot storyboards control staging/camera/timing only
 5. **Maintain visual/audio continuity across all shots**
 6. **AUTO-ANONYMOUS:** Visual prompts and non-dialogue fields must stay anonymous
 7. **AUTO-SAFETY: Güvenlik filtrelerine takılacak içeriği proaktif reframe et**
@@ -70,7 +70,7 @@ Tercihiniz:"
 - "tek tek" / "1-1" → Generate ONLY 1 shot per response
 - "devam et" / "continue" → Use previously established batch size
 - User can change mid-project: "şimdi tek tek gidelim"
-- If the user explicitly asks `/generate-storyboard` or provides character ref + storyboard ref + brief, use storyboard-reference mode and infer/split panel phases instead of asking for start/end frames.
+- If the user explicitly asks `/generate-storyboard` or provides character ref + brief, use storyboard-reference mode, generate character sheet prompts and per-shot storyboard prompts, and infer/split panel phases instead of asking for start/end frames.
 
 ---
 
@@ -109,7 +109,7 @@ Before any generation, read `.agent/model-profile.md` and follow the active mode
 Prompt describes **which source controls what**, then the action path:
 
 ```text
-1. [Material roles] — "Use @image1 as first frame", "camera from @video1"
+1. [Material roles] — "Use @Image1 as first frame", "camera from @video1"
 2. [Identity lock] — what must remain exactly consistent
 3. [Continuous-shot rule] — no scene cuts unless intentionally segmented
 4. [Timeline] — short prose or explicit time ranges for meaningful phases
@@ -123,8 +123,8 @@ Prompt describes **which source controls what**, then the action path:
 | Rule | Detail |
 |------|--------|
 | **Reference separation** | Split identity, action, and camera sources when needed |
-| **First-frame anchor** | Use `Use @image1 as the first frame of the scene.` when relevant |
-| **Continuous shot** | Use `No scene cuts throughout, one continuous shot.` for uninterrupted beats |
+| **First-frame anchor** | Use `Use @Image1 as the first frame of the scene.` when relevant; legacy `@image1` remains accepted |
+| **Continuous shot** | Use `No scene cuts throughout, one continuous shot.` only for uninterrupted beats |
 | **Segmentation** | Use time ranges only for real editorial phases, not decorative micro-beats |
 | **Extension** | Continue source clips with `Extend @video1 by [N]s` |
 
@@ -182,7 +182,7 @@ First sentence carries the most weight. Every prompt MUST follow this order:
 7. [Avoid line] (EVERY prompt — MANDATORY)
 ```
 
-> **Seedance adaptation:** When model is seedance-2.0, start with material-role declarations (`@image1`, `@video1`, `@audio1`) and replace generic action prose with concrete continuity-aware performance/timeline direction.
+> **Seedance adaptation:** When model is seedance-2.0, start with material-role declarations (`@Image1`/`@image1`, `@video1`, `@audio1`) and replace generic action prose with concrete continuity-aware performance/timeline direction.
 > **Kling adaptation:** When model is kling-3.0, replace step 3 (Action) with motion timeline (`first → then → finally`). Step 6 uses Kling tone markers instead of Audio Direction Block. See `.agent/model-profile.md` for golden prompt skeleton.
 
 ## VOICE DESIGN CONTRACT
@@ -289,7 +289,7 @@ Before outputting ANY shot:
 - [ ] Did each storyboard stage earn a distinct editorial job instead of representing micro-gestures?
 
 ### 4. Seedance-Specific Gates (when model is seedance-2.0)
-- [ ] Material roles are explicit when references exist? (`@image1`, `@video1`, `@audio1`)
+- [ ] Material roles are explicit when references exist? (`@Image1`/`@image1`, `@video1`, `@audio1`)
 - [ ] Identity reference, action reference, and camera reference are separated when needed?
 - [ ] First-frame anchor is explicit when required?
 - [ ] Continuous-shot wording is explicit unless phased timing is intentional?

package/content/skills/prompt-structure/SKILL.md

@@ -105,17 +105,19 @@ Avoid: distorted face, outfit drift, prop drift, lens drift, light-direction dri
 Before using any video template in this file:
 - Read `.agent/model-profile.md` and follow the active model contract.
 - If active model is **Kling 3.0**, do **not** default to the Veo-style `Audio direction:` bullet schema below.
-- If active model is **Seedance 2.0**, do **not** default to the Veo-style `Audio direction:` bullet schema below; use multimodal role assignment (`@image1`, `@video1`, `@audio1`) and timeline segmentation when needed.
-- If mode is **storyboard-reference**, do **not** assume first-frame or end-frame assets exist. Use character reference as identity lock and storyboard reference as composition/blocking/timing plan only.
+- If active model is **Seedance 2.0**, do **not** default to the Veo-style `Audio direction:` bullet schema below; use multimodal role assignment (`@Image1`/`@image1`, `@video1`, `@audio1`) and timeline segmentation when needed.
+- If mode is **storyboard-reference**, do **not** assume first-frame or end-frame assets exist. Generate character sheet prompts first, then generate one GPT Image 2 storyboard prompt per shot; character sheets are identity locks and generated shot storyboards are composition/blocking/timing plans only.
 - If project is a hybrid/smart-hybrid package, the local `.agent/skills/prompt-structure/SKILL.md` override takes precedence over this base file.
 
 ## Storyboard-Reference Video Prompt Structure
 
-Use this when the user provides a character reference image, storyboard reference image, and brief:
+Use this when the user provides a character reference image and brief. An external storyboard guide is optional:
 
 ```text
-Use the character reference as the exact identity anchor.
-Use the storyboard reference as the visual planning reference for composition, blocking, camera angle, pacing, and action progression only.
+Generate one 16:9 GPT Image 2 character sheet prompt per character: front, back, left profile, right profile, three-quarter full body, close-up face.
+Generate one 16:9 GPT Image 2 storyboard prompt per shot, 160-240 words, with the duration-aware panel budget.
+Use the generated character sheet as the exact identity anchor.
+Use the generated shot storyboard as the visual planning reference for composition, blocking, camera angle, pacing, and action progression only.
 Do not copy storyboard text, labels, panel borders, watermarks, logos, or alternate character design.
 
 [Core intent from brief]
@@ -576,8 +578,8 @@ Seedance 2.0 responds best when prompt writing behaves like a **multimodal direc
 ### Material Role Patterns
 
 ```text
-Use @image1 as the first frame of the scene.
-Reference character appearance from @image1, but reference camera movement from @video1.
+Use @Image1 as the first frame of the scene.
+Reference character appearance from @Image1, but reference camera movement from @video1.
 Reference character action from @video1, reference circular camera movement from @video2.
 Use @audio1 as background music and tonal rhythm reference.
 Extend @video1 by 5s, keeping the same environment, costume, and lighting continuity.
@@ -586,8 +588,8 @@ Extend @video1 by 5s, keeping the same environment, costume, and lighting contin
 ### Seedance Prompt Skeleton
 
 ```text
-Use @image1 as the first frame of the scene.
-Maintain character appearance exactly consistent with @image1.
+Use @Image1 as the first frame of the scene.
+Maintain character appearance exactly consistent with @Image1.
 Reference camera language from @video1, but do not copy its subject identity.
 Use @audio1 only as ambience / music rhythm reference.
 No scene cuts throughout, one continuous shot.
@@ -619,8 +621,9 @@ No scene cuts throughout, one continuous shot.
 
 ### Seedance Quality Notes
 
-- prefer `Use @image1 as the first frame` when first-frame identity lock matters
-- write `No scene cuts throughout, one continuous shot.` when you want uninterrupted motion
+- prefer `Use @Image1 as the first frame` when first-frame identity lock matters; legacy `@image1` remains accepted in older Film-Kit text
+- write `No scene cuts throughout, one continuous shot.` only when you want uninterrupted motion
+- for storyboard-reference prompts, generated character sheet tokens (`@Image1`, `@Image2`, ...) control identity while the generated shot storyboard token (the next `@Image`) controls composition, blocking, camera direction, timing, and action rhythm only
 - if action and camera references differ, say so explicitly
 - if audio is only a mood reference, say `Use @audio1 only as tonal ambience reference`
 - acting direction should be physical: `hesitates, swallows, tightens grip, glances over shoulder`

package/content/skills/reference-locking/SKILL.md

@@ -55,12 +55,14 @@ Replicate the artistic approach and atmosphere from the reference.
 For `storyboard-reference` mode:
 
 ```text
-Use @character1 as the exact identity reference.
-Use @storyboard1 as the storyboard planning reference for composition, blocking, camera direction, action progression, and visual rhythm only.
-Do not copy text, labels, watermarks, logos, panel borders, or alternate character design from @storyboard1.
+Use @character1 as the exact source reference for a one-time 16:9 GPT Image 2 character sheet.
+Use the generated character sheet token(s) as exact identity references.
+Use the generated shot storyboard token as the storyboard planning reference for composition, blocking, camera direction, action progression, and visual rhythm only.
+Optional @storyboard1 guide images are staging references only.
+Do not copy text, labels, watermarks, logos, panel borders, or alternate character design from any storyboard guide or generated storyboard.
 ```
 
-The storyboard reference never overrides face, hair, body proportions, wardrobe, accessories, or visible props locked by the character reference.
+The storyboard reference never overrides face, hair, body proportions, wardrobe, accessories, or visible props locked by the character reference and generated character sheet.
 
 ---
 

package/content/skills/semantic-consistency/SKILL.md

@@ -13,7 +13,7 @@ It turns semantic realism into a hard production gate instead of a best-effort p
 Every `shot-plan.json` or `team-plan.json` must carry a scene-level `visual_world` block.
 Use it as the canonical source for all shots in the same scene:
 
-In `storyboard-reference` mode, `storyboard-reference-plan.json` and each `SHOTNN.bundle.json` carry the same canonical role: the storyboard image informs camera, phase order, screen direction, and spatial staging only; the character reference remains the immutable identity source.
+In `storyboard-reference` mode, `storyboard-reference-plan.json` and each `SHOTNN.bundle.json` carry the same canonical role: generated character sheets remain the immutable identity source, while generated shot storyboards inform camera, phase order, screen direction, and spatial staging only.
 
 ```json
 {

package/content/skills/storyboard-reference/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: storyboard-reference
-description: Character reference + storyboard image + user brief to model-aware video prompt bundles for Veo 3.1, Seedance 2.0, and Kling 3.0 without requiring start/end frame generation.
+description: Character reference sheet prep + per-shot GPT Image 2 storyboard prompts + model-aware video prompt bundles for Veo 3.1, Seedance 2.0, and Kling 3.0 without requiring start/end frame generation.
 ---
 
 # Storyboard Reference Skill
@@ -9,27 +9,58 @@ description: Character reference + storyboard image + user brief to model-aware
 
 Use this skill when the user provides:
 
-- a character reference image
-- a storyboard reference image
+- one or more character reference images
 - a video brief or scenario text
+- optional external storyboard guide images
 
-The output is a copy-paste-ready prompt bundle for supported video models. This mode does not require ILK FRAME / SON FRAME generation.
+The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. The generated shot storyboard is the staging reference for the final video model prompt.
+
+## Reference Prep
+
+### Character Sheet Prompt
+
+For each character reference, generate this prompt once:
+
+- provider: `gpt-image-2`
+- aspect ratio: `16:9`
+- layout: one widescreen production storyboard sheet
+- required views: front full body, back full body, left profile, right profile, three-quarter full body, close-up face
+- identity lock: exact face, skull shape, hair, skin texture, body proportions, wardrobe, accessories, and visible props
+- forbidden: text, labels, arrows, panel numbers, logos, watermarks, alternate outfits, alternate character designs
+
+This sheet becomes the identity reference for every later shot storyboard.
+
+### Shot Storyboard Prompt
+
+For each shot, generate a professional GPT Image 2 storyboard prompt:
+
+- provider: `gpt-image-2`
+- aspect ratio: `16:9`
+- panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
+- hard cap: max 4 panels/phases per shot unless the configured project cap is lower
+- split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
+- target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
+- storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
+- continuity: include previous shot handoff, next shot handoff, shared `visual_world`, screen direction, lighting, and action rhythm
+
+The shot storyboard prompt must use the character sheet reference as the only identity source. Optional external storyboard guide images may inform composition and timing only.
 
 ## Role Separation
 
-`@character1` is the identity lock.
+Character references and generated character sheets are identity locks.
 
-Use it for face, hair, skin texture, body proportions, wardrobe, accessories, and visible props. Do not use it for camera path, storyboard timing, or background layout.
+Use them for face, hair, skin texture, body proportions, wardrobe, accessories, and visible props. Do not use them for camera path, storyboard timing, or background layout.
 
-`@storyboard1` is the editorial and camera plan.
+The generated shot storyboard is the editorial and camera plan.
 
-Use it for composition, blocking, camera angle, action progression, visual rhythm, and phase order. Do not use it to redesign the character, replace wardrobe, copy panel borders, copy text, copy logos, or import watermark details.
+Use it for composition, blocking, camera angle, action progression, visual rhythm, phase order, and handoff continuity. Do not use it to redesign the character, replace wardrobe, copy panel borders, copy text, copy logos, or import watermark details.
 
 ## Hard Rules
 
 - Character identity always wins over storyboard character design.
 - Storyboard text, labels, watermarks, logos, and panel borders are never copied into the video.
-- One prompt may contain at most 4 storyboard phases.
+- One prompt may contain at most 4 storyboard phases by default.
 - 5+ distinct storyboard phases must be split into multiple `SHOTNN.md` files.
 - Do not assume start/end frame assets exist in `storyboard-reference` mode.
 - Every model output must include an `Avoid` or negative prompt section.
@@ -41,14 +72,22 @@ Use it for composition, blocking, camera angle, action progression, visual rhyth
 
 Seedance 2.0:
 
-- Map `@image1` to character identity.
-- Map `@image2` to storyboard composition/timing.
+- Map character sheet images to `@Image1`, `@Image2`, ... with legacy aliases `@image1`, `@image2`, ...
+- Map the generated shot storyboard to the next image token, for example one character means `@Image2`, two characters means `@Image3`.
+- Character image tokens control identity, face, body proportions, wardrobe, accessories, and visible props.
+- The storyboard token controls composition, blocking, camera direction, timing, action rhythm, and phase order only.
+- Follow generated storyboard panels left-to-right, top-to-bottom. Do not reinterpret the action, pose logic, camera angle, emotional progression, frame variety, or final pose.
+- Treat storyboard arrows, labels, lens notes, and colored marks as planning annotations only; never render them into the video.
 - Use explicit timeline phases when the storyboard has multiple beats.
-- Include `No scene cuts throughout, one continuous shot` for continuous shots.
+- Use `No scene cuts throughout, one continuous shot` only for a true single uninterrupted camera move.
+- For multi-phase storyboard prompts, use only the planned phase transitions and do not add unplanned cuts.
+- Duration policy: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases.
+- Seedance provider limits: max 9 image references, 3 video references, 3 audio references, 12 total files, 4-15 seconds.
+- Storyboard text, panel borders, watermark, logo, and alternate character design are never identity sources.
 
 Veo 3.1:
 
-- Describe the storyboard as a visual planning reference, not a literal frame.
+- Describe the generated storyboard as a visual planning reference, not a literal frame.
 - Include camera, lens/framing, lighting, foreground/midground/background, continuity, and full `Audio direction`.
 - Do not request storyboard panel borders or on-screen text.
 
@@ -63,7 +102,11 @@ Kling 3.0:
 Each shot file contains:
 
 - Turkish summary
+- model control
 - input asset roles
+- reference asset requirements
+- provider reference tokens
+- GPT Image 2 storyboard prompt
 - storyboard interpretation
 - audio plan
 - prompt bundle for requested models
@@ -73,6 +116,8 @@ Generated files:
 
 ```text
 $OUTPUT_DIR/storyboard-reference-plan.json
+$OUTPUT_DIR/reference-prep/CHARACTER-SHEET-*.md
+$OUTPUT_DIR/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md
 $OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json
 $OUTPUT_DIR/shots/SHOTNN.md
 $OUTPUT_DIR/reports/STORYBOARD-REFERENCE-QA.md

package/content/workflows/generate-storyboard.md

@@ -1,5 +1,5 @@
 ---
-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 - Storyboard Reference Video Prompt Mode
@@ -7,8 +7,8 @@ description: Generate storyboard-reference prompt bundles from character referen
 ## Preconditions
 
 - Character reference image exists.
-- Storyboard 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.
 
 ## Read Order
@@ -25,38 +25,48 @@ description: Generate storyboard-reference prompt bundles from character referen
 ## Flow
 
 1. Confirm asset roles:
-   - `@character1`: `character_identity`, exact lock
-   - `@storyboard1`: `storyboard_plan`, staging only
-2. Confirm target models: `veo31`, `seedance-2.0`, `kling-3.0`, or a user-provided subset.
-3. Interpret storyboard panel count:
-   - 1 panel: one continuous action arc
-   - 2-4 panels: internal storyboard phases
-   - 5+ panels: split into multiple `SHOTNN.md` files
-4. Build `visual_world`:
+   - `@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
-5. Build model prompt bundle:
-   - Seedance role-separated `@image1` / `@image2` prompt
+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
-6. Run QA gates:
+8. Run QA gates:
    - reference lock
    - storyboard role separation
    - model grammar
    - avoid/negative prompt
    - audio plan
    - safety
-7. Write outputs under `$OUTPUT_DIR`.
+9. Write outputs under `$OUTPUT_DIR`.
 
 ## CLI Equivalent
 
 ```bash
 npx @milenyumai/film-kit generate-storyboard \
   --character-ref ./refs/character.png \
-  --storyboard-ref ./refs/storyboard.png \
   --brief ./scenario.md \
   --models veo31,seedance-2.0,kling-3.0 \
   --duration 8 \
@@ -64,12 +74,23 @@ npx @milenyumai/film-kit generate-storyboard \
   --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.
-- Missing storyboard 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/content/workflows/generate.md

@@ -153,14 +153,14 @@ Before writing prompts, design the Start→End transition:
 
 Before writing prompts, lock the multimodal control plan:
 
-1.  **Reference roles:** State which material controls identity, action, camera, and audio (`@image1`, `@video1`, `@video2`, `@audio1`).
-2.  **First-frame anchor:** If an image reference exists, start with `Use @image1 as the first frame of the scene.`
-3.  **Continuity mode:** Default to `No scene cuts throughout, one continuous shot.` unless the beat genuinely requires internal timeline segmentation.
+1.  **Reference roles:** State which material controls identity, action, camera, and audio (`@Image1`/`@image1`, `@video1`, `@video2`, `@audio1`).
+2.  **First-frame anchor:** If an image reference exists, start with `Use @Image1 as the first frame of the scene.`
+3.  **Continuity mode:** Use `No scene cuts throughout, one continuous shot.` only when the beat is genuinely uninterrupted; planned storyboard phase changes must be named instead.
 4.  **Timeline clarity:** For longer or more complex shots, split the action into explicit time ranges with one editorial job per phase.
 5.  **Reference separation:** If action and camera references come from different materials, say so explicitly.
 6.  **Performance realism:** Use concrete physical acting cues, not vague emotional labels.
 7.  **Extension mode:** When continuing from an existing clip, use `Extend @video1 by [N]s, ...` instead of rewriting the whole scene as a fresh cut.
-8.  **Identity lock:** When `@image1` defines identity, do not rewrite face/body/wardrobe design in prose; keep the same person/object exactly as reference and change only one meaningful beat.
+8.  **Identity lock:** When `@Image1` / `@image1` defines identity, do not rewrite face/body/wardrobe design in prose; keep the same person/object exactly as reference and change only one meaningful beat.
 
 #### Veo Gate (when model is veo31)
 
@@ -185,10 +185,10 @@ Before writing prompts, lock the multimodal control plan:
 
 #### Seedance Gate (when model is seedance-2.0)
 
-- [ ] Prompt declares material roles explicitly when references exist (`@image1`, `@video1`, `@audio1`)
+- [ ] Prompt declares material roles explicitly when references exist (`@Image1`/`@image1`, `@video1`, `@audio1`)
 - [ ] Identity reference, action reference, and camera reference are separated when they come from different inputs
-- [ ] `Use @image1 as the first frame of the scene.` appears when first-frame anchoring is needed
-- [ ] `No scene cuts throughout, one continuous shot.` is used for uninterrupted beats
+- [ ] `Use @Image1 as the first frame of the scene.` appears when first-frame anchoring is needed
+- [ ] `No scene cuts throughout, one continuous shot.` is used only for uninterrupted beats
 - [ ] Timeline segmentation is used only when the beat has meaningful internal phases
 - [ ] Extension syntax is used when continuing a prior clip (`Extend @video1 by ...`)
 - [ ] Acting direction is expressed with concrete body/performance cues, not vague labels

package/content/workflows/safety-check.md

@@ -78,9 +78,9 @@ Validate all prompts before delivery to ensure platform compliance.
 - prompt includes `stable background` and `no warping` constraints
 
 7. Seedance-only checks (when model is `seedance-2.0`)
-- reference roles are explicit when materials are used (`@image1`, `@video1`, `@audio1`)
+- reference roles are explicit when materials are used (`@Image1`/`@image1`, `@video1`, `@audio1`)
 - prompt separates identity reference from camera/action reference when needed
-- continuous shots explicitly say `No scene cuts throughout, one continuous shot.` unless segmented timing is justified
+- continuous shots explicitly say `No scene cuts throughout, one continuous shot.` only when uninterrupted; segmented timing/storyboard phases do not force no-cuts wording
 - segmented timing, if used, assigns a meaningful job to each phase instead of decorative micro-beats
 - extension prompts use `Extend @video1 by [N]s` syntax when continuing a source clip
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milenyumai/film-kit",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "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",