@milenyumai/film-kit 2.3.7 → 2.3.8

package/README.md

@@ -196,7 +196,7 @@ 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 professional 12-frame GPT Image 2 storyboard sheet 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
@@ -212,7 +212,7 @@ If your tool supports slash-style workflow prompts, this shorter first prompt is
 
 ```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.
+Storyboard-reference mode. Character reference: refs/character.png. Brief: scenario.md. Model: seedance-2.0. Duration: 15s. Aspect: 16:9. Generate the professional 12-frame graphite storyboard sheet 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:
@@ -227,7 +227,7 @@ npx @milenyumai/film-kit generate-storyboard \
   --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.
+After the command finishes, start with `outputs/storyboard-prompt.md`. It is the ready-to-use GPT Image 2 storyboard image prompt. The default sheet is a 4x3 grid of 12 labeled pencil panels (`Frame 001` through `Frame 012`) on cream/off-white paper, with a short title, action line, and `CAM:` line in every panel. 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:
 
@@ -301,10 +301,11 @@ 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 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.
+- Storyboard prompts default to a 12-panel 16:9 production-board sheet: 4x3 grid, `Frames 001-012`, cream/off-white paper, bold black frame borders, rough black-and-white graphite drawings, strong silhouettes, visible body/camera momentum, cinematic camera variety, and annotation colors only. Red movement arrows and blue notes are allowed for planning; full-color rendered panels remain forbidden. Hard negatives block photorealistic stills, full-color rendered panels, concept-art strips, CGI, anime, and polished illustration.
+- If the brief includes an explicit 1-12 numbered frame list, Film-Kit preserves those panel titles/actions/camera cues in the storyboard prompt. Otherwise it deterministically generates a 12-beat plan from start pose through final pose.
+- 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. Multi-shot Seedance prompts include `[STORYBOARD 12-BEAT ORDER]`, render the sheet as distinct fast micro-shots, and use quick cuts, match cuts, whip transitions, or motivated camera jumps between beats. Continuous-shot mode keeps `No scene cuts throughout` only when a true single uninterrupted shot is requested.
 - 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, style contract, default panel count, reading order, panel count, forbidden visual modes, 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, `panel_beats`, 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.

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

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

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

@@ -51,13 +51,22 @@ export class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter {
         ].join(" ").toLowerCase();
         return /dance|dancing|choreograph|sing|singing|song|vocal|sarki|sark|soyl|dans/.test(combined);
     }
+    formatStoryboardBeatOrder(input) {
+        return input.storyboardImagePrompt.panelBeats
+            .map(beat => `Frame ${beat.frameId} | Phase ${beat.phaseIndex} | ${beat.title}: ${beat.action} CAM: ${beat.camera}. Annotation cue is planning-only and must not render: ${beat.annotationCue}.`)
+            .join("\n");
+    }
     buildPrompt(input) {
         const audioPlan = buildAudioPlan(input);
         const storyboardEntry = this.getMappingEntries(input, "storyboard_plan")[0];
         const storyboardToken = storyboardEntry?.token ?? "@Image2";
+        const beatCount = input.storyboardImagePrompt.panelBeats.length || input.storyboardImagePrompt.panelCount;
+        const beatOrderHeader = `[STORYBOARD ${beatCount}-BEAT ORDER]`;
+        const finalBeatHoldSeconds = input.request.durationSeconds >= 8 ? "1.0" : "0.5";
+        const storyboardBeatOrder = this.formatStoryboardBeatOrder(input);
         const continuityInstruction = input.continuityMode === "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 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.`;
