@kolbo/mcp 1.84.1 → 1.84.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.84.1",
+  "version": "1.84.3",
   "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/apps/index.js

@@ -88,6 +88,17 @@ const WIDGET_CSP = {
     'https://assets.sketchfab.com',
     'https://sketchfab-prod-media.s3.amazonaws.com',
 
+    // Voice PREVIEW audio hosts. list_voices ships every voice with a
+    // preview_url and the card renders a real <audio> for it, but 150 of the
+    // 864 production voices store that preview on a provider host rather than a
+    // Kolbo bucket: 138 google voices on storage.googleapis.com and 12 on
+    // api.us.elevenlabs.io. media-src blocked both, so every google voice — the
+    // entire Hebrew set — rendered a player stuck at 0:00 / 0:00 with no error
+    // anywhere. The Spaces-hosted previews come free via HOST_MAP above; these
+    // two do not, because they are not ours.
+    'https://storage.googleapis.com',
+    'https://api.us.elevenlabs.io',
+
     // Default SYNCI catalog project. Any production override must be reviewed
     // and added here as an exact hostname before deployment.
     'https://gfbpxdkripkbbrcvoyeh.supabase.co',

package/src/apps/widgets/mediaGrid.js

@@ -48,17 +48,17 @@ function boot(sc) {
   var audioItems = sc.items.filter(function (i) { return i.media_type === 'audio'; });
   var visualItems = sc.items.filter(function (i) { return i.media_type !== 'audio'; });
   var h = '';
+  // Render everything currently in state — each PAGE is already capped
+  // server-side (GRID_CAP), so this grows one page per Load more instead of
+  // being pinned forever. The old hard slices (24 visual / 12 audio) meant an
+  // appended page could never actually appear, and the count below tallied all
+  // items while only 36 were drawn, so the button also lied about the total.
   if (visualItems.length) {
-    h += '<div class="k-grid">' + visualItems.slice(0, 24).map(cellHTML).join('') + '</div>';
+    h += '<div class="k-grid">' + visualItems.map(cellHTML).join('') + '</div>';
   }
   if (audioItems.length) {
-    h += audioItems.slice(0, 12).map(audioRowHTML).join('');
+    h += audioItems.map(audioRowHTML).join('');
   }
-  // Only a fixed page ever renders here (24 visual + 12 audio) — with a library
-  // in the thousands there was no way to reach the rest short of asking in
-  // chat. A visible "Load more" turns that into one click; it sends a message
-  // rather than calling the tool directly, since the widget has no host API
-  // to invoke a tool itself — same mechanism every other "Use" action here uses.
   var shown = visualItems.length + audioItems.length;
   if (sc.total != null && sc.total > shown) {
     h += '<button class="k-btn" id="load-more" style="width:100%;margin-top:10px">Load more (' +
@@ -145,13 +145,50 @@ function wire() {
   });
   var loadMore = el('load-more');
   if (loadMore) {
-    loadMore.onclick = function () {
-      window.kolbo.sendMessage('Show me the next page of this same media search (already saw ' +
-        (state.items.length) + ' of ' + state.total + ' results).');
-    };
+    loadMore.onclick = function () { fetchNextPage(loadMore); };
   }
 }
 
+// Fetch the next page IN the widget and append it.
+//
+// This used to sendMessage() a request for "the next page of this same media
+// search", on the stated belief that a widget has no way to invoke a tool. It
+// does — window.kolbo.callTool, the same bridge call every generation card
+// polls status with. And the message could not have worked anyway: the payload
+// carried no page number and none of the filters, so the model had nothing to
+// reconstruct the query from and would re-run page 1 or something else. The
+// button appeared to do nothing.
+function fetchNextPage(btn) {
+  if (!state || !state.page_tool || btn.disabled) return;
+  var next = (state.page || 1) + 1;
+  btn.disabled = true;
+  var label = btn.textContent;
+  btn.innerHTML = '<span class="k-spin"></span> Loading';
+  var args = {};
+  var q = state.query || {};
+  for (var k in q) { if (q[k] !== undefined && q[k] !== null && q[k] !== '') args[k] = q[k]; }
+  args.page = next;
+  if (state.page_size) args.page_size = state.page_size;
+
+  window.kolbo.callTool(state.page_tool, args).then(function (res) {
+    var sc = structured(res);
+    var more = (sc && sc.items) || [];
+    if (!more.length) {
+      // Nothing came back: say so rather than restoring a button that still
+      // looks like it has pages behind it.
+      btn.textContent = 'No more results';
+      return;
+    }
+    state.items = (state.items || []).concat(more);
+    state.page = (sc && sc.page) || next;
+    if (sc && sc.total != null) state.total = sc.total;
+    boot(state);            // re-renders the grid + a fresh Load more button
+  }).catch(function () {
+    btn.disabled = false;
+    btn.textContent = label;
+  });
+}
+
 function useItem(i) {
   var item = state.items[i];
   if (!item || !item.id) return;

package/src/tools/_shared.js

@@ -851,6 +851,18 @@ async function uiCompleted(p, textPayload, extraContent) {
     // above which assume everything finished together. Only set when the
     // caller actually has this shape; every existing caller is unaffected.
     ...(Array.isArray(p.items) ? { items: p.items } : {}),
+    // Transcription payload. get_generation_status is the ONLY way the live
+    // transcript widget learns its result, and it reads text/srt_url/txt_url off
+    // this object — but uiCompleted is shaped for the generation card and
+    // dropped every one, so a finished transcription rendered "(empty
+    // transcript)" with no SRT/TXT buttons while the text sat in the status
+    // response. structuredContent SHADOWS the text block on widget hosts, so
+    // omitting a field here is the same as deleting it.
+    ...(typeof p.text === 'string' ? { text: p.text } : {}),
+    ...(p.srt_url ? { srt_url: p.srt_url } : {}),
+    ...(p.word_by_word_srt_url ? { word_by_word_srt_url: p.word_by_word_srt_url } : {}),
+    ...(p.txt_url ? { txt_url: p.txt_url } : {}),
+    ...(p.audio_url ? { audio_url: p.audio_url } : {}),
     // The voice, by name and portrait. uiGenerating has carried this since the
     // chips were introduced; uiCompleted never did, so it silently dropped a
     // resolved voice its caller had already looked up — every FINISHED speech

package/src/tools/generate.js

@@ -1118,6 +1118,14 @@ function registerGenerateTools(server, client, options = {}) {
           state: single.state,
           urls: done ? urls : undefined,
           thumbnail_url: res.thumbnail_url,
+          // Transcription results ride the same status tool as media
+          // generations; without these the transcript widget merges a payload
+          // with no transcript in it and renders "(empty transcript)".
+          text: typeof res.text === 'string' ? res.text : undefined,
+          srt_url: res.srt_url || undefined,
+          word_by_word_srt_url: res.word_by_word_srt_url || undefined,
+          txt_url: res.txt_url || undefined,
+          audio_url: res.audio_url || undefined,
           // The refs the server actually conditioned on (reference_details) —
           // the live card merges this payload over its submit-time state, so
           // the finished card shows every reference, including server-side

package/src/tools/media.js

@@ -303,7 +303,17 @@ function registerMediaTools(server, client, options = {}) {
         title: 'Media Library',
         items,
         total: totalItems != null ? totalItems : media.length,
-        shown: Math.min(media.length, GRID_CAP)
+        shown: Math.min(media.length, GRID_CAP),
+        // Everything "Load more" needs to fetch page N+1 ITSELF. The button used
+        // to send a chat message asking the model to run the next page, on the
+        // belief that a widget cannot invoke a tool — it can
+        // (window.kolbo.callTool, the same call every generation card polls
+        // with). Worse, the payload carried no page and no filters, so the model
+        // could not reconstruct the query either and typically re-ran page 1.
+        page_tool: 'list_media',
+        page: page || 1,
+        page_size: page_size || 50,
+        query: { project_id, folder_id, type, category, source_type, sort, search }
       });
     }
   );