pmx-canvas 0.10.0 → 0.12.0

package/docs/http-api.md

@@ -3,6 +3,26 @@
 REST endpoints for all canvas operations + an SSE event stream. Works from
 any language. Default base URL: `http://localhost:4313`.
 
+## Board-targeted operations
+
+Registry-backed routes accept `targetBoardId` in the JSON body, or in query parameters
+for GET/DELETE. It must name an existing board. Board-bound reads, writes, batches and waits
+execute on that board without opening it, including across awaits and concurrent navigation.
+Omitting it retains the visible-board behavior. `agentId` identifies the writer for attribution
+and scope fences; it is not an authentication credential.
+
+Nested operations inherit the target and writer and reject conflicting overrides. Explicit
+`board`, `expectedBoardId` and `destinationBoardId` must agree with the target. Board metadata
+updates must name that board; a move-selection source must also agree. Deletion or
+workspace replacement invalidates pending work, never redirects it to another board.
+
+Board opening/deletion, backup restore and WebView automation refuse a target because they control the
+shared view/workspace. Catalog operations, board creation/pins, settings and knowledge categories
+retain their workspace scope and existing authority checks. AX timeline, evidence and steering
+are workspace-wide; `delivery/pending` uses the consumer's addressed inbox and the target board's
+`pendingActivity`. This is operation routing, not board-level access control. The SSE/poll stream
+still projects the human's visible board, not an individual caller's target.
+
 ## Operation cancellation and progress (0.10)
 
 Registry-backed operation routes use the request's abort signal. Disconnecting
