@kolbo/mcp 1.87.0 → 1.87.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.87.0",
+  "version": "1.87.2",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/skill/GENERATED.md

@@ -1,6 +1,6 @@
 # AUTO-GENERATED — do not edit
 
-This tree is mirrored from kolbo-code@20a6572, the single source of truth.
+This tree is mirrored from kolbo-code@b38e38c, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -1,435 +1,435 @@
----
-version: 0.9.13
-name: kolbo
-description: |
-  Generate, edit, analyze, and direct creative media through Kolbo AI: images,
-  video (Seedance, Veo, Kling, Hailuo), music, speech, sound, 3D, transcription,
-  Visual DNA, Creative Director batches, marketing assets, HTML artifacts, and
-  AI Docs, and approved Blender scene control. Use for sophisticated AI
-  filmmaking as well as individual media:
-  scripts, production bibles, recurring characters and locations, acting,
-  dialogue, music performance, blocking, physics, multi-shot continuity,
-  connected scenes, prompt audits, feature-length production planning, and
-  direct Blender scene building through the connected Kolbo Blender plugin.
-
-  NOT for: video editing / FFmpeg (use video-production), motion graphics
-  (use remotion-best-practices), code editing, or general chat.
-argument-hint: "[prompt-or-command] [--model <name>] [--image <path>] [--video <path>]"
-allowed-tools: Bash, Read, Write, Edit
----
-
-# Kolbo AI — Creative Generation, Analysis & Transcription
-
-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 shows results in **Library** (right panel) and on the generation card. Refer by description ("the rainy scene"). Store only user-approved results in `.kolbo/production.md`; pending takes stay out. 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 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
-
-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 (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 & 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). 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. 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.
-
-**Cost rules** (full tables + formulas in `references/workflows/cost-and-validation.md`):
-
-- **Video/lipsync `credit` is per-SECOND, not per-clip**: normally `total = credit × output_duration`. If video references are attached and `video_input_credit` is present, use the alternate provider tariff instead: `video_input_credit × (sum ceil(each input video duration) + output seconds) × video_input_resolution_multiplier`. Dedicated Seedance Edit uses its selected source duration as output; Extend uses the requested added duration. The other carve-out is `flat_credit_by_resolution`.
-- **Batch totalling 100+ credits**: run `check_credits` first.
-- **Quote real cost**: when the user approves the result, log its actual `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.
-- **Out of credits → `show_plans`.** A generation refused for credits already returns the upgrade card automatically — do NOT retry it, and do not re-run the tool "to be sure". Call `show_plans` yourself when the user asks about pricing, plans, upgrading, or how to get more credits. Prices are live and promo-adjusted; never quote them from memory. The user completes any purchase themselves on app.kolbo.ai/pricing — you cannot buy for them.
-
-For multi-scene / batch work this pairs with `generate_creative_director` (see below) — still confirm the brief first.
-
-## Routing Index — Read These Files on Demand
-
-| If the user wants to… | Read first |
-|---|---|
-| 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` |
-| Build, inspect, animate, light, render, or edit a **Blender scene through Kolbo Blender MCP** | `references/workflows/blender-mcp.md` |
-| 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` |
-| Build a **multi-scene set** (Creative Director, storyboard, campaign batch, 4+ angles) | `references/models/creative-director.md` |
-| Generate **music** (Suno, song, lyrics, jingle, score) | `references/models/music.md` |
-| Build an **HTML presentation / slide deck** | `references/models/html-presentation.md` |
-| Build a **landing page / marketing site** | `references/models/landing-page.md` |
-| Build a **dashboard / data viz / interactive widget / mini-game / UI mockup** | `references/models/visual-code.md` |
-| Generate with **any other model** (Flux, Kling, Sora, Hailuo, ElevenLabs, DeepDub, …) — also covers universal prompt-engineering basics | `references/models/prompt-copilot.md` |
-| Generate a **3D model** (Meshy, Trellis — mesh, texture, rigging, animation) | `references/models/3d.md` |
-| Build a **UGC ad / TV spot / branded video / unboxing / product review / virtual try-on** | `references/workflows/marketing-studio.md` |
-| Write a **complex multi-element still**, an **edit that must not drift** (identity / product / scene lock), or a **reusable prompt template** | `references/workflows/prompt-structure.md` |
-| Make anything look **shot on a phone** — UGC, selfie, candid, "authentic", a product photo that must not look like an ad (image OR video) | `references/workflows/ugc-smartphone.md` |
-| Make a **YouTube / Shorts / Reels thumbnail** or video cover | `references/workflows/thumbnails.md` |
-| Compose a **DTC ad image** (brand kit + ad format + avatar + product + reference media) | `references/workflows/dtc-ads.md` |
-| 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` |
-| Apply a **preset** — a named look, sheet, thumbnail, grading, camera move, Seedance shot recipe, music style — or decide whether one fits what the user just asked for | `references/workflows/presets.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` |
-| Inspect or change a connected **Blender** scene, render, import Kolbo media, or run approved Blender Python | `references/workflows/blender.md` |
-
-Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/src/config/systemPrompt.js` — same battle-tuned rules that power Kolbo's web-app help widget. Keep parity (see `packages/opencode/CLAUDE.md` "MCP & Skill Sync Rule").
-
-## Available MCP Tools
-
-### Generation
-| Tool | Description |
-|------|-------------|
-| `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. |
-| `generate_video_from_image` | Animate a still. Prompt describes motion, not subject. |
-| `generate_video_from_video` | Restyle/transform an existing video. Keeps original motion. |
-| `generate_elements` | Reference-driven video. **Primary route for DNA → video.** Prompt = Seedance Locked Intro (`Total` + `[GLOBAL LOOK]` / `[CAST]` / `[LOCATION]` + `SHOT N`). Every DNA in `visual_dna_ids` must also be `@Name` in that prompt. |
-| `generate_first_last_frame` | Keyframe interpolation between two frames. |
-| `generate_lipsync` | Lipsync an existing waveform onto a face. **Not the route for dialogue in a film you are generating** — write the line in the Seedance prompt instead. |
-| `generate_music` | Music generation (Suno + variants). |
-| `generate_speech` | TTS for narration, voiceover and standalone audio. **NOT for scene dialogue** — Seedance 2/2.5 performs quoted lines itself. |
-| `generate_sound` | Sound effects. |
-| `generate_3d` | 3D models from text / single image / multi-view. Returns GLB/FBX/OBJ/USDZ. Meshy V7 adds auto-rigging + ~697 animation presets (extra credits) and mesh/texture toggles — see `references/models/3d.md`. |
-| `analyze_video` | Kolbo's official video understanding (agentic Gemini — navigates the timeline itself, so long videos are cheap and timestamp / counting / "when does X happen" questions are answered directly). Public video URL or YouTube URL + optional `prompt`; sync, token-billed. See `workflows/transcription.md`. |
-| `separate_audio_stems` | Split a soundtrack into Dialogue / Music / Effects / without-dialogue (M&E). The route for removing or isolating speech, instrumental beds, and stems for dubbing. 5cr, inline. See `workflows/audio-stems.md`. |
-| `clean_dialogue_leftovers` | Strip voices still faintly audible in an M&E layer. 17cr — only when the user reports the leak, it trades fidelity. |
-| `separate_ambience` | Pull room tone out of the Effects bed as its own lane. 17cr. |
-
-### Discovery, Library, Visual DNA, Moodboards, Chat, Publishing
-| Tool | Purpose |
-|------|---------|
-| `list_models` / `list_voices` / `check_credits` / `show_plans` / `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. `show_plans` renders the balance + upgrade card for pricing/plan/upgrade questions. |
-| `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` / `list_cinematic_presets` | Style overlays + presets. `list_presets` spans FOUR distinct catalogs (`image`, `image_edit`, `video`, `music`; `text_to_video` is an alias for `video`, `shorts` is empty) — the `video` one holds 200+ Seedance shot recipes. `list_cinematic_presets` is a separate tool feeding the `cinematic` arg, never `preset_id`. Full doctrine + intent→catalog map: `references/workflows/presets.md`. 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** — 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. |
-| `create_moodboard` / `update_moodboard` / `delete_moodboard` | Moodboards from image URLs → AI master style prompt → pass `moodboard_id` to generation tools. Edit with `update_moodboard`; never delete+recreate. |
-| `clone_voice` / `import_elevenlabs_voice` / `delete_voice` | Custom voices (clone CHARGES CREDITS — confirm first; new voices show in `list_voices`) |
-| `trim_video` | Frame-accurate trim of a Kolbo-hosted video (tool waits and returns the URL). `edit_video` also gained `remove_background`. |
-| `create_doc` / `list_docs` / `get_doc` / `update_doc` / `share_doc` / `delete_doc` | AI Docs (Magic Pad): YOU author full HTML documents (plans, briefs, scripts, research) saved into the user's project, editable in the Kolbo app. `share_doc` returns a public link. `update_doc` content replaces the WHOLE doc — `get_doc` first. |
-| `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) |
-| `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. |
-| `blender_list_sessions` / `blender_get_scene` / `blender_search_docs` / `blender_capture_viewport` / `blender_apply_operations` / `blender_import_media` / `blender_render` / `blender_undo` / `blender_file_operation` / `blender_execute_python` / `blender_get_command_status` | Connected Blender control through the Kolbo extension. Every tool crosses into an external desktop host; read `workflows/blender.md` before the first call. |
-
-## ⚠️ Edit in place — never delete+recreate (HARD RULE — always on)
-
-Existing Kolbo objects keep a stable id. Generations, `@Name` / `#Name` bindings, share links, and teammates already point at that id. Deleting and making a new one orphans those links and throws away the stored analysis.
-
-| What changed | Tool |
-|---|---|
-| Visual DNA name, description, stills, sheet, type, attributes | `update_visual_dna` |
-| Project-cast DNA description or purpose note | `update_project_asset` |
-| Moodboard name, style notes, images | `update_moodboard` |
-| Project name or description | `get_project` then `update_project` |
-| Project cast membership | `link_project_asset` / `unlink_project_asset` (list first) |
-| Session title | `rename_session` |
-| Custom agent name / persona | `update_agent` |
-| AI Doc title / content | `get_doc` then `update_doc` |
-
-`delete_*` is only for objects the user asked to remove.
-
-## ⚠️ Visual DNA `@Name` in the prompt (HARD RULE — always on)
-
-Passing `visual_dna_ids` is **not enough**. For every DNA in that array you MUST also write `@ExactStoredName` in the prompt text (the `name` from `list_visual_dnas` / `create_visual_dna`). The engine binds identity by parsing `@tags`. No `@tag` → the DNA is wasted.
-
-- Right: `visual_dna_ids: ["vdna_…"]` + prompt `@Zohar walks into frame`
-- Wrong: `Zohar's`, `Zohar`, `the left man`, `the man on the LEFT`, `Visual DNA anchors: the man on the LEFT…` — none of these bind
-- Never invent a role label or possessive as a substitute for `@Name`
-- Same rule for moodboards: `#ExactBoardName`
-
-**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`.
-
-**Every still on a DNA can reach the model.** Kolbo now sends all of a DNA's reference images that fit the model's image-slot cap (user uploads first, then one still per DNA, then leftovers round-robin). If a DNA only gets one leftover slot and has no real character sheet, unused stills become a white grid. Mixed-vibe stills or environment photos that contain a main character will confuse the generation — keep each DNA surgically clean. Create-and-pack rules: `references/workflows/visual-dna.md`.
-
-## ⚠️ `enhance_prompt` — leave it OFF (HARD RULE)
-
-**Never pass `enhance_prompt: true` unless the user asked for it in words.** It is
-not a quality knob you turn on to be helpful — it sends the prompt to a rewriter
-first, so the model renders *different words than the ones the user wrote*.
-
-- The user says "make it more cinematic" → that is a request to change **your**
-  prompt. Write the better prompt yourself. It is NOT permission to enhance.
-- Only "enhance the prompt" / "improve my prompt" / "expand this prompt" is.
-- Passing it silently is the worst case: the card shows an `enhanced` chip the
-  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 — `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)
-
-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)
-
-This `kolbo` skill is the mandatory first layer for every Kolbo media task. Do **not** call `generate_*` / `generate_elements` / `generate_image_edit`, or write the billable prompt for them, until you have loaded every matching dependency **in this turn** (the `skill` tool for bundled skills and Read of the required Kolbo references). "I already know this," memory, or a prior-turn load does not count. Users will never invoke these skills themselves.
-
-Dependencies accumulate: narrative Elements work requires **Kolbo + filmmaking + elements-prompting**, not whichever one was loaded first. Before the first paid call, silently check the stack and load anything missing.
-
-| 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 / 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:
-
-`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 30,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). `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)
-
-A user-named tool — in any language — overrides every other rule. Recognized aliases:
-
-| User said (any language) | Use exactly |
-|---|---|
-| "director", "creative director", **"במאי"**, "ad set", "campaign tool", "storyboard tool" | `generate_creative_director` |
-| "image edit", "edit", "modify", "remove background", **"עריכת תמונה"** (paired with a per-image instruction) | `generate_image_edit` |
-| "elements" / **"אלמנטים"** | `generate_elements` |
-| "first/last frame" / **"פריימים"** | `generate_first_last_frame` |
-| "lipsync" / **"ליפסינק"** | `generate_lipsync` |
-
-**Mixed signals — named tool always wins.** "Image edit with the director tool to make 4 angles" → `generate_creative_director`.
-
-## ⚠️ Generate vs Edit (when the user did NOT name a tool)
-
-| User intent | Action | NOT this |
-|-------------|--------|----------|
-| "Create a video from scratch" | `generate_video` | — |
-| "Edit / Cut / Trim / Add subtitles / Remove silence / Convert to 9:16" | Load `video-production` skill → FFmpeg | ❌ `generate_video` |
-| "Create motion graphics / animated text / title sequence" | Load `remotion-best-practices` skill | ❌ `generate_video` |
-| "Animate this image" | `generate_video_from_image` | — |
-| "Restyle this video as anime" | `generate_video_from_video` | — |
-| "Modify THIS one image" — change bg, remove object, recolor | `generate_image_edit` | ❌ Not for multi-output |
-| "4 angles / poses / views of this character" / "variations of this character" | `generate_creative_director` with `visual_dna_ids` | ❌ Don't loop `generate_image_edit` |
-| "4 variations of THIS exact image" (same prompt, different seeds) | `generate_image` with `num_images=4` | ❌ Not `generate_image_edit` |
-
-## Core Workflow
-
-**Preset contract** (full doctrine — catalogs, intent→search map, cinematic dimensions: `references/workflows/presets.md`):
-- Custom instructions live on the **preset**, and it is almost always better than the paragraph you would improvise. Prefer `generate_image` + `preset_id` (not `generate_character_sheet`) for Character Sheet / Headless / Bible / location / product sheets.
-- **Presets are not image-only.** `type: "video"` holds 200+ Seedance 2 shot recipes (chase, orbital, drift, showcase, VFX, storyboard) and feeds `generate_video` + `generate_elements`; `image_edit` and `music` have their own catalogs. `image` and `image_edit` ids are NOT interchangeable.
-- **Search on the user's own noun when their request matches a catalog** — they rarely say "preset". `list_presets({ type, search: "<their word>" })` matches name + description + category together.
-- Always pass `search`. That is a silent id lookup. Do **not** omit it (that dumps a 632k-char 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. Never claim a preset was used without passing it.
-- Cinematic presets are a DIFFERENT tool (`list_cinematic_presets` → the `cinematic` arg, one id per dimension, omit for Auto) — never `preset_id`.
-
-1. **Check credits** ONCE per conversation (Step 0). Skip if already checked.
-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.
-   - **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.
-5. **Validate inputs** against model caps — see `references/workflows/cost-and-validation.md`.
-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 | User-approved ids + URLs only. Compaction-safe memory — not the user gallery or a candidate scratchpad. |
-
-**🛑 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.
-
-**Detecting failure — a generation can fail three ways. Treat ALL as failure:**
-
-1. **Tool returns `error`** — explicit. Surface it and suggest a retry. Keep the `generation_id` in the active run for recovery; never put failures in production.md.
-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 successful results the user explicitly approves to `.kolbo/production.md` — never pending, rejected, or 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`. 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.
-
-## ⚠️ 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.
-
-After the user approves a bucket, write its `session_id` + plan name into `.kolbo/production.md` `### Sessions`. Do not create or update the file for a pending bucket. Full rules: `references/workflows/production-planning.md` + `production-log.md`.
-
-## 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.
-- **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. Keep pending ids in the current run; persist only the user-approved winners in `.kolbo/production.md`.
-
-## ⚠️ Multi-output? Default to `generate_creative_director` (CRITICAL)
-
-`generate_creative_director` is **an agent**, not a niche tool. Plans each scene internally, locks consistency, runs in parallel. For 2+ related outputs, it's almost always right.
-
-**Tie-breaker:** about to fire ≥2 `generate_image` calls and the user did NOT dictate per-image prompts? Stop. Use `generate_creative_director`.
-
-**Never loop `generate_image` sequentially.** Either Creative Director or one parallel batch.
-
-**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.
-
-**Use a TRUE video-to-video model.** Image-to-video models reject with `WRONG_MODEL_TYPE`. Valid: `wan/2-7-videoedit`, `happyhorse/video-edit`, `kling-video/o3-video-to-video`, or any model whose DB `type` includes `video_to_video` (use `list_models({ type: "video_to_video" })`).
-
-**Motion-control / animate-move models invert the inputs**: `reference_images[0]` = the CHARACTER IMAGE to animate, `source_video` = the driving/reference video whose motion is transferred. Omitting the character image returns a `MOTION_CONTROL_INPUTS` error.
-
-**Do NOT** decompose into frames. **Do NOT** re-fire if the first call returned URLs.
-
-## ⚠️ Character-Driven Video — Frames First, Then Animate (CRITICAL)
-
-For any ad / story / scene-based video **created from scratch** featuring a Visual DNA character (NOT v2v edits):
-
-1. **Generate the shot frames first** via `generate_creative_director` with `scene_count` + `visual_dna_ids` (image mode). DNA is strongest in image gen; user can approve cheaply.
-2. **Confirm the frames** if >3 shots.
-3. **Animate each frame** with `generate_video_from_image`, fired in parallel.
-
-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`.
-
-## ⚠️ 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; Library already shows the 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.
-
-**Never update `.kolbo/production.md` merely because a generation succeeded.** Keep the result provisional in the generation card / Library, ask the user to choose, and write only the explicitly approved winner in the same turn as approval. Brief approval before generation is not output approval; silence, a topic change, or requesting the next task is not approval. See `references/workflows/production-log.md`.
-
-## Limitations & Safety
-
-- **Real people**: never identify specific individuals in photos, even public figures. Describe visible attributes only.
-- **NSFW**: Kolbo enforces content safety at the model level. If a generation fails on safety grounds, rephrase rather than retrying identically.
-- **Copyright**: style references are fine ("in the style of Studio Ghibli"); verbatim reproduction is not.
-- **No fabricated URLs**: only share URLs that actually came back from a tool call.
-
-## Sharing HTML Artifacts
-
-HTML/SVG/Mermaid artifacts have a **Share** button in the preview toolbar that uploads the artifact and copies a permanent public URL (no login required to view). Or call `publish_html_artifact({ title, content })` directly.
-
----
-
-If at this point you still don't know which `references/` file to load, default to `references/models/prompt-copilot.md` for generation prompts or `references/workflows/cost-and-validation.md` for cost/validation questions, or just keep going with this core file's rules.
+---
+version: 0.9.13
+name: kolbo
+description: |
+  Generate, edit, analyze, and direct creative media through Kolbo AI: images,
+  video (Seedance, Veo, Kling, Hailuo), music, speech, sound, 3D, transcription,
+  Visual DNA, Creative Director batches, marketing assets, HTML artifacts, and
+  AI Docs, and approved Blender scene control. Use for sophisticated AI
+  filmmaking as well as individual media:
+  scripts, production bibles, recurring characters and locations, acting,
+  dialogue, music performance, blocking, physics, multi-shot continuity,
+  connected scenes, prompt audits, feature-length production planning, and
+  direct Blender scene building through the connected Kolbo Blender plugin.
+
+  NOT for: video editing / FFmpeg (use video-production), motion graphics
+  (use remotion-best-practices), code editing, or general chat.
+argument-hint: "[prompt-or-command] [--model <name>] [--image <path>] [--video <path>]"
+allowed-tools: Bash, Read, Write, Edit
+---
+
+# Kolbo AI — Creative Generation, Analysis & Transcription
+
+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 shows results in **Library** (right panel) and on the generation card. Refer by description ("the rainy scene"). Store only user-approved results in `.kolbo/production.md`; pending takes stay out. 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 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
+
+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 (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 & 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). 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. 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.
+
+**Cost rules** (full tables + formulas in `references/workflows/cost-and-validation.md`):
+
+- **Video/lipsync `credit` is per-SECOND, not per-clip**: normally `total = credit × output_duration`. If video references are attached and `video_input_credit` is present, use the alternate provider tariff instead: `video_input_credit × (sum ceil(each input video duration) + output seconds) × video_input_resolution_multiplier`. Dedicated Seedance Edit uses its selected source duration as output; Extend uses the requested added duration. The other carve-out is `flat_credit_by_resolution`.
+- **Batch totalling 100+ credits**: run `check_credits` first.
+- **Quote real cost**: when the user approves the result, log its actual `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.
+- **Out of credits → `show_plans`.** A generation refused for credits already returns the upgrade card automatically — do NOT retry it, and do not re-run the tool "to be sure". Call `show_plans` yourself when the user asks about pricing, plans, upgrading, or how to get more credits. Prices are live and promo-adjusted; never quote them from memory. The user completes any purchase themselves on app.kolbo.ai/pricing — you cannot buy for them.
+
+For multi-scene / batch work this pairs with `generate_creative_director` (see below) — still confirm the brief first.
+
+## Routing Index — Read These Files on Demand
+
+| If the user wants to… | Read first |
+|---|---|
+| 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` |
+| Build, inspect, animate, light, render, or edit a **Blender scene through Kolbo Blender MCP** | `references/workflows/blender-mcp.md` |
+| 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` |
+| Build a **multi-scene set** (Creative Director, storyboard, campaign batch, 4+ angles) | `references/models/creative-director.md` |
+| Generate **music** (Suno, song, lyrics, jingle, score) | `references/models/music.md` |
+| Build an **HTML presentation / slide deck** | `references/models/html-presentation.md` |
+| Build a **landing page / marketing site** | `references/models/landing-page.md` |
+| Build a **dashboard / data viz / interactive widget / mini-game / UI mockup** | `references/models/visual-code.md` |
+| Generate with **any other model** (Flux, Kling, Sora, Hailuo, ElevenLabs, DeepDub, …) — also covers universal prompt-engineering basics | `references/models/prompt-copilot.md` |
+| Build a **UGC ad / TV spot / branded video / unboxing / product review / virtual try-on** | `references/workflows/marketing-studio.md` |
+| Write a **complex multi-element still**, an **edit that must not drift** (identity / product / scene lock), or a **reusable prompt template** | `references/workflows/prompt-structure.md` |
+| Make anything look **shot on a phone** — UGC, selfie, candid, "authentic", a product photo that must not look like an ad (image OR video) | `references/workflows/ugc-smartphone.md` |
+| Make a **YouTube / Shorts / Reels thumbnail** or video cover | `references/workflows/thumbnails.md` |
+| Compose a **DTC ad image** (brand kit + ad format + avatar + product + reference media) | `references/workflows/dtc-ads.md` |
+| 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` |
+| Apply a **preset** — a named look, sheet, thumbnail, grading, camera move, Seedance shot recipe, music style — or decide whether one fits what the user just asked for | `references/workflows/presets.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` |
+| Inspect or change a connected **Blender** scene, render, import Kolbo media, or run approved Blender Python | `references/workflows/blender.md` |
+
+Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/src/config/systemPrompt.js` — same battle-tuned rules that power Kolbo's web-app help widget. Keep parity (see `packages/opencode/CLAUDE.md` "MCP & Skill Sync Rule").
+
+## Available MCP Tools
+
+### Generation
+| Tool | Description |
+|------|-------------|
+| `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. |
+| `generate_video_from_image` | Animate a still. Prompt describes motion, not subject. |
+| `generate_video_from_video` | Restyle/transform an existing video. Keeps original motion. |
+| `generate_elements` | Reference-driven video. **Primary route for DNA → video.** Prompt = Seedance Locked Intro (`Total` + `[GLOBAL LOOK]` / `[CAST]` / `[LOCATION]` + `SHOT N`). Every DNA in `visual_dna_ids` must also be `@Name` in that prompt. |
+| `generate_first_last_frame` | Keyframe interpolation between two frames. |
+| `generate_lipsync` | Lipsync an existing waveform onto a face. **Not the route for dialogue in a film you are generating** — write the line in the Seedance prompt instead. |
+| `generate_music` | Music generation (Suno + variants). |
+| `generate_speech` | TTS for narration, voiceover and standalone audio. **NOT for scene dialogue** — Seedance 2/2.5 performs quoted lines itself. |
+| `generate_sound` | Sound effects. |
+| `generate_3d` | 3D models from text / single image / multi-view. Returns GLB/FBX/OBJ/USDZ. |
+| `analyze_video` | Kolbo's official video understanding (agentic Gemini — navigates the timeline itself, so long videos are cheap and timestamp / counting / "when does X happen" questions are answered directly). Public video URL or YouTube URL + optional `prompt`; sync, token-billed. See `workflows/transcription.md`. |
+| `separate_audio_stems` | Split a soundtrack into Dialogue / Music / Effects / without-dialogue (M&E). The route for removing or isolating speech, instrumental beds, and stems for dubbing. 5cr, inline. See `workflows/audio-stems.md`. |
+| `clean_dialogue_leftovers` | Strip voices still faintly audible in an M&E layer. 17cr — only when the user reports the leak, it trades fidelity. |
+| `separate_ambience` | Pull room tone out of the Effects bed as its own lane. 17cr. |
+
+### Discovery, Library, Visual DNA, Moodboards, Chat, Publishing
+| Tool | Purpose |
+|------|---------|
+| `list_models` / `list_voices` / `check_credits` / `show_plans` / `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. `show_plans` renders the balance + upgrade card for pricing/plan/upgrade questions. |
+| `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` / `list_cinematic_presets` | Style overlays + presets. `list_presets` spans FOUR distinct catalogs (`image`, `image_edit`, `video`, `music`; `text_to_video` is an alias for `video`, `shorts` is empty) — the `video` one holds 200+ Seedance shot recipes. `list_cinematic_presets` is a separate tool feeding the `cinematic` arg, never `preset_id`. Full doctrine + intent→catalog map: `references/workflows/presets.md`. 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** — 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. |
+| `create_moodboard` / `update_moodboard` / `delete_moodboard` | Moodboards from image URLs → AI master style prompt → pass `moodboard_id` to generation tools. Edit with `update_moodboard`; never delete+recreate. |
+| `clone_voice` / `import_elevenlabs_voice` / `delete_voice` | Custom voices (clone CHARGES CREDITS — confirm first; new voices show in `list_voices`) |
+| `trim_video` | Frame-accurate trim of a Kolbo-hosted video (tool waits and returns the URL). `edit_video` also gained `remove_background`. |
+| `create_doc` / `list_docs` / `get_doc` / `update_doc` / `share_doc` / `delete_doc` | AI Docs (Magic Pad): YOU author full HTML documents (plans, briefs, scripts, research) saved into the user's project, editable in the Kolbo app. `share_doc` returns a public link. `update_doc` content replaces the WHOLE doc — `get_doc` first. |
+| `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) and `thinking_level` from `list_models` type `text` thinkingLevels; omitted/invalid levels use the resolved model default, safeguards and legacy `deep_think` take precedence |
+| `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. |
+| `blender_list_sessions` / `blender_get_scene` / `blender_search_docs` / `blender_capture_viewport` / `blender_apply_operations` / `blender_import_media` / `blender_render` / `blender_undo` / `blender_file_operation` / `blender_execute_python` / `blender_get_command_status` | Connected Blender control through the Kolbo extension. Every tool crosses into an external desktop host; read `workflows/blender.md` before the first call. |
+
+## ⚠️ Edit in place — never delete+recreate (HARD RULE — always on)
+
+Existing Kolbo objects keep a stable id. Generations, `@Name` / `#Name` bindings, share links, and teammates already point at that id. Deleting and making a new one orphans those links and throws away the stored analysis.
+
+| What changed | Tool |
+|---|---|
+| Visual DNA name, description, stills, sheet, type, attributes | `update_visual_dna` |
+| Project-cast DNA description or purpose note | `update_project_asset` |
+| Moodboard name, style notes, images | `update_moodboard` |
+| Project name or description | `get_project` then `update_project` |
+| Project cast membership | `link_project_asset` / `unlink_project_asset` (list first) |
+| Session title | `rename_session` |
+| Custom agent name / persona | `update_agent` |
+| AI Doc title / content | `get_doc` then `update_doc` |
+
+`delete_*` is only for objects the user asked to remove.
+
+## ⚠️ Visual DNA `@Name` in the prompt (HARD RULE — always on)
+
+Passing `visual_dna_ids` is **not enough**. For every DNA in that array you MUST also write `@ExactStoredName` in the prompt text (the `name` from `list_visual_dnas` / `create_visual_dna`). The engine binds identity by parsing `@tags`. No `@tag` → the DNA is wasted.
+
+- Right: `visual_dna_ids: ["vdna_…"]` + prompt `@Zohar walks into frame`
+- Wrong: `Zohar's`, `Zohar`, `the left man`, `the man on the LEFT`, `Visual DNA anchors: the man on the LEFT…` — none of these bind
+- Never invent a role label or possessive as a substitute for `@Name`
+- **Asset tags are exempt from every English-only prompt rule.** Copy the actual stored `name` verbatim in its original language, case, spaces, punctuation, and diacritics. Stored `אסתר` → `@אסתר`, `ليلى` → `@ليلى`, `小雨` → `@小雨`; never `@Esther`, `@Layla`, or another translated/transliterated alias. Never slugify or rename an existing DNA to make a prompt English. Preserve these tags through every rewrite and final tool call.
+- 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 ANY generation call using `visual_dna_ids` (images, edits, Elements, or Creative Director): resolve each id to its stored `name` from the selected asset binding or `list_visual_dnas` / `get_visual_dna`, then confirm the final prompt includes the exact `@` + name. Missing or rewritten even one → fix the prompt, do not fire.
+
+Resolve names with `list_visual_dnas` first. Full binding rules: `references/workflows/visual-dna.md`.
+
+**Every still on a DNA can reach the model.** Kolbo now sends all of a DNA's reference images that fit the model's image-slot cap (user uploads first, then one still per DNA, then leftovers round-robin). If a DNA only gets one leftover slot and has no real character sheet, unused stills become a white grid. Mixed-vibe stills or environment photos that contain a main character will confuse the generation — keep each DNA surgically clean. Create-and-pack rules: `references/workflows/visual-dna.md`.
+
+## ⚠️ `enhance_prompt` — leave it OFF (HARD RULE)
+
+**Never pass `enhance_prompt: true` unless the user asked for it in words.** It is
+not a quality knob you turn on to be helpful — it sends the prompt to a rewriter
+first, so the model renders *different words than the ones the user wrote*.
+
+- The user says "make it more cinematic" → that is a request to change **your**
+  prompt. Write the better prompt yourself. It is NOT permission to enhance.
+- Only "enhance the prompt" / "improve my prompt" / "expand this prompt" is.
+- Passing it silently is the worst case: the card shows an `enhanced` chip the
+  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 — `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)
+
+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)
+
+This `kolbo` skill is the mandatory first layer for every Kolbo media task. Do **not** call `generate_*` / `generate_elements` / `generate_image_edit`, or write the billable prompt for them, until you have loaded every matching dependency **in this turn** (the `skill` tool for bundled skills and Read of the required Kolbo references). "I already know this," memory, or a prior-turn load does not count. Users will never invoke these skills themselves.
+
+Dependencies accumulate: narrative Elements work requires **Kolbo + filmmaking + elements-prompting**, not whichever one was loaded first. Before the first paid call, silently check the stack and load anything missing.
+
+| 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 / 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:
+
+`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 30,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). `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)
+
+A user-named tool — in any language — overrides every other rule. Recognized aliases:
+
+| User said (any language) | Use exactly |
+|---|---|
+| "director", "creative director", **"במאי"**, "ad set", "campaign tool", "storyboard tool" | `generate_creative_director` |
+| "image edit", "edit", "modify", "remove background", **"עריכת תמונה"** (paired with a per-image instruction) | `generate_image_edit` |
+| "elements" / **"אלמנטים"** | `generate_elements` |
+| "first/last frame" / **"פריימים"** | `generate_first_last_frame` |
+| "lipsync" / **"ליפסינק"** | `generate_lipsync` |
+
+**Mixed signals — named tool always wins.** "Image edit with the director tool to make 4 angles" → `generate_creative_director`.
+
+## ⚠️ Generate vs Edit (when the user did NOT name a tool)
+
+| User intent | Action | NOT this |
+|-------------|--------|----------|
+| "Create a video from scratch" | `generate_video` | — |
+| "Edit / Cut / Trim / Add subtitles / Remove silence / Convert to 9:16" | Load `video-production` skill → FFmpeg | ❌ `generate_video` |
+| "Create motion graphics / animated text / title sequence" | Load `remotion-best-practices` skill | ❌ `generate_video` |
+| "Animate this image" | `generate_video_from_image` | — |
+| "Restyle this video as anime" | `generate_video_from_video` | — |
+| "Modify THIS one image" — change bg, remove object, recolor | `generate_image_edit` | ❌ Not for multi-output |
+| "4 angles / poses / views of this character" / "variations of this character" | `generate_creative_director` with `visual_dna_ids` | ❌ Don't loop `generate_image_edit` |
+| "4 variations of THIS exact image" (same prompt, different seeds) | `generate_image` with `num_images=4` | ❌ Not `generate_image_edit` |
+
+## Core Workflow
+
+**Preset contract** (full doctrine — catalogs, intent→search map, cinematic dimensions: `references/workflows/presets.md`):
+- Custom instructions live on the **preset**, and it is almost always better than the paragraph you would improvise. Prefer `generate_image` + `preset_id` (not `generate_character_sheet`) for Character Sheet / Headless / Bible / location / product sheets.
+- **Presets are not image-only.** `type: "video"` holds 200+ Seedance 2 shot recipes (chase, orbital, drift, showcase, VFX, storyboard) and feeds `generate_video` + `generate_elements`; `image_edit` and `music` have their own catalogs. `image` and `image_edit` ids are NOT interchangeable.
+- **Search on the user's own noun when their request matches a catalog** — they rarely say "preset". `list_presets({ type, search: "<their word>" })` matches name + description + category together.
+- Always pass `search`. That is a silent id lookup. Do **not** omit it (that dumps a 632k-char 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. Never claim a preset was used without passing it.
+- Cinematic presets are a DIFFERENT tool (`list_cinematic_presets` → the `cinematic` arg, one id per dimension, omit for Auto) — never `preset_id`.
+
+1. **Check credits** ONCE per conversation (Step 0). Skip if already checked.
+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.
+   - **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.
+5. **Validate inputs** against model caps — see `references/workflows/cost-and-validation.md`.
+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 | User-approved ids + URLs only. Compaction-safe memory — not the user gallery or a candidate scratchpad. |
+
+**🛑 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.
+
+**Detecting failure — a generation can fail three ways. Treat ALL as failure:**
+
+1. **Tool returns `error`** — explicit. Surface it and suggest a retry. Keep the `generation_id` in the active run for recovery; never put failures in production.md.
+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 successful results the user explicitly approves to `.kolbo/production.md` — never pending, rejected, or 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`. 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.
+
+## ⚠️ 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.
+
+After the user approves a bucket, write its `session_id` + plan name into `.kolbo/production.md` `### Sessions`. Do not create or update the file for a pending bucket. Full rules: `references/workflows/production-planning.md` + `production-log.md`.
+
+## 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.
+- **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. Keep pending ids in the current run; persist only the user-approved winners in `.kolbo/production.md`.
+
+## ⚠️ Multi-output? Default to `generate_creative_director` (CRITICAL)
+
+`generate_creative_director` is **an agent**, not a niche tool. Plans each scene internally, locks consistency, runs in parallel. For 2+ related outputs, it's almost always right.
+
+**Tie-breaker:** about to fire ≥2 `generate_image` calls and the user did NOT dictate per-image prompts? Stop. Use `generate_creative_director`.
+
+**Never loop `generate_image` sequentially.** Either Creative Director or one parallel batch.
+
+**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.
+
+**Use a TRUE video-to-video model.** Image-to-video models reject with `WRONG_MODEL_TYPE`. Valid: `wan/2-7-videoedit`, `happyhorse/video-edit`, `kling-video/o3-video-to-video`, or any model whose DB `type` includes `video_to_video` (use `list_models({ type: "video_to_video" })`).
+
+**Motion-control / animate-move models invert the inputs**: `reference_images[0]` = the CHARACTER IMAGE to animate, `source_video` = the driving/reference video whose motion is transferred. Omitting the character image returns a `MOTION_CONTROL_INPUTS` error.
+
+**Do NOT** decompose into frames. **Do NOT** re-fire if the first call returned URLs.
+
+## ⚠️ Character-Driven Video — Frames First, Then Animate (CRITICAL)
+
+For any ad / story / scene-based video **created from scratch** featuring a Visual DNA character (NOT v2v edits):
+
+1. **Generate the shot frames first** via `generate_creative_director` with `scene_count` + `visual_dna_ids` (image mode). DNA is strongest in image gen; user can approve cheaply.
+2. **Confirm the frames** if >3 shots.
+3. **Animate each frame** with `generate_video_from_image`, fired in parallel.
+
+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`.
+
+## ⚠️ 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; Library already shows the 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.
+
+**Never update `.kolbo/production.md` merely because a generation succeeded.** Keep the result provisional in the generation card / Library, ask the user to choose, and write only the explicitly approved winner in the same turn as approval. Brief approval before generation is not output approval; silence, a topic change, or requesting the next task is not approval. See `references/workflows/production-log.md`.
+
+## Limitations & Safety
+
+- **Real people**: never identify specific individuals in photos, even public figures. Describe visible attributes only.
+- **NSFW**: Kolbo enforces content safety at the model level. If a generation fails on safety grounds, rephrase rather than retrying identically.
+- **Copyright**: style references are fine ("in the style of Studio Ghibli"); verbatim reproduction is not.
+- **No fabricated URLs**: only share URLs that actually came back from a tool call.
+
+## Sharing HTML Artifacts
+
+HTML/SVG/Mermaid artifacts have a **Share** button in the preview toolbar that uploads the artifact and copies a permanent public URL (no login required to view). Or call `publish_html_artifact({ title, content })` directly.
+
+---
+
+If at this point you still don't know which `references/` file to load, default to `references/models/prompt-copilot.md` for generation prompts or `references/workflows/cost-and-validation.md` for cost/validation questions, or just keep going with this core file's rules.

package/skill/references/models/seedance.md

@@ -23,48 +23,20 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
   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 MULTI-shot prompt with only shot body and no Total / Multishot header is a **failed turn** — rewrite before calling `generate_*`. A single-shot prompt uses the single-shot header instead and carries no `Multishot ON`; see "Shot count comes from the USER".
+  - 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 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 — and if they ask for ONE shot, deliver one shot with no `Multishot ON`.
+- **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: 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)
 
-## Shot count comes from the USER — decide this FIRST
-
-A SHOT is one uninterrupted camera take. A CUT is what separates two shots. Count
-what the user asked for before choosing the output shape.
-
-**ONE shot requested → write ONE shot.**
-- No `SHOT N` labels, no per-shot beats, and **no `Multishot ON`**. That flag declares
-  "this clip contains hard cuts" — on a single take it is false, and it additionally
-  forces prompt enhancement on the wire, rewriting the prompt the user just approved.
-- Header: `Single continuous shot, Xs total, AR`. Closing line: `Total: Xs / 1 shot / AR`.
-- Describe the take as ONE unbroken movement; internal beats are timestamps inside it
-  (`0:00–0:05 — the camera pushes in past the doorway…`), never numbered shots.
-- **Keep the Locked Intro blocks.** GLOBAL LOOK / CAST / LOCATION / PHYSICS are the
-  consistency stack, not the multi-shot part — a long continuous move needs them most.
-
-These all mean ONE shot, however long it runs and however far the camera travels:
-"one shot", "single shot", "one continuous take", "a oner", "no cuts", "unbroken",
-"one continuous camera movement". **Writing "N connected shots … no visible cut" is a
-contradiction** — no cut means one shot. That exact output is what this rule exists to
-stop; never emit it.
-
-**N shots requested → deliver exactly N.** Never round up to a nicer-sounding number,
-never add shots the user did not ask for, and never invent a maximum.
-
-**No count given → pick the SIMPLEST structure the idea needs.** One continuous take is
-very often right. A montage is a deliberate choice, never a default.
-
-## Locked Intro (DEFAULT for any cinematic piece — single-shot and Elements included)
-
-After the Total lines, every prompt with recurring people, a recurring place, or more than one shot opens with the locked blocks. A single continuous take keeps ALL of them — only the `SHOT N` beats and `Multishot ON` are multi-shot-only. Skip entirely for: a bare POV/orb with no cast, 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.
 
 ```
 N connected cinematic shots, Xs total, AR, Multishot ON

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

