@naumu/mcp 0.9.0 → 0.11.0

package/README.md

@@ -51,6 +51,7 @@ Add to your Cursor MCP settings:
 | `naumu_add_edge` | Create a relationship between two nodes |
 | `naumu_remove_node` | Delete a node and its connections |
 | `naumu_remove_edge` | Delete a relationship |
+| `naumu_create_topic` | Create a topic (filing destination) in a space; admin-only, name must be a lowercase slug, returns an `id` for `topicIds` params |
 | `naumu_ask` | Ask @Naumu a question and get a synthesised answer back (answer + sources + confidence + threadId + status); leaves a visible thread in the space |
 | `naumu_delegate` | Hand @Naumu a task to carry out asynchronously (add knowledge, make changes); returns a `threadId` immediately, then poll with `naumu_read_thread` |
 | `naumu_read_thread` | Read a thread's messages; each message carries a `status` of `processing` or `complete` |

package/dist/index.js

@@ -133,6 +133,9 @@ URL \u2192 tool mapping (the value after /spaces/ is the slug \u2014 resolve it
 
 Localhost URLs (http://localhost:3000/spaces/{slug}/...) follow the same shape \u2014 resolve the slug the same way. The MCP backend host is configured separately; the URL the user pastes is just for parsing structure.`;
 
+// ../mcp-core/src/version.ts
+var NAUMU_MCP_VERSION = "0.11.0";
+
 // ../mcp-core/src/tools/list-graphs.ts
 import { z } from "zod";
 function registerListGraphs(server2, client2) {
@@ -523,11 +526,11 @@ function registerSearch(server2, client2) {
     {
       title: "Search Graph",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
-      description: 'Hybrid search over graph nodes; use for meaning-based lookup when you don\'t know the exact label. Combines exact-token text matching (good for UUIDs, proper nouns, specific labels) with semantic similarity (good for paraphrase and meaning), then fuses both rankings with Reciprocal Rank Fusion. Returns the top matches with a `matchedVia` tag - `both` is the highest-confidence signal, then `semantic`, then `text`. Use `naumu_filter` for structured queries by type and attributes (e.g. "all in-progress Tasks"). Tip: include both synonyms ("authentication login SSO") and exact tokens you remember in the same query - the fusion handles both.',
+      description: 'Hybrid search over graph nodes; use for meaning-based lookup when you don\'t know the exact label. Combines text matching, which looks for the whole query as one contiguous substring (good for UUIDs, proper nouns, specific labels), with semantic similarity (good for paraphrase and meaning), then fuses both rankings with Reciprocal Rank Fusion. Returns the top matches with a `matchedVia` tag - `both` is the highest-confidence signal, then `semantic`, then `text`. Use `naumu_filter` for structured queries by type and attributes (e.g. "all in-progress Tasks").',
       inputSchema: z9.object({
         graphId: z9.string().describe("The graph ID"),
         query: z9.string().describe(
-          'Search query text. Mix synonyms and exact tokens freely (e.g. "auth login SSO 2fa Twitter handle").'
+          "A short contiguous phrase \u2014 an entity name, label, or ID. The text half matches it verbatim as a case-insensitive substring; the semantic half matches meaning."
         ),
         limit: z9.number().optional().default(20).describe("Max results to return (default 20, max 200). Adaptive cutoff may return fewer when the top match is weak."),
         nodeTypes: z9.array(z9.string()).optional().describe('Filter to specific node types (e.g. ["Type A", "Type B"])')
@@ -805,7 +808,7 @@ function registerAddNode(server2, client2) {
     {
       title: "Add Nodes (bulk)",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-      description: 'Create 1-25 nodes in the knowledge graph in a single call; use when you have a vetted, dedup-checked batch ready to insert. Keep batches small and atomic (5-25 nodes) so failures stay contained. Each node MUST include a non-empty `content` describing what it is. Returns one entry per input node with `{id, label, type, status: "created"}` - there is NO server-side dedup, every input becomes a node. Dedup is the caller\'s responsibility: BEFORE calling this tool, run `naumu_search` on each candidate label and skip/route to update if a result has high similarity (\u22650.78) and matching type. Warning: nodes are isolated until you connect them with `naumu_add_edge`. Prefer `naumu_delegate` for general knowledge intake - it discovers and creates connections for you.',
+      description: 'Create 1-25 nodes in the knowledge graph in a single call; use when you have a vetted, dedup-checked batch ready to insert. Keep batches small and atomic (5-25 nodes) so failures stay contained. Each node MUST include a non-empty `content` describing what it is. Returns one entry per input node with `{id, label, type, status: "created"}` - there is NO server-side dedup, every input becomes a node. Dedup is the caller\'s responsibility: BEFORE calling this tool, run `naumu_search` on each candidate label and treat a result as the same entity when its `matchedVia` is "semantic" or "both" AND its type matches AND the labels plausibly name the same thing - then reuse/update that node instead of creating one. (The `score` field is a rank-fusion value, not a similarity - do not compare it against a threshold.) Warning: nodes are isolated until you connect them with `naumu_add_edge`. Prefer `naumu_delegate` for general knowledge intake - it discovers and creates connections for you.',
       inputSchema: z13.object({
         graphId: z13.string().describe("The graph ID"),
         nodes: z13.array(NodeInput).min(1).max(25).describe("Batch of 1\u201325 nodes to create. Keep batches small for atomicity.")
@@ -1091,18 +1094,20 @@ function registerPostMessage(server2, client2) {
         idempotentHint: false,
         openWorldHint: false
       },
-      description: 'Post a message in a Naumu thread you participate in. Use it to reply to humans (or other bots) in a thread that pinged you. Plain text is accepted by default; for rendered @mentions pass a Tiptap JSON document with mention nodes (`{ type: "mention", attrs: { id, label } }`) and set contentFormat to "tiptap". @mentioning people loops them in (mention notifications, prompts) without invoking @Naumu. For a human, the mention `id` is their User id (from naumu_list_members or naumu_get_thread participantDetails) or their email - both work; for a bot/agent, use its identity id. To attach files call naumu_request_attachment_upload first, PUT the bytes to the returned uploadUrl, then pass the resulting attachmentIds here. The message needs either `content` or `attachmentIds`. Returns the created message JSON. To get a synthesised answer from @Naumu, use naumu_ask.',
+      description: 'Post a message in a Naumu thread you participate in. Use it to reply to humans (or other bots) in a thread that pinged you. Write `content` in markdown (the default format): **bold**, *italic*, `inline code`, fenced code blocks, `- ` bullets, `1. ` ordered lists, and `> ` quotes all render natively; headings and tables are not supported and render as plain text. Mentions are inline pills: `@[Name](id)` mentions a person or bot and `#[label](topic-id)` tags a topic. For a human the mention id is their User id (from naumu_list_members or naumu_get_thread participantDetails) or their email - both work; for a bot/agent use its identity id; `@[Naumu](naumu-ai)` addresses the @Naumu agent (a bare `@naumu` in prose also summons it, so only type it when you mean to). @mentioning people loops them in (mention notifications, prompts) without invoking @Naumu. Set contentFormat to "tiptap" only when you need rich content beyond the markdown subset, passing a Tiptap JSON document with mention nodes (`{ type: "mention", attrs: { id, label } }`). To attach files call naumu_request_attachment_upload first, PUT the bytes to the returned uploadUrl, then pass the resulting attachmentIds here. The message needs either `content` or `attachmentIds`. Returns the created message JSON. To get a synthesised answer from @Naumu, use naumu_ask.',
       inputSchema: z20.object({
         threadId: z20.string().describe("The thread ID to post into. You must be a participant in this thread."),
-        content: z20.string().optional().describe('Message body. Plain text by default; pass a Tiptap JSON document only if contentFormat is set to "tiptap". Optional when `attachmentIds` is provided.'),
-        contentFormat: z20.enum(["tiptap", "text"]).optional().describe('Format of `content`. Defaults to "text". Use "tiptap" for rendered mentions/embeds, e.g. a doc containing `{ type: "mention", attrs: { id: userIdOrEmailOrIdentityId, label: displayName } }` (a human mention id is their User id or email; a bot mention id is its identity id).'),
+        content: z20.string().optional().describe('Message body. Markdown by default (see the tool description for the supported subset and the `@[Name](id)` mention pill syntax); a Tiptap JSON document when contentFormat is "tiptap". Optional when `attachmentIds` is provided.'),
+        contentFormat: z20.enum(["tiptap", "markdown"]).optional().describe('Format of `content`. Defaults to "markdown" (rendered subset plus `@[Name](id)` / `#[label](topic-id)` mention pills). Use "tiptap" for full rich content, e.g. a doc containing `{ type: "mention", attrs: { id: userIdOrEmailOrIdentityId, label: displayName } }`.'),
         attachmentIds: z20.array(z20.string().min(1)).max(25).optional().describe("Attachment IDs from prior `naumu_request_attachment_upload` calls. Each must be a successfully-uploaded pending attachment in this graph (1-hour TTL). Up to 25 per message.")
       })
     },
     async ({ threadId, content, contentFormat, attachmentIds }) => {
       try {
         const body = {
-          contentFormat: contentFormat ?? "text"
+          // 'markdown' is the announced name for the API's 'text' mode;
+          // deployed backends may predate the alias, so translate on the wire.
+          contentFormat: contentFormat === "tiptap" ? "tiptap" : "text"
         };
         if (content !== void 0) body.content = content;
         if (attachmentIds && attachmentIds.length > 0) body.attachmentIds = attachmentIds;
@@ -1285,8 +1290,106 @@ function registerListTopics(server2, client2) {
   );
 }
 
-// ../mcp-core/src/tools/get-thread.ts
+// ../mcp-core/src/tools/create-topic.ts
 import { z as z25 } from "zod";
+var TOPIC_NAME_PATTERN = /^[a-z0-9-]+$/;
+var TOPIC_NAME_MAX_LENGTH = 50;
+var RESERVED_TOPIC_NAMES = [
+  "all",
+  "everyone",
+  "naumu",
+  "here",
+  "misc",
+  "hidden",
+  "space",
+  "shared-with-you"
+];
+function validateTopicName(name) {
+  const trimmed = name.trim();
+  if (trimmed.length === 0) return "Topic name is required.";
+  if (trimmed.length > TOPIC_NAME_MAX_LENGTH) {
+    return `Topic name must be at most ${TOPIC_NAME_MAX_LENGTH} characters (got ${trimmed.length}).`;
+  }
+  if (!TOPIC_NAME_PATTERN.test(trimmed)) {
+    return `Invalid topic name "${trimmed}". Only lowercase letters, numbers, and "-" are allowed (e.g. "core-team"). Replace spaces with hyphens and drop any other characters.`;
+  }
+  if (RESERVED_TOPIC_NAMES.includes(trimmed.toLowerCase())) {
+    return `Topic name "${trimmed}" is reserved. Reserved names: ${RESERVED_TOPIC_NAMES.join(", ")}.`;
+  }
+  return null;
+}
+function registerCreateTopic(server2, client2) {
+  server2.registerTool(
+    "naumu_create_topic",
+    {
+      title: "Create Topic",
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+      description: 'Create a new topic (filing destination) in a space; use when the topic a thread or note should be filed into does not exist yet. Check `naumu_list_topics` first so you reuse an existing topic instead of creating a near-duplicate. Returns the created topic `{id, name, color, visibilityMode, archived, openToWeb, webParticipation, createdAt, createdBy, memberIds, isMember}` - pass the returned `id` to the `topicIds` param of naumu_delegate, naumu_ask or naumu_create_note to file work into it. Name rules (validated before the call): lowercase letters, numbers and "-" only (channel-slug style, e.g. "core-team"), at most 50 characters, and never one of the reserved names all, everyone, naumu, here, misc, hidden, space, shared-with-you. Names are unique per space, case-insensitively. Requires admin rights on the space: editors and bot identities always get a 403, so do not attempt this on behalf of a bot. `visibilityMode` defaults to "open"; the caller is always added as a member, and `openToWeb` cannot be combined with a "closed" topic. Resolve `graphId` via naumu_list_graphs first.',
+      inputSchema: z25.object({
+        graphId: z25.string().describe("The space (graph) id to create the topic in."),
+        name: z25.string().min(1).describe(
+          'Topic name in channel-slug form: lowercase letters, numbers and "-" only, max 50 chars, not a reserved name. Unique per space (case-insensitive).'
+        ),
+        color: z25.string().optional().describe("Optional named color token for the topic badge. Omit unless the user asked for a specific color."),
+        visibilityMode: z25.enum(["default", "open", "closed"]).optional().describe(
+          'Who can see and join the topic. "open" (the default) lets any space member join, "default" is the space default, "closed" is invite-only.'
+        ),
+        openToWeb: z25.boolean().optional().describe('Expose the topic publicly on the web. Invalid together with visibilityMode "closed".'),
+        webParticipation: z25.enum(["participate", "view-only"]).optional().describe('What public web visitors may do when openToWeb is true. Defaults to "view-only".'),
+        memberIds: z25.array(z25.string()).optional().describe(
+          "User ids to add as topic members (get them from naumu_list_members). Ids that are not current space members are silently dropped. The caller is always added regardless."
+        )
+      })
+    },
+    async ({ graphId, name, color, visibilityMode, openToWeb, webParticipation, memberIds }) => {
+      const nameError = validateTopicName(name);
+      if (nameError) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Topic name validation failed - no topic was created: ${nameError}`
+            }
+          ],
+          isError: true
+        };
+      }
+      if (openToWeb === true && visibilityMode === "closed") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: 'Topic validation failed - no topic was created: public web access is only available on open or default topics, so openToWeb cannot be true when visibilityMode is "closed".'
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        const data = await client2.post(`/api/graphs/${graphId}/topics`, {
+          name: name.trim(),
+          color,
+          visibilityMode,
+          openToWeb,
+          webParticipation,
+          memberIds
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// ../mcp-core/src/tools/get-thread.ts
+import { z as z26 } from "zod";
 function sanitizeThreadParticipants2(thread) {
   if (!thread || typeof thread !== "object" || !("participantEmails" in thread)) {
     return thread;
@@ -1301,8 +1404,8 @@ function registerGetThread(server2, client2) {
       title: "Get Thread",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: "Fetch a single thread, including the human participant roster (`participantDetails` \u2014 userId, name, image) and bot roster (`identityParticipants` \u2014 id, name, isSystem). Use this when `naumu_list_threads` surfaced a candidate and you want to know exactly who is in it before posting. Pair with `naumu_read_thread` for message history.",
-      inputSchema: z25.object({
-        threadId: z25.string().describe("The thread ID to fetch.")
+      inputSchema: z26.object({
+        threadId: z26.string().describe("The thread ID to fetch.")
       })
     },
     async ({ threadId }) => {
@@ -1324,7 +1427,7 @@ function registerGetThread(server2, client2) {
 }
 
 // ../mcp-core/src/tools/create-thread.ts
-import { z as z26 } from "zod";
+import { z as z27 } from "zod";
 function registerCreateThread(server2, client2) {
   server2.registerTool(
     "naumu_create_thread",
@@ -1339,23 +1442,23 @@ function registerCreateThread(server2, client2) {
         openWorldHint: false
       },
       description: "Start a new conversation in a space. You are auto-attached as a participant, and the thread's formal creator is your primary owner (the user who registered you), so it shows in their sidebar. Optional `participants` adds humans (by userId) and other bots (by identityId) at creation. Optional `initialMessage` opens the conversation as your first message. Optional `topicIds` files the new thread into one or more topics (see naumu_list_topics for ids): it becomes visible to those topics' members from birth instead of staying a private thread between you and your owner. Filing is creation-only and only ever widens - it never removes the thread from a topic later. Tagging people loops them in without invoking @Naumu; only an explicit @Naumu mention, or naumu_ask, brings the agent in. Returns the created thread (including its id) so you can follow up with naumu_post_message.",
-      inputSchema: z26.object({
-        title: z26.string().min(1).max(200).optional().describe('Thread title shown in the sidebar. If omitted, Naumu generates a default like "Conversation YYYY-MM-DD".'),
-        participants: z26.array(
-          z26.discriminatedUnion("type", [
-            z26.object({
-              type: z26.literal("user"),
-              userId: z26.string().min(1).describe("User UUID \u2014 get these from `naumu_get_thread`/`naumu_read_thread` participant rosters or webhook payloads.")
+      inputSchema: z27.object({
+        title: z27.string().min(1).max(200).optional().describe('Thread title shown in the sidebar. If omitted, Naumu generates a default like "Conversation YYYY-MM-DD".'),
+        participants: z27.array(
+          z27.discriminatedUnion("type", [
+            z27.object({
+              type: z27.literal("user"),
+              userId: z27.string().min(1).describe("User UUID \u2014 get these from `naumu_get_thread`/`naumu_read_thread` participant rosters or webhook payloads.")
             }),
-            z26.object({
-              type: z26.literal("identity"),
-              identityId: z26.string().min(1).describe("Identity id (`identity-\u2026` or `id-\u2026`). Other bots in the same graph can be co-attached to multi-bot threads.")
+            z27.object({
+              type: z27.literal("identity"),
+              identityId: z27.string().min(1).describe("Identity id (`identity-\u2026` or `id-\u2026`). Other bots in the same graph can be co-attached to multi-bot threads.")
             })
           ])
         ).max(32).optional().describe("Up to 32 humans and/or other bots to attach at creation. Your primary owner is added automatically \u2014 you do NOT need to list them here."),
-        initialMessage: z26.string().min(1).max(32e3).optional().describe("Markdown body for the first message. Authored by you (the bot), so it appears in the thread under your name."),
-        visibility: z26.enum(["restricted", "internal", "open"]).optional().describe("`restricted` (invite-only, default) hides from non-participants. `internal` is visible to space members. `open` is visible to anyone who can see the space."),
-        topicIds: z26.array(z26.string()).max(8).optional().describe(
+        initialMessage: z27.string().min(1).max(32e3).optional().describe("Markdown body for the first message. Authored by you (the bot), so it appears in the thread under your name."),
+        visibility: z27.enum(["restricted", "internal", "open"]).optional().describe("`restricted` (invite-only, default) hides from non-participants. `internal` is visible to space members. `open` is visible to anyone who can see the space."),
+        topicIds: z27.array(z27.string()).max(8).optional().describe(
           "Topic ids (from naumu_list_topics) to file the NEW thread into, making it visible to those topics' members from birth. Creation-only and only ever widens - it never removes the thread from a topic later. Omit to keep the default private thread between you and your owner."
         )
       })
@@ -1384,32 +1487,53 @@ function registerCreateThread(server2, client2) {
 }
 
 // ../mcp-core/src/tools/request-attachment-upload.ts
-import { z as z27 } from "zod";
+import { z as z28 } from "zod";
 function registerRequestAttachmentUpload(server2, client2) {
   server2.registerTool(
     "naumu_request_attachment_upload",
     {
       title: "Request Attachment Upload",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-      description: 'Request a presigned S3 upload URL to attach a file to a message; use when you want to deliver generated content as a file (a markdown report, a PDF, an image, an audio recording, a video). Same flow Naumu users use for file uploads: get a signed URL, PUT the bytes to it directly, then call `naumu_post_message` with the returned `attachmentId` in `attachmentIds`. Per-MIME size caps apply (typically 50MB umbrella, 10MB for agent-readable types).\n\nReturns `{ attachmentId, uploadUrl, method, requiredHeaders, expiresAt }`. Use these EXACTLY:\n\u2022 `method` is "PUT".\n\u2022 Send every header in `requiredHeaders` (Content-Type matters for S3 signature validation).\n\u2022 Do NOT add an Authorization header - the URL itself is the auth.\n\u2022 Do NOT log `uploadUrl` - it is a bearer capability for the duration of the TTL.\n\u2022 `expiresAt` is a Unix-ms timestamp; the pending attachment vanishes at that moment whether or not you uploaded. Call `naumu_post_message` with the attachmentId before then or the upload orphans.\n\nServer-side checks at post time enforce that the attachment was uploaded by you, in this graph, for this thread - you cannot reuse an upload across threads.',
-      inputSchema: z27.object({
-        threadId: z27.string().describe("Thread the attachment will land in. You must be a participant. The pending attachment is keyed to this thread - you cannot reuse it for a different one."),
-        fileName: z27.string().min(1).describe("Original filename (with extension). Used as the display name in the message and for the S3 object suffix. Special characters are sanitized server-side."),
-        fileType: z27.string().min(1).describe("MIME type, e.g. `application/pdf`, `image/png`, `text/markdown`, `audio/mpeg`, `video/mp4`. The S3 PUT will enforce this Content-Type."),
-        fileSize: z27.number().int().positive().describe("File size in bytes. Validated against per-MIME caps before the URL is issued - exceeding the cap returns a 400."),
-        audioDurationSec: z27.number().positive().optional().describe("For audio attachments, duration in seconds. Validated against the audio recording cap (currently 8 hours).")
-      })
+      description: "Request a presigned S3 upload URL to attach a file - pass exactly one of `threadId`, `noteId`, or `canvasId` for where the upload will land, then PUT the bytes directly to the returned URL. Same flow Naumu users use for file uploads. User API keys and OAuth sessions must also pass `graphId` (a user spans many spaces; resolve it via `naumu_list_graphs`); bot keys resolve it automatically.\n\nThree destinations, three follow-up calls:\n\u2022 Thread: presign with `threadId` \u2192 PUT the bytes \u2192 call `naumu_post_message` with the returned `attachmentId` in `attachmentIds`.\n\u2022 Note: presign with `noteId` \u2192 PUT the bytes \u2192 call `naumu_note_append` (or any note write tool) with `![alt](attachment://<attachmentId>)` in the markdown. That single call binds the upload, embeds it inline as the note's canonical media node, and files it into the space's Files & Media library - the same syntax works for images, video, audio, and other files, dispatched by the upload's MIME type.\n\u2022 Canvas: presign with `canvasId` \u2192 PUT the bytes \u2192 call `naumu_persist_canvas_attachment` to extend the upload past its default 1-hour TTL. Placing the persisted attachment onto the canvas itself still happens in the app UI.\n\nTo attach media to a graph node, upload into a thread that originated or modified that node - files surface on the node via its threads; there is no separate node-attachment flow.\n\nPer-MIME size caps apply: 10MB for types the agent reads whole (image, text, PDF, office docs), otherwise the space plan's umbrella cap (50MB free, 500MB team, 1GB max). Audio takes the plan cap, NOT the 10MB agent-read budget - it is transcribed on upload and only the transcript reaches an agent, so a multi-hour recording is a legitimate attachment. Over-cap requests are refused with HTTP 413 before any URL is minted, and the size is re-checked at bind time against the object that actually landed - so an oversized upload is refused there too, not silently accepted.\n\nReturns `{ attachmentId, uploadUrl, method, requiredHeaders, expiresAt }`. Use these EXACTLY:\n\u2022 `method` is \"PUT\".\n\u2022 Send every header in `requiredHeaders`. It carries BOTH `Content-Type` and `Content-Length`, and both are load-bearing: `Content-Length` is signed INTO the URL, so the body must be exactly that many bytes or S3 answers 403. PUT the whole file as one fixed-length body - do not stream it, do not use chunked transfer encoding, and do not send a different byte count than the `fileSize` you declared here.\n\u2022 Do NOT add an Authorization header - the URL itself is the auth.\n\u2022 Do NOT log `uploadUrl` - it is a bearer capability for the duration of the TTL.\n\u2022 `expiresAt` is a Unix-ms timestamp; the pending attachment vanishes at that moment whether or not you uploaded. Bind it (post the message, embed the note reference, or persist the canvas attachment) before then or the upload orphans.\n\nServer-side checks at bind time enforce that the attachment was uploaded by you, in this graph, for this thread/note/canvas - you cannot reuse an upload across destinations.",
+      inputSchema: z28.object({
+        graphId: z28.string().optional().describe("Graph (space) UUID the destination lives in. REQUIRED for user API keys and OAuth sessions - a user spans many spaces, so nothing can infer it; resolve it once via `naumu_list_graphs` and reuse it. Bot keys may omit it: a bot is pinned to one graph and the tool resolves it automatically."),
+        threadId: z28.string().optional().describe("Destination thread - presign for a thread when the upload will be attached to a chat message via `naumu_post_message`'s `attachmentIds`. You must be a participant. Exactly one of `threadId`, `noteId`, or `canvasId` is required. The pending attachment is keyed to this thread - you cannot reuse it for a different one."),
+        noteId: z28.string().optional().describe("Destination note (Thought) - presign for a note when the upload will be embedded via `![alt](attachment://<attachmentId>)` in a note write tool call. Exactly one of `threadId`, `noteId`, or `canvasId` is required. The pending attachment is keyed to this note - you cannot reuse it for a different one."),
+        canvasId: z28.string().optional().describe("Destination canvas - presign for a canvas when the upload will be placed on a canvas; follow up with `naumu_persist_canvas_attachment` to extend its TTL. Exactly one of `threadId`, `noteId`, or `canvasId` is required. The pending attachment is keyed to this canvas - you cannot reuse it for a different one."),
+        fileName: z28.string().min(1).describe("Original filename (with extension). Used as the display name and for the S3 object suffix. Special characters are sanitized server-side."),
+        fileType: z28.string().min(1).describe("MIME type, e.g. `application/pdf`, `image/png`, `text/markdown`, `audio/mpeg`, `video/mp4`. The S3 PUT will enforce this Content-Type."),
+        fileSize: z28.number().int().positive().describe("File size in bytes, exact. Validated against per-MIME caps before the URL is issued - exceeding the cap returns a 413 (not a 400; 400 means a different rejection). This number is also signed into the upload URL as `Content-Length`, so it is a commitment, not an estimate: PUT exactly this many bytes. Audio is validated against the plan umbrella cap (50MB free / 500MB team / 1GB max), not the 10MB agent-read budget."),
+        audioDurationSec: z28.number().positive().optional().describe("For audio attachments, duration in seconds. Send it whenever you know it: audio carries an 8-hour ceiling on top of the size cap, and nothing measures the file server-side, so that ceiling is checked ONLY against a length you report. Omitting it skips the check rather than failing it - the size cap is what still binds you. Omit it rather than guessing: a wrong value is worse than none, and a deliberate under-report is a policy violation, not a workaround.")
+      }).refine(
+        (data) => [data.threadId, data.noteId, data.canvasId].filter((v) => v !== void 0).length === 1,
+        { message: "Exactly one of threadId, noteId, or canvasId is required - pick the single destination this upload is for." }
+      )
     },
-    async ({ threadId, fileName, fileType, fileSize, audioDurationSec }) => {
+    async ({ graphId, threadId, noteId, canvasId, fileName, fileType, fileSize, audioDurationSec }) => {
       try {
-        const me = await client2.get("/api/identities/me/whoami");
+        let resolvedGraphId = graphId;
+        if (resolvedGraphId === void 0) {
+          const me = await client2.get("/api/identities/me/whoami");
+          resolvedGraphId = me.graphId;
+        }
+        if (resolvedGraphId === void 0) {
+          return {
+            content: [{
+              type: "text",
+              text: "Error: graphId is required for this session. Your key is a user key, which spans multiple spaces - call naumu_list_graphs, pick the target space, and pass its id as graphId."
+            }],
+            isError: true
+          };
+        }
         const body = {
-          graphId: me.graphId,
-          threadId,
+          graphId: resolvedGraphId,
           fileName,
           fileType,
           fileSize
         };
+        if (threadId !== void 0) body.threadId = threadId;
+        if (noteId !== void 0) body.noteId = noteId;
+        if (canvasId !== void 0) body.canvasId = canvasId;
         if (audioDurationSec !== void 0) body.audioDurationSec = audioDurationSec;
         const data = await client2.post("/api/attachments/presign", body);
         return {
@@ -1426,8 +1550,38 @@ function registerRequestAttachmentUpload(server2, client2) {
   );
 }
 
+// ../mcp-core/src/tools/persist-canvas-attachment.ts
+import { z as z29 } from "zod";
+function registerPersistCanvasAttachment(server2, client2) {
+  server2.registerTool(
+    "naumu_persist_canvas_attachment",
+    {
+      title: "Persist Canvas Attachment",
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+      description: "Extend a canvas-bound pending attachment's TTL from its default 1 hour to 30 days; call right after `naumu_request_attachment_upload` (with `canvasId` set) and the S3 PUT, so the upload survives long enough to be used. This only persists the upload - actually placing it onto the canvas still happens in the app UI, there is no MCP canvas-editing tool yet. Safe to call more than once for the same attachmentId.",
+      inputSchema: z29.object({
+        attachmentId: z29.string().min(1).describe("The `attachmentId` returned by `naumu_request_attachment_upload` for this canvas.")
+      })
+    },
+    async ({ attachmentId }) => {
+      try {
+        const data = await client2.post(`/api/attachments/${attachmentId}/persist-canvas`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
 // ../mcp-core/src/tools/add-reaction.ts
-import { z as z28 } from "zod";
+import { z as z30 } from "zod";
 function registerAddReaction(server2, client2) {
   server2.registerTool(
     "naumu_add_reaction",
@@ -1435,10 +1589,10 @@ function registerAddReaction(server2, client2) {
       title: "Add Reaction",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       description: 'Add an emoji reaction to a message in a thread you are participating in; use for lightweight acknowledgement instead of posting a message. Idempotent - calling twice with the same emoji is a no-op (use `naumu_remove_reaction` to undo). Returns `{ ok, messageId, emoji, alreadyExisted, reactionCount, reactions }` so you can confirm the state without re-reading the thread; `alreadyExisted: true` means the reaction was already on the message and the call was a no-op.\n\nWhen to react vs. when to post a message:\n\u2022 React (no message) for lightweight acknowledgement (\u{1F440}, \u2705, \u{1F44D}), appreciation (\u2764\uFE0F, \u{1F64C}), laughter (\u{1F602}), or "I saw this".\n\u2022 Post a message for direct questions, clarification, important corrections, or final results - situations where words are required.\n\u2022 For long tasks: react \u{1F440} first to acknowledge, optionally post a short "On it - I\'ll report back" if the work will take >20s, do the work, then post the final result.\n\u2022 Ignore casual human banter, side-conversations someone else already answered, or anything where you would only say "ok"/"nice"/"lol".\n\nUse at most one reaction per message unless explicitly useful. Reactions are social backpressure relief, not a sparkle-confetti channel.',
-      inputSchema: z28.object({
-        threadId: z28.string().describe("Thread containing the message. You must be a participant."),
-        messageId: z28.string().describe("The message to react to."),
-        emoji: z28.string().min(1).describe('Emoji character (e.g. "\u{1F440}", "\u2705", "\u2764\uFE0F"). Custom-emoji shortcodes are NOT supported here - pass a real Unicode emoji.')
+      inputSchema: z30.object({
+        threadId: z30.string().describe("Thread containing the message. You must be a participant."),
+        messageId: z30.string().describe("The message to react to."),
+        emoji: z30.string().min(1).describe('Emoji character (e.g. "\u{1F440}", "\u2705", "\u2764\uFE0F"). Custom-emoji shortcodes are NOT supported here - pass a real Unicode emoji.')
       })
     },
     async ({ threadId, messageId, emoji }) => {
@@ -1462,7 +1616,7 @@ function registerAddReaction(server2, client2) {
 }
 
 // ../mcp-core/src/tools/remove-reaction.ts
-import { z as z29 } from "zod";
+import { z as z31 } from "zod";
 function registerRemoveReaction(server2, client2) {
   server2.registerTool(
     "naumu_remove_reaction",
@@ -1470,10 +1624,10 @@ function registerRemoveReaction(server2, client2) {
       title: "Remove Reaction",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       description: "Remove your own emoji reaction from a message; use to walk back an acknowledgement you previously added. Idempotent - calling on a reaction you never added is a no-op. Pair with `naumu_add_reaction` (e.g. you reacted \u{1F440} to start a task and want to clear it after a final result message lands). Returns `{ ok, messageId, emoji, alreadyExisted, reactionCount, reactions }` - `alreadyExisted: false` means there was nothing to remove and the call was a no-op.",
-      inputSchema: z29.object({
-        threadId: z29.string().describe("Thread containing the message. You must be a participant."),
-        messageId: z29.string().describe("The message to remove your reaction from."),
-        emoji: z29.string().min(1).describe("Emoji character to remove (must match what you originally reacted with).")
+      inputSchema: z31.object({
+        threadId: z31.string().describe("Thread containing the message. You must be a participant."),
+        messageId: z31.string().describe("The message to remove your reaction from."),
+        emoji: z31.string().min(1).describe("Emoji character to remove (must match what you originally reacted with).")
       })
     },
     async ({ threadId, messageId, emoji }) => {
@@ -1497,7 +1651,7 @@ function registerRemoveReaction(server2, client2) {
 }
 
 // ../mcp-core/src/tools/naumu-typing.ts
-import { z as z30 } from "zod";
+import { z as z32 } from "zod";
 function registerNaumuTyping(server2, client2) {
   server2.registerTool(
     "naumu_typing",
@@ -1508,9 +1662,9 @@ function registerNaumuTyping(server2, client2) {
       // repeating the same state is a no-op renew, so idempotent.
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       description: 'Show or hide your "is typing\u2026" pill in a thread; use to signal that you are composing a reply. Call with `state: "start"` the moment you decide to compose a reply (before any LLM call), and the server holds the pill alive - re-broadcasting on a short interval - until you stop, post a message, or the lease cap (~5 min) fires. You do NOT need to refresh on a timer; that\'s the lease\'s job.\n\nThe pill clears automatically when:\n\u2022 you call this tool with `state: "stop"`\n\u2022 you call `naumu_post_message` for the same thread (cleared on commit)\n\u2022 the lease cap expires\n\nUse `start` whenever you start work, even if you might end up not replying - call `stop` if you decide NOT to post. Calling `start` while a lease is already active renews it (resets the cap), so a long-running run can call `start` again as a heartbeat without breaking the indicator. You must be a participant of the thread.',
-      inputSchema: z30.object({
-        threadId: z30.string().describe("The thread ID to set typing in. You must be a participant."),
-        state: z30.enum(["start", "stop"]).describe('"start" acquires/renews the lease; "stop" ends it and clears the pill immediately.')
+      inputSchema: z32.object({
+        threadId: z32.string().describe("The thread ID to set typing in. You must be a participant."),
+        state: z32.enum(["start", "stop"]).describe('"start" acquires/renews the lease; "stop" ends it and clears the pill immediately.')
       })
     },
     async ({ threadId, state }) => {
@@ -1531,7 +1685,7 @@ function registerNaumuTyping(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-read.ts
-import { z as z31 } from "zod";
+import { z as z33 } from "zod";
 function registerNoteRead(server2, client2) {
   server2.registerTool(
     "naumu_note_read",
@@ -1539,8 +1693,8 @@ function registerNoteRead(server2, client2) {
       title: "Read Note",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: "Read the current contents of a note as markdown; use before editing so you know what you're working with. `naumu_note_find_replace` and the section-based tools (`naumu_note_insert`, `naumu_note_replace_section`, `naumu_note_delete_section`) anchor on text/headings present in the live doc.",
-      inputSchema: z31.object({
-        noteId: z31.string().describe("The note (Thought) ID")
+      inputSchema: z33.object({
+        noteId: z33.string().describe("The note (Thought) ID")
       })
     },
     async ({ noteId }) => {
@@ -1553,17 +1707,17 @@ function registerNoteRead(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-append.ts
-import { z as z32 } from "zod";
+import { z as z34 } from "zod";
 function registerNoteAppend(server2, client2) {
   server2.registerTool(
     "naumu_note_append",
     {
       title: "Append to Note",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-      description: "Append markdown blocks to the end of a note; use for additive note writing that never touches existing content. Other participants see your colored cursor while the write lands. Markdown supports headings (1-3), bold/italic/code, lists, blockquotes, code blocks, links, and tables.",
-      inputSchema: z32.object({
-        noteId: z32.string().describe("The note (Thought) ID to append to"),
-        markdown: z32.string().min(1).describe("Markdown content to append at the end of the note")
+      description: "Append markdown blocks to the end of a note; use for additive note writing that never touches existing content. Other participants see your colored cursor while the write lands. Markdown supports headings (1-3), bold/italic/code, lists, blockquotes, code blocks, links, and tables. To embed media, write `![alt](attachment://<attachmentId>)` as a sole-line image - the id must come from `naumu_request_attachment_upload` presigned with this same `noteId`. The one syntax covers images, video, audio, and other files, dispatched by the upload's MIME type into the note's canonical media node; an unresolvable or wrong-note id fails the whole write with a 400 naming the bad id. An id already embedded in the note can be repeated safely without re-uploading.",
+      inputSchema: z34.object({
+        noteId: z34.string().describe("The note (Thought) ID to append to"),
+        markdown: z34.string().min(1).describe("Markdown content to append at the end of the note")
       })
     },
     async ({ noteId, markdown }) => {
@@ -1576,18 +1730,18 @@ function registerNoteAppend(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-insert.ts
-import { z as z33 } from "zod";
+import { z as z35 } from "zod";
 function registerNoteInsert(server2, client2) {
   server2.registerTool(
     "naumu_note_insert",
     {
       title: "Insert After Heading",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-      description: "Insert markdown content into a note immediately after a named section; use to add content under a specific heading without rewriting it. The section ends at the next heading of equal-or-higher level (or end of doc). 404 if no heading matches `headingText` exactly - call `naumu_note_read` first to see the live structure.",
-      inputSchema: z33.object({
-        noteId: z33.string().describe("The note (Thought) ID"),
-        headingText: z33.string().min(1).describe("Exact text of the heading whose section the new content follows"),
-        markdown: z33.string().min(1).describe("Markdown content to insert at the end of that section")
+      description: "Insert markdown content into a note immediately after a named section; use to add content under a specific heading without rewriting it. The section ends at the next heading of equal-or-higher level (or end of doc). 404 if no heading matches `headingText` exactly - call `naumu_note_read` first to see the live structure. To embed media, write `![alt](attachment://<attachmentId>)` as a sole-line image - the id must come from `naumu_request_attachment_upload` presigned with this same `noteId`. The one syntax covers images, video, audio, and other files, dispatched by the upload's MIME type; an unresolvable or wrong-note id fails the whole write with a 400 naming the bad id.",
+      inputSchema: z35.object({
+        noteId: z35.string().describe("The note (Thought) ID"),
+        headingText: z35.string().min(1).describe("Exact text of the heading whose section the new content follows"),
+        markdown: z35.string().min(1).describe("Markdown content to insert at the end of that section")
       })
     },
     async ({ noteId, headingText, markdown }) => {
@@ -1603,19 +1757,19 @@ function registerNoteInsert(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-replace-section.ts
-import { z as z34 } from "zod";
+import { z as z36 } from "zod";
 function registerNoteReplaceSection(server2, client2) {
   server2.registerTool(
     "naumu_note_replace_section",
     {
       title: "Replace Section",
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
-      description: "Replace the body under a named heading with new markdown; use to rewrite one section of a note while leaving the rest intact. By default the heading row itself is preserved (set `keepHeading: false` to drop it too). 404 if no heading matches.",
-      inputSchema: z34.object({
-        noteId: z34.string().describe("The note (Thought) ID"),
-        headingText: z34.string().min(1).describe("Exact text of the heading anchoring the section"),
-        markdown: z34.string().describe("Replacement markdown for the section body"),
-        keepHeading: z34.boolean().optional().describe("Whether to keep the heading row itself. Default true.")
+      description: "Replace the body under a named heading with new markdown; use to rewrite one section of a note while leaving the rest intact. By default the heading row itself is preserved (set `keepHeading: false` to drop it too). 404 if no heading matches. To embed media, write `![alt](attachment://<attachmentId>)` as a sole-line image - the id must come from `naumu_request_attachment_upload` presigned with this same `noteId`. The one syntax covers images, video, audio, and other files, dispatched by the upload's MIME type; an unresolvable or wrong-note id fails the whole write with a 400 naming the bad id. An id already embedded elsewhere in the note can be repeated safely without re-uploading.",
+      inputSchema: z36.object({
+        noteId: z36.string().describe("The note (Thought) ID"),
+        headingText: z36.string().min(1).describe("Exact text of the heading anchoring the section"),
+        markdown: z36.string().describe("Replacement markdown for the section body"),
+        keepHeading: z36.boolean().optional().describe("Whether to keep the heading row itself. Default true.")
       })
     },
     async ({ noteId, headingText, markdown, keepHeading }) => {
@@ -1632,7 +1786,7 @@ function registerNoteReplaceSection(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-delete-section.ts
-import { z as z35 } from "zod";
+import { z as z37 } from "zod";
 function registerNoteDeleteSection(server2, client2) {
   server2.registerTool(
     "naumu_note_delete_section",
@@ -1640,9 +1794,9 @@ function registerNoteDeleteSection(server2, client2) {
       title: "Delete Section",
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
       description: "\u26A0 DESTRUCTIVE: remove a heading row plus its body (down to the next heading of equal-or-higher level); ONLY use when the user explicitly asks to drop a section. Anything inside that section is gone - there is no per-call undo. If you're unsure which heading they meant, call `naumu_note_read` first to see the current structure. Returns 404 if `headingText` does not exactly match any live heading.",
-      inputSchema: z35.object({
-        noteId: z35.string().describe("The note (Thought) ID"),
-        headingText: z35.string().min(1).describe("Exact text of the heading whose section will be deleted")
+      inputSchema: z37.object({
+        noteId: z37.string().describe("The note (Thought) ID"),
+        headingText: z37.string().min(1).describe("Exact text of the heading whose section will be deleted")
       })
     },
     async ({ noteId, headingText }) => {
@@ -1657,17 +1811,17 @@ function registerNoteDeleteSection(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-replace.ts
-import { z as z36 } from "zod";
+import { z as z38 } from "zod";
 function registerNoteReplace(server2, client2) {
   server2.registerTool(
     "naumu_note_replace",
     {
       title: "Replace Note",
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
-      description: "\u26A0 DESTRUCTIVE: replace the entire note content with new markdown; ONLY use when the user explicitly asks to rewrite/replace the whole note. Any concurrent human edits made during the call are silently overwritten. For additive work prefer `naumu_note_append`. For section-level edits use `naumu_note_replace_section`. For inline tweaks use `naumu_note_find_replace`. Read with `naumu_note_read` first if you weren't the last writer.",
-      inputSchema: z36.object({
-        noteId: z36.string().describe("The note (Thought) ID"),
-        markdown: z36.string().describe("New markdown content for the entire note")
+      description: "\u26A0 DESTRUCTIVE: replace the entire note content with new markdown; ONLY use when the user explicitly asks to rewrite/replace the whole note. Any concurrent human edits made during the call are silently overwritten. For additive work prefer `naumu_note_append`. For section-level edits use `naumu_note_replace_section`. For inline tweaks use `naumu_note_find_replace`. Read with `naumu_note_read` first if you weren't the last writer. To embed media, write `![alt](attachment://<attachmentId>)` as a sole-line image - the id must come from `naumu_request_attachment_upload` presigned with this same `noteId`. The one syntax covers images, video, audio, and other files, dispatched by the upload's MIME type; an unresolvable or wrong-note id fails the whole write with a 400 naming the bad id. Ids already embedded in the note (read them back via `naumu_note_read`) can be repeated safely without re-uploading.",
+      inputSchema: z38.object({
+        noteId: z38.string().describe("The note (Thought) ID"),
+        markdown: z38.string().describe("New markdown content for the entire note")
       })
     },
     async ({ noteId, markdown }) => {
@@ -1680,19 +1834,19 @@ function registerNoteReplace(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-find-replace.ts
-import { z as z37 } from "zod";
+import { z as z39 } from "zod";
 function registerNoteFindReplace(server2, client2) {
   server2.registerTool(
     "naumu_note_find_replace",
     {
       title: "Find/Replace in Note",
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
-      description: "Literal find/replace within a note's text content; use for mid-paragraph tweaks the section-based tools can't target. Marks (bold, italic, code, etc.) are preserved on the surrounding text. \u26A0 The match is literal-substring across every text leaf in the doc; an overly generic `find` (e.g. \" a \") can rewrite the doc unrecognizably. Pick a phrase distinctive enough to land where you mean. By default replaces every occurrence; set `all: false` for first-only. Returns `{ replacements }` so you can sanity-check the count.",
-      inputSchema: z37.object({
-        noteId: z37.string().describe("The note (Thought) ID"),
-        find: z37.string().min(1).describe("Substring to search for. Literal - no regex."),
-        replace: z37.string().describe("Replacement string. May be empty to delete the match."),
-        all: z37.boolean().optional().describe("Replace all occurrences (default true). Pass false to replace only the first.")
+      description: "Literal find/replace within a note's text content; use for mid-paragraph tweaks the section-based tools can't target. Marks (bold, italic, code, etc.) are preserved on the surrounding text. \u26A0 The match is literal-substring across every text leaf in the doc; an overly generic `find` (e.g. \" a \") can rewrite the doc unrecognizably. Pick a phrase distinctive enough to land where you mean. By default replaces every occurrence; set `all: false` for first-only. Returns `{ replacements }` so you can sanity-check the count. `replace` can embed media by containing `![alt](attachment://<attachmentId>)` as a sole-line image - the id must come from `naumu_request_attachment_upload` presigned with this same `noteId`; an unresolvable or wrong-note id fails the whole write with a 400 naming the bad id.",
+      inputSchema: z39.object({
+        noteId: z39.string().describe("The note (Thought) ID"),
+        find: z39.string().min(1).describe("Substring to search for. Literal - no regex."),
+        replace: z39.string().describe("Replacement string. May be empty to delete the match."),
+        all: z39.boolean().optional().describe("Replace all occurrences (default true). Pass false to replace only the first.")
       })
     },
     async ({ noteId, find, replace, all }) => {
@@ -1709,23 +1863,24 @@ function registerNoteFindReplace(server2, client2) {
 }
 
 // ../mcp-core/src/tools/create-note.ts
-import { z as z38 } from "zod";
+import { z as z40 } from "zod";
 function registerCreateNote(server2, client2) {
   server2.registerTool(
     "naumu_create_note",
     {
       title: "Create Note",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-      description: "Create a new empty note in a graph; use when you need a fresh note to write into. Returns the new note row including its `id` - pass that id to `naumu_note_append` / `naumu_note_replace` to fill in the content. Bots can only create notes in their own graph, and a bot-created note is private (participants only) unless `sharedWithSpace` is set true. Bots cannot file notes into topics \u2014 a bot passing `topicIds` is rejected (bots hold no topic membership); use `sharedWithSpace` instead.",
-      inputSchema: z38.object({
-        graphId: z38.string().describe("The graph ID to create the note in"),
-        title: z38.string().optional().describe("Optional title for the note"),
-        sharedWithSpace: z38.boolean().optional().describe("Share the note with everyone in the space. Omit (or false) to keep it private to its participants."),
-        topicIds: z38.array(z38.string()).max(8).optional().describe("File the note into these topics (get ids from naumu_list_topics), making it visible to those topics' members. Not available to bots.")
+      description: "Create a note in a graph, optionally with its full content already in place. Pass `markdown` to create the note and its body in a single call - the preferred path for imports and for any content you already hold. Returns the new note row including its `id`; use `naumu_note_append` / `naumu_note_replace` for LATER edits, not to fill in content you could have passed here. The returned row is the note as it stood BEFORE the body write landed, so its content may read as empty - the write still succeeded, do not retry the call or re-append the body. `attachment://` refs are not accepted in create-time `markdown`: upload the file after the note exists and embed it with a note write tool. Bots can only create notes in their own graph, and a bot-created note is private (participants only) unless `sharedWithSpace` is set true. Bots cannot file notes into topics - a bot passing `topicIds` is rejected (bots hold no topic membership); use `sharedWithSpace` instead.",
+      inputSchema: z40.object({
+        graphId: z40.string().describe("The graph ID to create the note in"),
+        title: z40.string().optional().describe("Optional title for the note"),
+        markdown: z40.string().optional().describe("Full initial note content as markdown. Provide it here to create the note with its content in a single call - preferred for imports; do not restate large content through extra edit calls."),
+        sharedWithSpace: z40.boolean().optional().describe("Share the note with everyone in the space. Omit (or false) to keep it private to its participants."),
+        topicIds: z40.array(z40.string()).max(8).optional().describe("File the note into these topics (get ids from naumu_list_topics), making it visible to those topics' members. Not available to bots.")
       })
     },
-    async ({ graphId, title, sharedWithSpace, topicIds }) => {
-      const data = await client2.post("/api/notes", { graphId, title, sharedWithSpace, topicIds });
+    async ({ graphId, title, markdown, sharedWithSpace, topicIds }) => {
+      const data = await client2.post("/api/notes", { graphId, title, markdown, sharedWithSpace, topicIds });
       return {
         content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
       };
@@ -1734,7 +1889,7 @@ function registerCreateNote(server2, client2) {
 }
 
 // ../mcp-core/src/tools/list-schema-violations.ts
-import { z as z39 } from "zod";
+import { z as z41 } from "zod";
 var DEFAULT_EXAMPLE_LIMIT = 5;
 var rowsForKind = (violations, kind) => {
   const rows = [];
@@ -1760,12 +1915,12 @@ function registerListSchemaViolations(server2, client2) {
       title: "List Schema Violations",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: "Audit a graph against its schema. By default returns a compact summary: total counts plus, for each violation kind, its count and up to 5 example nodes (id/label/type/message) \u2014 small enough not to flood the client. Violation kinds: parent_missing (schema expects a parent edge that does not exist), parent_multiple (more than one parent edge where one is expected), parent_mismatch (parent edge has wrong target type or relation label), parent_not_backbone (an edge uses a backbone/parent relation but is not stored as a backbone edge, so the subtree stays off the hierarchy), unknown_relation (edge uses a relation not in the schema), invalid_connection_target (edge connects to a type the schema does not allow for this source), unknown_type (node carries a type no longer in the schema), disconnected (node heads a group with no backbone path to the main tree). To see every node for one kind, pass `kind` to filter; `limit` caps how many rows are returned (examples in the default summary, or full rows when `kind` is set). Use for audits, import-verification, and CI-style checks after batch writes.",
-      inputSchema: z39.object({
-        graphId: z39.string().describe("The graph ID"),
-        kind: z39.string().optional().describe(
+      inputSchema: z41.object({
+        graphId: z41.string().describe("The graph ID"),
+        kind: z41.string().optional().describe(
           'Drill into one violation kind (e.g. "parent_not_backbone"). Returns the full list of nodes with that kind, up to `limit`, instead of the summary.'
         ),
-        limit: z39.number().int().min(1).optional().describe(
+        limit: z41.number().int().min(1).optional().describe(
           "Max rows to return. When `kind` is set, caps the full drill-down list (default: all). Otherwise caps example nodes per kind in the summary (default: 5)."
         )
       })
@@ -1817,7 +1972,7 @@ function registerListSchemaViolations(server2, client2) {
 }
 
 // ../mcp-core/src/tools/list-dense-nodes.ts
-import { z as z40 } from "zod";
+import { z as z42 } from "zod";
 function registerListDenseNodes(server2, client2) {
   server2.registerTool(
     "naumu_list_dense_nodes",
@@ -1825,10 +1980,10 @@ function registerListDenseNodes(server2, client2) {
       title: "List Dense Nodes",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: 'Return nodes whose child count (children via parent edges; mesh cross-links don\'t count) is \u2265 minConnections, grouped by type; use for /restructure hub detection. Each row includes `same_typed_child_count` - the number of children of the SAME type as the node (the Naumu hub-pattern signal) and `connection_count` - its total children. Sort the response by `same_typed_child_count` descending and route any node with \u226510 same-typed children through a mini-hub split. Pass `nodeTypes` (comma-separated) to restrict to a subset (e.g. ["Type A","Type B"]). Cheap to call - runs a single Cypher aggregation.',
-      inputSchema: z40.object({
-        graphId: z40.string().describe("The graph ID"),
-        minConnections: z40.number().int().min(1).describe("Minimum number of children (parent edges; mesh cross-links excluded). Typical: 10 for hub detection, 11 to count only hubs that exceed the round-4 \u226410 threshold."),
-        nodeTypes: z40.array(z40.string()).optional().describe("Optional list of node types to restrict the scan to.")
+      inputSchema: z42.object({
+        graphId: z42.string().describe("The graph ID"),
+        minConnections: z42.number().int().min(1).describe("Minimum number of children (parent edges; mesh cross-links excluded). Typical: 10 for hub detection, 11 to count only hubs that exceed the round-4 \u226410 threshold."),
+        nodeTypes: z42.array(z42.string()).optional().describe("Optional list of node types to restrict the scan to.")
       })
     },
     async ({ graphId, minConnections, nodeTypes }) => {
@@ -1846,7 +2001,7 @@ function registerListDenseNodes(server2, client2) {
 }
 
 // ../mcp-core/src/tools/list-node-connections.ts
-import { z as z41 } from "zod";
+import { z as z43 } from "zod";
 function registerListNodeConnections(server2, client2) {
   server2.registerTool(
     "naumu_list_node_connections",
@@ -1854,11 +2009,11 @@ function registerListNodeConnections(server2, client2) {
       title: "List Node Connections",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: 'Return a single node\'s edges (non-system) with the connected node on the other side; use during /restructure to confirm mini-hub candidates and verify reparenting outcomes. Filter with `edgeType` (relation label) and `direction` ("in" | "out" | "both", default both). Response: `{ node: {id,label,type}, edges: [{relation, direction, isParent, other: {id,label,type}}] }`.',
-      inputSchema: z41.object({
-        graphId: z41.string().describe("The graph ID"),
-        nodeId: z41.string().describe("The node ID to inspect"),
-        edgeType: z41.string().optional().describe('Restrict to a specific relation label (e.g. "ASSOCIATED_WITH"). Case-insensitive; non-alphanum chars are normalized.'),
-        direction: z41.enum(["in", "out", "both"]).optional().describe('Edge direction filter - "in" (incoming), "out" (outgoing), "both" (default).')
+      inputSchema: z43.object({
+        graphId: z43.string().describe("The graph ID"),
+        nodeId: z43.string().describe("The node ID to inspect"),
+        edgeType: z43.string().optional().describe('Restrict to a specific relation label (e.g. "ASSOCIATED_WITH"). Case-insensitive; non-alphanum chars are normalized.'),
+        direction: z43.enum(["in", "out", "both"]).optional().describe('Edge direction filter - "in" (incoming), "out" (outgoing), "both" (default).')
       })
     },
     async ({ graphId, nodeId, edgeType, direction }) => {
@@ -1876,7 +2031,7 @@ function registerListNodeConnections(server2, client2) {
 }
 
 // ../mcp-core/src/tools/reparent.ts
-import { z as z42 } from "zod";
+import { z as z44 } from "zod";
 function registerReparent(server2, client2) {
   server2.registerTool(
     "naumu_reparent",
@@ -1884,11 +2039,11 @@ function registerReparent(server2, client2) {
       title: "Reparent Node",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       description: 'Atomically swap a node\'s parent edge; use to move a child under a different parent (e.g. during /restructure to reparent children under newly-created mini-hubs). Deletes any existing `isParent: true` edges on the node and creates a new one to `newParentId` with relation `newRelation`. Preserves the node\'s id, content, attributes, and embedding - does NOT trigger embedding regeneration because only the parent edge changes. Idempotent: if the node already has the requested parent edge, response is `status: "skipped"`. Response shape: `{nodeId, oldParentId, newParentId, newRelation, status: "moved" | "skipped"}`.',
-      inputSchema: z42.object({
-        graphId: z42.string().describe("The graph ID"),
-        nodeId: z42.string().describe("The child node to reparent"),
-        newParentId: z42.string().describe("The new parent node id"),
-        newRelation: z42.string().describe('The new parent edge relation label (e.g. "PART_OF"). Must be valid per the schema for (child.type, relation, parent.type).')
+      inputSchema: z44.object({
+        graphId: z44.string().describe("The graph ID"),
+        nodeId: z44.string().describe("The child node to reparent"),
+        newParentId: z44.string().describe("The new parent node id"),
+        newRelation: z44.string().describe('The new parent edge relation label (e.g. "PART_OF"). Must be valid per the schema for (child.type, relation, parent.type).')
       })
     },
     async ({ graphId, nodeId, newParentId, newRelation }) => {
@@ -1904,7 +2059,7 @@ function registerReparent(server2, client2) {
 }
 
 // ../mcp-core/src/tools/batch-reparent.ts
-import { z as z43 } from "zod";
+import { z as z45 } from "zod";
 function registerBatchReparent(server2, client2) {
   server2.registerTool(
     "naumu_batch_reparent",
@@ -1912,11 +2067,11 @@ function registerBatchReparent(server2, client2) {
       title: "Batch Reparent Nodes",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       description: 'Reparent 1-25 nodes onto a shared `newParentId` with the same `newRelation`; use to move a same-typed cluster under a freshly-created mini-hub in /restructure. Same semantics as `naumu_reparent` per-node: atomic swap of the isParent edge, preserves id/content/attributes/embedding, no re-embedding. Idempotent per node (already-parented nodes return `status: "skipped"`). Per-node response array: `[{nodeId, oldParentId, newParentId, status: "moved" | "skipped" | "error", error?}]`.',
-      inputSchema: z43.object({
-        graphId: z43.string().describe("The graph ID"),
-        newParentId: z43.string().describe("Parent node id every nodeId in the batch will be parented to"),
-        newRelation: z43.string().describe("Parent edge relation label (must be valid per schema for child.type \u2192 parent.type)"),
-        nodeIds: z43.array(z43.string()).min(1).max(25).describe("1\u201325 child node ids to reparent under `newParentId`")
+      inputSchema: z45.object({
+        graphId: z45.string().describe("The graph ID"),
+        newParentId: z45.string().describe("Parent node id every nodeId in the batch will be parented to"),
+        newRelation: z45.string().describe("Parent edge relation label (must be valid per schema for child.type \u2192 parent.type)"),
+        nodeIds: z45.array(z45.string()).min(1).max(25).describe("1\u201325 child node ids to reparent under `newParentId`")
       })
     },
     async ({ graphId, newParentId, newRelation, nodeIds }) => {
@@ -1933,7 +2088,7 @@ function registerBatchReparent(server2, client2) {
 }
 
 // ../mcp-core/src/tools/chatgpt-search.ts
-import { z as z44 } from "zod";
+import { z as z46 } from "zod";
 
 // ../mcp-core/src/public-origin.ts
 function publicOrigin() {
@@ -1987,8 +2142,10 @@ function registerChatgptSearch(server2, client2) {
       title: "Search",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: "Search across all of the knowledge graphs (spaces) you can access and return the most relevant nodes. Returns `{ results: [{ id, title, url }] }`. Pass each result `id` to the `fetch` tool to read the full node. (This is the cross-space entry point for ChatGPT/Deep Research; within a single space, `naumu_search` exposes more controls.)",
-      inputSchema: z44.object({
-        query: z44.string().describe('Search query text. Mix synonyms and exact tokens freely (e.g. "auth login SSO 2fa").')
+      inputSchema: z46.object({
+        query: z46.string().describe(
+          "A short contiguous phrase \u2014 an entity name, label, or ID. The text half matches it verbatim as a case-insensitive substring; the semantic half matches meaning."
+        )
       })
     },
     async ({ query }) => {
@@ -2020,7 +2177,7 @@ function registerChatgptSearch(server2, client2) {
 }
 
 // ../mcp-core/src/tools/chatgpt-fetch.ts
-import { z as z45 } from "zod";
+import { z as z47 } from "zod";
 var NON_ATTRIBUTE_PROPS = /* @__PURE__ */ new Set([
   "id",
   "label",
@@ -2085,8 +2242,8 @@ function registerChatgptFetch(server2, client2) {
       title: "Fetch",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: "Fetch the full contents of a node returned by the `search` tool. Pass the result `id` verbatim (format `<graphId>:<nodeId>`). Returns `{ id, title, text, url }` where `text` is the node content plus its type, attributes, and connections.",
-      inputSchema: z45.object({
-        id: z45.string().describe("A resource id from a previous `search` result, in the form `<graphId>:<nodeId>`.")
+      inputSchema: z47.object({
+        id: z47.string().describe("A resource id from a previous `search` result, in the form `<graphId>:<nodeId>`.")
       })
     },
     async ({ id }) => {
@@ -2129,7 +2286,7 @@ function registerChatgptFetch(server2, client2) {
 }
 
 // ../mcp-core/src/tools/admission-status.ts
-import { z as z46 } from "zod";
+import { z as z48 } from "zod";
 function registerAdmissionStatus(server2, client2) {
   server2.registerTool(
     "naumu_admission_status",
@@ -2137,8 +2294,8 @@ function registerAdmissionStatus(server2, client2) {
       title: "Admission Status",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: "Show who can auto-join a Naumu space (graph) and who is waiting for approval: the whitelisted emails (people who join the moment they sign in with that email), the auto-join domain wildcards, and the count of pending join requests. When there are pending requests, this also returns the full list (who requested, their email, git-email hint, and message) so you can act on them with naumu_resolve_join_request. Use it during repo init to review or seed access, or whenever the user asks who has access to a space or who is asking to join.",
-      inputSchema: z46.object({
-        graphId: z46.string().describe("The space (graph) ID to inspect admission for. You must be a member of this space.")
+      inputSchema: z48.object({
+        graphId: z48.string().describe("The space (graph) ID to inspect admission for. You must be a member of this space.")
       })
     },
     async ({ graphId }) => {
@@ -2168,7 +2325,7 @@ function registerAdmissionStatus(server2, client2) {
 }
 
 // ../mcp-core/src/tools/whitelist-members.ts
-import { z as z47 } from "zod";
+import { z as z49 } from "zod";
 function registerWhitelistMembers(server2, client2) {
   server2.registerTool(
     "naumu_whitelist_members",
@@ -2181,10 +2338,10 @@ function registerWhitelistMembers(server2, client2) {
         openWorldHint: false
       },
       description: "Whitelist emails so those people auto-join a Naumu space (graph) the moment they sign in with that email. Use this during repo init: after you scrub git history, present the curated list of collaborators to the user, and get their explicit confirmation, call this with the confirmed emails. It is silent - it sends no invite emails, it just pre-authorizes those addresses. Returns which entries were created and which were skipped (already whitelisted or already members). Set repoInit true when this call is part of the repo init flow.",
-      inputSchema: z47.object({
-        graphId: z47.string().describe("The space (graph) ID to whitelist emails for. You must be a member of this space."),
-        emails: z47.array(z47.string()).min(1).describe("The emails to whitelist. Each becomes an exact-match auto-join entry. Present these to the user and get confirmation before calling."),
-        repoInit: z47.boolean().optional().describe("Set true when this whitelist is being seeded as part of the repo init flow, so onboarding is tracked correctly.")
+      inputSchema: z49.object({
+        graphId: z49.string().describe("The space (graph) ID to whitelist emails for. You must be a member of this space."),
+        emails: z49.array(z49.string()).min(1).describe("The emails to whitelist. Each becomes an exact-match auto-join entry. Present these to the user and get confirmation before calling."),
+        repoInit: z49.boolean().optional().describe("Set true when this whitelist is being seeded as part of the repo init flow, so onboarding is tracked correctly.")
       })
     },
     async ({ graphId, emails, repoInit }) => {
@@ -2208,7 +2365,7 @@ function registerWhitelistMembers(server2, client2) {
 }
 
 // ../mcp-core/src/tools/resolve-admission.ts
-import { z as z48 } from "zod";
+import { z as z50 } from "zod";
 function registerResolveAdmission(server2, client2) {
   server2.registerTool(
     "naumu_resolve_admission",
@@ -2221,9 +2378,9 @@ function registerResolveAdmission(server2, client2) {
         openWorldHint: false
       },
       description: "The call a coding agent makes right after connecting when a repo's .naumu references a space the user is not yet a member of. It evaluates whether the user can join and does it: outcome is joined-whitelist or joined-wildcard (the user is now a member - proceed), already-member (nothing to do), request-created (a join request was just filed and is awaiting a member's approval), or request-pending (a request was already open). When the response also carries reason 'seat-limit' on a request-created/request-pending outcome, the user WOULD have auto-joined via a whitelist/domain match but the space is at its seat limit - so their access is pending an admin approving them or upgrading the plan; relay that specific reason honestly, do not just say 'no match'. Pass gitEmailHint from `git config user.email` so a matching whitelist or domain rule can admit them. Relay the outcome to the user honestly: say plainly whether they joined or are waiting for approval - never imply access that is still pending.",
-      inputSchema: z48.object({
-        graphId: z48.string().describe("The space (graph) ID referenced by the repo .naumu file that the user wants to join."),
-        gitEmailHint: z48.string().optional().describe("The email from `git config user.email`, used to match whitelist entries and auto-join domains.")
+      inputSchema: z50.object({
+        graphId: z50.string().describe("The space (graph) ID referenced by the repo .naumu file that the user wants to join."),
+        gitEmailHint: z50.string().optional().describe("The email from `git config user.email`, used to match whitelist entries and auto-join domains.")
       })
     },
     async ({ graphId, gitEmailHint }) => {
@@ -2247,7 +2404,7 @@ function registerResolveAdmission(server2, client2) {
 }
 
 // ../mcp-core/src/tools/resolve-join-request.ts
-import { z as z49 } from "zod";
+import { z as z51 } from "zod";
 function registerResolveJoinRequest(server2, client2) {
   server2.registerTool(
     "naumu_resolve_join_request",
@@ -2260,10 +2417,10 @@ function registerResolveJoinRequest(server2, client2) {
         openWorldHint: false
       },
       description: "For a member resolving a pending join request surfaced by naumu_admission_status. Approve to add the requester to the space as a member, or deny to reject the request. Get the requestId from naumu_admission_status's pending list, and confirm the decision with the user before calling since approving grants access.",
-      inputSchema: z49.object({
-        graphId: z49.string().describe("The space (graph) ID the request is for. You must be a member of this space."),
-        requestId: z49.string().describe("The pending join request ID, taken from naumu_admission_status."),
-        action: z49.enum(["approve", "deny"]).describe("approve adds the requester as a member; deny rejects the request.")
+      inputSchema: z51.object({
+        graphId: z51.string().describe("The space (graph) ID the request is for. You must be a member of this space."),
+        requestId: z51.string().describe("The pending join request ID, taken from naumu_admission_status."),
+        action: z51.enum(["approve", "deny"]).describe("approve adds the requester as a member; deny rejects the request.")
       })
     },
     async ({ graphId, requestId, action }) => {
@@ -2313,9 +2470,16 @@ var TOOL_REGISTRARS = {
   naumu_whoami: registerWhoami,
   naumu_list_threads: registerListThreads,
   naumu_list_topics: registerListTopics,
+  // User-surface only. `POST /api/graphs/:id/topics` requires the ADMIN-only
+  // `space:manage-topics` permission, and bot identities always resolve to the
+  // editor role, so a bot calling this could only ever 403. It is therefore
+  // omitted from BOT_ONLY_TOOL_NAMES and has no entry in the backend
+  // PERMISSION_TO_MCP_TOOLS map (same treatment as the admission tools below).
+  naumu_create_topic: registerCreateTopic,
   naumu_get_thread: registerGetThread,
   naumu_create_thread: registerCreateThread,
   naumu_request_attachment_upload: registerRequestAttachmentUpload,
+  naumu_persist_canvas_attachment: registerPersistCanvasAttachment,
   naumu_add_reaction: registerAddReaction,
   naumu_remove_reaction: registerRemoveReaction,
   naumu_typing: registerNaumuTyping,
@@ -2389,7 +2553,7 @@ var client = new NaumuClient(apiUrl, apiKey);
 var server = new McpServer(
   {
     name: "naumu",
-    version: "0.4.0"
+    version: NAUMU_MCP_VERSION
   },
   {
     instructions: NAUMU_INSTRUCTIONS

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@naumu/mcp",
-	"version": "0.9.0",
+	"version": "0.11.0",
 	"description": "MCP server for Naumu – access your knowledge graph from Claude Code, Cursor, and other AI coding agents",
 	"license": "MIT",
 	"author": "Naumu <hello@naumu.ai>",