@kolbo/mcp 1.81.1 → 1.81.4

package/README.md

@@ -58,9 +58,12 @@ Or add the config by hand — this block is identical for every MCP client and c
 
 Restart your app, then ask it to generate something. The first time, a Kolbo login opens in your browser — click **Allow** (no API key to create). _Prefer an API key? Create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer) and add `"env": { "KOLBO_API_KEY": "kolbo_live_..." }` to the block above._
 
-### Browser-only (claude.ai / ChatGPT): the connector
+### Browser-only (claude.ai / ChatGPT / Codex): connector + zip
 
-No install at all — add the custom connector **`https://api.kolbo.ai/mcp`** under Settings → Connectors, then Connect → log in → Allow. Great for generating from text or URLs; to upload your own local files, use the config install above (it runs on your machine).
+1. Add the custom connector **`https://api.kolbo.ai/mcp`** under Settings → Connectors, then Connect → log in → Allow.
+2. Download **[`kolbo.zip`](https://github.com/Zoharvan12/kolbo-skills/raw/main/kolbo.zip)** and upload it as a skill (Claude.ai: Settings → Features → Skills; ChatGPT/Codex: Settings → Skills). Codex CLI: unzip into `~/.codex/skills/`.
+
+The zip is the canonical routing skill. Without it the tools still work, but the model will not load Seedance / Visual DNA / filmmaking rules.
 
 ### Optional upgrade: add the Kolbo skill for slash-commands + smart routing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.81.1",
+  "version": "1.81.4",
   "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@00aade6, the single source of truth.
+This tree is mirrored from kolbo-code@a463d99, 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.3
+version: 0.9.7
 name: kolbo
 description: |
   Generate, edit, analyze, and direct creative media through Kolbo AI: images,
@@ -20,11 +20,9 @@ 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).
 
-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.
-
-Users never see the bundled prompting skills. If you skip them, they get a lazy one-line prompt. **Loading is mandatory, not optional flavor.**
+This file is the **always-loaded core**: tool inventory + universal hard rules + routing index — for model-specific prompt rules, workflows, cost validation, etc., Read the matching `references/` file from the index below; loading is mandatory, not optional flavor (users never invoke the bundled skills themselves — skipping them yields a lazy one-line prompt).
 
 ## Step 0 — Bootstrap
 
@@ -32,26 +30,33 @@ Once per conversation, before any other Kolbo tool call:
 
 1. **Run `check_credits`.** If it fails with "Session expired" / "Not authenticated", ask the user to run `kolbo auth login` (or their branded CLI command like `sapir auth login`) and reload the editor.
 2. **If `list_models` returns empty**, MCP isn't wired — same fix.
-3. Use the balance ONLY for the low-balance check at this moment. **Never quote a "credits remaining" number later in the session** — coding/chat usage also deducts credits, so any remembered or computed balance is stale. Report only what each generation cost (`credits_used`); if the user asks what's left, run `check_credits` fresh right then.
+3. Use the balance ONLY for the low-balance check at this moment (see the "credits remaining" rule in the brief section below).
 
 If the user is on a whitelabel build (`sapir`, etc.), they must use their branded command — not `kolbo`. See `references/workflows/troubleshooting.md`.
 
-## 🎬 Confirm the Creative Brief BEFORE Generating (CRITICAL — read first)
+## 🎬 Confirm the Creative Brief & Cost BEFORE Generating (CRITICAL — read first)
 
 Never fire a paid generation the moment the user says "make X". First **present the brief back as a confirmation the user can change** — this is the single most important interaction. It gives the user control over what gets created and what it costs, instead of silently spending credits on defaults.
 
 **Before ANY paid image / video / music / speech / 3D generation**, unless the user has *explicitly* dictated every key parameter in this message, ask ONE labeled question (the UI renders it as an options card) confirming:
 
-- **Model** — your recommended pick as the default option, plus 1–2 alternatives (with their credit cost).
+- **Model** — your recommended pick as the default option, plus 1–2 alternatives (with their credit cost). Suggest a cheaper alternative if one fits.
 - **Aspect ratio** — e.g. `1:1 / 9:16 / 16:9` (offer the sensible default first).
 - **Count** — how many (1 / 4 / …).
 - **Resolution / quality / duration** — where the model supports it.
 - **Creative direction** — style / mood / scene, when the user was vague ("4 cats" → offer style options: photoreal / illustrated / cinematic / surprise-me).
 - **Credit cost** — state the total (`✦ N credits`) right in the question so cost is never a surprise.
 
