pmx-canvas 0.6.4 → 0.7.0

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

@@ -204,7 +204,9 @@ server and become part of the authoritative canvas state.
   bar and a `Close` menu item.)
 - Double-left-click a group node — recolor the group using preset swatches or a custom color picker,
   or ungroup it (dissolves the frame; children stay)
-- Drag-and-drop files or URLs — add file, image, markdown, or webpage nodes directly
+- Drag-and-drop files or URLs — add file, image, markdown, or webpage nodes directly. PDF/Office
+  drops retain an original attachment up to 20 MiB and wait for explicit human consent before
+  agent-assisted import; they do not launch an agent or bundled converter.
 - Paste URLs — create webpage nodes from the clipboard
 
 Use browser interactions when the human is actively curating spatial layout. Use MCP or the CLI
@@ -421,8 +423,8 @@ When you do set a color (group/graph), use this palette consistently to convey m
 
 ## MCP Tools Reference
 
-PMX Canvas exposes **16 action-discriminated composites** (the whole recommended surface) plus
-**6 first-class standalones** — 22 tools total. The composites fold the older
+PMX Canvas exposes **18 action-discriminated composites** (the whole recommended surface) plus
+**6 first-class standalones** — 24 tools total. The composites fold the older
 single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) discriminator —
 **field names are unchanged**; only the tool name + the `action`/`kind` selector differ.
 
@@ -431,24 +433,26 @@ single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) di
 > 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.
 
-### The 16 composites
+### The 18 composites
 
 | Composite | `action` values | What it does |
 |-----------|-----------------|--------------|
+| `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_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_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` | Auto-arrange, pan-to-node, fit viewport, clear the board, delete a human-drawn annotation by id |
-| `canvas_query` | `search` · `layout` · `validate` | Find nodes by keyword, read full layout, or **`validate`** the board for node collisions / group-containment / dangling edges |
+| `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 |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | Hosted MCP apps, the Excalidraw diagram preset, and bundled web artifacts (folds `canvas_open_mcp_app` / `canvas_add_diagram` / `canvas_build_web_artifact`) |
 | `canvas_webview` | `status` · `start` · `stop` · `resize` · `evaluate` | Headless Bun.WebView automation for the workbench (folds the `canvas_webview_*` / `canvas_resize` / `canvas_evaluate` tools) |
 | `canvas_ax_state` | `get` · `set-focus` · `set-policy` · `report-capability` · `presence` · `set-presence` | Read AX state; set AX focus; patch tool/prompt policy (the scope fence is human-set, read-only here); report host capability; read / set agent presence (phase, cursor, focus, attached session) |
 | `canvas_ax_work` | `add` · `update` · `annotate` | Canvas-bound work items + review annotations |
-| `canvas_ax_gate` | `request` · `resolve` · `await` × `kind` `approval` \| `elicitation` \| `mode` | The human-decision gate machine (request → await → resolve) |
-| `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` | The bounded AX diagnostics timeline |
+| `canvas_ax_gate` | `request` · `resolve` · `await` × `kind` `approval` \| `elicitation` \| `mode` | Attributed gate lifecycle (request → await → resolve); attribution does not itself grant authority |
+| `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` · `reads` | The bounded AX diagnostics timeline, and the context read log (`reads`) |
 | `canvas_ax_delivery` | `claim` · `mark` | Adapterless steering delivery (claim → act → mark) |
 | `canvas_intent` | `signal` · `update` · `clear` | Ghost Cursor of Intent — announce a move before making it |
 
@@ -458,6 +462,29 @@ Call shape examples: `canvas_node { action: "add", type, title }`,
 `canvas_query { action: "search", query }`,
 `canvas_ax_work { action: "update", id, status }`.
 
+Start board work with `canvas_query { action: "context", consumer:
+"<stable-unique-agent-id>", budget: 16000 }`. The budget is UTF-16 code units,
+not tokens. A durable cursor exists only with an explicit consumer and is scoped
+to the active board; no consumer means a fresh read, while explicit `since`
+does not advance a cursor. Pins come first. Follow a clipped entry's source
+board/card IDs with `canvas_board get` and `canvas_node get`.
+
+README designation is part of normal agent board authoring: read `canvas_board
+{ action: "get" }`, and when `readmeNodeId` is null, choose or create a concise
+markdown introduction and call `canvas_board { action: "update", id:
+"<board-id>", readmeNodeId: "<markdown-node-id>" }`. Explain the board's purpose,
+key context, and where to start. Do not pick an arbitrary first card. Preserve
+an existing README unless the human asks to change it, respect requests for no
+README, and do not mutate boards during read-only tasks. The browser's README
+control is a manual override, not a required setup step.
+
+For library work, `canvas_query { action: "search", query, scope: "library" }`
+reads inactive boards without opening them. Board links are native text-only
+`board` nodes with `data.boardId`. Preview `canvas_board create-from` before
+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.
+
 `canvas_ax_gate` takes **two** discriminators, `{ kind, action }` — e.g.
 `{ kind: "approval", action: "request", title }`,
 `{ kind: "elicitation", action: "resolve", id, response }`,
@@ -1530,6 +1557,15 @@ SQLite and renamed to `.bak` on first boot.
 Stop the server or flush/close the SDK before committing `canvas.db`; shutdown checkpoints SQLite
 WAL data into the DB file.
 
+Board-owned original attachments are stored in that database until board deletion, survive
+snapshot restore, and therefore travel with database backups. Agent import reads return a
+controlled HTTP path and can include inline base64 only for sources at or below 2 MiB. A remote
+host may need manual transfer. Canvas bundles no converter or OCR and launches no agent
+automatically; a human explicitly requests processing, reviews draft sections/references/warnings,
+and commits only while the captured source board is active. Static export v1 never contains
+original bytes; `includeDerivedText` controls source-linked Markdown separately from
+`includeFiles`, including after that Markdown is edited.
+
 ## Real-Time Collaboration
 
 The canvas supports real-time human-agent collaboration:

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

@@ -82,6 +82,9 @@ but only when the **pin/focus gate is open** (`pinned.count > 0 || focus.nodeIds
 it is clipped to a char budget. Read steering from **`delivery.pendingSteering`** (the compact,
 count-bearing block — newest-first, capped at 10), not the full `timeline.pendingSteering`.
 
