@kolbo/mcp 1.83.0 → 1.83.2

package/package.json

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

package/skill/SKILL.md

@@ -20,7 +20,7 @@ allowed-tools: Bash, Read, Write, Edit
 
 You have direct access to the Kolbo AI creative platform via MCP tools (auto-configured by `kolbo auth login`). Use them to generate and deliver real content — do NOT just describe what you would create.
 
-> 🚫 **Don't dump generated URLs as bare text or markdown links in chat** — the UI already shows results in **Library** (right panel) and on the generation card. Refer by description ("the rainy scene"), store URLs in `.kolbo/production.md`. INLINE `![](url)` images ARE allowed for catalog-style replies (per-item thumbs in numbered lists).
+> 🚫 **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).
 
@@ -55,7 +55,7 @@ Then generate **only** with the confirmed parameters. If the user changes an opt
 
 - **Video/lipsync `credit` is per-SECOND, not per-clip**: `total = credit × duration`. This is the universal rule for video/firstlast/elements/motion_graphic/cast types, not a per-model exception — `list_models` states it inline now. The one carve-out is a model with `flat_credit_by_resolution` set.
 - **Batch totalling 100+ credits**: run `check_credits` first.
-- **Quote real cost**: after firing, log `credits_used` (from the tool result) to `.kolbo/production.md` — never `base × count`.
+- **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.
 
@@ -105,12 +105,10 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 |------|-------------|
 | `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" })`. |
-| `edit_image` | Operation-routed image tools such as upscale, reframe, outpaint, background work, inpaint and enhance. Before choosing `model`, call `list_models` with the operation family (`image_upscale`, `image_reframe`, `image_zoom_out`, `background_remove`, `graphics_enhance`, etc.) and pass a concrete returned identifier. `multi_shot` and `split` use pinned processing, so omit `model` for those. |
 | `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. |
-| `edit_video` | Operation-routed video tools such as upscale, reframe, audio generation, watermark/background removal, face swap, extend, inpaint and retake. Discover the real engines through the operation family (`video_upscale`, `video_reframe`, `video_to_sound`, `video_extend`, etc.), compare caps/cost/`params`, and pass a concrete identifier — never a `kolbo_gateway_*` navigation row. |
 | `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. |
@@ -209,7 +207,9 @@ Scene dialogue is **never** `generate_speech` or `generate_lipsync`. Seedance 2
 
 ## ⚠️ Load the matching skill BEFORE generating (HARD RULE)
 
-Do **not** call `generate_*` / `generate_elements` / `generate_image_edit` until you have loaded the matching skill **in this turn** (the `skill` tool for bundled skills, and/or Read of the `references/` file). "I already know this" is not a load. Users will never invoke these skills themselves.
+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 |
 |---|---|---|
@@ -295,7 +295,7 @@ Four surfaces show the same job. Use this map — never invent a fifth:
 | **Library** (right panel — "This session" / "All media") | User-facing gallery of **completed** media | "Is the user's output there?" Point humans here — never to chat history. Finished clips/images land automatically — do **not** call `list_media` / `get_media` / `list_session_generations` to "check if it worked" after a generate you already submitted (burns credits/context, can pollute the session). A K/logo spinner tile **is** the in-progress placeholder for the same job, not a missing one. |
 | **Chat generation card** | Progress chrome while a job is in flight | Status badge only (`Generating` / done). A **black / empty preview while Generating is NORMAL** — the iframe has nothing to paint yet. It is **not** failure, not "lost", not a reason to re-fire. |
 | **`get_generation_status`** (MCP) | Agent API for job state | Whether the server job is `completed` / `failed` / still running, and the final `urls`. This is your SoT for in-flight work — **not** the card pixels. |
-| **`.kolbo/production.md`** | Your private log across turns | Ids + URLs after success. Compaction-safe memory — not the user gallery. |
+| **`.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_*`.
 
@@ -305,14 +305,14 @@ Four surfaces show the same job. Use this map — never invent a fifth:
 
 **Detecting failure — a generation can fail three ways. Treat ALL as failure:**
 
-1. **Tool returns `error`** — explicit. Surface, suggest retry, log `generation_id`.
+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 successes to `.kolbo/production.md` — never failed items.
+- 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`.
@@ -345,13 +345,13 @@ How to thread:
 3. New scene or new concept → new session. Same scene / same cast pass → never a new session.
 4. Image tools and video tools cannot share an id (server kinds differ). Cast/Locations stay image; scene clips stay video.
 
-Write each session's `session_id` + plan name into `.kolbo/production.md` `### Sessions`. Do **not** mark the phase Approved or jump to the next bucket until the user confirms (or you asked a labeled GATE and they answered). Full rules: `references/workflows/production-planning.md` + `production-log.md`.
+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. Persist every `generation_id` in `.kolbo/production.md`.
+- **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)
 
@@ -406,7 +406,7 @@ Avoid bare URL dumps and HTML `<table>` grids — Library already provides a gal
 
 **After `generate_creative_director` completes** — share results as individual URLs, one per scene. Do NOT create an HTML grid artifact.
 
-**Always** park every successful URL + `session_id` in `.kolbo/production.md` as a **candidate**. Promote to Approved and advance the plan only after the user confirms — see `references/workflows/production-log.md`.
+**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
 

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

