pmx-canvas 0.8.2 → 0.9.0

package/src/server/operations/ops/batch.ts

@@ -30,6 +30,7 @@ import { executeOperation, runWithSuppressedEmits } from '../registry.js';
 import { defineOperation, type Operation, type OperationContext } from '../types.js';
 import { readJsonValue } from '../http.js';
 import { isRecord } from './nodes.js';
+import { boardsPayload } from './boards.js';
 
 interface BatchEntry {
   op: string;
@@ -157,8 +158,10 @@ function createInternalBatchNode(args: Record<string, unknown>): Record<string,
  * entry shape. Most ops match the wire shape verbatim; the cases below diverge
  * because the legacy switch shaped them by hand.
  */
-function shapeBatchEntry(op: string, result: unknown): Record<string, unknown> {
+function shapeBatchEntry(op: string, result: unknown, creationReceipt = false): Record<string, unknown> {
   const body = isRecord(result) ? result : {};
+  // A retry's refs must describe its original creation, not a later live edit.
+  if (creationReceipt) return body;
 
   // node.add / node.update / group.create / graph.add: the legacy switch pushed
   // { ok:true, ...serializeCanvasNodeCompact(node), <extras> }. The wire shape
@@ -237,7 +240,13 @@ async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
           refs,
         };
       }
-      if (operation.op === 'node.add' && typeof args.type === 'string' && isInternalBatchNodeType(args.type)) {
+      if (
+        operation.op === 'node.add' &&
+        typeof args.type === 'string' &&
+        isInternalBatchNodeType(args.type) &&
+        args.destinationBoardId === undefined &&
+        args.requestId === undefined
+      ) {
         const result = createInternalBatchNode(args);
         results.push(result);
         if (typeof operation.assign === 'string' && operation.assign.trim().length > 0) {
@@ -258,7 +267,12 @@ async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
       if (canvasState.boardGeneration !== boardGeneration) {
         throw new Error('The board changed while the batch was running.');
       }
-      const result = shapeBatchEntry(operation.op, raw);
+      const result = shapeBatchEntry(
+        operation.op,
+        raw,
+        ['node.add', 'group.create', 'edge.add'].includes(operation.op) &&
+          (args.requestId !== undefined || args.destinationBoardId !== undefined),
+      );
       results.push(result);
       if (typeof operation.assign === 'string' && operation.assign.trim().length > 0) {
         refs[operation.assign] = result;
@@ -391,8 +405,25 @@ const batchOperation = defineOperation<z.infer<typeof batchSchema>, BatchEnvelop
     const operations = normalizeOperations(input.operations);
     // Suppress every per-entry SSE frame (auto layout emit + each handler's
     // ctx.emit). After the loop completes, emit ONE final canvas-layout-update.
+    const revision = canvasState.getContentRevision().revision;
     const envelope = await runWithSuppressedEmits(() => runBatch(operations));
-    ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    if (
+      revision !== canvasState.getContentRevision().revision ||
+      operations.some(
+        (entry) =>
+          !['node.add', 'group.create', 'edge.add'].includes(entry.op) ||
+          entry.args.destinationBoardId === undefined ||
+          entry.args.destinationBoardId === canvasState.activeBoardId,
+      )
+    )
+      ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    if (
+      operations.some(
+        (entry) =>
+          ['node.add', 'group.create', 'edge.add'].includes(entry.op) && entry.args.destinationBoardId !== undefined,
+      )
+    )
+      ctx.emit('boards-changed', boardsPayload());
     // The suppression window also swallows the pins op's context-pins-changed
     // frame, leaving the client's pin state (menus, indicators) stale until
     // reload (0.4.5 report Finding X). If the batch touched pins, follow the

package/src/server/operations/ops/boards.ts

@@ -1,6 +1,7 @@
 /**
  * Many boards (plan 012): board.list / board.get / board.create /
- * board.update / board.open / board.delete.
+ * board.update / board.open / board.delete, plus board.pin / board.unpin
+ * (vision move 0a: the working set across boards).
  *
  * Agents can explicitly open boards as well as list, read and create them.
  * Deletion requires the human (HUMAN_ONLY_OPS in registry.ts).
@@ -11,46 +12,111 @@
  *
  * This module must never import server.ts or index.ts.
  */
+import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { normalizeBoardCategory } from '../../../shared/boards.js';
+import { normalizeBoardFolder } from '../../../shared/boards.js';
+import { relationVocabularySchema } from '../../../shared/relations.js';
 import { canvasState, type CanvasLayout } from '../../canvas-state.js';
 import { openCanvasBoard } from '../../canvas-operations.js';
 import { summarizeNodeForAgentContext } from '../../../shared/agent-context.js';
+import { BRIEF_SUMMARY_LENGTH } from '../../context-brief.js';
+import { memoryGraph, boardConnections } from '../../memory-graph.js';
 import { defineOperation, OperationError, type Operation, type OperationContext } from '../types.js';
 
-export function boardsPayload(): Record<string, unknown> {
+/** The most cards a Home thumbnail draws (the largest first); the rest are noise at that size. */
+const PREVIEW_CARDS = 24;
+export const boardCatalogEpoch = randomUUID();
+let catalogRevision = 0;
+let reloadRevision = 0;
+
+/**
+ * A board's thumbnail on Home (docs/design/Home.dc.html): its cards as
+ * rectangles in 0–1 of the board's extent, pinned ones flagged.
+ */
+function boardPreview(
+  nodes: CanvasLayout['nodes'],
+  pins: readonly string[],
+): Array<{ x: number; y: number; w: number; h: number; pinned?: true }> {
+  const cards = nodes.filter((node) => node.type !== 'group');
+  if (cards.length === 0) return [];
+  const left = Math.min(...cards.map((node) => node.position.x));
+  const top = Math.min(...cards.map((node) => node.position.y));
+  const width = Math.max(...cards.map((node) => node.position.x + node.size.width)) - left || 1;
+  const height = Math.max(...cards.map((node) => node.position.y + node.size.height)) - top || 1;
+  const round = (value: number) => Math.round(value * 1000) / 1000;
+  return [...cards]
+    .sort((a, b) => b.size.width * b.size.height - a.size.width * a.size.height)
+    .slice(0, PREVIEW_CARDS)
+    .map((node) => ({
+      x: round((node.position.x - left) / width),
+      y: round((node.position.y - top) / height),
+      w: round(node.size.width / width),
+      h: round(node.size.height / height),
+      ...(pins.includes(node.id) ? { pinned: true as const } : {}),
+    }));
+}
+
+export function boardsPayload(reloaded = false): Record<string, unknown> {
+  const revision = ++catalogRevision;
+  if (reloaded) reloadRevision = revision;
   const boards = canvasState.listBoards();
   const names = new Map(boards.map((board) => [board.id, board.name]));
-  const links = new Map<string, Array<{ nodeId: string; boardId: string; title: string | null; missing: boolean }>>();
-  for (const board of boards) {
-    const nodes = canvasState.readBoard(board.id, false)?.layout.nodes ?? [];
-    links.set(
-      board.id,
-      nodes
-        .filter((node) => node.type === 'board')
-        .map((node) => {
-          const boardId = typeof node.data.boardId === 'string' ? node.data.boardId : '';
-          return { nodeId: node.id, boardId, title: names.get(boardId) ?? null, missing: !names.has(boardId) };
-        }),
-    );
-  }
+  const graph = memoryGraph();
+  const titles = new Map(graph.nodes.map((node) => [node.key, node.title]));
+  const connections = boardConnections(graph);
   return {
+    catalogEpoch: boardCatalogEpoch,
+    catalogRevision: revision,
+    reloadRevision,
+    boardGeneration: canvasState.boardGeneration,
     activeBoardId: canvasState.activeBoardId,
     boards: boards.map((board) => {
       const read = canvasState.readBoard(board.id, true);
       const readme = read?.layout.nodes.find((node) => node.id === board.readmeNodeId && node.type === 'markdown');
+      const pins = read?.state.contextPins ?? [];
+      const pinnedNodes = (read?.layout.nodes ?? []).filter((node) => pins.includes(node.id));
+      const summary = readme ? summarizeNodeForAgentContext(readme, { defaultTextLength: 1000 }) : null;
       return {
         ...board,
-        summary: readme ? summarizeNodeForAgentContext(readme, { defaultTextLength: 1000 }) : null,
-        pinnedTitles: (read?.layout.nodes ?? [])
-          .filter((node) => read?.state.contextPins.includes(node.id))
-          .map((node) => ({ nodeId: node.id, title: typeof node.data.title === 'string' ? node.data.title : node.id })),
-        links: links.get(board.id) ?? [],
-        backlinks: boards.flatMap((source) =>
-          (links.get(source.id) ?? [])
-            .filter((link) => link.boardId === board.id)
-            .map((link) => ({ boardId: source.id, title: source.name, nodeId: link.nodeId })),
-        ),
+        summary,
+        pinnedTitles: pinnedNodes.map((node) => ({
+          nodeId: node.id,
+          title: typeof node.data.title === 'string' ? node.data.title : node.id,
+        })),
+        preview: boardPreview(read?.layout.nodes ?? [], pins),
+        // What a pinned board's map roughly costs in the brief: its README and pinned cards as summaries.
+        mapChars:
+          (summary?.length ?? 0) +
+          pinnedNodes.reduce(
+            (sum, node) =>
+              sum +
+              summarizeNodeForAgentContext(node, {
+                defaultTextLength: BRIEF_SUMMARY_LENGTH,
+                webpageTextLength: BRIEF_SUMMARY_LENGTH,
+              }).length,
+            0,
+          ),
+        links: connections
+          .filter((edge) => edge.source.boardId === board.id)
+          .map((edge) => ({
+            id: edge.id,
+            nodeId: edge.source.cardId ?? '',
+            boardId: edge.target.boardId,
+            ...(edge.target.cardId ? { cardId: edge.target.cardId, cardTitle: titles.get(edge.to) ?? null } : {}),
+            title: names.get(edge.target.boardId) ?? null,
+            missing: edge.missing,
+            kind: edge.kind,
+          })),
+        backlinks: connections
+          .filter((edge) => edge.target.boardId === board.id)
+          .map((edge) => ({
+            id: edge.id,
+            boardId: edge.source.boardId,
+            title: names.get(edge.source.boardId) ?? '',
+            nodeId: edge.source.cardId ?? '',
+            kind: edge.kind,
+            ...(edge.target.cardId ? { cardId: edge.target.cardId } : {}),
+          })),
       };
     }),
   };
@@ -82,19 +148,21 @@ export function readTargetBoard(
   };
 }
 
-function emitBoardsChanged(ctx: OperationContext): void {
-  ctx.emit('boards-changed', boardsPayload());
+function emitBoardsChanged(ctx: OperationContext): Record<string, unknown> {
+  const payload = boardsPayload();
+  ctx.emit('boards-changed', payload);
+  return payload;
 }
 
 const jsonResult = (result: unknown) => ({
   content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
 });
 
-/** '' or null clears the category; undefined leaves it alone. */
-function boardCategory(value: unknown): string | null | undefined {
+/** '' or null clears the folder; undefined leaves it alone. */
+function boardFolder(value: unknown): string | null | undefined {
   if (value === undefined) return undefined;
   try {
-    return normalizeBoardCategory(typeof value === 'string' ? value : null);
+    return normalizeBoardFolder(typeof value === 'string' ? value : null);
   } catch (error) {
     throw new OperationError(error instanceof Error ? error.message : String(error));
   }
@@ -158,7 +226,7 @@ const boardGetOperation = defineOperation<z.infer<typeof getSchema>, Record<stri
 
 const createShape = {
   name: z.unknown().optional().describe('Board name'),
-  category: z.unknown().optional().describe('Folder path on Home, e.g. Engineering/Canvas'),
+  folder: z.unknown().optional().describe('Folder path on Home, e.g. Engineering/Canvas'),
 };
 const createSchema = z.looseObject(createShape);
 
@@ -174,12 +242,12 @@ const boardCreateOperation = defineOperation<z.infer<typeof createSchema>, Recor
       'Create a new empty board without opening it. Use canvas_board action "open" with the returned board id before writing to it.',
     extraShape: {
       name: z.string().describe('Board name'),
-      category: z.string().optional().describe('Folder path on Home, e.g. Engineering/Canvas'),
+      folder: z.string().optional().describe('Folder path on Home, e.g. Engineering/Canvas'),
     },
     formatResult: jsonResult,
   },
   handler: (input, ctx) => {
-    const board = canvasState.createBoard(boardName(input.name), boardCategory(input.category) ?? null);
+    const board = canvasState.createBoard(boardName(input.name), boardFolder(input.folder) ?? null);
     if (!board) throw new OperationError('Boards need a workspace database.', 409);
     emitBoardsChanged(ctx);
     return { ok: true, board };
@@ -209,8 +277,7 @@ const boardOpenOperation = defineOperation<z.infer<typeof openSchema>, Record<st
   handler: (input, ctx) => {
     const id = typeof input.id === 'string' && input.id.trim() ? input.id.trim() : null;
     if (!openCanvasBoard(id).ok) throw new OperationError(`Board "${id}" not found.`, 404);
-    emitBoardsChanged(ctx);
-    return { ok: true, ...boardsPayload() };
+    return { ok: true, ...emitBoardsChanged(ctx) };
   },
 });
 
@@ -219,8 +286,16 @@ const boardOpenOperation = defineOperation<z.infer<typeof openSchema>, Record<st
 const updateShape = {
   id: z.unknown().optional().describe('Board id'),
   name: z.unknown().optional().describe('New name'),
-  category: z.unknown().optional().describe('Folder path on Home; "" or null unfiles it'),
+  relationVocabulary: relationVocabularySchema
+    .optional()
+    .describe('Board relation vocabulary: open kinds with a meaning ink and direction'),
+  folder: z.unknown().optional().describe('Folder path on Home; "" or null unfiles it'),
   readmeNodeId: z.unknown().optional().describe('Markdown node id to use as README; null clears it'),
+  mapPosition: z
+    .object({ x: z.number().finite(), y: z.number().finite() })
+    .nullable()
+    .optional()
+    .describe('Persist a Home Map position; null returns to the generated folder layout'),
 };
 const updateSchema = z.looseObject(updateShape);
 
@@ -233,11 +308,11 @@ const boardUpdateOperation = defineOperation<z.infer<typeof updateSchema>, Recor
   mcp: {
     toolName: 'canvas_update_board',
     description:
-      'Rename a board, move it into a nested folder on Home (e.g. Engineering/Canvas; category "" unfiles it), or designate its markdown introduction with readmeNodeId. During board authoring, set a useful README when none exists; preserve an existing designation unless the human requests a change. Moving preserves the board ID and content.',
+      'Rename a board, move it into a nested folder on Home (e.g. Engineering/Canvas; folder "" unfiles it), or designate its markdown introduction with readmeNodeId. During board authoring, set a useful README when none exists; preserve an existing designation unless the human requests a change. Moving preserves the board ID and content.',
     extraShape: {
       id: z.string().describe('Board id'),
       name: z.string().optional().describe('New name'),
-      category: z.string().optional().describe('Folder path, up to 8 levels of 1–60 characters; "" unfiles it'),
+      folder: z.string().optional().describe('Folder path, up to 8 levels of 1–60 characters; "" unfiles it'),
       readmeNodeId: z.string().nullable().optional().describe('Markdown node id used as the board README'),
     },
     formatResult: jsonResult,
@@ -246,7 +321,9 @@ const boardUpdateOperation = defineOperation<z.infer<typeof updateSchema>, Recor
     const id = typeof input.id === 'string' ? input.id : '';
     const patch = {
       ...(input.name !== undefined ? { name: boardName(input.name) } : {}),
-      ...(input.category !== undefined ? { category: boardCategory(input.category) ?? null } : {}),
+      ...(input.relationVocabulary !== undefined ? { relationVocabulary: input.relationVocabulary } : {}),
+      ...(input.folder !== undefined ? { folder: boardFolder(input.folder) ?? null } : {}),
+      ...(input.mapPosition !== undefined ? { mapPosition: input.mapPosition } : {}),
     };
     if (input.readmeNodeId !== undefined) {
       const board = canvasState.readBoard(id, false);
@@ -267,15 +344,14 @@ const boardUpdateOperation = defineOperation<z.infer<typeof updateSchema>, Recor
         throw new OperationError('README must identify a markdown node on this board.');
       }
     }
-    emitBoardsChanged(ctx);
-    return { ok: true, ...boardsPayload() };
+    return { ok: true, ...emitBoardsChanged(ctx) };
   },
 });
 
 const fromShape = {
   sourceBoardId: z.string().describe('Source board id'),
   name: z.string().describe('New board name'),
-  category: z.string().optional(),
+  folder: z.string().optional(),
   nodeIds: z.array(z.string()).optional(),
   includeReadme: z.boolean().optional(),
   includeStructure: z.boolean().optional(),
@@ -310,13 +386,19 @@ const boardCreateFromOperation = defineOperation<z.infer<typeof fromSchema>, Rec
           title: typeof node.data.title === 'string' ? node.data.title : null,
           reusable: !['prompt', 'response', 'trace', 'mcp-app'].includes(node.type),
         })),
-        edges: source.layout.edges.map((edge) => ({ id: edge.id, from: edge.from, to: edge.to, type: edge.type })),
+        edges: source.layout.edges.map((edge) => ({
+          id: edge.id,
+          from: edge.from,
+          to: edge.to,
+          ...(edge.toBoardId !== undefined ? { toBoardId: edge.toBoardId } : {}),
+          type: edge.type,
+        })),
       };
     }
     const board = canvasState.createBoardFromBoard({
       ...input,
       name: boardName(input.name),
-      category: boardCategory(input.category),
+      folder: boardFolder(input.folder),
     });
     if (!board) throw new OperationError('Could not create board from source.', 409);
     emitBoardsChanged(ctx);
