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 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

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.

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 |

Model Support

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, @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.
  • 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
• Uses Kling-specific Start+End / storyboard prompt structure

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

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).

CLI

Base command:

npx @milenyumai/film-kit init --preset single|multi|hybrid|hybrid-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 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 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 |

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 |

Supported Flag Values

| Flag | Supported values | |---|---| | --preset | single, multi, hybrid, hybrid-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 | | --platforms | cursor, claude, copilot, antigravity, codex |

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",
  "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",
  "includeAgentsMd": true,
  "copyContent": true
}

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 |

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-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, 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, 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 and hybrid-smart keep their compact 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

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
• 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_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/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 typecheck
npm test
npm run build
npm pack --json --dry-run

Publish the single public package:

npm login
npm whoami
npm publish --access public

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