collabmd 0.1.49 → 0.1.52

package/src/domain/agent-tool-definitions.js

@@ -8,12 +8,6 @@ const REVISION_SCHEMA = {
   type: 'string',
 };
 
-const DOCUMENT_SCHEMA = objectSchema({
-  kind: { type: 'string' },
-  mtimeMs: { minimum: 0, type: 'number' },
-  path: { type: 'string' },
-  size: { minimum: 0, type: 'number' },
-});
 const WORKSPACE_ENTRY_SCHEMA = objectSchema({
   agentEditable: { type: 'boolean' },
   embeddable: { type: 'boolean' },
@@ -55,6 +49,15 @@ const VALIDATION_ISSUE_SCHEMA = objectSchema({
   target: { type: 'string' },
 });
 
+const MARKDOWN_VALIDATION_SCHEMA = objectSchema({
+  issues: { items: VALIDATION_ISSUE_SCHEMA, type: 'array' },
+  valid: { type: 'boolean' },
+});
+const VALIDATE_MARKDOWN_INPUT = {
+  description: 'Return reference validation for the exact saved revision. Markdown only; validation issues do not roll back the save.',
+  type: 'boolean',
+};
+
 const DIAGRAM_RENDER_OUTPUT_PROPERTIES = {
   endLine: { minimum: 1, type: 'integer' },
   format: { enum: ['png', 'svg'], type: 'string' },
@@ -208,6 +211,12 @@ const EXCALIDRAW_SUMMARY_ELEMENT_SCHEMA = {
     },
     endElementId: { type: 'string' },
     containerId: { type: 'string' },
+    fontFamily: {
+      description: 'Excalidraw font-family identifier. Standard Excalifont is 5; legacy Virgil is 1.',
+      minimum: 1,
+      type: 'integer',
+    },
+    fontName: { type: 'string' },
     fontSize: { exclusiveMinimum: 0, type: 'number' },
     height: { minimum: 0, type: 'number' },
     id: { type: 'string' },
@@ -242,7 +251,16 @@ const EXCALIDRAW_INSPECTION_PROPERTIES = {
   bounds: EXCALIDRAW_BOUNDS_SCHEMA,
   elementCount: { minimum: 0, type: 'integer' },
   elements: { items: EXCALIDRAW_SUMMARY_ELEMENT_SCHEMA, type: 'array' },
+  layout: objectSchema({
+    boundText: objectSchema({
+      misaligned: { minimum: 0, type: 'integer' },
+      outsideContainer: { minimum: 0, type: 'integer' },
+      staleHeight: { minimum: 0, type: 'integer' },
+      total: { minimum: 0, type: 'integer' },
+    }),
+  }),
   truncated: { type: 'boolean' },
+  valid: { type: 'boolean' },
   warnings: { items: EXCALIDRAW_WARNING_SCHEMA, type: 'array' },
 };
 const EXCALIDRAW_INSPECTION_SCHEMA = objectSchema(EXCALIDRAW_INSPECTION_PROPERTIES);
@@ -262,11 +280,6 @@ const EXCALIDRAW_RENDER_RESULT_PROPERTIES = {
   warnings: { items: { type: 'string' }, type: 'array' },
   width: { minimum: 1, type: 'integer' },
 };
-const EXCALIDRAW_RENDER_OUTPUT_PROPERTIES = {
-  ...EXCALIDRAW_RENDER_RESULT_PROPERTIES,
-  path: { type: 'string' },
-  revision: REVISION_SCHEMA,
-};
 const EXCALIDRAW_RENDER_INPUT_PROPERTIES = {
   format: {
     description: 'Image format. PNG is most widely supported by MCP clients.',
@@ -285,6 +298,10 @@ const EXCALIDRAW_RENDER_INPUT_PROPERTIES = {
     minLength: 1,
     type: 'string',
   },
+  render: {
+    description: 'Return an image render. Set false for a compact structural and layout verification response.',
+    type: 'boolean',
+  },
   scale: {
     description: 'Requested output scale; automatically reduced when needed to stay within 4096 pixels.',
     maximum: 4,
@@ -309,11 +326,29 @@ const EXCALIDRAW_INLINE_VERIFICATION_SCHEMA = objectSchema({
   inspection: EXCALIDRAW_INSPECTION_SCHEMA,
   ...EXCALIDRAW_RENDER_RESULT_PROPERTIES,
 }, ['inspection']);
+const EXCALIDRAW_COMPACT_VERIFICATION_PROPERTIES = {
+  elementCount: { minimum: 0, type: 'integer' },
+  format: { enum: ['png', 'svg'], type: 'string' },
+  inspection: EXCALIDRAW_INSPECTION_SCHEMA,
+  layout: EXCALIDRAW_INSPECTION_PROPERTIES.layout,
+  path: { type: 'string' },
+  revision: REVISION_SCHEMA,
+  valid: { type: 'boolean' },
+};
+const EXCALIDRAW_VERIFY_OUTPUT_SCHEMA = {
+  oneOf: [
+    objectSchema(EXCALIDRAW_COMPACT_VERIFICATION_PROPERTIES),
+    objectSchema({
+      ...EXCALIDRAW_COMPACT_VERIFICATION_PROPERTIES,
+      ...EXCALIDRAW_RENDER_RESULT_PROPERTIES,
+    }),
+  ],
+};
 
 export const AGENT_TOOL_DEFINITIONS = Object.freeze([
   {
     annotations: { idempotentHint: true, readOnlyHint: true },
-    description: 'List readable CollabMD Vault documents by path and kind.',
+    description: 'List current Vault files and directories, including binary metadata and agent capability flags.',
     inputSchema: objectSchema({
       cursor: {
         description: 'Path from the previous nextCursor; omit for the first page.',
@@ -326,7 +361,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
         uniqueItems: true,
       },
       limit: {
-        description: 'Maximum documents to return.',
+        description: 'Maximum entries to return.',
         maximum: 200,
         minimum: 1,
         type: 'integer',
@@ -335,34 +370,10 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
         description: 'Optional Vault directory or path prefix.',
         type: 'string',
       },
-    }, []),
-    method: 'listDocuments',
-    name: 'list_documents',
-    outputSchema: objectSchema({
-      documents: { items: DOCUMENT_SCHEMA, type: 'array' },
-      nextCursor: { type: ['string', 'null'] },
-      truncated: { type: 'boolean' },
-    }),
-    scope: 'vault:read',
-    untrustedContentHint: true,
-    webMcp: true,
-  },
-  {
-    annotations: { idempotentHint: true, readOnlyHint: true },
-    description: 'List current Vault files and directories, including binary metadata and agent capability flags.',
-    inputSchema: objectSchema({
-      cursor: {
-        description: 'Path from the previous nextCursor; omit for the first page.',
-        type: 'string',
-      },
-      limit: {
-        description: 'Maximum entries to return.',
-        maximum: 200,
-        minimum: 1,
-        type: 'integer',
-      },
-      prefix: {
-        description: 'Optional Vault directory or path prefix.',
+      pathQuery: {
+        description: 'Optional case-insensitive substring to match anywhere in an entry path.',
+        maxLength: 500,
+        minLength: 1,
         type: 'string',
       },
     }, []),
@@ -380,20 +391,42 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
 
   {
     annotations: { idempotentHint: true, readOnlyHint: true },
-    description: 'Search current Vault text with one fixed case-insensitive term. Returns path and line evidence.',
+    description: 'Search current Vault text with one literal case-insensitive phrase, not a natural-language question. Defaults to 10 files and 2 snippets each. Read relevant ranges before answering and cite path:line evidence. Narrow prefix or query when truncated; no matches do not prove a topic is absent.',
     inputSchema: objectSchema({
       limit: {
-        description: 'Maximum matching documents to return.',
+        default: 10,
+        description: 'Maximum matching documents to return (default 10).',
         maximum: 50,
         minimum: 1,
         type: 'integer',
       },
+      maxSnippetsPerFile: {
+        default: 2,
+        description: 'Maximum matching snippets returned per document (default 2).',
+        maximum: 10,
+        minimum: 1,
+        type: 'integer',
+      },
+      kinds: {
+        description: 'Optional CollabMD content kinds to include.',
+        items: { type: 'string' },
+        type: 'array',
+        uniqueItems: true,
+      },
+      prefix: {
+        description: 'Optional Vault directory or path prefix.',
+        type: 'string',
+      },
       query: {
         description: 'Literal case-insensitive text to find; regular expressions are not supported.',
         maxLength: 500,
         minLength: 2,
         type: 'string',
       },
+      wholeWord: {
+        description: 'Match only when the literal query is bounded by non-word characters.',
+        type: 'boolean',
+      },
     }, ['query']),
     method: 'searchVault',
     name: 'search_vault',
@@ -415,7 +448,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
         required: ['available', 'backend', 'minQueryLength', 'unavailableReason', 'version'],
         type: 'object',
       },
-      truncated: { type: 'boolean' },
+      truncated: { description: 'True when documents or snippets were omitted, or the search was incomplete. Counts cover observed matches, not necessarily all Vault matches.', type: 'boolean' },
     }),
     scope: 'vault:read',
     untrustedContentHint: true,
@@ -423,14 +456,21 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
   },
   {
     annotations: { idempotentHint: true, readOnlyHint: true },
-    description: 'Read a current CollabMD document range and return full-document revision for citations and edits.',
+    description: 'Read current text (default 80 lines) or a compact Markdown outline with full-document revision. Follow nextStartLine for more. Read content immediately before exact edits; on revision conflict reread and recompute. Maximum source size is 1000000 characters; a single content line over 100000 characters fails explicitly.',
     inputSchema: objectSchema({
       lineCount: {
-        description: 'Maximum number of lines to return.',
+        default: 80,
+        description: 'Maximum content lines or outline headings to return (default 80).',
         maximum: 500,
         minimum: 1,
         type: 'integer',
       },
+      mode: {
+        default: 'content',
+        description: 'Outline returns top-level ATX and single-line Setext headings, excluding fenced code and frontmatter. Heading text is capped at 200 characters.',
+        enum: ['content', 'outline'],
+        type: 'string',
+      },
       path: {
         description: 'Vault-relative document path.',
         maxLength: 1024,
@@ -448,13 +488,23 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
     outputSchema: objectSchema({
       content: { type: 'string' },
       endLine: { minimum: 1, type: 'integer' },
+      headings: {
+        items: objectSchema({
+          level: { minimum: 1, maximum: 6, type: 'integer' },
+          line: { minimum: 1, type: 'integer' },
+          text: { type: 'string' },
+          truncated: { type: 'boolean' },
+        }),
+        type: 'array',
+      },
+      nextStartLine: { type: ['integer', 'null'], minimum: 1 },
       kind: { type: 'string' },
       path: { type: 'string' },
       revision: REVISION_SCHEMA,
       startLine: { minimum: 1, type: 'integer' },
       totalLines: { minimum: 1, type: 'integer' },
       truncated: { type: 'boolean' },
-    }),
+    }, ['content', 'endLine', 'kind', 'nextStartLine', 'path', 'revision', 'startLine', 'totalLines', 'truncated']),
     scope: 'vault:read',
     untrustedContentHint: true,
     webMcp: true,
@@ -507,6 +557,65 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
     untrustedContentHint: true,
     webMcp: true,
   },
+  {
+    annotations: { idempotentHint: true, readOnlyHint: true },
+    description: 'Run a Base query and return filtered rows so you can verify filters and expected output.',
+    inputSchema: objectSchema({
+      limit: {
+        description: 'Maximum rows to return.',
+        maximum: 200,
+        minimum: 1,
+        type: 'integer',
+      },
+      path: {
+        description: 'Vault-relative .base path.',
+        maxLength: 1024,
+        minLength: 1,
+        type: 'string',
+      },
+      search: {
+        description: 'Optional case-insensitive row search across visible columns.',
+        maxLength: 500,
+        type: 'string',
+      },
+      view: {
+        description: 'Optional Base view name.',
+        maxLength: 200,
+        type: 'string',
+      },
+    }, ['path']),
+    method: 'queryBase',
+    name: 'query_base',
+    outputSchema: objectSchema({
+      columns: {
+        items: objectSchema({
+          id: { type: 'string' },
+          label: { type: 'string' },
+        }),
+        type: 'array',
+      },
+      path: { type: 'string' },
+      rows: {
+        items: objectSchema({
+          cells: {
+            additionalProperties: { type: 'string' },
+            type: 'object',
+          },
+          path: { type: 'string' },
+        }),
+        type: 'array',
+      },
+      totalRows: { minimum: 0, type: 'integer' },
+      truncated: { type: 'boolean' },
+      view: objectSchema({
+        name: { type: 'string' },
+        type: { type: 'string' },
+      }),
+    }),
+    scope: 'vault:read',
+    untrustedContentHint: true,
+    webMcp: true,
+  },
   {
     annotations: { idempotentHint: true, readOnlyHint: true },
     description: 'Render one standalone or fenced Mermaid/PlantUML diagram. Markdown with multiple diagrams requires the opening fence startLine. Mermaid rendering requires WebMCP.',
@@ -539,7 +648,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
 
   {
     annotations: { idempotentHint: true, readOnlyHint: true },
-    description: 'Inspect an Excalidraw scene structurally. Returns paint order, geometry, bindings, bounds, occlusion, clipping, and validity warnings.',
+    description: 'Inspect an Excalidraw scene structurally. Returns paint order, geometry, text style, bindings, bounds, layout diagnostics, occlusion, clipping, and validity warnings.',
     inputSchema: objectSchema({
       path: {
         description: 'Vault-relative .excalidraw path.',
@@ -557,19 +666,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
   },
   {
     annotations: { idempotentHint: true, readOnlyHint: true },
-    description: 'Render supported basic elements as PNG or SVG. Returns renderer metadata and warns when preview is not pixel-identical to Excalidraw.',
-    inputSchema: objectSchema(EXCALIDRAW_RENDER_INPUT_PROPERTIES, ['path']),
-    method: 'renderExcalidraw',
-    name: 'render_excalidraw',
-    outputSchema: objectSchema(EXCALIDRAW_RENDER_OUTPUT_PROPERTIES),
-    resultKind: 'image',
-    scope: 'vault:read',
-    untrustedContentHint: true,
-    webMcp: true,
-  },
-  {
-    annotations: { idempotentHint: true, readOnlyHint: true },
-    description: 'Inspect and render one Excalidraw revision in a single operation.',
+    description: 'Verify one Excalidraw revision with compact structural and layout diagnostics; render is optional.',
     inputSchema: objectSchema({
       ...EXCALIDRAW_RENDER_INPUT_PROPERTIES,
       inspectOcclusion: {
@@ -579,11 +676,8 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
     }, ['path']),
     method: 'verifyExcalidraw',
     name: 'verify_excalidraw',
-    outputSchema: objectSchema({
-      ...EXCALIDRAW_RENDER_OUTPUT_PROPERTIES,
-      inspection: EXCALIDRAW_INSPECTION_SCHEMA,
-    }),
-    resultKind: 'image',
+    outputSchema: EXCALIDRAW_VERIFY_OUTPUT_SCHEMA,
+    resultKind: 'optional-image',
     scope: 'vault:read',
     untrustedContentHint: true,
     webMcp: true,
@@ -610,7 +704,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
   },
   {
     annotations: { destructiveHint: false, idempotentHint: true, readOnlyHint: false },
-    description: 'Create a valid editable .excalidraw scene from basic Excalidraw elements, with optional same-revision verification.',
+    description: 'Create an editable .excalidraw scene. Before the first diagram in a task, call get_collabmd_syntax with kind="excalidraw" for design guidance and valid examples. Request inline inspection/rendering and examine the image before finishing.',
     inputSchema: objectSchema({
       elements: {
         description: 'One to 200 basic Excalidraw elements in back-to-front order. Text may bind to a container with containerId; groupIds define atomic movement groups. Arrows may bind with startElementId and endElementId. beforeElementId or afterElementId sets explicit placement.',
@@ -634,14 +728,14 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
       path: { type: 'string' },
       revision: REVISION_SCHEMA,
       verification: EXCALIDRAW_INLINE_VERIFICATION_SCHEMA,
-    }),
+    }, ['elementCount', 'path', 'revision']),
     resultKind: 'optional-image',
     scope: 'vault:edit',
     webMcp: true,
   },
   {
     annotations: { destructiveHint: false, idempotentHint: false, readOnlyHint: false },
-    description: 'Create, update, replace, translate, reorder, or delete elements in an existing .excalidraw scene when its revision still matches.',
+    description: 'Edit an existing .excalidraw scene only when its revision matches. Before the first diagram edit in a task, consult get_collabmd_syntax with kind="excalidraw". Inspect first, preserve existing style and unrelated elements, then verify the result. Supports create, update, replace, translate, reorder, and delete; bound-text metric edits reflow automatically.',
     inputSchema: objectSchema({
       create: {
         items: EXCALIDRAW_ELEMENT_INPUT_SCHEMA,
@@ -655,6 +749,11 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
         type: 'array',
         uniqueItems: true,
       },
+      normalizeTextPlacement: {
+        description: 'Normalize every bound text label to its container center and current line-height metrics. This can be the only edit operation.',
+        enum: [true],
+        type: 'boolean',
+      },
       path: {
         description: 'Vault-relative .excalidraw path returned by read_document.',
         maxLength: 1024,
@@ -690,6 +789,11 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
       elementCount: { minimum: 0, type: 'integer' },
       path: { type: 'string' },
       reordered: { minimum: 0, type: 'integer' },
+      reflowed: {
+        description: 'Number of bound text labels whose position or height was normalized.',
+        minimum: 0,
+        type: 'integer',
+      },
       replaced: { minimum: 0, type: 'integer' },
       revision: REVISION_SCHEMA,
       translated: {
@@ -699,14 +803,14 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
       },
       updated: { minimum: 0, type: 'integer' },
       verification: EXCALIDRAW_INLINE_VERIFICATION_SCHEMA,
-    }, ['created', 'deleted', 'elementCount', 'path', 'reordered', 'replaced', 'revision', 'translated', 'updated']),
+    }, ['created', 'deleted', 'elementCount', 'path', 'reordered', 'reflowed', 'replaced', 'revision', 'translated', 'updated']),
     resultKind: 'optional-image',
     scope: 'vault:edit',
     webMcp: true,
   },
   {
     annotations: { destructiveHint: false, idempotentHint: false, readOnlyHint: false },
-    description: 'Apply bounded exact replacements to a document only when its revision still matches.',
+    description: 'Apply up to 20 unique, non-overlapping exact replacements against the revision from a fresh content read. Combined old/new text is limited to 50000 characters. On conflict reread; on ambiguous matches include more surrounding text. Optional Markdown validation checks the saved revision.',
     inputSchema: objectSchema({
       path: {
         description: 'Vault-relative path returned by read_document.',
@@ -737,6 +841,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
         type: 'array',
       },
       revision: REVISION_SCHEMA,
+      validate: VALIDATE_MARKDOWN_INPUT,
     }, ['path', 'revision', 'replacements']),
     method: 'applyTextEdits',
     name: 'apply_text_edits',
@@ -744,13 +849,14 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
       path: { type: 'string' },
       replacementCount: { minimum: 1, type: 'integer' },
       revision: REVISION_SCHEMA,
-    }),
+      validation: MARKDOWN_VALIDATION_SCHEMA,
+    }, ['path', 'replacementCount', 'revision']),
     scope: 'vault:edit',
     webMcp: true,
   },
   {
     annotations: { destructiveHint: false, idempotentHint: true, readOnlyHint: false },
-    description: 'Create a new supported CollabMD text document. An identical retry succeeds; different content at an existing path fails.',
+    description: 'Create a new supported text document (up to 200000 characters). Inspect nearby naming/style and consult get_collabmd_syntax for unfamiliar kinds. Identical retries succeed; different content at an existing path fails. Optional Markdown validation checks the saved revision.',
     inputSchema: objectSchema({
       content: {
         description: 'Initial document text, normalized to LF line endings.',
@@ -763,6 +869,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
         minLength: 1,
         type: 'string',
       },
+      validate: VALIDATE_MARKDOWN_INPUT,
     }, ['path', 'content']),
     method: 'createDocument',
     name: 'create_document',
@@ -770,7 +877,8 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
       kind: { type: 'string' },
       path: { type: 'string' },
       revision: REVISION_SCHEMA,
-    }),
+      validation: MARKDOWN_VALIDATION_SCHEMA,
+    }, ['kind', 'path', 'revision']),
     scope: 'vault:edit',
     webMcp: true,
   },

package/src/domain/collabmd-content-capabilities.js

@@ -13,13 +13,63 @@ import {
   supportsCommentsForFilePath,
 } from './file-kind.js';
 
+const EXCALIDRAW_DESIGN_GUIDE = [
+  'Plan: State the question the diagram answers, its audience, the essential entities, and what each connection means. Choose a flowchart for steps/decisions or a layered layout for responsibilities/dependencies. Keep one main idea per diagram; split dense detail into another diagram. Do not invent relationships to fill space.',
+  'Layout: Choose left-to-right or top-to-bottom reading order. Place containers before labels and connectors. Align related nodes and use consistent sizes and gaps. As starting points, use 200 x 88 nodes, 80-120 units between columns, and 60-80 between rows; enlarge these for the actual text. Reserve clear connector lanes. Route arrows around unrelated shapes, minimize crossings, and make direction unambiguous. These are defaults, not constraints on an existing design.',
+  'Labels and bindings: Prefer short entity names and verb phrases for relationships. Start around 20-unit body text and 28-unit titles, with one font family. Enlarge the container or add deliberate line breaks instead of shrinking text to fit. Create labels as separate text elements using containerId; creation still requires explicit x/y and correctly sized bounds. Bind connectors with startElementId/endElementId and set points relative to the arrow x/y, near the appropriate shape edges. Binding identifies the relationship; it does not plan the route. Allow padding around labels and keep relationship labels away from arrowheads.',
+  'Visual hierarchy: Use a clear title, restrained strokes, and at most two or three semantic fill colors with readable dark labels on light fills. Use shape, position, or text as well as color to distinguish roles. Reuse colors for the same meaning. Give related elements groupIds when they should move together. Keep text above its container in paint order. Avoid decorative elements that compete with the information.',
+  'Existing diagrams: In WebMCP, get active context first. Inspect the existing scene and preserve its style, IDs, layout, and unrelated elements. Use edit_excalidraw with the returned revision. Prefer translate for moving containers/groups and their related text; inspect attached connector routes after movement. Use reorder for paint order and same-ID replace for a type change. Bound-text placement normalization re-centers labels; use it only when that is intended. On a revision conflict, inspect again and reconsider the edit.',
+  'Verify and refine: Create or edit with verify: { render: true } to receive inspection and an image for that exact revision. Check diagnostics for clipping, unintended overlaps, occlusion, text placement, and connectors crossing components. Examine the image for reading order, legibility, correct relationships, and clear arrow direction; structural validity alone does not establish visual quality. Fix concrete problems with revision-guarded edits and verify again. Use verify: { render: false } for intermediate create/edit checks when an image would add no information; use verify_excalidraw with render: true for the final image. Stop when the requested meaning is clear and no material layout issue remains; do not redraw solely to chase cosmetic variation.',
+  'Rendering limits: Remote collabmd-basic-svg previews approximate Excalidraw and report preview-not-pixel-identical; WebMCP uses the official browser renderer. If an image is unavailable, report that visual quality was not checked instead of claiming it was verified.',
+  'Examples below are complete MCP tools/call payloads using this server\'s schema. Choose a new Vault-relative path and adapt labels, geometry, and relationships. For WebMCP, call the corresponding collabmd_ tool with the arguments object. Reuse this guide during the task; fetching it before every edit is unnecessary.',
+].join('\n\n');
+
+const EXCALIDRAW_CREATION_EXAMPLES = [
+  {
+    name: 'create_excalidraw',
+    arguments: {
+      path: 'diagrams/request-flow.excalidraw',
+      elements: [
+        { id: 'title', type: 'text', x: 40, y: 32, text: 'Request review', fontSize: 28 },
+        { id: 'request', type: 'rectangle', x: 40, y: 96, width: 200, height: 88, backgroundColor: '#e7f5ff' },
+        { id: 'review', type: 'rectangle', x: 360, y: 96, width: 200, height: 88, backgroundColor: '#e7f5ff' },
+        { id: 'respond', type: 'rectangle', x: 680, y: 96, width: 200, height: 88, backgroundColor: '#e7f5ff' },
+        { id: 'request-label', type: 'text', x: 98, y: 127.5, text: 'Request', containerId: 'request' },
+        { id: 'review-label', type: 'text', x: 424, y: 127.5, text: 'Review', containerId: 'review' },
+        { id: 'respond-label', type: 'text', x: 738, y: 127.5, text: 'Respond', containerId: 'respond' },
+        { id: 'request-review', type: 'arrow', x: 244, y: 140, points: [[0, 0], [112, 0]], startElementId: 'request', endElementId: 'review' },
+        { id: 'review-respond', type: 'arrow', x: 564, y: 140, points: [[0, 0], [112, 0]], startElementId: 'review', endElementId: 'respond' },
+      ],
+      verify: { render: true },
+    },
+  },
+  {
+    name: 'create_excalidraw',
+    arguments: {
+      path: 'diagrams/service-layers.excalidraw',
+      elements: [
+        { id: 'title', type: 'text', x: 40, y: 32, text: 'Service layers', fontSize: 28 },
+        { id: 'presentation', type: 'rectangle', x: 40, y: 96, width: 360, height: 96, backgroundColor: '#e7f5ff' },
+        { id: 'application', type: 'rectangle', x: 40, y: 256, width: 360, height: 96, backgroundColor: '#e7f5ff' },
+        { id: 'storage', type: 'rectangle', x: 40, y: 416, width: 360, height: 96, backgroundColor: '#e7f5ff' },
+        { id: 'presentation-label', type: 'text', x: 148, y: 131.5, text: 'Presentation', containerId: 'presentation' },
+        { id: 'application-label', type: 'text', x: 154, y: 291.5, text: 'Application', containerId: 'application' },
+        { id: 'storage-label', type: 'text', x: 178, y: 451.5, text: 'Storage', containerId: 'storage' },
+        { id: 'presentation-application', type: 'arrow', x: 220, y: 196, points: [[0, 0], [0, 56]], startElementId: 'presentation', endElementId: 'application' },
+        { id: 'application-storage', type: 'arrow', x: 220, y: 356, points: [[0, 0], [0, 56]], startElementId: 'application', endElementId: 'storage' },
+      ],
+      verify: { render: true },
+    },
+  },
+].map((example) => JSON.stringify(example));
+
 const CAPABILITIES = Object.freeze({
   base: {
-    agentCreatable: false,
-    agentEditable: false,
+    agentCreatable: true,
+    agentEditable: true,
     editable: true,
     extensions: [BASE_FILE_EXTENSION],
-    guide: 'YAML Base definition. Embed a file with ![[query.base]] or an inline query with a fenced base block. Agent writes are disabled until Base validation is shared.',
+    guide: 'YAML Base definition. Embed a file with ![[query.base]] or an inline query with a fenced base block. Create and edit with create_document and apply_text_edits. After writing, use query_base to inspect filtered rows.',
     examples: ['```base\nfilters:\n  and: []\n```', '![[tasks.base]]'],
   },
   drawio: {
@@ -35,7 +85,7 @@ const CAPABILITIES = Object.freeze({
     agentEditable: true,
     editable: true,
     extensions: [EXCALIDRAW_FILE_EXTENSION],
-    guide: 'Excalidraw scene JSON managed by the canvas editor. Use create_excalidraw and edit_excalidraw rather than raw text edits. Element order is back-to-front; create supports beforeElementId and afterElementId, while edit supports relationship-aware translation, reorder, same-ID replace, and same-revision verification. Container or group translation also moves bound text and grouped members. Standalone auto-resizing text recalculates its bounds when text metrics change. Line, arrow, and freedraw dimensions are derived from points. Creation and editing support inline inspection and optional rendering; remote fallback renders report preview-not-pixel-identical. Supported agent element types: rectangle, ellipse, diamond, text, arrow, line, and freedraw. Embed with ![[drawing.excalidraw]].',
+    guide: 'Excalidraw scene JSON managed by the canvas editor. Use create_excalidraw and edit_excalidraw rather than raw text edits. Element order is back-to-front; create supports beforeElementId and afterElementId, while edit supports relationship-aware translation, reorder, same-ID replacement, and bound-text placement normalization. Container or group translation also moves bound text and grouped members. Standalone auto-resizing text recalculates its bounds when text metrics change; bound text whose font, size, line height, or content changes is re-centered and remeasured vertically. Line, arrow, and freedraw dimensions are derived from points. Creation and editing support inline inspection and optional rendering; verify_excalidraw can return compact layout diagnostics without an image. Remote fallback renders report preview-not-pixel-identical. Supported agent element types: rectangle, ellipse, diamond, text, arrow, line, and freedraw. Embed with ![[drawing.excalidraw]].',
     examples: ['![[drawing.excalidraw]]'],
   },
   html: {
@@ -59,12 +109,13 @@ const CAPABILITIES = Object.freeze({
     agentEditable: true,
     editable: true,
     extensions: [...MARKDOWN_FILE_EXTENSIONS],
-    guide: 'Markdown-it syntax with YAML frontmatter, headings, tables, task lists, fenced code, linkified URLs, [[wiki-links]], aliases, and embeds. Use ![[file.ext]] for Base, draw.io, Excalidraw, Mermaid, or PlantUML Vault embeds. Use ![Label](https://...) for public video embeds: valid YouTube URLs or direct public HTTPS URLs ending in .mp4, .webm, or .ogg. Use relative Markdown image paths for Vault image attachments. Raw HTML is disabled.',
+    guide: 'Markdown-it syntax with YAML frontmatter, headings, tables, task lists, fenced code, linkified URLs, [[wiki-links]], aliases, and embeds. Use $...$ for inline math and $$...$$ on its own lines for display math (KaTeX). Use ![[file.ext]] for Base, draw.io, Excalidraw, Mermaid, or PlantUML Vault embeds. Use ![Label](https://...) for public video embeds: valid YouTube URLs or direct public HTTPS URLs ending in .mp4, .webm, or .ogg. Use relative Markdown image paths for Vault image attachments. Raw HTML is disabled.',
     examples: [
       '---\ntags: [docs]\n---\n# Title\n\n- [ ] Task\n\n[[Other Note|Alias]]',
       '![[diagram.mmd]]\n![[diagram.puml]]\n![[drawing.excalidraw]]\n![[architecture.drawio]]\n![[query.base]]',
       '![Demo](https://www.youtube.com/watch?v=dQw4w9WgXcQ)\n![Demo](https://cdn.example.com/demo.webm)\n![Diagram](assets/diagram.png)',
       '```mermaid\nflowchart LR\n  A --> B\n```\n\n```plantuml\n@startuml\nAlice -> Bob\n@enduml\n```',
+      'Inline math $E = mc^2$ and display math:\n\n$$\n\\frac{a}{b}\n$$',
     ],
   },
   mermaid: {
@@ -127,9 +178,13 @@ export function listCollabMdContentCapabilities() {
 export function getCollabMdSyntaxGuide(kind) {
   const capability = getCollabMdContentCapability(kind);
   return capability ? {
-    examples: capability.examples,
+    examples: capability.kind === 'excalidraw'
+      ? [...EXCALIDRAW_CREATION_EXAMPLES, ...capability.examples]
+      : capability.examples,
     extensions: capability.extensions,
-    guide: capability.guide,
+    guide: capability.kind === 'excalidraw'
+      ? `${capability.guide}\n\n${EXCALIDRAW_DESIGN_GUIDE}`
+      : capability.guide,
     kind: capability.kind,
   } : null;
 }

package/src/domain/collaboration-protocol.js

@@ -1,2 +1,4 @@
+export const MSG_SYNC = 0;
+export const MSG_AWARENESS = 1;
 export const MSG_AGENT_FLUSH = 4;
 export const MSG_AGENT_FLUSH_ACK = 5;