@kolbo/mcp 1.71.0 → 1.71.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.71.0",
+  "version": "1.71.2",
   "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@9e4903a, the single source of truth.
+This tree is mirrored from kolbo-code@c5b2132, 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.2
+version: 0.8.4
 name: kolbo
 description: |
   Generate, edit, analyze, and direct creative media through Kolbo AI: images,
@@ -58,8 +58,8 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 | If the user wants to… | Read first |
 |---|---|
 | 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`; also load `references/workflows/filmmaking.md` for narrative, performance, or cross-shot continuity |
-| Generate a **Seedance 2 / 2.0** video | `references/models/seedance.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 |
 | Generate a **GPT Image 2** image | `references/models/gpt-image.md` |
 | Generate a **Nano Banana / Gemini** image | `references/models/nano-banana.md` |
 | Generate a **Veo 3 / 3.1** video | `references/models/veo.md` |
@@ -94,7 +94,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `generate_video` | Text-to-video. Does **not** support Visual DNA — use `generate_elements` for character-consistent video. |
 | `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.** |
+| `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_music` | Music generation (Suno + variants). |
@@ -114,7 +114,8 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `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. |
 | `search_music_library` / `browse_music_library` / `get_music_library_facets` / `get_music_track_audio` / `get_music_track_lyrics` / `get_music_track_related` / `analyze_script_for_music` / `acquire_clean_music_track` / `import_music_track_to_library` | **SYNCI licensed music** — a commercially licensed catalog, not free stock. Discovery and previews are free but **watermarked**; there is no unwatermarked URL until you pay. `acquire_clean_music_track` (or `import_music_track_to_library`, which also copies it to the media library) **CHARGES CREDITS** for the clean master — confirm with the user first, and pass a stable `requestId` so a retry doesn't buy it twice. `analyze_script_for_music` turns a script into search terms for `search_music_library`. Use this family when the user needs music cleared for commercial use; use `search_stock_media` with `mediaType: "music"` when free stock will do. |
 | `list_projects` / `move_session` | Projects: resolve a project NAME → the `project_id` you pass on generation/upload/doc calls; `move_session` relocates a whole session + its media when work landed in the wrong project. See "Projects — Where Work Lands" below. |
-| `create_project` / `update_project` / `archive_project` / `unarchive_project` / `list_sessions` | Project lifecycle + session inventory (deletion stays in-app). Create a project when the user starts new work, then pass its id on EVERY call. |
+| `create_project` / `update_project` / `archive_project` / `unarchive_project` / `list_sessions` / `rename_session` / `delete_session` / `restore_session` | Project lifecycle + session inventory. `list_sessions` returns `project_id` + `types[]` on every row. Soft-delete leftover empty sessions after a move; `restore_session` undoes trash. Create a project when the user starts new work, then pass its id on EVERY call. |
+| `bulk_move_sessions` / `list_session_generations` / `move_generations_to_session` / `split_session` / `undo_session_organization` | Reorganize many sessions or generations. `list_session_generations` is an inventory (not a live generation card). |
 | `add_project_context` / `list_project_context` / `delete_project_context` / `get_project_profile` / `regenerate_project_profile` | Project knowledge base (RAG): feed scripts/URLs/notes; `get_project_profile` = the living brief — read it to ground work in the project |
 | `create_moodboard` / `update_moodboard` / `delete_moodboard` | Moodboards from image URLs → AI master style prompt → pass `moodboard_id` to generation tools |
 | `clone_voice` / `import_elevenlabs_voice` / `delete_voice` | Custom voices (clone CHARGES CREDITS — confirm first; new voices show in `list_voices`) |
@@ -123,6 +124,25 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) |
 | `publish_html_artifact` | Publish HTML / SVG / Mermaid to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP. |
 
+## ⚠️ Visual DNA `@Name` in the prompt (HARD RULE — always on)
+
+Passing `visual_dna_ids` is **not enough**. For every DNA in that array you MUST also write `@ExactStoredName` in the prompt text (the `name` from `list_visual_dnas` / `create_visual_dna`). The engine binds identity by parsing `@tags`. No `@tag` → the DNA is wasted.
+
+- Right: `visual_dna_ids: ["vdna_…"]` + prompt `@Zohar walks into frame`
+- Wrong: `Zohar's`, `Zohar`, `the left man`, `the man on the LEFT`, `Visual DNA anchors: the man on the LEFT…` — none of these bind
+- Never invent a role label or possessive as a substitute for `@Name`
+- Same rule for moodboards: `#ExactBoardName`
+
+Resolve names with `list_visual_dnas` first. Full binding rules: `references/workflows/visual-dna.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 — …`
+
+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)
 
 A user-named tool — in any language — overrides every other rule. Recognized aliases:
@@ -172,9 +192,9 @@ Model types for `list_models`: `text_to_img`, `image_editing`, `text_to_video`,
 
 Everything in Kolbo — sessions, generations, media, docs — lives inside a PROJECT. Getting this wrong is the #1 user complaint ("my work went to the wrong project").
 
