@kolbo/mcp 1.79.4 → 1.79.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.79.4",
+  "version": "1.79.7",
   "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@a0342e4, the single source of truth.
+This tree is mirrored from kolbo-code@fccda44, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -24,6 +24,8 @@ You have direct access to the Kolbo AI creative platform via MCP tools (auto-con
 
 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.**
+
 ## Step 0 — Bootstrap
 
 Once per conversation, before any other Kolbo tool call:
@@ -59,8 +61,8 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 |---|---|
 | Make a **film / ad / scene / episode / campaign / any video with multiple or recurring characters** — read BEFORE planning a single shot | `references/workflows/production-planning.md` |
 | Direct, develop, audit, or continue a **film / episode / connected scene / complex performance** with continuity, acting, dialogue, music, blocking, or physics | `references/workflows/filmmaking.md` |
-| Generate a **Seedance 2.5** video | `references/models/seedance25.md` + Locked Intro in `references/models/seedance.md`. For narrative/continuity also load `references/workflows/filmmaking.md` — but compile the prompt as Locked Intro, NOT the SCENE CONTEXT / OPTICS / ACTION pack |
-| Generate a **Seedance 2 / 2.0** video **or Elements** (`generate_elements`) | `references/models/seedance.md` — same Locked Intro. Elements is NOT a different prompt language |
+| Generate a **Seedance 2.5** video | `skill` `elements-prompting` + `references/models/seedance25.md` + Locked Intro in `references/models/seedance.md`. For narrative/continuity also load `references/workflows/filmmaking.md` — but compile the prompt as Locked Intro, NOT the SCENE CONTEXT / OPTICS / ACTION pack |
+| Generate a **Seedance 2 / WAN / MiniMax H3 / Gemini / Elements** video (`generate_elements` or Visual DNA) | `skill` `elements-prompting` + `references/models/seedance.md` — same Locked Intro. Elements is NOT a different prompt language |
 | Generate a **GPT Image 2** image | `references/models/gpt-image.md` |
 | Generate a **Nano Banana / Gemini** image | `references/models/nano-banana.md` |
 | Generate a **Veo 3 / 3.1** video | `references/models/veo.md` |
@@ -93,7 +95,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 ### Generation
 | Tool | Description |
 |------|-------------|
-| `generate_image` | Single image from a text prompt. Supports Visual DNA, moodboards, image presets, reference images, web-search grounding. When a preset is requested, resolve it with `list_presets({ type: "image" })` and pass its exact id as `preset_id`. |
+| `generate_image` | Single image from a text prompt. Supports Visual DNA, moodboards, image presets (custom instructions live here), reference images, web-search grounding. Named sheets/styles: `list_presets({ type: "image", search: "headless" })` then `preset_id`. |
 | `generate_image_edit` | Edit/transform an existing image. Pass `source_images` + edit prompt. Image-editing presets are supported through `preset_id` from `list_presets({ type: "image_edit" })`. |
 | `generate_creative_director` | **2–8 related images or videos as one coherent set.** Use INSTEAD of multiple `generate_image` calls for any related multi-output. |
 | `generate_video` | Text-to-video. Accepts `visual_dna_ids` and `sound_enabled`; `generate_elements` is still the primary reference-driven route for a DNA-anchored film. |
@@ -116,7 +118,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `list_models` / `list_voices` / `check_credits` / `get_generation_status` / `cancel_generation` / `get_session_usage` | Discovery + status. `list_models` with no args returns the recommended shortlist out of ~428 — pass `type` for a full category with per-model caps. `cancel_generation` stops an in-flight job and refunds what it can: use it when the user changes their mind mid-generation instead of letting it run. |
 | `upload_media` / `create_upload_ticket` / `list_media` / `get_media` / `get_media_stats` / `favorite_media` / `unfavorite_media` / `delete_media` / `restore_media` / `permanently_delete_media` / `move_media` / `bulk_*_media` / `*_media_folder` | Media library — see `workflows/media-library.md`. Getting a LOCAL file in depends on where the server runs: `upload_media` with a path only works on a local (stdio) install; over a remote connector use `create_upload_ticket` and POST the file yourself. |
 | `create_visual_dna` / `generate_character_sheet` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` / `*_visual_dna_folder` (5 folder tools) | Visual DNA (+ character sheet, character folders) — see `workflows/visual-dna.md` |
-| `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays. A preset request is binding: resolve the requested or closest matching preset in the correct catalog, then pass its exact returned `id` as `preset_id`. Never say a preset was used if the generation call omitted it. |
+| `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays + sheet presets. Always pass `search` when you know the name — that is a silent id lookup, not a catalog to show. Never omit `preset_id` after claiming a preset was used. |
 | `list_color_palettes` / `analyze_color_palette` / `create_color_palette` / `update_color_palette` / `delete_color_palette` / `activate_color_palette` / `deactivate_color_palette` | **Color DNA — sticky and account-wide.** At most one palette is active at a time; while it is, it strict-grades **every** image and video generation automatically, with no per-call argument. `analyze_color_palette` pulls colors out of 1-5 image URLs for free and does NOT save. `create_color_palette` defaults `is_active: true`, which activates it and deactivates any other. Per-generation opt-out: `skip_color_palette: true` on `generate_image` / `generate_image_edit` / `generate_video` / `generate_video_from_image`. |
 | `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Custom chat agents — reusable named personas for `chat_send_message`. The agent's `description` IS the system instruction. Resolve a name the user mentions ("use my SEO agent") to an id with `list_agents`, then pass `agent_id`. Global/preset agents are read-only; only the user's own can be updated or deleted. |
 | `search_stock_media` / `get_stock_sources` / `get_stock_categories` / `get_stock_collections` / `get_stock_asset` / `analyze_script_for_stock` / `import_stock_asset` | Stock library (free, no credits) — EXISTING photos / videos / 3D / SFX / music. For stock **music** use `search_stock_media` with `mediaType: "music"` (semantic vibe query, e.g. "uplifting corporate background") → `get_stock_asset` for downloads. The older `*_music_library` tools are deprecated adapters over this — prefer the stock tools, except for the licensed-catalog tools in the next row. |
@@ -141,6 +143,10 @@ Passing `visual_dna_ids` is **not enough**. For every DNA in that array you MUST
 - Never invent a role label or possessive as a substitute for `@Name`
 - Same rule for moodboards: `#ExactBoardName`
 
+**Rewrite / compile never drops a tag.** If the user, a prior prompt, or `list_visual_dnas` already has `@gal_suit` / `@yonatan` / `#Board`, the Locked Intro you write MUST still contain those exact tokens in CAST **and** in every shot they appear in. Do not "clean" them into first names, `@Image 1 (Lee)`, "the singer", or a SCENE CONTEXT / ACTIVE REFERENCES block with no `@`. A compile that loses a tag is a failed turn — put the tags back before calling `generate_*`.
+
+Before `generate_elements` / any DNA video: for each id in `visual_dna_ids`, confirm the prompt string includes `@` + that DNA's stored `name`. Missing even one → fix the prompt, do not fire.
+
 Resolve names with `list_visual_dnas` first. Full binding rules: `references/workflows/visual-dna.md`.
 
 ## ⚠️ `enhance_prompt` — leave it OFF (HARD RULE)
@@ -156,21 +162,47 @@ first, so the model renders *different words than the ones the user wrote*.
   user never asked for, and their own wording never reached the model.
 - The default is `false` in every generation tool. Leave the argument out.
 
+## ⚠️ Never re-upload a Kolbo URL (HARD RULE)
+
+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.
+- Same rule after compaction: pull the URL from `.kolbo/production.md` and reuse it. Never download-then-reupload.
+
 ## ⚠️ Assets Before Shots (HARD RULE)
 
-For any film / ad / scene / episode / campaign the order is **Map → Create → Confirm → Shoot**: inventory every character, location and prop the script needs, build each as a Visual DNA (sheet presets), get the user's explicit approval on the asset set, and only then generate video. A shot fired against an unapproved cast is waste, not a draft.
+For any film / ad / scene / episode / campaign the order is **Map → Create → Confirm → Shoot** (the directing guide — load `references/workflows/production-planning.md` + `filmmaking.md` before creating anything). Crack the concept first. Then every character, location, and prop becomes a Visual DNA **from a sheet** (`list_presets` search → `generate_image` with that `preset_id` → `create_visual_dna`). Do **not** register a DNA from a single portrait and skip the sheet. Publish the session plan (`Cast` / `Locations` / `Scene NN — slug`). Get a GATE lock on the asset set. **Only then** video. A shot against an unapproved cast is waste.
 
 Scene dialogue is **never** `generate_speech` or `generate_lipsync`. Seedance 2 / 2.5 performs quoted lines written into the shot beat itself — English only. Full flow: `references/workflows/production-planning.md`.
 
+## ⚠️ Load the matching skill BEFORE generating (HARD RULE)
+
+Do **not** call `generate_*` / `generate_elements` / `generate_image_edit` until you have loaded the matching skill **in this turn** (the `skill` tool for bundled skills, and/or Read of the `references/` file). "I already know this" is not a load. Users will never invoke these skills themselves.
+
+| About to call / user intent | `skill` tool | Also Read |
+|---|---|---|
+| `generate_elements` **or** any video with Visual DNA **or** Seedance 2 / 2.5 / WAN / MiniMax H3 / Gemini video | `elements-prompting` | `references/models/seedance.md` (+ `seedance25.md` if 2.5) and `references/workflows/visual-dna.md` when DNA is in play |
+| `generate_image` / `generate_image_edit` | `image-prompting-guide` | `references/models/gpt-image.md` / `nano-banana.md` / `prompt-copilot.md` as the model requires. Complex stills / identity lock: `references/workflows/prompt-structure.md` |
+| `generate_video*` that is **not** Elements/DNA (Kling, Veo, Sora, Grok, Hailuo, generic t2v/i2v) | `video-prompting-guide` | matching `references/models/*.md` |
+| `generate_music` | `music-prompting` | `references/models/music.md` |
+| UGC / phone-shot / selfie / "authentic" / must-not-look-like-an-ad | — | `references/workflows/ugc-smartphone.md` |
+| Marketing / TV spot / branded video / unboxing / product review | — | `references/workflows/marketing-studio.md` |
+| DTC ad image | — | `references/workflows/dtc-ads.md` |
+| Product photoshoot / hero / lifestyle / try-on | — | `references/workflows/product-photoshoot.md` |
+| Thumbnail / cover | — | `references/workflows/thumbnails.md` |
+| Marketplace listing cards | — | `references/workflows/marketplace-cards.md` |
+| Film / episode / connected scene | — | `references/workflows/filmmaking.md` + `production-planning.md` |
+
 ## ⚠️ Seedance / Elements prompt contract (HARD RULE)
 
-`generate_elements`, Seedance 2, and Seedance 2.5 share **one** compile shape — the Locked Intro in `references/models/seedance.md`:
+`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 — …`
 
 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.
 
-Do **not** default Elements to `SCENE CONTEXT` / `OPTICS` / `ACTION` / `ACTIVE REFERENCES` department packs (those live in filmmaking audit/contracts for other models). Do not load `seedance-2-prompting` SCENE CONTEXT as the Elements format.
+Do **not** default Elements to `SCENE CONTEXT` / `OPTICS` / `ACTION` / `ACTIVE REFERENCES` department packs (those live in filmmaking audit/contracts for other models). `elements-prompting` is the craft skill (formerly `seedance-2-prompting`); Locked Intro is the compile shape.
 
 ## ⚠️ If the User Names a Tool, USE THAT TOOL (HARD RULE)
 
@@ -201,19 +233,24 @@ A user-named tool — in any language — overrides every other rule. Recognized
 
 ## Core Workflow
 
-**Preset contract:** if the user asks for a preset, names one, or says to use one of their/Kolbo presets, call `list_presets` with the matching type before generation and pass the selected exact `id` as `preset_id`. Use `image` for `generate_image` and `image_edit` for `generate_image_edit`. Never invent an id or silently continue without the requested preset.
+**Preset contract:**
+- Custom instructions live on the **preset**. Prefer `generate_image` + `preset_id` (not `generate_character_sheet`) for Character Sheet / Headless / Bible / location / product sheets.
+- Always `list_presets({ type: "image", search: "<name>" })` — `headless`, `bible`, `character sheet`. That is a silent id lookup. Do **not** omit `search` (that dumps the whole catalog). Reuse the id after the first hit.
+- Browse (no search) only when the user asked to see presets.
+- 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. **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`).
-3. **Pick the model**:
+2. **Load the matching skill** (HARD RULE above) — `skill` tool + Read the `references/` file. Do this 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.
    - **Never cheapest-swap a named family.** After compaction, "animate those images" is still Grok if the user said Grok. Seedance / Kling / Veo are not a "best balance" substitute. If the named family has no variant for this modality, ASK — do not silently switch.
    - 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.
-4. **Validate inputs** against model caps — see `references/workflows/cost-and-validation.md`.
-5. **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.
-6. **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.
-7. **Share the URL** after success. Never fabricate URLs.
+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.
 
 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`.
 
@@ -225,6 +262,27 @@ Everything in Kolbo — sessions, generations, media, docs — lives inside a PR
 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.
 
+## ⚠️ One session per plan bucket (HARD RULE)
+
+Omitting `session_id` on a generate call creates a **new** Kolbo sidebar session. Do that only when the **plan** starts a new bucket — not per take, not per shot, not because you just called a tool.
+
+Name buckets from the plan you already showed the user, then `rename_session` on first create:
+
+| Bucket | What lives in it | Kind |
+|---|---|---|
+| `Cast` | every character sheet / character DNA | image |
+| `Locations` | every environment | image |
+| `Props` | hero products / vehicles (if any) | image |
+| `Scene NN — <slug>` | that scene's video shots **and** retakes | video |
+
+How to thread:
+
+1. First generate of a bucket → omit `session_id`, read it from the result, immediately `rename_session` to the plan name (`Cast`, `Locations`, `Scene 03 — rooftop chase`).
+2. Every later generate in that bucket (more characters, another environment, shot 2, "make it darker", redo take 3) → pass that **same** `session_id`.
+3. New scene or new concept → new session. Same scene / same cast pass → never a new session.
+4. Image tools and video tools cannot share an id (server kinds differ). Cast/Locations stay image; scene clips stay video.
+
+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
 
@@ -244,7 +302,7 @@ Full tables + formulas in `references/workflows/cost-and-validation.md`. Quick r
 - **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 URLs first.** `files`/`source_images`/`image_url` only accept Kolbo-hosted URLs reliably; external URLs cause `400`.
+- **`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)
 
@@ -315,7 +373,7 @@ Avoid bare URL dumps and HTML `<table>` grids — canvas already provides a gall
 
 **After `generate_creative_director` completes** — share results as individual URLs, one per scene. Do NOT create an HTML grid artifact.
 
-**Always** record every URL in `.kolbo/production.md` — see `references/workflows/production-log.md`.
+**Always** park every successful URL + `session_id` in `.kolbo/production.md` as a **candidate**. Promote to Approved and advance the plan only after the user confirms — see `references/workflows/production-log.md`.
 
 ## Limitations & Safety
 

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

@@ -40,6 +40,8 @@ Always call `list_models({ type: "<tool-type>" })` first when the user hasn't na
 
 ## Universal Rules
 
+- **Keep every `@DNA` / `#Moodboard` / `@ImageN` token.** Same contract as the Kolbo help widget: tag EVERY referenced asset in the prompt text (exact `@DNA_name`, `@ImageN`, `#Name` — an untagged reference is silently dropped). The tag stays the canonical subject name in every shot. Never replace it with a nickname, role label, or pronoun. Rewriting a user prompt and losing `@yonatan` is a failed turn.
+- When the output is **one video** and the user has Visual DNA / several refs / "keep him consistent", write an **Elements** prompt (not a still, not Creative Director). Elements is video-only.
 - **Clean prompts only.** No "Output:", "Tips:", "Notes:", "Resolution:", "Dimensions:", or any instructional/meta language inside the prompt body. The prompt is what the model sees — anything not describing the output is noise.
 - **Resolution / aspect ratio / duration are MCP-tool params**, not prompt text. Pass them as separate fields on the tool call.
 - **Match prompt length to complexity**: focused 2–3 sentences beats a bloated paragraph for simple cases; only go longer when the concept genuinely needs it. Aim for **under ~200 tokens** — long prompts distort.

package/skill/references/models/seedance.md

@@ -14,6 +14,7 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 ## Universal Rules (apply to EVERY Seedance / Elements prompt)
 
 - **Visual DNA names are immutable anchors:** when `visual_dna_ids` is passed, every DNA MUST appear in the prompt as the exact literal `@DNA_name` (CAST + every shot it is in). Never "Zohar's", "the left man", "the man on the LEFT", a nickname, or a Visual DNA anchors paragraph without `@tags`.
+- **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.
 - **Order inside each shot**: Subject → Action → Camera → Constraints → (Audio/SFX if relevant). Do NOT restack GLOBAL LOOK style inside the shot.

package/skill/references/models/seedance25.md

@@ -20,7 +20,7 @@ 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.
+- **Up to 50 reference medias / Visual DNA mentions** (`@Name`, `@ImageN`, `#Moodboard`). Every referenced asset must be tagged in the prompt text. A rewrite that drops or renames a tag ( `@doron_fauda_1` → `DORON` / `the hero` ) is a failed turn — put the exact tag back.
 - **Multimodal refs:** images + video clips + audio can all anchor one generation.
 
 ## Locked Intro (DEFAULT — same shape as Seedance 2)

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

@@ -4,6 +4,12 @@ Load this file when the user wants to browse, list, organize, delete, restore, m
 
 The library covers both **uploaded files** and **AI-generated outputs the user has saved**. Tools fall into five groups: ingest, browse, lifecycle (delete/restore/move), folders, and favorites.
 
+## ⚠️ Already-hosted URLs — never re-upload
+
+`generate_*` / `list_media` / `get_media` / a prior `upload_media` already return a Kolbo CDN URL (`media.kolbo.ai`, `*.kolbo.ai`, Spaces). Pass that exact URL into the next generation tool. Calling `upload_media` on it duplicates the file.
+
+`upload_media` is only for a local path or an external (non-Kolbo) URL. If you already have a Kolbo URL, skip ingest.
+
 ## ⚠️ Present locally-produced media to the user
 
 When you produce a media file LOCALLY — `ffmpeg` via the `video-production` skill, Remotion render, manual `Bash` mux of audio + video, `edit_image` outputs saved to disk, any save-to-file flow — make sure the user can actually find and open it. Local files are invisible in the chat / canvas UI by default; only the path string makes it through.

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

@@ -32,10 +32,25 @@ The log records **what the user approved** — not everything you produced. Gett
    Say plainly which ones are in play, e.g. "created `@maya` and `@maya_alt` — here they are".
 3. **Ask for a decision** and name the options ("keep the first, redo the second, or both?").
 4. **Repeat** until the user is satisfied. Log nothing as approved during this stage.
-5. **On approval → update `.kolbo/production.md` immediately**, in the same turn, before your next tool call or final reply.
+5. **On approval → promote in `.kolbo/production.md` immediately**, in the same turn: move the winner out of Candidates, update `**Approved:**`, then you may start the next plan bucket. Do not advance `**Now working on:**` to the next phase before this.
 
 **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 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.
 
 **Don't lose candidate URLs while iterating.** Recording a candidate is not the same as claiming approval, and compaction will eat unlogged URLs. Park in-flight takes under a `#### Candidates (pending approval)` bullet, and on approval promote the winner to a normal entry and mark the rest `(rejected)`:
@@ -59,7 +74,12 @@ after the user picks take 2:
 
 ## When to WRITE to it
 
-**Immediately once an artifact is approved** (see the approval gates above), before your next tool call or your final reply. The runtime will inject a reminder after generation tool results — treat that as a hard rule, not a suggestion. Where there is no approval loop — the user asked for one thing and got it, or delegated the choice to you — approval is implicit and you log right away.
+Two writes, different jobs:
+
+1. **Right after a successful generate** — park the URL, `generation_id`, `credits_used`, and `session_id` under `#### Candidates (pending approval)` and under `### Sessions` if this is the first shot of a new bucket. Rewrite `## 🎯 Now` only for `**Awaiting approval:**` / the current bucket. This is what the runtime reminder is asking for. It is **not** approval.
+2. **After the user locks the bucket** — promote the winner, mark rejects, update `**Approved:**`, then you may change `**Now working on:**` to the next planned bucket.
+
+Where there is no production (user asked for one throwaway image and got it, or said "you pick") — approval is implicit and you log the finished entry right away. A film / ad / scene plan is never that case.
 
 Tools that REQUIRE logging:
 - `generate_image`, `generate_image_edit`, `edit_image`
@@ -95,12 +115,14 @@ Stub for first creation:
 **Now working on:** <the immediate next step>
 **Approved:** <locked assets — DNAs, moodboards, scenes; "nothing yet" if still iterating>
 **Awaiting approval:** <what you've presented and are waiting on; omit when nothing is pending>
+**Sessions:** <plan names + ids — Cast / Locations / Scene 01 — …; "none yet" until first generate>
 **Last updated:** <ISO date>
 
 ---
 
 ## Production: <name from user's request, slugified human label>
 
+### Sessions
 ### Cast
 ### Visual DNA
 ### Scenes
@@ -115,10 +137,17 @@ Subsections (`### Cast` etc.) are **suggested defaults**, not required. Adapt: a
 One bullet per artifact. Write the label **the way the user would reference it next time** ("the rainy one"), not the model's raw output.
 
 ```md
+### Sessions
+- **Cast** — sess_abc  (image) — @maya @doron
+- **Locations** — sess_def  (image) — @night_market
+- **Scene 01 — coffee shop** — sess_ghi  (video) — shots 1–4
+- **Scene 02 — rooftop chase** — (pending)
+
 ### Cast
 - **Maya** — female, 30, urban photographer, leather jacket
   - portrait: https://...characters/maya.png  (nano-banana-2, 2026-05-13)
   - visual DNA: vdna_8f2c  (@maya)
+  - session: sess_abc
 
 ### Scenes
 1. **Coffee shop morning** — Maya at counter, soft light, wide shot
@@ -152,6 +181,7 @@ When a user request supersedes a previous artifact (e.g., "redo scene 2 with mor
 6. **One file per workspace.** Multiple concurrent productions go under separate `## Production: <name>` headings inside the same file.
 7. **Approved state is user-granted, never assumed.** A generation succeeding is not approval. Only the user's "yes" — or their explicit delegation of the choice to you — promotes a candidate to an approved entry. Silence is not approval; neither is the user moving on to another topic.
 8. **The `## 🎯 Now` block names what is locked.** Keep an `**Approved:**` line there listing the currently-approved cast, DNAs, moodboards, and scenes, so the approved state survives compaction and is the first thing you read next session.
+9. **Sessions are part of the log.** Every bucket from the plan gets a `### Sessions` row (name from the plan, `session_id`, kind, which `@tags` / scene it holds). After the first generate of a bucket, `rename_session` to that plan name and write the id. Reuse that id — do not spawn untitled sessions for retakes.
 
 ## Bulk Generation Entry Shape
 

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

@@ -14,10 +14,10 @@ that has to match anything else.
 
 ## The order is not negotiable
 
-1. **Map** every element the script needs.
-2. **Create** each one as an approved asset (Visual DNA).
-3. **Confirm** the asset set with the user.
-4. **Only then** compile shots and generate video.
+1. **Map** every element the script needs — including the **session plan** (names).
+2. **Create** each one as an asset (Visual DNA), grouped into the planned sessions.
+3. **Confirm** that bucket with the user. Do not start the next bucket until they lock this one.
+4. **Only then** compile shots and generate video (one session per scene).
 
 Generating video before step 3 is how a production ends up with a different face
 in every shot and a re-shoot bill. A shot generated against an unapproved cast is
@@ -39,6 +39,30 @@ State the inventory back to the user as a list with counts and cost before
 creating anything. A 4-character, 2-location, 1-prop film is 7 assets, not "some
 characters".
 
+Also publish the **session plan** in that same MAP reply — exact sidebar titles
+you will `rename_session` to. Default buckets:
+
+| Session name | Kind | Contents |
+|---|---|---|
+| `Cast` | image | all character sheets / character DNAs |
+| `Locations` | image | all environments |
+| `Props` | image | hero products / vehicles (omit if none) |
+| `Scene 01 — <slug>` | video | every shot and retake of that scene |
+| `Scene 02 — <slug>` | video | next scene |
+
+Slugs come from the plan (`Scene 01 — coffee shop`, `Scene 03 — rooftop chase`),
+not generic "API Generations" or "Untitled". One video session **per scene**;
+shots live inside it. A new session is a new scene or a new concept — never a
+new take.
+
+Omitting `session_id` on generate creates a new session. First call of a bucket
+omits it, then `rename_session` immediately; every later call in that bucket
+passes the same id. Image and video kinds cannot share an id.
+
+Write those planned names into `.kolbo/production.md` `### Sessions` as
+`(pending)` during MAP. Fill in the real `session_id` when the first generate
+returns. See `production-log.md`.
+
 Separate **states** from **identities**: clean vs bloodied, day vs night, intact
 vs broken are their own assets. Do not expect one DNA to carry both.
 
@@ -58,26 +82,50 @@ Read the matching prompt reference before writing an asset prompt:
 for GPT Image 2. There is no Mirage reference file — prompt it as a plain cinematic
 still.
 
-Use the sheet presets rather than free-form portraits — `generate_character_sheet`
-with `sheet_type`:
+Resolve the sheet **preset** (custom instructions live there):
+`list_presets({ type: "image", search: "bible" | "headless" | "character sheet" })`
+then `generate_image` with that `preset_id`. Do not dump the catalog — always
+pass `search`.
 
-- `character` — front/back/face turnaround, the default for a speaking role
-- `character_bible` — denser model sheet (turnaround + faces + wardrobe + swatches) for a lead who appears across many shots
-- `character_headless` — wardrobe/body when clothing changes but the face must not
-- `environment` — location angles plus one signature detail
-- `product` — angles plus material and construction close-ups
-- `style` — one look applied across six varied subjects
+- `bible` — lead or anyone with a lot of detail (default when in doubt)
+- `headless` — body / wardrobe / instrument; face already locked
+- `character sheet` — simple supporting role
+- `location` / `product` — matching DNA type
 
-The sheet is the single strongest consistency booster. It costs credits, so offer
-it and generate on a yes.
+Sheets are **2K or 4K** (never 1K). Default 2K; 4K for bible / high-detail / when
+the user names 4K or GPT Image 2.
+
+Do not skip the sheet and `create_visual_dna` from a portrait. The sheet is the
+asset; the DNA stores it.
 
 Then `create_visual_dna` with the sheet as the reference and the matching
 `dna_type`. Name each DNA in the exact form it will be tagged with later.
 
-## 3. Confirm
+## 3. Confirm — a labeled GATE, then wait
+
+Show the user what this bucket produced and **stop**. Do not start Locations
+while Cast is still iterating. Do not shoot while assets are unapproved.
+Do not rewrite `## 🎯 Now` to the next phase until the gate is answered.
+
+If they do not volunteer a yes, end the turn with a GATE the next message can
+parse — not a vague "looks good?":
+
+```
+GATE — Cast
+Presented: @maya, @doron (candidates in the log)
+Lock + next: "lock cast" / "yes" / "next" / "now locations"
+Stay: "redo @maya" / "another take of the leather jacket"
+```
+
+Treat as confirmation: `yes`, `ok`, `lock`, `approved`, `that's the one`,
+`use take 2`, `next`, `go`, `continue`, or they name the **next** bucket
+("now do environments", "shoot scene 1") while treating the current set as done.
+
+Not confirmation: silence, "maybe", a question about something else, another
+take request. Ask the GATE again once; do not invent a yes.
 
-Show the user the asset set and get an explicit approval before shooting. This is
-the cheapest possible place to change their mind.
+On lock: promote candidates → Approved in `.kolbo/production.md`, then start
+the next planned bucket in **its** session.
 
 ## 4. Shoot
 

package/skill/references/workflows/prompt-structure.md

@@ -0,0 +1,131 @@
+<!-- Schema and preserve-vocabulary distilled from patterns observed across a
+     22,000-prompt open corpus (YouMind-OpenLab/ai-image-prompts-skill, MIT).
+     Patterns and field frequencies only — no prompt text or assets were copied. -->
+
+# Prompt Structure — Structured Blocks, Reference Contracts, Reusable Templates
+
+Load this file when a still-image request is **complex** (many elements that must all
+land), an **edit that must not drift**, or a **template the user will run more than once**.
+
+Simple asks do not need any of this. "A watercolor cat on a windowsill" is a finished
+prompt — structure added to a simple request just gives the model more surface to
+misread. Reach for these three tools only when the picture has parts that fight.
+
+---
+
+## 1. Structured blocks — for complex scenes
+
+When a single paragraph has to carry a subject, a wardrobe, a pose, an environment, a
+light setup and a camera, prose starts losing elements. Break it into labelled blocks so
+each one is independently checkable. This is the schema that recurs across thousands of
+working prompts, in frequency order — use the blocks the picture needs, skip the rest:
+
+```
+output_goal:   one sentence — what the finished image IS
+subject:       identity, expression, pose, wardrobe, accessories
+environment:   location, background, props, atmosphere
+lighting:      type, direction, quality, mood
+camera:        shot size, lens, angle, focus, depth of field
+composition:   framing, subject placement, negative space
+style:         medium, rendering, colour palette, reference era
+negative:      what must NOT appear
+aspect_ratio:  the target canvas
+```
+
+Rules that make it work rather than just look organised:
+
+- **`output_goal` first, one sentence.** It is the model's summary of intent, and it
+  catches briefs that contradict themselves before you write 400 words.
+- **One fact per field.** `"lighting": "hard noon sun from camera-left, deep short
+  shadows"` — not a paragraph.
+- **Nest only where it earns it.** `subject.hair`, `subject.expression`, `subject.pose`
+  are worth splitting when they matter; otherwise keep `subject` flat.
+- **`negative` is a real field, not a mood.** Name objects and treatments to exclude
+  ("no text, no watermark, no extra fingers, no lens flare"), not qualities to avoid.
+- **Never restate a block's content inside another block.** Style written into every
+  field is how a picture ends up over-styled and identical in every region.
+- JSON-ish, YAML-ish or plain labelled lines all work. Pick one and stay in it.
+
+## 2. The reference contract — how an edit stops drifting
+
+This is the highest-value pattern in the file. "Keep everything else the same" is too
+vague to hold, and it is why a chain of edits quietly turns a person into someone else.
+An edit prompt opens with an explicit contract:
+
+```
+reference_image:
+  use_uploaded_image: true
+  identity_lock: face_only | full_subject | product | scene | none
+  preserve: [ <the exact properties that must survive> ]
+edit_scope: <the ONE thing that changes>
+```
+
+**`identity_lock` says how much is frozen:**
+
+| Mode | What travels | Typical use |
+|---|---|---|
+| `face_only` | the face, nothing else | put this person in a new scene, outfit or style |
+| `full_subject` | face, body, wardrobe | same person, same clothes, new environment |
+| `product` | the object's design | the product in a new setting or lighting |
+| `scene` | the environment | same room, different subject |
+| `none` | nothing — a style reference only | borrow a look, not a thing |
+
+**`preserve` is a list of properties, never an adjective.** Name what actually drifts,
+in the order it drifts:
+
+- **People** — facial bone structure, nose shape, eye spacing, jawline, hairline and
+  hairstyle, skin tone and texture, expression, body proportions.
+- **Products** — label artwork, typography, logo placement, colours, proportions,
+  closure or cap, material finish.
+- **Scenes** — camera angle, layout, background objects, lighting direction.
+
+**The edit-scope field names ONE change.** "Change only the background to a night street." A
+prompt that re-describes the whole picture is a re-generation, and the model will
+re-imagine exactly the parts you wanted frozen.
+
+**Restate the whole contract on every iteration.** Drift is cumulative — the third edit
+in a chain is where the face goes. Never write "same as before".
+
+Two more invariants worth stating outright: natural anatomy must stay accurate, and a
+preserved object keeps its true scale relative to hands and surfaces.
+
+If the user has not uploaded anything, there is no reference contract to write — that is
+a from-scratch generation, and `text_to_image` is the tool.
+
+## 3. Reusable templates — named slots
+
+When the user wants a recipe rather than one picture ("for every product", "every
+episode cover", "swap the character"), write the prompt once and mark the variable parts
+as named slots carrying a working default:
+
+```
+{argument name="product name" default="the serum bottle"}
+```
+
+- Slot only what changes per run — subject, product name, on-image text, brand colour,
+  setting. Everything else stays literal, which is what makes the look reproducible.
+- **Every slot needs a default that actually renders**, so the template works unfilled.
+- Name slots for what they are — `"hero headline"`, `"character identity"` — never
+  `var1`.
+- **Reuse one slot name everywhere that value appears.** A nine-frame storyboard that
+  names the product in four frames uses one slot four times, not four slots.
+- A variation set is one template plus a single stated variation axis (angle, mood,
+  palette). Vary that axis only — a set whose look drifts between frames is not a set.
+- Deliver the filled version and say which slots to swap next time.
+
+---
+
+## Which tool for which ask
+
+| The ask | Reach for |
+|---|---|
+| One simple picture | none of this — write good prose |
+| Many elements that must all land | structured blocks |
+| Editing an upload; identity must survive | reference contract (+ blocks if complex) |
+| "I'll run this again for each X" | named slots |
+| A set of variations | one template + one variation axis |
+
+Related: `workflows/ugc-smartphone.md` for the phone-shot look (its product rules are the
+reference contract applied to packaging), `workflows/visual-dna.md` for locking identity
+across many generations rather than one edit, and `models/gpt-image.md` /
+`models/nano-banana.md` for per-model phrasing.

package/skill/references/workflows/research-first.md

@@ -45,7 +45,7 @@ Extract from this page, in compact bullets:
 
 ## Re-host every external image via `upload_media`
 
-The bulk-API rule applies: external URLs in `reference_images` / `source_images` / `image_url` cause **400 Bad Request**. Pipeline:
+The bulk-API rule applies: **external** (non-Kolbo) URLs in `reference_images` / `source_images` / `image_url` cause **400 Bad Request**. Skip this pipeline if the URL is already `media.kolbo.ai` / `*.kolbo.ai` / a generate_* result — pass that URL through. For a third-party host:
 
 1. `Bash: curl -fsSL "<external-url>" -o /tmp/<name>.<ext>` (or use WebFetch where it returns the binary)
 2. `mcp__kolbo__upload_media` with the local file → returns Kolbo CDN URL

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. **Create** a profile with `create_visual_dna` — provide reference images (max 4 — if the user gives more, pick the 4 most representative or ask which to keep; never pass 5+), optionally video and audio.
+1. **Sheet first, then DNA.** For any production asset (character / location / prop), resolve the sheet **preset** (`list_presets` with `search`) and `generate_image` with that `preset_id` — custom instructions live on the preset. Then `create_visual_dna` with the sheet as `character_sheet_url` (max 4 extra images — if the user gives more, pick the 4 most representative; never pass 5+). Optionally video and audio.
 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`.
@@ -85,6 +85,7 @@ Whenever a generation call passes `visual_dna_ids` (even just one), the prompt M
 - 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.
 
 **Wrong** (DNA `name` is `esther_model`, user wrote prompt in Hebrew):
 ```
@@ -244,12 +245,22 @@ Tools: `list_visual_dna_folders`, `create_visual_dna_folder` (`name`, optional h
 - **Creating many characters for one production?** Create the folder FIRST, then `move_visual_dna_to_folder` each DNA right after `create_visual_dna` — don't leave a big cast unsorted at root.
 - To list a folder's contents: `list_visual_dnas` and filter by each profile's `folder_id` (there is no server-side folder filter).
 
-## Character sheet — offer it for character DNAs
+## Character sheet — default for production assets (not a catalog preset)
 
-`generate_character_sheet` builds a multi-angle turnaround from reference image URLs — the strongest consistency booster for a character DNA. It CHARGES CREDITS, so:
-- When the user is about to create a **character** DNA, proactively OFFER it: "want me to generate a character sheet first? It makes the character far more consistent and costs a few credits." Run it only on a yes.
-- Flow: `generate_character_sheet {image_urls}` → show the sheet → `create_visual_dna {name, images, character_sheet_url: <url>}`.
-- For non-character DNAs (style/product/environment), skip it.
+Custom instructions live on the **image preset**. Resolve it silently, then generate:
+
+1. `list_presets({ type: "image", search: "headless" | "bible" | "character sheet" | "location" | "product" })`
+2. Pass the exact `id` as `preset_id` on `generate_image` (2K or 4K, never 1K; 4K for bible / high-detail / when named)
+3. Show the sheet → GATE → `create_visual_dna { name, images, character_sheet_url }`
+
+| Search | When |
+|---|---|
+| `bible` | Lead or anyone with a lot of detail (wardrobe, hair, accessories, instrument) |
+| `headless` | Face already locked, or clothing / instrument / body must stay independent of the face |
+| `character sheet` | Simple supporting person |
+| `location` / `product` | Matching DNA type |
+
+Do **not** omit `search` (that dumps the catalog). Do not show the preset picker. `generate_character_sheet` is fallback only if no preset matches.
 
 ### ⚠️ Aspect ratio — character sheets and bibles are LANDSCAPE
 

package/src/index.js

@@ -126,7 +126,7 @@ function createServer(opts = {}) {
       '5. Written deliverables (plans, briefs, scripts, research summaries) can live in Kolbo too: author them as AI Docs with `create_doc` (project-scoped, editable in the app, shareable via `share_doc`).',
       '6. TIMEOUT HANDLING (applies to EVERY generate_* / edit_* / chat_send_message / transcribe_audio tool): each tool blocks and polls internally, then gives up after its own window if the job is not yet terminal. A timeout is NOT a failure — it returns `_timed_out:true` with the `generation_id` (not an error), because the job is almost always STILL RUNNING on the server (or already finished). Call `get_generation_status` with that `generation_id` and `wait=true` to keep checking until state="completed". NEVER conclude the generation failed and re-run the same tool from scratch after a `_timed_out:true` result — that wastes the user\'s credits by paying twice. DIRECTOR / BATCH JOBS follow the same convention through a dedicated tool: generate_creative_director runs its scenes (image OR video) in parallel and only reports state="completed" once EVERY scene is terminal; on `_timed_out:true` call `get_creative_director_status` (not get_generation_status) with the returned generation_id and keep checking. If scenes already carry image_urls/video_urls, they are done; do not regenerate.',
       '7. SESSION CONTINUITY — one task, one session, always: every generation tool returns a `session_id`. For ANY follow-up, refinement, retry, or next step on the SAME task, pass that session_id back — never start fresh. BATCH RULE (critical): when a single user request produces multiple parallel generations (e.g. "animate these 5 images", "generate 3 variants"), do NOT launch them all at once without a session_id. Instead: (1) run the FIRST generation without session_id to create the session, (2) capture the session_id from its response, (3) pass that session_id to ALL remaining generations in the batch. This keeps the entire batch in one session. Exception: only omit session_id and start fresh when the user explicitly starts an unrelated new task.',
-      '8. LOCAL FILES / REFERENCE MEDIA — HOW TO HANDLE EVERY CASE. (A) User has a LOCAL file (audio, video, image, document) on their machine. What matters is WHERE THIS SERVER RUNS, not what your client can do — your own filesystem access is irrelevant if the server is somewhere else. On a LOCAL stdio install (server and client share a machine) → call `upload_media` with the absolute path, or pass the path straight to tools like `transcribe_audio` that accept local paths. Over a REMOTE connector the server cannot see that path no matter how capable you are, so a local path will always fail: if you can run shell commands or issue HTTP requests → call `create_upload_ticket` and POST the file to the returned upload_url yourself (fastest, no user interaction); if you cannot → call `media_upload_widget` IMMEDIATELY, the user uploads, and a `media.kolbo.ai` CDN URL comes back for any follow-up call. (B) You already have a public URL (media.kolbo.ai, any CDN, any direct link) → pass it directly; all Kolbo tools accept public URLs. NEVER search for DO Spaces keys, DigitalOcean credentials, or server-side upload credentials. NEVER ask the user to put the file on Google Drive, Dropbox, or Loom. NEVER invent or guess a URL. NEVER base64 anything but a tiny file — it costs context in proportion to file size; use the ticket or the widget instead.',
+      '8. LOCAL FILES / REFERENCE MEDIA — HOW TO HANDLE EVERY CASE. (A) User has a LOCAL file (audio, video, image, document) on their machine. What matters is WHERE THIS SERVER RUNS, not what your client can do — your own filesystem access is irrelevant if the server is somewhere else. On a LOCAL stdio install (server and client share a machine) → call `upload_media` with the absolute path, or pass the path straight to tools like `transcribe_audio` that accept local paths. Over a REMOTE connector the server cannot see that path no matter how capable you are, so a local path will always fail: if you can run shell commands or issue HTTP requests → call `create_upload_ticket` and POST the file to the returned upload_url yourself (fastest, no user interaction); if you cannot → call `media_upload_widget` IMMEDIATELY, the user uploads, and a `media.kolbo.ai` CDN URL comes back for any follow-up call. (B) You already have a public URL → pass it directly. A URL from generate_* / list_media / upload_media / media.kolbo.ai / any *.kolbo.ai host is ALREADY hosted — NEVER call upload_media on it (that duplicates the file). External (non-Kolbo) URLs may need one upload_media re-host; Kolbo URLs never do. NEVER search for DO Spaces keys, DigitalOcean credentials, or server-side upload credentials. NEVER ask the user to put the file on Google Drive, Dropbox, or Loom. NEVER invent or guess a URL. NEVER base64 anything but a tiny file — it costs context in proportion to file size; use the ticket or the widget instead.',
       '9. MODEL SELECTION — NAMED MODEL WINS, THEN STRENGTHS SUMMARY: ALWAYS pass a specific `model` on every generation tool — do NOT omit it (omitting falls back to "Smart Select" auto-routing, which hides the choice from the user; use it ONLY if the user explicitly asks you to auto-pick). If the user named a model this turn OR earlier in the conversation (including a compaction "Locked choices" / summary), that name is a FAMILY LOCK: pass it (or its display name) on every follow-up, including when the tool changes (text-to-video → image-to-video). Identifier resolution remaps a t2v id to the family\'s i2v sibling automatically. NEVER substitute a different brand because it is cheaper, faster, or "best balance" (Grok Imagine named → do not fire Seedance). If the named family has no variant for this modality, ASK — do not silently switch. Cheapest-summary routing applies ONLY when no model was named on this task: call `list_models` with the matching `type` and read each model\'s STRENGTHS SUMMARY — the "— …" clause printed after the credit cost — then pick the CHEAPEST model whose summary covers the task. `[NEW]` and `[RECOMMENDED]` badges, a high credit number, and "flagship"/"most intelligent" wording are NOT selection signals — never pick a model because it is newest, biggest or most expensive. Escalate to a premium/frontier model only when the user explicitly asks for maximum quality, or when no cheaper summary covers the requirement. Models printed under "Named-only" (no summary) are opt-in: use them only when the user names them. TEXT/CHAT: `chat_send_message` bills PER TOKEN, so the listed credit number is not the cost — a frontier text model (Claude Fable 5, GPT-5.6 Sol, Pro-class) costs 5-30x a mid-tier one per reply. Default ordinary chat (writing, brainstorming, Q&A, summarising) to a balanced mid-tier model and reserve the frontier tier for hard reasoning or long-form code the user asked for.',
       '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit`. Auto-pick only Nano Banana 2 (`nano-banana-2` / `nano-banana-2-image-editing`) or GPT Image 2 (`gpt-image-2` / `gpt-image-2/edit`) for photoreal photo edits, object removal, keep-subject/remove-others, or crowd cleanup. Do NOT auto-pick Flux 2 / flux-2/edit / Flux Klein — those are generate-from-scratch / style, named-only for editing. Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.',
       '11. PRESET CONTRACT: if the user asks for a preset, names a preset, or says to use one of their/Kolbo presets, you MUST call `list_presets` with the matching type before generation, resolve the named or closest matching preset, and pass its exact returned `id` as `preset_id`. Use type="image" for generate_image and type="image_edit" for generate_image_edit. Never silently ignore a preset request, never invent an id, and never claim a preset was applied unless `preset_id` was present in the generation call.'

package/src/tools/media.js

@@ -6,6 +6,7 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { resolveToBuffer, DEFAULT_MAX_FILE_MB, compactList } = require('./_shared');
+const { ownedUrl } = require('./owned-url');
 const { UI, uiResult, listResult } = require('../apps');
 
 // How many tiles the media grid renders. A rendering limit only — the text
@@ -160,9 +161,9 @@ function registerMediaTools(server, client, options = {}) {
   // ─── upload_media ──────────────────────────────────────────
   server.tool(
     'upload_media',
-    'Upload a local file (or remote URL) to the user\'s Kolbo media library and get back a stable Kolbo CDN URL. Use this when the user wants to reference a local file in multiple subsequent generation calls — upload once, then pass the returned URL to generate_image / generate_video / visual_dna / etc. Auto-detects media type (image / video / audio) from the file extension. For a single-use reference where you already have a public URL, you can skip this and pass the URL directly to the generation tool.',
+    'Upload a LOCAL file (or a NON-Kolbo remote URL) to the user\'s Kolbo media library and get back a stable Kolbo CDN URL. NEVER call this on a URL that is already Kolbo-hosted: generate_* / list_media / prior upload_media results, media.kolbo.ai, *.kolbo.ai, or DigitalOcean Spaces. Those URLs are already usable — pass them as-is to generate_* as reference_images / source_images / image_url. Use this only for a path on disk or an external (non-Kolbo) URL that needs re-hosting. Auto-detects media type from the file extension.',
     {
-      source: z.string().optional().describe('URL or absolute local path to the file to upload. For local files this is the primary mode; for URLs, this re-hosts the file on Kolbo CDN for stability. Provide this OR source_base64.'),
+      source: z.string().optional().describe('Absolute local path, or a NON-Kolbo URL to re-host. Do not pass a media.kolbo.ai / generate_* / list_media URL — those are already hosted and this tool will refuse to duplicate them. Provide this OR source_base64.'),
       source_base64: z.string().optional().describe('Raw file content as base64 (no data: prefix) — fallback for hosts with no filesystem or public URL (e.g. small images on claude.ai when the upload widget is unavailable). Requires `filename`. Keep under ~10MB; for larger files use media_upload_widget.'),
       filename: z.string().optional().describe('Original filename WITH extension (e.g. photo.png) — required with source_base64; the extension determines the media type.'),
       description: z.string().optional().describe('Optional description / caption for the uploaded media'),
@@ -171,6 +172,19 @@ function registerMediaTools(server, client, options = {}) {
     async ({ source, source_base64, filename, description, project_id }) => {
       if (!source && !source_base64) throw new Error('Provide source (URL or absolute local path) OR source_base64 (+ filename)');
 
+      if (source && ownedUrl(source)) {
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              reused: true,
+              url: source,
+              hint: 'This URL is already on Kolbo CDN. Pass it as-is to generate_* (reference_images / source_images / image_url / files). Do not upload again.',
+            }, null, 2),
+          }],
+        };
+      }
+
       if (source_base64) {
         if (!filename || !/\.[a-z0-9]{2,5}$/i.test(filename)) {
           throw new Error('source_base64 requires a `filename` with an extension (e.g. photo.png)');

package/src/tools/owned-url.js

@@ -0,0 +1,13 @@
+// Generation + library URLs already live on Kolbo CDN (media.kolbo.ai, Spaces).
+// Re-uploading them wastes storage and time — pass the URL through as-is.
+function ownedUrl(url) {
+  if (typeof url !== 'string' || !/^https?:\/\//i.test(url)) return false;
+  try {
+    const host = new URL(url).hostname;
+    return /(?:^|\.)kolbo\.ai$/.test(host) || /digitaloceanspaces\.com$/.test(host);
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { ownedUrl };