Film-Kit

Single-package cinematic prompt-engineering runtime for OpenAI Codex App, Claude Code, Cursor, GitHub Copilot, and Antigravity.

@milenyumai/film-kit is now the only public npm distribution. Presets are selected at init time, not at install time.

What Changed

• Public package surface is now only @milenyumai/film-kit
• Public CLI entrypoint is now only film-kit / npx @milenyumai/film-kit
• Product mode is selected with --preset
• Canonical project config is now film-kit.config.json
• Old package families remain in packages/* as internal preset sources, not public release targets

Install

Requirements:

• Node.js >=20

Install:

npm install --save-dev @milenyumai/film-kit

If it is already installed locally, the binary name is:

npx film-kit init --preset single

Package-direct invocation also works:

npx @milenyumai/film-kit init --preset single

Quick Start

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 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 and brief. It creates one-time GPT Image 2 character sheet prompts, per-shot GPT Image 2 storyboard prompts, and model-specific video prompt bundles without requiring start/end frames. A storyboard guide image can still be supplied, but it is optional.

Presets

| Preset | Purpose | Video/model surface | Storyboard / reference support | Default notes | |---|---|---|---|---| | single | Single-agent prompt runtime | veo31, kling-3.0, seedance-2.0 | Can store storyboard-reference config and ships the storyboard skill/workflow | Defaults to all supported platforms | | multi | Lead-directed multi-agent shot generation | veo31, kling-3.0, seedance-2.0 | Best fit for Seedance storyboard-reference teams: character sheets, shot storyboard prompts, team-plan metadata, handoff notes | Defaults to maxTeammates=5, batchSize=4 | | hybrid | Nano Banana still generation + GPT Image 2 companion metadata + fixed Kling video runtime | fixed kling-3.0 | Ships the updated storyboard skill/workflow for prompt planning; video runtime stays Kling-focused | No --model flag | | hybrid-smart | Nano Banana still generation + GPT Image 2 companion metadata + dialogue-aware Veo/Kling routing | fixed smart route | Ships the updated storyboard skill/workflow and GPT Image companion metadata | No --model flag | | gpt-image-smart | GPT Image 2 still generation + dialogue-aware Veo/Kling routing | fixed smart route | GPT Image 2-first preset; includes the character-sheet + per-shot storyboard prompt contract | 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 | Full pipeline option for Seedance storyboard-reference plus refs dir and render-stage config | Includes refs dir and fal model configuration |

Model Support

Canonical model metadata lives in src/lib/model-registry/*; see 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
• Uses the Veo-oriented prompt flow and audio-direction block
• Default warning still exists if model is omitted in some presets because current runtime remains backward-compatible

seedance-2.0

• Supported in single, multi, and studio
• Runtime now includes Seedance-specific prompt guidance
• Seedance prompt behavior emphasizes:
  • multimodal role assignment such as @Image1 / @image1, @video1, @audio1
  • first-frame anchoring like Use @Image1 as the first frame of the scene.
  • continuous-shot wording such as No scene cuts throughout, one continuous shot. only for uninterrupted camera moves
  • explicit extension syntax such as Extend @video1 by 5s
  • separation of identity reference vs camera reference vs action reference

kling-3.0

• 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 applies when the active video model is kling-3.0, including Kling-routed sections inside smart presets

Supported kling-preset values:

• ultra-realism
• balanced
• custom

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 brief rather than explicit start/end frames. Film-Kit first prepares character-sheet prompts, then per-shot storyboard prompts. Optional storyboard images can be supplied as loose composition/timing guides.

Storyboard Mode Setup For Supported Tools

Storyboard-reference mode is installed from the same canonical package for every tool:

npm install --save-dev @milenyumai/film-kit

You can also skip local install and use package-direct npx commands. Do not install or run old standalone preset package names.

Create your input files first:

mkdir -p refs
# Put the exact character identity image here:
# refs/character.png
#
# Put the video brief here:
# scenario.md

Install the storyboard runtime for all supported tools at once:

npx @milenyumai/film-kit init \
  --preset single \
  --model seedance-2.0 \
  --reference-mode storyboard-reference \
  --platforms codex,claude,cursor,copilot,antigravity \
  --max-storyboard-phases 4

Supported tool-specific setup commands:

| Tool | Setup command | Main files created | |---|---|---| | OpenAI Codex App | npx @milenyumai/film-kit init --preset single --model seedance-2.0 --reference-mode storyboard-reference --platforms codex --max-storyboard-phases 4 | AGENTS.md, .codex/config.toml, .codex/agents/*.toml, .agents/skills/storyboard-reference/SKILL.md | | Claude Code | npx @milenyumai/film-kit init --preset single --model seedance-2.0 --reference-mode storyboard-reference --platforms claude --max-storyboard-phases 4 | CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*, .claude/agents/prompt-engineer.md | | Cursor | npx @milenyumai/film-kit init --preset single --model seedance-2.0 --reference-mode storyboard-reference --platforms cursor --max-storyboard-phases 4 | .cursorrules, .cursor/rules/global.mdc, .agent/workflows/generate-storyboard.md | | GitHub Copilot | npx @milenyumai/film-kit init --preset single --model seedance-2.0 --reference-mode storyboard-reference --platforms copilot --max-storyboard-phases 4 | .github/copilot-instructions.md, .github/instructions/shotforge.instructions.md | | Antigravity | npx @milenyumai/film-kit init --preset single --model seedance-2.0 --reference-mode storyboard-reference --platforms antigravity --max-storyboard-phases 4 | .agent/skills/shotforge-generate/SKILL.md, .agent/workflows/generate-storyboard.md, .agent/skills/storyboard-reference/SKILL.md |

For a studio-style project with refs and render-stage metadata, use studio instead:

npx @milenyumai/film-kit init \
  --preset studio \
  --model seedance-2.0 \
  --reference-mode storyboard-reference \
  --platforms codex,claude,cursor,copilot,antigravity \
  --refs-dir ./refs \
  --gpt-image-size 2048x1152 \
  --gpt-image-quality medium \
  --gpt-image-format png \
  --max-storyboard-phases 4

After setup, open the Git project root in your tool. Use this as the first prompt in Codex, Claude Code, Cursor, Copilot Chat, or Antigravity:

Read the Film-Kit storyboard-reference instructions in AGENTS.md and .agent/workflows/generate-storyboard.md.

Use refs/character.png as the exact character identity reference.
Use scenario.md as the video brief.
Target model: seedance-2.0.
Duration: 15 seconds.
Aspect ratio: 16:9.

Generate the storyboard-reference package only:
- one GPT Image 2 character sheet prompt
- one 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
- outputs/prompt-bundles/SHOT01.bundle.json
- outputs/shots/SHOT01.md
- outputs/reports/STORYBOARD-REFERENCE-QA.md

Do not create ILK FRAME, İLK FRAME, SON FRAME, SHOT_START, or SHOT_END sections.
Do not render images or video yet; first produce and QA the prompt package.

If your tool supports slash-style workflow prompts, this shorter first prompt is also valid:

/generate
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:

npx @milenyumai/film-kit generate-storyboard \
  --character-ref ./refs/character.png \
  --brief ./scenario.md \
  --models seedance-2.0 \
  --duration 15 \
  --aspect 16:9 \
  --output-dir ./outputs

After the command finishes, start with outputs/storyboard-prompt.md. It is the ready-to-use GPT Image 2 storyboard image prompt. 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:

npx @milenyumai/film-kit init \
  --preset single \
  --model seedance-2.0 \
  --reference-mode storyboard-reference \
  --max-storyboard-phases 4

For multi-agent storyboard-reference generation:

npx @milenyumai/film-kit init \
  --preset multi \
  --model seedance-2.0 \
  --reference-mode storyboard-reference \
  --max-storyboard-phases 4

For a GPT Image 2-first workflow, initialize the smart image preset with the same reference mode:

npx @milenyumai/film-kit init \
  --preset gpt-image-smart \
  --reference-mode storyboard-reference \
  --gpt-image-size 2048x1152 \
  --gpt-image-quality medium \
  --gpt-image-format png

Generate prompt bundle files directly:

npx @milenyumai/film-kit generate-storyboard \
  --character-ref ./refs/character.png \
  --brief ./scenario.md \
  --models veo31,seedance-2.0,kling-3.0 \
  --duration 8 \
  --aspect 16:9 \
  --output-dir ./outputs

Add an external storyboard guide only when you already have one:

npx @milenyumai/film-kit generate-storyboard \
  --character-ref ./refs/character.png \
  --storyboard-ref ./refs/storyboard-guide.png \
  --brief ./scenario.md \
  --models seedance-2.0 \
  --duration 8

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
• outputs/shots/SHOTNN.md
• outputs/reports/STORYBOARD-REFERENCE-QA.md

In a project initialized with --reference-mode storyboard-reference, /generate is mode-guarded to use the storyboard-reference workflow. It will not generate start/end frame packages. If no character reference is available through --character-ref, an in-context image, or refs/character.png, generation stops and asks for one.

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.
• 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: 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, 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.
• 5+ storyboard phases are split into multiple SHOTNN.md files by default.
• Multi-phase storyboards use planned phase transitions instead of forcing No scene cuts throughout, one continuous shot.
• Seeing ILK FRAME, İLK FRAME, or SON FRAME in main storyboard-reference shot output means the old start/end runtime leaked in; treat that output as failed and rerun after reinitializing with --reference-mode storyboard-reference.
• Existing start/end workflows stay unchanged and remain the default.

CLI flags for direct storyboard bundle generation:

| Flag | Description | |---|---| | --character-ref | Required 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/scenario file | | --models | Comma-separated target models: veo31, seedance-2.0, kling-3.0 | | --duration | Duration in seconds per generated shot. Seedance provider range is 4-15 seconds | | --aspect | 16:9, 9:16, or 1:1 | | --storyboard-panel-count-hint | Optional GPT Image 2 storyboard sheet panel count, 1-12. Default: 12. This does not by itself split SHOT files | | --max-storyboard-phases | Upper bound per shot. Default: 4 |

CLI

Base command:

npx @milenyumai/film-kit init --preset single|multi|hybrid|hybrid-smart|gpt-image-smart|studio

Help:

npx @milenyumai/film-kit --help

Examples:

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

Common Flags

| Flag | Description | |---|---| | --preset | Required unless film-kit.config.json or a single legacy config already exists | | --output-dir | Output root. Default: ./outputs | | --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, --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, 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

Film-Kit writes film-kit.config.json after initialization and reads it on future runs.

Example:

{
  "preset": "studio",
  "outputDir": "./outputs",
  "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
}

Config Field Support Matrix

| 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

Film-Kit automatically detects and migrates one existing legacy config file on first run:

• shotforge-agent.config.json
• 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:

• Film-Kit infers the preset from the legacy filename
• Film-Kit resolves preset defaults through the new root dispatcher
• Film-Kit writes the final canonical config to film-kit.config.json
• Film-Kit returns a warning that the legacy config was migrated

If multiple legacy config files are present at the same time, Film-Kit fails fast and asks for cleanup or an explicit --preset.

Generated Runtime Surface

Film-Kit writes repo-scoped runtime files for supported editors and agents. Depending on preset and platform selection, output includes:

• .agent/
• .agents/
• .codex/config.toml
• .codex/agents/*.toml
• .claude/
• .cursor/
• .github/copilot-instructions.md
• AGENTS.md
• 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
• semantic consistency uses canonical visual_world

Reference Locking And Start/End Consistency

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, 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
• generated prompts should explicitly preserve the same person or object exactly as the reference
• silent redesign, restyling, redressing, age shifting, or prop redesign is considered a failure

Allowed movement inside a reference-locked shot is intentionally narrow:

• pose can change only if it is explicitly declared
• expression can change only if it is explicitly declared
• camera or environment state can change only if it is explicitly declared
• each start/end pair should carry only one major semantic delta unless the workflow marks a deliberate chain break or transition

Prompt Contract

Start/end still prompts are now optimized for structure, not raw length.

Image prompt contract:

• REFERENCE LOCK
• Keep same
• Change only
• short semantic anchor
• targeted avoid line

This means:

• reference-anchored image prompts are intentionally shorter and more surgical
• 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, 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

visual_world is the canonical continuity contract for semantic consistency and render review.

Reference-aware runtime and reports now carry these concepts:

• identity_lock: "exact-reference"
• shared_frame_invariants
• allowed_change
• reference_drift_forbidden: true

Generated specialist and render QA flows now explicitly fail on:

• face, hair, skin, body, wardrobe, accessory, or prop drift
• lens, angle, subject scale, light direction, or color-temperature drift
• unexplained semantic changes between start and end frames
• violations of declared Keep same invariants
• changes outside the declared Change only budget

Studio render QA also records render-level verdicts such as:

• reference_drift_status
• start_end_contract_status in start/end mode
• storyboard_reference_status and storyboard_handoff_status in storyboard-reference mode

Seedance Runtime Coverage

The package now carries Seedance-aware instructions in the generated runtime, not only in type definitions or CLI parsing.

That means generated prompt systems now include Seedance guidance in:

• model profile generation
• prompt structure skill
• audio design skill
• root generation workflows
• single-agent prompt engineer instructions
• multi-agent lead-director / shot-generator workflows

In practice, this gives generated teams explicit rules for:

• multimodal prompt composition
• continuous-shot language
• timeline segmentation
• reference-role separation
• clip extension syntax

Programmatic API

Public root exports:

• configureFilmKit(options)
• detectFilmKitPreset(rootDir)
• 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
• KlingPreset

Example:

import { configureFilmKit } from "@milenyumai/film-kit";

const result = await configureFilmKit({
  rootDir: process.cwd(),
  preset: "multi",
  model: "seedance-2.0",
  maxTeammates: 5,
  batchSize: 4
});

console.log(result.preset);
console.log(result.configPath);
console.log(result.written);
console.log(result.warnings);

For backward compatibility, configureAgents() is still exported for the single preset runtime, but new integrations should treat configureFilmKit() as the primary root API.

Postinstall Behavior

The package postinstall hook is intentionally conservative:

• if no preset can be detected, postinstall does nothing
• if film-kit.config.json exists, postinstall can rehydrate the runtime
• if FILM_KIT_PRESET is provided, postinstall can configure that preset non-interactively

Supported postinstall environment variables:

• FILM_KIT_PRESET
• FILM_KIT_MODEL
• 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
• FILM_KIT_REFS_DIR
• FILM_KIT_FAL_IMAGE_MODEL
• FILM_KIT_FAL_VIDEO_MODEL

This keeps install-time side effects low while still allowing CI or template-driven setup.

Repository Layout

Public distribution model:

• published package: @milenyumai/film-kit

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.

Release and Publish

Maintainer release checklist:

npm run release:check

Publish the single public package:

npm login
npm whoami
npm publish --access public

If the account has npm two-factor authentication enabled for publish, include the current one-time password from the authenticator app:

npm publish --access public --otp=123456

Optional validation before publish:

npm pkg get name version
npm view @milenyumai/film-kit version

If you want to deprecate previously published legacy package names and point users to the new surface, run:

npm deprecate @milenyumai/film-kit-multi@"*" "Deprecated. Use @milenyumai/film-kit with --preset multi."
npm deprecate @milenyumai/film-kit-hybrid@"*" "Deprecated. Use @milenyumai/film-kit with --preset hybrid."
npm deprecate @milenyumai/film-kit-hybrid-smart@"*" "Deprecated. Use @milenyumai/film-kit with --preset hybrid-smart."
npm deprecate @milenyumai/film-kit-studio@"*" "Deprecated. Use @milenyumai/film-kit with --preset studio."

License

MIT