pmx-canvas 0.2.7 → 0.3.1

package/docs/mcp.md

@@ -1,17 +1,19 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **84 tools** + **14 core resources**,
+PMX Canvas ships an MCP stdio server with **27 tools** + **14 core resources**,
 plus per-skill resources at `canvas://skills/<name>`. The server emits
 `notifications/resources/updated` when canvas state changes — humans pin
 nodes in the browser, agents are notified immediately.
 
-> **Consolidation in progress (plan-006/008).** The 84 tools are 15 action-discriminated
-> **composites** (recommended — see below) plus 69 legacy single-purpose tools.
-> The composites fold the legacy tools behind an `action` (and, for `canvas_ax_gate`,
-> a `kind`) enum; each action dispatches to the same operation, so behavior is
-> identical. Folded legacy tools are marked `Deprecated:` in their descriptions and
-> are removed in v0.3 per [`api-stability.md`](api-stability.md). **Prefer the
-> composites.**
+> **Consolidation completed in v0.3.0 (plan-006/008).** The MCP surface shrank
+> from 84 tools to 27: 15 action-discriminated **composites** (recommended —
+> see below) plus 12 standalone tools. The 57 legacy single-purpose tools that
+> the composites replaced were removed in v0.3.0 per
+> [`api-stability.md`](api-stability.md); their descriptions carried
+> `Deprecated:` prefixes for one minor before removal. The 6 snapshot tools
+> remain registered as deprecated standalones — they fold into a
+> `canvas_snapshot` composite in v0.4 (see [Standalone tools](#standalone-tools)
+> below). **Prefer the composites.**
 
 ## Connect
 
@@ -35,15 +37,15 @@ The canvas auto-starts on first tool call.
 Action-discriminated tools that consolidate the single-purpose tools. Each maps
 its `action` to the same operation the legacy tool used, so results are identical.
 
-| Composite | `action` values | Replaces |
+| Composite | `action` values | Replaced (removed in v0.3.0) |
 |-----------|-----------------|----------|
 | `canvas_node` | `add` · `get` · `update` · `remove` | `canvas_add_node`, `canvas_get_node`, `canvas_update_node`, `canvas_remove_node`, `canvas_add_html_node` (`add` + `type:"html"`), `canvas_add_html_primitive` (`add` + `type:"html"`, `primitive:"<kind>"`), `canvas_refresh_webpage_node` (`update` + `refresh:true`) |
 | `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` | `canvas_describe_schema`, `canvas_validate_spec`, `canvas_add_json_render_node`, `canvas_stream_json_render_node`, `canvas_add_graph_node` |
 | `canvas_edge` | `add` · `remove` | `canvas_add_edge`, `canvas_remove_edge` |
 | `canvas_group` | `create` · `add` · `ungroup` | `canvas_create_group`, `canvas_group_nodes`, `canvas_ungroup` |
 | `canvas_history` | `undo` · `redo` | `canvas_undo`, `canvas_redo` |
-| `canvas_view` | `arrange` · `focus` · `fit` · `clear` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear` |
-| `canvas_query` | `search` · `layout` | `canvas_search`, `canvas_get_layout` |
+| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear`, `canvas_remove_annotation` |
+| `canvas_query` | `search` · `layout` · `validate` | `canvas_search`, `canvas_get_layout`, `canvas_validate` |
 | `canvas_webview` | `status` · `start` · `stop` · `resize` · `evaluate` | `canvas_webview_status`, `canvas_webview_start`, `canvas_webview_stop`, `canvas_resize`, `canvas_evaluate` |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | `canvas_open_mcp_app`, `canvas_add_diagram`, `canvas_build_web_artifact` |
 | `canvas_ax_state` | `get` · `set-focus` · `set-policy` · `report-capability` | `canvas_get_ax`, `canvas_set_ax_focus`, `canvas_set_ax_policy`, `canvas_report_host_capability` |
@@ -64,7 +66,7 @@ veto it — before the mutation lands.
 - `clear` — abandon/dissolve it explicitly. Normal linked mutations settle automatically.
 
 Intents are **ephemeral presence**: never persisted, never snapshotted, never in
-`canvas_get_layout`, and auto-expiring. They ride their own SSE channel
+`canvas_query { action: "layout" }`, and auto-expiring. They ride their own SSE channel
 (`ax-intent` / `ax-intent-clear`) and replay to reconnecting browsers while still
 live. Best practice — narrate your next move: `signal` → mutate with the returned
 `intent.id` as `intentId`. A vetoed or expired linked mutation is rejected, and a
@@ -87,86 +89,105 @@ tools). `canvas_screenshot` also stays standalone — it returns a binary image
 the composite/registry JSON wire shape does not model. (Wave 5 folded
 `canvas_refresh_webpage_node` → `canvas_node { action: "update", refresh: true }` after
 fixing `node.update`'s `formatResult` to surface a FAILED refresh as `isError` +
-`{ ok:false, error }` instead of masking it as a false `{ ok:true }`.) Snapshots
-fold as their registry slice lands.
+`{ ok:false, error }` instead of masking it as a false `{ ok:true }`.) The 6
+snapshot tools are the one deferred fold: a `canvas_snapshot` composite is
+planned for v0.4 (the name collides with the legacy `canvas_snapshot` save
+tool, and [`api-stability.md`](api-stability.md) requires deprecating a tool
+for one minor before removing it) — they stay registered as deprecated
+standalones until then.
 
