@milenyumai/film-kit 1.0.4 → 1.2.0

package/README.md

@@ -1,20 +1,63 @@
 # Film-Kit: Hollywood-Standard Cinematic Prompt Engineering
 
-**Film-Kit**, Google Veo 3.1 ve Flow için optimize edilmiş, profesyonel "Prompt Engineering" ajanlarını (Claude Code, Cursor) projenize kuran bir araç setidir.
+**Film-Kit**, model-seçilebilir sinematik prompt mühendisliği ajanlarını (Claude Code, Cursor, VS Code Copilot, Antigravity) projenize kuran bir araç setidir.
 
 İ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.
 
+## 🧱 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`)
+
+Yani kaynak kod için tek "source of truth" vardır: `film-kit` reposu.
+
+---
+
+## 🎯 Model Desteği
+
+| 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 |
+
+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.
+
+Kling preset:
+- Varsayılan: `ultra-realism`
+- Varsayılan CFG hedefi: `0.45`
+
+### v1.2.0 — Yeni Özellikler
+
+**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
+
+**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
@@ -24,34 +67,50 @@ Claude Code içinde:
 ```
 Tek bir ajan ("Prompt Engineer") senaryoyu okur, analiz eder ve shotları sırayla üretir.
 
+Antigravity içinde:
+- Skill: `.agent/skills/shotforge-generate/SKILL.md`
+- Çalışma şekli: tek ajanlı, yüksek kontrol, shot-by-shot üretim
+
 **Ö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
 
 ---
 
 ## 🚀 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
 
 ### 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-multi
+/generate
 ```
 **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.
+
 **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ı (Min 60 kelime + coverage) paralel üretir.
+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.
@@ -60,15 +119,42 @@ Claude Code içinde:
 
 ---
 
+## ⚙️ Config Dosyaları
+
+Core (`shotforge-agent.config.json`):
+
+```json
+{
+  "outputDir": "./outputs",
+  "scenarioHint": "scenario.md",
+  "model": "kling-3.0",
+  "klingPreset": "ultra-realism"
+}
+```
+
+Multi (`film-kit-multi.config.json`):
+
+```json
+{
+  "outputDir": "./outputs",
+  "scenarioHint": "scenario.md",
+  "model": "kling-3.0",
+  "klingPreset": "ultra-realism",
+  "maxTeammates": 5,
+  "batchSize": 4
+}
+```
+
+---
+
 ## ⚡ Komut Referansı (Slash Commands)
 
 | Komut | Paket | İşlev |
 |-------|-------|-------|