@@ -115,6 +115,6 @@ Cost formula: `final_cost = credit × resolution_multipliers[resolution] × (sou
 - **Video**: `720p` (or the cheapest), with `default_duration` (or shortest in `supported_durations`).
 - **Sound**: respect `sound_enabled_by_default`; if false, leave off.
 
-## Always Log the Resolution / Duration / Sound Choices
+## Log Approved Resolution / Duration / Sound Choices
 
-Log `credits_used`, resolution, duration and sound state per entry — format in `production-log.md`.
+After the user approves the actual result, log its `credits_used`, resolution, duration, and sound state. Pending and rejected outputs stay out; use the format in `production-log.md`.

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

@@ -70,12 +70,12 @@ For ads featuring a specific product:
 
 | User provides | Do |
 |---|---|
-| **Product photo** (local file or URL) | `upload_media({ source })` → tag as `@image1` in prompt → log to `.kolbo/production.md` under `### Products` |
+| **User-approved product photo** (local file or URL) | `upload_media({ source })` → tag as `@image1` in prompt → log to `.kolbo/production.md` under `### Products` |
 | **Product URL only** (no photo) | Run `workflows/research-first.md` first to scrape hero images + brand palette; re-host via `upload_media` → use Kolbo CDN URL |
 | **Multiple angles** | Upload all in parallel (one `upload_media` call each) → pass all in `reference_images` → tag `@image1`, `@image2`, … per `workflows/visual-dna.md` reference-tagging rules |
 | **Nothing — text only** | Ask once: "Do you have a product photo? It dramatically improves fidelity." If they say no, proceed text-only but warn quality may be lower |
 
-**Always log products in `.kolbo/production.md`** so subsequent ads in the same workspace reuse the same CDN URL without re-uploading.
+**Log user-approved products in `.kolbo/production.md`** so subsequent ads reuse the same CDN URL. Generated variants stay out until approved.
 
 ## Reference Media Cap
 
@@ -121,6 +121,6 @@ Default-to-cheapest when the user hasn't expressed a quality intent and the diff
 1. **Always pick an ad format explicitly** with the user — never auto-pick.
 2. **Always confirm aspect ratio + resolution + quantity** before firing.
 3. **Always check for a brand kit** before scraping fresh — `Read .kolbo/brand-kits/<slug>.md` first.
-4. **Always log products + brand kits in `.kolbo/production.md`** so future ads reuse instead of re-uploading / re-scraping.
+4. **Log approved products + brand kits in `.kolbo/production.md`** so future ads reuse them. Do not log generated variants before output approval.
 5. **Retries:** one retry only when `failure.retryable === true` or the generation completed with empty URLs (SKILL.md "⚠️ Generation lifecycle"); otherwise surface the reason and let the user adjust.
 6. **Strict NO uninvited additions** in every ad prompt: "NO captions, NO subtitles, NO watermarks, NO extra text beyond what's specified."

package/skill/references/workflows/filmmaking.md

@@ -1,5 +1,7 @@
 # Filmmaking Router
 
+**Prerequisite:** the `kolbo` skill must already be loaded in this turn. This router extends Kolbo; it does not replace Kolbo's tool, model, cost, approval, and logging rules. For any Elements/reference-driven/Visual-DNA video, also load the `elements-prompting` skill before compiling or generating. If a dependency is missing, stop and load it first.
+
 Operate as a filmmaking system, not merely a prompt writer. Preserve project truth across generations while compiling every generation into a self-contained instruction the selected model can execute.
 
 ## Start here

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

@@ -126,7 +126,7 @@ For ads that feature a specific product:
 1. **Upload product photo** via `upload_media` → Kolbo CDN URL.
 2. **Pass as `reference_images`** to `generate_creative_director` / `generate_elements` / `generate_video_from_image`.
 3. **Tag with `@image1`** in the prompt.
