@milenyumai/film-kit 2.0.1 → 2.2.0

package/README.md

@@ -44,22 +44,29 @@ Initialize a project with one of the supported presets:
 npx @milenyumai/film-kit init --preset single --model veo31
 npx @milenyumai/film-kit init --preset single --model seedance-2.0
 npx @milenyumai/film-kit init --preset multi --model kling-3.0 --kling-preset ultra-realism
-npx @milenyumai/film-kit init --preset hybrid --aspect 16:9 --nano-size 4K
-npx @milenyumai/film-kit init --preset hybrid-smart --kling-preset balanced
-npx @milenyumai/film-kit init --preset studio --model seedance-2.0 --refs-dir ./refs
+npx @milenyumai/film-kit init --preset studio --model seedance-2.0 --reference-mode storyboard-reference --refs-dir ./refs
+npx @milenyumai/film-kit init --preset hybrid --aspect 16:9 --nano-size 4K --gpt-image-size 2048x1152
+npx @milenyumai/film-kit init --preset hybrid-smart --kling-preset balanced --gpt-image-quality medium
+npx @milenyumai/film-kit init --preset gpt-image-smart --gpt-image-size 2048x1152 --gpt-image-quality medium
+npx @milenyumai/film-kit init --preset studio --model seedance-2.0 --refs-dir ./refs --gpt-image-format png
 ```
 
 After the first run, Film-Kit writes `film-kit.config.json` and uses that file as the canonical project configuration.
 
+In Codex-enabled projects, all presets now include an optional `/codex-images` still phase after a successful `/generate`. It is always opt-in and never auto-starts.
+
+Storyboard-reference prompt generation is also available when you have a character reference image, storyboard reference image, and brief. It produces model-specific prompt bundles without requiring start/end frames.
+
 ## Presets
 
 | Preset | Purpose | Supported video model surface | Default notes |
 |---|---|---|---|
 | `single` | Single-agent prompt runtime | `veo31`, `kling-3.0`, `seedance-2.0` | Defaults to all supported platforms |
 | `multi` | Lead-directed multi-agent shot generation | `veo31`, `kling-3.0`, `seedance-2.0` | Defaults to `maxTeammates=5`, `batchSize=4` |
-| `hybrid` | Nano Banana still generation + fixed Kling video runtime | fixed `kling-3.0` | No `--model` flag |
-| `hybrid-smart` | Nano Banana still generation + dialogue-aware Veo/Kling routing | fixed smart route | No `--model` flag |
-| `studio` | Scenario-to-render pipeline with render-stage configuration | `veo31`, `kling-3.0`, `seedance-2.0` | Includes refs dir and fal model configuration |
+| `hybrid` | Nano Banana still generation + GPT Image 2 companion metadata + fixed Kling video runtime | fixed `kling-3.0` | No `--model` flag |
+| `hybrid-smart` | Nano Banana still generation + GPT Image 2 companion metadata + dialogue-aware Veo/Kling routing | fixed smart route | No `--model` flag |
+| `gpt-image-smart` | GPT Image 2 still generation + dialogue-aware Veo/Kling routing | fixed smart route | Defaults to `size=2048x1152`, `quality=medium`, `format=png` |
+| `studio` | Scenario-to-render pipeline with fal.ai render-stage configuration plus GPT Image 2 companion metadata | `veo31`, `kling-3.0`, `seedance-2.0` | Includes refs dir and fal model configuration |
 
 ## Model Support
 
@@ -85,15 +92,25 @@ After the first run, Film-Kit writes `film-kit.config.json` and uses that file a
 - Supported in `single`, `multi`, and `studio`
 - Fixed inside `hybrid`
 - Part of the router inside `hybrid-smart`
+- Part of the router inside `gpt-image-smart`
 - Uses Kling-specific Start+End / storyboard prompt structure
 
+### `gpt-image-2`
+
+- Supported as the still-image engine in `gpt-image-smart`
+- Supported as companion still prompt/API metadata in `hybrid`, `hybrid-smart`, and `studio`
+- Used for `ILK/İLK FRAME`, `SON FRAME`, and still coverage prompt sections
+- Default Image API metadata: `size=2048x1152`, `quality=medium`, `format=png`
+- V1 emits prompt/API command metadata only; it does not execute OpenAI SDK calls
+- Transparent backgrounds are not exposed because GPT Image 2 does not support them in these presets
+
 ### `kling-preset`
 
 `preset` and `kling-preset` are different things:
 
 - `preset` selects the Film-Kit product mode
 - `kling-preset` selects Kling quality behavior
-- `kling-preset` only applies when the active video model is `kling-3.0`
+- `kling-preset` applies when the active video model is `kling-3.0`, including Kling-routed sections inside smart presets
 
 Supported `kling-preset` values:
 
@@ -103,12 +120,41 @@ Supported `kling-preset` values:
 
 When the active model is not Kling, generated runtime files intentionally render the Kling preset as `n/a (Kling-only)`.
 
+## Storyboard Reference Mode
+
+Use this mode when the source material is a character reference image plus a storyboard image rather than explicit start/end frames.
+
+```bash
+npx @milenyumai/film-kit generate-storyboard \
+  --character-ref ./refs/character.png \
+  --storyboard-ref ./refs/storyboard.png \
+  --brief ./scenario.md \
+  --models veo31,seedance-2.0,kling-3.0 \
+  --duration 8 \
+  --aspect 16:9 \
+  --output-dir ./outputs
+```
+
+Outputs:
+
+- `outputs/storyboard-reference-plan.json`
+- `outputs/prompt-bundles/SHOTNN.bundle.json`
+- `outputs/shots/SHOTNN.md`
+- `outputs/reports/STORYBOARD-REFERENCE-QA.md`
+
+Rules:
+
+- `@character1` is the identity lock.
+- `@storyboard1` controls composition, blocking, camera, timing, and editorial phase order only.
+- 5+ storyboard phases are split into multiple `SHOTNN.md` files.
+- Existing start/end workflows stay unchanged and remain the default.
+
 ## CLI
 
 Base command:
 
 ```bash
