@milenyumai/film-kit 2.3.3 → 2.3.5

package/MODEL_REGISTRY.md

@@ -0,0 +1,136 @@
+# Film-Kit Model Registry
+
+Film-Kit model metadata is centralized in `src/lib/model-registry/*`.
+
+The registry is TypeScript `as const` metadata, not dynamic JSON. It is the canonical source for model identity, lifecycle, preset compatibility, reference-mode compatibility, capabilities, routing role, prompt grammar key, model profile key, and storyboard adapter resolution.
+
+Long prompt grammar, runtime profile prose, production guidance, and generated workflow text stay in the existing template, adapter, skill, and model-profile layers.
+
+## Discovery Summary
+
+Phase 0 found model ids in four broad surfaces:
+
+- Root validation and runtime selection: `src/lib/types.ts`, `src/lib/defaults.ts`, `src/lib/configure.ts`, `src/lib/cli.ts`, and `src/lib/film-kit.ts`.
+- Storyboard-reference routing: `src/lib/storyboard-reference/defaults.ts`, `request-normalizer.ts`, `prompt-bundle-builder.ts`, and `adapters/*`.
+- Internal preset packages: `packages/*/src/lib/*`, where model ids still appear in private preset defaults, templates, and generated runtime prose.
+- Public/user-facing prose and assertions: `README.md`, `content/*`, `packages/*/content/*`, and tests.
+
+Phase 1 moved the root runtime, CLI/config validation, `generate-storyboard --models`, storyboard-reference target validation, display-name lookup, default storyboard model list, and adapter resolution onto the registry.
+
+Phase 2 intentionally does not import the root registry directly from `packages/*`: package `tsconfig.json` files use `rootDir: src`, and the internal package sources remain private preset implementations. Public usage is guarded through the root dispatcher and root CLI.
+
+Remaining hardcoded model names in templates, content, and tests are prompt grammar, generated docs, explicit examples, or compatibility assertions rather than canonical validation sources.
+
+## Files
+
+- `src/lib/model-registry/types.ts` defines registry metadata shapes.
+- `src/lib/model-registry/registry.ts` owns the canonical model entries.
+- `src/lib/model-registry/selectors.ts` exposes lookup and selector helpers.
+- `src/lib/model-registry/validation.ts` owns fail-closed model validation.
+- `src/lib/model-registry/index.ts` is the public registry API barrel.
+
+## Public API
+
+- `getModel(id)`
+- `requireModel(id)`
+- `listModels()`
+- `listActiveModels()`
+- `listVideoModels()`
+- `listImageModels()`
+- `listActiveVideoModelIds()`
+- `listRunnableVideoModels()`
+- `listRunnableVideoModelIds()`
+- `listModelsForPreset(preset)`
+- `listModelsForReferenceMode(referenceMode)`
+- `isKnownModelId(value)`
+- `isActiveModelId(value)`
+- `isDeprecatedModelId(value)`
+- `isRemovedModelId(value)`
+- `isVideoModelId(value)`
+- `isImageModelId(value)`
+- `isModelSupportedByPreset(modelId, preset)`
+- `getModelAdapterKey(modelId)`
+- `getModelDisplayName(modelId)`
+- `getReplacementModel(modelId)`
+- `assertModelAllowed(modelId, context)`
+- `validateModelAllowed(modelId, context)`
+
+## Lifecycle Rules
+
+- `active`: accepted normally.
+- `experimental`: accepted normally, but may be surfaced as internal or preview metadata.
+- `deprecated`: accepted, emits an explicit warning, and should define `replacementModelId` when possible.
+- `removed`: fail-closed. Removed models must never silently fall back.
+
+## Adapter Routing
+
+Storyboard-reference video prompt routing resolves through `adapterKey`.
+
+- `veo31` -> Veo adapter
+- `seedance20` -> Seedance 2.0 adapter
+- `kling30` -> Kling 3.0 adapter
+- `generic` -> generic adapter, allowed only when the registry entry explicitly selects it
+- `none`, `gptImage2` -> not valid for video storyboard adapter routing
+
+Unknown model strings never receive a generic fallback.
+
+## Adding A Video Model
+
+1. Add one entry in `src/lib/model-registry/registry.ts`.
+2. Choose `modalities: ["video"]`.
+3. Set `lifecycleStatus`.
+4. Set `supportedPresets`.
+5. Set `supportedReferenceModes`.
+6. Set `supportedAspects`.
+7. Add `durationRange` or `durationPolicy`.
+8. Choose an existing `adapterKey` or add a new adapter.
+9. Set `promptGrammarKey` and `modelProfileKey`.
+10. Fill `routingRole` and `capabilities`.
+11. Add registry selector/validation tests.
+12. Add storyboard adapter routing tests when the model can generate video prompts.
+13. Update docs/examples only if the model should be publicly visible.
+
+Ideal new-video-model diff:
+
+- one registry entry
+- one adapter only if no existing adapter fits
+- focused tests
+- docs update when public
+
+## Adding An Image Model
+
+1. Add one registry entry with `modalities: ["image"]`.
+2. Do not add it to video-only CLI or storyboard video target validation.
+3. Pick image-aware `supportedPresets`.
+4. Use `adapterKey: "gptImage2"` only for GPT Image 2 behavior; use `none` or a future image adapter key otherwise.
+5. Add tests proving it appears in image selectors and not in video selectors.
+
+Image models must not widen video model types or `generate-storyboard --models`.
+
+## Deprecating A Model
+
+1. Change `lifecycleStatus` to `deprecated`.
+2. Add `deprecationMessage`.
+3. Add `replacementModelId` when there is a direct replacement.
+4. Keep compatibility metadata only for paths that still work.
+5. Add tests proving validation emits a warning.
+
+Do not silently rewrite deprecated model ids unless a dedicated migration test covers that behavior.
+
+## Removing A Model
+
+1. Change `lifecycleStatus` to `removed`.
+2. Keep the id in the registry so validation can fail with a clear message.
+3. Add `deprecationMessage` and `replacementModelId` when possible.
+4. Clear runtime compatibility if the model must not be routed.
+5. Add tests proving `assertModelAllowed` fails closed.
+
+Removed models must not fall back to active models or generic adapters.
+
+## Phase Boundaries
+
+Phase 1 connects the root runtime, CLI/config validation, and storyboard-reference adapter routing to the registry.
+
+Phase 2 keeps internal preset packages private. Package source builds use `rootDir: src`, so direct imports from root `src/lib/model-registry` would break package builds or create circular product coupling. Root `configureFilmKit()` and CLI validation are the canonical guardrails for public usage. Internal package prompt/template prose can continue to contain model names as generated runtime content.
+
+Phase 3 is this maintenance documentation plus README linkage.

