@milenyumai/film-kit 2.0.0 → 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,18 +240,81 @@ 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`
 - semantic consistency uses canonical `visual_world`
 
+## Reference Locking And Start/End Consistency
+
+When a reference image exists, Film-Kit now treats it as an immutable source, not a loose style hint.
+
+Default behavior across `single`, `multi`, `hybrid`, `hybrid-smart`, and `studio`:
+
+- face, hair, skin tone, body proportions, wardrobe, accessories, props, materials, patterns, and logos are treated as locked invariants
+- generated prompts should not re-describe identity details already visible in the reference
+- generated prompts should explicitly preserve the same person or object exactly as the reference
+- silent redesign, restyling, redressing, age shifting, or prop redesign is considered a failure
+
+Allowed movement inside a reference-locked shot is intentionally narrow:
+
+- pose can change only if it is explicitly declared
+- expression can change only if it is explicitly declared
+- camera or environment state can change only if it is explicitly declared
+- each start/end pair should carry only one major semantic delta unless the workflow marks a deliberate chain break or transition
+
+## Prompt Contract
+
+Start/end still prompts are now optimized for structure, not raw length.
+
+Image prompt contract:
+
+- `REFERENCE LOCK`
+- `Keep same`
+- `Change only`
+- short semantic anchor
+- targeted avoid line
+
+This means:
+
+- reference-anchored image prompts are intentionally shorter and more surgical
+- old image-quality heuristics based on minimum word counts are no longer the primary control surface
+- detailed prose is still expected for video prompts, where motion, timing, audio, and camera language need richer direction
+
+`hybrid` and `hybrid-smart` keep their compact still-prompt behavior. `single`, `multi`, and `studio` keep richer video prompt behavior for Veo, Kling, and Seedance.
+
+## Semantic QA And Render QA
+
+`visual_world` is the canonical continuity contract for semantic consistency and render review.
+
+Reference-aware runtime and reports now carry these concepts:
+
+- `identity_lock: "exact-reference"`
+- `shared_frame_invariants`
+- `allowed_change`
+- `reference_drift_forbidden: true`
+
+Generated specialist and render QA flows now explicitly fail on:
+
+- face, hair, skin, body, wardrobe, accessory, or prop drift
+- lens, angle, subject scale, light direction, or color-temperature drift
+- unexplained semantic changes between start and end frames
+- violations of declared `Keep same` invariants
+- changes outside the declared `Change only` budget
+
+Studio render QA also records render-level verdicts such as:
+
+- `reference_drift_status`
+- `start_end_contract_status`
+
 ## Seedance Runtime Coverage
 
 The package now carries Seedance-aware instructions in the generated runtime, not only in type definitions or CLI parsing.

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}\`
@@ -218,11 +309,11 @@ When the user asks \`/generate\`, convert the scenario into:
 ## Output Contract
 Each \`SHOTNN.md\` is a **single file** containing ALL shot details:
 - 🔗 Chain status (FIRST / CHAINED / CHAIN BREAK)
-- İLK FRAME (start frame image prompt — min 60 words)
-- SON FRAME (end frame image prompt — min 60 words)
+- İLK FRAME (start frame image prompt — compact reference-first still contract)
+- SON FRAME (end frame image prompt — same-visual-universe + one-delta still contract)
 - AUDIO PLAN (machine-readable shot audio contract)
-- VİDEO (video prompt with audio direction — min 80 words)
-- COVERAGE SHOTS (2-3 coverage shots within same file — each min 60 words)
+- VİDEO (video prompt with audio direction — min 120 words)
+- COVERAGE SHOTS (2-3 coverage shots within same file — compact stills + detailed coverage video when needed)
 - 🇹🇷 Turkish summary for each section
 - Avoid line on EVERY prompt
 
@@ -268,7 +359,7 @@ Read .agent/VOICE-DESIGN.md when dialogue, narrator VO, or reusable speaker iden
 5. SLOW BURN: 8s default duration. Split actions into multiple shots. "Ilmek ilmek islemek."
 6. Music: NONE by default. User must explicitly request.
 7. EVERY prompt must have an Avoid line. No exceptions.
-8. Coverage shots mandatory (2-3 per main shot, min 60 words each, included in same file).
+8. Coverage shots mandatory (2-3 per main shot, included in same file; stills stay compact, coverage videos stay detailed).
 9. Frame chaining: Last frame of SHOT[N] = First frame of SHOT[N+1].
 10. Semantic consistency: \`${config.outputDir}/shot-plan.json\` must include \`visual_world\`; prompts must align camera, named movement strategy, light/shadow vector, scale, reflections, physics, anatomy risk, and contextual logic.
 11. ILK/İLK FRAME section must contain a code block even for chained shots.
@@ -334,7 +425,7 @@ All skills at: \`.agent/skills/[name]/SKILL.md\`
 - AUTO-SAFETY: Proactively reframe sensitive content
 - Frame chaining: Last frame SHOT[N] = First frame SHOT[N+1]
 - Chained ILK/İLK FRAME code block contains only \`Use SHOT[prev]_END as exact first frame\`; any new visual prompt requires CHAIN BREAK
-- Coverage: 2-3 sub-shots per main shot (min 60 words each, in same file)
+- Coverage: 2-3 sub-shots per main shot (same file; compact stills, detailed coverage videos)
 - Avoid line: MANDATORY on every prompt
 - Music: NONE by default
 - Duration: 8s default, slow burn pacing
@@ -406,7 +497,7 @@ Before generating ANY prompts, read skills from \`.agent/skills/\`:
 9. **Voice Design:** keep project-level \`voiceCast\` in \`${config.outputDir}/shot-plan.json\` and per-shot \`Audio Plan\` in each VIDEO section.
 10. **ILK/İLK FRAME:** Always include a fenced code block, even when chained.
 11. **Chained ILK/İLK FRAME:** code block contains only \`Use SHOT[prev]_END as exact first frame\`; any new visual prompt requires CHAIN BREAK.
-12. **Quality Floor:** ILK >= 80, SON >= 80, VIDEO >= 120, coverage >= 70 words.
+12. **Image Prompt Contract:** reference-anchored ILK/SON use \`REFERENCE LOCK\` + \`Keep same\` + \`Change only\`; VIDEO >= 120; coverage video >= 70.
 13. **Specificity Floor:** lens/framing, lighting, and foreground/midground/background action are mandatory.
 14. **Spatial Realism Floor:** eyeline target, plane map, shared light source, and contact/depth cues are mandatory when relational staging matters.
 15. **Semantic Consistency Floor:** \`visual_world\`, perspective/geometry, shadow vector, scale map, reflections, gravity/contact physics, anatomy risk, foreground/background coherence, contextual contradictions, and targeted semantic avoid terms are mandatory.
@@ -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.
@@ -450,7 +542,7 @@ This workspace keeps high-level policy in \`CLAUDE.md\` and operational detail i
 - Maintain \`${config.outputDir}/shot-plan.json\` top-level \`visual_world\`
 - Keep \`Audio Plan\` blocks aligned to \`voiceCast\`
 - Keep \`ILK/İLK FRAME\` in a fenced code block even when chained
-- Quality floor and specificity floor are hard gates, not suggestions
+- Image prompt contract, specificity floor, and semantic floor are hard gates, not suggestions
 - Semantic consistency floor is a hard gate: camera/lens/camera-movement/light/shadow/scale/reflection/physics/anatomy/context must align to \`visual_world\`
 - Apply \`.agent/skills/spatial-blocking/SKILL.md\` whenever eyeline, compositing, or depth realism is critical
 
@@ -482,7 +574,7 @@ Use the Film-Kit core runtime.
 - maintain top-level \`visual_world\` inside \`${config.outputDir}/shot-plan.json\`
 - keep \`Audio Plan\` blocks valid against \`voiceCast\`
 - enforce AUTO-ANONYMOUS, AUTO-SAFETY, chaining, and coverage contracts
-- enforce quality floor: ILK >= 80, SON >= 80, VIDEO >= 120, coverage >= 70
+- enforce image prompt contract: compact reference-first ILK/SON, VIDEO >= 120, coverage video >= 70
 - enforce specificity floor: lens/framing, lighting, and foreground/midground/background action
 - enforce spatial realism: explicit eyeline target, plane map, shared light source, and contact/depth cues when needed
 - enforce semantic consistency: \`visual_world\`, perspective/geometry, shadow vector, scale map, reflection handling, physics/anatomy risk, foreground/background coherence, contextual contradictions, and scene-specific avoid terms
@@ -526,7 +618,7 @@ If using the native Claude subagent, read \`.claude/agents/prompt-engineer.md\`
    - Add machine-readable \`Audio Plan\` before every VIDEO section
    - Keep İLK FRAME as fenced code block even when chained
    - If chained, keep İLK FRAME code block to exact reuse text only; new visual prompt means CHAIN BREAK
-   - Enforce hard quality floor: ILK >= 80, SON >= 80, VIDEO >= 120, coverage >= 70
+   - Enforce image prompt contract: compact reference-first ILK/SON, VIDEO >= 120, coverage video >= 70
    - Enforce specificity floor: lens/framing + lighting + foreground/midground/background action
    - Enforce spatial realism floor: eyeline target + plane map + shared light source + contact/depth cues when applicable
    - Enforce semantic consistency floor: perspective/geometry + shadow vector + scale map + reflections + gravity/contact physics + anatomy risk + contextual contradiction check
@@ -607,7 +699,7 @@ FIRST SHOT / CHAINED from SHOT[prev]_END / CHAIN BREAK - Reason
 > Any new visual prompt in a chained ILK FRAME section requires CHAIN BREAK.
 
 \\\`\\\`\\\`
-[Image prompt — min 60 words, following prompt flow order]
+[Image prompt — compact still prompt. If refs exist: REFERENCE LOCK + Keep same + Change only + semantic anchor + Avoid]
 Avoid: blurry, low-res, noise, distorted faces, bad anatomy, extra limbs/fingers,
 plastic skin, waxy skin, on-screen text, watermark, logo, cartoon style, CGI look.
 \\\`\\\`\\\`
@@ -615,7 +707,7 @@ plastic skin, waxy skin, on-screen text, watermark, logo, cartoon style, CGI loo
 ### SON FRAME (SHOTNN_END)
 
 \\\`\\\`\\\`
-[Image prompt — min 60 words, following prompt flow order]
+[Image prompt — compact still prompt. Preserve same visual universe and declare one allowed change]
 Avoid: blurry, low-res, noise, distorted faces, bad anatomy, extra limbs/fingers,
 plastic skin, waxy skin, on-screen text, watermark, logo, cartoon style, CGI look.
 \\\`\\\`\\\`
@@ -629,7 +721,7 @@ plastic skin, waxy skin, on-screen text, watermark, logo, cartoon style, CGI loo
 ### VİDEO
 
 \\\`\\\`\\\`
-[Video prompt — min 80 words, following prompt flow order]
+[Video prompt — min 120 words, following prompt flow order]
 
 Audio direction:
 - Language: [TURKISH/ENGLISH/etc.]
@@ -654,11 +746,11 @@ inconsistent lighting, unnatural motion, on-screen text, watermark.
 🇹🇷 [Türkçe coverage özeti]
 
 \\\`\\\`\\\`
-[Coverage IMAGE prompt — min 60 words, standalone (not chained)]
+[Coverage IMAGE prompt — compact standalone still contract (not chained)]
 Avoid: blurry, low-res, noise, distorted faces, bad anatomy, on-screen text, watermark.
 \\\`\\\`\\\`
 \\\`\\\`\\\`
-[Coverage VIDEO prompt — min 60 words, with full audio direction block]
+[Coverage VIDEO prompt — min 70 words, with full audio direction block]
 
 Audio direction:
 - Language: [LANGUAGE]
@@ -812,7 +904,7 @@ Before generating ANY prompts, read skills from \`.agent/skills/\`:
 - **AUTO-SAFETY:** Proactively reframe sensitive content
 - **Frame Chaining:** Last frame of SHOT[N] = First frame of SHOT[N+1]
 - **Chain Hardening:** chained ILK/İLK FRAME code block contains only \`Use SHOT[prev]_END as exact first frame\`
-- **Coverage:** 2-3 sub-shots per main shot (in same file, min 60 words each)
+- **Coverage:** 2-3 sub-shots per main shot (in same file; stills compact, coverage videos detailed)
 - **Spatial Realism:** eyeline targets, shared light, depth scale, and anti-cutout staging must agree when subjects share frame
 - **Semantic Consistency:** \`visual_world\` controls perspective/geometry, shadow vector, scale map, reflections, physics, anatomy risk, background coherence, and contextual contradictions
 - **Avoid Line:** MANDATORY on every prompt
@@ -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)
@@ -909,7 +1002,7 @@ Before generating ANY prompts, read these skills:
 2. **Name Policy:** Dialogue naming follows \`${config.outputDir}/shot-plan.json\` policy
 3. **AUTO-SAFETY:** Proactively reframe sensitive content
 4. **Frame Chaining:** Last frame of SHOT[N] becomes first frame of SHOT[N+1]
-5. **Coverage Mandatory:** 2-3 sub-shots per main shot (in same file, min 60 words each)
+5. **Coverage Mandatory:** 2-3 sub-shots per main shot (in same file; stills compact, coverage videos detailed)
 6. **Avoid Line:** MANDATORY on every prompt (image + video + coverage)
 7. **Voice Design:** keep \`voiceCast\` in \`${config.outputDir}/shot-plan.json\` and \`Audio Plan\` in every speaking VIDEO section
 8. **Music: NONE** by default
@@ -923,10 +1016,11 @@ Before generating ANY prompts, read these skills:
 
 ## Quality Floor (Hard Gate)
 Reject and regenerate any shot that fails:
-- ILK FRAME < 80 words
-- SON FRAME < 80 words
+- reference-anchored ILK FRAME missing \`REFERENCE LOCK\`, \`Keep same\`, or \`Change only\`
+- SON FRAME drifts from the same visual universe or changes more than one major beat
 - VIDEO < 120 words
-- any coverage prompt < 70 words
+- any coverage video prompt < 70 words
+- reference-visible face/hair/skin/body/wardrobe/accessories/prop design drift
 - missing explicit lens/framing/camera movement details
 - missing explicit lighting direction/intensity/atmosphere details
 - missing explicit foreground/midground/background action details
@@ -977,13 +1071,15 @@ ${isKling
 - Visual prompts in English; dialogue kept in source language.
 - Main chain continuity: SHOT[N]_END -> SHOT[N+1]_START.
 - Default duration: 8s slow burn.
-- Prompt rewriter active — longer prompts (80-120 words) give more control.
+- Prompt rewriter active — longer prompts (80-120 words) give more control for VIDEO prompts; reference-anchored image prompts should stay compact and delta-only.
 
 ### Veo Image-to-Video
 When generating video from a reference image:
 - The model extracts lighting and style directly from the image
 - Do NOT repeat visual info already in the image (e.g., "warm light", "35mm film")
+- Keep the same identity, wardrobe, accessories, prop design, lens feel, light direction, and subject scale
 - Focus only on the **change**: motion, action, and audio
+- Use the same seed for same-scene reference variants and start/end pairs; change seed only for structural repair or \`CHAIN BREAK\`
 
 ### Veo Re-Take Strategy
 | Error Type | Fix | Seed |
@@ -992,7 +1088,7 @@ When generating video from a reference image:
 | Extra limbs | Add "extra limbs, extra fingers" to Avoid | New seed |
 | Motion inconsistency | Simplify movement, fewer actions | Same seed |
 | Light jumps | Specify light source more precisely | Same seed |
-| Character inconsistent | Strengthen reference lock, repeat "EXACTLY" | Same seed |
+| Character inconsistent | Strengthen immutable reference lock, remove face/body/wardrobe redesign text | Same locked seed |
 | Background drift | Add background details | Same seed |
 | Robotic motion | Add "organic natural movement" + micro-behavior | New seed |
 
@@ -1038,6 +1134,9 @@ The more aligned these are, the cleaner the transition:
 - Light direction & white balance
 - Overall perspective
 
+**Keep same:** identity, face, hair, skin tone, body proportions, wardrobe, accessories, prop design, lens family, camera height, subject scale, light direction, color temperature, and location shell.
+**Change only:** one major semantic beat such as expression, hand position, body lean, prop position, or environmental state.
+
 > Large angle differences or mismatched lens feel forces the model to "guess" perspective → warp increases.
 
 **Human face/hands rules:**

package/content/agents/prompt-engineer.md

@@ -42,10 +42,11 @@ You are a senior Technical Prompt Engineer specialized in model-aware cinematic
 12. **HER prompt'ta Avoid satırı ZORUNLU (❗ coverage dahil)**
 13. **🇹🇷 Türkçe özet: Her shot ve coverage için 1 cümlelik Türkçe özet ekle**
 14. Emotional arc: Film genelinde gerilim eğrisi (1-5) uygula
-15. **Hard quality floor:** ILK >=80, SON >=80, VIDEO >=120, coverage >=70 kelime
+15. **Hard prompt floor:** reference-anchored ILK/SON use `REFERENCE LOCK` + `Keep same` + `Change only`; VIDEO >=120; coverage video >=70
 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 ve contextual contradiction her shot'ta geçmeli
+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
 
 ---
 
@@ -271,7 +272,7 @@ Before outputting ANY shot:
 - [ ] Quality floor passes? (ILK>=80, SON>=80, VIDEO>=120, coverage>=70)
 - [ ] Specificity floor passes? (lens + lighting + FG/MG/BG action)
 - [ ] Spatial realism passes? (eyeline target + plane map + shared light + contact/depth cues)
-- [ ] Semantic consistency passes? (`visual_world` fields + perspective/geometry + shadow vector + scale map + reflection/physics/anatomy/context checks)
+- [ ] Semantic consistency passes? (`visual_world` fields + perspective/geometry + shadow vector + scale map + reflection/physics/anatomy/context + reference drift + allowed-change checks)
 - [ ] Model Control block exists? (`Model`, `Preset`, `CFG`, `Transition Mode`)
 
 ### 3. Kling-Specific Gates (when model is kling-3.0)

package/content/skills/frame-chaining/SKILL.md

@@ -360,7 +360,16 @@ When preparing Start and End frames for Kling 3.0, both frames MUST share:
 | **Light direction & WB** | Same source, same color temperature |
 | **Overall perspective** | Same spatial depth and vanishing points |
 
-> Mismatched elements force Kling to "guess" → warp, melting, and artifacts increase.
+> Mismatched elements force Kling to "guess" → warp, melting, and artifacts increase.
+
+### Keep Same / Change Only Contract
+
+For a reference-locked start/end pair:
+
+- `Keep same:` identity, face, hair, skin tone, body proportions, wardrobe, accessories, prop design, lens family, camera height, subject scale, light direction, color temperature, and location shell
+- `Change only:` one major semantic beat such as expression, hand position, body lean, prop position, or environmental state
+- if two or more major semantic changes are needed, declare `CHAIN BREAK` or split into additional shots
+- do not redesign anything already visible in the reference image
 
 ### Face & Hands Stability for Start+End
 

package/content/skills/prompt-structure/SKILL.md

@@ -19,7 +19,7 @@ description: Image and video prompt templates, camera movement vocabulary, stabi
 | **Positive Framing** | Describe what SHOULD happen (negative prompts less effective) |
 | **Specific Action Verbs** | "strides" > "walks", "glides" > "moves" |
 | **Professional Terms** | Use industry-standard cinematography language |
-| **Ideal Length** | 80-120 words per video prompt |
+| **Ideal Length** | Video prompts: 80-120 words. Reference-anchored image prompts: compact 35-70 words; hybrid still pairs can go 20-50 when anchors are strong |
 | **Reference Commands First** | Always start with reference image instructions |
 | **Safety First** | Always consider filter implications |
 | **Short Sentence Rule** | Split long sentences across shots |
@@ -36,28 +36,26 @@ description: Image and video prompt templates, camera movement vocabulary, stabi
 
 | Sıra | İçerik | Örnek |
 |------|--------|-------|
-| **1** | Tek cümle sahne özeti | "Cinematic close-up of a young soldier in a dim bunker." |
-| **2** | Kim/Ne/Nerede | Karakter fiziksel tanımı, kıyafet, konum |
-| **3** | Aksiyon | Ne yapıyor, mikro-davranış, oyunculuk |
-| **4** | Kamera + Lens | "85mm f/2.0, shallow DOF, handheld" |
-| **5** | Işık + Atmosfer | "Warm oil lamp, dramatic side shadows" |
-| **6** | Audio direction | Sadece video prompt'larında |
-| **7** | Avoid line | HER prompt'ta zorunlu |
+| **1** | Reference lock / frame intent | "Same person exactly as reference. Do not modify." |
+| **2** | Keep same | Kimlik, wardrobe, prop design, lens feel, ışık yönü, subject scale |
+| **3** | Change only | Tek anlamlı değişim: ifade, el pozisyonu, aksiyon beat'i |
+| **4** | Kamera + Lens | "35mm lens feel, eye-level medium shot" |
+| **5** | Semantic anchor | Işık yönü, gölge vektörü, scale/depth, location shell |
+| **6** | Audio direction | Sadece video prompt'larında |
+| **7** | Avoid line | HER prompt'ta zorunlu |
 
 > **İlk cümle = "Bu shot ne?" sorusunun tek cümlelik cevabı olmalı.**
 
 ### Standard Template
 
 ```
