@kolbo/mcp 1.79.0 → 1.79.2

package/package.json

@@ -1,65 +1,66 @@
-{
-  "name": "@kolbo/mcp",
-  "version": "1.79.0",
-  "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
-  "main": "src/index.js",
-  "bin": {
-    "kolbo-mcp": "./bin/kolbo-mcp.js"
-  },
-  "scripts": {
-    "start": "node src/index.js",
-    "smoke": "node scripts/smoke.js",
-    "check-skill-bundle": "node scripts/check-skill-bundle.js",
-    "check-parity": "node scripts/check-parity.js",
-    "prepublishOnly": "node scripts/smoke.js && node scripts/check-skill-bundle.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-model-catalog.js && node scripts/check-skill-tools.js && node scripts/check-submission-contract.js && node scripts/check-install.js",
-    "check-model-catalog": "node scripts/check-model-catalog.js",
-    "check-widget-fields": "node scripts/check-widget-fields.js",
-    "check-widget-render": "node scripts/check-widget-render.js",
-    "check-skill-tools": "node scripts/check-skill-tools.js",
-    "check-submission-contract": "node scripts/check-submission-contract.js",
-    "generate-chatgpt-submission": "node scripts/generate-chatgpt-submission.js",
-    "check-install": "node scripts/check-install.js"
-  },
-  "keywords": [
-    "kolbo",
-    "mcp",
-    "ai",
-    "image-generation",
-    "video-generation",
-    "music-generation",
-    "text-to-speech",
-    "claude-code",
-    "claude-desktop",
-    "model-context-protocol"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Zoharvan12/kolbo-mcp"
-  },
-  "homepage": "https://docs.kolbo.ai/developer-api/claude-code-skill",
-  "author": "Kolbo AI <support@kolbo.ai>",
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "src/",
-    "bin/",
-    "skill/",
-    "README.md"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/ext-apps": "^1.7.4",
-    "@modelcontextprotocol/sdk": "1.29.0",
-    "form-data": "^4.0.6",
-    "zod": "^3.25.0"
-  },
-  "overrides": {
-    "hono": "^4.12.12",
-    "@hono/node-server": "^1.19.13",
-    "path-to-regexp": "^8.4.2"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@kolbo/mcp",
+  "version": "1.79.2",
+  "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
+  "main": "src/index.js",
+  "bin": {
+    "kolbo-mcp": "./bin/kolbo-mcp.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "smoke": "node scripts/smoke.js",
+    "check-skill-bundle": "node scripts/check-skill-bundle.js",
+    "check-parity": "node scripts/check-parity.js",
+    "prepublishOnly": "node scripts/smoke.js && node scripts/check-skill-bundle.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-model-catalog.js && node scripts/check-skill-tools.js && node scripts/check-doctrine-parity.js && node scripts/check-submission-contract.js && node scripts/check-install.js",
+    "check-model-catalog": "node scripts/check-model-catalog.js",
+    "check-widget-fields": "node scripts/check-widget-fields.js",
+    "check-widget-render": "node scripts/check-widget-render.js",
+    "check-skill-tools": "node scripts/check-skill-tools.js",
+    "check-submission-contract": "node scripts/check-submission-contract.js",
+    "generate-chatgpt-submission": "node scripts/generate-chatgpt-submission.js",
+    "check-install": "node scripts/check-install.js",
+    "check-doctrine-parity": "node scripts/check-doctrine-parity.js"
+  },
+  "keywords": [
+    "kolbo",
+    "mcp",
+    "ai",
+    "image-generation",
+    "video-generation",
+    "music-generation",
+    "text-to-speech",
+    "claude-code",
+    "claude-desktop",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Zoharvan12/kolbo-mcp"
+  },
+  "homepage": "https://docs.kolbo.ai/developer-api/claude-code-skill",
+  "author": "Kolbo AI <support@kolbo.ai>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "skill/",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.4",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "form-data": "^4.0.6",
+    "zod": "^3.25.0"
+  },
+  "overrides": {
+    "hono": "^4.12.12",
+    "@hono/node-server": "^1.19.13",
+    "path-to-regexp": "^8.4.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skill/GENERATED.md

@@ -1,6 +1,6 @@
 # AUTO-GENERATED — do not edit
 
-This tree is mirrored from kolbo-code@b950100, the single source of truth.
+This tree is mirrored from kolbo-code@a0342e4, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 0.8.4
+version: 0.9.0
 name: kolbo
 description: |
   Generate, edit, analyze, and direct creative media through Kolbo AI: images,
@@ -57,6 +57,7 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 
 | If the user wants to… | Read first |
 |---|---|
+| Make a **film / ad / scene / episode / campaign / any video with multiple or recurring characters** — read BEFORE planning a single shot | `references/workflows/production-planning.md` |
 | Direct, develop, audit, or continue a **film / episode / connected scene / complex performance** with continuity, acting, dialogue, music, blocking, or physics | `references/workflows/filmmaking.md` |
 | Generate a **Seedance 2.5** video | `references/models/seedance25.md` + Locked Intro in `references/models/seedance.md`. For narrative/continuity also load `references/workflows/filmmaking.md` — but compile the prompt as Locked Intro, NOT the SCENE CONTEXT / OPTICS / ACTION pack |
 | Generate a **Seedance 2 / 2.0** video **or Elements** (`generate_elements`) | `references/models/seedance.md` — same Locked Intro. Elements is NOT a different prompt language |
@@ -70,6 +71,7 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 | Build a **dashboard / data viz / interactive widget / mini-game / UI mockup** | `references/models/visual-code.md` |
 | Generate with **any other model** (Flux, Kling, Sora, Hailuo, ElevenLabs, DeepDub, …) — also covers universal prompt-engineering basics | `references/models/prompt-copilot.md` |
 | Build a **UGC ad / TV spot / branded video / unboxing / product review / virtual try-on** | `references/workflows/marketing-studio.md` |
+| Write a **complex multi-element still**, an **edit that must not drift** (identity / product / scene lock), or a **reusable prompt template** | `references/workflows/prompt-structure.md` |
 | Make anything look **shot on a phone** — UGC, selfie, candid, "authentic", a product photo that must not look like an ad (image OR video) | `references/workflows/ugc-smartphone.md` |
 | Make a **YouTube / Shorts / Reels thumbnail** or video cover | `references/workflows/thumbnails.md` |
 | Compose a **DTC ad image** (brand kit + ad format + avatar + product + reference media) | `references/workflows/dtc-ads.md` |
@@ -94,14 +96,14 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `generate_image` | Single image from a text prompt. Supports Visual DNA, moodboards, image presets, reference images, web-search grounding. When a preset is requested, resolve it with `list_presets({ type: "image" })` and pass its exact id as `preset_id`. |
 | `generate_image_edit` | Edit/transform an existing image. Pass `source_images` + edit prompt. Image-editing presets are supported through `preset_id` from `list_presets({ type: "image_edit" })`. |
 | `generate_creative_director` | **2–8 related images or videos as one coherent set.** Use INSTEAD of multiple `generate_image` calls for any related multi-output. |
-| `generate_video` | Text-to-video. Does **not** support Visual DNA — use `generate_elements` for character-consistent video. |
+| `generate_video` | Text-to-video. Accepts `visual_dna_ids` and `sound_enabled`; `generate_elements` is still the primary reference-driven route for a DNA-anchored film. |
 | `generate_video_from_image` | Animate a still. Prompt describes motion, not subject. |
 | `generate_video_from_video` | Restyle/transform an existing video. Keeps original motion. |
 | `generate_elements` | Reference-driven video. **Primary route for DNA → video.** Prompt = Seedance Locked Intro (`Total` + `[GLOBAL LOOK]` / `[CAST]` / `[LOCATION]` + `SHOT N`). Every DNA in `visual_dna_ids` must also be `@Name` in that prompt. |
 | `generate_first_last_frame` | Keyframe interpolation between two frames. |
-| `generate_lipsync` | Lipsync audio to an image or video face. |
+| `generate_lipsync` | Lipsync an existing waveform onto a face. **Not the route for dialogue in a film you are generating** — write the line in the Seedance prompt instead. |
 | `generate_music` | Music generation (Suno + variants). |
-| `generate_speech` | TTS. Use `list_voices` to pick a voice. |
+| `generate_speech` | TTS for narration, voiceover and standalone audio. **NOT for scene dialogue** — Seedance 2/2.5 performs quoted lines itself. |
 | `generate_sound` | Sound effects. |
 | `generate_3d` | 3D models from text / single image / multi-view. Returns GLB/FBX/OBJ/USDZ. |
 | `separate_audio_stems` | Split a soundtrack into Dialogue / Music / Effects / without-dialogue (M&E). The route for removing or isolating speech, instrumental beds, and stems for dubbing. 5cr, inline. See `workflows/audio-stems.md`. |
@@ -154,12 +156,20 @@ first, so the model renders *different words than the ones the user wrote*.
   user never asked for, and their own wording never reached the model.
 - The default is `false` in every generation tool. Leave the argument out.
 
+## ⚠️ Assets Before Shots (HARD RULE)
+
+For any film / ad / scene / episode / campaign the order is **Map → Create → Confirm → Shoot**: inventory every character, location and prop the script needs, build each as a Visual DNA (sheet presets), get the user's explicit approval on the asset set, and only then generate video. A shot fired against an unapproved cast is waste, not a draft.
+
+Scene dialogue is **never** `generate_speech` or `generate_lipsync`. Seedance 2 / 2.5 performs quoted lines written into the shot beat itself — English only. Full flow: `references/workflows/production-planning.md`.
+
 ## ⚠️ Seedance / Elements prompt contract (HARD RULE)
 
 `generate_elements`, Seedance 2, and Seedance 2.5 share **one** compile shape — the Locked Intro in `references/models/seedance.md`:
 
 `Total: Xs / N shots / AR` → `[GLOBAL LOOK – LOCKED, APPLIES TO EVERY SHOT]` → `[CAST – IDENTICAL IN EVERY SHOT]` (each person is `@DNAName`) → `[LOCATION]` → `SHOT N — 0:00–0:02 — …`
 
+Write the beats at FULL DEPTH. The cap is 15,000 characters on Seedance 2.5 (10,000 on 2.0) — a 30s / 8+ shot compile should land around 4k–9k, and every beat carries its own camera move, a performance task for the speaker AND the listeners, prop/hand state, and the sound in that beat. A one-line shot beat is under-written; the structure alone is not the craft. Read `references/models/seedance25.md` before compiling.
+
 Do **not** default Elements to `SCENE CONTEXT` / `OPTICS` / `ACTION` / `ACTIVE REFERENCES` department packs (those live in filmmaking audit/contracts for other models). Do not load `seedance-2-prompting` SCENE CONTEXT as the Elements format.
 
 ## ⚠️ If the User Names a Tool, USE THAT TOOL (HARD RULE)

package/skill/VERSION

@@ -1 +1 @@
-0.8.4
+0.9.0

package/skill/references/filmmaking/routing.md

@@ -69,9 +69,11 @@ Keep identity, world, period, audio ownership, safety, and editorial objective f
 
 ## 4. Select the audio lane
 
+The generation family from section 2 must already be known — see section 6. A model that bakes audio in decides how the lane executes, and sometimes that it is not a separate lane at all.
+
 | Lane | Use when | Required truth |
 |---|---|---|
-| Dialogue | Actors speak exact lines | speaker, verbatim text, timing, voice identity, listener behavior, silence ownership |
+| Dialogue | Actors speak exact lines | speaker, verbatim text, timing, voice identity, listener behavior, silence ownership. **On Seedance 2 / 2.5 this lane executes IN-PROMPT** — quoted lines written into the shot beat, performed natively; never a TTS or lip-sync tool |
 | Exact-song lip-sync | A supplied waveform must own the mouth | source asset, performer ownership, exact lyrics/phonetics, breath seams, non-performer mouth behavior |
 | Native music performance | The model should create or perform a musical moment | musical structure, performers, vocal ownership, tempo/beat behavior, desired score/SFX relationship |
 | Ambience/SFX only | Music belongs in post or silence is dramatic | environment bed, timed effects, no-score instruction if model supports it |
@@ -93,9 +95,11 @@ Load a pack only when a relevant signal is present:
 
 ## 6. Select the adapter
 
-Read the target model adapter last so it can translate the creative plan into actual limits and syntax. Never let the adapter replace the story, performance, or production truth.
+Identify the target model as soon as the generation family in section 2 is fixed — **before** choosing the audio lane in section 4. A model that bakes audio in (Seedance 2 / 2.5) owns dialogue, ambience and score itself, so a lane chosen model-neutrally produces a plan the model cannot execute.
+
+Read the adapter's limits and syntax last, at compile time, so it translates the creative plan rather than replacing it. Never let the adapter replace the story, performance, or production truth.
 
-If the model is unspecified, ask only when the answer materially changes the deliverable. Otherwise produce a model-neutral shot card and state which adapter remains unresolved.
+If the model is unspecified, ask only when the answer materially changes the deliverable — whether the family bakes audio in is exactly that case. Otherwise produce a model-neutral shot card and state which adapter remains unresolved.
 
 ## 7. Select output depth
 

package/skill/references/models/gpt-image.md

@@ -23,6 +23,7 @@ Load this file when the user wants a **GPT Image 2 / gpt-image-2** image (OpenAI
 - **Photorealism trigger**: include the literal word **"photorealistic"** to engage the model's photorealistic mode. Supporting phrases: "real photograph", "taken on a real camera", "professional photography", "iPhone photo", "35mm film". Camera specs (lens mm, aperture) work for high-level look but are loosely interpreted — use for vibe, not physics.
 - **Composition**: specify framing/viewpoint (close-up, wide, top-down), perspective (eye-level, low-angle), lighting/mood (soft diffuse, golden hour, high-contrast). If layout matters, call out placement ("logo top-right", "subject centered, negative space on left").
 - **People, pose, action**: describe scale, body framing, gaze, object interactions ("full body visible, feet included", "looking down at the open book, not at the camera", "hands naturally gripping the handlebar").
+- **Complex scene, an edit that must not drift, or a reusable template**: use the block schema, the reference contract (`identity_lock` + an explicit `preserve` list) and named slots from `workflows/prompt-structure.md`.
 - **Constraints — what changes vs what stays**: state exclusions and invariants explicitly. For edits use **"change only X" + "keep everything else the same"**, and re-state the preserve list on every iteration to prevent drift. Common invariants: identity, geometry, layout, brand elements, camera angle, saturation, contrast, labels, surrounding objects. Always include "no watermark, no extra text, no logos/trademarks" unless the brief specifies otherwise.
 - **Text in images**: put literal text in **quotes** or **ALL CAPS**, specify typography (font style, size, color, placement). For tricky words / brand names, spell letter-by-letter. Recommend quality **high** when text is small, dense, or multi-font.
 - **Multi-image inputs**: reference each input by number with a short description ("Image 1: product photo… Image 2: style reference…") and describe the interaction ("apply Image 2's style to Image 1", "place the dog from Image 2 next to the woman in Image 1"). Use `@image1` / `@image2` tags — see `workflows/visual-dna.md`.

package/skill/references/models/nano-banana.md

@@ -72,6 +72,7 @@ Layer these onto any framework to lift good → breathtaking.
 - **Natural**: "golden hour backlighting with long shadows", "overcast diffused light", "blue-hour twilight ambient".
 
 ### Camera, lens, focus (hardware = visual DNA)
+- **Editing an upload?** Open with a reference contract — `identity_lock` plus a named `preserve` list — not "keep everything else the same". See `workflows/prompt-structure.md`.
 - **`iPhone` is a vibe word, not a look** — for a real phone-capture image (and for a product photo that must not read as an ad) read `workflows/ugc-smartphone.md` and write the optics/processing/light/imperfection stack.
 - **Hardware vibe**: `GoPro` for distorted action immersion · `Fujifilm` for authentic color science · `disposable camera` for raw nostalgic flash · `Hasselblad medium format` for editorial fashion · `iPhone` for everyday realism · `ARRI ALEXA` for cinematic.
 - **Lens / focus**: "low-angle shot, shallow depth of field f/1.8", "wide-angle for vast scale", "macro for intricate detail", "85mm portrait compression", "anamorphic 2.39:1 bokeh".

package/skill/references/models/seedance.md

@@ -109,8 +109,10 @@ These elevate rich cinematic / reference-anchored sequences. For a short, tight,
 
 ## Dialogue & expression
 
-- Dialogue goes in quotes and may be in ANY language (Hebrew included). For silent tension, deliver it as expression, not speech: `He does not speak. His expression clearly says: "…"`.
-- **Seedance PERFORMS quoted dialogue natively** — synced voices, lip movement, and room tone come out of the video model itself. Never route scene dialogue through TTS (`generate_speech`) or `generate_lipsync`; write each line in quotes inside its shot beat (`DANIEL says: "…"`) and generate once.
+- **Dialogue is PERFORMED by the model, never by a TTS tool.** Quoted lines in the prompt come back as synced speech with lip movement and room tone, together with the SFX you name in AUDIO. Scene dialogue therefore never routes through `generate_speech` or `generate_lipsync` — write the line in quotes inside its shot beat and let Seedance act it.
+- **Write dialogue in ENGLISH.** Seedance does not reliably perform other languages, and Hebrew in particular does not work — it comes back as accented gibberish or English-shaped mouth movement. Never offer a user "Hebrew dialogue directly". If the delivered film has to be Hebrew, the honest routes are: (a) keep the spoken lines English, or (b) stage the beat as expression + on-screen text, or (c) generate the scene clean and dub it afterwards as an explicit, separately-priced pass. Say which one you are doing.
+- `list_models` reports `sound_generation_type: "none"` for Seedance 2 / 2.5 because there is no in-app sound toggle (`sound_baked_in: true`). That field does NOT mean the model is silent. Do not read it as a reason to add TTS.
+- For silent tension, deliver it as expression, not speech: `He does not speak. His expression clearly says: "…"`.
 
 ## Content tone
 

package/skill/references/models/seedance25.md

@@ -9,13 +9,17 @@ Load this file when the user wants a **Seedance 2.5** video (they said "2.5" / "
 
 **Kolbo MCP routing:** `generate_video` or `generate_elements` (refs / Visual DNA / first-last). Run `list_models({ type: "text_to_video" })` and pick the Seedance 2.5 variant by name.
 
-**Audio:** Seedance 2.5 still emits real synced audio. `list_models` may show `sound_generation_type: none` because there is no in-app toggle (`sound_baked_in: true`). Do not tell the user the model is silent. Quoted dialogue in the prompt is PERFORMED — synced voices, lip movement, room tone — so scene dialogue never goes through `generate_speech` or `generate_lipsync`; write the lines in quotes inside their shot beats.
+**Audio:** Seedance 2.5 emits real synced audio. `list_models` shows `sound_generation_type: none` only because there is no in-app toggle (`sound_baked_in: true`) — it does NOT mean the model is silent, and it is never a reason to reach for TTS. Quoted dialogue is PERFORMED (synced voices, lip movement, room tone) alongside the SFX named in AUDIO, so scene dialogue never goes through `generate_speech` or `generate_lipsync`; write the lines in quotes inside their shot beats.
+
+**Dialogue language: English.** Other languages are not reliably performed, and Hebrew does not work — it returns accented gibberish or English-shaped mouth movement. Never offer a user "Hebrew dialogue directly". See `models/seedance.md` for the three honest alternatives.
+
+**Draft at 480p.** Resolution is a credit MULTIPLIER, not a flat rate. Relative to 720p: 480p ×0.44, 1080p ×2.25. A 30s pass costs ~540cr at 480p against ~1230cr at 720p and ~2770cr at 1080p. Block the film at 480p, get the user's sign-off on staging, performance and timing, then re-run only the approved cut at delivery resolution.
 
 ## What's NEW in 2.5 (verified — never hedge)
 
 - **Duration 4–30 seconds**, whole seconds. 30s IS supported.
 - **Up to 30 shots/cuts in ONE generation.** Deliver exactly N if N ≤ 30.
-- **Prompt cap 30,000 characters** for the entire prompt as one string.
+- **Prompt cap 15,000 characters** for the entire prompt as one string (`max_prompt_length` in the catalog; Seedance 2.0 is 10,000). Verify with `list_models` rather than trusting this number — it was documented as 30,000 for months, which is double the real limit.
 - **Up to 50 reference medias / Visual DNA mentions** (`@Name`, `@ImageN`, `#Moodboard`). Every referenced asset must be tagged in the prompt text.
 - **Multimodal refs:** images + video clips + audio can all anchor one generation.
 
@@ -37,11 +41,13 @@ UGC / phone vertical (full craft: `workflows/ugc-smartphone.md`): NEVER write "c
 
 ## Prompt length
 
-Simple ≤15s ~120–280 words. Locked-intro cinematic 15s typically 400–900 words. Full 30s / 15+ shots typically 700–1200 words / ~4k–9k chars. Hard cap 30,000. Never split into part 1 / part 2.
+Simple ≤15s ~120–280 words. Locked-intro cinematic 15s typically 400–900 words. Full 30s / 15+ shots typically 700–1200 words / ~4k–9k chars. Hard cap 15,000 characters. Never split into part 1 / part 2.
+
+A one-line shot beat is UNDER-WRITTEN. At 30s / 8+ shots you have ~15k characters to work with and a thin prompt wastes them: every beat carries its own camera move, performance task for BOTH the speaker and the listeners, prop/hand state, and the sound in that beat. If a 30s compile lands under ~4k characters, it is too thin — go back and direct it.
 
 ## Feature-Block (optional, UNDER the Locked Intro)
 
-Reach for extra department passes only when the user wants "their best possible 30 seconds" AND the 30k budget still has room after GLOBAL LOOK / CAST / LOCATION. Never replace the Locked Intro.
+Reach for extra department passes only when the user wants "their best possible 30 seconds" AND the 15k budget still has room after GLOBAL LOOK / CAST / LOCATION. Never replace the Locked Intro.
 
 May add above GLOBAL LOOK: **EMOTIONAL INTENT** + **SIGNATURE MOMENT**.
 May add under the shot list: CAMERA timecode pass, SOUND timestamps, PHYSICS contract, EDITING/CONTINUITY, DIRECTORIAL NOTES.

package/skill/references/workflows/filmmaking.md

@@ -19,6 +19,7 @@ Read [routing.md](references/filmmaking/routing.md) for the full decision rules.
 
 | Request | Mode | Read |
 |---|---|---|
+| Any multi-asset or multi-scene production — film, ad, episode, campaign, recurring or multiple characters | Production planning | `references/workflows/production-planning.md` **first** — map assets, build the DNAs, confirm the set, only then shoot |
 | Premise, outline, screenplay, weak scene | Development | `scene-engine.md`, then `workflows.md` |
 | Character, location, prop, state, voice, or production preparation | Pre-production | `asset-preproduction.md`, `production-bible.md`; add `acting-direction.md` for recurring characters |
 | One generation-ready video prompt | Direction | `prompt-contracts.md`, selected craft references, then the model adapter |

package/skill/references/workflows/production-planning.md

@@ -0,0 +1,104 @@
+<!-- PARITY: the asset-first rule and the model defaults here are mirrored in
+     kolbo-api/src/config/systemPrompt.js and the help widget's skillRouter.
+     Change all three together. -->
+
+# Production Planning — map the assets before you shoot
+
+Any request for a film, ad, scene, episode, campaign or "video with characters"
+starts here, **before** a single video credit is spent. Most users do not know
+this flow exists; they ask for a film and expect a film. Walk them through it
+rather than jumping to a prompt.
+
+Skip it only for a genuine one-off: a single clip, no recurring subject, nothing
+that has to match anything else.
+
+## The order is not negotiable
+
+1. **Map** every element the script needs.
+2. **Create** each one as an approved asset (Visual DNA).
+3. **Confirm** the asset set with the user.
+4. **Only then** compile shots and generate video.
+
+Generating video before step 3 is how a production ends up with a different face
+in every shot and a re-shoot bill. A shot generated against an unapproved cast is
+not a draft, it is waste.
+
+## 1. Map
+
+Read the script and produce an explicit inventory. Name every element, even the
+ones that feel obvious — the ones that get skipped are the ones that drift:
+
+| Kind | DNA type | What it owns |
+|---|---|---|
+| Every speaking or recurring person | `character` | identity, wardrobe, physical state, performance |
+| Every location, including reverse angles | `environment` | geography, landmarks, materials, light logic |
+| Every hero prop, product, vehicle | `product` | identity, scale, material, damage/version state |
+| The film's overall look, when it must hold across shots | `style` | visual register only |
+
+State the inventory back to the user as a list with counts and cost before
+creating anything. A 4-character, 2-location, 1-prop film is 7 assets, not "some
+characters".
+
+Separate **states** from **identities**: clean vs bloodied, day vs night, intact
+vs broken are their own assets. Do not expect one DNA to carry both.
+
+## 2. Create
+
+Generate the reference imagery, then register it as a Visual DNA.
+
+**Model defaults for the asset pass** (this is an image job — never a video model):
+
+| Asset | Model | Why |
+|---|---|---|
+| Cinematic environments; invented / original characters | **`mirage-film-2`** (MIRAGE FILM 2, 3cr) | cinematic look at a third the cost — the default for anything being invented from scratch |
+| Assets needing reference fidelity, legible text, or editing | **`nano-banana-2`** (10cr) or **`gpt-image-2`** (12cr) | stronger reference adherence and text; GPT Image 2 when the asset carries readable words |
+
+Read the matching prompt reference before writing an asset prompt:
+`references/models/nano-banana.md` for Nano Banana, `references/models/gpt-image.md`
+for GPT Image 2. There is no Mirage reference file — prompt it as a plain cinematic
+still.
+
+Use the sheet presets rather than free-form portraits — `generate_character_sheet`
+with `sheet_type`:
+
+- `character` — front/back/face turnaround, the default for a speaking role
+- `character_bible` — denser model sheet (turnaround + faces + wardrobe + swatches) for a lead who appears across many shots
+- `character_headless` — wardrobe/body when clothing changes but the face must not
+- `environment` — location angles plus one signature detail
+- `product` — angles plus material and construction close-ups
+- `style` — one look applied across six varied subjects
+
+The sheet is the single strongest consistency booster. It costs credits, so offer
+it and generate on a yes.
+
+Then `create_visual_dna` with the sheet as the reference and the matching
+`dna_type`. Name each DNA in the exact form it will be tagged with later.
+
+## 3. Confirm
+
+Show the user the asset set and get an explicit approval before shooting. This is
+the cheapest possible place to change their mind.
+
+## 4. Shoot
+
+Only now compile shots. Defaults:
+
+- **`generate_elements` with Seedance 2.5** (`seedance-2-5`) for the film itself —
+  up to 30s and 30 shots in ONE generation, up to 20 Visual DNAs, dialogue and SFX
+  baked in. `generate_video` also accepts `visual_dna_ids` now; Elements remains
+  the primary reference-driven route.
+- **Seedance 2.0** (`seedance-2`, cheaper, 4–15s, 9 DNAs) when the piece is short
+  and the cast is small. `seedance-2-fast` / `seedance-2-mini` for cheap blocking.
+- Every DNA in `visual_dna_ids` must also appear as `@ExactName` in the prompt.
+- Dialogue in quotes inside its shot beat — English only, never TTS or lipsync.
+  See `models/seedance25.md`.
+- **First pass at 480p.** Resolution is a credit multiplier (480p ×0.44 vs 720p,
+  1080p ×2.25). Block, approve, then re-run the approved cut at delivery
+  resolution.
+
+## What this replaces
+
+Do not plan a film as "N separate image-to-video clips plus TTS plus lipsync".
+That shape is a legacy of models that could not hold a cast or speak. It costs
+more, drifts between shots, and produces dead-eyed dubbed performance. One
+multi-shot Seedance generation against approved DNAs is the current answer.