pmx-canvas 0.7.1 → 0.7.3

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

@@ -430,8 +430,8 @@ single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) di
 
 > **Legacy single-purpose tools were removed in v0.3.0.** The old names (`canvas_add_node`,
 > `canvas_update_node`, `canvas_request_approval`, `canvas_add_work_item`, …) are no longer
-> registered — use the composites instead. The authoritative legacy→composite mapping table lives
-> in [`docs/mcp.md`](../../../docs/mcp.md) — this skill does not re-enumerate the removed names.
+> registered — use the composites below and fresh MCP `tools/list` for the installed runtime's
+> authoritative action schemas. This skill does not re-enumerate the removed names.
 
 ### The 18 composites
 
@@ -439,11 +439,11 @@ single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) di
 |-----------|-----------------|--------------|
 | `canvas_import` | `list` · `read` · `submit` · `unavailable` | Process human-requested imports: inspect metadata/controlled bytes, submit reviewable Markdown with references/warnings/agent description, or report unavailable. Request/cancel/commit are human-only |
 | `canvas_node` | `add` · `get` · `update` · `remove` | Create / read / mutate / delete a node. **`add` covers html + primitives too**: `{ action:"add", type:"html", html:"…" }` and `{ action:"add", type:"html", primitive:"choice-grid", data:{} }` — no separate add-html tool needed |
-| `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` | Schema introspection, spec dry-run validation, and native json-render / graph node creation |
+| `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` · `workboard` | Schema introspection, spec dry-run validation, native json-render / graph node creation, and a live AX work-item board |
 | `canvas_edge` | `add` · `update` · `remove` | Connect / edit / disconnect nodes |
 | `canvas_group` | `create` · `add` · `ungroup` | Manage spatial group containers |
 | `canvas_history` | `undo` · `redo` | Time travel through the mutation ring buffer |
-| `canvas_board` | `list` · `get` · `create` · `create-from` · `update` | Boards, README designation, links/backlinks, and inactive copies |
+| `canvas_board` | `list` · `get` · `create` · `create-from` · `open` · `update` | Boards, shared-workbench switching, README designation, links/backlinks, and inactive copies |
 | `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | Named snapshots: save/list/restore/delete, garbage-collect old ones, diff current canvas vs a snapshot (`diff` takes `snapshot`, not `id`) |
 | `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` · `get-tour` · `set-tour` | Auto-arrange, pan-to-node, fit viewport, clear the board, delete annotations, read/persist ordered presentation stops (`tour: null` derives group order) |
 | `canvas_query` | `context` · `search` · `layout` · `validate` | Read the budgeted cross-board brief, find nodes by keyword, read full layout, or **`validate`** the board for node collisions / group-containment / dangling edges |
@@ -485,6 +485,11 @@ creation: `prompt`, `response`, `trace`, and `mcp-app` are excluded; README and
 group structure are optional; fresh IDs are allocated; pins, AX state, and
 history are not copied; the source remains unchanged and the new board inactive.
 
+Use `canvas_board { action: "open", id: "<board-id>" }` to open a created or
+existing board before authoring. Verify the returned `activeBoardId`; opening
+switches the shared visible workbench and all subsequent write targets, not
+just this agent's context. `id: null` opens Home. Deletion stays human-only.
+
 `canvas_ax_gate` takes **two** discriminators, `{ kind, action }` — e.g.
 `{ kind: "approval", action: "request", title }`,
 `{ kind: "elicitation", action: "resolve", id, response }`,

package/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -53,6 +53,12 @@ canvas writes — which reach the server as MCP or HTTP tool calls, not as `copi
 to that session by the server. Nothing to configure; `GET /api/canvas/ax/presence` shows the live
 state.
 
+Read presence before starting board work. Reuse the extension's `copilot` session and
+steering consumer; do not attach a second session such as “Copilot – team overview” with
+a new source or `agentId`. Send task names as `detail` on `source: "copilot"`, preserving
+the host's identity and polling route. The adapter owns attach/detach; the agent must not
+end it after each task. Explicit agent IDs are reserved for genuinely independent subagents.
+
 ## What the Adapter Does
 
 - Opens the live PMX workbench directly in a native Copilot canvas panel.
