@kolbo/mcp 1.81.2 → 1.81.5

package/skill/references/workflows/filmmaking.md

@@ -52,30 +52,6 @@ Compile only what the current generation needs. A video model cannot resolve “
 
 Kolbo Visual DNA is semantic project truth, not merely reference imagery. Read and preserve the saved DNA type and analyzed context: character DNAs own identity/state/performance/voice; environment and scene DNAs own location/geography/light; product DNAs own prop/product identity, scale, material, and state; style DNAs own the visual register. Keep exact tags and never reinterpret one DNA type as another.
 
-## Choose control density
-
-Never equate sophistication with maximum length.
-
-- **Strict** — lock exact blocking, count, timing, dialogue, hand/prop state, axis, scale, or failure-prone physics. Use for continuity-heavy dialogue, expensive hero shots, repeated failures, and exact music synchronization.
-- **Anchored** — dictate non-negotiable story/continuity/physics anchors and allow camera or performance variation inside them. Use for complex spectacle where controlled discovery is valuable.
-- **Exploratory** — protect identity, world, safety, and essential beats while inviting coverage variations. Use for montage, inserts, music-video coverage, and ideation.
-
-If the user supplied an exact prompt, preserve its chosen density unless the failure diagnosis proves density itself is the problem.
-
-## Select craft packs
-
-Load only what the shot needs:
-
-- Story causality and scene reversals: [scene-engine.md](references/filmmaking/scene-engine.md)
-- Asset building, versions, and stress tests: [asset-preproduction.md](references/filmmaking/asset-preproduction.md)
-- Character performance, listening, and voice identity: [acting-direction.md](references/filmmaking/acting-direction.md)
-- Geography, axes, eyelines, diagrams, and state continuity: [blocking-continuity.md](references/filmmaking/blocking-continuity.md)
-- Shot size, optics, operator behavior, and visual grammar: [cinematography.md](references/filmmaking/cinematography.md)
-- Action feasibility, mass, materials, transformations, and impossible shots: [physics-action.md](references/filmmaking/physics-action.md)
-- Dialogue, ambience, native audio, source-song performance, and post music: [audio-dialogue-music.md](references/filmmaking/audio-dialogue-music.md)
-
-Do not paste every craft pack into every prompt. Translate the selected pack into the shortest observable instructions that preserve the intended result.
-
 ## Compile a shot
 
 Read [prompt-contracts.md](references/filmmaking/prompt-contracts.md) for exact structures.
@@ -92,7 +68,7 @@ Before writing, establish:
 8. Audio ownership, exact words/lyrics, and whether music is native, source-driven, or reserved for post.
 9. Model capability limits and target generation mode.
 
-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.
+Prompt-length limits apply to the entire compiled generation prompt as one string, including whitespace, headers, timecodes, dialogue, audio, and locks. Count after compilation; read the cap from `max_prompt_length` via `list_models` (see `models/seedance25.md`).
 
 **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.
 

package/skill/references/workflows/marketing-studio.md

@@ -44,15 +44,17 @@ If the user mentions a product / brand but no mode word, default to `ugc`. If th
 
 The mode determines which Kolbo MCP tool to call, what defaults to set, and what's forbidden.
 
-| Mode | Primary tool | aspect_ratio | duration | sound_enabled | Captions / watermarks |
-|---|---|---|---|:-:|:-:|
-| `ugc`, `ugc_how_to`, `ugc_unboxing`, `ugc_virtual_try_on`, `product_review` | `generate_video_from_image` (frame-first) OR `generate_elements` (Visual DNA → video) | **`9:16`** | model's `default_duration` (5–8s) | OFF | **Never add** |
-| `product_showcase` | `generate_creative_director` with `workflow_type: "video"` (for multi-shot) OR `generate_video` (single) | `16:9` or `1:1` | 5–10s | ON if model supports `sound_generation_type: "native"` | Allowed if user asks |
-| `tv_spot` | `generate_creative_director` with `workflow_type: "video"` (3–6 shots for a beat structure) | `16:9` | 15–30s total | ON (full audio + dialogue) | Allowed if part of the spot |
-| `virtual_try_on` | `generate_elements` with character Visual DNA + product as `reference_images` | `9:16` or `4:5` | 5–8s | OFF | Never add |
-| `wild_card` | User's chosen model with broader prompt latitude (no mode-specific defaults) | User's pick | User's pick | User's pick | User's pick |
+| Mode | Primary tool |
+|---|---|
+| `ugc`, `ugc_how_to`, `ugc_unboxing`, `ugc_virtual_try_on`, `product_review` | `generate_video_from_image` (frame-first) OR `generate_elements` (Visual DNA → video) |
+| `product_showcase` | `generate_creative_director` with `workflow_type: "video"` (for multi-shot) OR `generate_video` (single) |
+| `tv_spot` | `generate_creative_director` with `workflow_type: "video"` (3–6 shots for a beat structure) |
+| `virtual_try_on` | `generate_elements` with character Visual DNA + product as `reference_images` |
+| `wild_card` | User's chosen model with broader prompt latitude (no mode-specific defaults) |
+
+Aspect / duration / sound / captions defaults for the `ugc*` family live in "UGC Family Defaults" below.
 