-npx @milenyumai/film-kit init --preset single|multi|hybrid|hybrid-smart|studio
+npx @milenyumai/film-kit init --preset single|multi|hybrid|hybrid-smart|gpt-image-smart|studio
 ```
 
 Help:
@@ -122,10 +168,12 @@ Examples:
 ```bash
 npx @milenyumai/film-kit init --preset single --model veo31
 npx @milenyumai/film-kit init --preset single --model seedance-2.0 --platforms cursor,claude,codex
+npx @milenyumai/film-kit init --preset studio --reference-mode storyboard-reference --max-storyboard-phases 4
 npx @milenyumai/film-kit init --preset multi --model seedance-2.0 --max-teammates 5 --batch-size 4
 npx @milenyumai/film-kit init --preset multi --model kling-3.0 --kling-preset balanced
 npx @milenyumai/film-kit init --preset hybrid --kling-preset ultra-realism --aspect 16:9 --nano-size 2K
 npx @milenyumai/film-kit init --preset hybrid-smart --aspect 9:16 --max-kling-custom-shots 4
+npx @milenyumai/film-kit init --preset gpt-image-smart --aspect 16:9 --gpt-image-size 2048x1152 --gpt-image-quality high --gpt-image-format png
 npx @milenyumai/film-kit init --preset studio --model seedance-2.0 --refs-dir ./refs
 npx @milenyumai/film-kit init --preset studio --model kling-3.0 --fal-video-model fal-ai/kling-video/v3/pro/image-to-video
 npx @milenyumai/film-kit init --preset single --overwrite
@@ -140,27 +188,34 @@ npx @milenyumai/film-kit init --preset single --overwrite
 | `--scenario-hint` | Scenario file hint. Default: `scenario.md` |
 | `--scenario` | Alias of `--scenario-hint` |
 | `--overwrite`, `-f` | Overwrite existing runtime files |
+| `--reference-mode` | `start-end`, `storyboard-reference`, or `hybrid`. Default: `start-end` |
+| `--max-storyboard-phases` | Storyboard-reference phase cap per prompt. Default: `4` |
 
 ### Preset-Specific Flags
 
 | Preset | Allowed flags |
 |---|---|