-Then generate **only** with the confirmed parameters. If the user changes an option, use the change. This mirrors the approval-card flow: propose → let them adjust → confirm → generate.
+Then generate **only** with the confirmed parameters. If the user changes an option, use the change. This mirrors the approval-card flow: propose → let them adjust → confirm → generate. Never fire on defaults the user didn't choose.
+
+**Only skip the brief/cost confirmation when** the user's message already pins model + aspect + count + creative direction (e.g. "generate 4 photoreal tabby cats, 1:1, z-image/turbo") — then just state the cost one-liner and fire. A low credit cost is **not** a reason to skip: cheap ≠ no-confirmation. What matters is whether the user actually chose the parameters.
 
-**Only skip the brief confirmation when** the user's message already pins model + aspect + count + creative direction (e.g. "generate 4 photoreal tabby cats, 1:1, z-image/turbo") — then just state the cost one-liner and fire. A low credit cost is **not** a reason to skip: cheap ≠ no-confirmation. What matters is whether the user actually chose the parameters.
+**Cost rules** (full tables + formulas in `references/workflows/cost-and-validation.md`):
+
+- **Video/lipsync `credit` is per-SECOND, not per-clip**: `total = credit × duration`. This is the universal rule for video/firstlast/elements/motion_graphic/cast types, not a per-model exception — `list_models` states it inline now. The one carve-out is a model with `flat_credit_by_resolution` set.
+- **Batch totalling 100+ credits**: run `check_credits` first.
+- **Quote real cost**: after firing, log `credits_used` (from the tool result) to `.kolbo/production.md` — never `base × count`.
+- **Never state "credits remaining" from arithmetic** (opening balance − generation costs). Coding/chat usage deducts credits too, so the math is always wrong. Report cost only; if the user asks for their balance, call `check_credits` fresh at that moment.
 
 For multi-scene / batch work this pairs with `generate_creative_director` (see below) — still confirm the brief first.
 
@@ -80,11 +85,13 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 | Generate **brand product imagery** (studio shot, lifestyle, Pinterest pin, hero banner, carousel, ad pack, virtual try-on, conceptual, restyle) | `references/workflows/product-photoshoot.md` |
 | Generate **marketplace listing cards** (Amazon main + secondary + A+ content) | `references/workflows/marketplace-cards.md` |
 | Use **Visual DNA** / character consistency / `@name` syntax | `references/workflows/visual-dna.md` |
+| Use **Color DNA** / brand palette grading | `references/workflows/color-dna.md` |
 | Start or continue a **multi-step production** (storyboard → scenes → final cut) | `references/workflows/production-log.md` |
 | **Transcribe** or **analyze** audio/video | `references/workflows/transcription.md` |
 | **Split a soundtrack into layers** — remove/isolate speech, strip narration, instrumental bed, stems for dubbing | `references/workflows/audio-stems.md` |
 | **Scrape brand/product info** before generating + persist as `.kolbo/brand-kits/<slug>.md` | `references/workflows/research-first.md` |
 | Browse, manage, or present existing **media library** items | `references/workflows/media-library.md` |
+| Run a **client review / approval loop** — share a cut for feedback, timestamped comments, versions (v1→v2), approve / request-changes, guest links | `references/workflows/review-collections.md` |
 | Confirm **cost** or validate **resolution / aspect / duration** against model caps | `references/workflows/cost-and-validation.md` |
 | Hit an **auth / MCP / 429** issue | `references/workflows/troubleshooting.md` |
 
@@ -118,13 +125,13 @@ 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` / `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_moodboards` / `get_moodboard` / `list_presets` | Style overlays + sheet presets — see **Preset contract** in Core Workflow. Never omit `preset_id` after claiming a preset was used. |
+| `list_color_palettes` / `analyze_color_palette` / `create_color_palette` / `update_color_palette` / `delete_color_palette` / `activate_color_palette` / `deactivate_color_palette` | **Color DNA — sticky + account-wide; at most one palette active at a time**, and while active it strict-grades **every** image and video generation automatically. Per-generation opt-out: `skip_color_palette: true`. Details: `workflows/color-dna.md`. |
 | `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Custom chat agents — reusable named personas for `chat_send_message`. The agent's `description` IS the system instruction. Resolve a name the user mentions ("use my SEO agent") to an id with `list_agents`, then pass `agent_id`. Global/preset agents are read-only; only the user's own can be updated or deleted. |
 | `search_stock_media` / `get_stock_sources` / `get_stock_categories` / `get_stock_collections` / `get_stock_asset` / `analyze_script_for_stock` / `import_stock_asset` | Stock library (free, no credits) — EXISTING photos / videos / 3D / SFX / music. For stock **music** use `search_stock_media` with `mediaType: "music"` (semantic vibe query, e.g. "uplifting corporate background") → `get_stock_asset` for downloads. The older `*_music_library` tools are deprecated adapters over this — prefer the stock tools, except for the licensed-catalog tools in the next row. |
