pmx-canvas 0.10.0 → 0.12.0

package/dist/types/shared/ax-surface-protocol.d.ts

@@ -16,12 +16,11 @@ export declare const AX_SURFACE_ACK_SOURCE = "pmx-canvas-ax-ack";
 export declare const HTML_SURFACE_PUSH_SOURCE = "pmx-canvas-html-node";
 /** Tab-local JSON viewer state handoff, independent of AX capabilities. */
 export declare const JSON_VIEWER_STATE_SOURCE = "pmx-canvas-json-state";
-/** Ext-app boot beacon: the iframe's scripts executed (WebKit watchdog liveness). */
-export declare const EXT_APP_BOOT_BEACON_SOURCE = "pmx-canvas-ext-app-alive";
-/**
- * Parent→ext-app paint probe (Finding N): the parent asks the app document to
- * answer with a double-rAF `paint-tick` beacon. A frame whose rendering
- * pipeline is live answers within a frame or two; silence past the timeout is
- * the paint-fail signal that drives the recovery ladder.
- */
-export declare const EXT_APP_PAINT_PROBE_SOURCE = "pmx-canvas-ext-app-paint-probe";
+/** MCP apps share their window channel with an SDK JSON-RPC transport. */
+export declare const MCP_SURFACE_METHOD = "notifications/pmx/surface";
+export declare function surfaceNotification(params: Record<string, unknown>): {
+    jsonrpc: "2.0";
+    method: string;
+    params: Record<string, unknown>;
+};
+export declare function readSurfaceNotification(message: unknown): unknown;

package/dist/types/shared/human-presence.d.ts