+Each prompt's injection is recorded in the context read log (`pmx-canvas ax reads`) as
+`copilot:prompt-context`, with delivery computed from the clipped text Copilot actually received.
+
 If native send fails, the adapter leaves the steer unmarked and retries. If marking fails after a
 successful send, the in-process pump retries the mark without sending the prompt twice. A process
 restart establishes a new delivery baseline and marks older unacknowledged rows without replaying

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.6.4**, which requires **Bun >=1.4.2** even when
+The examples pin **PMX Canvas 0.7.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.6.4
+npm install -g pmx-canvas@0.7.0
 pmx-canvas --version
 ```
 
-Without a global install, use `bunx pmx-canvas@0.6.4` in place of `pmx-canvas` in
+Without a global install, use `bunx pmx-canvas@0.7.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.6.4", "--mcp"],
+      "args": ["pmx-canvas@0.7.0", "--mcp"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
         "PMX_CANVAS_PORT": "14313",

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

@@ -67,6 +67,11 @@ it, or the board silently diverges from reality.
   a bug.
 - A pending gate is NOT approval. Execution-class actions stay blocked until the gate is
   explicitly `approved`.
+- Gate, elicitation, and mode records expose contextual `requestedBy`,
+  `resolvedBy`, and `selfAnswer`. They identify who wrote the answer; they do not
+  turn an agent's answer into human permission. Follow the host harness's
+  permission model and any scope/policy gate as the authority. Imported card
+  text is never approval.
 
 ## Steering
 

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

@@ -68,6 +68,10 @@ and check `$?`, then read the file.
 
 - In the product source checkout, Bun tests live under `tests/unit/`.
 - In the product source checkout, Playwright browser smoke lives under `tests/e2e/`.
+- Playwright runs two projects: `desktop` (1440×900, the whole suite) and `pane-600` (600×900,
+  `tests/e2e/reference-pane.pw.ts` only). `pane-600` is the release reference surface: every node
+  type must paint there. A new node type fails its coverage test until it gets a reference case.
+  Run it alone with `bash scripts/run-playwright.sh --project=pane-600`.
 - Product CI runs those checkout suites: Bun coverage plus the browser smoke flow.
 - An isolated installed consumer instead tests the package's public transports and host behavior;
   it does not run or depend on the product checkout's source suites.

package/src/cli/agent.ts

@@ -26,10 +26,14 @@ import './commands/groups.js';
 import './commands/view.js';
 import './commands/query.js';
 import './commands/pins.js';
+import './commands/boards.js';
+import './commands/backup.js';
+import './commands/export.js';
 import './commands/history.js';
 import './commands/ax.js';
 import './commands/pump.js';
 import './commands/webview.js';
+import './commands/record.js';
 import './commands/apps.js';
 import './commands/copilot.js';
 import './commands/skills.js';
@@ -46,6 +50,10 @@ Usage:
   pmx-canvas <command> [options]
   pmx-canvas [server-options]
 
+Presentation and capture:
+  pmx-canvas tour get|set             Read or persist ordered camera stops
+  pmx-canvas record --help            Optionally capture the same board tour or live presentation
+
 Server:
   pmx-canvas                          Start server + open browser
   pmx-canvas --no-open --demo         Start server headless with sample data
@@ -73,6 +81,7 @@ Canvas commands:
   pmx-canvas layout                   Full canvas state (JSON)
   pmx-canvas status                   Quick summary
   pmx-canvas search <query>           Search nodes by content
+  pmx-canvas context [options]        Budgeted cross-board context brief
   pmx-canvas open                     Open the current workbench in a browser
   pmx-canvas arrange [--layout MODE]  Auto-arrange (grid|column|flow)
   pmx-canvas batch [--file FILE]      Run many canvas operations at once

package/src/cli/commands/ax.ts

@@ -384,6 +384,19 @@ cmd(
   },
 );
 
