@kolbo/mcp 1.81.0 → 1.81.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.81.0",
+  "version": "1.81.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@fccda44, the single source of truth.
+This tree is mirrored from kolbo-code@6836af5, 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.9.0
+version: 0.9.6
 name: kolbo
 description: |
   Generate, edit, analyze, and direct creative media through Kolbo AI: images,
@@ -20,7 +20,29 @@ allowed-tools: Bash, Read, Write, Edit
 
 You have direct access to the Kolbo AI creative platform via MCP tools (auto-configured by `kolbo auth login`). Use them to generate and deliver real content — do NOT just describe what you would create.
 
-> 🚫 **Don't dump generated URLs as bare text or markdown links in chat** — the UI already renders artifacts as a gallery tile + canvas. Refer by description ("the rainy scene"), store URLs in `.kolbo/production.md`. INLINE `![](url)` images ARE allowed for catalog-style replies (per-item thumbs in numbered lists).
+> 🚫 **Don't dump generated URLs as bare text or markdown links in chat** — the UI already shows results in **Library** (right panel) and on the generation card. Refer by description ("the rainy scene"), store URLs in `.kolbo/production.md`. INLINE `![](url)` images ARE allowed for catalog-style replies (per-item thumbs in numbered lists).
+
+## ⚠️ Source of truth for generations (HARD RULE — read this)
+
+Agents keep getting confused because three UIs show the same job. Use this map — never invent a fourth:
+
+| Surface | What it is | Trust it for |
+|---|---|---|
+| **Library** (right panel — "This session" / "All media") | User-facing gallery of **completed** media | "Is the user's output there?" Point humans here. Finished clips/images land automatically — do **not** `list_media` / `get_media` just to verify a `generate_*` you just ran. |
+| **Chat generation card** | Progress chrome while a job is in flight | Status badge only (`Generating` / done). A **black / empty preview while Generating is NORMAL** — the iframe has nothing to paint yet. It is **not** failure, not "lost", not a reason to re-fire. |
+| **`get_generation_status`** (MCP) | Agent API for job state | Whether the server job is `completed` / `failed` / still running, and the final `urls`. This is your SoT for in-flight work — **not** the card pixels. |
+| **`.kolbo/production.md`** | Your private log across turns | Ids + URLs after success. Compaction-safe memory — not the user gallery. |
+
+**Do NOT:**
+- Treat an empty/black chat card as "generation failed" or "nothing produced".
+- Re-call `generate_*` because Library still shows a K/logo spinner tile while the job is running — that tile **is** the in-progress placeholder for the same job.
+- Call `list_media` / `get_media` / `list_session_generations` to "check if it worked" after a generate you already submitted — that burns credits/context and can pollute the session.
+- Tell the user to look at chat history for finals — tell them **Library → This session**.
+
+**Do:**
+- After `submitted` / `_timed_out`: end the turn, or one `get_generation_status(..., wait=true)`.
+- When done: say the result is in Library; log URLs to `.kolbo/production.md`.
+- If the user asks "where is it?" → Library (This session). If they ask "is it done?" and you don't have urls yet → `get_generation_status` once.
 
 This file is the **always-loaded core**: tool inventory + universal hard rules + routing index. For any model-specific prompt rules, Visual DNA workflow, production log format, marketing workflow, cost validation, etc., **Read the matching `references/` file from the index below**. Don't try to remember the rules — load the file when you need them.
 
@@ -117,23 +139,41 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 |------|---------|
 | `list_models` / `list_voices` / `check_credits` / `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. |
 | `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` / `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` |
+| `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. Always pass `search` when you know the name — that is a silent id lookup, not a catalog to show. 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 and account-wide.** At most one palette is active at a time; while it is, it strict-grades **every** image and video generation automatically, with no per-call argument. `analyze_color_palette` pulls colors out of 1-5 image URLs for free and does NOT save. `create_color_palette` defaults `is_active: true`, which activates it and deactivates any other. Per-generation opt-out: `skip_color_palette: true` on `generate_image` / `generate_image_edit` / `generate_video` / `generate_video_from_image`. |
 | `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. |
 | `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` / `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. |