-| `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` / `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. |
+| `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** — commercially licensed catalog, not free stock; previews are **watermarked**. `acquire_clean_music_track` / `import_music_track_to_library` **CHARGES CREDITS** for the clean master — confirm with the user first + pass a stable `requestId`. Details: `workflows/media-library.md` "SYNCI licensed music". |
+| `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. 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. |
 | `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 |
 | `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. |
@@ -133,6 +140,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `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) |
+| `create_review_asset` / `add_review_version` / `set_review_status` / `create_review_comment` / `reply_review_comment` / `resolve_review_comment` / `unresolve_review_comment` / `create_review_collection` / `create_review_share_link` / `revoke_review_share_link` / `get_review_storage_usage` (+ list/get/update/delete siblings) | **Kolbo Review** — Frame.io-style client review: asset = media + appended versions (new cut = `add_review_version`, never delete+recreate), timecoded comments per version, approve/request-changes status, guest share links (no Kolbo account; comment-only unless `canSetStatus`). 5GB review storage cap. See `workflows/review-collections.md`. |
 | `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)
@@ -187,7 +195,7 @@ first, so the model renders *different words than the ones the user wrote*.
 A URL from `generate_*`, `list_media`, `get_media`, or a prior `upload_media` is **already on Kolbo CDN**. Pass that exact URL to the next tool (`reference_images` / `source_images` / `image_url` / `files`). Do **not** call `upload_media`, `create_upload_ticket`, or `media_upload_widget` on it — that copies the file a second time and wastes storage.
 
 - Hosts that are already hosted: `media.kolbo.ai`, any `*.kolbo.ai`, Kolbo DigitalOcean Spaces.
-- `upload_media` is only for a **local disk path** or an **external** (non-Kolbo) URL that the tools would 400 on.
+- `upload_media` is only for a **local disk path** or an **external** (non-Kolbo) URL — `files`/`source_images`/`image_url` reject unknown hosts with `400`; a Kolbo URL passes through as-is.
 - Same rule after compaction: pull the URL from `.kolbo/production.md` and reuse it. Never download-then-reupload.
 
 ## ⚠️ Assets Before Shots (HARD RULE)
@@ -218,7 +226,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.
 
@@ -260,7 +268,7 @@ A user-named tool — in any language — overrides every other rule. Recognized
 - Pass the exact returned `id` as `preset_id`. Never invent an id.
 
 1. **Check credits** ONCE per conversation (Step 0). Skip if already checked.
-2. **Load the matching skill** (HARD RULE above) — `skill` tool + Read the `references/` file. Do this before the first paid call in the turn.
+2. **Load the matching skill** (HARD RULE above) before the first paid call in the turn.
 3. **Discover models** with `list_models` using a `type` filter — but **skip when the user names a specific model** (this turn **or** earlier in the conversation / compaction `## Locked choices`).
 4. **Pick the model**:
    - User named one → that name is a **family lock**, not a single catalog row. Use it. Identifiers resolve leniently — `"z-image"` / `"nano banana 2"` / `"grok imagine"` auto-resolve, including to the sibling for the tool you are calling (`grok-imagine-text-to-video` on `generate_video_from_image` becomes `grok-imagine-image-to-video`). `list_models` is still authoritative for constraints, caps, and pricing — not for swapping brands.
