@milenyumai/film-kit 2.2.1 → 2.3.1

package/packages/gpt-image-smart/content/skills/storyboard-reference/SKILL.md

@@ -1,28 +1,124 @@
 ---
 name: storyboard-reference
-description: Character reference + storyboard image + brief to model-aware video prompt bundles without requiring start/end frames.
+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
 
-Use when the user provides a character reference, storyboard reference, and video brief.
+## Purpose
+
+Use this skill when the user provides:
+
+- one or more character reference images
+- a video brief or scenario text
+- optional external storyboard guide images
+
+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`: exact identity lock for face, hair, body proportions, wardrobe, accessories, and visible props.
-- `@storyboard1`: composition, blocking, camera angle, action progression, visual rhythm, and phase order only.
+Character references and generated character sheets are identity locks.
+
+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.
+
+The generated shot storyboard is the editorial and camera plan.
+
+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.
-- Do not copy storyboard text, logos, watermarks, labels, or panel borders.
-- One prompt may contain at most 4 storyboard phases.
-- 5+ distinct phases must split into multiple `SHOTNN.md` files.
-- Do not require ILK FRAME / SON FRAME assets in `storyboard-reference` mode.
-- Every model prompt needs `Avoid` or negative prompt coverage.
-- Dialogue stays in the user's original language.
-- Music is `NONE` unless explicitly requested.
+- Storyboard text, labels, watermarks, logos, and panel borders are never copied into the video.
+- 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.
+- Dialogue remains in the user's original language.
+- Music is `NONE` unless the user explicitly asks for music.
+- Fail closed on public figure, real-person likeness, trademark/logo, or unsafe visual requests.
+
+## Model Grammar
+
+Seedance 2.0:
+
+- 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.
+- 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 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.
+
+Kling 3.0:
+
+- Prompt code block starts with `[CHARACTER / SUBJECT CONSISTENCY]`.
+- Include `[CORE INTENT]`, `[TOTAL DURATION]`, `[VISUAL STYLE]`, `[CAMERA]`, `[SHOT N | time range]`, `[AUDIO]`, `[TIMING RULES]`, `[BACKGROUND RULES]`, `[FINAL FRAME PRIORITY]`, and `[NEGATIVE PROMPT]`.
+- Use `resolved storyboard composition`, not `final frame exactly`, when no end frame exists.
 
 ## Output Contract
 
-Write `$OUTPUT_DIR/storyboard-reference-plan.json`, `$OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json`, `$OUTPUT_DIR/shots/SHOTNN.md`, and `$OUTPUT_DIR/reports/STORYBOARD-REFERENCE-QA.md`.
+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
+- QA verdict
+
+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/packages/gpt-image-smart/content/workflows/generate-storyboard.md

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

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

@@ -1,28 +1,124 @@
 ---
 name: storyboard-reference
-description: Character reference + storyboard image + brief to model-aware video prompt bundles without requiring start/end frames.
+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
 
-Use when the user provides a character reference, storyboard reference, and video brief.
+## Purpose
+
+Use this skill when the user provides:
+
+- one or more character reference images
+- a video brief or scenario text
+- optional external storyboard guide images
+
+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`: exact identity lock for face, hair, body proportions, wardrobe, accessories, and visible props.
-- `@storyboard1`: composition, blocking, camera angle, action progression, visual rhythm, and phase order only.
+Character references and generated character sheets are identity locks.
+
+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.
+
+The generated shot storyboard is the editorial and camera plan.
+
+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.
-- Do not copy storyboard text, logos, watermarks, labels, or panel borders.
-- One prompt may contain at most 4 storyboard phases.
-- 5+ distinct phases must split into multiple `SHOTNN.md` files.
-- Do not require ILK FRAME / SON FRAME assets in `storyboard-reference` mode.
-- Every model prompt needs `Avoid` or negative prompt coverage.
-- Dialogue stays in the user's original language.
-- Music is `NONE` unless explicitly requested.
+- Storyboard text, labels, watermarks, logos, and panel borders are never copied into the video.
+- 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.
+- Dialogue remains in the user's original language.
+- Music is `NONE` unless the user explicitly asks for music.
+- Fail closed on public figure, real-person likeness, trademark/logo, or unsafe visual requests.
+
+## Model Grammar
+
+Seedance 2.0:
+
+- 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.
+- 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 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.
+
+Kling 3.0:
+
+- Prompt code block starts with `[CHARACTER / SUBJECT CONSISTENCY]`.
+- Include `[CORE INTENT]`, `[TOTAL DURATION]`, `[VISUAL STYLE]`, `[CAMERA]`, `[SHOT N | time range]`, `[AUDIO]`, `[TIMING RULES]`, `[BACKGROUND RULES]`, `[FINAL FRAME PRIORITY]`, and `[NEGATIVE PROMPT]`.
+- Use `resolved storyboard composition`, not `final frame exactly`, when no end frame exists.
 
 ## Output Contract
 