+| `list_projects` / `get_project` / `move_session` | Projects: resolve a project NAME → the `project_id` you pass on generation/upload/doc calls; `get_project` returns the full description (list clips it). `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` / `rename_session` / `delete_session` / `restore_session` | Project lifecycle + session inventory. Edit name/description with `update_project` (read via `get_project` first). Rename sessions with `rename_session` — never delete+recreate. `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 |
+| `list_project_assets` / `link_project_asset` / `unlink_project_asset` / `update_project_asset` | Project CAST roster: the Visual DNAs and moodboards tagged onto a project (`@Name` / `#Name`). `update_project_asset` writes each tagged DNA's identity description and/or its project-scoped purpose note. Never unlink+relink to edit. |
+| `create_moodboard` / `update_moodboard` / `delete_moodboard` | Moodboards from image URLs → AI master style prompt → pass `moodboard_id` to generation tools. Edit with `update_moodboard`; never delete+recreate. |
 | `clone_voice` / `import_elevenlabs_voice` / `delete_voice` | Custom voices (clone CHARGES CREDITS — confirm first; new voices show in `list_voices`) |
 | `trim_video` | Frame-accurate trim of a Kolbo-hosted video (tool waits and returns the URL). `edit_video` also gained `remove_background`. |
 | `create_doc` / `list_docs` / `get_doc` / `update_doc` / `share_doc` / `delete_doc` | AI Docs (Magic Pad): YOU author full HTML documents (plans, briefs, scripts, research) saved into the user's project, editable in the Kolbo app. `share_doc` returns a public link. `update_doc` content replaces the WHOLE doc — `get_doc` first. |
 | `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. |
 
+## ⚠️ Edit in place — never delete+recreate (HARD RULE — always on)
+
+Existing Kolbo objects keep a stable id. Generations, `@Name` / `#Name` bindings, share links, and teammates already point at that id. Deleting and making a new one orphans those links and throws away the stored analysis.
+
+| What changed | Tool |
+|---|---|
+| Visual DNA name, description, stills, sheet, type, attributes | `update_visual_dna` |
+| Project-cast DNA description or purpose note | `update_project_asset` |
+| Moodboard name, style notes, images | `update_moodboard` |
+| Project name or description | `get_project` then `update_project` |
+| Project cast membership | `link_project_asset` / `unlink_project_asset` (list first) |
+| Session title | `rename_session` |
+| Custom agent name / persona | `update_agent` |
+| AI Doc title / content | `get_doc` then `update_doc` |
+
+`delete_*` is only for objects the user asked to remove.
+
 ## ⚠️ 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.
@@ -149,6 +189,8 @@ Before `generate_elements` / any DNA video: for each id in `visual_dna_ids`, con
 
 Resolve names with `list_visual_dnas` first. Full binding rules: `references/workflows/visual-dna.md`.
 
+**Every still on a DNA can reach the model.** Kolbo now sends all of a DNA's reference images that fit the model's image-slot cap (user uploads first, then one still per DNA, then leftovers round-robin). If a DNA only gets one leftover slot and has no real character sheet, unused stills become a white grid. Mixed-vibe stills or environment photos that contain a main character will confuse the generation — keep each DNA surgically clean. Create-and-pack rules: `references/workflows/visual-dna.md`.
+
 ## ⚠️ `enhance_prompt` — leave it OFF (HARD RULE)
 
 **Never pass `enhance_prompt: true` unless the user asked for it in words.** It is
@@ -198,7 +240,7 @@ Do **not** call `generate_*` / `generate_elements` / `generate_image_edit` until
 
 `generate_elements`, Seedance 2 / 2.5, WAN, MiniMax H3, Gemini, and any Visual DNA video share **one** compile shape — the Locked Intro in `references/models/seedance.md`. Load `elements-prompting` first (craft, `@Image N` mapping, eight elements), then compile:
 