-**Pick the actual model** with `list_models({ type: "..." })` and validate caps before firing — see SKILL.md "Resolution / Aspect / Duration — validate against caps".
+**Pick the actual model** with `list_models({ type: "..." })` and validate caps before firing — see `references/workflows/cost-and-validation.md`.
 
 ## The Look Itself — read `workflows/ugc-smartphone.md`
 
@@ -149,8 +151,7 @@ Scale to 2–6 slots. Keep `hook → demo → payoff` as the minimum arc; add `t
 ### 2. Rendering rules (hard invariants — apply to EVERY slot)
 
 - One aspect ratio across all slots (UGC = `9:16`). Never mix.
-- **No on-image text**, captions, subtitles, watermarks, or lower-thirds (users add captions in post).
-- **Identity lock**: same presenter, same wardrobe, same lighting environment across all slots — open the prompt with `same character throughout all shots`.
+- **Identity lock**: same presenter, same wardrobe, same lighting environment across all slots — bind identity by tagging `@<dna-name>` in every slot description (identity binds via the DNA; the phrase "same character throughout all shots" is FORBIDDEN — see `models/seedance.md`).
 - Hands and product must read cleanly — no deformed hands, no floating / clipping product, product logo legible when held.
 - Phone-shot aesthetic (handheld sway, window/screen key) unless the mode is polished (`tv_spot`, `product_showcase`).
 
@@ -183,7 +184,7 @@ Track these so each slot's call is reproducible and the arc stays coherent:
 Brief: *"15s UGC review of a skincare serum, tech-savvy woman creator."*
 
 1. Ensure/create presenter Visual DNA (tech-savvy woman) → `visual_dna_id`.
-2. Board: `generate_image` a 3-panel `16:9` sheet — (a) chest-up hook holding the serum, (b) hands applying it, (c) thumbs-up reaction — `same character throughout all shots`, locked to the DNA. → `board_media_id`.
+2. Board: `generate_image` a 3-panel `16:9` sheet — (a) chest-up hook holding the serum, (b) hands applying it, (c) thumbs-up reaction — `@<dna-name>` tagged in every panel description, locked to the DNA. → `board_media_id`.
 3. Slots (each `9:16`, ~5s, sound OFF, animate from the matching board panel + product `@image2`):
    - Slot 1 (hook): "Before this serum my routine was five products…" holding it to camera.
    - Slot 2 (demo): hands applying, product in active use.
@@ -194,9 +195,8 @@ Brief: *"15s UGC review of a skincare serum, tech-savvy woman creator."*
 
 1. **Always pick a mode explicitly.** Don't auto-pick from one ambiguous word. If the user said "make me an ad" with no other signal, offer labeled options: `[UGC / TV Spot / Product Showcase / Surprise me]`.
 2. **Always confirm aspect ratio + duration + sound** before firing — these materially change output and cost. One question, labeled options.
-3. **Default UGC settings are hard rules** — captions OFF, music OFF, watermarks OFF — even when the user doesn't mention them. Only flip when they ask.
-4. **No auto-retry on failure.** If the generation fails (content policy, model OOM), surface the reason and let the user adjust prompt or product.
-5. **Show results without dumping URLs** — see SKILL.md "Generated URLs in chat".
+3. **Retries:** one retry only when `failure.retryable === true` or the generation completed with empty URLs (SKILL.md "⚠️ Generation lifecycle"); otherwise surface the reason and let the user adjust prompt or product.
+4. **Show results without dumping URLs** — see SKILL.md "Generated URLs in chat".
 
 ## Prompt Template Seed for UGC
 

package/skill/references/workflows/media-library.md

@@ -70,7 +70,7 @@ fails to open (exit 26).
 
 | User says | Call |
 |---|---|
-| "Upload this file" / "host this" / "give me a public URL for this" | `upload_media` — but see "Local files" below if it's a path on the user's disk |
+| "Upload this file" / "host this" / "give me a public URL for this" | `upload_media` — but see "Local files" above if it's a path on the user's disk |
 | "Show my media" / "list my images/videos" / "what do I have?" | `list_media` (pass `type` / `category` / `project_id` / `folder_id` / `search`) |
 | "Show my favorites" / "list starred items" | `list_media` with `category=favorites` |
 | "List everything in project X" | `list_media` with `project_id=X` |
@@ -110,3 +110,13 @@ fails to open (exit 26).
 8. **Bulk caps:** 1000 ids for `bulk_delete_media` / `bulk_restore_media` / `bulk_permanently_delete_media` / `bulk_move_media`; 500 ids for `add_media_to_folder` / `remove_media_from_folder`. Split larger jobs into successive calls.
 9. **Folder share resolution:** `share_media_folder` takes emails; users not found come back in `not_found`. Report those to the user — don't assume the share succeeded silently. Members can list/add/remove items but cannot delete the folder or reshare it.
 10. **`get_media` accepts a generation_id as a fallback** for the `media_id` arg, so you can chase down items the user references by their original generation rather than by library id.
+
+## SYNCI licensed music — operational detail
+
+The `*_music_library` tools (`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`) front **SYNCI**, 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` **CHARGES CREDITS** for the clean master. Confirm with the user first, and pass a stable `requestId` so a retry doesn't buy the track twice.
+- `import_music_track_to_library` charges the same way AND also copies the clean track into the media library.
+- `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. When free stock will do, use `search_stock_media` with `mediaType: "music"` instead.

package/skill/references/workflows/product-photoshoot.md

@@ -61,7 +61,7 @@ The mode determines which Kolbo MCP tool to call and what defaults to use.
 
 **For multi-output modes** (`social_carousel`, `ad_creative_pack`), always use `generate_creative_director` — never fire ≥2 `generate_image` calls in a loop. See `models/creative-director.md`.
 
-**Always validate** `aspect_ratio` and `resolution` against the chosen model's `supported_aspect_ratios` / `supported_resolutions` via `list_models` — see SKILL.md "Resolution / Aspect / Duration — validate against caps".
+**Always validate** `aspect_ratio` and `resolution` against the chosen model's `supported_aspect_ratios` / `supported_resolutions` via `list_models` — see `references/workflows/cost-and-validation.md`.
 
 ## Pre-Generation Interview (CRITICAL)
 

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

@@ -38,20 +38,8 @@ The log records **what the user approved** — not everything you produced. Gett
 
 **Never write an artifact into the log as approved without the user's approval.**
 
-If they did not volunteer a yes, end the turn with a **GATE** the next message can
-parse (same contract as `production-planning.md`):
-
-```
-GATE — <bucket name>
-Presented: <what is in play>
-Lock + next: "lock <bucket>" / "yes" / "next" / "now <next bucket>"
-Stay: "redo @name" / "another take of …"
-```
-
-Confirmation the agent may treat as a lock: `yes`, `ok`, `lock`, `approved`,
-`that's the one`, `use take 2`, `next`, `go`, `continue`, or they name the next
-planned bucket while treating this set as done. Silence / "maybe" / a new
-question is **not** a lock — repeat the GATE once, do not invent a yes.
+If they didn't volunteer a yes, end the turn with the GATE block from
+`production-planning.md` §3.
 
 **If the user genuinely doesn't care** — "whatever you think", "you pick", "don't care", or they hand you the whole job — then **you decide**. Choose, say in one line which you picked and why, and log it as usual with `(agent-selected)`. Do not stall a production waiting for an approval the user has already delegated to you.
 

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