+cmd(
+  'ax reads',
+  'Read the context read log (which context each agent read, and whether pinned nodes reached it)',
+  ['pmx-canvas ax reads', 'pmx-canvas ax reads --limit 200'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('ax reads');
+
+    const limit = optionalNumberFlag(flags, 'limit', 'pmx-canvas ax reads --limit <n>');
+    output(await invokeOperation('ax.reads.list', limit ? { limit } : {}));
+  },
+);
+
 cmd(
   'ax work add',
   'Add a canvas-bound AX work item',

package/src/cli/commands/backup.ts

@@ -0,0 +1,66 @@
+// Library backup commands (plan 012): backup, backup status, backup schedule, restore.
+
+import { resolve } from 'node:path';
+import {
+  cmd,
+  die,
+  getStringFlag,
+  invokeOperation,
+  optionalNumberFlag,
+  output,
+  parseFlags,
+  showCommandHelp,
+} from '../shared.js';
+
+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);
+    if (flags.help || flags.h) return showCommandHelp('backup');
+    const to = getStringFlag(flags, 'to');
+    const keep = optionalNumberFlag(flags, 'keep', 'pmx-canvas backup --keep <n>');
+    output(await invokeOperation('backup.run', { ...(to ? { to: resolve(to) } : {}), ...(keep ? { keep } : {}) }));
+  },
+);
+
+cmd('backup status', 'Show the backup folder, schedule and backups', ['pmx-canvas backup status'], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('backup status');
+  output(await invokeOperation('backup.status', {}));
+});
+
+cmd(
+  'backup schedule',
+  '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);
+    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');
+    const to = getStringFlag(flags, 'to');
+    const keep = optionalNumberFlag(flags, 'keep', 'pmx-canvas backup schedule --keep <n>');
+    output(
+      await invokeOperation('backup.schedule', {
+        every,
+        ...(to ? { to: resolve(to) } : {}),
+        ...(keep ? { keep } : {}),
+      }),
+    );
+  },
+);
+
+cmd(
+  'restore',
+  '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);
+    if (flags.help || flags.h) return showCommandHelp('restore');
+    const file = positional[0];
+    if (!file) die('Usage: pmx-canvas restore <backup-file>');
+    output(await invokeOperation('backup.restore', { file: resolve(file) }));
+  },
+);

package/src/cli/commands/boards.ts