-| `single` | `--model`, `--kling-preset`, `--platforms` |
-| `multi` | `--model`, `--kling-preset`, `--max-teammates`, `--batch-size` |
-| `hybrid` | `--kling-preset`, `--aspect`, `--nano-size`, `--platforms` |
-| `hybrid-smart` | `--kling-preset`, `--aspect`, `--nano-size`, `--max-kling-custom-shots`, `--platforms` |
-| `studio` | `--model`, `--kling-preset`, `--max-teammates`, `--batch-size`, `--refs-dir`, `--fal-image-model`, `--fal-video-model`, `--platforms` |
+| `single` | `--model`, `--kling-preset`, `--platforms`, `--reference-mode`, `--max-storyboard-phases` |
+| `multi` | `--model`, `--kling-preset`, `--max-teammates`, `--batch-size`, `--reference-mode`, `--max-storyboard-phases` |
+| `hybrid` | `--kling-preset`, `--aspect`, `--nano-size`, `--gpt-image-size`, `--gpt-image-quality`, `--gpt-image-format`, `--platforms`, `--reference-mode`, `--max-storyboard-phases` |
+| `hybrid-smart` | `--kling-preset`, `--aspect`, `--nano-size`, `--gpt-image-size`, `--gpt-image-quality`, `--gpt-image-format`, `--max-kling-custom-shots`, `--platforms`, `--reference-mode`, `--max-storyboard-phases` |
+| `gpt-image-smart` | `--kling-preset`, `--aspect`, `--gpt-image-size`, `--gpt-image-quality`, `--gpt-image-format`, `--max-kling-custom-shots`, `--platforms`, `--reference-mode`, `--max-storyboard-phases` |
+| `studio` | `--model`, `--kling-preset`, `--max-teammates`, `--batch-size`, `--refs-dir`, `--fal-image-model`, `--fal-video-model`, `--gpt-image-size`, `--gpt-image-quality`, `--gpt-image-format`, `--platforms`, `--reference-mode`, `--max-storyboard-phases` |
 
 ### Supported Flag Values
 
 | Flag | Supported values |
 |---|---|
-| `--preset` | `single`, `multi`, `hybrid`, `hybrid-smart`, `studio` |
+| `--preset` | `single`, `multi`, `hybrid`, `hybrid-smart`, `gpt-image-smart`, `studio` |
 | `--model` | `veo31`, `kling-3.0`, `seedance-2.0` |
 | `--kling-preset` | `ultra-realism`, `balanced`, `custom` |
 | `--aspect` | `16:9`, `9:16`, `1:1` |
 | `--nano-size` | `1K`, `2K`, `4K` |
+| `--gpt-image-size` | `auto` or `WIDTHxHEIGHT` where both edges are multiples of 16, max edge <= 3840, ratio <= 3:1, and total pixels stay within GPT Image 2 limits |
+| `--gpt-image-quality` | `low`, `medium`, `high`, `auto` |
+| `--gpt-image-format` | `png`, `jpeg`, `webp` |
 | `--platforms` | `cursor`, `claude`, `copilot`, `antigravity`, `codex` |
+| `--reference-mode` | `start-end`, `storyboard-reference`, `hybrid` |
 
 ## Canonical Config
 
@@ -175,12 +230,23 @@ Example:
   "scenarioHint": "scenario.md",
   "platforms": ["cursor", "claude", "copilot", "antigravity", "codex"],
   "model": "seedance-2.0",
+  "referenceMode": "storyboard-reference",
+  "storyboardReferenceMode": {
+    "enabled": true,
+    "maxStoryboardPhases": 4,
+    "generateAllModelPrompts": true,
+    "strictReferenceLock": true,
+    "splitStoryboardOverload": true
+  },
   "klingPreset": "ultra-realism",
   "maxTeammates": 5,
   "batchSize": 4,
   "refsDir": "./refs",
   "falImageModel": "fal-ai/nano-banana-2/edit",
   "falVideoModel": "fal-ai/kling-video/v3/pro/image-to-video",
+  "gptImageSize": "2048x1152",
+  "gptImageQuality": "medium",
+  "gptImageFormat": "png",
   "includeAgentsMd": true,
   "copyContent": true
 }
@@ -188,24 +254,29 @@ Example:
 
 ### Config Field Support Matrix
 