-1. **User names a project** ("in my Acme project", "for the film") → call `list_projects` ONCE to resolve the name to an ObjectId, then pass that id as `project_id` on **EVERY** subsequent `generate_*` / `upload_media` / `create_doc` / `chat_send_message` call in the conversation. It is **per-call, NOT sticky** — any call that omits it silently lands in the default "API Generations" bucket (`is_default: true`). Accounts often hold hundreds of projects, so pass `list_projects({ search: "acme" })` rather than listing everything; the list is paginated (50/page) and hides archived projects unless you pass `include_archived: true`.
-2. **No project mentioned** → omit `project_id`; the default bucket is correct. Don't ask unless intent is ambiguous.
-3. **Work landed in the wrong project? MOVE it, never regenerate**: `move_session` relocates a whole session + all its media (works for any session type — the `session_id` from generation responses, chats, transcriptions); `move_media` / `bulk_move_media` / `move_folder_contents` relocate individual media items.
+1. **User names a project** ("in my Acme project", "for the film") → call `list_projects` ONCE to resolve the name to an ObjectId, then pass that **same** id as `project_id` on **EVERY** subsequent `generate_*` / `upload_media` / `create_doc` / `chat_send_message` call in **this conversation**. There is no server-side sticky store — omitting it on any later call silently lands in the default "API Generations" bucket (`is_default: true`). Once resolved, treat that id as required for the rest of the conversation. Accounts often hold hundreds of projects, so pass `list_projects({ search: "acme" })` rather than listing everything; the list is paginated (50/page) and hides archived projects unless you pass `include_archived: true`.
+2. **No project mentioned** → omit `project_id`; the default bucket is correct. Don't ask unless intent is ambiguous. If `list_sessions` already returned a `project_id` for the work you are continuing, keep passing that id.
+3. **Work landed in the wrong project? MOVE it, never regenerate**: `move_session` relocates a whole session + all its media (works for any session type — the `session_id` from generation responses, chats, transcriptions); `move_media` / `bulk_move_media` / `move_folder_contents` relocate individual media items. Empty leftover sessions after a move: `delete_session` (soft-delete; `restore_session` undoes it). `rename_session` only changes the sidebar title.
 
 
 ## Cost Awareness — Quick Rules

package/skill/VERSION

@@ -1 +1 @@
-0.8.2
+0.8.4

package/skill/references/models/seedance.md

@@ -9,13 +9,16 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 **Kolbo MCP routing:** Seedance is a video model — call `generate_video` (text-to-video) or `generate_elements` (when video references / Visual DNA / first-last frames are involved). Run `list_models({ type: "text_to_video" })` and pick a Seedance variant by name.
 
-## Universal Rules (apply to EVERY Seedance prompt)
+**Elements uses this same file.** `generate_elements` is not a second prompt language. Do not write `SCENE CONTEXT` / `OPTICS` / `ACTION` department packs for Elements or Seedance — those are filmmaking audit contracts, not the generation compile shape.
 
