@milenyumai/film-kit 1.2.1 → 1.4.0

package/README.md

@@ -1,127 +1,156 @@
-# Film-Kit: Hollywood-Standard Cinematic Prompt Engineering
+# Film-Kit
 
-**Film-Kit**, model-seçilebilir sinematik prompt mühendisliği ajanlarını (Claude Code, Cursor, VS Code Copilot, Antigravity) projenize kuran bir araç setidir.
+Professional cinematic prompt-engineering kits for Claude Code, Cursor, GitHub Copilot, and Antigravity.
 
-İki versiyonu vardır:
-1. **Film-Kit (Core):** Tek ajanlı, manuel kontrollü üretim.
-2. **Film-Kit Multi (Pro):** Çok ajanlı, paralel üretim ve uzman denetimi.
+Film-Kit ships as a single repository with four npm packages:
 
-## 🧱 Repository Modeli (Tek Repo)
-Bu proje **tek GitHub repository (monorepo)** olarak yönetilir:
-- Core paket: repo kökü (`@milenyumai/film-kit`)
-- Multi paket: `packages/multi` (`@milenyumai/film-kit-multi`)
+| Package | Use case | Video route |
+|---|---|---|
+| `@milenyumai/film-kit` | Core single-agent workflow | `veo31` or `kling-3.0` |
+| `@milenyumai/film-kit-multi` | Multi-agent parallel production | `veo31` or `kling-3.0` |
+| `@milenyumai/film-kit-hybrid` | Nano Banana stills + Kling video | fixed `kling-3.0` |
+| `@milenyumai/film-kit-hybrid-smart` | Nano Banana stills + smart Veo/Kling routing | dialogue-aware route |
 
-Yani kaynak kod için tek "source of truth" vardır: `film-kit` reposu.
+## Release Highlights
 
----
+- Professional native Claude Code surfaces across all packages:
+  - valid `.claude/settings*.json`
+  - native `.claude/agents/*`
+  - cleanup of stale mode-specific Claude artifacts
+- Shared `spatial-blocking` skill for gaze, plane depth, light cohesion, compositing realism, and anti-miniature control.
+- Aligned quality gates across Claude Code, Cursor, Copilot, and Antigravity.
+- Stronger Kling 3.0 and Kling multi-shot guidance, including practical route rules and hard caps.
 
-## 🎯 Model Desteği
+## Editors
 
-| Model ID | Durum | Not |
-|----------|-------|-----|
-| `veo31` | ✅ Destekleniyor | Flow/Veo prompt akışı, Image-to-Video, Re-Take Strategy |
-| `kling-3.0` | ✅ Destekleniyor | Start+End, Multi-Shot (2-6), Element Binding, vCoT, Native Audio |
+All packages generate professional project surfaces for:
 
-Soft geçiş politikası:
-- `--model` verilmezse geçici olarak `veo31` atanır.
-- CLI bir deprecation warning basar: gelecek major sürümde model zorunlu olacak.
-- Alternatif: `FILM_KIT_MODEL=kling-3.0` environment variable ile default ayarlanabilir.
+- Claude Code
+- Cursor
+- GitHub Copilot
+- Antigravity
 
-Kling preset:
-- Varsayılan: `ultra-realism`
-- Varsayılan CFG hedefi: `0.45`
+## Package Guide
 
-### v1.2.0 — Yeni Özellikler
+### 1. `@milenyumai/film-kit`
 
