pmx-canvas 0.12.0 → 0.12.1

package/.github/extensions/pmx-canvas/extension.mjs

@@ -50,6 +50,7 @@ function delay(ms) {
 async function fetchJson(baseUrl, path, options = {}) {
     const response = await fetch(`${baseUrl}${path}`, {
         ...options,
+        headers: { "x-pmx-source": "copilot", ...options.headers },
         signal: AbortSignal.timeout(options.timeoutMs ?? HEALTH_TIMEOUT_MS),
     });
     if (!response.ok) {

package/.github/extensions/pmx-canvas/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.12.0"
+  "version": "0.12.1"
 }

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.12.1] - 2026-11-05
+
+### Fixed
+
+- Copilot adapter actions are attributed to Copilot instead of appearing as a separate API writer.
+- Bundled agent guidance now describes current delivery, consent, live-card, batch and tour behavior accurately.
+- Web artifact setup stops on dependency-install failures and shows the package-manager error.
+- Reduced disk writes when creating a workspace database without weakening save durability.
+
+### Internal
+
+- Browser CI uses Ubuntu 24.04, which the installed Playwright version supports.
+- Editor-history checks now verify that the history panel opens before continuing.
+
 ## [0.12.0] - 2026-10-31
 
 ### Added

package/dist/amp-plugin/pmx-canvas/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.12.0"
+  "version": "0.12.1"
 }

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/SKILL.md

@@ -15,11 +15,13 @@ Use this entry guide for every task, then load only the task-specific reference
 
 ## Runtime and skill identity
 
-PMX Canvas 0.12.0 requires **Bun >=1.4.4**, including npm installations. Check `bun --version`
+PMX Canvas 0.12.1 requires **Bun >=1.4.4**, including npm installations. Check `bun --version`
 and the MCP host's PATH. Install or configure only when requested. Read
 [Installing PMX Canvas](references/installing-pmx-canvas.md) for pinned setup and managed services.
 In Amp, portal access and native MCP discovery are separate; workspace commands need human trust