@@ -268,17 +276,57 @@ 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. **Fire the call(s)** — then follow "⚠️ Generation lifecycle" below for waiting, status, and failure handling.
+7. **Share the result** after success — per "⚠️ Generated URLs in Chat" and the no-fabricated-URLs rule in Limitations & Safety.
 
 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`.
 
+## ⚠️ Generation lifecycle — source of truth, waiting, failures (HARD RULE — read this)
+
+**How calls work:** each generation tool blocks until the job 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.
+
+Four surfaces show the same job. Use this map — never invent a fifth:
+
+| 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 — never to chat history. Finished clips/images land automatically — do **not** call `list_media` / `get_media` / `list_session_generations` to "check if it worked" after a generate you already submitted (burns credits/context, can pollute the session). A K/logo spinner tile **is** the in-progress placeholder for the same job, not a missing one. |
+| **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. |
+
+**🛑 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_*`.
+
+**🛑 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` as the **only** follow-up, no parallel Write/Edit/Think while it waits.
+
+**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: check ALL in-flight ids in ONE call, never one by one, never without `wait`. If it comes back with some still processing, call it ONCE more with `wait=true` and the remaining ids.
+
+**🛑 Runaway-loop guard — ONE generation per requested item.** When the user asks for **one specific change**, the answer is **a single tool call**. After URLs return, **stop**. Surface and wait. You are NOT allowed to:
+- Fire the same tool 3+ times in a single turn unless the user explicitly asked for "N variations".
+- Re-fire because you think the result might not be exactly what the user wanted.
+- Auto-retry on success.
+- Fire 5+ parallel `generate_video*` calls speculatively.
+
+**Only re-fire when:** user explicitly asked for variations with a count, OR previous call returned `failure.retryable === true` (ONE retry), OR previous call returned `completed` but `urls.length === 0` (ONE retry).
+
+**Detecting failure — a generation can fail three ways. Treat ALL as failure:**
+
+1. **Tool returns `error`** — explicit. Surface, suggest retry, log `generation_id`.
+2. **Tool returns `completed` but `urls` is empty** — silent failure (NSFW filter, model OOM, upstream 5xx). Tell user "completed without an output — retrying" and re-fire ONCE. Do NOT claim it worked.
+3. **Tool hangs / never returns** — MCP poll timed out. Call `get_generation_status(generation_id, wait=true)` IMMEDIATELY. The server might be done.
+
+**Reporting:**
+- Don't celebrate before reading the result. Verify `urls` is non-empty.
+- Don't auto-retry without surfacing the failure. Partial batches: list failed items + reasons + successful count, and surface the user's count — "6 of 8 ready", not "videos ready". Never "✅ all done!" on partials.
+- Log only successes to `.kolbo/production.md` — never failed items.
+- When done: say the result is in **Library → This session**. "Where is it?" → Library (This session). "Is it done?" with no urls yet → `get_generation_status` once.
+
+`failure` envelope structure + retry rules: `references/workflows/troubleshooting.md`.
+
 ## 📁 Projects — Where Work Lands (CRITICAL)
 
 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 **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`.
+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`. When the user starts new work, `create_project` first, then pass its id the same way.
 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.
 
@@ -304,25 +352,11 @@ How to thread:
 
 Write each session's `session_id` + plan name into `.kolbo/production.md` `### Sessions`. Do **not** mark the phase Approved or jump to the next bucket until the user confirms (or you asked a labeled GATE and they answered). Full rules: `references/workflows/production-planning.md` + `production-log.md`.
 
-## Cost Awareness — Quick Rules
-
-Full tables + formulas in `references/workflows/cost-and-validation.md`. Quick rules:
-
-- **Skip the brief/cost confirmation ONLY** when the user's message already pins model + count + aspect + creative direction (see "Confirm the Creative Brief" above). Low cost alone is **not** a reason to skip — cheap generations still get the one labeled confirmation unless the user chose the parameters.
-- **Otherwise confirm** via the labeled-question card: the parameters + the credit cost, suggest a cheaper alternative if one fits, wait for the user's pick. Never fire on defaults the user didn't choose.
-- **Batch totalling 100+ credits**: run `check_credits` first.
-- **Quote real cost**: after firing, log `credits_used` (from the tool result) to `.kolbo/production.md` — never `base × count`.
-- **Video/lipsync `credit` is per-SECOND, not per-clip**: `total = credit × duration`. This is the universal rule for video/firstlast/elements/motion_graphic/cast types, not a per-model exception — `list_models` states it inline now. The one carve-out is a model with `flat_credit_by_resolution` set.
-- **Never state "credits remaining" from arithmetic** (opening balance − generation costs). Coding/chat usage deducts credits too, so the math is always wrong. Report cost only; if the user asks for their balance, call `check_credits` fresh at that moment.
-
 ## 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.