+## Universal Rules (apply to EVERY Seedance / Elements prompt)
+
+- **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`.
 - **First line ALWAYS declares shot structure**: total duration, shot count, aspect ratio. Example: `Total: 15s / 6 shots / 16:9`. Put it at the BOTTOM of the prompt too. For connected narrative sequences the proven phrasing is `N connected cinematic shots, 15 seconds total, 16:9, Multishot ON` — use it and keep `Multishot ON` for any multi-shot story.
-- **Order inside each shot**: Subject → Action → Camera → Style → Constraints → (Audio/SFX if relevant).
-- **Prompt length**: aim for ~120–280 words TOTAL across all shots combined (not per shot). Shorter than ~120 words = random output. Longer risks the 8000-char cap below and makes the model forget the opening. For 6-shot prompts, keep each shot 1–2 tight sentences.
-- **Character lock**: if a character recurs, open with `same character throughout all shots` to stop identity drift.
-- **Max 3 shots per single-shot prompt; max 6 shots in a multi-shot montage.** More causes drift.
+- **Then the Locked Intro** — `[GLOBAL LOOK]` / `[CAST]` / `[LOCATION]` — before any shot. A one-liner `same character throughout` is not a character lock.
+- **Order inside each shot**: Subject → Action → Camera → Constraints → (Audio/SFX if relevant). Do NOT restack GLOBAL LOOK style inside the shot.
+- **Prompt length**: simple single-idea pieces ~120–280 words. Locked-intro cinematic typically 400–900 words. Shorter than ~120 words = random output. The 8000-char cap below always wins.
+- **Shot count is user-directed.** If the user asks for N shots, deliver exactly N in one prompt unless they ask to split.
 - **Always describe at least one camera movement per shot.**
 - **Tell Seedance what the camera is NOT doing** (e.g. `no cuts, no zoom, natural head movement`) — this is what locks POV.
 - **Final prompt is always English**, wrapped in a copy-ready code block. Detect intent in any language and reply in the user's language, but the prompt itself is English.
@@ -26,6 +29,32 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
   - **Never** split into multiple prompts, multiple code blocks, or "part 1 / part 2" to evade the cap.
   - Before outputting, internally count the characters of the final prompt as a single string. If > 8000, rewrite tighter and re-count. Repeat until ≤ 8000. Only then show the user.
 
+## Locked Intro (DEFAULT for any multi-shot cinematic — including Elements)
+
+After the Total line, every multi-shot prompt — and any piece with recurring people or a recurring place — opens with three locked blocks. Skip only for: true single-shot POV/orb, 3×3 grid-panel mode, or video-edit tasks.
+
+```
+Total: Xs / N shots / AR
+N connected cinematic shots, Xs total, AR, Multishot ON
+
+[GLOBAL LOOK – LOCKED, APPLIES TO EVERY SHOT]
+<body>, <lens family>, <film stock>, <aspect> spherical, <stop>. <DoF, grain, grade as law>. <movement grammar>. <performance + audio law>.
+
+[CAST – IDENTICAL IN EVERY SHOT]
+@Exact_DNA_name: age, build, hair, face, wardrobe, signature details.
+PROP: recurring object.
+
+[LOCATION]
+Place in materials + light + color field. Blocking. Background LIFE.
+
+SHOT 1 — 0:00–0:02 — Medium / camera position
+(physical verbs, timed acting, quoted dialogue)
+…
+Total: Xs / N shots / AR
+```
+
+When a Visual DNA exists, its exact `@DNA_name` IS the cast name — never place a nickname before it or substitute one later. For plain image refs use `@ImageN`.
+
 ## The 5 Formats
 
 ### 1. Transformations (highest-performing format)
@@ -62,16 +91,13 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 ### 6. Reference-Anchored Cinematic Sequence (multi-character / named references — highest-fidelity format)
 
-Use whenever the user gives named characters or multiple reference images (`@Image1`, `@Image2`, …) — a tactical unit clearing a bunker, a duel between two referenced characters, a war scene. **This is always an Elements-mode prompt** (route the card to `elements`). Structure:
+Use whenever the user gives named characters, Visual DNAs, or multiple reference images (`@Image1`, `@Image2`, …). **This is always an Elements-mode prompt** (`generate_elements`). Structure:
 
-1. **Labeled scene header FIRST** (grounds the scene before any shot):
-   - `Time of day:` — hour + light quality + atmosphere (dust, haze, heavy silence before action).
-   - `Location:` — the environment in concrete physical detail (materials, wear, light direction, high-contrast blown-out entrance, etc.).
-   - `Characters:` — ONE line per person: `Name @ImageN — wardrobe, position in frame, what they carry`. End with "All must match their character references exactly."
-2. **REFERENCE CONSISTENCY block** — map every reference and pin what must NOT change: `Reference Image 1 is <X>. Preserve exact face, hair, anatomy, wardrobe, colors, props.` Add per-character energy/aura color rules, and any already-established story state (e.g. "the gem is already shattered — no intact gem, no red glow"). End with "Do not redesign, morph, recolor, or swap either character, their clothing, anatomy, weapons, or the environment."
-3. **Shots** — either titled (`Shot 1 — Medium Wide / Tactical Positioning`) or timecoded (`SHOT 1 — 0:00–0:03`); timecodes must sum to the total duration. Under each shot use **Camera → Action → Audio** in that order.
-4. **Continuity** — to chain a series, open with `Begin as a seamless continuation from <the exact last beat of the previous video>.`
-5. Close with whichever **Power Blocks** below actually apply (this format usually warrants all three; a simpler scene may need only AUDIO).
+1. **Locked Intro FIRST** (GLOBAL LOOK / CAST / LOCATION). CAST is one line per person: `@Exact_DNA_name` or `Name @ImageN — wardrobe, position, what they carry`. End CAST with "All must match their character references exactly." Never "the man on the LEFT" without an `@tag`.
+2. **REFERENCE CONSISTENCY block** — map every reference and pin what must NOT change: `@Zohar` / `Reference Image 1 is <X>. Preserve exact face, hair, anatomy, wardrobe, colors, props.`
+3. **Shots** — timecoded `SHOT N — 0:00–0:03`. Re-use the same `@DNA_name` in every shot that person appears. Camera → Action → Audio.
+4. **Continuity** — ONLY when the user will attach the previous video / last frame as an input. Otherwise the prompt is STANDALONE.
+5. Close with whichever **Power Blocks** below actually apply.
 
 ## Power Blocks (CONDITIONAL — add ONLY the ones the shot actually needs; never pad a simple prompt)
 
@@ -93,7 +119,7 @@ These elevate rich cinematic / reference-anchored sequences. For a short, tight,
 
 ## Universal Craft Layer (apply on top of any format above)
 
-> This is the universal film-direction layer that lifts every prompt above the boilerplate. **Deep-dive reference:** `~/.kolbo/skills/seedance-2-prompting/SKILL.md` (Craft Edition — full block structure, every optical technique, and the pre-flight checklist).
+> Craft layer for observables (FOV degrees, km/h, Kelvin). Do **not** switch the compile shape to that skill's SCENE CONTEXT / OPTICS / ACTION pack — Locked Intro above is the only default for Seedance and Elements.
 
 ### Core principle
 
@@ -226,4 +252,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`). Tag the DNA inside the prompt with `@<dna-name>` — 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`). Use the exact literal `@DNA_name` as the character name in CAST and re-anchor every shot where it appears — never a nickname, alias, possessive (`Zohar's`), or spatial label (`the left man`). See `workflows/visual-dna.md`. For grid/storyboard inputs, the source frame is `@image1`.

