@milenyumai/film-kit 1.4.3 → 2.0.1

package/README.md

@@ -1,239 +1,446 @@
 # Film-Kit
 
-Professional cinematic prompt-engineering kits for OpenAI Codex App, Claude Code, Cursor, GitHub Copilot, and Antigravity.
+Single-package cinematic prompt-engineering runtime for OpenAI Codex App, Claude Code, Cursor, GitHub Copilot, and Antigravity.
 
-Film-Kit ships as a single repository with five npm packages:
+`@milenyumai/film-kit` is now the only public npm distribution. Presets are selected at `init` time, not at install time.
 
-| Package | Use case | Video route |
-|---|---|---|
-| `@milenyumai/film-kit` | Core single-agent workflow | `veo31` or `kling-3.0` |
-| `@milenyumai/film-kit-multi` | Multi-agent parallel production | `veo31` or `kling-3.0` |
-| `@milenyumai/film-kit-hybrid` | Nano Banana stills + Kling video | fixed `kling-3.0` |
-| `@milenyumai/film-kit-hybrid-smart` | Nano Banana stills + smart Veo/Kling routing | dialogue-aware route |
-| `@milenyumai/film-kit-studio` | Scenario to rendered media | fal.ai Nano Banana + Kling render pipeline |
+## What Changed
 
-## Release Highlights
+- 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
 
-- Professional native Claude Code surfaces across all packages:
-  - valid `.claude/settings*.json`
-  - native `.claude/agents/*`
-  - cleanup of stale mode-specific Claude artifacts
-- Shared `spatial-blocking` skill for gaze, plane depth, light cohesion, compositing realism, and anti-miniature control.
-- Voice-design aware audio contract with project-level `voiceCast`, shot-level `Audio Plan`, and backward-compatible `Audio direction` blocks.
-- Aligned quality gates across Claude Code, Cursor, Copilot, and Antigravity.
-- Stronger Kling 3.0 and Kling multi-shot guidance, including practical route rules and hard caps.
-- OpenAI Codex App repo-scoped surfaces across packages:
-  - `.codex/config.toml` with full-auto local profile
-  - `.codex/agents/*.toml` custom agents that point back to Film-Kit roles
-  - `.agents/skills/*/SKILL.md` Codex skill mirror
-  - AGENTS.md project-root, trusted-project, and worktree bootstrap guidance
+## Install
 
-## Editors
+Requirements:
 
-All packages generate professional project surfaces for:
+- Node.js `>=20`
 
-- OpenAI Codex App
-- Claude Code
-- Cursor
-- GitHub Copilot
-- Antigravity
+Install:
 
-## OpenAI Codex App Support
-
-Film-Kit writes repo-scoped Codex files so the Codex desktop app can discover the project from the Git root:
-
-- `.codex/config.toml` uses `approval_policy = "never"`, `sandbox_mode = "danger-full-access"`, and `[agents] max_threads = 6`, `max_depth = 1`.
-- `.codex/agents/*.toml` defines minimal custom agents that read the canonical `.agent/agents/*.md` role files.
-- `.agents/skills/*/SKILL.md` mirrors the final `.agent/skills` runtime so Codex skill discovery sees package-specific overrides.
-- Studio adds a project-scoped fal.ai MCP entry at `.codex/config.toml` with `required = false`; missing `FAL_KEY` is reported during render rather than breaking init.
-- If Codex opens a worktree without dependencies or build output, follow `AGENTS.md`: run `npm install` and `npm run build` before package commands.
+```bash
+npm install --save-dev @milenyumai/film-kit
+```
 
-## Package Guide
+If it is already installed locally, the binary name is:
 
-### 1. `@milenyumai/film-kit`
+```bash
+npx film-kit init --preset single
+```
 
-Single-agent package for controlled shot-by-shot generation.
+Package-direct invocation also works:
 
 ```bash
-npx @milenyumai/film-kit init
-npx @milenyumai/film-kit init --model veo31
-npx @milenyumai/film-kit init --model kling-3.0 --kling-preset ultra-realism
+npx @milenyumai/film-kit init --preset single
 ```
 
-Best for:
+## Quick Start
 
-- solo work
-- smaller productions
-- manual supervision of every shot
+Initialize a project with one of the supported presets:
 
-Key contracts:
+```bash
+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
+```
 
-- one file per shot
-- hard quality floor: `ILK >= 80`, `SON >= 80`, `VIDEO >= 120`, `coverage >= 70`
-- shared spatial realism gate when subjects interact
+After the first run, Film-Kit writes `film-kit.config.json` and uses that file as the canonical project configuration.
 
-### 2. `@milenyumai/film-kit-multi`
+## Presets
 
-Parallel production package with Lead Director, shot teammates, and specialist validation.
+| 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 |
 
-```bash
-npx @milenyumai/film-kit-multi init
-npx @milenyumai/film-kit-multi init --model veo31
-npx @milenyumai/film-kit-multi init --model kling-3.0 --kling-preset ultra-realism
-```
+## Model Support
 
-Best for:
+### `veo31`
 
-- larger productions
-- 10+ shot sequences
-- team-style generation inside Claude Code Agent Teams or Antigravity Mission Control
+- 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
 
-Key contracts:
+### `seedance-2.0`
 
-- `team-plan.json`
-- 8 specialist validators in 3-phase execution (continuity -> parallel quality checks -> delivery)
-- parallel batch generation
-- spatial contract for multi-subject staging
+- 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
 
-### 3. `@milenyumai/film-kit-hybrid`
+### `kling-3.0`
 
