pmx-canvas 0.8.2 → 0.9.0

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

@@ -47,8 +47,8 @@ panel.
 
 The extension also reports Copilot's real context window: the SDK's `session.usage_info`
 event (`currentTokens` / `tokenLimit`, root agent only) is posted to the presence as
-`contextUsage`, so the board's top-bar meter reads **Context** with the live numbers rather
-than the pinned-context estimate (**Pins**).
+`contextUsage`, so the board's context panel names how many tokens Copilot's whole context holds,
+next to what the brief costs.
 
 The extension attaches a Copilot session to the canvas when it joins the host session, flips the
 phase to `thinking` on every submitted prompt, and detaches on exit. While attached the workbench

package/skills/pmx-canvas/references/importing-context.md

@@ -0,0 +1,132 @@
+# Importing context
+
+Use this workflow when bringing existing context into PMX Canvas from folders, repositories,
+documents, notes, backlogs, structured exports or knowledge bases. It guides organization and
+verification, not a universal file converter or live sync. PDF/Office attachments still require
+the human-consented extraction and review workflow; this guide does not bypass it.
+
+## Inspect the source before choosing the structure
+
+Inventory the requested scope, file types, existing categories, references and assets. Read
+representative content before mapping it: folder names alone do not establish board boundaries,
+and files may contain several independent items or one argument that should stay together.
+Identify duplicates, historical material, unsupported formats and inaccessible sources. Report
+gaps rather than silently skipping them or claiming extraction succeeded. Keep private context
+within the authorized destination; a folder import is not permission to include credentials.
+
+## Choose boards and cards by purpose
+
+Categories organize boards; boards hold coherent topics or workflows; cards hold useful content.
+Preserve useful categories and folder context without mechanically copying the directory tree.
+A project folder may become an overview board, a backlog with item cards, and a research board.
+Several small files may belong on one board; a single export may need several boards. Choose
+cards by useful units of meaning, not automatically one per file, heading or data row. Retain
+section context, nested details and useful source ordering when splitting content. These are
+examples, not a fixed taxonomy. Explain consequential grouping choices and make them easy to revise.
+Several boards in one category are fine. Keep an argument together when splitting would lose
+meaning. Group related cards and use the main skill's README and focus guidance for a readable start.
+
+Lead each card with the task, item, decision or document section the reader came to find.
+Retain ancestor headings, folder/repository context and source details below that content,
+not as repeated preambles that push every useful item below the card's visible area. Preserve
+meaning and source hierarchy without making the reader expand every card to identify it.
+
+## Preserve sources and stable targets
+
+Work in an isolated workspace for a test import. Preserve an existing import before replacing
+it, and leave source material unchanged unless editing it was requested. Record source paths,
+URLs or record IDs, revisions where available, and the source-item/section → board/card ID
+mapping so interruptions and retries can reuse created objects instead of duplicating them.
+Distinguish faithful imports from summaries; keep a path back to the original. Capture the active
+board before writes, separately from any explicit destination. Create destination boards and
+cards before rewriting internal references, use returned IDs rather than guessed titles, and
+preserve external links.
+
+Create supported static cards, groups and edges on an inactive board with `destinationBoardId`
+without switching the human's view. Static nodes are Markdown, status, context, ledger, trace,
+diff, Mermaid and plain HTML; images, runtime-backed nodes, generated primitives and intents
+are not supported by this path. Updates/removals still require the active board. In a named
+`canvas_batch`, each operation's `args` carries its destination and retry fields; group children
+and edge endpoints can use the existing named references. `toBoardId` independently chooses a
+remote edge endpoint, not the board that owns its source.
+
+Assign a stable `requestId` to each logical static node/group/edge creation and retain it in
+the source-to-canvas mapping. Retry with the same input and destination: the durable receipt
+returns the original result after interruption or restart, even if the object was subsequently
+edited or deleted. It does not restore deleted objects. Changed-input reuse conflicts; a new
+intentional creation gets a new ID even when its content is identical. Batch operations commit
+in sequence, not as one all-or-nothing import. Persist the mapping as receipts arrive.
+
+`expectedBoardId` guards the active board even with an explicit destination. A stale guard
+means refresh context, not substitute the destination ID or switch the human's view to retry.
+For active-only work, explicitly open the intended board and verify its returned ID first.
+Scope fences and human edit locks remain enforced. If Home is active, list/open a suitable
+board before reading board context; library discovery and background static creation can
+stay on Home. For retrieval, `canvas_query` search accepts intersecting `boardId` and `folder`
+filters. Folder includes slash-boundary descendants; `folder: ""` selects unfiled boards.
+Filters default omitted scope to library, while explicit active scope never widens. Search
+never changes the active board.
+
+Use native `references` edges for explicit source links and qualified remote endpoints for
+cross-board cards. Add semantic relations only when the source supports them; record the
+supporting passage or source reference in `reason`. Similar subjects alone do not establish
+dependency, causation or supersession. Follow the main skill's direction rules for dependency kinds.
+
+Preserve historical/draft status and source evidence dates. Importing, reading or rendering
+content does not revalidate it. Flag source contradictions separately from conversion errors
+and product bugs; do not silently rewrite uncertain facts or invent validation dates.
+
+## Markdown link conversion
+
+For content represented as Markdown, use returned IDs in `[[board-id#card-id|label]]` links
+and keep code spans/fences unchanged. In table cells, escape the alias pipe:
+`[[board-id#card-id\|label]]`. Otherwise the table parser can split the link before the wiki
+link parser sees it. Zero unresolved links is not sufficient: compare expected source link
+occurrences with rendered anchors. This is a Markdown rendering concern, not a source-format requirement.
+
+## Keep picture bytes out of long Markdown
+
+Prefer local asset references over large base64 image strings embedded in Markdown. The
+embedded bytes enlarge layout/render requests; inline pictures remain supported. Choosing
+file-backed assets is a representation choice, not proof that a parser or loading bug is fixed.
+Keep private pictures in the authorized workspace; do not upload them to a public image host.
+
+One supported approach is a file-backed image card in the document's board:
+
+```json
+{"action":"add","type":"image","content":"assets/diagram.png","title":"System diagram"}
+```
+
+Call `canvas_node` with that payload, then use the returned ID in the document:
+`![System diagram](/api/canvas/image/<image-node-id>)`. Keep the original alt text and connect
+the document to its figure card when useful. This route resolves nodes on the active board:
+keep the image card in the same board, and recheck references after copying or moving cards.
+
+Relative image creation paths resolve against the canvas workspace root, not the server's
+launch directory. An absolute path inside that workspace also works. Image creation requires
+opening its destination board; do not send `destinationBoardId` or `requestId` for image nodes.
+The database stores the path, not the file bytes: retain the assets alongside it, update paths
+if relocating the workspace, and verify images in exports rather than assuming the live URL
+is portable.
+
+## Verify the imported workspace, not just the API receipts
+
+1. Account for each in-scope source item as imported, summarized, intentionally excluded or
+   unresolved. Reconcile split items, references and assets with the mapping. Check edge endpoints,
+   group containment and collisions with `canvas_query { action: "validate" }`.
+2. Open representative boards for the content actually imported: for example a dense backlog,
+   long document, linked table or picture-heavy board. Wait for the correct board and populated
+   card bodies, not only titles or HTTP success. Images must load with nonzero natural dimensions.
+3. Wait for the intended card/group bounding rectangle after a camera update. Two animation
+   frames do not prove an asynchronous layout update arrived. Inspect screenshots at the
+   intended viewing zoom for readable cards, relations, labels and unobscured controls.
+4. Click local and cross-board links; verify the intended card becomes visible. On a disposable
+   test service, restart and verify persistence, including pictures. Compare asset bytes when
+   changing image representation to confirm originals were preserved.
+5. If loading is slow, measure board-open to rendered-content readiness on repeated equivalent
+   workloads. Include a text-only control; record payload sizes, cache conditions and whether
+   measurements used a local connection or the user's host. Separate observations from causes.
+
+Report coverage, unresolved issues and storage requirements. Distinguish an import workaround
+from a product fix, and a source snapshot from live synchronization. Keep private source paths,
+names and content out of reusable skills and public issue reports.

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.0**, 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.0
 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.0` 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.0", "--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.0", "--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.0 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,41 @@ 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');
     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 +146,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',