-## Tools (legacy single-purpose)
+## Standalone tools
+
+12 tools that intentionally stay outside the composites — either because
+folding them would hurt (distinct callers, binary payloads, trust-boundary or
+execution-intent semantics), or because they're mid-deprecation pending a
+v0.4 composite. See [Migration reference](#migration-reference) below for the
+57 tools these composites replaced.
 
 | Tool | Description |
 |------|-------------|
-| `canvas_add_node` | Add a node (markdown, status, context, file, webpage, html, etc.) |
-| `canvas_add_html_node` | **Deprecated** → `canvas_node { action: "add", type: "html" }`. Create an `html` node from a self-contained HTML/JS document (sandboxed iframe) |
-| `canvas_add_html_primitive` | **Deprecated** → `canvas_node { action: "add", type: "html", primitive: "<kind>" }`. Create a reusable generated HTML communication primitive as a sandboxed `html` node |
-| `canvas_add_diagram` | Hand-drawn diagram via the hosted Excalidraw MCP App (preset alias for `canvas_open_mcp_app`) |
-| `canvas_open_mcp_app` | Open any [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) server's `ui://` resource as an iframe node |
-| `canvas_describe_schema` | Describe the running server's create schemas, examples, json-render catalog, and HTML primitive catalog |
-| `canvas_validate_spec` | Validate a json-render spec, graph payload, or HTML primitive payload without creating a node |
-| `canvas_refresh_webpage_node` | **Deprecated** → `canvas_node { action: "update", refresh: true }`. Re-fetch and update a webpage node from its stored URL |
-| `canvas_add_json_render_node` | Create a native json-render node from a validated spec |
-| `canvas_stream_json_render_node` | Progressively build a json-render node from SpecStream JSON-Patch ops (live/streaming panels) |
-| `canvas_add_graph_node` | Create a native graph node (line, bar, pie, area, scatter, radar, stacked-bar, composed, sparkline, dot-plot, bullet, slopegraph) |
-| `canvas_build_web_artifact` | Build a bundled HTML artifact and open it on the canvas |
-
-`canvas_add_html_node` accepts optional `summary`, `agentSummary`, `embeddedNodeIds`, and
-`embeddedUrls`. PMX also derives a bounded text summary from visible HTML, so rich HTML nodes stay
-searchable and readable in pinned/spatial context.
-| `canvas_update_node` | Update content, position, size, collapsed state |
-| `canvas_remove_node` | Remove a node and its edges |
-| `canvas_get_layout` | Get full canvas state |
-| `canvas_get_node` | Get a single node by ID |
-| `canvas_remove_annotation` | Remove a human-drawn annotation by ID |
-| `canvas_add_edge` | Connect two nodes |
-| `canvas_remove_edge` | Remove a connection |
-| `canvas_arrange` | Auto-arrange (grid/column/flow) |
-| `canvas_validate` | Validate collisions, containment, and missing edge endpoints |
-| `canvas_focus_node` | Pan viewport to a node; use CLI `focus --no-pan` when you only need to select/raise |
-| `canvas_fit_view` | Fit the canvas viewport to all nodes or a selected subset |
-| `canvas_get_ax` | Read the PMX AX state (focus, work items, approvals, review annotations, host capability) plus pinned/focused context |
-| `canvas_set_ax_focus` | Set the host-agnostic AX focus node set; adapters can pass a source such as `codex` |
-| `canvas_record_ax_event` | Record a normalized timeline `agent-event` (prompt/assistant-message/tool-start/tool-result/failure/approval/steering) |
-| `canvas_send_steering` | Record a `steering-message`: a user instruction from the surface to the active agent session |
-| `canvas_get_ax_timeline` | Read the bounded AX timeline (events, evidence, steering) plus counts |
-| `canvas_add_work_item` | Add a canvas-bound `work-item` (visible task/plan/status tied to nodes) |
-| `canvas_update_work_item` | Update a work item's title/status/detail/nodeIds by ID |
-| `canvas_request_approval` | Request human approval via an `approval-gate` (pending) before a high-impact action |
-| `canvas_resolve_approval` | Resolve a pending approval gate (`approved`/`rejected`) |
-| `canvas_add_evidence` | Record an `evidence-item` on the timeline (logs/tool-result/screenshot/file/diff/test-output) |
-| `canvas_add_review_annotation` | Add a canvas-bound `review-annotation` (comment/finding) anchored to a node, file, or region |
-| `canvas_report_host_capability` | Report a host/session `host-capability` for diagnostics |
+| `canvas_batch` | Run a batch of canvas operations with `$ref` support |
+| `canvas_pin_nodes` | Pin nodes to include in agent context |
+| `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 |
 | `canvas_ax_interaction` | Submit one capability-gated AX interaction envelope (`{ type, sourceNodeId, payload }`) that maps onto an AX operation; the server re-validates and clamps sandboxed surfaces to their own node |
-| `canvas_claim_ax_delivery` | Claim undelivered steering messages for an adapterless consumer (loop-safe — never returns steering the consumer originated) |
-| `canvas_mark_ax_delivery` | Mark a steering message delivered for a consumer |
-| `canvas_request_elicitation` | Request structured human input via a canvas-bound `elicitation` (pending) |
-| `canvas_respond_elicitation` | Respond to / resolve a pending elicitation |
-| `canvas_request_mode` | Request a workflow `mode-request` transition (plan/execute/autonomous) |
-| `canvas_resolve_mode` | Resolve a pending mode request |
 | `canvas_ingest_activity` | Ingest a harness-forwarded agent activity (tool/session event); the board auto-reacts with kind-driven, overridable defaults (failure → work item + review + evidence; `tool-result`+success → evidence). Makes AX bidirectional |
-| `canvas_await_approval` | Block until an approval gate resolves (human approves/rejects in the browser) or the timeout elapses (`timeoutMs` 0 = immediate read). Gates that actually gate |
-| `canvas_await_elicitation` | Block until an elicitation is answered or the timeout elapses |
-| `canvas_await_mode` | Block until a mode request resolves or the timeout elapses |
-| `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 |
-| `canvas_set_ax_policy` | Patch the canvas-bound tool/prompt policy (`tools.allowed\|excluded\|approvalRequired`, `prompt.systemAppend\|mode`); patches merge and are normalized |
-| `canvas_pin_nodes` | Pin nodes to include in agent context |
-| `canvas_clear` | Clear all nodes and edges |
-| `canvas_snapshot` | Save current canvas as a named snapshot |
-| `canvas_list_snapshots` | List saved snapshots, bounded to the newest 20 by default |
-| `canvas_gc_snapshots` | Delete old snapshots while keeping the newest N |
-| `canvas_restore` | Restore canvas from a saved snapshot |
-| `canvas_delete_snapshot` | Delete a saved snapshot |
-| `canvas_search` | Find nodes by title/content keywords |
-| `canvas_undo` | Undo the last canvas mutation |
-| `canvas_redo` | Redo the last undone mutation |
-| `canvas_diff` | Compare current canvas vs a saved snapshot |
-| `canvas_create_group` | Create a group containing specified nodes |
-| `canvas_group_nodes` | Add nodes to an existing group |
-| `canvas_ungroup` | Release all children from a group |
-| `canvas_batch` | Run a batch of canvas operations with `$ref` support |
-| `canvas_webview_status` | Get Bun.WebView automation status for the workbench |
-| `canvas_webview_start` | Start or replace the Bun.WebView automation session |
-| `canvas_webview_stop` | Stop the active Bun.WebView automation session |
-| `canvas_evaluate` | Evaluate JavaScript in the active workbench automation session |
-| `canvas_resize` | Resize the active workbench automation viewport |
 | `canvas_screenshot` | Capture a screenshot from the active workbench automation session |
+| `canvas_snapshot` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Save current canvas as a named snapshot |
+| `canvas_list_snapshots` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). List saved snapshots, bounded to the newest 20 by default |
+| `canvas_restore` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Restore canvas from a saved snapshot |
+| `canvas_delete_snapshot` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Delete a saved snapshot |
+| `canvas_gc_snapshots` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Delete old snapshots while keeping the newest N |
+| `canvas_diff` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Compare current canvas vs a saved snapshot |
+
+`canvas_node { action: "add", type: "html" }` accepts optional `summary`, `agentSummary`,
+`embeddedNodeIds`, and `embeddedUrls`. PMX also derives a bounded text summary from visible
+HTML, so rich HTML nodes stay searchable and readable in pinned/spatial context.
+
+## Migration reference
+
+The 57 legacy single-purpose tools below were removed in v0.3.0. Each row is
+the composite call that replaces it — kept as a lookup table for anyone
+migrating an older integration.
+
+| Removed tool | Composite replacement |
+|------|-------------|
+| `canvas_add_node` | `canvas_node { action: "add" }` |
+| `canvas_get_node` | `canvas_node { action: "get" }` |
+| `canvas_update_node` | `canvas_node { action: "update" }` |
+| `canvas_remove_node` | `canvas_node { action: "remove" }` |
+| `canvas_add_html_node` | `canvas_node { action: "add", type: "html" }` |
+| `canvas_add_html_primitive` | `canvas_node { action: "add", type: "html", primitive: "<kind>" }` |
+| `canvas_refresh_webpage_node` | `canvas_node { action: "update", refresh: true }` |
+| `canvas_describe_schema` | `canvas_render { action: "describe-schema" }` |
+| `canvas_validate_spec` | `canvas_render { action: "validate" }` |
+| `canvas_add_json_render_node` | `canvas_render { action: "add-json-render" }` |
+| `canvas_stream_json_render_node` | `canvas_render { action: "stream-json-render" }` |
+| `canvas_add_graph_node` | `canvas_render { action: "add-graph" }` |
+| `canvas_add_edge` | `canvas_edge { action: "add" }` |
+| `canvas_remove_edge` | `canvas_edge { action: "remove" }` |
+| `canvas_create_group` | `canvas_group { action: "create" }` |
+| `canvas_group_nodes` | `canvas_group { action: "add" }` |
+| `canvas_ungroup` | `canvas_group { action: "ungroup" }` |
+| `canvas_undo` | `canvas_history { action: "undo" }` |
+| `canvas_redo` | `canvas_history { action: "redo" }` |
+| `canvas_arrange` | `canvas_view { action: "arrange" }` |
+| `canvas_focus_node` | `canvas_view { action: "focus" }` |
+| `canvas_fit_view` | `canvas_view { action: "fit" }` |
+| `canvas_clear` | `canvas_view { action: "clear" }` |
+| `canvas_remove_annotation` | `canvas_view { action: "remove-annotation" }` |
+| `canvas_search` | `canvas_query { action: "search" }` |
+| `canvas_get_layout` | `canvas_query { action: "layout" }` |
+| `canvas_validate` | `canvas_query { action: "validate" }` |
+| `canvas_open_mcp_app` | `canvas_app { action: "open-mcp-app" }` |
+| `canvas_add_diagram` | `canvas_app { action: "diagram" }` |
+| `canvas_build_web_artifact` | `canvas_app { action: "build-artifact" }` |
+| `canvas_webview_status` | `canvas_webview { action: "status" }` |
+| `canvas_webview_start` | `canvas_webview { action: "start" }` |
+| `canvas_webview_stop` | `canvas_webview { action: "stop" }` |
+| `canvas_resize` | `canvas_webview { action: "resize" }` |
+| `canvas_evaluate` | `canvas_webview { action: "evaluate" }` |
+| `canvas_get_ax` | `canvas_ax_state { action: "get" }` |
+| `canvas_set_ax_focus` | `canvas_ax_state { action: "set-focus" }` |
+| `canvas_set_ax_policy` | `canvas_ax_state { action: "set-policy" }` |
+| `canvas_report_host_capability` | `canvas_ax_state { action: "report-capability" }` |
+| `canvas_add_work_item` | `canvas_ax_work { action: "add" }` |
+| `canvas_update_work_item` | `canvas_ax_work { action: "update" }` |
+| `canvas_add_review_annotation` | `canvas_ax_work { action: "annotate" }` |
+| `canvas_request_approval` | `canvas_ax_gate { kind: "approval", action: "request" }` |
+| `canvas_resolve_approval` | `canvas_ax_gate { kind: "approval", action: "resolve" }` |
+| `canvas_await_approval` | `canvas_ax_gate { kind: "approval", action: "await" }` |
+| `canvas_request_elicitation` | `canvas_ax_gate { kind: "elicitation", action: "request" }` |
+| `canvas_respond_elicitation` | `canvas_ax_gate { kind: "elicitation", action: "resolve" }` |
+| `canvas_await_elicitation` | `canvas_ax_gate { kind: "elicitation", action: "await" }` |
+| `canvas_request_mode` | `canvas_ax_gate { kind: "mode", action: "request" }` |
+| `canvas_resolve_mode` | `canvas_ax_gate { kind: "mode", action: "resolve" }` |
+| `canvas_await_mode` | `canvas_ax_gate { kind: "mode", action: "await" }` |
+| `canvas_get_ax_timeline` | `canvas_ax_timeline { action: "read" }` |
+| `canvas_record_ax_event` | `canvas_ax_timeline { action: "record-event" }` |
+| `canvas_add_evidence` | `canvas_ax_timeline { action: "add-evidence" }` |
+| `canvas_send_steering` | `canvas_ax_timeline { action: "send-steering" }` |
+| `canvas_claim_ax_delivery` | `canvas_ax_delivery { action: "claim" }` |
+| `canvas_mark_ax_delivery` | `canvas_ax_delivery { action: "mark" }` |
 
 ## Resources
 
