@kolbo/mcp 1.78.0 → 1.79.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.78.0",
+  "version": "1.79.1",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

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.

package/src/tools/color_palettes.js

@@ -31,7 +31,12 @@ function registerColorPaletteTools(server, client, options = {}) {
       const palettes = result.color_palettes || [];
       const text = JSON.stringify({ color_palettes: palettes, pagination: result.pagination }, null, 2);
 
-      if (ui()) {
+      // Ship structuredContent UNCONDITIONALLY. Gating on ui() left every host that
+      // renders widgets without advertising MCP Apps (Kolbo Code) with text-only rows
+      // that carry no thumbnail field at all — and its BY_TOOL map still force-mounts
+      // the media grid on them, so the card rendered one broken-file glyph per cell.
+      // media.js and listResult() have always done it this way; these five lagged.
+      {
         return uiResult(UI.mediaGrid, text, {
           widget: 'media-grid',
           title: 'Color DNA Palettes',

package/src/tools/generate.js

@@ -541,7 +541,7 @@ function registerGenerateTools(server, client, options = {}) {
   // retired textToVideoGeneration path and was stale.
   server.tool(
     'generate_video',
-    'Generate a video from a text prompt using Kolbo AI. For SEVERAL different videos, pass all their prompts in `prompts` in ONE call (one combined widget) — never a series of separate calls. For animating an existing still image into motion, use generate_video_from_image instead. For a coordinated multi-scene video campaign, use generate_creative_director with workflow_type="video". Supports reference images (for style/composition guidance) and Visual DNA for character consistency. ROUTE BEFORE CALLING: when reference images anchor IDENTITY (specific characters, a specific product, a location that must match) — especially 2+ of them — that is generate_elements, not this tool; reference_images here are loose style/composition hints. Decide the right tool FIRST: a mis-routed call still starts a PAID generation, and switching tools afterwards without cancel_generation leaves the user paying for both. Returns the final video URL when complete.',
+    'Generate a video from a text prompt using Kolbo AI. For SEVERAL different videos, pass all their prompts in `prompts` in ONE call (one combined widget) — never a series of separate calls. For animating an existing still image into motion, use generate_video_from_image instead. For a coordinated multi-scene video campaign, use generate_creative_director with workflow_type="video". Supports reference images (for style/composition guidance) and Visual DNA for character consistency. Seedance 2/2.5 PERFORM quoted dialogue natively (synced voice, lip movement, room tone) — do not route scene dialogue to generate_speech or generate_lipsync; write it in ENGLISH (other languages, Hebrew included, do not perform reliably). Resolution is a credit MULTIPLIER (vs 720p: 480p x0.44, 1080p x2.25, 4k x4.95), so draft at 480p and re-run only the approved cut at delivery resolution. ROUTE BEFORE CALLING: when reference images anchor IDENTITY (specific characters, a specific product, a location that must match) — especially 2+ of them — that is generate_elements, not this tool; reference_images here are loose style/composition hints. Decide the right tool FIRST: a mis-routed call still starts a PAID generation, and switching tools afterwards without cancel_generation leaves the user paying for both. Returns the final video URL when complete.',
     {
       prompt: z.string().optional().describe('Text description of the video to generate. Required unless `prompts` is provided.'),
       prompts: promptsField('videos'),
@@ -621,7 +621,7 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_video_from_image ─────────────────────────────
   server.tool(
     'generate_video_from_image',
-    'Animate an existing still image into a video using Kolbo AI. The image comes from `image_url`; `prompt` describes the motion (not the subject — the subject is already in the image). For generating a video from scratch, use generate_video. ANIMATING SEVERAL SHOTS OF THE SAME SEQUENCE? Pass them ALL in `items` in ONE call (one combined widget) — never a series of separate calls, which buries the chat under one widget per clip. Across calls (a sequence longer than the batch cap), make the first call without `session_id`, take the `session_id` from its result, and pass that same `session_id` on every following call — otherwise each clip becomes its own session and the user gets a stack of near-identical single-clip sessions in the Kolbo sidebar. Returns the final video URL(s) when complete.',
+    'Animate an existing still image into a video using Kolbo AI. The image comes from `image_url`; `prompt` describes the motion (not the subject — the subject is already in the image). For generating a video from scratch, use generate_video. FOR A MULTI-SHOT FILM with recurring characters or locations, prefer ONE generate_elements call carrying the whole DNA-anchored sequence over a series of separate image-to-video clips. ANIMATING SEVERAL SHOTS OF THE SAME SEQUENCE? Pass them ALL in `items` in ONE call (one combined widget) — never a series of separate calls, which buries the chat under one widget per clip. Across calls (a sequence longer than the batch cap), make the first call without `session_id`, take the `session_id` from its result, and pass that same `session_id` on every following call — otherwise each clip becomes its own session and the user gets a stack of near-identical single-clip sessions in the Kolbo sidebar. Returns the final video URL(s) when complete.',
     {
       image_url: z.string().optional().describe('URL of the source image to animate. Required unless `items` is provided.'),
       prompt: z.string().optional().describe('Text description of the desired MOTION (e.g., "camera slowly pans right while the character walks forward"). Required unless `items` is provided.'),
@@ -772,7 +772,7 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_speech ───────────────────────────────────────
   server.tool(
     'generate_speech',
-    'Convert text to speech using Kolbo AI. Default provider is ElevenLabs. To pick a specific voice by language/gender, call list_voices first and pass the returned voice_id (or a voice display name — both work). Every voice belongs to a provider (ElevenLabs, DeepDub, MiniMax, Google/Gemini, OpenAI, Zonos) and each provider exposes its own expressive/style controls below — the engine ignores any control that does not apply to the chosen voice\'s provider, so it is safe to pass only what you need. Returns the final audio URL when complete.',
+    'Convert text to speech using Kolbo AI. SCOPE: narration, voiceover, and standalone audio (ads, explainers, audiobooks, announcements). This is NOT the route for character dialogue in a film you are generating with Seedance 2/2.5 — those models PERFORM quoted dialogue natively (synced voices, lip movement, room tone), so sending scene dialogue here just adds a second, unsynced voice track. Default provider is ElevenLabs. To pick a specific voice by language/gender, call list_voices first and pass the returned voice_id (or a voice display name — both work). Every voice belongs to a provider (ElevenLabs, DeepDub, MiniMax, Google/Gemini, OpenAI, Zonos) and each provider exposes its own expressive/style controls below — the engine ignores any control that does not apply to the chosen voice\'s provider, so it is safe to pass only what you need. Returns the final audio URL when complete.',
     {
       text: z.string().describe('The text to convert to speech'),
       voice: z.string().optional().describe('Voice ID or display name — MUST come from a `list_voices` result, never constructed. Google/Gemini ids in particular are not validated provider-side: an id that is not in the catalog is silently mapped to another voice (or a default one) and the audio comes back in a voice nobody asked for. Do not pattern-match a locale onto an id you saw for another language. Default: "Rachel"'),
@@ -1185,7 +1185,7 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_elements ─────────────────────────────────────
   server.tool(
     'generate_elements',
-    'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". PROMPT CONTRACT (Seedance / Elements): Locked Intro only — Total line, then [GLOBAL LOOK] / [CAST] / [LOCATION] / SHOT N. Do NOT write SCENE CONTEXT / OPTICS / ACTION department packs. Every Visual DNA in visual_dna_ids MUST also appear in the prompt as @ExactDNAName (e.g. "@Zohar walks…") — never "Zohar\'s" or "the man on the left" as a substitute. IMPORTANT: different models accept different numbers of inputs — call list_models type="elements" and read elements_max_images / elements_max_videos / elements_max_audio on the chosen model before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
+    'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". PRIMARY ROUTE FOR A DNA-ANCHORED MULTI-SHOT FILM: one call can carry the whole sequence — seedance-2-5 takes 4-30s, up to 30 shots and 20 Visual DNAs in a SINGLE generation (seedance-2: 4-15s, 9 DNAs) — instead of a stack of separate clips. DIALOGUE IS PERFORMED NATIVELY: quoted dialogue in the prompt comes back as synced voices with lip movement, room tone and the SFX named in the AUDIO block — never route scene dialogue to generate_speech or generate_lipsync. Write dialogue in ENGLISH; other languages (Hebrew included) do not perform reliably. COST: resolution is a MULTIPLIER, not a flat fee (vs 720p: 480p x0.44, 1080p x2.25, 4k x4.95) — run blocking/draft passes at 480p and re-run only the approved cut at delivery resolution. PROMPT CONTRACT (Seedance / Elements): Locked Intro only — Total line, then [GLOBAL LOOK] / [CAST] / [LOCATION] / SHOT N. Do NOT write SCENE CONTEXT / OPTICS / ACTION department packs. Every Visual DNA in visual_dna_ids MUST also appear in the prompt as @ExactDNAName (e.g. "@Zohar walks…") — never "Zohar\'s" or "the man on the left" as a substitute. IMPORTANT: different models accept different numbers of inputs — call list_models type="elements" and read elements_max_images / elements_max_videos / elements_max_audio on the chosen model before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
     {
       prompt: z.string().describe('Locked Intro prompt (Seedance/Elements): Total line, [GLOBAL LOOK], [CAST] with @ExactDNAName for every visual_dna_ids entry, [LOCATION], then SHOT N. Not SCENE CONTEXT/OPTICS/ACTION packs. Never substitute "the left man" or "Zohar\'s" for @Name.'),
       model: z.string().optional().describe('Model identifier. If the user already named a family (Grok / Kling / Veo / Seedance / …), pass THAT family — never default to Seedance because Elements often uses it. Use list_models type="elements" for exact ids and elements_max_* caps. Do NOT omit (omitting = Smart Select).'),
@@ -1462,7 +1462,7 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_lipsync ──────────────────────────────────────
   server.tool(
     'generate_lipsync',
-    'Lipsync an audio track to a source image or video. Both `source` (image or video) and `audio` can be provided as URLs or as absolute local file paths. Pass a text_prompt only if the model supports it (some lipsync models do character performance from a prompt). **Validate before submitting: for `lipsync-video` sources, the input video duration must fall within `min_video_duration`-`max_video_duration` from list_models; audio duration must fall within `min_audio_duration`-`max_audio_duration` (and if `audio_max_follows_video_duration: true`, audio is also capped at the video duration); audio format must be in `supported_audio_formats` when specified.** Returns a lipsynced video URL.',
+    'Lipsync an audio track to a source image or video. SCOPE: it syncs an EXISTING audio waveform to a face in footage you already have (dubbing, translation, fixing a delivered take). It is NOT how you get characters to speak in a film you are generating — Seedance 2/2.5 perform quoted dialogue natively with synced lip movement, so a scene generated there needs no lipsync pass. Both `source` (image or video) and `audio` can be provided as URLs or as absolute local file paths. Pass a text_prompt only if the model supports it (some lipsync models do character performance from a prompt). **Validate before submitting: for `lipsync-video` sources, the input video duration must fall within `min_video_duration`-`max_video_duration` from list_models; audio duration must fall within `min_audio_duration`-`max_audio_duration` (and if `audio_max_follows_video_duration: true`, audio is also capped at the video duration); audio format must be in `supported_audio_formats` when specified.** Returns a lipsynced video URL.',
     {
       source: z.string().describe('URL or absolute local path to the source image or video (the face to animate). For lipsync-video: duration must fall within `min_video_duration`-`max_video_duration` from list_models.'),
       audio: z.string().describe('URL or absolute local path to the audio track (the voice to sync to). Duration must fall within `min_audio_duration`-`max_audio_duration` from list_models; format must be in `supported_audio_formats` (when set).'),

package/src/tools/presets.js

@@ -33,7 +33,12 @@ function registerPresetTools(server, client, options = {}) {
         note: 'Filter with `type` (image | image_edit | video | music | text_to_video) to see a focused set. Pass the chosen exact id as `preset_id` on the next generation call.',
       });
 
-      if (ui()) {
+      // Ship structuredContent UNCONDITIONALLY. Gating on ui() left every host that
+      // renders widgets without advertising MCP Apps (Kolbo Code) with text-only rows
+      // that carry no thumbnail field at all — and its BY_TOOL map still force-mounts
+      // the media grid on them, so the card rendered one broken-file glyph per cell.
+      // media.js and listResult() have always done it this way; these five lagged.
+      {
         return uiResult(UI.mediaGrid, text, {
           widget: 'media-grid',
           title: 'Presets' + (type ? ' — ' + type : ''),

package/src/tools/stock_library.js

@@ -78,7 +78,12 @@ function registerStockLibraryTools(server, client, options = {}) {
         : '';
       const text = `${head}\n\n${shownAssets.map(assetLine).join('\n\n')}${moreHint}\n\nUse [source:sourceId] with get_stock_asset for full variants, or import_stock_asset to copy it into the media library.`;
 
-      if (ui()) {
+      // Ship structuredContent UNCONDITIONALLY. Gating on ui() left every host that
+      // renders widgets without advertising MCP Apps (Kolbo Code) with text-only rows
+      // that carry no thumbnail field at all — and its BY_TOOL map still force-mounts
+      // the media grid on them, so the card rendered one broken-file glyph per cell.
+      // media.js and listResult() have always done it this way; these five lagged.
+      {
         const items = assets.slice(0, 24).map((a) => {
           const mt = widgetMediaType(a.mediaType);
           return {
@@ -160,7 +165,12 @@ function registerStockLibraryTools(server, client, options = {}) {
         total: result.count,
       });
 
-      if (ui()) {
+      // Ship structuredContent UNCONDITIONALLY. Gating on ui() left every host that
+      // renders widgets without advertising MCP Apps (Kolbo Code) with text-only rows
+      // that carry no thumbnail field at all — and its BY_TOOL map still force-mounts
+      // the media grid on them, so the card rendered one broken-file glyph per cell.
+      // media.js and listResult() have always done it this way; these five lagged.
+      {
         const collections = result.collections || [];
         const items = collections.slice(0, 24).map((c) => ({
           id: c.id,

package/src/tools/visual_dna.js

@@ -207,7 +207,7 @@ function registerVisualDnaTools(server, client, options = {}) {
   // ─── generate_character_sheet ──────────────────────────────
   server.tool(
     'generate_character_sheet',
-    'Generate a reference sheet for a Visual DNA from 1+ reference image URLs — the same step the in-app Visual DNA wizard offers, for EVERY DNA type via `sheet_type`: character = multi-angle turnaround, product = angles + branding/material/construction close-ups, environment = location angles + one signature detail, style = a style board (the same look applied to six varied subjects). The sheet is the single strongest consistency booster for a DNA, and it always preserves the reference\'s original art style (2D stays 2D, photo stays photo). CHARGES CREDITS, so when the user is about to create a DNA, OFFER this first ("want me to generate a reference sheet for stronger consistency? it costs a few credits") and only run it on a yes. Returns `character_sheet_url` — pass it as `character_sheet_url` to `create_visual_dna` with the matching `dna_type`.',
+    'STANDARD FIRST STEP OF THE ASSET PASS for any film/ad/scene: inventory the characters, locations and props the script needs, generate a sheet for each, create its Visual DNA from that sheet, confirm the whole set with the user, and only THEN generate video. Sheets for cinematic environments and invented characters run well on `mirage-film-2` (3cr); use `nano-banana-2` (10cr) or `gpt-image-2` (12cr) when reference fidelity or legible text matters. Generate a reference sheet for a Visual DNA from 1+ reference image URLs — the same step the in-app Visual DNA wizard offers, for EVERY DNA type via `sheet_type`: character = multi-angle turnaround, product = angles + branding/material/construction close-ups, environment = location angles + one signature detail, style = a style board (the same look applied to six varied subjects). The sheet is the single strongest consistency booster for a DNA, and it always preserves the reference\'s original art style (2D stays 2D, photo stays photo). CHARGES CREDITS, so when the user is about to create a DNA, OFFER this first ("want me to generate a reference sheet for stronger consistency? it costs a few credits") and only run it on a yes. Returns `character_sheet_url` — pass it as `character_sheet_url` to `create_visual_dna` with the matching `dna_type`.',
     {
       image_urls: z.array(z.string()).min(1).describe('Reference image URLs of the subject (for characters: front/side/varied angles work best). Use generated-image URLs or upload_media output.'),
       sheet_type: z.enum(['character', 'character_headless', 'character_bible', 'product', 'environment', 'style']).optional().describe('Sheet layout. character = front/back/face turnaround. character_headless = wardrobe/body refs with a headless front panel (use when clothing must change without fighting the face sheet). character_bible = denser production model-sheet (turnaround + faces + wardrobe + color swatches). product / environment / style = matching DNA types. Defaults to character.')

package/src/tools/voices.js

@@ -80,7 +80,12 @@ function registerVoiceTools(server, client, options = {}) {
       const range = `${start + 1}–${start + shownVoices.length}`;
       const text = `Available voices (showing ${range} of ${voices.length}, page ${pageNum}/${pageCount}):\n\n${lines.join('\n\n')}${narrowHint}\n\nUse the "voice_id" value in generate_speech calls.`;
 
-      if (ui()) {
+      // Ship structuredContent UNCONDITIONALLY. Gating on ui() left every host that
+      // renders widgets without advertising MCP Apps (Kolbo Code) with text-only rows
+      // that carry no thumbnail field at all — and its BY_TOOL map still force-mounts
+      // the media grid on them, so the card rendered one broken-file glyph per cell.
+      // media.js and listResult() have always done it this way; these five lagged.
+      {
         return uiResult(UI.mediaGrid, text, {
           widget: 'media-grid',
           title: 'Voices',