@@ -138,14 +144,22 @@ Default discovery order:
 3. `PMX_CANVAS_PORT` / `PMX_WEB_CANVAS_PORT` / `4313` on loopback.
 4. Managed server startup for the current workspace when `autoStart` is not `false`.
 
-The adapter rejects an unrelated running PMX server unless `serverUrl` is explicit or
-`allowWorkspaceMismatch` is true.
+The adapter rejects an unrelated running PMX server unless `allowWorkspaceMismatch` is true,
+including when `serverUrl` is explicit.
+
+If discovery fails, the panel shows a connection page, not a partial workbench. It checks the
+original target automatically; **Check connection** retries immediately and **Start server**
+explicitly allows local startup even if `autoStart` was disabled. After recovery it navigates
+to the server's real `/workbench`, with Home and recent boards. Adapter actions keep using that
+server and refuse writes if its workspace changes. Reopen the canvas explicitly to select a
+different target. The fallback shell's own `/health` or `/api/canvas/boards` returning 404 is
+expected: the shell is not a PMX API proxy.
 
 ## Actions
 
 | Action | Purpose |
 |---|---|
-| `status` | Return PMX server health and persisted AX state. |
+| `status` | Return PMX server health and persisted AX state, excluding serialized node context (`includeContext=false`). |
 | `get_ax_context` | Return current pinned + focused AX context. |
 | `focus_nodes` | Set AX focus with `source: "copilot"`. |
 | `send_instruction` | Send an explicit prompt into the active Copilot session. |

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

@@ -4,7 +4,7 @@ Use this reference when the `pmx-canvas` skill is installed but the `pmx-canvas`
 
 ## Prerequisites and version
 
-The examples pin **PMX Canvas 0.7.1**, which requires **Bun >=1.4.2** even when
+The examples pin **PMX Canvas 0.7.3**, which requires **Bun >=1.4.2** even when
 installed through npm: the CLI runs through Bun, not Node. Check `bun --version`
 first. If missing or older, follow the [Bun installation instructions](https://bun.sh/docs/installation)
 with the user's authorization. Ensure Bun is on the MCP host's PATH as well as the
@@ -17,11 +17,11 @@ in `SKILL.md`. Do not pair newer checkout guidance with an older runtime unknowi
 ## Install from npm
 
 ```bash
-npm install -g pmx-canvas@0.7.1
+npm install -g pmx-canvas@0.7.3
 pmx-canvas --version
 ```
 
-Without a global install, use `bunx pmx-canvas@0.7.1` in place of `pmx-canvas` in
+Without a global install, use `bunx pmx-canvas@0.7.3` in place of `pmx-canvas` in
 the commands below. Do not use unpinned `bunx pmx-canvas` for a version-specific check.
 
 ## Choose the workspace and target
@@ -91,7 +91,7 @@ discards empty env values, remove `PMX_CANVAS_URL` from its launch environment i
   "mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.7.1", "--mcp"],
