@milenyumai/film-kit 2.3.5 → 2.3.7

package/README.md

@@ -126,6 +126,109 @@ When the active model is not Kling, generated runtime files intentionally render
 
 Use this mode when the source material is a character reference image plus a brief rather than explicit start/end frames. Film-Kit first prepares character-sheet prompts, then per-shot storyboard prompts. Optional storyboard images can be supplied as loose composition/timing guides.
 
+### Storyboard Mode Setup For Supported Tools
+
+Storyboard-reference mode is installed from the same canonical package for every tool:
+
+```bash
+npm install --save-dev @milenyumai/film-kit
+```
+
+You can also skip local install and use package-direct `npx` commands. Do not install or run old standalone preset package names.
+
+Create your input files first:
+
+```bash
+mkdir -p refs
+# Put the exact character identity image here:
+# refs/character.png
+#
+# Put the video brief here:
+# scenario.md
+```
+
+Install the storyboard runtime for all supported tools at once:
+
+```bash
+npx @milenyumai/film-kit init \
+  --preset single \
+  --model seedance-2.0 \
+  --reference-mode storyboard-reference \
+  --platforms codex,claude,cursor,copilot,antigravity \
+  --max-storyboard-phases 4
+```
+
+Supported tool-specific setup commands:
+
+| Tool | Setup command | Main files created |
+|---|---|---|
+| OpenAI Codex App | `npx @milenyumai/film-kit init --preset single --model seedance-2.0 --reference-mode storyboard-reference --platforms codex --max-storyboard-phases 4` | `AGENTS.md`, `.codex/config.toml`, `.codex/agents/*.toml`, `.agents/skills/storyboard-reference/SKILL.md` |
+| Claude Code | `npx @milenyumai/film-kit init --preset single --model seedance-2.0 --reference-mode storyboard-reference --platforms claude --max-storyboard-phases 4` | `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*`, `.claude/agents/prompt-engineer.md` |
+| Cursor | `npx @milenyumai/film-kit init --preset single --model seedance-2.0 --reference-mode storyboard-reference --platforms cursor --max-storyboard-phases 4` | `.cursorrules`, `.cursor/rules/global.mdc`, `.agent/workflows/generate-storyboard.md` |
+| GitHub Copilot | `npx @milenyumai/film-kit init --preset single --model seedance-2.0 --reference-mode storyboard-reference --platforms copilot --max-storyboard-phases 4` | `.github/copilot-instructions.md`, `.github/instructions/shotforge.instructions.md` |
+| Antigravity | `npx @milenyumai/film-kit init --preset single --model seedance-2.0 --reference-mode storyboard-reference --platforms antigravity --max-storyboard-phases 4` | `.agent/skills/shotforge-generate/SKILL.md`, `.agent/workflows/generate-storyboard.md`, `.agent/skills/storyboard-reference/SKILL.md` |
+
+For a studio-style project with refs and render-stage metadata, use `studio` instead:
+
+```bash
+npx @milenyumai/film-kit init \
+  --preset studio \
+  --model seedance-2.0 \
+  --reference-mode storyboard-reference \
+  --platforms codex,claude,cursor,copilot,antigravity \
+  --refs-dir ./refs \
+  --gpt-image-size 2048x1152 \
+  --gpt-image-quality medium \
+  --gpt-image-format png \
+  --max-storyboard-phases 4
+```
+
+After setup, open the Git project root in your tool. Use this as the first prompt in Codex, Claude Code, Cursor, Copilot Chat, or Antigravity:
+
+```text
+Read the Film-Kit storyboard-reference instructions in AGENTS.md and .agent/workflows/generate-storyboard.md.
+
+Use refs/character.png as the exact character identity reference.
+Use scenario.md as the video brief.
+Target model: seedance-2.0.
+Duration: 15 seconds.
+Aspect ratio: 16:9.
+
+Generate the storyboard-reference package only:
+- one GPT Image 2 character sheet prompt
+- one 12-panel raw-pencil GPT Image 2 storyboard prompt
+- one Seedance 2.0 video prompt that uses the generated storyboard as @Image2
+- outputs/storyboard-prompt.md
+- outputs/storyboard-prompts/SHOT01-GPT-IMAGE-2-STORYBOARD.md
+- outputs/prompt-bundles/SHOT01.bundle.json
+- outputs/shots/SHOT01.md
+- outputs/reports/STORYBOARD-REFERENCE-QA.md
+
+Do not create ILK FRAME, İLK FRAME, SON FRAME, SHOT_START, or SHOT_END sections.
+Do not render images or video yet; first produce and QA the prompt package.
+```
+
+If your tool supports slash-style workflow prompts, this shorter first prompt is also valid:
+
+```text
+/generate
+Storyboard-reference mode. Character reference: refs/character.png. Brief: scenario.md. Model: seedance-2.0. Duration: 15s. Aspect: 16:9. Generate the 12-panel raw-pencil storyboard prompt and Seedance video prompt package only. No ILK/SON frames. No rendering yet.
+```
+
+Terminal-only generation is available when you want the package files without opening an agent tool:
+
+```bash
+npx @milenyumai/film-kit generate-storyboard \
+  --character-ref ./refs/character.png \
+  --brief ./scenario.md \
+  --models seedance-2.0 \
+  --duration 15 \
+  --aspect 16:9 \
+  --output-dir ./outputs
+```
+
+After the command finishes, start with `outputs/storyboard-prompt.md`. It is the ready-to-use GPT Image 2 storyboard image prompt. Then use `outputs/shots/SHOT01.md` or `outputs/prompt-bundles/SHOT01.bundle.json` for the Seedance 2.0 prompt.
+
 Initialize a Seedance storyboard-reference runtime:
 
 ```bash
@@ -198,9 +301,10 @@ Rules:
 - GPT Image 2 still prompts use `REFERENCE LOCK`, `Keep same`, `Change only`, and `Avoid` sections so character identity, wardrobe, props, and materials stay immutable unless explicitly changed.
 - Each `SHOTNN.md` includes a professional `GPT IMAGE 2 STORYBOARD PROMPT`; the generated shot storyboard controls composition, blocking, camera, timing, and editorial phase order only.
 - If no external storyboard image exists, Film-Kit still generates the GPT Image 2 storyboard bootstrap prompt and writes it to both `outputs/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md` and the convenience alias `outputs/storyboard-prompt.md`.
-- Storyboard prompts use production-board grammar: 16:9 storyboard sheet, rough black-and-white pencil panels, strong silhouettes, visible body/camera momentum, cinematic camera variety, and optional color-coded planning annotations. Seedance is instructed to follow the panel order while ignoring arrows, notes, labels, and timestamps in the rendered video.
+- Storyboard prompts default to a 12-panel 16:9 production-board sheet: white paper, rough black-and-white pencil drawings, strong silhouettes, visible body/camera momentum, cinematic camera variety, and color-coded planning annotations only. Hard negatives block photorealistic stills, full-color rendered panels, concept-art strips, CGI, anime, and polished illustration.
+- Seedance treats the generated storyboard token as the complete visual/action/camera/choreography source, follows all beats left-to-right/top-to-bottom, and ignores arrows, labels, notes, page headers, timestamps, panel borders, and other annotations in the rendered video.
 - Seedance provider-facing tokens map generated character sheets first (`@Image1`, `@Image2`, ...) and the generated shot storyboard next. Legacy lowercase aliases remain documented in runtime text.
-- `SHOTNN.bundle.json` includes `storyboard_creation` metadata with provider, prompt path, alias path, reading order, panel count, Seedance token, annotation policy, and prompt text.
+- `SHOTNN.bundle.json` includes `storyboard_creation` metadata with provider, prompt path, alias path, style contract, default panel count, reading order, panel count, forbidden visual modes, Seedance token, annotation policy, and prompt text.
 - Speaking shots must bind `Audio Plan.activeSpeakerKey` back to project-level `voiceCast`; broken voice bindings fail QA.
 - Public-figure, celebrity, likeness, logo, trademark, or brand references in the brief, dialogue metadata, or reference metadata are blocked unless safely anonymized first.
 - Phase budget: 4-6s uses 1-2 phases, 7-10s uses 2-3 phases, and 11-15s uses 3-4 phases.
@@ -219,7 +323,7 @@ CLI flags for direct storyboard bundle generation:
 | `--models` | Comma-separated target models: `veo31`, `seedance-2.0`, `kling-3.0` |
 | `--duration` | Duration in seconds per generated shot. Seedance provider range is 4-15 seconds |
 | `--aspect` | `16:9`, `9:16`, or `1:1` |
-| `--storyboard-panel-count-hint` | Optional GPT Image 2 storyboard sheet panel count, `1-12`. This does not by itself split SHOT files |
+| `--storyboard-panel-count-hint` | Optional GPT Image 2 storyboard sheet panel count, `1-12`. Default: `12`. This does not by itself split SHOT files |
 | `--max-storyboard-phases` | Upper bound per shot. Default: `4` |
 
 ## CLI

package/build/lib/storyboard-reference/adapters/seedance20.d.ts

@@ -10,6 +10,7 @@ export declare class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter
     private getMappingEntries;
     private formatCharacterRoleLine;
     private formatStoryboardRoleLine;
+    private hasDanceOrSingingIntent;
     buildPrompt(input: AdapterInput): ModelPromptOutput;
     validate(output: ModelPromptOutput): ModelPromptQa;
 }

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

@@ -40,24 +40,37 @@ export class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter {
         const storyboardEntry = this.getMappingEntries(input, "storyboard_plan")[0];
         const token = storyboardEntry?.token ?? "@Image2";
         const alias = storyboardEntry?.legacyAlias;
-        return `Use ${token} as the shot storyboard reference for composition, blocking, camera direction, timing, action rhythm, and phase order only. Do not copy storyboard text, labels, panel borders, watermarks, logos, or alternate character design from ${token}.${alias ? ` Legacy alias: ${alias}.` : ""}`;
+        return `Use ${token} as the shot storyboard reference and generated storyboard reference image: the complete visual/action/camera/choreography source for beat order, composition, blocking, camera direction, timing, action rhythm, framing variety, and final pose only. Do not copy storyboard text, labels, notes, arrows, panel borders, page headers, watermarks, logos, or alternate character design from ${token}.${alias ? ` Legacy alias: ${alias}.` : ""}`;
+    }
+    hasDanceOrSingingIntent(input) {
+        const combined = [
+            input.request.brief,
+            input.request.audioIntent,
+            input.request.styleIntent,
+            ...input.request.dialogue.map(line => `${line.speaker}: ${line.text}`)
+        ].join(" ").toLowerCase();
+        return /dance|dancing|choreograph|sing|singing|song|vocal|sarki|sark|soyl|dans/.test(combined);
     }
     buildPrompt(input) {
         const audioPlan = buildAudioPlan(input);
         const storyboardEntry = this.getMappingEntries(input, "storyboard_plan")[0];
         const storyboardToken = storyboardEntry?.token ?? "@Image2";
         const continuityInstruction = input.continuityMode === "continuous-shot"
-            ? `Use the generated storyboard reference ${storyboardToken} as the complete visual, action, camera, and choreography source for this ${input.request.durationSeconds}-second video. Follow the single storyboard beat exactly. No scene cuts throughout, one continuous shot.`
-            : `Use the generated storyboard reference ${storyboardToken} as the complete visual, action, camera, and choreography source for this ${input.request.durationSeconds}-second video. Follow all ${input.storyboardImagePrompt.panelCount} beats sequentially from left-to-right, top-to-bottom as the exact visual beat order. Do not reinterpret actions, poses, camera angles, emotional progression, frame variety, movement logic, shot order, or the final pose. Compress the full ${input.storyboardImagePrompt.panelCount}-beat sequence into the full duration as fast readable motion snapshots, not full-length actions. Use urgent rhythm, storyboard-motivated cuts, quick cuts, match cuts, whip transitions, or motivated camera moves only when the storyboard supports them. Do not add unplanned cuts, extra scene jumps, duplicate performers, or new locations.`;
+            ? `Use the generated storyboard reference ${storyboardToken} as the complete visual/action/camera/choreography source for this ${input.request.durationSeconds}-second video. Follow all ${input.storyboardImagePrompt.panelCount} beats sequentially from left-to-right, top-to-bottom as the exact visual beat order within one uninterrupted camera move. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose. Compress the full ${input.storyboardImagePrompt.panelCount}-beat sequence into the requested duration as fast readable motion snapshots, not full-length actions. No scene cuts throughout, one continuous shot.`
+            : `Use the generated storyboard reference ${storyboardToken} as the complete visual/action/camera/choreography source for this ${input.request.durationSeconds}-second video. Follow all ${input.storyboardImagePrompt.panelCount} beats sequentially from left-to-right, top-to-bottom as the exact visual beat order. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose. Compress the full ${input.storyboardImagePrompt.panelCount}-beat sequence into the requested duration as fast readable motion snapshots, not full-length actions. Use urgent rhythm, storyboard-motivated cuts, quick cuts, match cuts, whip transitions, or motivated camera moves only when the storyboard supports them. Do not add unplanned cuts, extra scene jumps, duplicate performers, or new locations.`;
         const characterEntries = this.getMappingEntries(input, "character_identity");
         const characterTokenText = characterEntries.map(entry => entry.token).join(", ") || "@Image1";
+        const performanceEmphasis = this.hasDanceOrSingingIntent(input)
+            ? "\nFor singing or dance briefs: continuous live singing must show visible breath, synchronized mouth movement, body strain, fabric motion, grounded footwork, floor contact, and phrase-level physical effort across the full movement."
+            : "";
         const promptText = `${this.formatCharacterRoleLine(input)}
 ${this.formatStoryboardRoleLine(input)}
 
 [REFERENCE ROLES]
 - Identity reference: ${characterTokenText} locks face, hair, body proportions, wardrobe, accessories, visible props, and material continuity.