-Write `$OUTPUT_DIR/storyboard-reference-plan.json`, `$OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json`, `$OUTPUT_DIR/shots/SHOTNN.md`, and `$OUTPUT_DIR/reports/STORYBOARD-REFERENCE-QA.md`.
+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
+- QA verdict
+
+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/packages/hybrid/content/workflows/generate-storyboard.md

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

package/packages/hybrid-smart/content/skills/storyboard-reference/SKILL.md

@@ -1,28 +1,124 @@
 ---
 name: storyboard-reference
-description: Character reference + storyboard image + brief to model-aware video prompt bundles without requiring start/end frames.
+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
 
-Use when the user provides a character reference, storyboard reference, and video brief.
+## Purpose
+
+Use this skill when the user provides:
+
+- one or more character reference images
+- a video brief or scenario text
+- optional external storyboard guide images
+
+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`: exact identity lock for face, hair, body proportions, wardrobe, accessories, and visible props.
-- `@storyboard1`: composition, blocking, camera angle, action progression, visual rhythm, and phase order only.
+Character references and generated character sheets are identity locks.
+
+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.
+
+The generated shot storyboard is the editorial and camera plan.
+
+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.
-- Do not copy storyboard text, logos, watermarks, labels, or panel borders.
-- One prompt may contain at most 4 storyboard phases.
-- 5+ distinct phases must split into multiple `SHOTNN.md` files.
-- Do not require ILK FRAME / SON FRAME assets in `storyboard-reference` mode.
-- Every model prompt needs `Avoid` or negative prompt coverage.
-- Dialogue stays in the user's original language.
-- Music is `NONE` unless explicitly requested.
+- Storyboard text, labels, watermarks, logos, and panel borders are never copied into the video.
+- 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.
+- Dialogue remains in the user's original language.
+- Music is `NONE` unless the user explicitly asks for music.
+- Fail closed on public figure, real-person likeness, trademark/logo, or unsafe visual requests.
+
+## Model Grammar
+
+Seedance 2.0:
+
+- 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.
+- 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 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.
+
+Kling 3.0:
+
+- Prompt code block starts with `[CHARACTER / SUBJECT CONSISTENCY]`.
+- Include `[CORE INTENT]`, `[TOTAL DURATION]`, `[VISUAL STYLE]`, `[CAMERA]`, `[SHOT N | time range]`, `[AUDIO]`, `[TIMING RULES]`, `[BACKGROUND RULES]`, `[FINAL FRAME PRIORITY]`, and `[NEGATIVE PROMPT]`.
+- Use `resolved storyboard composition`, not `final frame exactly`, when no end frame exists.
 
 ## Output Contract
 
-Write `$OUTPUT_DIR/storyboard-reference-plan.json`, `$OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json`, `$OUTPUT_DIR/shots/SHOTNN.md`, and `$OUTPUT_DIR/reports/STORYBOARD-REFERENCE-QA.md`.
+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
+- QA verdict
+
+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
+```