-`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 — …`
+`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.
 
@@ -248,9 +290,13 @@ A user-named tool — in any language — overrides every other rule. Recognized
    - Auto-select → **only when no model was named on this task**. Then pick from "Auto-selectable" (models with a `summary`). Cheapest fit. Prefer `[RECOMMENDED]` when cost is similar.
    - Never auto-select from "Named-only" section.
 5. **Validate inputs** against model caps — see `references/workflows/cost-and-validation.md`.
-6. **How calls work**: each tool blocks until generation is fully complete. Images: seconds. Video: minutes. Multiple tool calls in one response run concurrently. On hosts with live widgets the tool instead returns `submitted` instantly — the card updates on its own; you only need `get_generation_status` when a follow-up step needs the output URLs.
-7. **Checking status — NEVER poll in a loop**: `get_generation_status` takes `wait=true` (blocks server-side until done, ~3 min) and `generation_ids` (check MANY generations in ONE call — returns `all_done` + which are still running). One `wait=true` call replaces any polling loop. If it comes back with some still processing, call it ONCE more with `wait=true` and the remaining ids.
-8. **Share the URL** after success. Never fabricate URLs.
+6. **How calls work**: each tool blocks until generation is fully complete. Images: seconds. Video: minutes. Multiple tool calls in one response run concurrently. On hosts with live widgets the tool instead returns `submitted` (or `_timed_out`) instantly — the card updates on its own.
+7. **🛑 After `submitted` / `_timed_out` — END THE TURN (credit guard)**: Do **not** keep thinking, writing skills, editing files, or planning "next steps" while a generation is still running. That burns the user's coding/chat credits for nothing. Either:
+   - **Stop immediately** after telling the user it's generating in Library / the card above (preferred when you do not need the output URLs yet), OR
+   - If the **next** required step needs those URLs, call `get_generation_status` **once** with `wait=true` (and `generation_ids` for a batch) as the **only** follow-up — no parallel Write/Edit/Think while it waits.
+   - A black preview on the chat card is expected until URLs exist — not a signal to retry.
+8. **Checking status — NEVER poll in a loop**: `get_generation_status` takes `wait=true` (blocks server-side until done, ~3 min) and `generation_ids` (check MANY generations in ONE call — returns `all_done` + which are still running). One `wait=true` call replaces any polling loop. If it comes back with some still processing, call it ONCE more with `wait=true` and the remaining ids.
+9. **Share the URL** after success. Never fabricate URLs.
 
 Model types for `list_models`: `text_to_img`, `image_editing`, `text_to_video`, `img_to_video`, `draw_to_video`, `video_to_video`, `elements`, `firstlastgenerations`, `lipsync-image`, `lipsync-video`, `music_gen`, `text_to_speech`, `text_to_sound`, `stt`, `text`, `3d_text_to_model`, `3d_image_to_model`, `3d_multi_image_to_model`, `3d_world`.
 
@@ -298,7 +344,8 @@ Full tables + formulas in `references/workflows/cost-and-validation.md`. Quick r
 ## Rate Limiting & Batch Generation
 
 - `generate_image`: 30/min. All other generation tools: 10/min per type. 300/min global. `upload_media`: 300/min, no credit cost.
-- **⚠️ NEVER re-fire a generation you already called.** Aborted / timed-out calls still process server-side. Run `get_generation_status` (with `wait=true`) before retrying.
+- **⚠️ NEVER re-fire a generation you already called.** Aborted / timed-out / `submitted` calls still process server-side. Finish with `get_generation_status` (`wait=true`) — never a second `generate_*`. A black chat card or Library K-tile is not a missing job.
+- **⚠️ NEVER keep working while a generation is in flight.** After `submitted` / `_timed_out`, end the turn or block on one `wait=true` status call. Writing production.md / skills / "merge decisions" while the card spins wastes coding credits.
 - **Tracking a batch**: check ALL in-flight ids in ONE `get_generation_status` call with `generation_ids` + `wait=true`. Read `all_done` / `still_processing` from the response — do not check ids one by one, and never re-call without `wait`.
 - **Batch ≤10 items**: output ALL tool calls in one response — they run concurrently.
 - **Bulk >10 items**: real-world ceilings — `generate_image` 8–10 in-flight, image-edit 5–8, video tools 3–5, `generate_video_from_video` 3, music/speech/sound 5–8. Fire one batch → wait → fire next. Persist every `generation_id` in `.kolbo/production.md`.
@@ -367,9 +414,9 @@ A generation can fail three ways. Treat ALL as failure:
 Chat renders markdown natively. `![alt](url)` = inline image. `[label](url)` = labeled link with preview.
 
 - **Catalog-style replies** (numbered lists of characters / scenes / products): embed `![alt](url)` so each item shows inline.
-- **Conversational replies** ("4 shots ready"): keep prose short; canvas chip already shows gallery.
+- **Conversational replies** ("4 shots ready"): keep prose short; Library already shows the gallery.
 
-Avoid bare URL dumps and HTML `<table>` grids — canvas already provides a gallery.
+Avoid bare URL dumps and HTML `<table>` grids — Library already provides a gallery.
 
 **After `generate_creative_director` completes** — share results as individual URLs, one per scene. Do NOT create an HTML grid artifact.
 

package/skill/VERSION

@@ -1 +1 @@
-0.9.0
+0.9.6

package/skill/references/models/seedance.md

@@ -15,8 +15,15 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 - **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.
-- **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.
-- **Then the Locked Intro** — `[GLOBAL LOOK]` / `[CAST]` / `[LOCATION]` — before any shot. A one-liner `same character throughout` is not a character lock.
+- **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:
+  1. `N connected cinematic shots, Xs total, AR, Multishot ON`
+  2. `Total: Xs / N shots / AR`
+  Then Locked Intro, then `SHOT N — 0:00–0:02 — Size / camera` beats whose ranges **sum exactly to Xs**. Last line repeats `Total: Xs / N shots / AR`.
+  - Example (15s / 6 shots): `6 connected cinematic shots, 15 seconds total, 16:9, Multishot ON` + `Total: 15s / 6 shots / 16:9`
+  - UGC / phone vertical: `N connected phone shots, Xs total, 9:16, Multishot ON` (never the word "cinematic").
+  - A prompt with only shot body and no Total / Multishot header is a **failed turn** — rewrite before calling `generate_*`.
+- **MCP `duration` must match the Total line.** Pass `duration: X` (whole seconds) on `generate_video` / `generate_elements` / `generate_video_from_image` equal to the `Xs` in `Total: Xs / …`. Mismatch = wrong-length clip.
+- **Then the Locked Intro** — `[GLOBAL LOOK]` / `[CAST]` / `[LOCATION]` (+ LOCATION MAP / CONTINUITY / PHYSICS for multi-shot) — 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.
@@ -32,11 +39,11 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 ## 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.
+After the Total lines, every multi-shot prompt — and any piece with recurring people or a recurring place — opens with the 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
+Total: Xs / N shots / AR
 
 [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>.
@@ -48,14 +55,37 @@ PROP: recurring object.
 [LOCATION]
 Place in materials + light + color field. Blocking. Background LIFE.
 
+[LOCATION MAP]
+Named seats / sides in SCREEN language (screen-left armchair, center couch, door camera-left).
+
+[CONTINUITY – LOCKED ACROSS EVERY CUT]
+Axis / camera side of the line. Screen direction. Eyelines. Floor props stay. Which hand holds what. No teleport.
+
+[PHYSICS]
+Weight into furniture, props resting, cloth/hair settle, no float.
+
 SHOT 1 — 0:00–0:02 — Medium / camera position
 (physical verbs, timed acting, quoted dialogue)
-…
+SHOT 2 — 0:02–0:05 — …
+… (ranges MUST sum to Xs)
 Total: Xs / N shots / AR
+POSITIVE LOCKS: <2–4 sentences restating positions / mouth / optical signature>
 ```
 
 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`.
 
+## OUTPUT CONTRACT (WINS — same as help widget)
+
+ONE fenced prompt. Required shape or the turn failed:
+1. `N connected cinematic shots, Xs total, AR, Multishot ON`
+2. `Total: Xs / N shots / AR`
+3. GLOBAL LOOK → CAST → LOCATION → LOCATION MAP → CONTINUITY → PHYSICS (dense, before any shot)
+4. `SHOT 1 — 0:00–0:02 — …` through SHOT N; timecodes sum to Xs; continuity bridge after SHOT 1
+5. Closing `Total: Xs / N shots / AR` + short POSITIVE LOCKS
+6. Tool call `duration` = Xs
+
+FORBIDDEN: omitting Total / Multishot; "same character throughout" as the only lock; one fence per shot; `[0s]`/`[3s]` stubs; splitting a ≤15s story into multiple generations unless the user asks.
+
 ## The 5 Formats
 
 ### 1. Transformations (highest-performing format)

package/skill/references/models/seedance25.md

@@ -23,21 +23,45 @@ Load this file when the user wants a **Seedance 2.5** video (they said "2.5" / "
 - **Up to 50 reference medias / Visual DNA mentions** (`@Name`, `@ImageN`, `#Moodboard`). 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.
 