-[REFERENCE LOCK section if applicable]
-
-Cinematic still frame of [subject with reference adherence] in [frozen pose].
-[Environment + time of day].
-Lighting: [specific setup].
-Camera: [framing], [lens mm], [aperture], photorealistic, crisp focus, no motion blur, no text.
-[Safety injection if needed]
-
-[Full avoid line]
+[REFERENCE LOCK] Same person/object exactly as reference. Do not modify, enhance, reinterpret, restyle, redress, or redesign anything visible in the reference.
+Keep same: identity, wardrobe/accessories, prop design, lens feel, camera height, subject scale, light direction, color temperature, location shell.
+Change only: [one intentional beat].
+[Frame intent + composition + brief action].
+Semantic consistency: [shadow direction], [scale map], [reflection/physics note].
+[Safety injection if needed]
+Avoid: [targeted failures including reference drift / outfit drift / prop drift / lens drift / light-direction drift]
 ```
 
 ### Semantic Consistency Layer
@@ -78,19 +76,27 @@ Use SHOT[prev]_END as exact first frame.
 ```
 
 Any new start-frame visual prompt must be declared as `CHAIN BREAK - [reason]`.
+
+### Reference-Anchored Image Prompt Contract
+
+When a reference exists:
+
+- do not restate face, hair, skin tone, body build, wardrobe, accessories, or prop design as freeform descriptive prose
+- use `Keep same:` for invariants and `Change only:` for one meaningful delta
+- do not re-explain style or lighting already visible in the reference image
+- use compact prompts; density matters more than length
+- if more than one major semantic change is needed, split the beat or declare `CHAIN BREAK`
 
 ### Example: Character in Environment
 