-- Camera reference: ${storyboardToken} controls composition, camera direction, framing, screen direction, shot order, and lens rhythm only.
-- Action reference: ${storyboardToken} controls blocking, pose logic, timing, action rhythm, phase order, and emotional progression only.
+- Storyboard reference image: ${storyboardToken} is the complete visual/action/camera/choreography source.
+- Camera reference: ${storyboardToken} controls composition, camera direction, framing, screen direction, shot order, framing variety, and lens rhythm only.
+- Action reference: ${storyboardToken} controls blocking, pose logic, timing, action rhythm, phase order, choreography, and emotional progression only.
 - Audio reference: use the Audio Plan text below for dialogue, SFX, ambience, and music intent; do not infer audio from storyboard annotations unless explicitly requested.
 
 ${continuityInstruction}
@@ -69,13 +82,13 @@ ${input.request.brief}
 ${formatPhaseLines(input.interpretation.phases)}
 
 [GPT IMAGE 2 STORYBOARD SOURCE]
-Use the generated storyboard image from ${input.storyboardImagePrompt.outputPath} as ${storyboardToken}. It has ${input.storyboardImagePrompt.panelCount} panel(s), follows the shot handoff, and is not an identity source. Treat colored arrows, panel labels, lens notes, and framing marks as planning annotations only; never render arrows, annotation marks, notes, labels, timestamps, panel borders, or storyboard text into the video.
+Use the generated storyboard image from ${input.storyboardImagePrompt.outputPath} as ${storyboardToken}. It has ${input.storyboardImagePrompt.panelCount} panel(s), follows the shot handoff, and is not an identity source. Treat colored arrows, panel labels, lens notes, framing marks, and page headers as planning annotations only; never render storyboard annotations, arrows, labels, notes, timestamps, page headers, panel borders, or storyboard text into the video.
 
 [CAMERA]
 ${input.interpretation.cameraPlan.framing}, ${input.interpretation.cameraPlan.movement}, ${input.interpretation.cameraPlan.lens}, ${input.interpretation.cameraPlan.stabilization}. Preserve ${input.interpretation.cameraPlan.screenDirection}.
 
 [PERFORMANCE]