@@ -143,11 +143,12 @@ the next planned bucket in **its** session.
 Only now compile shots. Defaults:
 
 - **`generate_elements` with Seedance 2.5** (`seedance-2-5`) for the film itself —
-  up to 30s and 30 shots in ONE generation, up to 20 Visual DNAs, dialogue and SFX
-  baked in. `generate_video` also accepts `visual_dna_ids` now; Elements remains
-  the primary reference-driven route.
-- **Seedance 2.0** (`seedance-2`, cheaper, 4–15s, 9 DNAs) when the piece is short
-  and the cast is small. `seedance-2-fast` / `seedance-2-mini` for cheap blocking.
+  up to 30s and 30 shots in ONE generation, dialogue and SFX baked in. DNA cap:
+  read `max_visual_dna` from `list_models`. `generate_video` also accepts
+  `visual_dna_ids` now; Elements remains the primary reference-driven route.
+- **Seedance 2.0** (`seedance-2`, cheaper, 4–15s, smaller DNA cap per
+  `list_models`) when the piece is short and the cast is small.
+  `seedance-2-fast` / `seedance-2-mini` for cheap blocking.
 - Every DNA in `visual_dna_ids` must also appear as `@ExactName` in the prompt.
 - Dialogue in quotes inside its shot beat — English only, never TTS or lipsync.
   See `models/seedance25.md`.

package/skill/references/workflows/review-collections.md