package/README.md

@@ -70,6 +70,8 @@ Storyboard-reference prompt generation is also available when you have a charact
 
 ## Model Support
 
+Canonical model metadata lives in `src/lib/model-registry/*`; see [MODEL_REGISTRY.md](./MODEL_REGISTRY.md) for the add/update/deprecate/remove checklist. Public model selection still happens at init time through the root package and CLI.
+
 ### `veo31`
 
 - Default single, multi, and studio model
@@ -181,6 +183,7 @@ npx @milenyumai/film-kit generate-storyboard \
 Outputs:
 
 - `outputs/storyboard-reference-plan.json`
+- `outputs/storyboard-prompt.md`
 - `outputs/reference-prep/CHARACTER-SHEET-*.md`
 - `outputs/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md`
 - `outputs/prompt-bundles/SHOTNN.bundle.json`
@@ -194,8 +197,10 @@ Rules:
 - `@character1` is used once to create a 16:9 character sheet prompt with front, back, side, three-quarter, and face close-up views.
 - 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.
-- Storyboard prompts use production-board grammar: rough black-and-white pencil panels, strong silhouettes, visible body/camera momentum, and optional color-coded planning annotations. Seedance is instructed to follow the panel order while ignoring arrows, notes, labels, and timestamps in the rendered video.
+- If no external storyboard image exists, Film-Kit still generates the GPT Image 2 storyboard bootstrap prompt and writes it to both `outputs/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md` and the convenience alias `outputs/storyboard-prompt.md`.
+- Storyboard prompts use production-board grammar: 16:9 storyboard sheet, rough black-and-white pencil panels, strong silhouettes, visible body/camera momentum, cinematic camera variety, and optional color-coded planning annotations. Seedance is instructed to follow the panel order while ignoring arrows, notes, labels, and timestamps in the rendered video.
 - Seedance provider-facing tokens map generated character sheets first (`@Image1`, `@Image2`, ...) and the generated shot storyboard next. Legacy lowercase aliases remain documented in runtime text.