-Keep the same performer identity from ${characterTokenText}; do not duplicate the character. Visible performance must include breath, mouth movement when dialogue or singing is present, body strain, fabric motion, floor or prop contact, and emotional escalation while preserving exact identity. Acting stays concrete and physically grounded: gaze, breathing, posture, hand behavior, and facial tension evolve from the brief without changing wardrobe or body design.
+Keep the same performer identity from ${characterTokenText}; do not duplicate the character. Visible performance must include breath, mouth movement when dialogue or singing is present, body strain, fabric motion, floor or prop contact, and emotional escalation while preserving exact identity. Acting stays concrete and physically grounded: gaze, breathing, posture, hand behavior, and facial tension evolve from the brief without changing wardrobe or body design.${performanceEmphasis}
 
 [AUDIO]
 Dialogue: ${buildDialogueTranscript(input)}.
@@ -84,9 +97,9 @@ Ambience: ${audioPlan.ambience.join(", ")}.
 Music: NONE.
 
 [CONTINUITY]
-Identity reference stays locked to ${characterTokenText}. Storyboard ${storyboardToken} controls staging, shot order, pose logic, camera variety, emotional progression, and visual rhythm only. Character design, wardrobe, accessories, and visible props cannot be inherited from the storyboard. Storyboard text, panel borders, arrows, colored marks, lens notes, watermark, logo, and alternate character design are never identity sources and must not appear in the rendered video.
+Identity reference stays locked to ${characterTokenText}. Storyboard ${storyboardToken} controls staging, shot order, pose logic, camera variety, framing variety, emotional progression, choreography, final pose, and visual rhythm only. Character design, wardrobe, accessories, and visible props cannot be inherited from the storyboard. Storyboard text, panel borders, arrows, colored marks, lens notes, page headers, watermark, logo, and alternate character design are never identity sources and must not appear in the rendered video.
 