-```
-[REFERENCE LOCK] Using uploaded reference image: The soldier - Match this person's face EXACTLY. Do NOT invent new facial features.
-
-Cinematic still frame of the person from the reference, wearing dusty Ottoman artillery uniform, standing beside a massive artillery piece, one hand on the cannon barrel, determined expression. Ottoman coastal fortification, smoke-filled atmosphere, late afternoon harsh sunlight.
-Lighting: Dramatic side-light from setting sun, long shadows, dust particles visible in light beams.
-Camera: Medium shot, 35mm lens, f/4, photorealistic, crisp focus, no motion blur, no text.
-Maintaining exact likeness from the reference throughout. Historical reenactment style. Documentary approach.
-
-Avoid: blurry, low-res, noise, distorted faces, bad anatomy, extra limbs/fingers, plastic skin, waxy skin, airbrushed skin, on-screen text, watermark, logo, cartoon style, CGI look, different face than reference.
-```
+```
+[REFERENCE LOCK] Same soldier exactly as the uploaded reference. Do not modify face, hair, skin, body, uniform, fez, or cannon design.
+Keep same: identity, uniform, fez, cannon design, medium-shot 35mm lens feel, eye-level camera, late-afternoon side light, smoke-filled fortification layout.
+Change only: the soldier's expression shifts to determined while one hand rests on the cannon barrel.
+Cinematic still frame for a reaction-hold handoff.
+Semantic consistency: long shadows fall screen-right; scale map keeps soldier foreground, cannon midground, smoke depth behind.
+Avoid: distorted face, outfit drift, prop drift, lens drift, light-direction drift, bad anatomy, extra fingers, on-screen text, watermark.
+```
 
 ---