@@ -0,0 +1,98 @@
+# Kolbo Review — client review & approval collections
+
+Load this file when the user wants **feedback on finished media**: send a cut to a client,
+collect timestamped comments, run an approve / request-changes loop, ship a v2 against the
+same feedback thread, or share work with someone who has no Kolbo account. This is a
+Frame.io-style layer over the media library — assets, versions, comments, statuses, and
+guest share links — all project-scoped like everything else in Kolbo.
+
+Not for: publishing a page (`publish_html_artifact`), sharing a whole media folder
+(`share_media_folder`), or internal doc collaboration (`share_doc`).
+
+## Tool inventory
+
+| Tool | What it does |
+|---|---|
+| `create_review_asset` | New review asset with v1 media attached (`name`, `media_id`, optional `collection_id`, `version_note`). |
+| `list_review_assets` / `get_review_asset` | Browse a project's review assets (filter by `collection_id` / `status`); fetch one with all versions + URLs. |
+| `update_review_asset` | Rename, move to a collection (`collection_id: null` = uncollected), or switch `current_version_index`. |
+| `add_review_version` | Append a new version to an existing asset from a `media_id`. |
+| `set_review_status` | Workflow status: `in_progress` / `needs_review` / `approved` / `changes_requested`. |
+| `delete_review_asset` | Soft-delete an asset AND its underlying review media. |
+| `create_review_collection` / `list_review_collections` / `update_review_collection` / `delete_review_collection` | Folder layer. Deleting a collection is soft — its assets become uncollected, not deleted. |
+| `create_review_comment` / `list_review_comments` / `reply_review_comment` / `edit_review_comment` / `delete_review_comment` | Text comments, optional video timecodes (`time_start` / `time_end`, seconds). One level of reply threading. |
+| `resolve_review_comment` / `unresolve_review_comment` | Close / reopen a comment thread. |
+| `create_review_share_link` / `list_review_share_links` / `revoke_review_share_link` | Guest links (no Kolbo account) for one asset or a whole collection. |
+| `get_review_storage_usage` | `usedBytes` vs the 5GB review cap for the API-key owner. |
+
+## The core flow
+
+```
+upload_media (or reuse a generation's media_id from list_media)
+  → create_review_collection (only if grouping multiple assets)
+  → create_review_asset            ← media becomes v1
+  → set_review_status "needs_review"
+  → create_review_share_link       ← hand the client the share_url
+  → list_review_comments           ← read what came back
+  → fix → add_review_version       ← v2 on the SAME asset
+  → resolve_review_comment on each addressed note
+  → set_review_status "approved" (usually the client does this via the link)
+```
+
+Media must already exist in the library — every attach point takes a `media_id` from
+`upload_media` / `create_upload_ticket` / `media_upload_widget` / `list_media`, never a raw
+URL or local path.
+
+## Version semantics
+
+- Versions **append**; labels are auto-set `v1`, `v2`, … — you can't choose or reorder them.
+- `add_review_version` automatically makes the new version current. Use
+  `update_review_asset({ current_version_index })` only to point BACK at an older cut.
+- **Comments attach to a version's media**, not the asset. `list_review_comments` defaults
+  to the current version — after adding v2, pass `version_media_id` to re-read v1 feedback.
+  Comments do not carry forward; the v2 thread starts clean.
+- Never delete+recreate an asset to "update" it — that orphans the comment history and
+  every share link already sent to the client. New cut = `add_review_version`. Rename /
+  re-file = `update_review_asset`. Delete is for abandoning the review entirely.
+
+## Share links — permissions and defaults
+
+`create_review_share_link` targets an `asset` or a `collection` (collection links cover
+every asset inside, including ones added later). Guest defaults if you pass nothing:
+
+| Permission | Default |
+|---|---|
+| `canComment`, `canViewOtherComments`, `canSwitchVersions` | **true** |
+| `canDownload`, `canResolveOwn`, `canSetStatus` | **false** |
+| `require_email` | **true** — guests identify by email before viewing |
+| `role_label` | `"Client"` (max 40 chars) |
+
+- Want the client to approve directly? Pass `permissions: { canSetStatus: true }` —
+  otherwise they can only comment and you relay the verdict via `set_review_status`.
+- Lockdown options: `password` (a NEW guest password — never an account credential),
+  `allowed_emails`, `expires_at` (ISO8601).
+- Links are revoked by id (`revoke_review_share_link`), not edited — to change permissions,
+  create a new link and revoke the old one. This is the one place recreate IS the mechanism.
+- When someone other than the owner sets a status, the owner gets a notification — don't
+  also announce it manually.
+
+## Storage — the 5GB cap
+
+Review media is **copied into dedicated review storage** and counts against a flat 5GB cap
+per account — separate from library storage. The cap is enforced on `create_review_asset`
+AND `add_review_version`; hitting it returns `REVIEW_STORAGE_LIMIT` (413). That error is a
+real limit, not a transient failure — don't retry. Check `get_review_storage_usage`
+(`usedBytes` / `capBytes`) before bulk-adding large videos, and free space by deleting
+finished review assets (the library originals are untouched).
+
+## Practical notes
+
+- All of this is instant CRUD — no credits, no polling, no `get_generation_status`.
+- Project contract applies: pass the same `project_id` you resolved via `list_projects` on
+  `create_review_asset` / `create_review_collection` / the list calls.
+- `status` filter on `list_review_assets` takes exactly the four enum values — "pending" /
+  "done" are not statuses.
+- Comment ids are `note_id` in the reply/edit/delete/resolve tools; version notes cap at
+  1000 chars.
+- Guests can only resolve their own comments, and only if you granted `canResolveOwn` — the
+  resolve loop on client feedback is normally yours to run after fixing.

package/skill/references/workflows/troubleshooting.md