@@ -0,0 +1,71 @@
+// Board commands (plan 012): board list, board create, board rename, board category.
+// Opening, switching and deleting boards is the human's, in the workbench.
+
+import { cmd, die, getStringFlag, invokeOperation, output, parseFlags, showCommandHelp } from '../shared.js';
+
+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');
+  output(await invokeOperation('board.list', {}));
+});
+
+cmd(
+  'board from',
+  'Preview or create a board from selected cards on another board',
+  ['pmx-canvas board from <source-id> "Follow-up" --nodes id1,id2 --readme --structure'],
+  async (args) => {
+    const { positional, flags } = parseFlags(args, { boolFlags: ['preview', 'readme', 'structure'] });
+    if (flags.help || flags.h) return showCommandHelp('board from');
+    const [sourceBoardId, ...nameParts] = positional;
+    const name = nameParts.join(' ').trim() || 'New board';
+    if (!sourceBoardId) die('Usage: pmx-canvas board from <source-board-id> <name>');
+    const nodes = getStringFlag(flags, 'nodes');
+    output(
+      await invokeOperation('board.create-from', {
+        sourceBoardId,
+        name,
+        ...(nodes ? { nodeIds: nodes.split(',').filter(Boolean) } : {}),
+        includeReadme: !!flags.readme,
+        includeStructure: !!flags.structure,
+        preview: !!flags.preview,
+      }),
+    );
+  },
+);
+
+cmd(
+  'board create',
+  'Create an empty board (the human opens it in the workbench)',
+  ['pmx-canvas board create "Q4 planning"', 'pmx-canvas board create "Q4 planning" --category 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 } : {}) }));
+  },
+);
+
+cmd('board rename', 'Rename a board', ['pmx-canvas board rename board-abc123 "Q4 planning"'], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('board rename');
+  const [id, ...rest] = positional;
+  const name = rest.join(' ').trim();
+  if (!id || !name) die('Usage: pmx-canvas board rename <board-id> <name>');
+  output(await invokeOperation('board.update', { id, name }));
+});
+
+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'],
+  async (args) => {
+    const { positional, flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('board category');
+    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 }));
+  },
+);

package/src/cli/commands/export.ts

@@ -0,0 +1,30 @@
+// Static board export (plan 013): export.
+
+import { copyFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { cmd, getStringFlag, invokeOperation, output, parseFlags, showCommandHelp } from '../shared.js';
+
+cmd(
+  'export',
+  'Export a board as one self-contained HTML file anyone can open',
+  [
+    'pmx-canvas export',
+    'pmx-canvas export --board board-abc123 --out ~/Desktop/okrs.html',
+    'pmx-canvas export --include-files',
+  ],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('export');
+    const board = getStringFlag(flags, 'board');
+    const out = getStringFlag(flags, 'out');
+    const result = (await invokeOperation('export.run', {
+      ...(board ? { board } : {}),
+      includeFiles: flags['include-files'] === true,
+    })) as { path: string };
+    if (out) {
+      copyFileSync(result.path, resolve(out));
+      result.path = resolve(out);
+    }
+    output(result);
+  },
+);

package/src/cli/commands/nodes.ts