+- `SHOTNN.bundle.json` includes `storyboard_creation` metadata with provider, prompt path, alias path, reading order, panel count, Seedance token, annotation policy, and prompt text.
 - 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.
@@ -214,7 +219,7 @@ CLI flags for direct storyboard bundle generation:
 | `--models` | Comma-separated target models: `veo31`, `seedance-2.0`, `kling-3.0` |
 | `--duration` | Duration in seconds per generated shot. Seedance provider range is 4-15 seconds |
 | `--aspect` | `16:9`, `9:16`, or `1:1` |
-| `--storyboard-panel-count-hint` | Optional total panel/phase hint. 5+ phases are split when overload splitting is enabled |
+| `--storyboard-panel-count-hint` | Optional GPT Image 2 storyboard sheet panel count, `1-12`. This does not by itself split SHOT files |
 | `--max-storyboard-phases` | Upper bound per shot. Default: `4` |
 
 ## CLI
@@ -484,6 +489,25 @@ Public root exports:
 - `FILM_KIT_CONFIG_FILE`
 - `FILM_KIT_PRESETS`
 - `LEGACY_CONFIG_FILES`
+- `getModel(id)`
+- `requireModel(id)`
+- `listModels()`
+- `listActiveModels()`
+- `listVideoModels()`
+- `listImageModels()`
+- `listModelsForPreset(preset)`
+- `listModelsForReferenceMode(referenceMode)`
+- `isKnownModelId(value)`
+- `isActiveModelId(value)`
+- `isDeprecatedModelId(value)`
+- `isRemovedModelId(value)`
+- `isVideoModelId(value)`
+- `isImageModelId(value)`
+- `isModelSupportedByPreset(modelId, preset)`
+- `getModelAdapterKey(modelId)`
+- `getReplacementModel(modelId)`
+- `assertModelAllowed(id, context)`
+- `validateModelAllowed(id, context)`
 - `FilmKitPreset`
 - `SupportedModel`
 - `SupportedPlatform`

package/build/index.d.ts

@@ -1,5 +1,7 @@
 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";
+export { assertModelAllowed, getModel, getModelAdapterKey, getModelDisplayName, getReplacementModel, isActiveModelId, isDeprecatedModelId, isImageModelId, isKnownModelId, isModelSupportedByPreset, isRemovedModelId, isVideoModelId, listActiveModels, listActiveVideoModelIds, listImageModels, listModels, listModelsForPreset, listModelsForReferenceMode, listRunnableVideoModelIds, listRunnableVideoModels, listVideoModels, requireModel, validateModelAllowed } from "./lib/model-registry/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 { CharacterReferenceSheetPrompt, ModelPromptOutput, ModelRouteMetadata, PromptBundle, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, SeedanceContinuityMode, ShotHandoffNote, StoryboardImagePrompt, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoPromptRequest } from "./lib/storyboard-reference/index.js";
+export type { ActiveModelId, AudioModelId, DeprecatedModelId, ImageModelId, KnownModelId, ModelAdapterKey, ModelAllowedContext, ModelAllowedResult, ModelCapabilities, ModelLifecycleStatus, ModelModality, ModelRegistryEntry, MultimodalModelId, RemovedModelId, VideoModelId } from "./lib/model-registry/index.js";
+export type { CharacterReferenceSheetPrompt, ModelPromptOutput, ModelRouteMetadata, PromptBundle, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, SeedanceContinuityMode, ShotHandoffNote, StoryboardCreationMetadata, StoryboardImagePrompt, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoPromptRequest } from "./lib/storyboard-reference/index.js";