@@ -255,27 +276,27 @@ raw stroke geometry or visual shape.
 
 Annotations are a browser-visible markup layer. Use the pen toolbar button to
 draw and the eraser toolbar button to remove an annotation again; agents can also
-remove a known annotation ID with `canvas_remove_annotation`.
+remove a known annotation ID with `canvas_view { action: "remove-annotation", id }`.
 
 Use WebView automation when an agent needs to actually see annotations as drawn.
-For example, inspect `.annotation-layer path` with `canvas_evaluate` or capture a
-`canvas_screenshot` to distinguish an arrow from a line, circle, or highlight.
+For example, inspect `.annotation-layer path` with `canvas_webview { action: "evaluate" }`
+or capture a `canvas_screenshot` to distinguish an arrow from a line, circle, or highlight.
 
 ## Node-type routing
 
-MCP node creation uses dedicated tools for structured node families. Read
-`mcp.nodeTypeRouting` from `canvas_describe_schema` / `canvas://schema` when
-in doubt:
-
-- `json-render` → `canvas_add_json_render_node`
-- `graph` → `canvas_add_graph_node`
-- `html-primitive` → `canvas_node { action: "add", type: "html", primitive: "<kind>" }` (or the deprecated `canvas_add_html_primitive`)
-- `html` → `canvas_node { action: "add", type: "html" }` (or the deprecated `canvas_add_html_node`)
-- `web-artifact` → `canvas_build_web_artifact`
-- `mcp-app` → `canvas_open_mcp_app`
-- `group` → `canvas_create_group`
+MCP node creation uses dedicated composite actions for structured node
+families. Read `mcp.nodeTypeRouting` from `canvas_render { action:
+"describe-schema" }` / `canvas://schema` when in doubt:
+
+- `json-render` → `canvas_render { action: "add-json-render" }`
+- `graph` → `canvas_render { action: "add-graph" }`
+- `html-primitive` → `canvas_node { action: "add", type: "html", primitive: "<kind>" }`
+- `html` → `canvas_node { action: "add", type: "html" }`
+- `web-artifact` → `canvas_app { action: "build-artifact" }`
+- `mcp-app` → `canvas_app { action: "open-mcp-app" }`
+- `group` → `canvas_group { action: "create" }`
 - Basic nodes (`markdown`, `status`, `file`, `image`, `webpage`) →