+      "args": ["pmx-canvas@0.7.3", "--mcp"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
         "PMX_CANVAS_PORT": "14313",
@@ -123,6 +123,78 @@ If you are using a local checkout instead of the published package, point the co
 Restart the host's MCP process after changing configuration. Inspect startup output for
 fallback ports; do not assume the configured port is the one the MCP server bound.
 
+## Amp: connect the agent separately from the portal
+
+PMX does not ship a dedicated Amp lifecycle adapter. Amp can use the native MCP tools;
+the portal is only the human's browser UI. Configure MCP inside the orb or runner where
+Amp executes, not only on the user's laptop. Merge this into that workspace's
+`.amp/settings.json`, preserving other settings (Amp does not use the generic `.mcp.json`):
+
+```json
+{
+  "amp.mcpServers": {
+    "canvas": {
+      "command": "bunx",
+      "args": ["pmx-canvas@0.7.3", "--mcp"],
+      "includeTools": ["canvas_*"],
+      "env": {
+        "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
+        "PMX_CANVAS_PORT": "14313",
+        "PMX_CANVAS_URL": "",
+        "PMX_CANVAS_AGENT_SOURCE": "amp"
+      }
+    }
+  }
+}
+```
+
+Replace root and port with the **existing portal service's actual workspace and local
+listening port**. A supervised service may use an assigned `PORT`, not 4313 or 14313;
+inspect its status/logs and `/health`. Do not put the public portal URL in the stdio
+command or copy another test run's absolute paths. Use an absolute executable path if
+the MCP process cannot find Bun. The `canvas_*` filter exposes the Canvas tool family.
+
+### Workspace trust is a human approval
+
+Run `amp mcp doctor` from this workspace to distinguish `awaiting approval` from a
+missing executable or connection failure. A new workspace MCP command requires the
+user to review and approve it. Give the user this command to run in that workspace's
+orb Terminal or runner terminal (replace `canvas` if the configured server name differs):
+
+```bash
+amp mcp approve canvas
+```
+
+The agent must not run this approval itself or move the command to global settings or
+`--mcp-config` to bypass workspace trust. Approval authorizes execution of this MCP
+command; it is not a new Canvas import consent or permission to mutate arbitrary boards.
+After approval, reload MCP connections (`reload_mcp` in Amp) and require `connected`.
+Discover `canvas` tools with `tool_search`; for the full unfiltered 0.7.3 server there
+are 24 tools. If still absent, inspect the server status, command/PATH and target instead
+of reinstalling blindly. See [Amp MCP documentation](https://ampcode.com/docs/customize/mcp).
+
+### Verify native tools, then steering
+
+1. Check `/health` for the expected package version and canonical workspace. Through
+   Amp's discovered tools, read `canvas_board { action: "get" }` and
+   `canvas_query { action: "context" }`; verify the board matches the visible portal.
+   A CLI smoke check or SDK-spawned MCP client does not establish native Amp discovery.
+2. For a requested end-to-end check, use a disposable board. Pin a known card in the
+   portal and require a native context read to return that card as pinned. Use one
+   stable presence/steering identity (`amp` above, or a unique source per independent
+   agent); reuse any adapter-owned session instead of attaching a duplicate.
+3. Send a fresh browser message addressed to that identity. The running agent claims
+   it with `canvas_ax_delivery` using the same `consumer`, reads the relevant card,
+   signals intent, and performs the requested edit through native Canvas tools.
+4. Verify the visible result in the browser before marking the message delivered for
+   that consumer. A subsequent claim should omit it. Detach only test-owned sessions.
+
+This proves an **active agent can poll and act**, not automatic wake-up of an idle Amp
+thread, background polling, or automatic agent launch for imports. An MCP connection
+does not install a steering pump. Only configure a pump/host integration when requested;
+its startup backlog rules are in the main skill. Tool discovery and resource reads also
+do not establish Amp support for native MCP Skills-extension discovery or activation.
+
 ## Verify the actual target before writes
 
 For the local target selected above:

package/skills/pmx-canvas-testing/SKILL.md

@@ -139,6 +139,12 @@ Four ways a test silently stops discriminating in this repo:
 - For `graph`, `json-render`, `mcp-app`, webpage, and image nodes, API geometry is not enough.
   Verify the rendered browser frame when changing sizing: iframe/body `scrollHeight` and
   `scrollWidth` should fit the available frame unless scrolling is the intended behavior.
+- For JSON focus transitions, edit a bound input and load a multi-item runtime list inline,
+  expand and verify both, edit/replace them in focus mode, then close and verify both again.
+  Exercise `src` and `srcdoc`, including AX-disabled JSON. No save, spec edit or reload belongs
+  between those assertions. Separately verify a real spec revision resets to authored state,
+  and that local drafts never entered the server spec. See `tests/e2e/json-render-forms.pw.ts`.
+  Eval definitions are not evidence of executing this browser regression or a model benchmark.
 - When checking embedded frame fit manually, start from a clean seeded state, rebuild stale bundles,
   and inspect the actual iframe document in a browser. Server dimensions can look correct while the
   embedded content is still clipped.
@@ -160,6 +166,49 @@ Four ways a test silently stops discriminating in this repo:
 - If browser tests fail after a client change, confirm the bundle was rebuilt and the server
   started from the updated code
 
+### Keep first-failure evidence before rerunning
+
+Use a separate directory for each attempt, including non-browser probes. Save the exact
+command, target/version, exit status, stdout and stderr; keep credentials out of logs.
+Before rerunning Playwright, copy its failure traces/screenshots and results out of the
+runner's overwritten output directory. Never overwrite an initial failure log with a rerun.
+For a shell gate, capture its status even with `set -e`, for example:
+
+```bash
+attempt_dir=$(mktemp -d /tmp/pmx-check.XXXXXX)
+printf '%s\n' 'bun run test' > "$attempt_dir/command.txt"
+status=0
+bun run test > "$attempt_dir/stdout.log" 2> "$attempt_dir/stderr.log" || status=$?
+printf '%s\n' "$status" > "$attempt_dir/exit-status.txt"
+# Inspect this attempt before rerunning; return the gate's original exit status.
+(exit "$status")
+```
+
+Record what changed between attempts. Distinguish harness corrections, product fixes,
+unchanged retries and host approval. A corrected pass does not make the original attempt
+green. If logs were lost, say so; never reconstruct them or claim first-run success.
+
+## Native-host verification is separate from transport checks
+
+Record source, packed-package, registry-package, portal and native-host results separately.
+An SDK subprocess's MCP handshake/catalog is not evidence that Amp discovered tools.
+For Amp setup/trust and the pin → read → addressed steer → edit → visible result → ack
+procedure, follow the bundled [installation reference](../pmx-canvas/references/installing-pmx-canvas.md#amp-connect-the-agent-separately-from-the-portal).
+MCP-only consumers should read `skill://pmx-canvas/references/installing-pmx-canvas.md`
+directly with `resources/read`, not traverse outside the testing skill's resource tree.
+Workspace trust approval belongs to the human; report a blocked native check until approved.
+Include a different-recipient negative control for addressed delivery on a disposable board.
+Verify the rendered edit before acknowledging; detach only test-owned sessions afterward.
+Do not label active-agent polling as idle-thread wake-up, a persistent pump, or automatic
+import-agent launch. Native MCP tools do not prove native Skills-extension discovery.
+
+List unexercised surfaces explicitly: native Copilot/WebKit, Windows-native behavior,
+physical mobile, OCR and Office extraction need their own evidence. Source adapter tests
+or a source helper pointed at a published server do not establish installed-adapter execution.
+Sampled resource digests are not a full-catalog audit; eval definitions are not scored model
+results; a skipped mirror check is not validation. Do not change the product merely to
+turn an untested surface into a claimed pass.
+
 ## Handoff Standard
 
 Before marking work done, report:

package/src/cli/commands/backup.ts

@@ -12,12 +12,23 @@ import {
   showCommandHelp,
 } from '../shared.js';
 
+function backupArgs(command: string, args: string[], supported: string[]) {
+  const parsed = parseFlags(args, { boolFlags: ['off'] });
+  const allowed = new Set(['help', 'h', ...supported]);
+  const unknown = Object.keys(parsed.flags).find((flag) => !allowed.has(flag));
+  if (unknown) die(`Unknown ${command} flag: --${unknown}`, `Run: pmx-canvas ${command} --help`);
+  for (const name of ['to', 'keep', 'every']) {
+    if (parsed.flags[name] === true) die(`Missing value for --${name}`, `Run: pmx-canvas ${command} --help`);
+  }
+  return parsed;
+}
+
 cmd(
   'backup',
   'Back up every board to a folder (safe while the server runs)',
   ['pmx-canvas backup', 'pmx-canvas backup --to ~/Backups/pmx --keep 14'],
   async (args) => {
-    const { flags } = parseFlags(args);
+    const { flags } = backupArgs('backup', args, ['to', 'keep']);
     if (flags.help || flags.h) return showCommandHelp('backup');
     const to = getStringFlag(flags, 'to');
     const keep = optionalNumberFlag(flags, 'keep', 'pmx-canvas backup --keep <n>');
@@ -26,7 +37,7 @@ cmd(
 );
 
 cmd('backup status', 'Show the backup folder, schedule and backups', ['pmx-canvas backup status'], async (args) => {
-  const { flags } = parseFlags(args);
+  const { flags } = backupArgs('backup status', args, []);
   if (flags.help || flags.h) return showCommandHelp('backup status');
   output(await invokeOperation('backup.status', {}));
 });
@@ -36,7 +47,7 @@ cmd(
   'Back up on a schedule, run by the server',
   ['pmx-canvas backup schedule --every 24h --keep 14 --to ~/Backups/pmx', 'pmx-canvas backup schedule --off'],
   async (args) => {
-    const { flags } = parseFlags(args);
+    const { flags } = backupArgs('backup schedule', args, ['every', 'off', 'to', 'keep']);
     if (flags.help || flags.h) return showCommandHelp('backup schedule');
     const every = flags.off ? 'off' : getStringFlag(flags, 'every');
     if (!every) die('Usage: pmx-canvas backup schedule --every <30m|24h|7d> [--keep <n>] [--to <folder>] | --off');
@@ -57,7 +68,7 @@ cmd(
   'Replace every board with a backup (the current file is kept as canvas.db.before-restore)',
   ['pmx-canvas restore ~/Backups/pmx/canvas-20260927T090000000Z.db'],
   async (args) => {
-    const { positional, flags } = parseFlags(args);
+    const { positional, flags } = backupArgs('restore', args, []);
     if (flags.help || flags.h) return showCommandHelp('restore');
     const file = positional[0];
     if (!file) die('Usage: pmx-canvas restore <backup-file>');

package/src/cli/commands/boards.ts

@@ -1,5 +1,4 @@
-// Board commands (plan 012): board list, board create, board rename, board category.
-// Opening, switching and deleting boards is the human's, in the workbench.
+// Board commands. Opening changes the shared workbench; deletion remains human-only.
 
 import { cmd, die, getStringFlag, invokeOperation, output, parseFlags, showCommandHelp } from '../shared.js';
 
@@ -9,6 +8,20 @@ cmd('board list', 'List boards, most recently opened first', ['pmx-canvas board
   output(await invokeOperation('board.list', {}));
 });
 
+cmd(
+  'board open',
+  'Open a board in the shared workbench, or return Home with --home',
+  ['pmx-canvas board open <board-id>', 'pmx-canvas board open --home'],
+  async (args) => {
+    const { positional, flags } = parseFlags(args, { boolFlags: ['home'] });
+    if (flags.help || flags.h) return showCommandHelp('board open');
+    if (positional.length > 1 || (flags.home ? positional.length !== 0 : !positional[0])) {
+      die('Usage: pmx-canvas board open <board-id> | --home');
+    }
+    output(await invokeOperation('board.open', { id: flags.home ? null : positional[0] }));
+  },
+);
+
 cmd(
   'board from',
   'Preview or create a board from selected cards on another board',
@@ -35,7 +48,7 @@ cmd(
 
 cmd(
   'board create',
-  'Create an empty board (the human opens it in the workbench)',
+  'Create an empty board (use board open with its returned id before writing)',
   ['pmx-canvas board create "Q4 planning"', 'pmx-canvas board create "Q4 planning" --category Planning'],
   async (args) => {
     const { positional, flags } = parseFlags(args);

package/src/client/canvas/AttentionHistory.tsx

@@ -5,6 +5,7 @@ import {
   closeAttentionHistory,
   openAttentionHistory,
 } from '../state/attention-store';
+import { IconClose } from '../icons';
 
 function formatTimestamp(timestamp: number): string {
   return new Date(timestamp).toLocaleTimeString([], {
@@ -73,7 +74,7 @@ export function AttentionHistory() {
           aria-label="Collapse changes panel"
           title="Collapse"
         >
-          ×
+          <IconClose />
         </button>
       </div>
       <div class="attention-history-list">

package/src/client/canvas/BoardSwitcher.tsx

@@ -1,7 +1,7 @@
 import { render, type VNode } from 'preact';
 import { useLayoutEffect, useMemo, useRef, useState } from 'preact/hooks';
 import { activeBoard, activeBoardId, boardList, boardsLoaded, openBoard } from '../state/boards-store';
-import { IconLogo, IconArrange } from '../icons';
+import { IconLogo, IconArrange, IconChevronDown, IconPlus } from '../icons';
 import { promptNewBoard } from './HomeView';
 
 const RECENT_LIMIT = 8;
@@ -76,7 +76,7 @@ export function BoardSwitcher({ fallbackName }: { fallbackName: string }) {
       >
         <span class="board-switcher-name">{label}</span>
         <span class="board-switcher-caret" aria-hidden="true">
-          ▾
+          <IconChevronDown />
         </span>
       </button>
       {open && anchor && (
@@ -130,7 +130,7 @@ export function BoardSwitcher({ fallbackName }: { fallbackName: string }) {
                 }}
               >
                 <span class="board-switcher-icon" aria-hidden="true">
-                  +
+                  <IconPlus size={18} />
                 </span>
                 New board…
               </button>