@kolbo/mcp 1.31.7 → 1.33.0

package/README.md

@@ -1,250 +1,252 @@
-# @kolbo/mcp
-
-Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Desktop via MCP (Model Context Protocol).
-
-Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.
-
-**✨ Interactive widgets (v1.30+):** in claude.ai and Claude Desktop, generations render as live Kolbo cards — real-time progress with model + settings chips, an inline result gallery / video player, and one-click **Animate · Edit · Recreate · Download** actions. Library and model searches render as browsable grids with audio preview. Text-only clients (Claude Code, Cursor) keep the classic text responses.
-
-## Set up — paste one prompt, or one config block (keyless, no API key)
-
-### Easiest: paste this prompt to your AI
-
-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):
-
-```
-Connect the Kolbo AI MCP server (generate images, video, music and more).
-
-- 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.
-
-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 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 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.
--->
-
-Run this once — it sets up the **full** Kolbo experience (the MCP tools **and** the routing skill) for every installed agent (Claude Desktop, Claude Code, Cursor), 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
-{
-  "mcpServers": {
-    "kolbo": {
-      "command": "npx",
-      "args": ["-y", "@kolbo/mcp@latest"]
-    }
-  }
-}
-```
-
-| Client | Where the config goes |
-|--------|----------------------|
-| **Claude Code** | `.claude/settings.json` (or `claude mcp add kolbo -- npx -y @kolbo/mcp@latest`) |
-| **Claude Desktop** | `claude_desktop_config.json` |
-| **Cursor** | `.cursor/mcp.json` |
-| **Kolbo Code** | configured automatically on `kolbo auth login` |
-
-Restart your app, then ask it to generate something. The first time, a Kolbo login opens in your browser — click **Allow** (no API key to create). _Prefer an API key? Create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer) and add `"env": { "KOLBO_API_KEY": "kolbo_live_..." }` to the block above._
-
-### Browser-only (claude.ai / ChatGPT): the connector
-
-No install at all — add the custom connector **`https://api.kolbo.ai/mcp`** under Settings → Connectors, then Connect → log in → Allow. Great for generating from text or URLs; to upload your own local files, use the config install above (it runs on your machine).
-
-### Optional upgrade: add the Kolbo skill for slash-commands + smart routing
-
-The config above is all you need. If you want one-word slash-commands (`/kolbo:marketing-studio`, `/kolbo:product-photoshoot`, …) and automatic routing to the best tool with the right defaults, install the Kolbo skill on top — it's an enhancement layer, not a requirement:
-
-```bash
-# Claude Code (also writes the MCP config for you, so you can skip Step 2 above)
-claude plugin marketplace add Zoharvan12/kolbo-skills
-claude plugin install kolbo@kolbo-skills
-
-# Cursor / Codex / any agent (cross-agent installer)
-npx skills add Zoharvan12/kolbo-skills
-```
-
-The skill content is the same canonical routing logic that ships inside [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so however you connect, the behavior matches. See the full setup guide at [docs.kolbo.ai/developer-api/claude-code-skill](https://docs.kolbo.ai/developer-api/claude-code-skill).
-
-### Use it
-
-Just ask your agent naturally:
-
-**Generation**
-- *"Generate an image of a sunset over mountains"*
-- *"Create a 5-second video of waves crashing"*
-- *"Build a 4-scene storyboard for a coffee shop ad"*
-- *"Remove the background from this image"*
-- *"Make a lo-fi hip hop beat"*
-- *"Read this out loud with a British female voice"*
-
-**Marketing & UGC**
-- *"Make me a UGC ad for my sneaker brand — 9:16, talking-head style"*
-- *"TV spot for my new beverage, 15 seconds, cinematic"*
-- *"Unboxing video for this product photo"*
-
-**Brand & product imagery**
-- *"Pinterest pin for my candle brand, cottagecore mood"*
-- *"Hero banner for my landing page, wide format"*
-- *"Lifestyle shot of my product in a kitchen"*
-- *"4 ad creative variants for Meta and TikTok"*
-
-**Marketplace listings**
-- *"Generate Amazon main image + 5 secondary images for my product"*
-- *"Full A+ content set for my Shopify listing"*
-
-**Analysis & utility**
-- *"Ask Claude about the latest AI news with web search on"*
-- *"Analyze this video and tell me what prompts are shown on screen"*
-- *"What's in this image?"*
-- *"Create a Visual DNA profile called 'Alex' from these images"*
-- *"Use the same brand as last time"* (loads a persisted brand kit from the workspace)
-
-Without the optional skill, the config block alone already exposes every tool — you just describe what you want. With the skill installed, each of these is also routed to the right MCP tool with the right defaults — UGC mode picks 9:16 + sound-off + no-captions, marketplace mode enforces compliance (pure white bg, no text, no props), product photoshoot mode uses the right aspect for the platform (2:3 Pinterest, 16:9 hero banner, 1:1 IG feed), etc. The routing logic is shared with [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so the behavior is identical however you connect.
-
-## Available Tools (86)
-
-**Generation**
-| Tool | Description |
-|------|-------------|
-| `generate_image` | Text → image |
-| `generate_image_edit` | Existing image(s) + prompt → edited image |
-| `generate_video` | Text → video |
-| `generate_video_from_image` | Still image + motion prompt → video |
-| `generate_video_from_video` | Input video → restyled video, or burn in subtitles (video-to-video). `prompt` optional — prompt-less models (VEED Subtitles, Act Two, Wan Animate) use `preset` / `source_language` / `translation_language`, plus `srt_content` / `srt_file_url` / `vocabulary` / `customization` for VEED |
-| `generate_elements` | Reference images/videos + prompt → animated video |
-| `generate_first_last_frame` | First frame + last frame → interpolated video |
-| `generate_lipsync` | Source image/video + audio → lipsynced video (Sync-3 adds active-speaker selection, emotion, model mode, temperature) |
-| `generate_creative_director` | One brief → N coordinated scenes (image or video) |
-| `generate_music` | Text (+ optional lyrics) → song |
-| `generate_speech` | Text + voice → spoken audio |
-| `generate_sound` | Text → sound effect |
-| `generate_3d` | Text or reference images → 3D model (GLB/FBX/OBJ/USDZ) |
-| `transcribe_audio` | Audio/video URL or file → text + SRT subtitles |
-
-Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard_id` for character/style consistency across outputs — you can compose `create_visual_dna` → `generate_image` (with the DNA applied server-side) in a single agent turn. `generate_creative_director` also accepts `moodboard_ids` plural for blending.
-
-Every generation tool also accepts an optional `resolution` arg. Images use `"1K"` (~1024px) / `"2K"` (Full HD) / `"3K"` (QHD) / `"4K"` (UHD); videos use vertical-pixel tiers like `"720p"` / `"1080p"` / `"1440p"` / `"2160p"`. Values are model-dependent — call `list_models` and read the chosen model's `supported_resolutions` and `resolutionMultipliers`. Omit to use the model default.
-
-Every generation tool also accepts an optional `project_id` arg that routes the generation into a specific project (owned or shared with edit+). Call `list_projects` to discover IDs. When omitted, generations land in the user's auto-created "API Generations" project.
-
-**Chat & Vision**
-| Tool | Description |
-|------|-------------|
-| `chat_send_message` | Multi-turn chat with any Kolbo model. Pass `media_urls` to analyze images, videos, or audio — auto-routes to Gemini for vision. Supports web search and deep think. |
-| `chat_list_conversations` | List past chat threads |
-| `chat_get_messages` | Fetch messages in a conversation |
-
-**Visual DNA** (reusable character/style/product profiles)
-| Tool | Description |
-|------|-------------|
-| `create_visual_dna` | Create a profile from URLs or local files |
-| `list_visual_dnas` | List your profiles |
-| `get_visual_dna` | Fetch one profile |
-| `delete_visual_dna` | Delete a profile |
-
-**Moodboards**
-| Tool | Description |
-|------|-------------|
-| `list_moodboards` | Browse presets + your moodboards |
-| `get_moodboard` | Fetch one moodboard with all image URLs |
-
-**Media Library**
-| Tool | Description |
-|------|-------------|
-| `upload_media` | Upload a local file (or remote URL) → stable Kolbo CDN URL for reuse |
-| `list_media` | Browse media library — filter by `project_id`, `folder_id`, `type`, `category` (ai / uploaded / edited / favorites / training-lab), `source_type`, `sort`, `search`, pagination |
-| `list_media_folders` | List the user's media folders (owned + shared) — discover `folder_id` values to pass to `list_media` |
-| `create_media_folder` | Create a new folder (name, optional description / color / icon) |
-| `update_media_folder` | Rename / recolor / re-icon a folder (owner only) |
-| `delete_media_folder` | Soft-delete a folder (owner only; items remain in library) |
-| `add_media_to_folder` | Add up to 500 media items to a folder (idempotent) |
-| `remove_media_from_folder` | Remove media items from a folder |
-| `share_media_folder` | Share a folder by user email (owner only) |
-| `unshare_media_folder` | Revoke a user's access to a folder (owner only) |
-| `favorite_media` | Mark a media item as favorited (idempotent) — pass `media_id` from `list_media` |
-| `unfavorite_media` | Remove a media item from favorites (idempotent) — pass `media_id` from `list_media` |
-| `get_media` | Fetch one media item's full details by id |
-| `delete_media` | Soft-delete a media item (30-day trash) |
-| `restore_media` | Restore a trashed item |
-| `permanently_delete_media` | Hard-delete (NOT reversible — confirm with user first) |
-| `move_media` | Re-assign a media item to a different project |
-| `bulk_delete_media` | Soft-delete up to 1000 items in one call |
-| `bulk_restore_media` | Restore up to 1000 trashed items |
-| `bulk_permanently_delete_media` | Hard-delete up to 1000 (NOT reversible) |
-| `bulk_move_media` | Move up to 1000 items to a project (atomic — all-or-nothing) |
-| `move_folder_contents` | Move every item in a folder to a project |
-| `get_media_stats` | Counts + storage bytes per type (optionally per project) |
-
-**Artifacts**
-| Tool | Description |
-|------|-------------|
-| `publish_html_artifact` | Publish an HTML page, SVG, or Mermaid diagram and get a public shareable URL on `sites.kolbo.ai`. Pass `share_token` from a prior publish to update the same URL in place (old content kept in version history). |
-
-**Music Library** (stock / production music)
-| Tool | Description |
-|------|-------------|
-| `search_music_library` | Search the licensed stock-music catalog by keyword + genre/mood/BPM/duration filters. Find a ready-made track (distinct from `generate_music`, which composes a new song). |
-| `analyze_script_for_music` | AI: turn a video/voiceover script into a music search (`query`, `mood`, `genre`, `keywords`). |
-| `browse_music_library` | Browse the catalog without a query (paginated). |
-| `get_music_library_facets` | List available genres, moods, instruments + BPM/duration ranges. |
-| `get_music_track_audio` | Get a track's downloadable 128/320/WAV URLs by id. |
-| `get_music_track_related` | Get stems + alternate versions of a track. |
-| `get_music_track_lyrics` | Get lyrics text, theme, and explicit flag for a track. |
-
-**Stock Library** (multi-source stock media: Pexels, Pixabay, Sketchfab 3D, Music)
-| Tool | Description |
-|------|-------------|
-| `search_stock_media` | Search photos/videos/illustrations/vectors/3D/music across providers. `source="all"` returns one interleaved feed. Find ready-made assets / b-roll (distinct from `generate_image`/`generate_video`). |
-| `get_stock_sources` | List enabled sources + which media types/filters each supports. |
-| `get_stock_categories` | List dynamic category/topic chips (pass `providerParam` as the `category` filter). |
-| `get_stock_asset` | Get one asset with all download variants, author, license, and attribution. |
-| `analyze_script_for_stock` | AI: turn a script into b-roll search terms (`queries[]`, `mediaType`, `keywords`). |
-| `import_stock_asset` | Copy a stock asset into the media library (CDN copy, stable URL). Free. |
-
-**Shorts Creator** (long video → viral vertical shorts, two-phase)
-| Tool | Description |
-|------|-------------|
-| `shorts_analyze` | Phase 1: analyze a long video (Kolbo media-library URL, ≤30 min) → AI-picked best moments with titles, hooks, scores, accent beats. Flat 15 credits. Polls until moments are ready (~1-3 min). |
-| `shorts_list_presets` | List restyle presets (identifier, name, preview video, default mode/subtitle style). |
-| `shorts_get_transcript` | Word-level Scribe transcript of the source video (`words`, `language`, `sourceDuration`) — the base for the Review & Edit workflow (build `delete_ranges` cuts + edited `srt_content`). |
-| `shorts_estimate` | Price a selection before rendering — free. Per-short credits + chunk counts. `delete_ranges` cuts shorten the effective duration (cheaper). |
-| `shorts_render` | Phase 2: render up to 5 shorts (15-90s each) from picked moments — `accents` mode (restyle strongest beats, cheaper) or `full` (restyle everything), optional burned-in subtitles. Per short: optional `delete_ranges` (cut dead air, absolute source seconds, ≥8s must remain) and `srt_content` (user-edited SRT, cut-timeline times, ≤200KB). Polls until done (~5-20 min), returns final URLs. Failed shorts auto-refund. |
-| `shorts_status` | One-shot job state read (moments / shorts / phase) — resume after a timeout. |
-| `shorts_cancel` | Cancel a job and refund unused credits. |
-
-**Discovery & Account**
-| Tool | Description |
-|------|-------------|
-| `list_models` | Current model catalog with costs and capabilities |
-| `list_voices` | TTS voices (presets + cloned) |
-| `list_presets` | Generation presets across image/video/music/text-to-video catalogs |
-| `list_projects` | List owned + shared projects (id, name, role, is_default) — call first to resolve a project name into the `project_id` you pass to generation tools |
-| `check_credits` | Check credit balance |
-| `get_generation_status` | Poll a generation by ID (fallback if a tool times out) |
-
-## Environment Variables
-
-Both are optional — the local install logs in via the browser on first use.
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `KOLBO_API_KEY` | No | Set a `kolbo_live_` key to skip the browser login (create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer)). |
-| `KOLBO_API_URL` | No | Custom API URL (default: `https://api.kolbo.ai/api`) |
-
-## Links
-
-- [API Documentation](https://docs.kolbo.ai/developer-api)
-- [Kolbo AI Platform](https://kolbo.ai)
-- [Get API Key](https://app.kolbo.ai)
+# @kolbo/mcp
+
+Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Desktop via MCP (Model Context Protocol).
+
+Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.
+
+**✨ Interactive widgets (v1.30+):** in claude.ai and Claude Desktop, generations render as live Kolbo cards — real-time progress with model + settings chips, an inline result gallery / video player, and one-click **Animate · Edit · Recreate · Download** actions. Library and model searches render as browsable grids with audio preview. Text-only clients (Claude Code, Cursor) keep the classic text responses.
+
+## Set up — paste one prompt, or one config block (keyless, no API key)
+
+### Easiest: paste this prompt to your AI
+
+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):
+
+```
+Connect the Kolbo AI MCP server (generate images, video, music and more).
+
+- 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.
+
+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 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 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.
+-->
+
+Run this once — it sets up the **full** Kolbo experience (the MCP tools **and** the routing skill) for every installed agent (Claude Desktop, Claude Code, Cursor), 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
+{
+  "mcpServers": {
+    "kolbo": {
+      "command": "npx",
+      "args": ["-y", "@kolbo/mcp@latest"]
+    }
+  }
+}
+```
+
+| Client | Where the config goes |
+|--------|----------------------|
+| **Claude Code** | `.claude/settings.json` (or `claude mcp add kolbo -- npx -y @kolbo/mcp@latest`) |
+| **Claude Desktop** | `claude_desktop_config.json` |
+| **Cursor** | `.cursor/mcp.json` |
+| **Kolbo Code** | configured automatically on `kolbo auth login` |
+
+Restart your app, then ask it to generate something. The first time, a Kolbo login opens in your browser — click **Allow** (no API key to create). _Prefer an API key? Create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer) and add `"env": { "KOLBO_API_KEY": "kolbo_live_..." }` to the block above._
+
+### Browser-only (claude.ai / ChatGPT): the connector
+
+No install at all — add the custom connector **`https://api.kolbo.ai/mcp`** under Settings → Connectors, then Connect → log in → Allow. Great for generating from text or URLs; to upload your own local files, use the config install above (it runs on your machine).
+
+### Optional upgrade: add the Kolbo skill for slash-commands + smart routing
+
+The config above is all you need. If you want one-word slash-commands (`/kolbo:marketing-studio`, `/kolbo:product-photoshoot`, …) and automatic routing to the best tool with the right defaults, install the Kolbo skill on top — it's an enhancement layer, not a requirement:
+
+```bash
+# Claude Code (also writes the MCP config for you, so you can skip Step 2 above)
+claude plugin marketplace add Zoharvan12/kolbo-skills
+claude plugin install kolbo@kolbo-skills
+
+# Cursor / Codex / any agent (cross-agent installer)
+npx skills add Zoharvan12/kolbo-skills
+```
+
+The skill content is the same canonical routing logic that ships inside [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so however you connect, the behavior matches. See the full setup guide at [docs.kolbo.ai/developer-api/claude-code-skill](https://docs.kolbo.ai/developer-api/claude-code-skill).
+
+### Use it
+
+Just ask your agent naturally:
+
+**Generation**
+- *"Generate an image of a sunset over mountains"*
+- *"Create a 5-second video of waves crashing"*
+- *"Build a 4-scene storyboard for a coffee shop ad"*
+- *"Remove the background from this image"*
+- *"Make a lo-fi hip hop beat"*
+- *"Read this out loud with a British female voice"*
+
+**Marketing & UGC**
+- *"Make me a UGC ad for my sneaker brand — 9:16, talking-head style"*
+- *"TV spot for my new beverage, 15 seconds, cinematic"*
+- *"Unboxing video for this product photo"*
+
+**Brand & product imagery**
+- *"Pinterest pin for my candle brand, cottagecore mood"*
+- *"Hero banner for my landing page, wide format"*
+- *"Lifestyle shot of my product in a kitchen"*
+- *"4 ad creative variants for Meta and TikTok"*
+
+**Marketplace listings**
+- *"Generate Amazon main image + 5 secondary images for my product"*
+- *"Full A+ content set for my Shopify listing"*
+
+**Analysis & utility**
+- *"Ask Claude about the latest AI news with web search on"*
+- *"Analyze this video and tell me what prompts are shown on screen"*
+- *"What's in this image?"*
+- *"Create a Visual DNA profile called 'Alex' from these images"*
+- *"Use the same brand as last time"* (loads a persisted brand kit from the workspace)
+
+Without the optional skill, the config block alone already exposes every tool — you just describe what you want. With the skill installed, each of these is also routed to the right MCP tool with the right defaults — UGC mode picks 9:16 + sound-off + no-captions, marketplace mode enforces compliance (pure white bg, no text, no props), product photoshoot mode uses the right aspect for the platform (2:3 Pinterest, 16:9 hero banner, 1:1 IG feed), etc. The routing logic is shared with [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so the behavior is identical however you connect.
+
+## Available Tools (86)
+
+**Generation**
+| Tool | Description |
+|------|-------------|
+| `generate_image` | Text → image |
+| `generate_image_edit` | Existing image(s) + prompt → edited image |
+| `generate_video` | Text → video |
+| `generate_video_from_image` | Still image + motion prompt → video |
+| `generate_video_from_video` | Input video → restyled video, or burn in subtitles (video-to-video). `prompt` optional — prompt-less models (VEED Subtitles, Act Two, Wan Animate) use `preset` / `source_language` / `translation_language`, plus `srt_content` / `srt_file_url` / `vocabulary` / `customization` for VEED |
+| `generate_elements` | Reference images/videos + prompt → animated video |
+| `generate_first_last_frame` | First frame + last frame → interpolated video |
+| `generate_lipsync` | Source image/video + audio → lipsynced video (Sync-3 adds active-speaker selection, emotion, model mode, temperature) |
+| `generate_creative_director` | One brief → N coordinated scenes (image or video) |
+| `generate_music` | Text (+ optional lyrics) → song |
+| `generate_speech` | Text + voice → spoken audio |
+| `generate_sound` | Text → sound effect |
+| `generate_3d` | Text or reference images → 3D model (GLB/FBX/OBJ/USDZ) |
+| `transcribe_audio` | Audio/video URL or file → text + SRT subtitles |
+
+Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard_id` for character/style consistency across outputs — you can compose `create_visual_dna` → `generate_image` (with the DNA applied server-side) in a single agent turn. `generate_creative_director` also accepts `moodboard_ids` plural for blending.
+
+Every generation tool also accepts an optional `resolution` arg. Images use `"1K"` (~1024px) / `"2K"` (Full HD) / `"3K"` (QHD) / `"4K"` (UHD); videos use vertical-pixel tiers like `"720p"` / `"1080p"` / `"1440p"` / `"2160p"`. Values are model-dependent — call `list_models` and read the chosen model's `supported_resolutions` and `resolutionMultipliers`. Omit to use the model default.
+
+Every generation tool also accepts an optional `project_id` arg that routes the generation into a specific project (owned or shared with edit+). Call `list_projects` to discover IDs. When omitted, generations land in the user's auto-created "API Generations" project. `project_id` is per-call, NOT sticky — pass it on every call once the user names a working project. Misplaced work is recoverable via `move_media` / `move_session`.
+
+**Chat & Vision**
+| Tool | Description |
+|------|-------------|
+| `chat_send_message` | Multi-turn chat with any Kolbo model. Pass `media_urls` to analyze images, videos, or audio — auto-routes to Gemini for vision. Supports web search and deep think. |
+| `chat_list_conversations` | List past chat threads |
+| `chat_get_messages` | Fetch messages in a conversation |
+
+**Visual DNA** (reusable character/style/product profiles)
+| Tool | Description |
+|------|-------------|
+| `create_visual_dna` | Create a profile from URLs or local files |
+| `list_visual_dnas` | List your profiles |
+| `get_visual_dna` | Fetch one profile |
+| `delete_visual_dna` | Delete a profile |
+
+**Moodboards**
+| Tool | Description |
+|------|-------------|
+| `list_moodboards` | Browse presets + your moodboards |
+| `get_moodboard` | Fetch one moodboard with all image URLs |
+
+**Media Library**
+| Tool | Description |
+|------|-------------|
+| `upload_media` | Upload a local file (or remote URL) → stable Kolbo CDN URL for reuse |
+| `list_media` | Browse media library — filter by `project_id`, `folder_id`, `type`, `category` (ai / uploaded / edited / favorites / training-lab), `source_type`, `sort`, `search`, pagination |
+| `list_media_folders` | List the user's media folders (owned + shared) — discover `folder_id` values to pass to `list_media` |
+| `create_media_folder` | Create a new folder (name, optional description / color / icon) |
+| `update_media_folder` | Rename / recolor / re-icon a folder (owner only) |
+| `delete_media_folder` | Soft-delete a folder (owner only; items remain in library) |
+| `add_media_to_folder` | Add up to 500 media items to a folder (idempotent) |
+| `remove_media_from_folder` | Remove media items from a folder |
+| `share_media_folder` | Share a folder by user email (owner only) |
+| `unshare_media_folder` | Revoke a user's access to a folder (owner only) |
+| `favorite_media` | Mark a media item as favorited (idempotent) — pass `media_id` from `list_media` |
+| `unfavorite_media` | Remove a media item from favorites (idempotent) — pass `media_id` from `list_media` |
+| `get_media` | Fetch one media item's full details by id |
+| `delete_media` | Soft-delete a media item (30-day trash) |
+| `restore_media` | Restore a trashed item |
+| `permanently_delete_media` | Hard-delete (NOT reversible — confirm with user first) |
+| `move_media` | Re-assign a media item to a different project |
+| `bulk_delete_media` | Soft-delete up to 1000 items in one call |
+| `bulk_restore_media` | Restore up to 1000 trashed items |
+| `bulk_permanently_delete_media` | Hard-delete up to 1000 (NOT reversible) |
+| `bulk_move_media` | Move up to 1000 items to a project (atomic — all-or-nothing) |
+| `move_folder_contents` | Move every item in a folder to a project |
+| `get_media_stats` | Counts + storage bytes per type (optionally per project) |
+
+**Artifacts**
+| Tool | Description |
+|------|-------------|
+| `publish_html_artifact` | Publish an HTML page, SVG, or Mermaid diagram and get a public shareable URL on `sites.kolbo.ai`. Pass `share_token` from a prior publish to update the same URL in place (old content kept in version history). |
+
+**Music Library** (stock / production music)
+| Tool | Description |
+|------|-------------|
+| `search_music_library` | Search the licensed stock-music catalog by keyword + genre/mood/BPM/duration filters. Find a ready-made track (distinct from `generate_music`, which composes a new song). |
+| `analyze_script_for_music` | AI: turn a video/voiceover script into a music search (`query`, `mood`, `genre`, `keywords`). |
+| `browse_music_library` | Browse the catalog without a query (paginated). |
+| `get_music_library_facets` | List available genres, moods, instruments + BPM/duration ranges. |
+| `get_music_track_audio` | Get a track's downloadable 128/320/WAV URLs by id. |
+| `get_music_track_related` | Get stems + alternate versions of a track. |
+| `get_music_track_lyrics` | Get lyrics text, theme, and explicit flag for a track. |
+
+**Stock Library** (multi-source stock media: Pexels, Pixabay, Sketchfab 3D, Music)
+| Tool | Description |
+|------|-------------|
+| `search_stock_media` | Search photos/videos/illustrations/vectors/3D/music across providers. `source="all"` returns one interleaved feed. Find ready-made assets / b-roll (distinct from `generate_image`/`generate_video`). |
+| `get_stock_sources` | List enabled sources + which media types/filters each supports. |
+| `get_stock_categories` | List dynamic category/topic chips (pass `providerParam` as the `category` filter). |
+| `get_stock_asset` | Get one asset with all download variants, author, license, and attribution. |
+| `analyze_script_for_stock` | AI: turn a script into b-roll search terms (`queries[]`, `mediaType`, `keywords`). |
+| `import_stock_asset` | Copy a stock asset into the media library (CDN copy, stable URL). Free. |
+
+**Shorts Creator** (long video → viral vertical shorts, two-phase)
+| Tool | Description |
+|------|-------------|
+| `shorts_analyze` | Phase 1: analyze a long video (Kolbo media-library URL, ≤30 min) → AI-picked best moments with titles, hooks, scores, accent beats. Flat 15 credits. Polls until moments are ready (~1-3 min). |
+| `shorts_list_presets` | List restyle presets (identifier, name, preview video, default mode/subtitle style). |
+| `shorts_get_transcript` | Word-level Scribe transcript of the source video (`words`, `language`, `sourceDuration`) — the base for the Review & Edit workflow (build `delete_ranges` cuts + edited `srt_content`). |
+| `shorts_estimate` | Price a selection before rendering — free. Per-short credits + chunk counts. `delete_ranges` cuts shorten the effective duration (cheaper). |
+| `shorts_render` | Phase 2: render up to 5 shorts (15-90s each) from picked moments — `accents` mode (restyle strongest beats, cheaper) or `full` (restyle everything), optional burned-in subtitles. Per short: optional `delete_ranges` (cut dead air, absolute source seconds, ≥8s must remain) and `srt_content` (user-edited SRT, cut-timeline times, ≤200KB). Polls until done (~5-20 min), returns final URLs. Failed shorts auto-refund. |
+| `shorts_status` | One-shot job state read (moments / shorts / phase) — resume after a timeout. |
+| `shorts_cancel` | Cancel a job and refund unused credits. |
+
+**Discovery & Account**
+| Tool | Description |
+|------|-------------|
+| `list_models` | Current model catalog with costs and capabilities |
+| `list_voices` | TTS voices (presets + cloned) |
+| `list_presets` | Generation presets across image/video/music/text-to-video catalogs |
+| `list_projects` | List owned + shared projects (id, name, role, is_default) — call first to resolve a project name into the `project_id` you pass to generation tools |
+| `move_session` | Move a session (generation, chat, transcription…) and ALL its media to another project |
+| `create_doc` / `list_docs` / `get_doc` / `update_doc` / `share_doc` / `delete_doc` | AI Docs (Magic Pad): author project-scoped HTML documents, edit them, get public share links |
+| `check_credits` | Check credit balance |
+| `get_generation_status` | Check one or many generations (`generation_ids`); `wait=true` blocks server-side until done — replaces client polling loops |
+
+## Environment Variables
+
+Both are optional — the local install logs in via the browser on first use.
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `KOLBO_API_KEY` | No | Set a `kolbo_live_` key to skip the browser login (create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer)). |
+| `KOLBO_API_URL` | No | Custom API URL (default: `https://api.kolbo.ai/api`) |
+
+## Links
+
+- [API Documentation](https://docs.kolbo.ai/developer-api)
+- [Kolbo AI Platform](https://kolbo.ai)
+- [Get API Key](https://app.kolbo.ai)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.31.7",
+  "version": "1.33.0",
   "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,7 +1,7 @@
 # AUTO-GENERATED — do not edit
 
 This skill/ tree is mirrored from kolbo-code (the single source of truth)
-by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@53720a8.
+by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@17e585e.
 
 It is the skill that 'npx @kolbo/mcp install' deploys into the user's agent.
 To change it, edit packages/opencode/skills/kolbo/ in kolbo-code and push;

package/skill/SKILL.md

@@ -35,7 +35,7 @@ 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.
+3. Use the balance ONLY for the low-balance check at this moment. **Never quote a "credits remaining" number later in the session** — coding/chat usage also deducts credits, so any remembered or computed balance is stale. Report only what each generation cost (`credits_used`); if the user asks what's left, run `check_credits` fresh right then.
 
 If the user is on a whitelabel build (`sapir`, etc.), they must use their branded command — not `kolbo`. See `references/workflows/troubleshooting.md`.
 
@@ -154,8 +154,9 @@ A user-named tool — in any language — overrides every other rule. Recognized
    - 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.
+5. **How calls work**: each tool blocks until generation is fully complete. Images: seconds. Video: minutes. Multiple tool calls in one response run concurrently. On hosts with live widgets the tool instead returns `submitted` instantly — the card updates on its own; you only need `get_generation_status` when a follow-up step needs the output URLs.
+6. **Checking status — NEVER poll in a loop**: `get_generation_status` takes `wait=true` (blocks server-side until done, ~3 min) and `generation_ids` (check MANY generations in ONE call — returns `all_done` + which are still running). One `wait=true` call replaces any polling loop. If it comes back with some still processing, call it ONCE more with `wait=true` and the remaining ids.
+7. **Share the URL** after success. Never fabricate URLs.
 
 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`.
 
@@ -167,11 +168,13 @@ Full tables + formulas in `references/workflows/cost-and-validation.md`. Quick r
 - **Otherwise confirm** via the labeled-question card: the parameters + the credit cost, suggest a cheaper alternative if one fits, wait for the user's pick. Never fire on defaults the user didn't choose.
 - **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`.
+- **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.
 
 ## 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.
+- **⚠️ NEVER re-fire a generation you already called.** Aborted / timed-out calls still process server-side. Run `get_generation_status` (with `wait=true`) before retrying.
+- **Tracking a batch**: check ALL in-flight ids in ONE `get_generation_status` call with `generation_ids` + `wait=true`. Read `all_done` / `still_processing` from the response — do not check ids one by one, and never re-call without `wait`.
 - **Batch ≤10 items**: output ALL tool calls in one response — they run concurrently.
 - **Bulk >10 items**: real-world ceilings — `generate_image` 8–10 in-flight, image-edit 5–8, video tools 3–5, `generate_video_from_video` 3, music/speech/sound 5–8. Fire one batch → wait → fire next. Persist every `generation_id` in `.kolbo/production.md`.
 - **`upload_media` external URLs first.** `files`/`source_images`/`image_url` only accept Kolbo-hosted URLs reliably; external URLs cause `400`.
@@ -224,7 +227,7 @@ 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.
+3. **Tool hangs / never returns** — MCP poll timed out. Call `get_generation_status(generation_id, wait=true)` IMMEDIATELY. The server might be done.
 
 **Always:**
 - Don't celebrate before reading the result. Verify `urls` is non-empty.

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

@@ -48,6 +48,8 @@ Apply when confirming cost before firing:
 
 **Batch totalling 100+ credits:** run `check_credits` first and include the available balance in the summary.
 
+**After generating, report cost only — never "credits remaining".** Coding/chat usage also deducts credits, so any balance you compute (opening balance − generation costs) is wrong by the time you say it. Quote `credits_used` per generation / batch total; if the user asks what's left, run `check_credits` fresh at that moment and quote that number.
+
 ## ⚠️ Quote Real Cost, Never Estimates (CRITICAL)
 
 Pre-flight formulas above are for **preview only**. After firing, every generation returns `credits_used` (multiplier-adjusted total) and `credits_breakdown` (per-model attribution).

package/skill/references/workflows/troubleshooting.md

@@ -30,6 +30,10 @@ This re-wires the MCP configuration automatically. Then restart the session.
 
 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".
 
+## Checking generation status without spinning
+
+`get_generation_status` supports `wait=true` (blocks server-side until the generation reaches a final state, up to ~3 min) and `generation_ids` (many ids in one call → returns `all_done`, `still_processing`, and per-generation results). **Never call it repeatedly in a loop** — one `wait=true` call replaces the loop. If some generations are still running after the wait window, call it ONCE more with `wait=true` and only the `still_processing` ids.
+
 ## Failure envelope from `get_generation_status`
 
 When a generation fails, `get_generation_status` returns a structured `failure` field alongside `error`:

package/src/index.js

@@ -69,6 +69,7 @@ const { registerPresetTools } = require('./tools/presets');
 const { registerAppBuilderTools } = require('./tools/app_builder');
 const { registerArtifactTools } = require('./tools/artifacts');
 const { registerProjectTools } = require('./tools/projects');
+const { registerDocTools } = require('./tools/docs');
 const { registerVoiceTools } = require('./tools/voices');
 const { registerMusicLibraryTools } = require('./tools/music_library');
 const { registerStockLibraryTools } = require('./tools/stock_library');
@@ -103,6 +104,19 @@ function createServer(opts = {}) {
     // Connector avatar for hosts that render server icons (claude.ai tool
     // headers show this instead of a letter monogram).
     icons: [{ src: 'https://api.kolbo.ai/assets/kolbo-ai.png', mimeType: 'image/png', sizes: ['512x512'] }]
+  }, {
+    // Server-level instructions surfaced to the host model on initialize.
+    // The single most common failure mode is project confusion — spell out
+    // the project contract here so every client gets it without a skill file.
+    instructions: [
+      'PROJECT CONTRACT (read this before generating anything):',
+      'Everything in Kolbo lives inside a PROJECT — sessions, generations, and media are all project-scoped.',
+      '1. When the user names a project ("in my Acme project", "for the summer campaign"), call `list_projects` ONCE to resolve the name to an id, then pass that id as `project_id` on EVERY subsequent generate_* / chat_send_message / upload_media call in the conversation. The target project is per-call, NOT sticky — any call that omits `project_id` silently lands in the default "API Generations" bucket (flagged is_default:true), which users experience as their work going to the wrong project.',
+      '2. `list_projects` lists the user\'s platform projects (for generations/media/chat). `app_builder_list_projects` is a DIFFERENT tool that scopes App Builder coding sessions only — never use one where the other is meant.',
+      '3. Misplaced work is fixable: `move_media` / `bulk_move_media` / `move_folder_contents` move media items between projects; `move_session` moves a whole session (plus its media) to another project. If the user says a generation landed in the wrong project, move it rather than regenerating.',
+      '4. If the user has not mentioned any project, omit `project_id` — the default bucket is correct in that case. Do not ask which project to use unless the user\'s intent is ambiguous.',
+      '5. Written deliverables (plans, briefs, scripts, research summaries) can live in Kolbo too: author them as AI Docs with `create_doc` (project-scoped, editable in the app, shareable via `share_doc`).'
+    ].join('\n')
   });
 
   // Register all tools. `inlineImages` (off by default) is opt-in: only the
@@ -121,6 +135,7 @@ function createServer(opts = {}) {
   registerAppBuilderTools(server, client, toolOptions);
   registerArtifactTools(server, client, toolOptions);
   registerProjectTools(server, client, toolOptions);
+  registerDocTools(server, client, toolOptions);
   registerMusicLibraryTools(server, client, toolOptions);
   registerStockLibraryTools(server, client, toolOptions);
   registerShortsCreatorTools(server, client, toolOptions);

package/src/tools/_shared.js

@@ -251,7 +251,7 @@ function creditFields(polledResult) {
 // resolve a name → ObjectId.
 const { z } = require('zod');
 const projectIdField = z.string().optional().describe(
-  'Project ObjectId to drop this generation into. Call `list_projects` to discover IDs (the API has no concept of project names — only ObjectIds). Omit to use the user\'s default "API Generations" project. Requires owner / edit / full permission on the project; view-only is rejected.'
+  'Project ObjectId to drop this generation into. Call `list_projects` to discover IDs (the API has no concept of project names — only ObjectIds). IMPORTANT: this is per-call, NOT sticky — once the user has named a working project, pass its id on EVERY generation call in the conversation; any call that omits it silently lands in the default "API Generations" project instead. Requires owner / edit / full permission on the project; view-only is rejected.'
 );
 
 // ─── Optional inline-image content blocks ────────────────────────────────────
@@ -396,7 +396,7 @@ async function uiGenerating(p) {
   const text = JSON.stringify({
     status: 'submitted',
     generation_id: p.gen.generation_id,
-    _widget_note: 'A live Kolbo widget is rendering this generation for the user (progress + final result + action buttons). Tell the user it is generating and the card above will update — do NOT poll in a loop. If you later need the output URLs (e.g. for a follow-up edit), call get_generation_status once with this generation_id.',
+    _widget_note: 'A live Kolbo widget is rendering this generation for the user (progress + final result + action buttons). Tell the user it is generating and the card above will update — do NOT poll in a loop. If you need the output URLs (e.g. for a follow-up edit or a report), call get_generation_status ONCE with wait=true — it blocks until done. Tracking several generations? Pass ALL their ids in generation_ids in that one call.',
   }, null, 2);
   return uiResult(UI.generation, text, structured);
 }

package/src/tools/chat.js

@@ -70,15 +70,17 @@ function registerChatTools(server, client) {
   // ─── chat_list_conversations ───────────────────────────────
   server.tool(
     'chat_list_conversations',
-    'List your SDK chat conversations, most-recent first. Returns session_id, name, and activity timestamps.',
+    'List the user\'s chat conversations across ALL projects, most-recent first. Returns session_id, name, project_id, and activity timestamps. Pass `project_id` to narrow to one project (resolve names via `list_projects`).',
     {
       page: z.number().optional().describe('Page number, 1-indexed. Default: 1'),
-      limit: z.number().optional().describe('Results per page, max 50. Default: 20')
+      limit: z.number().optional().describe('Results per page, max 50. Default: 20'),
+      project_id: z.string().optional().describe('Restrict to conversations in one project (Mongo ObjectId from `list_projects`). Omit to list across all projects.')
     },
-    async ({ page, limit }) => {
+    async ({ page, limit, project_id }) => {
       const params = new URLSearchParams();
       if (page) params.set('page', String(page));
       if (limit) params.set('limit', String(limit));
+      if (project_id) params.set('project_id', project_id);
 
       const qs = params.toString();
       const result = await client.get(`/v1/chat/conversations${qs ? '?' + qs : ''}`);

package/src/tools/docs.js

@@ -0,0 +1,119 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+const { z } = require('zod');
+const { projectIdField } = require('./_shared');
+
+const CONTENT_GUIDE = 'HTML body content. Use clean semantic HTML the in-app editor understands: <h1>-<h3>, <p>, <ul>/<ol>/<li>, <table>, <blockquote>, <strong>/<em>, <a>. No <script>/<style>/<iframe> (stripped server-side). Write the FULL document yourself — this is where you author the doc.';
+
+function registerDocTools(server, client) {
+  // ─── create_doc ────────────────────────────────────────────
+  server.tool(
+    'create_doc',
+    'Create an AI Doc (Magic Pad document) in the user\'s Kolbo workspace. YOU author the document: write complete, well-structured HTML content (plans, briefs, scripts, research summaries, meeting notes…) and save it here so the user can read and edit it in the Kolbo app. Docs are project-scoped — when the user is working in a named project, resolve it with `list_projects` and pass `project_id`. Returns the doc id; use `share_doc` afterwards if the user wants a public link.',
+    {
+      title: z.string().describe('Document title (shown in the app sidebar).'),
+      content: z.string().describe(CONTENT_GUIDE),
+      project_id: projectIdField
+    },
+    async ({ title, content, project_id }) => {
+      const body = { title, content };
+      if (project_id) body.project_id = project_id;
+      const result = await client.post('/v1/docs', body);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            doc: result.doc,
+            _hint: 'Doc created. The user can open it in the Kolbo app under the project\'s AI Docs. Call share_doc with shared:true to get a public link.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── list_docs ─────────────────────────────────────────────
+  server.tool(
+    'list_docs',
+    'List the user\'s AI Docs (Magic Pad documents) across all projects, most recently updated first. Pass `project_id` (from `list_projects`) to narrow to one project. Returns id, title, project_id, share state, and timestamps — use `get_doc` to read a doc\'s content.',
+    {
+      project_id: z.string().optional().describe('Restrict to docs in one project (ObjectId from `list_projects`). Omit to list across all projects.'),
+      page: z.number().optional().describe('Page number, 1-indexed. Default: 1'),
+      limit: z.number().optional().describe('Results per page, max 50. Default: 20')
+    },
+    async ({ project_id, page, limit }) => {
+      const params = new URLSearchParams();
+      if (project_id) params.set('project_id', project_id);
+      if (page) params.set('page', String(page));
+      if (limit) params.set('limit', String(limit));
+      const qs = params.toString();
+      const result = await client.get(`/v1/docs${qs ? '?' + qs : ''}`);
+      return { content: [{ type: 'text', text: JSON.stringify({ docs: result.docs || [], pagination: result.pagination || null }, null, 2) }] };
+    }
+  );
+
+  // ─── get_doc ───────────────────────────────────────────────
+  server.tool(
+    'get_doc',
+    'Fetch one AI Doc including its full HTML content. Use before editing an existing doc (read → modify → `update_doc`).',
+    {
+      doc_id: z.string().describe('The doc ObjectId (from create_doc or list_docs).')
+    },
+    async ({ doc_id }) => {
+      const result = await client.get(`/v1/docs/${encodeURIComponent(doc_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result.doc, null, 2) }] };
+    }
+  );
+
+  // ─── update_doc ────────────────────────────────────────────
+  server.tool(
+    'update_doc',
+    'Update an AI Doc\'s title and/or content. Content REPLACES the whole document — call `get_doc` first, apply the user\'s edits to the full HTML, and send the complete result back.',
+    {
+      doc_id: z.string().describe('The doc ObjectId to update.'),
+      title: z.string().optional().describe('New title. Omit to keep the current one.'),
+      content: z.string().optional().describe('Full replacement ' + CONTENT_GUIDE)
+    },
+    async ({ doc_id, title, content }) => {
+      const body = {};
+      if (title !== undefined) body.title = title;
+      if (content !== undefined) body.content = content;
+      const result = await client.put(`/v1/docs/${encodeURIComponent(doc_id)}`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.doc, null, 2) }] };
+    }
+  );
+
+  // ─── share_doc ─────────────────────────────────────────────
+  server.tool(
+    'share_doc',
+    'Enable or disable public sharing of an AI Doc. When enabling, returns a stable public link (app.kolbo.ai/shared/magicpad/…) anyone can open — give it to the user. Set `editable` to also let link visitors edit the doc.',
+    {
+      doc_id: z.string().describe('The doc ObjectId.'),
+      shared: z.boolean().describe('true = publicly shared, false = private again (the link stops working).'),
+      editable: z.boolean().optional().describe('Whether link visitors can edit. Default: unchanged (false for new shares).')
+    },
+    async ({ doc_id, shared, editable }) => {
+      const body = { shared };
+      if (editable !== undefined) body.editable = editable;
+      const result = await client.patch(`/v1/docs/${encodeURIComponent(doc_id)}/share`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.doc, null, 2) }] };
+    }
+  );
+
+  // ─── delete_doc ────────────────────────────────────────────
+  server.tool(
+    'delete_doc',
+    'Delete an AI Doc (soft delete — recoverable from the app\'s trash flow). Owner only. Confirm with the user before deleting anything they did not just create in this conversation.',
+    {
+      doc_id: z.string().describe('The doc ObjectId to delete.')
+    },
+    async ({ doc_id }) => {
+      const result = await client.delete(`/v1/docs/${encodeURIComponent(doc_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+}
+
+module.exports = { registerDocTools };

package/src/tools/generate.js

@@ -418,17 +418,71 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── get_generation_status ─────────────────────────────────
   server.tool(
     'get_generation_status',
-    'Check the status of a generation. Use this as a FALLBACK when a generation tool returned a timeout error — the generation is probably still running on the server. Pass the generation_id from the timeout error (or from any prior generation response).',
+    'Check the status of one or more generations. Use after a generation tool returned "submitted" (widget hosts) or timed out. Tracking SEVERAL concurrent generations? Pass them ALL in generation_ids — one call returns an all_done summary. Need the final result? Set wait=true and the server blocks until every generation finishes (up to ~3 min). NEVER call this tool repeatedly in a loop — one wait=true call replaces the whole loop.',
     {
-      generation_id: z.string().describe('The generation ID to check')
+      generation_id: z.string().optional().describe('A single generation ID to check'),
+      generation_ids: z.array(z.string()).optional().describe('Multiple generation IDs to check in ONE call. Returns { all_done, pending, generations[] } — always prefer this over checking IDs one by one.'),
+      wait: z.boolean().optional().describe('If true, block until every generation reaches a terminal state (completed/failed), up to ~3 minutes, then return the final results. Use this instead of re-calling the tool in a loop.')
     },
-    async ({ generation_id }) => {
-      const result = await client.get(`/v1/generate/${encodeURIComponent(generation_id)}/status`);
+    async ({ generation_id, generation_ids, wait }) => {
+      const ids = (generation_ids && generation_ids.length > 0)
+        ? generation_ids
+        : (generation_id ? [generation_id] : []);
+      if (ids.length === 0) throw new Error('Provide generation_id or generation_ids');
+
+      // One status check (or blocking poll) per id. Never let one bad id
+      // reject the whole batch — surface it as a failed entry instead.
+      const checkOne = async (id) => {
+        try {
+          if (wait) {
+            const result = await pollUntilDone(client, id, { interval: 5000, timeout: 180000 });
+            return { generation_id: id, ...result };
+          }
+          const result = await client.get(`/v1/generate/${encodeURIComponent(id)}/status`);
+          return { generation_id: id, ...result };
+        } catch (err) {
+          if (err.timedOut) {
+            return { generation_id: id, state: 'processing', note: 'Still running after 3 min of waiting — call get_generation_status again with wait=true.' };
+          }
+          if (err.name === 'GenerationFailedError') {
+            return { generation_id: id, state: 'failed', error: err.message };
+          }
+          return { generation_id: id, state: 'unknown', error: err.message };
+        }
+      };
+
+      const results = await Promise.all(ids.map(checkOne));
+
+      const pending = results.filter(r => r.state !== 'completed' && r.state !== 'failed' && r.state !== 'cancelled');
+      const doneHint = 'ALL generations are in a final state — do NOT poll again. Report the results to the user.';
+      const pendingHint = wait
+        ? 'Some generations are still running after the wait window. Call get_generation_status ONCE more with wait=true and the remaining generation_ids — do not spin without wait.'
+        : 'Some generations are still processing. Do NOT re-call this tool in a loop — call it ONCE with wait=true (and all pending generation_ids) to block until they finish.';
+
+      // Single-id calls keep the original flat shape — the generation widget
+      // polls this tool with { generation_id } and reads state/result at the
+      // top level.
+      if (!generation_ids || generation_ids.length === 0) {
+        const single = results[0];
+        single._hint = pending.length === 0
+          ? 'This generation is in a FINAL state — do not poll it again.'
+          : pendingHint;
+        return {
+          content: [{ type: 'text', text: JSON.stringify(single, null, 2) }]
+        };
+      }
 
       return {
         content: [{
           type: 'text',
-          text: JSON.stringify(result, null, 2)
+          text: JSON.stringify({
+            all_done: pending.length === 0,
+            completed: results.filter(r => r.state === 'completed').length,
+            failed: results.filter(r => r.state === 'failed' || r.state === 'cancelled').length,
+            still_processing: pending.map(r => r.generation_id),
+            _hint: pending.length === 0 ? doneHint : pendingHint,
+            generations: results
+          }, null, 2)
         }]
       };
     }
@@ -833,7 +887,7 @@ function registerGenerateTools(server, client, options = {}) {
         return uiResult(UI.transcript, JSON.stringify({
           status: 'submitted',
           generation_id: startResponse.generation_id,
-          _widget_note: 'A live Kolbo transcription widget is rendering above — it shows progress, the transcript text, and SRT/TXT download buttons. Tell the user it is transcribing. If you need the transcript text for a follow-up step, call get_generation_status with this generation_id once done.',
+          _widget_note: 'A live Kolbo transcription widget is rendering above — it shows progress, the transcript text, and SRT/TXT download buttons. Tell the user it is transcribing. If you need the transcript text for a follow-up step, call get_generation_status ONCE with this generation_id and wait=true — it blocks until done; do NOT poll in a loop.',
         }, null, 2), {
           widget: 'transcript', phase: 'generating',
           generation_id: startResponse.generation_id,

package/src/tools/media.js

@@ -16,9 +16,10 @@ function registerMediaTools(server, client, options = {}) {
     'Upload a local file (or remote URL) to the user\'s Kolbo media library and get back a stable Kolbo CDN URL. Use this when the user wants to reference a local file in multiple subsequent generation calls — upload once, then pass the returned URL to generate_image / generate_video / visual_dna / etc. Auto-detects media type (image / video / audio) from the file extension. For a single-use reference where you already have a public URL, you can skip this and pass the URL directly to the generation tool.',
     {
       source: z.string().describe('URL or absolute local path to the file to upload. For local files this is the primary mode; for URLs, this re-hosts the file on Kolbo CDN for stability.'),
-      description: z.string().optional().describe('Optional description / caption for the uploaded media')
+      description: z.string().optional().describe('Optional description / caption for the uploaded media'),
+      project_id: z.string().optional().describe('Project ObjectId to file the upload into. Call `list_projects` to resolve a name → id. When the user is working in a named project, pass it here too — omitting it files the upload outside that project.')
     },
-    async ({ source, description }) => {
+    async ({ source, description, project_id }) => {
       if (!source) throw new Error('source is required (URL or absolute local path)');
 
       // Even for URL input we download-and-reupload — that's the whole point
@@ -32,6 +33,7 @@ function registerMediaTools(server, client, options = {}) {
       const form = new FormData();
       form.append('file', resolved.buffer, { filename: resolved.filename, contentType: resolved.contentType });
       if (description) form.append('description', description);
+      if (project_id) form.append('project_id', project_id);
 
       const result = await client.postMultipart('/v1/media/upload', form);
 
@@ -49,7 +51,7 @@ function registerMediaTools(server, client, options = {}) {
     'list_media',
     'Browse the user\'s Kolbo media library — both uploaded files AND AI-generated outputs they have saved. Powerful filtering: scope to a single project (`project_id`), a user folder (`folder_id`), a "section" / category (`category`: ai / uploaded / edited / favorites / training-lab), a media type (`type`: image / video / audio), or generation provenance (`source_type`). Combine filters freely. Use this to discover what the user already has before generating something new, to retrieve a specific past creation, or to list everything in a project for downstream batch work.',
     {
-      project_id: z.string().optional().describe('Restrict to a single project (Mongo ObjectId). Use `app_builder_list_projects` to discover IDs. Omit to list across all the user\'s media.'),
+      project_id: z.string().optional().describe('Restrict to a single project (Mongo ObjectId). Use `list_projects` to discover IDs (NOT `app_builder_list_projects` — that is App Builder only). Omit to list across all the user\'s media.'),
       folder_id: z.string().optional().describe('Restrict to a user folder (Mongo ObjectId). Discover folder IDs via `list_media_folders`. Takes precedence over project_id when both are set.'),
       type: z.enum(['image', 'video', 'audio', 'all']).optional().describe('Filter by media type. Default: all types.'),
       category: z.enum(['ai', 'uploaded', 'edited', 'favorites', 'training-lab', 'all']).optional().describe('Filter by "section" (matches the Kolbo desktop app sidebar): `ai` = AI-generated, `uploaded` = files the user uploaded, `edited` = AI-edited variants, `favorites` = items the user starred, `training-lab` = training-lab assets. Default: all sections.'),
@@ -320,7 +322,7 @@ function registerMediaTools(server, client, options = {}) {
     'Move a media item to a different project. Caller must own the item AND have access to the target project. Items in shared projects from other members cannot be moved by you. Use this when the user says "move this to project X" or wants to reorganize.',
     {
       media_id: z.string().describe('MediaLibraryItem id to move.'),
-      project_id: z.string().describe('Target project id (use `app_builder_list_projects` to discover ids).')
+      project_id: z.string().describe('Target project id (use `list_projects` to discover ids — NOT `app_builder_list_projects`).')
     },
     async ({ media_id, project_id }) => {
       const result = await client.patch(

package/src/tools/projects.js

@@ -9,7 +9,7 @@ function registerProjectTools(server, client) {
   // ─── list_projects ─────────────────────────────────────────
   server.tool(
     'list_projects',
-    'List the user\'s projects (owned + shared with edit/full/owner permission). Use this to resolve a project NAME the user mentioned ("put this in my Acme Campaign project") into the project ObjectId you pass back as `project_id` on any generation tool. The tool the user mentions a project by name OR by location, you MUST call this first — the generation tools accept only ObjectIds, not names. Returns id, name, role, and is_default. The project flagged `is_default: true` is the auto-created "API Generations" bucket every SDK generation lands in when project_id is omitted.',
+    'List the user\'s platform projects (owned + shared with edit/full/owner permission). Use this to resolve a project NAME the user mentioned ("put this in my Acme Campaign project") into the project ObjectId you pass back as `project_id` on generation / chat / upload / move tools. Whenever the user mentions a project by name OR location, you MUST call this first — those tools accept only ObjectIds, not names — and then pass the resolved `project_id` on EVERY subsequent call in the conversation (it is per-call, not sticky; omitting it drops work into the default bucket). Returns id, name, role, and is_default. The project flagged `is_default: true` is the auto-created "API Generations" bucket every SDK generation lands in when project_id is omitted. NOT the same as `app_builder_list_projects`, which scopes App Builder coding sessions only.',
     {},
     async () => {
       const result = await client.get('/v1/projects');
@@ -31,6 +31,31 @@ function registerProjectTools(server, client) {
       };
     }
   );
+
+  // ─── move_session ──────────────────────────────────────────
+  server.tool(
+    'move_session',
+    'Move a session — and ALL of its media library items — to another project. Works for any session type: generation sessions (the `session_id` returned by generate_* tools), chat conversations, transcription sessions, etc. Use this when work landed in the wrong project (e.g. the default "API Generations" bucket) and the user wants it in a named project — moving is always better than regenerating. Caller must own the session and have edit/full/owner permission on the target project. Resolve the target project id with `list_projects` first.',
+    {
+      session_id: z.string().describe('The session ObjectId to move (from a generation submit response, chat_list_conversations, or an "Open in Kolbo" link).'),
+      project_id: z.string().describe('Target project ObjectId. Call `list_projects` to resolve a project name to its id.'),
+      type: z.string().optional().describe('Optional session type hint to speed up the lookup: image, video, video_from_image, music, speech, sound, image_edit, creative_director, chat, elements, first_last_frame, lipsync, video_from_video, transcription, global_image_edit, global_video_edit, shorts. Omit if unsure — the server probes all types.')
+    },
+    async ({ session_id, project_id, type }) => {
+      const body = { project_id };
+      if (type) body.type = type;
+      const result = await client.patch(`/v1/sessions/${encodeURIComponent(session_id)}/project`, body);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            session: result.session,
+            _hint: 'The session and its media now live in the new project. Future generations still need `project_id` passed explicitly on each call.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
 }
 
 module.exports = { registerProjectTools };