-  `canvas_add_node`
+  `canvas_node { action: "add" }`
 
 ## CLI/MCP alignment
 

package/docs/node-types.md

@@ -45,7 +45,7 @@ When an agent edits a file through its normal tools, the canvas node updates
 automatically via `fs.watch()`.
 
 ```ts
-canvas_add_node({ type: 'file', content: 'src/server/index.ts' })
+canvas_node({ action: 'add', type: 'file', content: 'src/server/index.ts' })
 ```
 
 ## Image nodes
@@ -55,7 +55,8 @@ HTTP(S)-backed images preserve provenance so agents can tell where evidence
 came from. Nodes can carry validation status or warnings.
 
 ```ts
-canvas_add_node({
+canvas_node({
+  action: 'add',
   type: 'image',
   content: 'artifacts/dashboard.png',
   data: {
@@ -73,8 +74,8 @@ keep enough information for an agent to refresh the node from the original
 URL later.
 
 ```ts
-canvas_add_node({ type: 'webpage', url: 'https://example.com/docs' })
-canvas_refresh_webpage_node({ id: 'node-abc123' })
+canvas_node({ action: 'add', type: 'webpage', url: 'https://example.com/docs' })
+canvas_node({ action: 'update', id: 'node-abc123', refresh: true })
 ```
 
 ## MCP App nodes
@@ -82,11 +83,12 @@ canvas_refresh_webpage_node({ id: 'node-abc123' })
 `mcp-app` nodes embed other MCP servers' UI resources (`ui://...`) directly
 on the canvas as sandboxed iframes. Any server implementing the
 [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps)
