pmx-canvas 0.9.3 → 0.10.0

package/dist/types/mcp/canvas-access.d.ts

@@ -1,16 +1,11 @@
 import { type CanvasLayout, type CanvasNodeState, type PmxCanvas } from '../server/index.js';
-import type { PmxAxSource } from '../server/ax-state.js';
 import type { ContextReadInput } from '../server/context-reads.js';
 import { type OperationInvoker } from '../server/operations/index.js';
 type AxStateResult = ReturnType<PmxCanvas['getAxState']>;
 type AxContextResult = ReturnType<PmxCanvas['getAxContext']>;
-type SubmitAxInteractionInput = Parameters<PmxCanvas['submitAxInteraction']>[0];
-type SubmitAxInteractionResult = ReturnType<PmxCanvas['submitAxInteraction']>;
 type GetPendingSteeringResult = ReturnType<PmxCanvas['getPendingSteering']>;
 type ListElicitationsResult = ReturnType<PmxCanvas['listElicitations']>;
 type ListModeRequestsResult = ReturnType<PmxCanvas['listModeRequests']>;
-type IngestActivityInput = Parameters<PmxCanvas['ingestActivity']>[0];
-type IngestActivityResult = ReturnType<PmxCanvas['ingestActivity']>;
 type GetPolicyResult = ReturnType<PmxCanvas['getPolicy']>;
 type GetAxTimelineQuery = Parameters<PmxCanvas['getAxTimeline']>[0];
 type GetAxTimelineResult = ReturnType<PmxCanvas['getAxTimeline']>;
