@kolbo/mcp 1.21.0 → 1.22.0

package/README.md

@@ -11,30 +11,30 @@ Generate images, videos, music, speech, sound effects, multi-scene campaigns, an
 Copy this and paste it to Claude, ChatGPT, Cursor, or any AI assistant — it installs Kolbo itself (picks local config or remote connector based on what it can do):
 
 ```
-Set up the Kolbo AI MCP server so you can generate images, video, music and more.
+Connect the Kolbo AI MCP server (generate images, video, music and more).
 
-- If you can edit files (Claude Code, Cursor, Claude Desktop): add this to my MCP config, then tell me to restart the app:
-  {"mcpServers":{"kolbo":{"command":"npx","args":["-y","@kolbo/mcp@latest"]}}}
-  On first use a Kolbo login opens in my browser — I'll click Allow (no API key needed).
-- If you support remote connectors (claude.ai, ChatGPT): add the custom connector URL https://api.kolbo.ai/mcp and walk me through logging in.
+- If you can run terminal commands (Claude Code, Cursor, Claude Desktop, or any local setup): run "npx -y @kolbo/mcp install" — it auto-configures Kolbo in the right place. If you can't run it, give me the command to run. Then I'll restart the app.
+- If you're a browser chat (claude.ai, ChatGPT): add a custom connector with URL https://api.kolbo.ai/mcp under Settings → Connectors, then Connect → log in → Allow.
 
-Then confirm Kolbo is connected and offer to generate a test image of a sunset.
+No API key needed — on first use a Kolbo login opens in my browser and I click Allow. When set up, confirm Kolbo is connected and offer to generate a test image of a sunset.
 ```
 
-### Or add the config yourself
+### Or set it up yourself — one command
 
 <!--
   AI ASSISTANT SETUP INSTRUCTIONS — if you are an AI agent reading this to set up Kolbo for a user, do exactly this:
-  1. If you can edit files (Claude Code, Cursor, Claude Desktop): write the JSON block below — it has NO api key — into the user's MCP config, merging into any existing "mcpServers":
-     - Claude Code:    .claude/settings.json (or run: claude mcp add kolbo -- npx -y @kolbo/mcp@latest)
-     - Claude Desktop: claude_desktop_config.json
-     - Cursor:         .cursor/mcp.json
-     Then tell the user to restart. On their first generation a Kolbo login opens in the browser — they click Allow (no API key to create).
-  2. If you're a web chat that can't edit files (claude.ai, ChatGPT): tell the user to add the connector URL https://api.kolbo.ai/mcp under Settings → Connectors instead.
-  The JSON config alone enables every tool. The plugin below is an optional slash-command upgrade.
+  1. If you can run a terminal command (Claude Code, Cursor, Claude Desktop): run `npx -y @kolbo/mcp install` — it writes the keyless config to the right file for every installed agent. (Don't hand-edit settings.json; the installer is deterministic.) Then tell the user to restart the app. On the first generation a Kolbo login opens in the browser — they click Allow (no API key).
+  2. If you're a web chat that can't run commands (claude.ai, ChatGPT): tell the user to add the connector URL https://api.kolbo.ai/mcp under Settings → Connectors instead.
+  The plugin below is an optional slash-command upgrade.
 -->
 
-This single block is identical for every MCP client and carries **no API key** — on first use it logs you in via the browser:
+Run this once — it auto-configures Claude Desktop, Claude Code, and Cursor (whichever you have), keyless:
+
+```bash
+npx -y @kolbo/mcp install
+```
+
+Or add the config by hand — this block is identical for every MCP client and carries **no API key** (on first use it logs you in via the browser):
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -37,6 +37,7 @@
   "files": [
     "src/",
     "bin/",
+    "skill/",
     "README.md"
   ],
   "dependencies": {

package/skill/SKILL.md

@@ -0,0 +1,251 @@
+---
+version: 0.4.0
+name: kolbo
+description: |
+  Generate, edit, or analyze creative media via the Kolbo AI MCP server.
+  Covers images (GPT Image 2, Nano Banana, Flux, ...), video (Seedance 2,
+  Veo 3.1, Kling, Hailuo, ...), music (Suno), TTS (ElevenLabs), 3D,
+  transcription, Visual DNA (character consistency), Marketing Studio
+  (UGC + DTC ads + product photoshoot + marketplace cards),
+  Creative Director (multi-scene batches), HTML artifact publishing
+  (presentations, landing pages, dashboards), and the App Builder.
+
+  Use when: "generate", "create", "make me a", "edit", "animate",
+  "transcribe", "Visual DNA", "the same character", "UGC ad",
+  "TikTok / Reels / Shorts", "unboxing", "product review", "TV spot",
+  "Pinterest pin", "product photo", "lifestyle shot", "hero banner",
+  "ad pack", "social carousel", "virtual try-on", "Amazon listing",
+  "marketplace cards", "A+ content", "build a presentation/slide deck",
+  "landing page", "dashboard / widget / game", "music / song / jingle",
+  "TTS / voice", "sound effect", "3D model", "build me an app".
+
+  Chain: train Visual DNA → use vdna_id in any DNA-aware tool;
+  research-first → persist brand kit (.kolbo/brand-kits/) → DTC ads /
+  product photoshoot / marketplace cards; generate frames (Creative
+  Director) → animate each frame (generate_video_from_image).
+
+  NOT for: video editing / FFmpeg work (use video-production skill),
+  motion graphics (use remotion-best-practices skill), code editing,
+  general chat outside media generation.
+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 renders artifacts as a gallery tile + canvas. Refer by description ("the rainy scene"), store URLs in `.kolbo/production.md`. INLINE `![](url)` images ARE allowed for catalog-style replies (per-item thumbs in numbered lists).
+
+This file is the **always-loaded core**: tool inventory + universal hard rules + routing index. For any model-specific prompt rules, Visual DNA workflow, production log format, marketing workflow, cost validation, etc., **Read the matching `references/` file from the index below**. Don't try to remember the rules — load the file when you need them.
+
+## 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. Remember the credit balance for the session; don't re-check on every turn.
+
+If the user is on a whitelabel build (`sapir`, etc.), they must use their branded command — not `kolbo`. See `references/workflows/troubleshooting.md`.
+
+## Routing Index — Read These Files on Demand
+
+| If the user wants to… | Read first |
+|---|---|
+| Generate a **Seedance 2** video | `references/models/seedance.md` |
+| 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` |
+| 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` |
+| Use **Visual DNA** / character consistency / `@name` syntax | `references/workflows/visual-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` |
+| **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` |
+| Use the **App Builder** (React app generation) | `references/workflows/app-builder.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` |
+
+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, reference images, web-search grounding. |
+| `generate_image_edit` | Edit/transform an existing image. Pass `source_images` + edit prompt. |
+| `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. Does **not** support Visual DNA — use `generate_elements` for character-consistent video. |
+| `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.** |
+| `generate_first_last_frame` | Keyframe interpolation between two frames. |
+| `generate_lipsync` | Lipsync audio to an image or video face. |
+| `generate_music` | Music generation (Suno + variants). |
+| `generate_speech` | TTS. Use `list_voices` to pick a voice. |
+| `generate_sound` | Sound effects. |
+| `generate_3d` | 3D models from text / single image / multi-view. Returns GLB/FBX/OBJ/USDZ. |
+
+### Discovery, Library, Visual DNA, Moodboards, Chat, App Builder, Publishing
+| Tool | Purpose |
+|------|---------|
+| `list_models` / `list_voices` / `check_credits` / `get_generation_status` / `get_session_usage` | Discovery + status |
+| `upload_media` / `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` |
+| `create_visual_dna` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` | Visual DNA — see `workflows/visual-dna.md` |
+| `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays |
+| `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) |
+| `app_builder_*` (9 tools) | Full React app generation — see `workflows/app-builder.md` |
+| `publish_html_artifact` | Publish HTML / SVG / Mermaid to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP. |
+
+## ⚠️ 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
+
+1. **Check credits** ONCE per conversation (Step 0). Skip if already checked.
+2. **Discover models** with `list_models` using a `type` filter — but **skip when the user names a specific model**.
+3. **Pick the model**:
+   - User named one → use it.
+   - Auto-select → only from "Auto-selectable" section (models with a `summary`). Cheapest fit. Prefer `[RECOMMENDED]` when cost is similar.
+   - Never auto-select from "Named-only" section.
+4. **Validate inputs** against model caps — see `references/workflows/cost-and-validation.md`.
+5. **How calls work**: each tool blocks until generation is fully complete. Images: seconds. Video: minutes. Multiple tool calls in one response run concurrently. If a call times out, use `get_generation_status` with the returned generation ID.
+6. **Share the URL** after success. Never fabricate URLs.
+
+Model types for `list_models`: `text_to_img`, `image_editing`, `text_to_video`, `img_to_video`, `draw_to_video`, `video_to_video`, `elements`, `firstlastgenerations`, `lipsync-image`, `lipsync-video`, `music_gen`, `text_to_speech`, `text_to_sound`, `stt`, `text`, `3d_text_to_model`, `3d_image_to_model`, `3d_multi_image_to_model`, `3d_world`.
+
+## Cost Awareness — Quick Rules
+
+Full tables + formulas in `references/workflows/cost-and-validation.md`. Quick rules:
+
+- **Skip cost confirmation** when the user already specified model + count + duration, OR when a single generation costs < 5 credits.
+- **Required cost confirmation** otherwise: one-line summary, suggest cheaper alternative if available, wait for confirm.
+- **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`.
+
+## Rate Limiting & Batch Generation
+
+- `generate_image`: 30/min. All other generation tools: 10/min per type. 300/min global. `upload_media`: 300/min, no credit cost.
+- **⚠️ NEVER re-fire a generation you already called.** Aborted / timed-out calls still process server-side. Run `get_generation_status` before retrying.
+- **Batch ≤10 items**: output ALL tool calls in one response — they run concurrently.
+- **Bulk >10 items**: real-world ceilings — `generate_image` 8–10 in-flight, image-edit 5–8, video tools 3–5, `generate_video_from_video` 3, music/speech/sound 5–8. Fire one batch → wait → fire next. Persist every `generation_id` in `.kolbo/production.md`.
+- **`upload_media` external URLs first.** `files`/`source_images`/`image_url` only accept Kolbo-hosted URLs reliably; external URLs cause `400`.
+
+## ⚠️ 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" })`).
+
+**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`.
+
+## ⚠️ Detecting Failed Generations (CRITICAL)
+
+A generation can fail three ways. Treat ALL as failure:
+
+1. **Tool returns `error`** — explicit. Surface, suggest retry, log `generation_id`.
+2. **Tool returns `completed` but `urls` is empty** — silent failure (NSFW filter, model OOM, upstream 5xx). Tell user "completed without an output — retrying" and re-fire ONCE. Do NOT log to `.kolbo/production.md`. Do NOT claim it worked.
+3. **Tool hangs / never returns** — MCP poll timed out. Call `get_generation_status(generation_id)` IMMEDIATELY. The server might be done.
+
+**Always:**
+- Don't celebrate before reading the result. Verify `urls` is non-empty.
+- Don't auto-retry without surfacing the failure. Partial batches: list failed items + reasons + successful count. Never "✅ all done!" on partials.
+- Don't log failed items to `.kolbo/production.md`. Only successes.
+- Surface the user's count. "6 of 8 ready", not "videos ready".
+
+`failure` envelope structure + retry rules: `references/workflows/troubleshooting.md`.
+
+## ⚠️ Generated URLs in Chat (CRITICAL)
+
+Chat renders markdown natively. `![alt](url)` = inline image. `[label](url)` = labeled link with preview.
+
+- **Catalog-style replies** (numbered lists of characters / scenes / products): embed `![alt](url)` so each item shows inline.
+- **Conversational replies** ("4 shots ready"): keep prose short; canvas chip already shows gallery.
+
+Avoid bare URL dumps and HTML `<table>` grids — canvas already provides a gallery.
+
+**After `generate_creative_director` completes** — share results as individual URLs, one per scene. Do NOT create an HTML grid artifact.
+
+**Always** record every URL in `.kolbo/production.md` — see `references/workflows/production-log.md`.
+
+## 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/VERSION

@@ -0,0 +1 @@
+0.4.0

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

@@ -0,0 +1,106 @@
+<!-- PARITY: this file mirrors getCreativeDirectorPromptSystemPrompt() in
+     kolbo-api/src/config/systemPrompt.js (lines ~1062–1155).
+     When that function changes, update this file in the same session. -->
+
+# Creative Director — Multi-Scene Prompt Rules
+
+Load this file when the user wants **2–8 related outputs from one brief** — storyboards, ad campaigns, character lookbooks, multi-angle/multi-pose sets, scene variations. For single-image work see `models/gpt-image.md` / `models/nano-banana.md`. For single-clip video see `models/seedance.md` / `models/veo.md`.
+
+**Kolbo MCP routing:** always call `generate_creative_director` (NEVER fire ≥2 `generate_image` calls in a loop). Pass `scene_count: 1–8`, optional `visual_dna_ids`, `reference_images`, `moodboard_id`, `workflow_type: "video"` for clips, `model` to pin a specific image/video model.
+
+## What the Creative Director Tool Is
+
+A multi-scene batch generator. Submit 1–8 scenes in one go and the tool fans them out in parallel into images or videos, optionally locked to a character/product (Visual DNA) and a mood/style (Moodboard). Total wall time = slowest scene, not the sum.
+
+### The Three Modes
+- **Photo Auto Pilot** — each scene = one image. Optional reference images for style/subject. Best for: campaign batches, product shoots, character lookbooks, ad variants. Pass `workflow_type: "image"` (or omit — image is default).
+- **Video Auto Pilot** — each scene = one short video clip. Optional reference image per scene anchors the starting frame. Best for: storyboards, mood reels, ad teasers, character action sequences. Pass `workflow_type: "video"`.
+- **Cinema Manual** — per-scene **first frame + last frame** + per-scene prompt. Full cinematic control over composition transitions. Best for: hero shots, controlled camera moves, deliberate edits.
+
+### Identity & Style Locks
+- **Visual DNA** — attach a character/product preset via `visual_dna_ids` to lock identity across all scenes. Up to **8 Visual DNAs** can be active at once (e.g. main character + product + side character). See `workflows/visual-dna.md` for the `@name` syntax — every DNA must be tagged inside the prompt.
+- **Moodboard** — attach `moodboard_id` (or `moodboard_ids`) for a curated mood/style reference that anchors the aesthetic of the whole batch.
+- When the user mentions a recurring character/product, **ask** if they want to use a Visual DNA and recommend it. Same for a consistent aesthetic → recommend a Moodboard.
+
+## CRITICAL Kolbo Platform Rules
+
+- **Aspect ratio and resolution are MCP-tool params** (`aspect_ratio`, `resolution`) — NEVER include "16:9", "9:16", "1024x1536", "2K", or any size syntax inside the scene prompts.
+- **Model selection is the `model` param** — never hardcode "Nano Banana", "Veo", "Seedance", "Flux" inside the scene text.
+- Output scenes in the exact format below — anything else breaks the parser.
+- **Never pass `num_images` to `generate_creative_director`** — use `scene_count` (1–8). `num_images` is for `generate_image` (same prompt, different seeds).
+
+## The Output Format (non-negotiable)
+
+All scenes go in **ONE fenced code block** in this exact shape:
+```
+Scene 1: <prompt for scene 1>
+Scene 2: <prompt for scene 2>
+Scene 3: <prompt for scene 3>
+...
+```
+- One scene per line. Each line starts with `Scene N:` followed by a single concise prompt.
+- **No meta-commentary inside the block**: no "Output:", "Tips:", "Notes:", resolution, dimensions, or "this scene…" preamble.
+- Number sequentially from 1. Hard cap at 8 scenes.
+
+## How to Build the Batch
+
+### Step 1 — Pick the right mode
+- Single static asset per scene → **Photo Auto Pilot**
+- Motion / camera moves → **Video Auto Pilot**
+- Controlled first→last frame transitions → **Cinema Manual**
+
+### Step 2 — Decide the narrative arc
+A great batch isn't 8 random shots — it's a sequence with intent. Pick one structure:
+- **Campaign**: establishing → product hero → lifestyle → detail → close
+- **Storyboard**: setup → inciting action → escalation → climax → resolution
+- **Character lookbook**: full body → 3/4 → portrait → action → environment
+- **Ad concept**: hook → tension → reveal → CTA
+- **Variant exploration**: same concept, varying angle/lighting/mood/palette
+
+### Step 3 — Write each scene under the right framework
+
+**Photo Auto Pilot scene prompt** (image instruction):
+- Vary at least one axis between scenes: angle, lighting, mood, framing, palette.
+- Concise: 1–3 sentences. Concept-led, not keyword soup.
+- Subject + Action + Setting + Style cue.
+- If a Visual DNA is attached, refer to the subject by `@<dna-name>` — the DNA does identity work, don't re-describe it every scene.
+
+**Video Auto Pilot scene prompt** (motion instruction):
+- The model can see the reference image — **describe what happens, not what's already there**.
+- Always name a **camera move** per scene: `dolly in`, `pull-back`, `arc orbit`, `tracking shot`, `handheld natural lag`, `crane up`, `static drift`, `crash zoom`.
+- Format: `<action> + <camera move>`. Short and action-led.
+- Don't re-describe what the image already shows; describe the verb.
+
+**Cinema Manual scene prompt** (transition instruction):
+- The user provides first frame + last frame. Describe what bridges them: motion, time-passage, camera move, transformation.
+- Be explicit about the transition type: `smooth dolly between`, `time-lapse`, `match cut`, `whip pan reveal`.
+
+### Step 4 — Apply consistency rules
+- If recurring subject: keep description anchored to the same noun across scenes ("the woman", "the bottle") or use a single `@<dna-name>` consistently. Don't rename her in scene 4.
+- If recurring location: same world descriptors throughout (don't switch "Tel Aviv rooftop" to "downtown LA" mid-batch unless that's the arc).
+- Vary lighting/angle/composition between scenes — never two consecutive identical setups.
+
+## Output Discipline
+
+- Final scenes in ONE fenced code block in `Scene N:` format. **No model names, no resolutions, no aspect ratios inside scenes.**
+- When summarizing the call to the user, state separately:
+  - **Mode:** Photo Auto Pilot / Video Auto Pilot / Cinema Manual — one-line why
+  - **Recommended model:** (Nano Banana 2 / Nano Banana Pro / GPT Image 2 for photo; Veo / Seedance 2 / Kling for video) — one-line why
+  - **Aspect / Resolution preset:** what to pass — one-line why
+  - **Visual DNA / Moodboard:** recommend if applicable, or "—" if not
+  - **Why this arc works:** 1 line on the narrative choice
+- Reply explanations in the user's language; scenes themselves in English.
+
+## After Generation
+
+**Share results as individual URLs, one per scene. Do NOT create an HTML grid artifact or any combined layout.** Just list each scene's title and its image URL on separate lines — the desktop canvas already renders them as a gallery. See SKILL.md "Generated URLs in chat".
+
+## Character-Driven Video — Frames First
+
+For any ad / story / scene-based video **created from scratch** featuring a Visual DNA character, do NOT jump straight from DNA to per-shot video. The right flow is:
+
+1. **Generate the shot frames first** as still images via `generate_creative_director` with `scene_count` + `visual_dna_ids` + `workflow_type: "image"`. DNA is strongest in image generation; the user can approve cheaply before any expensive video runs.
+2. **Confirm the frames with the user** if there are more than ~3 shots, or if the user hasn't said "go straight to video."
+3. **Animate each frame** with `generate_video_from_image`, passing each approved frame as `image_url`.
+
+Skip frames-first only when the user says "go straight to video / skip the storyboard", on single-shot quick experiments, or when the user supplies their own approved frames.

package/skill/references/models/gpt-image.md

@@ -0,0 +1,111 @@
+<!-- PARITY: this file mirrors getGptImagePromptSystemPrompt() in
+     kolbo-api/src/config/systemPrompt.js (lines ~858–965).
+     When that function changes, update this file in the same session. -->
+
+# GPT Image 2 — Prompt Rules
+
+Load this file when the user wants a **GPT Image 2 / gpt-image-2** image (OpenAI). For other image models see `models/nano-banana.md`, `models/creative-director.md`, or `models/prompt-copilot.md`.
+
+**Kolbo MCP routing:** call `generate_image` (text-to-image) or `generate_image_edit` (edits with `source_images`). Pass `model: "gpt-image-2"` when the user named it; otherwise consult `list_models({ type: "text_to_img" })`.
+
+## CRITICAL Kolbo Platform Rules
+
+- **Resolution and aspect ratio are MCP-tool params** (`aspect_ratio`, `resolution`) — NEVER include `size=`, `1024x1536`, aspect-ratio tags, or any resolution syntax inside the `prompt` field.
+- Pass aspect / resolution as separate tool parameters. Quality (`low` / `medium` / `high`) is its own param too — never bake it into the prompt text.
+- Do not write Python, `client.images.generate`, OpenAI SDK code, or `size=` keyword arguments. The user is generating through Kolbo's MCP tools.
+
+## Universal Prompting Rules (apply to EVERY prompt)
+
+- **Structure + goal**: write prompts in a consistent order — background/scene → subject → key details → constraints → declared intended use (ad / UI mock / infographic / poster / logo / etc.). The "intended use" line sets the mode and polish level.
+- **Format**: prefer skimmable templates over clever syntax. Use short labeled segments or line breaks for complex requests. Minimal, descriptive paragraph, JSON-like, instruction-style, or tag-based all work — pick whichever is most maintainable for that asset.
+- **Specificity + quality cues**: be concrete about materials, shapes, textures, and medium (photo / watercolor / 3D render / vector). Add targeted quality levers only when needed (`film grain`, `textured brushstrokes`, `macro detail`).
+- **Photorealism trigger**: include the literal word **"photorealistic"** to engage the model's photorealistic mode. Supporting phrases: "real photograph", "taken on a real camera", "professional photography", "iPhone photo", "35mm film". Camera specs (lens mm, aperture) work for high-level look but are loosely interpreted — use for vibe, not physics.
+- **Composition**: specify framing/viewpoint (close-up, wide, top-down), perspective (eye-level, low-angle), lighting/mood (soft diffuse, golden hour, high-contrast). If layout matters, call out placement ("logo top-right", "subject centered, negative space on left").
+- **People, pose, action**: describe scale, body framing, gaze, object interactions ("full body visible, feet included", "looking down at the open book, not at the camera", "hands naturally gripping the handlebar").
+- **Constraints — what changes vs what stays**: state exclusions and invariants explicitly. For edits use **"change only X" + "keep everything else the same"**, and re-state the preserve list on every iteration to prevent drift. Common invariants: identity, geometry, layout, brand elements, camera angle, saturation, contrast, labels, surrounding objects. Always include "no watermark, no extra text, no logos/trademarks" unless the brief specifies otherwise.
+- **Text in images**: put literal text in **quotes** or **ALL CAPS**, specify typography (font style, size, color, placement). For tricky words / brand names, spell letter-by-letter. Recommend quality **high** when text is small, dense, or multi-font.
+- **Multi-image inputs**: reference each input by number with a short description ("Image 1: product photo… Image 2: style reference…") and describe the interaction ("apply Image 2's style to Image 1", "place the dog from Image 2 next to the woman in Image 1"). Use `@image1` / `@image2` tags — see `workflows/visual-dna.md`.
+- **Iterate, don't overload**: prefer a clean base prompt + single-change follow-ups ("make lighting warmer", "remove the extra tree", "restore the original background") over one giant prompt.
+
+## Latency vs Fidelity (recommend `quality` param)
+
+- **low**: high-volume batches, drafts, ideation, latency-sensitive cases. Often "good enough" — default for variant exploration.
+- **medium**: balanced. Style probing, normal exploration.
+- **high**: final assets, small/dense text, multi-font layouts, close-up portraits, identity-sensitive edits, infographics, diagrams, posters, UI with labels, scientific visuals, slides with charts/footnotes.
+
+## Use Cases (text → image)
+
+### Infographics, diagrams, scientific visuals, slides/charts
+- Treat as artifact spec, not illustration request. Name exact deliverable. Define hierarchy. Provide real text/data verbatim in quotes.
+- Demand: readable typography, polished spacing, no decorative clutter, no stock-photo treatment.
+- Recommend: `quality: "high"`, landscape `aspect_ratio` for deck/slide outputs.
+
+### Photorealism
+- Prompt as if a real photo is being captured in the moment. Use photography language (lens, lighting, framing). Explicitly ask for **real texture** — pores, wrinkles, fabric wear, imperfections.
+- Avoid words that imply studio polish ("glamorized", "heavily retouched") unless that's the brief.
+
+### Logos
+- Brand personality + use case + clean, original mark + strong silhouette + balanced negative space + scales from small to large. Flat design, minimal strokes, no gradients unless essential. Plain background, generous padding, centered. "Original, non-infringing".
+- Recommend: `quality: "medium"`, square or portrait `aspect_ratio`; pass `num_images: 4` for variants.
+
+### Ads / marketing creatives
+- Write like a creative brief: brand, audience, culture, concept, composition, exact copy. Let the model make taste decisions inside boundaries.
+- Quote the tagline verbatim, demand exactly one rendering, integrated into the layout.
+
+### Story-to-comic / multi-panel
+- Define the narrative as a sequence of clear visual beats — one per panel. Number each panel and describe action concretely. For multi-panel sets, prefer `generate_creative_director` with `scene_count` — see `models/creative-director.md`.
+
+### UI mockups
+- Describe the product **as if it already exists**. Focus on layout, hierarchy, spacing, real interface elements. Avoid concept-art language. Place inside a device frame when relevant ("iPhone frame").
+
+### Translation in images (edit)
+- "Translate the text to <lang>. Do not change any other aspect of the image. Preserve typography style, placement, spacing, and hierarchy. Translate verbatim. No reflow unless necessary. Do not edit logos, icons, or imagery."
+
+## Use Cases (text + image → image, edits)
+
+For edits, the prompt should be tight and constraint-heavy. Call `generate_image_edit` with `source_images: [...]`.
+
+### Style transfer
+- "Use the same style from the input image. Generate <new subject/scene>. Keep <palette/texture/brushwork> consistent. Background: <X>. Framing: <Y>. No extra elements."
+
+### Virtual try-on
+- Lock the person (face, body shape, pose, hair, expression). Change garments only. Demand realistic fit (draping, folds, occlusion), consistent lighting and shadows so it doesn't look pasted on. No accessories/text/logos unless asked.
+
+### Drawing → photoreal render
+- "Preserve exact layout, proportions, perspective. Add realism via plausible materials, lighting, environment. Do not add new elements or text."
+
+### Product mockup / extraction
+- Plain opaque background, centered product, crisp silhouette, no halos/fringing. Preserve geometry and label legibility exactly. Only light polishing + subtle contact shadow. No restyling.
+
+### Marketing creative with in-image text
+- Quote copy exactly. Demand "verbatim, no extra characters, exactly once". Specify font style, contrast, kerning, placement.
+
+### Lighting / weather transformation
+- Change ONLY environmental conditions (lighting direction/quality, shadows, atmosphere, precipitation, wetness). Preserve identity, geometry, camera angle, object placement.
+
+### Object removal
+- "Remove the <X>. Do not change anything else." Keep edits surgical. Re-state every invariant.
+
+### Person → scene compositing
+- Ground realism: natural lighting, believable detail, no cinematic grading unless asked. Lock subject identity, expression, body. Higher input fidelity helps likeness across larger scene edits.
+
+### Multi-image referencing / compositing
+- Specify which input to transplant ("the dog from `@image2`"), where it goes ("right next to the woman in `@image1`"), and what stays ("scene, background, framing"). Match lighting, perspective, scale, and shadows.
+
+### Interior design swap (precision edit)
+- "Replace ONLY <object> with <new object>. Preserve camera angle, room lighting, floor shadows, surrounding objects. Photorealistic contact shadows and fabric texture."
+
+### Character consistency across pages (children's book / story art)
+- Step 1: establish a **character anchor** — lock appearance, proportions, outfit, palette, personality on a plain background. Better yet: create a Visual DNA (see `workflows/visual-dna.md`).
+- Step 2+: feed the anchor (or DNA via `visual_dna_ids`) as input. "Continue the story using `@<dna-name>`. Do not redesign. Same <outfit/features/palette>. New scene: <X>."
+
+## Output Discipline
+
+- Pass the prompt as the `prompt` field on `generate_image` / `generate_image_edit`.
+- **NEVER** include resolution/size/aspect/ratio strings inside the prompt body.
+- When summarizing the call to the user, mention 3 things separately from the prompt:
+  - **Aspect / Resolution preset:** `<portrait | landscape | square | wide / 2K>` with a one-line why
+  - **Quality:** `<low | medium | high>` with a one-line why
+  - **Why this works:** 1 line on the key prompting choice (constraint clarity / text fidelity / identity lock / etc.)
+- If the user asks in any language other than English, write explanations in their language but keep the prompt itself English.
+- Suggest small, single-change iterations for follow-ups rather than re-writing the whole prompt.