+            ? `Use the generated storyboard reference ${storyboardToken} as the complete visual/action/camera/choreography source for this ${input.request.durationSeconds}-second video. Follow all ${beatCount} beats sequentially from left-to-right, top-to-bottom as the exact visual beat order within one uninterrupted camera move. Render the beats as sequential pose snapshots inside one continuous camera move; each beat must visibly change pose, framing pressure, or movement state without becoming a separate scene cut. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose. Compress the full ${beatCount}-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 ${beatCount} beats sequentially from left-to-right, top-to-bottom as the exact visual beat order. Render as ${beatCount} distinct micro-shots / fast motion snapshots. Do not smooth the storyboard into one continuous generic action. Each beat must visibly change pose, camera framing, and movement state. Do not reinterpret pose, action, camera angle, emotional progression, framing variety, movement logic, shot order, or final pose. Compress the full ${beatCount}-beat sequence into the requested duration as fast readable motion snapshots, not full-length actions. Use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats. Final beat holds for the last ${finalBeatHoldSeconds} seconds. 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)
@@ -81,6 +90,9 @@ ${input.request.brief}
 [STORYBOARD PHASES]
 ${formatPhaseLines(input.interpretation.phases)}
 
+${beatOrderHeader}
+${storyboardBeatOrder}
+
 [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, 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.
 
@@ -139,6 +151,8 @@ Avoid: identity drift, face drift, outfit drift, duplicated performer, storyboar
                     && /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)
+                    && /Render as \d+ distinct micro-shots \/ fast motion snapshots/i.test(output.promptText)
+                    && /Do not smooth the storyboard into one continuous generic action/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)
@@ -148,7 +162,10 @@ Avoid: identity drift, face drift, outfit drift, duplicated performer, storyboar
             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),
+                : !hasNoCutsRule
+                    && /quick cuts/i.test(output.promptText)
+                    && /match cuts/i.test(output.promptText)
+                    && /whip transitions/i.test(output.promptText),
             musicNone: /Music: NONE/i.test(output.promptText)
         };
         const issues = [

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

@@ -4,4 +4,4 @@ export { resolveAssetRoles } from "./asset-role-resolver.js";
 export { interpretStoryboard } from "./storyboard-interpreter.js";
 export { renderShotMarkdown, writeStoryboardReferenceOutputs } from "./output-writer.js";
 export { assertSafeStoryboardReferenceRequest, assertStoryboardReferenceBuildPass, validateModelPromptOutput, validatePromptBundle, validateResolvedAssetRoles } from "./validators.js";
-export type { AdapterInput, AudioPlan, CameraPlan, CharacterReferenceSheetPrompt, ContinuityAnchors, DialogueLine, ModelPromptOutput, ModelPromptQa, ModelRouteMetadata, NormalizedVideoPromptRequest, PromptBundle, PromptBundleQa, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, ReferenceAssetRole, ReferenceLockStrength, ResolvedAssetRoles, SeedanceContinuityMode, ShotHandoffNote, StoryboardCreationMetadata, StoryboardImagePrompt, StoryboardInterpretation, StoryboardPhase, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePlan, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoModelPromptAdapter, VideoPromptRequest, VisualWorld, VoiceCastEntry } from "./types.js";
+export type { AdapterInput, AudioPlan, CameraPlan, CharacterReferenceSheetPrompt, ContinuityAnchors, DialogueLine, ModelPromptOutput, ModelPromptQa, ModelRouteMetadata, NormalizedVideoPromptRequest, PromptBundle, PromptBundleQa, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, ReferenceAssetRole, ReferenceLockStrength, ResolvedAssetRoles, SeedanceContinuityMode, ShotHandoffNote, StoryboardCreationMetadata, StoryboardImagePrompt, StoryboardInterpretation, StoryboardPanelBeat, StoryboardPhase, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePlan, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoModelPromptAdapter, VideoPromptRequest, VisualWorld, VoiceCastEntry } from "./types.js";

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

@@ -168,8 +168,221 @@ Avoid: text, labels, arrows, captions, panel numbers, watermarks, logos, extra c
         };
     });
 }
+const FALLBACK_PANEL_BEATS = [
+    {
+        title: "Start Pose",
+        action: "Open on the character's first readable body shape, eyeline, and weight before the action begins.",
+        camera: "wide or medium-wide establishing frame with clear screen direction",
+        annotationCue: "blue note marks entry tempo; red arrow marks first weight direction"
+    },
+    {
+        title: "Shared Intent",
+        action: "Clarify the emotional objective, gaze target, and relationship to the room or prop.",
+        camera: "medium frame that keeps face, hands, and target geography readable",
+        annotationCue: "blue note marks breath or pause; red arrow marks gaze or hand intention"
+    },
+    {
+        title: "First Motion",
+        action: "Begin the first visible movement from the brief with grounded foot, hand, or torso mechanics.",
+        camera: "low or side angle that shows the first physical push clearly",
+        annotationCue: "red movement arrows show direction and contact"
+    },
+    {
+        title: "Build Action",
+        action: "Escalate the central action with stronger body momentum and visible cause-and-effect.",
+        camera: "tracking medium shot or motivated push-in following the action",
+        annotationCue: "red arrows mark acceleration; blue note marks camera tempo"
+    },
+    {
+        title: "Camera Shift",
+        action: "Change framing to reveal a new angle on the same action without changing identity or location.",
+        camera: "motivated angle jump, whip pan, overhead, or tighter close-up",
+        annotationCue: "blue notes mark camera jump and lens emphasis"
+    },
+    {
+        title: "Flow / Contact",
+        action: "Show fabric, hair, floor, prop, or environmental contact proving the motion is physical.",
+        camera: "close side frame that keeps contact point and body force visible",
+        annotationCue: "red arrows mark contact force; blue note marks rhythm"
+    },
+    {
+        title: "Insert Detail",
+        action: "Cut to a concrete detail: hand tension, foot pressure, reflection, prop movement, or breath.",
+        camera: "tight insert or extreme close-up with shallow but readable focus",
+        annotationCue: "blue note names the detail; red arrow marks micro-motion"
+    },
+    {
+        title: "Peak Motion",
+        action: "Hit the most forceful movement shape from the brief with maximum readable silhouette.",
+        camera: "dynamic low angle, overhead, or long-lens compression at peak energy",
+        annotationCue: "red movement arrows mark peak direction and body line"
+    },
+    {
+        title: "Breath Reaction",
+        action: "Let the character's breath, face, gaze, or shoulders register the consequence of the peak.",
+        camera: "close-up or tight medium on face, hands, and breath",
+        annotationCue: "blue notes mark breath and emotional tempo"
+    },
+    {
+        title: "Final Approach",
+        action: "Drive toward the resolved composition while preserving screen direction and continuity.",
+        camera: "motivated push, lateral track, or controlled handheld move into final pose",
+        annotationCue: "red arrows show final approach; blue note marks camera settle"
+    },
+    {
+        title: "Resolved Emotion",
+        action: "Hold the emotional endpoint in posture, gaze, facial tension, and body balance.",
+        camera: "stable medium or close composition with the resolved eyeline",
+        annotationCue: "blue note marks hold duration and breath"
+    },
+    {
+        title: "Success / Final Pose",
+        action: "End on the strongest final readable pose or composition promised by the brief.",
+        camera: "final composed frame with clean silhouette and no new action",
+        annotationCue: "blue note marks final hold; red arrows taper off"
+    }
+];
+function frameIdForIndex(index) {
+    return String(index).padStart(3, "0");
+}
+function normalizePanelText(value, fallback) {
+    const normalized = (value ?? "")
+        .replace(/[*_`#>]+/g, "")
+        .replace(/\s+/g, " ")
+        .replace(/^[\s:;,.|\-–—]+|[\s:;,.|\-–—]+$/g, "")
+        .trim();
+    return normalized || fallback;
+}
+function briefAnchor(brief) {
+    const normalized = brief.replace(/\s+/g, " ").trim();
+    return normalized.length > 220 ? `${normalized.slice(0, 217).trim()}...` : normalized;
+}
+function phaseIndexForPanel(panelIndex, panelCount, phaseCount) {
+    return Math.min(phaseCount, Math.floor((panelIndex * phaseCount) / Math.max(1, panelCount)) + 1);
+}
+function extractStoryboardTitle(brief, shotId, lastFrameId) {
+    const titleMatch = brief.match(/^\s*Title:\s*(.+?)\s*$/im);
+    const explicitTitle = normalizePanelText(titleMatch?.[1], "");
+    return explicitTitle || `${shotId} STORYBOARD (Frames 001-${lastFrameId})`;
+}
+function parseNumberedFrameLine(line) {
+    const match = line.match(/^\s*(?:[-*]\s*)?(?:(?:frame|panel)\s*)?0*(1[0-2]|[1-9])(?:\s*[\).:-]|\s+[-–—]\s+|\s+)/i);
+    if (!match)
+        return undefined;
+    const index = Number(match[1]);
+    const text = line.slice(match[0].length).trim();
+    if (!text)
+        return undefined;
+    return { index, text };
+}
+function splitExplicitFrameText(text, fallbackCamera) {
+    let body = text;
+    let camera = fallbackCamera;
+    const cameraMatch = body.match(/\b(?:CAM|Camera)\s*:\s*(.+)$/i);
+    if (cameraMatch) {
+        camera = normalizePanelText(cameraMatch[1], fallbackCamera);
+        body = body.slice(0, cameraMatch.index).trim();
+    }
+    const delimiterMatch = body.match(/\s[-–—]\s|:\s/);
+    if (!delimiterMatch || delimiterMatch.index === undefined) {
+        return {
+            title: normalizePanelText(body.split(/\s+/).slice(0, 5).join(" "), "Storyboard Beat"),
+            action: normalizePanelText(body, "Continue the storyboard action from the brief."),
+            camera
+        };
+    }
+    const delimiterStart = delimiterMatch.index;
+    const delimiterEnd = delimiterStart + delimiterMatch[0].length;
+    const title = normalizePanelText(body.slice(0, delimiterStart), "Storyboard Beat");
+    const action = normalizePanelText(body.slice(delimiterEnd), body);
+    return { title, action, camera };
+}
+function parseExplicitStoryboardPanelBeats(input) {
+    const parsedLines = input.brief
+        .split(/\r?\n/)
+        .map(parseNumberedFrameLine)
+        .filter((line) => Boolean(line));
+    if (parsedLines.length < input.panelCount) {
+        return undefined;
+    }
+    const byIndex = new Map(parsedLines.map(line => [line.index, line.text]));
+    const hasRequiredFrames = Array.from({ length: input.panelCount }, (_, index) => index + 1)
+        .every(index => byIndex.has(index));
+    if (!hasRequiredFrames) {
+        return undefined;
+    }
+    return Array.from({ length: input.panelCount }, (_, index) => {
+        const panelIndex = index + 1;
+        const parsed = splitExplicitFrameText(byIndex.get(panelIndex) ?? "", input.cameraFallback);
+        return {
+            index: panelIndex,
+            frameId: frameIdForIndex(panelIndex),
+            title: parsed.title,
+            action: parsed.action,
+            camera: parsed.camera,
+            annotationCue: "preserve user-specified beat; red movement arrows and blue camera/breath notes only",
+            phaseIndex: phaseIndexForPanel(index, input.panelCount, input.phaseCount)
+        };
+    });
+}
+function buildFallbackStoryboardPanelBeats(input) {
+    const brief = briefAnchor(input.request.brief);
+    const cameraFallbacks = [
+        `${input.interpretation.cameraPlan.framing}; ${input.interpretation.cameraPlan.screenDirection}`,
+        "medium framing with readable eyeline, hands, and posture",
+        "low or side angle emphasizing grounded first movement",
+        `${input.interpretation.cameraPlan.movement} while preserving screen direction`,
+        "motivated camera jump, whip pan, overhead, or tighter close-up",
+        "close side frame on body force, floor contact, fabric, hair, or prop response",
+        "tight insert or extreme close-up on physical detail",
+        "dynamic peak-energy frame with the strongest silhouette",
+        "close-up or tight medium on breath, gaze, and consequence",
+        "motivated push, track, or handheld move into the ending composition",
+        "stable medium or close frame holding the emotional resolution",
+        "final composed frame with clean silhouette and no new action"
+    ];
+    return Array.from({ length: input.panelCount }, (_, index) => {
+        const templateIndex = input.panelCount >= FALLBACK_PANEL_BEATS.length
+            ? Math.min(index, FALLBACK_PANEL_BEATS.length - 1)
+            : Math.round((index * (FALLBACK_PANEL_BEATS.length - 1)) / Math.max(1, input.panelCount - 1));
+        const template = FALLBACK_PANEL_BEATS[templateIndex] ?? FALLBACK_PANEL_BEATS.at(-1);
+        const phase = input.interpretation.phases[phaseIndexForPanel(index, input.panelCount, input.interpretation.phases.length) - 1];
+        return {
+            index: index + 1,
+            frameId: frameIdForIndex(index + 1),
+            title: template.title,
+            action: `${template.action} Brief anchor: ${brief}. Phase cue: ${phase?.subjectAction ?? "continue the shot action."}`,
+            camera: cameraFallbacks[templateIndex] ?? template.camera,
+            annotationCue: template.annotationCue,
+            phaseIndex: phaseIndexForPanel(index, input.panelCount, input.interpretation.phases.length)
+        };
+    });
+}
+function buildStoryboardPanelBeats(input) {
+    const cameraFallback = `${input.interpretation.cameraPlan.framing}, ${input.interpretation.cameraPlan.movement}, ${input.interpretation.cameraPlan.lens}`;
+    return parseExplicitStoryboardPanelBeats({
+        brief: input.request.brief,
+        panelCount: input.panelCount,
+        phaseCount: input.interpretation.phases.length,
+        cameraFallback
+    }) ?? buildFallbackStoryboardPanelBeats(input);
+}
+function formatPanelBeatPlan(panelBeats) {
+    return panelBeats
+        .map(beat => `Frame ${beat.frameId} | ${beat.title}
+Action: ${beat.action}
+CAM: ${beat.camera}
+NOTE: ${beat.annotationCue}
+Phase: ${beat.phaseIndex}`)
+        .join("\n\n");
+}
 function buildStoryboardImagePrompt(input) {
     const { request, assets, shotId, interpretation, characterReferenceSheetPrompts } = input;
+    const panelBeats = buildStoryboardPanelBeats({
+        request,
+        interpretation,
+        panelCount: input.storyboardSheetPanelCount
+    });
     const characterSheetIds = characterReferenceSheetPrompts.map(prompt => prompt.id);
     const externalStoryboardGuideIds = assets.storyboards.map(storyboard => storyboard.asset.id);
     const sheetRefs = characterReferenceSheetPrompts
@@ -184,6 +397,13 @@ function buildStoryboardImagePrompt(input) {
     const panelLabel = input.storyboardSheetPanelCount === 1
         ? "1 cinematic panel"
         : `${input.storyboardSheetPanelCount} cinematic panels`;
+    const panelGrid = input.storyboardSheetPanelCount === 12
+        ? "4x3 grid of 12 pencil-sketched panels"
+        : `${input.storyboardSheetPanelCount} pencil-sketched panel${input.storyboardSheetPanelCount === 1 ? "" : "s"} in a clean production storyboard sheet`;
+    const lastFrameId = panelBeats.at(-1)?.frameId ?? frameIdForIndex(input.storyboardSheetPanelCount);
+    const frameRange = `Frames 001-${lastFrameId}`;
+    const storyboardTitle = extractStoryboardTitle(request.brief, shotId, lastFrameId);
+    const panelBeatPlan = formatPanelBeatPlan(panelBeats);
     const continuityStyle = interpretation.phases.length <= 1
         ? `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.`;
@@ -193,6 +413,7 @@ function buildStoryboardImagePrompt(input) {
         provider: "gpt-image-2",
         aspectRatio: "16:9",
         panelCount: input.storyboardSheetPanelCount,
+        panelBeats,
         style: "raw-pencil-production-storyboard",
         characterSheetIds,
         externalStoryboardGuideIds,
@@ -202,21 +423,29 @@ function buildStoryboardImagePrompt(input) {
 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.
+Only annotation arrows/marks/notes may use color; all storyboard artwork remains black graphite pencil on cream/off-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 ${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}
+Change only: Create a raw ${shotId} storyboard focused on intense physical movement and clear cinematic action from this scene: ${request.brief}. Title: ${storyboardTitle}. Layout: ${panelGrid}, ${frameRange}, cream/off-white paper, bold black frame borders, readable storyboard margins, and no rendered color artwork. 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 production storyboard with black-and-white rough pencil linework on cream/off-white paper. 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.
+
+Visible panel labeling requirements: every panel must visibly include its Frame 001-style frame ID, the short panel title, one concise action line, and a CAM: line. Use these exact beats, preserving titles and order:
+
+${panelBeatPlan}
+
+NOTES: Add compact blue notes for breath, camera, and tempo cues only where useful. Keep notes short and outside the image action area.
 
-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.
+LEGEND: red movement arrows = movement; blue notes = breath/camera/tempo cue; green marks = framing/composition; orange marks = lighting direction; purple marks = vocal/emotional emphasis. No timestamps.
 
-Panel direction: ${continuityStyle} The scene brief is: ${request.brief} Previous handoff: ${input.previousShotHandoff}. Next handoff: ${input.nextShotHandoff}. Planned panel actions: ${phaseDirection}
+Panel direction: ${continuityStyle} The scene brief is: ${request.brief} Previous handoff: ${input.previousShotHandoff}. Next handoff: ${input.nextShotHandoff}. Planned video phase actions: ${phaseDirection}
 
 Camera and staging: show ${interpretation.cameraPlan.framing}, ${interpretation.cameraPlan.movement}, ${interpretation.cameraPlan.lens}; preserve ${interpretation.cameraPlan.screenDirection}. Use cinematic arthouse camerawork with handheld energy, whip pans, orbit movement, overhead shots, low angles, side silhouettes, aggressive close-ups, long lens compression, inserts, and extreme negative space whenever motivated by the beat. Maintain the same environment, lighting, atmosphere, foreground, midground, and background continuity: ${interpretation.visualWorld.environment}; ${interpretation.visualWorld.lighting}; ${interpretation.visualWorld.foreground}; ${interpretation.visualWorld.midground}; ${interpretation.visualWorld.background}; ${interpretation.visualWorld.atmosphere}.
 
-Annotation color system: red arrows for body movement, blue arrows for camera movement, green marks for framing/composition, orange marks for lighting direction, purple marks for vocal or emotional emphasis when relevant, black text only for very short lens notes and panel labels. No timestamps.
+Annotation color system: red movement arrows for body movement, blue notes for camera movement, breath, and tempo, green marks for framing/composition, orange marks for lighting direction, purple marks for vocal or emotional emphasis when relevant, black text only for short lens notes and panel labels. No timestamps.
 
 Every panel must contain visible momentum. Every panel must contain visible motion, strong body momentum, or clear behavioral change: gaze shift, breath, weight transfer, contact with ground/prop, fabric motion, hand tension, floor contact, hair or clothing motion, or a readable pose transition. Avoid static standing poses unless explicitly required by the beat. Keep the location minimal and readable. End with one overwhelming final readable movement pose or composition that preserves the shot's emotional endpoint.
 
@@ -328,14 +557,15 @@ function buildStoryboardCreationMetadata(request, storyboardImagePrompt, provide
         ],
         annotation_colors_allowed: true,
         reading_order: "left-to-right, top-to-bottom",
+        panel_beats: storyboardImagePrompt.panelBeats,
         character_sheet_ids: storyboardImagePrompt.characterSheetIds,
         external_storyboard_guide_ids: storyboardImagePrompt.externalStoryboardGuideIds,
         seedance_token: storyboardEntry?.token ?? "@Image2",
         annotation_policy: {
             rendered_in_video: false,
             color_system: {
-                red: "body movement",
-                blue: "camera movement",
+                red: "movement arrows",
+                blue: "breath / camera / tempo notes",
                 green: "framing / composition",
                 orange: "lighting direction",
                 purple: "vocal / emotional emphasis",

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

@@ -128,6 +128,7 @@ export interface StoryboardImagePrompt {
     provider: "gpt-image-2";
     aspectRatio: "16:9";
     panelCount: number;
+    panelBeats: StoryboardPanelBeat[];
     style: "raw-pencil-production-storyboard";
     characterSheetIds: string[];
     externalStoryboardGuideIds: string[];
@@ -135,6 +136,15 @@ export interface StoryboardImagePrompt {
     nextShotHandoff: string;
     promptText: string;
 }
+export interface StoryboardPanelBeat {
+    index: number;
+    frameId: string;
+    title: string;
+    action: string;
+    camera: string;
+    annotationCue: string;
+    phaseIndex: number;
+}
 export interface StoryboardCreationMetadata {
     provider: "gpt-image-2";
     prompt_path: string;
@@ -151,14 +161,15 @@ export interface StoryboardCreationMetadata {
     ];
     annotation_colors_allowed: true;
     reading_order: "left-to-right, top-to-bottom";
+    panel_beats: StoryboardPanelBeat[];
     character_sheet_ids: string[];
     external_storyboard_guide_ids: string[];
     seedance_token: string;
     annotation_policy: {
         rendered_in_video: false;
         color_system: {
-            red: "body movement";
-            blue: "camera movement";
+            red: "movement arrows";
+            blue: "breath / camera / tempo notes";
             green: "framing / composition";
             orange: "lighting direction";
             purple: "vocal / emotional emphasis";

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

@@ -121,6 +121,10 @@ export function validatePromptBundle(bundle, assets, voiceCast = []) {
             && 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
+            && Array.isArray(bundle.storyboard_creation?.panel_beats)
+            && bundle.storyboard_creation.panel_beats.length === bundle.storyboardImagePrompt.panelCount
+            && Array.isArray(bundle.storyboardImagePrompt.panelBeats)
+            && bundle.storyboardImagePrompt.panelBeats.length === bundle.storyboardImagePrompt.panelCount
             && 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

@@ -37,13 +37,15 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
 - 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
+- structured panel beats: every storyboard prompt must carry a numbered panel beat plan with `Frame 001`-style IDs, short titles, action lines, `CAM:` lines, annotation cues, and phase mapping
 - 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: 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
+- storyboard art grammar: cream/off-white paper 16:9 production storyboard sheet, 4x3 grid when using the default 12 panels, bold black frame borders, actual drawings black and white graphite 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
+- annotation grammar: annotations only may use color; red movement arrows = movement, blue notes = breath/camera/tempo cue, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
+- visible sheet text: panel labels, short titles, one action line, `CAM:` line, `NOTES`, and `LEGEND` are allowed on the storyboard sheet; timestamps are forbidden
 - 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.
@@ -62,6 +64,8 @@ Use it for composition, blocking, camera angle, action progression, visual rhyth
 
 - Character identity always wins over storyboard character design.
 - Storyboard text, labels, watermarks, logos, and panel borders are never copied into the video.
+- If the brief contains a complete 1-12 numbered frame list, preserve the user's panel titles, action beats, and camera cues in the storyboard prompt.
+- If the brief does not contain a complete frame list, generate a deterministic 12-beat sheet: start pose, shared intent, first motion, build action, camera shift, flow/contact, insert/detail, peak motion, breath/reaction, final approach, resolved emotion, success/final pose.
 - 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.
@@ -80,6 +84,9 @@ Seedance 2.0:
 - 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.
+- Include `[STORYBOARD 12-BEAT ORDER]` for default sheets and list Frame 001-012 with title, action, camera, and phase mapping.
+- In multi-shot storyboard mode, render as 12 distinct micro-shots / fast motion snapshots. Do not smooth the storyboard into one continuous generic action. Each beat must visibly change pose, camera framing, and movement state.
+- Use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats. For 8s+ videos, hold the final beat for the last 1.0 seconds; for shorter videos, hold it for the last 0.5 seconds.
 - 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.
@@ -111,7 +118,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
-- storyboard_creation metadata in `SHOTNN.bundle.json`
+- storyboard_creation metadata in `SHOTNN.bundle.json`, including `panel_beats`
 - audio plan
 - prompt bundle for requested models
 - QA verdict

package/content/workflows/generate-storyboard.md

@@ -38,6 +38,9 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
    - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
+   - default storyboard sheet uses `Frames 001-012` in a 4x3 grid
+   - every panel must have a visible frame label, short title, one action line, and `CAM:` line
+   - if the brief includes a full 1-12 frame list, preserve those titles/actions/camera cues; otherwise generate deterministic start-pose-to-final-pose beats
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,11 +51,14 @@ 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
+   - enforce cream/off-white paper, black-and-white rough graphite production storyboard artwork, and bold black frame borders; only annotation arrows/marks/notes may use color
+   - include `NOTES` and `LEGEND`; red movement arrows and blue notes are allowed as planning annotations only; no timestamps
    - 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
+   - Seedance multi-shot prompts include `[STORYBOARD 12-BEAT ORDER]`, render 12 distinct micro-shots / fast motion snapshots, avoid smoothing into one generic action, and use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats
+   - Seedance continuous-shot prompts keep the same beat order inside one uninterrupted camera move and reserve `No scene cuts throughout` for true single-shot mode only
    - Veo visual-planning prompt with full audio direction
    - Kling block-structured storyboard route
 8. Run QA gates:

package/package.json

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

@@ -37,13 +37,15 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
 - 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
+- structured panel beats: every storyboard prompt must carry a numbered panel beat plan with `Frame 001`-style IDs, short titles, action lines, `CAM:` lines, annotation cues, and phase mapping
 - 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: 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
+- storyboard art grammar: cream/off-white paper 16:9 production storyboard sheet, 4x3 grid when using the default 12 panels, bold black frame borders, actual drawings black and white graphite 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
+- annotation grammar: annotations only may use color; red movement arrows = movement, blue notes = breath/camera/tempo cue, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
+- visible sheet text: panel labels, short titles, one action line, `CAM:` line, `NOTES`, and `LEGEND` are allowed on the storyboard sheet; timestamps are forbidden
 - 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.
@@ -62,6 +64,8 @@ Use it for composition, blocking, camera angle, action progression, visual rhyth
 
 - Character identity always wins over storyboard character design.
 - Storyboard text, labels, watermarks, logos, and panel borders are never copied into the video.
+- If the brief contains a complete 1-12 numbered frame list, preserve the user's panel titles, action beats, and camera cues in the storyboard prompt.
+- If the brief does not contain a complete frame list, generate a deterministic 12-beat sheet: start pose, shared intent, first motion, build action, camera shift, flow/contact, insert/detail, peak motion, breath/reaction, final approach, resolved emotion, success/final pose.
 - 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.
@@ -80,6 +84,9 @@ Seedance 2.0:
 - 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.
+- Include `[STORYBOARD 12-BEAT ORDER]` for default sheets and list Frame 001-012 with title, action, camera, and phase mapping.
+- In multi-shot storyboard mode, render as 12 distinct micro-shots / fast motion snapshots. Do not smooth the storyboard into one continuous generic action. Each beat must visibly change pose, camera framing, and movement state.
+- Use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats. For 8s+ videos, hold the final beat for the last 1.0 seconds; for shorter videos, hold it for the last 0.5 seconds.
 - 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.
@@ -111,7 +118,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
-- storyboard_creation metadata in `SHOTNN.bundle.json`
+- storyboard_creation metadata in `SHOTNN.bundle.json`, including `panel_beats`
 - audio plan
 - prompt bundle for requested models
 - QA verdict

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

@@ -38,6 +38,9 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
    - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
+   - default storyboard sheet uses `Frames 001-012` in a 4x3 grid
+   - every panel must have a visible frame label, short title, one action line, and `CAM:` line
+   - if the brief includes a full 1-12 frame list, preserve those titles/actions/camera cues; otherwise generate deterministic start-pose-to-final-pose beats
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,11 +51,14 @@ 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
+   - enforce cream/off-white paper, black-and-white rough graphite production storyboard artwork, and bold black frame borders; only annotation arrows/marks/notes may use color
+   - include `NOTES` and `LEGEND`; red movement arrows and blue notes are allowed as planning annotations only; no timestamps
    - 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
+   - Seedance multi-shot prompts include `[STORYBOARD 12-BEAT ORDER]`, render 12 distinct micro-shots / fast motion snapshots, avoid smoothing into one generic action, and use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats
+   - Seedance continuous-shot prompts keep the same beat order inside one uninterrupted camera move and reserve `No scene cuts throughout` for true single-shot mode only
    - Veo visual-planning prompt with full audio direction
    - Kling block-structured storyboard route
 8. Run QA gates:

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

@@ -37,13 +37,15 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
 - 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
+- structured panel beats: every storyboard prompt must carry a numbered panel beat plan with `Frame 001`-style IDs, short titles, action lines, `CAM:` lines, annotation cues, and phase mapping
 - 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: 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
+- storyboard art grammar: cream/off-white paper 16:9 production storyboard sheet, 4x3 grid when using the default 12 panels, bold black frame borders, actual drawings black and white graphite 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
+- annotation grammar: annotations only may use color; red movement arrows = movement, blue notes = breath/camera/tempo cue, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
+- visible sheet text: panel labels, short titles, one action line, `CAM:` line, `NOTES`, and `LEGEND` are allowed on the storyboard sheet; timestamps are forbidden
 - 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.
@@ -62,6 +64,8 @@ Use it for composition, blocking, camera angle, action progression, visual rhyth
 
 - Character identity always wins over storyboard character design.
 - Storyboard text, labels, watermarks, logos, and panel borders are never copied into the video.
+- If the brief contains a complete 1-12 numbered frame list, preserve the user's panel titles, action beats, and camera cues in the storyboard prompt.
+- If the brief does not contain a complete frame list, generate a deterministic 12-beat sheet: start pose, shared intent, first motion, build action, camera shift, flow/contact, insert/detail, peak motion, breath/reaction, final approach, resolved emotion, success/final pose.
 - 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.
@@ -80,6 +84,9 @@ Seedance 2.0:
 - 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.
+- Include `[STORYBOARD 12-BEAT ORDER]` for default sheets and list Frame 001-012 with title, action, camera, and phase mapping.
+- In multi-shot storyboard mode, render as 12 distinct micro-shots / fast motion snapshots. Do not smooth the storyboard into one continuous generic action. Each beat must visibly change pose, camera framing, and movement state.
+- Use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats. For 8s+ videos, hold the final beat for the last 1.0 seconds; for shorter videos, hold it for the last 0.5 seconds.
 - 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.
@@ -111,7 +118,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
-- storyboard_creation metadata in `SHOTNN.bundle.json`
+- storyboard_creation metadata in `SHOTNN.bundle.json`, including `panel_beats`
 - audio plan
 - prompt bundle for requested models
 - QA verdict

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

@@ -38,6 +38,9 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
    - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
+   - default storyboard sheet uses `Frames 001-012` in a 4x3 grid
+   - every panel must have a visible frame label, short title, one action line, and `CAM:` line
+   - if the brief includes a full 1-12 frame list, preserve those titles/actions/camera cues; otherwise generate deterministic start-pose-to-final-pose beats
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,11 +51,14 @@ 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
+   - enforce cream/off-white paper, black-and-white rough graphite production storyboard artwork, and bold black frame borders; only annotation arrows/marks/notes may use color
+   - include `NOTES` and `LEGEND`; red movement arrows and blue notes are allowed as planning annotations only; no timestamps
    - 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
+   - Seedance multi-shot prompts include `[STORYBOARD 12-BEAT ORDER]`, render 12 distinct micro-shots / fast motion snapshots, avoid smoothing into one generic action, and use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats
+   - Seedance continuous-shot prompts keep the same beat order inside one uninterrupted camera move and reserve `No scene cuts throughout` for true single-shot mode only
    - Veo visual-planning prompt with full audio direction
    - Kling block-structured storyboard route
 8. Run QA gates:

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

@@ -37,13 +37,15 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
 - 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
+- structured panel beats: every storyboard prompt must carry a numbered panel beat plan with `Frame 001`-style IDs, short titles, action lines, `CAM:` lines, annotation cues, and phase mapping
 - 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: 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
+- storyboard art grammar: cream/off-white paper 16:9 production storyboard sheet, 4x3 grid when using the default 12 panels, bold black frame borders, actual drawings black and white graphite 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
+- annotation grammar: annotations only may use color; red movement arrows = movement, blue notes = breath/camera/tempo cue, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
+- visible sheet text: panel labels, short titles, one action line, `CAM:` line, `NOTES`, and `LEGEND` are allowed on the storyboard sheet; timestamps are forbidden
 - 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.
@@ -62,6 +64,8 @@ Use it for composition, blocking, camera angle, action progression, visual rhyth
 
 - Character identity always wins over storyboard character design.
 - Storyboard text, labels, watermarks, logos, and panel borders are never copied into the video.
+- If the brief contains a complete 1-12 numbered frame list, preserve the user's panel titles, action beats, and camera cues in the storyboard prompt.
+- If the brief does not contain a complete frame list, generate a deterministic 12-beat sheet: start pose, shared intent, first motion, build action, camera shift, flow/contact, insert/detail, peak motion, breath/reaction, final approach, resolved emotion, success/final pose.
 - 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.
@@ -80,6 +84,9 @@ Seedance 2.0:
 - 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.
+- Include `[STORYBOARD 12-BEAT ORDER]` for default sheets and list Frame 001-012 with title, action, camera, and phase mapping.
+- In multi-shot storyboard mode, render as 12 distinct micro-shots / fast motion snapshots. Do not smooth the storyboard into one continuous generic action. Each beat must visibly change pose, camera framing, and movement state.
+- Use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats. For 8s+ videos, hold the final beat for the last 1.0 seconds; for shorter videos, hold it for the last 0.5 seconds.
 - 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.
@@ -111,7 +118,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
-- storyboard_creation metadata in `SHOTNN.bundle.json`
+- storyboard_creation metadata in `SHOTNN.bundle.json`, including `panel_beats`
 - audio plan
 - prompt bundle for requested models
 - QA verdict

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

@@ -38,6 +38,9 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
    - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
+   - default storyboard sheet uses `Frames 001-012` in a 4x3 grid
+   - every panel must have a visible frame label, short title, one action line, and `CAM:` line
+   - if the brief includes a full 1-12 frame list, preserve those titles/actions/camera cues; otherwise generate deterministic start-pose-to-final-pose beats
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,11 +51,14 @@ 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
+   - enforce cream/off-white paper, black-and-white rough graphite production storyboard artwork, and bold black frame borders; only annotation arrows/marks/notes may use color
+   - include `NOTES` and `LEGEND`; red movement arrows and blue notes are allowed as planning annotations only; no timestamps
    - 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
+   - Seedance multi-shot prompts include `[STORYBOARD 12-BEAT ORDER]`, render 12 distinct micro-shots / fast motion snapshots, avoid smoothing into one generic action, and use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats
+   - Seedance continuous-shot prompts keep the same beat order inside one uninterrupted camera move and reserve `No scene cuts throughout` for true single-shot mode only
    - Veo visual-planning prompt with full audio direction
    - Kling block-structured storyboard route
 8. Run QA gates:

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

@@ -37,13 +37,15 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
 - 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
+- structured panel beats: every storyboard prompt must carry a numbered panel beat plan with `Frame 001`-style IDs, short titles, action lines, `CAM:` lines, annotation cues, and phase mapping
 - 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: 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
+- storyboard art grammar: cream/off-white paper 16:9 production storyboard sheet, 4x3 grid when using the default 12 panels, bold black frame borders, actual drawings black and white graphite 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
+- annotation grammar: annotations only may use color; red movement arrows = movement, blue notes = breath/camera/tempo cue, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
+- visible sheet text: panel labels, short titles, one action line, `CAM:` line, `NOTES`, and `LEGEND` are allowed on the storyboard sheet; timestamps are forbidden
 - 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.
@@ -62,6 +64,8 @@ Use it for composition, blocking, camera angle, action progression, visual rhyth
 
 - Character identity always wins over storyboard character design.
 - Storyboard text, labels, watermarks, logos, and panel borders are never copied into the video.
+- If the brief contains a complete 1-12 numbered frame list, preserve the user's panel titles, action beats, and camera cues in the storyboard prompt.
+- If the brief does not contain a complete frame list, generate a deterministic 12-beat sheet: start pose, shared intent, first motion, build action, camera shift, flow/contact, insert/detail, peak motion, breath/reaction, final approach, resolved emotion, success/final pose.
 - 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.
@@ -80,6 +84,9 @@ Seedance 2.0:
 - 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.
+- Include `[STORYBOARD 12-BEAT ORDER]` for default sheets and list Frame 001-012 with title, action, camera, and phase mapping.
+- In multi-shot storyboard mode, render as 12 distinct micro-shots / fast motion snapshots. Do not smooth the storyboard into one continuous generic action. Each beat must visibly change pose, camera framing, and movement state.
+- Use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats. For 8s+ videos, hold the final beat for the last 1.0 seconds; for shorter videos, hold it for the last 0.5 seconds.
 - 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.
@@ -111,7 +118,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
-- storyboard_creation metadata in `SHOTNN.bundle.json`
+- storyboard_creation metadata in `SHOTNN.bundle.json`, including `panel_beats`
 - audio plan
 - prompt bundle for requested models
 - QA verdict

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

@@ -38,6 +38,9 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
    - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
+   - default storyboard sheet uses `Frames 001-012` in a 4x3 grid
+   - every panel must have a visible frame label, short title, one action line, and `CAM:` line
+   - if the brief includes a full 1-12 frame list, preserve those titles/actions/camera cues; otherwise generate deterministic start-pose-to-final-pose beats
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,11 +51,14 @@ 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
+   - enforce cream/off-white paper, black-and-white rough graphite production storyboard artwork, and bold black frame borders; only annotation arrows/marks/notes may use color
+   - include `NOTES` and `LEGEND`; red movement arrows and blue notes are allowed as planning annotations only; no timestamps
    - 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
+   - Seedance multi-shot prompts include `[STORYBOARD 12-BEAT ORDER]`, render 12 distinct micro-shots / fast motion snapshots, avoid smoothing into one generic action, and use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats
+   - Seedance continuous-shot prompts keep the same beat order inside one uninterrupted camera move and reserve `No scene cuts throughout` for true single-shot mode only
    - Veo visual-planning prompt with full audio direction
    - Kling block-structured storyboard route
 8. Run QA gates:

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

@@ -37,13 +37,15 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
 - 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
+- structured panel beats: every storyboard prompt must carry a numbered panel beat plan with `Frame 001`-style IDs, short titles, action lines, `CAM:` lines, annotation cues, and phase mapping
 - 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: 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
+- storyboard art grammar: cream/off-white paper 16:9 production storyboard sheet, 4x3 grid when using the default 12 panels, bold black frame borders, actual drawings black and white graphite 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
+- annotation grammar: annotations only may use color; red movement arrows = movement, blue notes = breath/camera/tempo cue, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
+- visible sheet text: panel labels, short titles, one action line, `CAM:` line, `NOTES`, and `LEGEND` are allowed on the storyboard sheet; timestamps are forbidden
 - 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.
@@ -62,6 +64,8 @@ Use it for composition, blocking, camera angle, action progression, visual rhyth
 
 - Character identity always wins over storyboard character design.
 - Storyboard text, labels, watermarks, logos, and panel borders are never copied into the video.
+- If the brief contains a complete 1-12 numbered frame list, preserve the user's panel titles, action beats, and camera cues in the storyboard prompt.
+- If the brief does not contain a complete frame list, generate a deterministic 12-beat sheet: start pose, shared intent, first motion, build action, camera shift, flow/contact, insert/detail, peak motion, breath/reaction, final approach, resolved emotion, success/final pose.
 - 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.
@@ -80,6 +84,9 @@ Seedance 2.0:
 - 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.
+- Include `[STORYBOARD 12-BEAT ORDER]` for default sheets and list Frame 001-012 with title, action, camera, and phase mapping.
+- In multi-shot storyboard mode, render as 12 distinct micro-shots / fast motion snapshots. Do not smooth the storyboard into one continuous generic action. Each beat must visibly change pose, camera framing, and movement state.
+- Use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats. For 8s+ videos, hold the final beat for the last 1.0 seconds; for shorter videos, hold it for the last 0.5 seconds.
 - 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.
@@ -111,7 +118,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
-- storyboard_creation metadata in `SHOTNN.bundle.json`
+- storyboard_creation metadata in `SHOTNN.bundle.json`, including `panel_beats`
 - audio plan
 - prompt bundle for requested models
 - QA verdict

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

@@ -38,6 +38,9 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - 7-10 seconds: 2-3 video phases
    - 11-15 seconds: 3-4 video phases
    - GPT Image 2 storyboard sheet defaults to 12 panels; explicit panel hints may request 1-12 panels
+   - default storyboard sheet uses `Frames 001-012` in a 4x3 grid
+   - every panel must have a visible frame label, short title, one action line, and `CAM:` line
+   - if the brief includes a full 1-12 frame list, preserve those titles/actions/camera cues; otherwise generate deterministic start-pose-to-final-pose beats
    - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
@@ -48,11 +51,14 @@ 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
+   - enforce cream/off-white paper, black-and-white rough graphite production storyboard artwork, and bold black frame borders; only annotation arrows/marks/notes may use color
+   - include `NOTES` and `LEGEND`; red movement arrows and blue notes are allowed as planning annotations only; no timestamps
    - 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
+   - Seedance multi-shot prompts include `[STORYBOARD 12-BEAT ORDER]`, render 12 distinct micro-shots / fast motion snapshots, avoid smoothing into one generic action, and use quick cuts, match cuts, whip transitions, and motivated camera jumps between beats
+   - Seedance continuous-shot prompts keep the same beat order inside one uninterrupted camera move and reserve `No scene cuts throughout` for true single-shot mode only
    - Veo visual-planning prompt with full audio direction
    - Kling block-structured storyboard route
 8. Run QA gates: