pmx-canvas 0.11.0 → 0.12.0

package/docs/RELEASE.md

@@ -25,8 +25,11 @@ single source of truth for the release dance — see also
 
 ## Pre-flight gates
 
-Run these locally before tagging. They mirror what `publish.yml`
-re-runs in CI; a failure here means the publish workflow will also fail.
+Run these locally before tagging. `test.yml` runs the client and browser suites.
+For tag releases, `publish.yml` requires a successful Test run for the exact
+tagged commit, then reruns build, typecheck, unit tests and release smoke.
+Publish does not rerun the client or browser suites. A green remote run does
+not clear an unresolved local failure.
 
 ```bash
 bun install --frozen-lockfile
@@ -35,7 +38,7 @@ bun run build
 bun test tests/unit         # 200+ tests, all green
 bun run test:web-canvas     # Playwright E2E, all green
 bun run test:e2e-cli        # fresh-workspace CLI eval
-bun run release:check       # bundles + lints
+bun run release:check       # build + typecheck + lint + unit + client + browser tests
 bun run release:smoke       # packs + boots from a clean dir
 bun run pack:dry-run        # confirms the tarball shape
 ```
@@ -179,8 +182,10 @@ git push origin v0.1.6
 It will:
 
 1. Verify the tag matches `package.json` version.
-2. Re-run typecheck / build / unit / E2E / pack.
-3. `npm publish --access public --provenance` using the `NPM_TOKEN`
+2. Require a successful Test workflow run for the exact tagged commit.
+3. Re-run build, typecheck, unit tests and release smoke (pack and clean-consumer checks).
+   Browser E2E is covered by Test, not rerun by Publish.
+4. `npm publish --access public --provenance` using the `NPM_TOKEN`
    secret. Provenance attestations are signed via sigstore and visible
    on the npm package page.
 
@@ -203,24 +208,26 @@ Every release since 0.3.0 has been retested against **stale** skill mirrors:
 consumer workspaces (e.g. `personalclaude`) carry copies of the pmx-canvas
 skills under `.github/`, `.codex/`, `.claude/`, and `.agents/`, and testers
 repeatedly had to sync them mid-cycle before results were trustworthy. After
-publishing, update the installed package in the consumer workspace and re-sync
-its four mirrors from `<global npm root>/pmx-canvas/skills/` so the first test
-pass runs against the released skills, not the previous version's guidance.
+publishing, update the installed package in the consumer workspace and check
+its installed skill copies against that package before trusting skill-guided results.
 
-This is now one command in the consumer workspace (added post-0.4.3):
+Start with drift detection, which does not overwrite local changes:
 
 ```bash
-pmx-canvas skills sync --yes     # refreshes every INSTALLED skill copy from the package
 pmx-canvas skills sync --check   # drift detection only (exit 1 when stale)
 ```
 
 It discovers the skill copies already installed in the workspace (whatever
-agent layout owns them — no host list is assumed) and compares/replaces
+agent layout owns them — no host list is assumed) and compares
 **whole trees** — `references/`, `evals/`, fixtures — not `SKILL.md` hashes
 alone (the 0.3.x–0.4.x cycles repeatedly hit drift where the hash matched but
-supporting files were stale). Also re-run
-`pmx-canvas copilot install-extension --yes` in repos that use the Copilot
-adapter so the panel picks up new open-URL behavior.
+supporting files were stale). Review the differences and preserve local edits.
+Only run `pmx-canvas skills sync --yes` after the owner approves replacing the
+affected copies; it replaces all drifted installed copies of `pmx-canvas`,
+`pmx-canvas-testing` and `pmx-canvas-orchestration`. For a clean release-guidance
+check without that approval, use a disposable consumer workspace.
+Updating the Copilot adapter with `pmx-canvas copilot install-extension --yes`
+likewise requires approval to replace its installed files.
 
 ## GitHub release
 

package/docs/agent-plugin.md

@@ -1,5 +1,9 @@
 # PMX Canvas agent plugin
 
