@milenyumai/film-kit 2.0.1 → 2.1.0

package/README.md

@@ -51,6 +51,8 @@ npx @milenyumai/film-kit init --preset studio --model seedance-2.0 --refs-dir ./
 
 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 |
@@ -238,13 +240,14 @@ Film-Kit writes repo-scoped runtime files for supported editors and agents. Depe
 - `.cursor/`
 - `.github/copilot-instructions.md`
 - `AGENTS.md`
-- runtime workflows such as `generate`, `chain`, `safety-check`, `recover`, `finish`
+- 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`

package/build/lib/templates.js

@@ -112,6 +112,91 @@ model_reasoning_effort = "high"
 developer_instructions = ${tomlString(developerInstructions)}
 `;
 }
+function buildCodexImageSkill(workflowFile, outputDir) {
+    return `---
+name: film-kit-codex-images
+description: Optional Codex-native still image phase for Film-Kit. Use after successful prompt generation when the user wants to create or iteratively edit accepted ILK FRAME and SON FRAME images inside Codex. Never auto-start; offer it after /generate and wait for user confirmation.
+---
+
+# Film-Kit Codex Images
+
+This skill is for **Codex only**. It adds a still-image phase after Film-Kit prompt generation.
+
+## Read First
+1. \`${workflowFile}\`
+2. \`.agent/model-profile.md\`
+3. the relevant shot files under \`${outputDir}/shots/\`
+4. \`${outputDir}/shot-plan.json\`
+5. report files under \`${outputDir}/reports/\` when the workflow requires them
+
+## Trigger Rules
+- Start only when the user explicitly asks for image generation/editing or accepts the \`/codex-images\` suggestion after \`/generate\`.
+- Do not auto-start this phase.
+- Do not use it for coverage stills or video generation in v1.
+
+## Core Behavior
+- Use Codex's built-in image generation/editing flow.
+- If a local image file must be edited, first bring it into the conversation context, then edit it.
+- Generate \`ILK FRAME\` from the accepted shot prompt plus references.
+- Generate \`SON FRAME\` by iterating from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
+- For chained shots, default the next shot's \`ILK FRAME\` to the previously accepted \`SON FRAME\` unless the user explicitly requests a fresh start.
+- After every image, ask the user to accept it or request a targeted edit.
+
+## Output Contract
+- Save accepted stills under \`${outputDir}/codex-images/SHOTNN/\`
+- Canonical files: \`ilk-frame.png\`, \`son-frame.png\`
+- Iterations use sibling versioned filenames such as \`ilk-frame-v2.png\` and \`son-frame-v3.png\`
+- Keep \`${outputDir}/codex-images/manifest.json\` updated
+- Keep \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` updated
+`;
+}
+function buildCodexImagesWorkflow(outputDir) {
+    return `---
+description: Optional Codex-native still image phase for Film-Kit single-agent output
+---
+
+# /codex-images - Film-Kit Codex Still Phase
+
+## Preconditions
+- \`/generate\` completed successfully
+- shot files already exist under \`${outputDir}/shots/\`
+- this phase is opt-in; start only after the user confirms
+
+## Reference Priority
+1. images already present in the active Codex conversation
+2. user-supplied local image paths
+3. repo-local \`refs/\` folders when present
+
+## Output Contract
+\`\`\`text
+${outputDir}/codex-images/
+├── SHOTNN/
+│   ├── ilk-frame.png
+│   ├── ilk-frame-v2.png
+│   ├── son-frame.png
+│   └── son-frame-v3.png
+├── manifest.json
+└── ../reports/CODEX-IMAGE-REPORT.md
+\`\`\`
+
+## Flow
+1. Ask which shot range to process. Default to sequential order.
+2. For a fresh shot, generate \`ILK FRAME\` from the accepted prompt plus references.
+3. Show the result and ask the user to accept it or request a targeted edit.
+4. Save the accepted start image as \`ilk-frame.png\`; keep previous attempts as versioned siblings.
+5. Generate \`SON FRAME\` by editing from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
+6. Show the result and ask the user to accept it or request a targeted edit.
+7. Save the accepted end image as \`son-frame.png\`; keep previous attempts as versioned siblings.
+8. If the next shot is chained, default its \`ILK FRAME\` to the accepted previous \`SON FRAME\` unless the user explicitly asks for a fresh start.
+9. Update \`${outputDir}/codex-images/manifest.json\` and \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` after each accepted image.
+
+## Hard Rules
+- Never auto-start this workflow.
+- V1 covers only main-shot \`ILK FRAME\` and \`SON FRAME\`.
+- Do not generate coverage stills or video here.
+- Preserve chain continuity unless the user explicitly requests a reset.
+`;
+}
 export function buildProjectFiles(config) {
     const files = {};
     // Runtime model profile file is generated from selected model options.
@@ -143,8 +228,11 @@ export function buildProjectFiles(config) {
         files[".codex/config.toml"] = buildCodexConfig();
         files[".codex/agents/prompt-engineer.toml"] = buildCodexAgentToml("prompt_engineer", "Film-Kit prompt engineer for single-agent cinematic shot generation, repair, and delivery QA.", `Read AGENTS.md first, then .agent/model-profile.md, .agent/MASTER.md, .agent/VOICE-DESIGN.md, .agent/agents/prompt-engineer.md, and the requested .agent/workflows/*.md file before acting.
 Use .agents/skills for Codex App skill discovery; .agent remains the Film-Kit legacy runtime source.
+When /generate finishes successfully inside Codex, always offer /codex-images as an optional still-image phase. Never auto-start it.
 Keep outputs under ${config.outputDir} unless the user explicitly changes the output contract.
 For worktree runs, if node_modules or build outputs are missing and package.json exists, bootstrap with npm install and npm run build before running package commands.`);
+        files[".agents/skills/film-kit-codex-images/SKILL.md"] = buildCodexImageSkill(".agent/workflows/codex-images.md", config.outputDir);
+        files[".agent/workflows/codex-images.md"] = buildCodexImagesWorkflow(config.outputDir);
         if (config.platforms.includes("antigravity")) {
             files[".agents/skills/shotforge-generate/SKILL.md"] = buildAntigravitySkill(config);
         }
@@ -190,11 +278,13 @@ All rules, skills, and workflows are located under \`.agent/\`.
 | \`/safety-check\` | \`.agent/workflows/safety-check.md\` |
 | \`/recover\` | \`.agent/workflows/recover.md\` |
 | \`/finish\` | \`.agent/workflows/finish.md\` |
+| \`/codex-images\` | \`.agent/workflows/codex-images.md\` |
 
 ## OpenAI Codex App
 - Open the Git root as the Codex project root; Codex discovers \`AGENTS.md\`, \`.codex/config.toml\`, and \`.agents/skills/\` from that root.
 - Repo-scoped Codex config lives in \`.codex/config.toml\`; Codex may ignore it until the project is trusted in the app.
 - Codex skills live under \`.agents/skills/*/SKILL.md\`; \`.agent/skills\` remains the legacy Film-Kit runtime mirror for Claude/Cursor/Copilot/Antigravity.
+- Codex-native still phase lives in \`.agents/skills/film-kit-codex-images/SKILL.md\` and starts with \`/codex-images\` only after user confirmation.
 - Codex custom agents live in \`.codex/agents/*.toml\` and point back to the canonical \`.agent/agents/*.md\` role files.
 - Full-auto Codex profile: \`approval_policy = "never"\`, \`sandbox_mode = "danger-full-access"\`, \`[agents] max_threads = 6\`, \`max_depth = 1\`.
 - Worktree bootstrap: if \`node_modules\` or build output is missing, run \`npm install\` and \`npm run build\` before package commands.
@@ -208,6 +298,7 @@ When the user asks \`/generate\`, convert the scenario into:
 - \`${config.outputDir}/reports/SEMANTIC-REPORT.md\` — Semantic consistency gate result
 - \`${config.outputDir}/reports/DELIVERY-REPORT.md\` — Delivery gate result
 - \`${config.outputDir}/_index.md\` — Shot list with chain & status tracking
+- Optional Codex still phase: \`${config.outputDir}/codex-images/manifest.json\` + \`${config.outputDir}/reports/CODEX-IMAGE-REPORT.md\`
 
 ## Input
 - Preferred scenario file: \`${config.scenarioHint}\`
@@ -420,6 +511,7 @@ Before generating ANY prompts, read skills from \`.agent/skills/\`:
 | \`/safety-check\` | \`.agent/workflows/safety-check.md\` |
 | \`/recover\` | \`.agent/workflows/recover.md\` |
 | \`/finish\` | \`.agent/workflows/finish.md\` |
+| \`/codex-images\` | \`.agent/workflows/codex-images.md\` |
 
 ## Claude Code Ops
 - Use \`/memory\` to verify which CLAUDE and rule files are loaded.
@@ -888,6 +980,7 @@ Before generating ANY prompts, read these skills:
 | /safety-check | \`.agent/workflows/safety-check.md\` — Validate before delivery |
 | /recover | \`.agent/workflows/recover.md\` — Recover failed gates |
 | /finish | \`.agent/workflows/finish.md\` — Complete project, create summary |
+| /codex-images | \`.agent/workflows/codex-images.md\` — Optional Codex-native still phase |
 
 ## Input
 - Scenario source: \`${config.scenarioHint}\` (or selected file in editor)

package/content/agents/prompt-engineer.md

@@ -46,6 +46,7 @@ You are a senior Technical Prompt Engineer specialized in model-aware cinematic
 16. **Hard specificity floor:** Her promptta lens/framing, lighting ve FG/MG/BG action detayları zorunlu
 17. **Spatial realism floor:** eyeline target, plane map, shared light source, contact/weight cues ve tam ölçek derinlik mantığı gerektiğinde zorunlu
 18. **Semantic consistency floor:** `shot-plan.json.visual_world` kanonik olmalı; perspective/geometry, shadow vector, scale map, reflection handling, gravity/contact physics, anatomy risk, foreground/background coherence, contextual contradiction, immutable reference lock ve allowed-change budget her shot'ta geçmeli
+19. **Codex still phase rule:** `/generate` başarıyla bittiyse ve çalışma Codex içindeyse `/codex-images` opsiyonunu öner; asla otomatik başlatma
 
 ---
 

package/content/workflows/generate.md

@@ -40,6 +40,8 @@ $OUTPUT_DIR/
 │   ├── SAFETY-REPORT.md     # Safety and policy validation
 │   ├── SEMANTIC-REPORT.md   # Perspective, shadow, scale, physics validation
 │   └── DELIVERY-REPORT.md   # Final packaging validation
+├── codex-images/            # Optional, created only after /codex-images is approved in Codex
+│   └── SHOTNN/              # Accepted ilk/son stills + versioned edits
 └── _index.md                # Shot list with status and report gate table
 ```
 
@@ -365,8 +367,11 @@ Delivery report: $OUTPUT_DIR/reports/DELIVERY-REPORT.md
 
 Devam etmek icin: 'devam et' veya '/chain'
 Tamamlama icin: '/finish'
+Codex'te opsiyonel still fazi icin: '/codex-images' (yalnizca kullanici onaylarsa)
 ```
 
+If generation succeeds inside Codex, offer `/codex-images` as an optional still-image phase. Never auto-start it.
+
 ---
 
 ## Reject Weak Prompt Style

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@milenyumai/film-kit",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Single-package Film-Kit distribution with preset-driven cinematic runtime setup for OpenAI Codex App, Claude Code, Cursor, Copilot, and Antigravity.",
   "type": "module",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
   "bin": {
-    "film-kit": "./build/cli.js"
+    "film-kit": "build/cli.js"
   },
   "exports": {
     ".": {

package/packages/hybrid/README.md

@@ -30,6 +30,7 @@ npx @milenyumai/film-kit init --preset hybrid --aspect 16:9 --nano-size 4K
 - OpenAI Codex App / Cursor / Copilot / Antigravity surfaces
 - `.codex/config.toml` + `.codex/agents/prompt-engineer.toml`
 - `.agents/skills/*/SKILL.md` Codex skill mirror with the hybrid prompt-structure override
+- optional Codex still phase via `.agents/skills/film-kit-codex-images/SKILL.md` and `/codex-images`
 - hybrid overrides and prompt-structure overrides
 
 ## Contracts

package/packages/hybrid/build/lib/templates.js

@@ -20,6 +20,92 @@ model_reasoning_effort = "high"
 developer_instructions = ${tomlString(developerInstructions)}
 `;
 }
+function buildCodexImageSkill(workflowFile, outputDir) {
+    return `---
+name: film-kit-codex-images
+description: Optional Codex-native still image phase for Film-Kit Hybrid. Use after successful prompt generation when the user wants to create or iteratively edit accepted ILK FRAME and SON FRAME images inside Codex. Never auto-start; offer it after /generate and wait for user confirmation.
+---
+
+# Film-Kit Codex Images
+
+This skill is for **Codex only**. It adds a still-image phase after Film-Kit prompt generation.
+
+## Read First
+1. \`${workflowFile}\`
+2. \`.agent/model-profile.md\`
+3. \`${outputDir}/shot-plan.json\`
+4. the relevant shot files under \`${outputDir}/shots/\`
+5. report files under \`${outputDir}/reports/\`
+
+## Trigger Rules
+- Start only when the user explicitly asks for image generation/editing or accepts the \`/codex-images\` suggestion after \`/generate\`.
+- Do not auto-start this phase.
+- Do not use it for coverage stills or video generation in v1.
+
+## Core Behavior
+- Use Codex's built-in image generation/editing flow.
+- If a local image file must be edited, first bring it into the conversation context, then edit it.
+- Generate \`ILK FRAME\` from the accepted shot prompt plus references.
+- Generate \`SON FRAME\` by iterating from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
+- For chained shots, default the next shot's \`ILK FRAME\` to the previously accepted \`SON FRAME\` unless the user explicitly requests a fresh start.
+- After every image, ask the user to accept it or request a targeted edit.
+
+## Output Contract
+- Save accepted stills under \`${outputDir}/codex-images/SHOTNN/\`
+- Canonical files: \`ilk-frame.png\`, \`son-frame.png\`
+- Iterations use sibling versioned filenames such as \`ilk-frame-v2.png\` and \`son-frame-v3.png\`
+- Keep \`${outputDir}/codex-images/manifest.json\` updated
+- Keep \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` updated
+`;
+}
+function buildCodexImagesWorkflow(outputDir) {
+    return `---
+description: Optional Codex-native still image phase for Film-Kit Hybrid output
+---
+
+# /codex-images - Film-Kit Hybrid Codex Still Phase
+
+## Preconditions
+- \`/generate\` completed successfully
+- shot files already exist under \`${outputDir}/shots/\`
+- \`${outputDir}/shot-plan.json\` exists
+- this phase is opt-in; start only after the user confirms
+
+## Reference Priority
+1. images already present in the active Codex conversation
+2. user-supplied local image paths
+3. repo-local \`refs/\` folders when present
+
+## Output Contract
+\`\`\`text
+${outputDir}/codex-images/
+├── SHOTNN/
+│   ├── ilk-frame.png
+│   ├── ilk-frame-v2.png
+│   ├── son-frame.png
+│   └── son-frame-v3.png
+├── manifest.json
+└── ../reports/CODEX-IMAGE-REPORT.md
+\`\`\`
+
+## Flow
+1. Ask which shot range to process. Default to sequential order.
+2. For a fresh shot, generate \`ILK FRAME\` from the accepted still prompt plus references.
+3. Show the result and ask the user to accept it or request a targeted edit.
+4. Save the accepted start image as \`ilk-frame.png\`; keep previous attempts as versioned siblings.
+5. Generate \`SON FRAME\` by editing from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
+6. Show the result and ask the user to accept it or request a targeted edit.
+7. Save the accepted end image as \`son-frame.png\`; keep previous attempts as versioned siblings.
+8. If the next shot is chained, default its \`ILK FRAME\` to the accepted previous \`SON FRAME\` unless the user explicitly asks for a fresh start.
+9. Update \`${outputDir}/codex-images/manifest.json\` and \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` after each accepted image.
+
+## Hard Rules
+- Never auto-start this workflow.
+- V1 covers only main-shot \`ILK FRAME\` and \`SON FRAME\`.
+- Do not generate coverage stills or video here.
+- Preserve chain continuity unless the user explicitly requests a reset.
+`;
+}
 export function buildHybridProjectFiles(config) {
     const files = {};
     files[".agent/model-profile.md"] = buildModelProfile(config);
@@ -51,8 +137,11 @@ export function buildHybridProjectFiles(config) {
         files[".codex/agents/prompt-engineer.toml"] = buildCodexAgentToml("prompt_engineer", "Film-Kit hybrid prompt engineer for Nano Banana start/end frames and Kling 3.0 video prompts.", `Read AGENTS.md first, then .agent/model-profile.md, .agent/MASTER.md, .agent/VOICE-DESIGN.md, .agent/HYBRID-OVERRIDES.md, .agent/agents/prompt-engineer.md, and the requested .agent/workflows/*.md file before acting.
 Use .agents/skills for Codex App skill discovery; .agent remains the Film-Kit legacy runtime source.
 Use the hybrid .agents/skills/prompt-structure/SKILL.md override for Kling 3.0 VIDEO grammar.
+When /generate finishes successfully inside Codex, always offer /codex-images as an optional still-image phase. Never auto-start it.
 Keep outputs under ${config.outputDir} unless the user explicitly changes the output contract.
 For worktree runs, if node_modules or build outputs are missing and package.json exists, bootstrap with npm install and npm run build before package commands.`);
+        files[".agents/skills/film-kit-codex-images/SKILL.md"] = buildCodexImageSkill(".agent/workflows/codex-images-hybrid.md", config.outputDir);
+        files[".agent/workflows/codex-images-hybrid.md"] = buildCodexImagesWorkflow(config.outputDir);
         if (config.platforms.includes("antigravity")) {
             files[".agents/skills/shotforge-generate/SKILL.md"] = buildAntigravitySkill(config);
         }
@@ -81,6 +170,7 @@ Hybrid image/video prompt generation.
 - Open the Git root as the Codex project root; Codex discovers \`AGENTS.md\`, \`.codex/config.toml\`, and \`.agents/skills/\` from that root.
 - Repo-scoped Codex config lives in \`.codex/config.toml\`; Codex may ignore it until the project is trusted in the app.
 - Codex skills live under \`.agents/skills/*/SKILL.md\`; \`.agent/skills\` remains the legacy Film-Kit runtime mirror for Claude/Cursor/Copilot/Antigravity.
+- Codex-native still phase lives in \`.agents/skills/film-kit-codex-images/SKILL.md\` and starts with \`/codex-images\` only after user confirmation.
 - Codex custom agents live in \`.codex/agents/*.toml\` and point back to the canonical \`.agent/agents/*.md\` role files.
 - Full-auto Codex profile: \`approval_policy = "never"\`, \`sandbox_mode = "danger-full-access"\`, \`[agents] max_threads = 6\`, \`max_depth = 1\`.
 - Worktree bootstrap: if \`node_modules\` or build output is missing, run \`npm install\` and \`npm run build\` before package commands.
@@ -101,6 +191,7 @@ Hybrid image/video prompt generation.
 - ONE FILE PER SHOT: \`SHOTNN.md\` includes main shot + coverage
 - \`${config.outputDir}/shot-plan.json\` carries top-level \`voiceCast\`
 - \`${config.outputDir}/shot-plan.json\` carries top-level \`visual_world\`
+- Optional Codex still phase: \`${config.outputDir}/codex-images/manifest.json\` + \`${config.outputDir}/reports/CODEX-IMAGE-REPORT.md\`
 - Image sections (ILK/SON + still coverage prompts) are written for ${config.imageModelDisplay}
 - Video sections are written for ${config.videoModelDisplay}
 - Speaking \`VIDEO\` sections include machine-readable \`AUDIO PLAN\`
@@ -115,6 +206,7 @@ Hybrid image/video prompt generation.
 - Default aspect ratio: \`${config.defaultAspectRatio}\`
 - Nano Banana target size: \`${config.nanoBananaImageSize}\`
 - Kling preset: \`${config.klingPreset}\`
+- Codex still workflow: \`.agent/workflows/codex-images-hybrid.md\`
 `;
 }
 function buildCursorLegacyRules(config) {
@@ -231,6 +323,7 @@ function buildClaudeRoot(config) {
 
 ## Workflows
 - /generate -> \`.agent/workflows/generate.md\`
+- /codex-images -> \`.agent/workflows/codex-images-hybrid.md\`
 - /chain -> \`.agent/workflows/chain.md\`
 - /safety-check -> \`.agent/workflows/safety-check.md\`
 - /recover -> \`.agent/workflows/recover.md\`
@@ -247,6 +340,7 @@ This workspace uses a split model workflow.
 Always read \`.agent/model-profile.md\`, \`.agent/HYBRID-OVERRIDES.md\`, and \`.claude/rules/*\` before /generate.
 Read \`.agent/VOICE-DESIGN.md\` whenever dialogue, narrator VO, or reusable speaker identity exists.
 Use \`.claude/agents/prompt-engineer.md\` for shot drafting or repair when delegation helps.
+If Codex completed \`/generate\`, offer \`/codex-images\` as an opt-in still phase instead of auto-starting it.
 Apply \`.agent/skills/spatial-blocking/SKILL.md\` whenever gaze, compositing, or depth realism is critical.
 Write shot files to \`${config.outputDir}/shots/SHOTNN.md\`.
 `;

package/packages/hybrid/content/workflows/generate.md

@@ -103,6 +103,9 @@ For each `SHOTNN.md`:
 10. Reject outputs with disconnected eyelines, pasted-cutout compositing, or toy-scale depth caused by missing plane/light integration.
 11. Reject outputs that violate `visual_world`, shadow vector, scale/depth, reflection/physics/anatomy, contextual logic, targeted semantic avoid terms, reference drift, allowed-change budget, or chained ILK exact-reuse rules.
 
+### 4. Codex Follow-up
+If this workflow is running inside Codex and generation succeeds, offer `/codex-images` as an optional still-image phase. Never auto-start it.
+
 ## Non-Negotiables
 - ONE FILE PER SHOT (`SHOTNN.md` includes coverage)
 - Avoid line on every prompt

package/packages/hybrid-smart/README.md

@@ -32,6 +32,7 @@ npx @milenyumai/film-kit init --preset hybrid-smart --kling-preset balanced
 - OpenAI Codex App / Cursor / Copilot / Antigravity surfaces
 - `.codex/config.toml` + `.codex/agents/prompt-engineer.toml`
 - `.agents/skills/*/SKILL.md` Codex skill mirror with the smart hybrid prompt-structure override
+- optional Codex still phase via `.agents/skills/film-kit-codex-images/SKILL.md` and `/codex-images`
 - smart hybrid overrides and route-aware prompt-structure overrides
 
 ## Contracts

package/packages/hybrid-smart/build/lib/templates.js

@@ -20,6 +20,92 @@ model_reasoning_effort = "high"
 developer_instructions = ${tomlString(developerInstructions)}
 `;
 }
+function buildCodexImageSkill(workflowFile, outputDir) {
+    return `---
+name: film-kit-codex-images
+description: Optional Codex-native still image phase for Film-Kit Hybrid Smart. Use after successful prompt generation when the user wants to create or iteratively edit accepted ILK FRAME and SON FRAME images inside Codex. Never auto-start; offer it after /generate and wait for user confirmation.
+---
+
+# Film-Kit Codex Images
+
+This skill is for **Codex only**. It adds a still-image phase after Film-Kit prompt generation.
+
+## Read First
+1. \`${workflowFile}\`
+2. \`.agent/model-profile.md\`
+3. \`${outputDir}/shot-plan.json\`
+4. the relevant shot files under \`${outputDir}/shots/\`
+5. report files under \`${outputDir}/reports/\`
+
+## Trigger Rules
+- Start only when the user explicitly asks for image generation/editing or accepts the \`/codex-images\` suggestion after \`/generate\`.
+- Do not auto-start this phase.
+- Do not use it for coverage stills or video generation in v1.
+
+## Core Behavior
+- Use Codex's built-in image generation/editing flow.
+- If a local image file must be edited, first bring it into the conversation context, then edit it.
+- Generate \`ILK FRAME\` from the accepted shot prompt plus references.
+- Generate \`SON FRAME\` by iterating from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
+- For chained shots, default the next shot's \`ILK FRAME\` to the previously accepted \`SON FRAME\` unless the user explicitly requests a fresh start.
+- After every image, ask the user to accept it or request a targeted edit.
+
+## Output Contract
+- Save accepted stills under \`${outputDir}/codex-images/SHOTNN/\`
+- Canonical files: \`ilk-frame.png\`, \`son-frame.png\`
+- Iterations use sibling versioned filenames such as \`ilk-frame-v2.png\` and \`son-frame-v3.png\`
+- Keep \`${outputDir}/codex-images/manifest.json\` updated
+- Keep \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` updated
+`;
+}
+function buildCodexImagesWorkflow(outputDir) {
+    return `---
+description: Optional Codex-native still image phase for Film-Kit Hybrid Smart output
+---
+
+# /codex-images - Film-Kit Hybrid Smart Codex Still Phase
+
+## Preconditions
+- \`/generate\` completed successfully
+- shot files already exist under \`${outputDir}/shots/\`
+- \`${outputDir}/shot-plan.json\` exists
+- this phase is opt-in; start only after the user confirms
+
+## Reference Priority
+1. images already present in the active Codex conversation
+2. user-supplied local image paths
+3. repo-local \`refs/\` folders when present
+
+## Output Contract
+\`\`\`text
+${outputDir}/codex-images/
+├── SHOTNN/
+│   ├── ilk-frame.png
+│   ├── ilk-frame-v2.png
+│   ├── son-frame.png
+│   └── son-frame-v3.png
+├── manifest.json
+└── ../reports/CODEX-IMAGE-REPORT.md
+\`\`\`
+
+## Flow
+1. Ask which shot range to process. Default to sequential order.
+2. For a fresh shot, generate \`ILK FRAME\` from the accepted still prompt plus references.
+3. Show the result and ask the user to accept it or request a targeted edit.
+4. Save the accepted start image as \`ilk-frame.png\`; keep previous attempts as versioned siblings.
+5. Generate \`SON FRAME\` by editing from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
+6. Show the result and ask the user to accept it or request a targeted edit.
+7. Save the accepted end image as \`son-frame.png\`; keep previous attempts as versioned siblings.
+8. If the next shot is chained, default its \`ILK FRAME\` to the accepted previous \`SON FRAME\` unless the user explicitly asks for a fresh start.
+9. Update \`${outputDir}/codex-images/manifest.json\` and \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` after each accepted image.
+
+## Hard Rules
+- Never auto-start this workflow.
+- V1 covers only main-shot \`ILK FRAME\` and \`SON FRAME\`.
+- Do not generate coverage stills or video here.
+- Preserve chain continuity unless the user explicitly requests a reset.
+`;
+}
 export function buildSmartHybridProjectFiles(config) {
     const files = {};
     files[".agent/model-profile.md"] = buildModelProfile(config);
@@ -51,8 +137,11 @@ export function buildSmartHybridProjectFiles(config) {
         files[".codex/agents/prompt-engineer.toml"] = buildCodexAgentToml("prompt_engineer", "Film-Kit smart hybrid prompt engineer for Nano Banana stills and dialogue-aware Veo/Kling routing.", `Read AGENTS.md first, then .agent/model-profile.md, .agent/MASTER.md, .agent/VOICE-DESIGN.md, .agent/SMART-HYBRID-OVERRIDES.md, .agent/agents/prompt-engineer.md, and the requested .agent/workflows/*.md file before acting.
 Use .agents/skills for Codex App skill discovery; .agent remains the Film-Kit legacy runtime source.
 Use the smart hybrid .agents/skills/prompt-structure/SKILL.md override for Veo dialogue routes and Kling no-dialogue routes.
+When /generate finishes successfully inside Codex, always offer /codex-images as an optional still-image phase. Never auto-start it.
 Keep outputs under ${config.outputDir} unless the user explicitly changes the output contract.
 For worktree runs, if node_modules or build outputs are missing and package.json exists, bootstrap with npm install and npm run build before package commands.`);
+        files[".agents/skills/film-kit-codex-images/SKILL.md"] = buildCodexImageSkill(".agent/workflows/codex-images-hybrid-smart.md", config.outputDir);
+        files[".agent/workflows/codex-images-hybrid-smart.md"] = buildCodexImagesWorkflow(config.outputDir);
         if (config.platforms.includes("antigravity")) {
             files[".agents/skills/shotforge-generate/SKILL.md"] = buildAntigravitySkill(config);
         }
@@ -82,6 +171,7 @@ Smart hybrid image/video prompt generation.
 - Open the Git root as the Codex project root; Codex discovers \`AGENTS.md\`, \`.codex/config.toml\`, and \`.agents/skills/\` from that root.
 - Repo-scoped Codex config lives in \`.codex/config.toml\`; Codex may ignore it until the project is trusted in the app.
 - Codex skills live under \`.agents/skills/*/SKILL.md\`; \`.agent/skills\` remains the legacy Film-Kit runtime mirror for Claude/Cursor/Copilot/Antigravity.
+- Codex-native still phase lives in \`.agents/skills/film-kit-codex-images/SKILL.md\` and starts with \`/codex-images\` only after user confirmation.
 - Codex custom agents live in \`.codex/agents/*.toml\` and point back to the canonical \`.agent/agents/*.md\` role files.
 - Full-auto Codex profile: \`approval_policy = "never"\`, \`sandbox_mode = "danger-full-access"\`, \`[agents] max_threads = 6\`, \`max_depth = 1\`.
 - Worktree bootstrap: if \`node_modules\` or build output is missing, run \`npm install\` and \`npm run build\` before package commands.
@@ -102,6 +192,7 @@ Smart hybrid image/video prompt generation.
 - ONE FILE PER SHOT: \`SHOTNN.md\` includes main shot + coverage
 - \`${config.outputDir}/shot-plan.json\` carries top-level \`voiceCast\`
 - \`${config.outputDir}/shot-plan.json\` carries top-level \`visual_world\`
+- Optional Codex still phase: \`${config.outputDir}/codex-images/manifest.json\` + \`${config.outputDir}/reports/CODEX-IMAGE-REPORT.md\`
 - Image sections (ILK/SON + still coverage prompts) are written for ${config.imageModelDisplay}
 - Video sections are routed by dialogue presence (dialogue->${config.veoVideoModelId}, no-dialogue->${config.klingVideoModelId})
 - Speaking video sections include machine-readable \`AUDIO PLAN\`
@@ -117,6 +208,7 @@ Smart hybrid image/video prompt generation.
 - Nano Banana target size: \`${config.nanoBananaImageSize}\`
 - Kling preset: \`${config.klingPreset}\`
 - Kling custom shot max (app.kling): \`${config.maxKlingCustomShots}\`
+- Codex still workflow: \`.agent/workflows/codex-images-hybrid-smart.md\`
 `;
 }
 function buildCursorLegacyRules(config) {
@@ -233,6 +325,7 @@ function buildClaudeRoot(config) {
 
 ## Workflows
 - /generate -> \`.agent/workflows/generate.md\`
+- /codex-images -> \`.agent/workflows/codex-images-hybrid-smart.md\`
 - /chain -> \`.agent/workflows/chain.md\`
 - /safety-check -> \`.agent/workflows/safety-check.md\`
 - /recover -> \`.agent/workflows/recover.md\`
@@ -249,6 +342,7 @@ This workspace uses a split model workflow.
 Always read \`.agent/model-profile.md\`, \`.agent/SMART-HYBRID-OVERRIDES.md\`, and \`.claude/rules/*\` before /generate.
 Read \`.agent/VOICE-DESIGN.md\` whenever dialogue, narrator VO, or reusable speaker identity exists.
 Use \`.claude/agents/prompt-engineer.md\` for shot drafting or repair when delegation helps.
+If Codex completed \`/generate\`, offer \`/codex-images\` as an opt-in still phase instead of auto-starting it.
 Apply \`.agent/skills/spatial-blocking/SKILL.md\` whenever gaze, compositing, or depth realism is critical.
 Write shot files to \`${config.outputDir}/shots/SHOTNN.md\`.
 `;

package/packages/hybrid-smart/content/workflows/generate.md

@@ -115,6 +115,9 @@ For each `SHOTNN.md`:
 12. Reject outputs with disconnected eyelines, pasted-cutout compositing, or toy-scale depth caused by missing plane/light integration.
 13. Reject outputs that violate `visual_world`, shadow vector, scale/depth, reflection/physics/anatomy, contextual logic, targeted semantic avoid terms, reference drift, allowed-change budget, or chained ILK exact-reuse rules.
 
+### 4. Codex Follow-up
+If this workflow is running inside Codex and generation succeeds, offer `/codex-images` as an optional still-image phase. Never auto-start it.
+
 ## Non-Negotiables
 - ONE FILE PER SHOT (`SHOTNN.md` includes coverage)
 - Avoid line on every prompt

package/packages/multi/README.md

@@ -33,6 +33,7 @@ npx @milenyumai/film-kit init --preset multi --model seedance-2.0
 - OpenAI Codex App config under `.codex/config.toml`
 - OpenAI Codex custom agents under `.codex/agents/*.toml`
 - Codex skill mirror under `.agents/skills/*/SKILL.md`
+- optional Codex still phase via `.agents/skills/film-kit-codex-images/SKILL.md` and `/codex-images`
 - multi rules under `.claude/rules/`
 - Antigravity skills:
   - `.agent/skills/shotforge-generate/SKILL.md`
@@ -69,6 +70,7 @@ Specialists run in three phases after all shot batches complete:
 ## Workflow
 
 - `/generate` -> lead planning + teammate spawning + 3-phase specialist validation
+- `/codex-images` -> optional Codex-native still phase after all reports pass
 - `/chain` -> chained continuation
 - `/safety-check` -> specialist validation
 - `/recover` -> deterministic recovery with impacted range definition

package/packages/multi/build/lib/configure.js

@@ -242,7 +242,9 @@ export async function configureMultiAgents(options = {}) {
             || relativePath === ".agent/skills/shotforge-generate-multi/SKILL.md";
         const isCodexConfig = relativePath.startsWith(".codex/")
             || relativePath === ".agents/skills/shotforge-generate/SKILL.md"
-            || relativePath === ".agents/skills/shotforge-generate-multi/SKILL.md";
+            || relativePath === ".agents/skills/shotforge-generate-multi/SKILL.md"
+            || relativePath === ".agents/skills/film-kit-codex-images/SKILL.md"
+            || relativePath === ".agent/workflows/codex-images-multi.md";
         const isRuntimeModelFile = relativePath === ".agent/model-profile.md";
         if (fileExists && !isClaudeConfig && !isAntigravityConfig && !isCodexConfig && !isRuntimeModelFile && !resolved.overwrite) {
             skipped.push(relativePath);

package/packages/multi/build/lib/templates.js

@@ -126,12 +126,104 @@ const MULTI_CODEX_AGENTS = [
     ["delivery-editor", "delivery_editor", "Audit final package completeness, report dependencies, and delivery readiness."]
 ];
 function buildMultiCodexAgent(roleFile, name, description, config) {
+    const leadDirectorNote = roleFile === "lead-director"
+        ? "\nWhen /generate finishes successfully inside Codex and every required specialist report passes, offer /codex-images as an optional still-image phase. Never auto-start it."
+        : "";
     return buildCodexAgentToml(name, description, `Read AGENTS.md first, then .agent/model-profile.md, .agent/MASTER.md, .agent/VOICE-DESIGN.md, .agent/agents/${roleFile}.md, and the relevant .agent/workflows/*.md file before acting.
 Use .agents/skills for Codex App skill discovery; .agent remains the Film-Kit legacy runtime source.
 Respect file ownership from AGENTS.md: shot teammates write only assigned SHOTNN.md files, specialists write only their report files, and the Lead owns plan/index/final summary files.
+${leadDirectorNote}
 Keep outputs under ${config.outputDir} unless the user explicitly changes the output contract.
 For worktree runs, if node_modules or build outputs are missing and package.json exists, bootstrap with npm install and npm run build before package commands.`);
 }
+function buildCodexImageSkill(workflowFile, outputDir) {
+    return `---
+name: film-kit-codex-images
+description: Optional Codex-native still image phase for Film-Kit Multi. Use after successful prompt generation when the user wants to create or iteratively edit accepted ILK FRAME and SON FRAME images inside Codex. Never auto-start; offer it only after all required reports pass and the user confirms.
+---
+
+# Film-Kit Codex Images
+
+This skill is for **Codex only**. It adds a still-image phase after Film-Kit prompt generation and specialist validation.
+
+## Read First
+1. \`${workflowFile}\`
+2. \`.agent/model-profile.md\`
+3. \`${outputDir}/team-plan.json\`
+4. the relevant shot files under \`${outputDir}/shots/\`
+5. all required report files under \`${outputDir}/reports/\`
+
+## Trigger Rules
+- Start only when the user explicitly asks for image generation/editing or accepts the \`/codex-images\` suggestion after \`/generate\`.
+- Do not auto-start this phase.
+- Only offer it after all mandatory specialist reports pass.
+- Do not use it for coverage stills or video generation in v1.
+
+## Core Behavior
+- Use Codex's built-in image generation/editing flow.
+- If a local image file must be edited, first bring it into the conversation context, then edit it.
+- Generate \`ILK FRAME\` from the accepted shot prompt plus references.
+- Generate \`SON FRAME\` by iterating from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
+- For chained shots, default the next shot's \`ILK FRAME\` to the previously accepted \`SON FRAME\` unless the user explicitly requests a fresh start.
+- After every image, ask the user to accept it or request a targeted edit.
+
+## Output Contract
+- Save accepted stills under \`${outputDir}/codex-images/SHOTNN/\`
+- Canonical files: \`ilk-frame.png\`, \`son-frame.png\`
+- Iterations use sibling versioned filenames such as \`ilk-frame-v2.png\` and \`son-frame-v3.png\`
+- Keep \`${outputDir}/codex-images/manifest.json\` updated
+- Keep \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` updated
+`;
+}
+function buildCodexImagesWorkflow(outputDir) {
+    return `---
+description: Optional Codex-native still image phase for Film-Kit Multi output
+---
+
+# /codex-images - Film-Kit Multi Codex Still Phase
+
+## Preconditions
+- \`/generate\` completed successfully
+- shot files already exist under \`${outputDir}/shots/\`
+- \`${outputDir}/team-plan.json\` exists
+- every mandatory specialist report under \`${outputDir}/reports/\` passed
+- this phase is opt-in; start only after the user confirms
+
+## Reference Priority
+1. images already present in the active Codex conversation
+2. user-supplied local image paths
+3. repo-local \`refs/\` folders when present
+
+## Output Contract
+\`\`\`text
+${outputDir}/codex-images/
+├── SHOTNN/
+│   ├── ilk-frame.png
+│   ├── ilk-frame-v2.png
+│   ├── son-frame.png
+│   └── son-frame-v3.png
+├── manifest.json
+└── ../reports/CODEX-IMAGE-REPORT.md
+\`\`\`
+
+## Flow
+1. Process shots sequentially unless the user explicitly requests a different order.
+2. For a fresh shot, generate \`ILK FRAME\` from the accepted still prompt plus references.
+3. Show the result and ask the user to accept it or request a targeted edit.
+4. Save the accepted start image as \`ilk-frame.png\`; keep previous attempts as versioned siblings.
+5. Generate \`SON FRAME\` by editing from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
+6. Show the result and ask the user to accept it or request a targeted edit.
+7. Save the accepted end image as \`son-frame.png\`; keep previous attempts as versioned siblings.
+8. If the next shot is chained, default its \`ILK FRAME\` to the accepted previous \`SON FRAME\` unless the user explicitly asks for a fresh start.
+9. Update \`${outputDir}/codex-images/manifest.json\` and \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` after each accepted image.
+
+## Hard Rules
+- Never auto-start this workflow.
+- V1 covers only main-shot \`ILK FRAME\` and \`SON FRAME\`.
+- Do not generate coverage stills or video here.
+- Preserve chain continuity unless the user explicitly requests a reset.
+`;
+}
 /**
  * Build project files for multi-agent mode.
  * Generates Claude Code configs plus Antigravity multi orchestration skills.
@@ -471,6 +563,8 @@ Use this playbook when a teammate fails or a quality gate fails.
     for (const [roleFile, name, description] of MULTI_CODEX_AGENTS) {
         files[`.codex/agents/${roleFile}.toml`] = buildMultiCodexAgent(roleFile, name, description, config);
     }
+    files[".agents/skills/film-kit-codex-images/SKILL.md"] = buildCodexImageSkill(".agent/workflows/codex-images-multi.md", config.outputDir);
+    files[".agent/workflows/codex-images-multi.md"] = buildCodexImagesWorkflow(config.outputDir);
     if (config.includeAgentsMd) {
         files["AGENTS.md"] = `# Film-Kit Multi - Agent Teams Contract
 
@@ -497,6 +591,7 @@ Multi-agent parallel generation with shot teammates and specialist validators.
 - Team plan is stored in \`${config.outputDir}/team-plan.json\`
 - \`${config.outputDir}/team-plan.json\` is also the authoritative top-level \`voiceCast\` package
 - \`${config.outputDir}/team-plan.json\` is also the authoritative top-level \`visual_world\` package
+- Optional Codex still phase: \`${config.outputDir}/codex-images/manifest.json\` + \`${config.outputDir}/reports/CODEX-IMAGE-REPORT.md\`
 - Batch reports are stored in \`${config.outputDir}/reports/\`
 - Specialist reports are mandatory before completion:
   - \`${config.outputDir}/reports/CONTINUITY-REPORT.md\`
@@ -511,6 +606,7 @@ Multi-agent parallel generation with shot teammates and specialist validators.
 
 ## Workflows
 - \`/generate\` -> \`.agent/workflows/generate-multi.md\`
+- \`/codex-images\` -> \`.agent/workflows/codex-images-multi.md\`
 - \`/chain\` -> \`.agent/workflows/chain-multi.md\`
 - \`/safety-check\` -> \`.agent/workflows/safety-check-multi.md\`
 - \`/recover\` -> \`.agent/workflows/recover-multi.md\`
@@ -520,6 +616,7 @@ Multi-agent parallel generation with shot teammates and specialist validators.
 - Open the Git root as the Codex project root; Codex discovers \`AGENTS.md\`, \`.codex/config.toml\`, and \`.agents/skills/\` from that root.
 - Repo-scoped Codex config lives in \`.codex/config.toml\`; Codex may ignore it until the project is trusted in the app.
 - Codex skills live under \`.agents/skills/*/SKILL.md\`; \`.agent/skills\` remains the legacy Film-Kit runtime mirror for Claude/Cursor/Copilot/Antigravity.
+- Codex-native still phase lives in \`.agents/skills/film-kit-codex-images/SKILL.md\` and starts with \`/codex-images\` only after user confirmation.
 - Codex custom agents live in \`.codex/agents/*.toml\` and point back to the canonical \`.agent/agents/*.md\` role files.
 - Full-auto Codex profile: \`approval_policy = "never"\`, \`sandbox_mode = "danger-full-access"\`, \`[agents] max_threads = 6\`, \`max_depth = 1\`.
 - Worktree bootstrap: if \`node_modules\` or build output is missing, run \`npm install\` and \`npm run build\` before package commands.
@@ -602,6 +699,7 @@ Before ANY work, read ALL skills from \`.agent/skills/\`:
 7. Wait for all batch reports before specialist validation
 8. Run continuity, safety, stability, dialogue, character-consistency, color-continuity, semantic, pacing, and delivery specialists
 9. Finalize only after every required report passes
+10. In Codex, after all required reports pass, offer \`/codex-images\` as an optional still-image phase and wait for explicit user confirmation
 
 ## Critical Rules
 - AUTO-ANONYMOUS: Replace ALL real names with physical descriptions
@@ -624,6 +722,7 @@ Before ANY work, read ALL skills from \`.agent/skills/\`:
 
 ## Workflows
 - \`/generate\` -> \`.agent/workflows/generate-multi.md\`
+- \`/codex-images\` -> \`.agent/workflows/codex-images-multi.md\`
 - \`/chain\` -> \`.agent/workflows/chain-multi.md\`
 - \`/safety-check\` -> \`.agent/workflows/safety-check-multi.md\`
 - \`/recover\` -> \`.agent/workflows/recover-multi.md\`
@@ -662,6 +761,7 @@ This workspace keeps high-level policy in \`CLAUDE.md\` and execution detail in
 - Lead Director owns \`${config.outputDir}/project-info.md\`, \`${config.outputDir}/_index.md\`, \`${config.outputDir}/team-plan.json\`, \`${config.outputDir}/FINAL-SUMMARY.md\`
 - Shot Generators own only assigned \`${config.outputDir}/shots/SHOTNN.md\`
 - Specialists own only files inside \`${config.outputDir}/reports/\`
+- Codex still phase writes only to \`${config.outputDir}/codex-images/\` and \`${config.outputDir}/reports/CODEX-IMAGE-REPORT.md\`
 - Keep top-level \`voiceCast\` in \`${config.outputDir}/team-plan.json\`
 - Keep top-level \`visual_world\` in \`${config.outputDir}/team-plan.json\`
 - Keep \`Audio Plan\` blocks aligned to \`voiceCast\`
@@ -672,6 +772,7 @@ This workspace keeps high-level policy in \`CLAUDE.md\` and execution detail in
 
 ## Debugging
 - Use \`/memory\` to confirm this file and \`.claude/rules/*\` are loaded
+- In Codex, never auto-start \`/codex-images\`; offer it only after successful \`/generate\` completion and passing reports
 - If delegation gets confused, restate task-specific context explicitly in the spawn prompt
 `;
 }
@@ -708,7 +809,7 @@ Own only:
 - \`${config.outputDir}/team-plan.json\`
 - \`${config.outputDir}/FINAL-SUMMARY.md\`
 
-Never write shot prompts directly. Do not finalize until every required report exists and passes. Keep top-level \`voiceCast\` and \`visual_world\` in \`${config.outputDir}/team-plan.json\`, lock director-grade shot count before teammate sizing, then enforce spatial, semantic, and voice contracts in teammate assignments.`);
+Never write shot prompts directly. Do not finalize until every required report exists and passes. In Codex, once all required reports pass, offer \`/codex-images\` as an optional still-image phase and wait for explicit user confirmation. Keep top-level \`voiceCast\` and \`visual_world\` in \`${config.outputDir}/team-plan.json\`, lock director-grade shot count before teammate sizing, then enforce spatial, semantic, and voice contracts in teammate assignments.`);
 }
 function buildClaudeShotGeneratorSubagent(config) {
     return buildClaudeSubagent("shot-generator", "Generate assigned Film-Kit multi batches with strict chaining, coverage, anonymity, and report output.", `Read \`.agent/model-profile.md\`, \`.agent/MASTER.md\`, \`.agent/VOICE-DESIGN.md\`, \`.agent/agents/shot-generator.md\`, and \`.agent/workflows/generate-teammate.md\`.

package/packages/multi/content/agents/lead-director.md

@@ -301,6 +301,7 @@ Do not close project until all are true:
 - `$OUTPUT_DIR/reports/DELIVERY-REPORT.md` exists and is pass
 - `$OUTPUT_DIR/_index.md` is complete and lists all report statuses
 - `$OUTPUT_DIR/FINAL-SUMMARY.md` is written
+- If running inside Codex, `/codex-images` is offered only after all required reports pass and only if the user explicitly opts in
 
 ## Recovery Policy
 

package/packages/multi/content/workflows/generate-multi.md

@@ -132,3 +132,4 @@ If any report is missing or fail: run `.agent/workflows/recover-multi.md`.
 1. Update `$OUTPUT_DIR/_index.md` (all final statuses + report table)
 2. Write `$OUTPUT_DIR/FINAL-SUMMARY.md`
 3. Include team size, batch map, recovery actions, and final gate results
+4. If running inside Codex, offer `/codex-images` as an optional still-image phase only after every required report passes. Never auto-start it.

package/packages/studio/README.md

@@ -21,6 +21,7 @@ npx @milenyumai/film-kit init --preset studio --model seedance-2.0 --refs-dir ./
 - Everything film-kit-multi does (lead-directed multi-agent production with 8 specialists)
 - PLUS actual image and video rendering via fal.ai MCP integration
 - OpenAI Codex App repo-scoped config, custom agents, skill mirror, and fal.ai MCP setup
+- optional Codex still phase via `.agents/skills/film-kit-codex-images/SKILL.md` and `/codex-images`
 - Generates real still frames using Nano Banana 2
 - Generates real videos using Kling 3.0 Pro
 - Supports reference images for character/location consistency
@@ -62,6 +63,7 @@ The render supervisor automatically maps characters and locations from shot prom
 ## Workflows
 
 - `/generate` → multi-agent shot prompt generation (inherited from film-kit-multi)
+- `/codex-images` → optional Codex-native still phase for accepted ILK/SON frame iteration
 - `/render` → fal.ai rendering pipeline (NEW)
 - `/chain`, `/safety-check`, `/recover`, `/finish` → inherited from film-kit-multi
 

package/packages/studio/build/lib/configure.js

@@ -319,7 +319,9 @@ export async function configureStudioAgents(options = {}) {
             || relativePath === ".agent/skills/shotforge-generate-multi/SKILL.md";
         const isCodexConfig = relativePath.startsWith(".codex/")
             || relativePath === ".agents/skills/shotforge-generate/SKILL.md"
-            || relativePath === ".agents/skills/shotforge-generate-multi/SKILL.md";
+            || relativePath === ".agents/skills/shotforge-generate-multi/SKILL.md"
+            || relativePath === ".agents/skills/film-kit-codex-images/SKILL.md"
+            || relativePath === ".agent/workflows/codex-images-studio.md";
         const isRuntimeModelFile = relativePath === ".agent/model-profile.md";
         if (fileExists && !isClaudeConfig && !isAntigravityConfig && !isCodexConfig && !isRuntimeModelFile && !resolved.overwrite) {
             skipped.push(relativePath);

package/packages/studio/build/lib/templates.js

@@ -141,13 +141,115 @@ const STUDIO_CODEX_AGENTS = [
     ["render-supervisor", "render_supervisor", "Orchestrate fal.ai rendering, frame chaining, render reports, and semantic render QA."]
 ];
 function buildStudioCodexAgent(roleFile, name, description, config) {
+    const leadDirectorNote = roleFile === "lead-director"
+        ? "\nWhen /generate finishes successfully inside Codex and every mandatory specialist report passes, offer /codex-images as an optional still-image phase. Never auto-start it. Keep /render as the separate fal.ai render pipeline."
+        : "";
     return buildCodexAgentToml(name, description, `Read AGENTS.md first, then .agent/model-profile.md, .agent/MASTER.md, .agent/VOICE-DESIGN.md, .agent/agents/${roleFile}.md, and the relevant .agent/workflows/*.md file before acting.
 Use .agents/skills for Codex App skill discovery; .agent remains the Film-Kit legacy runtime source.
 Respect file ownership from AGENTS.md: shot teammates write only assigned SHOTNN.md files, specialists write only their report files, the Lead owns plan/index/final summary files, and the Render Supervisor owns renders plus render reports.
 Use the fal-ai MCP server from .codex/config.toml for render work when FAL_KEY is available; if FAL_KEY is missing, report the blocker instead of failing init.
+${leadDirectorNote}
 Keep outputs under ${config.outputDir} unless the user explicitly changes the output contract.
 For worktree runs, if node_modules or build outputs are missing and package.json exists, bootstrap with npm install and npm run build before package commands.`);
 }
+function buildCodexImageSkill(workflowFile, outputDir, refsDir) {
+    return `---
+name: film-kit-codex-images
+description: Optional Codex-native still image phase for Film-Kit Studio. Use after successful prompt generation when the user wants to create or iteratively edit accepted ILK FRAME and SON FRAME images inside Codex. Never auto-start; offer it only after all mandatory reports pass and keep /render separate.
+---
+
+# Film-Kit Codex Images
+
+This skill is for **Codex only**. It adds a still-image phase after Film-Kit prompt generation and specialist validation.
+
+## Read First
+1. \`${workflowFile}\`
+2. \`.agent/model-profile.md\`
+3. \`${outputDir}/team-plan.json\`
+4. the relevant shot files under \`${outputDir}/shots/\`
+5. all required report files under \`${outputDir}/reports/\`
+
+## Trigger Rules
+- Start only when the user explicitly asks for image generation/editing or accepts the \`/codex-images\` suggestion after \`/generate\`.
+- Do not auto-start this phase.
+- Only offer it after all mandatory specialist reports pass.
+- Keep \`/render\` as the separate fal.ai render/video workflow.
+- Do not use this phase for coverage stills or video generation in v1.
+
+## Reference Priority
+1. images already present in the active Codex conversation
+2. user-supplied local image paths
+3. repo-local \`refs/\` folders when present
+4. studio \`${refsDir}/\`
+
+## Core Behavior
+- Use Codex's built-in image generation/editing flow.
+- If a local image file must be edited, first bring it into the conversation context, then edit it.
+- Generate \`ILK FRAME\` from the accepted shot prompt plus references.
+- Generate \`SON FRAME\` by iterating from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
+- For chained shots, default the next shot's \`ILK FRAME\` to the previously accepted \`SON FRAME\` unless the user explicitly requests a fresh start.
+- After every image, ask the user to accept it or request a targeted edit.
+
+## Output Contract
+- Save accepted stills under \`${outputDir}/codex-images/SHOTNN/\`
+- Canonical files: \`ilk-frame.png\`, \`son-frame.png\`
+- Iterations use sibling versioned filenames such as \`ilk-frame-v2.png\` and \`son-frame-v3.png\`
+- Keep \`${outputDir}/codex-images/manifest.json\` updated
+- Keep \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` updated
+`;
+}
+function buildCodexImagesWorkflow(outputDir, refsDir) {
+    return `---
+description: Optional Codex-native still image phase for Film-Kit Studio output
+---
+
+# /codex-images - Film-Kit Studio Codex Still Phase
+
+## Preconditions
+- \`/generate\` completed successfully
+- shot files already exist under \`${outputDir}/shots/\`
+- \`${outputDir}/team-plan.json\` exists
+- every mandatory specialist report under \`${outputDir}/reports/\` passed
+- this phase is opt-in; start only after the user confirms
+- \`/render\` remains separate and is not replaced by this workflow
+
+## Reference Priority
+1. images already present in the active Codex conversation
+2. user-supplied local image paths
+3. repo-local \`refs/\` folders when present
+4. studio \`${refsDir}/\`
+
+## Output Contract
+\`\`\`text
+${outputDir}/codex-images/
+├── SHOTNN/
+│   ├── ilk-frame.png
+│   ├── ilk-frame-v2.png
+│   ├── son-frame.png
+│   └── son-frame-v3.png
+├── manifest.json
+└── ../reports/CODEX-IMAGE-REPORT.md
+\`\`\`
+
+## Flow
+1. Process shots sequentially unless the user explicitly requests a different order.
+2. For a fresh shot, generate \`ILK FRAME\` from the accepted still prompt plus references.
+3. Show the result and ask the user to accept it or request a targeted edit.
+4. Save the accepted start image as \`ilk-frame.png\`; keep previous attempts as versioned siblings.
+5. Generate \`SON FRAME\` by editing from the accepted \`ILK FRAME\` while preserving \`REFERENCE LOCK\`, \`Keep same\`, and \`Change only\`.
+6. Show the result and ask the user to accept it or request a targeted edit.
+7. Save the accepted end image as \`son-frame.png\`; keep previous attempts as versioned siblings.
+8. If the next shot is chained, default its \`ILK FRAME\` to the accepted previous \`SON FRAME\` unless the user explicitly asks for a fresh start.
+9. Update \`${outputDir}/codex-images/manifest.json\` and \`${outputDir}/reports/CODEX-IMAGE-REPORT.md\` after each accepted image.
+
+## Hard Rules
+- Never auto-start this workflow.
+- V1 covers only main-shot \`ILK FRAME\` and \`SON FRAME\`.
+- Do not generate coverage stills or video here.
+- Preserve chain continuity unless the user explicitly requests a reset.
+- Keep \`/render\` available as the separate fal.ai render/video pipeline.
+`;
+}
 /**
  * Build project files for studio mode.
  * Superset of multi-agent mode: all multi files + fal.ai render pipeline.
@@ -191,6 +293,8 @@ export function buildStudioProjectFiles(config) {
     for (const [roleFile, name, description] of STUDIO_CODEX_AGENTS) {
         files[`.codex/agents/${roleFile}.toml`] = buildStudioCodexAgent(roleFile, name, description, config);
     }
+    files[".agents/skills/film-kit-codex-images/SKILL.md"] = buildCodexImageSkill(".agent/workflows/codex-images-studio.md", config.outputDir, config.refsDir);
+    files[".agent/workflows/codex-images-studio.md"] = buildCodexImagesWorkflow(config.outputDir, config.refsDir);
     // ── AGENTS.md ───────────────────────────────────────────────────────
     if (config.includeAgentsMd) {
         files["AGENTS.md"] = buildAgentsMd(config);
@@ -251,9 +355,11 @@ Before ANY work, read ALL skills from \`.agent/skills/\`:
 6. Wait for all batch reports before specialist validation
 7. Run continuity, safety, stability, dialogue, character-consistency, color-continuity, semantic, pacing, and delivery specialists
 8. Finalize only after every required report passes
+9. In Codex, after all mandatory specialist reports pass, offer \`/codex-images\` as an optional still-image phase and wait for explicit user confirmation
 
 ## Render Pipeline
 - \`/render\` workflow runs after \`/generate\` completes and all specialist reports pass
+- \`/codex-images\` is a separate manual Codex-native still phase and does not replace \`/render\`
 - Shots render SEQUENTIALLY — frame chaining requires previous shot's output
 - Frame chain: SHOT[N] SON FRAME → reused as SHOT[N+1] ILK FRAME (no re-generation)
 - SON FRAME uses its own ILK FRAME as reference for intra-shot consistency
@@ -286,6 +392,7 @@ Before ANY work, read ALL skills from \`.agent/skills/\`:
 
 ## Workflows
 - \`/generate\` -> \`.agent/workflows/generate-multi.md\`
+- \`/codex-images\` -> \`.agent/workflows/codex-images-studio.md\`
 - \`/chain\` -> \`.agent/workflows/chain-multi.md\`
 - \`/safety-check\` -> \`.agent/workflows/safety-check-multi.md\`
 - \`/recover\` -> \`.agent/workflows/recover-multi.md\`
@@ -332,6 +439,7 @@ This workspace keeps high-level policy in \`CLAUDE.md\` and execution detail in
 - Shot Generators own only assigned \`${config.outputDir}/shots/SHOTNN.md\`
 - Specialists own only files inside \`${config.outputDir}/reports/\`
 - Render Supervisor owns \`${config.outputDir}/renders/\`, \`${config.outputDir}/reports/RENDER-REPORT.md\`, and \`${config.outputDir}/reports/SEMANTIC-RENDER-REPORT.md\`
+- Codex still phase writes only to \`${config.outputDir}/codex-images/\` and \`${config.outputDir}/reports/CODEX-IMAGE-REPORT.md\`
 - Image prompt contract, specificity floor, and semantic floor are hard gates, not suggestions
 - Semantic consistency floor is a hard gate, including exact chained ILK reuse and \`visual_world\` alignment
 - Do not let teammates create extra SHOT files beyond the locked batch ranges
@@ -339,6 +447,7 @@ This workspace keeps high-level policy in \`CLAUDE.md\` and execution detail in
 
 ## Render Pipeline Rules
 - \`/render\` runs only after \`/generate\` completes and all specialist reports pass
+- \`/codex-images\` is manual, still-only, and separate from the fal.ai pipeline
 - Shots render SEQUENTIALLY — frame chaining requires previous shot's output
 - SHOT[N] SON FRAME → reused as SHOT[N+1] ILK FRAME (chained, no re-generation)
 - SON FRAME uses its own ILK FRAME as image reference for intra-shot consistency
@@ -349,6 +458,7 @@ This workspace keeps high-level policy in \`CLAUDE.md\` and execution detail in
 
 ## Debugging
 - Use \`/memory\` to confirm this file and \`.claude/rules/*\` are loaded
+- In Codex, never auto-start \`/codex-images\`; offer it only after successful \`/generate\` completion and passing reports
 - If delegation gets confused, restate task-specific context explicitly in the spawn prompt
 - Verify fal-ai MCP is connected via \`.claude/settings.json\`
 `;
@@ -389,7 +499,7 @@ Own only:
 - \`${config.outputDir}/team-plan.json\`
 - \`${config.outputDir}/FINAL-SUMMARY.md\`
 
-Never write shot prompts directly. Do not finalize until every required report exists and passes. Lock director-grade shot count before teammate sizing, then enforce spatial contracts in teammate assignments.`);
+Never write shot prompts directly. Do not finalize until every required report exists and passes. In Codex, once all mandatory specialist reports pass, offer \`/codex-images\` as an optional still-image phase and wait for explicit user confirmation. Keep \`/render\` as the separate fal.ai pipeline. Lock director-grade shot count before teammate sizing, then enforce spatial contracts in teammate assignments.`);
 }
 function buildClaudeShotGeneratorSubagent(config) {
     return buildClaudeSubagent("shot-generator", "Generate assigned Film-Kit multi batches with strict chaining, coverage, anonymity, and report output.", `Read \`.agent/model-profile.md\`, \`.agent/MASTER.md\`, \`.agent/agents/shot-generator.md\`, and \`.agent/workflows/generate-teammate.md\`.
@@ -1014,6 +1124,7 @@ Multi-agent parallel generation with shot teammates, specialist validators, and
 - Active model rules: \`.agent/model-profile.md\`
 - Team plan is stored in \`${config.outputDir}/team-plan.json\`
 - \`${config.outputDir}/team-plan.json\` carries top-level \`visual_world\`
+- Optional Codex still phase: \`${config.outputDir}/codex-images/manifest.json\` + \`${config.outputDir}/reports/CODEX-IMAGE-REPORT.md\`
 - Batch reports are stored in \`${config.outputDir}/reports/\`
 - Specialist reports are mandatory before completion:
   - \`${config.outputDir}/reports/CONTINUITY-REPORT.md\`
@@ -1031,6 +1142,7 @@ Multi-agent parallel generation with shot teammates, specialist validators, and
 
 ## Workflows
 - \`/generate\` -> \`.agent/workflows/generate-multi.md\`
+- \`/codex-images\` -> \`.agent/workflows/codex-images-studio.md\`
 - \`/chain\` -> \`.agent/workflows/chain-multi.md\`
 - \`/safety-check\` -> \`.agent/workflows/safety-check-multi.md\`
 - \`/recover\` -> \`.agent/workflows/recover-multi.md\`
@@ -1041,9 +1153,11 @@ Multi-agent parallel generation with shot teammates, specialist validators, and
 - Open the Git root as the Codex project root; Codex discovers \`AGENTS.md\`, \`.codex/config.toml\`, and \`.agents/skills/\` from that root.
 - Repo-scoped Codex config lives in \`.codex/config.toml\`; Codex may ignore it until the project is trusted in the app.
 - Codex skills live under \`.agents/skills/*/SKILL.md\`; \`.agent/skills\` remains the legacy Film-Kit runtime mirror for Claude/Cursor/Copilot/Antigravity.
+- Codex-native still phase lives in \`.agents/skills/film-kit-codex-images/SKILL.md\` and starts with \`/codex-images\` only after user confirmation.
 - Codex custom agents live in \`.codex/agents/*.toml\` and point back to the canonical \`.agent/agents/*.md\` role files.
 - Full-auto Codex profile: \`approval_policy = "never"\`, \`sandbox_mode = "danger-full-access"\`, \`[agents] max_threads = 6\`, \`max_depth = 1\`.
 - fal.ai MCP config is project-scoped in \`.codex/config.toml\` with \`required = false\`; if \`FAL_KEY\` is missing, report the render blocker instead of failing init.
+- \`/render\` remains the fal.ai pipeline; \`/codex-images\` is the manual Codex-native still collaboration surface.
 - Worktree bootstrap: if \`node_modules\` or build output is missing, run \`npm install\` and \`npm run build\` before package commands.
 
 ## Skills (shared by all agents)
@@ -1067,6 +1181,7 @@ Multi-agent parallel generation with shot teammates, specialist validators, and
 - Video model: \`${config.falVideoModel}\`
 - Reference images: \`${config.refsDir}/\`
 - Render output: \`${config.outputDir}/renders/SHOTNN/\`
+- Codex still workflow: \`.agent/workflows/codex-images-studio.md\`
 - Frame chaining: SHOT[N] SON FRAME → reused as SHOT[N+1] ILK FRAME
 - SON FRAME references its own ILK FRAME for intra-shot consistency
 - Scene boundaries break the chain; ILK FRAME generated fresh

package/packages/studio/content/agents/render-supervisor.md

@@ -153,6 +153,7 @@ Write `$OUTPUT_DIR/reports/RENDER-REPORT.md` with this strict structure:
 ## Rules
 
 - Do not start rendering until all specialist reports pass
+- `/codex-images` is a separate manual Codex still workflow; do not write into `$OUTPUT_DIR/codex-images/` and do not replace `/render`
 - Always check cost before rendering; alert user if cost exceeds $10
 - Render shots SEQUENTIALLY — chaining requires previous shot's output
 - Use `submit_job` for video generation (never `run_model` — too slow)