@kolbo/mcp 1.84.2 → 1.85.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.84.2",
+  "version": "1.85.0",
   "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@24a7092, the single source of truth.
+This tree is mirrored from kolbo-code@261fab2, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -9,7 +9,8 @@ description: |
   filmmaking as well as individual media:
   scripts, production bibles, recurring characters and locations, acting,
   dialogue, music performance, blocking, physics, multi-shot continuity,
-  connected scenes, prompt audits, and feature-length production planning.
+  connected scenes, prompt audits, feature-length production planning, and
+  direct Blender scene building through the connected Kolbo Blender plugin.
 
   NOT for: video editing / FFmpeg (use video-production), motion graphics
   (use remotion-best-practices), code editing, or general chat.
@@ -68,6 +69,7 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 |---|---|
 | 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` |
+| Build, inspect, animate, light, render, or edit a **Blender scene through Kolbo Blender MCP** | `references/workflows/blender-mcp.md` |
 | Generate a **Seedance 2.5** video | `skill` `elements-prompting` + `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 / WAN / MiniMax H3 / Gemini / Elements** video (`generate_elements` or Visual DNA) | `skill` `elements-prompting` + `references/models/seedance.md` — same Locked Intro. Elements is NOT a different prompt language |
 | Generate a **GPT Image 2** image | `references/models/gpt-image.md` |
@@ -86,6 +88,7 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 | Compose a **DTC ad image** (brand kit + ad format + avatar + product + reference media) | `references/workflows/dtc-ads.md` |
 | Generate **brand product imagery** (studio shot, lifestyle, Pinterest pin, hero banner, carousel, ad pack, virtual try-on, conceptual, restyle) | `references/workflows/product-photoshoot.md` |
 | Generate **marketplace listing cards** (Amazon main + secondary + A+ content) | `references/workflows/marketplace-cards.md` |
+| Apply a **preset** — a named look, sheet, thumbnail, grading, camera move, Seedance shot recipe, music style — or decide whether one fits what the user just asked for | `references/workflows/presets.md` |
 | Use **Visual DNA** / character consistency / `@name` syntax | `references/workflows/visual-dna.md` |
 | Use **Color DNA** / brand palette grading | `references/workflows/color-dna.md` |
 | Start or continue a **multi-step production** (storyboard → scenes → final cut) | `references/workflows/production-log.md` |