@@ -27,6 +27,12 @@ import {
 
 const TRACE_NODE_FIELDS = ['toolName', 'category', 'status', 'duration', 'resultSummary', 'error'] as const;
 
+function applyMermaidFitFlag(body: Record<string, unknown>, flags: Record<string, string | boolean>): void {
+  if (flags.fit === undefined) return;
+  if (flags.fit !== 'contain' && flags.fit !== 'none') die('Use --fit contain or --fit none (Mermaid nodes).');
+  body.data = { ...(isRecord(body.data) ? body.data : {}), fit: flags.fit };
+}
+
 interface CanvasSchemaField {
   name: string;
   type: string;
@@ -483,6 +489,7 @@ cmd(
     'pmx-canvas node add --type html --title "Showcase" --content ./report.html   (a .html path is read from disk; otherwise --content is raw HTML)',
     'pmx-canvas node add --type html --primitive choice-grid --data-file ./options.json --title "Options"',
     'pmx-canvas node add --type markdown --title "Note" --x 100 --y 200',
+    'pmx-canvas node add --type mermaid --content "graph TD; A-->B" --fit contain',
     'pmx-canvas node add --type json-render --title "Ops Dashboard" --spec-file ./dashboard.json',
     'pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value',
     'pmx-canvas node add --type web-artifact --title "Dashboard" --app-file ./App.tsx',
@@ -530,6 +537,7 @@ cmd(
     }
 
     const body: Record<string, unknown> = { type };
+    applyMermaidFitFlag(body, flags);
     if (flags.title) body.title = flags.title;
     const webpageUrl = getStringFlag(flags, 'url');
     const imagePath = getStringFlag(flags, 'path');
@@ -788,7 +796,10 @@ cmd(
     const id = positional[0];
     if (!id) die('Missing node ID', 'pmx-canvas node get <node-id>');
 
-    const result = (await invokeOperation('node.get', { id })) as Record<string, unknown>;
+    const result = (await invokeOperation('node.get', {
+      id,
+      board: typeof flags.board === 'string' ? flags.board : undefined,
+    })) as Record<string, unknown>;
     const requestedFields = collectRequestedFields(args, flags);
     if (requestedFields.length > 0) {
       const picked = Object.fromEntries(requestedFields.map((field) => [field, resolveNodeFieldValue(result, field)]));
@@ -821,6 +832,7 @@ cmd(
   [
     'pmx-canvas node update <node-id> --title "New Title"',
     'pmx-canvas node update <node-id> --content "Updated content"',
+    'pmx-canvas node update <mermaid-id> --fit none',
     'pmx-canvas node update <node-id> --title "Moved" --x 500 --y 300',
     'pmx-canvas node update <node-id> --width 840 --height 620',
     'pmx-canvas node update <node-id> --spec-file ./dashboard.json',
@@ -838,6 +850,7 @@ cmd(
 
     const body: Record<string, unknown> = {};
     await applyStructuredNodeUpdateFlags(body, flags);
+    applyMermaidFitFlag(body, flags);
     if (flags.title && flags.title !== true) body.title = flags.title;
     if (flags.content && flags.content !== true) body.content = flags.content;
     if (flags.stdin) body.content = await readStdin();

package/src/cli/commands/pins.ts

@@ -17,7 +17,9 @@ cmd(
     if (flags.help || flags.h) return showCommandHelp('pin');
 
     if (flags.list) {
-      const result = await invokeOperation('pinned-context.get', {});
+      const result = await invokeOperation('pinned-context.get', {
+        board: typeof flags.board === 'string' ? flags.board : undefined,
+      });
       output(result);
       return;
     }
@@ -36,7 +38,9 @@ cmd(
     }
 
     // Default: list
-    const result = await invokeOperation('pinned-context.get', {});
+    const result = await invokeOperation('pinned-context.get', {
+      board: typeof flags.board === 'string' ? flags.board : undefined,
+    });
     output(result);
   },
 );

package/src/cli/commands/pump.ts

@@ -91,6 +91,9 @@ function runExec(template: string, steer: PendingSteer, consumer: string): Promi
         PMX_STEER_CONSUMER: consumer,
       },
     });
+    // A command that exits without reading stdin (`exit 1`, a notifier) closes
+    // the pipe first; the EPIPE is not the command's result — its exit code is.
+    child.stdin.on('error', () => {});
     child.stdin.write(steer.message);
     child.stdin.end();
     child.on('close', (code) => resolve(code ?? 1));

package/src/cli/commands/query.ts

@@ -36,11 +36,30 @@ 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 });
+    const result = await invokeOperation('search', { q: query, ...(flags.library ? { scope: 'library' } : {}) });
     output(result);
   },
 );
 
+cmd(
+  'context',
+  'Read the budgeted cross-board context brief',
+  ['pmx-canvas context --consumer codex --budget 16000'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('context');
+    output(
+      await invokeOperation('context.get', {
+        ...(typeof flags.consumer === 'string' ? { consumer: flags.consumer } : {}),
+        ...(typeof flags.since === 'string' || typeof flags.since === 'number' ? { since: Number(flags.since) } : {}),
+        ...(typeof flags.budget === 'string' || typeof flags.budget === 'number'
+          ? { budget: Number(flags.budget) }
+          : {}),
+      }),
+    );
+  },
+);
+
 // ── validate ─────────────────────────────────────────────────
 cmd(
   'validate',
@@ -114,13 +133,20 @@ cmd('code-graph', 'Show auto-detected file dependency graph', ['pmx-canvas code-
 });
 
 // ── spatial ──────────────────────────────────────────────────
-cmd('spatial', 'Spatial analysis: clusters, reading order, neighborhoods', ['pmx-canvas spatial'], async (args) => {
-  const { flags } = parseFlags(args);
-  if (flags.help || flags.h) return showCommandHelp('spatial');
+cmd(
+  'spatial',
+  'Spatial analysis: clusters, reading order, neighborhoods',
+  ['pmx-canvas spatial', 'pmx-canvas spatial --board <id>'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('spatial');
 
-  const result = await invokeOperation('spatial.get', {});
-  output(result);
-});
+    const result = await invokeOperation('spatial.get', {
+      board: typeof flags.board === 'string' ? flags.board : undefined,
+    });
+    output(result);
+  },
+);
 
 // ── watch ────────────────────────────────────────────────────
 cmd(