pmx-canvas 0.8.2 → 0.9.1

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.8.2**, which requires **Bun >=1.4.2** even when
+The examples pin **PMX Canvas 0.9.1**, 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.8.2
+npm install -g pmx-canvas@0.9.1
 pmx-canvas --version
 ```
 
-Without a global install, use `bunx pmx-canvas@0.8.2` in place of `pmx-canvas` in
+Without a global install, use `bunx pmx-canvas@0.9.1` in place of `pmx-canvas` in
 the commands below. Do not use unpinned `bunx pmx-canvas` for a version-specific check.
 
 ## Choose the workspace and target
@@ -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.8.2", "--mcp"],
+      "args": ["pmx-canvas@0.9.1", "--mcp"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
         "PMX_CANVAS_PORT": "14313",
@@ -135,7 +135,7 @@ Amp executes, not only on the user's laptop. Merge this into that workspace's
   "amp.mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.8.2", "--mcp"],
+      "args": ["pmx-canvas@0.9.1", "--mcp"],
       "includeTools": ["canvas_*"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
@@ -169,7 +169,7 @@ The agent must not run this approval itself or move the command to global settin
 `--mcp-config` to bypass workspace trust. Approval authorizes execution of this MCP
 command; it is not a new Canvas import consent or permission to mutate arbitrary boards.
 After approval, reload MCP connections (`reload_mcp` in Amp) and require `connected`.
-Discover `canvas` tools with `tool_search`; for the full unfiltered 0.8.2 server there
+Discover `canvas` tools with `tool_search`; for the full unfiltered 0.9.1 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).
 

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

@@ -19,10 +19,11 @@ Persist a tour with `canvas_view { action: "set-tour", tour: { stops: [...] } }`
 ```
 
 - `nodeId` may identify a card or group. Its persisted position and size determine the camera.
+- `rect` is a world-space box `{ x, y, width, height }` (top-left corner plus size).
 - An explicit viewport is `{ x, y, scale }`, with positive `scale`. Translation is screen-space:
   `screen = world * scale + offset`.
 - `duration` is transition time in seconds (default 1; zero jumps). Valid values are 0–3600.
-- `padding` is screen pixels around a node target (default 40).
+- `padding` is screen pixels around a node or rect target (default 40).
 - `easing` is `linear`, `ease-in-out` (default), or `ease-out`.
 - `pullback` is 0–4 (default 0). It zooms out during the move without changing either endpoint.
 - A tour contains at most 1000 stops.
@@ -39,6 +40,20 @@ ID. A saved `{ "stops": [] }` intentionally has no stops; it does not enable gro
 Preserve the tour of each board when working across boards and target the intended board before
 setting or reading it.
 