package/skill/references/models/seedance25.md

@@ -9,6 +9,8 @@ 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.
+
 ## What's NEW in 2.5 (verified — never hedge)
 
 - **Duration 4–30 seconds**, whole seconds. 30s IS supported.
@@ -62,4 +64,4 @@ Skip CORE STYLE / SUBJECT / ENVIRONMENT — the three locked blocks already own
 
 ## Where to run in Kolbo
 
-Same routing as Seedance 2 (`first_last_frame` / `elements` / `image_to_video` / `text_to_video`). Pair Visual DNA with `generate_elements` and tag `@<dna-name>` inside the prompt.
+Same routing as Seedance 2 (`first_last_frame` / `elements` / `image_to_video` / `text_to_video`). Pair Visual DNA with `generate_elements` and write the exact `@DNA_name` in CAST and every shot — never "Zohar's" / "the left man" / an untagged "Visual DNA anchors" paragraph. Elements uses this same Locked Intro; do not compile SCENE CONTEXT / OPTICS / ACTION packs.

package/skill/references/workflows/filmmaking.md

@@ -93,27 +93,19 @@ Before writing, establish:
 
 Prompt-length limits apply to the entire compiled generation prompt as one string, including whitespace, headers, timecodes, dialogue, audio, and locks. Count after compilation. For the current Seedance 2.5 adapter snapshot, the hard ceiling is 30,000 characters; never borrow that number for another model.
 
-For a serious controlled shot, prefer this logical order, omitting irrelevant blocks:
+**Seedance 2 / Seedance 2.5 / `generate_elements` — Locked Intro is the only compile shape.** Read `references/models/seedance.md` (and `seedance25.md` for 2.5 caps). Do not emit the SCENE CONTEXT / OPTICS / ACTION department pack below as the generation prompt. Every Visual DNA in play must be `@ExactName` in CAST and in each shot — never "the left man" or a possessive.
 
 ```text
-SCENE CONTEXT
-ACTIVE REFERENCES
-LOCATION MAP
-FIRST FRAME AND SPATIAL BLOCKING
-FORMAT MODE
-OPTICS
-CAMERA
-ACTION TIMING / SHOTS
-PHYSICS
-LIGHTING
-ACTING TASKS
-DIALOGUE
-AUDIO / MUSIC
-STYLE
-POSITIVE LOCKS
+Total: Xs / N shots / AR
+[GLOBAL LOOK – LOCKED, APPLIES TO EVERY SHOT]
+[CAST – IDENTICAL IN EVERY SHOT]   ← @DNAName per person
+[LOCATION]
+SHOT N — 0:00–0:02 — …
 ```
 
-For anchored or exploratory work, collapse compatible blocks and protect only non-negotiables. Never manufacture a rigid skeleton when a looser model-native prompt is more likely to succeed.
+The SCENE CONTEXT pack in `prompt-contracts.md` is an **audit / pre-compile checklist** for non-Seedance models and Workbench diagnosis — not the default Elements prompt.
+
+For anchored or exploratory work on other models, collapse compatible blocks and protect only non-negotiables. Never manufacture a rigid skeleton when a looser model-native prompt is more likely to succeed.
 
 ## Preserve continuity
 

package/skill/references/workflows/visual-dna.md

@@ -81,7 +81,8 @@ Whenever a generation call passes `visual_dna_ids` (even just one), the prompt M
 **Use the actual stored name, programmatically.** When you call `list_visual_dnas` (or `create_visual_dna`), read the `name` field off the response and use that exact string after the `@`. Do NOT:
 
 - Translate the name into another language ("אסתר" / "esther" / "אסתי" — pick whichever string is in `name` and use ONLY that one).
-- Invent a friendlier alias ("the model", "המודל", "her").
+- Invent a friendlier alias ("the model", "המודל", "her", "Zohar's", "the left man", "the man on the LEFT").
+- Write a "Visual DNA anchors:" prose block that describes position/wardrobe but never writes `@ExactName`.
 - Write the character's name in plain text without the `@` prefix.
 - Drop the `@name` when only one DNA is passed — the engine still needs the binding so it knows the DNA is the *subject* and not a passive style.
 

package/src/apps/html.js