@@ -173,6 +193,11 @@ are JSON `[boardId,cardId]`. If the snapshot exceeds a quarter of the budget, `c
 explicitly requires rechecking cached cards via lifecycle-get before reuse. Empty lists in an
 incomplete snapshot do not mean healthy or active. Delivered entries still carry qualification.
 
+`GET /health` includes `bundleStamp`, the `<mtimeMs>-<size>` of `dist/canvas/index.js` that
+tabs compare on (re)connect to decide whether to reload. It is read once per process: when it
+differs from the file on disk, new page loads get the rebuilt files but already-open tabs keep
+their old JavaScript until the server restarts.
+
 `GET /health` includes `contracts: ["pmx-embedded-workbench-v4"]` when the daemon
 enforces `expectedBoardId` and `expectedContentRevision` preconditions, bulk-write
 fences/locks using validated geometry and affected automatic parent frames only,
@@ -217,9 +242,15 @@ content auto-height or indirect parent-group reflow after editing a child.
   update and are included in snapshots/undo. They are board-wide writes under a scope fence.
 - `POST /api/canvas/tour/go` with `{ "stop": 2 }` or `{ "step": "next" | "previous" }`
   (plus optional `"present": false`) moves the shared tour cursor →
-  `{ ok, index, total, stop }`; 400 when the stop does not exist or the board has no stops.
+  `{ ok, index, total, stop, catalogEpoch, boardGeneration, sequence }`;
+  400 when the stop does not exist or the board has no stops.
   Broadcasts `canvas-tour-step`; idle workbenches start presenting unless `present` is false.
+  Response and event share the same monotonically increasing `sequence` within the
+  server's `catalogEpoch`. Viewers accept only newer steps for their current epoch
+  and board generation, so delayed echoes cannot rewind or replay the camera.
 - `POST /api/canvas/tour/exit` leaves presentation in every viewer (`canvas-tour-exit`).
+  Returns `{ ok, catalogEpoch, boardGeneration, sequence }`; the event shares that
+  identity and the step sequence, so an old exit cannot dismiss a newer presentation.
 - `POST /api/canvas/camera/move` with exactly one of `nodeId`, `rect: { x, y, width, height }`
   or `viewport: { x, y, scale }`, plus optional `duration`, `easing`, `padding`, `pullback`
   → `{ ok, stop, viewport }`. Broadcasts `canvas-camera-move`; browsers ease to the target in
@@ -229,6 +260,29 @@ content auto-height or indirect parent-group reflow after editing a child.
 Tour steps and camera moves are navigation: no undo entry, no agent-presence write, no
 scope-fence check.
 
+`tour/go` and `tour/exit` accept optional `presenter: { clientId, intent,
+catalogEpoch, boardGeneration }`. The workbench assigns each document a random ID
+and each gesture an increasing positive safe-integer intent. The server rejects
+an old activation or an intent no newer than that document's accepted watermark
+with `{ ok: true, superseded: true }`, without moving the cursor or emitting an event.
+A structurally valid newer command supersedes older ones even if its stop is missing.
+This lets Present proceed while an earlier Exit request is stalled, without that
+late Exit stopping the restart. Resume reads cannot outlive their originating intent.
+
+This is latest-intent-wins, not FIFO: reversed relative Next requests can coalesce.
+Different documents, including a reload, remain independent; unfenced agent calls
+and other documents still act in server arrival order. Reload is not cancellation
+of an old document's pending request. A board activation retains at most 4096
+document IDs, refusing new IDs with 409 rather than evicting an ordering record.
+Switching boards resets that limit; requests stamped with the old activation still
+cannot apply. The SDK exposes the same fence through `goToTourStop(step,
+{ presenter })` and `exitTour(presenter)`; fenced go may return `{ superseded: true }`.
+
+Presentation's Back/Next buttons share this cursor with keyboard and agent navigation.
+They sit beside Exit at the top; hover/focus tooltips show the shortcuts. Node and
+rectangle targets fit below those controls, while explicit viewport targets remain
+exact. Presentation does not change the saved board viewport.
+
 The [tour model and recording walkthrough](cli.md#tour-and-presentation) describes
 targets, duration, easing, padding, and pullback. Open `/workbench?present=1` to hide
 chrome; camera movement is local to that viewer. Recording writes local files via
@@ -271,6 +325,43 @@ open either board.
 Board-list `links` expose qualified `boardId`/`cardId` targets; native card
 connections include `cardTitle` (null if missing), so footers need not display raw IDs.
 
+### Move original cards to a new board
+
+`GET /api/canvas/boards/:id` returns `contentRevision` alongside `board` and `open`.
+Use that revision for `POST /api/canvas/boards/move-selection`:
+
+```json
+{"sourceBoardId":"board-source","nodeIds":["card-a","group-b"],"name":"Follow-up","expectedRevision":42,"requestId":"unique-move-request","preview":true}
+```
+
+Preview is read-only and returns `{ok:true, preview}` with expanded `nodeIds`,
+`affectedBoardIds`, `readmeNodeId`, `pinnedNodeIds`, `liveTaskNodeIds`, `attachmentIds`,
+`blockers` and `notices`. Commit with the identical input and `preview:false` (or omitted).
+The source must still be open and at that revision. Commit rechecks permissions and bindings,
+then atomically returns `{ok:true, sourceBoardId, destinationBoardId, portalId, nodeIds,
+affectedBoardIds, replayed}`. It never opens the destination. The SDK exposes the same input
+through `moveSelectionToNewBoard(input)`.
+
+Keep the request ID and exact input until success is known. Retrying after an interrupted reply
+or restart returns the original result without another board or portal, even if the source is
+no longer open. Reusing that ID with different input returns 409. A stale revision or unsafe
+binding also returns 409; binding refusals include `blockers`. Resolve the cause and preview
+again before a new attempt.
+
+This moves identities, not copies. Groups include descendants; card/edge IDs, relative geometry,
+content revisions, pins, review/read evidence and supported attachments survive. Incoming and
+outgoing relations, wiki bindings and provenance retarget across the library. The destination
+inherits the source folder, theme and relation vocabulary. A selected README moves its designation.
+Live task cards keep their original `workItemBoardId` and `workItemId`; task authority stays put.
+Board-space annotations stay on the source, which receives a portal at the moved selection.
+
+The entire move is refused for unsafe runtime producers, external app sessions, task/flow action
+bindings, partial or unfinished imports, source tours targeting moved cards, unresolved local
+viewer references, edit locks or scope fences on affected boards. Nothing is silently dropped.
+Pre-move Undo/Redo is cleared on affected boards. Older snapshots remain readable but neither
+whole-board nor single-card restore may cross the move boundary. Use a post-move snapshot for
+restore; consult older snapshots to recover text manually without recreating the old identities.
+
 ### Markdown previews and saved links
 
 `POST /api/render` accepts `{markdown, nodeId?, expectedBoardId?}` and returns `{html}`.
@@ -388,6 +479,14 @@ stored once per file. Live MCP apps become placeholders; local file contents
 are left out unless `includeFiles` is true. Files are written to `exports/`
 beside the database. Built-app files are only embedded when they are regular,
 bounded-size files inside the board's owned `.pmx-canvas/artifacts/` directory.
+Exports retain saved card positions and sizes, heading display, and the board's
+named theme. Charts and dashboards use embedded card layout without repeating
+the shell title; explicit chart heights remain unchanged. Viewer bundles, palette
+CSS and shell fonts are embedded. Read-only exports omit live work controls.
+When running from source, run `bun run build` before exporting. Export requires
+the complete built viewer assets, `surface-theme.css`, and the font files referenced
+by `global.css`; the installed package includes them. A missing asset tree is not
+a supported text-only export mode.
 The preview manifest lists card links, remote images, and statically visible
 network destinations in embedded HTML. Imported source-linked Markdown is also
 excluded unless `includeDerivedText=true`, independently of `includeFiles`;
@@ -462,6 +561,13 @@ opening that board or changing where writes go. This is supported by
 return 404. Omit `board` to read the active board. Live AX session/delivery reads
 and fixed MCP resources continue to describe the open board.
 
+The workbench's `POST /api/canvas/update` accepts `{updates: [{id, position?, size?,
+collapsed?, zIndex?}], expectedBoardId?, recordHistory?}`. `zIndex` is finite and
+persists stacking without changing geometry. The workbench raises a group and its
+children together, keeping the frame below its children. Title-bar gestures save
+stacking and geometry together on release. Layout notifications and reloads retain
+that order.
+
 ```bash
 # Get canvas state
 curl http://localhost:4313/api/canvas/state