@@ -128,7 +131,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `list_models` / `list_voices` / `check_credits` / `show_plans` / `get_generation_status` / `cancel_generation` / `get_session_usage` | Discovery + status. `list_models` with no args returns the recommended shortlist out of ~428 — pass `type` for a full category with per-model caps. `cancel_generation` stops an in-flight job and refunds what it can: use it when the user changes their mind mid-generation instead of letting it run. `show_plans` renders the balance + upgrade card for pricing/plan/upgrade questions. |
 | `upload_media` / `create_upload_ticket` / `list_media` / `get_media` / `get_media_stats` / `favorite_media` / `unfavorite_media` / `delete_media` / `restore_media` / `permanently_delete_media` / `move_media` / `bulk_*_media` / `*_media_folder` | Media library — see `workflows/media-library.md`. Getting a LOCAL file in depends on where the server runs: `upload_media` with a path only works on a local (stdio) install; over a remote connector use `create_upload_ticket` and POST the file yourself. |
 | `create_visual_dna` / `update_visual_dna` / `generate_character_sheet` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` / `*_visual_dna_folder` (5 folder tools) | Visual DNA (+ character sheet, character folders) — see `workflows/visual-dna.md`. Edit with `update_visual_dna`; never delete+recreate. |
-| `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays + sheet presets — see **Preset contract** in Core Workflow. Never omit `preset_id` after claiming a preset was used. |
+| `list_moodboards` / `get_moodboard` / `list_presets` / `list_cinematic_presets` | Style overlays + presets. `list_presets` spans FOUR distinct catalogs (`image`, `image_edit`, `video`, `music`; `text_to_video` is an alias for `video`, `shorts` is empty) — the `video` one holds 200+ Seedance shot recipes. `list_cinematic_presets` is a separate tool feeding the `cinematic` arg, never `preset_id`. Full doctrine + intent→catalog map: `references/workflows/presets.md`. Never omit `preset_id` after claiming a preset was used. |
 | `list_color_palettes` / `analyze_color_palette` / `create_color_palette` / `update_color_palette` / `delete_color_palette` / `activate_color_palette` / `deactivate_color_palette` | **Color DNA — sticky + account-wide; at most one palette active at a time**, and while active it strict-grades **every** image and video generation automatically. Per-generation opt-out: `skip_color_palette: true`. Details: `workflows/color-dna.md`. |
 | `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Custom chat agents — reusable named personas for `chat_send_message`. The agent's `description` IS the system instruction. Resolve a name the user mentions ("use my SEO agent") to an id with `list_agents`, then pass `agent_id`. Global/preset agents are read-only; only the user's own can be updated or deleted. |
 | `search_stock_media` / `get_stock_sources` / `get_stock_categories` / `get_stock_collections` / `get_stock_asset` / `analyze_script_for_stock` / `import_stock_asset` | Stock library (free, no credits) — EXISTING photos / videos / 3D / SFX / music. For stock **music** use `search_stock_media` with `mediaType: "music"` (semantic vibe query, e.g. "uplifting corporate background") → `get_stock_asset` for downloads. The older `*_music_library` tools are deprecated adapters over this — prefer the stock tools, except for the licensed-catalog tools in the next row. |
@@ -234,7 +237,7 @@ Dependencies accumulate: narrative Elements work requires **Kolbo + filmmaking +
 
 `N connected cinematic shots, Xs total, AR, Multishot ON` → `Total: Xs / N shots / AR` → `[GLOBAL LOOK – LOCKED, APPLIES TO EVERY SHOT]` → `[CAST – IDENTICAL IN EVERY SHOT]` (each person is `@DNAName`) → `[LOCATION]` → LOCATION MAP / CONTINUITY / PHYSICS → `SHOT N — 0:00–0:02 — …` (ranges sum to Xs) → closing `Total: Xs / N shots / AR`. Pass MCP `duration: X` matching that Total. Omitting Total / Multishot is a failed compile — same contract as the Kolbo help widget.
 
-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.
+Write the beats at FULL DEPTH. The cap is 30,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). `elements-prompting` is the craft skill (formerly `seedance-2-prompting`); Locked Intro is the compile shape.
 
@@ -267,11 +270,14 @@ A user-named tool — in any language — overrides every other rule. Recognized
 
 ## Core Workflow
 
-**Preset contract:**
-- Custom instructions live on the **preset**. Prefer `generate_image` + `preset_id` (not `generate_character_sheet`) for Character Sheet / Headless / Bible / location / product sheets.
-- Always `list_presets({ type: "image", search: "<name>" })` — `headless`, `bible`, `character sheet`. That is a silent id lookup. Do **not** omit `search` (that dumps the whole catalog). Reuse the id after the first hit.
+**Preset contract** (full doctrine — catalogs, intent→search map, cinematic dimensions: `references/workflows/presets.md`):
+- Custom instructions live on the **preset**, and it is almost always better than the paragraph you would improvise. Prefer `generate_image` + `preset_id` (not `generate_character_sheet`) for Character Sheet / Headless / Bible / location / product sheets.
+- **Presets are not image-only.** `type: "video"` holds 200+ Seedance 2 shot recipes (chase, orbital, drift, showcase, VFX, storyboard) and feeds `generate_video` + `generate_elements`; `image_edit` and `music` have their own catalogs. `image` and `image_edit` ids are NOT interchangeable.
+- **Search on the user's own noun when their request matches a catalog** — they rarely say "preset". `list_presets({ type, search: "<their word>" })` matches name + description + category together.
+- Always pass `search`. That is a silent id lookup. Do **not** omit it (that dumps a 632k-char catalog). Reuse the id after the first hit.
 - Browse (no search) only when the user asked to see presets.
-- Pass the exact returned `id` as `preset_id`. Never invent an id.
+- Pass the exact returned `id` as `preset_id`. Never invent an id. Never claim a preset was used without passing it.
+- Cinematic presets are a DIFFERENT tool (`list_cinematic_presets` → the `cinematic` arg, one id per dimension, omit for Auto) — never `preset_id`.
 
 1. **Check credits** ONCE per conversation (Step 0). Skip if already checked.
 2. **Load the matching skill** (HARD RULE above) before the first paid call in the turn.

package/skill/references/models/seedance.md

@@ -13,6 +13,8 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 ## Universal Rules (apply to EVERY Seedance / Elements prompt)
 
+- **NO MUSIC BY DEFAULT (HARD):** Unless the user explicitly asks for music, every final Seedance prompt—including every Elements/reference-driven prompt—must explicitly say `No music. No musical score.` Keep requested dialogue, synchronized production sound, ambience, and SFX; "no music" does not mean "no audio." If the user explicitly requests music, describe that music instead and omit the no-music lock. Never invent background music from cinematic tone alone.
+- **NO FAMOUS NAMES OR IP IN PROMPTS (HARD):** Never put celebrity/public-figure names, real directors or artists, copyrighted character/franchise/IP names, famous campaign names or slogans, or famous studio/company names into a final Seedance or Elements prompt. Translate user-supplied references into concrete visual traits—medium, shape language, palette, lighting, texture, camera behavior, pacing, and mood—without repeating the famous name. Preserve exact user-owned Visual DNA and asset tags.
 - **Visual DNA names are immutable anchors:** when `visual_dna_ids` is passed, every DNA MUST appear in the prompt as the exact literal `@DNA_name` (CAST + every shot it is in). Never "Zohar's", "the left man", "the man on the LEFT", a nickname, or a Visual DNA anchors paragraph without `@tags`.
 - **Rewrites never thin out or rename anchors.** "`@X anchors Odysseus`" is NOT a reference line, and `Odysseus` must never replace `@X` later. Every referenced asset keeps its exact literal tag plus a full role line on every rewrite. Re-use the exact DNA tag in every shot it participates in. A compile that dropped `@gal_suit` / `@yonatan` / `#Board` is a failed turn.
 - **DURATION + SHOT STRUCTURE (HARD — same as help widget):** every text-to-video / Elements prompt MUST open AND close with total duration, shot count, and aspect. Omit only for video-edit tasks (source duration is locked). Required first lines:
@@ -97,7 +99,7 @@ FORBIDDEN: omitting Total / Multishot; "same character throughout" as the only l
 - Always supply: **clear location, clear power mismatch, defined escalation arc**.
 - Describe choreography beat by beat — Seedance executes what you write.
 - Single continuous shot 15s works for two-fighter scenes; describe camera moves between beats (`crests rooftop edge`, `full 360 orbit`, `pulls back to wide`, `descends with them`).
-- Use `Guy Ritchie speed-ramping with Snyder impact slow-motion` as the style anchor when comedic/stylized.
+- Use `playful speed-ramping with heavy impact slow-motion` as the style anchor when comedic/stylized.
 
 ### 5. Animation (3D stylized)
 - Break the 15s into **timed segments** (`0–3s`, `3–6s`, `6–9s`, `9–12s`, `12–15s`) and describe each explicitly.
@@ -196,7 +198,7 @@ Use only the discrete steps. Not "23°" — use 18° or 29°.
 - **Emotion through muscle movement**, not labels. ❌ "she looks sad" → ✅ "her eyes drop to the table, jaw tightens, she swallows once before answering."
 - **WB in Kelvin.** 3200K / 4000K / 5600K / 8500K. Pick ONE for the scene's mood.
 - **Color as material + light + role**, never a flat list. ❌ "she wears red, he wears blue" → ✅ "crimson silk scarf catching the cold tungsten spill from the corridor".
-- **No equipment names**, no director references, no "shot on ARRI / Sigma 85mm / Roger Deakins".
+- **No equipment names and no famous creative references**; describe the observable lens, lighting, movement, texture, and grade instead.
 
 ### Cuts and timing
 
@@ -270,4 +272,4 @@ Seedance 2 lives in the **Video** category. Route the prompt card by the INPUTS:
 
 ## Seedance + Visual DNA / References
 
-When a character must stay consistent, pair Seedance with Visual DNA via `generate_elements` (NOT `generate_video` — text-to-video silently drops `visual_dna_ids`). `@DNA_name` tagging rules: see `workflows/visual-dna.md`. For grid/storyboard inputs, the source frame is `@image1`.
+When a character must stay consistent, pair Seedance with Visual DNA via `generate_elements` (NOT `generate_video` — text-to-video silently drops `visual_dna_ids`). `@DNA_name` tagging rules: see `workflows/visual-dna.md`. For grid/storyboard inputs, the source frame is `@image1`.

package/skill/references/models/seedance25.md