@@ -109,11 +109,63 @@ function monogram(name) {
 function structured(res) {
   if (!res) return null;
   if (res.structuredContent) return res.structuredContent;
+  if (res.result) return structured(res.result);
   try {
     var t = (res.content || []).filter(function (c) { return c.type === 'text'; })[0];
     return t ? JSON.parse(t.text) : null;
   } catch (e) { return null; }
 }
+// Hosts that do not advertise MCP Apps (Kolbo Code) get plain JSON
+// ({ sessions }, { generations }, { projects }, …) with no items[].
+// Normalize those shapes so list.html and the generation fallback can
+// leave Loading on first paint without waiting for a newer host.
+function listPayload(sc) {
+  if (!sc || typeof sc !== 'object') return null;
+  if (sc.widget && sc.widget !== 'list') return null;
+  if (sc.phase || sc.generation_id || sc.generation_ids) return null;
+  if (Array.isArray(sc.items)) {
+    return {
+      widget: 'list',
+      title: sc.title || 'List',
+      items: sc.items,
+      total: sc.total != null ? sc.total : sc.items.length
+    };
+  }
+  var key = sc.sessions ? 'sessions' : sc.projects ? 'projects' : sc.generations ? 'generations'
+    : sc.agents ? 'agents' : sc.docs ? 'docs' : sc.folders ? 'folders' : sc.sources ? 'sources' : '';
+  var rows = key ? sc[key] : null;
+  if (!Array.isArray(rows)) return null;
+  var titles = {
+    sessions: 'Sessions', projects: 'Projects', generations: 'Generations',
+    agents: 'Agents', docs: 'Docs', folders: 'Folders', sources: 'Knowledge Base'
+  };
+  return {
+    widget: 'list',
+    title: sc.title || titles[key] || 'List',
+    items: rows.map(function (row) {
+      var types = Array.isArray(row.types)
+        ? row.types.filter(function (x) { return typeof x === 'string'; })
+        : String(row.type || '').split('|').filter(Boolean);
+      var id = row.session_id || row.id || row.generation_id || row.file_key;
+      var name = row.name || row.title || (row.prompt ? String(row.prompt).slice(0, 80) : '') || types[0] || 'Item';
+      return {
+        id: id,
+        title: name,
+        subtitle: [
+          types.join(', ') || row.role || row.status || row.description,
+          id,
+          row.project_id ? 'project ' + row.project_id : null,
+          row.updated_at ? String(row.updated_at).slice(0, 10) : null,
+          row.output_count ? row.output_count + ' outputs' : null
+        ].filter(Boolean).join(' · '),
+        badge: types[0] || row.role || row.status,
+        open_url: row.open_url || row.share_url || null,
+        meta: row.item_count != null ? String(row.item_count) : undefined
+      };
+    }),
+    total: sc.total != null ? sc.total : (sc.count != null ? sc.count : rows.length)
+  };
+}
 </script>
 <script>${script}</script>
 </body>

package/src/apps/index.js

@@ -166,6 +166,13 @@ function uiResult(uri, text, structured) {
   };
 }
 
+/** List tools always ship structuredContent — Kolbo Code does not advertise
+ *  MCP Apps, so gating on appsEnabled() left list.html / the generation
+ *  fallback stuck on Loading with only `{ sessions }` text. */
+function listResult(text, structured) {
+  return uiResult(UI.list, text, structured);
+}
+
 /* ------------------------------------------------------------------ */
 /* Model icon lookup (name/identifier → absolute avatar URL)           */
 /* ------------------------------------------------------------------ */
