npm package: @milenyumai/film-kit
Description: Hollywood-standard cinematic prompt engineering toolkit with model profiles (Veo 3.1 / Kling 3.0). Auto-configures AI agents (OpenAI Codex App, Cursor, Claude Code, VS Code Copilot, Antigravity) with production-grade shot generation system.
Latest version: 1.4.3

# Film-Kit

Professional cinematic prompt-engineering kits for OpenAI Codex App, Claude Code, Cursor, GitHub Copilot, and Antigravity.

Film-Kit ships as a single repository with five npm packages:

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

## Release Highlights

- 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

## Editors

All packages generate professional project surfaces for:

- OpenAI Codex App
- Claude Code
- Cursor
- GitHub Copilot
- Antigravity

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

## Package Guide

### 1. `@milenyumai/film-kit`

Single-agent package for controlled shot-by-shot generation.

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

Best for:

- solo work
- smaller productions
- manual supervision of every shot

Key contracts:

- one file per shot
- hard quality floor: `ILK >= 80`, `SON >= 80`, `VIDEO >= 120`, `coverage >= 70`
- shared spatial realism gate when subjects interact

### 2. `@milenyumai/film-kit-multi`

Parallel production package with Lead Director, shot teammates, and specialist validation.

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

Best for:

- larger productions
- 10+ shot sequences
- team-style generation inside Claude Code Agent Teams or Antigravity Mission Control

Key contracts:

- `team-plan.json`
- 8 specialist validators in 3-phase execution (continuity -> parallel quality checks -> delivery)
- parallel batch generation
- spatial contract for multi-subject staging

### 3. `@milenyumai/film-kit-hybrid`

Hybrid package for Nano Banana still prompts and Kling 3.0 video prompts.

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

Pipeline:

- `ILK/SON` still prompts -> Nano Banana Pro / Google
- `VIDEO` prompts -> Kling 3.0

Key contracts:

- 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

### 4. `@milenyumai/film-kit-hybrid-smart`

Hybrid package with Nano Banana stills and dialogue-aware video routing.

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

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

## Shared Quality System

Film-Kit packages now share a stronger realism layer:

- 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

This behavior is implemented through:

- `.agent/skills/spatial-blocking/SKILL.md`
- workflow hard gates
- Claude local rules and native subagents

## Output Contract

All packages keep the same editorial mindset:

- 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

## Configuration Files

Core:

```json
{
  "outputDir": "./outputs",
  "scenarioHint": "scenario.md",
  "model": "kling-3.0",
  "klingPreset": "ultra-realism"
}
```

Multi:

```json
{
  "outputDir": "./outputs",
  "scenarioHint": "scenario.md",
  "model": "kling-3.0",
  "klingPreset": "ultra-realism",
  "maxTeammates": 5,
  "batchSize": 4
}
```

Hybrid:

```json
{
  "outputDir": "./outputs",
  "scenarioHint": "scenario.md",
  "defaultAspectRatio": "16:9",
  "nanoBananaImageSize": "2K",
  "klingPreset": "ultra-realism"
}
```

Smart hybrid:

```json
{
  "outputDir": "./outputs",
  "scenarioHint": "scenario.md",
  "defaultAspectRatio": "16:9",
  "nanoBananaImageSize": "2K",
  "klingPreset": "ultra-realism",
  "maxKlingCustomShots": 4
}
```

## Development

```bash
npm install
npm run typecheck
npm test
```

Package publishing happens from:

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

## License

MIT