pmx-canvas 0.11.0 → 0.12.1

package/skills/pmx-canvas/evals/evals.json

@@ -536,8 +536,8 @@
     {
       "id": 22,
       "name": "tour-authoring-and-capture",
-      "prompt": "Turn the Overview group and the Results card into a presentation tour, then tell me how to capture it deterministically at 1920x1080. I want a one-second overview move, a zero-duration jump to Results, and no changes to another viewer's camera.",
-      "expected_output": "Targets the intended board, resolves the real group/card IDs, persists one tour with canvas_view set-tour, and uses valid node targets with durations 1 and 0. Explains that presentation is viewer-local and does not auto-advance. Gives deterministic record guidance using the same saved tour, --resolution 1920x1080, --present, and a new output path after verifying the matching daemon/workspace and Chrome/Bun WebView prerequisites. Does not invent a separate recording timeline or use realtime --duration.",
+      "prompt": "On the current board, turn the Overview group and the Results card into a presentation tour, then tell me how to capture it deterministically at 1920x1080. I want a one-second overview move, a zero-duration jump to Results, and no changes to another viewer's camera. That viewer is already presenting.",
+      "expected_output": "Verifies the current board, resolves the real group/card IDs, persists one tour with canvas_view set-tour, and uses valid node targets with durations 1 and 0. Distinguishes viewer-local rendering/free pan and isolated recording from shared tour navigation and exit. Does not call tour-go, tour-exit or move, switch boards, or use human Next/Back controls. Explains that present:false still advances viewers already presenting. Gives deterministic record guidance using the same saved tour, --resolution 1920x1080, --present, and a new output path after verifying the matching daemon/workspace and Chrome/Bun WebView prerequisites. Does not invent a separate recording timeline or use realtime --duration.",
       "assertions": [
         {
           "name": "persists-valid-shared-tour-model",
@@ -556,7 +556,30 @@
         },
         {
           "name": "preserves-viewer-camera",
-          "description": "States that the presentation/capture camera is local and stops advance manually, rather than moving another viewer's camera",
+          "description": "Keeps the already-presenting viewer unchanged by avoiding shared tour-go/tour-exit/move, board switching and human navigation; distinguishes isolated capture from the shared cursor and does not treat present:false as isolation",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 44,
+      "name": "presenter-superseded-is-not-applied-navigation",
+      "prompt": "In disposable boards A and B, verify optional presenter ordering. On visible A send a valid go with intent 2, then an exit with intent 1 for the same document and activation. Repeat with a stale activation. Include an independent-document control and an ordinary unfenced call. Then target background B with a presenter-bearing call and an unfenced control. Can ok:true or the SDK exit return prove the stale command ran?",
+      "expected_output": "Reads the actual activation stamps and uses positive safe-integer intents with independent document IDs. Checks applied delivery stamps and cursor/event behavior. Older intent, stale activation and presenter-bearing background calls return ok:true,superseded:true without navigation or cursor change. Independent and unfenced controls still apply on their target board; B's tour does not replace A's cursor or navigate its viewers. Explains that the fence orders requests, does not grant authority or isolate same-board viewers, and that SDK exit returns void while fenced go may return superseded:true. Does not count eval definitions as executed evidence.",
+      "assertions": [
+        {
+          "name": "checks-superseded-side-effects",
+          "description": "Observes no navigation event or cursor change for stale intent, stale activation and presenter-bearing background calls, rather than treating ok:true as applied navigation",
+          "type": "output_check"
+        },
+        {
+          "name": "positive-controls-and-stamps",
+          "description": "Verifies applied epoch/generation/sequence for the newer request and independent-document/unfenced controls; B's unfenced call changes only B's cursor while A remains visible with its own cursor",
+          "type": "output_check"
+        },
+        {
+          "name": "sdk-return-boundary",
+          "description": "Distinguishes fenced go's superseded result from exit's void return and avoids claiming viewer isolation or authority from the fence",
           "type": "output_check"
         }
       ]
@@ -564,7 +587,7 @@
     {
       "id": 23,
       "name": "multi-board-targeting",
-      "prompt": "I have Roadmap and Incident Review boards. Add a decision note only to Incident Review and set its tour to the Summary group. Do not disturb Roadmap.",
+      "prompt": "Using raw MCP without an Amp plugin binding, I have Roadmap and Incident Review boards. Add a decision note only to Incident Review and set its tour to the Summary group. Preserve Roadmap content; switching the shared view is allowed.",
       "expected_output": "Lists/gets boards, resolves the exact Incident Review board and calls canvas_board action open or CLI board open with its ID, verifies the returned activeBoardId, searches for the Summary group there, then adds the note and sets that board's tour. It explains that opening switches the shared view but preserves Roadmap content. It does not infer IDs from titles, mutate Roadmap, invent inactive-board write targeting, or assume that a board switch succeeded. It validates Incident Review and reports board/node IDs.",
       "assertions": [
         {
@@ -730,7 +753,7 @@
     {
       "id": 30,
       "name": "amp-native-steering-evidence-boundary",
-      "prompt": "On this disposable board, native Amp MCP is connected and your source/consumer is amp-review. The browser pinned the Review card and sent amp-review a fresh instruction to append receipt CHECK-30. Prove the round trip, then confirm that an idle Amp thread will now wake automatically and that native Skills discovery works.",
+      "prompt": "On this disposable board, raw native Amp MCP is connected without the directory plugin and your source/consumer is amp-review. The browser pinned the Review card and sent amp-review a fresh instruction to append receipt CHECK-30. Prove the round trip, then confirm that an idle Amp thread will now wake automatically and that native Skills discovery works.",
       "expected_output": "Uses actual Amp Canvas tools to read the pinned card, claims only as amp-review, signals intent and appends the requested receipt without losing existing content. Verifies the rendered receipt before marking that delivery for amp-review and confirms it is no longer pending. Uses a different recipient as a negative control and detaches only self-owned test sessions. Reports active-agent polling as verified but declines to infer idle-thread wake-up, persistent pumping or native MCP Skills discovery from this evidence.",
       "assertions": [
         {
@@ -1058,6 +1081,88 @@
           "type": "output_check"
         }
       ]
+    },
+    {
+      "id": 45,
+      "name": "quiet-expiry-versus-veto-and-leaf-linkage",
+      "prompt": "In a disposable canvas, signal separate create intents for three Markdown cards. Let the harness quietly expire one, human-veto another, and leave the third live. Create each through a separate batch leaf using the returned intent ID. Explain whether putting one intentId on the batch envelope would protect every sibling. Do not bypass the veto or treat expiry as approval.",
+      "expected_output": "Uses operations[].args.intentId on supported node.add leaves, never the batch envelope. Verifies the expired case proceeds unlinked, the vetoed case creates no card, and the live case settles once. Explains the standalone-MCP versus attached-HTTP top-level mismatch without relying on either behavior. Ordinary scope/revision rules still apply; no new ID is minted to evade the veto.",
+      "assertions": [
+        {
+          "name": "distinguishes-expiry-from-human-refusal",
+          "description": "Readback finds the expired control's card but no vetoed card; the agent neither labels quiet expiry a veto nor retries the vetoed plan under another ID",
+          "type": "output_check"
+        },
+        {
+          "name": "links-only-the-supported-leaf",
+          "description": "Trace puts intentId in node.add args, verifies live settlement, and does not claim one settled intent protects later siblings or a top-level batch intent is portable",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 46,
+      "name": "amp-bound-delivery-and-separate-jev-consents",
+      "prompt": "The actual Amp plugin binds this thread to A while the human views B. Its context packet contains a receive token and a summary of A/Review. Addressed steering asks you to append CHECK-46 there. Context ranking is enabled but Jev advice is off. Show the edit, acknowledge it, and ask Jev to rank your proposed changes. Can you read canvas://context instead, open A, or wake a sleeping orb? Do not change consent yourself.",
+      "expected_output": "Checks session status, receives each supplied packet token, reads full A/Review through routed MCP, edits without switching B, and verifies the result before acknowledging steering. Does not mistake a context receipt for a full read or completed action. Declines Jev inference without the separate advice consent, using deterministic fallback or requesting human opt-in. Reports awake-executor idle wake separately from sleeping-orb resume.",
+      "assertions": [
+        {
+          "name": "uses-bound-tools-without-navigation",
+          "description": "Trace uses routed MCP rather than CLI or resources/read, preserves B's active view, and never overrides the bound destination",
+          "type": "output_check"
+        },
+        {
+          "name": "receive-is-not-acknowledge",
+          "description": "Packet reception precedes full content reading and action; visible CHECK-46 verification precedes steering acknowledgment, and failed/unverified work is not acknowledged",
+          "type": "output_check"
+        },
+        {
+          "name": "consent-and-wake-boundaries",
+          "description": "Ranking consent is not reused for advice, no consent is enabled by the agent, and native awake-executor wake is not claimed to wake a sleeping orb",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 47,
+      "name": "authored-versus-live-task-card-ownership",
+      "prompt": "In a disposable library, A and B each have a task named Review. Show A's existing task as a live status card and also create an independent authored plan card. Mark A's task in-progress, move its presentation to B, then delete that presentation. Do not transfer or cancel either task. Can you edit the live card's title/progress or rebind it to B's same-named task?",
+      "expected_output": "Resolves task identity on A, creates the live card using workItemId without derived fields, and creates the authored card separately with workState. Updates the task through canvas_ax_work on A. After moving, confirms immutable workItemBoardId A and fresh task-derived display; rejects title/progress edits and rebinding. Deleting the presentation leaves both tasks intact and the authored card independent.",
+      "assertions": [
+        {
+          "name": "separates-task-from-presentation",
+          "description": "Live creation includes the resolved task ID but no derived title/content/workState/detail/progress; authored creation uses workState without a task binding",
+          "type": "output_check"
+        },
+        {
+          "name": "preserves-owner-across-move",
+          "description": "Readback after relocation shows owner A, the original task ID and updated state, never B's same-title task; no rebinding or direct display-field edit is attempted as a solution",
+          "type": "output_check"
+        },
+        {
+          "name": "deletion-is-not-cancellation",
+          "description": "After deleting only the presentation, qualified task reads confirm A's task is still in-progress and B's task unchanged; authored plan data remains independent",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 48,
+      "name": "batch-annotation-partial-result-and-tool-envelopes",
+      "prompt": "In a disposable canvas, read canvas_help for supported batch operations. Add a text annotation with an explicit ID, then submit a deliberate unsupported edge.update as the second batch entry. Inspect the failure before retrying the annotation, then remove it. Compare the raw structured replies from canvas_help, canvas_batch and canvas_ingest_activity. Can you always unwrap result.data or retry the entire failed batch?",
+      "expected_output": "Uses annotation.add/remove, identifies edge.update as unsupported, and checks the failedIndex plus committed results/refs before retrying. Equal normalized annotation content with the same ID reuses the mark; removal is not a durable replay receipt. Distinguishes registry result.operation/outcome/data, help metadata under result and direct activity fields. It preserves isError/partial state instead of discarding it or blindly replaying writes.",
+      "assertions": [
+        {
+          "name": "partial-failure-keeps-earlier-annotation",
+          "description": "Failure at index 1 retains one annotation; identical-ID/content retry does not duplicate it, and removal erases that mark only",
+          "type": "output_check"
+        },
+        {
+          "name": "decodes-per-tool-contract",
+          "description": "Extracts batch results from structuredContent.result.data and checks outcome partial, reads help from result, and reads activity fields directly without blanket unwrapping",
+          "type": "output_check"
+        }
+      ]
     }
   ]
 }

package/skills/pmx-canvas/references/full-reference.md

@@ -349,7 +349,7 @@ The CLI targets `http://localhost:4313` by default. Override with `PMX_CANVAS_UR
 | Type | Purpose | When to use |
 |------|---------|-------------|
 | `markdown` | Rich formatted content | Explanations, documentation, notes, findings |
-| `status` | Compact color-coded indicator | Progress tracking, build/test results, task state |
+| `status` | Compact status or deliberately authored work card | Work plans with `data.workState`; phase/tool status without it |
 | `file` | Live file viewer (auto-watches) | Show source code with live updates on file change |
 | `image` | Image display | Screenshots, diagrams, charts |
 | `context` | Context card | Key context the human should see |
@@ -419,6 +419,9 @@ contract). Their meaning comes from the node **type** and value instead: a `stat
 `waiting` — e.g. `review` → green, `running` → accent; an unrecognized phase renders gray), and a
 `trace` node from its `status` field (`success` → green, `failed` → red, `running` → accent). To
 color an arbitrary region, group the nodes and set the group's `color`.
+Authored status cards with `data.workState` instead use the work-state glyph and label:
+blocked uses the warning token, done the success token, and cancelled the muted token.
+Do not set arbitrary colors to encode work state.
 
 When you do set a color (group/graph), use this palette consistently to convey meaning:
 - **Green** (`#22c55e`) — success, done, healthy
@@ -455,9 +458,9 @@ enforce conditional requirements. Non-registry tools use `tools/list` instead.
 | `canvas_edge` | `add` · `update` · `remove` | Connect / edit / disconnect nodes |
 | `canvas_group` | `create` · `add` · `ungroup` | Manage spatial group containers |
 | `canvas_history` | `undo` · `redo` | Time travel through the mutation ring buffer |
-| `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 workspace categories/folder properties/shared relation templates; knowledge writes never open a board. Template edits/deletion never rewrite boards or connections. `category-remove` takes `id` and refuses explicit folder assignments, including empty folders; reassign or clear them first. |
+| `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 workspace categories/folder properties/shared relation templates; knowledge writes never open a board. Template edits/deletion never rewrite boards or connections. `category-remove` takes `id` and refuses explicit folder assignments, including empty folders; reassign or clear them first. |
 | `canvas_snapshot` | `save` · `list` · `restore` · `restore-node` · `delete` · `gc` · `diff` | Named snapshots: save/list/restore/delete, garbage-collect old ones, diff current canvas vs a snapshot (`diff` takes `snapshot`, not `id`); `restore-node` puts one card (`nodeId`) back to its content in snapshot `id` |
-| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` · `get-tour` · `set-tour` · `tour-go` · `tour-exit` · `move` | Auto-arrange, pan-to-node, fit viewport, clear the board, delete annotations, read/persist ordered presentation stops (`tour: null` derives group order), present a stop / exit, ease the camera to a node, rect or viewport (never an undo step) |
+| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `add-annotation` · `remove-annotation` · `get-tour` · `set-tour` · `tour-go` · `tour-exit` · `move` | Auto-arrange, pan-to-node, fit viewport, clear the board, draw/write/erase annotations, read/persist ordered presentation stops (`tour: null` derives group order), present a stop / exit, ease the camera to a node, rect or viewport (never an undo step) |
 | `canvas_query` | `context` · `graph` · `search` · `layout` · `validate` | Read the budgeted brief or summary-only connected memory graph, find nodes, read full layout, or **`validate`** collisions / containment / dangling edges |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | Hosted MCP apps, the Excalidraw diagram preset, and bundled web artifacts (folds `canvas_open_mcp_app` / `canvas_add_diagram` / `canvas_build_web_artifact`) |
 | `canvas_webview` | `status` · `start` · `stop` · `resize` · `evaluate` | Headless Bun.WebView automation for the workbench (folds the `canvas_webview_*` / `canvas_resize` / `canvas_evaluate` tools) |
@@ -498,6 +501,18 @@ group structure are optional; fresh IDs are allocated; pins, AX state, and
 history are not copied; the source remains unchanged and the new board inactive.
 The new board records `previousBoardId` pointing to its source.
 
+For an identity-preserving move, use `canvas_board` action `move-selection`, not
+copy/delete. Read the active source board's `contentRevision` with `get`. Preview
+with `sourceBoardId`, `nodeIds`, `name`, `expectedRevision: contentRevision`,
+`requestId` and `preview: true`; inspect blockers and notices before committing
+with the same inputs without `preview`. Retry an uncertain response with the same
+request ID and inputs. Group descendants move together; unsafe bindings refuse
+the entire move. Cards retain identities, pins, relations and review history,
+without new validation or read evidence. The source stays open with a portal to
+the new board. Pre-move Undo/Redo is cleared on affected boards; older snapshots
+remain inspectable but cannot be restored across the move. Open the returned
+`destinationBoardId` only when navigation is wanted.
+
 ### Connected memory (wave 2)
 
 Home Folders, Map and Graph, wiki links/backlinks, and brief discovery share one
@@ -609,8 +624,11 @@ persisted, auto-expiring (~8s), never in `canvas_query layout`.
 Narrate → linked mutation → automatic settle:
 1. `canvas_intent { action: "signal", kind: "create", nodeType: "markdown", label: "Add evidence", reason: "capturing the failing test", confidence: 0.8 }` → returns `intent.id` and the `position` the canvas chose.
 2. Make the real move and pass that id: `canvas_node { action: "add", intentId: <intent.id>, ... }`.
-3. PMX rejects the mutation if the intent was vetoed or expired; otherwise the
-   successful mutation settles the ghost into the resulting node automatically.
+3. A human-vetoed intent rejects its linked mutation. A quietly expired ghost does not:
+   the write proceeds unlinked, subject to the ordinary permissions and revision checks.
+   A successful write linked to a still-live intent settles the ghost automatically.
+   Expiry is neither approval nor a human veto. Never retry a vetoed plan under a new ID
+   just to bypass the human's decision.
 
 Use `canvas_intent { action: "clear", id }` only when abandoning a plan without
 performing the linked mutation.
@@ -635,9 +653,18 @@ edits; destructive actions (clear/restore/remove); and creating
 artifact/report/dashboard nodes. Skip for tiny metadata fixes, API-only pin/unpin
 verification, deterministic report-node refreshes the human just asked for,
 post-restore cleanup, and bulk fixture churn. **For batch work, signal one ghost
-per human-meaningful move, not one per low-level op** — e.g. one "lay out the
-investigation board" intent, then run the batch with that linked `intentId` (use
-`seq` to order staged previews) so the human watches the wireframe before it fills.
+per human-meaningful move, not one per low-level op.** Put its `intentId` inside the
+supported leaf operation's `args`, never on the `canvas_batch` envelope. Each live
+intent settles once; it is not a veto gate for every sibling in a batch. For example,
+after signalling a create intent, use its actual returned ID in this leaf:
+
+```json
+{"operations":[{"op":"node.add","args":{"type":"markdown","title":"Evidence","content":"Observed failure","intentId":"<returned-intent-id>"}}]}
+```
+
+Do not rely on a top-level batch `intentId`: standalone MCP can refuse it, while the
+attached HTTP batch reader does not forward it. Unsupported operations cannot be made
+veto-linked by wrapping them in a batch. Use `seq` to order separate staged previews.
 
 ### Standalones (first-class — not deprecated)
 
@@ -648,10 +675,12 @@ composite in v0.4.0 (actions `save | list | restore | delete | gc | diff`); the
 standalones were removed after their deprecated 0.3.x window.
 
 `canvas_batch` supports exactly these ops: `node.add`, `node.update`, `node.remove`, `graph.add`,
-`edge.add`, `edge.update`, `edge.remove`, `group.create`, `group.add`, `group.remove`, `pin.set`/`pin.add`/
-`pin.remove`, `snapshot.save`, and `arrange`. Anything else fails with "Unsupported canvas_batch
+`edge.add`, `edge.remove`, `group.create`, `group.add`, `group.remove`, `annotation.add`,
+`annotation.remove`, `pin.set`, `pin.add`, `pin.remove`, `snapshot.save`, and `arrange`.
+`edge.update` is not supported. Anything else fails with "Unsupported canvas_batch
 operation" — batch is non-atomic, so earlier ops stay applied and the response carries
-`failedIndex`. `canvas_screenshot` requires an active automation WebView: call
+`failedIndex`, `results` and `refs`. Inspect that committed prefix before retrying; an
+error does not roll it back. `canvas_screenshot` requires an active automation WebView: call
 `canvas_webview { action: "start" }` first.
 
 > **Removed in v0.3.0 → use the composite instead**: `canvas_open_mcp_app` / `canvas_add_diagram` /
@@ -702,8 +731,33 @@ delete+recreate; preserves edges, pins, position)
 
 **`canvas_node { action: "get", id }`** — Get a single node's full data by `id`.
 
-**`canvas_view { action: "remove-annotation", id }`** — Remove a human-drawn annotation by `id`. Use when
-context gives you the annotation ID; use WebView first if you need to identify a mark by shape or location.
+**`canvas_view { action: "add-annotation", points, … }`** — Draw freehand ink with at least two
+world-coordinate points, or set `type: "text"`, `text` and one point to write a note.
+`width` is stroke width (default 4, clamped to 1–24) or font size (default 24,
+clamped to 1–96). `color` defaults to `currentColor`, the theme's annotation ink;
+explicit colors must be `#rrggbb`. Text is trimmed to 240 characters, labels to 160.
+Bounds and creation time are server-derived.
+
+Freehand points render as straight segments with round caps/joins, without automatic
+smoothing. Sample curves densely for smooth-looking outlines and loops. Cursor updates
+through `canvas_ax_state { action: "set-presence", cursor: { x, y } }` are separate,
+ephemeral presence, not drawing gestures; reuse your writer identity without attaching
+a session. An annotation appears complete on creation, not as a streaming stroke.
+See [Shared ink and questions](workbench-workflows.md#shared-ink-and-questions).
+
+Use an explicit `id` for retries: equal normalized content returns the existing mark
+without another Undo entry, while different content conflicts. After erasing or Undo,
+adding the ID creates a mark again; this is not a durable creation receipt.
+
+**`canvas_view { action: "remove-annotation", id }`** — Erase a whole human or agent mark,
+not the underlying card. An absent mark returns not-found. Context gives you IDs;
+inspect the canvas first when identifying a mark by shape or location.
+CLI and MCP batches accept `annotation.add` / `annotation.remove` with the same arguments.
+
+Humans and agents share this layer. Use marks when helpful, not for every task.
+The human may answer in the external agent host's composer; no PMX session,
+PMX composer or reply card is required. Marks are not approval gates, and drawing
+or erasing does not answer a question or execute a loop. Existing scope fences apply.
 
 **`canvas_node { action: "update", id, refresh: true }`** — Re-fetch the URL stored on a `webpage` node
 - `id` (required): webpage node to refresh
@@ -962,17 +1016,17 @@ below operates on the live canvas state through the `canvas_webview` composite.
 Useful workbench selectors:
 - Nodes: `.canvas-node`, `.canvas-node.active`, `.canvas-node.context-pinned`, `.canvas-node.group-node`
 - Node internals: `.node-title`, `.node-titlebar`, `.node-body`, `.node-type-badge`, `.node-controls`
-- Annotations: `.annotation-layer path` renders human-drawn freehand ink. Use WebView
-  to inspect or screenshot annotation shapes; MCP/context resources only expose compact
-  annotation target summaries, not the raw visual shape. Humans can remove marks with
-  the eraser in the rail's Annotate popover; agents can remove a known annotation ID with
-  `canvas_view { action: "remove-annotation" }`.
+- Annotations: `.annotation-layer path` renders shared freehand ink; `.annotation-layer text`
+  renders text notes. Use WebView to inspect or screenshot shapes; MCP/context resources
+  expose IDs, text, labels, targets and bounds, not raw stroke geometry. Humans use the
+  rail's Draw / Text note / Eraser tools; agents use `canvas_view` actions
+  `add-annotation` / `remove-annotation` on the same layer.
 - Canvas chrome (rail-chrome-v2): `.tool-rail`, `.top-bar` (`.connection-dot`, `.agent-chip`,
   `.gate-badge`, `.context-chip`, `.external-indicator`, `.start-session-btn`),
   `.connection-banner`, `.canvas-region`, `.session-panel`, `.command-bar`, `.selection-bar`,
   `.activity-feed`, `.writers-sheet`, `.session-receipt`, `.snapshot-panel` (the History
   drawer), `.minimap`, `.empty-state`, `.command-palette`, `.expanded-overlay-panel`.
-- Presence: `.agent-cursor` (attached agent), `.human-cursor` (other tabs), `.scope-fence`,
+- Presence: `.agent-cursor` (attached or external agent), `.human-cursor` (other tabs), `.scope-fence`,
   `.canvas-node.agent-mutating` (shimmer), `.node-yield-pill`.
 - Groups: `.canvas-node.group-node` with `.group-name-pill`, `.group-actions`, `.group-chip`
   (collapsed); `.drop-pill` while a dragged node would join/leave a group; `.edge-hint-pill`
@@ -1146,6 +1200,22 @@ writes occurred. Interaction, activity-ingestion and screenshot tools instead
 use direct structured objects matching their schemas. Check `isError` and domain
 outcomes. A composite's annotations cover all its actions, not just reads.
 
+Paired example: `canvas_node { action: "add", type: "markdown", content: "Evidence" }`
+returns registry data under `structuredContent.result.data` (excerpt; the ID varies):
+
+```json
+{"result":{"operation":"node.add","outcome":"success","data":{"ok":true,"id":"example-node"}}}
+```
+
+By contrast, `canvas_help {}` returns `structuredContent.result.operations`, not
+`result.data`. `canvas_help { op: "node.add" }` returns metadata with `operation`,
+`tool`, `description` and `inputSchema` directly under `result`.
+For direct tools (`canvas_ax_interaction`, `canvas_ingest_activity`, `canvas_screenshot`),
+read fields directly from `structuredContent` according to their `outputSchema`.
+These are different contracts, not optional wrappers to strip recursively. Text blocks
+are a separate representation; an SDK/host may already return `structuredContent`.
+On a failed call, inspect its error response and partial results before retrying writes.
+
 Cancellation releases supported AX waits, aborts webpage fetches before late
 content writes, and stops subsequent batch operations. Completed writes remain;
 batch partial results retain `results` and `refs`. A created webpage can remain
@@ -1449,7 +1519,7 @@ The `canvas://spatial-context` resource reveals how the human has organized info
   This implies sequence or priority.
 - **Pinned neighborhoods** — For each pinned node, nearby unpinned nodes are listed. These
   are the human's implicit context — things they consider related to what they pinned.
-- **Annotations** — Human-drawn markup is summarized by target/bounds only, e.g. an
+- **Annotations** — Shared markup is summarized by ID, label, text, target and bounds, e.g. an
   annotation over a node or empty canvas region. Use WebView (`canvas_webview { action: "start" }` +
   `canvas_webview { action: "evaluate" }`/`canvas_screenshot`) when you need to see whether the mark is an
   arrow, line, circle, or other drawn shape. Remove known annotations with
@@ -1575,15 +1645,59 @@ Show system components and how they interact:
 
 ### Task Plan with Dependencies
 
-Track work items and their relationships:
+Show useful work deliberately, not a card per task or event. Ordinary work cards are authored
+node data, not AX work items. They require no session and create no approval or execution.
+
+1. Create a `status` node with `data.workState`: `todo`, `in-progress`, `blocked`, `done` or
+   `cancelled`. Use string `data.detail` for context and optional `data.progress` from 0 to 100.
+   Progress is independent of state: Done does not imply 100%; `null` clears progress.
+2. Update the same card through `canvas_node { action: "update", id, data: { ... } }`.
+   Include `expectedBoardId` and `expectedContentRevision` when an edit depends on a prior read.
+3. Connect steps, dependencies, alternatives and intentional loops with existing relations.
+   A drawn loop does not execute. Group distinct phases when useful, then inspect readability.
+4. Humans use **New work card** from the background menu and **Edit/Save/Cancel** inside the card.
+   Drafts and pending/refused saves survive focus-mode open/close, but not a page reload.
+   The editor's temporary growth does not resize the saved card.
+
+MCP creation:
+
+```json
+{"action":"add","type":"status","title":"Verify","data":{"workState":"todo","detail":"Run browser checks"}}
+```
+
+CLI creation uses structured batch data, not `node add --data` (that flag is for graph series):
+
+```bash
+pmx-canvas batch --json '[{"op":"node.add","args":{"type":"status","title":"Verify","data":{"workState":"todo","detail":"Run browser checks"}}}]'
+```
+
+Without `data.workState`, status cards retain their phase/tool display. Session-task linking
+is not provided by these authored cards. Questions can be drawn or written beside the plan;
+the human can answer in the external agent host's composer, without a PMX reply card.
+
+### Live task cards
+
+A live card presents an existing AX work item; it is not another task or an authored
+work plan. Read the task first with `canvas_ax_work { action: "list" }` on its owning
+board, then create a `status` presentation using that task's actual ID:
+
+```json
+{"action":"add","type":"status","data":{"workItemId":"<existing-task-id>"}}
+```
 
-1. Create `status` nodes for each task
-2. Color-code: green=done, yellow=in-progress, red=blocked, gray=queued, blue=ready/available
-3. Connect with `depends-on` edges — use `dashed` style for blocked dependencies, `solid` for
-   satisfied ones
-4. Update status nodes as work progresses using `canvas_node { action: "update" }`
-5. Arrange with `flow` layout to show the dependency chain left-to-right
-6. Group related tasks if the plan has distinct phases
+The owner defaults to the current board. To present a task from another board, supply
+its explicit `data.workItemBoardId` too. Both task ID and owner are fixed at creation;
+moving the card does not transfer the task. Create through the current board owner
+(or the Amp plugin's bound board), not `destinationBoardId` background creation.
+
+Omit `title`, `content`, `workState`, `detail`, `progress`, `axWorkStatus`,
+`liveWorkAvailable` and `liveWorkSource` from creation and updates, including nested
+data fields. The server derives title, detail, status and source from the task; these
+are read-only display fields. Update the underlying work item on its owning board with
+`canvas_ax_work { action: "update", id: "<existing-task-id>", status: "in-progress" }`.
+Position and size still belong to the card. Deleting the presentation does not cancel
+or delete the task. If the task is unavailable, the card displays that fact rather than
+becoming an editable authored card. To change the binding, create a new presentation.
 
 ### Code Exploration
 

package/skills/pmx-canvas/references/html-primitives.md

@@ -110,6 +110,13 @@ agent.
 - `interaction-prototype` exposes live controls and copyable config for implementation tuning.
 - Tell the human which copy/export button to use, then ask them to paste the result back if you need to act on edits.
 
+The card menu also offers **Copy JSON** for non-presentation HTML primitives. Open the viewer
+first: this reads its current interactive state, preferring the expanded frame when present,
+not a stale export of saved node data. The reply is bound to the frame source, document token
+and request ID; the parent workbench requests clipboard access from the human's click.
+Clipboard permission or host limitations can still refuse the copy and show an error.
+This does not persist edits, support arbitrary raw HTML, or replace the per-format buttons above.
+
 ## Sandbox And Persistence
 
 - Primitive output runs inside the existing HTML iframe sandbox with scripts allowed but no same-origin access.

package/skills/pmx-canvas/references/installing-pmx-canvas.md

@@ -4,7 +4,7 @@ Use this reference when the `pmx-canvas` skill is installed but the `pmx-canvas`
 
 ## Prerequisites and version
 
-The examples pin **PMX Canvas 0.11.0**, which requires **Bun >=1.4.4** even when
+The examples pin **PMX Canvas 0.12.1**, which requires **Bun >=1.4.4** even when
 installed through npm: the CLI runs through Bun, not Node. Check `bun --version`
 first. If missing or older, follow the [Bun installation instructions](https://bun.sh/docs/installation)
 with the user's authorization. Ensure Bun is on the MCP host's PATH as well as the
@@ -22,11 +22,11 @@ in `SKILL.md`. Do not pair newer checkout guidance with an older runtime unknowi
 ## Install from npm
 
 ```bash
-npm install -g pmx-canvas@0.11.0
+npm install -g pmx-canvas@0.12.1
 pmx-canvas --version
 ```
 
-Without a global install, use `bunx pmx-canvas@0.11.0` in place of `pmx-canvas` in
+Without a global install, use `bunx pmx-canvas@0.12.1` in place of `pmx-canvas` in
 the commands below. Do not use unpinned `bunx pmx-canvas` for a version-specific check.
 
 ## Choose the workspace and target
@@ -96,7 +96,7 @@ discards empty env values, remove `PMX_CANVAS_URL` from its launch environment i
   "mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.11.0", "--mcp"],
+      "args": ["pmx-canvas@0.12.1", "--mcp"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
         "PMX_CANVAS_PORT": "14313",
@@ -130,9 +130,59 @@ fallback ports; do not assume the configured port is the one the MCP server boun
 
 ## Amp: connect the agent separately from the portal
 
-PMX does not ship a dedicated Amp lifecycle adapter. Amp can use the native MCP tools;
-the portal is only the human's browser UI. Configure MCP inside the orb or runner where
-Amp executes, not only on the user's laptop. Merge this into that workspace's
+PMX ships an opt-in directory plugin with board binding and receipt-based steering, or
+you can configure raw MCP for active polling. The portal is the human's browser UI;
+neither opening it nor configuring raw MCP installs the plugin. Choose one integration
+for the task rather than creating duplicate writers.
+
+### Amp plugin: bound threads
+
+When installation is requested, copy the complete installed package directory
+`node_modules/pmx-canvas/dist/amp-plugin/pmx-canvas` to the project's
+`.amp/plugins/pmx-canvas`. Inspect existing plugin files and preserve local changes;
+replacement needs owner approval. Reload Amp plugins and load the qualified
+`pmx-canvas:pmx-canvas` skill. Approve its workspace MCP command through the normal
+human trust flow, never by bypassing it. No global plugin installation is implied.
+
+Use `pmx_canvas_session { action: "open" }` to start/reconnect and verify the service,
+then `bind` with an existing explicit `boardId`. `status` reports the binding and
+shared active board; `unbind` removes only this thread's binding. Binding does not
+open a board, change sharing, or create an access-control boundary.
+
+Bound MCP tool calls route to that board with identity `amp:<thread-id>`, even when
+the human views another board or Home. Use `canvas_query` for context and full
+`canvas_node` reads for needed content. CLI calls and MCP resource reads are not
+intercepted. Do not navigate the shared workbench through bound calls, override the
+destination, or open the board to make a write work. A missing board or changed
+binding fails instead of silently targeting the visible board; a binding change
+during a turn requires a new turn.
+
+At turn start, return the supplied context token through
+`pmx_canvas_delivery { action: "receive", token }`. Reception records the delivered
+map, not full card reads, understanding or approval. For a steering token, receive it,
+read the relevant content, act, verify the result, and only then call
+`pmx_canvas_delivery { action: "acknowledge", token }`. Do not acknowledge failed or
+unverified work. Uncertain sends require human resolution, not blind retries or
+deleting the transport journal.
+
+Addressed steering can start an idle thread or queue into a busy turn only while
+the plugin executor is awake. It does not wake a sleeping orb or hold a keep-alive
+lease. A raw MCP polling test does not prove this native delivery path.
+
+**Context ranking** and **Jev advice** are separate opt-ins, both off by default.
+Their Amp commands require separate human confirmation for the current binding and
+disclose data sent to TypeSafe Jev and the invoking thread's inference billing.
+Ranking reorders optional summaries; advice suggests formats or review order without
+creating output or verifying work. One consent never enables the other. Rebinding
+does not carry either consent. Respect deterministic fallback and report it rather
+than retrying with another provider. See the
+[plugin contract](https://github.com/pskoett/pmx-canvas/blob/main/docs/amp-plugin.md)
+for request fields, retry identities and native acceptance limits.
+
+### Raw MCP: active polling
+
+Configure MCP inside the orb or runner where Amp executes, not only on the user's
+laptop. Merge this into that workspace's
 `.amp/settings.json`, preserving other settings (Amp does not use the generic `.mcp.json`):
 
 ```json
@@ -140,7 +190,7 @@ Amp executes, not only on the user's laptop. Merge this into that workspace's
   "amp.mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.11.0", "--mcp"],
+      "args": ["pmx-canvas@0.12.1", "--mcp"],
       "includeTools": ["canvas_*"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
@@ -174,7 +224,7 @@ The agent must not run this approval itself or move the command to global settin
 `--mcp-config` to bypass workspace trust. Approval authorizes execution of this MCP
 command; it is not a new Canvas import consent or permission to mutate arbitrary boards.
 After approval, reload MCP connections (`reload_mcp` in Amp) and require `connected`.
-Discover `canvas` tools with `tool_search`; the full unfiltered 0.11.0 server has 25 tools,
+Discover `canvas` tools with `tool_search`; the full unfiltered 0.12.1 server has 25 tools,
 including `canvas_help`. If still absent, inspect the server status, command/PATH and target instead
 of reinstalling blindly. See [Amp MCP documentation](https://ampcode.com/docs/customize/mcp).
 
@@ -194,8 +244,8 @@ of reinstalling blindly. See [Amp MCP documentation](https://ampcode.com/docs/cu
 4. Verify the visible result in the browser before marking the message delivered for
    that consumer. A subsequent claim should omit it. Detach only test-owned sessions.
 
-This proves an **active agent can poll and act**, not automatic wake-up of an idle Amp
-thread, background polling, or automatic agent launch for imports. An MCP connection
+This raw-MCP check proves an **active agent can poll and act**, not automatic wake-up
+of an idle Amp thread, background polling, or automatic agent launch for imports. An MCP connection
 does not install a steering pump. Only configure a pump/host integration when requested;
 its startup backlog rules are in the main skill. Tool discovery and resource reads also
 do not establish Amp support for native MCP Skills-extension discovery or activation.