@@ -494,6 +501,7 @@ module.exports = {
   attachToolWidgetMeta,
   uiMeta,
   uiResult,
+  listResult,
   appsEnabled,
   modelIcon,
   modelInfo,

package/src/apps/widgets/generation.js

@@ -889,6 +889,8 @@ function completedFromPlain(sc) {
 /* ---------- wire host events ---------- */
 window.kolbo.onToolResult(function (result) {
   var sc = result.structuredContent || structured(result);
+  var list = listPayload(sc);
+  if (list) return renderList(list);
   if (sc && (sc.phase || sc.widget)) return boot(sc);
   var recovered = completedFromPlain(sc);
   if (recovered) return boot(recovered);
@@ -907,7 +909,10 @@ window.kolbo.ready(function (ctx) {
   var info = ctx && ctx.toolInfo;
   if (!state && info) {
     originTool = (info.tool && info.tool.name) || originTool;
-    if (info.result && info.result.structuredContent) return boot(info.result.structuredContent);
+    var raw = info.result && (info.result.structuredContent || structured(info.result));
+    var list = listPayload(raw);
+    if (list) return renderList(list);
+    if (raw) return boot(raw);
     bootPre(originTool, null);
   }
 });

package/src/apps/widgets/list.js

@@ -43,17 +43,30 @@ el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openL
 var state = null;
 
 function boot(sc) {
-  if (!sc || !sc.items) return;
-  state = sc;
-  el('title').textContent = sc.title || 'List';
-  var total = sc.total != null ? sc.total : sc.items.length;
+  var list = listPayload(sc);
+  if (!list) return false;
+  state = list;
+  el('title').textContent = list.title || 'List';
+  var total = list.total != null ? list.total : list.items.length;
   el('count-chip').style.display = '';
   el('count-chip').textContent = total + (total === 1 ? ' item' : ' items');
-  if (!sc.items.length) { el('stage').innerHTML = '<div class="k-empty">Nothing here yet</div>'; return; }
-  el('stage').innerHTML = sc.items.slice(0, 40).map(itemHTML).join('');
+  if (!list.items.length) {
+    el('stage').classList.add('k-empty');
+    el('stage').innerHTML = 'Nothing here yet';
+    window.kolbo.notifySize();
+    return true;
+  }
+  el('stage').innerHTML = list.items.slice(0, 40).map(itemHTML).join('');
   el('stage').classList.remove('k-empty');
   wire();
   window.kolbo.notifySize();
+  return true;
+}
+
+function apply(result) {
+  if (!result) return false;
+  var inner = result.result || result;
+  return boot(inner.structuredContent || structured(inner) || inner);
 }
 
 function itemHTML(item, i) {
@@ -86,11 +99,11 @@ function wire() {
 }
 
 window.kolbo.onToolResult(function (result) {
-  var sc = result.structuredContent || structured(result);
-  if (sc && sc.items) return boot(sc);
-  var card = document.querySelector('.k-card');
-  if (card) card.style.display = 'none';
-  window.kolbo.notifySize();
+  apply(result);
+});
+window.kolbo.ready(function (ctx) {
+  var info = ctx && ctx.toolInfo;
+  if (info && info.result) apply(info.result);
 });
 `;
 

package/src/tools/agents.js

@@ -4,10 +4,9 @@
  * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
 
 const { z } = require('zod');
-const { UI, uiResult, appsEnabled } = require('../apps');
+const { listResult } = require('../apps');
 
-function registerAgentTools(server, client, options = {}) {
-  const ui = () => appsEnabled(server, options);
+function registerAgentTools(server, client) {
   // ─── list_agents ───────────────────────────────────────────
   server.tool(
     'list_agents',
@@ -22,22 +21,18 @@ function registerAgentTools(server, client, options = {}) {
         count: result.count || agents.length
       }, null, 2);
 
-      if (ui()) {
-        return uiResult(UI.list, text, {
-          widget: 'list',
-          title: 'Your Agents',
-          items: agents.map(a => ({
-            id: a.id,
-            title: (a.emoji ? a.emoji + ' ' : '') + a.name,
-            subtitle: a.description,
-            badge: a.is_global ? 'preset' : null,
-            use_hint: 'Use my "{TITLE}" agent (agent_id: {ID}) for this conversation.'
-          })),
-          total: agents.length
-        });
-      }
-
-      return { content: [{ type: 'text', text }] };
+      return listResult(text, {
+        widget: 'list',
+        title: 'Your Agents',
+        items: agents.map(a => ({
+          id: a.id,
+          title: (a.emoji ? a.emoji + ' ' : '') + a.name,
+          subtitle: a.description,
+          badge: a.is_global ? 'preset' : null,
+          use_hint: 'Use my "{TITLE}" agent (agent_id: {ID}) for this conversation.'
+        })),
+        total: agents.length
+      });
     }
   );
 

package/src/tools/docs.js

@@ -5,12 +5,11 @@
 
 const { z } = require('zod');
 const { projectIdField } = require('./_shared');
-const { UI, uiResult, appsEnabled } = require('../apps');
+const { listResult } = require('../apps');
 
 const CONTENT_GUIDE = 'HTML body content. Use clean semantic HTML the in-app editor understands: <h1>-<h3>, <p>, <ul>/<ol>/<li>, <table>, <blockquote>, <strong>/<em>, <a>. No <script>/<style>/<iframe> (stripped server-side). Write the FULL document yourself — this is where you author the doc.';
 
-function registerDocTools(server, client, options = {}) {
-  const ui = () => appsEnabled(server, options);
+function registerDocTools(server, client) {
   // ─── create_doc ────────────────────────────────────────────
   server.tool(
     'create_doc',
@@ -55,21 +54,17 @@ function registerDocTools(server, client, options = {}) {
       const docs = result.docs || [];
       const text = JSON.stringify({ docs, pagination: result.pagination || null }, null, 2);
 
-      if (ui()) {
-        return uiResult(UI.list, text, {
-          widget: 'list',
-          title: 'Your AI Docs',
-          items: docs.map(d => ({
-            id: d.id,
-            title: d.title,
-            subtitle: (d.updated_at ? String(d.updated_at).slice(0, 10) : '') + (d.is_shared ? ' · shared' : ''),
-            open_url: d.share_url || null
-          })),
-          total: docs.length
-        });
-      }
-
-      return { content: [{ type: 'text', text }] };
+      return listResult(text, {
+        widget: 'list',
+        title: 'Your AI Docs',
+        items: docs.map(d => ({
+          id: d.id,
+          title: d.title,
+          subtitle: (d.updated_at ? String(d.updated_at).slice(0, 10) : '') + (d.is_shared ? ' · shared' : ''),
+          open_url: d.share_url || null
+        })),
+        total: docs.length
+      });
     }
   );
 

package/src/tools/media.js

@@ -6,7 +6,7 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { resolveToBuffer, DEFAULT_MAX_FILE_MB, compactList } = require('./_shared');
-const { UI, uiResult, appsEnabled } = require('../apps');
+const { UI, uiResult, listResult, appsEnabled } = require('../apps');
 
 // How many tiles the media grid renders. A rendering limit only — the text
 // payload always carries the full page, and `total` reports the real library
@@ -343,22 +343,18 @@ function registerMediaTools(server, client, options = {}) {
       const folders = result.folders || [];
       const text = JSON.stringify({ folders, count: result.count || 0 }, null, 2);
 
-      if (ui()) {
-        return uiResult(UI.list, text, {
-          widget: 'list',
-          title: 'Media Folders',
-          items: folders.map(f => ({
-            id: f.id,
-            title: f.name,
-            subtitle: f.description,
-            meta: (f.item_count || 0) + (f.item_count === 1 ? ' item' : ' items'),
-            use_hint: 'List media in my "{TITLE}" folder (folder_id: {ID}).'
-          })),
-          total: folders.length
-        });
-      }
-
-      return { content: [{ type: 'text', text }] };
+      return listResult(text, {
+        widget: 'list',
+        title: 'Media Folders',
+        items: folders.map(f => ({
+          id: f.id,
+          title: f.name,
+          subtitle: f.description,
+          meta: (f.item_count || 0) + (f.item_count === 1 ? ' item' : ' items'),
+          use_hint: 'List media in my "{TITLE}" folder (folder_id: {ID}).'
+        })),
+        total: folders.length
+      });
     }
   );
 

package/src/tools/projects.js

@@ -5,10 +5,9 @@
 
 const { z } = require('zod');
 const { buildProjectUrl } = require('./_shared');
-const { UI, uiResult, appsEnabled } = require('../apps');
+const { listResult } = require('../apps');
 
-function registerProjectTools(server, client, options = {}) {
-  const ui = () => appsEnabled(server, options);
+function registerProjectTools(server, client) {
   // ─── list_projects ─────────────────────────────────────────
   server.tool(
     'list_projects',
@@ -42,22 +41,18 @@ function registerProjectTools(server, client, options = {}) {
         _hint: 'Pass the chosen `id` as `project_id` on any generate_* tool to drop the generation into that project. Omit project_id to use the project flagged is_default:true. `open_url` opens that project\'s media in the web app (share it with the user). If `pagination.has_more` is true there are more projects — narrow with `search` rather than paging through everything.'
       }, null, 2);
 
-      if (ui()) {
-        return uiResult(UI.list, text, {
-          widget: 'list',
-          title: 'Your Projects',
-          items: projects.map(p => ({
-            id: p.id,
-            title: p.name,
-            subtitle: p.role + (p.is_default ? ' · default' : '') + (p.is_archived ? ' · archived' : ''),
-            open_url: p.open_url,
-            use_hint: 'Use my "{TITLE}" project (project_id: {ID}) for what I do next.'
-          })),
-          total: projects.length
-        });
-      }
-
-      return { content: [{ type: 'text', text }] };
+      return listResult(text, {
+        widget: 'list',
+        title: 'Your Projects',
+        items: projects.map(p => ({
+          id: p.id,
+          title: p.name,
+          subtitle: p.role + (p.is_default ? ' · default' : '') + (p.is_archived ? ' · archived' : ''),
+          open_url: p.open_url,
+          use_hint: 'Use my "{TITLE}" project (project_id: {ID}) for what I do next.'
+        })),
+        total: projects.length
+      });
     }
   );
 
@@ -135,20 +130,17 @@ function registerProjectTools(server, client, options = {}) {
         generations,
         _hint: 'This is an inventory, not a live generation. Pass the `id` values to `move_generations_to_session` (into an existing session) or `split_session` (into a new one). `in_flight: true` means it is still running and cannot be moved yet.'
       }, null, 2);
-      if (ui()) {
-        return uiResult(UI.list, text, {
-          widget: 'list',
-          title: (result.session && result.session.name) || 'Session generations',
-          items: generations.map((g) => ({
-            id: g.id,
-            title: (g.prompt && String(g.prompt).slice(0, 80)) || g.id,
-            subtitle: [g.status, g.output_count ? g.output_count + ' outputs' : null].filter(Boolean).join(' · '),
-            badge: g.in_flight ? 'running' : g.status
-          })),
-          total: generations.length
-        });
-      }
-      return { content: [{ type: 'text', text }] };
+      return listResult(text, {
+        widget: 'list',
+        title: (result.session && result.session.name) || 'Session generations',
+        items: generations.map((g) => ({
+          id: g.id,
+          title: (g.prompt && String(g.prompt).slice(0, 80)) || g.id,
+          subtitle: [g.status, g.output_count ? g.output_count + ' outputs' : null].filter(Boolean).join(' · '),
+          badge: g.in_flight ? 'running' : g.status
+        })),
+        total: generations.length
+      });
     }
   );
 
@@ -316,26 +308,22 @@ function registerProjectTools(server, client, options = {}) {
         _hint: 'Each row has project_id — pass it on every later generate/chat/upload in this conversation. Empty leftover sessions after a move: delete_session.'
       }, null, 2);
 
-      if (ui()) {
-        return uiResult(UI.list, text, {
-          widget: 'list',
-          title: 'Sessions' + (type ? ' — ' + type : '') + ' (' + sessions.length + ')',
-          items: sessions.map(s => ({
-            id: s.session_id,
-            title: s.name || s.types[0] || s.type || 'Session',
-            subtitle: [
-              s.session_id,
-              (s.types || []).join(', '),
-              s.project_id ? 'project ' + s.project_id : null,
-              s.updated_at ? String(s.updated_at).slice(0, 10) : null
-            ].filter(Boolean).join(' · '),
-            badge: (s.types && s.types[0]) || undefined
-          })),
-          total: sessions.length
-        });
-      }
-
-      return { content: [{ type: 'text', text }] };
+      return listResult(text, {
+        widget: 'list',
+        title: 'Sessions' + (type ? ' — ' + type : '') + ' (' + sessions.length + ')',
+        items: sessions.map(s => ({
+          id: s.session_id,
+          title: s.name || s.types[0] || s.type || 'Session',
+          subtitle: [
+            s.session_id,
+            (s.types || []).join(', '),
+            s.project_id ? 'project ' + s.project_id : null,
+            s.updated_at ? String(s.updated_at).slice(0, 10) : null
+          ].filter(Boolean).join(' · '),
+          badge: (s.types && s.types[0]) || undefined
+        })),
+        total: sessions.length
+      });
     }
   );
 
@@ -416,21 +404,17 @@ function registerProjectTools(server, client, options = {}) {
       const sources = result.sources || [];
       const text = JSON.stringify({ sources, count: result.count || 0 }, null, 2);
 
-      if (ui()) {
-        return uiResult(UI.list, text, {
-          widget: 'list',
-          title: 'Project Knowledge Base',
-          items: sources.map(s => ({
-            id: s.file_key,
-            title: s.title || s.type,
-            subtitle: s.type + ' · ' + s.status,
-            open_url: s.url || null
-          })),
-          total: sources.length
-        });
-      }
-
-      return { content: [{ type: 'text', text }] };
+      return listResult(text, {
+        widget: 'list',
+        title: 'Project Knowledge Base',
+        items: sources.map(s => ({
+          id: s.file_key,
+          title: s.title || s.type,
+          subtitle: s.type + ' · ' + s.status,
+          open_url: s.url || null
+        })),
+        total: sources.length
+      });
     }
   );
 

package/src/tools/visual_dna.js

@@ -6,7 +6,7 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { resolveToBuffer: sharedResolveToBuffer, VISUAL_DNA_MAX_BYTES, projectScopeReadField, compactList } = require('./_shared');
-const { UI, uiResult, appsEnabled } = require('../apps');
+const { UI, uiResult, listResult, appsEnabled } = require('../apps');
 
 // Visual DNA caps reference media at 25MB per file (stricter than the
 // default _shared.resolveToBuffer cap — DNA profiles only need enough
@@ -227,21 +227,17 @@ function registerVisualDnaTools(server, client, options = {}) {
       const folders = result.folders || [];
       const text = JSON.stringify({ folders, count: result.count || 0 }, null, 2);
 
-      if (ui()) {
-        return uiResult(UI.list, text, {
-          widget: 'list',
-          title: 'Visual DNA Folders',
-          items: folders.map(f => ({
-            id: f.id,
-            title: f.name,
-            meta: f.item_count != null ? (f.item_count + (f.item_count === 1 ? ' DNA' : ' DNAs')) : null,
-            use_hint: 'List Visual DNAs in my "{TITLE}" folder (folder_id: {ID}).'
-          })),
-          total: folders.length
-        });
-      }
-
-      return { content: [{ type: 'text', text }] };
+      return listResult(text, {
+        widget: 'list',
+        title: 'Visual DNA Folders',
+        items: folders.map(f => ({
+          id: f.id,
+          title: f.name,
+          meta: f.item_count != null ? (f.item_count + (f.item_count === 1 ? ' DNA' : ' DNAs')) : null,
+          use_hint: 'List Visual DNAs in my "{TITLE}" folder (folder_id: {ID}).'
+        })),
+        total: folders.length
+      });
     }
   );