@@ -324,6 +406,64 @@ const boardCreateFromOperation = defineOperation<z.infer<typeof fromSchema>, Rec
   },
 });
 
+// ── board.pin / board.unpin ───────────────────────────────────
+// A pinned board joins the agent's working set: its README and pinned cards
+// travel in the brief whichever board is open. Pinning is context, never a
+// write target; writes still go to the open board.
+
+const pinShape = {
+  id: z.unknown().optional().describe('Board id'),
+  reason: z.unknown().optional().describe('Why this board matters; shown to the human on hover'),
+};
+const pinSchema = z.looseObject(pinShape);
+
+const boardPinOperation = defineOperation<z.infer<typeof pinSchema>, Record<string, unknown>>({
+  name: 'board.pin',
+  mutates: false,
+  input: pinSchema,
+  inputShape: pinShape,
+  http: { method: 'POST', path: '/api/canvas/boards/:id/pin' },
+  mcp: {
+    toolName: 'canvas_pin_board',
+    description:
+      "Pin a board into the agent's working set: its README and pinned cards reach the brief whichever board is open. Read-only context; writes still go to the open board.",
+    extraShape: {
+      id: z.string().describe('Board id'),
+      reason: z.string().optional().describe('Why this board matters; shown to the human on hover'),
+    },
+    formatResult: jsonResult,
+  },
+  handler: (input, ctx) => {
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    const reason =
+      typeof input.reason === 'string' && input.reason.trim() ? input.reason.trim().slice(0, 280) : undefined;
+    if (!canvasState.pinBoard(id, reason)) throw new OperationError(`Board "${id}" not found.`, 404);
+    return { ok: true, ...emitBoardsChanged(ctx) };
+  },
+});
+
+const unpinShape = { id: z.unknown().optional().describe('Board id') };
+const unpinSchema = z.looseObject(unpinShape);
+
+const boardUnpinOperation = defineOperation<z.infer<typeof unpinSchema>, Record<string, unknown>>({
+  name: 'board.unpin',
+  mutates: false,
+  input: unpinSchema,
+  inputShape: unpinShape,
+  http: { method: 'POST', path: '/api/canvas/boards/:id/unpin' },
+  mcp: {
+    toolName: 'canvas_unpin_board',
+    description: "Remove a board from the agent's working set.",
+    extraShape: { id: z.string().describe('Board id') },
+    formatResult: jsonResult,
+  },
+  handler: (input, ctx) => {
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!canvasState.unpinBoard(id)) throw new OperationError(`Board "${id}" not found.`, 404);
+    return { ok: true, ...emitBoardsChanged(ctx) };
+  },
+});
+
 // ── board.delete (human only) ─────────────────────────────────
 
 const deleteShape = {
@@ -342,8 +482,7 @@ const boardDeleteOperation = defineOperation<z.infer<typeof deleteSchema>, Recor
     // Deleting the open board returns to Home through the same path as opening it.
     if (id === canvasState.activeBoardId) openCanvasBoard(null);
     if (!canvasState.deleteBoard(id)) throw new OperationError(`Board "${id}" not found.`, 404);
-    emitBoardsChanged(ctx);
-    return { ok: true, ...boardsPayload() };
+    return { ok: true, ...emitBoardsChanged(ctx) };
   },
 });
 