@@ -38,18 +33,12 @@ export interface CanvasAccess {
     listWorkItems(): Promise<ListWorkItemsResult>;
     listApprovalGates(): Promise<ListApprovalGatesResult>;
     listReviewAnnotations(): Promise<ListReviewAnnotationsResult>;
-    submitAxInteraction(input: SubmitAxInteractionInput, options?: {
-        source?: PmxAxSource;
-    }): Promise<SubmitAxInteractionResult>;
     getPendingSteering(options?: {
         consumer?: string;
         limit?: number;
     }): Promise<GetPendingSteeringResult>;
     listElicitations(): Promise<ListElicitationsResult>;
     listModeRequests(): Promise<ListModeRequestsResult>;
-    ingestActivity(input: IngestActivityInput, options?: {
-        source?: PmxAxSource;
-    }): Promise<IngestActivityResult>;
     getPolicy(): Promise<GetPolicyResult>;
     getHistory(): Promise<HistoryResult>;
     getPinnedNodeIds(board?: string): Promise<string[]>;
@@ -62,7 +51,7 @@ export interface CanvasAccess {
     runBatch(operations: RunBatchInput): Promise<RunBatchResult>;
     getCodeGraph(): Promise<CodeGraphResult>;
     getAutomationWebViewStatus(): Promise<AutomationWebViewStatus>;
-    screenshotAutomationWebView(options?: AutomationScreenshotOptions): Promise<Uint8Array>;
+    screenshotAutomationWebView(options?: AutomationScreenshotOptions, signal?: AbortSignal): Promise<Uint8Array>;
 }
 export declare function refreshCanvasAccess(access: CanvasAccess): Promise<CanvasAccess>;
 /**

package/dist/types/mcp/resource-subscriptions.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CanvasAccess } from './canvas-access.js';
+/** One subscription set and event source per MCP connection. Notifications are not reads. */
+export declare function registerResourceSubscriptions(server: McpServer, getCanvas: () => Promise<CanvasAccess>): {
+    attach: (canvas: CanvasAccess) => void;
+    dispose: () => void;
+};

package/dist/types/mcp/server.d.ts

@@ -19,4 +19,6 @@
  * }
  * ```
  */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createMcpServer(): McpServer;
 export declare function startMcpServer(): Promise<void>;

package/dist/types/server/ax-wait.d.ts

@@ -33,4 +33,5 @@ export declare function waitForAxCondition(opts: {
     ready: () => boolean;
     timeoutMs: number;
     channel?: string;
+    signal?: AbortSignal;
 }): Promise<void>;

package/dist/types/server/canvas-operations.d.ts

@@ -168,6 +168,7 @@ export declare function resolveCanvasNode(nodeRef: CanvasNodeLookupInput): {
 };
 export declare function refreshCanvasWebpageNode(id: string, options?: {
     url?: string;
+    signal?: AbortSignal;
 }): Promise<{
     ok: boolean;
     id: string;

package/dist/types/server/index.d.ts

@@ -1,8 +1,8 @@
 import { EventEmitter } from 'node:events';
 import type { Camera, Tour, TourStop } from '../shared/tour.js';
-import { type TourStep, type TourStepResult } from './tour-control.js';
+import { type TourState, type TourStep, type TourStepResult } from './tour-control.js';
 export type { Tour, TourStop } from '../shared/tour.js';
-export type { TourStep, TourStepResult } from './tour-control.js';
+export type { TourState, TourStep, TourStepResult } from './tour-control.js';
 import type { AgentPhase, AgentPresence, AgentPresenceSnapshot } from '../shared/agent-presence.js';
 import { canvasState } from './canvas-state.js';
 import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
@@ -163,7 +163,7 @@ export declare class PmxCanvas extends EventEmitter {
     ungroupNodes(groupId: string, options?: {
         intentId?: string;
     }): boolean;
-    getTour(): Tour;
+    getTour(): TourState;
     setTour(tour: Tour | null): void;
     /** Present a tour stop (index, `next` or `previous`) in the workbench. Not recorded in undo history. */
     goToTourStop(step: TourStep, options?: {

package/dist/types/server/operations/http.d.ts

@@ -1,3 +1,13 @@
+import { type OperationProgress } from './types.js';
+/** Opt-in NDJSON; the terminal frame retains the ordinary HTTP status/body. */
+export type OperationStreamFrame = {
+    type: 'progress';
+    progress: OperationProgress;
+} | {
+    type: 'result';
+    status: number;
+    body: unknown;
+};
 export declare function matchOperationPath(template: string, pathname: string): Record<string, string> | null;
 /**
  * Shared body reader: preserves the parsed JSON value as-is (object, array,

package/dist/types/server/operations/index.d.ts

@@ -3,6 +3,6 @@ export { dispatchOperationRoute } from './http.js';
 export { runCanvasBatchOperation, type BatchEnvelope } from './ops/batch.js';
 export type { OpenMcpAppCoreResult } from './ops/app.js';
 export { LocalOperationInvoker, HttpOperationInvoker, type OperationInvoker } from './invoker.js';
-export { registerOperationTools, registerCompositeTools, type OperationToolHost } from './mcp.js';
+export { registerOperationTools, registerCompositeTools, registerOperationHelpTool, type OperationToolHost, } from './mcp.js';
 export { compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';
-export { OperationError, defineOperation, type Operation, type OperationContext, type OperationDefinition, type OperationErrorStatus, } from './types.js';
+export { OperationError, defineOperation, type Operation, type OperationContext, type OperationDefinition, type OperationExecutionOptions, type OperationErrorStatus, type OperationProgress, } from './types.js';

package/dist/types/server/operations/invoker.d.ts

@@ -1,5 +1,6 @@
+import { type OperationExecutionOptions } from './types.js';
 export interface OperationInvoker {
-    invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
+    invoke(name: string, input: Record<string, unknown>, options?: OperationExecutionOptions): Promise<unknown>;
 }
 /**
  * The agent-presence label for a transport: `PMX_CANVAS_AGENT_SOURCE` lets a
@@ -14,7 +15,7 @@ export declare class LocalOperationInvoker implements OperationInvoker {
     private readonly proxiedRead;
     /** `source` labels this caller's agent presence ('mcp', 'sdk', …). */
     constructor(source?: string, allowExternalMcp?: boolean);
-    invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
+    invoke(name: string, input: Record<string, unknown>, options?: OperationExecutionOptions): Promise<unknown>;
 }
 /** Builds the HTTP request from the op's route template (`:id` from input, GET flags to query). */
 export declare class HttpOperationInvoker implements OperationInvoker {
@@ -24,5 +25,5 @@ export declare class HttpOperationInvoker implements OperationInvoker {
     private readonly proxiedRead;
     /** `source` labels this caller's agent presence on the server ('cli', 'mcp', …). */
     constructor(baseUrl: string, source?: string, allowExternalMcp?: boolean);
-    invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown>;
+    invoke(name: string, rawInput: Record<string, unknown>, options?: OperationExecutionOptions): Promise<unknown>;
 }

package/dist/types/server/operations/mcp-contracts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MCP's output is the FORMATTER projection, never the larger HTTP payload.
+ * `result` wraps prose/arrays without pretending they are JSON objects. Each
+ * operation validates its stable fields; loose payloads preserve full:true and
+ * extensible node/app data. No schema advertises an unconstrained root record.
+ */
+import { z } from 'zod';
+import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+export declare function operationOutputSchema(operations: string[]): z.ZodObject<{
+    result: z.ZodUnion<readonly [...z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>[], z.ZodObject<{
+        operation: z.ZodNull;
+        outcome: z.ZodLiteral<"error">;
+        data: z.ZodObject<{
+            message: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+export declare function structuredOperationResult(operation: string, formatted: CallToolResult): CallToolResult;
+export declare function operationToolError(error: unknown): CallToolResult;
+export declare function operationToolAnnotations(toolName: string): ToolAnnotations;

package/dist/types/server/operations/mcp.d.ts

@@ -12,6 +12,8 @@ export interface OperationToolHost extends OperationMcpToolHost {
     recordContextRead(read: ContextReadInput): Promise<void>;
 }
 export declare function registerOperationTools(server: McpServer, getHost: () => Promise<OperationToolHost>): void;
+/** Registry metadata only: never boots a canvas or records a content read. */
+export declare function registerOperationHelpTool(server: McpServer): void;
 /**
  * Register composite (action-discriminated) MCP tools (plan-006). Each action
  * dispatches to a registered operation, reusing that op's `mcp.buildInput` and

package/dist/types/server/operations/ops/batch.d.ts

@@ -5,6 +5,7 @@ export interface BatchEnvelope {
     refs: Record<string, unknown>;
     failedIndex?: number;
     error?: string;
+    cancelled?: boolean;
 }
 export declare const batchOperations: Operation[];
 /**

package/dist/types/server/operations/registry.d.ts

@@ -1,4 +1,4 @@
-import { type Operation } from './types.js';
+import { type Operation, type OperationExecutionOptions } from './types.js';
 export declare function registerOperation(op: Operation): void;
 export declare function getOperation(name: string): Operation;
 export declare function listOperations(): Operation[];
@@ -12,7 +12,7 @@ export declare function getOperationEventEmitter(): OperationEventEmitter | null
 export declare function isEmitSuppressed(): boolean;
 /** Suppress this call chain's per-entry frames; the batch emits its final frame afterward. */
 export declare function runWithSuppressedEmits<T>(fn: () => Promise<T>): Promise<T>;
-export interface ExecuteOperationMeta {
+export interface ExecuteOperationMeta extends OperationExecutionOptions {
     /**
      * Skip the synthesized auto-ghost: set by the workbench's own HTTP calls
      * (a human dragging a node is not agent activity) and by canvas.batch for

package/dist/types/server/operations/types.d.ts

@@ -20,7 +20,17 @@ export declare class OperationError extends Error {
     readonly details?: Record<string, unknown>;
     constructor(message: string, status?: OperationErrorStatus, details?: Record<string, unknown>);
 }
-export interface OperationContext {
+export interface OperationProgress {
+    progress: number;
+    total?: number;
+    message?: string;
+}
+/** Cooperative cancellation: completed writes are never rolled back. */
+export interface OperationExecutionOptions {
+    signal?: AbortSignal;
+    onProgress?: (progress: OperationProgress) => void | Promise<void>;
+}
+export interface OperationContext extends OperationExecutionOptions {
     /** Emit a workbench SSE event (e.g. extra `canvas-layout-update` frames, focus, viewport). */
     emit(event: string, payload?: Record<string, unknown>): void;
 }
@@ -53,7 +63,7 @@ export interface OperationMcpToolHost {
      * restore summary).
      */
     invoker(): {
-        invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
+        invoke(name: string, input: Record<string, unknown>, options?: OperationExecutionOptions): Promise<unknown>;
     };
 }
 export interface OperationMcpTool {

package/dist/types/server/server.d.ts

@@ -80,6 +80,8 @@ export interface PrimaryWorkbenchCanvasPromptRequest {
     contextNodeIds: string[];
 }
 type PrimaryWorkbenchCanvasPromptHandler = (request: PrimaryWorkbenchCanvasPromptRequest) => Promise<void>;
+/** In-process invalidation observers share the same events as daemon SSE clients. */
+export declare function onWorkbenchEvent(listener: (event: string) => void): () => void;
 export declare function setPrimaryWorkbenchAutoOpenEnabled(enabled: boolean): void;
 export declare function isPrimaryWorkbenchAutoOpenEnabled(): boolean;
 export declare function hasWorkbenchSubscribers(): boolean;

package/dist/types/server/webpage-node.d.ts

@@ -37,6 +37,7 @@ export declare function checkWebpageHop(originScope: AddressScope, hopScope: Add
 export declare function fetchWebpageSnapshot(inputUrl: string, options?: {
     resolveHost?: ResolveHost;
     timeoutMs?: number;
+    signal?: AbortSignal;
 }): Promise<WebpageSnapshot>;
 export declare function getWebpageFetchErrorDetails(error: unknown): {
     message: string;

package/docs/api-reference.md

@@ -6,7 +6,7 @@
 
 ## MCP Server
 
-24 tools: 18 action-discriminated composites (`canvas_import`, `canvas_board`, `canvas_node`, `canvas_render`, `canvas_edge`, `canvas_group`, `canvas_history`, `canvas_view`, `canvas_query`, `canvas_webview`, `canvas_app`, `canvas_snapshot`, `canvas_ax_state`, `canvas_ax_work`, `canvas_ax_gate`, `canvas_ax_timeline`, `canvas_ax_delivery`, `canvas_intent`) plus 6 standalone tools (`canvas_batch`, `canvas_pin_nodes`, `canvas_invoke_command`, `canvas_ax_interaction`, `canvas_ingest_activity`, `canvas_screenshot`). `canvas_import` is the agent half of the human-consented attachment workflow: agents list/read requested imports, submit reviewable Markdown, or report unavailable; they cannot request, cancel, or commit. The 57 legacy single-purpose tools the composites replaced were removed in v0.3.0; v0.4.0 shipped the `canvas_snapshot` composite and removed the 6 deprecated snapshot standalones. Prefer composites for new MCP calls; see `docs/mcp.md` for the authoritative tool list and the legacy-to-composite migration reference.
+25 tools: 18 action-discriminated composites (`canvas_import`, `canvas_board`, `canvas_node`, `canvas_render`, `canvas_edge`, `canvas_group`, `canvas_history`, `canvas_view`, `canvas_query`, `canvas_webview`, `canvas_app`, `canvas_snapshot`, `canvas_ax_state`, `canvas_ax_work`, `canvas_ax_gate`, `canvas_ax_timeline`, `canvas_ax_delivery`, `canvas_intent`) plus 7 standalone tools (`canvas_help`, `canvas_batch`, `canvas_pin_nodes`, `canvas_invoke_command`, `canvas_ax_interaction`, `canvas_ingest_activity`, `canvas_screenshot`). `canvas_help { op }` returns one MCP registry operation's public arguments and guidance without accessing the canvas; omit `op` to list names. `canvas_import` is the agent half of the human-consented attachment workflow: agents list/read requested imports, submit reviewable Markdown, or report unavailable; they cannot request, cancel, or commit. The 57 legacy single-purpose tools the composites replaced were removed in v0.3.0; v0.4.0 shipped the `canvas_snapshot` composite and removed the 6 deprecated snapshot standalones. Prefer composites for new MCP calls; see `docs/mcp.md` for the authoritative tool list and the legacy-to-composite migration reference.
 
 ### Agent-assisted document imports
 
@@ -18,7 +18,7 @@ The `diagram` action of `canvas_app` is a thin preset in `src/server/diagram-pre
 
 15 static canvas resources: `canvas://boards`, `canvas://pinned-context`, `canvas://schema`, `canvas://layout`, `canvas://summary`, `canvas://spatial-context`, `canvas://history`, `canvas://code-graph`, `canvas://ax`, `canvas://ax-context`, `canvas://ax-timeline`, `canvas://ax-work`, `canvas://ax-pending-steering`, `canvas://ax-delivery`, `canvas://skills`; two canvas resource templates: `canvas://context{?budget,consumer,since}` and `canvas://graph{?focus,depth}`. Bundled skills additionally register per-skill `canvas://skills/<name>` resources and the `skill://{name}/{+path}` file template.
 