@@ -26,9 +26,9 @@ If Kolbo tools timeout or aren't listed, the MCP server may not be wired. Tell t
 ```
 This re-wires the MCP configuration automatically. Then restart the session.
 
-## Black / empty chat card while "Generating"
+## Generation status, waiting, black cards
 
-**Not a bug and not a failure.** The chat generation card's preview stays dark until the job has media. Library shows a K/logo placeholder tile for the same in-flight job. Do **not** re-fire `generate_*`, do **not** `list_media` to "find" it. Wait, or call `get_generation_status` once with `wait=true`. When complete, the result appears in Library (This session) — that is the user-facing source of truth.
+Status semantics, `wait=true` batching, black-card-is-normal and the credit guard live in SKILL.md "⚠️ Generation lifecycle — source of truth, waiting, failures".
 
 ## "Rate limited" (429 errors)
 
@@ -47,12 +47,6 @@ Call `list_color_palettes` and look for `is_active: true`. Then either
 grade by writing colours into the prompt — the palette is applied after, and the
 prompt loses.
 
-## Checking generation status without spinning
-
-`get_generation_status` supports `wait=true` (blocks server-side until the generation reaches a final state, up to ~3 min) and `generation_ids` (many ids in one call → returns `all_done`, `still_processing`, and per-generation results). **Never call it repeatedly in a loop** — one `wait=true` call replaces the loop. If some generations are still running after the wait window, call it ONCE more with `wait=true` and only the `still_processing` ids.
-
-**Credit guard:** after a generate tool returns `submitted` / `_timed_out`, do not keep thinking or editing files while the card spins — that burns coding credits. End the turn, or make **one** `wait=true` status call if you need the URLs next.
-
 ## Failure envelope from `get_generation_status`
 
 When a generation fails, `get_generation_status` returns a structured `failure` field alongside `error`:

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

@@ -8,7 +8,7 @@ Visual DNA profiles capture the visual "identity" of a character, style, product
 
 ## Workflow
 
-1. **Sheet first, then DNA.** For any production asset (character / location / prop), resolve the sheet **preset** (`list_presets` with `search`) and `generate_image` with that `preset_id` — custom instructions live on the preset. Then `create_visual_dna` with the sheet as `character_sheet_url` (max 4 extra images — if the user gives more, pick the 4 most representative **that share the same identity and vibe**; never pass 5+). Optionally video and audio. See **Purity** above before you generate those stills.
+1. **Sheet first, then DNA.** For any production asset (character / location / prop), resolve the sheet **preset** (`list_presets` with `search`) and `generate_image` with that `preset_id` — custom instructions live on the preset. Then `create_visual_dna` with the sheet as `character_sheet_url` (max 4 extra images — if the user gives more, pick the 4 most representative **that share the same identity and vibe**; never pass 5+). Optionally video and audio. See **Purity** below before you generate those stills.
 2. **Types**: `character` (default), `style`, `product`, `scene`, `environment`.
 3. **Use** the profile by passing its `id` in `visual_dna_ids` in: `generate_image`, `generate_creative_director`, `generate_elements`, `generate_video_from_image`, `generate_video_from_video`, `generate_first_last_frame`.
 4. **List/inspect** profiles with `list_visual_dnas` / `get_visual_dna`.
@@ -22,7 +22,7 @@ Visual DNA profiles capture the visual "identity" of a character, style, product
 Kolbo no longer sends only the first still or the character sheet. For every attached DNA:
 
 1. **User-uploaded refs take image slots first.**
-2. **Remaining slots:** one main still per DNA, then leftover stills from each DNA **round-robin** until the model's image-slot cap (`elementsMaxImages` / equivalent) is full.
+2. **Remaining slots:** one main still per DNA, then leftover stills from each DNA **round-robin** until the model's image-slot cap (`elements_max_images` / equivalent) is full.
 3. **If every still fits the cap, every still is sent** as its own reference. A 4-image character DNA on a 9-slot model is four slots, not one.
 4. **If a DNA only gets one leftover slot**, has **no distinct character sheet**, and still has unused stills, those leftovers are composited into a **white grid / collage** (up to 9 cells) so the model still sees them. A real character sheet is never overwritten by a collage.
 5. **Native Kling Elements** stays one element per DNA (sheet / frontal). Other providers use the slot pack above.
@@ -104,16 +104,7 @@ Fields to read for the image source (use the first one present on the item): `th
 
 ## ⚠️ @name Syntax — ALWAYS use it when passing visual_dna_ids (MANDATORY)
 
