pmx-canvas 0.6.5 → 0.7.1

package/dist/types/server/operations/ops/ax-shared.d.ts

@@ -16,14 +16,14 @@ export declare const AX_SOURCES: readonly ["agent", "amp", "api", "browser", "cl
 export declare const AX_SOURCE_SHAPE: z.ZodOptional<z.ZodEnum<{
     amp: "amp";
     agent: "agent";
+    system: "system";
+    sdk: "sdk";
     api: "api";
     browser: "browser";
     cli: "cli";
     codex: "codex";
     copilot: "copilot";
     mcp: "mcp";
-    sdk: "sdk";
-    system: "system";
 }>>;
 /** Zod schema for the optional `agentId` field shared by AX MCP tool shapes. */
 export declare const AX_AGENT_ID_SHAPE: z.ZodOptional<z.ZodString>;

package/dist/types/server/operations/ops/backup.d.ts

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const backupOperations: Operation[];

package/dist/types/server/operations/ops/boards.d.ts

@@ -0,0 +1,10 @@
+import { type CanvasLayout } from '../../canvas-state.js';
+import { type Operation } from '../types.js';
+export declare function boardsPayload(): Record<string, unknown>;
+/** Read a board without opening it. Omitted board preserves the active-board contract. */
+export declare function readTargetBoard(boardId?: unknown, includeBlobs?: boolean): {
+    boardId: string | null;
+    layout: CanvasLayout;
+    pinnedNodeIds: Set<string>;
+};
+export declare const boardOperations: Operation[];

package/dist/types/server/operations/ops/export.d.ts

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const exportOperations: Operation[];

package/dist/types/server/operations/ops/imports.d.ts

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const importOperations: Operation[];

package/dist/types/server/operations/ops/nodes.d.ts

@@ -1,7 +1,7 @@
 import { type CanvasLayout, type CanvasNodeState } from '../../canvas-state.js';
 import { type CanvasSizeAdjustment } from '../../canvas-operations.js';
 import { type Operation } from '../types.js';
-export declare const NODE_TYPES: readonly ["markdown", "status", "context", "ledger", "trace", "file", "diff", "mermaid", "image", "mcp-app", "webpage", "html", "group"];
+export declare const NODE_TYPES: readonly ["markdown", "board", "status", "context", "ledger", "trace", "file", "diff", "mermaid", "image", "mcp-app", "webpage", "html", "group"];
 /** Per-type default node frame size (formerly copy-pasted ladders). */
 export declare function defaultNodeSize(type: string): {
     width: number;

package/dist/types/server/operations/ops/query.d.ts

@@ -1,2 +1,4 @@
 import { type Operation } from '../types.js';
+export declare const DEFAULT_CONTEXT_BRIEF_BUDGET = 16000;
+export declare const MAX_CONTEXT_BRIEF_BUDGET = 100000;
 export declare const queryOperations: Operation[];

package/dist/types/server/operations/registry.d.ts

@@ -9,7 +9,7 @@ export declare function setOperationEventEmitter(emitter: OperationEventEmitter
  * mcpapp.open, whose canvas node is created as a side-effect of `ext-app-open` —
  * use this to reject loudly instead of silently no-op'ing in a suppressed run. */
 export declare function isEmitSuppressed(): boolean;
-/** Run `fn` with all operation SSE emits suppressed; restores depth on finally. */
+/** Suppress this call chain's per-entry frames; the batch emits its final frame afterward. */
 export declare function runWithSuppressedEmits<T>(fn: () => Promise<T>): Promise<T>;
 export interface ExecuteOperationMeta {
     /**
@@ -29,6 +29,14 @@ export interface ExecuteOperationMeta {
      * to agents only, and batch inner writes are always agent-originated.
      */
     fromWorkbench?: boolean;
+    /** Authorship only: true when the per-boot workbench token matched. */
+    humanAuthor?: boolean;
+    /**
+     * An MCP server attached to this daemon, or a host adapter, fetching on an
+     * agent's behalf. It records the read the agent actually made itself
+     * (POST /api/canvas/ax/context-reads), so this fetch is not recorded.
+     */
+    proxiedRead?: boolean;
 }
 export declare function executeOperation(name: string, rawInput: unknown, meta?: ExecuteOperationMeta): Promise<unknown>;
 export {};

package/dist/types/server/operations/types.d.ts

@@ -45,7 +45,7 @@ export interface OperationHttpRoute {
 }
 /** Host capabilities available to MCP result formatters. */
 export interface OperationMcpToolHost {
-    getPinnedNodeIds(): Promise<string[]>;
+    getPinnedNodeIds(board?: string): Promise<string[]>;
     /**
      * Invoke another registered operation over the host's transport (local or
      * HTTP) — structural subset of OperationInvoker to avoid an import cycle.

package/dist/types/server/server.d.ts

@@ -23,6 +23,7 @@
  * - POST /api/canvas/graph        -> create a native graph node
  * - GET  /api/canvas/json-render/view?nodeId=... -> local json-render viewer
  * - GET  /api/canvas/file-bytes?nodeId=... -> raw bytes for a file node
+ * - GET  /api/canvas/exports/<file>        -> a written static board export (sandboxed)
  * - POST /api/canvas/web-artifact -> build bundled HTML artifact + optional canvas node
  * - GET  /api/workbench/events   -> SSE event stream
  * - GET  /api/workbench/poll     -> proxy-safe polling transport (same events, JSON)

package/dist/types/server/trace-manager.d.ts

@@ -37,6 +37,13 @@ declare class TraceManager {
         durationMs?: number;
         failed?: boolean;
     }): void;
+    /**
+     * The chain's last node is gone (another board was opened, or it was
+     * deleted): start a new chain instead of wiring edges to a missing node.
+     */
+    private dropStaleChain;
+    /** Forget the trace chain without touching nodes. */
+    resetChain(): void;
     clearTrace(): void;
     getTraceNodeCount(): number;
     private getOrigin;

package/dist/types/server/webpage-node.d.ts

@@ -17,9 +17,30 @@ export interface WebpageSnapshot {
 }
 export declare function normalizeWebpageUrl(rawUrl: string): string;
 export declare function summarizeWebpageContent(data: Record<string, unknown>, maxLength?: number): string;
-export declare function fetchWebpageSnapshot(inputUrl: string): Promise<WebpageSnapshot>;
+export type AddressScope = 'public' | 'private' | 'link-local';
+/**
+ * Where an IP literal points. `private` covers loopback, RFC 1918, CGNAT and
+ * IPv6 ULA; `link-local` is kept apart because it holds cloud metadata
+ * (169.254.169.254) and is refused on every hop.
+ */
+export declare function classifyAddress(address: string): AddressScope;
+type ResolveHost = (hostname: string) => Promise<Array<{
+    address: string;
+    family: number;
+}>>;
+/**
+ * Refuses link-local on every hop, and a redirect that moves a public fetch
+ * onto a loopback or private address. A URL the caller points at a local dev
+ * server on purpose still loads, and may redirect within the local network.
+ */
+export declare function checkWebpageHop(originScope: AddressScope, hopScope: AddressScope, hopUrl: string): void;
+export declare function fetchWebpageSnapshot(inputUrl: string, options?: {
+    resolveHost?: ResolveHost;
+    timeoutMs?: number;
+}): Promise<WebpageSnapshot>;
 export declare function getWebpageFetchErrorDetails(error: unknown): {
     message: string;
     statusCode: number | null;
     contentType: string | null;
 };
+export {};

package/dist/types/server/workbench-auth.d.ts

@@ -0,0 +1,3 @@
+/** Per-process capability used only to distinguish workbench clicks from HTTP agents. */
+export declare const workbenchToken: string;
+export declare function isWorkbenchToken(value: string | null): boolean;

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

@@ -0,0 +1,6 @@
+/** The Home category migrated 0.6 snapshots land on, so they do not bury the boards in use. */
+export declare const MIGRATED_SNAPSHOT_CATEGORY = "From old snapshots";
+/** Slash-separated folder paths shared by the UI, HTTP/MCP and SDK. */
+export declare function normalizeBoardCategory(value: string | null): string | null;
+/** Includes implicit parents, so a board in A/B can also be moved into A. */
+export declare function categoryAncestors(path: string): string[];

package/docs/RELEASE.md

@@ -40,6 +40,11 @@ bun run pack:dry-run        # confirms the tarball shape
 do not call `bun x playwright test` directly; it fails before test
 discovery with a `.esm.preflight` loader error (ERR-20260508-001).
 
+The Playwright run includes the `pane-600` project
+(`tests/e2e/reference-pane.pw.ts`): the reference surface, Chromium at
+600 px. Every node type must paint there or the release does not ship.
+Embedded WebKit panes (the Copilot app) stay best-effort.
+
 `bun run test:e2e-cli` starts a local server in a fresh temp workspace
 and exercises the CLI flows from
 [`docs/evals/e2e-cli-coverage.md`](evals/e2e-cli-coverage.md).

package/docs/cli.md

@@ -8,6 +8,19 @@ wins over `--port`, and both win over the environment variables). An invalid
 value for either flag is a hard error — the CLI never falls back silently to
 the default port.
 
+Read commands accept `--board <board-id>` without switching the active board:
+`layout` (including `--summary`), `status`, `spatial`, `pin --list`, and
+`node get`. Writes and presence still target the board open in the workbench;
+unknown board IDs fail rather than falling back to it.
+
+An in-flight asynchronous write stops if the board changes; subsequent calls use
+the newly open board. Batches stop rather than continuing on another board, and
+already-completed entries remain applied.
+
+On SIGINT or SIGTERM, the server saves before exiting. If saving fails, it reports
+the error and stays running so the in-memory edits can be recovered. Fix the
+storage failure and retry shutdown; a forced process kill can still lose edits.
+
 ```bash
 pmx-canvas node list --port 4750                      # target a non-default daemon
 pmx-canvas --server-url http://127.0.0.1:4750 status  # same, by URL
@@ -262,6 +275,53 @@ pmx-canvas fit <id-a> <id-b>          # Fit to just these nodes
 `--width` / `--height`. After creating output a human should see, focus a single
 node or fit the new ids — auto-placement is board-relative, not camera-relative.
 
+## Boards
+
+```bash
+pmx-canvas board list                          # most recently opened first; activeBoardId null = Home
+pmx-canvas board create "Q4 planning"          # created, not opened
+pmx-canvas board rename <board-id> "New name"
+pmx-canvas board create "Q4 planning" --category Planning
+pmx-canvas board category <board-id> "Planning/Quarterly" # nested folders; --clear unfiles it
+pmx-canvas board from <source-id> "Follow-up" --preview
+pmx-canvas board from <source-id> "Follow-up" --nodes id1,id2 --readme --structure
+```
+
+Commands write to the board open in the workbench. Opening, switching and
+deleting boards happens in the workbench (the human's call). `board from`
+excludes `prompt`, `response`, `trace`, and `mcp-app` cards; selected reusable
+cards get fresh IDs. `--structure` includes group frames; edges between copied
+cards are retained automatically. `--readme` carries the designated README. The new board remains inactive and
+does not inherit pins, AX state, or mutation history.
+
+## Backup and restore
+
+Boards save automatically. Backups are separate recovery copies of the whole library,
+configured through the CLI or HTTP API rather than the Home screen. Scheduled backups
+run while the server is running; scheduling is off until configured.
+
+```bash
+pmx-canvas backup                                   # every board, now; into .pmx-canvas/backups
+pmx-canvas backup --to ~/Backups/pmx --keep 14
+pmx-canvas backup schedule --every 24h --keep 14 --to ~/Backups/pmx   # run by the server
+pmx-canvas backup schedule --off
+pmx-canvas backup status
+pmx-canvas restore ~/Backups/pmx/canvas-20260927T090000000Z.db    # keeps canvas.db.before-restore
+```
+
+## Export
+
+```bash
+pmx-canvas export                                  # the open board → .pmx-canvas/exports/<board>-<time>.html
+pmx-canvas export --board <board-id> --out ~/Desktop/okrs.html
+pmx-canvas export --include-files                  # include local file contents (left out by default)
+pmx-canvas export --include-derived-text           # include imported document text (left out by default)
+```
+
+The two private-content flags are independent opt-ins. `--include-files` does not include
+source-derived document text, and `--include-derived-text` does not include local file contents.
+Unknown export flags are rejected instead of being ignored.
+
 ## Snapshots
 
 ```bash
@@ -275,6 +335,18 @@ pmx-canvas diff <snapshot-id>         # Compare the canvas against a snapshot
 
 ## AX context
 
+The cross-board brief has its own compact command. Its budget is measured in
+UTF-16 code units (default 16000, maximum 100000), not model tokens. `--consumer`
+selects a durable cursor scoped to the open board; `--since` performs an
+explicit pull without changing that cursor. With neither flag, every call starts
+from the beginning. Use a stable, unique consumer ID per agent/adapter; changing
+or sharing it loses or conflates delivery progress.
+
+```bash
+pmx-canvas context --consumer codex --budget 16000
+pmx-canvas context --since 42 --budget 8000
+```
+
 AX commands expose the host-agnostic context contract used by adapters. Pins
 remain the explicit human-curated context set; AX focus is the current
 attention target and persists with canvas state and snapshots.
@@ -298,6 +370,7 @@ pmx-canvas ax event add --kind tool-start --summary "ran tests"
 pmx-canvas ax steer "focus on the failing test first"
 pmx-canvas ax evidence add --kind test-output --title "unit pass"
 pmx-canvas ax timeline --limit 50
+pmx-canvas ax reads --limit 50   # context read log: which context each agent read, pinned delivery
 
 # Work items (canvas-bound)
 pmx-canvas ax work add --title "Wire up auth" --status in-progress node-1

package/docs/http-api.md

@@ -43,14 +43,173 @@ targets, duration, easing, padding, and pullback. Open `/workbench?present=1` to
 chrome; camera movement is local to that viewer. Recording writes local files via
 the CLI, not an HTTP job endpoint.
 
+## Boards
+
+A workspace holds many named boards; one is open at a time. Agent writes go to
+the open board. While no board is open (Home), the first write opens the most
+recently opened board, or creates one when the workspace has none;
+`canvas.clear` on Home opens nothing. Only the trusted workbench opens or
+deletes a board — HTTP calls require both `x-pmx-workbench: 1` and the
+per-boot `x-pmx-workbench-token` embedded in the served `/workbench` HTML;
+the marker alone is not authority. Public HTTP integrations must not open or
+delete boards. In-process SDK embedding hosts retain authority to do so.
+Every change emits a
+`boards-changed` SSE frame with `{ activeBoardId, boards }`.
+
+`category` is a folder path, for example `Engineering/Canvas/Decisions`.
+Home renders nested, collapsible folders and searches board names and paths.
+Paths support up to eight levels, each with 1–60 characters; surrounding spaces
+are trimmed. Empty segments and `.`/`..` are rejected. `null` or `""` unfiles a
+board. Folders are derived from boards, so empty folders do not persist. Moving
+a board changes its path, not its ID or content.
+
+```bash
+# List boards (most recently opened first) and which is open (null = Home)
+curl http://localhost:4313/api/canvas/boards
+
+# Read one board
+curl http://localhost:4313/api/canvas/boards/<board-id>
+
+# Create a board (optionally in a category) — it is NOT opened
+curl -X POST http://localhost:4313/api/canvas/boards \
+  -H "Content-Type: application/json" -d '{"name":"Q4 planning","category":"Planning"}'
+
+# Preview/create an inactive copy from reusable cards (preview false creates)
+curl -X POST http://localhost:4313/api/canvas/boards/from \
+  -H "Content-Type: application/json" \
+  -d '{"sourceBoardId":"board-source","name":"Follow-up","nodeIds":["node-1"],"includeReadme":true,"includeStructure":true,"preview":true}'
+
+# Rename and/or file under a category on Home ("category": "" removes it)
+curl -X PATCH http://localhost:4313/api/canvas/boards/<board-id> \
+  -H "Content-Type: application/json" -d '{"name":"Q4 planning (final)","category":"Planning"}'
+
+# Designate a Markdown card on this board as its README (null clears it)
+curl -X PATCH http://localhost:4313/api/canvas/boards/<board-id> \
+  -H "Content-Type: application/json" -d '{"readmeNodeId":"<markdown-node-id>"}'
+
+# Open a board, or Home with {"id":null} — workbench only
+curl -X POST http://localhost:4313/api/canvas/boards/open \
+  -H "Content-Type: application/json" -H "x-pmx-workbench: 1" \
+  -H "x-pmx-workbench-token: <token-from-served-workbench>" -d '{"id":"<board-id>"}'
+
+# Delete a board and its snapshots — workbench only; deleting the open board returns to Home
+curl -X DELETE http://localhost:4313/api/canvas/boards/<board-id> \
+  -H "x-pmx-workbench: 1" -H "x-pmx-workbench-token: <token-from-served-workbench>"
+```
+
+## Backup and restore
+
+A backup is one SQLite file holding every board, its snapshots and blobs,
+written with `VACUUM INTO` (safe while the server runs) to
+`canvas-<timestamp>.db` in the backup folder — by default `backups/` beside the
+database (`.pmx-canvas/backups`). Keeping the newest `keep` (default 14)
+removes older backups in that folder. The schedule is stored in the database
+and runs inside the server. Not exposed over MCP.
+
+```bash
+# Folder, schedule, last backup and the backups on disk
+curl http://localhost:4313/api/canvas/backup
+
+# Back up now (optional folder and keep)
+curl -X POST http://localhost:4313/api/canvas/backup \
+  -H "Content-Type: application/json" -d '{"to":"/Users/me/Backups/pmx","keep":14}'
+
+# Back up every 24h ("30m", "7d"; at least once a minute; "off" stops it)
+curl -X POST http://localhost:4313/api/canvas/backup/schedule \
+  -H "Content-Type: application/json" -d '{"every":"24h","keep":14,"to":"/Users/me/Backups/pmx"}'
+
+# Replace every board with a backup; the current file is kept as canvas.db.before-restore.
+# Refuses files that are not PMX Canvas databases, and the live database itself.
+curl -X POST http://localhost:4313/api/canvas/backup/restore \
+  -H "Content-Type: application/json" -d '{"file":"/Users/me/Backups/pmx/canvas-20260927T090000000Z.db"}'
+```
+
+## Static board export
+
+One self-contained, read-only HTML file of one board (pan, zoom, expand) that
+opens with no server or install. Cards render as escaped text; html cards,
+charts, diagrams and built apps run in sandboxed iframes, with viewer bundles
+stored once per file. Live MCP apps become placeholders; local file contents
+are left out unless `includeFiles` is true. Files are written to `exports/`
+beside the database. Built-app files are only embedded when they are regular,
+bounded-size files inside the board's owned `.pmx-canvas/artifacts/` directory.
+The preview manifest lists card links, remote images, and statically visible
+network destinations in embedded HTML. Imported source-linked Markdown is also
+excluded unless `includeDerivedText=true`, independently of `includeFiles`;
+editing it does not remove that classification. Original attachment bytes are
+never embedded in v1. Embedded scripts can make additional
+network requests that cannot be inventoried in advance. Not exposed over MCP —
+sharing is the human's act.
+
+```bash
+# What the file would contain (defaults to the open board; ?board=<id> for another)
+curl "http://localhost:4313/api/canvas/export/preview?includeFiles=false&includeDerivedText=false"
+
+# Write it → { path, url, bytes, manifest }
+curl -X POST http://localhost:4313/api/canvas/export \
+  -H "Content-Type: application/json" \
+  -d '{"board":"<board-id>","includeFiles":false,"includeDerivedText":false}'
+
+# Serve a written export (opaque-origin sandbox; ?download=1 as an attachment)
+curl "http://localhost:4313/api/canvas/exports/<file>.html?download=1" -o board.html
+```
+
+## Agent-assisted document imports
+
+PDF and Office uploads are raw bytes, not JSON. Upload requires the trusted
+workbench token, an active captured board, a non-empty body of at most 20 MiB,
+and creates both an original file card and an `attached` import. The original
+remains board-owned until board deletion; snapshot restore does not remove it,
+and whole-database backups include it.
+
+```bash
+curl -X POST \
+  "http://localhost:4313/api/canvas/attachments?boardId=<board-id>&name=report.pdf&mime=application/pdf&x=40&y=40" \
+  -H "x-pmx-workbench-token: <token>" --data-binary @report.pdf
+
+# Human-only: explicit consent asks the connected agent; captured board must be open
+curl -X POST http://localhost:4313/api/canvas/imports/<import-id>/request \
+  -H "Content-Type: application/json" -H "x-pmx-workbench: 1" \
+  -H "x-pmx-workbench-token: <token>" \
+  -d '{"consent":true}'
+
+# Agent reads metadata and a controlled byte path; inline=true adds base64 only <=2 MiB
+curl "http://localhost:4313/api/canvas/imports/<import-id>?inline=true"
+curl http://localhost:4313/api/canvas/attachments/<attachment-id>/bytes -o source.bin
+
+# Agent submits a reviewable draft (allowed even if another board is active)
+curl -X POST http://localhost:4313/api/canvas/imports/<import-id>/submit \
+  -H "Content-Type: application/json" \
+  -d '{"sections":[{"title":"Summary","markdown":"...","reference":"page 1"}],"warnings":[],"agentDescription":"Extracted with the connected host PDF reader"}'
+
+# Human-only review/commit; the original captured board must be open
+curl -X POST http://localhost:4313/api/canvas/imports/<import-id>/commit \
+  -H "x-pmx-workbench: 1" -H "x-pmx-workbench-token: <token>"
+```
+
+`GET /api/canvas/imports?boardId=...` lists jobs. An agent that cannot access or
+interpret the source posts `{ "reason": "..." }` to
+`/api/canvas/imports/:id/unavailable`; a human may later request a new attempt.
+Humans can cancel requested or drafted jobs at `/cancel`. There is no bundled
+converter, OCR, automatic agent launch, or guarantee for charts, scans, and
+host-specific formats. A remote agent may need the human/host to transfer the
+bytes before it can submit a draft.
+
 ## Canvas state
 
+Read endpoints accept an optional `board=<board-id>` query parameter without
+opening that board or changing where writes go. This is supported by
+`/api/canvas/state`, `/api/canvas/node/:id`, `/api/canvas/summary`,
+`/api/canvas/spatial-context`, and `/api/canvas/pinned-context`. Unknown boards
+return 404. Omit `board` to read the active board. Live AX session/delivery reads
+and fixed MCP resources continue to describe the open board.
+
 ```bash
 # Get canvas state
 curl http://localhost:4313/api/canvas/state
 
-# Search nodes (optional limit= caps the result count)
-curl "http://localhost:4313/api/canvas/search?q=auth&limit=10"
+# Search the library (omit scope for the active board)
+curl "http://localhost:4313/api/canvas/search?q=auth&limit=10&scope=library"
 
 # Validate the current layout
 curl http://localhost:4313/api/canvas/validate
@@ -108,6 +267,11 @@ A node creation request must resolve a `type` — pass it in the body (`{ "type"
 ... }`) or as a `?type=` query param. An empty / type-less body returns `400`
 rather than silently creating a markdown node.
 
+An optional `boardId` on node creation is a captured-board precondition, not a
+switch command: if it no longer matches the active board, the request returns
+`409` without creating a node or opening a board from Home. The file-drop UI
+uses this to prevent delayed uploads from landing on a different board.
+
 Mermaid nodes accept `data: { "fit": "contain" | "none" }` on both
 `POST /api/canvas/node` and `PATCH /api/canvas/node/:id`. The default, `contain`,
 shrinks overflowing diagrams without changing aspect ratio; `none` keeps 100%
@@ -223,14 +387,30 @@ curl -X POST http://localhost:4313/api/canvas/context-pins \
 
 # Get pinned context
 curl http://localhost:4313/api/canvas/pinned-context
+
+# Cross-board brief. budget is a UTF-16 character ceiling (default 16000, max 100000).
+# Without since, the board/consumer cursor advances through only fully delivered revisions.
+curl 'http://localhost:4313/api/canvas/context?consumer=codex&budget=16000'
 ```
 
+`consumer` is optional. Supply a stable unique value only for a durable,
+board-scoped cursor; without `consumer` or `since`, each request starts from the
+beginning. An explicit `since` never advances a cursor. The brief prioritizes
+pins, then relevant current-board changes and asks, then compact linked or
+same-folder board context. Every item carries source board/card IDs. If card text
+is clipped, use those IDs with the board/node read route rather than guessing
+from the excerpt. Reading inactive boards does not open them.
+
 ## AX context and focus
 
 AX context is the host-agnostic agent-experience layer. It combines existing
 context pins with a persisted focus node set that adapters can inject into
 their native prompt/context hooks.
 
+The context response includes `boardId` (`null` on Home), captured with its content
+and pins. Adapters should send that ID when recording a proxied context read, rather
+than looking up whichever board is active after delivery.
+
 ```bash
 # Get persisted AX state
 curl http://localhost:4313/api/canvas/ax
@@ -276,6 +456,22 @@ curl -X POST http://localhost:4313/api/canvas/ax/evidence \
 # Timeline — read the bounded timeline (default limit 50, max 200)
 curl "http://localhost:4313/api/canvas/ax/timeline?limit=50"
 
+# Context reads — which canvas context each agent read, and whether its pinned
+# nodes were in what came back (newest first, default 50, max 500; the per-consumer
+# summary covers the whole retained log of 5,000 reads). Agent reads of pinned
+# context, AX context, AX state, summary, spatial context and layout are recorded
+# automatically; the workbench's own reads are not.
+curl "http://localhost:4313/api/canvas/ax/context-reads?limit=50"
+
+# Context reads — a proxy (an MCP server attached to this daemon, a host adapter)
+# records the read its agent actually made. Its own fetches send
+# `x-pmx-proxied-read: 1` so they are not recorded twice.
+# Pass boardId captured at read time (null for Home); omitting it uses the
+# currently open board. MCP bytes measure the final formatted text response.
+curl -X POST http://localhost:4313/api/canvas/ax/context-reads \
+  -H "Content-Type: application/json" \
+  -d '{"channel":"adapter","resource":"copilot:prompt-context","consumer":"copilot","pinnedNodeIds":["node-1"],"deliveredNodeIds":["node-1"],"bytes":2048}'
+
 # Canvas-bound — add / update a work item
 curl -X POST http://localhost:4313/api/canvas/ax/work \
   -H "Content-Type: application/json" \