-Resource change notifications: the MCP server emits `notifications/resources/updated` when canvas state changes. Pin changes notify `canvas://pinned-context`; all mutations notify `canvas://layout`, `canvas://summary`, `canvas://spatial-context`, `canvas://history`, `canvas://code-graph`, and `canvas://graph`. This enables real-time human→agent collaboration — humans pin nodes in the browser, agents are notified immediately.
+Resource change notifications: subscribe to each live URI to receive `notifications/resources/updated` when canvas state or knowledge policies change. Notifications invalidate cached data without reading it. Subscriptions belong to the connection; subscribe again after reconnecting. See [Resource subscriptions](mcp.md#resource-subscriptions-010).
 
 ### AX Primitives (host-agnostic)
 

package/docs/cli.md

@@ -100,7 +100,7 @@ Tours persist with the board and snapshots, participate in undo, and clear with
 the board. A file containing `null` resets the tour: when none is saved, groups
 are sorted by y, then x, then ID. A saved empty `stops` array deliberately has no
 stops. SDK: `canvas.setTour(tourOrNull)` / `canvas.getTour()`, which returns
-the tour directly; read stops from `.stops`.
+`{ tour, derived, position }` as of 0.10; read stops from `.tour.stops`.
 
 ### Driving a tour (agents)
 

package/docs/http-api.md

@@ -3,6 +3,37 @@
 REST endpoints for all canvas operations + an SSE event stream. Works from
 any language. Default base URL: `http://localhost:4313`.
 
+## Operation cancellation and progress (0.10)
+
+Registry-backed operation routes use the request's abort signal. Disconnecting
+stops supported AX waits, cancels webpage fetching and prevents later batch
+operations from starting. Completed writes remain. Cancellation is cooperative:
+external app builds/runtime calls and local WebView captures cannot be interrupted
+mid-call. A standalone cancelled operation returns HTTP 499 with
+`{ "ok": false, "cancelled": true, "error": "Operation cancelled." }` when the
+connection still permits a response. An interrupted batch retains completed
+`results` and `refs` in its partial-failure body and adds `cancelled: true`.
+Disconnected clients must inspect state before retrying; they may never receive
+that body. Cancellation is not rollback.
+
+Send `Accept: application/x-ndjson` to opt into batch and supported AX wait progress
+over the operation response stream. Each newline-delimited JSON frame is one of:
+
+```json
+{"type":"progress","progress":{"progress":1,"total":3,"message":"node.add"}}
+{"type":"result","status":200,"body":{"ok":true,"results":[],"refs":{}}}
+```
+
+The examples show frame shapes, not one complete batch. The terminal `result`
+frame carries the ordinary operation status and body; the stream's HTTP 200 does
+not establish operation success. Without this header, routes keep their ordinary
+JSON status/body. Early validation errors may still be ordinary JSON. The
+in-process and HTTP operation invokers accept optional `{ signal, onProgress }`;
+the HTTP invoker negotiates this stream only when given a progress callback.
+
+AX wait routes accept `timeoutMs` as well as the direct-HTTP `waitMs` parameter;
+`timeoutMs` takes precedence when both are supplied.
+
 ## Knowledge lifecycle data (plan 017 slice 1)
 
 The slice-1 data contract now also drives the workbench, due engine and qualified agent context.

package/docs/mcp.md

@@ -1,10 +1,92 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **24 tools**, **15 static canvas
+PMX Canvas ships an MCP stdio server with **25 tools**, **15 static canvas
 resources**, and two canvas resource templates, plus per-skill resources at
 `canvas://skills/<name>` and the `skill://{name}/{+path}` template. The server emits
-`notifications/resources/updated` when canvas state changes — humans pin
-nodes in the browser, agents are notified immediately.
+`notifications/resources/updated` to subscribed connections when canvas state changes.
+This uses MCP SDK v1, not SDK v2.
+
+## Operation help (0.10)
+
+Call `canvas_help {}` for the sorted registry names exposed through MCP, then
+`canvas_help { op: "node.add" }` for one operation's public `tool`, `description`
+and JSON `inputSchema`. The schema includes required fields, public field names
+and constant routing selectors (`action`, and `kind` for gates). For example,
+`ax.approval.request` maps to `canvas_ax_gate` with `kind: "approval"`,
+`action: "request"` and the optional `approvalAction` field.
+
+Text contains the JSON result; structured content wraps it in `{ result }`.
+Unknown names, internal/human-only operations and non-registry tools such as
+`canvas_screenshot` return text-only `isError`; use `tools/list` for those tools.
+Help reads registry metadata only: it never starts a canvas, writes state, records
+a content read or advances a cursor. It is read-only and idempotent.
+
+Help derives its schema and guidance from the operation registry, not from live
+board state. Handlers still enforce conditional requirements and authorization.
+Existing input schemas stay in `tools/list`; help does not enable lazy discovery
+in hosts. Repeated equivalent output branches are grouped within each tool,
+preserving operation/payload validation and partial-error receipts.
+
+## Tool results and effect hints (0.10)
+
+All 25 tools advertise an object `outputSchema`. Registry-dispatched tools return
+`structuredContent.result = { operation, outcome, data }`. `operation` names the
+dispatched action (for example `node.add`), `outcome` is `success`, `error` or
+`partial`, and `data` is the existing compact tool result. Prose results use
+`data.message`. Exceptions use `operation: null`, `outcome: "error"` and
+`data.message`; this does not guarantee that nothing changed before the exception.
+Batch failures retain completed `results` and `refs`, with `partial` when at least
+one entry completed. Check both `isError` and the outcome before using a result.
+
+The three handwritten tools keep direct structured objects: `canvas_ax_interaction`
+returns its accepted interaction, `canvas_ingest_activity` its event and reaction
+records, and `canvas_screenshot` capture metadata alongside model-visible image
+content. Their errors are text-only `isError` replies. Existing model-facing text
+and compact/full projections remain unchanged; structured results do not introduce
+additional full-card or UI payloads. Inspect the advertised schema for each tool.
+
+All tools declare `readOnlyHint`, `destructiveHint`, `idempotentHint` and
+`openWorldHint`. Composite hints cover every action, not only their read actions.
+`canvas_query` is not read-only because context reads can advance a durable
+consumer cursor. Hints describe effects; they grant no permission or retry guarantee.
+
+## Cancellation and progress (0.10)
+
+MCP cancellation reaches the operation layer in both local and daemon-attached
+connections. Supported AX waits release their listeners and timers immediately;
+batches stop before the next operation and keep completed writes. Webpage fetches
+receive the signal and stop before writing fetched content after cancellation.
+Cancellation does not roll back a created node or other completed mutations.
+If webpage creation already committed, its receipt retains `fetch.cancelled: true`.
+External app builds/runtime calls and local WebView captures are not interruptible
+mid-call; do not treat cancellation as proof that those side effects stopped.
+
+Calls supplying `_meta.progressToken` receive `notifications/progress` at batch
+entry boundaries and supported AX wait start/completion, with `progress`, optional
+`total`, optional `message` and the same token. This works over the daemon bridge
+as well as local stdio. No token means
+no progress notifications. A host that aborts its connection may not receive a
+partial result; inspect canvas state before retrying. See the
+[HTTP streaming contract](http-api.md#operation-cancellation-and-progress-010).
+
+## Resource subscriptions (0.10)
+
+The server advertises `resources.subscribe`. Send `resources/subscribe` with an
+exact live URI, then `resources/unsubscribe` to stop. Subscriptions belong to the
+connection and disappear on close; reconnecting clients must subscribe again.
+
+Live resources are `canvas://layout`, `boards`, `summary`, `context`, `graph`,
+`spatial-context`, `history`, `code-graph`, `pinned-context`, `ax`, `ax-context`,
+`ax-timeline`, `ax-work`, `ax-pending-steering` and `ax-delivery` (each with the
+`canvas://` prefix). Parameterized context and graph URIs are supported, for example
+`canvas://context?consumer=my-agent&budget=3000`; notifications echo the exact
+subscribed URI. Static schema and bundled skill resources do not support subscriptions.
+
+Notifications invalidate cached data, not deliver it. Read the resource when needed.
+They can be broader than the underlying change, and daemon reconnection invalidates
+subscribed resources to cover missed events. Notification delivery does not record
+a context read or advance a consumer cursor. Explicit `resources/read` works without
+subscriptions, including on hosts that do not use this capability.
 
 > **Consolidation complete (plan-006/008).** The MCP surface shrank from 84
 > tools to 22: 16 action-discriminated **composites** (recommended — see
@@ -83,12 +165,12 @@ Add to your agent's MCP config:
 }
 ```
 
-The canvas auto-starts on first tool call.
+The canvas auto-starts on first canvas operation, not on `canvas_help`.
 
 ## Private MCP App preview
 
 `pmx-canvas --mcp-app` runs a **separate, experimental stdio profile**; the
-24-tool `--mcp` profile above is unchanged. Build from this checkout first:
+25-tool `--mcp` profile above is separate. Build from this checkout first:
 
 ```bash
 bun run build
@@ -358,7 +440,7 @@ Single-card and layout reads record delivered content, not incident relations.
 Use a complete graph or brief relation entry to acknowledge those relations.
 Reads never mark full card content read or
 switch the workbench. Pull needed cards in full separately.
-No new tool is added: the tool count stays 24.
+These reads add no tools beyond the catalog listed above.
 
 Library search is `canvas_query { action: "search", query: "auth", scope:
 "library" }`. It returns board/card IDs and never switches the active board.
@@ -491,13 +573,14 @@ agent intends to publish its own cursor or attention target.
 
 ## Standalone tools
 
-6 tools that intentionally stay outside the composites — folding them would
+7 tools that intentionally stay outside the composites — folding them would
 hurt (distinct callers, binary payloads, trust-boundary or execution-intent
 semantics). See [Migration reference](#migration-reference) below for the
 legacy tools the composites replaced.
 
 | Tool | Description |
 |------|-------------|
+| `canvas_help` | List MCP registry operations or fetch one operation's public arguments and guidance (`op` optional); no canvas access |
 | `canvas_batch` | Run a batch of canvas operations with `$ref` support |
 | `canvas_pin_nodes` | Pin nodes to include in agent context (`nodeIds`, `mode` set/add/remove, optional `reason` shown to the human) |
 | `canvas_invoke_command` | Invoke a registry command (`pmx.plan`, `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`); records a `command` agent-event, unknown names rejected |
@@ -703,20 +786,9 @@ interaction against the node's effective capabilities.
 
 ## Change notifications
 
-The MCP server emits `notifications/resources/updated` whenever canvas state
-changes:
-
-- Pin changes notify `canvas://pinned-context`, `canvas://ax`, and `canvas://ax-context`
-- AX focus changes notify `canvas://ax` and `canvas://ax-context`
-- Canvas-bound AX mutations (work items, approval gates, review annotations,
-  host capability) notify `canvas://ax`, `canvas://ax-work`, and `canvas://ax-context`
-- AX timeline mutations (agent-events, evidence, steering) notify
-  `canvas://ax-timeline` and `canvas://ax-context`
-- All mutations notify `canvas://layout`, `canvas://summary`,
-  `canvas://spatial-context`, `canvas://history`, `canvas://code-graph`, and `canvas://graph`
-
-This closes the human-to-agent loop: spatial curation in the browser becomes
-an immediate signal in the agent's context.
+Notifications require an explicit subscription to each live resource URI. See
+[Resource subscriptions](#resource-subscriptions-010) for connection lifetime,
+reconnection and broad cache invalidation. Receiving a notification is not a content read.
 
 ## Codex App Adapter