@@ -22,6 +22,7 @@ export interface HumanPresence {
 export interface HumanPresenceSnapshot {
     humans: HumanPresence[];
 }
+export declare const HUMAN_NAME_MAX_LENGTH = 40;
 /** A tab that stops reporting is gone after this. */
 export declare const HUMAN_PRESENCE_TTL_MS = 30000;
 /** A grab the tab stops renewing (crash, tab closed mid-drag) releases after this. */

package/dist/types/shared/lifecycle-status.d.ts

@@ -19,6 +19,8 @@ export interface LifecycleQualification {
     contentChangedAt: string | null;
     /** The revisions a validating reviewer must have inspected, qualified by source relation. */
     observations: Record<string, number | null>;
+    /** Warnings keyed by the same qualified source identity as observations. */
+    sourceWarnings?: Record<string, string[]>;
     sources: SourceQualification[];
     relevance: 'card-pinned' | 'board-pinned' | 'not-selected';
 }

package/dist/types/shared/tour.d.ts

@@ -81,6 +81,14 @@ export declare const tourSchema: z.ZodObject<{
         pullback: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/** Latest intent from one document, scoped to the server's board activation. */
+export declare const tourPresenterSchema: z.ZodObject<{
+    clientId: z.ZodString;
+    intent: z.ZodNumber;
+    catalogEpoch: z.ZodString;
+    boardGeneration: z.ZodNumber;
+}, z.core.$strip>;
+export type TourPresenter = z.infer<typeof tourPresenterSchema>;
 export type Tour = z.infer<typeof tourSchema>;
 export type TourStop = z.infer<typeof tourStopSchema>;
 export type Camera = z.infer<typeof cameraSchema>;

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/Chrome.dc.html

@@ -13,7 +13,7 @@
 body{margin:0}
 </style>
 </helmet>
-<div style="width: 1440px; height: 1000px; box-sizing: border-box; padding: 40px 48px; background: #081524; color: #e6eef7; font-family: 'IBM Plex Sans', system-ui, sans-serif; font-size: 13px; line-height: 1.5; display: grid; grid-template-columns: 500px repeat(2, minmax(0, 1fr)); gap: 40px">
+<div style="width: 1440px; height: 1360px; box-sizing: border-box; padding: 40px 48px; background: #081524; color: #e6eef7; font-family: 'IBM Plex Sans', system-ui, sans-serif; font-size: 13px; line-height: 1.5; display: grid; grid-template-columns: 500px repeat(2, minmax(0, 1fr)); gap: 40px">
 
 <section style="display: flex; flex-direction: column; gap: 14px">
 <div><h2 style="margin: 0; font-size: 15px; font-weight: 600">7 · Tool rail in a 690px-tall window</h2><p style="margin: 2px 0 0; font-size: 12px; color: #8ea3bd">20 buttons need 850px. Settings-type tools move into one menu.</p></div>
@@ -62,7 +62,7 @@ body{margin:0}
 </section>
 
 <section style="display: flex; flex-direction: column; gap: 14px">
-<div><h2 style="margin: 0; font-size: 15px; font-weight: 600">8 · Node header</h2><p style="margin: 2px 0 0; font-size: 12px; color: #8ea3bd">Expand and the context pin always show; ⋯ on hover opens the existing node menu (now with Open in new tab), and Set as README stays in the markdown footer.</p></div>
+<div><h2 style="margin: 0; font-size: 15px; font-weight: 600">8 · Node header</h2><p style="margin: 2px 0 0; font-size: 12px; color: #8ea3bd">Expand and the context pin always show; ⋯ on hover or keyboard focus opens the node menu. Set as README lives here, becoming Remove as README on the current README. Edit stays visible below Markdown.</p></div>
 
 <span style="font-size: 11px; font-weight: 500; letter-spacing: 0.06em; text-transform: uppercase; color: #6b7d94">Today</span>
 <div style="border-radius: 12px 12px 8px 8px; border: 1px solid #1b2c44; background: #0f1d31; box-shadow: 0 0 0 1px rgba(244,197,66,0.3), 0 8px 24px rgba(244,197,66,0.1); overflow: hidden">
@@ -78,7 +78,8 @@ body{margin:0}
 <div style="border-radius: 10px; border: 1px solid #1b2c44; background: #0f1d31; box-shadow: 0 1px 2px rgba(0,0,0,0.4), 0 6px 20px rgba(0,0,0,0.24); overflow: hidden">
 <div style="display: flex; align-items: center; gap: 8px; height: 36px; padding: 0 8px 0 12px; border-bottom: 1px solid #1b2c44">
 <svg width="16" height="16" viewBox="0 0 24 24" style="color: #8ea3bd; fill: none; stroke: currentColor; stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round"><path d="M6 5h12a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V7a2 2 0 0 1 2-2zM8 10h8M8 14h5"></path></svg>
-<span style="flex: 1; font-size: 12px; font-weight: 600">PMX Canvas — guided tour</span>
+<span style="flex: 1; min-width: 0; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; font-size: 12px; font-weight: 600">PMX Canvas — guided tour</span>
+<span style="flex-shrink: 0; font-size: 11px; color: #8ea3bd">README</span>
 <button aria-label="Expand (Enter)" style="width: 22px; height: 22px; border: 0; border-radius: 6px; padding: 0; background: transparent; color: #b9c6d6; display: flex; align-items: center; justify-content: center; flex-shrink: 0"><svg width="13" height="13" viewBox="0 0 24 24" style="fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round"><path d="M14 4h6v6M20 4l-7 7M10 20H4v-6M4 20l7-7"></path></svg></button>
 <button aria-label="Add to context (P)" style="width: 18px; height: 18px; box-sizing: border-box; border: 1.5px solid #6b7d94; border-radius: 999px; padding: 0; background: transparent; color: #b9c6d6; display: flex; align-items: center; justify-content: center; flex-shrink: 0"><svg width="10" height="10" viewBox="0 0 24 24" style="fill: none; stroke: currentColor; stroke-width: 2.4; stroke-linecap: round; stroke-linejoin: round"><path d="M9 4h6l-.8 5.5 2.8 3H7l2.8-3zM12 12.5V20"></path></svg></button>
 <!-- Reserve the hover-action slots: revealing More/Close must not move the pin. -->
@@ -111,7 +112,8 @@ body{margin:0}
 <div style="height: 236px; display: flex; flex-direction: column; border: 1px solid #1b2c44; border-radius: 10px; overflow: hidden; background: #0f1d31">
 <div style="flex-shrink: 0; height: 36px; display: flex; align-items: center; padding: 0 12px; border-bottom: 1px solid #1b2c44; font-size: 12px; font-weight: 600">Research index</div>
 <div style="flex: 1; min-height: 0; display: flex; flex-direction: column">
-<div style="flex: 1; min-height: 0; padding: 10px 12px; overflow: auto; font-size: 13px; color: #b9c6d6">Read the source, then follow <a href="#reference-footer" style="color: #e6eef7">the evidence</a>.<div style="margin-top: 20px; font-size: 12px; color: #8ea3bd">Set as README <span style="float: right">Edit</span></div></div>
+<div style="flex: 1; min-height: 0; padding: 10px 12px; overflow: auto; font-size: 13px; color: #b9c6d6">Read the source, then follow <a href="#reference-footer" style="color: #e6eef7">the evidence</a>.</div>
+<div style="flex-shrink: 0; border-top: 1px solid #1b2c44; padding: 6px 36px 6px 8px; text-align: right"><button style="border: 1px solid transparent; border-radius: 6px; padding: 4px 8px; background: transparent; color: #8ea3bd; font: 500 11px 'IBM Plex Sans', sans-serif">Edit</button></div>
 <div id="reference-footer" role="region" aria-label="Cross-board references" tabindex="0" style="flex-shrink: 0; max-height: min(40%, 132px); overflow: auto; overscroll-behavior: contain">
 <div style="padding: 6px 12px; border-top: 1px solid #1b2c44; font-size: 12px; color: #b9c6d6">↗ references: Research / Interview notes</div>
 <div style="padding: 6px 12px; border-top: 1px solid #1b2c44; font-size: 12px; color: #b9c6d6">↗ references: Research / Findings</div>
@@ -174,11 +176,35 @@ body{margin:0}
 <span style="font-size: 11px; color: #8ea3bd">Fit and focus keep a lane clear for floating chrome.</span>
 </div>
 </div>
+
+<div style="display: flex; flex-direction: column; gap: 8px">
+<h2 style="margin: 0; font-size: 15px; font-weight: 600">Present · hover / keyboard focus</h2>
+<p style="margin: 0; font-size: 11px; color: #8ea3bd">2026-10-25: the button describes this tooltip with aria-describedby. In the narrow ⋯ menu, the same text appears in flow below Present so the scrolling menu cannot clip it.</p>
+<div role="tooltip" style="max-width: 240px; padding: 10px 12px; border: 1px solid #2a4566; border-radius: 10px; background: #0f1d31; color: #b9c6d6; font-size: 12px; line-height: 1.35">
+<strong style="color: #e6eef7">Present board</strong>
+<p>A presentation follows either a saved tour or the board’s groups.</p>
+<p>Saved tour: ask your agent to define the stops and their order. Each stop can focus on a card, a group, a rectangular area, or a specific camera position.</p>
+<p style="margin-bottom: 0">No saved tour: every group becomes a stop, ordered top-to-bottom, then left-to-right. It doesn’t automatically visit every card.</p>
+</div>
+</div>
+<div style="display: flex; flex-direction: column; gap: 8px">
+<h2 style="margin: 0; font-size: 15px; font-weight: 600">Presentation · navigation</h2>
+<p style="margin: 0; font-size: 11px; color: #8ea3bd">Owner decision, 2026-10-25: Back and Next sit beside Exit at the top-right. Instructions appear only in hover/focus tooltips, never in a corner panel. End buttons stay focusable but unavailable; their descriptions remain accessible.</p>
+<div style="position: relative; height: 180px; border: 1px solid #1b2c44; border-radius: 10px; background: #081524">
+<div style="position: absolute; top: 16px; right: 16px; display: flex; gap: 8px">
+<button style="padding: 8px 14px; min-height: 38px; border: 1px solid #8ea3bd; border-radius: 8px; background: #0f1d31; color: #e6eef7; font: inherit; font-weight: 600; opacity: .5" aria-disabled="true">Back</button>
+<button style="padding: 8px 14px; min-height: 38px; border: 1px solid #8ea3bd; border-radius: 8px; background: #0f1d31; color: #e6eef7; font: inherit; font-weight: 600">Next</button>
+<button style="padding: 8px 14px; min-height: 38px; border: 1px solid #8ea3bd; border-radius: 8px; background: #0f1d31; color: #e6eef7; font: inherit; font-weight: 600">Exit presentation</button>
+</div>
+<div style="position: absolute; top: 66px; right: 16px; width: 168px; padding: 10px 12px; border: 1px solid #2a4566; border-radius: 10px; background: #0f1d31; box-shadow: 0 14px 36px #0006; font-size: 12px"><strong>Next stop</strong><br><span style="color: #8ea3bd">→ / ↓ / Space</span></div>
+</div>
+<p style="margin: 0; font-size: 11px; color: #8ea3bd">Back: Previous stop, ← / ↑. Next: Next stop, → / ↓ / Space. Exit: Exit presentation, Esc. Fit clears the top controls; exact camera targets and recording remain exact.</p>
+</div>
 </section>
 
 </div>
 </x-dc>
-<script type="text/x-dc" data-dc-script data-props='{"$preview":{"width":1440,"height":1000}}'>
+<script type="text/x-dc" data-dc-script data-props='{"$preview":{"width":1440,"height":1360}}'>
 class Component extends DCLogic {
   renderVals() {
     var P = {
@@ -245,7 +271,7 @@ class Component extends DCLogic {
       optIn('Trace', 'Show execution traces. Turning off keeps existing traces and never starts an agent.', false, false),
       setting('Send feedback', '', 'Share feedback about PMX Canvas.')
     ];
-    var nodeMenu = [m('Focus', ''), m('Rename…', ''), m('Collapse', ''), m('Open in new tab', '', true), msep, m('Delete', '⌫')];
+    var nodeMenu = [m('Focus', ''), m('Rename…', ''), m('Collapse', ''), m('Open in new tab', ''), msep, m('Set as README', '', true), msep, m('Delete', '⌫')];
     var oldIcons = [{ d: P.ctx }, { d: P.ask }, { d: P.open }, { d: P.expand }, { d: P.chevron }, { d: P.close }];
     return { railToday: railToday, railNew: railNew, settings: settings, nodeMenu: nodeMenu, oldIcons: oldIcons };
   }