@@ -514,7 +620,8 @@ term-OR discovery and whole-term ranking remain unchanged. Search never navigate
 `POST /api/canvas/node` accepts `destinationBoardId` to create on a stored board
 without opening it or changing the human's active board. `expectedBoardId` remains
 an **active-board** precondition, not a destination selector; stale values return 409.
-Unknown destinations return 404. This is creation-only, not background CRUD.
+Unknown destinations return 404. `destinationBoardId` is creation-only. Use
+`targetBoardId` for board-scoped reads and mutations without shared navigation.
 
 Optional `requestId` identifies a logical creation within the workspace database.
 Use the same id, destination and creation input when retrying; a new intentional
@@ -547,8 +654,24 @@ descendants and affected parent frames. Edges resolve `from`/`fromSearch` and
 target board, not the owner of the edge. Both endpoints' relation clocks update
 without changing their content/freshness. A retry returns its original group or
 edge receipt, preserving later edits and not resurrecting removals. A request ID
-cannot be reused for a different creation operation. Inactive group membership
-updates/removals and other background CRUD remain unsupported.
+cannot be reused for a different creation operation. `destinationBoardId` selects
+the destination for creation only. Use `targetBoardId` for background updates,
+removals and group membership changes (see [board-targeted operations](#board-targeted-operations)).
+
+For authored work cards, create `type: "status"` with
+`data: { workState: "todo", detail: "Plan the change", progress: 25 }`.
+`workState` accepts `todo`, `in-progress`, `blocked`, `done`, `cancelled`;
+`detail` must be a string and progress must be 0–100 or `null` to clear it.
+PATCH merges supplied data fields and validates the resulting work card. Use
+`expectedBoardId` and `expectedContentRevision` to refuse stale edits. These cards
+do not create session work or approvals. See [work cards](node-types.md#work-cards).
+
+For a read-only live task presentation, POST `{"type":"status","data":{"workItemId":"<task-id>"}}`
+on the task's active board. Unknown tasks, background creation, supplied display fields,
+reference changes and display-field PATCHes return 400. Title, detail, work state and attribution
+are derived from the existing task; progress is absent. Geometry and pins remain writable.
+Use the existing AX work update endpoint to change the task. Deleting a presentation never
+cancels work. See [live task cards](node-types.md#read-only-live-task-cards).
 
 ```bash
 # Add a node
@@ -590,9 +713,10 @@ against the node's top-level `contentRevision`; stale content returns `409`
 without changing the node. Conditional edits cannot request webpage refresh.
 The private MCP App uses these guards to reject stale board actions and note drafts.
 
-Native Markdown Save captures the currently observed revision for each attempt. Newer content
-arriving during rendering or network delivery refuses that attempt and keeps the draft; a later
-deliberate human Save may replace already-observed work. Queued saves advance their precondition
+Markdown Save uses the draft's original content revision in both standalone and hosted workbenches.
+Newer content refuses the save and keeps the draft, even if the peer update arrived before Save
+was clicked. Retrying a stale draft still refuses; copy it before reloading to reconcile with the
+latest saved text. Queued saves advance their precondition
 only through successful acknowledgements of their own preceding saves, never through an external
 revision or an automatic retry after conflict. Acknowledgements from before a restart, restore,
 or board replacement cannot update canonical content, clear an unsaved draft or advance queued
@@ -613,6 +737,10 @@ hosted MCP App still refuses file-linked edits. This is not a crash-recovery dis
 Replacing a JSON-render node's `spec` preserves its current title; include `title`
 to rename it explicitly. A new authored spec still resets the viewer's local drafts.
 
+Markdown nodes accept `data: { "display": "heading" | "card" }` on creation and
+update. Heading display removes the card frame and uses its title as a section
+label; it does not alter content, position, or pin membership.
+
 Mermaid nodes accept `data: { "fit": "contain" | "none" }` on both
 `POST /api/canvas/node` and `PATCH /api/canvas/node/:id`. The default, `contain`,
 shrinks overflowing diagrams without changing aspect ratio; `none` keeps 100%
@@ -709,8 +837,23 @@ curl -X POST http://localhost:4313/api/canvas/annotation \
 curl -X DELETE http://localhost:4313/api/canvas/annotation/ann-123
 ```
 
-Agent-readable context reports annotation IDs, targets, and bounds. Use WebView
-inspection or screenshots when the drawn shape matters.
+Both agents and humans use this layer. Set `type: "text"`, `text` and a point to
+write a note; omit `type` for freehand ink with at least two points. Coordinates
+are canvas world coordinates, independent of pan and zoom. `width` is stroke
+width for ink (default 4, clamped to 1–24), or font size for text (default 24,
+clamped to 1–96). Text is trimmed to 240 characters and labels to 160.
+
+An explicit `id` makes creation retryable while that mark exists: the same
+normalized content returns the existing mark without another Undo entry;
+different content returns 409. After removal or Undo, adding that ID creates
+the mark again. This is not a durable creation receipt. Removal erases the whole
+mark, never the underlying cards; missing IDs return 404. Agent writes obey the
+existing scope fence, including annotation points and removal bounds.
+
+Agent-readable context reports annotation IDs, labels, text-note content,
+targets and bounds without raw stroke points. Use screenshots when the drawn
+shape matters. Questions can be answered in the external agent host's composer;
+no PMX session or canvas reply is required, and marks are not approval gates.
 
 ## Viewport
 
@@ -782,8 +925,17 @@ a merged receipt has recorded more than 20 IDs across sessions; unrelated pins s
 
 `consumer` is optional. Supply a stable unique value only for a durable,
 board-scoped cursor; without `consumer` or `since`, each request starts from the
-beginning. An explicit `since` never advances a cursor. The brief is a map,
-not a dump: an `overview` entry for the open board first, then pins, then each
+beginning. An explicit `since` never advances a cursor. `contextDelivery=false`
+prepares the brief without recording a read or advancing the
+consumer cursor. Adapters must record reception separately; preparation is not
+delivery. `includeSteering=false` excludes steering when the host delivers addressed
+instructions separately. Both flags default to true.
+
+Before capturing context, live task cards reconcile their displayed content and
+content revisions with their task owner, including after restart or another writer's
+task update. This does not attribute an edit to the reader or reset consumer cursors.
+
+The brief is a map, not a dump: an `overview` entry for the open board first, then pins, then each
 pin's neighbours (reason `near`: up to five unpinned cards within a 600 canvas-pixel
 edge-to-edge gap, nearest first, with `near: { pinNodeId, pinTitle }`), then relevant
 current-board changes and asks, then pinned boards (reason `pinned-board`: the board and its pinned
@@ -896,6 +1048,11 @@ curl "http://localhost:4313/api/canvas/ax/context-status?board=<board-id>"
 # For a captured graph/brief, also pass seenLinkRevisions: {"node-1": 12} from
 # the delivered linksRevision values, not revisions fetched after delivery.
 # Only seenNodeIds with captured entries are acknowledged when this map is supplied.
+# Optional deliveryId deduplicates receipt retries by source, consumer and board
+# while the original read is retained (the read log retains 5000 rows).
+# Repeating it returns the original read, never revisions fetched at retry time.
+# Receipt identities outlive diagnostic pruning. An expired retry returns HTTP 409
+# with code=context_receipt_expired; obtain fresh context instead of retrying that ID.
 curl -X POST http://localhost:4313/api/canvas/ax/context-reads \
   -H "Content-Type: application/json" \
   -d '{"channel":"adapter","resource":"copilot:prompt-context","consumer":"copilot","pinnedNodeIds":["node-1"],"deliveredNodeIds":["node-1"],"bytes":2048}'
@@ -1152,6 +1309,10 @@ curl -X POST http://localhost:4313/api/canvas/ax/interaction \
 # browser composer offers a target picker fed by live presence — always claim
 # with your own label or addressed steering never reaches you.
 curl "http://localhost:4313/api/canvas/ax/delivery/pending?consumer=copilot&limit=20"
+# addressedOnly=true requires consumer and excludes broadcasts BEFORE the limit.
+# offset skips matching pending messages; restart at zero after an empty page.
+# Used by hosts that can wake one explicitly addressed thread.
+curl "http://localhost:4313/api/canvas/ax/delivery/pending?consumer=amp:T-example&addressedOnly=true"
 
 # Long-poll: `waitMs` parks the request until steering for this consumer
 # arrives or the timeout elapses (capped at 120000ms) — the reactive loop for
@@ -1294,6 +1455,8 @@ all consume this stream. Auto-reconnect with exponential backoff.
 
 The direct workbench's `connected` snapshot renews its per-process
 `workbenchToken` (also embedded in boot HTML) over both SSE and polling.
+It is followed by `boards-changed` before the layout, so later tour commands
+already have a board identity even when the separate catalog HTTP read is delayed.
 A same-bundle daemon restart does not reload the page or discard an open draft.
 Registered writes and file saves marked as workbench calls with a supplied stale capability
 return 409 until reconnect renews it; they are never silently recorded as agent
@@ -1471,6 +1634,10 @@ curl -X POST http://localhost:4313/api/workbench/webview/screenshot \
 Build a canvas in one shot. Earlier results can be referenced from later
 operations via `$assigned-name.field`.
 
+Entries retain the caller's transport source for per-agent scope checks. An
+optional top-level `agentId` supplies the default writer identity for entries
+without their own `args.agentId`. Batches never inherit a human scope bypass.
+
 ```bash
 curl -X POST http://localhost:4313/api/canvas/batch \
   -H "Content-Type: application/json" \
@@ -1483,6 +1650,7 @@ Supported operations:
 - `graph.add`
 - `edge.add`
 - `group.create`, `group.add`, `group.remove`
+- `annotation.add`, `annotation.remove`
 - `pin.set`, `pin.add`, `pin.remove`
 - `snapshot.save`
 - `arrange`

package/docs/mcp.md

@@ -6,6 +6,25 @@ resources**, and two canvas resource templates, plus per-skill resources at
 `notifications/resources/updated` to subscribed connections when canvas state changes.
 This uses MCP SDK v1, not SDK v2.
 
+## Board-targeted tools
+
+Registry-backed tools and AX interaction/activity tools accept `targetBoardId` and `agentId`.
+Board-bound operations retain that target across awaits and nested batches without changing the
+human's view. See the [routing contract](http-api.md#board-targeted-operations) for conflicts,
+workspace-wide operations and permissions. `canvas_screenshot` rejects a target: its image is
+of the shared WebView, not a background board.
+
+The [Amp plugin](amp-plugin.md) supplies the target and authenticated thread identity for bound
+MCP tool calls. It does not intercept MCP resource reads or CLI commands. Use routed query tools
+instead of `canvas://` resources when reading a bound background board.
+
+The plugin's `pmx_canvas_delivery` tool is an Amp host tool, not part of this MCP catalog.
+It confirms automatic context reception separately from successful steering actions.
+Context preparation uses `contextDelivery: false`; adapters record receipts through the
+[HTTP context-reads endpoint](http-api.md#ax-context-and-focus), not a public MCP write action.
+`canvas_ax_delivery` with `action: "claim"` supports `addressedOnly` and `offset` so a host pump
+can scan beyond already-received instructions without marking them acted on.
+
 ## Operation help (0.10)
 
 Call `canvas_help {}` for the sorted registry names exposed through MCP, then
@@ -146,6 +165,10 @@ tour: { stops: [...] } }` persists an ordered tour; `tour: null` resets it.
 presents a stop in the workbench, `"tour-exit"` leaves presentation, and
 `canvas_view { action: "move", nodeId | rect | viewport, duration, easing, padding, pullback }`
 eases the camera. None of these enter undo history.
+`tour-go` and `tour-exit` also accept the optional document `presenter` fence
+described in [HTTP board tours](http-api.md#board-tours). Superseded requests return
+`{ ok: true, superseded: true }` with no delivery or event. Ordinary agent calls
+omit it and retain shared arrival-order navigation.
 See the [tour model and CLI walkthrough](cli.md#tour-and-presentation) for stop
 fields. Recording is a local CLI operation; no remote recording/file-writing
 tool is added.
@@ -374,7 +397,7 @@ its `action` to the same operation the legacy tool used, so results are identica
 | `canvas_edge` | `add` · `update` · `remove` | `canvas_add_edge`, `canvas_update_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` · `remove-annotation` · `get-tour` · `set-tour` · `tour-go` · `tour-exit` · `move` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear`, `canvas_remove_annotation` |
+| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `add-annotation` · `remove-annotation` · `get-tour` · `set-tour` · `tour-go` · `tour-exit` · `move` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear`, `canvas_remove_annotation` |
 | `canvas_query` | `context` · `graph` · `search` · `layout` · `validate` | Budgeted context and summary-only connected memory; the others replace `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` |
@@ -384,7 +407,7 @@ its `action` to the same operation the legacy tool used, so results are identica
 | `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` · `reads` · `read-status` | `canvas_get_ax_timeline`, `canvas_record_ax_event`, `canvas_add_evidence`, `canvas_send_steering` (`reads` is the context read log; `read-status` is per node: last read, by whom, at which content revision) |
 | `canvas_ax_delivery` | `claim` (long-polls with `timeoutMs`) · `mark` | `canvas_claim_ax_delivery`, `canvas_mark_ax_delivery` |
 | `canvas_intent` | `signal` · `update` · `clear` | _(new — Ghost Cursor of Intent; no legacy standalone tool)_ |
-| `canvas_board` | `list` · `get` · `create` · `create-from` · `open` · `update` · `pin` · `unpin` · `knowledge-list` · `category-set` · `category-remove` · `folder-set` · `relation-preset-set` · `relation-preset-remove` | Boards and explicit workspace category/folder/shared-preset data |
+| `canvas_board` | `list` · `get` · `create` · `create-from` · `move-selection` · `open` · `update` · `pin` · `unpin` · `knowledge-list` · `category-set` · `category-remove` · `folder-set` · `relation-preset-set` · `relation-preset-remove` | Boards and explicit workspace category/folder/shared-preset data |
 | `canvas_snapshot` | `save` · `list` · `restore` · `restore-node` · `delete` · `gc` · `diff` | `canvas_snapshot` (legacy save tool), `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`, `canvas_diff` — removed in v0.4.0 after one deprecated minor |
 
 For receipt-safe single-card Undo, use `canvas_snapshot { action: "restore-node", id,
@@ -412,6 +435,17 @@ first: `prompt`, `response`, `trace`, and `mcp-app` are not reusable. Creation i
 transactional and inactive, assigns fresh node/edge IDs, and copies no pins, AX
 state, or history. Groups and the designated README are opt-in.
 
+`canvas_board { action: "move-selection", sourceBoardId, nodeIds, name,
+expectedRevision, requestId, preview: true }` instead previews relocation of the
+original cards, expanding group descendants. Get `contentRevision` from `get`
+for `expectedRevision`. Commit the same input without `preview`; retain the
+request ID for safe retries, including after restart. A successful result names
+`destinationBoardId`, `portalId`, moved `nodeIds`, affected boards and `replayed`.
+It does not open the destination. Preview exposes unsafe bindings and the history
+boundary: pre-move Undo/Redo clears; older snapshots remain readable but cannot
+restore across the move. Resolve blockers before committing, never omit cards
+silently. See the [move contract](http-api.md#move-original-cards-to-a-new-board).
+
 The copy records `previousBoardId` for its source. Board `update` accepts
 `mapPosition: { x, y }` or `null` to persist/reset a Home Map position.
 `canvas_edge { action: "add", from, to, toBoardId, type }` connects the open
@@ -513,6 +547,21 @@ into `persistFile: true` with both preconditions and top-level `content` to save
 workspace `.md` file and card together. In this mode, `data` accepts only the `rendered` preview;
 refused saves change neither. See [the file-save contract](http-api.md#nodes).
 
+For Markdown nodes, `canvas_node` actions `add` and `update` accept
+`data: { display: "heading" | "card" }`. Heading display uses the existing title
+and content as a frameless section label, without changing pin membership.
+
+For authored work cards, use `canvas_node { action: "add", type: "status", title:
+"Verify", data: { workState: "todo", detail: "Run browser checks" } }`. Update the
+same fields with `action: "update"`. State is `todo`, `in-progress`, `blocked`,
+`done` or `cancelled`; optional `progress` is 0–100 or `null` to clear it.
+These are ordinary cards, not sessions or approvals. [Work-card behavior](node-types.md#work-cards).
+
+To present an existing task read-only, use `canvas_node { action: "add", type: "status",
+data: { workItemId: "<task-id>" } }` on its active board. Omit title, detail, state and progress:
+the task supplies display fields. Remove the card without cancelling work; update the task
+through `canvas_ax_work`, not `canvas_node`. The reference cannot be patched or converted.
+
 For Mermaid nodes, `canvas_node` actions `add` and `update` accept
 `data: { fit: "contain" | "none" }`. Contain is the default, shrinking overflow
 uniformly; none keeps 100% with scrolling. Use Open as site for 100% without
@@ -805,14 +854,25 @@ AX state records where the focus came from. The full workflow lives in
 
 ## Annotation Visibility
 
-Human-drawn canvas annotations are rendered as browser SVG ink. MCP resources
-keep annotation context compact: agents see annotation counts, bounds, and target
-summaries such as the node or empty canvas region that was marked, but not the
-raw stroke geometry or visual shape.
+Humans and agents share browser SVG ink and text notes. MCP resources keep context
+compact: annotation IDs, labels, text-note content, bounds and target summaries,
+without raw stroke geometry. These are distinct from AX review annotations.
+
+```json
+{"action":"add-annotation","id":"option-question","type":"text","points":[{"x":160,"y":320}],"text":"Use this option?"}
+```
 
-Annotations are a browser-visible markup layer. Humans draw with the rail's
-Annotate popover (pen / text / eraser — the eraser removes a mark); agents can also
-remove a known annotation ID with `canvas_view { action: "remove-annotation", id }`.
+Pass that input to `canvas_view`. Omit `type` for freehand drawing with at least
+two points. Coordinates are canvas world coordinates, not screen pixels.
+`color` defaults to the theme's annotation ink; `width` controls stroke width
+or text size. [Defaults and retry rules](http-api.md#annotations) match HTTP.
+Erase a whole mark with `canvas_view { action: "remove-annotation", id }`.
+Both operations also work in `canvas_batch` as `annotation.add` / `annotation.remove`.
+
+Use marks when helpful for questions, pointing and emphasis, not for every task.
+The human can answer in the external agent host's composer; the agent then uses
+its canvas tools to act on the answer. No PMX composer or Session is required,
+and drawing or erasing a mark never resolves an approval.
 
 Use WebView automation when an agent needs to actually see annotations as drawn.
 For example, inspect `.annotation-layer path` with `canvas_webview { action: "evaluate" }`

package/docs/node-types.md

@@ -1,9 +1,9 @@
 # Node types
 
-`board` is a native text-only link. Set `data.boardId` to the durable target ID. Its header pin pins the
+`board` is a native link with a lightweight board thumbnail. Set `data.boardId` to the durable target ID. Its header pin pins the
 linked board into the agent's working set (`canvas_board { action: "pin" }`), not the portal card.
 Titles resolve from that ID, so renames and folder moves are safe; deleted
-targets render explicitly as missing. It is not an iframe or a cross-board card
+targets render explicitly as missing, with **Link to board…** to choose a replacement. It is not an iframe or a cross-board card
 edge. Static exports lock the card and intentionally do not embed the target
 title or summary, so exporting this board does not disclose another board.
 
@@ -17,7 +17,7 @@ see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
 | Type | Purpose |
 |------|---------|
 | `markdown` | Rich markdown with rendered preview |
-| `status` | Compact status indicator (phase, message, elapsed time) |
+| `status` | Authored work card, or a compact phase/message status indicator |
 | `context` | Context cards, token usage, workspace grounding |
 | `ledger` | Execution ledger summary |
 | `trace` | Agent trace pills (tool calls, subagent activity) |
@@ -32,7 +32,7 @@ see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
 | `html` | Self-contained HTML/JS in a sandboxed iframe |
 | `web-artifact` | Bundled React/Tailwind artifact (full single-file app) |
 | `group` | Spatial container/frame around other nodes |
-| `board` | Text-only link to another board, with its README summary and navigation |
+| `board` | Lightweight thumbnail link to another board, with its README summary and navigation |
 
 Creation applies per-type frame defaults and readability minimums. When a
 dimension is defaulted or clamped, HTTP and MCP create responses include a
@@ -48,6 +48,53 @@ response warns about the distinction.
 Thread node types `prompt` and `response` exist internally for agent
 conversation rendering and are not created through public APIs.
 
+## Work cards
+
+Choose **New work card** in the canvas background menu, then **Edit** inside the card.
+Title, work state, detail and optional progress save together. Cancel (or Escape inside
+the form) discards the draft. Editing grows the card locally without resizing its saved
+frame. A refused or stale save keeps the draft; Cancel returns to the latest saved state.
+Drafts, refused saves and pending saves survive opening and closing focus mode in the
+same browser tab. Unsaved drafts are not persisted across a page reload.
+
+Agents use ordinary status-node creation/update with `data.workState`: `todo`,
+`in-progress`, `blocked`, `done` or `cancelled`. `data.detail` is a string;
+`data.progress` is an optional number from 0 to 100, or `null` to clear it.
+State and progress are independent: Done does not invent 100%.
+
+```json
+{"type":"status","title":"3. Verify","data":{"workState":"in-progress","detail":"Run the browser checks.","progress":60}}
+```
+
+These are deliberately authored plans, not a task feed. They create no session, task,
+approval or execution. Connect them with existing relations, including intentional loops.
+Status nodes without `workState` or `workItemId` keep their existing phase/tool display.
+
+### Read-only live task cards
+
+Choose **Show on board** on a session task row to present that existing task. **Show card**
+focuses its existing presentation. No task or session automatically creates a card.
+Agents use ordinary status creation with `data: { workItemId: "<existing-task-id>" }` on
+the active board. The immutable reference includes `workItemBoardId`, defaulting to the
+active board. Moving the presentation to another board preserves that original task owner;
+an ordinary planning card cannot be converted by patching it.
+
+Title, detail, work state and attribution are derived from the task record, not independently
+editable card fields. Do not supply those fields or progress when creating a live card.
+The persisted display cache is refreshed on task changes, Undo and reload. Update the task
+through the existing work-item API, not a card PATCH. Geometry, pins and relations remain editable.
+Ending a session preserves its task cards; removing a card does not cancel the task.
+A missing task displays **Task unavailable**, never an actionable control. Static exports
+label live cards as read-only snapshots. No progress percentage or approval controls are added.
+Selective board copies become independent authored work cards, without a task reference or task attribution.
+
+## Shared node behavior
+
+The spatial board and its content scale proportionally at every zoom, without
+switching layouts. Iframe previews mount automatically near the viewport and
+remain mounted to preserve arbitrary app state. There is no lifetime preview cap;
+memory use grows with the viewers visited. Board links and Mermaid render inline.
+
 Full node reads expose server-owned `createdBy`, `lastEditedBy`, and
 `contentRevision`. Authors distinguish human, agent, system, and unknown;
 legacy nodes remain unknown. The revision advances on semantic content changes,
@@ -73,6 +120,15 @@ that fits the work — each step adds capability and bundle weight.
 
 ## Markdown tasks
 
+Use **Display as heading** in a Markdown card's context menu for a frameless section
+label. Its title becomes the heading and its content remains below it. **Display as card**
+restores the frame; this does not change the content or context pins. Agents can set
+`data.display` to `"heading"` or `"card"` through ordinary node creation or updates.
+**Set as README** in the card's ⋯ menu designates the board's existing README field;
+the current README instead offers **Remove as README** to clear it. A quiet **README**
+word stays visible in the designated card's header, including heading display.
+**Edit** stays visible below ordinary Markdown. Heading display has no footer.
+
 Tick a task directly on its card, including quoted and nested tasks. A card click changes
 only that task's `[ ]` or `[x]` marker, preserving the rest of the source exactly.
 Task-shaped text in code examples and raw HTML checkboxes are not Markdown task controls.
@@ -119,6 +175,9 @@ different type by extension:
 
 ## Mermaid nodes
 
+Diagrams render inline with the canvas palette, rather than in an iframe. Invalid
+source shows a visible error and **Retry**. Native WebKit hosts remain best-effort.
+
 Mermaid diagrams default to `data.fit: "contain"`: when the diagram overflows
 the available body, it shrinks uniformly until the entire diagram fits. Small
 diagrams stay at 100%; aspect ratio, labels, and edges are preserved, in both
@@ -216,6 +275,12 @@ with the server's transport, tool name, and arguments.
 
 ## json-render nodes
 
+Embedded dashboards and charts inherit all nine named canvas themes. Their root
+card fills the viewer without an extra panel or shadow. A root title identical to
+the canvas card title is hidden; distinct authored titles and descriptions remain.
+Theme changes preserve viewer-local inputs. A failed replacement keeps the last
+painted document and offers **Retry** instead of repeatedly reloading it.
+
 `json-render` nodes turn structured JSON specs into rendered UI panels
 (dashboards, tables, forms, cards) without writing HTML. PMX Canvas ships the
 [`@json-render/*`](https://www.npmjs.com/package/@json-render/core) 0.21.0 runtime
@@ -372,6 +437,10 @@ Fitting waits for local or remote human grabs to end. A growing ungrouped,
 screen-unpinned card moves downward if needed to leave a 24px gap from neighboring
 cards, without moving those neighbors. A relocation records one undo step for
 both size and position; height-only adjustments do not add undo entries.
+Repeated measurements from the same document do not reverse Undo or a smaller
+height set by another writer. Changed content dimensions, width or chrome can
+fit again. Replacing or reopening the viewer starts a fresh measurement, so this
+suppression does not survive reload, collapse/reopen or a board switch.
 Grouped or screen-pinned cards retain their positions. Collapsed cards and cards
 marked `strictSize` or `userResized` are not automatically resized. Hosted MCP
 apps and webpage viewers do not use this authored-content fitting behavior.
@@ -380,6 +449,22 @@ Read the settled node geometry after mounting rather than treating requested
 dimensions as final. Prefer targeted node reads or the CLI's projected layout
 fields over fetching full content merely to check spacing.
 
+### Move original cards between boards
+
+Use **Move to new board** from the selection bar or a group's **⋯** menu. Name the
+destination, preview the expanded selection and its pins/README/history effects, then
+choose **Move and open**. Groups include all descendants. The source receives a working
+portal; the destination contains the same card identities, not copies. A late reply never
+overrides a newer board choice. If the reply is interrupted, **Retry move** reuses the same
+request without creating a duplicate destination.
+
+Save or cancel local drafts first. Runtime sessions, streams, authority-bearing controls,
+partial imports and unsupported cross-board references can refuse the whole move with a
+reason. Read-only live task cards keep their original owner; moving never starts or cancels
+a task. Board-space annotations stay on the source. Pre-move Undo/Redo clears on affected
+boards; older snapshots remain inspectable, but cannot restore across that boundary.
+See the [move contract](http-api.md#move-original-cards-to-a-new-board) for agent access.
+
 ## HTML nodes
 
 `html` nodes render a normal self-contained HTML/JS document in a sandboxed iframe.
@@ -431,6 +516,14 @@ component gallery, interaction prototype, flowchart, SVG illustration set,
 presentation, explainer, status report, incident report, triage board, config
 editor, or prompt tuner.
 
+The card's ⋯ menu offers **Copy JSON** for primitives with JSON export (all except
+the custom `presentation` template). It copies the mounted document's current
+state, including interactive edits, rather than the original server data.
+Open the viewer first; unavailable/reloading content or denied clipboard access
+shows a failure message. Copy prompt and the shared inner-header copy buttons are
+removed. Primitive-specific actions such as Copy diff and Copy SVG remain.
+Ordinary HTML nodes do not receive this menu item.
+
 Omitted fields may use the template's examples. Explicit empty arrays, empty
 strings, or `null` mean “show nothing”: the field's section, heading, and
 dependent controls are omitted rather than replaced with sample content.
@@ -535,6 +628,10 @@ as dashed-border frames with a title bar and optional accent color.
   its children stay as independent nodes (one undo step); `canvas_group { action: "ungroup" }`
   does exactly the same
 - Collapsing a group hides children and shows a summary
+- **Open group** in the frame menu, or Enter on the focused frame, drills into its
+  original cards. Breadcrumbs and Escape restore the parent camera and selection.
+  Outside-link stubs navigate to the actual cards. This view creates no boards or
+  copies and does not change context pins or what agents can read.
 - By default, group creation preserves the children's current positions and
   expands the frame around them
 - Pass `childLayout` to auto-pack children (`grid`, `column`, `flow`)
@@ -549,6 +646,14 @@ canvas_group({ action: 'create', title: 'Auth Module', childIds: ['node-1', 'nod
 
 All edges support labels, styles (solid/dashed/dotted), and animation.
 
+Select an edge to edit its kind, label or reason inline, or delete it. Parallel
+links show their pair count. Dependency counts report cyclic clusters and cards
+affected downstream of the selected cards; `loop` and `if-fails` remain inert flow
+illustrations. Qualified dependency/source warnings carry a separate amber mark.
+In a card's Relations panel, **Show lineage** highlights its local dependency and
+derivation component; **Show on canvas** highlights its direct connections. Remote
+targets remain accessible through their named references.
+
 Native edges optionally carry `toBoardId`: `from` belongs to the open source
 board and `to` identifies a card on that target board. These connections appear
 in the visible source card footer with readable board/card titles; missing