-can be opened with `canvas_open_mcp_app`.
+can be opened with `canvas_app { action: "open-mcp-app" }`.
 
 Generic `pmx-canvas node add --type mcp-app` is intentionally rejected —
-these nodes need tool/session metadata. Use `canvas_open_mcp_app` (or the
-`canvas_add_diagram` Excalidraw preset) instead.
+these nodes need tool/session metadata. Use `canvas_app { action:
+"open-mcp-app" }` (or the `canvas_app { action: "diagram" }` Excalidraw
+preset) instead.
 
 ### Excalidraw preset (hand-drawn diagrams)
 
@@ -95,7 +97,8 @@ server at `https://mcp.excalidraw.com/mcp`. PMX Canvas exposes a one-call
 preset:
 
 ```ts
-canvas_add_diagram({
+canvas_app({
+  action: 'diagram',
   elements: [
     { type: 'rectangle', id: 'a', x: 80, y: 120, width: 180, height: 80,
       roundness: { type: 3 }, backgroundColor: '#a5d8ff', fillStyle: 'solid',
@@ -111,8 +114,8 @@ canvas_add_diagram({
 });
 ```
 
-For any other MCP App, call `canvas_open_mcp_app` directly with the server's
-transport, tool name, and arguments.
+For any other MCP App, call `canvas_app { action: "open-mcp-app" }` directly
+with the server's transport, tool name, and arguments.
 
 ## json-render nodes
 
@@ -122,7 +125,8 @@ transport, tool name, and arguments.
 and component catalog (core + react + shadcn).
 
 ```ts
-canvas_add_json_render_node({
+canvas_render({
+  action: 'add-json-render',
   title: 'Deploy status',
   spec: {
     root: 'card',
@@ -144,7 +148,8 @@ host-provided handlers. PMX wires AX handlers named after interaction types, so
 spec action named `ax.*` becomes a capability-gated AX interaction:
 
 ```ts
