@milenyumai/film-kit 1.4.3 → 2.0.0

package/README.md

@@ -1,239 +1,384 @@
 # 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:
+
+```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
+```
 
-Key contracts:
+After the first run, Film-Kit writes `film-kit.config.json` and uses that file as the canonical project configuration.
 
-- one file per shot
-- hard quality floor: `ILK >= 80`, `SON >= 80`, `VIDEO >= 120`, `coverage >= 70`
-- shared spatial realism gate when subjects interact
+## Presets
 
-### 2. `@milenyumai/film-kit-multi`
+| 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 |
 
-Parallel production package with Lead Director, shot teammates, and specialist validation.
+## Model Support
 
-```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
-```
+### `veo31`
 
-Best for:
+- 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
 
-- larger productions
-- 10+ shot sequences
-- team-style generation inside Claude Code Agent Teams or Antigravity Mission Control
+### `seedance-2.0`
 
-Key contracts:
+- 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
 
-- `team-plan.json`
-- 8 specialist validators in 3-phase execution (continuity -> parallel quality checks -> delivery)
-- parallel batch generation
-- spatial contract for multi-subject staging
+### `kling-3.0`
 
-### 3. `@milenyumai/film-kit-hybrid`
+- Supported in `single`, `multi`, and `studio`
+- Fixed inside `hybrid`
+- Part of the router inside `hybrid-smart`
+- Uses Kling-specific Start+End / storyboard prompt structure
 
-Hybrid package for Nano Banana still prompts and Kling 3.0 video prompts.
+### `kling-preset`
 
-```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
-```
+`preset` and `kling-preset` are different things:
 
-Pipeline:
+- `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`
 
-- `ILK/SON` still prompts -> Nano Banana Pro / Google
-- `VIDEO` prompts -> Kling 3.0
+Supported `kling-preset` values:
 
-Key contracts:
+- `ultra-realism`
+- `balanced`
+- `custom`
 
-- 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
+When the active model is not Kling, generated runtime files intentionally render the Kling preset as `n/a (Kling-only)`.
 
-### 4. `@milenyumai/film-kit-hybrid-smart`
+## CLI
 
-Hybrid package with Nano Banana stills and dialogue-aware video routing.
+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:
-
-- 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
+Help:
 
-## 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`
+
+## 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);
 ```
 
-Smart hybrid:
+For backward compatibility, `configureAgents()` is still exported for the single preset runtime, but new integrations should treat `configureFilmKit()` as the primary root API.
 
-```json
-{
-  "outputDir": "./outputs",
-  "scenarioHint": "scenario.md",
-  "defaultAspectRatio": "16:9",
-  "nanoBananaImageSize": "2K",
-  "klingPreset": "ultra-realism",
-  "maxKlingCustomShots": 4
-}
-```
+## 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:
 
-## Development
+- 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
 ```
 
-Package publishing happens from:
+Publish the single public package:
+
+```bash
+npm login
+npm whoami
+npm publish --access public
+```
 
-- 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`
+Optional validation before publish:
+
+```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
 

package/build/cli.js

@@ -1,83 +1,31 @@
 #!/usr/bin/env node
-import { configureAgents } from "./lib/configure.js";
+import { parseCliCommand, renderCliUsage } from "./lib/cli.js";
+import { configureFilmKit } from "./lib/film-kit.js";
 const args = process.argv.slice(2);
