@kolbo/mcp 1.80.0 → 1.81.0

package/README.md

@@ -153,6 +153,7 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | Tool | Description |
 |------|-------------|
 | `create_visual_dna` | Create a profile from URLs or local files |
+| `update_visual_dna` | Edit name, description, stills, sheet, or type in place (never delete+recreate) |
 | `list_visual_dnas` | List your profiles |
 | `get_visual_dna` | Fetch one profile |
 | `delete_visual_dna` | Delete a profile |
@@ -162,6 +163,7 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 |------|-------------|
 | `list_moodboards` | Browse presets + your moodboards |
 | `get_moodboard` | Fetch one moodboard with all image URLs |
+| `create_moodboard` / `update_moodboard` / `delete_moodboard` | Create / edit in place / delete |
 
 **Color DNA** — sticky, account-wide: the ACTIVE palette strict-grades every generation until deactivated. Opt a single generation out with `skip_color_palette`.
 | Tool | Description |
@@ -238,7 +240,8 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `list_voices` | TTS voices (presets + cloned) |
 | `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 |
+| `list_projects` | List owned + shared projects (id, name, description, role, is_default) — call first to resolve a project name into the `project_id` you pass to generation tools |
+| `get_project` | Full project record including the unclipped description — read this before `update_project` |
 | `move_session` | Move ONE session (generation, chat, transcription…) and ALL its generations + media to another project |
 | `bulk_move_sessions` | Move up to 100 sessions into one project in a single call — mixed types allowed, per-session failures reported |
 | `list_session_generations` | A session's generations as complete groups (prompt + all its outputs) — the ids the two organize tools below take |
@@ -246,7 +249,7 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `split_session` | Carve selected generations out into a brand-new named session, atomically |
 | `undo_session_organization` | Reverse a move/split within 15 minutes, using the `operation_id` it returned |
 | `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 |