-canvas_add_json_render_node({
+canvas_render({
+  action: 'add-json-render',
   title: 'Approve plan',
   spec: {
     root: 'btn',
@@ -164,8 +169,8 @@ source + per-viewer nonce + node id) and submits it server-side; `json-render` /
 `graph` viewers are sandboxed surfaces, so caller-supplied `nodeIds` are clamped
 to the node's own id. See the [MCP reference](mcp.md#node-interactions-capability-gated).
 
-Use `canvas_describe_schema` / `canvas_validate_spec` to introspect the
-component catalog before building a spec.
+Use `canvas_render { action: "describe-schema" }` / `canvas_render { action:
+"validate" }` to introspect the component catalog before building a spec.
 
 ## HTML nodes
 
@@ -182,7 +187,9 @@ match the active theme. Theme updates are posted into sandboxed HTML iframes,
 so theme-aware HTML can follow dark/light switches without reopening the node.
 
 ```ts
-canvas_add_html_node({
+canvas_node({
+  action: 'add',
+  type: 'html',
   title: 'Cost projection',
   html: '<canvas id="c"></canvas><script src="https://cdn.jsdelivr.net/npm/chart.js"></script><script>...</script>',
 })
@@ -213,8 +220,10 @@ presentation, explainer, status report, incident report, triage board, config
 editor, or prompt tuner.
 
 ```ts
-canvas_add_html_primitive({
-  kind: 'choice-grid',
+canvas_node({
+  action: 'add',
+  type: 'html',
+  primitive: 'choice-grid',
   title: 'Implementation options',
   data: {
     items: [
@@ -246,9 +255,9 @@ A **web artifact** is a single-file, fully bundled HTML app (React + Tailwind
 real interactive app — charts, forms, mini-dashboards — beyond what a static
 node or `html` snippet can express.
 
-`canvas_build_web_artifact` takes source strings (`App.tsx`, optional
-`index.css`, `main.tsx`, `index.html`, plus extra files), runs the bundled
-web-artifacts-builder scripts, writes the self-contained HTML to
+`canvas_app { action: "build-artifact" }` takes source strings (`App.tsx`,
+optional `index.css`, `main.tsx`, `index.html`, plus extra files), runs the
+bundled web-artifacts-builder scripts, writes the self-contained HTML to
 `.pmx-canvas/artifacts/<slug>.html`, and (by default) opens it in the canvas.
 
 ```bash
@@ -277,7 +286,7 @@ as dashed-border frames with a title bar and optional accent color.
   lay children out inside it
 
 ```ts
-canvas_create_group({ title: 'Auth Module', childIds: ['node-1', 'node-2'], color: '#4a9eff' })
+canvas_group({ action: 'create', title: 'Auth Module', childIds: ['node-1', 'node-2'], color: '#4a9eff' })
 ```
 
 ## Edge types
@@ -296,25 +305,26 @@ All edges support labels, styles (solid/dashed/dotted), and animation.
 Agents don't have to guess node shapes. The running server exposes its create
 schemas, json-render component catalog, and node-type examples:
 
-- `canvas_describe_schema` / `GET /api/canvas/schema` — list all node-create
-  schemas, required fields, json-render components, HTML primitives, and sample payloads
-- `canvas_validate_spec` / `POST /api/canvas/schema/validate` — validate a
+- `canvas_render { action: "describe-schema" }` / `GET /api/canvas/schema` — list all
+  node-create schemas, required fields, json-render components, HTML primitives, and sample payloads
+- `canvas_render { action: "validate" }` / `POST /api/canvas/schema/validate` — validate a
   json-render spec, graph payload, or HTML primitive payload **without** creating a node
-- `canvas_validate` / `GET /api/canvas/validate` — validate the current
+- `canvas_query { action: "validate" }` / `GET /api/canvas/validate` — validate the current
   layout for collisions, containment, and missing edge endpoints
 - `canvas://schema` — the same data as an MCP resource
 
 The CLI's `node schema` / `validate spec` subcommands surface the same data
 from the terminal.
 
-MCP node creation uses dedicated tools for structured node families. Read
-`mcp.nodeTypeRouting` from `canvas_describe_schema` when in doubt:
-`json-render` → `canvas_add_json_render_node`,
-`graph` → `canvas_add_graph_node`,
-`html-primitive` → `canvas_add_html_primitive`,
-`html` → `canvas_add_html_node`,
-`web-artifact` → `canvas_build_web_artifact`,
-`mcp-app` → `canvas_open_mcp_app`,
-`group` → `canvas_create_group`.
+MCP node creation uses dedicated composite actions for structured node
+families. Read `mcp.nodeTypeRouting` from `canvas_render { action:
+"describe-schema" }` when in doubt:
+`json-render` → `canvas_render { action: "add-json-render" }`,
+`graph` → `canvas_render { action: "add-graph" }`,
+`html-primitive` → `canvas_node { action: "add", type: "html", primitive: "<kind>" }`,
+`html` → `canvas_node { action: "add", type: "html" }`,
+`web-artifact` → `canvas_app { action: "build-artifact" }`,
+`mcp-app` → `canvas_app { action: "open-mcp-app" }`,
+`group` → `canvas_group { action: "create" }`.
 Basic nodes (`markdown`, `status`, `file`, `image`, `webpage`) use
-`canvas_add_node`.
+`canvas_node { action: "add" }`.

package/docs/plans/plan-006-mcp-tool-consolidation.md

@@ -1,6 +1,8 @@
 # Plan 006: MCP tool consolidation (69 tools to 21)
 
-**Status:** In progress — wave 1 landed (7 canvas composites) and the AX wave landed (5 composites: `canvas_ax_state`, `canvas_ax_work`, `canvas_ax_gate`, `canvas_ax_timeline`, `canvas_ax_delivery`). Remaining: `canvas_snapshot` (name held by the legacy save tool until v0.3), `canvas_app`/`canvas_webview` (need plan-005 item 8), and the deferred actions `refresh` / `add-primitive` / `remove-annotation` / board validation.
+**Status: completed in v0.3.0 (canvas_snapshot composite moved to v0.4).**
+
+**Status (historical):** In progress — wave 1 landed (7 canvas composites) and the AX wave landed (5 composites: `canvas_ax_state`, `canvas_ax_work`, `canvas_ax_gate`, `canvas_ax_timeline`, `canvas_ax_delivery`). Remaining (closed by plan-008 + the v0.3.0 removal): `canvas_snapshot` (name held by the legacy save tool until v0.4), `canvas_app`/`canvas_webview` (landed via plan-005 item 8), and the deferred actions `refresh` / `add-primitive` / `remove-annotation` / board validation (landed via plan-008 waves 1 and 5).
 **Date:** 2026-06-12
 **Depends on:** plan-005 (operation registry). Slices 1-4 are migrated; consolidation lands per-domain as the corresponding registry slices complete.
 **Motivation:** docs/tech-debt-assessment-2026-06.md item 2. Governed by docs/api-stability.md (deprecation: marked in one minor, removed in the next).

package/docs/plans/plan-008-registry-finish.md

@@ -1,5 +1,7 @@
 # Plan 008 — Finish the operation-registry refactor (plan-005 items 8–9 + plan-006 completion)
 
+**Status: completed in v0.3.0 (canvas_snapshot composite moved to v0.4).**
+
 **Status:** Complete
 **Date:** 2026-06-15
 **Depends on:** plan-005 (registry — slices 1–7 merged), plan-006 (consolidation — waves 1–2 merged), plan-007 (AX domain — merged).

package/docs/plans/plan-009-tech-debt-backlog.md

@@ -0,0 +1,51 @@
+# Plan 009 — Tech debt backlog (open findings from the July 2026 assessment)
+
+**Status:** Open
+**Date:** 2026-07-06
+**Motivation:** [`docs/tech-debt-assessment-2026-07.md`](../tech-debt-assessment-2026-07.md) (revised 2026-07-06). The v0.3.0 tree plus the same-day fix pass closed H1, H2, M12, and the small residuals of C2/C3/M4/M7/M9/L7. This plan records everything still open so it survives the release. Finding IDs below refer to the assessment, which carries the full `file:line` evidence.
+
+Each item is tagged by shape: **project** (multi-day, own plan/PR), **decision** (needs a maintainer call before code), or **small** (safe standalone change).
+
+## Phase 1 — finish what was started
+
+| Item | Source | What's open | Shape |
+|---|---|---|---|
+| Complete the registry migration | C1 | Fold the remaining hand-written routes in `server.ts` into operations; collapse the 76-method `PmxCanvas` onto `executeOperation`; migrate the CLI's 60 raw `fetch` calls onto the operation invoker. **Slice 1 done post-0.3.0:** the 7 `/api/ext-app/*` routes moved to `ops/ext-app.ts` (~290 lines out of `server.ts`, the 5 clone handlers — old M5 — collapsed to one parametrized definition; wire envelopes byte-identical, no new MCP tools). **Slice 2 done:** the 15 ax wire routes (8 GET lists + `ax/context` + `ax/surface-snapshot` + `pinned-context` + `code-graph` + `ax/activity` + `ax/interaction` + legacy `PATCH /api/canvas/ax`) moved to `ops/ax-read.ts` (~370 more lines out of `server.ts`); `open-external` stays hand-written (coupled to the live server port + system browser opener). **Slice 3 done:** theme GET/POST, canvas update, viewport, annotation POST, and node `:id/refresh` moved to the registry (`ops/canvas-wire.ts`, plus additions to `ops/viewport.ts`, `ops/annotation.ts`, `ops/nodes.ts`); the two dispatch gates unified into one `/api/` gate; `server.ts` is at ~2,980 lines (from 3,873 at the audit). **Remaining routes (~20)** are the deliberate poor fits (SSE, binary, HTML/static, file bodies) plus four server-coupled handlers: `prompt` + workbench `state`/`open`/`intent` (module-local `primaryWorkbench*` session state), `render` (Excalidraw URL-normalizer chain), `open-external` (live port + system browser). Those need state injection like the webview runner — a deliberate follow-up, not mechanical. After routes, the bigger halves remain: `PmxCanvas` (76 methods) onto `executeOperation`, and the CLI's raw fetches onto the invoker. | project (in progress) |
+| One HTTP envelope | M4 residual | Registry ops return bare bodies, legacy ext-app handlers `{ok:true,result}`, 404s plaintext. Unify (naturally falls out of C1). Also: surface persistence save failures via a `/health` degraded flag — `canvas-state.ts` has 63 catch→warn→continue sites. | project (with C1) |
+| `dist/` commit policy | C3 residual | **Decided + done post-0.3.0:** `dist/` stays committed; `test.yml` now has a `dist/types` staleness gate (rebuild + fail on drift). The `dist/canvas`/`dist/json-render` bundles are deliberately not byte-checked — bundler output varies across bun versions; their staleness story folds into M1. | done |
+| Skill-mirror validator | C2 residual | `validate:agent-skills` exits 0 when the (local-only, gitignored) trees are absent. Docs are honest about this now; decide whether to repoint, gate, or delete the check. | decision |
+| Generate CLAUDE.md/AGENTS.md from one source | M9 residual | The twins are byte-identical again but still hand-maintained; generate or symlink to prevent the next drift. | small |
+
+## Phase 2 — make the safety net real
+
+| Item | Source | What's open | Shape |
+|---|---|---|---|
+| Lint/format tooling | H6 | **Done post-0.3.0:** Biome 2.5 adopted — `bun run lint` / `lint:fix`, wired into `release:check` (making RELEASE.md's "lints" claim true) and CI. First-run format sweep landed as its own mechanical commit; 7 lint errors hand-fixed (incl. a real conditional-hooks bug in `SelectionBar.tsx`). Deliberately disabled rules to revisit: a11y group, `useExhaustiveDependencies` (misfires on Preact signals), `noNonNullAssertion` (143 deliberate uses), `noArrayIndexKey` (13 sites). ~77 warnings (unused imports/vars, optional-chain) left as a burn-down list — warnings don't fail the gate. | done |
+| Client + server unit coverage | H7 | Zero component render tests (no DOM test lib in repo); untested big modules: `ax-state-manager.ts` (826 lines), `mcp-app-host.ts` (814), `canvas-schema.ts` (644), `shared/semantic-attention.ts` (600, in zero test files). Coverage is collected but gates nothing; tests aren't typechecked. Add `happy-dom` + `@testing-library/preact`, a tests tsconfig, and a coverage threshold. | project |
+| Daemon port/lock lifecycle | H4 | **Fixed post-0.3.0** (`src/cli/daemon.ts` + `tests/unit/cli-daemon.test.ts`). Note the original finding was partly wrong: the daemon child was already strict-port (`PmxCanvas.start` pins `allowPortFallback: false`), so fallback-blind polling could not occur. The real defects — fixed — were: the pre-check accepted any responsive `/health` as "already running" (even a foreign workspace's daemon), a TOCTOU double-spawn window, the pid recorded only after health passed (slow start → unkillable orphan), and no PID-recycling guard. The flaky `pmx-canvas-sdk.test.ts` port collision is NOT this — it's M8's copy-pasted `getAvailablePort()` racing. | done |
+| Test-suite structure | M8 | Integration monoliths under `tests/unit/` (`server-api` 5,213 lines, `cli-node` 2,903); `getAvailablePort()` copy-pasted in 5 files; `waitForPersistence(650ms)` fixed sleeps in 9 files + ~19 magic `Bun.sleep`s; Playwright lacks `retries`/`forbidOnly`; `test:e2e-cli` (517-line script) runs in no CI workflow. *Post-0.3.0:* `operation-parity` now binds port 0 and derives the port from the base URL (removes one reserve-then-rebind race); the shared-helper dedup and the rest remain. Also noted: `ax-parity.test.ts` is a string-matching source-analysis test whose needles broke when Biome re-wrapped `cmd(` calls — its CLI needles are now layout-independent, but any future needle should avoid depending on line layout. **Also noted (2026-07-07):** the `server-api` Excalidraw diagram tests do real network round-trips to the hosted `mcp.excalidraw.com` MCP server and intermittently time out (30s) under full parallel runs — they should be mocked or moved to a network-tagged tier. | project |
+| `noUncheckedIndexedAccess` | L7 residual | Enable in tsconfig; will surface many index-access errors — treat as its own sweep. | small (noisy) |
+
+## Phase 3 — client consolidation
+
+| Item | Source | What's open | Shape |
+|---|---|---|---|
+| One node factory | H5 | `sse-bridge.ts` (1,066 lines) keeps its own `DEFAULT_POSITIONS`/`makeNode` divergent from `canvas-store`; `responseToThreadMap` is not cleaned on SSE reconnect; server-side `syncEventToCanvasState` (~330 lines) mirrors it as an if/else chain with geometry defaults duplicated against `ensureDefaultDockedNodes`. Share one factory; treat `canvas-layout-update` as the single source of truth; table-drive the event sync. | project |
+| Shared AX iframe bridge | M2 | The ~33-line `onAxMessage` listener is copy-pasted in `HtmlNode.tsx`, `McpAppNode.tsx`, `ExtAppFrame.tsx`; `pmx-canvas-ax` protocol string spread across 9 sites. This is the sandboxed-surface trust boundary (prior near-miss: LRN-20260607-005). Extract `useAxSurfaceBridge` + a protocol-constants module. | project (security-adjacent) |
+| `ExtAppFrame.tsx` timing hacks | M3 | 915 lines, 12 refs, 7 `setTimeout`s, 5 rAFs, WebKit remount slot counter, 1200 ms fallback bootstrap, two near-duplicate `buildHostContext` blocks. Extract `useExtAppBridge`; single `buildHostContext`. | project |
+| json-render stack decision | M1 | Preact + React 19 + recharts all runtime deps; 7 exact-pinned `@json-render/*` incl. 3 devtools packages shipped; `dist/json-render/index.js` 1.37 MB and `dist/canvas/index.js` 599 KB both unminified; build script shells to python3 with a stale-bundle fallback. Minimum: minify, move devtools to devDependencies, lazy-load the viewer, replace the python mtime gate. Bigger call: separate optional package if the React stack stays. | decision + project |
+| Client dead code / duplication | L1, L2, L3 | `ContextPinHud.tsx` unreferenced; three pure re-export shims; two parallel markdown-format stacks; `global.css` 3,746 lines with 11 `!important` vs 227 inline styles and unscaled z-indexes. | small (batchable) |
+
+## Smaller items (no phase, pick up opportunistically)
+
+| Item | Source | What's open |
+|---|---|---|
+| Per-action composite schemas | M6 | Composite tools advertise every field optional; per-action required fields fail only at runtime. Decide: `oneOf` schemas vs per-action requirement docs. (Now the only schema surface agents see.) |
+| Packaging | M10 | `files` ships both `src/` and `dist/` (~double tarball, two import paths); `bin` points at raw `.ts` (undocumented Bun-only constraint); `@types/turndown` in runtime deps. |
+| Env var hygiene | M11 residual | `PMX_CANVAS_PORT` vs `PMX_WEB_CANVAS_PORT` applied inconsistently across entry points; `PMX_DATA` (15 uses) and the `PMX_CANVAS_JSON_RENDER_*` / `PMX_MCP_APP_HOST_*` families undocumented. |
+| `publish.yml` e2e gap | M11 residual | Publishing skips e2e with no verification that the tagged SHA passed `test.yml`. |
+| MCP notification fan-out | M7 residual | Five `canvas://` resource URIs notify on every mutation regardless of type (`mcp/server.ts:95-99`). |
+| Legacy migration code on every boot | L4 | JSON→SQLite migration runs unconditionally (`canvas-state.ts:758,785`); gate behind a one-shot marker and retire. |
+| Suppression/mutation plumbing | L5 | Two parallel suppression depth-counters; `onMutation` is a single-slot setter wired twice (last-write-wins). |
+| Module-global lifecycle leaks | L6 | ~20 module-level `let`s in `server.ts`; code-graph debounce timer survives `stopCanvasServer`; remote SSE watcher loop has no cancellation. |
+| June doc citations | L7 residual | `tech-debt-assessment-2026-06.md` cites gitignored `.learnings/` entries future maintainers can't read. |

package/docs/tech-debt-assessment-2026-06.md

@@ -1,6 +1,6 @@
 # Tech Debt Assessment & Direction Proposal — June 2026
 
-**Status:** Proposed
+**Status:** Superseded by [tech-debt-assessment-2026-07.md](tech-debt-assessment-2026-07.md)
 **Date:** 2026-06-10
 **Scope:** Full-repo audit at v0.1.36 (~70k lines TS; src/server 23.2k, src/client 13.9k, src/mcp 4.2k, src/cli 4.0k)