-- **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`.
-- **`upload_media` external (non-Kolbo) URLs only.** `files`/`source_images`/`image_url` reject unknown hosts with `400`. A `media.kolbo.ai` / generate_* URL is already hosted — pass it through. Never `upload_media` a Kolbo URL.
 
 ## ⚠️ Multi-output? Default to `generate_creative_director` (CRITICAL)
 
@@ -334,18 +368,6 @@ Full tables + formulas in `references/workflows/cost-and-validation.md`. Quick r
 
 **Parameter gotcha:** `num_images` (1–4, same prompt different seeds) on `generate_image` vs `scene_count` (1–8, distinct prompt per scene) on `generate_creative_director`. **Never pass `num_images` to Creative Director.**
 
-## 🛑 Runaway-Loop Guard — ONE Generation per Requested Item (CRITICAL)
-
-When the user asks for **one specific change**, the answer is **a single tool call**. After URLs return, **stop**. Surface and wait.
-
-You are NOT allowed to:
-- Fire the same tool 3+ times in a single turn unless the user explicitly asked for "N variations".
-- Re-fire because you think the result might not be exactly what the user wanted.
-- Auto-retry on success.
-- Fire 5+ parallel `generate_video*` calls speculatively.
-
-**Only re-fire when:** user explicitly asked for variations with a count, OR previous call returned `failure.retryable === true` (ONE retry), OR previous call returned `completed` but `urls.length === 0` (ONE retry).
-
 ## ⚠️ Editing an Existing Video → ONE Call, Not Frames-First (CRITICAL)
 
 Existing video → modify → **single `generate_video_from_video` call** with source video URL + edit prompt.
@@ -366,30 +388,14 @@ For any ad / story / scene-based video **created from scratch** featuring a Visu
 
 Skip frames-first only when the user says "go straight to video", single-shot quick experiments, or the user supplies approved frames. Full rules: `references/models/creative-director.md`.
 
-## ⚠️ Detecting Failed Generations (CRITICAL)
-
-A generation can fail three ways. Treat ALL as failure:
-
-1. **Tool returns `error`** — explicit. Surface, suggest retry, log `generation_id`.
-2. **Tool returns `completed` but `urls` is empty** — silent failure (NSFW filter, model OOM, upstream 5xx). Tell user "completed without an output — retrying" and re-fire ONCE. Do NOT log to `.kolbo/production.md`. Do NOT claim it worked.
-3. **Tool hangs / never returns** — MCP poll timed out. Call `get_generation_status(generation_id, wait=true)` IMMEDIATELY. The server might be done.
-
-**Always:**
-- Don't celebrate before reading the result. Verify `urls` is non-empty.
-- Don't auto-retry without surfacing the failure. Partial batches: list failed items + reasons + successful count. Never "✅ all done!" on partials.
-- Don't log failed items to `.kolbo/production.md`. Only successes.
-- Surface the user's count. "6 of 8 ready", not "videos ready".
-
-`failure` envelope structure + retry rules: `references/workflows/troubleshooting.md`.
-
 ## ⚠️ Generated URLs in Chat (CRITICAL)
 
 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.3
+0.9.7

package/skill/references/models/creative-director.md

@@ -18,7 +18,7 @@ A multi-scene batch generator. Submit 1–8 scenes in one go and the tool fans t
 - **Cinema Manual** — per-scene **first frame + last frame** + per-scene prompt. Full cinematic control over composition transitions. Best for: hero shots, controlled camera moves, deliberate edits.
 
 ### Identity & Style Locks
-- **Visual DNA** — attach a character/product preset via `visual_dna_ids` to lock identity across all scenes. Up to **8 Visual DNAs** can be active at once (e.g. main character + product + side character). See `workflows/visual-dna.md` for the `@name` syntax — every DNA must be tagged inside the prompt.
+- **Visual DNA** — attach a character/product preset via `visual_dna_ids` to lock identity across all scenes (e.g. main character + product + side character). The cap is per model — read `max_visual_dna` from `list_models`. See `workflows/visual-dna.md` for the `@name` syntax — every DNA must be tagged inside the prompt.
 - **Moodboard** — attach `moodboard_id` (or `moodboard_ids`) for a curated mood/style reference that anchors the aesthetic of the whole batch.
 - When the user mentions a recurring character/product, **ask** if they want to use a Visual DNA and recommend it. Same for a consistent aesthetic → recommend a Moodboard.
 
@@ -97,13 +97,7 @@ A great batch isn't 8 random shots — it's a sequence with intent. Pick one str
 
 ## Character-Driven Video — Frames First
 
-For any ad / story / scene-based video **created from scratch** featuring a Visual DNA character, do NOT jump straight from DNA to per-shot video. The right flow is:
-
-1. **Generate the shot frames first** as still images via `generate_creative_director` with `scene_count` + `visual_dna_ids` + `workflow_type: "image"`. DNA is strongest in image generation; the user can approve cheaply before any expensive video runs.
-2. **Confirm the frames with the user** if there are more than ~3 shots, or if the user hasn't said "go straight to video."
-3. **Animate each frame** with `generate_video_from_image`, passing each approved frame as `image_url`.
-
-Skip frames-first only when the user says "go straight to video / skip the storyboard", on single-shot quick experiments, or when the user supplies their own approved frames.
+SKILL.md's frames-first rule applies. The Creative Director deltas: generate the frames via `generate_creative_director` with `workflow_type: "image"` (+ `scene_count`, `visual_dna_ids`), then animate each approved frame with `generate_video_from_image`, passing it as `image_url`.
 
 ## UGC sets and thumbnail sets
 

package/skill/references/models/music.md

@@ -4,7 +4,7 @@
 
 # Music — Prompt Rules (Suno-led)
 
-Load this file when the user wants AI-generated **music** — full songs, lyrics, instrumentals, jingles, scores, soundtracks, lo-fi beats, trailers, ad music. Primarily Suno; the same craft applies to other music models. For TTS / voice cloning see `models/prompt-copilot.md`. For sound effects see SKILL.md "Sound Effects".
+Load this file when the user wants AI-generated **music** — full songs, lyrics, instrumentals, jingles, scores, soundtracks, lo-fi beats, trailers, ad music. Primarily Suno; the same craft applies to other music models. For TTS / voice cloning see `models/prompt-copilot.md`. For sound effects see `generate_sound` (SKILL.md tool table).
 
 **Kolbo MCP routing:** call `generate_music`. Suno is a model option — use `list_models({ type: "music_gen" })` to see versions. Pass `instrumental` and `duration` as separate params; pass the Style/Description text as `style` and the Lyrics as `lyrics`.
 

package/skill/references/models/prompt-copilot.md

@@ -101,7 +101,7 @@ For models that DO expose `negative_prompt` (some text-to-image variants), keep
 | `21:9` | Ultrawide cinematic, banner |
 | `3:1` / `1:3` | Hero banner, narrow strip |
 
-Model-dependent — always check `supported_aspect_ratios` on the model via `list_models` before passing a value. See SKILL.md "Resolution / Aspect / Duration — validate against caps".
+Model-dependent — always check `supported_aspect_ratios` on the model via `list_models` before passing a value. See `references/workflows/cost-and-validation.md`.
 
 ### Safety / content policy
 

package/skill/references/models/seedance.md

@@ -15,28 +15,30 @@ 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.
+- **Prompt length**: simple single-idea pieces ~120–280 words. Locked-intro cinematic typically 400–900 words. Shorter than ~120 words = random output. The 10,000-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.
-- **HARD CAP: 8000 characters TOTAL for the ENTIRE prompt** — measured as one single string, including ALL shots, ALL boilerplate, ALL SFX lines, the opening style block, the closing `Total: …` line, every newline, every space, every punctuation mark. This is non-negotiable.
-  - Applies to ANY prompt: 1 shot or 6 shots, single POV or full montage — the WHOLE thing must fit under 8000 chars combined.
-  - It is NOT 8000 chars per shot. It is 8000 chars per prompt.
-  - If your draft exceeds 8000 chars, trim aggressively in this order: (1) cut redundant adjectives, (2) collapse the opening cinematic boilerplate, (3) shorten SFX lists, (4) merge or drop shots — keep escalation beats and cut filler beats, (5) tighten action descriptions to verb-led essentials.
-  - **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.
+- **HARD CAP: 10,000 characters TOTAL for the ENTIRE prompt** — measured as one single string including all shots, boilerplate, SFX lines, and the Total lines. It is per PROMPT, not per shot. **Never** split into multiple prompts, code blocks, or "part 1 / part 2" to evade the cap. Count the final prompt before output; if over, trim (cut adjectives, collapse boilerplate, shorten SFX lists, merge or drop shots) and re-count until it fits.
 
 ## 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,15 +50,28 @@ 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)
+
+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
+## The 6 Formats
 
 ### 1. Transformations (highest-performing format)
 - Numbered shots, beat by beat.
@@ -218,7 +233,7 @@ Place CAMERA in the **3rd position** of each shot's core layers (Subject → Act
 - No equipment / director names?
 - Emotion through muscle, not labels?
 - Multishot: FOV per segment + "no drift mid-segment"?
-- 8000-char cap honored?
+- prompt-cap honored?
 
 ## Grid Storyboard Mode (3×3 grid input)
 
@@ -243,7 +258,6 @@ When the user uploads a 3×3 grid image and asks for Seedance prompts, switch to
 - Final prompt(s) ALWAYS in a fenced code block ready to paste into Seedance.
 - After the code block, give a 1-line "why this works" note (camera/escalation/physics choice).
 - If user asked in any language other than English, write your explanation in their language but keep the prompt itself English.
-- **Never exceed 8000 characters TOTAL for the entire prompt as one string** — that is the WHOLE prompt including every shot, every line of boilerplate, every SFX list, every newline. NOT 8000 per shot — 8000 for the prompt as one combined unit. Count before output. If over, rewrite tighter (cut adjectives, collapse boilerplate, merge or drop shots). NEVER split into multiple prompts / multiple code blocks / "part 1 / part 2" to work around the limit.
 
 ## Where to run in Kolbo
 
@@ -256,4 +270,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`). 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`.
+When a character must stay consistent, pair Seedance with Visual DNA via `generate_elements` (NOT `generate_video` — text-to-video silently drops `visual_dna_ids`). `@DNA_name` tagging rules: see `workflows/visual-dna.md`. For grid/storyboard inputs, the source frame is `@image1`.

package/skill/references/models/seedance25.md

@@ -20,24 +20,48 @@ Load this file when the user wants a **Seedance 2.5** video (they said "2.5" / "
 - **Duration 4–30 seconds**, whole seconds. 30s IS supported.
 - **Up to 30 shots/cuts in ONE generation.** Deliver exactly N if N ≤ 30.
 - **Prompt cap 15,000 characters** for the entire prompt as one string (`max_prompt_length` in the catalog; Seedance 2.0 is 10,000). Verify with `list_models` rather than trusting this number — it was documented as 30,000 for months, which is double the real limit.
-- **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.
+- **Large reference / Visual DNA capacity** (`@Name`, `@ImageN`, `#Moodboard`) — read the exact caps from `max_visual_dna` / `elements_max_images` in `list_models`. Every referenced asset must be tagged in the prompt text. A rewrite that drops or renames a tag ( `@doron_fauda_1` → `DORON` / `the hero` ) is a failed turn — put the exact tag back.
 - **Multimodal refs:** images + video clips + audio can all anchor one generation.
 