-Hybrid package for Nano Banana still prompts and Kling 3.0 video prompts.
+- Supported in `single`, `multi`, and `studio`
+- Fixed inside `hybrid`
+- Part of the router inside `hybrid-smart`
+- Uses Kling-specific Start+End / storyboard prompt structure
 
-```bash
-npx @milenyumai/film-kit-hybrid init
-npx @milenyumai/film-kit-hybrid init --aspect 16:9 --nano-size 4K
-npx @milenyumai/film-kit-hybrid init --kling-preset balanced
-```
+### `kling-preset`
 
-Pipeline:
+`preset` and `kling-preset` are different things:
 
-- `ILK/SON` still prompts -> Nano Banana Pro / Google
-- `VIDEO` prompts -> Kling 3.0
+- `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`
 
-Key contracts:
+Supported `kling-preset` values:
 
-- one file per shot
-- route is always `kling-3.0`
-- app.kling custom storyboard cap: `4`
-- Kling prompt code blocks start with `[CHARACTER / SUBJECT CONSISTENCY]`
-- hybrid-specific spatial realism rules for layered blocking
+- `ultra-realism`
+- `balanced`
+- `custom`
 
-### 4. `@milenyumai/film-kit-hybrid-smart`
+When the active model is not Kling, generated runtime files intentionally render the Kling preset as `n/a (Kling-only)`.
 
-Hybrid package with Nano Banana stills and dialogue-aware video routing.
+## CLI
+
+Base command:
 
 ```bash
-npx @milenyumai/film-kit-hybrid-smart init
-npx @milenyumai/film-kit-hybrid-smart init --aspect 9:16 --nano-size 4K
-npx @milenyumai/film-kit-hybrid-smart init --kling-preset balanced
+npx @milenyumai/film-kit init --preset single|multi|hybrid|hybrid-smart|studio
 ```
 
-Pipeline:
-
-- `ILK/SON` still prompts -> Nano Banana Pro / Google
-- dialogue video sections -> Veo 3.1
-- no-dialogue video sections -> Kling 3.0
-
-Key contracts:
+Help:
 
-- per-section route declaration
-- Veo/Kling grammar separation
-- app.kling custom storyboard cap: `4`
-- Kling-routed no-dialogue prompt code blocks start with `[CHARACTER / SUBJECT CONSISTENCY]`
-- shared spatial realism gate
-
-## Shared Quality System
+```bash
+npx @milenyumai/film-kit --help
+```
 
-Film-Kit packages now share a stronger realism layer:
+Examples:
 
-- explicit eyeline targets
-- plane map for foreground / midground / background
-- body orientation alignment
-- shared motivated light source
-- depth and contact cues to avoid pasted-cutout or toy-scale results
+```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 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
+```
 
-This behavior is implemented through:
+### Common Flags
 
-- `.agent/skills/spatial-blocking/SKILL.md`
-- workflow hard gates
-- Claude local rules and native subagents
+| 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 |
 
-## Output Contract
+### Preset-Specific Flags
 
-All packages keep the same editorial mindset:
+| 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` |
 
-- one file per shot: `SHOTNN.md`
-- coverage stays inside the same shot file
-- reports are generated under `reports/`
-- continuity handoff is explicit
-- cut motivation and editorial purpose are mandatory
+### Supported Flag Values
 
-## Configuration Files
+| 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` |
 
-Core:
+## Canonical Config
 
-```json
-{
-  "outputDir": "./outputs",
-  "scenarioHint": "scenario.md",
-  "model": "kling-3.0",
-  "klingPreset": "ultra-realism"
-}
-```
+Film-Kit writes `film-kit.config.json` after initialization and reads it on future runs.
 
-Multi:
+Example:
 
 ```json
 {
+  "preset": "studio",
   "outputDir": "./outputs",
   "scenarioHint": "scenario.md",
-  "model": "kling-3.0",
+  "platforms": ["cursor", "claude", "copilot", "antigravity", "codex"],
+  "model": "seedance-2.0",
   "klingPreset": "ultra-realism",
   "maxTeammates": 5,
-  "batchSize": 4
+  "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
 }
 ```
 
-Hybrid:
+### 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`, `chain`, `safety-check`, `recover`, `finish`
+
+Editorial/runtime contract shared across the package:
 
-```json
-{
-  "outputDir": "./outputs",
-  "scenarioHint": "scenario.md",
-  "defaultAspectRatio": "16:9",
-  "nanoBananaImageSize": "2K",
-  "klingPreset": "ultra-realism"
-}
-```
+- one file per shot: `SHOTNN.md`
+- coverage lives inside the same shot file
+- report files live under `reports/`
+- 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`
 
-Smart hybrid:
+## Reference Locking And Start/End Consistency
 
-```json
-{
-  "outputDir": "./outputs",
-  "scenarioHint": "scenario.md",
-  "defaultAspectRatio": "16:9",
-  "nanoBananaImageSize": "2K",
-  "klingPreset": "ultra-realism",
-  "maxKlingCustomShots": 4
-}
+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:
+
+```ts
+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);
 ```
 
-## Development
+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:
 
 ```bash
-npm install
 npm run typecheck
 npm test
+npm run build
+npm pack --json --dry-run
+```
+
+Publish the single public package:
+
+```bash
+npm login
+npm whoami
+npm publish --access public
 ```
 
-Package publishing happens from:
+Optional validation before publish:
 
-- repo root for `@milenyumai/film-kit`
-- `packages/multi` for `@milenyumai/film-kit-multi`
-- `packages/hybrid` for `@milenyumai/film-kit-hybrid`
-- `packages/hybrid-smart` for `@milenyumai/film-kit-hybrid-smart`
-- `packages/studio` for `@milenyumai/film-kit-studio`
+```bash
+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:
+
+```bash
+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