-4. **Log in `.kolbo/production.md`** under a `### Products` subsection so future ads in the same workspace reuse the same CDN URL (don't re-upload).
+4. **After the user approves the product asset, log it in `.kolbo/production.md`** under `### Products` so future ads reuse the same CDN URL. Pending variants stay out.
 
 If the user gives a **product URL** instead of a photo, see `workflows/research-first.md` — scrape, extract images, re-host via `upload_media`, persist as a brand kit at `.kolbo/brand-kits/<slug>.md`.
 

package/skill/references/workflows/marketplace-cards.md

@@ -125,7 +125,7 @@ Skip questions whose answer is obvious from the request.
   ...
   ```
   Do NOT wrap them in an HTML grid artifact — the canvas already shows the gallery.
-- Log all URLs to `.kolbo/production.md` under `## Production: <product name>` → `### Marketplace Cards` subsection.
+- After the user approves specific cards, log only those URLs to `.kolbo/production.md` under `## Production: <product name>` → `### Marketplace Cards`.
 - If a `main_image` came back with text / props (compliance failure), surface the issue and re-fire with stronger prompt prohibitions — don't ship a non-compliant main image.
 
 ## Existing Main-Image Reuse
@@ -143,4 +143,4 @@ If the user already has an approved `main_image` from a prior session and wants
 3. **Always reuse brand kit** — Read `.kolbo/brand-kits/<slug>.md` first; pass palette + fonts to every A+ module.
 4. **Recommend GPT Image 2 + 2K/4K for dense-text A+ modules** — Nano Banana renders text well but GPT Image 2 wins at multi-line technical layouts.
 5. **For bundles, always use `generate_creative_director`** — never fire 13 parallel `generate_image` calls.
-6. **Log everything to `.kolbo/production.md`** — marketplace listings get updated quarterly; reuse beats regenerate.
+6. **After approval, log the approved cards to `.kolbo/production.md`** — pending and rejected variants stay out; approved listings can then be reused.

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

@@ -143,7 +143,7 @@ For `social_carousel` / `ad_creative_pack` (multi-output by design):
 - Call the chosen MCP tool — single command, no preamble.
 - For multi-output: `generate_creative_director` returns N URLs; share them as individual lines (do NOT build an HTML grid artifact — the canvas already shows the gallery).
 - For single-output: one image URL.
-- Log every URL + model + resolution + mode into `.kolbo/production.md` under `### <Mode>` subsection.
+- After the user approves a result, log only that URL + model + resolution + mode into `.kolbo/production.md` under `### <Mode>`.
 
 ## UX Rules
 

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

@@ -1,116 +1,104 @@
 # Production Log — `.kolbo/production.md`
 
-Load this file when starting a multi-step production, or before any continuation of prior media work ("edit", "redo", "the same character", `@name` references, "scene N").
+Load this file when starting a multi-step production, or before continuing prior
+media work ("edit", "redo", "the same character", `@name`, "scene N").
 
-## Why It Exists
+## Purpose and boundary
 
-Every URL, id, and brief produced by a Kolbo MCP tool MUST be recorded in `.kolbo/production.md` in the user's workspace. This file is **your** (agent) source of truth for prior artifacts across turns — not chat history (unreliable / compacted) and not a substitute for the user's **Library** gallery. URLs scattered across `tool_result` blobs are unreliable to re-scan and disappear entirely on context compaction. If the user named a model, write that name into `## 🎯 Now` and keep using that family on every follow-up — compaction is not permission to cheapest-swap.
+`.kolbo/production.md` is the agent's durable registry of **user-approved**
+artifacts across turns. It is not the user's gallery and it is not a scratchpad
+for generations that are still being judged.
 
-**User vs agent SoT:** finished media for the human → **Library → This session**. Job state while in flight → `get_generation_status`. Your memory → this file. Chat cards are progress UI only.
+The boundary is absolute:
 
-## When to READ it
+- Do not create, edit, or append to the file when a generation succeeds.
+- Do not log pending candidates, rejected takes, failures, unapproved session
+  ids, planned buckets, or estimated costs.
+- Write only after the user explicitly approves the actual generated result.
+- Approval of the brief before generation does not approve the output.
+- Silence, a topic change, asking for another take, or merely continuing the
+  workflow is not approval.
 
-Read `.kolbo/production.md` **before** acting on any of these signals:
-- "edit", "animate", "combine", "redo", "polish", "fix", "regenerate"
-- "the same character / scene / image / video / sound", "that X", "scene N", "the rainy one", etc.
-- `@name` references for Visual DNA
-- Any continuation of prior media work ("now make scene 3")
-
-If the file is missing and the user is referencing prior media, ask the user — do not guess from chat.
-
-## ⚠️ Approval gates — the user is usually still iterating (READ THIS FIRST)
-
-Most media work is an **approval loop**, not a single shot. The user generates, looks, asks for another take, and keeps going until satisfied. This is the normal case for **images, image sets, Visual DNAs, moodboards, and videos** alike.
-
-The log records **what the user approved** — not everything you produced. Getting this wrong is expensive in both directions: log too eagerly and take 3 of 7 is enshrined as "the character"; log too late and the approved URL is gone after compaction.
-
-**The loop:**
-
-1. **Generate** candidates.
-2. **Present them so the user can actually judge.** Never ask "approve?" over bare URLs or ids — the user cannot see those. Use the widget-carrying tools:
-   - Visual DNAs → `list_visual_dnas` (renders a thumbnail media grid; `create_visual_dna` returns text only, so follow it with this)
-   - Moodboards → `list_moodboards`
-   - Images / videos / audio → show the returned URLs as markdown images/links
-   Say plainly which ones are in play, e.g. "created `@maya` and `@maya_alt` — here they are".
-3. **Ask for a decision** and name the options ("keep the first, redo the second, or both?").
-4. **Repeat** until the user is satisfied. Log nothing as approved during this stage.
-5. **On approval → promote in `.kolbo/production.md` immediately**, in the same turn: move the winner out of Candidates, update `**Approved:**`, then you may start the next plan bucket. Do not advance `**Now working on:**` to the next phase before this.
-
-**Never write an artifact into the log as approved without the user's approval.**
-
-If they didn't volunteer a yes, end the turn with the GATE block from
-`production-planning.md` §3.
-
-**If the user genuinely doesn't care** — "whatever you think", "you pick", "don't care", or they hand you the whole job — then **you decide**. Choose, say in one line which you picked and why, and log it as usual with `(agent-selected)`. Do not stall a production waiting for an approval the user has already delegated to you.
+Library → This session is the human-facing source for completed and provisional
+media. `get_generation_status` is the source for in-flight jobs. The production
+log is the source only for what has been locked.
 
-**Don't lose candidate URLs while iterating.** Recording a candidate is not the same as claiming approval, and compaction will eat unlogged URLs. Park in-flight takes under a `#### Candidates (pending approval)` bullet, and on approval promote the winner to a normal entry and mark the rest `(rejected)`:
+## Read before continuation
 
-```md
-2. **Rainy street walk** — neon reflections, slow dolly
-   #### Candidates (pending approval)
-   - take 1: https://...02-rain-a.png  (flux-2-pro, 2026-08-17)
-   - take 2: https://...02-rain-b.png  (flux-2-pro, 2026-08-17)
-```
+Read `.kolbo/production.md` before acting on:
 
-after the user picks take 2:
+- "edit", "animate", "combine", "redo", "polish", "fix", "regenerate"
+- "the same character / scene / image / video / sound", "that one", "scene N"
+- `@name` references for Visual DNA
+- any continuation of previously approved media work
 
-```md
-2. **Rainy street walk** — neon reflections, slow dolly
-   - still: https://...02-rain-b.png  (flux-2-pro · 1K, approved 2026-08-17)
-   - take 1: https://...02-rain-a.png  (rejected 2026-08-17)
-```
+If the file is missing and the user references prior work, resolve it from the
+current conversation or Library/session tools. Do not guess and do not create a
+placeholder entry.
 
-**Re-confirm state after a long loop.** When a session has churned through many takes, restate the approved set before moving on — "so we're locked on: @maya, moodboard #noir, scenes 1-3" — and make the log match. An approval loop that ends without a written-down approved state is how the wrong asset ships.
+## Approval loop
 
-## When to WRITE to it
+1. Generate the requested result.
+2. Present it through the generation card / Library so the user can judge it.
+3. Ask for a concrete decision: which result to lock, redo, or discard.
+4. Keep all iterations provisional and leave `.kolbo/production.md` untouched.
+5. When the user explicitly approves a visible result, update the log in that
+   same turn and record only the approved winner.
+6. Only after that write may the production advance to the next gated bucket.
 
-Two writes, different jobs:
+Clear approvals include `approve`, `lock`, `that's the one`, `use take 2`, or an
+equally unambiguous choice naming the actual result. If the user delegates a
+choice **after seeing the takes** ("you choose between these"), choose one,
+state which one, and log it as `(user-delegated choice)`. A pre-generation "you
+pick" still requires approval of the resulting media before writing.
 
-1. **Right after a successful generate** — park the URL, `generation_id`, `credits_used`, and `session_id` under `#### Candidates (pending approval)` and under `### Sessions` if this is the first shot of a new bucket. Rewrite `## 🎯 Now` only for `**Awaiting approval:**` / the current bucket. This is what the runtime reminder is asking for. It is **not** approval.
-2. **After the user locks the bucket** — promote the winner, mark rejects, update `**Approved:**`, then you may change `**Now working on:**` to the next planned bucket.
+Legacy logs may contain `Candidates` sections. Treat them as unapproved. Do not
+add new candidates. Promote only the item the user explicitly chooses; leave
+unselected legacy lines untouched rather than adding new rejected entries.
 
-Where there is no production (user asked for one throwaway image and got it, or said "you pick") — approval is implicit and you log the finished entry right away. A film / ad / scene plan is never that case.
+## Write after approval
 
-Tools that REQUIRE logging:
-- `generate_image`, `generate_image_edit`, `edit_image`
-- `generate_video`, `generate_video_from_image`, `generate_video_from_video`, `edit_video`
-- `generate_elements`, `generate_first_last_frame`, `generate_lipsync`
-- `generate_music`, `generate_sound`, `generate_speech`
-- `generate_3d`, `generate_creative_director`
-- `create_visual_dna`, `upload_media`
+For an approved result, record:
 
-Tools that do NOT log: `list_*`, `get_*`, `check_credits`, `chat_*`, `transcribe_audio` (read-only / discovery).
+- a plain-English label the user would use
+- output URL
+- model, resolution/quality, and video duration/sound state when applicable
+- ISO approval date
+- actual `credits_used` from the tool result—not a catalog estimate
+- `session_id` and `generation_id` when returned
+- Visual DNA / moodboard bindings such as `@maya → vdna_id`
 
-## File creation — pick the right tool to avoid the "must Read first" error
+If the approved result replaces an older approved asset, mark the old entry
+`(superseded YYYY-MM-DD)` and add the new entry beneath it. Do not delete history.
 
-`Edit` refuses to overwrite a file unless you've `Read` it first in the same session. Pick by file state:
+### Tool choice
 
 | State | Tool |
 |---|---|
-| File **does not exist** (typical first turn) | `Write` with the full stub below |
-| File **exists** | `Read` first, then `Edit` |
-| Not sure | `Read` first; on ENOENT, fall back to `Write` |
+| File does not exist at approval time | `Write` with the stub below |
+| File exists | `Read`, then `Edit` |
+| Not sure | `Read`; on ENOENT, use `Write` |
 
-Stub for first creation:
+## Canonical stub
 
 ```md
-<!-- .kolbo/production.md — agent-managed media artifact registry.
+<!-- .kolbo/production.md — agent-managed registry of user-approved media.
+     Pending and rejected generations stay in Library, not in this file.
      User may hand-edit; agent must Read-before-Edit to reconcile. -->
 
 # Production Log
 
 ## 🎯 Now
 
-**Brief:** <paraphrase of user's overall goal in 1-3 sentences>
-**Now working on:** <the immediate next step>
-**Approved:** <locked assets — DNAs, moodboards, scenes; "nothing yet" if still iterating>
-**Awaiting approval:** <what you've presented and are waiting on; omit when nothing is pending>
-**Sessions:** <plan names + ids — Cast / Locations / Scene 01 — …; "none yet" until first generate>
+**Brief:** <paraphrase of the approved production goal in 1-3 sentences>
+**Now working on:** <the next approved production step>
+**Approved:** <locked assets>
+**Sessions:** <approved plan names + ids>
 **Last updated:** <ISO date>
 
 ---
 
-## Production: <name from user's request, slugified human label>
+## Production: <name from user's request>
 
 ### Sessions
 ### Cast
@@ -120,101 +108,44 @@ Stub for first creation:
 ### Final
 ```
 
-Subsections (`### Cast` etc.) are **suggested defaults**, not required. Adapt: a logo set has `### Logos`, an album has `### Tracks`, a 3D render has `### Models`. Leave empty subsections out of the file when you create entries.
-
-## Entry shape
+Subsection headings are suggestions. Adapt them to the production and omit empty
+ones.
 
-One bullet per artifact. Write the label **the way the user would reference it next time** ("the rainy one"), not the model's raw output.
+## Entry example
 
 ```md
 ### Sessions
-- **Cast** — sess_abc  (image) — @maya @doron
-- **Locations** — sess_def  (image) — @night_market
-- **Scene 01 — coffee shop** — sess_ghi  (video) — shots 1–4
-- **Scene 02 — rooftop chase** — (pending)
-
-### Cast
-- **Maya** — female, 30, urban photographer, leather jacket
-  - portrait: https://...characters/maya.png  (nano-banana-2, 2026-05-13)
-  - visual DNA: vdna_8f2c  (@maya)
-  - session: sess_abc
+- `Scene 02 — rainy street` — `ses_abc123` (video; approved 2026-08-28)
 
 ### Scenes
-1. **Coffee shop morning** — Maya at counter, soft light, wide shot
-   - still: https://...scenes/01-coffee.png  (flux-2-pro, 2026-05-13)
-   - video: (pending)
 2. **Rainy street walk** — neon reflections, slow dolly
-   - still: https://...scenes/02-rain.png  (flux-2-pro, 2026-05-13)
-   - video: https://...videos/02-rain.mp4  (kling-2, 2026-05-13)
-```
-
-## Header rewrite rule (Manus pattern — IMPORTANT)
-
-The `## 🎯 Now` block at the top of the file is **rewritten every turn** to keep the brief + current step near the model's recency window. Body sections (everything below the first `---`) are **append-only**.
-
-When a user request supersedes a previous artifact (e.g., "redo scene 2 with more rain"), do not delete the old entry. Mark it `(superseded YYYY-MM-DD)` and place the new entry beneath:
-
-```md
-2. **Rainy street walk** — neon reflections, slow dolly
-   - still: https://...scenes/02-rain.png (superseded 2026-05-13)
-   - still: https://...scenes/02-rain-v2.png  (flux-2-pro, 2026-05-13)
-   - video: https://...videos/02-rain-v2.mp4  (kling-2, 2026-05-13)
+   - video: https://.../02-rain-b.mp4
+   - model: kling-2 · 1080p · 5s · sound-on
+   - generation_id: gen_8a2c…
+   - session_id: ses_abc123
+   - credits_used: 24
+   - approved: 2026-08-28
 ```
 
 ## Rules
 
-1. **First touch `Write`, subsequent touches `Read` → `Edit`** (see "File creation" above). If `Edit` fails on exact-match, `Read` again — the user may have hand-edited.
-2. **Plain English labels** — write what the user would call it.
-3. **Append-only body.** Only the `## 🎯 Now` header is rewritten. Never delete artifact entries; mark them `(superseded)` instead.
-4. **Do not log failures.** Only successful generations.
-5. **Resolve user references via the log, not chat history.** If the user says "scene 3," use the URL the log says is scene 3, even if a later tool_result mentioned a different URL.
-6. **One file per workspace.** Multiple concurrent productions go under separate `## Production: <name>` headings inside the same file.
-7. **Approved state is user-granted, never assumed.** A generation succeeding is not approval. Only the user's "yes" — or their explicit delegation of the choice to you — promotes a candidate to an approved entry. Silence is not approval; neither is the user moving on to another topic.
-8. **The `## 🎯 Now` block names what is locked.** Keep an `**Approved:**` line there listing the currently-approved cast, DNAs, moodboards, and scenes, so the approved state survives compaction and is the first thing you read next session.
-9. **Sessions are part of the log.** Every bucket from the plan gets a `### Sessions` row (name from the plan, `session_id`, kind, which `@tags` / scene it holds). After the first generate of a bucket, `rename_session` to that plan name and write the id. Reuse that id — do not spawn untitled sessions for retakes.
-
-## Bulk Generation Entry Shape
-
-For batch runs (50-item UGC sets, etc.), persist every `generation_id` (even for failures) — required for `get_generation_status` recovery and cross-session dedupe.
-
-```md
-12. ✅ Asian F 24, bedroom, hype POV
-    - generation_id: gen_8a2c…
-    - url: https://…
-    - model: seedance-2 · 720p · 10s · sound-on
-    - generated: 2026-05-14T07:42Z
-13. ❌ Latino M 31, gym
-    - generation_id: gen_ff19…
-    - error: 429 Too many generation requests
-    - retry_after: 2026-05-14T07:43Z
-```
-
-## Always log the resolution / duration / sound choices
-
-Production-log entries should include the resolution and (for video) duration + sound state alongside the URL, so the user can see what they paid for:
-
-```md
-- still: https://...01-coffee.png  (flux-2-pro · 1K, 2026-05-14)
-- video: https://...02-rain.mp4   (kling-2 · 1080p · 5s · sound-off, 2026-05-14)
-```
+1. Approved artifacts only; generation success is never approval.
+2. First touch uses `Write`; later touches use `Read` then `Edit`.
+3. Body history is append-only. Mark replacements superseded; never delete.
+4. Never log failures, rejected takes, or pending candidates.
+5. Keep one file per workspace; separate productions use separate headings.
+6. Resolve references from approved entries, not from an arbitrary later take.
+7. Add a session row only when its associated result/bucket is approved. Reuse
+   the active `session_id` for provisional retakes without logging it.
+8. Preserve prompt tags and their URL / DNA-id bindings in approved entries.
 
-## Production Log vs TodoWrite
+## Production Log vs task planning
 
-Use both — different jobs:
-
-| | `.kolbo/production.md` | `TodoWrite` |
+| | `.kolbo/production.md` | Task plan |
 |---|---|---|
-| Purpose | Durable artifact registry | Ephemeral step plan |
-| Lifetime | Persists across sessions / compaction | Per turn / per request |
-| Content | URLs, ids, briefs | "Do X, then Y, then Z" |
-| Example | `still: https://...01-coffee.png` | `Generate visual DNA for Maya` |
-
-## Real Cost Quoting
-
-Every generation now returns `credits_used` (multiplier-adjusted total) and `credits_breakdown` (per-model attribution). **Log `credits_used` to `.kolbo/production.md`, not `base × count`.**
-
-```json
-{ "credits_used": 12, "credits_breakdown": [{ "model": "nano-banana-2", "base": 8, "final": 12, ... }], "urls": [...] }
-```
+| Purpose | Durable approved artifact registry | Current provisional work |
+| Content | Locked URLs, ids, sessions, actual cost | Generate, review, redo, choose |
+| Write time | After explicit output approval | Before and during iteration |
 
-When the user asks "how much did I spend?" → call `get_session_usage` for the real, multiplier-adjusted session total + per-tool + per-model breakdowns (same numbers as the desktop bottom-bar counter).
+When the user asks how much a session spent, call `get_session_usage`; do not
+derive a remaining balance from production-log entries.

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

@@ -59,9 +59,10 @@ Omitting `session_id` on generate creates a new session. First call of a bucket
 omits it, then `rename_session` immediately; every later call in that bucket
 passes the same id. Image and video kinds cannot share an id.
 
-Write those planned names into `.kolbo/production.md` `### Sessions` as
-`(pending)` during MAP. Fill in the real `session_id` when the first generate
-returns. See `production-log.md`.
+Keep planned names in the working plan during MAP. Do not create or update
+`.kolbo/production.md` for pending buckets. After the user approves a bucket,
+write its plan name and real `session_id` under `### Sessions`. See
+`production-log.md`.
 
 Separate **states** from **identities**: clean vs bloodied, day vs night, intact
 vs broken are their own assets. Do not expect one DNA to carry both.
@@ -123,7 +124,7 @@ parse — not a vague "looks good?":
 
 ```
 GATE — Cast
-Presented: @maya, @doron (candidates in the log)
+Presented: @maya, @doron (provisional; not yet in the production log)
 Lock + next: "lock cast" / "yes" / "next" / "now locations"
 Stay: "redo @maya" / "another take of the leather jacket"
 ```
@@ -135,8 +136,9 @@ Treat as confirmation: `yes`, `ok`, `lock`, `approved`, `that's the one`,
 Not confirmation: silence, "maybe", a question about something else, another
 take request. Ask the GATE again once; do not invent a yes.
 
-On lock: promote candidates → Approved in `.kolbo/production.md`, then start
-the next planned bucket in **its** session.
+On lock: write the approved result into `.kolbo/production.md`, then start the
+next planned bucket in **its** session. Rejected and pending takes never enter
+the log.
 
 ## 4. Shoot
 

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

@@ -50,7 +50,7 @@ The bulk-API rule applies: **external** (non-Kolbo) URLs in `reference_images` /
 1. `Bash: curl -fsSL "<external-url>" -o /tmp/<name>.<ext>` (or use WebFetch where it returns the binary)
 2. `mcp__kolbo__upload_media` with the local file → returns Kolbo CDN URL
 3. Use the returned CDN URL in any subsequent generation call
-4. Log both URLs in the production log (so the user can trace provenance)
+4. After the user approves the researched direction, log its two source URLs in the production log for provenance
 
 ## Synthesizing the research
 
@@ -154,7 +154,7 @@ The other workflow files consume the brand kit:
 - `workflows/marketplace-cards.md` — palette + fonts critical for A+ module consistency
 - `workflows/marketing-studio.md` — voice/tone shapes UGC presenter dialogue; palette shapes any branded overlays
 
-Always cite the brand-kit slug in the production log so reviewers can trace which kit drove a given generation.
+When an approved generation is logged, cite the brand-kit slug so reviewers can trace which kit drove it. Do not update the log for pending results.
 
 ## Building prompts informed by the research
 

package/skill/references/workflows/transcription.md

@@ -149,7 +149,7 @@ visual_dna_ids: ["vdna_8f2c"]   // maya
 
 The point is **not** to dump an essay into the prompt — it's to make sure every concrete detail the next model needs to preserve (or change) is named, so the chain doesn't lose continuity across steps.
 
-**Production-log tie-in:** when you analyze a generated still/clip, write a one-line description into `.kolbo/production.md` next to the URL — that way the next chained step can read the log instead of re-analyzing.
+**Production-log tie-in:** only if the still/clip is already user-approved and present in `.kolbo/production.md`, add a one-line analysis beside its URL. Never create an entry for an unapproved asset merely because it was analyzed.
 
 ## Image Analysis Detail (when the user uploads images)
 

package/skill/references/workflows/troubleshooting.md

@@ -68,7 +68,7 @@ When a generation fails, `get_generation_status` returns a structured `failure`
 
 Branch on `failure.category` / `failure.retryable`:
 
-- `category === "content_policy"` (or `code === "CONTENT_FLAGGED_SENSITIVE"`) → **do not retry the same prompt**. Tell the user the model refused, suggest a less explicit phrasing or a Visual DNA fallback. Log to `.kolbo/production.md` Failures section with the exact reason.
+- `category === "content_policy"` (or `code === "CONTENT_FLAGGED_SENSITIVE"`) → **do not retry the same prompt**. Tell the user the model refused and suggest a less explicit phrasing or a Visual DNA fallback. Keep the failure out of `.kolbo/production.md`.
 - `category === "auth"` or `code === "[KOLBO_AUTH_EXPIRED]"` → surface the reconnect flow, don't auto-retry.
 - `retryable === true` (transient: network, rate limit, provider 5xx) → retry once with the same payload after a short pause. If it fails again, surface to user.
 - `retryable === false` and unknown category → surface the raw `message` to the user, don't retry.

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

@@ -63,7 +63,7 @@ When the user says "use the model אסתר" but you've only created a DNA for "
 
 ## ⚠️ Don't re-fetch / re-list your own outputs (CRITICAL)
 
-After a generation tool returns its URLs, those URLs are **already** in **Library** (right panel — This session) and in `.kolbo/production.md`. Do **NOT** call `list_media`, `get_media`, `get_media_stats`, `list_visual_dnas`, or `chat_send_message` with `media_urls` on those URLs just to "verify" or "fetch thumbnails of the results":
+After a generation tool returns its URLs, those URLs are already in **Library** (right panel — This session). They enter `.kolbo/production.md` only after the user approves the actual result. Do **NOT** call `list_media`, `get_media`, `get_media_stats`, `list_visual_dnas`, or `chat_send_message` with `media_urls` just to "verify" or "fetch thumbnails":
 
 - It burns credits and time for zero new information.
 - Every such tool call streams partial output into the session, which forces Library to re-evaluate (visible flicker on the gallery tiles).
@@ -75,7 +75,7 @@ After a generation tool returns its URLs, those URLs are **already** in **Librar
 - You need details about something generated in an **earlier session** that you don't have a record of.
 - You're chasing a specific user reference like "the rainy clip from yesterday" that isn't in the current chat's `.kolbo/production.md`.
 
-For media you generated this session, you already know the prompt, model, and result URL — write that into `.kolbo/production.md` and reference it from context.
+For media generated this session, use the current tool result while approval is pending. After explicit output approval, write the winner's prompt, model, and URL into `.kolbo/production.md`.
 
 ## ⚠️ Presenting list results — show thumbnails (MANDATORY)
 
@@ -179,7 +179,7 @@ Lipsync @video1's speaker to the dialogue track @Audio1, keeping the original am
 2. **For edits, the source is `@image1` (or `@video1`).** In `generate_image_edit`, the first entry of `source_images` is the canonical base.
 3. **Visual DNA tags are name-based, not positional.** `@maya` always means the DNA you registered as `name: "maya"`, regardless of where its id sits in `visual_dna_ids`.
 4. **Tag every reference you actually pass.** If you pass a reference but never mention it in the prompt, the engine often treats it as decorative — either drop it or name it explicitly.
-5. **Tags carry across the production log.** When you log a generation to `.kolbo/production.md`, write the prompt with the tags intact and record the `@name → URL` / `@name → vdna_id` binding alongside.
+5. **Tags carry across the production log.** When the user approves a generation and you log it, preserve the prompt tags and record the `@name → URL` / `@name → vdna_id` binding alongside.
 6. **Tag even single-reference calls when a DNA, video, or audio is involved.** Single plain image with no DNA can use prose ("this image"), but as soon as the call also carries a DNA, a video ref, or an audio ref, tag every asset so the engine knows the subject vs. the modifier role.
 
 **Failure modes the tags fix:**

package/src/tools/generate.js

@@ -1254,12 +1254,12 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_elements ─────────────────────────────────────
   server.tool(
     'generate_elements',
-    'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". PRIMARY ROUTE FOR A DNA-ANCHORED MULTI-SHOT FILM: one call can carry the whole sequence — seedance-2-5 takes 4-30s, up to 30 shots and 20 Visual DNAs in a SINGLE generation (seedance-2: 4-15s, 9 DNAs) — instead of a stack of separate clips. DIALOGUE IS PERFORMED NATIVELY: quoted dialogue in the prompt comes back as synced voices with lip movement, room tone and the SFX named in the AUDIO block — never route scene dialogue to generate_speech or generate_lipsync. Write dialogue in ENGLISH; other languages (Hebrew included) do not perform reliably. COST: resolution is a MULTIPLIER, not a flat fee (vs 720p: 480p x0.44, 1080p x2.25, 4k x4.95) — run blocking/draft passes at 480p and re-run only the approved cut at delivery resolution. PROMPT CONTRACT (Seedance / Elements): Locked Intro only — Total line, then [GLOBAL LOOK] / [CAST] / [LOCATION] / SHOT N. Do NOT write SCENE CONTEXT / OPTICS / ACTION department packs. Every Visual DNA in visual_dna_ids MUST also appear in the prompt as @ExactDNAName (e.g. "@Zohar walks…") — never "Zohar\'s" or "the man on the left" as a substitute. IMPORTANT: different models accept different numbers of inputs — call list_models type="elements" and read elements_max_images / elements_max_videos / elements_max_audio on the chosen model before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
+    'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". PRIMARY ROUTE FOR A DNA-ANCHORED MULTI-SHOT FILM: one call can carry the whole sequence — seedance-2-5 takes 4-30s, up to 30 shots and 20 Visual DNAs in a SINGLE generation (seedance-2: 4-15s, 9 DNAs) — instead of a stack of separate clips. DIALOGUE IS PERFORMED NATIVELY: quoted dialogue in the prompt comes back as synced voices with lip movement, room tone and the SFX named in the AUDIO block — never route scene dialogue to generate_speech or generate_lipsync. Write dialogue in ENGLISH; other languages (Hebrew included) do not perform reliably. COST: resolution is a multiplier. When list_models publishes `video_input_credit` and this call carries videos, charge that rate against `sum(ceil(each input video duration)) + output duration`; otherwise use the normal output-second rate. PROMPT CONTRACT (Seedance / Elements): Locked Intro only — Total line, then [GLOBAL LOOK] / [CAST] / [LOCATION] / SHOT N. Do NOT write SCENE CONTEXT / OPTICS / ACTION department packs. Every Visual DNA in visual_dna_ids MUST also appear in the prompt as @ExactDNAName (e.g. "@Zohar walks…") — never "Zohar\'s" or "the man on the left" as a substitute. IMPORTANT: different models accept different numbers and durations of inputs — call list_models type="elements" and read elements_max_images / elements_max_videos / elements_max_audio plus min_video_duration / max_video_duration before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
     {
       prompt: z.string().describe('Locked Intro prompt (Seedance/Elements): Total line, [GLOBAL LOOK], [CAST] with @ExactDNAName for every visual_dna_ids entry, [LOCATION], then SHOT N. Not SCENE CONTEXT/OPTICS/ACTION packs. Never substitute "the left man" or "Zohar\'s" for @Name.'),
       model: z.string().optional().describe('Model identifier. If the user already named a family (Grok / Kling / Veo / Seedance / …), pass THAT family — never default to Seedance because Elements often uses it. Use list_models type="elements" for exact ids and elements_max_* caps. Do NOT omit (omitting = Smart Select).'),
       reference_images: z.array(z.string()).optional().describe('Array of image references (product shots, character references, etc.). Accepts a public URL (forwarded as-is; if the API rejects an external URL as untrusted, it is auto-rehosted into the media library and retried once) OR an absolute local path, which is uploaded for you. **Cap: pass at most `elements_max_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.**'),
-      reference_videos: z.array(z.string()).optional().describe('Array of reference videos for models that accept video inputs. Accepts a public URL (forwarded as-is; if the API rejects an external URL as untrusted, it is auto-rehosted into the media library and retried once) OR an absolute local path, which is uploaded for you. **Cap: pass at most `elements_max_videos` URLs from list_models — if the cap is 0 the model rejects videos.**'),
+      reference_videos: z.array(z.string()).optional().describe('Array of reference videos for models that accept video inputs. Accepts a public URL (forwarded as-is; if the API rejects an external URL as untrusted, it is auto-rehosted into the media library and retried once) OR an absolute local path, which is uploaded for you. **Cap: pass at most `elements_max_videos` URLs and keep every clip within `min_video_duration`-`max_video_duration` from list_models.** If `video_input_credit` is present, every attached video contributes `ceil(its duration)` to combined-second billing, in addition to output duration.'),
       reference_audio_urls: z.array(z.string()).optional().describe('Array of reference audio tracks for models that accept audio inputs. Accepts a public URL (forwarded as-is; if the API rejects an external URL as untrusted, it is auto-rehosted into the media library and retried once) OR an absolute local path, which is uploaded for you. **Cap: pass at most `elements_max_audio` URLs from list_models.** `audio_url` remains supported as the legacy single-track form.'),
       audio_url: z.string().optional().describe('A single reference audio track — legacy form of reference_audio_urls. Accepts a public URL (forwarded as-is; if the API rejects an external URL as untrusted, it is auto-rehosted into the media library and retried once) OR an absolute local path, which is uploaded for you. **Audio constraints: `elements_max_audio` from list_models gates whether audio is accepted at all; audio duration must fall within `min_audio_duration`-`max_audio_duration`; format must be in `supported_audio_formats` (if specified).**'),
       files: z.array(z.string()).optional().describe('Untyped catch-all for mixed media — images, videos AND audio, each a URL or an absolute local path. The kind is detected from the file extension and the item is routed to the matching reference list, so a local .mp4 is sent as a video and a local .mp3 as audio. Prefer the typed lists (reference_images / reference_videos / reference_audio_urls) when you already know the kind; they accept local paths too. URLs given here are forwarded as URLs, never re-uploaded. **Caps still apply per kind: `elements_max_images` / `elements_max_videos` / `elements_max_audio` from list_models. Local uploads are capped at 200MB each.**'),

package/src/tools/models.js

@@ -106,6 +106,7 @@ const identifierRow = (m) => ({
   name: m.name,
   types: m.types,
   credit: m.credit,
+  ...(m.video_input_credit != null ? { video_input_credit: m.video_input_credit } : {}),
   ...(m.recommended ? { recommended: true } : {}),
   ...(m.new_model ? { new_model: true } : {}),
 });
@@ -115,7 +116,7 @@ function registerModelTools(server, client, options = {}) {
   // ─── list_models ───────────────────────────────────────────
   server.tool(
     'list_models',
-    'List available AI models on Kolbo. Filter by `type` to narrow to a generation type, and pass `format: "json"` to enumerate the catalog with exact identifiers — `format: "json"` + `type` returns the full raw model documents (every constraint field, for programmatic comparison / cap validation before submitting a generation); `format: "json"` alone returns a compact index of EVERY model and its identifier. Default `format: "text"` returns the human-readable summary. NEVER guess a model identifier: call this tool. ⚠️ COST: for any model whose type is video / firstlast / elements / motion_graphic / cast, `credit` is a PER-SECOND rate, not a per-clip price — multiply by the requested `duration` before quoting cost to the user (e.g. `credit: 9` at `duration: 8` is 72 credits, not 9). This is the universal rule, not a per-model exception. The one carve-out is a model with `flat_credit_by_resolution` set — those charge the flat rate regardless of duration. Every other model type (image, audio, 3D, per-token text) already bills flat per generation as `credit` states.',
+    'List available AI models on Kolbo. Filter by `type` to narrow to a generation type, and pass `format: "json"` to enumerate the catalog with exact identifiers — `format: "json"` + `type` returns the full raw model documents (every constraint field, for programmatic comparison / cap validation before submitting a generation); `format: "json"` alone returns a compact index of EVERY model and its identifier. Default `format: "text"` returns the human-readable summary. NEVER guess a model identifier: call this tool. ⚠️ COST: video / firstlast / elements / motion_graphic / cast rates are normally per output second. If a model publishes `video_input_credit` and the request includes one or more input videos, use that alternate rate and bill `sum(ceil(each input video duration)) + output duration`; each input rounds separately. A `flat_credit_by_resolution` model instead charges the flat tier regardless of duration. Every other model type (image, audio, 3D, per-token text) bills as its catalog fields state.',
     {
       type: z.string().optional().describe('Filter by DB type name. Generation: "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". Image-edit engines: "image_upscale", "image_reframe", "image_zoom_out", "inpaint", "erase", "face_swap", "background_remove", "background_replace", "skin_enhancer", "graphics_enhance". Video-edit engines: "video_upscale", "video_reframe", "video_background_removal", "video_to_sound", "video_face_swap", "video_watermark_removal", "video_extend", "video_inpaint", "video_retake". For edit_image/edit_video, query the operation-specific type and pass a CONCRETE returned identifier; never submit a kolbo_gateway_* row, because those are web-navigation aliases rather than AI engines. Legacy aliases also accepted: "image", "image_edit", "video", "video_from_image", "video_from_video", "music", "speech", "sound", "chat", "lipsync", "three_d", "first_last_frame", "transcription". Omit for all models.'),
       format: z.enum(['text', 'json']).optional().describe('Output format. "text" (default) returns a human-readable summary with the most-used caps. "json" is the source of truth for identifiers and caps: with `type` it returns the raw model documents from the API (identifier, credit, supported_durations, supported_resolutions, supported_aspect_ratios, max_reference_images, max_visual_dna, max_video_duration, …) for EVERY model of that type; without `type` it returns a compact index of every model in the catalog and its exact identifier. Use it whenever you need an identifier you have not seen listed, or must verify a cap before passing a value that might exceed a model-specific limit.'),
@@ -213,6 +214,14 @@ function registerModelTools(server, client, options = {}) {
           );
         }
 
+        if (m.video_input_credit != null) {
+          const vm = m.video_input_resolution_multipliers || {};
+          const tiers = Object.keys(vm).length
+            ? ' · ' + Object.entries(vm).map(([r, mult]) => `${r} (${mult}×)`).join(' · ')
+            : '';
+          parts.push(`video_input_price: ${m.video_input_credit} credits/combined-second${tiers} · bill sum(ceil(each input video)) + output`);
+        }
+
         // Output durations (video gen output, not source video)
         if (Array.isArray(m.supported_durations) && m.supported_durations.length) {
           const ds = m.supported_durations;
@@ -369,7 +378,7 @@ function registerModelTools(server, client, options = {}) {
       const cost = m => (m.output_token_rate != null
         ? `${m.input_token_rate ?? '?'}/${m.output_token_rate} credits per 1K tokens (in/out)`
         : isPerSecondVideo(m)
-          ? `${m.credit} credits/second (× requested duration — NOT a flat per-clip price)`
+          ? `${m.credit} credits/output-second${m.video_input_credit != null ? `; ${m.video_input_credit} credits/combined-second with video input` : ''}`
           : `${m.credit} credits`);
       const formatModel = m =>
         `${m.identifier} (${m.name}) - ${cost(m)}${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}${m.summary ? ` — ${detailed ? m.summary : brief(m.summary)}` : ''}${detailed ? formatSpecs(m) : ''}`;