-| Field | `single` | `multi` | `hybrid` | `hybrid-smart` | `studio` |
-|---|---|---|---|---|---|
-| `preset` | yes | yes | yes | yes | yes |
-| `outputDir` | yes | yes | yes | yes | yes |
-| `scenarioHint` | yes | yes | yes | yes | yes |
-| `platforms` | yes | no | yes | yes | yes |
-| `model` | yes | yes | no | no | yes |
-| `klingPreset` | yes | yes | yes | yes | yes |
-| `maxTeammates` | no | yes | no | no | yes |
-| `batchSize` | no | yes | no | no | yes |
-| `defaultAspectRatio` | no | no | yes | yes | no |
-| `nanoBananaImageSize` | no | no | yes | yes | no |
-| `maxKlingCustomShots` | no | no | no | yes | no |
-| `refsDir` | no | no | no | no | yes |
-| `falImageModel` | no | no | no | no | yes |
-| `falVideoModel` | no | no | no | no | yes |
-| `includeAgentsMd` | yes | yes | yes | yes | yes |
-| `copyContent` | yes | yes | yes | yes | yes |
+| Field | `single` | `multi` | `hybrid` | `hybrid-smart` | `gpt-image-smart` | `studio` |
+|---|---|---|---|---|---|---|
+| `preset` | yes | yes | yes | yes | yes | yes |
+| `outputDir` | yes | yes | yes | yes | yes | yes |
+| `scenarioHint` | yes | yes | yes | yes | yes | yes |
+| `platforms` | yes | no | yes | yes | yes | yes |
+| `model` | yes | yes | no | no | no | yes |
+| `referenceMode` | yes | yes | yes | yes | yes | yes |
+| `storyboardReferenceMode` | yes | yes | yes | yes | yes | yes |
+| `klingPreset` | yes | yes | yes | yes | yes | yes |
+| `maxTeammates` | no | yes | no | no | no | yes |
+| `batchSize` | no | yes | no | no | no | yes |
+| `defaultAspectRatio` | no | no | yes | yes | yes | no |
+| `nanoBananaImageSize` | no | no | yes | yes | no | no |
+| `gptImageSize` | no | no | yes | yes | yes | yes |
+| `gptImageQuality` | no | no | yes | yes | yes | yes |
+| `gptImageFormat` | no | no | yes | yes | yes | yes |
+| `maxKlingCustomShots` | no | no | no | yes | yes | no |
+| `refsDir` | no | no | no | no | no | yes |
+| `falImageModel` | no | no | no | no | no | yes |
+| `falVideoModel` | no | no | no | no | no | yes |
+| `includeAgentsMd` | yes | yes | yes | yes | yes | yes |
+| `copyContent` | yes | yes | yes | yes | yes | yes |
 
 ## Legacy Config Migration
 
@@ -215,6 +286,7 @@ Film-Kit automatically detects and migrates one existing legacy config file on f
 - `film-kit-multi.config.json`
 - `film-kit-hybrid.config.json`
 - `film-kit-hybrid-smart.config.json`
+- `film-kit-gpt-image-smart.config.json`
 - `film-kit-studio.config.json`
 
 Migration behavior:
@@ -238,13 +310,14 @@ Film-Kit writes repo-scoped runtime files for supported editors and agents. Depe
 - `.cursor/`
 - `.github/copilot-instructions.md`
 - `AGENTS.md`
-- runtime workflows such as `generate`, `chain`, `safety-check`, `recover`, `finish`
+- runtime workflows such as `generate`, `generate-storyboard`, `codex-images`, `chain`, `safety-check`, `recover`, `finish`
 
 Editorial/runtime contract shared across the package:
 
 - one file per shot: `SHOTNN.md`
 - coverage lives inside the same shot file
 - report files live under `reports/`
+- optional Codex still outputs live under `codex-images/` with `manifest.json` and `reports/CODEX-IMAGE-REPORT.md`
 - continuity and first-frame chaining are explicit
 - voice design uses top-level `voiceCast`
 - per-shot sound control uses `Audio Plan`
@@ -254,7 +327,7 @@ Editorial/runtime contract shared across the package:
 
 When a reference image exists, Film-Kit now treats it as an immutable source, not a loose style hint.
 
-Default behavior across `single`, `multi`, `hybrid`, `hybrid-smart`, and `studio`:
+Default behavior across `single`, `multi`, `hybrid`, `hybrid-smart`, `gpt-image-smart`, and `studio`:
 
 - face, hair, skin tone, body proportions, wardrobe, accessories, props, materials, patterns, and logos are treated as locked invariants
 - generated prompts should not re-describe identity details already visible in the reference
@@ -286,7 +359,7 @@ This means:
 - old image-quality heuristics based on minimum word counts are no longer the primary control surface
 - detailed prose is still expected for video prompts, where motion, timing, audio, and camera language need richer direction
 
-`hybrid` and `hybrid-smart` keep their compact still-prompt behavior. `single`, `multi`, and `studio` keep richer video prompt behavior for Veo, Kling, and Seedance.
+`hybrid`, `hybrid-smart`, and `gpt-image-smart` keep structured still-prompt behavior. `single`, `multi`, and `studio` keep richer video prompt behavior for Veo, Kling, and Seedance.
 
 ## Semantic QA And Render QA
 
@@ -383,6 +456,9 @@ Supported postinstall environment variables:
 - `FILM_KIT_KLING_PRESET`
 - `FILM_KIT_HYBRID_ASPECT`
 - `FILM_KIT_HYBRID_IMAGE_SIZE`
+- `FILM_KIT_GPT_IMAGE_SIZE`
+- `FILM_KIT_GPT_IMAGE_QUALITY`
+- `FILM_KIT_GPT_IMAGE_FORMAT`
 - `FILM_KIT_MAX_TEAMMATES`
 - `FILM_KIT_BATCH_SIZE`
 - `FILM_KIT_MAX_KLING_CUSTOM_SHOTS`