+PMX Canvas is a collaborative canvas where you and your AI agent collect evidence, analyze findings,
+and develop ideas together. Pin material as context for your agent, then ask it to add findings,
+comparisons, or diagrams to the board for you to review, present, and build on.
+
 `plugins/pmx-canvas/` is a self-contained [Agent Plugins 1.0](https://agent-plugins.org/)
 package. It contains only PMX Canvas: the portable MCP server configuration and a native
 canvas extension for the GitHub Copilot app. It does not include frame integrations,
@@ -97,6 +101,14 @@ Use the exact version from `runtime.json` and the port from the panel's `status`
 `PMX_CANVAS_PORT` selects a preferred port; `PMX_CANVAS_URL` targets an existing server.
 An explicit URL that fails ownership checks is reported rather than silently replaced.
 
+## Context and steering delivery
+
+The Copilot adapter reads AX context and marks steering delivery with the same `copilot`
+consumer identity. Its next context excludes instructions and pickups already delivered to
+Copilot. A different consumer can still see them pending; that is not a failed Copilot receipt.
+The delivery mark records handoff to the host, not proof that the requested action succeeded.
+This is separate from the Amp plugin's explicit context receipt and action acknowledgment.
+
 ## Package maintenance
 
 The plugin's adapter copies are generated from `.github/extensions/pmx-canvas/`:
@@ -116,8 +128,10 @@ The portable root contains `plugin.json`, `mcp.json`, `start-mcp.mjs`, `tools.js
 `runtime.json`, and license notices for the bundled dependencies. Copilot auto-discovers the native adapter at
 `com.github.copilot/extensions/pmx-canvas/extension.mjs`.
 
-The marketplace preview is copied from `docs/screenshot.png` to `assets/preview.png` on each
-plugin build. The manifest's `extensions.com.github.copilot.logo` points to that packaged PNG.
+The plugin logo is copied from `docs/design/plugin-logo.png` to `assets/preview.png` on each
+plugin build. It is a 512 × 512 export of the PMX Focus Field brand mark, not a canvas screenshot.
+The marketplace requires that image path; the manifest's `extensions.com.github.copilot.logo`
+points to it. The editable source and regeneration command are in [the design guide](design.md#plugin-logo).
 
 Publishing a repository package does not register it in a curated marketplace or make it
 Featured in the Copilot app. Those are separate submission and review steps.

package/docs/amp-plugin.md

@@ -0,0 +1,271 @@
+# Amp plugin, context and steering
+
+The Wave 5 Amp plugin opens the workspace Canvas and binds each Amp thread to an existing board.
+Bound MCP calls read and edit that board while the human views another board or Home. Bound
+threads receive context at turn start and addressed steering can wake an idle thread.
+People can set a self-reported cursor name in Canvas. Optional Jev context ranking and on-demand
+format/review advice are off by default, with separate human consent.
+
+## Install locally
+
+Requires Bun >=1.4.4 and Amp with directory-plugin skills. The tested baseline is
+`0.0.1793119929-g574f34` (2026-10-27). Source: `plugins/amp/`; build: `bun run build:plugin`.
+The npm package includes the generated directory at `dist/amp-plugin/pmx-canvas`.
+
+Copy that complete directory to your project's `.amp/plugins/pmx-canvas`. For an installed
+package, copy from `node_modules/pmx-canvas/dist/amp-plugin/pmx-canvas`. Do not overwrite an
+existing plugin or locally edited skills: inspect the differences and approve replacement first.
+Reload Amp plugins. Nothing is installed in a personal or workspace-global plugin repository.
+
+Amp registers `pmx-canvas:pmx-canvas`, `pmx-canvas:pmx-canvas-testing` and
+`pmx-canvas:pmx-canvas-orchestration`. They are generated copies of the existing PMX skills,
+not separate authoring sources. The main skill bundles MCP and gates its tools until loaded.
+Approve the workspace MCP command through Amp's normal trust flow. A Portal alone does not
+prove native MCP discovery. `canvas_connect_workspace` accepts only this executor's directory.
+
+## Commands and session tool
+
+| Command | Effect |
+|---|---|
+| PMX Canvas: Open | Start/reconnect, verify workspace, version and bundle stamp, then open the Amp Portal. |
+| PMX Canvas: Bind | Choose an existing board for this thread, without opening or editing it. |
+| PMX Canvas: Status | Read service identity, binding, whether its board exists, and the shared active board. Does not start a service. |
+| PMX Canvas: Unbind | Remove only this thread's binding. Works while the server is down. |
+| PMX Canvas: Resolve pending steering | Inspect uncertain sends, then explicitly retry or dismiss with human confirmation. |
+| PMX Canvas: Context ranking | Enable Jev after human confirmation for this binding, or turn it off. |
+| PMX Canvas: Jev advice | Separately enable on-demand format/review advice after human confirmation, or turn it off. |
+
+Agents use `pmx_canvas_session` with `action: "open" | "bind" | "status" | "unbind"`.
+Bind requires an explicit `boardId`. Invocation thread identity comes from Amp, never model input.
+
+Each binding stores workspace, thread, board and stable consumer ID `amp:<thread-id>` in
+`.pmx-canvas/amp-bindings/<thread-id>.json`. Keep this runtime directory out of Git. Separate files
+prevent one thread's update from overwriting another's. Bindings survive plugin reload and
+service restart. Missing boards are reported, never silently rebound. Board navigation and
+moving cards do not change a binding. Unbind is idempotent.
+Each binding also has an incarnation ID. Repeating Bind to the same board keeps it; unbinding
+and binding again invalidates old receipts, even for the same board. Installations created
+before this delivery increment must Unbind, then Bind again.
+
+**Bindings route PMX MCP tool calls.** The plugin supplies `targetBoardId` and the authenticated
+`amp:<thread-id>` identity before invocation. Conflicting destinations and nested overrides fail;
+missing/deleted boards never fall back to the visible board. Batches, delayed operations, approval
+waits, undo history and file watchers retain their board ownership across human navigation.
+An active turn retains the binding it started with or first used. If that binding changes or
+disappears, subsequent Canvas calls fail until a new turn starts, including after plugin reload.
+
+Open still displays the shared workbench. There is no private per-thread browser. Bound calls
+cannot navigate the shared workbench, restore the workspace backup, or control/capture its shared
+WebView. Board deletion remains an unscoped human library action. Tour/camera commands affect
+only their target board; they reach the browser only when
+that board is visible. CLI calls and MCP resource reads are **not** intercepted by the plugin;
+use routed MCP query tools for bound-board context.
+
+A binding is routing, not an access-control or privacy boundary. Board-owned metadata updates
+must name the bound board. Catalog reads, board creation, board pins, workspace settings and
+knowledge categories keep their workspace scope and existing permission checks. AX timeline,
+evidence and addressed steering/delivery are workspace-wide; a steering wait can wake on a message
+sent from another board, while its `pendingActivity` contains only the bound board's work/gates.
+Cross-board relation targets remain explicit.
+
+## Automatic delivery
+
+At `agent.start`, the plugin prepares a context map with a 12,000-character JSON budget.
+Preparation records no reads and advances no cursor. The agent returns the supplied token to
+`pmx_canvas_delivery { action: "receive", token }` to confirm reception. This records the
+delivered map and complete links, never full card-content reads. Omitted or clipped changes
+remain beyond the saved cursor. Pull a card with the existing MCP tools to read its full content.
+The plugin keeps its own per-thread, per-board cursor, separate from other readers' cursors.
+
+While the plugin executor is awake, it checks persisted bindings every five seconds for steering
+addressed exactly to `amp:<thread-id>`. Broadcasts and messages for other consumers are excluded
+before the queue limit. It appends the instruction through Amp's native thread API: an idle
+thread starts a turn; a busy thread receives queued steering, which Amp can inject into the
+current turn after a tool returns without another `agent.start`. This does not wake a sleeping
+orb, hold a keep-alive lease, or create a scheduler. Scanning resumes when the plugin runs again.
+The pump scans successive pages of 50 messages so unacknowledged instructions cannot hide later
+ones. Instructions over 32,000 characters are not clipped or sent: they appear as `blocked-size`
+in Resolve pending steering, where a human can dismiss them and send a shorter instruction.
+
+The agent first receives the steering token, then acts and verifies the result, then calls
+`pmx_canvas_delivery { action: "acknowledge", token }`. Host acceptance, reception and action
+acknowledgment are separate states. An action that failed or was not verified must not be
+acknowledged as successful. The plugin cannot itself certify the agent's work.
+
+Each thread has a SQLite transport journal beside its binding. A send is reserved durably before
+calling Amp, preventing duplicate pumps from sending the same instruction. An interrupted or
+timed-out send remains **uncertain**, not automatically retried. Reconciliation checks the last
+200 transcript messages for the exact user-message payload; finding it confirms acceptance,
+not action completion. Absence does not prove non-delivery. Status exposes pending tokens and
+polling errors; Resolve pending steering requires human confirmation because retrying an
+uncertain send can duplicate an instruction. Dismiss closes delivery without claiming success.
+Journals retain packet identities across reloads; do not delete them to retry a message.
+Receipt identities also survive Canvas's 5,000-row diagnostic retention. A retry whose original
+read has expired is refused rather than counted again; start a new turn for fresh context.
+Stop cancels receipt and acknowledgment requests before a pending discovery can initiate a write.
+
+Queued steering with an obsolete binding or completed packet is cancelled at turn start.
+Finish or dismiss pending steering before binding to another board. Unbind stops delivery;
+the human can still dismiss a pending packet after unbinding or deleting its board.
+No exactly-once action-execution guarantee is made.
+
+## Runtime boundaries
+
+The plugin reuses exact-version PMX runtime discovery and refuses a foreign workspace. Startup
+prefers the project's installed matching-version package, then the pinned registry runtime if
+the package is absent. An installed version mismatch fails instead of downloading another copy.
+In an orb it probes the actual ports returned by `amp orb services ensure`, including custom
+ports. If those services do not include Canvas, it creates a supervised Canvas service. The
+connection hint in `.pmx-canvas/amp-server.json` is revalidated against workspace health on reuse.
+It never holds an orb keep-alive lease. Outside an orb it uses the existing local PMX daemon
+launcher. `PMX_CANVAS_URL` is an explicit target, not a fallback. An unavailable explicit target
+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.
+
+Amp supplies the Portal URL and access controls. Open does not change sharing or multiplayer.
+
+## Optional context relevance
+
+**Context ranking** is off by default. Its human-only confirmation explains that your current
+prompt and optional summaries go to TypeSafe Jev through Amp, using the invoking thread's
+inference billing. Consent applies to the current thread/board binding, survives reload,
+and does not carry to a new binding. Repeating the command disables it. Session Status reports
+`contextRanking: "off" | "jev"`. Enabling cannot opt an already-started preparation into inference.
+Existing prepared packets remain byte-identical on retries. An interrupted ranking attempt is
+durably claimed: another delivery instance or a reload falls back without submitting it again.
+
+Context ranking only reorders optional summaries already admitted by the context compiler:
+`near`, `linked` and `folder`. Explicit pins, pinned boards, human instructions, changes,
+title-only discovery entries and lifecycle-qualified pins are not candidates. No new sources
+are fetched. No content is removed, no omission is hidden, and no cursor or receipt is advanced
+by ranking. Existing workspace/binding boundaries still apply; relevance is not authorization.
+The compiler's omitted content cannot be recovered by this ranker. This changes order, not
+content membership or full-content read accounting. It does not reduce the compiled brief's
+size. The ranking report adds delivery metadata, and ranking makes a separate billed inference
+request; no recall, token-saving or cost-saving claim is made.
+
+Each fresh preparation uses at most one batch of 20 questions. Inputs are bounded to 2,000
+UTF-16 units of the current prompt, 160 per title and 600 per summary; serialized decision
+state cannot exceed 24,000 units. Later candidates keep their original positions. Scores use
+three levels: unrelated, background, directly useful. Sort descending with stable ties; no
+confidence threshold is treated as proof. The delivery includes the model version, ranked and
+eligible counts, clipping flag, or fallback reason. Missing API, unavailable provider, invalid
+answers, oversized input or a three-second timeout retain deterministic order, with no retry
+or substitute provider. The host API cannot cancel a timed-out inference call; late results
+are ignored and may still be billed. Production enablement is never changed by evaluations.
+
+## On-demand output and review advice
+
+`pmx_canvas_advice` operates only on facts the agent supplies. **Jev advice** requires its own
+human confirmation per binding; enabling Context ranking does not enable advice. Status reports
+`jevAdvice: "off" | "jev"`. Consent survives reload, but rebinding disables it. The confirmation
+discloses the supplied text, TypeSafe provider and invoking thread's inference billing.
+
+Every request requires `requestId` (1–100 characters), `task` (1–2,000), and `action`:
+
+- `representation`: requires `summary` (up to 12,000 characters); optional `explicitFormat`
+  (1–80) preserves the user's exact choice without inference, even when advice is off or the
+  format is unsupported. Otherwise Jev suggests Markdown, Mermaid, graph, json-render, HTML,
+  image or diff. The deterministic fallback is Markdown.
+- `review`: requires 1–20 `changes`, each with a unique `id` (1–160), `title` (up to 160)
+  and `summary` (up to 600). Scores order changes by review urgency with stable ties. Every ID
+  is retained; the fallback preserves input order. A single change needs no inference.
+
+Lengths are UTF-16 units. Serialized decision state is limited to 24,000 units, with one
+three-second inference attempt per logical request. Invalid results, missing providers and
+timeouts return an explicit fallback, never another provider or automatic retry. Reuse the
+same `requestId` and identical input to retry, including across plugin reloads. Reusing an ID
+with different input fails. An interrupted or concurrent retry freezes the durable fallback
+rather than risking another billed call. Completed responses are immutable. Turning advice
+off affects new requests; a retry can still return its previously completed result.
+
+Advice creates no output, fetches no source, records no read and verifies no work. The main
+agent must create and verify the actual result. A review priority is not a correctness or
+security verdict. Responses report `mode` (`explicit`, `jev`, or `fallback`), the selected
+format or ordered IDs, and the actual model or fallback reason.
+
+### Reproduce the native decision evaluation
+
+In a source checkout, temporarily register `scripts/eval-amp-context.ts` through a root plugin
+file in `.amp/plugins/` that re-exports its default export. Load that file with Amp's plugin
+loader and call its `evaluate_canvas_context` tool. Remove the temporary plugin and reload
+afterward. This development harness is not bundled into the production plugin.
+
+The harness sends four fixed fictional pairs in both candidate orders, never workspace data.
+Expected ordering is authored in `tests/fixtures/context-relevance.ts`, independently of model
+scores. It compares against the unchanged compiler order, checks unchanged contents and pins,
+and writes model version, input size and elapsed time to `.amp/in/artifacts/jev-context-*.json`.
+It includes semantic relevance and misleading source instructions. A passing small diagnostic
+set is not evidence of general task improvement or prompt-injection immunity. The decision
+API exposes no billed cost, so the report does not invent one.
+
+The same harness exposes `evaluate_canvas_advice`: four fictional representation cases and
+two review pairs in both orders, with expectations in `tests/fixtures/jev-advice.ts`. It compares
+against Markdown and unchanged review order, checks unchanged inputs, and saves
+`.amp/in/artifacts/jev-advice-*.json`. Neither evaluator changes production consent. These
+diagnostics do not establish rendered output quality or replace native human opt-in acceptance.
+
+## Collaboration and names
+
+Use Amp's existing thread access, multiplayer and Portal controls to share. Canvas adds no
+account, guest token or permission picker. Amp's [Portal access documentation](https://ampcode.com/docs/orbs/portals#access-and-lifecycle)
+describes the current controls and workspace restrictions. The installed CLI also exposes
+`amp orb portal access`; its presence is not evidence of an external guest completing the flow.
+Sharing a Portal exposes its port, including other boards and APIs available there, not just
+the current board URL. Only share a workspace whose contents are appropriate for the audience.
+Public Portal access does not grant access to the Amp thread or its review tools.
+
+Open **Your name** at the end of the Canvas top bar. Enter up to 40 characters and choose
+**Save name**. Other participants see the name on your cursor. Cancel, Escape or blank input
+keeps the existing name. The name is saved in this browser when storage is available and
+survives reload and reconnect. Renaming does not change the visitor's tab ID; two people may
+choose the same name without merging their presence. A name is self-reported, not verified
+identity, attribution to an Amp account, or an access grant. Naming makes no access-control
+request and does not change thread or Portal sharing.
+
+This control is available in the HTTP workbench, including an Amp Portal, not an MCP-hosted
+workbench or an agent-view tab. An initial `?name=` still works; saving a name removes that
+parameter so a reload cannot overwrite the saved choice.
+
+**Acceptance boundary:** two browsers inside the owning orb can verify Canvas collaboration,
+but Amp routes those Portal requests directly to the service without external authentication.
+That does not verify an outside guest's sign-in, public access, or revocation. Test those
+separately with fictional data and the owner's approved sharing scope.
+
+## Verification
+
+`bun test tests/unit/amp-plugin.test.ts` checks bindings and workspace safety through the
+registered session tool. `bun run typecheck` checks against the pinned published Amp types.
+`tests/unit/amp-delivery.test.ts` checks receipt accounting, clipped context, wrong recipients,
+competing pumps, interrupted sends/receipts and restart against real Canvas HTTP and SQLite.
+`tests/unit/boards-api.test.ts` checks concurrent HTTP routing, restart persistence, nested
+identity, waits and refusal paths. `tests/e2e/boards.pw.ts` checks visible-board isolation,
+reconnect and opening the populated target board. These do not substitute for native hooks.
+After `bun run build:plugin`, verify a fresh copied package with `amp plugins list` and
+`amp skill info pmx-canvas:pmx-canvas`, then reload the actual host and test discovery and
+`pmx_canvas_session`. Test native MCP trust separately from an SDK handshake.
+
+Native acceptance includes open, bind, reload, status, unbind, a foreign-workspace refusal,
+two independent thread bindings, persisted boards after service restart, and a rendered Portal.
+Actual orb pause/resume and a second live Amp thread must be reported separately from simulated
+thread contexts or process restarts. Do not call the entire Wave 5 integration verified from
+these foundation checks.
+Delivery acceptance also requires an actually idle thread to wake from addressed Canvas steering,
+receive its context, edit the bound board, show the rendered result and acknowledge only afterward.
+
+Native acceptance on Amp `0.0.1793405518-gc59f01` verified idle wake, busy delivery into the
+current turn, bound MCP routing through `code_exec`, rendered edits before acknowledgment,
+receipt retries, reload and end-of-turn journal cleanup. Wrong-recipient steering stayed pending.
+Obsolete queued-packet cancellation and sleeping-orb resume were not exercised; startup
+cancellation guards have unit coverage, not native cancellation acceptance.
+
+Independent-orb Jev diagnostics on `jev-1.14.0` passed 8/8 context cases against 4/8 unchanged
+order, and two advice runs each passed 8/8 against a 3/8 deterministic baseline. These are small
+fictional diagnostics, not general quality, latency or cost benchmarks. Native disabled advice,
+explicit format, receipt idempotency and reload were exercised. Human-confirmed enablement,
+enabled next-turn ranking and native advice revocation/rebinding remain acceptance checks.

package/docs/cli.md

@@ -333,6 +333,24 @@ pmx-canvas batch --file ./canvas-ops.json
 See [HTTP API → batch](http-api.md#batch-operations) for the operation
 schema; the same JSON works for the CLI batch file.
 
+Authored [work cards](node-types.md#work-cards) use structured `data` through batch:
+
+```bash
+pmx-canvas batch --json '[{"op":"node.add","args":{"type":"status","title":"Verify","data":{"workState":"todo","detail":"Run browser checks"}}}]'
+pmx-canvas batch --json '[{"op":"node.update","args":{"id":"<card-id>","data":{"workState":"done","progress":null}}}]'
+```
+
+The ordinary `node add --data` flag is for graph series, not general node data.
+
+Present an existing task read-only on its active board:
+
+```bash
+pmx-canvas batch --json '[{"op":"node.add","args":{"type":"status","data":{"workItemId":"<task-id>"}}}]'
+```
+
+Do not send title, detail, work state or progress; these follow the task. Removing the card
+does not cancel work. Update the task through `ax work update`, not a card patch.
+
 ## Web artifacts
 
 ```bash
@@ -405,6 +423,8 @@ pmx-canvas board pin <board-id> --reason "Q4 rests on it" # join the agent's wor
 pmx-canvas board unpin <board-id>
 pmx-canvas board from <source-id> "Follow-up" --preview
 pmx-canvas board from <source-id> "Follow-up" --nodes id1,id2 --readme --structure
+pmx-canvas board move-selection <source-id> "Follow-up" --nodes id1,id2 --revision 42 --request move-123 --preview
+pmx-canvas board move-selection <source-id> "Follow-up" --nodes id1,id2 --revision 42 --request move-123
 ```
 
 Commands write to the board open in the workbench. `board open` switches the
@@ -418,6 +438,15 @@ cards are retained automatically. `--readme` carries the designated README. The
 does not inherit pins, AX state, or mutation history. Its `previousBoardId`
 records the source board.
 
+`board move-selection` moves the original cards instead. Read `board get <source-id>`
+for `contentRevision`, pass it as `--revision`, and preview first. Group selections
+include descendants. Keep `--request` and all other inputs unchanged when retrying an
+interrupted commit; a recorded success returns the same destination after restart.
+The operation leaves a portal but does not open the destination. It preserves pins,
+relations and review/read history, and refuses the whole selection if bindings cannot
+move safely. Pre-move Undo/Redo clears; old snapshots remain inspectable but cannot
+restore across the move. See the [move contract](http-api.md#move-original-cards-to-a-new-board).
+
 ## Connected memory
 
 ```bash
@@ -643,9 +672,19 @@ reports annotation targets and bounds; it does not describe whether the human
 drew an arrow, line, circle, or other shape. Inspect `.annotation-layer path` or
 take a screenshot when the drawn form matters.
 
-Humans draw with the rail's Annotate popover (pen / text) and remove marks with its eraser.
-If an agent already knows the annotation ID from context, it can remove it through
-MCP with `canvas_view { action: "remove-annotation", id }`.
+Humans and agents share pen, text and whole-mark erasing. CLI agents use the
+existing batch command:
+
+```bash
+pmx-canvas batch --json '[{"op":"annotation.add","args":{"id":"question-b","type":"text","points":[{"x":160,"y":320}],"text":"Use option B?"}}]'
+pmx-canvas batch --json '[{"op":"annotation.remove","args":{"id":"question-b"}}]'
+```
+
+For freehand ink, omit `type` and supply at least two points in canvas world
+coordinates. [Annotation defaults and retry rules](http-api.md#annotations) are
+shared across transports. Layout/context reads include text notes as well as mark
+IDs and bounds. The human can answer in the external agent host's composer;
+neither Sessions nor PMX's composer is required.
 
 ## When to reach for the CLI
 

package/docs/design/GuestName.dc.html

@@ -0,0 +1,50 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Guest name: existing presence, self-reported names</title>
+<script src="./support.js"></script>
+</head>
+<body>
+<x-dc>
+<helmet><style>
+body { margin:0; background:#081524; }
+.states { display:flex; gap:24px; padding:24px; font:13px/1.4 'IBM Plex Sans',sans-serif; }
+.state { width:600px; height:600px; background:var(--bg); color:var(--text); }
+.dark { --bg:#081524; --panel:#0b192b; --soft:#0f1d31; --line:#1b2c44; --text:#e6eef7; --muted:#8ea3bd; --accent:#4BBCFF; }
+.light { --bg:#f7f8fa; --panel:#ffffff; --soft:#eff2f6; --line:#d5dce5; --text:#172b44; --muted:#536a83; --accent:#1A7ABF; }
+.bar { height:44px; display:flex; align-items:center; gap:8px; padding:0 14px; background:var(--soft); border-bottom:1px solid var(--line); }
+.board { flex:1; } .context { color:var(--muted); font-size:12px; }
+.initial { width:28px; height:28px; border:1px solid var(--line); border-radius:50%; background:var(--soft); color:var(--text); font:600 12px 'IBM Plex Sans',sans-serif; }
+.dialog { box-sizing:border-box; width:440px; margin:90px auto 0; padding:14px; background:var(--panel); border:1px solid var(--line); border-radius:12px; display:flex; flex-direction:column; gap:10px; box-shadow:0 18px 60px #0003; }
+.title { font-weight:600; } .description { color:var(--muted); font-size:12px; }
+input { box-sizing:border-box; width:100%; padding:8px 10px; border:1px solid var(--accent); border-radius:8px; background:var(--bg); color:var(--text); font:13px/1.4 'IBM Plex Mono',monospace; }
+.actions { display:flex; justify-content:flex-end; gap:8px; }
+.actions button { min-height:36px; padding:8px 14px; border:1px solid var(--line); border-radius:7px; background:var(--soft); color:var(--text); font:600 12px 'IBM Plex Sans',sans-serif; }
+.actions .save { background:var(--accent); border-color:var(--accent); color:var(--bg); }
+.cursor { margin:55px 0 0 60px; color:var(--muted); } .cursor span { background:var(--soft); padding:3px 6px; border:1px solid var(--line); border-radius:4px; font-size:11px; }
+.note { padding:20px; color:var(--muted); font-size:12px; }
+</style></helmet>
+<div class="states">
+  <section class="state dark">
+    <div class="bar"><span class="board">Field notes ▾</span><span class="context">Nothing in context</span><span>⋯</span><button class="initial" aria-label="Your name: guest-4a8c">G</button></div>
+    <div class="dialog" role="dialog" aria-label="Your name on this canvas">
+      <div class="title">Your name on this canvas</div>
+      <div class="description">Shown on your cursor. Self-reported, not a verified identity or an access grant. Saved in this browser.</div>
+      <input aria-label="Your name on this canvas" placeholder="e.g. Alex" maxlength="40" value="Alex">
+      <div class="actions"><button>Cancel</button><button class="save">Save name</button></div>
+    </div>
+    <div class="note">Optional entry. Escape or Cancel keeps the current name. Up to 40 characters. No sharing or permission controls.</div>
+  </section>
+  <section class="state light">
+    <div class="bar"><span class="board">Field notes ▾</span><span class="context">Nothing in context</span><span>⋯</span><button class="initial" aria-label="Your name: Sam">S</button></div>
+    <div class="cursor">➤ <span>Alex</span></div>
+    <div class="note">The other browser sees Alex on the existing cursor tag. A rename keeps the same visitor ID; equal names never combine visitors. The 28px button stays at the end of the bar at 600, 1024 and 1920px.</div>
+  </section>
+</div>
+</x-dc>
+<script type="text/x-dc" data-dc-script data-props='{"$preview":{"width":1272,"height":648}}'>
+class Component extends DCLogic { renderVals() { return {}; } }
+</script>
+</body>
+</html>

package/docs/design/PluginLogo.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="14" fill="#081524"/>
+  <rect x="8" y="8" width="48" height="48" rx="7" fill="none" stroke="#4BBCFF" stroke-width="2.2" opacity="0.35"/>
+  <rect x="16" y="16" width="32" height="32" rx="5" fill="none" stroke="#4BBCFF" stroke-width="2.2" opacity="0.6"/>
+  <rect x="24" y="24" width="16" height="16" rx="3" fill="none" stroke="#4BBCFF" stroke-width="2.2"/>
+  <rect x="29" y="29" width="6" height="6" rx="1" fill="#4BBCFF"/>
+</svg>

package/docs/design/WorkCards.dc.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Work cards · in-card editing</title><script src="./support.js"></script></head>
+<body><x-dc><helmet>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap">
+<style>
+body{margin:0}.work-design{box-sizing:border-box;width:1440px;min-height:980px;padding:48px;background:#081524;color:#e6eef7;font:13px/1.6 'IBM Plex Sans',sans-serif}.work-design h1{font-size:28px;margin:0}.work-design p{color:#8ea3bd}.work-design .examples{display:flex;gap:40px;align-items:flex-start;margin:32px 0}.work-design .card{box-sizing:border-box;width:360px;background:#0f1d31;border:1px solid #1b2c44;border-radius:10px;box-shadow:0 1px 2px #0006;padding:16px}.work-design h2{font-size:15px;margin:0 0 16px}.work-design .state{font-weight:600}.work-design .detail{white-space:pre-wrap}.work-design label{display:flex;flex-direction:column;gap:4px;margin:12px 0}.work-design input,.work-design select,.work-design textarea,.work-design button{box-sizing:border-box;font:inherit;color:inherit;background:#081524;border:1px solid #1b2c44;border-radius:6px;padding:8px}.work-design textarea{min-height:80px}.work-design footer{display:flex;justify-content:flex-end;gap:8px;margin-top:16px}.work-design .primary{background:#4BBCFF;color:#081524}.work-design .states{display:flex;gap:24px}.work-design .blocked{color:#f4c542}.work-design .done{color:#2fd07f}.work-design small{color:#8ea3bd}.work-design .error{color:#f4c542}
+</style></helmet>
+<main class="work-design">
+<h1>Work cards · edit inside the card</h1>
+<p>Option A selected 2026-10-27. Ordinary status nodes with an explicitly authored work state. No session or execution controls.</p>
+<div class="examples">
+<section><h2>Read</h2><article class="card"><h2>3. Verify</h2><div class="state">◐ In progress</div><p class="detail">Run the browser checks.</p><small>60% complete</small><footer><button>Edit</button></footer></article></section>
+<section><h2>Edit / create</h2><article class="card"><h2>3. Verify</h2><form><label>Title<input value="3. Verify"></label><label>Work state<select><option>In progress</option><option>To do</option><option>Blocked</option><option>Done</option><option>Cancelled</option></select></label><label>Detail<textarea>Run the browser checks.</textarea></label><label>Progress (%) · optional<input type="number" min="0" max="100" value="60"></label><footer><button type="button">Cancel</button><button type="button" class="primary">Save</button></footer></form></article></section>
+<section><h2>Refused save</h2><article class="card"><h2>Draft stays editable</h2><p class="error">Could not save. Your draft is still here. Check the connection or whether the card changed.</p><p>Save is disabled while a request is pending. A stale content revision is refused, never silently overwritten.</p></article></section>
+</div>
+<div class="states"><span>○ To do</span><span>◐ In progress</span><span class="blocked">⧗ Blocked</span><span class="done">✓ Done</span><span>× Cancelled</span></div>
+<p>New work card in the canvas menu creates a status node in To do. Edit opens this form. The card grows locally while editing; saved geometry stays unchanged. Cancel discards the draft. Escape cancels inside the form. Saving changes authored data only, never creates a session or task.</p>
+<p>Work state is independent of progress. Done does not invent a percentage. Progress can be cleared. Agent activity remains violet and context remains blue; an authored In progress state is neutral.</p>
+<p>At 600 px, the same card and form fit the canvas. Focus view uses the same controls. Existing phase/tool status indicators keep their non-work behavior.</p>
+<h2>Read-only live cards · selected 2026-10-27</h2>
+<p>In the session task row, Show on board creates a separate live presentation. Once present, the action reads Show card and focuses it. No conversion of ordinary planning cards.</p>
+<div class="examples">
+<section><h2>Session task row</h2><article class="card"><h2>Verify the change</h2><p>Run the browser checks.</p><div class="state">◐ In progress</div><footer><button>Show on board</button></footer></article></section>
+<section><h2>Live presentation</h2><article class="card"><h2>Verify the change</h2><small>↗ Live task · reviewer · Read-only</small><div class="state">◐ In progress</div><p>Run the browser checks.</p></article></section>
+<section><h2>Missing reference</h2><article class="card"><h2>Task unavailable</h2><div class="blocked">⚠ Task unavailable</div><p>The linked task is no longer on this board.</p><small>Read-only · removing this card does not cancel work.</small></article></section>
+</div>
+<p>Live title, detail, state and attribution follow the task record. No Edit, progress percentage or approval controls. Ending a session keeps the task and its presentation; deleting a presentation never cancels the task. Focus mode uses the same read-only content.</p>
+<h2>Move to new board · Wave 5</h2>
+<p>Selection bar: Move to new board (icon + hover hint at narrow widths). Group menu: Move to new board. Use the existing text-prompt modal shell, 540 px maximum width, 16 px viewport margin, 14 px padding, 8 px gaps, 17 px heading. At 600 px the same 540 px dialog scrolls inside the viewport; at 1920 px it stays centered and bounded. Keep the canvas behind it.</p>
+<div class="examples">
+<section><h2>Name</h2><article class="card" style="width:400px"><h2>Move to new board</h2><p>Move the original cards, including group contents. Leave a portal on this board.</p><label>New board name<input value="Follow-up"></label><footer><button>Cancel</button><button class="primary">Preview move</button></footer></article></section>
+<section><h2>Review</h2><article class="card" style="width:400px"><h2>Move to new board</h2><label>New board name<input value="Follow-up" readonly></label><p>4 cards · 2 pinned · 3 affected boards</p><p>README moves with the cards. Live tasks keep their original owner. Content, relations and review history are preserved; moving does not validate or read content.</p><p class="error">⚠ History boundary: pre-move Undo/Redo is cleared on affected boards. Older snapshots remain inspectable, but cannot be restored across the move.</p><p>Board-space annotations stay here. The new board opens after the move.</p><footer><button>Cancel</button><button class="primary">Move and open</button></footer></article></section>
+<section><h2>Blocked / uncertain reply</h2><article class="card" style="width:400px"><h2>Move to new board</h2><p class="error">⚠ Cannot move this selection</p><p>live-chart: finish the active stream before moving this card.</p><p>No cards moved. Close, resolve the listed bindings and preview again.</p><footer><button>Close</button></footer><hr><p>If the reply is interrupted, keep the original request and show Retry move. Never silently create a second board. A board switch or closing the dialog cancels the delayed navigation, not a committed move.</p></article></section>
+</div>
+<p>Before moving, save or cancel local card drafts. Capture the board and selection when opening. Preview is read-only; commit rechecks current state. No copy checkbox or reverse move. Escape closes the dialog; pending requests do not steal later navigation. Buttons use the existing palette accent; warnings use amber with a glyph and words.</p>
+</main></x-dc>
+<script type="text/x-dc" data-dc-script data-props='{"$preview":{"width":1440,"height":2400}}'>class Component extends DCLogic { renderVals() { return {}; } }</script>
+</body></html>

package/docs/design/canvas.json

@@ -2,6 +2,20 @@
   "v": 3,
   "attachments": {},
   "boards": {
+    "GuestName.dc.html": {
+      "h": 648,
+      "title": "Guest name entry and existing presence",
+      "w": 1272,
+      "x": 9120,
+      "y": 5960
+    },
+    "WorkCards.dc.html": {
+      "h": 2400,
+      "title": "Work cards — in-card editing (selected 2026-10-27)",
+      "w": 1440,
+      "x": 7600,
+      "y": 5960
+    },
     "AgentContext.dc.html": {
       "h": 1500,
       "title": "What the agent did with context",
@@ -377,6 +391,8 @@
     "Relations.dc.html",
     "Flows.dc.html",
     "Uses.dc.html",
+    "WorkCards.dc.html",
+    "GuestName.dc.html",
     "Vision.dc.html",
     "AgentContext.dc.html",
     "Themes.dc.html",