@kolbo/mcp 1.68.0 → 1.69.0

package/README.md

@@ -113,13 +113,13 @@ Just ask your agent naturally:
 
 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 (117)
+## Available Tools
 
 **Generation**
 | Tool | Description |
 |------|-------------|
-| `generate_image` | Text → image |
-| `generate_image_edit` | Existing image(s) + prompt → edited image |
+| `generate_image` | Text → image. Supports `preset_id` from `list_presets type="image"`. |
+| `generate_image_edit` | Existing image(s) + prompt → edited image. Supports `preset_id` from `list_presets type="image_edit"`. |
 | `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 |
@@ -233,7 +233,7 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 |------|-------------|
 | `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_presets` | Generation presets across image/image-edit/video/music/text-to-video catalogs. Pass the selected exact id as `preset_id`; never claim a preset was applied without it. |
 | `list_cinematic_presets` | "Cinema mode" presets grouped by dimension (camera, lens, focal_length, aperture, angle, shot_type, color_palette, lighting) — pass ids via the `cinematic` arg on `generate_image` / `generate_image_edit`. Only when the user wants a specific cinematic look |
 | `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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.68.0",
+  "version": "1.69.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -10,11 +10,13 @@
     "start": "node src/index.js",
     "smoke": "node scripts/smoke.js",
     "check-parity": "node scripts/check-parity.js",
-    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-model-catalog.js && node scripts/check-skill-tools.js && node scripts/check-install.js",
+    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-model-catalog.js && node scripts/check-skill-tools.js && node scripts/check-submission-contract.js && node scripts/check-install.js",
     "check-model-catalog": "node scripts/check-model-catalog.js",
     "check-widget-fields": "node scripts/check-widget-fields.js",
     "check-widget-render": "node scripts/check-widget-render.js",
     "check-skill-tools": "node scripts/check-skill-tools.js",