+## Drive a tour
+
+The server holds one in-memory tour cursor, tied to the board it was started on (a tour on another board replaces it). `canvas_view { action: "tour-go", stop: 0 }`
+starts presenting in open workbenches; `step: "next" | "previous"` moves relative to wherever the
+audience is (a human's arrow keys move the same cursor) and clamps at the ends. Pass
+`present: false` to move only viewers already presenting. `canvas_view { action: "tour-exit" }`
+leaves presentation everywhere. `get-tour` reports `position` (the current stop, or null).
+
+`canvas_view { action: "move", nodeId | rect | viewport, duration, easing, padding, pullback }`
+eases the camera without a tour. Outside a presentation the end camera becomes the board
+viewport. Tour steps and moves never enter undo history, never count as agent writes, and are
+allowed under a scope fence. Viewers with reduced motion jump instead of animating; a
+deterministic capture ignores both.
+
 ## Capture prerequisites and behavior
 
 Start and verify the matching PMX daemon first: its `/health` workspace and version must match the

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

@@ -53,6 +53,10 @@ and check `$?`, then read the file.
 - Test-only changes: run `bun run test` and `bun run test:coverage` if coverage matters
 - Client/UI/browser interaction changes: run `bun run test:web-canvas`
 - Cross-stack or non-trivial changes: run `bun run test:all`
+- Bundled skill/documentation-only changes: run
+  `bun test tests/unit/bundled-skills.test.ts tests/unit/no-native-tooltips.test.ts`
+  and `git diff --check`; inspect public-contract prose against source. No client rebuild or
+  full browser suite is needed when executable behavior has not changed.
 - Before changing browser-visible behavior under `src/client/`: rebuild with `bun run build`
   Manual browser validation also requires a fresh client bundle. `bun run test:web-canvas`
   already does this for you.
@@ -146,6 +150,13 @@ Four ways a test silently stops discriminating in this repo:
   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.
+- For viewer refreshes, run `tests/e2e/viewer-refresh-frames.pw.ts`: it delays the runtime-state
+  restore beyond document load and checks every captured frame for blank/white flashes in
+  Harbor with light/dark OS settings and Daylight with dark OS settings. Keep the frame assertions;
+  a settled DOM check cannot prove the handoff stayed painted. Reset canvas-bound work as well as
+  nodes between cases. The inert replacement renders behind the active iframe, so select the
+  foreground with `iframe:not([inert])`, not `iframe:visible`. Keep capturing until the last
+  update is actually in the foreground; a momentary one-iframe count may precede the next poll.
 - 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.
@@ -158,6 +169,15 @@ Four ways a test silently stops discriminating in this repo:
 - User-facing creation flows must end with the new nodes visible: after the create (plus the
   skill-mandated focus/fit), a screenshot must show them without any manual pan. A `panned: true`
   API result alone is not proof — verify the frame is on-screen and unobscured.
+- Layout validation proves node non-overlap, not relation readability. After content settles,
+  inspect edge lines, labels, arrowheads and authorship marks at the intended viewing zoom,
+  including after auto-arrange; do not prescribe one universal gap.
+- Context/receipt checks must distinguish map delivery (seen links and board read status) from
+  full card-content reads. Check one-open stacked See change, clipped-excerpt captions and
+  whole-card Undo with a latest-human-edit negative control. Retain a receipt across a board
+  switch: snapshot comparison must reopen its owning board, Undo/Unpin must not affect the
+  foreign board, and lens marks must use only active-board touches. Check the narrow agent
+  initial's counts/lens/panel interaction separately. Use disposable boards for these checks.
 
 ## Failure Handling
 

package/src/cli/agent.ts

@@ -52,6 +52,8 @@ Usage:
 
 Presentation and capture:
   pmx-canvas tour get|set             Read or persist ordered camera stops
+  pmx-canvas tour go <n|next|previous> Present a stop; tour exit leaves presentation
+  pmx-canvas camera move --node <id>  Ease the camera to a node, --rect or --viewport
   pmx-canvas record --help            Optionally capture the same board tour or live presentation
 
 Server:

package/src/cli/commands/ax.ts

@@ -397,6 +397,18 @@ cmd(
   },
 );
 