-**Kling 3.0:**
-- Golden Prompt Skeleton (6-step Start+End)
-- 3 copy-paste template (Minimal Realism, Swap, Loop)
-- Multi-Shot Protocol (2-6 shots, `Shot X,` prefix)
-- Element Binding (karakter/nesne tutarlılığı)
-- Advanced Camera (vCoT triggers: Dolly Zoom, Dutch angle, Bird's-eye)
-- Native Audio (tonlama, lip sync, narrative SFX)
-- Troubleshooting guide + 10-point checklist
+Single-agent package for controlled shot-by-shot generation.
 
-**Veo 3.1:**
-- Image-to-Video entropy rule (stil tekrarı yok)
-- Re-Take Strategy table (7 hata tipi + seed yönetimi)
-
----
-
-## 📦 Paket 1: Film-Kit (Core)
-**Kullanım:** Bireysel projeler, öğrenme, <10 shot senaryolar.
-**Platformlar:** Claude Code + Cursor + Copilot + Antigravity
-
-### Kurulum (Tek Komut)
-Boş bir klasörde terminali açın:
 ```bash
 npx @milenyumai/film-kit init
 npx @milenyumai/film-kit init --model veo31
 npx @milenyumai/film-kit init --model kling-3.0 --kling-preset ultra-realism
 ```
 
-### Kullanım
-Claude Code içinde:
-```text
-/generate
-```
-Tek bir ajan ("Prompt Engineer") senaryoyu okur, analiz eder ve shotları sırayla üretir.
+Best for:
+
+- solo work
+- smaller productions
+- manual supervision of every shot
 
-Antigravity içinde:
-- Skill: `.agent/skills/shotforge-generate/SKILL.md`
-- Çalışma şekli: tek ajanlı, yüksek kontrol, shot-by-shot üretim
+Key contracts:
 
-**Özellikler:**
-- Veo 3.1 Prompt Flow (Subject > Action > Camera > Light)
-- Kling 3.0 Start+End geçiş kuralları (model-profile üzerinden)
-- Profesyonel Audio Blocks (Dialogue, SFX, Mix)
-- Zorunlu Avoid Line
-- Auto-Safety & Auto-Anonymous
-- Hard Quality Gate: `ILK>=80`, `SON>=80`, `VIDEO>=120`, `Coverage>=70` kelime
-- Specificity Gate: lens + ışık + FG/MG/BG aksiyon detayı zorunlu
+- one file per shot
+- hard quality floor: `ILK >= 80`, `SON >= 80`, `VIDEO >= 120`, `coverage >= 70`
+- shared spatial realism gate when subjects interact
 
----
+### 2. `@milenyumai/film-kit-multi`
 
-## 🚀 Paket 2: Film-Kit Multi (Pro)
-**Kullanım:** Profesyonel stüdyo işleri, uzun metraj, 10+ shot senaryolar.
-**Platformlar:** Claude Code Agent Teams + Antigravity Mission Control
+Parallel production package with Lead Director, shot teammates, and specialist validation.
 
-### Kurulum (Tek Komut)
-Boş bir klasörde terminali açın:
 ```bash
 npx @milenyumai/film-kit-multi init
 npx @milenyumai/film-kit-multi init --model veo31
 npx @milenyumai/film-kit-multi init --model kling-3.0 --kling-preset ultra-realism
 ```
 
-### Kullanım
-Claude Code içinde:
-```text
-/generate
+Best for:
+
+- larger productions
+- 10+ shot sequences
+- team-style generation inside Claude Code Agent Teams or Antigravity Mission Control
+
+Key contracts:
+
+- `team-plan.json`
+- 8 specialist validators in 3-phase execution (continuity -> parallel quality checks -> delivery)
+- parallel batch generation
+- spatial contract for multi-subject staging
+
+### 3. `@milenyumai/film-kit-hybrid`
+
+Hybrid package for Nano Banana still prompts and Kling 3.0 video prompts.
+
+```bash
+npx @milenyumai/film-kit-hybrid init
+npx @milenyumai/film-kit-hybrid init --aspect 16:9 --nano-size 4K
+npx @milenyumai/film-kit-hybrid init --kling-preset balanced
+```
+
+Pipeline:
+
+- `ILK/SON` still prompts -> Nano Banana Pro / Google
+- `VIDEO` prompts -> Kling 3.0
+
+Key contracts:
+
+- one file per shot
+- route is always `kling-3.0`
+- app.kling custom storyboard cap: `3`
+- hybrid-specific spatial realism rules for layered blocking
+
+### 4. `@milenyumai/film-kit-hybrid-smart`
+
+Hybrid package with Nano Banana stills and dialogue-aware video routing.
+
+```bash
+npx @milenyumai/film-kit-hybrid-smart init
+npx @milenyumai/film-kit-hybrid-smart init --aspect 9:16 --nano-size 4K
+npx @milenyumai/film-kit-hybrid-smart init --kling-preset balanced
 ```
-**Lead Director** ajanı ekibi kurar ve yönetir.
 
-Antigravity içinde:
-- Skill: `.agent/skills/shotforge-generate/SKILL.md`
-- Alias: `.agent/skills/shotforge-generate-multi/SKILL.md`
-- Çalışma şekli: Mission Control'de Lead + paralel Shot Generator + Specialist quality gates
-- Not: Skill içinde copy-paste Lead/Worker/Specialist görev şablonları ve hard quality gate bulunur.
+Pipeline:
+
+- `ILK/SON` still prompts -> Nano Banana Pro / Google
+- dialogue video sections -> Veo 3.1
+- no-dialogue video sections -> Kling 3.0
+
+Key contracts:
+
+- per-section route declaration
+- Veo/Kling grammar separation
+- app.kling custom storyboard cap: `3`
+- shared spatial realism gate
 
-**Süreç:**
-1. **Planning:** Lead Director senaryoyu analiz eder, `team-plan.json` oluşturur.
-2. **Casting:** İhtiyaca göre 5'e kadar **Shot Generator** ajanı spawn eder.
-3. **Execution:** Ajanlar shotları hard quality gate ile paralel üretir (`ILK>=80`, `SON>=80`, `VIDEO>=120`, `Coverage>=70`).
-4. **Validation:** 3 Uzman Ajan devreye girer:
-   - `continuity-editor`: Zincirleme (chain) hatalarını yakalar.
-   - `safety-auditor`: Güvenlik ve anonimlik ihlallerini tarar.
-   - `delivery-editor`: Dosya bütünlüğünü ve formatı denetler.
-5. **Recovery:** Hata varsa `/recover` workflow'u otomatik düzeltir.
+## Shared Quality System
 
----
+Film-Kit packages now share a stronger realism layer:
 
-## ⚙️ Config Dosyaları
+- explicit eyeline targets
+- plane map for foreground / midground / background
+- body orientation alignment
+- shared motivated light source
+- depth and contact cues to avoid pasted-cutout or toy-scale results
 
-Core (`shotforge-agent.config.json`):
+This behavior is implemented through:
+
+- `.agent/skills/spatial-blocking/SKILL.md`
+- workflow hard gates
+- Claude local rules and native subagents
+
+## Output Contract
+
+All packages keep the same editorial mindset:
+
+- one file per shot: `SHOTNN.md`
+- coverage stays inside the same shot file
+- reports are generated under `reports/`
+- continuity handoff is explicit
+- cut motivation and editorial purpose are mandatory
+
+## Configuration Files
+
+Core:
 
 ```json
 {
@@ -132,7 +161,7 @@ Core (`shotforge-agent.config.json`):
 }
 ```
 
-Multi (`film-kit-multi.config.json`):
+Multi:
 
 ```json
 {
@@ -145,38 +174,46 @@ Multi (`film-kit-multi.config.json`):
 }
 ```
 
----
+Hybrid:
 
-## ⚡ Komut Referansı (Slash Commands)
+```json
+{
+  "outputDir": "./outputs",
+  "scenarioHint": "scenario.md",
+  "defaultAspectRatio": "16:9",
+  "nanoBananaImageSize": "2K",
+  "klingPreset": "ultra-realism"
+}
+```
 
-| Komut | Paket | İşlev |
-|-------|-------|-------|
-| `/generate` | Core / Multi | Kurulu moda göre tekli veya multi üretim başlatır. |
-| `/chain` | Her İkisi | Son üretilen shot'ın bitiş karesinden devam eder. |
-| `/finish` | Her İkisi | Projeyi sonlandırır ve `FINAL-SUMMARY.md` yazar. |
-| `/recover` | Her İkisi | Başarısız üretimleri veya kalite kontrol takılanlarını onarır. |
-| `/safety-check` | Her İkisi | Manuel güvenlik taraması yapar. |
+Smart hybrid:
 
----
+```json
+{
+  "outputDir": "./outputs",
+  "scenarioHint": "scenario.md",
+  "defaultAspectRatio": "16:9",
+  "nanoBananaImageSize": "2K",
+  "klingPreset": "ultra-realism",
+  "maxKlingCustomShots": 3
+}
+```
+
+## Development
 
-## 🆚 Karşılaştırma
+```bash
+npm install
+npm run typecheck
+npm test
+```
 
-| Özellik | Film-Kit (Core) | Film-Kit Multi (Pro) |
-|---------|-----------------|----------------------|
-| **Mimari** | Tek Ajan | Lead + Teammates + Specialists |
-| **Hız (20 Shot)** | ~60 dk | ~20 dk (Paralel) |
-| **Kalite Gate** | Hard prompt gate | Hard prompt gate + specialist gate |
-| **Tutarlılık** | Manuel Kontrol | `continuity-editor` Denetimi |
-| **Güvenlik** | Prompt İçi Filtre | `safety-auditor` Taraması |
-| **Planlama** | Yok | `team-plan.json` Kontratlı |
-| **Recovery** | Manuel | Otomatik `/recover` |
+Package publishing happens from:
 
----
+- repo root for `@milenyumai/film-kit`
+- `packages/multi` for `@milenyumai/film-kit-multi`
+- `packages/hybrid` for `@milenyumai/film-kit-hybrid`
+- `packages/hybrid-smart` for `@milenyumai/film-kit-hybrid-smart`
 
-## 🛠 Gereksinimler
-- **Node.js:** v20+
-- **Claude Code:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (Sadece Multi için)
-- **Editör/Platform:** VS Code, Cursor, Claude Code veya Antigravity
+## License
 
-## 📄 Lisans
 MIT

package/build/lib/configure.js

@@ -1,6 +1,6 @@
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { readdir, readFile } from "node:fs/promises";
+import { readdir, readFile, rm } from "node:fs/promises";
 import { exists, readJsonIfExists, writeText } from "./fs.js";
 import { resolveOptions } from "./defaults.js";
 import { buildProjectFiles } from "./templates.js";
@@ -72,6 +72,27 @@ function renderContentTemplate(content, vars) {
 function getModelDisplayName(model) {
     return model === "kling-3.0" ? "Kling 3.0" : "Google Flow + Veo 3.1";
 }
+async function removePathIfExists(rootDir, relativePath) {
+    const absolutePath = join(rootDir, relativePath);
+    if (await exists(absolutePath)) {
+        await rm(absolutePath, { force: true, recursive: true });
+    }
+}
+async function removeStaleClaudeArtifacts(rootDir) {
+    const stalePaths = [
+        ".claude/rules/multi-generate.md",
+        ".claude/rules/team-coordination.md",
+        ".claude/rules/recovery-playbook.md",
+        ".claude/agents/lead-director.md",
+        ".claude/agents/shot-generator.md",
+        ".claude/agents/continuity-editor.md",
+        ".claude/agents/safety-auditor.md",
+        ".claude/agents/delivery-editor.md"
+    ];
+    for (const relativePath of stalePaths) {
+        await removePathIfExists(rootDir, relativePath);
+    }
+}
 export async function configureAgents(options = {}) {
     const rootDir = options.rootDir ?? process.cwd();
     const packageConfigPath = join(rootDir, "shotforge-agent.config.json");
@@ -102,6 +123,9 @@ export async function configureAgents(options = {}) {
     if (copyContent !== undefined)
         merged.copyContent = copyContent;
     const resolved = resolveOptions(merged);
+    if (resolved.platforms.includes("claude")) {
+        await removeStaleClaudeArtifacts(resolved.rootDir);
+    }
     // 1. Copy content files (.agent/ system) if enabled
     const contentResult = resolved.copyContent
         ? await copyContentFiles(resolved.rootDir, resolved.overwrite, {

package/build/lib/templates.js

@@ -15,6 +15,7 @@ export function buildProjectFiles(config) {
     if (config.platforms.includes("claude")) {
         files["CLAUDE.md"] = buildClaudeRoot(config);
         files[".claude/CLAUDE.md"] = buildClaudeLocal(config);
+        files[".claude/agents/prompt-engineer.md"] = buildClaudePromptEngineerSubagent(config);
         files[".claude/rules/generate-flow.md"] = buildClaudeRuleGenerateFlow(config);
         files[".claude/rules/output-contract.md"] = buildClaudeRuleOutputContract(config);
         files[".claude/settings.json"] = buildClaudeSettings();
@@ -46,12 +47,13 @@ All rules, skills, and workflows are located under \`.agent/\`.
 - **Model Profile:** \`.agent/model-profile.md\` — Active model rules and constraints
 - **Agent:** \`.agent/agents/prompt-engineer.md\` — Senior prompt engineer agent
 
-### Skills (7 modules)
+### Skills (8 modules)
 | Skill | Path | Priority |
 |-------|------|----------|
 | Safety Compliance | \`.agent/skills/safety-compliance/SKILL.md\` | P0 — ALWAYS |
 | Reference Locking | \`.agent/skills/reference-locking/SKILL.md\` | P1 — When refs provided |
 | Frame Chaining | \`.agent/skills/frame-chaining/SKILL.md\` | P2 — ALWAYS |
+| Spatial Blocking | \`.agent/skills/spatial-blocking/SKILL.md\` | P2 — Relational realism / gaze / depth |
 | Coverage System | \`.agent/skills/coverage-system/SKILL.md\` | P2 — ALWAYS (mandatory) |
 | Visual Modes | \`.agent/skills/visual-modes/SKILL.md\` | P4 — ALWAYS |
 | Audio Design | \`.agent/skills/audio-design/SKILL.md\` | P4 — When dialogue/SFX |
@@ -115,6 +117,7 @@ Read .agent/model-profile.md first to apply model-specific rules.
 | Safety & Celebrity Ban | .agent/skills/safety-compliance/SKILL.md | ALWAYS |
 | Reference Locking | .agent/skills/reference-locking/SKILL.md | When refs provided |
 | Frame Chaining | .agent/skills/frame-chaining/SKILL.md | Multi-shot projects |
+| Spatial Blocking | .agent/skills/spatial-blocking/SKILL.md | Multi-subject / gaze / scale-critical shots |
 | Coverage System | .agent/skills/coverage-system/SKILL.md | ALWAYS (mandatory) |
 | Visual Modes | .agent/skills/visual-modes/SKILL.md | All visual work |
 | Audio Design | .agent/skills/audio-design/SKILL.md | Dialogue/SFX needed |
@@ -166,8 +169,9 @@ Read \`.agent/model-profile.md\` for active model constraints.
 ## SKILL LOADING (MANDATORY)
 Before generating ANY prompts:
 1. ALWAYS load: safety-compliance, frame-chaining, coverage-system, prompt-structure, visual-modes
-2. Load if refs provided: reference-locking
-3. Load if dialogue/SFX: audio-design
+2. Load for relational realism: spatial-blocking
+3. Load if refs provided: reference-locking
+4. Load if dialogue/SFX: audio-design
 
 All skills at: \`.agent/skills/[name]/SKILL.md\`
 
@@ -202,27 +206,46 @@ All skills at: \`.agent/skills/[name]/SKILL.md\`
 }
 /* ---------- CLAUDE ---------- */
 function buildClaudeRoot(config) {
-    return `# CLAUDE.md — Film-Kit (Hollywood Standard)
+    return `# CLAUDE.md — Film-Kit Core Runtime
 
-> Professional Cinematic Prompt Engineering for ${getModelDisplayName(config.model)}
+> Professional single-agent cinematic prompt engineering for ${getModelDisplayName(config.model)}
 
-## System Entry Point
-Read \`.agent/MASTER.md\` for the complete production ruleset.
-Read \`.agent/ARCHITECTURE.md\` for the system overview.
-Read \`.agent/model-profile.md\` for active model constraints.
-Read \`.agent/agents/prompt-engineer.md\` for agent behavior.
+## Workspace Mode
+Single-agent shot package generation. Claude Code may use the native \`prompt-engineer\` subagent for focused drafting or repair, but planning and delivery stay in one session.
+
+## Mandatory Read Order
+1. \`.agent/model-profile.md\`
+2. \`.agent/MASTER.md\`
+3. \`.agent/ARCHITECTURE.md\`
+4. \`.agent/agents/prompt-engineer.md\`
+5. \`.claude/CLAUDE.md\`
+6. relevant files under \`.claude/rules/\`
 
-## CRITICAL: Skill Loading Protocol
+## Native Claude Code Components
+- Project memory files: \`CLAUDE.md\` and \`.claude/CLAUDE.md\`
+- Native subagent: \`.claude/agents/prompt-engineer.md\`
+- Operational rules: \`.claude/rules/generate-flow.md\`, \`.claude/rules/output-contract.md\`
+
+## Skill Loading Protocol
 Before generating ANY prompts, read skills from \`.agent/skills/\`:
 - \`safety-compliance/SKILL.md\` — ALWAYS (P0)
 - \`reference-locking/SKILL.md\` — When refs provided (P1)
 - \`frame-chaining/SKILL.md\` — ALWAYS for multi-shot (P2)
+- \`spatial-blocking/SKILL.md\` — when gaze / scale / compositing realism matters (P2)
 - \`coverage-system/SKILL.md\` — ALWAYS, mandatory (P2)
 - \`visual-modes/SKILL.md\` — ALWAYS (P4)
 - \`audio-design/SKILL.md\` — When dialogue/SFX (P4)
 - \`prompt-structure/SKILL.md\` — ALWAYS (P5)
 
-## Universal Rules (Always Active)
+## Generation Contract
+- Scenario source: active/selected markdown file first, fallback \`${config.scenarioHint}\`
+- Model: \`${config.model}\` (${getModelDisplayName(config.model)})
+- Kling preset: \`${config.klingPreset}\`
+- Create \`${config.outputDir}/project-info.md\`, \`${config.outputDir}/shot-plan.json\`, and \`${config.outputDir}/_index.md\`
+- Write \`${config.outputDir}/shots/SHOTNN.md\` per shot; coverage stays in the same file
+- Refresh \`${config.outputDir}/reports/SAFETY-REPORT.md\` and \`${config.outputDir}/reports/DELIVERY-REPORT.md\` before \`/finish\`
+
+## Non-Negotiables
 1. **AUTO-ANONYMOUS:** Replace ALL real person names in visual prompts with physical descriptions.
 2. **Dialogue Name Policy:** Follow \`${config.outputDir}/shot-plan.json\` policy.
 3. **AUTO-SAFETY:** Proactively reframe content that may trigger safety filters.
@@ -230,9 +253,12 @@ Before generating ANY prompts, read skills from \`.agent/skills/\`:
 5. **Pacing:** 8s default, slow burn. "Ilmek ilmek islemek."
 6. **Music:** NONE by default.
 7. **Avoid line:** MANDATORY on every prompt (image, video, coverage).
-8. **Coverage:** 2-3 sub-shots within same SHOTNN.md file, min 60 words each.
+8. **Coverage:** 2-3 sub-shots within same SHOTNN.md file, min 70 words each.
 9. **ILK/İLK FRAME:** Always include a fenced code block, even when chained.
-10. **ONE FILE PER SHOT:** No separate coverage files.
+10. **Quality Floor:** ILK >= 80, SON >= 80, VIDEO >= 120, coverage >= 70 words.
+11. **Specificity Floor:** lens/framing, lighting, and foreground/midground/background action are mandatory.
+12. **Spatial Realism Floor:** eyeline target, plane map, shared light source, and contact/depth cues are mandatory when relational staging matters.
+13. **ONE FILE PER SHOT:** No separate coverage files.
 
 ## Workflows
 | Command | Workflow |
@@ -243,43 +269,66 @@ Before generating ANY prompts, read skills from \`.agent/skills/\`:
 | \`/recover\` | \`.agent/workflows/recover.md\` |
 | \`/finish\` | \`.agent/workflows/finish.md\` |
 
-## I/O
-- Scenario source: \`${config.scenarioHint}\` (or active editor tab)
-- Model: \`${config.model}\` (${getModelDisplayName(config.model)})
-- Kling preset: \`${config.klingPreset}\`
-- Output: \`${config.outputDir}/shots/SHOTNN.md\` per shot (single file with coverage)
-- Index: \`${config.outputDir}/_index.md\`
-- Project info: \`${config.outputDir}/project-info.md\`
-- Plan: \`${config.outputDir}/shot-plan.json\`
-- Reports: \`${config.outputDir}/reports/SAFETY-REPORT.md\`, \`${config.outputDir}/reports/DELIVERY-REPORT.md\`
-
-Follow rules under \`.claude/rules/\`.
+## Claude Code Ops
+- Use \`/memory\` to verify which CLAUDE and rule files are loaded.
+- Use the native \`prompt-engineer\` subagent for focused drafting, repair, or review inside Claude Code.
+- Follow the stricter rule when \`.agent/\` and \`.claude/\` instructions overlap.
 `;
 }
 function buildClaudeLocal(config) {
-    return `# Local Claude Project Rules — Film-Kit
-
-This workspace uses the Film-Kit Hollywood prompt engineering system.
-All production rules are in \`.agent/MASTER.md\`.
-Always read \`.agent/model-profile.md\` before any generation.
+    return `# Local Claude Project Rules — Film-Kit Core
+
+This workspace keeps high-level policy in \`CLAUDE.md\` and operational detail in \`.claude/rules/\`.
+
+## Before Any Generation or Repair
+1. Read \`.agent/model-profile.md\`
+2. Read \`.agent/MASTER.md\`
+3. Read \`.agent/agents/prompt-engineer.md\`
+4. Read \`.agent/workflows/generate.md\` or the requested workflow
+5. Apply AUTO-ANONYMOUS and AUTO-SAFETY before drafting
+6. Prefer the active/selected markdown file as scenario source; fallback is \`${config.scenarioHint}\`
+7. Do not mark work complete while any required report is missing or fail
+
+## Core Runtime Rules
+- Write only inside \`${config.outputDir}\`
+- Keep one file per shot: \`${config.outputDir}/shots/SHOTNN.md\`
+- Maintain \`${config.outputDir}/shot-plan.json\` dialogue naming policy
+- Keep \`ILK/İLK FRAME\` in a fenced code block even when chained
+- Quality floor and specificity floor are hard gates, not suggestions
+- Apply \`.agent/skills/spatial-blocking/SKILL.md\` whenever eyeline, compositing, or depth realism is critical
+
+## Debugging
+- Use \`/memory\` to confirm this file and \`.claude/rules/*\` are loaded
+- If delegation helps, use \`.claude/agents/prompt-engineer.md\`
+`;
+}
+function buildClaudePromptEngineerSubagent(config) {
+    return `---
+name: prompt-engineer
+description: Generate and repair Film-Kit single-agent shot packages with strict anonymity, chaining, coverage, and delivery gates.
+---
 
-## On /generate
-1. Read \`.agent/workflows/generate.md\` for full procedure
-2. Analyze scenario, auto-anonymize, apply safety
-3. Generate shot files at \`${config.outputDir}/shots/SHOTNN.md\`
-4. Each SHOTNN.md: İLK FRAME + SON FRAME + VİDEO + 2-3 Coverage (ALL IN ONE FILE)
-5. Keep İLK FRAME as a fenced code block even when chained
-6. Maintain visual anonymity; apply dialogue name policy from \`${config.outputDir}/shot-plan.json\`
-7. Generate/refresh reports in \`${config.outputDir}/reports/\` before finish
-
-## Priority Hierarchy
-| Priority | Rule |
-|----------|------|
-| P0 | Platform Safety (overrides everything) |
-| P1 | Reference Fidelity |
-| P2 | Chain Continuity |
-| P3 | Story Integrity |
-| P4 | Visual Quality |
+Use the Film-Kit core runtime.
+
+## Read First
+1. \`.agent/model-profile.md\`
+2. \`.agent/MASTER.md\`
+3. \`.agent/agents/prompt-engineer.md\`
+4. \`.agent/workflows/generate.md\`
+5. \`.claude/rules/output-contract.md\`
+
+## Responsibilities
+- draft and repair shot files under \`${config.outputDir}/shots/\`
+- apply \`${config.outputDir}/shot-plan.json\` dialogue naming policy
+- enforce AUTO-ANONYMOUS, AUTO-SAFETY, chaining, and coverage contracts
+- enforce quality floor: ILK >= 80, SON >= 80, VIDEO >= 120, coverage >= 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
+
+## Boundaries
+- do not skip safety or delivery reports
+- do not split coverage into separate files
+- if asked to review only, report issues instead of regenerating shots by default
 `;
 }
 function buildClaudeRuleGenerateFlow(config) {
@@ -288,6 +337,7 @@ function buildClaudeRuleGenerateFlow(config) {
 ## Full Procedure
 Read \`.agent/workflows/generate.md\` for the complete generation workflow.
 Read \`.agent/model-profile.md\` for active model constraints.
+If using the native Claude subagent, read \`.claude/agents/prompt-engineer.md\` and give it an explicit shot range or repair target.
 
 ## Quick Reference
 1. **Scenario Analysis:**
@@ -309,6 +359,9 @@ Read \`.agent/model-profile.md\` for active model constraints.
    - Analyze scene type (Dialogue / Action / Emotional / Establishing)
    - Generate main shot (İLK FRAME + SON FRAME + VİDEO)
    - Keep İLK FRAME as fenced code block even when chained
+   - Enforce hard quality floor: ILK >= 80, SON >= 80, VIDEO >= 120, coverage >= 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
    - Generate 2-3 coverage shots (in same file)
    - Write to \`${config.outputDir}/shots/SHOT[NN].md\`
    - Update \`${config.outputDir}/_index.md\`
@@ -504,6 +557,12 @@ OTS pairs must be symmetrical across the axis.
 ### Eyeline Match
 Character gaze directions must be spatially consistent between cuts.
 
+### Relational Realism
+- When multiple subjects share frame, define foreground/midground/background explicitly.
+- Name the gaze target and write \`not camera\` when camera-looking would be a failure.
+- Keep one motivated light source across subjects.
+- Add contact / weight / support cues to avoid pasted composite look.
+
 ### Dramaturgy (for dialogue scenes)
 Analyze per character: Objective → Obstacle → Stakes → Subtext → Beat turns.
 Embed as physical behavior in prompts, NOT as metadata.
@@ -514,20 +573,14 @@ Embed as physical behavior in prompts, NOT as metadata.
 }
 function buildClaudeSettings() {
     return JSON.stringify({
-        model_preferences: {
-            style: "cinematic"
-        },
-        workspace_rules: {
-            enabled: true
-        }
-    }, null, 2);
+        effortLevel: "high"
+    }, null, 2) + "\n";
 }
 function buildClaudeSettingsLocal() {
     return JSON.stringify({
-        local_overrides: {
-            use_selected_file_first: true
-        }
-    }, null, 2);
+        autoMemoryEnabled: true,
+        showTurnDuration: true
+    }, null, 2) + "\n";
 }
 /* ---------- COPILOT ---------- */
 function buildCopilotInstructions(config) {
@@ -544,10 +597,11 @@ Before generating ANY prompts, read skills from \`.agent/skills/\`:
 1. \`safety-compliance/SKILL.md\` — ALWAYS (celebrity ban, auto-anonymous)
 2. \`reference-locking/SKILL.md\` — When reference images provided
 3. \`frame-chaining/SKILL.md\` — ALWAYS for multi-shot continuity
-4. \`coverage-system/SKILL.md\` — ALWAYS (mandatory coverage shots)
-5. \`visual-modes/SKILL.md\` — ALWAYS (Ultra Realism default)
-6. \`audio-design/SKILL.md\` — When dialogue or SFX needed
-7. \`prompt-structure/SKILL.md\` — ALWAYS (prompt templates)
+4. \`spatial-blocking/SKILL.md\` — When gaze / depth / scale realism is critical
+5. \`coverage-system/SKILL.md\` — ALWAYS (mandatory coverage shots)
+6. \`visual-modes/SKILL.md\` — ALWAYS (Ultra Realism default)
+7. \`audio-design/SKILL.md\` — When dialogue or SFX needed
+8. \`prompt-structure/SKILL.md\` — ALWAYS (prompt templates)
 
 ### When User Asks /generate
 1. Read \`.agent/workflows/generate.md\` for the full procedure
@@ -564,6 +618,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]
 - **Coverage:** 2-3 sub-shots per main shot (in same file, min 60 words each)
+- **Spatial Realism:** eyeline targets, shared light, depth scale, and anti-cutout staging must agree when subjects share frame
 - **Avoid Line:** MANDATORY on every prompt
 - **Music:** NONE by default
 - **Duration:** 8s default, slow burn pacing
@@ -619,10 +674,11 @@ Before generating ANY prompts, read these skills:
 1. \`.agent/skills/safety-compliance/SKILL.md\` — ALWAYS
 2. \`.agent/skills/reference-locking/SKILL.md\` — When refs provided
 3. \`.agent/skills/frame-chaining/SKILL.md\` — ALWAYS
-4. \`.agent/skills/coverage-system/SKILL.md\` — ALWAYS (mandatory)
-5. \`.agent/skills/visual-modes/SKILL.md\` — ALWAYS
-6. \`.agent/skills/audio-design/SKILL.md\` — When dialogue/SFX
-7. \`.agent/skills/prompt-structure/SKILL.md\` — ALWAYS
+4. \`.agent/skills/spatial-blocking/SKILL.md\` — When gaze / depth / scale realism is critical
+5. \`.agent/skills/coverage-system/SKILL.md\` — ALWAYS (mandatory)
+6. \`.agent/skills/visual-modes/SKILL.md\` — ALWAYS
+7. \`.agent/skills/audio-design/SKILL.md\` — When dialogue/SFX
+8. \`.agent/skills/prompt-structure/SKILL.md\` — ALWAYS
 
 ## Workflows
 | Command | Workflow |
@@ -658,6 +714,7 @@ Before generating ANY prompts, read these skills:
 9. **8s duration** default, slow burn pacing
 10. **ILK/İLK FRAME:** always keep fenced code block
 11. **ONE FILE PER SHOT:** SHOTNN.md contains main shot + all coverage
+12. **Relational Realism:** preserve eyeline targets, shared light, depth scale, and anti-cutout staging when multiple subjects share frame
 
 ## Quality Floor (Hard Gate)
 Reject and regenerate any shot that fails:
@@ -668,6 +725,8 @@ Reject and regenerate any shot that fails:
 - missing explicit lens/framing/camera movement details
 - missing explicit lighting direction/intensity/atmosphere details
 - missing explicit foreground/midground/background action details
+- missing explicit eyeline target or \`not camera\` instruction when gaze matters
+- missing explicit shared light source / depth / contact cues in multi-subject shots
 
 ## Reject Weak Prompt Style
 Do not accept generic filler language:
@@ -731,6 +790,20 @@ When generating video from a reference image:
 
 ## Kling 3.0 Rules${isKling ? " (ACTIVE)" : " (Reference)"}
 
+### Official Kling 3.0 Capability Surface
+The official Kling surface currently advertises:
+- Text to Video
+- Image to Video
+- Multi-Image to Video
+- Elements Reference / Multi-Elements
+- Video Extension
+- Lip-Sync
+- Video Effects
+- Audio Generation
+- Kling 3.0 series API availability
+
+Treat that surface as a planning signal: identity anchors, reusable elements, and clean start/end staging matter more than adjective-heavy prose.
+
 ### Mindset: Kling as Transition Director
 Kling's job with Start+End: **preserve the starting composition**, generate **physically plausible** intermediate motion, and **arrive at the end composition**.
 
@@ -919,6 +992,8 @@ Kling 3.0 can manage **2 to 6 shots** in a single 15-second generation.
 3. **Time Distribution:** 15 seconds must be logically divided (e.g., Shot 1: 3s, Shot 2: 7s, Shot 3: 5s)
 4. **Maximum:** 6 shots per generation; for more, use separate generations with chaining
 
+Official examples favor short, concrete camera-and-action openings. Start with the movement path or subject action, then lock the stable identity/background constraints.
+
 **Example Multi-Shot Prompt:**
 \`\`\`
 Shot 1, Close-up of a bearded man in his 40s, wearing a dusty military uniform. He stares ahead, jaw clenched. Tripod-locked, 85mm, shallow DOF. (3s)

package/content/ARCHITECTURE.md

@@ -9,7 +9,7 @@
 Modular system consisting of:
 
 - **1 Specialist Agent** - Technical Prompt Engineer
-- **7 Skills** - Domain-specific knowledge modules
+- **8 Skills** - Domain-specific knowledge modules
 - **4 Workflows** - Slash command procedures
 
 ---
@@ -27,8 +27,9 @@ Modular system consisting of:
 │   ├── safety-compliance/   # Platform safety & celebrity ban
 │   ├── reference-locking/   # Reference image system
 │   ├── frame-chaining/      # Shot continuity protocol
-│   ├── coverage-system/     # Mandatory coverage shots (NEW)
-│   ├── visual-modes/        # Ultra Realism & style modes
+│   ├── coverage-system/     # Mandatory coverage shots (NEW)
+│   ├── spatial-blocking/    # Eyeline, depth, scale, compositing realism
+│   ├── visual-modes/        # Ultra Realism & style modes
 │   ├── audio-design/        # Sound design rules
 │   └── prompt-structure/    # Prompt engineering patterns
 └── workflows/
@@ -45,19 +46,20 @@ Modular system consisting of:
 
 | Agent | Focus | Skills Used |
 |-------|-------|-------------|
-| `prompt-engineer` | Cinematic prompt generation for Veo 3.1 | All 7 skills |
-
----
-
-## 🧩 Skills (7)
+| `prompt-engineer` | Cinematic prompt generation for Veo 3.1 / Kling 3.0 | All 8 skills |
+
+---
+
+## 🧩 Skills (8)
 
 | Skill | Description |
 |-------|-------------|
 | `safety-compliance` | **Platform safety**, celebrity name prohibition, AUTO-ANONYMOUS (otomatik anonimleştirme), AUTO-SAFETY, safe framing, content restrictions |
-| `reference-locking` | **Reference image enforcement**, EXACTLY language, repeat protocol |
-| `frame-chaining` | **Shot continuity**, last frame → first frame chaining, scene transition protocol (fade, dissolve, match cut) |
-| `coverage-system` | **Mandatory coverage shots** (Reaction, OTS, Insert, Cutaway, ECU, Wide) + L-cut/J-cut + 30° kuralı + **180° kuralı** + eyeline match + matching action + multi-character blocking |
-| `visual-modes` | **Ultra Realism** default, stylization triggers, anti-AI artifact rules + **renk sürekliliği** + magic hour + flashback/rüya görsel ayrımı |
+| `reference-locking` | **Reference image enforcement**, EXACTLY language, repeat protocol |
+| `frame-chaining` | **Shot continuity**, last frame → first frame chaining, scene transition protocol (fade, dissolve, match cut) |
+| `coverage-system` | **Mandatory coverage shots** (Reaction, OTS, Insert, Cutaway, ECU, Wide) + L-cut/J-cut + 30° kuralı + **180° kuralı** + eyeline match + matching action + multi-character blocking |
+| `spatial-blocking` | **Relational realism**: eyeline targeting, plane mapping, body orientation, shared lighting, depth/scale integration, anti-cutout / anti-miniature cues |
+| `visual-modes` | **Ultra Realism** default, stylization triggers, anti-AI artifact rules + **renk sürekliliği** + magic hour + flashback/rüya görsel ayrımı |
 | `audio-design` | **Sound design** rules, voice realism, SFX, ambience, audio direction block + diegetic/non-diegetic ses ayrımı |
 | `prompt-structure` | Image/video prompt templates, camera vocabulary, seed parameter, prompt rewriter, **re-take strategy**, coverage prompt yazım standartları (≥60 kelime) |
 
@@ -83,9 +85,10 @@ User Scenario → Agent Activated → Read model-profile → Load Required Skill
                             .agent/model-profile.md (ALWAYS FIRST)
                                        ↓
                             safety-compliance (ALWAYS)
-                            reference-locking (if refs provided)
-                            frame-chaining (ALWAYS)
-                            coverage-system (ALWAYS - mandatory)
+                            reference-locking (if refs provided)
+                            frame-chaining (ALWAYS)
+                            spatial-blocking (when gaze/depth/scale realism matters)
+                            coverage-system (ALWAYS - mandatory)
                             visual-modes (check for style triggers)
                             audio-design (if dialogue/SFX needed)
                             prompt-structure (ALWAYS)

package/content/MASTER.md

@@ -24,8 +24,9 @@ Scenario Received → Check for elements:
     │
     ├── Celebrity/Public Figure mentioned? → READ safety-compliance/SKILL.md
     ├── Reference images provided? → READ reference-locking/SKILL.md
-    ├── Multiple shots? → READ frame-chaining/SKILL.md (ALWAYS)
-    ├── Style keywords (anime, noir, etc.)? → READ visual-modes/SKILL.md
+    ├── Multiple shots? → READ frame-chaining/SKILL.md (ALWAYS)
+    ├── Multi-subject / gaze / depth realism? → READ spatial-blocking/SKILL.md
+    ├── Style keywords (anime, noir, etc.)? → READ visual-modes/SKILL.md
     ├── Dialogue/SFX needed? → READ audio-design/SKILL.md
     ├── ALWAYS READ → coverage-system/SKILL.md (MANDATORY)
     └── ALWAYS READ → prompt-structure/SKILL.md
@@ -157,11 +158,18 @@ When user provides references, EVERY prompt MUST:
 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 detayı
 3. [Aksiyon] — Ne yapıyor, mikro-davranış, oyunculuk ipucu
-4. [Kamera + Lens] — "85mm f/2.0, shallow DOF, static with handheld micro-movement"
-5. [Işık + Atmosfer] — "Warm oil lamp key light from screen-left, deep shadows"
-6. [Audio direction block] — (sadece video prompt'larında)
-7. [Avoid line] — (HER prompt'ta zorunlu)
-```
+4. [Kamera + Lens] — "85mm f/2.0, shallow DOF, static with handheld micro-movement"
+5. [Işık + Atmosfer] — "Warm oil lamp key light from screen-left, deep shadows"
+6. [Audio direction block] — (sadece video prompt'larında)
+7. [Avoid line] — (HER prompt'ta zorunlu)
+```
+
+**Spatial Blocking Layer (zorunlu, uygun sahnelerde):**
+- Foreground / midground / background açıkça tanımlanır
+- Karakterin bakış hedefi net yazılır (`not camera` gerektiğinde açıkça belirtilir)
+- Çene / omuz / gövde yönü bakışı destekler
+- Tek motive ışık kaynağı ve tüm öznelere etkisi yazılır
+- Derinlik ve ölçek için haze / contrast falloff / tam ölçek ilişkisi belirtilir
 
 **❌ YANLIŞ:** Detayla başlayıp sahne özetini ortada vermek
 **✅ DOĞRU:** İlk cümle = "Bu shot ne?" sorusunun tek cümlelik cevabı

package/content/agents/prompt-engineer.md

@@ -1,7 +1,7 @@
 ---
 name: prompt-engineer
 description: Senior Technical Prompt Engineer for model-aware runtime profiles (Veo 3.1 / Kling 3.0). Converts shot lists and scenarios into production-grade cinematic prompts optimized for continuity and platform compliance.
-skills: safety-compliance, reference-locking, frame-chaining, coverage-system, visual-modes, audio-design, prompt-structure
+skills: safety-compliance, reference-locking, frame-chaining, coverage-system, spatial-blocking, visual-modes, audio-design, prompt-structure
 ---
 
 # Prompt Engineer - Hollywood Standard Cinematic Video Generation
@@ -41,8 +41,9 @@ 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
-16. **Hard specificity floor:** Her promptta lens/framing, lighting ve FG/MG/BG action detayları zorunlu
+15. **Hard quality floor:** ILK >=80, SON >=80, VIDEO >=120, coverage >=70 kelime
+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
 
 ---
 
@@ -199,8 +200,9 @@ Before outputting ANY shot:
 - [ ] Audio direction present on EVERY video prompt? (Veo block or Kling inline)
 - [ ] 2-3 Coverage shots included in the same file?
 - [ ] Quality floor passes? (ILK>=80, SON>=80, VIDEO>=120, coverage>=70)
-- [ ] Specificity floor passes? (lens + lighting + FG/MG/BG action)
-- [ ] Model Control block exists? (`Model`, `Preset`, `CFG`, `Transition Mode`)
+- [ ] Specificity floor passes? (lens + lighting + FG/MG/BG action)
+- [ ] Spatial realism passes? (eyeline target + plane map + shared light + contact/depth cues)
+- [ ] Model Control block exists? (`Model`, `Preset`, `CFG`, `Transition Mode`)
 
 ### 3. Kling-Specific Gates (when model is kling-3.0)
 - [ ] Motion timeline uses `first → then → finally` structure?

package/content/skills/spatial-blocking/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: spatial-blocking
+description: Relational staging system for eyelines, plane mapping, contact/weight cues, shared lighting, and depth integration. Prevents pasted-composite, toy-scale, and disconnected-gaze artifacts in realistic scenes.
+---
+
+# Spatial Blocking & Relational Realism
+
+> **Philosophy:** A believable frame is not a pile of objects. It is a set of spatial relationships.
+> **Core Principle:** If subjects do not share gaze, light, depth, and physical contact logic, the image will look fake no matter how detailed the prompt is.
+
+---
+
+## When To Load
+
+Load this skill whenever ANY of these are true:
+
+- two or more subjects appear in the same frame
+- a person must look at a specific object/person, not the camera
+- foreground and background subjects must feel naturally integrated
+- a vehicle / large prop / architecture piece shares the frame with a person
+- scale, perspective, or compositing realism matters
+
+If unsure, load it.
+
+---
+
+## Primary Failure Modes
+
+| Failure | What It Looks Like | Root Cause |
+|---------|--------------------|-----------|
+| **Disconnected gaze** | Subject looks at camera or empty air | Eyeline target not specified spatially |
+| **Cutout / pasted composite** | Person feels dropped in like PNG | Shared light/contact/occlusion logic missing |
+| **Toy / miniature scale** | Soldier, tank, building look like models | Wrong depth cues, texture contrast, or focal logic |
+| **Floating subject** | Body has no weight against environment | No support/contact/pressure cues |
+| **Plane confusion** | Foreground/background feel collapsed | No plane map or atmospheric depth plan |
+
+---
+
+## Mandatory Spatial Contract
+
+For any spatially complex shot, the prompt must answer all five:
+
+1. **Plane Map:** Who/what is in foreground, midground, background?
+2. **Eyeline Map:** Exactly who is looking at what?
+3. **Body Orientation:** How are chin, torso, shoulders, and hands oriented?
+4. **Light Map:** What is the motivated key light and how does it hit each subject?
+5. **Depth Map:** How do contrast, texture, and haze change by distance?
+
+If even one is missing, realism drops sharply.
+
+---
+
+## 1. Plane Map
+
+Always define frame layers explicitly when multiple subjects share the frame.
+
+### Required Language
+
+Use this kind of phrasing:
+
+```text
+Foreground left: elderly woman, 1 meter from camera, filling the left third.
+Midground center: tank turret, 3 meters behind her.
+Upper midground: soldier emerging from hatch above the turret.
+Background: apartment facade softened by sodium-vapor haze.
+```
+
+### Rules
+
+- Give each important subject a plane: foreground / midground / background
+- Give rough distance when scale matters
+- Give frame position: left third, center, upper right, etc.
+- If one subject overlaps another, say so
+
+### Do Not Write
+
+- "A woman and a tank in the street"
+- "Soldier behind her"
+
+Those describe inventory, not spatial staging.
+
+---
+
+## 2. Eyeline Map
+
+AI is weak at "X looks at Y" unless you specify target, height, and direction.
+
+### Required Language
+
+```text
+Her eyes are locked upward toward the soldier in the hatch, not toward the camera.
+The soldier looks downward toward the woman below him.
+Both eyelines intersect on the tank hatch line.
+```
+
+### Rules
+
+- Name the target object/person explicitly
+- State `not camera` when camera-looking would be a common failure
+- Use directional phrasing: upward, downward, screen-left, across frame
+- Make head angle and gaze angle support each other
+
+### Eyeline Checklist
+
+- eyes target is named
+- head angle supports eye direction
+- body orientation supports head angle
+- reciprocal gaze is specified when two characters interact
+
+---
+
+## 3. Body Orientation & Contact
+
+Subjects feel fake when gaze says one thing but body says another.
+
+### Required Language
+
+```text
+Her chin tilts upward, shoulders turned toward the tank, raised palm directed toward the soldier.
+The soldier braces both forearms on the hatch rim, torso leaning slightly forward.
+```
+
+### Contact / Weight Cues
+
+Always add physical support cues for realism:
+
+- palm pressing against metal
+- elbow resting on hatch rim
+- sleeve compression at wrist
+- boot planted on track guard
+- cloth tension where arm is raised
+- body weight shifted into the grounded leg
+
+These cues reduce the pasted-PNG feeling.
+
+---
+
+## 4. Shared Light Map
+
+The fastest way to create a composite artifact is to light each subject as if they live in different scenes.
+
+### Required Language
+
+```text
+Single motivated sodium-vapor streetlamp from upper right.
+Warm amber spill hits the woman's headscarf, the soldier's helmet, and the tank turret from the same direction.
+Soft bounce from the tank's green metal lifts the underside of her raised hand.
+```
+
+### Rules
+
+- name one motivated light source first
+- specify direction: upper right, screen-left, back-right, overhead
+- specify color temperature / hue
+- mention how the same source affects each major subject
+- if there is bounce, rim, or practical spill, say where it comes from
+
+### Shared-Light Checklist
+
+- same key direction for all subjects
+- same color family across subjects
+- shadows make sense relative to source
+- metallic / fabric / skin materials react differently but consistently
+
+---
+
+## 5. Depth, Scale, and Atmospheric Integration
+
+Distance must change the image.
+
+### Required Language
+
+```text
+Foreground skin and cloth retain crisp microtexture.
+The soldier in upper midground has slightly softer contrast and less pore detail.
+Background building falls into warm haze with reduced microcontrast.
+Tank remains heavy and full-scale, not miniature.
+```
+
+### Rules
+
+- foreground = highest texture fidelity
+- distant subjects = lower microcontrast, less skin detail, more haze
+- big machines must feel heavy through scale words: massive, full-scale, weighty, armored bulk
+- use atmospheric perspective for night haze, smoke, dust, humidity
+- do not make every plane equally sharp unless style explicitly demands it
+
+### Miniature-Effect Warning
+
+Toy-like images often come from:
+
+- shallow depth of field applied incorrectly across huge depth range
+- too much crisp detail on distant small figures
+- no haze or contrast falloff
+- clean edges with no atmospheric integration
+
+---
+
+## Occlusion & Edge Integration
+
+When one subject overlaps another, say it.
+
+### Examples
+
+```text
+Her raised arm partially overlaps the turret.
+The soldier is framed by the open hatch rim.
+The tank barrel passes behind her gesture line.
+```
+
+This helps kill cutout edges and independent-object rendering.
+
+---
+
+## Prompt Injection Template
+
+Add a compact spatial paragraph like this in difficult shots:
+
+```text
+Spatial blocking: foreground left [subject], [distance], [frame position]. Midground [anchor object]. Background [environment]. Eyeline: [subject A] looks [direction] toward [target], not camera; [subject B] looks back [direction]. Body orientation: [chin/torso/hand direction]. Shared lighting: [motivated source], [direction], [color], affecting all subjects consistently. Depth integration: foreground crisp, background softened by [haze/smoke/dust], full-scale perspective, no miniature effect.
+```
+
+---
+
+## Image Prompt Fix Strategy
+
+When a still image fails:
+
+1. simplify to one motivated light source
+2. add plane map and explicit distances
+3. add `not camera` to eyeline instruction
+4. add contact/weight cues
+5. add depth integration sentence
+
+Do not fix everything by adding more adjectives. Fix the relationship logic.
+
+---
+
+## Video Prompt Fix Strategy
+
+For video prompts, preserve the same spatial logic over time:
+
+- eyeline target stays stable unless the action changes it
+- body orientation changes gradually, not magically
+- light direction does not jump between frames
+- background remains stable relative to camera move
+- contact points stay believable throughout motion
+
+If motion breaks realism, reduce movement complexity before adding detail.
+
+---
+
+## Anti-Artifact Avoid Terms
+
+Use when relevant:
+
+```text
+Avoid: disconnected eyelines, looking into camera, pasted composite look, cutout edges, floating subject, mismatched light direction, toy-like scale, miniature effect, warped perspective, detached shadows, inconsistent atmospheric depth.
+```
+
+---
+
+## Professional Retake Table
+
+| Problem | Fix |
+|---------|-----|
+| Character looks at random place | add exact gaze target + `not camera` + head angle |
+| Person feels pasted into scene | add shared light source + bounce/rim logic + occlusion/contact cues |
+| Background soldier looks like toy | reduce distant detail, add haze, lower contrast, confirm full-scale perspective |
+| Vehicle and human feel mismatched | specify distance, overlap, and support/contact relationship |
+| Raised hand / gesture feels disconnected | state target, arm direction, wrist tension, shadow/bounce behavior |
+
+---
+
+## Final QA Checklist
+
+Before shipping a shot:
+
+- [ ] foreground / midground / background are explicit
+- [ ] gaze target is explicit
+- [ ] `not camera` is used when needed
+- [ ] torso / chin / hand orientation align with gaze
+- [ ] one motivated light source is named
+- [ ] distant planes lose contrast/detail appropriately
+- [ ] contact / pressure / support cues exist
+- [ ] avoid line covers composite / scale / gaze artifacts when relevant
+
+---
+
+> **Remember:** Realism comes from agreement. Eyes, body, light, depth, and contact all need to agree about the same world.

package/content/skills/visual-modes/SKILL.md

@@ -97,7 +97,7 @@ These artifacts identify AI-generated content. AVOID them absolutely:
 Include at end of EVERY image prompt:
 
 ```
-Avoid: blurry, low-res, noise, jpeg artifacts, motion blur, out of focus, distorted faces, bad anatomy, extra limbs/fingers, deformed hands, mismatched eyes, warped perspective, inconsistent lighting, banding, over-sharpening, plastic skin, waxy skin, airbrushed skin, beauty filter, porcelain doll look, symmetrical face, duplicate people, floating artifacts, on-screen text, captions/subtitles, watermark, logo, UI elements, cartoon/anime style, illustration style, CGI look, video game graphics, 3D render look, artificial lighting, synthetic appearance.
+Avoid: blurry, low-res, noise, jpeg artifacts, motion blur, out of focus, distorted faces, bad anatomy, extra limbs/fingers, deformed hands, mismatched eyes, warped perspective, inconsistent lighting, banding, over-sharpening, plastic skin, waxy skin, airbrushed skin, beauty filter, porcelain doll look, symmetrical face, duplicate people, floating artifacts, cutout edges, pasted composite look, toy-like scale, miniature effect, disconnected eyelines, on-screen text, captions/subtitles, watermark, logo, UI elements, cartoon/anime style, illustration style, CGI look, video game graphics, 3D render look, artificial lighting, synthetic appearance.
 ```
 
 ---
@@ -107,7 +107,7 @@ Avoid: blurry, low-res, noise, jpeg artifacts, motion blur, out of focus, distor
 Include at end of EVERY video prompt:
 
 ```
-Avoid: distorted faces, morphing, bad anatomy, extra limbs/fingers, blurry, flickering, frame drops, inconsistent lighting, unnatural motion, warping, rolling shutter artifacts, camera jitter, on-screen text, captions/subtitles, watermark, logo, cartoon/anime style, CGI motion, synthetic appearance, robotic movement, puppet-like animation, uncanny valley expressions.
+Avoid: distorted faces, morphing, bad anatomy, extra limbs/fingers, blurry, flickering, frame drops, inconsistent lighting, unnatural motion, warping, rolling shutter artifacts, camera jitter, cutout edges, pasted composite look, toy-like scale, miniature effect, disconnected eyelines, on-screen text, captions/subtitles, watermark, logo, cartoon/anime style, CGI motion, synthetic appearance, robotic movement, puppet-like animation, uncanny valley expressions.
 ```
 
 ---

package/content/workflows/generate.md

@@ -95,6 +95,9 @@ For EACH shot:
    - explicit lens/framing/camera movement
    - explicit lighting direction/intensity/atmosphere
    - explicit foreground/midground/background action details
+   - explicit eyeline target / body orientation when a subject looks at someone or something
+   - explicit shared light source / bounce logic when multiple subjects share frame
+   - explicit depth/scale integration when more than one plane is visible
 9. Generate coverage prompts (2-3 per main shot, min 70 words each).
 10. Add Turkish summary for shot and each coverage section.
 11. Apply model-specific generation gates (see below).
@@ -130,6 +133,7 @@ Before writing prompts, design the Start→End transition:
 - [ ] Duration matches transformation budget
 - [ ] Start/end frames verified for same visual universe
 - [ ] Dialogue uses `"quotation marks"` with tone markers (Kling inline format)
+- [ ] Eyelines, plane map, and shared-light logic stay consistent across start/end frames
 
 ### 4. Validation Pass (Mandatory Before Completion)
 

package/content/workflows/safety-check.md

@@ -44,9 +44,17 @@ Validate all prompts before delivery to ensure platform compliance.
 - chain breaks are explicitly declared when needed
 
 4. Quality checks
-- main image prompts >= 60 words
-- main video prompts >= 80 words
-- coverage prompts >= 60 words
+- `ILK/İLK FRAME` prompt >= 80 words
+- `SON FRAME` prompt >= 80 words
+- `VIDEO/VİDEO` prompt >= 120 words
+- each coverage prompt >= 70 words
+- lens/framing/camera movement details are explicit
+- lighting direction/intensity/atmosphere details are explicit
+- foreground/midground/background action details are explicit
+- gaze target is explicit when a character is looking at a subject/object
+- shared motivated light source is explicit when multiple subjects share frame
+- contact / weight / support cues exist when compositing realism is critical
+- depth / scale integration is explicit when multiple planes are visible
 
 5. Kling-only checks (when model is `kling-3.0`)
 - `Model Control` block exists in each SHOT file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milenyumai/film-kit",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Hollywood-standard cinematic prompt engineering toolkit with model profiles (Veo 3.1 / Kling 3.0). Auto-configures AI agents (Cursor, Claude Code, VS Code Copilot, Antigravity) with production-grade shot generation system.",
   "type": "module",
   "main": "./build/index.js",