-## 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/models/veo.md

@@ -15,7 +15,7 @@ Load this file when the user wants a **Veo 3 / Veo 3.1** (Google) video. For oth
 ## CRITICAL Kolbo Platform Rules
 
 - **Aspect ratio, resolution, and clip length are MCP-tool params** (`aspect_ratio`, `resolution`, `duration`). **NEVER include "16:9", "9:16", "720p", "1080p", "4 seconds", "8s", or any duration / aspect / resolution string inside the prompt body.**
-- Pass `sound_enabled: true/false` as a separate param when the user mentions audio — see SKILL.md "Sound on/off".
+- Pass `sound_enabled: true/false` as a separate param when the user mentions audio — see `workflows/cost-and-validation.md`.
 - Don't write Python / Vertex AI / API call syntax. The user is generating through Kolbo's MCP tools.
 
 ## Model Capabilities (informs recommendations, never in the prompt body)

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

@@ -0,0 +1,12 @@
+# Color DNA — Brand Palette Grading
+
+Load this file when the user works with Color DNA / color palettes: creating, activating, analyzing, or opting a generation out of palette grading.
+
+Core contract (also in SKILL.md): **Color DNA is sticky and account-wide — at most one palette is active at a time**, and while one is active it strict-grades **every** image and video generation automatically, with no per-call argument.
+
+Operational detail:
+
+- `analyze_color_palette` pulls colors out of 1–5 image URLs **for free** and does **NOT** save anything — use it to draft a palette before creating one.
+- `create_color_palette` defaults `is_active: true`, which activates the new palette and deactivates any other active one.
+- Per-generation opt-out: `skip_color_palette: true` on `generate_image` / `generate_image_edit` / `generate_video` / `generate_video_from_image`.
+- Manage with `list_color_palettes` / `update_color_palette` / `activate_color_palette` / `deactivate_color_palette` / `delete_color_palette` (edit in place — never delete+recreate).