package/build/index.js

@@ -1,3 +1,4 @@
 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";
+export { assertModelAllowed, getModel, getModelAdapterKey, getModelDisplayName, getReplacementModel, isActiveModelId, isDeprecatedModelId, isImageModelId, isKnownModelId, isModelSupportedByPreset, isRemovedModelId, isVideoModelId, listActiveModels, listActiveVideoModelIds, listImageModels, listModels, listModelsForPreset, listModelsForReferenceMode, listRunnableVideoModelIds, listRunnableVideoModels, listVideoModels, requireModel, validateModelAllowed } from "./lib/model-registry/index.js";

package/build/lib/cli.js

@@ -2,7 +2,7 @@ import { FILM_KIT_CONFIG_FILE, FILM_KIT_PRESETS, detectFilmKitPreset, isFilmKitP
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { exists } from "./fs.js";
-const SUPPORTED_MODELS = ["veo31", "kling-3.0", "seedance-2.0"];
+import { listActiveVideoModelIds, validateModelAllowed } from "./model-registry/index.js";
 const SUPPORTED_KLING_PRESETS = ["ultra-realism", "balanced", "custom"];
 const SUPPORTED_ASPECTS = ["16:9", "9:16", "1:1"];
 const SUPPORTED_REFERENCE_MODES = ["start-end", "storyboard-reference", "hybrid"];
@@ -87,6 +87,9 @@ const PRESET_ALLOWED_FLAGS = {
     ])
 };
 const COMMON_FLAGS = new Set(["--preset", "--output-dir", "--scenario-hint", "--scenario", "--overwrite", "-f"]);