-## Locked Intro (DEFAULT — same shape as Seedance 2)
+## Universal Rules (HARD — same as help widget OUTPUT CONTRACT)
+
+- **First lines ALWAYS declare shot structure** (text-to-video / Elements / reference gen — NOT video-edit):
+  1. `N connected cinematic shots, Xs total, AR, Multishot ON`
+  2. `Total: Xs / N shots / AR`
+  Example: `12 connected cinematic shots, 30 seconds total, 16:9, Multishot ON` + `Total: 30s / 12 shots / 16:9`
+  UGC phone: `N connected phone shots, Xs total, 9:16, Multishot ON` — never the word "cinematic"; restate `9:16 vertical phone frame` in every shot.
+- **Last line repeats** `Total: Xs / N shots / AR` + short POSITIVE LOCKS.
+- **Shot timecodes MUST sum to Xs.** `SHOT 1 — 0:00–0:02` … through SHOT N ending at Xs. Never `[0s]` / `[3s]` stubs.
+- **MCP `duration` = Xs** on the generate call. Mismatch is a failed turn.
+- Duration range **4–30s**; shot count **≤30** in one generation. Do not split a ≤30s story into multiple 10s clips unless the user asks.
+- Omit Total / Multishot / shot-count headers only for **video editing** (source duration locked) — use Edit Goal blocks instead.
 