package/skill/references/workflows/cost-and-validation.md

@@ -8,9 +8,9 @@ Creative generations bill against the user's Kolbo credit balance. **Billing uni
 
 | Type | Billing unit | Credit range | Example |
 |------|-------------|-------------|---------|
-| **Image** | per image (flat) | 1–30 cr | Flux.1 Fast = 1 cr, Midjourney = 4 cr. If `resolution` is set, check `resolutionMultipliers` — some families multiply cost significantly at higher tiers. |
+| **Image** | per image (flat) | 1–30 cr | Flux.1 Fast = 1 cr, Midjourney = 4 cr. If `resolution` is set, check `resolution_multipliers` — some families multiply cost significantly at higher tiers. |
 | **Image edit** | per image (flat) | 2–20 cr | |
-| **Video** | **cr/s × duration** | 2–30 cr/s | Kandinsky 5 Fast × 5s = 10 cr; Seedance 2.0 × 10s = 300 cr. Check `resolutionMultipliers` + `soundCreditMultiplier`. |
+| **Video** | **cr/s × duration** | 2–30 cr/s | Kandinsky 5 Fast × 5s = 10 cr; Seedance 2.0 × 10s = 300 cr. Check `resolution_multipliers` + `sound_credit_multiplier`. |
 | **Video from image** | **cr/s × duration** | 4–30 cr/s | Same per-second rule. |
 | **Elements (ref-to-video)** | **cr/s × duration** | 4–30 cr/s | Check `credit` and multipliers in `list_models type="elements"`. |
 | **Lipsync** | **cr/s × duration** | 5–20 cr/s | |