-| `generate_character_sheet` | Generate a multi-angle character sheet from reference images (credits) → pass URL to create_visual_dna for stronger character consistency |
+| `generate_character_sheet` | Generate a multi-angle character sheet from reference images (credits) → pass URL to create_visual_dna or update_visual_dna |
 | `list_visual_dna_folders` / `create_visual_dna_folder` / `update_visual_dna_folder` / `delete_visual_dna_folder` / `move_visual_dna_to_folder` | Organize Visual DNA characters into user folders (create/rename/recolor/delete + move DNAs in/out) |
 | `create_project` / `update_project` / `archive_project` / `unarchive_project` | Project lifecycle (create/rename/describe/archive; deletion stays in-app) |
 | `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Custom chat agents (reusable named personas; `description` is the system instruction) |
@@ -254,6 +257,7 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `list_sessions` | Enumerate sessions across all types, filterable by project, `type`, and `types[]` |
 | `rename_session` / `delete_session` / `restore_session` | Rename a session; soft-delete leftovers after a move; restore from trash |
 | `add_project_context` / `list_project_context` / `delete_project_context` / `get_project_profile` / `regenerate_project_profile` | Project knowledge base (RAG): feed scripts/URLs/notes, read the synthesized living brief |
+| `list_project_assets` / `link_project_asset` / `unlink_project_asset` / `update_project_asset` | Project cast: tag Visual DNAs / moodboards onto a project, write each DNA's description and purpose note |
 | `create_moodboard` / `update_moodboard` / `delete_moodboard` | Build/edit moodboards from image URLs (AI style analysis → master prompt) |
 | `clone_voice` / `import_elevenlabs_voice` / `delete_voice` | Custom voices: clone from an audio sample, import by ElevenLabs ID, delete |
 | `trim_video` | Frame-accurate server-side trim of a Kolbo-hosted video (async job, tool waits) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.80.0",
+  "version": "1.81.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,6 +1,6 @@
 # AUTO-GENERATED — do not edit
 
-This tree is mirrored from kolbo-code@b39d555, the single source of truth.
+This tree is mirrored from kolbo-code@fccda44, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/src/client.js

@@ -451,17 +451,25 @@ class KolboClient {
   // poll loop, which does its own capped backoff in polling.js) still surfaces
   // the 429 straight to the caller, now with the wait spelled out in the message.
   async postMultipart(reqPath, formData) {
+    return this._multipart('POST', reqPath, formData);
+  }
+
+  async putMultipart(reqPath, formData) {
+    return this._multipart('PUT', reqPath, formData);
+  }
+
+  async _multipart(method, reqPath, formData) {
     if (!this.apiKey) await this._ensureLogin();
     return retryOnce429(async () => {
-      const result = await this._doMultipart(reqPath, formData);
+      const result = await this._doMultipart(method, reqPath, formData);
       if (result._status === 401 && this._tryRefreshKey()) {
-        return this._doMultipart(reqPath, formData);
+        return this._doMultipart(method, reqPath, formData);
       }
       return result;
     });
   }
 
-  async _doMultipart(reqPath, formData) {
+  async _doMultipart(method, reqPath, formData) {
     const url = `${this.baseUrl}${reqPath}`;
     const headers = {
       'X-API-Key': this.apiKey,
@@ -484,7 +492,7 @@ class KolboClient {
     let response;
     try {
       response = await fetch(url, {
-        method: 'POST',
+        method,
         headers,
         body,
         signal: composed.signal
@@ -493,12 +501,12 @@ class KolboClient {
       if (isAbortError(err)) {
         if (callerSignal?.aborted) {
           throw new KolboApiError(
-            `Upload cancelled by caller: POST ${reqPath}`,
+            `Upload cancelled by caller: ${method} ${reqPath}`,
             { code: 'REQUEST_CANCELLED', status: 499 }
           );
         }
         throw new KolboApiError(
-          `Upload timed out after ${UPLOAD_TIMEOUT_MS / 1000}s: POST ${reqPath} ` +
+          `Upload timed out after ${UPLOAD_TIMEOUT_MS / 1000}s: ${method} ${reqPath} ` +
           `(${Math.round(body.length / 1024)}KB). Raise KOLBO_UPLOAD_TIMEOUT_MS for slow links.`,
           { code: 'UPLOAD_TIMEOUT', status: 504 }
         );

package/src/toolAnnotations.js

@@ -17,7 +17,8 @@ const READ_ONLY = [
   '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_projects', 'get_project', 'list_sessions', 'list_project_context', 'get_project_profile',
+  'list_project_assets',
   'list_session_generations',
   'list_agents', 'list_docs', 'get_doc',
   'get_review_storage_usage', 'list_review_assets', 'get_review_asset',
@@ -47,6 +48,7 @@ const PRIVATE_WRITE = [
   'rename_session', 'restore_session',
   'create_project', 'update_project',
   'archive_project', 'unarchive_project', 'add_project_context',
+  'link_project_asset', 'unlink_project_asset',
   'create_agent',
   'create_doc',
   'create_review_asset', 'update_review_asset', 'add_review_version',
@@ -69,7 +71,7 @@ const DESTRUCTIVE_WRITE = [
   'separate_audio_stems', 'clean_dialogue_leftovers', 'separate_ambience',
 
   // Deletes and whole-value replacement updates are conservatively destructive.
-  'delete_voice', 'delete_visual_dna', 'delete_visual_dna_folder',
+  'delete_voice', 'update_visual_dna', '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',
@@ -77,6 +79,7 @@ const DESTRUCTIVE_WRITE = [
   'unshare_media_folder',
   'delete_session',
   'delete_project_context', 'regenerate_project_profile',
+  'update_project_asset',
   'update_agent', 'delete_agent', 'update_doc', 'delete_doc',
   'delete_review_asset', 'delete_review_collection',
   'edit_review_comment', 'delete_review_comment',

package/src/tools/_shared.js

@@ -53,8 +53,8 @@ const FILE_INPUT_TOOLS = [
   'generate_video', 'generate_video_from_image', 'generate_video_from_video',
   'generate_elements', 'generate_first_last_frame', 'generate_lipsync',
   'generate_3d', 'edit_image', 'edit_video', 'transcribe_audio',
-  'create_visual_dna', 'generate_character_sheet', 'clone_voice',
-  'chat_send_message', 'create_moodboard',
+  'create_visual_dna', 'update_visual_dna', 'generate_character_sheet', 'clone_voice',
+  'chat_send_message', 'create_moodboard', 'update_moodboard',
   'separate_audio_stems', 'clean_dialogue_leftovers', 'separate_ambience'
 ];
 

package/src/tools/agents.js

@@ -59,7 +59,7 @@ function registerAgentTools(server, client) {
   // ─── update_agent ──────────────────────────────────────────
   server.tool(
     'update_agent',
-    'Update a custom chat agent\'s name, description (persona/instructions), or emoji/thumbnail. Only personal agents you own can be edited — global preset agents are protected. Resolve the agent id with list_agents first.',
+    'Edit a custom chat agent in place: name, description (persona/instructions), or emoji/thumbnail. NEVER delete and recreate an agent to change its persona — conversations already reference this agent_id. Only personal agents you own can be edited — global preset agents are protected. Resolve the agent id with list_agents first.',
     {
       agent_id: z.string().describe('Agent id (from list_agents).'),
       name: z.string().optional().describe('New name.'),

package/src/tools/docs.js

@@ -84,7 +84,7 @@ function registerDocTools(server, client) {
   // ─── 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.',
+    'Edit an AI Doc in place: title and/or content. NEVER delete and recreate a doc to change its text — existing share links and the sidebar entry stay on this id. 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.'),

package/src/tools/moodboards.js

@@ -93,7 +93,7 @@ function registerMoodboardTools(server, client, options = {}) {
   // ─── update_moodboard ──────────────────────────────────────
   server.tool(
     'update_moodboard',
-    'Update a moodboard\'s name, style guide, and/or images. Providing `image_urls` REPLACES the whole image set and re-analyzes the style (master prompt regenerates). Owner only.',
+    'Edit a moodboard in place: name, style guide, and/or images. NEVER delete and recreate a board to rename it or swap stills — existing generations already reference this id as moodboard_id / #Name. Providing `image_urls` REPLACES the whole image set and re-analyzes the style (master prompt regenerates). Owner only.',
     {
       moodboard_id: z.string().describe('Moodboard id (from list_moodboards).'),
       name: z.string().optional().describe('New name.'),
@@ -113,7 +113,7 @@ function registerMoodboardTools(server, client, options = {}) {
   // ─── delete_moodboard ──────────────────────────────────────
   server.tool(
     'delete_moodboard',
-    'Permanently delete a moodboard (owner only; system presets cannot be deleted). The underlying image files stay in storage — only the board is removed. Confirm with the user before deleting boards they did not just create.',
+    'Permanently delete a moodboard (owner only; system presets cannot be deleted). Do NOT use this to rename or change images — that is `update_moodboard`. The underlying image files stay in storage — only the board is removed. Confirm with the user before deleting boards they did not just create.',
     { moodboard_id: z.string().describe('Moodboard id to delete.') },
     async ({ moodboard_id }) => {
       const result = await client.delete(`/v1/moodboards/${encodeURIComponent(moodboard_id)}`);

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.'),
@@ -184,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')
     },
@@ -208,7 +317,7 @@ 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. This IS the Character Sheet / Headless / Bible preset — do not call list_presets for those names.'),
@@ -249,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)
         }]
       };