@kolbo/mcp 1.79.7 → 1.81.0

package/src/tools/presets.js

@@ -12,55 +12,56 @@ function registerPresetTools(server, client, options = {}) {
   // ─── list_presets ──────────────────────────────────────────
   server.tool(
     'list_presets',
-    '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.',
+    'Resolve a generation preset and pass its exact id as preset_id. ALWAYS pass `search` when you already know the name (headless, bible, character sheet, a user preset) — that is a silent id lookup, not a catalog to show the user. Omit search only when they asked to browse. Custom instructions live on the preset, so prefer generate_image + preset_id over generate_character_sheet. Never invent an id.',
     {
-      type: z.string().optional().describe('Filter by catalog: "image" | "image_edit" | "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.'),
+      search: z.string().optional().describe('Name lookup, e.g. "headless", "bible", "character sheet". Required when resolving a named sheet/style — do not list the whole catalog.')
     },
-    async ({ type }) => {
+    async ({ type, search }) => {
       const params = new URLSearchParams();
       if (type) params.set('type', type);
+      if (search) params.set('search', search);
       const qs = params.toString();
       const result = await client.get(`/v1/presets${qs ? '?' + qs : ''}`);
 
-      const presets = result.presets || [];
-      // Full catalog measured 632,919 chars — the single biggest payload in the
-      // tool surface. The model only needs enough to pick a preset_id.
+      let presets = result.presets || [];
+      if (search && !result.search) {
+        const q = search.toLowerCase();
+        presets = presets.filter((p) => `${p.name || ''} ${p.description || ''} ${p.category || ''}`.toLowerCase().includes(q));
+      }
+      const lookup = Boolean(search);
+      // Full catalog measured 632,919 chars. A named lookup should return a handful of rows.
       const text = compactList(presets, {
         fields: ['id', 'name', 'category', 'type', 'description'],
-        cap: 60,
+        cap: lookup ? 8 : 12,
         total: result.count || presets.length,
-        extra: result.warning ? { warning: result.warning } : undefined,
-        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.',
+        extra: {
+          ...(result.warning ? { warning: result.warning } : {}),
+          ...(lookup ? { _lookup: true } : {}),
+        },
+        note: lookup
+          ? 'Pick the closest id and pass it as preset_id. Do not show this list to the user.'
+          : 'Pass search next time if you already know the name. Pass the chosen exact id as preset_id.',
       });
 
-      // Ship structuredContent UNCONDITIONALLY. Gating on ui() left every host that
-      // renders widgets without advertising MCP Apps (Kolbo Code) with text-only rows
-      // that carry no thumbnail field at all — and its BY_TOOL map still force-mounts
-      // the media grid on them, so the card rendered one broken-file glyph per cell.
-      // media.js and listResult() have always done it this way; these five lagged.
-      {
-        return uiResult(UI.mediaGrid, text, {
-          widget: 'media-grid',
-          title: 'Presets' + (type ? ' — ' + type : ''),
-          items: presets.slice(0, 24).map(p => ({
-            id: p.id,
-            title: p.name,
-            subtitle: p.category,
-            // API returns thumbnail_url / audio_url (see sdk listPresets) — NOT
-            // thumbnail / audio_preview_url. Reading the wrong key rendered every
-            // preset as a blank tile and dropped music previews entirely.
-            thumbnail: p.thumbnail_url || p.thumbnail,
-            media_type: p.audio_url ? 'audio' : 'image',
-            preview_audio: p.audio_url,
-            url: p.thumbnail_url || p.thumbnail,
-            use_hint: 'Use preset "{TITLE}" (preset_id: {ID}) for my next generation — ask me for the prompt.'
-          })),
-          total: result.count || presets.length,
-          has_more: presets.length > 24
-        });
-      }
+      if (lookup) return { content: [{ type: 'text', text }] };
 
-      return { content: [{ type: 'text', text }] };
+      return uiResult(UI.list, text, {
+        widget: 'list',
+        title: 'Presets' + (type ? ' — ' + type : ''),
+        items: presets.slice(0, 8).map(p => ({
+          id: p.id,
+          title: p.name,
+          subtitle: p.category,
+          thumbnail: p.thumbnail_url || p.thumbnail,
+          media_type: p.audio_url ? 'audio' : 'image',
+          preview_audio: p.audio_url,
+          url: p.thumbnail_url || p.thumbnail,
+          use_hint: 'Use preset "{TITLE}" (preset_id: {ID}) for my next generation — ask me for the prompt.'
+        })),
+        total: result.count || presets.length,
+        has_more: presets.length > 8
+      });
     }
   );
 

package/src/tools/projects.js

@@ -29,6 +29,7 @@ function registerProjectTools(server, client) {
       const projects = (result.projects || []).map(p => ({
         id: p.id,
         name: p.name,
+        description: p.description || null,
         role: p.role,
         is_default: !!p.is_default,
         is_archived: !!p.is_archived,
@@ -48,7 +49,7 @@ function registerProjectTools(server, client) {
         items: projects.map(p => ({
           id: p.id,
           title: p.name,
-          subtitle: p.role + (p.is_default ? ' · default' : '') + (p.is_archived ? ' · archived' : ''),
+          subtitle: (p.description || p.role) + (p.is_default ? ' · default' : '') + (p.is_archived ? ' · archived' : ''),
           thumbnail: p.thumbnail_url,
           open_url: p.open_url,
           use_hint: 'Use my "{TITLE}" project (project_id: {ID}) for what I do next.'
@@ -240,14 +241,27 @@ function registerProjectTools(server, client) {
     }
   );
 
+  // ─── get_project ───────────────────────────────────────────
+  server.tool(
+    'get_project',
+    'Fetch one project by id including its FULL description (list_projects clips descriptions to ~400 chars). Call this before `update_project` when you need to edit the brief, logline, or notes — read, apply the user\'s edits, send the complete description back.',
+    {
+      project_id: z.string().describe('Project ObjectId from list_projects.')
+    },
+    async ({ project_id }) => {
+      const result = await client.get(`/v1/projects/${encodeURIComponent(project_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result.project || result, null, 2) }] };
+    }
+  );
+
   // ─── update_project ────────────────────────────────────────
   server.tool(
     'update_project',
-    'Rename a project and/or update its description. Changing the description also refreshes the project\'s AI profile in the background.',
+    'Rename a project and/or replace its description. NEVER delete a project or create a new one just to change the brief — this edits in place. Description REPLACES the whole text: call `get_project` first, apply the user\'s edits, send the complete result. Changing the description also refreshes the project\'s AI profile in the background.',
     {
-      project_id: z.string().describe('Project ObjectId (from list_projects).'),
+      project_id: z.string().describe('Project ObjectId (from list_projects / get_project).'),
       name: z.string().optional().describe('New name.'),
-      description: z.string().optional().describe('New description (replaces the old one).')
+      description: z.string().optional().describe('New description (replaces the old one; max 10k chars, markdown OK).')
     },
     async ({ project_id, name, description }) => {
       const body = {};
@@ -331,7 +345,7 @@ function registerProjectTools(server, client) {
 
   server.tool(
     'rename_session',
-    'Rename a session the user can see in the Kolbo sidebar. Use after `list_sessions` when they say "call this Hero Sequence" or leftover API daily names should become human titles. Does not move the session or its media.',
+    'Rename a session the user can see in the Kolbo sidebar. Use this to edit a session title in place — never delete and recreate a session just to change its name. Call this immediately after the first generate of a plan bucket so the title matches the production plan (`Cast`, `Locations`, `Scene 03 — rooftop chase`) instead of an API daily name. Also use when the user says "call this Hero Sequence". Does not move the session or its media.',
     {
       session_id: z.string().describe('Session ObjectId from `list_sessions` or a generate_* result.'),
       name: z.string().describe('New sidebar title (1–200 characters).'),
@@ -443,6 +457,135 @@ function registerProjectTools(server, client) {
     }
   );
 
+  server.tool(
+    'list_project_assets',
+    'List the Visual DNAs and moodboards tagged onto a project\'s CAST roster — the @Name / #Name assets this project actually uses. Each DNA row includes its stored description plus a project-scoped `note` ("what this asset is for here"). Call this before editing the cast, writing DNA descriptions, or generating against a named project. Does not list the user\'s whole library — only what is tagged on THIS project.',
+    { project_id: z.string().describe('Project ObjectId from list_projects.') },
+    async ({ project_id }) => {
+      const result = await client.get(`/v1/projects/${encodeURIComponent(project_id)}/assets`);
+      const dnas = result.visual_dnas || [];
+      const moodboards = result.moodboards || [];
+      const text = JSON.stringify({
+        visual_dnas: dnas,
+        moodboards,
+        _hint: 'Edit a DNA\'s identity description with update_project_asset (description) or update_visual_dna. The `note` is project-scoped purpose (update_project_asset note). Link missing assets with link_project_asset — do not delete+recreate.'
+      }, null, 2);
+      return listResult(text, {
+        widget: 'list',
+        title: 'Project cast',
+        items: [
+          ...dnas.map((d) => ({
+            id: d.id,
+            title: '@' + (d.name || d.id),
+            subtitle: [d.dna_type, d.note || d.description].filter(Boolean).join(' · ')
+          })),
+          ...moodboards.map((m) => ({
+            id: m.id,
+            title: '#' + (m.name || m.id),
+            subtitle: ['moodboard', m.note || m.summary].filter(Boolean).join(' · ')
+          }))
+        ],
+        total: dnas.length + moodboards.length
+      });
+    }
+  );
+
+  server.tool(
+    'link_project_asset',
+    'Tag an existing Visual DNA or moodboard onto a project\'s cast roster so it shows up as @Name / #Name for this project (and in the AI cast list). Does NOT copy or recreate the asset. After linking a DNA, write its description with update_project_asset. Optional `note` is the project-scoped purpose ("hero, dark-bg logo").',
+    {
+      project_id: z.string().describe('Project ObjectId.'),
+      asset_type: z.enum(['visual_dna', 'moodboard']).describe('Kind of asset to tag.'),
+      asset_id: z.string().describe('Visual DNA id or moodboard id (from list_visual_dnas / list_moodboards).'),
+      note: z.string().optional().describe('Optional project-scoped purpose note (max 1000 chars).')
+    },
+    async ({ project_id, asset_type, asset_id, note }) => {
+      const result = await client.post(`/v1/projects/${encodeURIComponent(project_id)}/assets/link`, {
+        asset_type,
+        asset_id
+      });
+      let savedNote = null;
+      if (note !== undefined) {
+        const n = await client.put(
+          `/v1/projects/${encodeURIComponent(project_id)}/assets/${encodeURIComponent(asset_type)}/${encodeURIComponent(asset_id)}/note`,
+          { note }
+        );
+        savedNote = n.note;
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            asset: result.asset,
+            note: savedNote,
+            _hint: asset_type === 'visual_dna'
+              ? 'DNA is on the cast. Write its identity description with update_project_asset (description) — do not delete and recreate.'
+              : 'Moodboard is on the cast. Set a purpose note with update_project_asset if needed.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  server.tool(
+    'unlink_project_asset',
+    'Remove a Visual DNA or moodboard from a project\'s cast roster. The asset itself stays in the user\'s library — this only untags it from the project. Do NOT use this to edit a description; that is update_project_asset / update_visual_dna.',
+    {
+      project_id: z.string().describe('Project ObjectId.'),
+      asset_type: z.enum(['visual_dna', 'moodboard']).describe('Kind of asset to untag.'),
+      asset_id: z.string().describe('Asset id from list_project_assets.')
+    },
+    async ({ project_id, asset_type, asset_id }) => {
+      const result = await client.delete(
+        `/v1/projects/${encodeURIComponent(project_id)}/assets/${encodeURIComponent(asset_type)}/${encodeURIComponent(asset_id)}`
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'update_project_asset',
+    'Edit a tagged project-cast asset in place. `description` writes the Visual DNA\'s identity text (the thing @Name injects — same as update_visual_dna prompt_helper). `note` is the project-scoped purpose ("what this asset is for HERE", fed into the AI cast roster). Pass either or both. NEVER unlink+relink or delete+recreate a DNA to change its description. Moodboards: `note` only here; use update_moodboard for style/images.',
+    {
+      project_id: z.string().describe('Project ObjectId.'),
+      asset_type: z.enum(['visual_dna', 'moodboard']).describe('Kind of tagged asset.'),
+      asset_id: z.string().describe('Asset id from list_project_assets.'),
+      description: z.string().optional().describe('For visual_dna: new identity description (replaces prompt_helper on the DNA itself). Ignored for moodboards.'),
+      note: z.string().optional().describe('Project-scoped purpose note (max 1000 chars). Pass "" to clear.')
+    },
+    async ({ project_id, asset_type, asset_id, description, note }) => {
+      if (description === undefined && note === undefined) {
+        throw new Error('Provide description and/or note');
+      }
+      const out = {};
+      if (note !== undefined) {
+        const n = await client.put(
+          `/v1/projects/${encodeURIComponent(project_id)}/assets/${encodeURIComponent(asset_type)}/${encodeURIComponent(asset_id)}/note`,
+          { note }
+        );
+        out.note = n.note;
+      }
+      if (description !== undefined) {
+        if (asset_type !== 'visual_dna') {
+          throw new Error('description is only valid for asset_type=visual_dna — use update_moodboard for moodboard style notes');
+        }
+        const dna = await client.put(`/v1/visual-dna/${encodeURIComponent(asset_id)}`, {
+          prompt_helper: description
+        });
+        out.visual_dna = dna.visual_dna || dna;
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            ...out,
+            _hint: 'Cast asset updated in place. Keep using the same id and @Name.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
   server.tool(
     'regenerate_project_profile',
     'Force-regenerate a project\'s AI profile from its current context sources (also clears any manual-edit lock). Use after adding several new sources when the user wants the brief refreshed now.',

package/src/tools/visual_dna.js

@@ -23,12 +23,12 @@ function registerVisualDnaTools(server, client, options = {}) {
   // ─── create_visual_dna ─────────────────────────────────────
   server.tool(
     'create_visual_dna',
-    'Create a Visual DNA profile from reference media. Each item in images/video/audio can be a public URL or an absolute local file path. Max 4 images, 1 video, 1 audio. Files capped at 25MB each. For EVERY DNA type, a reference sheet dramatically improves consistency (character turnaround / product details / location angles / style board) — offer to generate one with `generate_character_sheet` (matching `sheet_type`) first, then pass its URL as `character_sheet_url` here (see that tool).',
+    'Create a Visual DNA profile from reference media. Each item in images/video/audio can be a public URL or an absolute local file path. Max 4 images, 1 video, 1 audio. Files capped at 25MB each. Those stills are ALL packed into later generations (every image slot the model has, or a white grid if only one leftover slot remains) — so they must share one identity and one vibe. Character DNA: only that person (anonymous crowd OK, no second hero). Environment/location DNA: the place only — empty or anonymous crowd, NEVER a main character or recognizable hero face. Product: only that product. Style: one art direction. Separate states (day/night, clean/bloody) = separate DNAs. For EVERY DNA type, a reference sheet dramatically improves consistency (character turnaround / product details / location angles / style board) — offer to generate one with `generate_character_sheet` (matching `sheet_type`) first, then pass its URL as `character_sheet_url` here (see that tool).',
     {
       name: z.string().describe('Name of the Visual DNA profile. **Pick a short, lowercase, no-space single token** (e.g. `maya`, `tokyo_neon`, `brand_red`, `esther_model`) — never names with spaces (`Sarah Johnson` ❌). The user/LLM types this as `@<name>` inside generation prompts, and the @ parser stops at the first space, so `@Sarah Johnson` matches only `Sarah` and the binding silently drops. Multi-word concepts should use underscores or be a single token. Names are case-insensitive on lookup, but **reserved** values rejected on creation: `Image1`, `Image2`, …, `Video1`, …, `Audio1`, … (any-language characters allowed; max 100 chars).'),
       dna_type: z.string().optional().describe('Type: "character", "style", "product", "scene", "environment". Default: "character"'),
       prompt_helper: z.string().optional().describe('Optional description/notes to guide DNA extraction'),
-      images: z.array(z.string()).optional().describe('Array of image sources (URLs or absolute local paths). Max 4.'),
+      images: z.array(z.string()).optional().describe('Array of image sources (URLs or absolute local paths). Max 4. All of them can reach the model on later gens — same subject, same vibe only; no extra heroes on character DNAs, no main characters on environment DNAs.'),
       video: z.string().optional().describe('Optional video source (URL or absolute local path)'),
       audio: z.string().optional().describe('Optional audio source (URL or absolute local path) — the character\'s voice, 5-30s of clean speech. Stored on the DNA and used two ways: (1) as REFERENCE AUDIO in video generation — attaching this DNA to an image-to-video generation on a model with audio slots (Seedance 2.x, Wan 3.0) auto-attaches the clip and tells the model it is that character\'s voice; (2) as the source for a real speaking voice, but ONLY when you ask for one — see `voice_source`.'),
       voice_source: z.enum(['none', 'clone', 'assign', 'design']).optional().describe('What to do about a SPEAKING voice. **Pass "none" when the audio is just a reference clip** (the usual case for video work) — the clip is stored and usable as video reference audio, and nothing else happens. "clone" mints an ElevenLabs voice from the uploaded audio, which consumes a voice slot and may EVICT another of the user\'s voices to free one; it also makes the DNA addressable as `dna_<id>` in text-to-speech. "assign" points at an existing voice (pass `assigned_voice_id`). "design" generates a voice from the character\'s look. ⚠️ Omitting this while passing `audio` keeps the legacy behaviour and CLONES — pass "none" explicitly unless the user asked for a voice.'),
@@ -153,7 +153,8 @@ function registerVisualDnaTools(server, client, options = {}) {
           id: d.id,
           title: d.name,
           subtitle: (d.dna_type || '') + (Array.isArray(d.tags) && d.tags.length ? ' · ' + d.tags.slice(0, 3).join(', ') : ''),
-          thumbnail: d.thumbnail_url || d.thumbnail,
+          thumbnail: d.sheet_url || d.thumbnail_url || d.thumbnail,
+          url: d.sheet_url || d.thumbnail_url || d.thumbnail,
           media_type: 'image',
           use_hint: 'Use Visual DNA "{TITLE}" (id: {ID}) in my next generation for character/style consistency.'
         })),
@@ -183,10 +184,119 @@ function registerVisualDnaTools(server, client, options = {}) {
     }
   );
 
+  // ─── update_visual_dna ─────────────────────────────────────
+  server.tool(
+    'update_visual_dna',
+    'Edit an existing Visual DNA in place — name, description, type, character sheet, stills, video, audio, or character attributes. NEVER delete and recreate a DNA to change any of those: the old id is what generations, sessions, and @Name bindings already point at. Providing `images` REPLACES the whole still set (max 4) and re-analyzes the profile. Omit images to keep current stills. Owner only; global presets cannot be edited (import first).',
+    {
+      visual_dna_id: z.string().describe('Visual DNA id from list_visual_dnas / create_visual_dna.'),
+      name: z.string().optional().describe('New name. Same no-space single-token rule as create_visual_dna — @Name binding stops at the first space.'),
+      dna_type: z.string().optional().describe('Type: "character", "style", "product", "scene", "environment". Changing type re-analyzes the profile.'),
+      prompt_helper: z.string().optional().describe('New description / intent notes. Replaces the old ones and re-synthesizes the DNA analysis when the text actually changes. Pass "" to clear.'),
+      images: z.array(z.string()).optional().describe('Full replacement still set (URLs or absolute local paths). Max 4. Omit to keep current stills. Same purity rules as create: one identity, one vibe.'),
+      video: z.string().optional().describe('Replacement video source (URL or absolute local path).'),
+      audio: z.string().optional().describe('Replacement audio source (URL or absolute local path).'),
+      character_sheet_url: z.string().optional().describe('New reference sheet URL (from generate_character_sheet). Sets the DNA\'s primary sheet without replacing stills.'),
+      remove_character_sheet: z.boolean().optional().describe('If true, clears the stored character sheet. Do not combine with character_sheet_url.'),
+      gender: z.string().optional().describe('Character attribute (character DNAs).'),
+      ethnicity: z.string().optional().describe('Character attribute (character DNAs).'),
+      body_type: z.string().optional().describe('Character attribute (character DNAs).'),
+      hair_color: z.string().optional().describe('Character attribute (character DNAs).'),
+      eye_color: z.string().optional().describe('Character attribute (character DNAs).'),
+      skin_tone: z.string().optional().describe('Character attribute (character DNAs).'),
+      age_range: z.string().optional().describe('Character attribute (character DNAs).'),
+      specific_age: z.number().optional().describe('Character attribute (character DNAs).')
+    },
+    async ({
+      visual_dna_id, name, dna_type, prompt_helper, images, video, audio,
+      character_sheet_url, remove_character_sheet,
+      gender, ethnicity, body_type, hair_color, eye_color, skin_tone, age_range, specific_age
+    }) => {
+      const imageList = Array.isArray(images) ? images.filter(Boolean) : [];
+      if (imageList.length > 4) throw new Error('Maximum 4 images allowed');
+      const hasMedia = imageList.length > 0 || !!video || !!audio;
+      const hasMeta = name !== undefined || dna_type !== undefined || prompt_helper !== undefined
+        || character_sheet_url !== undefined || remove_character_sheet !== undefined
+        || gender !== undefined || ethnicity !== undefined || body_type !== undefined
+        || hair_color !== undefined || eye_color !== undefined || skin_tone !== undefined
+        || age_range !== undefined || specific_age !== undefined;
+      if (!hasMedia && !hasMeta) {
+        throw new Error('Provide at least one field to update');
+      }
+
+      const attrs = {
+        ...(gender !== undefined ? { gender } : {}),
+        ...(ethnicity !== undefined ? { ethnicity } : {}),
+        ...(body_type !== undefined ? { body_type } : {}),
+        ...(hair_color !== undefined ? { hair_color } : {}),
+        ...(eye_color !== undefined ? { eye_color } : {}),
+        ...(skin_tone !== undefined ? { skin_tone } : {}),
+        ...(age_range !== undefined ? { age_range } : {}),
+        ...(specific_age !== undefined ? { specific_age } : {})
+      };
+      const path = `/v1/visual-dna/${encodeURIComponent(visual_dna_id)}`;
+
+      if (!hasMedia) {
+        const body = { ...attrs };
+        if (name !== undefined) body.name = name;
+        if (dna_type !== undefined) body.dna_type = dna_type;
+        if (prompt_helper !== undefined) body.prompt_helper = prompt_helper;
+        if (character_sheet_url !== undefined) body.character_sheet_url = character_sheet_url;
+        if (remove_character_sheet !== undefined) body.remove_character_sheet = remove_character_sheet;
+        const result = await client.put(path, body);
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              visual_dna: result.visual_dna || result,
+              _hint: 'DNA updated in place — keep using this same id and the new stored name in @tags.'
+            }, null, 2)
+          }]
+        };
+      }
+
+      const [imageFiles, videoFile, audioFile] = await Promise.all([
+        Promise.all(imageList.map(src => resolveToBuffer(src, 'image'))),
+        video ? resolveToBuffer(video, 'video') : Promise.resolve(null),
+        audio ? resolveToBuffer(audio, 'audio') : Promise.resolve(null)
+      ]);
+
+      const form = new FormData();
+      if (name !== undefined) form.append('name', name);
+      if (dna_type) form.append('dnaType', dna_type);
+      if (prompt_helper !== undefined) form.append('promptHelper', prompt_helper);
+      if (character_sheet_url) form.append('characterSheetUrl', character_sheet_url);
+      if (remove_character_sheet !== undefined) {
+        form.append('removeCharacterSheet', remove_character_sheet ? 'true' : 'false');
+      }
+      for (const [k, v] of Object.entries(attrs)) form.append(k, String(v));
+      for (const f of imageFiles) {
+        form.append('images', f.buffer, { filename: f.filename, contentType: f.contentType });
+      }
+      if (videoFile) {
+        form.append('videos', videoFile.buffer, { filename: videoFile.filename, contentType: videoFile.contentType });
+      }
+      if (audioFile) {
+        form.append('audio', audioFile.buffer, { filename: audioFile.filename, contentType: audioFile.contentType });
+      }
+
+      const result = await client.putMultipart(path, form);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            visual_dna: result.visual_dna || result,
+            _hint: 'DNA updated in place — keep using this same id and the new stored name in @tags.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
   // ─── delete_visual_dna ─────────────────────────────────────
   server.tool(
     'delete_visual_dna',
-    'Delete a Visual DNA profile by ID. Only the owner can delete.',
+    'Permanently delete a Visual DNA profile. Only the owner can delete. Do NOT use this to rename, restyle, swap stills, or change a description — that is `update_visual_dna`. Confirm with the user before deleting a DNA they did not just create.',
     {
       visual_dna_id: z.string().describe('The Visual DNA profile ID to delete')
     },
@@ -207,18 +317,25 @@ function registerVisualDnaTools(server, client, options = {}) {
   // ─── generate_character_sheet ──────────────────────────────
   server.tool(
     'generate_character_sheet',
-    'STANDARD FIRST STEP OF THE ASSET PASS for any film/ad/scene: inventory the characters, locations and props the script needs, generate a sheet for each, create its Visual DNA from that sheet, confirm the whole set with the user, and only THEN generate video. Sheets for cinematic environments and invented characters run well on `mirage-film-2` (3cr); use `nano-banana-2` (10cr) or `gpt-image-2` (12cr) when reference fidelity or legible text matters. Generate a reference sheet for a Visual DNA from 1+ reference image URLs — the same step the in-app Visual DNA wizard offers, for EVERY DNA type via `sheet_type`: character = multi-angle turnaround, product = angles + branding/material/construction close-ups, environment = location angles + one signature detail, style = a style board (the same look applied to six varied subjects). The sheet is the single strongest consistency booster for a DNA, and it always preserves the reference\'s original art style (2D stays 2D, photo stays photo). CHARGES CREDITS, so when the user is about to create a DNA, OFFER this first ("want me to generate a reference sheet for stronger consistency? it costs a few credits") and only run it on a yes. Returns `character_sheet_url` — pass it as `character_sheet_url` to `create_visual_dna` with the matching `dna_type`.',
+    'STANDARD FIRST STEP OF THE ASSET PASS for any film/ad/scene: inventory the characters, locations and props the script needs, generate a sheet for each, create its Visual DNA from that sheet, confirm the whole set with the user, and only THEN generate video. Sheets for cinematic environments and invented characters run well on `mirage-film-2` (3cr); use `nano-banana-2` (10cr) or `gpt-image-2` (12cr) when reference fidelity or legible text matters. Generate a reference sheet for a Visual DNA from 1+ reference image URLs — the same step the in-app Visual DNA wizard offers, for EVERY DNA type via `sheet_type`: character = multi-angle turnaround, product = angles + branding/material/construction close-ups, environment = location angles + one signature detail (NO main character / recognizable hero face in an environment sheet — anonymous crowd is OK; those stills are packed into every later gen), style = a style board (the same look applied to six varied subjects). Keep every source image the same identity and vibe. The sheet is the single strongest consistency booster for a DNA, and it always preserves the reference\'s original art style (2D stays 2D, photo stays photo). CHARGES CREDITS, so when the user is about to create a DNA, OFFER this first ("want me to generate a reference sheet for stronger consistency? it costs a few credits") and only run it on a yes. Returns `character_sheet_url` — pass it as `character_sheet_url` to `create_visual_dna` with the matching `dna_type`.',
     {
       image_urls: z.array(z.string()).min(1).describe('Reference image URLs of the subject (for characters: front/side/varied angles work best). Use generated-image URLs or upload_media output.'),
-      sheet_type: z.enum(['character', 'character_headless', 'character_bible', 'product', 'environment', 'style']).optional().describe('Sheet layout. character = front/back/face turnaround. character_headless = wardrobe/body refs with a headless front panel (use when clothing must change without fighting the face sheet). character_bible = denser production model-sheet (turnaround + faces + wardrobe + color swatches). product / environment / style = matching DNA types. Defaults to character.')
+      sheet_type: z.enum(['character', 'character_headless', 'character_bible', 'product', 'environment', 'style']).optional().describe('Sheet layout. character = front/back/face turnaround. character_headless = wardrobe/body refs with a headless front panel (use when clothing must change without fighting the face sheet). character_bible = denser production model-sheet (turnaround + faces + wardrobe + color swatches). product / environment / style = matching DNA types. Defaults to character. This IS the Character Sheet / Headless / Bible preset — do not call list_presets for those names.'),
+      model: z.string().optional().describe('Image model for the sheet. Default nano-banana-2. Pass gpt-image-2 when the user names it.'),
+      resolution: z.enum(['2K', '4K']).optional().describe('Sheet resolution. 2K or 4K only — never 1K. Default 2K. Use 4K for character_bible, high-detail leads, or when the user asks.')
     },
-    async ({ image_urls, sheet_type }) => {
+    async ({ image_urls, sheet_type, model, resolution }) => {
       // The endpoint is blocking and a 2K multi-panel sheet routinely runs past the
       // 120s default: the MCP aborted while kolbo-api kept going, finished, and
       // billed — the user saw "Failed" for a sheet they had already paid for.
       const result = await client.post(
         '/v1/visual-dna/character-sheet',
-        { image_urls, ...(sheet_type ? { sheet_type } : {}) },
+        {
+          image_urls,
+          ...(sheet_type ? { sheet_type } : {}),
+          ...(model ? { model } : {}),
+          ...(resolution ? { resolution } : {}),
+        },
         { timeoutMs: CHARACTER_SHEET_TIMEOUT_MS },
       );
       // `urls` is NOT redundant with character_sheet_url. Every generation-card
@@ -241,7 +358,7 @@ function registerVisualDnaTools(server, client, options = {}) {
             phase: 'completed',
             kind: 'image',
             credits_used: result.credits_used,
-            _hint: 'Show the sheet to the user, then pass character_sheet_url to create_visual_dna as that DNA\'s reference.'
+            _hint: 'Show the sheet to the user, then pass character_sheet_url to create_visual_dna (new DNA) or update_visual_dna (existing DNA). Never delete and recreate.'
           }, null, 2)
         }]
       };