-approval. A connected MCP server does not install an idle-thread wake-up adapter.
+approval. Raw MCP does not install an idle-thread wake-up adapter. The opt-in
+[Amp plugin](references/installing-pmx-canvas.md#amp-plugin-bound-threads) adds board binding,
+receipt-based delivery and steering while its executor is awake.
 
 After upgrading, run `pmx-canvas skills sync --check` first (exit 1 means drift). Review whole-tree
 differences and preserve local edits. `skills sync --yes` replaces all drifted installed copies
@@ -60,12 +62,15 @@ See [workspace targeting](references/workbench-workflows.md#workspace-safety) fo
 
 ## Read, then act on the intended board
 
-1. Reuse one visible workbench. Call `canvas_board { action: "list" }` before board work.
-   Home (`activeBoardId: null`) is not an empty library. Open the intended board when active-board
-   work requires it and verify the returned `activeBoardId`. Opening changes the shared workbench.
+1. With the Amp plugin, inspect `pmx_canvas_session { action: "status" }` and use its bound
+   board without opening it. Use routed MCP query tools, not resource reads or CLI calls;
+   those bypass binding. Without a binding, reuse one visible workbench and call
+   `canvas_board { action: "list" }` before board work.
+   Home (`activeBoardId: null`) is not an empty library. For unbound active-board work, open
+   the intended board and verify `activeBoardId`. Opening changes the shared workbench.
    Library discovery and supported background creation need no switch.
-2. Read `canvas://context?consumer=<stable-unique-id>` or
-   `canvas_query { action: "context", consumer: "<stable-unique-id>" }`. Use a stable consumer
+2. Read `canvas_query { action: "context", consumer: "<stable-unique-id>" }`, or, without
+   a binding, `canvas://context?consumer=<stable-unique-id>`. Use a stable consumer
    only when durable deltas are wanted; omit it for a fresh read. Follow `cursor.next` as `since`
    to finish a budgeted brief. Budgets are UTF-16 code units, not tokens.
 3. The brief is a map of summaries, pins and relations, not a full-content read. Pull needed cards
@@ -77,7 +82,9 @@ See [workspace targeting](references/workbench-workflows.md#workspace-safety) fo
    marks prove delivery, not understanding or approval. Refresh stale context after interruptions.
 5. Snapshot before clear, restore or major rearrangement. Confirm destructive changes first.
 6. Signal meaningful mutations with `canvas_intent { action: "signal", ttlMs: 30000, ... }`,
-   then pass the returned `intent.id` as `intentId`. Only an explicit intent gives a pre-write
+   then pass the returned `intent.id` on a supported node/edge/group mutation. For batches,
+   link the supported leaf's `args.intentId`, never the batch envelope. Quiet expiry proceeds
+   unlinked; a human veto refuses the linked write. Only an explicit intent gives a pre-write
    veto window; automatic ghosts are not a substitute. Skip signals for trivial/high-frequency churn.
 7. Reuse an adapter-owned session. Inspect `canvas_ax_state { action: "presence" }` first.
    Copilot's `copilot` identity is not a new task-named agent. Put task descriptions in `detail`.
@@ -86,7 +93,9 @@ See [workspace targeting](references/workbench-workflows.md#workspace-safety) fo
    Inspect rendered content, sizes and relations before reporting success. A stored payload or
    `panned: true` is not evidence of what the human sees.
 9. Read steering as your own consumer, act, verify the visible result, then mark that message
-   delivered. Remove owned temporary nodes when the task calls for leaving the board unchanged.
+   delivered. With the Amp plugin, first `receive` the supplied token, then `acknowledge` only
+   after verified action; receiving a context map is not a full card read or completion.
+   Remove owned temporary nodes when the task calls for leaving the board unchanged.
 
 When authoring a board, inspect its `readmeNodeId`. If absent, choose/create a concise Markdown
 introduction and designate it through `canvas_board update`. Preserve an existing human choice.
@@ -121,6 +130,9 @@ Standalone tools: `canvas_batch`, `canvas_pin_nodes`, `canvas_screenshot`, `canv
 `canvas_ingest_activity`, `canvas_invoke_command`, `canvas_help`. Do not invent removed legacy tools.
 See [full API reference](references/full-reference.md) for payloads and
 [composite action lists](references/workbench-workflows.md#current-mcp-composites).
+Before interpreting a reply, read [MCP result shapes](references/full-reference.md#mcp-results-and-cancellation-010):
+registry results use `result.data`, help uses `result`, and direct tools use their own schema.
+Do not apply one unwrap rule to every tool; retain partial-write and error information.
 
 ## Choose the lightest useful surface
 
@@ -138,6 +150,9 @@ For ordinary work planning, deliberately create `status` cards with `data.workSt
 session, task or approval; do not generate a card for every work event. Connect useful steps,
 alternatives and loops with existing relations. Humans can Edit/Save/Cancel inside each card.
 See [work planning](references/full-reference.md#task-plan-with-dependencies) for examples.
+To display an existing task instead, create a [live task card](references/full-reference.md#live-task-cards)
+with `data.workItemId`. Its task-derived fields are read-only and its task owner is immutable;
+update the underlying task, not the presentation. Deleting the card does not cancel the task.
 
 Read [HTML primitives](references/html-primitives.md) before choosing their payloads or copy/export
 flows, [AX control surfaces](references/ax-html-control-surface.md) before authoring interactive
@@ -213,8 +228,9 @@ otherwise recheck before reuse.
 Read [Tours and recording](references/tours-and-recording.md) before authoring, navigating or
 capturing a tour. `set-tour` persists stops; deterministic capture uses the same model in its own
 viewer. Rendering and free pan are local, but human Next/Back and agent `tour-go` share a cursor
-and affect presenting viewers; `tour-exit` exits everywhere. Optional presenter fences reject stale
-commands, not other viewers. A superseded result is not applied navigation.
+for the target board and affect its presenting viewers; `tour-exit` exits those viewers.
+Optional presenter fences reject stale commands and presenter-bearing background calls,
+not other viewers. A superseded result is not applied navigation.
 
 Use the [browser workflow reference](references/workbench-workflows.md#browser-workflows) for
 keyboard, groups, menus, reconnect/draft behavior and host-local theme overrides. Use the picker

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/evals/evals.json

@@ -564,17 +564,17 @@
     {
       "id": 44,
       "name": "presenter-superseded-is-not-applied-navigation",
-      "prompt": "In a disposable board, verify optional presenter ordering. 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. 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 and stale activation return ok:true,superseded:true without a navigation event or cursor change. Independent and unfenced controls still apply. Explains that the fence orders requests, does not grant authority or isolate viewers, and that SDK exit returns void while fenced go may return superseded:true. Does not count eval definitions as executed evidence.",
+      "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 and activation, rather than treating ok:true as applied navigation",
+          "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 exercises independent-document and unfenced calls without inventing mandatory presenter credentials",
+          "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"
         },
         {
@@ -587,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": [
         {
@@ -753,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": [
         {
@@ -1081,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/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/references/full-reference.md

@@ -624,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.
@@ -650,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)
 
@@ -663,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` /
@@ -1186,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
@@ -1645,6 +1675,30 @@ Without `data.workState`, status cards retain their phase/tool display. Session-
 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>"}}
+```
+
+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
 
 Understand a codebase by visualizing file relationships:

package/dist/amp-plugin/pmx-canvas/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.12.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.12.0
+npm install -g pmx-canvas@0.12.1
 pmx-canvas --version
 ```
 
-Without a global install, use `bunx pmx-canvas@0.12.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.12.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.12.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.12.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.

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/references/tours-and-recording.md

@@ -32,8 +32,8 @@ Open `/workbench?present=1` for chrome-free viewing. Right, Down, or Space advan
 goes back; Escape or **Exit presentation** exits. Right-drag pans and interrupts an ongoing
 transition without editing cards. Stops do not auto-advance. A missing node target reports an
 error and may be skipped. Camera rendering and free pan are viewer-local, but human Back/Next
-and arrow keys advance the shared cursor for all presenting viewers; Exit leaves presentation
-everywhere. `present: false` does not isolate navigation from another presenting viewer.
+and arrow keys advance the target board's shared cursor for its presenting viewers; Exit leaves
+presentation for those viewers. `present: false` does not isolate viewers of the same board.
 Deterministic capture uses its own viewer and ignores live navigation. Recording hides the exit control.
 
 Tours are board-scoped, persist with that board and its snapshots, participate in undo, and clear
@@ -44,11 +44,15 @@ setting or reading it.
 
 ## Drive a tour
 
-The server holds one in-memory tour cursor, tied to the board it was started on (a tour on another board replaces it). `canvas_view { action: "tour-go", stop: 0 }`
-starts presenting in open workbenches; `step: "next" | "previous"` moves relative to wherever the
-audience is (a human's arrow keys move the same cursor) and clamps at the ends. Pass
+The server keeps board-local in-memory tour cursors, not one workspace-wide cursor.
+`canvas_view { action: "tour-go", stop: 0 }` starts presenting in workbenches showing the
+target board; `step: "next" | "previous"` moves relative to that board's cursor
+(a human's arrow keys move the same cursor) and clamps at the ends. Pass
 `present: false` to move only viewers already presenting. `canvas_view { action: "tour-exit" }`
-leaves presentation everywhere. `get-tour` reports `position` (the current stop, or null).
+exits presentation on the target board. `get-tour` reports `position` (the current stop, or null).
+Bound background calls do not navigate the human's visible board. Cursors are not durable:
+tour edits or activation changes can invalidate them, so read `get-tour` rather than assuming
+a previous stop survives reopening a board.
 
 `canvas_view { action: "move", nodeId | rect | viewport, duration, easing, padding, pullback }`
 eases the camera without a tour. Outside a presentation the end camera becomes the board
@@ -68,8 +72,10 @@ Use a distinct `clientId` per document, an increasing positive safe-integer `int
 and the actual server activation's epoch and nonnegative safe-integer generation. Ordinary
 agent calls may omit this object. It orders requests; it is not authorization or viewer isolation.
 
-A stale activation or duplicate/older intent returns `{ ok: true, superseded: true }` with no
-navigation event or cursor change. Do not claim navigation from `ok: true` alone. Applied results
+A stale activation, duplicate/older intent, or presenter-bearing call on a background board
+returns `{ ok: true, superseded: true }` with no navigation event or cursor change.
+Ordinary unfenced background calls still target their own board, not the visible one.
+Do not claim navigation from `ok: true` alone. Applied results
 and events carry `catalogEpoch`, `boardGeneration` and `sequence`; presenter-aware clients use
 these to reject stale acknowledgements and events. A structurally valid newer intent is claimed
 before resolving the stop, so even a missing newer stop supersedes older requests.

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/references/workbench-workflows.md

@@ -104,7 +104,10 @@ For pinned installation, MCP configuration, managed services, and disposable ver
 read [Installing PMX Canvas](installing-pmx-canvas.md).
 In Amp, follow that reference's [Amp setup](installing-pmx-canvas.md#amp-connect-the-agent-separately-from-the-portal):
 portal access is separate from native MCP, workspace commands need human trust approval,
-and a connected MCP server does not install an idle-thread wake-up adapter.
+and raw MCP does not install an idle-thread wake-up adapter. The opt-in
+[Amp plugin](installing-pmx-canvas.md#amp-plugin-bound-threads) adds board binding and
+receipt-based steering while its executor is awake. Use routed query tools for bound
+context; CLI calls and resource reads are not intercepted.
 
 ## Reading bundled skills over MCP
 
@@ -130,8 +133,10 @@ the served catalog is a startup snapshot. Local mirrors still use `skills sync`
    Use a disposable consumer when testing released guidance without permission to replace
    owned mirrors. After an authorized upgrade, restart the matching HTTP daemon and `--mcp`
    processes; Bun does not hot-reload a running process.
-1. **Open or focus the workbench before mutating.** Reuse one visible canvas surface for the
-   session.
+1. **Check the session's target before mutating.** With the Amp plugin, read
+   `pmx_canvas_session { action: "status" }` and keep using its bound board without opening
+   it or navigating the shared workbench. Without a binding, reuse one visible canvas surface
+   and open the intended board when active-board work requires it.
 2. **Verify workspace identity at the actual target.** Read `GET /health` at the URL your
    CLI/MCP/browser is using; its `workspace` must equal the intended canonical absolute root.
    `pmx-canvas serve status --port=<port>` checks the local listener on that port, not an
@@ -149,6 +154,9 @@ the served catalog is a startup snapshot. Local mirrors still use `skills sync`
    human watches intent form and can veto mid-thought. Skip it only for trivial in-place tweaks or
    high-frequency batch churn. The default TTL (~8s) expires between agent turns: signal with
    `ttlMs: 30000` and settle by passing `intentId` on the mutation in the same or next call.
+   Link only supported node/edge/group mutations; in a batch put the ID on the leaf's
+   `args.intentId`, not the envelope. Quiet expiry proceeds unlinked; a human veto refuses
+   the linked write. An intent is not permission or a batch-wide gate.
    Since 0.4.5, an agent mutation WITHOUT a signal still shows a server-synthesized **auto-ghost**
    (rendered lighter — dimmer, dotted, no veto — and settled instantly). That is a visibility
    floor, not a replacement: only an explicit signal gives the human a real pre-mutation veto

package/docs/agent-plugin.md

@@ -90,6 +90,12 @@ The adapter uses the session's **working directory**, not Copilot's session-stat
 `workspacePath` or the plugin installation directory. Boards remain in the project's
 `.pmx-canvas/canvas.db`.
 
+Copilot's native adapter labels its HTTP operations as `copilot`, including AX writes.
+To use that same writer identity over MCP, configure the host's MCP process with
+`PMX_CANVAS_AGENT_SOURCE=copilot`; the portable launcher forwards it to the runtime.
+It does not assume every plugin client is Copilot. Give independent clients their own
+source label, or use an explicit `agentId` on their operations, to keep them distinct.
+
 The daemon belongs to the workspace and stays running when one client closes, so closing
 the native panel cannot break another MCP client. Stop it explicitly from the project:
 

package/docs/amp-plugin.md

@@ -122,10 +122,9 @@ launcher. `PMX_CANVAS_URL` is an explicit target, not a fallback. An unavailable
 fails rather than starting a second server. Version mismatch or a missing/unknown bundle stamp
 also fails, including at MCP connection and subsequent requests.
 
-**Release limitation:** the published `0.11.0` runtime lacks the required bundle stamp. This
-foundation is verified with the locally packed package, not registry-only startup. A compatible
-release is required before recommending the registry fallback. No publication is part of this
-increment.
+The `0.12.0` package includes the required bundle stamp and generated Amp plugin. The older
+`0.11.0` runtime lacks that stamp and cannot serve this integration. Verify the actual runtime
+version and stamp on each connection; a local build alone does not prove registry startup.
 
 Amp supplies the Portal URL and access controls. Open does not change sharing or multiplayer.