-Whenever a generation call passes `visual_dna_ids` (even just one), the prompt MUST refer to each Visual DNA by `@<exact-name>` — the literal `name` field as it was set in `create_visual_dna` and as it appears in `list_visual_dnas`. This is how the engine binds the DNA to a role in the scene. Without `@name`, the engine guesses, drops the DNA, or blends multiple DNAs together.
-
-**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", "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.
-- **Drop or "clean" tags while rewriting a prompt** (help-widget parity). Compiling SCENE CONTEXT / Locked Intro / a "better" English prompt is not permission to delete `@gal_suit` or rewrite `@yonatan` as `Yonatan`. Copy every existing `@` / `#` token into the new prompt, then add craft around them.
+SKILL.md's `@Name` hard rule applies; here is why it binds that way:
 
 **Wrong** (DNA `name` is `esther_model`, user wrote prompt in Hebrew):
 ```
@@ -228,31 +219,11 @@ You can combine all three reference types in a single call — they're additive,
 
 ## Visual DNA Limits
 
-Read `max_visual_dna` from `list_models` for the exact cap, AND `supports_visual_dna` for the on/off boolean. A model can support DNA without an explicit cap, or have a non-null cap but silently ignore DNA on certain paths (e.g. `generate_video`). Typical ranges: image models (non-Kling) up to **8**, Kling image models **3**, Elements video models **3–5**, everything else up to **3**.
+Read `max_visual_dna` (and `elements_max_images` for image-slot packing) from `list_models` for the chosen model, AND `supports_visual_dna` for the on/off boolean. A model can support DNA without an explicit cap, or have a non-null cap but silently ignore DNA on certain paths (e.g. `generate_video`). Typical ranges: image models (non-Kling) up to **8**, Kling image models **3**, Elements video models **3–5**, everything else up to **3**.
 
 ## ⚠️ Visual DNA Creation — Always Generate Reference Images First (MANDATORY)
 
-**Before calling `create_visual_dna` for a character**, always generate 2 reference images first and include them alongside any user-provided images. These give the Visual DNA engine multi-angle coverage and dramatically improve consistency.
-
-**Step 1 — Generate both images in parallel (one `generate_image` call each, fire simultaneously):**
-
-1. **4-angle character sheet** — prompt: `"[character description], character reference sheet showing front view, back view, left side view, right side view, four panels arranged in a 2x2 grid, neutral solid background, full body, photorealistic"`, aspect ratio `16:9` (or `3:2` — always landscape, see the aspect-ratio rule below)
-2. **Close-up portrait** — prompt: `"[character description], close-up portrait, face and shoulders, neutral solid background, soft studio lighting, photorealistic"`, aspect ratio `1:1`
-
-**Step 2 — Call `create_visual_dna`** with:
-- `images`: the 4-angle sheet URL first, then the close-up URL — **plus** the user's reference photo(s) only if they provided one (i.e. a real person or existing character they want to match). If they gave no reference image, the 2 generated images alone are sufficient.
-- `type`: `"character"`
-- `name`: single-token lowercase descriptive name (see naming rule above)
-
-**Why:** A single reference photo only shows one angle. The close-up gives the engine facial detail; the 4-angle sheet gives it body geometry and pose range. Together they produce far more consistent generations. Both stills (and any user photos you add) must be the **same person, same vibe** — they will all be packed into the next generation.
-
-**Skip this only if** the user explicitly says "just use my image as-is" or provides 3+ reference images already covering multiple angles.
-
-### Environments, products, style — same precision
-
-- **Environment / location:** generate empty (or crowd-only) plates. Prompt out heroes and readable faces. A location DNA that contains `@maya` in the frame will put Maya in every later shot of that place.
-- **Product:** isolated angles, consistent lighting, readable label. No extra hero unless the product is worn and the body is generic.
-- **Style:** one look, applied cleanly. Do not mix neon-cyber and dusty-western stills on the same style DNA.
+**Before calling `create_visual_dna` for a character**, generate the reference stills first — a multi-angle sheet plus a close-up gives the engine far better coverage than a single photo. Route the stills through the **preset contract** (`list_presets` search → `preset_id` on `generate_image`), never a raw hand-written sheet prompt — see "Character sheet — default for production assets" below for the full flow, preset search terms, and aspect-ratio rules. Include the user's reference photo(s) alongside only if they provided one. **Skip this only if** the user explicitly says "just use my image as-is" or provides 3+ reference images already covering multiple angles.
 
 ## When to Use
 

package/src/apps/bridge.js

@@ -22,6 +22,7 @@
  *   .onThemeChange(fn)         — fn(hostContext) on host-context-changed
  *   .callTool(name, args)      — Promise<CallToolResult>
  *   .sendMessage(text)         — append a user chat message (returns Promise)
+ *   .insertText(text)          — paste into the host composer, do not send
  *   .openLink(url)             — open external URL
  *   .copyText(text)            — copy via the host clipboard (ui/copy-text)
  *   .notifySize()              — report content size to host
@@ -183,6 +184,9 @@ const BRIDGE_JS = `
     sendMessage: function (text) {
       return request('ui/message', { role: 'user', content: [{ type: 'text', text: text }] });
     },
+    insertText: function (text) {
+      return request('ui/insert-text', { text: text });
+    },
     openLink: function (url) { return request('ui/open-link', { url: url }); },
     copyText: function (text) { return request('ui/copy-text', { text: text }); },
     // Hand a piece of this widget's media to the host's composer. Dragging it

package/src/apps/html.js