-After the Total line, every multi-shot cinematic opens with:
+## Locked Intro (DEFAULT — same shape as Seedance 2)
 
 ```
+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]
 [LOCATION]
+[LOCATION MAP]
+[CONTINUITY – LOCKED ACROSS EVERY CUT]
+[PHYSICS]
+
+SHOT 1 — 0:00–0:02 — Medium / camera position
+…
+Total: Xs / N shots / AR
 ```
 
-then timecoded `SHOT N — 0:00–0:02 — Medium / camera position` beats. Full skeleton, acting rules, and optical craft: `models/seedance.md`.
+Full acting / continuity craft: `models/seedance.md`. Do not skip the Total lines or the three look/cast/location blocks. Do not restack GLOBAL LOOK inside shots.
+
+2.5 is where this format earns its keep: 15 shots timed to 30s, ~5k characters, one locked look so every cut matches camera / grade / cast.
 
-2.5 is where this format earns its keep: 15 shots timed to 30s, ~5k characters, one locked look so every cut matches camera / grade / cast. Do not skip the three blocks. Do not restack GLOBAL LOOK inside shots.
+## OUTPUT CONTRACT (WINS — mirror of help widget)
 
-UGC / phone vertical (full craft: `workflows/ugc-smartphone.md`): NEVER write "cinematic". GLOBAL LOOK is phone-native. Use `N connected phone shots, Xs total, 9:16, Multishot ON` and restate `9:16 vertical phone frame` inside every shot.
+ONE fenced prompt. Missing Total / Multishot / summing timecodes / matching `duration` = failed skill turn.
+FORBIDDEN: "same character throughout" as the only lock; one fence per shot; claiming you followed the skill while omitting GLOBAL LOOK / CAST / LOCATION / Multishot ON.
 
 ## Prompt length
 

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

@@ -4,7 +4,9 @@ Load this file when starting a multi-step production, or before any continuation
 
 ## Why It Exists
 