+    "check-submission-contract": "node scripts/check-submission-contract.js",
+    "generate-chatgpt-submission": "node scripts/generate-chatgpt-submission.js",
     "check-install": "node scripts/check-install.js"
   },
   "keywords": [

package/skill/SKILL.md

@@ -93,8 +93,8 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 ### 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_image` | Single image from a text prompt. Supports Visual DNA, moodboards, image presets, reference images, web-search grounding. When a preset is requested, resolve it with `list_presets({ type: "image" })` and pass its exact id as `preset_id`. |
+| `generate_image_edit` | Edit/transform an existing image. Pass `source_images` + edit prompt. Image-editing presets are supported through `preset_id` from `list_presets({ type: "image_edit" })`. |
 | `generate_creative_director` | **2–8 related images or videos as one coherent set.** Use INSTEAD of multiple `generate_image` calls for any related multi-output. |
 | `generate_video` | Text-to-video. Does **not** support Visual DNA — use `generate_elements` for character-consistent video. |
 | `generate_video_from_image` | Animate a still. Prompt describes motion, not subject. |
@@ -113,7 +113,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `list_models` / `list_voices` / `check_credits` / `get_generation_status` / `cancel_generation` / `get_session_usage` | Discovery + status. `list_models` with no args returns the recommended shortlist out of ~428 — pass `type` for a full category with per-model caps. `cancel_generation` stops an in-flight job and refunds what it can: use it when the user changes their mind mid-generation instead of letting it run. |
 | `upload_media` / `create_upload_ticket` / `list_media` / `get_media` / `get_media_stats` / `favorite_media` / `unfavorite_media` / `delete_media` / `restore_media` / `permanently_delete_media` / `move_media` / `bulk_*_media` / `*_media_folder` | Media library — see `workflows/media-library.md`. Getting a LOCAL file in depends on where the server runs: `upload_media` with a path only works on a local (stdio) install; over a remote connector use `create_upload_ticket` and POST the file yourself. |
 | `create_visual_dna` / `generate_character_sheet` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` / `*_visual_dna_folder` (5 folder tools) | Visual DNA (+ character sheet, character folders) — see `workflows/visual-dna.md` |
-| `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays |
+| `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays. A preset request is binding: resolve the requested or closest matching preset in the correct catalog, then pass its exact returned `id` as `preset_id`. Never say a preset was used if the generation call omitted it. |
 | `list_color_palettes` / `analyze_color_palette` / `create_color_palette` / `update_color_palette` / `delete_color_palette` / `activate_color_palette` / `deactivate_color_palette` | **Color DNA — sticky and account-wide.** At most one palette is active at a time; while it is, it strict-grades **every** image and video generation automatically, with no per-call argument. `analyze_color_palette` pulls colors out of 1-5 image URLs for free and does NOT save. `create_color_palette` defaults `is_active: true`, which activates it and deactivates any other. Per-generation opt-out: `skip_color_palette: true` on `generate_image` / `generate_image_edit` / `generate_video` / `generate_video_from_image`. |
 | `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Custom chat agents — reusable named personas for `chat_send_message`. The agent's `description` IS the system instruction. Resolve a name the user mentions ("use my SEO agent") to an id with `list_agents`, then pass `agent_id`. Global/preset agents are read-only; only the user's own can be updated or deleted. |
 | `search_stock_media` / `get_stock_sources` / `get_stock_categories` / `get_stock_collections` / `get_stock_asset` / `analyze_script_for_stock` / `import_stock_asset` | Stock library (free, no credits) — EXISTING photos / videos / 3D / SFX / music. For stock **music** use `search_stock_media` with `mediaType: "music"` (semantic vibe query, e.g. "uplifting corporate background") → `get_stock_asset` for downloads. The older `*_music_library` tools are deprecated adapters over this — prefer the stock tools, except for the licensed-catalog tools in the next row. |
@@ -158,6 +158,8 @@ A user-named tool — in any language — overrides every other rule. Recognized
 
 ## Core Workflow
 
+**Preset contract:** if the user asks for a preset, names one, or says to use one of their/Kolbo presets, call `list_presets` with the matching type before generation and pass the selected exact `id` as `preset_id`. Use `image` for `generate_image` and `image_edit` for `generate_image_edit`. Never invent an id or silently continue without the requested preset.
+
 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**:

package/src/apps/index.js

@@ -54,44 +54,45 @@ function widgetHtml(uri) {
 // img/script/style/font/media-src; connectDomains to connect-src.
 const WIDGET_CSP = {
   resourceDomains: [
-    // Exact hosts FIRST — not every host CSP implementation honors wildcards,
-    // and a declared-but-unmatched allowlist blocks harder than no declaration.
-    'https://api.kolbo.ai',                     // model icons (/assets)
+    // Public production hosts owned by Kolbo.
+    'https://api.kolbo.ai',
     'https://app.kolbo.ai',
-    'https://media.kolbo.ai',                   // media CDN (prod)
-    'https://media-staging.kolbo.ai',
-    'https://media-dev.kolbo.ai',
+    'https://media.kolbo.ai',
+    'https://cdn.kolbo.ai',
     'https://kolboai-production.ams3.digitaloceanspaces.com',
     'https://kolboai-production.ams3.cdn.digitaloceanspaces.com',
-    'https://kolboai-development.ams3.digitaloceanspaces.com',
-    'https://kolboai-development.ams3.cdn.digitaloceanspaces.com',
+    'https://kolbo-general-media.fra1.digitaloceanspaces.com',
     'https://kolbo-general-media.fra1.cdn.digitaloceanspaces.com',
-    'https://fonts.googleapis.com',             // Inter / JetBrains Mono stylesheet
-    'https://fonts.gstatic.com',                // font files
-    'https://images.pexels.com',                // stock thumbnails
-    'https://images.unsplash.com',              // stock thumbnails (Unsplash)
-    'https://plus.unsplash.com',                // Unsplash+ premium images
-    'https://cdn.coverr.co',                    // Coverr video thumbnails
-    'https://cdn.freesound.org',                // Freesound waveform previews
-    // Wildcards as a second layer for hosts that do support them.
-    'https://*.kolbo.ai',
-    'https://*.digitaloceanspaces.com',
-    'https://*.cdn.digitaloceanspaces.com',
-    'https://*.pexels.com',
-    'https://*.pixabay.com',
-    'https://*.unsplash.com',
-    'https://*.coverr.co',
-    'https://*.freesound.org',
-    'https://*.sketchfab.com',
-    'https://*.cloudfront.net',
+
+    // Fonts used by the shared widget shell.
+    'https://fonts.googleapis.com',
+    'https://fonts.gstatic.com',
+
+    // Exact preview hosts returned by the production stock integrations.
+    'https://images.pexels.com',
+    'https://videos.pexels.com',
+    'https://images.unsplash.com',
+    'https://plus.unsplash.com',
+    'https://pixabay.com',
+    'https://cdn.pixabay.com',
+    'https://coverr.co',
+    'https://cdn.coverr.co',
+    'https://freesound.org',
+    'https://cdn.freesound.org',
+    'https://sketchfab.com',
+    'https://media.sketchfab.com',
+    'https://cdn.sketchfab.com',
+    'https://assets.sketchfab.com',
+    'https://sketchfab-prod-media.s3.amazonaws.com',
+
+    // Default SYNCI catalog project. Any production override must be reviewed
+    // and added here as an exact hostname before deployment.
+    'https://gfbpxdkripkbbrcvoyeh.supabase.co',
   ],
   // connect-src — XHR/fetch FROM widget iframes. Used by the upload widget to
   // POST files to /mcp/upload with its short-lived ticket.
   connectDomains: [
     'https://api.kolbo.ai',
-    'https://api-staging.kolbo.ai',
-    'https://api-dev.kolbo.ai',
-    'https://*.kolbo.ai',
   ],
 };
 
@@ -418,7 +419,6 @@ const TOOL_WIDGETS = {
   generate_3d: UI.generation,
   edit_image: UI.generation,
   edit_video: UI.generation,
-  shorts_render: UI.generation,
   // transcript viewer
   transcribe_audio: UI.transcript,
   // model catalog
@@ -433,7 +433,6 @@ const TOOL_WIDGETS = {
   list_voices: UI.mediaGrid,
   list_visual_dnas: UI.mediaGrid,
   list_moodboards: UI.mediaGrid,
-  shorts_analyze: UI.mediaGrid,
   // NOTE: list_color_palettes' handler has always called uiResult(UI.mediaGrid, ...)
   // (see color_palettes.js) but was missing here — hosts that prepare the widget
   // iframe from the tool DECLARATION (claude.ai reads tools/list, not the result)
@@ -463,6 +462,7 @@ function attachToolWidgetMeta(server) {
 
 module.exports = {
   UI,
+  WIDGET_CSP,
   TOOL_WIDGETS,
   registerApps,
   attachToolWidgetMeta,

package/src/apps/theme.js

@@ -140,7 +140,7 @@ body {
   background: linear-gradient(transparent, rgba(0, 0, 0, 0.65));
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .k-skel.done::after { animation: none; background: none; }
-.k-cell-fill { width: 100%; height: 100%; object-fit: cover; display: block; }
+.k-cell-fill { width: 100%; height: 100%; object-fit: contain; display: block; background: #000; }
 .k-gen-badge {
   position: absolute; top: 10px; left: 10px; z-index: 2;
   display: inline-flex; align-items: center; gap: 6px;
@@ -170,7 +170,7 @@ body {
 .k-media { position: relative; border-radius: 10px; overflow: hidden; border: 1px solid var(--border);
   background: #000; cursor: pointer; transition: transform 300ms var(--spring), box-shadow 300ms var(--smooth); }
 .k-media:hover { transform: scale(1.015); box-shadow: 0 8px 28px rgba(0, 0, 0, 0.45); }
-.k-media img, .k-media video { display: block; width: 100%; height: 100%; object-fit: cover; }
+.k-media img, .k-media video { display: block; width: 100%; height: 100%; object-fit: contain; }
 .k-media.selected { outline: 2px solid var(--brand); outline-offset: 1px; }
 
 /* ---- Per-item hover download button (multi-image grids, CD scenes, viewer) ---- */
@@ -257,7 +257,7 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
   background: var(--surface); cursor: pointer; transition: transform 250ms var(--spring); }
 .k-cell:hover { transform: translateY(-2px) scale(1.01); }
 .k-cell .k-cell-media { position: relative; aspect-ratio: 1; background: #000; }
-.k-cell .k-cell-media img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.k-cell .k-cell-media img { width: 100%; height: 100%; object-fit: contain; display: block; }
 .k-cell-play { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); }
 .k-cell .k-cell-label { padding: 6px 8px; font-size: 11px; color: var(--text-muted);
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }

package/src/apps/widgets/mediaGrid.js

@@ -112,7 +112,7 @@ function wire() {
       e.stopPropagation();
       var url = b.getAttribute('data-video-play');
       var holder = b.parentNode;
-      holder.innerHTML = '<video src="' + esc(url) + '" controls autoplay playsinline style="width:100%;height:100%;object-fit:cover"></video>';
+      holder.innerHTML = '<video src="' + esc(url) + '" controls autoplay playsinline style="width:100%;height:100%;object-fit:contain;background:#000"></video>';
       holder.querySelector('video').onclick = function (ev) { ev.stopPropagation(); };
     };
   });

package/src/index.js

@@ -76,7 +76,8 @@ const { registerReviewTools } = require('./tools/review');
 const { registerVoiceTools } = require('./tools/voices');
 const { registerMusicLibraryTools } = require('./tools/music_library');
 const { registerStockLibraryTools } = require('./tools/stock_library');
-const { registerApps, attachToolWidgetMeta } = require('./apps');
+const { registerApps, attachToolWidgetMeta } = require('./apps');
+const { attachToolAnnotations } = require('./toolAnnotations');
 
 /**
  * Build a fully-configured Kolbo MCP server (all tool groups registered)
@@ -126,7 +127,8 @@ function createServer(opts = {}) {
       '7. SESSION CONTINUITY — one task, one session, always: every generation tool returns a `session_id`. For ANY follow-up, refinement, retry, or next step on the SAME task, pass that session_id back — never start fresh. BATCH RULE (critical): when a single user request produces multiple parallel generations (e.g. "animate these 5 images", "generate 3 variants"), do NOT launch them all at once without a session_id. Instead: (1) run the FIRST generation without session_id to create the session, (2) capture the session_id from its response, (3) pass that session_id to ALL remaining generations in the batch. This keeps the entire batch in one session. Exception: only omit session_id and start fresh when the user explicitly starts an unrelated new task.',
       '8. LOCAL FILES / REFERENCE MEDIA — HOW TO HANDLE EVERY CASE. (A) User has a LOCAL file (audio, video, image, document) on their machine. What matters is WHERE THIS SERVER RUNS, not what your client can do — your own filesystem access is irrelevant if the server is somewhere else. On a LOCAL stdio install (server and client share a machine) → call `upload_media` with the absolute path, or pass the path straight to tools like `transcribe_audio` that accept local paths. Over a REMOTE connector the server cannot see that path no matter how capable you are, so a local path will always fail: if you can run shell commands or issue HTTP requests → call `create_upload_ticket` and POST the file to the returned upload_url yourself (fastest, no user interaction); if you cannot → call `media_upload_widget` IMMEDIATELY, the user uploads, and a `media.kolbo.ai` CDN URL comes back for any follow-up call. (B) You already have a public URL (media.kolbo.ai, any CDN, any direct link) → pass it directly; all Kolbo tools accept public URLs. NEVER search for DO Spaces keys, DigitalOcean credentials, or server-side upload credentials. NEVER ask the user to put the file on Google Drive, Dropbox, or Loom. NEVER invent or guess a URL. NEVER base64 anything but a tiny file — it costs context in proportion to file size; use the ticket or the widget instead.',
       '9. MODEL SELECTION — ROUTE BY THE STRENGTHS SUMMARY, NEVER BY THE BADGE OR THE PRICE TAG: ALWAYS pass a specific `model` on every generation tool — do NOT omit it (omitting falls back to "Smart Select" auto-routing, which hides the choice from the user; use it ONLY if the user explicitly asks you to auto-pick). To choose: call `list_models` with the matching `type` and read each model\'s STRENGTHS SUMMARY — the "— …" clause printed after the credit cost. That summary IS the routing instruction: match it against what the user actually asked for (subject, style, motion, length, quality bar, speed), then pick the CHEAPEST model whose summary covers the task. `[NEW]` and `[RECOMMENDED]` badges, a high credit number, and "flagship"/"most intelligent" wording are NOT selection signals — never pick a model because it is newest, biggest or most expensive. Escalate to a premium/frontier model only when the user explicitly asks for maximum quality, or when no cheaper summary covers the requirement. Models printed under "Named-only" (no summary) are opt-in: use them only when the user names them. TEXT/CHAT: `chat_send_message` bills PER TOKEN, so the listed credit number is not the cost — a frontier text model (Claude Fable 5, GPT-5.6 Sol, Pro-class) costs 5-30x a mid-tier one per reply. Default ordinary chat (writing, brainstorming, Q&A, summarising) to a balanced mid-tier model and reserve the frontier tier for hard reasoning or long-form code the user asked for.',
-      '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit` (it runs on strong dedicated editing models, same as image generation). Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.'
+      '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit` (it runs on strong dedicated editing models, same as image generation). Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.',
+      '11. PRESET CONTRACT: if the user asks for a preset, names a preset, or says to use one of their/Kolbo presets, you MUST call `list_presets` with the matching type before generation, resolve the named or closest matching preset, and pass its exact returned `id` as `preset_id`. Use type="image" for generate_image and type="image_edit" for generate_image_edit. Never silently ignore a preset request, never invent an id, and never claim a preset was applied unless `preset_id` was present in the generation call.'
     ].join('\n')
   });
   const progress = require('./progress');
@@ -171,8 +173,12 @@ function createServer(opts = {}) {
   // transport. Without it, a remote-connector model reads "absolute local path",
   // sees no filesystem, and tells the user Kolbo cannot accept their file —
   // the single most-reported failure, despite the upload tools existing.
-  attachFileInputHints(server, toolOptions);
-  // Declaration-level `_meta['ui/resourceUri']` on every widget-carrying tool —
+  attachFileInputHints(server, toolOptions);
+  // OpenAI public-app review requires every exposed tool to declare the three
+  // safety hints explicitly. The exact contract also fails closed when a tool
+  // is added or removed without a classification.
+  attachToolAnnotations(server);
+  // Declaration-level `_meta['ui/resourceUri']` on every widget-carrying tool —
   // claude.ai prepares the widget iframe from tools/list, not from the result.
   attachToolWidgetMeta(server);
 

package/src/toolAnnotations.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * Public MCP safety contract.
+ *
+ * ChatGPT app review requires every exposed tool to declare all three hints.
+ * Keep this map exact: the submission gate rejects missing, duplicate, stale,
+ * or non-boolean entries whenever the registered tool surface changes.
+ */
+
+const READ_ONLY = [
+  'get_creative_director_status', 'get_generation_status', 'list_models',
+  'check_credits', 'get_session_usage', 'list_voices',
+  'chat_list_conversations', 'chat_get_messages',
+  'list_visual_dnas', 'get_visual_dna', 'list_visual_dna_folders',
+  'list_moodboards', 'get_moodboard',
+  'list_color_palettes', 'analyze_color_palette',
+  'list_media', 'list_media_folders', 'get_media', 'get_media_stats',
+  'list_presets', 'list_cinematic_presets',
+  'list_projects', 'list_sessions', 'list_project_context', 'get_project_profile',
+  'list_session_generations',
+  'list_agents', 'list_docs', 'get_doc',
+  'get_review_storage_usage', 'list_review_assets', 'get_review_asset',
+  'list_review_collections', 'list_review_comments', 'list_review_share_links',
+  'search_music_library', 'analyze_script_for_music', 'browse_music_library',
+  'get_music_library_facets', 'get_music_track_audio',
+  'get_music_track_related', 'get_music_track_lyrics',
+  'search_stock_media', 'get_stock_sources', 'get_stock_categories',
+  'get_stock_collections', 'get_stock_asset', 'analyze_script_for_stock',
+];
+
+const PRIVATE_WRITE = [
+  'media_upload_widget', 'create_upload_ticket', 'upload_media',
+  'favorite_media', 'unfavorite_media',
+  'create_media_folder', 'update_media_folder',
+  'add_media_to_folder', 'remove_media_from_folder',
+  'share_media_folder',
+  'restore_media', 'move_media', 'bulk_restore_media', 'bulk_move_media',
+  'move_folder_contents',
+  'import_elevenlabs_voice',
+  'create_visual_dna', 'create_visual_dna_folder', 'update_visual_dna_folder',
+  'move_visual_dna_to_folder',
+  'create_moodboard',
+  'create_color_palette', 'activate_color_palette', 'deactivate_color_palette',
+  'move_session', 'bulk_move_sessions', 'move_generations_to_session',
+  'split_session', 'undo_session_organization',
+  'create_project', 'update_project',
+  'archive_project', 'unarchive_project', 'add_project_context',
+  'create_agent',
+  'create_doc',
+  'create_review_asset', 'update_review_asset', 'add_review_version',
+  'set_review_status', 'create_review_collection', 'update_review_collection',
+  'create_review_comment', 'reply_review_comment',
+  'resolve_review_comment', 'unresolve_review_comment',
+  'import_stock_asset',
+];
+
+const DESTRUCTIVE_WRITE = [
+  // These actions spend credits, enqueue irreversible work, or cancel it.
+  'generate_image', 'generate_image_edit', 'generate_creative_director',
+  'generate_video', 'generate_video_from_image', 'generate_music',
+  'generate_speech', 'generate_sound', 'cancel_generation',
+  'generate_elements', 'generate_first_last_frame', 'generate_lipsync',
+  'generate_video_from_video', 'transcribe_audio', 'generate_3d',
+  'edit_image', 'edit_video', 'trim_video', 'clone_voice',
+  'chat_send_message', 'generate_character_sheet',
+  'acquire_clean_music_track', 'import_music_track_to_library',
+
+  // Deletes and whole-value replacement updates are conservatively destructive.
+  'delete_voice', 'delete_visual_dna', 'delete_visual_dna_folder',
+  'update_moodboard', 'delete_moodboard',
+  'update_color_palette', 'delete_color_palette',
+  'delete_media_folder', 'delete_media', 'permanently_delete_media',
+  'bulk_delete_media', 'bulk_permanently_delete_media',
+  'unshare_media_folder',
+  'delete_project_context', 'regenerate_project_profile',
+  'update_agent', 'delete_agent', 'update_doc', 'delete_doc',
+  'delete_review_asset', 'delete_review_collection',
+  'edit_review_comment', 'delete_review_comment',
+];
+
+const OPEN_WORLD_WRITE = [
+  'publish_html_artifact', 'create_review_share_link',
+];
+
+const OPEN_WORLD_DESTRUCTIVE = [
+  'share_doc', 'revoke_review_share_link',
+];
+
+const CONTRACT_GROUPS = [
+  [READ_ONLY, { readOnlyHint: true, openWorldHint: false, destructiveHint: false }],
+  [PRIVATE_WRITE, { readOnlyHint: false, openWorldHint: false, destructiveHint: false }],
+  [DESTRUCTIVE_WRITE, { readOnlyHint: false, openWorldHint: false, destructiveHint: true }],
+  [OPEN_WORLD_WRITE, { readOnlyHint: false, openWorldHint: true, destructiveHint: false }],
+  [OPEN_WORLD_DESTRUCTIVE, { readOnlyHint: false, openWorldHint: true, destructiveHint: true }],
+];
+
+function buildToolAnnotations() {
+  const annotations = Object.create(null);
+  for (const [names, hints] of CONTRACT_GROUPS) {
+    for (const name of names) {
+      if (annotations[name]) throw new Error(`Duplicate safety annotation contract for tool: ${name}`);
+      annotations[name] = Object.freeze({ ...hints });
+    }
+  }
+  return Object.freeze(annotations);
+}
+
+const TOOL_ANNOTATIONS = buildToolAnnotations();
+
+function attachToolAnnotations(server) {
+  const registered = server?._registeredTools || {};
+  const registeredNames = Object.keys(registered).sort();
+  const contractNames = Object.keys(TOOL_ANNOTATIONS).sort();
+  const missing = registeredNames.filter((name) => !TOOL_ANNOTATIONS[name]);
+  const stale = contractNames.filter((name) => !registered[name]);
+  if (missing.length || stale.length) {
+    throw new Error(
+      `Tool annotation contract mismatch. Missing: ${missing.join(', ') || 'none'}. `
+      + `Stale: ${stale.join(', ') || 'none'}.`
+    );
+  }
+  for (const name of registeredNames) registered[name].annotations = TOOL_ANNOTATIONS[name];
+}
+
+module.exports = {
+  TOOL_ANNOTATIONS,
+  CONTRACT_GROUPS,
+  attachToolAnnotations,
+};

package/src/tools/generate.js

@@ -141,7 +141,7 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_image ────────────────────────────────────────
   server.tool(
     'generate_image',
-    'Generate image(s) from a text prompt using Kolbo AI. Supports Visual DNA profiles (for character/style/product consistency), moodboards (for style direction), reference images (for composition guidance), batch generation (num_images for variations of ONE prompt, `prompts` for SEVERAL different prompts in one combined widget), and web-search grounding. When the user wants multiple distinct images, pass all their prompts in `prompts` in ONE call — never a series of separate generate_image calls. For EDITING an existing image, use generate_image_edit instead. For a coordinated multi-scene set planned by AI from a single brief (storyboard, ad campaign), use generate_creative_director. Returns the final image URL(s) when complete.',
+    'Generate image(s) from a text prompt using Kolbo AI. Supports Visual DNA profiles (for character/style/product consistency), moodboards (for style direction), Kolbo image presets, reference images (for composition guidance), batch generation (num_images for variations of ONE prompt, `prompts` for SEVERAL different prompts in one combined widget), and web-search grounding. PRESET CONTRACT: when the user asks to use a preset, a named preset, or "one of my/Kolbo image presets", call list_presets type="image" first, resolve the requested or best-matching preset, and pass its exact id as `preset_id`; never silently generate without it. When the user wants multiple distinct images, pass all their prompts in `prompts` in ONE call — never a series of separate generate_image calls. For EDITING an existing image, use generate_image_edit instead. For a coordinated multi-scene set planned by AI from a single brief (storyboard, ad campaign), use generate_creative_director. Returns the final image URL(s) when complete.',
     {
       prompt: z.string().optional().describe('Text description of the image to generate. Required unless `prompts` is provided.'),
       prompts: promptsField('images'),
@@ -155,7 +155,7 @@ function registerGenerateTools(server, client, options = {}) {
       enable_web_search: z.boolean().optional().describe('Enable web-search grounding for the prompt (useful for current events, brand references, real-world accuracy). Default: false'),
       resolution: z.string().optional().describe('Image resolution tier: "1K" (~1024px), "2K" (Full HD), "3K" (QHD), or "4K" (UHD). Model-dependent — call list_models and read supported_resolutions on the chosen model. Read resolution_multipliers on the same model to predict credit cost. Omit to use the model default.'),
       quality: z.string().optional().describe('Quality tier for models that support it (e.g. "low", "medium", "high", "auto"). Check list_models → supported_qualities on the chosen model. "auto" is normalised to "medium" on gpt-image-2. Omit to use the model default.'),
-      preset_id: z.string().optional().describe('Preset ID from list_presets type="image" to apply a saved style preset to this generation.'),
+      preset_id: z.string().optional().describe('Exact preset ID from list_presets type="image". If the user requests any image preset, resolve it with list_presets and pass it here; do not omit it.'),
       cinematic: CINEMATIC_SCHEMA,
       skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one image ungraded.'),
       project_id: projectIdField,
@@ -218,7 +218,7 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_image_edit ──────────────────────────────────
   server.tool(
     'generate_image_edit',
-    'THE tool for ANY prompt-driven / content edit of an existing image — changing the scene ("make it night", "change the sky to sunset"), adding/removing/replacing objects, restyling, recoloring, compositing, or any "edit this image to…" request. This is the image-editing equivalent of generate_image and runs on strong dedicated editing models (nano-banana-2, gpt-image-2). Provide the source image URL(s) in `source_images` and the instruction in `prompt`. Supports Visual DNA profiles and moodboards for style-consistent edits. Do NOT use `edit_image` for these — that tool is only for mechanical enhancements (upscale/reframe/remove-background/skin). For a brand-new image from scratch, use generate_image. Returns the edited image URL(s) when complete.',
+    'THE tool for ANY prompt-driven / content edit of an existing image — changing the scene ("make it night", "change the sky to sunset"), adding/removing/replacing objects, restyling, recoloring, compositing, or any "edit this image to…" request. This is the image-editing equivalent of generate_image and runs on strong dedicated editing models (nano-banana-2, gpt-image-2). Provide the source image URL(s) in `source_images` and the instruction in `prompt`. Supports Visual DNA profiles, moodboards, and Kolbo image-editing presets. PRESET CONTRACT: if the user requests a preset, call list_presets type="image_edit" and pass its exact id as `preset_id`; never silently omit it. Do NOT use `edit_image` for these — that tool is only for mechanical enhancements (upscale/reframe/remove-background/skin). For a brand-new image from scratch, use generate_image. Returns the edited image URL(s) when complete.',
     {
       prompt: z.string().describe('Description of the edit to apply (e.g., "remove the background", "change the sky to sunset")'),
       model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Many text-to-image ids double as editors: the server auto-routes a base id to its editing variant when source_images is present (e.g. "gpt-image-2" → gpt-image-2/edit, "nano-banana-2" → nano-banana-2/edit) — passing the bare id is fine, no need to hunt for the "/edit" suffix yourself. BUT this only works for models that actually have a registered edit variant (most flagship models do: gpt-image, nano-banana, flux-2, seedream, qwen, wan, grok-imagine, kling-image families). Models with none (Midjourney, Flux Pro/Ultra, Imagen4, Ideogram, Recraft, Higgsfield Soul, Krea, Dreamina, and others) silently ignore source_images if passed here instead of erroring — if unsure, confirm the model appears in `list_models type="image_editing"` before trusting a bare id, or just use a known-safe default: "nano-banana-pro/edit" (best general prompt editor), "gpt-image-2" (photoreal, strong text), or "flux-2/edit".'),
@@ -230,22 +230,23 @@ function registerGenerateTools(server, client, options = {}) {
       moodboard_id: z.string().optional().describe('Moodboard ID whose master_prompt and style_guide should be applied.'),
       enable_web_search: z.boolean().optional().describe('Enable web-search grounding. Default: false'),
       resolution: z.string().optional().describe('Image resolution tier: "1K" / "2K" / "3K" / "4K". Model-dependent — call list_models and read supported_resolutions. Default: "1K" for most edit models.'),
+      preset_id: z.string().optional().describe('Exact preset ID from list_presets type="image_edit" to apply an image-editing preset. If the user requests a preset, resolve and pass it; do not silently omit it.'),
       cinematic: CINEMATIC_SCHEMA,
       skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one edit ungraded.'),
       project_id: projectIdField,
       session_id: sessionIdField
     },
-    async ({ prompt, model, source_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id, session_id }) => {
+    async ({ prompt, model, source_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id, cinematic, skip_color_palette, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'image_editing'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/image-edit', {
         prompt, model, source_images, aspect_ratio, enhance_prompt, num_images,
-        visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id, session_id
+        visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id, cinematic, skip_color_palette, project_id, session_id
       });
 
       if (ui()) return uiGenerating({
         tool: 'generate_image_edit', kind: 'image', gen, client, model, prompt,
         count: num_images,
-        settings: imageSettings({ resolution, aspect_ratio, enhance_prompt, enable_web_search, visual_dna_ids, moodboard_id, cinematic }),
+        settings: imageSettings({ resolution, aspect_ratio, enhance_prompt, enable_web_search, visual_dna_ids, moodboard_id, preset_id, cinematic }),
         reference_image: source_images?.[0]
       });
 

package/src/tools/presets.js

@@ -12,9 +12,9 @@ function registerPresetTools(server, client, options = {}) {
   // ─── list_presets ──────────────────────────────────────────
   server.tool(
     'list_presets',
-    'List generation presets across image, video, music, and text-to-video catalogs. Presets bundle a specific prompt template + style direction that can be passed to a generation tool via its `preset_id` arg for a one-shot creative direction. Filter by `type` to narrow to a specific catalog. Returns id, name, description, thumbnail, category, and (for music) audio preview URL.',
+    'List generation presets across image, image-editing, video, music, and text-to-video catalogs. Use this BEFORE generating whenever the user requests a preset, names a preset, or asks to use one of their/Kolbo presets. Resolve the requested name or choose the closest match from the correct `type`, then pass the returned exact `id` as `preset_id` on the generation tool. Never claim a preset was used unless that id is passed. Returns id, name, description, thumbnail, category, and (for music) audio preview URL.',
     {
-      type: z.string().optional().describe('Filter by catalog: "image" | "video" | "music" | "text_to_video". Omit for all.')
+      type: z.string().optional().describe('Filter by catalog: "image" | "image_edit" | "video" | "music" | "text_to_video". Omit for all.')
     },
     async ({ type }) => {
       const params = new URLSearchParams();
@@ -30,7 +30,7 @@ function registerPresetTools(server, client, options = {}) {
         cap: 60,
         total: result.count || presets.length,
         extra: result.warning ? { warning: result.warning } : undefined,
-        note: 'Filter with `type` (image | video | music | text_to_video) to see a focused set.',
+        note: 'Filter with `type` (image | image_edit | video | music | text_to_video) to see a focused set. Pass the chosen exact id as `preset_id` on the next generation call.',
       });
 
       if (ui()) {

package/src/tools/projects.js

@@ -64,7 +64,7 @@ function registerProjectTools(server, client, options = {}) {
   // ─── 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.',
+    'Move ONE session — and ALL of its generations and 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. For SEVERAL sessions use `bulk_move_sessions` instead: one call, up to 100 sessions, and it reports per-session failures. Caller needs edit/full/owner permission on BOTH the source and target projects (a shared-project member can move a teammate\'s session). 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.'),
@@ -85,6 +85,141 @@ function registerProjectTools(server, client, options = {}) {
       };
     }
   );
+
+  // ─── bulk_move_sessions ────────────────────────────────────
+  server.tool(
+    'bulk_move_sessions',
+    'Move MANY sessions into one project in a single call — the tool to use when reorganizing a user\'s library ("file all my Acme work into the Acme project", "clean up the API Generations bucket"). Each session carries ALL of its generations and media with it. Prefer this over looping `move_session`: one call handles up to 100 sessions, while `move_session` is rate limited per call. Sessions of mixed types (chat + image + video) can go in the SAME call. Each session moves independently, so one that cannot move — a generation still running, a Creative Director session, or one you lack edit access to — does NOT block the rest; check `failed[]` in the result and report those to the user. Resolve session ids with `list_sessions` and the target project id with `list_projects` first.',
+    {
+      session_ids: z.array(z.string()).describe('Session ObjectIds to move (from `list_sessions`, a generation submit response, or an "Open in Kolbo" link). Up to 100 per call; types may be mixed.'),
+      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 that speeds up the lookup when EVERY id in the batch is the same type: image, video, video_from_image, music, speech, sound, image_edit, chat, elements, first_last_frame, lipsync. Omit for mixed batches — the server probes all types.')
+    },
+    async ({ session_ids, project_id, type }) => {
+      const body = { session_ids, project_id };
+      if (type) body.type = type;
+      const result = await client.post('/v1/sessions/move', body);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            project_id: result.project_id,
+            moved_sessions_count: result.moved_sessions_count,
+            moved_generations_count: result.moved_generations_count,
+            moved_media_count: result.moved_media_count,
+            skipped: result.skipped,
+            failed: result.failed,
+            operation_ids: result.operation_ids,
+            _hint: (result.failed && result.failed.length)
+              ? 'Some sessions did not move — tell the user which ones and why (see failed[]). The rest are already in the new project.'
+              : 'Every session, its generations and its media now live in the new project. Pass any operation_id to `undo_session_organization` within 15 minutes to reverse one.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── list_session_generations ──────────────────────────────
+  server.tool(
+    'list_session_generations',
+    'List a session\'s generations as complete GROUPS — each entry is one generation with its prompt and ALL the outputs it produced. Call this FIRST whenever the user wants to reorganize WITHIN or BETWEEN sessions ("move these three shots into their own session", "split the good takes out"), because `move_generations_to_session` and `split_session` take the ids this returns. Also the cheapest way to see what is actually inside a session before moving it. A generation is never separable from its own outputs, so you always move whole entries. Only image, image-to-video, lipsync and video-to-video sessions support this level of organization; other types return SESSION_TYPE_NOT_MOVABLE and should be moved whole with `move_session`.',
+    {
+      session_id: z.string().describe('The session ObjectId to inspect.'),
+      type: z.string().optional().describe('Optional session type hint to speed up the lookup. Omit if unsure.')
+    },
+    async ({ session_id, type }) => {
+      const path = `/v1/sessions/${encodeURIComponent(session_id)}/generations`;
+      const result = await client.get(path + (type ? `?type=${encodeURIComponent(type)}` : ''));
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            session: result.session,
+            generations: result.generations,
+            _hint: 'Pass the `id` values to `move_generations_to_session` (into an existing session) or `split_session` (into a new one). `in_flight: true` means it is still running and cannot be moved yet.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── move_generations_to_session ───────────────────────────
+  server.tool(
+    'move_generations_to_session',
+    'Move SELECTED generations out of one session and into another EXISTING session — the way to merge scattered work ("put these shots into my Hero Sequence session", "these three belong with the earlier batch"). Only the chosen generations and THEIR OWN output media move; shared uploads and reference images stay with the source session, so nothing another generation still depends on is dragged away. The destination must be a session of the SAME kind, and may live in a different project as long as you can edit both. Get the generation ids from `list_session_generations` and the destination id from `list_sessions`. Running generations cannot be moved — wait for them to finish.',
+    {
+      session_id: z.string().describe('Source session ObjectId — the session the generations are in now.'),
+      generation_ids: z.array(z.string()).describe('Generation ids to move, from `list_session_generations`. Whole entries only.'),
+      target_session_id: z.string().describe('Destination session ObjectId. Must be the same session kind as the source.'),
+      type: z.string().optional().describe('Optional session type hint to speed up the lookup. Omit if unsure.')
+    },
+    async ({ session_id, generation_ids, target_session_id, type }) => {
+      const body = { generation_ids, target_session_id };
+      if (type) body.type = type;
+      const result = await client.post(
+        `/v1/sessions/${encodeURIComponent(session_id)}/generations/move`, body
+      );
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            moved_generations_count: result.moved_generations_count,
+            moved_media_count: result.moved_media_count,
+            target_session_id: result.target_session_id,
+            project_id: result.project_id,
+            operation_id: result.operation_id,
+            _hint: 'Reversible for 15 minutes — pass operation_id to `undo_session_organization`.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── split_session ─────────────────────────────────────────
+  server.tool(
+    'split_session',
+    'Carve selected generations out of a session into a BRAND NEW named session, atomically. Use when one session has grown into several distinct pieces of work ("separate the product shots from the lifestyle ones", "give the approved takes their own session"). Creates the new session and moves the chosen generations plus their output media into it in one transaction — nothing half-lands. The new session goes in the same project unless you pass `project_id`. Get the generation ids from `list_session_generations` first.',
+    {
+      session_id: z.string().describe('Source session ObjectId to split.'),
+      generation_ids: z.array(z.string()).describe('Generation ids to move into the new session, from `list_session_generations`.'),
+      name: z.string().describe('Name for the new session — make it descriptive, the user sees it in the sidebar.'),
+      project_id: z.string().optional().describe('Put the new session in a DIFFERENT project. Omit to keep it in the source session\'s project. You need edit access on both.'),
+      type: z.string().optional().describe('Optional session type hint to speed up the lookup. Omit if unsure.')
+    },
+    async ({ session_id, generation_ids, name, project_id, type }) => {
+      const body = { generation_ids, name };
+      if (project_id) body.project_id = project_id;
+      if (type) body.type = type;
+      const result = await client.post(`/v1/sessions/${encodeURIComponent(session_id)}/split`, body);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            session: result.session,
+            moved_generations_count: result.moved_generations_count,
+            moved_media_count: result.moved_media_count,
+            operation_id: result.operation_id,
+            _hint: 'Reversible for 15 minutes — `undo_session_organization` removes the new session and returns its generations.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── undo_session_organization ─────────────────────────────
+  server.tool(
+    'undo_session_organization',
+    'Reverse a session move, generation move, or split within 15 minutes of making it. Use immediately when the user says the reorganization was wrong ("no, put that back", "undo that move"). Takes the `operation_id` returned by `move_session`, `bulk_move_sessions`, `move_generations_to_session` or `split_session` — a batch move returns one id PER session, so call this once per id you want to reverse. Refuses safely if the work has moved again since, rather than yanking records out of wherever they now live.',
+    {
+      operation_id: z.string().describe('The operation_id from the move/split result you want to reverse.')
+    },
+    async ({ operation_id }) => {
+      const result = await client.post(
+        `/v1/sessions/organize/undo/${encodeURIComponent(operation_id)}`, {}
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
   // ─── create_project ────────────────────────────────────────
   server.tool(
     'create_project',

package/src/tools/review.js

@@ -297,7 +297,7 @@ function registerReviewTools(server, client) {
         canSwitchVersions: z.boolean().optional(),
         canSetStatus: z.boolean().optional(),
       }).optional(),
-      password: z.string().optional(),
+      password: z.string().optional().describe('Optional NEW password to set on this guest review link. This is not the user\'s Kolbo password and must never contain an account credential.'),
       allowed_emails: z.array(z.string()).optional(),
       expires_at: z.string().optional().describe('ISO8601 expiry datetime.'),
     },