@@ -403,6 +479,7 @@ Internal preset source layout:
 - `packages/multi`
 - `packages/hybrid`
 - `packages/hybrid-smart`
+- `packages/gpt-image-smart`
 - `packages/studio`
 
 These subpackages are marked `private: true` and are bundled as internal sources for the root package build and tarball.

package/build/cli.js

@@ -1,13 +1,29 @@
 #!/usr/bin/env node
 import { parseCliCommand, renderCliUsage } from "./lib/cli.js";
 import { configureFilmKit } from "./lib/film-kit.js";
+import { buildStoryboardReferencePromptBundles, writeStoryboardReferenceOutputs } from "./lib/storyboard-reference/index.js";
 const args = process.argv.slice(2);
 try {
     const parsed = await parseCliCommand(args, process.cwd());
-    if (parsed.command === "help" || !parsed.options) {
+    if (parsed.command === "help") {
         console.log(renderCliUsage());
         process.exit(0);
     }
+    if (parsed.command === "generate-storyboard") {
+        if (!parsed.storyboardRequest) {
+            throw new Error("Missing generate-storyboard request.");
+        }
+        console.log("🎬 Film-Kit: Generating storyboard-reference prompt bundle...\n");
+        const buildResult = buildStoryboardReferencePromptBundles(parsed.storyboardRequest);
+        const writeResult = await writeStoryboardReferenceOutputs(buildResult, process.cwd());
+        console.log(`✅ Files written: ${writeResult.written.length}`);
+        writeResult.written.forEach(file => console.log(`   ${file}`));
+        console.log(`\n🎬 Done! Storyboard-reference outputs are ready in ${writeResult.rootDir}\n`);
+        process.exit(0);
+    }
+    if (!parsed.options) {
+        throw new Error("Missing init options.");
+    }
     console.log(`🎬 Film-Kit: Configuring '${parsed.options.preset}' preset...\n`);
     const result = await configureFilmKit(parsed.options);
     if (result.written.length > 0) {

package/build/index.d.ts

@@ -1,3 +1,5 @@
 export { configureFilmKit, detectFilmKitPreset, FILM_KIT_CONFIG_FILE, FILM_KIT_PRESETS, LEGACY_CONFIG_FILES } from "./lib/film-kit.js";
 export { configureAgents } from "./lib/configure.js";
-export type { AgentConfigOptions, ConfigureFilmKitResult, ConfigureResult, FilmKitConfigFile, FilmKitConfigOptions, FilmKitPreset, HybridAspectRatio, KlingPreset, NanoBananaImageSize, SupportedModel, SupportedPlatform } from "./lib/types.js";
+export { buildStoryboardReferencePromptBundles, normalizeVideoPromptRequest, renderShotMarkdown, writeStoryboardReferenceOutputs } from "./lib/storyboard-reference/index.js";
+export type { AgentConfigOptions, ConfigureFilmKitResult, ConfigureResult, FilmKitConfigFile, FilmKitConfigOptions, FilmKitPreset, GptImageFormat, GptImageQuality, GptImageSize, HybridAspectRatio, KlingPreset, NanoBananaImageSize, ReferenceMode, StoryboardReferenceConfig, SupportedModel, SupportedPlatform } from "./lib/types.js";
+export type { ModelPromptOutput, PromptBundle, ReferenceAsset, StoryboardReferenceBuildResult, StoryboardReferenceWriteResult, VideoPromptRequest } from "./lib/storyboard-reference/index.js";

package/build/index.js

@@ -1,2 +1,3 @@
 export { configureFilmKit, detectFilmKitPreset, FILM_KIT_CONFIG_FILE, FILM_KIT_PRESETS, LEGACY_CONFIG_FILES } from "./lib/film-kit.js";
 export { configureAgents } from "./lib/configure.js";
+export { buildStoryboardReferencePromptBundles, normalizeVideoPromptRequest, renderShotMarkdown, writeStoryboardReferenceOutputs } from "./lib/storyboard-reference/index.js";

package/build/lib/cli.d.ts

@@ -1,7 +1,9 @@
+import type { VideoPromptRequest } from "./storyboard-reference/index.js";
 import type { FilmKitConfigOptions } from "./types.js";
 export interface ParsedCliCommand {
-    command: "init" | "help";
+    command: "init" | "generate-storyboard" | "help";
     options?: FilmKitConfigOptions;
+    storyboardRequest?: VideoPromptRequest;
 }
 export declare function parseCliCommand(args: string[], rootDir?: string): Promise<ParsedCliCommand>;
 export declare function renderCliUsage(): string;