@@ -354,5 +493,7 @@ export const boardOperations: Operation[] = [
   boardCreateOperation,
   boardCreateFromOperation,
   boardUpdateOperation,
+  boardPinOperation,
+  boardUnpinOperation,
   boardDeleteOperation,
 ];

package/src/server/operations/ops/canvas-wire.ts

@@ -7,6 +7,7 @@
  * This module must never import server.ts or index.ts.
  */
 import { z } from 'zod';
+import { workspaceSettingsPatchSchema } from '../../../shared/workspace-settings.js';
 import { normalizeCanvasTheme } from '../../canvas-db.js';
 import { applyCanvasNodeUpdates } from '../../canvas-operations.js';
 import { canvasState } from '../../canvas-state.js';
@@ -98,4 +99,33 @@ const applyUpdatesOperation = defineOperation<z.infer<typeof applyUpdatesSchema>
   },
 });
 
-export const canvasWireOperations: Operation[] = [themeGetOperation, themeSetOperation, applyUpdatesOperation];
+const settingsGetOperation = defineOperation({
+  name: 'settings.get',
+  mutates: false,
+  input: emptySchema,
+  inputShape: emptyShape,
+  http: { method: 'GET', path: '/api/canvas/settings' },
+  handler: () => ({ ok: true, workspaceSettings: canvasState.getWorkspaceSettings() }),
+});
+
+const settingsSetOperation = defineOperation({
+  name: 'settings.set',
+  mutates: false,
+  // Strip transport attribution/precondition fields before storing the patch.
+  input: z.object(workspaceSettingsPatchSchema.shape),
+  inputShape: workspaceSettingsPatchSchema.shape,
+  http: { method: 'POST', path: '/api/canvas/settings' },
+  handler: (input, ctx) => {
+    const workspaceSettings = canvasState.updateWorkspaceSettings(input);
+    ctx.emit('settings-changed', { workspaceSettings });
+    return { ok: true, workspaceSettings };
+  },
+});
+
+export const canvasWireOperations: Operation[] = [
+  themeGetOperation,
+  themeSetOperation,
+  settingsGetOperation,
+  settingsSetOperation,
+  applyUpdatesOperation,
+];