-const command = args[0];
-const overwrite = args.includes("--overwrite") || args.includes("-f");
-const SUPPORTED_MODELS = ["veo31", "kling-3.0"];
-const SUPPORTED_KLING_PRESETS = ["ultra-realism", "balanced", "custom"];
-function parseFlagValue(flag) {
-    const exactIndex = args.indexOf(flag);
-    if (exactIndex >= 0 && args[exactIndex + 1]) {
-        return args[exactIndex + 1];
+try {
+    const parsed = await parseCliCommand(args, process.cwd());
+    if (parsed.command === "help" || !parsed.options) {
+        console.log(renderCliUsage());
+        process.exit(0);
     }
-    const prefixed = args.find(a => a.startsWith(`${flag}=`));
-    if (prefixed) {
-        return prefixed.slice(flag.length + 1);
+    console.log(`🎬 Film-Kit: Configuring '${parsed.options.preset}' preset...\n`);
+    const result = await configureFilmKit(parsed.options);
+    if (result.written.length > 0) {
+        console.log(`✅ Files written: ${result.written.length}`);
+        result.written.forEach(file => console.log(`   ${file}`));
     }
-    return undefined;
-}
-function parseModel() {
-    const modelRaw = parseFlagValue("--model");
-    if (!modelRaw)
-        return undefined;
-    if (SUPPORTED_MODELS.includes(modelRaw)) {
-        return modelRaw;
-    }
-    throw new Error(`Invalid --model value: ${modelRaw}. Supported: ${SUPPORTED_MODELS.join(", ")}`);
-}
-function parseKlingPreset() {
-    const presetRaw = parseFlagValue("--kling-preset");
-    if (!presetRaw)
-        return undefined;
-    if (SUPPORTED_KLING_PRESETS.includes(presetRaw)) {
-        return presetRaw;
-    }
-    throw new Error(`Invalid --kling-preset value: ${presetRaw}. Supported: ${SUPPORTED_KLING_PRESETS.join(", ")}`);
-}
-if (command === "init") {
-    console.log("🎬 Film-Kit: Configuring AI agents...\n");
-    try {
-        const model = parseModel();
-        const klingPreset = parseKlingPreset();
-        const configureOptions = {
-            rootDir: process.cwd(),
-            overwrite
-        };
-        if (model)
-            configureOptions.model = model;
-        if (klingPreset)
-            configureOptions.klingPreset = klingPreset;
-        const result = await configureAgents(configureOptions);
-        if (result.written.length > 0) {
-            console.log(`✅ Files written: ${result.written.length}`);
-            result.written.forEach(f => console.log(`   ${f}`));
-        }
-        if (result.skipped.length > 0) {
-            console.log(`⏭️  Files skipped (already exist): ${result.skipped.length}`);
-        }
-        if (result.warnings.length > 0) {
-            console.log("\n⚠️  Warnings:");
-            result.warnings.forEach(w => console.log(`   - ${w}`));
-        }
-        console.log("\n🎬 Done! Your AI agents are configured for Hollywood-grade prompt engineering.");
-        console.log("   Use /generate in your AI editor to start creating shots.\n");
+    if (result.skipped.length > 0) {
+        console.log(`⏭️  Files skipped (already exist): ${result.skipped.length}`);
     }
-    catch (err) {
-        console.error("❌ Error:", err.message);
-        process.exit(1);
+    if (result.warnings.length > 0) {
+        console.log("\n⚠️  Warnings:");
+        result.warnings.forEach(warning => console.log(`   - ${warning}`));
     }
+    console.log(`\n🎬 Done! '${result.preset}' preset is active.`);
+    console.log(`   Canonical config: ${result.configPath}\n`);
 }
-else {
-    console.log(`
-🎬 @milenyumai/film-kit — Hollywood-grade prompt engineering (Veo 3.1 + Kling 3.0)
-
-Usage:
-  npx @milenyumai/film-kit init                                              Configure AI agents in current directory
-  npx @milenyumai/film-kit init --model veo31|kling-3.0                      Select target model profile
-  npx @milenyumai/film-kit init --model kling-3.0 --kling-preset ultra-realism|balanced|custom
-  npx @milenyumai/film-kit init --overwrite                                  Force update existing .agent content files
-
-Or install as a dependency (auto-configures on install):
-  npm install --save-dev @milenyumai/film-kit
-`);
+catch (err) {
+    console.error("❌ Error:", err.message);
+    console.log(renderCliUsage());
+    process.exit(1);
 }

package/build/index.d.ts

@@ -1,2 +1,3 @@
+export { configureFilmKit, detectFilmKitPreset, FILM_KIT_CONFIG_FILE, FILM_KIT_PRESETS, LEGACY_CONFIG_FILES } from "./lib/film-kit.js";
 export { configureAgents } from "./lib/configure.js";
-export type { AgentConfigOptions, ConfigureResult, KlingPreset, SupportedModel, SupportedPlatform } from "./lib/types.js";
+export type { AgentConfigOptions, ConfigureFilmKitResult, ConfigureResult, FilmKitConfigFile, FilmKitConfigOptions, FilmKitPreset, HybridAspectRatio, KlingPreset, NanoBananaImageSize, SupportedModel, SupportedPlatform } from "./lib/types.js";

package/build/index.js

@@ -1 +1,2 @@
+export { configureFilmKit, detectFilmKitPreset, FILM_KIT_CONFIG_FILE, FILM_KIT_PRESETS, LEGACY_CONFIG_FILES } from "./lib/film-kit.js";
 export { configureAgents } from "./lib/configure.js";

package/build/lib/cli.d.ts

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