pmx-canvas 0.11.0 → 0.12.1

package/docs/design.md

@@ -21,6 +21,33 @@ contract and the schedule.
 3. Apply the [Principles](#principles), above all the fixed meaning colours.
 4. Meet the [Definition of done](#definition-of-done-for-any-design-work) before calling it done.
 
+## Plugin logo
+
+The plugin uses the existing Focus Field brand mark, matching the canvas favicon:
+blue (`#4BBCFF`) concentric rounded squares on Harbor navy (`#081524`). The source is
+[`PluginLogo.svg`](design/PluginLogo.svg), exported at 512 × 512 to
+[`plugin-logo.png`](design/plugin-logo.png). The plugin build copies that PNG to the
+marketplace-required `assets/preview.png` path referenced by `extensions.com.github.copilot.logo`.
+README screenshots remain unchanged. This packages existing branding; it does not change canvas
+styling or establish which image the Copilot plugin-list row displays.
+
+To regenerate the PNG from the repository root with the existing Playwright installation:
+
+```bash
+bun -e '
+import { chromium } from "@playwright/test";
+const browser = await chromium.launch({ headless: false });
+try {
+  const page = await browser.newPage({ viewport: { width: 512, height: 512 }, deviceScaleFactor: 1 });
+  await page.setContent(`<body style="margin:0">${await Bun.file("docs/design/PluginLogo.svg").text()}</body>`);
+  await page.locator("svg").screenshot({ path: "docs/design/plugin-logo.png", omitBackground: true });
+} finally {
+  await browser.close();
+}
+'
+bun run build:plugin
+```
+
 ## Token system
 
 Drawn on [`TokenSystem.dc.html`](design/TokenSystem.dc.html); per-theme meaning colours on
@@ -121,6 +148,7 @@ the same change.
 | [`Themes.dc.html`](design/Themes.dc.html) | Meaning colours across all nine themes, proposed names | 0 |
 | [`Chrome.dc.html`](design/Chrome.dc.html) | Rail at 690 px, node header (expand and context pin always visible, the rest under ⋯), bounded reference footer, section headings, floating chrome | 0 |
 | [`EmptyState.dc.html`](design/EmptyState.dc.html) | Empty board: Drop files here, Paste a link, Start a note with collaboration guidance, then a separate agent-first path | 0 |
+| [`GuestName.dc.html`](design/GuestName.dc.html) | Optional Your name button, existing text dialog and named collaborator cursor. Self-reported names only; sharing stays in Amp. | 5, Amp collaboration |
 | [`Context.dc.html`](design/Context.dc.html) | Nodes in context: every state, the count chip, the command bar | 0–1 |
 | [`NearPin.dc.html`](design/NearPin.dc.html) | Near a pin: the dotted “near” chip on a pinned node's unpinned neighbours, tethers on hover, the moment of change, combinations, 600 px; ships with the brief carrying neighbours (title + summary, reason “near <pin>”) | 1 |
 | [`ContextChip.dc.html`](design/ContextChip.dc.html), [`ContextChip600.dc.html`](design/ContextChip600.dc.html) | The one context chip (decided with the maintainer 2026-10-07: placement, near muted, quiet empty state, agent-pin dots, “N in context” at 600 px): top bar, right, replacing the floating ContextPinBar and the ContextBudget meter; at rest for cards, near, boards, agent-only pins, nothing pinned; opened into Cards (full, × unpin, clear all), Near (derived, title + summary, no ×, Pin to promote) and Boards (read state, × unpin). **A pinned board travels as a map** (decided 2026-10-07): folder, README summary, each pinned card's title + summary, links and backlinks; the agent pulls a card or board in full itself, so the chip shows no full / summary / not-sent state. **A cost, not a budget** (decided with the maintainer 2026-10-08): the chip shows what the brief costs as ≈ tokens, with no meter, share or clipped state; when the host reports its agent's token usage the panel names that count too (“Copilot’s whole context holds 42.8k tokens”). The brief's size limit stays internal as a page size. At rest it is the summary, always visible and right-aligned in the top bar at every width; the details open only on click. At ≤ 760 px the summary is “N in context” with no token text, and the bar gives way in this order: session id and counts; Export, Present, zoom and fit fold into ⋯; agent chip to its avatar, Start agent session to its icon; the board name truncates — the dot, board pin, summary and ⋯ never collapse. Harbor and Daylight, 600 px. Supersedes the chip wording on Context, NearPin and BoardPins | 1 (slices 4b, 5b) |
@@ -154,6 +182,17 @@ With the beta on, the existing Start agent session action sits below that guidan
 The existing panel, type and colour tokens stay; actions form one readable column, and
 short windows scroll the guide rather than cutting off either starting path.
 
+**Guest name entry (2026-10-31).** A neutral 28px initial button at the end of the top bar
+opens the existing text prompt, with its existing 440px maximum width, padding and actions.
+The caption explains that a name is self-reported and grants no access. Entry is optional;
+Cancel and Escape keep the current name. Save trims the name to the existing 40-character
+presence limit and remembers it in this browser, without changing the tab's presence ID.
+The existing cursor tags identify collaborators. No people panel or sharing controls are
+added. The button remains visible when the bar folds at narrow widths, including Home;
+MCP-hosted workbenches and agent-view tabs do not report human presence or offer this control.
+The drawing refines the minimal dialog option, retaining actual text-prompt geometry rather
+than the generated concept's smaller panel. Amp controls access to the port, not one board.
+
 **Canvas mouse gestures (owner decision, 2026-10-19).** Right-click on empty canvas
 opens the existing creation menu on release. Holding the right button and moving more
 than 5 screen pixels pans; releasing after a drag never opens a menu, even when the
@@ -320,8 +359,9 @@ Standalone viewers and HTML/artifact viewers retain their existing load path; no
   working set (README and pinned cards in full, on every board); there is no separate card
   pin, which would only send the portal's summary while this board is open. Every other
   card keeps its card pin.
-- **Relations are the edge layer, not node types.** Design work adds no node type;
-  the vision's own `ask` node (move 3) is separate.
+- **Relations are the edge layer, not node types.** Design work adds no node type.
+  The general `ask` node is deferred by the Wave 5 decision below; ordinary planning questions
+  and alternatives use existing cards.
 - **Any size, from a side pane to a full window.** The workbench lives in narrow agent-host
   panes, the resizable side browser in the Claude desktop app, and full browser windows. Every
   drawing shows the narrow end (600 px) and a full window before it is built, and the build
@@ -362,15 +402,71 @@ vision's target designs, not screenshots of the shipped workbench. The Wave-3
 foundation does not implement every interaction pictured in them. It provides
 per-board vocabularies, semantic inks, separate endpoint slots, authored reasons,
 evidence/source/use queries, downstream review qualification and view-only
-highlights. Parallel-pair count badges, cycle/affected counts, the compact inline
-edge editor, amber stale-lineage strokes and the Show lineage / Show on canvas
-actions are not implemented. The current editor is a context menu with text
-dialogs; source changes appear as review-due card footers, not recoloured edges.
-Group drill-in with breadcrumbs and outside endpoint stubs belongs to Wave 5.
+highlights. Wave 5 adds parallel-pair counts, dependency cycle/affected counts,
+the compact inline edge editor and Show lineage / Show on canvas. A cycle count
+means cyclic dependency clusters, not every illustrated route through a graph.
+Source warnings reuse lifecycle qualification and appear as amber glyphs and words
+beside the semantic label, rather than replacing the relation ink with amber.
+Group drill-in adds breadcrumbs and outside endpoint stubs on the same board.
+The boundary is neutral, reserving blue for context pins; hidden viewers stay mounted
+so navigation does not discard drafts. These are scoped deviations from the older
+drawings' blue boundary and amber relation strokes, not new relation meanings.
 The sketches' suggested-link Accept/Dismiss treatment was superseded by the
 2026-10-10 direct-edit decision recorded above; it is not a pending acceptance
 workflow. A demo of existing features must not be used to claim full sketch parity.
 
+**Wave 5 decision, 2026-10-27.** The owner reaffirmed Uses' Agent flow, Dependencies and
+Decision drawings; Flows remains the reference for group navigation. Humans and agents author ordinary cards and
+relations, showing work deliberately rather than automatically creating a card for every task.
+Illustrated loops describe a plan; they do not execute it. Planning works without Sessions.
+An explicitly linked session-task card presents the existing record's live state; starting a
+session does not convert the plan. Native-agent approvals stay in the host, PMX session controls
+remain separate, and explicit/automatic ghost feedback is unchanged. The general `ask` card
+is deferred.
+
+Agents also use the existing pen, text and whole-mark eraser layer for questions and
+emphasis. This adds no new visual controls or mark style. Humans can answer in their
+external agent host's composer; PMX's composer and Sessions are optional.
+
+**Work-card authoring, selected 2026-10-27:** [WorkCards](design/WorkCards.dc.html)
+adds option A's in-card editor to the approved Uses work steps. Title, work state,
+detail and optional progress are authored node data. Edit grows the card locally;
+Save/Cancel do not persist that temporary geometry. Drafts, refused saves and pending
+saves survive opening and closing focus mode. Generic phase/tool status cards
+remain unchanged.
+
+**Read-only live cards, selected 2026-10-27:** the same WorkCards artboard adds a
+**Show on board** action to task rows, becoming **Show card** when presented. A live
+card shows task state, detail and attribution with a **Read-only** caption, no Edit,
+progress or approval controls. Missing references show **Task unavailable**. Ordinary
+plans are not converted, ending a session preserves cards, and deleting a card does not cancel work.
+Existing selective board copies detach the live reference and task attribution, producing
+an independent authored card. They do not copy tasks or create cross-board live links.
+
+**Move to new board** is the agreed label for multi-selection and the group's **⋯** menu:
+move the cards, preserve identity/history/relations and leave a portal. No reverse move or
+inline-board operation in this wave. Opening a group within the current board is navigation
+only, with breadcrumbs and outside endpoints, not a new board. These decisions supersede the
+earlier automatic work-card and make/inline-board wording. Implementation and technical
+checkpoints live in [plan 020](plans/plan-020-wave-5-work-planning.md).
+[WorkCards](design/WorkCards.dc.html) now draws name, preview, refusal and interrupted-reply
+states using the existing modal shell. Preview names pins, README, live owners and the
+Undo/snapshot boundary. Save or cancel local card drafts before moving. A late reply never
+overrides newer navigation; a retry uses the original request ID.
+
+**Amp plugin added to Wave 5, 2026-10-27.** The owner added the native Canvas plugin
+described in [this discussion](https://ampcode.com/threads/T-01a17d25-69d9-7693-986a-f3991de6a346).
+It hosts Canvas through Amp's Portal and connects context, steering, creation, sharing and
+collaboration to Amp threads. Jev optionally ranks context, chooses output representation and
+prioritizes review; the integration works without it. Amp retains execution, credentials and
+native permissions. The owner simplified sharing to **use Amp's existing sharing; let the guest
+enter their name**. Add identification through existing canvas presence, not a separate guest
+permission system, share server or custom expiry/revocation. A name is self-reported and grants
+no additional access. Participation follows Amp's existing access model; do not promise anonymous
+or board-only access that it does not provide. General hosted accounts and organization roles
+remain later work. Draw the missing name-entry and identified-guest states here before UI
+implementation; packaging, reliability gates and acceptance are in plan 020, Slice 4.
+
 | Wave | Vision | Function (build) | Design (proposal boards) | Done when |
 |---|---|---|---|---|
 | **0. Foundation**: shipped in 0.8.0; remaining foundation gaps ship with plan 019 step 3 | Moves 5, 9, 10 | Bundle Plex; controls inherit the font; type/radius/shadow tokens; meaning tokens per theme; theme renames (`dark` → Harbor, `light` → Daylight, neutral; no aliases); pin style that survives selection and attention; violet header bar replaces amber halos and focus fields | Today / Proposed, Tokens, Themes, Rail and node header, Nodes in context | No control renders in a fallback font; token test passes for all nine themes; reference cases pass at 600, 1024 and 1920 px; demo board regenerated |
@@ -378,7 +474,7 @@ workflow. A demo of existing features must not be used to claim full sketch pari
 | **2. Connected memory views** — implemented, verification gates apply | Moves 0, 14 | One board/card projection for Home, links/backlinks, brief discovery and `canvas://graph{?focus,depth}`; saved wiki ID bindings, direct cross-board card edges, previous-board chains, persisted Map positions | Home Map, Home Graph (deviations below) | Map and Graph are generated from the library; orphans visible; works at 600 px and in a full window |
 | **3. Relations layer** | Moves 0, 1, 13 | Edge `reason` and an open `kind` with a per-board vocabulary; relations carried in the brief's text form; "derived from" with staleness from provenance and recipes; relation queries for the inspector | Relations, Lineage, One relation layer | Hovering a node explains each link; a changed source turns downstream nodes amber; the agent's brief includes relations |
 | **4. Frame host and viewers** | Moves 5, 9 | One frame host passing the full theme tokens; json-render defaults to the canvas theme with an opt-out for design experiments; native proportional canvas at every zoom | Node types 1–3, Zoom | Viewers use the canvas palette and fill their authored space; approaching a viewer mounts it automatically and retains its state when panning away; no alternate grid or lifetime preview cap |
-| **5. Agent output and groups as pages** | Moves 3, 0 | Work items, gates and asks as nodes; make board / inline board; opening a group keeps its outside links | One relation layer (agent flow), Lineage (open a group) | Agent output is styled by the same shell and tokens; a group opened as a board shows its outside stubs |
+| **5. Work planning, group navigation and Amp integration** | Moves 3, 0; native Amp plugin | Deliberate work cards and relations; optional live task views; Move to new board with a portal; group drill-in; Amp Portal/context/steering plugin with optional Jev; native Amp sharing plus guest names; no reverse move | Uses (agent flow, dependencies, decisions), Flows (open a group), Relations; move/plugin states to be drawn | Human and agent can plan without Sessions; loops stay inert; drill-in keeps outside stubs; moves preserve identity/audit; native Amp sharing and guest identification pass; shared shell/tokens and plan 020 checks pass |
 | **Later: hosted version** | Part 4 (moved from Part 3, 2026-10-19) | Read-only link, comments, second writer, accounts and roles; org → team → personal scopes with configurable categories and per-user pins; built once for the ChatGPT Sites and later Cloudflare editions | HomeTeam is the earlier two-root look ahead; updated scope/category drawings are required before building, retaining explicit publication and locked cards for unreadable boards | Exports and shared views inherit the tokens; a viewer sees the same meaning colours; nothing personal reaches a wider audience without explicit publication |
 
 **Folders and portals (decided 2026-10-06).** Home uses folders as the visible hierarchy (where a
@@ -486,6 +582,13 @@ scroll references instead of moving the canvas. No graph data is collapsed or re
 Reading expanded Markdown, closing it or following a link without input preserves
 the exact source and revision. Pending real edits still finish before navigation.
 
+**Expanded-editor refusals (2026-10-31).** The existing attention toast, history
+panel and Updates tab render inside the expanded dialog so they remain in its
+keyboard focus loop, above its content and below blocking dialogs. Their placement,
+dimensions and palette stay unchanged. Opening history dismisses the toast, and
+queued notices stay in history without covering the open panel. Closing history
+returns focus to Updates; reopening it never closes the editor or discards its draft.
+
 **Owner-guide fixes (2026-10-20).** The same reference list follows cards into focus
 mode, above the provenance strip, capped at 132 screen pixels there. It retains every
 target without displacing the document. A refused Markdown save keeps the reader and

package/docs/evals/agents-md-sections.md

@@ -0,0 +1,38 @@
+# Eval: does each AGENTS.md section change what agents do?
+
+Run 2026-10-26. Rerun it whenever a section is added or questioned; delete sections that change
+nothing, rewrite sections that change behaviour in the wrong direction.
+
+## Method
+
+1. Copy `AGENTS.md` into neutrally named directories: the full file (control) and one copy per
+   treatment with a single `##` section removed.
+2. Start three subagents per variant. Each reads only its copy and writes the work plan it would
+   follow for two fixed requests, without implementing:
+   - "Wiki aliases inside fenced code blocks get turned into links on Markdown cards. Fix it."
+   - "Add a lastSavedAt field to GET /health."
+3. Score each plan on observable choices: skills named, plan mode, subagents, and the core
+   verification steps (failing test first, `pmx_canvas_health`, live check, docs and changelog).
+
+Plans, not implementations: this measures what the instructions steer, which is what a section
+can change. Subagents may also see the real repository guidance, which would shrink differences.
+
+## Results (n = 3 per variant)
+
+| Variant | Pipeline skills named | Plan mode (request 1 / 2) | Plans using a subagent | Core verification |
+|---|---|---|---|---|
+| Full file | 3/3 | 2/3 · 3/3 | 5/6 | 3/3 |
+| Without Agent Skill Pipeline | 0/3 | 3/3 · 3/3 | 3/6 | 3/3 |
+| Without Workflow Orchestration | 3/3 | 0/3 · 0/3 | 1/6 | 3/3 |
+
+`bun run acceptance` appeared in 2/3, 0/3 and 2/3 plans respectively; with n = 3 that is not
+distinguishable from noise.
+
+## Decisions
+
+- **Workflow Orchestration: deleted.** Its only effect was plan mode and subagents for a one-file
+  fix and a one-field change, which Amp's own guidance and Core Principles 1 and 4 already govern.
+  Verification was identical without it.
+- **Agent Skill Pipeline: kept, corrected.** Removing it drops the owner's pipeline skills from
+  every plan, so it is load-bearing. It wrongly said the skills exist only in gitignored local
+  trees; they are global user skills, available in every orb.

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,
@@ -300,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}`.
@@ -558,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
@@ -591,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
@@ -634,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
@@ -757,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
 
@@ -830,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
@@ -944,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}'
@@ -1200,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
@@ -1521,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" \
@@ -1533,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
@@ -378,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` |
@@ -388,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,
@@ -416,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
@@ -521,6 +551,17 @@ 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
@@ -813,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" }`