@creator-notes/cnotes 0.16.11 → 0.16.15

package/dist/mcp-server.js

@@ -10,9 +10,9 @@
 //         "command": "node",
 //         "args": ["/path/to/pm-notes/cli/dist/mcp-server.js"],
 //         "env": {
-//           "CN_SERVER": "https://your-codespace.app.github.dev",
-//           "CN_TOKEN": "your-token",
-//           "CN_WORKSPACE": "your-workspace-id"
+//           "CNOTES_SERVER": "https://your-codespace.app.github.dev",
+//           "CNOTES_TOKEN": "your-token",
+//           "CNOTES_WORKSPACE": "your-workspace-id"
 //         }
 //       }
 //     }
@@ -30,21 +30,21 @@ import { buildSchema } from "./lib/build-schema.js";
 // ---------------------------------------------------------------------------
 // Environment
 // ---------------------------------------------------------------------------
-const CN_SERVER = process.env.CN_SERVER;
-const CN_TOKEN = process.env.CN_TOKEN;
-const CN_WORKSPACE = process.env.CN_WORKSPACE;
-if (!CN_SERVER || !CN_TOKEN || !CN_WORKSPACE) {
+const CNOTES_SERVER = process.env.CNOTES_SERVER;
+const CNOTES_TOKEN = process.env.CNOTES_TOKEN;
+const CNOTES_WORKSPACE = process.env.CNOTES_WORKSPACE;
+if (!CNOTES_SERVER || !CNOTES_TOKEN || !CNOTES_WORKSPACE) {
     const missing = [
-        !CN_SERVER && "CN_SERVER",
-        !CN_TOKEN && "CN_TOKEN",
-        !CN_WORKSPACE && "CN_WORKSPACE",
+        !CNOTES_SERVER && "CNOTES_SERVER",
+        !CNOTES_TOKEN && "CNOTES_TOKEN",
+        !CNOTES_WORKSPACE && "CNOTES_WORKSPACE",
     ].filter(Boolean);
     process.stderr.write(`cnotes-mcp: missing required env vars: ${missing.join(", ")}\n` +
         "Set them in your Claude Desktop config or shell environment.\n");
     process.exit(1);
 }
-const api = new ApiClient(CN_SERVER, CN_TOKEN);
-const workspaceId = CN_WORKSPACE;
+const api = new ApiClient(CNOTES_SERVER, CNOTES_TOKEN);
+const workspaceId = CNOTES_WORKSPACE;
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -108,7 +108,7 @@ server.resource("types", "cnotes://types", async () => ({
 // ---------------------------------------------------------------------------
 // Notes tools
 // ---------------------------------------------------------------------------
-server.tool("cn_notes_list", "List notes in the workspace. Returns metadata by default. Set includeContent=true to include full note content (useful to avoid multiple cn_notes_get calls).", {
+server.tool("cnotes_notes_list", "List notes in the workspace. Returns metadata by default. Set includeContent=true to include full note content (useful to avoid multiple cnotes_notes_get calls).", {
     search: z.string().optional().describe("Full-text search query"),
     type: z.string().optional().describe("Filter by note type (e.g. Meeting, PRD)"),
     tags: z.string().optional().describe("Filter by tags (comma-separated)"),
@@ -126,7 +126,7 @@ server.tool("cn_notes_list", "List notes in the workspace. Returns metadata by d
     format: includeContent ? "markdown" : undefined,
     limit: String(limit ?? 20),
 })));
-server.tool("cn_notes_get", "Get one or more notes by display ID (e.g. MEETING-12, PRD-3). Always returns an array, in input order, in a single round-trip. Pass one ID for one note, or many IDs to batch-fetch — never call this tool multiple times in parallel for different IDs.", {
+server.tool("cnotes_notes_get", "Get one or more notes by display ID (e.g. MEETING-12, PRD-3). Always returns an array, in input order, in a single round-trip. Pass one ID for one note, or many IDs to batch-fetch — never call this tool multiple times in parallel for different IDs.", {
     ids: z
         .array(z.string())
         .min(1)
@@ -151,13 +151,13 @@ server.tool("cn_notes_get", "Get one or more notes by display ID (e.g. MEETING-1
     // Preserve input order.
     return ids.map((id) => byDisplayId.get(id));
 }));
-server.tool("cn_notes_delete", "Delete (archive) a note.", {
+server.tool("cnotes_notes_delete", "Delete (archive) a note.", {
     id: z.string().describe("Note display ID or Convex ID"),
 }, async ({ id }) => withErrorHandling(async () => {
     const noteId = await resolveNoteId(api, workspaceId, id);
     return api.delete(`/api/notes/${noteId}`);
 }));
-server.tool("cn_notes_bulk_archive", "Archive or unarchive multiple notes in one operation. More efficient than calling cn_notes_delete multiple times.", {
+server.tool("cnotes_notes_bulk_archive", "Archive or unarchive multiple notes in one operation. More efficient than calling cnotes_notes_delete multiple times.", {
     ids: z.array(z.string()).describe("Array of note display IDs or Convex IDs"),
     unarchive: z.boolean().optional().default(false).describe("Set true to unarchive instead of archive"),
 }, async ({ ids, unarchive }) => withErrorHandling(async () => {
@@ -168,7 +168,7 @@ server.tool("cn_notes_bulk_archive", "Archive or unarchive multiple notes in one
         isArchived: !unarchive,
     });
 }));
-server.tool("cn_notes_bulk_retype", "Retype multiple notes to a new type in one operation. Each note is atomically retyped (new note created, old archived, cross-linked).", {
+server.tool("cnotes_notes_bulk_retype", "Retype multiple notes to a new type in one operation. Each note is atomically retyped (new note created, old archived, cross-linked).", {
     ids: z.array(z.string()).describe("Array of note display IDs or Convex IDs to retype"),
     targetType: z.string().describe("Target type name (must be an existing supertag, e.g. 'Insight')"),
 }, async ({ ids, targetType }) => withErrorHandling(async () => {
@@ -179,7 +179,7 @@ server.tool("cn_notes_bulk_retype", "Retype multiple notes to a new type in one
         targetType,
     });
 }));
-server.tool("cn_notes_update", "Update note metadata (type, tags, pin/archive status). Does NOT change content — use cn_versions_create for that. Title is read-only (derived from # h1 heading in content).", {
+server.tool("cnotes_notes_update", "Update note metadata (type, tags, pin/archive status). Does NOT change content — use cnotes_versions_create for that. Title is read-only (derived from # h1 heading in content).", {
     id: z.string().describe("Note display ID or Convex ID"),
     type: z.string().optional().describe("New note type (must be an existing supertag, e.g. 'Insight')"),
     tags: z.string().optional().describe("Replace tags (comma-separated). Use empty string to clear."),
@@ -214,16 +214,43 @@ const NoteCreateItem = z.object({
     markdown: z.string().describe("Note content as markdown (the first # h1 heading becomes the title)"),
     tags: z.array(z.string()).optional().describe("Tags for this note"),
 });
-server.tool("cn_notes_create", "Create one or more interlinked notes in a single atomic transaction. Pass `notes` as a single item object or an array of items. Title is derived from the # h1 heading in each note's markdown. Relationship link syntax inside markdown: use [@key: Title](relationship:references) to cross-reference another note in the same batch (the @key is replaced with the new note's display ID after creation), or [NOTE-12: Title](relationship:references) to reference an existing note. ALWAYS include the `: Title` part — the title-less form `[NOTE-12](relationship:references)` saves a chip with `title: null` that renders as \"Untitled\" in the UI. The relationship name is free-form (e.g. references, supports, triggers); use `references` if unsure. If validation fails, the response includes a structured `details.items` array pinpointing which item (by index + key) is malformed and why.", {
+server.tool("cnotes_notes_create", "Create one or more interlinked notes in a single atomic transaction. Before authoring, read the target type's rubric (cnotes_types_show, or the validationPrompt field from cnotes_types_list) and write to it so the note lands well-formed. Pass `notes` as a single item object or an array of items. Title is derived from the # h1 heading in each note's markdown. Relationship link syntax inside markdown: use [@key: Title](relationship:references) to cross-reference another note in the same batch (the @key is replaced with the new note's display ID after creation), or [NOTE-12: Title](relationship:references) to reference an existing note. ALWAYS include the `: Title` part — the title-less form `[NOTE-12](relationship:references)` saves a chip with `title: null` that renders as \"Untitled\" in the UI. The relationship name is free-form (e.g. references, supports, triggers); use `references` if unsure. The response echoes each used type's rubric under `rubrics` — revise in-loop if a note falls short. If validation fails, the response includes a structured `details.items` array pinpointing which item (by index + key) is malformed and why.", {
     notes: z
         .union([NoteCreateItem, z.array(NoteCreateItem).min(1)])
         .describe("Either a single item object or a non-empty array of items."),
-}, async ({ notes }) => withErrorHandling(() => api.post("/api/notes/bulk", {
-    action: "bulkCreate",
-    workspaceId,
-    notes: Array.isArray(notes) ? notes : [notes],
-})));
-server.tool("cn_notes_retype", "Change a single note's type. Atomic operation: creates a new note with the target type, archives the old one, and cross-links both.", {
+}, async ({ notes }) => withErrorHandling(async () => {
+    const items = Array.isArray(notes) ? notes : [notes];
+    const result = await api.post("/api/notes/bulk", {
+        action: "bulkCreate",
+        workspaceId,
+        notes: items,
+    });
+    // A1 — echo the rubric for each type used so the agent sees the standard
+    // for what it just wrote and can revise in-loop. Zero LLM. Non-fatal: the
+    // create already succeeded if we got here.
+    try {
+        const supertags = await api.get("/api/supertags", {
+            workspaceId,
+        });
+        const byName = new Map();
+        for (const s of Array.isArray(supertags) ? supertags : []) {
+            const nm = String(s.name || "").toLowerCase();
+            if (nm && s.validationPrompt)
+                byName.set(nm, String(s.validationPrompt));
+        }
+        const rubrics = Array.from(new Set(items.map((n) => String(n.type))))
+            .map((t) => ({ type: t, rubric: byName.get(t.toLowerCase()) || "" }))
+            .filter((r) => r.rubric);
+        if (rubrics.length > 0 && result && typeof result === "object") {
+            result.rubrics = rubrics;
+        }
+    }
+    catch {
+        // Skip the rubric echo if supertags can't be fetched.
+    }
+    return result;
+}));
+server.tool("cnotes_notes_retype", "Change a single note's type. Atomic operation: creates a new note with the target type, archives the old one, and cross-links both.", {
     noteId: z.string().describe("Display ID of the note to retype (e.g. NOTE-1)"),
     targetType: z.string().describe("Target type name (must be an existing supertag)"),
 }, async ({ noteId, targetType }) => withErrorHandling(() => api.post("/api/notes/retype", {
@@ -234,7 +261,7 @@ server.tool("cn_notes_retype", "Change a single note's type. Atomic operation: c
 // ---------------------------------------------------------------------------
 // Search tools
 // ---------------------------------------------------------------------------
-server.tool("cn_search_semantic", "Semantic (vector) search across notes. Better for meaning-based queries.", {
+server.tool("cnotes_search_semantic", "Semantic (vector) search across notes. Better for meaning-based queries.", {
     query: z.string().describe("Search query"),
     limit: z.number().optional().default(10).describe("Max results"),
     canvasId: z.string().optional().describe("Scope search to notes on a canvas"),
@@ -247,26 +274,26 @@ server.tool("cn_search_semantic", "Semantic (vector) search across notes. Better
 // ---------------------------------------------------------------------------
 // Canvas tools
 // ---------------------------------------------------------------------------
-server.tool("cn_canvas_list", "List canvases in the workspace. Archived canvases are excluded by default.", {
+server.tool("cnotes_canvas_list", "List canvases in the workspace. Archived canvases are excluded by default.", {
     includeArchived: z.boolean().optional().default(false).describe("Include archived canvases"),
 }, async ({ includeArchived }) => withErrorHandling(() => api.get("/api/canvas", {
     workspaceId,
     ...(includeArchived ? { includeArchived: "true" } : {}),
 })));
-server.tool("cn_canvas_get", "Get canvas details including nodes, edges, and canvas links. Richtext node content is returned as markdown.", {
+server.tool("cnotes_canvas_get", "Get canvas details including nodes, edges, and canvas links. Richtext node content is returned as markdown.", {
     canvasId: z.string().describe("Canvas ID"),
 }, async ({ canvasId }) => withErrorHandling(() => api.get(`/api/canvas/${encodeURIComponent(canvasId)}`, { workspaceId, format: "markdown" })));
-server.tool("cn_canvas_read", "Read every note on a canvas as one concatenated markdown document, in display order (top-to-bottom, then left-to-right). Use this to think across a canvas in a single round-trip — preferred over canvas_get + N notes_get calls.", {
+server.tool("cnotes_canvas_read", "Read every note on a canvas as one concatenated markdown document, in display order (top-to-bottom, then left-to-right). Use this to think across a canvas in a single round-trip — preferred over canvas_get + N notes_get calls.", {
     canvasId: z.string().describe("Canvas ID"),
 }, async ({ canvasId }) => withErrorHandling(async () => readCanvasMarkdown(api, workspaceId, canvasId)));
-server.tool("cn_canvas_create", "Create a new canvas. Goal and target audience are required — every canvas must declare its purpose and who it serves.", {
+server.tool("cnotes_canvas_create", "Create a new canvas. Goal and target audience are required — every canvas must declare its purpose and who it serves.", {
     name: z.string().describe("Canvas name"),
     goal: z.string().describe("Canvas goal — the purpose, desired outcome, and what it should communicate (markdown). Required."),
     targetAudience: z.string().describe("Target audience — who this canvas is meant to serve or inform. Required."),
 }, async ({ name, goal, targetAudience }) => {
     return withErrorHandling(() => api.post("/api/canvas", { workspaceId, title: name, goal, targetAudience }));
 });
-server.tool("cn_canvas_update", "Update canvas metadata: title, goal (purpose/outcome), and/or target audience. Use this to set or change the intent metadata that guides agents working on this canvas.", {
+server.tool("cnotes_canvas_update", "Update canvas metadata: title, goal (purpose/outcome), and/or target audience. Use this to set or change the intent metadata that guides agents working on this canvas.", {
     canvasId: z.string().describe("Canvas ID"),
     title: z.string().optional().describe("New canvas title"),
     goal: z.string().optional().describe("Canvas goal — the purpose, desired outcome, and what it should communicate (markdown)"),
@@ -284,21 +311,21 @@ server.tool("cn_canvas_update", "Update canvas metadata: title, goal (purpose/ou
         body.targetAudience = targetAudience;
     return withErrorHandling(() => api.patch(`/api/canvas/${encodeURIComponent(canvasId)}`, body, { workspaceId }));
 });
-server.tool("cn_canvas_delete", "Delete a canvas.", {
+server.tool("cnotes_canvas_delete", "Delete a canvas.", {
     canvasId: z.string().describe("Canvas ID"),
 }, async ({ canvasId }) => withErrorHandling(() => api.delete(`/api/canvas/${canvasId}`)));
-server.tool("cn_canvas_archive", "Archive or unarchive a canvas. Archiving is a soft delete (sets archivedAt timestamp). Use unarchive=true to restore.", {
+server.tool("cnotes_canvas_archive", "Archive or unarchive a canvas. Archiving is a soft delete (sets archivedAt timestamp). Use unarchive=true to restore.", {
     canvasId: z.string().describe("Canvas ID"),
     unarchive: z.boolean().optional().default(false).describe("Set true to unarchive/restore instead of archive"),
 }, async ({ canvasId, unarchive }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
     action: unarchive ? "unarchive" : "archive",
 })));
-server.tool("cn_canvas_set_home", "Set a canvas as the workspace home/default canvas. Clears any previous home canvas.", {
+server.tool("cnotes_canvas_set_home", "Set a canvas as the workspace home/default canvas. Clears any previous home canvas.", {
     canvasId: z.string().describe("Canvas ID to set as home"),
 }, async ({ canvasId }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, { action: "setAsHome" })));
 // --- Deprecated single-item wrappers (delegate to bulk_add) ---
 // Kept for backward compatibility with existing MCP clients.
-server.tool("cn_canvas_add_node", "[Deprecated: use cn_canvas_bulk_add] Add a note to a canvas as a node.", {
+server.tool("cnotes_canvas_add_node", "[Deprecated: use cnotes_canvas_bulk_add] Add a note to a canvas as a node.", {
     canvasId: z.string().describe("Canvas ID"),
     noteId: z.string().describe("Note display ID or Convex ID"),
     x: z.number().optional().default(100).describe("X position"),
@@ -307,7 +334,7 @@ server.tool("cn_canvas_add_node", "[Deprecated: use cn_canvas_bulk_add] Add a no
     action: "bulkAddNodes",
     items: [{ type: "note", noteId, positionX: x, positionY: y }],
 })));
-server.tool("cn_canvas_add_text", "[Deprecated: use cn_canvas_bulk_add] Add a text annotation node to a canvas.", {
+server.tool("cnotes_canvas_add_text", "[Deprecated: use cnotes_canvas_bulk_add] Add a text annotation node to a canvas.", {
     canvasId: z.string().describe("Canvas ID"),
     text: z.string().describe("Text content"),
     size: z.enum(["heading", "paragraph"]).optional().default("heading").describe("Text size"),
@@ -318,9 +345,9 @@ server.tool("cn_canvas_add_text", "[Deprecated: use cn_canvas_bulk_add] Add a te
     action: "bulkAddNodes",
     items: [{ type: "text", content: text, fontSize: size === "paragraph" ? 18 : 32, colorVariant: color, positionX: x, positionY: y }],
 })));
-server.tool("cn_canvas_add_richtext", "[Deprecated: use cn_canvas_bulk_add] Add a richtext annotation node to a canvas.", {
+server.tool("cnotes_canvas_add_richtext", "[Deprecated: use cnotes_canvas_bulk_add] Add a richtext annotation node to a canvas.", {
     canvasId: z.string().describe("Canvas ID"),
-    content: z.string().describe("Richtext content as markdown. To link to notes, use [NOTE-123: Title](relationship:references)."),
+    content: z.string().describe("Richtext content as markdown. Plain markdown ONLY — do NOT use [NOTE-X](relationship:...) or [[...]] mention syntax here (it corrupts the card, which renders blank); reference notes as plain display IDs (\"see RISK-64\"). Keep it sticky-sized (≤ ~3 sentences): richtext is unversioned, unsearchable presentation furniture — knowledge worth keeping belongs in a typed note."),
     size: z.enum(["small", "medium", "large"]).optional().default("small").describe("Display size"),
     color: z.string().optional().describe("Background color hex"),
     x: z.number().optional().default(100).describe("X position"),
@@ -329,7 +356,7 @@ server.tool("cn_canvas_add_richtext", "[Deprecated: use cn_canvas_bulk_add] Add
     action: "bulkAddNodes",
     items: [{ type: "richtext", content, size, colorHex: color, positionX: x, positionY: y }],
 })));
-server.tool("cn_canvas_add_list", "[Deprecated: use cn_canvas_bulk_add] Add a list/grid node grouping notes on a canvas. The description is the only label; its first paragraph derives the searchable title.", {
+server.tool("cnotes_canvas_add_list", "[Deprecated: use cnotes_canvas_bulk_add] Add a list/grid node grouping notes on a canvas. The description is the only label; its first paragraph derives the searchable title.", {
     canvasId: z.string().describe("Canvas ID"),
     description: z.string().min(1).describe("Rich-text description (markdown). Required. First paragraph derives the searchable title."),
     noteIds: z.string().optional().describe("Comma-separated note IDs"),
@@ -347,7 +374,7 @@ server.tool("cn_canvas_add_list", "[Deprecated: use cn_canvas_bulk_add] Add a li
             positionY: y,
         }],
 })));
-server.tool("cn_canvas_add_link", "[Deprecated: use cn_canvas_bulk_add] Add a link to another canvas.", {
+server.tool("cnotes_canvas_add_link", "[Deprecated: use cnotes_canvas_bulk_add] Add a link to another canvas.", {
     canvasId: z.string().describe("Canvas ID"),
     targetCanvasId: z.string().describe("Target canvas ID to link to"),
     x: z.number().optional().default(100).describe("X position"),
@@ -357,7 +384,7 @@ server.tool("cn_canvas_add_link", "[Deprecated: use cn_canvas_bulk_add] Add a li
     items: [{ type: "canvas", linkedCanvasId: targetCanvasId, positionX: x, positionY: y }],
 })));
 // --- Primary bulk tool ---
-server.tool("cn_canvas_bulk_add", "Add one or more items to a canvas. Use this for ALL canvas additions — single or multiple. Supports all node types: note, text, richtext, list, canvas (link to another canvas), and edge. ALWAYS prefer this over repeated single-item calls. Items are processed in order so edges can reference nodes created earlier in the same batch via sourceItemIndex/targetItemIndex.", {
+server.tool("cnotes_canvas_bulk_add", "Add one or more items to a canvas. Use this for ALL canvas additions — single or multiple. Supports all node types: note, text, richtext, list, canvas (link to another canvas), and edge. ALWAYS prefer this over repeated single-item calls. Items are processed in order so edges can reference nodes created earlier in the same batch via sourceItemIndex/targetItemIndex.\n\nELEMENT CHOICE — notes are the knowledge tier (typed, versioned, searchable, the only content agents read back in full); everything else is presentation furniture. Default any claim/fact/decision/finding worth keeping to a typed NOTE. Use text for one-line section labels, richtext only for sticky-sized framing (orientation banners, emphasis quoting a note, image tiles — never the sole home of a claim), list for grouping member notes (description = one-line frame; N distinct things = N notes), canvas for portals, edge for note-to-note relationships (notes only — text/richtext endpoints fail; mirror the relationship as a mention in the note bodies).", {
     canvasId: z.string().describe("Canvas ID"),
     notes: z.array(z.object({
         noteId: z.string().describe("Note display ID or Convex ID"),
@@ -381,7 +408,7 @@ server.tool("cn_canvas_bulk_add", "Add one or more items to a canvas. Use this f
         }),
         z.object({
             type: z.literal("richtext"),
-            content: z.string().describe("Markdown content. To link to notes, use [NOTE-123: Title](relationship:references)."),
+            content: z.string().describe("Markdown content. Plain markdown ONLY — no [NOTE-X](relationship:...) / [[...]] mention syntax (corrupts the card); reference notes as plain display IDs. Sticky-sized (≤ ~3 sentences); knowledge worth keeping goes in a note."),
             x: z.number().describe("X position"),
             y: z.number().describe("Y position"),
             size: z.enum(["small", "medium", "large"]).optional().describe("Node size"),
@@ -389,7 +416,7 @@ server.tool("cn_canvas_bulk_add", "Add one or more items to a canvas. Use this f
         }),
         z.object({
             type: z.literal("list"),
-            description: z.string().min(1).describe("Rich-text description (markdown). Required. First paragraph derives the searchable title — this is the only label for list nodes."),
+            description: z.string().min(1).describe("One-line FRAME (markdown). Required. First paragraph derives the searchable title — this is the only label for list nodes. The CONTENT of a list is its member notes (noteIds), never the description: N distinct things = N typed notes grouped here. No mention syntax."),
             x: z.number().describe("X position"),
             y: z.number().describe("Y position"),
             viewMode: z.enum(["list", "grid"]).optional(),
@@ -439,14 +466,14 @@ server.tool("cn_canvas_bulk_add", "Add one or more items to a canvas. Use this f
         items: allItems,
     });
 }));
-server.tool("cn_canvas_place", "Place items on a canvas using a DECLARATIVE LAYOUT (no x/y math). The server measures every item, packs them with no overlaps, and inserts them in a single batch. PREFER THIS over cn_canvas_bulk_add whenever you can express the layout as stacks/grids/anchors — which is almost always. The agent should describe STRUCTURE (rows, columns, what's near what), not pixel coordinates.\n\nThe call is best-effort, NOT atomic: per-item failures are reported in the response (HTTP 207) but the items that succeeded stay on the canvas. Always inspect `items[].error` and `edges[].error` in the response.\n\nThe `doc` argument is a layout document:\n  { root: <LayoutNode>, edges?: [{from, to, label?}], origin?: {x, y} }\n\n<LayoutNode> is one of:\n  • { kind: 'stack',  axis: 'vertical'|'horizontal', gap?: 'tight'|'medium'|'spacious'|<px>, align?: 'start'|'center'|'end', items: [<LayoutNode>...] }\n  • { kind: 'grid',   columns: <n>, gap?: ..., items: [<LayoutNode>...] }\n  • { kind: 'anchor', to: '<displayId or canvas node id>', direction: 'right'|'left'|'above'|'below', gap?: ..., child: <LayoutNode> }\n  • { kind: 'item',   type: 'note'|'text'|'richtext'|'list'|'canvas', key?: '<name>', ...item-specific fields }\n\nLeaf item shapes (no x/y!):\n  note:     { kind:'item', type:'note', noteId:'NOTE-3', key?:'a' }\n  text:     { kind:'item', type:'text', content:'Hello', fontSize?:32, colorVariant?:'normal'|'muted'|'highlighted' }\n  richtext: { kind:'item', type:'richtext', content:'# Markdown OK', size?:'small'|'medium'|'large', colorHex?:'#3B82F6' }\n  list:     { kind:'item', type:'list', name:'My list', noteIds?:['NOTE-1','NOTE-2'], viewMode?:'list'|'grid' }\n  canvas:   { kind:'item', type:'canvas', linkedCanvasId:'<id>' }\n\nEdges reference endpoints by, in priority order: `@<key>` (any item with a `key` placed in the same call), the original noteId/displayId of a note placed in this call (e.g. 'NOTE-7'), or the displayId / convex id of a node already on the canvas.\n\nExample (a SWOT-like quadrant):\n  {\n    root: {\n      kind:'stack', axis:'vertical', gap:'spacious',\n      items:[\n        { kind:'stack', axis:'horizontal', gap:'spacious', items:[\n          { kind:'grid', columns:2, items:[\n            { kind:'item', type:'note', noteId:'STR-1' },\n            { kind:'item', type:'note', noteId:'STR-2' },\n          ]},\n          { kind:'grid', columns:2, items:[\n            { kind:'item', type:'note', noteId:'WEAK-1' },\n          ]},\n        ]},\n        { kind:'stack', axis:'horizontal', gap:'spacious', items:[ /* opportunities + threats */ ]},\n      ],\n    },\n  }", {
+server.tool("cnotes_canvas_place", "Place items on a canvas using a DECLARATIVE LAYOUT (no x/y math). The server measures every item, packs them with no overlaps, and inserts them in a single batch. PREFER THIS over cnotes_canvas_bulk_add whenever you can express the layout as stacks/grids/anchors — which is almost always. The agent should describe STRUCTURE (rows, columns, what's near what), not pixel coordinates.\n\nELEMENT CHOICE: default content to typed NOTES (the only versioned, searchable tier agents can read back); text = one-line labels, richtext = sticky-sized framing only, list = member notes behind a one-line frame, edges connect notes only.\n\nThe call is best-effort, NOT atomic: per-item failures are reported in the response (HTTP 207) but the items that succeeded stay on the canvas. Always inspect `items[].error` and `edges[].error` in the response.\n\nThe `doc` argument is a layout document:\n  { root: <LayoutNode>, edges?: [{from, to, label?}], origin?: {x, y} }\n\n<LayoutNode> is one of:\n  • { kind: 'stack',  axis: 'vertical'|'horizontal', gap?: 'tight'|'medium'|'spacious'|<px>, align?: 'start'|'center'|'end', items: [<LayoutNode>...] }\n  • { kind: 'grid',   columns: <n>, gap?: ..., items: [<LayoutNode>...] }\n  • { kind: 'anchor', to: '<displayId or canvas node id>', direction: 'right'|'left'|'above'|'below', gap?: ..., child: <LayoutNode> }\n  • { kind: 'item',   type: 'note'|'text'|'richtext'|'list'|'canvas', key?: '<name>', ...item-specific fields }\n\nLeaf item shapes (no x/y!):\n  note:     { kind:'item', type:'note', noteId:'NOTE-3', key?:'a' }\n  text:     { kind:'item', type:'text', content:'Hello', fontSize?:32, colorVariant?:'normal'|'muted'|'highlighted' }  // one-line section labels only\n  richtext: { kind:'item', type:'richtext', content:'# Markdown OK', size?:'small'|'medium'|'large', colorHex?:'<hex>' }  // sticky-sized framing only; plain markdown, NO [NOTE-X](relationship:...) mention syntax (corrupts the card); knowledge worth keeping = a note\n  list:     { kind:'item', type:'list', description:'One-line frame — first paragraph becomes the title', noteIds?:['NOTE-1','NOTE-2'], viewMode?:'list'|'grid' }  // description is REQUIRED and is a frame, never the content: N distinct things = N notes in noteIds\n  canvas:   { kind:'item', type:'canvas', linkedCanvasId:'<id>' }\n\nEdges reference endpoints by, in priority order: `@<key>` (any item with a `key` placed in the same call), the original noteId/displayId of a note placed in this call (e.g. 'NOTE-7'), or the displayId / convex id of a node already on the canvas.\n\nExample (a SWOT-like quadrant):\n  {\n    root: {\n      kind:'stack', axis:'vertical', gap:'spacious',\n      items:[\n        { kind:'stack', axis:'horizontal', gap:'spacious', items:[\n          { kind:'grid', columns:2, items:[\n            { kind:'item', type:'note', noteId:'STR-1' },\n            { kind:'item', type:'note', noteId:'STR-2' },\n          ]},\n          { kind:'grid', columns:2, items:[\n            { kind:'item', type:'note', noteId:'WEAK-1' },\n          ]},\n        ]},\n        { kind:'stack', axis:'horizontal', gap:'spacious', items:[ /* opportunities + threats */ ]},\n      ],\n    },\n  }", {
     canvasId: z.string().describe("Canvas ID"),
     doc: z.any().describe("Layout document. See tool description for shape."),
 }, async ({ canvasId, doc }) => withErrorHandling(() => api.post(`/api/canvas/${encodeURIComponent(canvasId)}?workspaceId=${encodeURIComponent(workspaceId)}`, {
     action: "placeLayout",
     doc,
 })));
-server.tool("cn_canvas_bulk_move", "Move multiple nodes to new positions in one operation. More efficient than calling cn_canvas_move_node multiple times.", {
+server.tool("cnotes_canvas_bulk_move", "Move multiple nodes to new positions in one operation. More efficient than calling cnotes_canvas_move_node multiple times.", {
     canvasId: z.string().describe("Canvas ID"),
     moves: z.array(z.object({
         nodeId: z.string().describe("Canvas node ID"),
@@ -463,14 +490,14 @@ server.tool("cn_canvas_bulk_move", "Move multiple nodes to new positions in one
         positionY: m.y,
     })),
 })));
-server.tool("cn_canvas_bulk_remove", "Remove multiple nodes from a canvas in one operation. More efficient than calling cn_canvas_remove_node multiple times.", {
+server.tool("cnotes_canvas_bulk_remove", "Remove multiple nodes from a canvas in one operation. More efficient than calling cnotes_canvas_remove_node multiple times.", {
     canvasId: z.string().describe("Canvas ID"),
     nodeIds: z.array(z.string()).describe("Array of node IDs to remove"),
 }, async ({ canvasId, nodeIds }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
     action: "bulkRemoveNodes",
     nodeIds,
 })));
-server.tool("cn_canvas_add_edge", "Connect two nodes on a canvas with an edge. Defaults to an arrow at the target end and a solid line.", {
+server.tool("cnotes_canvas_add_edge", "Connect two nodes on a canvas with an edge. Defaults to an arrow at the target end and a solid line.", {
     canvasId: z.string().describe("Canvas ID"),
     sourceNodeId: z.string().describe("Source node ID"),
     targetNodeId: z.string().describe("Target node ID"),
@@ -494,7 +521,7 @@ server.tool("cn_canvas_add_edge", "Connect two nodes on a canvas with an edge. D
         lineStyle,
     });
 }));
-server.tool("cn_canvas_update_edge", "Update an edge: change its label, toggle arrowheads, switch line style, or reverse direction. Only the fields you pass are changed.", {
+server.tool("cnotes_canvas_update_edge", "Update an edge: change its label, toggle arrowheads, switch line style, or reverse direction. Only the fields you pass are changed.", {
     canvasId: z.string().describe("Canvas ID"),
     edgeId: z.string().describe("Canvas edge ID"),
     label: z
@@ -523,7 +550,7 @@ server.tool("cn_canvas_update_edge", "Update an edge: change its label, toggle a
         body.reverse = reverse;
     return api.post(`/api/canvas/${canvasId}`, body);
 }));
-server.tool("cn_canvas_move_node", "Move a node to a new position on a canvas.", {
+server.tool("cnotes_canvas_move_node", "Move a node to a new position on a canvas.", {
     canvasId: z.string().describe("Canvas ID"),
     nodeId: z.string().describe("Canvas node ID"),
     nodeType: z.enum(["note", "text", "list", "canvas", "richtext"]).optional().default("note").describe("Node type"),
@@ -536,27 +563,27 @@ server.tool("cn_canvas_move_node", "Move a node to a new position on a canvas.",
     positionX: x,
     positionY: y,
 })));
-server.tool("cn_canvas_remove_node", "Remove a node from a canvas.", {
+server.tool("cnotes_canvas_remove_node", "Remove a node from a canvas.", {
     canvasId: z.string().describe("Canvas ID"),
     nodeId: z.string().describe("Canvas node ID"),
 }, async ({ canvasId, nodeId }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
     action: "removeNode",
     nodeId,
 })));
-server.tool("cn_canvas_remove_edge", "Remove an edge from a canvas.", {
+server.tool("cnotes_canvas_remove_edge", "Remove an edge from a canvas.", {
     canvasId: z.string().describe("Canvas ID"),
     edgeId: z.string().describe("Canvas edge ID"),
 }, async ({ canvasId, edgeId }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
     action: "removeEdge",
     edgeId,
 })));
-server.tool("cn_canvas_digest", "Get the AI-generated digest of a canvas: narrative summary, key themes, and a per-note summary list covering every note on the canvas. Run this first when starting work on any canvas — it gives you full orientation in a single call, so you don't need to read each note individually. Each note entry has shape { displayId, title, type, summary }; when summary is null the AI summary hasn't generated yet. The notes list is always populated, even when digest status is 'none' or 'stale'.", {
+server.tool("cnotes_canvas_digest", "Get the AI-generated digest of a canvas: narrative summary, key themes, and a per-note summary list covering every note on the canvas. Run this first when starting work on any canvas — it gives you full orientation in a single call, so you don't need to read each note individually. Each note entry has shape { displayId, title, type, summary }; when summary is null the AI summary hasn't generated yet. The notes list is always populated, even when digest status is 'none' or 'stale'.", {
     canvasId: z.string().describe("Canvas ID"),
 }, async ({ canvasId }) => withErrorHandling(() => api.get(`/api/canvas/${encodeURIComponent(canvasId)}/digest`, { workspaceId })));
-server.tool("cn_canvas_digest_generate", "Request digest (re)generation for a canvas. Use when digest status is 'none' or you want a fresh summary. The digest is generated async — poll cn_canvas_digest after ~60s.", {
+server.tool("cnotes_canvas_digest_generate", "Request digest (re)generation for a canvas. Use when digest status is 'none' or you want a fresh summary. The digest is generated async — poll cnotes_canvas_digest after ~60s.", {
     canvasId: z.string().describe("Canvas ID"),
 }, async ({ canvasId }) => withErrorHandling(() => api.post(`/api/canvas/${encodeURIComponent(canvasId)}/digest?workspaceId=${encodeURIComponent(workspaceId)}`, {})));
-server.tool("cn_canvas_activity", "Show recent activity on a canvas — edits, agent runs, gestures, restores — newest first. Use this to find out what changed and who changed it before making further edits, or to confirm a previous agent run actually applied. Returns { canvasName, operations: Array<{ _id, operationType, actorName, actorSource ('human'|'agent'|'import'|'api'), agentRunId, userPrompt, status ('in_progress'|'applied'|'reverted'|'failed'), eventCount, affectedEntityIds, summary, structuredSummary: { headline, summary, byCategory[], themes[] }, startedAt, completedAt }>}.", {
+server.tool("cnotes_canvas_activity", "Show recent activity on a canvas — edits, agent runs, gestures, restores — newest first. Use this to find out what changed and who changed it before making further edits, or to confirm a previous agent run actually applied. Returns { canvasName, operations: Array<{ _id, operationType, actorName, actorSource ('human'|'agent'|'import'|'api'), agentRunId, userPrompt, status ('in_progress'|'applied'|'reverted'|'failed'), eventCount, affectedEntityIds, summary, structuredSummary: { headline, summary, byCategory[], themes[] }, startedAt, completedAt }>}.", {
     canvasId: z.string().describe("Canvas ID"),
     limit: z.number().int().min(1).max(200).optional().describe("Max entries (default 50, max 200)"),
 }, async ({ canvasId, limit }) => {
@@ -565,8 +592,8 @@ server.tool("cn_canvas_activity", "Show recent activity on a canvas — edits, a
         params.limit = String(limit);
     return withErrorHandling(() => api.get(`/api/canvas/${encodeURIComponent(canvasId)}/activity`, params));
 });
-server.tool("cn_canvas_templates", "List available canvas templates.", {}, async () => withErrorHandling(() => api.get("/api/canvas/template")));
-server.tool("cn_canvas_from_template", "Create a canvas from a predefined template.", {
+server.tool("cnotes_canvas_templates", "List available canvas templates.", {}, async () => withErrorHandling(() => api.get("/api/canvas/template")));
+server.tool("cnotes_canvas_from_template", "Create a canvas from a predefined template.", {
     templateId: z.string().describe("Template ID"),
     title: z.string().optional().describe("Custom canvas title"),
 }, async ({ templateId, title }) => withErrorHandling(() => api.post("/api/canvas/template", {
@@ -577,7 +604,7 @@ server.tool("cn_canvas_from_template", "Create a canvas from a predefined templa
 // ---------------------------------------------------------------------------
 // Timeline
 // ---------------------------------------------------------------------------
-server.tool("cn_timeline", "Show recent changes across notes. Supports relative time (7d, 2w) or ISO dates.", {
+server.tool("cnotes_timeline", "Show recent changes across notes. Supports relative time (7d, 2w) or ISO dates.", {
     since: z.string().optional().default("7d").describe("Start of range (e.g. 7d, 2w, 2026-03-21)"),
     until: z.string().optional().describe("End of range (default: now)"),
     type: z.string().optional().describe("Filter by note type (comma-separated)"),
@@ -618,8 +645,30 @@ function parseDuration(input) {
 // ---------------------------------------------------------------------------
 // Types (supertags)
 // ---------------------------------------------------------------------------
-server.tool("cn_types_list", "List note types (supertags) in the workspace.", {}, async () => withErrorHandling(() => api.get("/api/supertags", { workspaceId })));
-server.tool("cn_types_create", "Create a new note type (supertag).", {
+server.tool("cnotes_types_list", "List note types (supertags) in the workspace. Each entry carries a `validationPrompt` (its quality rubric — what a good instance contains); read it before authoring.", {}, async () => withErrorHandling(() => api.get("/api/supertags", { workspaceId })));
+server.tool("cnotes_types_show", "Show one note type's quality rubric (validationPrompt) — what a good instance of that type contains. Read this BEFORE authoring a note of this type so it lands well-formed.", {
+    name: z.string().describe("Type name (e.g. 'Decision', 'Insight')"),
+}, async ({ name }) => withErrorHandling(async () => {
+    const list = await api.get("/api/supertags", { workspaceId });
+    const want = name.trim().toLowerCase();
+    const match = (Array.isArray(list) ? list : []).find((s) => String(s.name || "").toLowerCase() === want ||
+        String(s.displayName || "").toLowerCase() === want);
+    if (!match) {
+        return {
+            error: `Type "${name}" not found`,
+            hint: "Call cnotes_types_list to see valid type names.",
+        };
+    }
+    return {
+        name: match.name,
+        displayName: match.displayName,
+        prefix: match.prefix,
+        description: match.description ?? null,
+        rubric: match.validationPrompt ?? null,
+        validationEnabled: match.validationEnabled ?? false,
+    };
+}));
+server.tool("cnotes_types_create", "Create a new note type (supertag).", {
     name: z.string().describe("Type name, PascalCase, no spaces (e.g. PainPoint, UserStory)"),
     displayName: z.string().optional().describe("Display name (can have spaces)"),
     prefix: z.string().optional().describe("ID prefix, uppercase (e.g. PAINPOINT, USERSTORY)"),
@@ -633,7 +682,7 @@ server.tool("cn_types_create", "Create a new note type (supertag).", {
     description,
     color,
 })));
-server.tool("cn_types_update", "Update a note type (supertag).", {
+server.tool("cnotes_types_update", "Update a note type (supertag).", {
     name: z.string().describe("Type name to update"),
     displayName: z.string().optional().describe("New display name"),
     prefix: z.string().optional().describe("New ID prefix (uppercase)"),
@@ -654,7 +703,7 @@ server.tool("cn_types_update", "Update a note type (supertag).", {
 // ---------------------------------------------------------------------------
 // Relationships
 // ---------------------------------------------------------------------------
-server.tool("cn_relationships_list", "List note relationships in the workspace.", {
+server.tool("cnotes_relationships_list", "List note relationships in the workspace.", {
     noteDisplayId: z.string().optional().describe("Filter by note display ID"),
 }, async ({ noteDisplayId }) => withErrorHandling(() => api.get("/api/relationships", {
     workspaceId,
@@ -663,7 +712,7 @@ server.tool("cn_relationships_list", "List note relationships in the workspace."
 // ---------------------------------------------------------------------------
 // Memory (Zep)
 // ---------------------------------------------------------------------------
-server.tool("cn_memory_query", "Search facts and entities in the knowledge graph by relevance.", {
+server.tool("cnotes_memory_query", "Search facts and entities in the knowledge graph by relevance.", {
     query: z.string().describe("Search query"),
     limit: z.number().optional().default(10).describe("Max results per category"),
 }, async ({ query, limit }) => withErrorHandling(() => api.post("/api/zep/query", {
@@ -671,7 +720,7 @@ server.tool("cn_memory_query", "Search facts and entities in the knowledge graph
     query,
     limit: limit ?? 10,
 })));
-server.tool("cn_memory_facts", "List all workspace facts from the knowledge graph.", {}, async () => withErrorHandling(async () => {
+server.tool("cnotes_memory_facts", "List all workspace facts from the knowledge graph.", {}, async () => withErrorHandling(async () => {
     const data = await api.post("/api/zep/query", {
         workspaceId,
         query: "all facts",
@@ -679,7 +728,7 @@ server.tool("cn_memory_facts", "List all workspace facts from the knowledge grap
     });
     return data.allFacts;
 }));
-server.tool("cn_memory_entities", "List all workspace entities (people, topics, orgs) from the knowledge graph.", {}, async () => withErrorHandling(async () => {
+server.tool("cnotes_memory_entities", "List all workspace entities (people, topics, orgs) from the knowledge graph.", {}, async () => withErrorHandling(async () => {
     const data = await api.post("/api/zep/query", {
         workspaceId,
         query: "all entities",
@@ -690,7 +739,7 @@ server.tool("cn_memory_entities", "List all workspace entities (people, topics,
 // ---------------------------------------------------------------------------
 // Versions
 // ---------------------------------------------------------------------------
-server.tool("cn_versions_list", "List versions of a note.", {
+server.tool("cnotes_versions_list", "List versions of a note.", {
     noteId: z.string().describe("Note display ID or Convex ID"),
 }, async ({ noteId }) => withErrorHandling(async () => {
     const notesList = await api.get("/api/notes", {
@@ -703,7 +752,7 @@ server.tool("cn_versions_list", "List versions of a note.", {
         throw new Error(`Note not found: ${noteId}`);
     return note.versions || [];
 }));
-server.tool("cn_versions_create", "Create a new version of a note. Content is markdown. To link to other notes, use [NOTE-123: Title](relationship:references) inside the markdown — always include the title (the part after the colon) or the chip renders as 'Untitled'. The relationship name is free-form (e.g. references, triggers, caused-by); use 'references' if unsure.", {
+server.tool("cnotes_versions_create", "Create a new version of a note. Content is markdown. To link to other notes, use [NOTE-123: Title](relationship:references) inside the markdown — always include the title (the part after the colon) or the chip renders as 'Untitled'. The relationship name is free-form (e.g. references, triggers, caused-by); use 'references' if unsure.", {
     noteId: z.string().describe("Note display ID or Convex ID"),
     markdown: z.string().describe("New content as markdown"),
     description: z.string().describe("Change description (required)"),
@@ -717,8 +766,8 @@ server.tool("cn_versions_create", "Create a new version of a note. Content is ma
 // ---------------------------------------------------------------------------
 // Workspace
 // ---------------------------------------------------------------------------
-server.tool("cn_workspace_list", "List all workspaces the authenticated user belongs to.", {}, async () => withErrorHandling(() => api.get("/api/workspaces")));
-server.tool("cn_workspace_current", "Get details about the current workspace.", {}, async () => withErrorHandling(() => api.get(`/api/workspaces/${workspaceId}`)));
+server.tool("cnotes_workspace_list", "List all workspaces the authenticated user belongs to.", {}, async () => withErrorHandling(() => api.get("/api/workspaces")));
+server.tool("cnotes_workspace_current", "Get details about the current workspace.", {}, async () => withErrorHandling(() => api.get(`/api/workspaces/${workspaceId}`)));
 // ---------------------------------------------------------------------------
 // Files
 // ---------------------------------------------------------------------------
@@ -729,7 +778,7 @@ const FILE_MIME_MAP = {
     ".gif": "image/gif",
     ".webp": "image/webp",
 };
-server.tool("cn_files_upload", "Upload an image file to the workspace. Returns the public URL. Supports .jpg, .jpeg, .png, .gif, .webp (max 5MB).", {
+server.tool("cnotes_files_upload", "Upload an image file to the workspace. Returns the public URL. Supports .jpg, .jpeg, .png, .gif, .webp (max 5MB).", {
     filePath: z.string().describe("Absolute path to the image file on disk"),
 }, async ({ filePath }) => withErrorHandling(async () => {
     const absPath = path.resolve(filePath);
@@ -759,14 +808,14 @@ server.tool("cn_files_upload", "Upload an image file to the workspace. Returns t
     const result = await api.postFormData("/api/upload-image", buildFormData);
     return {
         ...result,
-        fullUrl: `${CN_SERVER}${result.url}`,
-        markdown: `![${filename}](${CN_SERVER}${result.url})`,
+        fullUrl: `${CNOTES_SERVER}${result.url}`,
+        markdown: `![${filename}](${CNOTES_SERVER}${result.url})`,
     };
 }));
 // ---------------------------------------------------------------------------
 // Schema
 // ---------------------------------------------------------------------------
-server.tool("cn_schema", "Describe this workspace in one call: valid note types (with prefixes), common relationship slugs, resource field shapes, and the canvas node kinds. Call this once at the start of a session instead of guessing type names or reading docs.", {}, async () => withErrorHandling(() => buildSchema(api, workspaceId)));
+server.tool("cnotes_schema", "Describe this workspace in one call: valid note types (with prefixes), common relationship slugs, resource field shapes, and the canvas node kinds. Call this once at the start of a session instead of guessing type names or reading docs.", {}, async () => withErrorHandling(() => buildSchema(api, workspaceId)));
 // ---------------------------------------------------------------------------
 // Start
 // ---------------------------------------------------------------------------