+function supportedVideoModelText() {
+    return listActiveVideoModelIds().join(", ");
+}
 function parseIntegerFlag(raw, flag) {
     const value = Number.parseInt(raw, 10);
     if (!Number.isInteger(value) || value <= 0) {
@@ -181,10 +184,10 @@ function parseKnownFlags(args) {
                 options.platforms = parsePlatforms(nextValue);
                 break;
             case "--model":
-                if (!SUPPORTED_MODELS.includes(nextValue)) {
-                    throw new Error(`Invalid --model value: ${nextValue}. Supported: ${SUPPORTED_MODELS.join(", ")}`);
-                }
-                options.model = nextValue;
+                options.model = validateModelAllowed(nextValue, {
+                    requiredModalities: ["video"],
+                    usage: "--model"
+                }).model.id;
                 break;
             case "--kling-preset":
                 if (!SUPPORTED_KLING_PRESETS.includes(nextValue)) {
@@ -293,9 +296,11 @@ function parseModels(raw) {
         throw new Error("Invalid --models value. Expected at least one supported model.");
     }
     for (const model of models) {
-        if (!SUPPORTED_MODELS.includes(model)) {
-            throw new Error(`Invalid --models value: ${model}. Supported: ${SUPPORTED_MODELS.join(", ")}`);
-        }
+        validateModelAllowed(model, {
+            requiredModalities: ["video"],
+            referenceMode: "storyboard-reference",
+            usage: "--models"
+        });
     }
     return models;
 }
@@ -472,6 +477,17 @@ export async function parseCliCommand(args, rootDir = process.cwd()) {
             `You can also commit ${FILM_KIT_CONFIG_FILE} and rerun init.`);
     }
     validatePresetFlags(preset, providedFlags);
+    if (options.model) {
+        const validationContext = {
+            preset,
+            requiredModalities: ["video"],
+            usage: "--model"
+        };
+        if (options.referenceMode !== undefined) {
+            validationContext.referenceMode = options.referenceMode;
+        }
+        validateModelAllowed(options.model, validationContext);
+    }
     return {
         command: "init",
         options: {
@@ -518,7 +534,7 @@ generate-storyboard flags:
   --character-ref      Character identity reference image path or URL (repeatable or comma-separated)
   --storyboard-ref     Optional storyboard guide image path or URL (repeatable or comma-separated)
   --brief              Inline brief text or a path to a brief file
-  --models             Comma-separated models: veo31,seedance-2.0,kling-3.0
+  --models             Comma-separated models: ${supportedVideoModelText()}
   --duration           Duration in seconds per generated shot
   --aspect             16:9|9:16|1:1
   --output-dir         Output root (default: ./outputs)
@@ -526,7 +542,7 @@ generate-storyboard flags:
   --dialogue           Repeatable "Speaker: exact line" value
   --audio-intent       SFX/ambience direction
   --style-intent       Visual style direction
-  --storyboard-panel-count-hint  Panel/phase count hint; 5+ panels split into multiple SHOTNN files
+  --storyboard-panel-count-hint  GPT Image 2 storyboard sheet panel count, 1-12; does not split SHOT files by itself
   --max-storyboard-phases  Upper bound per SHOTNN storyboard phase count
 
 Install:

package/build/lib/configure.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 import { readdir, readFile, rm } from "node:fs/promises";
 import { exists, readJsonIfExists, writeText } from "./fs.js";
 import { resolveOptions } from "./defaults.js";
+import { getModelDisplayName as getRegistryModelDisplayName } from "./model-registry/index.js";
 import { buildProjectFiles } from "./templates.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -159,6 +160,7 @@ description: Generate storyboard-reference prompt bundles from character referen
 \`\`\`text
 ${vars.outputDir}/
 ├── storyboard-reference-plan.json
+├── storyboard-prompt.md
 ├── reference-prep/
 │   └── CHARACTER-SHEET-*.md
 ├── storyboard-prompts/
@@ -186,18 +188,21 @@ ${vars.outputDir}/
    - \`maxStoryboardPhases: ${vars.maxStoryboardPhases}\`
    - \`voiceCast\` when dialogue or narration exists
    - \`visual_world\` for camera, lens, lighting, scale, reflection, physics, screen direction, and continuity anchors
-4. Split the scenario into shots by dramatic beat. Use this phase budget:
+4. Split the scenario into shots by dramatic beat. Use this video phase budget:
    - 4-6 seconds: 1-2 phases
    - 7-10 seconds: 2-3 phases
    - 11-15 seconds: 3-4 phases
-   - 5+ distinct phases: split into separate \`SHOTNN.md\` files
+   - 5+ distinct real video phases, scene changes, or location/action blocks: split into separate \`SHOTNN.md\` files
+   - GPT Image 2 storyboard sheets may use 1-12 panels; 5-12 storyboard sheet panels alone do not force a split
 5. For each shot, write a GPT Image 2 storyboard prompt:
    - use character sheets as the only identity source
    - use optional storyboard guides only for staging and timing
+   - use raw black-and-white rough pencil storyboard panels, strong silhouettes, visible motion, cinematic camera variety, and color-coded planning annotations
    - include previous-shot handoff and next-shot handoff
    - preserve shared \`visual_world\`, lighting, screen direction, and action rhythm
 6. Build model-ready video prompt bundles:
    - Seedance: character sheet tokens first, generated shot storyboard token next
+   - Seedance: follow storyboard panels left-to-right/top-to-bottom as visual/action/camera source, but never render arrows, labels, annotations, timestamps, or panel borders
    - Veo: visual planning prompt with full audio direction
    - Kling: block-structured storyboard route, not a mandatory Start+End frame route
 7. Keep coverage inside the same \`SHOTNN.md\`; coverage uses storyboard planning prompts and does not request separate start/end still prompts.
@@ -350,13 +355,14 @@ description: Finalize storyboard-reference prompt packages after storyboard QA p
 ## Validate Files
 
 1. \`${vars.outputDir}/storyboard-reference-plan.json\` exists.
-2. \`${vars.outputDir}/reference-prep/\` contains character sheet prompt files.
-3. \`${vars.outputDir}/storyboard-prompts/\` contains per-shot GPT Image 2 storyboard prompts.
-4. \`${vars.outputDir}/prompt-bundles/\` contains model prompt bundles.
-5. Every \`${vars.outputDir}/shots/SHOTNN.md\` contains the required storyboard-reference sections.
-6. Coverage stays in the same \`SHOTNN.md\`.
-7. No generated shot contains forbidden start/end frame sections or exact first-frame reuse instructions.
-8. \`storyboard_reference_status\` and \`storyboard_handoff_status\` are pass.
+2. \`${vars.outputDir}/storyboard-prompt.md\` exists as the storyboard bootstrap alias.
+3. \`${vars.outputDir}/reference-prep/\` contains character sheet prompt files.
+4. \`${vars.outputDir}/storyboard-prompts/\` contains per-shot GPT Image 2 storyboard prompts.
+5. \`${vars.outputDir}/prompt-bundles/\` contains model prompt bundles with \`storyboard_creation\` metadata.
+6. Every \`${vars.outputDir}/shots/SHOTNN.md\` contains the required storyboard-reference sections.
+7. Coverage stays in the same \`SHOTNN.md\`.
+8. No generated shot contains forbidden start/end frame sections or exact first-frame reuse instructions.
+9. \`storyboard_reference_status\` and \`storyboard_handoff_status\` are pass.
 
 ## Final Summary
 
@@ -549,13 +555,6 @@ description: Storyboard-reference prompt structure for GPT Image 2 character she
 Do not emit main-shot \`ILK FRAME\`, \`İLK FRAME\`, \`SON FRAME\`, \`SHOTNN_START\`, \`SHOTNN_END\`, or exact first-frame reuse instructions in storyboard-reference mode.
 `;
 }
-function getModelDisplayName(model) {
-    if (model === "kling-3.0")
-        return "Kling 3.0";
-    if (model === "seedance-2.0")
-        return "Seedance 2.0";
-    return "Google Flow + Veo 3.1";
-}
 function getKlingPresetDisplay(model, klingPreset) {
     return model === "kling-3.0" ? klingPreset : "n/a (Kling-only)";
 }
@@ -622,7 +621,7 @@ export async function configureAgents(options = {}) {
         scenarioHint: resolved.scenarioHint,
         model: resolved.model,
         klingPreset: getKlingPresetDisplay(resolved.model, resolved.klingPreset),
-        modelDisplayName: getModelDisplayName(resolved.model),
+        modelDisplayName: getRegistryModelDisplayName(resolved.model),
         referenceMode: resolved.referenceMode,
         storyboardReferenceActive,
         maxStoryboardPhases: resolved.storyboardReferenceMode.maxStoryboardPhases

package/build/lib/defaults.js

@@ -1,3 +1,4 @@
+import { validateModelAllowed } from "./model-registry/index.js";
 const ALL_PLATFORMS = ["cursor", "claude", "copilot", "antigravity", "codex"];
 const DEFAULT_MODEL = "veo31";
 const DEFAULT_KLING_PRESET = "ultra-realism";
@@ -31,12 +32,21 @@ export function normalizeStoryboardReferenceConfig(input, referenceMode) {
 export function resolveOptions(input) {
     const warnings = [];
     const model = input.model ?? DEFAULT_MODEL;
+    const modelValidationContext = {
+        requiredModalities: ["video"],
+        usage: "runtime"
+    };
+    if (input.referenceMode !== undefined) {
+        modelValidationContext.referenceMode = input.referenceMode;
+    }
+    const modelValidation = validateModelAllowed(model, modelValidationContext);
     const klingPreset = input.klingPreset ?? DEFAULT_KLING_PRESET;
     const referenceMode = input.referenceMode ?? DEFAULT_REFERENCE_MODE;
     const storyboardReferenceMode = normalizeStoryboardReferenceConfig(input.storyboardReferenceMode, referenceMode);
     if (!input.model) {
         warnings.push("Model not specified. Falling back to veo31. In the next major release, --model will be required.");
     }
+    warnings.push(...modelValidation.warnings);
     if (referenceMode === "storyboard-reference" && !storyboardReferenceMode.enabled) {
         warnings.push("referenceMode is storyboard-reference, but storyboardReferenceMode.enabled is false.");
     }

package/build/lib/film-kit.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 import { configureAgents } from "./configure.js";
 import { resolveOptions } from "./defaults.js";
 import { exists, readJsonIfExists, writeText } from "./fs.js";
+import { validateModelAllowed } from "./model-registry/index.js";
 export const FILM_KIT_CONFIG_FILE = "film-kit.config.json";
 export const FILM_KIT_PRESETS = [
     "single",
@@ -370,6 +371,20 @@ export async function configureFilmKit(options = {}) {
     assignDefined(merged, options);
     merged.rootDir = rootDir;
     merged.preset = preset;
+    const rootValidationWarnings = [];
+    const mergedModel = readString(merged.model);
+    if (mergedModel) {
+        const validationContext = {
+            preset,
+            requiredModalities: ["video"],
+            usage: "film-kit.config.json model"
+        };
+        const mergedReferenceMode = readString(merged.referenceMode);
+        if (mergedReferenceMode !== undefined) {
+            validationContext.referenceMode = mergedReferenceMode;
+        }
+        rootValidationWarnings.push(...validateModelAllowed(mergedModel, validationContext).warnings);
+    }
     const runtime = await loadPresetRuntime(preset);
     const resolved = runtime.resolve(pickPresetOptions(preset, merged));
     if (resolved.referenceMode === undefined && merged.referenceMode !== undefined) {
@@ -382,7 +397,7 @@ export async function configureFilmKit(options = {}) {
     const result = await runtime.configure(configureOptions);
     const configPath = join(rootDir, FILM_KIT_CONFIG_FILE);
     await writeText(configPath, `${JSON.stringify(buildFilmKitConfigFile(preset, resolved), null, 2)}\n`);
-    const warnings = [...result.warnings];
+    const warnings = [...rootValidationWarnings, ...result.warnings];
     if (legacyMatch) {
         warnings.push(`Migrated legacy config '${legacyMatch.filename}' to '${FILM_KIT_CONFIG_FILE}'.`);
     }

package/build/lib/model-registry/index.d.ts

@@ -0,0 +1,4 @@
+export { MODEL_REGISTRY, type ActiveModelId, type AudioModelId, type DeprecatedModelId, type ImageModelId, type KnownModelId, type MultimodalModelId, type RemovedModelId, type VideoModelId } from "./registry.js";
+export { getModel, getModelAdapterKey, getModelDisplayName, getReplacementModel, isActiveModelId, isDeprecatedModelId, isImageModelId, isKnownModelId, isModelSupportedByPreset, isRemovedModelId, isVideoModelId, listActiveModels, listActiveVideoModelIds, listImageModels, listModels, listModelsForPreset, listModelsForReferenceMode, listRunnableVideoModelIds, listRunnableVideoModels, listVideoModels, requireModel } from "./selectors.js";
+export { assertModelAllowed, validateModelAllowed } from "./validation.js";
+export type { ModelAdapterKey, ModelAllowedContext, ModelAllowedResult, ModelCapabilities, ModelDurationRange, ModelLifecycleStatus, ModelModality, ModelProfileKey, ModelRegistryAspectRatio, ModelRegistryEntry, ModelRegistryPreset, ModelRegistryReferenceMode, ModelRoutingRole, PromptGrammarKey } from "./types.js";

package/build/lib/model-registry/index.js

@@ -0,0 +1,3 @@
+export { MODEL_REGISTRY } from "./registry.js";
+export { getModel, getModelAdapterKey, getModelDisplayName, getReplacementModel, isActiveModelId, isDeprecatedModelId, isImageModelId, isKnownModelId, isModelSupportedByPreset, isRemovedModelId, isVideoModelId, listActiveModels, listActiveVideoModelIds, listImageModels, listModels, listModelsForPreset, listModelsForReferenceMode, listRunnableVideoModelIds, listRunnableVideoModels, listVideoModels, requireModel } from "./selectors.js";
+export { assertModelAllowed, validateModelAllowed } from "./validation.js";