@@ -28,7 +28,7 @@ Apply when confirming cost before firing:
 - **Music**: flat per generation — `total = model_credit` (duration does not change cost).
 - **TTS**: `total = model_credit × ceil(character_count / 100)`. Count actual characters first. 1000 chars with ElevenLabs = 50 credits.
 - **Images / 3D / Sound effects**: `total = model_credit × quantity`.
-- **Resolution / audio multipliers**: if `resolution` is set or model has native audio, read `resolutionMultipliers[tier]` and `soundCreditMultiplier`. Formula: `final = base × resolutionMult × (sound ? soundMult : 1) × durationSeconds`.
+- **Resolution / audio multipliers**: if `resolution` is set or model has native audio, read `resolution_multipliers[tier]` and `sound_credit_multiplier`. Formula: `final = base × resolutionMult × (sound ? soundMult : 1) × durationSeconds`.
 
 ### Tier label → pixel mapping (rough)
 
@@ -38,8 +38,7 @@ Apply when confirming cost before firing:
 ## When to Confirm Cost
 
 **Skip cost confirmation when:**
-- The user already specified model + count + duration ("make 5 videos, seedance 2 fast, 15s" IS the confirmation).
-- A single generation costs under 5 credits.
+- Model + count + aspect + creative direction are already pinned by the user ("make 5 videos, seedance 2 fast, 15s" IS the confirmation).
 
 **Required cost confirmation when:**
 - Anything else — present a one-line summary: "8 videos × 5s × [model] @ X cr/s = **Y credits**. Proceed?"
@@ -52,21 +51,7 @@ Apply when confirming cost before firing:
 
 ## ⚠️ Quote Real Cost, Never Estimates (CRITICAL)
 
-Pre-flight formulas above are for **preview only**. After firing, every generation returns `credits_used` (multiplier-adjusted total) and `credits_breakdown` (per-model attribution).
-
-```json
-{
-  "credits_used": 12,
-  "credits_breakdown": [
-    { "model": "nano-banana-2", "base": 8, "final": 12, ... }
-  ],
-  "urls": [...]
-}
-```
-
-**Log `credits_used` to `.kolbo/production.md`**, not `base × count`. The multiplier-adjusted number is the only truth.
-
-When the user asks "how much did I spend?" → call `get_session_usage` for the real, multiplier-adjusted session total + per-tool + per-model breakdowns (same numbers as the desktop bottom-bar counter).
+Pre-flight formulas above are for **preview only** — after firing, quote the returned `credits_used`, never `base × count`. Log `credits_used`, resolution, duration and sound state per entry — format in `production-log.md`.
 
 ## Validation Pattern — Every Generation
 
@@ -132,9 +117,4 @@ Cost formula: `final_cost = credit × resolution_multipliers[resolution] × (sou
 
 ## Always Log the Resolution / Duration / Sound Choices
 
-Production-log entries should include the resolution and (for video) duration + sound state alongside the URL, so the user can see what they paid for:
-
-```md
-- still: https://...01-coffee.png  (flux-2-pro · 1K, 2026-05-14)
-- video: https://...02-rain.mp4   (kling-2 · 1080p · 5s · sound-off, 2026-05-14)
-```
+Log `credits_used`, resolution, duration and sound state per entry — format in `production-log.md`.

package/skill/references/workflows/dtc-ads.md

@@ -122,5 +122,5 @@ Default-to-cheapest when the user hasn't expressed a quality intent and the diff
 2. **Always confirm aspect ratio + resolution + quantity** before firing.
 3. **Always check for a brand kit** before scraping fresh — `Read .kolbo/brand-kits/<slug>.md` first.
 4. **Always log products + brand kits in `.kolbo/production.md`** so future ads reuse instead of re-uploading / re-scraping.
-5. **No auto-retry on failure** — surface the reason and let the user adjust.
+5. **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.
 6. **Strict NO uninvited additions** in every ad prompt: "NO captions, NO subtitles, NO watermarks, NO extra text beyond what's specified."

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

@@ -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
 
@@ -36,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,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.
 
+## Generation status, waiting, black cards
+
+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)
 
 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".
@@ -43,10 +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.
-
 ## 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.
@@ -63,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").
@@ -103,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):
 ```
@@ -227,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