@@ -136,7 +136,8 @@ function modelChipHTML(name, iconUrl) {
   return '<span class="k-chip brand">' + inner + esc(name) + '</span>';
 }
 function monogram(name) {
-  return '<span class="k-mono-icon">' + esc(String(name).trim().charAt(0).toUpperCase()) + '</span>';
+  var ch = String(name || '').replace(/^[@#]+/, '').trim().charAt(0) || '?';
+  return '<span class="k-mono-icon">' + esc(ch.toUpperCase()) + '</span>';
 }
 // In-widget preview overlay — every card (generation chips, media grid, list
 // rows) uses this so a DNA / reference / library thumb opens a popup in Kolbo

package/src/apps/index.js

@@ -630,6 +630,7 @@ const TOOL_WIDGETS = {
   list_docs: UI.list,
   list_media_folders: UI.list,
   list_visual_dna_folders: UI.list,
+  list_project_assets: UI.list,
 };
 
 function attachToolWidgetMeta(server) {

package/src/apps/theme.js

@@ -340,7 +340,8 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
   background: var(--brand-soft); }
 .k-audio-meta { flex: 1; min-width: 0; }
 .k-audio-title { font-size: 12.5px; font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-.k-audio-sub { font-size: 11px; color: var(--text-faint); }
+.k-audio-sub { font-size: 11px; color: var(--text-faint);
+  display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
 .k-generated-audio {
   display: grid; grid-template-columns: 40px minmax(0, 1fr) auto;
   align-items: center; gap: 7px 10px;

package/src/apps/widgets/catalog.js

@@ -67,7 +67,7 @@ function boot(sc) {
   Array.prototype.forEach.call(document.querySelectorAll('[data-g]'), function (row) {
     row.onclick = function () {
       var m = state.groups[+row.getAttribute('data-g')].models[+row.getAttribute('data-m')];
-      window.kolbo.sendMessage(m.use_hint || ('Generate something with the "' + m.name + '" model — ask me what I want to make.'));
+      window.kolbo.insertText(m.identifier || m.name || '');
     };
   });
   window.kolbo.notifySize();

package/src/apps/widgets/generation.js

@@ -75,6 +75,34 @@ var TOOL_TITLES = {
   generate_creative_director: 'Creative Director', edit_image: 'Image Edit', edit_video: 'Video Edit',
   get_generation_status: 'Generations'
 };
+var OPEN_ROUTES = {
+  generate_image: { path: '/image-tools', tool: 'text-to-image' },
+  generate_image_edit: { path: '/image-tools', tool: 'image-editing' },
+  edit_image: { path: '/image-tools', tool: 'image-editing' },
+  generate_video: { path: '/video-tools', tool: 'text-to-video' },
+  generate_video_from_image: { path: '/video-tools', tool: 'image-to-video' },
+  generate_elements: { path: '/video-tools', tool: 'image-to-video', mode: 'elements' },
+  generate_first_last_frame: { path: '/video-tools', tool: 'image-to-video', mode: 'first-last' },
+  generate_video_from_video: { path: '/video-tools', tool: 'video-to-video' },
+  generate_lipsync: { path: '/video-tools', tool: 'lipsync' },
+  generate_music: { path: '/audio-tools', tool: 'music-generator' },
+  generate_speech: { path: '/audio-tools', tool: 'text-to-speech' },
+  generate_sound: { path: '/audio-tools', tool: 'text-to-sound' },
+  transcribe_audio: { path: '/audio-tools', tool: 'speech-to-text' },
+  generate_creative_director: { path: '/creative-director' }
+};
+function kolboUrl(sc) {
+  if (sc && typeof sc.open_url === 'string' && sc.open_url) return sc.open_url;
+  var sid = sc && (sc.session_id || sc.sessionId);
+  var route = OPEN_ROUTES[(sc && sc.tool) || originTool];
+  if (!route || !sid) return 'https://app.kolbo.ai';
+  var url = 'https://app.kolbo.ai' + route.path + '?session=' + encodeURIComponent(sid);
+  if (route.tool) url += '&tool=' + route.tool;
+  if (route.mode) url += '&mode=' + route.mode;
+  var pid = sc && (sc.project_id || sc.projectId);
+  if (pid) url += '&project=' + encodeURIComponent(pid);
+  return url;
+}
 
 // Long text is clamped by CSS (.k-prompt 2 lines / .k-caption 1 line). Expand
 // lives on a separate button so the text itself stays selectable.
@@ -488,20 +516,20 @@ function stopNow(sc, spec) {
         var refund = 0;
         sts.forEach(function (s) { if (s.credits_refunded) refund += s.credits_refunded; });
         return {
-          cancelled: sts.some(function (s) { return s.cancelled !== false; }),
+          cancelled: sts.some(function (s) { return s.cancelled === true; }),
           credits_refunded: refund || undefined
         };
       })
     : window.kolbo.callTool(spec.tool, spec.args).then(function (r) { return structured(r) || {}; });
-  call.then(function (st) {
-    if (st.cancelled === false) {
-      // Already terminal — let the normal poll path report the real outcome
-      // instead of claiming a cancel that did not happen.
-      cancelRequested = false;
-      renderStopButton(sc);
-      return schedulePoll(sc);
-    }
-    renderCancelled(st.credits_refunded);
+    call.then(function (st) {
+      if (!st || st.cancelled !== true) {
+        // Empty host ack used to land here as {} and the card painted
+        // cancelled while the job kept running. Only an explicit cancel counts.
+        cancelRequested = false;
+        renderStopButton(sc);
+        return schedulePoll(sc);
+      }
+      renderCancelled(st.credits_refunded);
   }).catch(function () {
     cancelRequested = false;
     renderStopButton(sc);
@@ -608,7 +636,12 @@ function poll(sc) {
       var done = Object.assign({}, sc, r, {
         phase: 'completed',
         urls: r.urls || st.urls || [],
-        credits_used: st.credits_used != null ? st.credits_used : sc.credits_used
+        credits_used: st.credits_used != null ? st.credits_used : sc.credits_used,
+        // Status structuredContent used to set open_url:undefined and wipe the
+        // session deep-link the generating card already had.
+        open_url: (sc && sc.open_url) || r.open_url,
+        session_id: (sc && (sc.session_id || sc.sessionId)) || r.session_id || st.session_id,
+        project_id: (sc && (sc.project_id || sc.projectId)) || r.project_id || st.project_id
       });
       state = done;
       el('credits').textContent = done.credits_used != null ? fmtCredits(done.credits_used) : '';
@@ -652,6 +685,11 @@ function handleBatchStatus(sc, st) {
   if (!st.all_done) return schedulePoll(sc);
 
   var scenes = [], failedCount = 0, credits = 0, haveCredits = false, allUrls = [];
+  // get_generation_status resolves model_name/model_icon into EACH result
+  // (addDisplayNames in generate.js) — sc is only the submit-time guess
+  // (usually "Smart Select"). Every id in one batch ran the same model, so the
+  // first resolved one is enough to replace the guess on the finished card.
+  var resolved = {};
   gens.forEach(function (g, i) {
     var r = g.result || g;
     var urls = (r && r.urls) || [];
@@ -659,6 +697,11 @@ function handleBatchStatus(sc, st) {
     allUrls = allUrls.concat(urls);
     var c = g.credits_used != null ? g.credits_used : (r.credits_used != null ? r.credits_used : null);
     if (c != null) { credits += c; haveCredits = true; }
+    if (!resolved.model_name && r.model_name) {
+      resolved.model = r.model;
+      resolved.model_name = r.model_name;
+      resolved.model_icon = r.model_icon;
+    }
     scenes.push({
       scene_number: i + 1,
       title: (sc.prompts && sc.prompts[i]) || '',
@@ -668,7 +711,7 @@ function handleBatchStatus(sc, st) {
   });
   if (!scenes.length) return renderError('All ' + gens.length + ' generations failed');
 
-  var done = Object.assign({}, sc, {
+  var done = Object.assign({}, sc, resolved, {
     phase: 'completed', kind: 'scenes', batch: true, scenes: scenes, urls: [],
     credits_used: haveCredits ? credits : sc.credits_used
   });
@@ -902,10 +945,14 @@ function renderBatchGrid(sc) {
         dlBtnHTML(it.url) + '</div>';
     }).join('') + '</div>';
   wireDlButtons(el('stage'));
+  // In-widget popup, not the host round-trip focusMedia() uses — a batch grid
+  // tile has no visible full-size image otherwise, so a host that never resolves
+  // requestDisplayMode() (or drops window.open after the async round trip eats
+  // the click's user-activation window) leaves the click doing nothing at all.
   Array.prototype.forEach.call(el('stage').querySelectorAll('[data-focus]'), function (cell) {
     var it = items[+cell.getAttribute('data-focus')];
     if (it.type !== 'image') return; // <video controls> owns its own clicks
-    cell.onclick = function () { focusMedia(it.url); };
+    cell.onclick = function () { openPeek(it.url, 'image', it.label); };
   });
   renderActions(sc);
   window.kolbo.notifySize();
@@ -949,7 +996,7 @@ function renderStatusGrid(sc) {
   Array.prototype.forEach.call(el('stage').querySelectorAll('[data-focus]'), function (cell) {
     var it = items[+cell.getAttribute('data-focus')];
     if (it.kind !== 'image') return; // <video controls> owns its own clicks
-    cell.onclick = function () { focusMedia(it.url); };
+    cell.onclick = function () { openPeek(it.url, 'image', it.title); };
   });
   renderActions(sc);
   window.kolbo.notifySize();
@@ -1030,7 +1077,7 @@ function renderTrackingIssue(msg) {
       (state && state.generation_id ? '\\nGeneration ID: ' + state.generation_id : ''));
   };
   el('tracking-open').onclick = function () {
-    window.kolbo.openLink((state && state.open_url) || 'https://app.kolbo.ai');
+    window.kolbo.openLink(kolboUrl(state));
   };
   window.kolbo.notifySize();
 }
@@ -1100,7 +1147,7 @@ function renderActions(sc) {
   el('actions').innerHTML = a.join('');
 
   bind('btn-download', function () { window.kolbo.openLink(downloadUrl(currentUrl())); });
-  bind('btn-open', function () { window.kolbo.openLink(state.open_url || 'https://app.kolbo.ai'); });
+  bind('btn-open', function () { window.kolbo.openLink(kolboUrl(state)); });
   bind('btn-recreate', function () {
     window.kolbo.sendMessage('Recreate this with the same settings' +
       (state.model ? '\\nModel: ' + state.model : '') +
@@ -1195,7 +1242,10 @@ function completedFromPlain(sc) {
       aspect_ratio: originArgs.aspect_ratio,
       quality: originArgs.quality
     },
-    urls: sc.urls || []
+    urls: sc.urls || [],
+    session_id: sc.session_id || originArgs.session_id,
+    project_id: sc.project_id || originArgs.project_id,
+    open_url: sc.open_url
   });
 }