@kolbo/mcp 1.21.0 → 1.22.0

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

@@ -0,0 +1,155 @@
+# 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").
+
+## Why It Exists
+
+Every URL, id, and brief produced by a Kolbo MCP tool MUST be recorded in `.kolbo/production.md` in the user's workspace. This file — not chat history — is your source of truth for prior artifacts: URLs scattered across `tool_result` blobs are unreliable to re-scan and disappear entirely on context compaction.
+
+## When to READ it
+
+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.
+
+## When to WRITE to it
+
+**Immediately after every successful generation tool call**, before your next tool call or your final reply. The runtime will inject a reminder after generation tool results — treat that as a hard rule, not a suggestion.
+
+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`
+
+Tools that do NOT log: `list_*`, `get_*`, `check_credits`, `chat_*`, `transcribe_audio` (read-only / discovery).
+
+## File creation — pick the right tool to avoid the "must Read first" error
+
+`Edit` refuses to overwrite a file unless you've `Read` it first in the same session. Pick by file state:
+
+| 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` |
+
+Stub for first creation:
+
+```md
+<!-- .kolbo/production.md — agent-managed media artifact registry.
+     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>
+**Last updated:** <ISO date>
+
+---
+
+## Production: <name from user's request, slugified human label>
+
+### Cast
+### Visual DNA
+### Scenes
+### Audio
+### 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
+
+One bullet per artifact. Write the label **the way the user would reference it next time** ("the rainy one"), not the model's raw output.
+
+```md
+### Cast
+- **Maya** — female, 30, urban photographer, leather jacket
+  - portrait: https://...characters/maya.png  (nano-banana-2, 2026-05-13)
+  - visual DNA: vdna_8f2c  (@maya)
+
+### 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)
+```
+
+## 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.
+
+## 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)
+```
+
+## Production Log vs TodoWrite
+
+Use both — different jobs:
+
+| | `.kolbo/production.md` | `TodoWrite` |
+|---|---|---|
+| 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": [...] }
+```
+
+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).

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

@@ -0,0 +1,174 @@
+# Research-First Creative — Scrape Before Generating
+
+Load this file when the brief involves a real brand, product URL, audience, or market — especially for ads, marketing creative, or anything tied to identity / brand palette / on-image text.
+
+## Why
+
+When the user gives you a **product URL, brand reference, or "make X for Y audience" brief**, don't jump straight to prompts. Spend one turn researching first — the cost of a single research turn is far less than 10 mis-aimed generations.
+
+## When to do research-first
+
+- Any URL appears in the brief (product page, landing page, brand site)
+- The brief names a brand, product, or company you don't already have context on
+- The brief targets a specific audience / language / market with conventions you should respect (Hebrew/Israeli, Japanese, Gen-Z TikTok, B2B SaaS, luxury, etc.)
+- The brief explicitly says "research" / "תחקור" / "look up" / "find examples" / "check best practices"
+
+## How to research (parallel calls in one response)
+
+Fire these IN PARALLEL — they're independent reads:
+
+1. **`WebSearch`** for prompt-engineering patterns specific to the chosen model. **The model name in the search query MUST be the literal model the user named** — never substitute a generic / default / "popular" model. If the user said "nano banana 2", search for `"nano banana 2" prompt …`, NOT `"flux" prompt …` or `"midjourney" prompt …`. The same HARD RULE that applies to *calling* the named model applies to *researching* it. Examples (replace `<model>` with the user's exact wording):
+   - `"<model>" prompt engineering ad image text rendering`
+   - `"<model>" hex color font specification advertising prompt`
+   - `"<model>" hebrew text RTL rendering` (or any user-named language)
+2. **`WebSearch`** for the audience / market design conventions:
+   - `<audience> advertising design trends <year>`
+   - `<language> typography <use case> RTL/LTR best practices`
+3. **`WebFetch`** the product URL with a precise extraction prompt (see below).
+4. (Optional) `WebSearch` for competitor / reference visuals to set bar.
+
+## Extracting the product page (WebFetch prompt template)
+
+Don't ask WebFetch a vague "what is this page" — ask for structured extraction:
+
+```
+Extract from this page, in compact bullets:
+1. Product name + one-line value proposition.
+2. 3–5 concrete capabilities/benefits (user-facing language).
+3. All product hero / screenshot image URLs visible in the page.
+4. Brand color hex codes — pull from inline `style=`, `<style>` tags, or
+   linked CSS, ignoring generic UI defaults (#fff/#000). Identify which
+   color plays which role (primary CTA, headline text, background, accent).
+5. Brand voice signals (tone, target user, formality).
+6. Any explicit fonts named in CSS or visible.
+```
+
+## Re-host every external image via `upload_media`
+
+The bulk-API rule applies: external URLs in `reference_images` / `source_images` / `image_url` cause **400 Bad Request**. Pipeline:
+
+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)
+
+## Synthesizing the research
+
+In the production log create:
+```md
+### Research notes
+- Prompt patterns for <model>: …
+- Audience conventions: …
+
+### Product brief
+- Name: …
+- Value prop: …
+- Capabilities: …, …, …
+
+### Brand palette
+- primary: #...
+- accent: #...
+- text: #...
+- bg: #...
+
+### Re-hosted assets
+- hero_1: <kolbo CDN url>  (from <original url>)
+```
+
+## Persist as a Reusable Brand Kit
+
+After research, **persist the brand-identity bits into a reusable file** at `.kolbo/brand-kits/<slug>.md` so future generations in any session can read it instead of re-scraping. This is the durable, cross-session record (the production log is per-production; brand kits are per-brand).
+
+**Slug rule:** lowercase, single token, derived from the domain (`drinkolipop` from `drinkolipop.com`, `acme_skincare` from `acme-skincare.io`). Strip TLD and hyphens.
+
+**Brand kit file schema** (use `Write` for first creation; `Read → Edit` for updates):
+
+```md
+<!-- .kolbo/brand-kits/<slug>.md — agent-managed brand identity registry.
+     Reusable across all generations for this brand. Read first before scraping. -->
+
+# Brand Kit: <Brand Name>
+
+url: https://...
+fetched: 2026-05-23
+last_refreshed: 2026-05-23
+
+## Identity
+brand_name: ...
+tagline: ...
+business_overview: <1-2 sentences>
+industry: <fashion | beauty | food | beverage | electronics | saas | ...>
+
+## Visuals
+logo_url: <kolbo CDN url, re-hosted via upload_media>
+primary_color: #...
+accent_color: #...
+text_color: #...
+bg_color: #...
+fonts:
+  headline: <font name>
+  body: <font name>
+  mono: <font name, optional>
+
+## Voice & Audience
+tone: <playful | refined | technical | bold | warm | ...>
+target_user: <one-line persona>
+formality: <casual | professional | luxury>
+
+## Hero Assets (re-hosted via upload_media)
+- hero_1: <kolbo CDN url>  (from <original url>)
+- hero_2: <kolbo CDN url>  (from <original url>)
+- product_1: <kolbo CDN url>  (from <original url>)
+
+## Notes
+- Any brand-specific gotchas, design rules, do-not-show items
+```
+
+### When to READ a brand kit
+
+Before any generation tied to a known brand — **always** Read first:
+
+- User mentions a brand by name ("make a Pinterest pin for OliPop")
+- User pastes a brand URL again ("make ads for drinkolipop.com")
+- User says "use the same brand as last time" / "match our brand"
+- Any DTC ad / product photoshoot / marketplace card request where the brand is implicit
+
+If `.kolbo/brand-kits/<slug>.md` exists, **skip the research-first workflow entirely** for the brand-extraction parts (palette, logo, fonts, voice). Still do `WebSearch` for fresh prompt-engineering patterns or audience trends if needed.
+
+If it doesn't exist and there's a URL, run the full research workflow above and **end by persisting the brand kit**.
+
+### When to UPDATE a brand kit
+
+- User explicitly says "the brand updated their colors / logo / fonts"
+- Brand kit is >90 days old AND the user is starting a major campaign (refresh recommended, not mandatory)
+- Generation results look "off-brand" and palette is suspect — refresh to verify
+
+Update by `Read → Edit`. Bump `last_refreshed`. Keep older asset URLs in place (they still work) and append new ones.
+
+### Brand-kit reuse downstream
+
+The other workflow files consume the brand kit:
+
+- `workflows/dtc-ads.md` — pulls palette + fonts + logo into every ad prompt
+- `workflows/product-photoshoot.md` — bakes hex codes into prompts; uses logo as `reference_images[0]`
+- `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.
+
+## Building prompts informed by the research
+
+When generating ad / marketing creative based on this research:
+
+- **Exact hex codes for every color** — `#FF4D2E` not "orange". Match brand palette.
+- **On-image text in literal double quotes** — `"שלום עולם"` not `Hebrew greeting`. Specify language and direction (RTL/LTR) when non-English.
+- **Per text element**: position, font weight, point size, color hex, alignment.
+- **Forbid uninvited additions** — explicitly tell the model: NO captions, NO subtitles, NO watermarks, NO extra text beyond what's specified. Same rule as UGC defaults.
+- **Use research findings to shape composition** — e.g. if research said "Israeli social ads favor bold contrast and minimal copy", reflect that.
+- Always **approve the concept + sample prompts with the user** before firing the full batch when the batch is ≥4 ads or the user said "approve first".
+
+## Skipping research is OK when…
+
+- User gave no URL, no brand, no audience-specific signal — pure creative ("make a sunset")
+- User said "skip research" / "just generate" / "I have the prompt ready"
+- The brief is for a single quick draft

package/skill/references/workflows/transcription.md

@@ -0,0 +1,163 @@
+# Transcription & Video/Audio Analysis
+
+Load this file when the user wants to transcribe audio/video, get SRT subtitles, or analyze video/audio content. For image analysis, use native vision (no tool needed) — see "Image analysis" at bottom.
+
+## Decision Tree
+
+You have three routes. The right one depends on the file profile — pick before calling any tool.
+
+```
+Image (jpg/png/webp)?                         → Read directly (native vision, up to 10 per pass)
+File >100MB OR >15 min OR dialogue-dense?     → HYBRID (transcribe + ffmpeg frames + Read + your synthesis)
+User wants the transcript/SRT as deliverable? → transcribe_audio, return the URLs
+Precise answer about one specific frame?      → ffmpeg that frame → Read
+Otherwise (short/medium video, mixed content) → upload_media → chat_send_message (Gemini native)
+```
+
+## Why `upload_media` → chat is **not** always the default
+
+Gemini-via-chat processes frames + motion + audio in one pass and is the simplest route when it works. But it has three known failure surfaces — recognize them and pivot to the hybrid path:
+
+1. **>100MB upload cap.** Hard limit; the upload won't succeed. No option but to split with ffmpeg or go hybrid.
+2. **Long-form decay** (rough threshold: 15–20 min). Even when it fits, attention degrades — shallow or hallucinated answers on the back half of the file.
+3. **Transcription-dense laziness.** Lectures, interviews, podcasts, anything where speech is the substance: chat models summarize aggressively, paraphrase quotes wrong, or silently skip stretches. Always transcribe these first to get the actual words, then add visuals only if they matter.
+
+## The hybrid path (workaround for all three failures)
+
+```
+1. transcribe_audio({ source }) → text, srt_url, word_by_word_srt_url, duration
+2. Read the transcript text from the tool output directly
+3. Pick 3–8 timestamps from the SRT where visuals actually matter
+4. ffmpeg -ss <ts> -i <file> -frames:v 1 <frame.jpg>   (one extract per timestamp)
+5. Read each frame with native vision (up to ~10 frames per analysis pass)
+6. Synthesize from transcript + frames + the user's question
+```
+
+This is usually **cheaper** than chat for long files — transcription is per-minute, ffmpeg + Read are free — and produces stronger answers on dialogue-heavy material because you have the complete text, not a model's summary of it.
+
+For media >30 min (past the transcription cap), split with ffmpeg into ~25-min chunks, transcribe each, concatenate.
+
+## Transcribe-as-deliverable vs transcribe-as-input
+
+| Request pattern | Action |
+|---|---|
+| "Transcribe this" / "give me an SRT" / "I need word-by-word timing" / "make subtitles" | Run `transcribe_audio`, return the URL(s). The transcript IS the deliverable. |
+| "What did they say about X?" / "Summarize this meeting" / "Find the part where they mention Y" | Run `transcribe_audio` to *get* the text → **you** read/summarize/search. Transcript is a means, not the answer. |
+
+## `transcribe_audio` — tool details
+
+- `source`: URL or absolute local path.
+- **Audio**: mp3, wav, m4a, flac, aac. **Video** (audio track extracted): mp4, mov, webm, mkv, avi, m4v.
+- **30-minute hard cap.** Longer → split with ffmpeg first.
+- Returns:
+  - `text` — full transcript, plain.
+  - `srt_url` — grouped SRT (~12 words per line, up to 2 lines per subtitle). Use this for normal subtitle delivery.
+  - `word_by_word_srt_url` — one word per cue with millisecond-precise start/end (ElevenLabs Scribe v2). Use **only** when downstream is animation (Remotion captions, after-effects karaoke, precise speech-aligned cuts). Noise for normal subtitle workflows.
+  - `txt_url` — plain text file.
+  - `duration` — seconds.
+- Cost: per-minute (`model.credit × duration_minutes`). Run `check_credits` before transcribing very long files.
+- Read-only / discovery — does NOT trigger the `.kolbo/production.md` log nudge. If the user wants the transcript saved as a durable artifact, `Write` it to a workspace file, not the production log.
+
+## `upload_media` → `chat_send_message` — tool details
+
+- `upload_media({ source: "/absolute/local/path/file.mp4" })` → returns `{ url, thumbnail_url, ... }`. **Use `url`** (the CDN URL); ignore `thumbnail_url` (preview JPG only).
+- `chat_send_message({ message, media_urls: [url] })`:
+  - `media_urls` is **mandatory** — the model only sees the file if you pass the CDN URL here. Always an array.
+  - **Omit `model`** — Smart Select auto-routes to Gemini when media is detected.
+  - Sessions do NOT remember media between messages. On retry: reuse the same CDN URL (no re-upload), but always pass `media_urls` again.
+  - Batch / many short videos cost-sensitively: `list_models` for the cheapest Gemini, pass it explicitly.
+
+## Image analysis — never via chat
+
+You have native vision. **Always `Read` images directly** (you handle up to 10 per pass). Do not `upload_media` + chat for images unless the user explicitly names a specific Kolbo chat model. Don't extract frames from images either — they're already viewable.
+
+**NEVER ask the user which path to use — diagnose from the file profile and pick.**
+
+## ⚠️ Batching Media in Chat Messages (CRITICAL)
+
+**Send ALL media in ONE `chat_send_message` call.** `media_urls` accepts up to **10 URLs**. Each separate chat call counts toward rate limits — splitting trips "Too many generation requests."
+
+```
+# Step 1: parallel uploads (one response)
+upload_media({ source: "video1.mp4" }) → url1
+... (up to 10)
+
+# Step 2: ONE chat call with all URLs
+chat_send_message({ message: "Analyze all 5 videos...", media_urls: [url1, url2, ...] })
+```
+
+On 429: wait 60s, retry the same chat call — reuse the CDN URLs, do not re-upload.
+
+**Never:** pass a local path in `media_urls` (CDN URLs only); use a transcription `.txt` URL as a video URL; construct a CDN URL yourself; split media across multiple chat calls.
+
+## Analyzing the source before a chained generation — when it's worth it
+
+Before feeding a media asset into another generation tool (`generate_image_edit`, `edit_image`, `generate_video_from_image`, `generate_first_last_frame`, `generate_video_from_video`, `edit_video`, `generate_elements`, `generate_lipsync`), think about whether you actually *know* what's in the source. If you don't, analyze it first so the next prompt can reference concrete details instead of generic adjectives.
+
+**Analyze first when:**
+
+- The source is **old** — more than a few turns back, or pulled via `list_media` / `get_media` from earlier in the project. Context has drifted; you likely don't remember the specifics.
+- The source was **user-provided without a description** — they pasted a URL or uploaded a file but didn't say what it shows.
+- The previous prompt was **vague** ("make something pretty", "a cool shot") — the output details matter and you don't know them.
+- The chain step needs to **preserve specific details** the original prompt didn't pin down (exact pose, color of a prop, lighting direction, audio room tone, etc.).
+- Source is a **video or audio** going into elements / video-from-video / lipsync — motion direction, pacing, voice characteristics, and ambient bed drive the next prompt and can't be guessed from a URL.
+
+**Skip analysis when:**
+
+- You **just generated** the asset in the same conversation with a precise prompt — that prompt *is* the spec. Re-analyzing wastes credits.
+- The edit is **mechanical** — "remove background", "brighten 10%", "loop to 5 seconds", "crop to 1:1". The source content doesn't matter.
+- The user already **described what's in it** in this turn.
+
+Default to skipping unless one of the "analyze first" cases applies — an analysis-per-step habit on long chains burns credits and latency without adding signal.
+
+**How to analyze (pick by media type):**
+
+| Source media | How |
+|---|---|
+| Image (URL or local) | Your native vision — view it directly. No `chat_send_message` round-trip needed. |
+| Video / Audio | `chat_send_message({ message: "Describe...", media_urls: [url] })`. Batch up to 10 URLs in **one** call (see batching rule above). Omit `model` so Smart Select routes to Gemini vision. |
+
+**What the analysis should extract** (use whatever is relevant for the next step's prompt):
+
+- **Subject** — pose, expression, framing (head-and-shoulders / full body / wide).
+- **Wardrobe & props** — exact colors, materials, distinguishing items.
+- **Scene & environment** — location, time of day, weather, background depth.
+- **Lighting & color palette** — dominant temperature, key/fill direction, contrast, color grade.
+- **Camera** — angle, focal length feel (wide / portrait), depth-of-field.
+- **Motion** (videos only) — direction, speed, camera move (push-in, pan, locked), what changes between first and last frame.
+- **Audio** (videos/audio only) — voice characteristics, ambient bed, speech pace, music tempo/mood.
+- **Anything that already looks wrong** — artifacts, blurred faces, wrong fingers, blown highlights, audio glitches — note these so the next prompt either fixes them (edit) or doesn't preserve them (elements/video).
+
+**Then write the next prompt with concrete references**, not generic adjectives. Example for an image-to-video chain:
+
+Bad — generic, no analysis:
+```
+prompt: "Animate this image with a slow push-in"
+image_url: <generated still>
+```
+
+Good — analyzed first, prompt names the specifics:
+```
+prompt: "Slow 4-second dolly-in toward @maya's face from the medium shot;
+         the warm golden-hour rim light on her left shoulder stays
+         consistent; the wind moves the leaves behind her gently to the
+         right. Camera locked, no shake. Subject does not turn — she keeps
+         the half-smile and direct eye contact from the still."
+image_url: <generated still>
+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.
+
+## Image Analysis Detail (when the user uploads images)
+
+When the user shares an image and asks about it:
+
+- **Analyze thoroughly**: describe composition, subjects, colors, lighting, style, text/signage, setting, mood, visible objects, and any embedded information (charts, diagrams, screenshots).
+- **Reference specific regions** when helpful: "top-left corner", "in the foreground", "the figure on the right".
+- **Extract text verbatim** when asked (OCR-style requests are fine).
+- **Cannot identify real people.** Describe hair, clothing, pose, expression, and apparent role — but never name a specific individual, even a well-known public figure. If the user insists, decline and offer to describe instead.
+- **Copyrighted content**: summarize and reference, don't reproduce verbatim large chunks.
+- If the user wants an **edit** based on the analysis, hand off to `generate_image_edit` (visual edit) or `generate_video_from_image` (motion).

package/skill/references/workflows/troubleshooting.md

@@ -0,0 +1,73 @@
+# Troubleshooting
+
+Load this file when the user hits an auth error, MCP tools aren't responding, or they're being rate-limited.
+
+## "API key is invalid or expired"
+
+This usually means the CLI is sending a key to the wrong API endpoint.
+
+**Common cause — whitelabel overlap:** if the user previously used regular `kolbo` and then switched to a whitelabel/partner CLI (e.g. `sapir`), the old API key may still be cached against the main Kolbo API. Running `kolbo` instead of the branded command (`sapir`) overwrites the MCP config with the wrong endpoint.
+
+**Fix:** tell the user to re-authenticate with their branded CLI command:
+```
+sapir auth login
+```
+(Replace `sapir` with their actual CLI command.)
+
+Then **restart the editor/session** so the MCP picks up the new key and endpoint.
+
+**Important:** whitelabel users must always use their branded CLI command (e.g. `sapir`), not `kolbo`, to keep the MCP pointed at the correct API.
+
+## MCP tools not responding or not found
+
+If Kolbo tools timeout or aren't listed, the MCP server may not be wired. Tell the user to run:
+```
+<their-cli-command> auth login
+```
+This re-wires the MCP configuration automatically. Then restart the session.
+
+## "Rate limited" (429 errors)
+
+Wait 60s for the window to reset, retry only the failed calls. For batch image work prefer `generate_creative_director` over multiple `generate_image` calls. Full rate-limit details + retry sequence: see SKILL.md "Rate Limiting & Batch Generation".
+
+## Failure envelope from `get_generation_status`
+
+When a generation fails, `get_generation_status` returns a structured `failure` field alongside `error`:
+
+```json
+{
+  "state": "failed",
+  "error": "The input or output was flagged as sensitive…",
+  "failure": {
+    "message": "The input or output was flagged as sensitive…",
+    "category": "content_policy",
+    "code": "CONTENT_FLAGGED_SENSITIVE",
+    "retryable": false,
+    "severity": "error",
+    "provider": "kie-nano-banana"
+  }
+}
+```
+
+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 === "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.
+
+## Kolbo Code Documentation
+
+Full public documentation for Kolbo Code (the CLI you are running inside) lives at **[docs.kolbo.ai/docs/kolbo-code](https://docs.kolbo.ai/docs/kolbo-code)**. If the user asks about installation, authentication, voice input, supported languages, commands, or how to uninstall, point them to the matching page below rather than guessing:
+
+| Topic | Path |
+|-------|------|
+| Overview & quick links | `/docs/kolbo-code` |
+| Installation (npm / bun / brew / scoop / choco) | `/docs/kolbo-code/installation` |
+| Sign in with Kolbo (device-code OAuth) | `/docs/kolbo-code/authentication` |
+| Push-to-talk voice input (hold `space`) | `/docs/kolbo-code/voice-input` |
+| 12 supported UI languages + RTL | `/docs/kolbo-code/languages` |
+| Full CLI command reference | `/docs/kolbo-code/commands` |
+| Uninstall + cleanup | `/docs/kolbo-code/uninstall` |
+
+The MDX sources are in the `kolbo-docs` repo under `content/docs/kolbo-code/`. When the user's question has a concrete answer in one of those pages, cite the path and summarize — do not invent new instructions.