-Every URL, id, and brief produced by a Kolbo MCP tool MUST be recorded in `.kolbo/production.md` in the user's workspace. This file — not chat history — is your source of truth for prior artifacts: URLs scattered across `tool_result` blobs are unreliable to re-scan and disappear entirely on context compaction. If the user named a model, write that name into `## 🎯 Now` and keep using that family on every follow-up — compaction is not permission to cheapest-swap.
+Every URL, id, and brief produced by a Kolbo MCP tool MUST be recorded in `.kolbo/production.md` in the user's workspace. This file is **your** (agent) source of truth for prior artifacts across turns — not chat history (unreliable / compacted) and not a substitute for the user's **Library** gallery. URLs scattered across `tool_result` blobs are unreliable to re-scan and disappear entirely on context compaction. If the user named a model, write that name into `## 🎯 Now` and keep using that family on every follow-up — compaction is not permission to cheapest-swap.
+
+**User vs agent SoT:** finished media for the human → **Library → This session**. Job state while in flight → `get_generation_status`. Your memory → this file. Chat cards are progress UI only.
 
 ## When to READ it
 

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

@@ -98,8 +98,19 @@ the user names 4K or GPT Image 2.
 Do not skip the sheet and `create_visual_dna` from a portrait. The sheet is the
 asset; the DNA stores it.
 
+**Purity (HARD).** Every still on a DNA is packed into later generations (all
+slots the model has, or a white grid if only one slot is left). Keep each
+profile surgically clean: one identity, one vibe. Environment / location
+stills must not contain a main character or recognizable hero face (anonymous
+crowd is OK). Character stills must not contain a second lead. Separate
+states (day/night, clean/bloody) are separate DNAs. Full pack + purity
+rules: `references/workflows/visual-dna.md`.
+
 Then `create_visual_dna` with the sheet as the reference and the matching
 `dna_type`. Name each DNA in the exact form it will be tagged with later.
+Immediately `link_project_asset` it onto the working project and
+`update_project_asset` with the identity `description` plus a purpose `note`.
+Do not leave a cast DNA undescribed on the project roster.
 
 ## 3. Confirm — a labeled GATE, then wait
 

package/skill/references/workflows/troubleshooting.md

@@ -26,6 +26,10 @@ 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"
+
+**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.
+
 ## "Rate limited" (429 errors)
 
 Wait 60s for the window to reset, retry only the failed calls. For batch image work prefer `generate_creative_director` over multiple `generate_image` calls. Full rate-limit details + retry sequence: see SKILL.md "Rate Limiting & Batch Generation".
@@ -47,6 +51,8 @@ prompt loses.
 
 `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,13 +8,40 @@ 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; never pass 5+). Optionally video and audio.
+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.
 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`.
+5. **Edit in place** with `update_visual_dna` (name, `prompt_helper`, stills, `character_sheet_url`, type, attributes). NEVER `delete_visual_dna` + `create_visual_dna` to rename, restyle, swap stills, or change a description — the old id is what generations and `@Name` already bind to. Providing `images` replaces the whole still set and re-analyzes; omit images to keep them.
+6. **Tag it onto the project cast.** After `create_visual_dna` for named-project work, call `link_project_asset` (`asset_type: "visual_dna"`) then `update_project_asset` with a real `description` (the DNA identity text the roster injects) and a `note` (what this asset is for in THIS project). List first with `list_project_assets`. Same for moodboards (`asset_type: "moodboard"`, note only — style edits stay on `update_moodboard`). Never unlink+relink to change a description.
 
 **Server-side auto-routing:** passing `visual_dna_ids` is enough — the server expands the DNA's reference images and auto-routes the selected text-to-image model to its image-editing variant (e.g. `nano-banana-2` → `nano-banana-2-image-editing`). You do NOT need to also pass `reference_images` when using DNA. If the chosen model has no edit variant at all, the server falls back to using the DNA's images as style references on the t2i model. DNA payloads are never silently dropped.
 