-Avoid: identity drift, face drift, outfit drift, duplicated performer, storyboard text, annotations, panel borders, colored arrows, annotation marks, lens notes, timestamps, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps. No text, no annotations, no timestamps, no watermark.`;
+Avoid: identity drift, face drift, outfit drift, duplicated performer, storyboard text, annotations, panel borders, colored arrows, annotation marks, lens notes, labels, notes, page headers, timestamps, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps. No text, no annotations, no labels, no notes, no timestamps, no page headers, no watermark.`;
         const output = {
             model: this.model,
             displayName: getDisplayName(this.model),
@@ -123,13 +136,16 @@ Avoid: identity drift, face drift, outfit drift, duplicated performer, storyboar
             usesStoryboardToken: output.promptText.includes(storyboardToken) && /shot storyboard reference/i.test(output.promptText),
             followsStoryboardOrder: continuityMode === "continuous-shot"
                 ? hasNoCutsRule
+                    && /Follow all \d+ beats sequentially from left-to-right, top-to-bottom/i.test(output.promptText)
+                    && /Do not reinterpret pose, action, camera angle, emotional progression/i.test(output.promptText)
                 : /left-to-right, top-to-bottom/i.test(output.promptText)
-                    && /Do not reinterpret actions, poses, camera angles, emotional progression/i.test(output.promptText),
+                    && /Do not reinterpret pose, action, camera angle, emotional progression/i.test(output.promptText),
             separatesReferenceRoles: /Identity reference:/i.test(output.promptText)
+                && /Storyboard reference image:/i.test(output.promptText)
                 && /Camera reference:/i.test(output.promptText)
                 && /Action reference:/i.test(output.promptText)
                 && /Audio reference:/i.test(output.promptText),
-            blocksStoryboardIdentitySources: /Storyboard text, panel borders, arrows, colored marks, lens notes, watermark, logo, and alternate character design are never identity sources/i.test(output.promptText),
+            blocksStoryboardIdentitySources: /Storyboard text, panel borders, arrows, colored marks, lens notes, page headers, watermark, logo, and alternate character design are never identity sources/i.test(output.promptText),
             continuityMode: continuityMode === "continuous-shot"
                 ? hasNoCutsRule
                 : !hasNoCutsRule && /storyboard-motivated cuts/i.test(output.promptText),

package/build/lib/storyboard-reference/prompt-bundle-builder.js

@@ -43,8 +43,9 @@ function resolvePromptAdapter(model) {
     return adapter;
 }
 const MAX_STORYBOARD_SHEET_PANELS = 12;
-function getStoryboardSheetPanelCount(request, phaseBudget) {
-    const panelCount = request.storyboardPanelCountHint ?? phaseBudget.recommendedMaxPhases;
+const DEFAULT_STORYBOARD_SHEET_PANELS = 12;
+function getStoryboardSheetPanelCount(request) {
+    const panelCount = request.storyboardPanelCountHint ?? DEFAULT_STORYBOARD_SHEET_PANELS;
     if (panelCount > MAX_STORYBOARD_SHEET_PANELS) {
         throw new Error(`Invalid storyboardPanelCountHint. Expected 1-${MAX_STORYBOARD_SHEET_PANELS} panels for one GPT Image 2 storyboard sheet.`);
     }
@@ -180,8 +181,11 @@ function buildStoryboardImagePrompt(input) {
     const phaseDirection = interpretation.phases
         .map(phase => `Phase ${phase.index}: ${phase.job}; ${phase.subjectAction}; camera behavior: ${phase.cameraBehavior}; background behavior: ${phase.backgroundBehavior}.`)
         .join(" ");
+    const panelLabel = input.storyboardSheetPanelCount === 1
+        ? "1 cinematic panel"
+        : `${input.storyboardSheetPanelCount} cinematic panels`;
     const continuityStyle = interpretation.phases.length <= 1
-        ? "Because this is a single uninterrupted beat, show one decisive action moment with a clear entry pose, motion direction, and final body intention inside the same panel."
+        ? `Because this is a single uninterrupted beat, still create ${panelLabel} as sequential motion snapshots of one continuous camera move. Each panel must clarify entry pose, motion direction, body mechanics, camera shift, and final body intention without implying separate scenes.`
         : `Read panels left-to-right, top-to-bottom as a planned visual beat sequence. Create ${input.storyboardSheetPanelCount} distinct beat snapshot${input.storyboardSheetPanelCount === 1 ? "" : "s"} distributed across the video phases. Each panel must show a distinct body pose, camera size/angle, movement logic, and emotional escalation, not decorative micro-poses.`;
     return {
         shotId,
@@ -189,18 +193,24 @@ function buildStoryboardImagePrompt(input) {
         provider: "gpt-image-2",
         aspectRatio: "16:9",
         panelCount: input.storyboardSheetPanelCount,
-        style: "professional-production-storyboard",
+        style: "raw-pencil-production-storyboard",
         characterSheetIds,
         externalStoryboardGuideIds,
         previousShotHandoff: input.previousShotHandoff,
         nextShotHandoff: input.nextShotHandoff,
-        promptText: `REFERENCE LOCK: Use the generated character sheet reference${characterReferenceSheetPrompts.length === 1 ? "" : "s"} (${sheetRefs}) as the only source for character identity, face, hair, skin texture, body proportions, wardrobe, accessories, material behavior, and visible props.
+        promptText: `HARD NEGATIVE STORYBOARD STYLE LOCK:
+Do not create photorealistic cinematic stills.
+Do not create full-color rendered panels.
+Do not create concept art, movie frames, underwater/color-grade panels, 3D render, anime, CGI, or polished illustration.
+Only annotation arrows/marks may use color; all storyboard artwork remains black pencil on white paper.
+
+REFERENCE LOCK: Use the generated character sheet reference${characterReferenceSheetPrompts.length === 1 ? "" : "s"} (${sheetRefs}) as the only source for character identity, face, hair, skin texture, body proportions, wardrobe, accessories, material behavior, and visible props.
 
 Keep same: every character identity detail from the character sheet${characterReferenceSheetPrompts.length === 1 ? "" : "s"}, the declared visual world, screen direction, environmental continuity, lighting direction, prop continuity, and shot handoff logic. Storyboard text, arrows, labels, panel borders, watermarks, logos, and alternate character designs are never identity sources.
 
-Change only: create a raw cinematic storyboard sheet for ${shotId}. 16:9 storyboard sheet, exactly ${input.storyboardSheetPanelCount} cinematic panel${input.storyboardSheetPanelCount === 1 ? "" : "s"}. The storyboard controls composition, blocking, camera direction, timing, phase order, action rhythm, and emotional progression only. ${externalGuideText}
+Change only: Create a raw ${shotId} storyboard focused on intense physical movement and clear cinematic action from this scene: ${request.brief}. White paper production layout. 16:9 storyboard sheet, ${panelLabel}. Use exactly ${panelLabel}. The storyboard controls composition, blocking, camera direction, timing, phase order, action rhythm, and emotional progression only. ${externalGuideText}
 
-Storyboard drawing style: raw contemporary film storyboard with black-and-white rough pencil linework. The actual storyboard drawings must be black-and-white only: rough pencil lines, minimal detail, fast gesture drawing energy, simple anatomy construction, strong silhouette readability, lightweight unfinished choreography previs, not polished concept art or final render.
+Storyboard drawing style: raw contemporary production storyboard with black-and-white rough pencil linework. Actual storyboard drawings must be black and white only. Use rough pencil lines, minimal detail, fast gesture drawing energy, simple anatomy construction, strong silhouette readability, lightweight unfinished choreography previs, not polished concept art or final render.
 
 Panel direction: ${continuityStyle} The scene brief is: ${request.brief} Previous handoff: ${input.previousShotHandoff}. Next handoff: ${input.nextShotHandoff}. Planned panel actions: ${phaseDirection}
 
@@ -308,6 +318,15 @@ function buildStoryboardCreationMetadata(request, storyboardImagePrompt, provide
             ? "generated-with-external-guide"
             : "generated",
         panel_count: storyboardImagePrompt.panelCount,
+        default_panel_count: DEFAULT_STORYBOARD_SHEET_PANELS,
+        style_contract: "raw-pencil-production-storyboard",
+        forbidden_visual_modes: [
+            "photorealistic stills",
+            "full-color panels",
+            "concept-art strip",
+            "CGI render"
+        ],
+        annotation_colors_allowed: true,
         reading_order: "left-to-right, top-to-bottom",
         character_sheet_ids: storyboardImagePrompt.characterSheetIds,
         external_storyboard_guide_ids: storyboardImagePrompt.externalStoryboardGuideIds,
@@ -421,7 +440,7 @@ export function buildStoryboardReferencePromptBundles(input) {
     const voiceCast = buildVoiceCast(request);
     const phaseBudget = buildStoryboardPhaseBudget(request.durationSeconds, request.storyboardReferenceMode.maxStoryboardPhases);
     const providerFileLimits = buildProviderFileLimitReport(request, characterReferenceSheetPrompts.length + 1);
-    const storyboardSheetPanelCount = getStoryboardSheetPanelCount(request, phaseBudget);
+    const storyboardSheetPanelCount = getStoryboardSheetPanelCount(request);
     const videoPhaseCount = getVideoPhaseCount(request, phaseBudget);
     const maxPhases = phaseBudget.effectiveMaxStoryboardPhases;
     const splitRequired = videoPhaseCount > maxPhases;

package/build/lib/storyboard-reference/types.d.ts

@@ -128,7 +128,7 @@ export interface StoryboardImagePrompt {
     provider: "gpt-image-2";
     aspectRatio: "16:9";
     panelCount: number;
-    style: "professional-production-storyboard";
+    style: "raw-pencil-production-storyboard";
     characterSheetIds: string[];
     externalStoryboardGuideIds: string[];
     previousShotHandoff: string;
@@ -141,6 +141,15 @@ export interface StoryboardCreationMetadata {
     alias_path: string;
     source_mode: "generated" | "generated-with-external-guide";
     panel_count: number;
+    default_panel_count: 12;
+    style_contract: "raw-pencil-production-storyboard";
+    forbidden_visual_modes: [
+        "photorealistic stills",
+        "full-color panels",
+        "concept-art strip",
+        "CGI render"
+    ];
+    annotation_colors_allowed: true;
     reading_order: "left-to-right, top-to-bottom";
     character_sheet_ids: string[];
     external_storyboard_guide_ids: string[];

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

@@ -114,8 +114,13 @@ export function validatePromptBundle(bundle, assets, voiceCast = []) {
         hasStoryboardReference: assets.storyboards.length >= 1 || Boolean(bundle.storyboardImagePrompt),
         hasStoryboardImagePrompt: Boolean(bundle.storyboardImagePrompt?.promptText.trim()),
         hasStoryboardCreationMetadata: Boolean(bundle.storyboard_creation?.prompt_text.trim())
+            && bundle.storyboard_creation?.prompt_text === bundle.storyboardImagePrompt.promptText
             && bundle.storyboard_creation?.prompt_path === bundle.storyboardImagePrompt.outputPath
             && bundle.storyboard_creation?.panel_count === bundle.storyboardImagePrompt.panelCount
+            && bundle.storyboard_creation?.default_panel_count === 12
+            && bundle.storyboard_creation?.style_contract === "raw-pencil-production-storyboard"
+            && bundle.storyboard_creation?.forbidden_visual_modes.includes("photorealistic stills")
+            && bundle.storyboard_creation?.annotation_colors_allowed === true
             && bundle.storyboard_creation?.annotation_policy.rendered_in_video === false,
         storyboardPromptHasReferenceLockStructure: hasGptImageStillPromptContract(bundle.storyboardImagePrompt?.promptText ?? ""),
         hasAvoidLineEverywhere: Object.values(bundle.modelPrompts).every(output => Boolean(output) && hasAvoidOrNegativePrompt(output.promptText)),

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

@@ -36,12 +36,13 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- storyboard sheet panel budget: default is 12 cinematic panels in one GPT Image 2 storyboard sheet; an explicit storyboard panel hint may request 1-12 panels
 - video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
 - hard cap: max 4 video phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - 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
+- storyboard art grammar: white paper 16:9 production storyboard sheet, actual drawings black and white only, rough pencil lines, minimal detail, fast gesture drawing energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- hard negative style lock: do not create photorealistic cinematic stills, full-color rendered panels, concept art, movie frames, underwater/color-grade panels, 3D render, anime, CGI, or polished illustration
 - 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
 
@@ -76,9 +77,10 @@ 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.
+- The storyboard token is the complete visual/action/camera/choreography source and controls composition, blocking, camera direction, timing, action rhythm, framing variety, final pose, and phase order only.
+- Follow all storyboard beats left-to-right, top-to-bottom. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose.
+- Compress the full 12-beat default storyboard sheet into the requested duration as readable motion snapshots while preserving the duration-aware video phase budget.
+- Treat storyboard arrows, labels, notes, lens notes, page headers, panel borders, 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.

package/content/workflows/generate-storyboard.md

@@ -37,7 +37,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 4-6 seconds: 1-2 video phases
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
-   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,6 +48,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
 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
+   - enforce white-paper, black-and-white rough pencil production storyboard artwork; only annotation arrows/marks may use color
    - include previous shot handoff and next shot handoff
    - preserve shared location, lighting, screen direction, action rhythm, and scene continuity
 7. Build model prompt bundle:

package/package.json

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

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

@@ -36,12 +36,13 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- storyboard sheet panel budget: default is 12 cinematic panels in one GPT Image 2 storyboard sheet; an explicit storyboard panel hint may request 1-12 panels
 - video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
 - hard cap: max 4 video phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - 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
+- storyboard art grammar: white paper 16:9 production storyboard sheet, actual drawings black and white only, rough pencil lines, minimal detail, fast gesture drawing energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- hard negative style lock: do not create photorealistic cinematic stills, full-color rendered panels, concept art, movie frames, underwater/color-grade panels, 3D render, anime, CGI, or polished illustration
 - 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
 
@@ -76,9 +77,10 @@ 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.
+- The storyboard token is the complete visual/action/camera/choreography source and controls composition, blocking, camera direction, timing, action rhythm, framing variety, final pose, and phase order only.
+- Follow all storyboard beats left-to-right, top-to-bottom. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose.
+- Compress the full 12-beat default storyboard sheet into the requested duration as readable motion snapshots while preserving the duration-aware video phase budget.
+- Treat storyboard arrows, labels, notes, lens notes, page headers, panel borders, 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.

package/packages/gpt-image-smart/content/workflows/generate-storyboard.md

@@ -37,7 +37,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 4-6 seconds: 1-2 video phases
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
-   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,6 +48,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
 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
+   - enforce white-paper, black-and-white rough pencil production storyboard artwork; only annotation arrows/marks may use color
    - include previous shot handoff and next shot handoff
    - preserve shared location, lighting, screen direction, action rhythm, and scene continuity
 7. Build model prompt bundle:
@@ -95,3 +96,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/packages/hybrid/content/skills/storyboard-reference/SKILL.md

@@ -36,12 +36,13 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- storyboard sheet panel budget: default is 12 cinematic panels in one GPT Image 2 storyboard sheet; an explicit storyboard panel hint may request 1-12 panels
 - video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
 - hard cap: max 4 video phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - 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
+- storyboard art grammar: white paper 16:9 production storyboard sheet, actual drawings black and white only, rough pencil lines, minimal detail, fast gesture drawing energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- hard negative style lock: do not create photorealistic cinematic stills, full-color rendered panels, concept art, movie frames, underwater/color-grade panels, 3D render, anime, CGI, or polished illustration
 - 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
 
@@ -76,9 +77,10 @@ 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.
+- The storyboard token is the complete visual/action/camera/choreography source and controls composition, blocking, camera direction, timing, action rhythm, framing variety, final pose, and phase order only.
+- Follow all storyboard beats left-to-right, top-to-bottom. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose.
+- Compress the full 12-beat default storyboard sheet into the requested duration as readable motion snapshots while preserving the duration-aware video phase budget.
+- Treat storyboard arrows, labels, notes, lens notes, page headers, panel borders, 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.

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

@@ -37,7 +37,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 4-6 seconds: 1-2 video phases
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
-   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,6 +48,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
 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
+   - enforce white-paper, black-and-white rough pencil production storyboard artwork; only annotation arrows/marks may use color
    - include previous shot handoff and next shot handoff
    - preserve shared location, lighting, screen direction, action rhythm, and scene continuity
 7. Build model prompt bundle:
@@ -95,3 +96,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/packages/hybrid-smart/content/skills/storyboard-reference/SKILL.md

@@ -36,12 +36,13 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- storyboard sheet panel budget: default is 12 cinematic panels in one GPT Image 2 storyboard sheet; an explicit storyboard panel hint may request 1-12 panels
 - video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
 - hard cap: max 4 video phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - 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
+- storyboard art grammar: white paper 16:9 production storyboard sheet, actual drawings black and white only, rough pencil lines, minimal detail, fast gesture drawing energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- hard negative style lock: do not create photorealistic cinematic stills, full-color rendered panels, concept art, movie frames, underwater/color-grade panels, 3D render, anime, CGI, or polished illustration
 - 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
 
@@ -76,9 +77,10 @@ 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.
+- The storyboard token is the complete visual/action/camera/choreography source and controls composition, blocking, camera direction, timing, action rhythm, framing variety, final pose, and phase order only.
+- Follow all storyboard beats left-to-right, top-to-bottom. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose.
+- Compress the full 12-beat default storyboard sheet into the requested duration as readable motion snapshots while preserving the duration-aware video phase budget.
+- Treat storyboard arrows, labels, notes, lens notes, page headers, panel borders, 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.

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

@@ -37,7 +37,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 4-6 seconds: 1-2 video phases
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
-   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,6 +48,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
 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
+   - enforce white-paper, black-and-white rough pencil production storyboard artwork; only annotation arrows/marks may use color
    - include previous shot handoff and next shot handoff
    - preserve shared location, lighting, screen direction, action rhythm, and scene continuity
 7. Build model prompt bundle:
@@ -95,3 +96,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/packages/multi/content/skills/storyboard-reference/SKILL.md

@@ -36,12 +36,13 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- storyboard sheet panel budget: default is 12 cinematic panels in one GPT Image 2 storyboard sheet; an explicit storyboard panel hint may request 1-12 panels
 - video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
 - hard cap: max 4 video phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - 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
+- storyboard art grammar: white paper 16:9 production storyboard sheet, actual drawings black and white only, rough pencil lines, minimal detail, fast gesture drawing energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- hard negative style lock: do not create photorealistic cinematic stills, full-color rendered panels, concept art, movie frames, underwater/color-grade panels, 3D render, anime, CGI, or polished illustration
 - 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
 
@@ -76,9 +77,10 @@ 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.
+- The storyboard token is the complete visual/action/camera/choreography source and controls composition, blocking, camera direction, timing, action rhythm, framing variety, final pose, and phase order only.
+- Follow all storyboard beats left-to-right, top-to-bottom. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose.
+- Compress the full 12-beat default storyboard sheet into the requested duration as readable motion snapshots while preserving the duration-aware video phase budget.
+- Treat storyboard arrows, labels, notes, lens notes, page headers, panel borders, 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.

package/packages/multi/content/workflows/generate-storyboard.md

@@ -37,7 +37,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 4-6 seconds: 1-2 video phases
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
-   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,6 +48,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
 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
+   - enforce white-paper, black-and-white rough pencil production storyboard artwork; only annotation arrows/marks may use color
    - include previous shot handoff and next shot handoff
    - preserve shared location, lighting, screen direction, action rhythm, and scene continuity
 7. Build model prompt bundle:
@@ -95,3 +96,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/packages/studio/content/skills/storyboard-reference/SKILL.md

@@ -36,12 +36,13 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- storyboard sheet panel budget: default is 12 cinematic panels in one GPT Image 2 storyboard sheet; an explicit storyboard panel hint may request 1-12 panels
 - video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
 - hard cap: max 4 video phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - 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
+- storyboard art grammar: white paper 16:9 production storyboard sheet, actual drawings black and white only, rough pencil lines, minimal detail, fast gesture drawing energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- hard negative style lock: do not create photorealistic cinematic stills, full-color rendered panels, concept art, movie frames, underwater/color-grade panels, 3D render, anime, CGI, or polished illustration
 - 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
 
@@ -76,9 +77,10 @@ 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.
+- The storyboard token is the complete visual/action/camera/choreography source and controls composition, blocking, camera direction, timing, action rhythm, framing variety, final pose, and phase order only.
+- Follow all storyboard beats left-to-right, top-to-bottom. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose.
+- Compress the full 12-beat default storyboard sheet into the requested duration as readable motion snapshots while preserving the duration-aware video phase budget.
+- Treat storyboard arrows, labels, notes, lens notes, page headers, panel borders, 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.

package/packages/studio/content/workflows/generate-storyboard.md

@@ -37,7 +37,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 4-6 seconds: 1-2 video phases
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
-   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,6 +48,7 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
 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
+   - enforce white-paper, black-and-white rough pencil production storyboard artwork; only annotation arrows/marks may use color
    - include previous shot handoff and next shot handoff
    - preserve shared location, lighting, screen direction, action rhythm, and scene continuity
 7. Build model prompt bundle:
@@ -95,3 +96,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`