+cmd(
+  'ax reads status',
+  'Read status for a board: its last agent read, per-node reads and revisions, and pin metadata',
+  ['pmx-canvas ax reads status', 'pmx-canvas ax reads status --board <board-id>'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('ax reads status');
+
+    output(await invokeOperation('ax.reads.status', typeof flags.board === 'string' ? { board: flags.board } : {}));
+  },
+);
+
 cmd(
   'ax work add',
   'Add a canvas-bound AX work item',

package/src/cli/commands/boards.ts

@@ -2,6 +2,55 @@
 
 import { cmd, die, getStringFlag, invokeOperation, output, parseFlags, showCommandHelp } from '../shared.js';
 
+cmd(
+  'board vocabulary',
+  'Set a board relation vocabulary from JSON',
+  ['pmx-canvas board vocabulary <id> \'[{"kind":"supports","ink":"supports","directed":true}]\''],
+  async (args) => {
+    const [id, json] = args;
+    if (!id || !json) die('Expected board id and vocabulary JSON.');
+    output(await invokeOperation('board.update', { id, relationVocabulary: JSON.parse(json) }));
+  },
+);
+
+cmd(
+  'board knowledge',
+  'Workspace knowledge actions with a JSON payload',
+  [
+    'pmx-canvas board knowledge list',
+    'pmx-canvas board knowledge category-remove \'{"id":"unused-category"}\'',
+    'pmx-canvas board knowledge folder-set \'{"path":"A","categoryId":null,"lifecycleOverride":null}\'',
+  ],
+  async (args) => {
+    const [action, payload = '{}'] = args;
+    if (
+      ![
+        'list',
+        'category-set',
+        'category-remove',
+        'folder-set',
+        'relation-preset-set',
+        'relation-preset-remove',
+      ].includes(action ?? '')
+    )
+      die('Expected list, category-set, category-remove, folder-set, relation-preset-set or relation-preset-remove.');
+    output(await invokeOperation(`knowledge.${action}`, JSON.parse(payload)));
+  },
+);
+
+cmd(
+  'board lifecycle',
+  'Card lifecycle and audited reviews with a JSON payload',
+  ['pmx-canvas board lifecycle get \'{"id":"card"}\''],
+  async (args) => {
+    const [action, payload = '{}'] = args;
+    if (!['get', 'set', 'review', 'restore'].includes(action ?? '')) die('Expected get, set, review or restore.');
+    output(
+      await invokeOperation(action === 'review' ? 'node.review' : `node.lifecycle-${action}`, JSON.parse(payload)),
+    );
+  },
+);
+
 cmd('board list', 'List boards, most recently opened first', ['pmx-canvas board list'], async (args) => {
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('board list');
@@ -49,14 +98,42 @@ cmd(
 cmd(
   'board create',
   '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'],
+  ['pmx-canvas board create "Q4 planning"', 'pmx-canvas board create "Q4 planning" --folder Planning'],
   async (args) => {
     const { positional, flags } = parseFlags(args);
     if (flags.help || flags.h) return showCommandHelp('board create');
+    if ('category' in flags) die('The --category flag was removed.', 'Use --folder <folder> instead.');
     const name = positional.join(' ').trim();
-    if (!name) die('Usage: pmx-canvas board create <name> [--category <category>]');
-    const category = getStringFlag(flags, 'category');
-    output(await invokeOperation('board.create', { name, ...(category ? { category } : {}) }));
+    if (!name) die('Usage: pmx-canvas board create <name> [--folder <folder>]');
+    const folder = getStringFlag(flags, 'folder');
+    output(await invokeOperation('board.create', { name, ...(folder ? { folder } : {}) }));
+  },
+);
+
+cmd(
+  'board pin',
+  "Pin a board into the agent's working set (its README and pinned cards reach every brief)",
+  ['pmx-canvas board pin board-abc123', 'pmx-canvas board pin board-abc123 --reason "Q4 rests on it"'],
+  async (args) => {
+    const { positional, flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('board pin');
+    const [id] = positional;
+    if (!id || positional.length > 1) die('Usage: pmx-canvas board pin <board-id> [--reason <why>]');
+    const reason = getStringFlag(flags, 'reason');
+    output(await invokeOperation('board.pin', { id, ...(reason ? { reason } : {}) }));
+  },
+);
+
+cmd(
+  'board unpin',
+  "Remove a board from the agent's working set",
+  ['pmx-canvas board unpin board-abc123'],
+  async (args) => {
+    const { positional, flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('board unpin');
+    const [id] = positional;
+    if (!id || positional.length > 1) die('Usage: pmx-canvas board unpin <board-id>');
+    output(await invokeOperation('board.unpin', { id }));
   },
 );
 
@@ -70,15 +147,15 @@ cmd('board rename', 'Rename a board', ['pmx-canvas board rename board-abc123 "Q4
 });
 
 cmd(
-  'board category',
-  'File a board under a category on Home (--clear removes it)',
-  ['pmx-canvas board category board-abc123 "Planning"', 'pmx-canvas board category board-abc123 --clear'],
+  'board folder',
+  'File a board under a folder on Home (--clear removes it)',
+  ['pmx-canvas board folder board-abc123 "Planning"', 'pmx-canvas board folder board-abc123 --clear'],
   async (args) => {
     const { positional, flags } = parseFlags(args);
-    if (flags.help || flags.h) return showCommandHelp('board category');
+    if (flags.help || flags.h) return showCommandHelp('board folder');
     const [id, ...rest] = positional;
-    const category = flags.clear ? '' : rest.join(' ').trim();
-    if (!id || (!category && !flags.clear)) die('Usage: pmx-canvas board category <board-id> <category> | --clear');
-    output(await invokeOperation('board.update', { id, category }));
+    const folder = flags.clear ? '' : rest.join(' ').trim();
+    if (!id || (!folder && !flags.clear)) die('Usage: pmx-canvas board folder <board-id> <folder> | --clear');
+    output(await invokeOperation('board.update', { id, folder }));
   },
 );

package/src/cli/commands/edges.ts

@@ -39,18 +39,46 @@ cmd(
       type,
       ...(from ? { from } : {}),
       ...(to ? { to } : {}),
+      ...(typeof flags['to-board'] === 'string' ? { toBoardId: flags['to-board'] } : {}),
       ...(fromSearch ? { fromSearch } : {}),
       ...(toSearch ? { toSearch } : {}),
     };
     if (flags.label && flags.label !== true) body.label = flags.label;
+    if (typeof flags.kind === 'string') body.kind = flags.kind;
+    if (typeof flags.reason === 'string') body.reason = flags.reason;
     if (typeof flags.style === 'string') body.style = flags.style;
     if (flags.animated) body.animated = true;
+    for (const [flag, field] of [
+      ['destination-board', 'destinationBoardId'],
+      ['request-id', 'requestId'],
+      ['expected-board', 'expectedBoardId'],
+    ] as const) {
+      if (typeof flags[flag] === 'string') body[field] = flags[flag];
+    }
 
     const result = await invokeOperation('edge.add', body);
     output(result);
   },
 );
 
+cmd(
+  'edge update',
+  'Edit a relation kind, reason, label or appearance',
+  ['pmx-canvas edge update <id> --kind supports --reason "Evidence from interviews"'],
+  async (args) => {
+    const { positional, flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('edge update');
+    if (!positional[0]) die('Missing edge ID', 'pmx-canvas edge update <id> --kind supports');
+    const body: Record<string, unknown> = { id: positional[0] };
+    for (const key of ['kind', 'reason', 'label', 'type', 'style']) {
+      if (typeof flags[key] === 'string') body[key] = flags[key];
+    }
+    if (flags['clear-kind']) body.kind = null;
+    if (flags['clear-reason']) body.reason = null;
+    output(await invokeOperation('edge.update', body));
+  },
+);
+
 // ── edge list ────────────────────────────────────────────────
 cmd('edge list', 'List all edges on the canvas', ['pmx-canvas edge list'], async (args) => {
   const { flags } = parseFlags(args);

package/src/cli/commands/groups.ts

@@ -38,6 +38,13 @@ cmd(
     if (height !== undefined) body.height = height;
     if (typeof flags['child-layout'] === 'string') body.childLayout = flags['child-layout'];
     if (positional.length > 0) body.childIds = positional;
+    for (const [flag, field] of [
+      ['destination-board', 'destinationBoardId'],
+      ['request-id', 'requestId'],
+      ['expected-board', 'expectedBoardId'],
+    ] as const) {
+      if (typeof flags[flag] === 'string') body[field] = flags[flag];
+    }
 
     const result = await invokeOperation('group.create', body);
     output(result);

package/src/cli/commands/nodes.ts

@@ -133,6 +133,7 @@ function summarizeNodeResult(node: Record<string, unknown>): Record<string, unkn
     ...(node.path !== undefined ? { path: node.path } : {}),
     ...(node.url !== undefined ? { url: node.url } : {}),
     ...(node.provenance !== undefined ? { provenance: node.provenance } : {}),
+    ...(node.qualification !== undefined ? { qualification: node.qualification } : {}),
     ...(typeof data.mode === 'string' ? { mode: data.mode } : {}),
     ...(typeof data.viewerType === 'string' ? { viewerType: data.viewerType } : {}),
     ...(typeof data.serverName === 'string' ? { serverName: data.serverName } : {}),

package/src/cli/commands/query.ts

@@ -28,7 +28,7 @@ import {
 cmd(
   'search',
   'Search nodes by title or content',
-  ['pmx-canvas search "design doc"', 'pmx-canvas search --query "TODO"'],
+  ['pmx-canvas search "design doc"', 'pmx-canvas search --query "TODO" --folder "Research" --board-id <id>'],
   async (args) => {
     const { positional, flags } = parseFlags(args);
     if (flags.help || flags.h) return showCommandHelp('search');
@@ -36,11 +36,43 @@ cmd(
     const query = positional[0] || (typeof flags.query === 'string' ? flags.query : '');
     if (!query) die('Missing search query', 'pmx-canvas search "query"');
 
-    const result = await invokeOperation('search', { q: query, ...(flags.library ? { scope: 'library' } : {}) });
+    if (flags.scope !== undefined && flags.scope !== 'active' && flags.scope !== 'library')
+      die('--scope must be active or library.');
+    const result = await invokeOperation('search', {
+      q: query,
+      ...(flags.scope ? { scope: flags.scope } : flags.library ? { scope: 'library' } : {}),
+      ...(typeof flags['board-id'] === 'string' ? { boardId: flags['board-id'] } : {}),
+      ...(typeof flags.folder === 'string' ? { folder: flags.folder } : {}),
+      ...(typeof flags.limit === 'string' ? { limit: Number(flags.limit) } : {}),
+    });
     output(result);
   },
 );
 
+cmd(
+  'memory-graph',
+  'Explore the board/card relation graph (summary-only)',
+  [
+    'pmx-canvas memory-graph',
+    'pmx-canvas memory-graph --focus pins --depth 2',
+    'pmx-canvas memory-graph --projection boards',
+  ],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('memory-graph');
+    if (flags.depth !== undefined && (typeof flags.depth !== 'string' || !flags.depth.trim())) {
+      die('--depth requires an integer from 0 to 4.');
+    }
+    output(
+      await invokeOperation('memory-graph.get', {
+        ...(typeof flags.focus === 'string' ? { focus: flags.focus } : {}),
+        ...(flags.depth !== undefined ? { depth: Number(flags.depth) } : {}),
+        ...(flags.projection !== undefined ? { projection: flags.projection } : {}),
+      }),
+    );
+  },
+);
+
 cmd(
   'context',
   'Read the budgeted cross-board context brief',