@@ -19,9 +19,11 @@ Load this file when the user wants a **Seedance 2.5** video (they said "2.5" / "
 
 - **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 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.
+- **Prompt cap 30,000 characters** for the entire prompt as one string (`max_prompt_length` in the catalog; Seedance 2.0 is 10,000). Raised from 15,000 on 2026-08-30 after the whole provider chain was verified live to serve it. Verify with `list_models` rather than trusting this number — it has moved before.
 - **Large reference / Visual DNA capacity** (`@Name`, `@ImageN`, `#Moodboard`) — read the exact caps from `max_visual_dna` / `elements_max_images` in `list_models`. Every referenced asset must be tagged in the prompt text. A rewrite that drops or renames a tag ( `@doron_fauda_1` → `DORON` / `the hero` ) is a failed turn — put the exact tag back.
 - **Multimodal refs:** images + video clips + audio can all anchor one generation.
+- **NO MUSIC BY DEFAULT (HARD):** Unless the user explicitly asks for music, every final Seedance 2.5 prompt—including every Elements/reference-driven prompt—must explicitly say `No music. No musical score.` Preserve requested dialogue, synchronized production sound, ambience, and SFX; no music does not mean "no audio." If music is explicitly requested, describe it and omit the no-music lock.
+- **NO FAMOUS NAMES OR IP IN PROMPTS (HARD):** Never put celebrity/public-figure names, real directors or artists, copyrighted character/franchise/IP names, famous campaign names or slogans, or famous studio/company names into a final Seedance 2.5 or Elements prompt. Translate user-supplied references into concrete visual traits without repeating the famous name; preserve exact user-owned Visual DNA and asset tags.
 
 ## Universal Rules (HARD — same as help widget OUTPUT CONTRACT)
 
@@ -65,7 +67,7 @@ FORBIDDEN: "same character throughout" as the only lock; one fence per shot; cla
 
 ## 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 15,000 characters. 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 30,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.
 

package/skill/references/workflows/blender-mcp.md

@@ -0,0 +1,127 @@
+# Blender MCP Scene Craft
+
+Read this reference whenever the user wants an agent to inspect, build, block,
+animate, light, render, or modify a live Blender scene through the Kolbo Blender
+plugin. This is Blender work, not AI video generation: do not ask for a model,
+project, aspect ratio, or credit confirmation unless the request also includes a
+paid Kolbo media generation.
+
+## Connection and execution boundary
+
+- Discover the user's connected Blender sessions first. If there is more than
+  one, identify the intended file/session from the returned name and scene
+  summary rather than guessing.
+- Read the scene before editing it. Start with a compact summary, then inspect
+  only the relevant objects, collections, cameras, materials, and timeline.
+- Prefer validated structured scene operations. Use Blender Python only when the
+  requested result cannot be expressed structurally; Python has full machine
+  authority and requires explicit approval unless trusted mode is active.
+- Ordinary reversible construction and animation can execute directly. Deletion,
+  file open/overwrite, arbitrary paths or URLs, add-on installation, and Python
+  remain approval-gated.
+- Keep edits in one undoable batch where the tool supports it. Never save,
+  overwrite, open another file, or render an entire animation unless requested.
+
+## Scene construction rules
+
+- Preserve existing work unless the user explicitly asks to replace it. Put a
+  new build in a clearly named collection and use stable descriptive names.
+- Respect the scene unit system. Blender defaults commonly represent meters, but
+  inspect the actual unit settings before creating dimensioned objects.
+- Build recognizable assembled objects, not symbolic blocks. A chair needs a
+  seat, back, and visible supports or legs; a table needs a top and believable
+  supports; doors, lamps, shelves, vehicles, and props need the parts that make
+  their silhouette and function readable.
+- Objects and datablocks are separate. Check whether mesh or material data is
+  shared before editing it; make it single-user when only one instance should
+  change.
+- Prefer non-destructive modifiers for adjustable geometry. Apply destructive
+  mesh edits only when the result needs to be final or the user asks for them.
+- When raw Blender operators are required, set Object/Edit mode, active object,
+  and selection explicitly. Operators can silently fail or affect the wrong
+  object when context is inherited from the viewport.
+- Capture object references immediately after creation. Blender may suffix names
+  on collision, so do not assume a requested name was accepted unchanged.
+
+## Shots, cuts, and camera motion
+
+A request for multiple shots means a real timeline sequence, not several unused
+cameras:
+
+1. Set a deliberate frame range from the scene FPS and requested duration.
+2. Create one camera per hard-cut shot unless the user explicitly wants one
+   continuous take.
+3. Bind each shot camera to a timeline camera marker on the exact first frame of
+   that shot.
+4. Make the opening camera active and verify every requested cut by scrubbing the
+   boundary frames.
+
+Never interpolate one camera through a hard cut. A cut is the marker switching
+from one camera to another; animation belongs inside each shot.
+
+For camera movement inside a shot:
+
+- Keyframe both location and rotation at the first and last movement frames.
+- Use `LINEAR` interpolation by default for a constant-speed dolly, truck, crane,
+  orbit, push-in, or pull-out. Blender's automatic Bezier handles can ease or
+  overshoot unexpectedly and make continuous motion accelerate near keyframes.
+- Use `BEZIER` only when the brief explicitly calls for easing, a soft settle, or
+  an authored speed ramp. Inspect the curve for overshoot.
+- Use `CONSTANT` only for intentional holds or stepped animation, never to fake a
+  camera cut.
+- Keep a lock-off truly static. Do not add redundant drifting keyframes.
+- Keep the camera aimed at the intended subject throughout the move. Verify the
+  midpoint as well as the endpoints; two acceptable endpoints can still produce
+  a bad path through geometry.
+- Respect the camera's rotation mode. Structured operations use Euler radians;
+  raw Python should inspect the existing mode before choosing Euler or quaternion
+  keyframes.
+- For a dolly zoom, animate lens and camera distance together. Do not call a
+  location-only push-in a dolly zoom.
+
+## Blocking and animation quality
+
+- Establish readable contact and weight: feet meet the floor, chairs meet the
+  ground, tableware sits on the tabletop, hands meet held props, and objects do
+  not visibly interpenetrate unless intentional.
+- Keyframe after setting the transform for that frame. Keyframe every channel
+  needed to preserve the pose; missing rotation keys commonly cause unwanted
+  interpolation.
+- Do not add animation merely because the scene has a timeline. Animate only the
+  requested subjects and cameras.
+- For repeated motion, prefer a clean reusable cycle or duplication of verified
+  keys over noisy frame-by-frame keys.
+- In armature work, confirm the target bones are not constraint-driven before
+  keyframing them. Constraints can override apparently valid animation.
+
+## Materials, lighting, and presentation
+
+- Give hero surfaces deliberate materials with plausible roughness and metallic
+  values. Reuse shared materials for related parts instead of creating a material
+  per primitive.
+- Light for form and subject separation. A practical starting rig is a motivated
+  key, softer fill, and optional rim or practical light; adapt it to the requested
+  mood rather than mechanically adding three lights.
+- Check render visibility separately from viewport visibility when an object
+  appears missing.
+- Set an appropriate camera lens and composition. Avoid placing a camera without
+  checking framing through a viewport capture.
+
+## Verify before reporting completion
+
+After applying edits:
+
+1. Re-read the scene and confirm the expected object, collection, camera, marker,
+   frame-range, and animation counts.
+2. Capture the viewport or a low-cost preview from the active camera.
+3. For animation, inspect the first frame, every cut boundary, one midpoint per
+   moving shot, and the final frame. Confirm interpolation is the intended type.
+4. Correct concrete failures before reporting success. Do not say a scene is
+   animated merely because keyframes exist.
+5. Report what actually changed: named collection, object count, shot cameras,
+   cut frames, animated channels, and any approval still waiting.
+
+For complex Python work, return concise structured results from Blender rather
+than dumping console output. Update the dependency graph before reading computed
+transforms or modifier results, and inspect progressively instead of returning an
+entire large scene.

package/skill/references/workflows/presets.md

@@ -0,0 +1,137 @@
+# Presets — Kolbo's stored instruction blocks
+
+A preset is a long, hand-tuned instruction block stored in Kolbo's catalog. Passing
+`preset_id` prepends it to the user's prompt at generation time. **The craft lives on
+the preset** — a three-panel character sheet, a Seedance shot-sequence structure, a
+grading recipe — and it is always better than the paragraph you would improvise.
+
+Until now the skill only ever taught `type: "image"` for character sheets. That left the
+largest catalog in the product — **263 video presets, over 200 of them Seedance 2 shot
+recipes** — invisible to every agent. If the user's request looks like something in a
+catalog below, search it before you write the prompt yourself.
+
+## The catalogs
+
+`list_presets({ type, search })`. Sizes measured 2026-08-31; they drift, so **never
+memorise ids or names — always resolve live.**
+
+| `type` | Size | Categories (the search vocabulary) | Passed to |
+|---|---|---|---|
+| `image` | ~146 | thumbnails, text, style, layout, personas, grading, camera | `generate_image` |
+| `image_edit` | ~103 | style, camera control, grading, layout, enhancement | `generate_image_edit` |
+| `video` | ~263 | **seedance 2 (200+)**, camera, storyboard, character, vfx | `generate_video`, `generate_elements` |
+| `music` | ~54 | *(flat — no categories; search name/description)* | `generate_music` |
+
+Two more `type` values exist and are traps:
+
+- **`text_to_video` is an alias for `video`** — the same collection since consolidation,
+  returned with a different `type` label. Use `video`. Asking for both double-counts.
+- **`shorts` is empty** (0 rows in production). Shorts Creator is built but not in
+  service. Do not offer it.
+
+**`image` and `image_edit` are separate collections and their ids are NOT
+interchangeable.** An `image` id on `generate_image_edit` fails. Resolve against the
+catalog for the tool you are about to call.
+
+**No preset on `generate_video_from_image`.** Image-to-video takes `visual_dna_ids` but
+not `preset_id`. If a user wants a video preset look, route through `generate_video` or
+`generate_elements`.
+
+## Reading the user's intent
+
+This is the part that matters. The user rarely says "use a preset" — they describe an
+outcome that a preset already encodes. Search when the request matches a row here:
+
+| The user asks for… | Catalog | Search terms that hit |
+|---|---|---|
+| A character/location/product reference sheet, turnaround, model sheet | `image` | `character sheet`, `headless`, `bible`, `location`, `product` |
+| A YouTube / Shorts / Reels thumbnail, a video cover | `image` | `thumbnail` — and read `workflows/thumbnails.md` |
+| Text *in* the image — a headline, poster copy, a title card | `image` | `text`, `title`, `poster` |
+| A named look: anime, noir, claymation, 35mm, cyberpunk | `image` | `style`, or the look itself |
+| A colour treatment: teal-orange, bleach bypass, film stock | `image` / `image_edit` | `grading` |
+| A specific framing: overhead, macro, wide establishing | `image` / `image_edit` | `camera` |
+| A person archetype: influencer, CEO, athlete, elderly | `image` | `personas` |
+| A grid, split-screen, collage, comparison, panel layout | `image` | `layout` |
+| Upscale / restore / clean up / sharpen an existing image | `image_edit` | `enhancement` |
+| Any Seedance 2 / 2.5 shot — chase, duel, drift, reveal, showcase | `video` | describe the ACTION: `chase`, `orbital`, `drift`, `duel`, `showcase` |
+| A camera move: dolly, crane, whip pan, bullet time | `video` | `camera` |
+| A storyboard or multi-shot beat sheet | `video` | `storyboard` |
+| VFX: explosions, particles, morphs, energy | `video` | `vfx` |
+| A music genre, mood, or instrumentation | `music` | the genre or mood word |
+
+Search on the **noun the user used**, not a category name — the tool matches against
+name, description and category together, so `"drift"` finds *Impossible Continuous
+Drift* without you knowing which category it lives in.
+
+## Discovery contract
+
+- **Always pass `search`.** The full catalog measured 632,919 characters; dumping it
+  burns the context window and returns nothing you can act on. A named lookup returns a
+  handful of rows.
+- Browse (`search` omitted) **only when the user asked to see what's available.** That
+  renders a picker widget — it is for the human, not for you.
+- The response carries `total` (catalog size) and `omitted_from_this_page`. A large
+  `omitted` on a lookup means your search was too broad — narrow it, don't paginate.
+- **Reuse the id.** Once resolved in a conversation, it stays valid; do not re-search
+  for every generation in a batch.
+- **Never invent, guess, or reconstruct an id from memory.** Ids are opaque ObjectIds.
+- Do not filter results yourself by `category` casing — the API lowercases what Mongo
+  stores capitalised (`Layout` → `layout`). Match on meaning, not string equality.
+
+## Applying one
+
+- Pass the **exact returned `id`** as `preset_id`. One preset per generation — there is
+  no array.
+- **Never claim a preset was used without passing `preset_id`.** Saying "I applied the
+  Headless Character Sheet preset" while omitting the field is a fabricated result.
+- The preset is **prepended**, not substituted: still write a real prompt describing the
+  subject. The preset supplies the treatment, you supply the content. A preset with an
+  empty prompt produces the preset's stock example.
+- **Prefer `generate_image` + `preset_id` over `generate_character_sheet`** for any
+  sheet. The custom instructions live on the preset; the dedicated tool has less craft
+  in it.
+- Video preset descriptions reference `@image1`, `@image2` for their subjects — when a
+  preset says that, supply reference images in that order.
+
+## Preset vs Visual DNA vs moodboard vs Color DNA
+
+They stack, and they answer different questions. Do not substitute one for another:
+
+- **Preset** — *how it is rendered.* Treatment, structure, camera, layout.
+- **Visual DNA** (`visual_dna_ids` + `@Name` in the prompt) — *who or what is in it.*
+  Identity lock. See `workflows/visual-dna.md`.
+- **Moodboard** (`moodboard_id` + `#Name`) — *the reference vibe*, derived from images.
+- **Color DNA** — *the grade*, account-wide and automatic while active. See
+  `workflows/color-dna.md`.
+
+A preset carrying its own grading language can fight an active Color DNA. If the user
+picked both and the output drifts, that is the collision — say so and offer
+`skip_color_palette: true` rather than silently dropping the preset.
+
+## Cinematic presets are a different tool
+
+`list_cinematic_presets` — ~136 presets across dimensions (today: camera, lens,
+focal_length, aperture, angle, shot_type, color_palette, lighting; data-driven, always
+fetch). These are **not** `list_presets` rows and do not go in `preset_id`.
+
+- Pass chosen ids via the `cinematic` argument of `generate_image` /
+  `generate_image_edit`, **at most one id per dimension**.
+- **"Auto" is the absence of a selection** — omit the dimension, or the whole
+  `cinematic` object. Do not hunt for an "auto" preset.
+- Call with no args for a compact index, then pass `dimension` for full descriptions of
+  just the one you are choosing from.
+- **Only call this when the user wants a deliberate photographic look.** For an ordinary
+  generation, don't. "Make it cinematic" as a vague adjective is a prompt-quality
+  request, not a request for this tool.
+
+## When NOT to reach for a preset
+
+- The user gave a **specific, complete creative direction of their own.** A preset
+  prepends 200+ words that will compete with theirs. Their words win.
+- They named a **preset explicitly** — resolve that one, do not substitute a "better" match.
+- The request is a **plain edit** ("remove the background", "make it 4K"). Those are
+  `edit_image` mechanics, not presets.
+- You are **mid-batch on an approved look.** Changing preset between shots in one
+  sequence breaks continuity — that is the whole point of a locked global look.
+- You could not find a good match. **Say nothing and write a good prompt.** Announcing
+  that you searched for presets is noise; silently applying a poor match is worse.

package/skill/references/workflows/thumbnails.md

@@ -184,6 +184,21 @@ by the centre-square-crop test below. State this explicitly in the prompt ("gene
 margin on both sides, nothing touches the left/right edge") rather than fixing it after
 generation.
 
+**Multi-element layout recipe that shipped (Aug 2026, nano-banana-2):** when a comp
+carries 4+ graphic elements (headline, badge, app tile, still cards, brand chip), three
+prompt clauses turned a cluttered mess into an approved final:
+- **Glassmorphism containers** — put every element in its own "frosted translucent
+  glass container, soft blur, subtle white border, delicate shadow". Unifies the pile
+  into one designed system; solid stickers read as clutter.
+- **STRICT NON-OVERLAP RULE** stated as its own sentence — "clear margin between every
+  element; nothing touches the face or hair" — models honour it remarkably well.
+- **LIKENESS PRIORITY preamble** — face fidelity *drifts as element count grows*. With
+  4+ elements, open the prompt with "preserve his EXACT face, identical to the Visual
+  DNA identity, do not drift the facial features" or the subject becomes a stranger.
+- **Pin each mark to its container** — with two logos in one comp the model WILL swap
+  them; write "the tile shows ONLY the [X] mark; NEVER put [Y] on this tile; [Y]
+  appears ONLY in the bottom chip". Verify every logo placement on delivery.
+
 ## Variation ladder
 
 Vary the **concept**, never the words: bold dynamic · clean minimal · vibrant saturated ·

package/src/index.js

@@ -77,6 +77,7 @@ const { registerVoiceTools } = require('./tools/voices');
 const { registerMusicLibraryTools } = require('./tools/music_library');
 const { registerStockLibraryTools } = require('./tools/stock_library');
 const { registerAudioStemTools } = require('./tools/audio_stems');
+const { registerAnalyzeTools } = require('./tools/analyze');
 const { registerBlenderTools } = require('./tools/blender');
 const { registerApps, attachToolWidgetMeta } = require('./apps');
 const { attachToolAnnotations } = require('./toolAnnotations');
@@ -170,6 +171,7 @@ function createServer(opts = {}) {
   registerVisualDnaTools(server, client, toolOptions);
   registerMoodboardTools(server, client, toolOptions);
   registerColorPaletteTools(server, client, toolOptions);
+  registerAnalyzeTools(server, client, toolOptions);
   registerMediaTools(server, client, toolOptions);
   registerPresetTools(server, client, toolOptions);
   registerArtifactTools(server, client, toolOptions);

package/src/toolAnnotations.js

@@ -74,6 +74,7 @@ const DESTRUCTIVE_WRITE = [
   'chat_send_message', 'generate_character_sheet',
   'acquire_clean_music_track', 'import_music_track_to_library',
   'separate_audio_stems', 'clean_dialogue_leftovers', 'separate_ambience',
+  'analyze_video',
 
   // Deletes and whole-value replacement updates are conservatively destructive.
   'delete_voice', 'update_visual_dna', 'delete_visual_dna', 'delete_visual_dna_folder',

package/src/tools/_shared.js

@@ -55,7 +55,8 @@ const FILE_INPUT_TOOLS = [
   'generate_3d', 'edit_image', 'edit_video', 'transcribe_audio',
   'create_visual_dna', 'update_visual_dna', 'generate_character_sheet', 'clone_voice',
   'chat_send_message', 'create_moodboard', 'update_moodboard',
-  'separate_audio_stems', 'clean_dialogue_leftovers', 'separate_ambience'
+  'separate_audio_stems', 'clean_dialogue_leftovers', 'separate_ambience',
+  'analyze_video'
 ];
 
 const REMOTE_FILE_HINT =

package/src/tools/analyze.js

@@ -0,0 +1,50 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+const { z } = require('zod');
+const { projectIdField } = require('./_shared');
+
+function registerAnalyzeTools(server, client) {
+  // ─── analyze_video ──────────────────────────────────────────
+  // Kolbo's official video understanding. Sync — the server holds the socket for
+  // long videos, so there is nothing to poll.
+  server.tool(
+    'analyze_video',
+    'Understand a video with Kolbo\'s official video-understanding model (agentic Gemini: it navigates the timeline itself — frames, audio and transcript on demand — instead of sampling fixed frames, so long videos are cheap and timestamp / "when does X happen" / counting questions are answered directly). Pass a public https video URL or a YouTube URL plus an optional question in `prompt`; with no prompt you get an exhaustive description + verbatim transcript. Billed by the analyzer\'s real token usage. Local file → upload it first (create_upload_ticket / upload_media / media_upload_widget) and pass the returned URL. For subtitle files use transcribe_audio instead.',
+    {
+      video_url: z.string().optional().describe('Public https URL of the video (Kolbo media URL from upload_media / list_media, or any public file). Either this or youtube_url.'),
+      youtube_url: z.string().optional().describe('A youtube.com / youtu.be link. Either this or video_url.'),
+      prompt: z.string().optional().describe('The question or task about the video (e.g. "At what timestamp does the logo appear?", "Count how many people speak", "Summarize the three main arguments"). Omit for a full description + verbatim transcript.'),
+      quality: z.enum(['standard', 'hq']).optional().describe('"standard" (default, Flash-Lite) or "hq" (Flash, higher accuracy, ~2.5x the token price). Use hq for short clips where precision matters.'),
+      project_id: projectIdField,
+    },
+    async ({ video_url, youtube_url, prompt, quality, project_id }) => {
+      if (!video_url && !youtube_url) {
+        return { content: [{ type: 'text', text: 'Provide video_url or youtube_url. Local file? Upload it first (create_upload_ticket / upload_media / media_upload_widget) and pass the returned URL.' }], isError: true };
+      }
+      const result = await client.post('/v1/analyze/video', {
+        ...(video_url ? { video_url } : {}),
+        ...(youtube_url ? { youtube_url } : {}),
+        ...(prompt ? { prompt } : {}),
+        ...(quality ? { quality } : {}),
+        ...(project_id ? { project_id } : {}),
+      });
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            analysis: result.analysis,
+            model: result.model,
+            agentic: result.agentic,
+            usage: result.usage,
+            credits_used: result.credits_used,
+          }, null, 2),
+        }],
+      };
+    }
+  );
+}
+
+module.exports = { registerAnalyzeTools };