-| `/generate` | Core | Tek ajanla sıralı üretim başlatır. |
-| `/generate-multi` | Multi | Multi-ajan takımıyla paralel üretim başlatır. |
+| `/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` | Multi | Başarısız batch'leri veya kalite kontrol takılanları onarır. |
+| `/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. |
 
 ---
@@ -79,6 +165,7 @@ Claude Code içinde:
 |---------|-----------------|----------------------|
 | **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ı |
@@ -87,9 +174,9 @@ Claude Code içinde:
 ---
 
 ## 🛠 Gereksinimler
-- **Node.js:** v18+
+- **Node.js:** v20+
 - **Claude Code:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (Sadece Multi için)
-- **Editör:** VS Code, Cursor veya Terminal
+- **Editör/Platform:** VS Code, Cursor, Claude Code veya Antigravity
 
 ## 📄 Lisans
 MIT

package/build/cli.js

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

package/build/index.d.ts

@@ -1,2 +1,2 @@
 export { configureAgents } from "./lib/configure.js";
-export type { AgentConfigOptions, ConfigureResult, SupportedPlatform } from "./lib/types.js";
+export type { AgentConfigOptions, ConfigureResult, KlingPreset, SupportedModel, SupportedPlatform } from "./lib/types.js";

package/build/lib/configure.js

@@ -64,8 +64,14 @@ function renderContentTemplate(content, vars) {
     return content
         .replaceAll("$OUTPUT_DIR", vars.outputDir)
         .replaceAll("$SCENARIO_HINT", vars.scenarioHint)
+        .replaceAll("$MODEL_DISPLAY", vars.modelDisplayName)
+        .replaceAll("$MODEL", vars.model)
+        .replaceAll("$KLING_PRESET", vars.klingPreset)
         .replaceAll("$ARGUMENTS", "");
 }
+function getModelDisplayName(model) {
+    return model === "kling-3.0" ? "Kling 3.0" : "Google Flow + Veo 3.1";
+}
 export async function configureAgents(options = {}) {
     const rootDir = options.rootDir ?? process.cwd();
     const packageConfigPath = join(rootDir, "shotforge-agent.config.json");
@@ -74,6 +80,8 @@ export async function configureAgents(options = {}) {
     const outputDir = options.outputDir ?? fromFile?.outputDir;
     const scenarioHint = options.scenarioHint ?? fromFile?.scenarioHint;
     const platforms = options.platforms ?? fromFile?.platforms;
+    const model = options.model ?? fromFile?.model;
+    const klingPreset = options.klingPreset ?? fromFile?.klingPreset;
     const overwrite = options.overwrite ?? fromFile?.overwrite;
     const includeAgentsMd = options.includeAgentsMd ?? fromFile?.includeAgentsMd;
     const copyContent = options.copyContent ?? fromFile?.copyContent;
@@ -83,6 +91,10 @@ export async function configureAgents(options = {}) {
         merged.scenarioHint = scenarioHint;
     if (platforms !== undefined)
         merged.platforms = platforms;
+    if (model !== undefined)
+        merged.model = model;
+    if (klingPreset !== undefined)
+        merged.klingPreset = klingPreset;
     if (overwrite !== undefined)
         merged.overwrite = overwrite;
     if (includeAgentsMd !== undefined)
@@ -94,7 +106,10 @@ export async function configureAgents(options = {}) {
     const contentResult = resolved.copyContent
         ? await copyContentFiles(resolved.rootDir, resolved.overwrite, {
             outputDir: resolved.outputDir,
-            scenarioHint: resolved.scenarioHint
+            scenarioHint: resolved.scenarioHint,
+            model: resolved.model,
+            klingPreset: resolved.klingPreset,
+            modelDisplayName: getModelDisplayName(resolved.model)
         })
         : { written: [], skipped: [] };
     // 2. Generate platform-specific config files
@@ -104,7 +119,8 @@ export async function configureAgents(options = {}) {
     for (const [relativePath, content] of Object.entries(files)) {
         const absolutePath = join(resolved.rootDir, relativePath);
         const fileExists = await exists(absolutePath);
-        if (fileExists && !resolved.overwrite) {
+        const isRuntimeModelFile = relativePath === ".agent/model-profile.md";
+        if (fileExists && !isRuntimeModelFile && !resolved.overwrite) {
             skipped.push(relativePath);
             continue;
         }
@@ -114,6 +130,7 @@ export async function configureAgents(options = {}) {
     return {
         rootDir: resolved.rootDir,
         written,
-        skipped
+        skipped,
+        warnings: resolved.warnings
     };
 }

package/build/lib/defaults.js

@@ -1,12 +1,23 @@
 const ALL_PLATFORMS = ["cursor", "claude", "copilot", "antigravity"];
+const DEFAULT_MODEL = "veo31";
+const DEFAULT_KLING_PRESET = "ultra-realism";
 export function resolveOptions(input) {
+    const warnings = [];
+    const model = input.model ?? DEFAULT_MODEL;
+    const klingPreset = input.klingPreset ?? DEFAULT_KLING_PRESET;
+    if (!input.model) {
+        warnings.push("Model not specified. Falling back to veo31. In the next major release, --model will be required.");
+    }
     return {
         rootDir: input.rootDir ?? process.cwd(),
         outputDir: input.outputDir ?? "./outputs",
         scenarioHint: input.scenarioHint ?? "scenario.md",
         platforms: (input.platforms && input.platforms.length > 0 ? input.platforms : ALL_PLATFORMS).slice(),
+        model,
+        klingPreset,
         overwrite: input.overwrite ?? false,
         includeAgentsMd: input.includeAgentsMd ?? true,
-        copyContent: input.copyContent ?? true
+        copyContent: input.copyContent ?? true,
+        warnings
     };
 }