+## How those images actually reach the model (packing)
+
+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.
+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.
+
+So every image you store on a DNA can appear in the generation — as its own slot or as a cell in that grid. Unused stills are no longer ignored.
+
+## Purity — what may live on a DNA (HARD)
+
+Because leftover stills now travel with the DNA, a junk-drawer profile poisons every generation that uses it.
+
+- **One DNA = one identity + one vibe.** All stills must feel like the same person / place / product / look. Do not mix two lighting moods, two eras, or two art directions on one profile.
+- **Character DNA:** only that character. No second hero, no "also include the friend." Extra people only as **anonymous crowd / background extras** — never a named, readable, or story-important second face.
+- **Environment / scene / location DNA:** architecture, light, materials, geography. Empty, or with anonymous crowd / atmosphere extras, is OK. **Do not put a main character, hero, or recognizable face that is not supposed to live in that place** — they will bleed into every shot that uses the location.
+- **Product DNA:** only that product (angles, materials, label). No hand-model hero unless the product is worn-on-body and the body is generic / faceless.
+- **Style DNA:** one art direction. A style board applied to varied subjects is OK. Two conflicting looks in one style DNA is not.
+- **Separate states = separate DNAs** (clean vs bloodied, day vs night, intact vs broken). Do not dump both into one profile.
+- When **generating** stills for a DNA, lock subject + wardrobe/era/palette in the prompt and explicitly forbid extra heroes / wrong-location characters.
+- If the user hands you mixed refs, pick the stills that share vibe + identity (or generate clean ones). Do not register a junk drawer. Max 4 extra images on `create_visual_dna` still applies — those 4 are **all consumed**.
+
 ## ⚠️ Pre-flight: Verify the Visual DNA Exists Before Using It (MANDATORY)
 
 NEVER reference a Visual DNA by name, role, or assumed identity without first confirming it exists in the user's library. This is a frequent failure mode: the user mentions a character ("אסתר", "Maya", "the model from before"), the agent assumes a matching Visual DNA exists, calls `generate_image` / `generate_elements` with a guessed or fabricated `visual_dna_ids` value, and the generation fails or produces the wrong identity.
@@ -36,11 +63,12 @@ When the user says "use the model אסתר" but you've only created a DNA for "
 
 ## ⚠️ Don't re-fetch / re-list your own outputs (CRITICAL)
 
-After a generation tool returns its URLs, those URLs are **already** in the canvas (the desktop app's gallery panel) and in `.kolbo/production.md`. Do **NOT** call `list_media`, `get_media`, `get_media_stats`, `list_visual_dnas`, or `chat_send_message` with `media_urls` on those URLs just to "verify" or "fetch thumbnails of the results":
+After a generation tool returns its URLs, those URLs are **already** in **Library** (right panel — This session) and in `.kolbo/production.md`. Do **NOT** call `list_media`, `get_media`, `get_media_stats`, `list_visual_dnas`, or `chat_send_message` with `media_urls` on those URLs just to "verify" or "fetch thumbnails of the results":
 
 - It burns credits and time for zero new information.
-- Every such tool call streams partial output into the session, which forces the desktop canvas to re-evaluate (visible flicker on the gallery tiles).
+- Every such tool call streams partial output into the session, which forces Library to re-evaluate (visible flicker on the gallery tiles).
 - The thumbnails returned by `list_media` / `get_media` are the SAME asset you just generated.
+- A black chat generation card while `Generating` is normal — do not treat it as missing output.
 
 **Only call list/get media tools when:**
 - The user explicitly asks ("what do I have in my library?", "show me my old DNAs").
@@ -216,10 +244,16 @@ Read `max_visual_dna` from `list_models` for the exact cap, AND `supports_visual
 - `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.
+**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.
+
 ## When to Use
 
 - User wants the same character across multiple **images** or a campaign → `generate_image` / `generate_creative_director` with `visual_dna_ids`
@@ -251,7 +285,7 @@ Custom instructions live on the **image preset**. Resolve it silently, then gene
 
 1. `list_presets({ type: "image", search: "headless" | "bible" | "character sheet" | "location" | "product" })`
 2. Pass the exact `id` as `preset_id` on `generate_image` (2K or 4K, never 1K; 4K for bible / high-detail / when named)
-3. Show the sheet → GATE → `create_visual_dna { name, images, character_sheet_url }`
+3. Show the sheet → GATE → `create_visual_dna { name, images, character_sheet_url }` (or `update_visual_dna` with `character_sheet_url` when the DNA already exists)
 
 | Search | When |
 |---|---|