@@ -17,7 +17,7 @@ Creative generations bill against the user's Kolbo credit balance. **Billing uni
 | **Music** | per generation (flat) | 15–60 cr | Suno v5 = 15 cr; ElevenLabs Music = 60 cr |
 | **Speech (TTS)** | per 100 characters | 2–5 cr/100 chars | ElevenLabs (5) × 500 chars = 25 cr |
 | **Sound effects** | per generation (flat) | 4–7 cr | |
-| **3D model** | per model (flat, × toggle multipliers on Meshy V7) | 5–300 cr | Trellis = 5 cr; Trellis 2 = 60 cr; Meshy v5/v6 = 150 cr; Meshy V7 = 186 cr base (no-texture ~124; +rigging ~217; +rigging+animation ~236); Marble 1.1 = 300 cr |
+| **3D model** | per model (flat) | 5–300 cr | Trellis = 5 cr; Meshy v6 = 150 cr; Marble 1.1 = 300 cr |
 | **Transcription (stt)** | per minute of audio | `model.credit × duration_minutes` | |
 
 ## Calculation Formulas

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

@@ -130,18 +130,18 @@ visual_dna_ids: ["vdna_abc",  // dana
 
 The match is **literal and case-insensitive**, so:
 - The `@name` must equal the stored `name` field (e.g. if `name: "esther_model"` → write `@esther_model`, not `@Esther`, not `@אסתר`, not `@the model`).
-- Any-language characters are supported — if the DNA was created with `name: "אסתר"` you write `@אסתר`. Use the EXACT stored string.
+- Any-language characters are supported — if the DNA was created with `name: "אסתר"` you write `@אסתר`. Use the EXACT stored string. Asset tags are identifiers and are exempt from English-only prompt/dialogue rules: never translate, transliterate, lowercase, strip diacritics, replace spaces, or slugify an existing name. Resolve the selected id with `get_visual_dna` if the current name is unknown; never guess from the user's language or a production-log alias.
 - Mentions terminate at punctuation (`.,!?`), double-spaces, another `@`, or end of string. So `@maya, wearing...` matches `maya`.
 
 This composes with `@image1` / `@image2` positional tags for plain reference/source images — see "Reference Tagging" below.
 
 ### ⚠️ Naming rule for `create_visual_dna` — NO SPACES (MANDATORY)
 
-The `name` you set MUST be a **single token, lowercase, no spaces, ASCII-safe** — `esther_model`, `dana`, `tokyo_neon`, `brand_red`. Never `Sarah Johnson`, never `the red dress`.
+For a NEW DNA, prefer a short single token in the user's chosen language, such as `אסתר`, `ليلى`, `小雨`, or `esther_model`. ASCII and lowercase are not required. This naming recommendation never permits rewriting an EXISTING stored name or its prompt tag.
 
 Reason: the prompt parser stops the `@<token>` match at the first space (and at `.,!?` punctuation). So `@Sarah Johnson` matches *only* `Sarah` — if no DNA named `Sarah` exists, the mention is silently dropped and the DNA never binds. A single-token name is the only way to guarantee inline `@name` works in any sentence, in any language, without forcing the user to write awkward punctuation around it.
 
-Use underscores for multi-word concepts (`old_town`, not `Old Town`). When the user proposes a name with spaces, accept the intent but collapse it into a single token before storing (`"Sarah Johnson"` → `sarah_johnson`) and tell them once how you'll refer to it. Source of truth: [kolbo-docs / Visual DNA & @ References](https://docs.kolbo.ai/kolbo-code/visual-dna).
+For new multi-word names, suggest underscores in the same language. Do not silently translate or rename a user-specified name. For existing names, preserve the full stored string and selected id, including spaces; if binding fails, report the limitation instead of inventing an alias or renaming the user's DNA.
 
 ## Reference Tagging — `@image1` / `@video1` / `@Audio1`
 

package/skill/references/models/3d.md

@@ -1,51 +0,0 @@
-# 3D Generation (`generate_3d`)
-
-Three model families, discoverable via `list_models` with types `3d_text_to_model`,
-`3d_image_to_model`, `3d_multi_image_to_model` (plus `3d_world` for world/splat generation).
-Settings are **family-scoped** — params for a different family than the selected model are
-silently ignored, so match the params to the model you pass.
-
-## Families & when to pick each
-
-| Family | Identifiers | Pick when | Base credits |
-|---|---|---|---|
-| **Meshy V7** | `fal-ai/meshy/v7/image-to-3d`, `fal-ai/meshy/v7/multi-image-to-3d` | Game-ready assets, characters (rigging!), highest fidelity, PBR | 186 |
-| Meshy v5/v6 | `meshy/v5/multi-image-to-3d`, `meshy/v6-preview/*` (incl. the only **text**-to-3D) | Text mode, or legacy compatibility | 150 |
-| Trellis v1 | `trellis-image-to-3d`, `trellis-multi-image-to-3d` | Fast + cheap drafts | 5 |
-| Trellis 2 | `trellis-2-image-to-3d` | Better quality than v1, 4K textures, polygon control | 60 |
-
-Multi-image mode: 2–4 images of the SAME object from different angles (Trellis: up to 6).
-More angles = better reconstruction. Output formats: GLB (always, in-app preview), FBX/OBJ/USDZ
-and textures via the full package.
-
-## Meshy V7 settings (the full-control family)
-
-- `topology` `"triangle"|"quad"`, `target_polycount` 100–300000 (default 30000), `symmetry_mode` `"off"|"auto"|"on"`.
-- `should_remesh` (default true) — false keeps the raw reconstructed mesh, ignores topology/polycount.
-- `should_texture` (default true) — **false is cheaper** (~0.67× base). Disables `enable_pbr`,
-  `texture_prompt`, `texture_image_url`.
-- `texture_prompt` (≤600 chars) and/or `texture_image_url` — guide texturing.
-- `enable_tpose` — output an A/T-pose character.
-- **Rigging**: `enable_rigging` auto-rigs a humanoid (best with clear limbs) + basic walk/run
-  animations; `rigging_height_meters` (default 1.7). **~1.17× credit surcharge.**
-- **Animation**: `enable_animation` (requires `enable_rigging`) applies one preset from Meshy's
-  ~697-action library via `animation_action_id` 0–696 (default 92 "Idle"; 0=Idle, 1=Walk, 14=Run,
-  4=Attack, 22=Dance, 290=Wave — full catalog at docs.meshy.ai/en/api/animation-library).
-  **Additional ~1.09× surcharge on top of rigging.** Returns `animation_glb`/`animation_fbx` plus
-  the rigged character files.
-
-Credit math is toggle-multiplied off the base price (server-computed; the exact quote comes back
-in the generation response) — e.g. base 186 → +rigging 217 → +animation 236; no-texture 124.
-
-## Trellis settings
-
-- v1: `texture_size` `"512"|"1024"|"2048"`, `ss_guidance_strength`/`ss_sampling_steps`,
-  `slat_guidance_strength`/`slat_sampling_steps` (more steps = higher quality, slower),
-  `mesh_simplify`, `multiimage_algo` `"stochastic"|"multidiffusion"` (multi mode), `seed`.
-- Trellis 2: `resolution` `"512"|"1024"|"1536"`, `t2_texture_size` `"1024"|"2048"|"4096"`,
-  `decimation_target` (polygons), `remesh` (default true), `tex_sampling_steps`, `seed`.
-
-## Text mode (Meshy v6-preview only)
-
-`prompt` required; `art_style` `"realistic"|"sculpture"` (sculpture disables PBR),
-`enable_prompt_expansion` for AI prompt enrichment.