package/src/server/operations/ops/edges.ts

@@ -4,6 +4,7 @@
  * This module must never import server.ts or index.ts.
  */
 import { z } from 'zod';
+import { relationKindSchema, relationReasonSchema } from '../../../shared/relations.js';
 import type { CanvasEdge } from '../../canvas-state.js';
 import { addCanvasEdge, removeCanvasEdge, updateCanvasEdge } from '../../canvas-operations.js';
 import { readJsonValue } from '../http.js';
@@ -16,6 +17,8 @@ const VALID_EDGE_STYLES = new Set(['solid', 'dashed', 'dotted']);
 // ── edge.add ──────────────────────────────────────────────────
 
 const edgeAddShape = {
+  destinationBoardId: z.string().min(1).optional().describe('Board owning the source and edge; does not activate it'),
+  requestId: z.string().min(1).optional().describe('Logical creation identity for retry-safe edge creation'),
   intentId: z
     .string()
     .optional()
@@ -23,6 +26,11 @@ const edgeAddShape = {
     .describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
   from: z.string().optional().catch(undefined).describe('Source node ID'),
   to: z.string().optional().catch(undefined).describe('Target node ID'),
+  toBoardId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Target board ID for a cross-board edge; independent of the source destinationBoardId'),
   fromSearch: z
     .string()
     .optional()
@@ -34,6 +42,10 @@ const edgeAddShape = {
     .catch(undefined)
     .describe('Resolve the target node by exact or fuzzy title/content search'),
   type: z.unknown().optional().describe('Edge type: flow, depends-on, relation, or references'),
+  kind: relationKindSchema
+    .optional()
+    .describe('Open semantic kind, e.g. supports, contradicts, derived-from, supersedes'),
+  reason: relationReasonSchema.optional().describe('Why this relation exists'),
   label: z.unknown().optional().describe('Edge label text'),
   style: z.unknown().optional().describe('Optional edge stroke style: solid, dashed, or dotted'),
   animated: z.unknown().optional().describe('Animate the edge stroke'),
@@ -80,7 +92,10 @@ const edgeAddOperation = defineOperation<z.infer<typeof edgeAddSchema>, CanvasEd
                 id: body.id,
                 from: body.from,
                 to: body.to,
+                ...(body.toBoardId ? { toBoardId: body.toBoardId } : {}),
                 type: body.type,
+                kind: body.kind,
+                reason: body.reason,
                 label: body.label,
                 style: body.style,
                 animated: body.animated,
@@ -108,16 +123,23 @@ const edgeAddOperation = defineOperation<z.infer<typeof edgeAddSchema>, CanvasEd
     }
     try {
       return addCanvasEdge({
+        destinationBoardId: input.destinationBoardId,
+        requestId: input.requestId,
+        intentId: input.intentId,
         ...(typeof body.from === 'string' ? { from: body.from } : {}),
         ...(typeof body.to === 'string' ? { to: body.to } : {}),
+        ...(typeof body.toBoardId === 'string' ? { toBoardId: body.toBoardId } : {}),
         ...(typeof body.fromSearch === 'string' ? { fromSearch: body.fromSearch } : {}),
         ...(typeof body.toSearch === 'string' ? { toSearch: body.toSearch } : {}),
         type: rawType as CanvasEdge['type'],
+        ...(input.kind ? { kind: input.kind } : {}),
+        ...(input.reason ? { reason: input.reason } : {}),
         ...(body.label ? { label: String(body.label) } : {}),
         ...(style ? { style: style as CanvasEdge['style'] } : {}),
         ...(body.animated !== undefined ? { animated: Boolean(body.animated) } : {}),
       });
     } catch (error) {
+      if (error instanceof OperationError) throw error;
       throw new OperationError(error instanceof Error ? error.message : 'Duplicate or self-edge.');
     }
   },
@@ -129,6 +151,8 @@ const edgeAddOperation = defineOperation<z.infer<typeof edgeAddSchema>, CanvasEd
 const edgeUpdateShape = {
   id: z.string().optional().catch(undefined).describe('Edge ID to update'),
   type: z.unknown().optional().describe('New edge type: flow, depends-on, relation, or references'),
+  kind: relationKindSchema.nullable().optional().describe('Semantic kind; null clears it'),
+  reason: relationReasonSchema.nullable().optional().describe('Why this relation exists; null clears it'),
   label: z.unknown().optional().describe('New label text; empty string or null clears the label'),
   style: z.unknown().optional().describe('New stroke style: solid, dashed, or dotted'),
   animated: z.unknown().optional().describe('Animate the edge stroke'),
@@ -162,7 +186,15 @@ const edgeUpdateOperation = defineOperation<z.infer<typeof edgeUpdateSchema>, Ca
           {
             type: 'text' as const,
             text: JSON.stringify(
-              { id: body.id, type: body.type, label: body.label, style: body.style, animated: body.animated },
+              {
+                id: body.id,
+                type: body.type,
+                kind: body.kind,
+                reason: body.reason,
+                label: body.label,
+                style: body.style,
+                animated: body.animated,
+              },
               null,
               2,
             ),
@@ -177,7 +209,9 @@ const edgeUpdateOperation = defineOperation<z.infer<typeof edgeUpdateSchema>, Ca
     if (!id) {
       throw new OperationError('Missing required field: id.');
     }
-    const patch: Partial<Pick<CanvasEdge, 'type' | 'label' | 'style' | 'animated'>> = {};
+    const patch: Partial<Pick<CanvasEdge, 'type' | 'kind' | 'reason' | 'label' | 'style' | 'animated'>> = {};
+    if ('kind' in input) patch.kind = input.kind ?? undefined;
+    if ('reason' in input) patch.reason = input.reason || undefined;
     if ('type' in body && body.type !== undefined) {
       if (typeof body.type !== 'string' || !VALID_EDGE_TYPES.has(body.type)) {
         throw new OperationError(`Invalid edge type: "${String(body.type)}".`);

package/src/server/operations/ops/groups.ts

@@ -21,6 +21,8 @@ function pickChildLayout(value: unknown): 'grid' | 'column' | 'flow' | undefined
 // ── group.create ──────────────────────────────────────────────
 
 const groupCreateShape = {
+  destinationBoardId: z.string().min(1).optional().describe('Create the group on this board without activating it'),
+  requestId: z.string().min(1).optional().describe('Logical creation identity for retry-safe group creation'),
   intentId: z
     .string()
     .optional()
@@ -90,7 +92,7 @@ const groupCreateOperation = defineOperation<z.infer<typeof groupCreateSchema>,
     const width = typeof body.width === 'number' ? body.width : undefined;
     const height = typeof body.height === 'number' ? body.height : undefined;
     const childLayout = pickChildLayout(body.childLayout);
-    if (childIds.length > 0) {
+    if (childIds.length > 0 && input.destinationBoardId === undefined && input.requestId === undefined) {
       const missingChildIds = childIds.filter((id) => !canvasState.getNode(id));
       if (missingChildIds.length > 0) {
         throw new OperationError(
@@ -99,6 +101,9 @@ const groupCreateOperation = defineOperation<z.infer<typeof groupCreateSchema>,
       }
     }
     return createCanvasGroup({
+      destinationBoardId: input.destinationBoardId,
+      requestId: input.requestId,
+      intentId: input.intentId,
       title,
       childIds,
       color,