pmx-canvas 0.6.4 → 0.7.0

package/docs/cli.md

@@ -8,11 +8,109 @@ 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
 ```
 
+## Tour and presentation
+
+This is the small tour slice of the [vision's “board is the presentation”](product-vision-2026-09.md#12-tours-the-board-is-the-presentation-m):
+the existing cards remain the content, rather than being rebuilt as a separate deck.
+The same stops and camera interpolation drive interactive presentation and optional capture.
+A visual stop editor and carrying tours into static exports/share links are not implemented here.
+
+Click **Present** in the top bar, or open `/workbench?present=1` for a chrome-free
+embedded/capture view. Right/Down/Space advances, Left/Up goes back, Esc exits.
+The camera is local to the viewer; board content continues updating over SSE.
+Stops do not auto-advance. Missing targets show an error and can be skipped.
+
+Save this as `tour.json` (replace the IDs with IDs from `pmx-canvas node list`):
+
+```json
+{
+  "stops": [
+    { "target": { "nodeId": "overview-group" }, "duration": 1.5, "padding": 60 },
+    { "target": { "nodeId": "detail-note" }, "duration": 2, "easing": "ease-in-out", "pullback": 0.7 },
+    { "target": { "viewport": { "x": 80, "y": 100, "scale": 0.5 } }, "duration": 1 }
+  ]
+}
+```
+
+```bash
+pmx-canvas tour set --file tour.json
+pmx-canvas tour get
+```
+
+A stop targets either a node ID (including a group ID) or an explicit viewport.
+Viewport translation is screen-space: `screen = world * scale + offset`.
+`duration` is transition time in seconds (default 1, zero jumps); `padding` is
+screen pixels around a target (default 40). Easing is `linear`, `ease-in-out`
+(default), or `ease-out`. Zoom interpolates logarithmically about the moving
+world-space centre. `pullback` (0–4, default 0) subtracts a sinusoidal log-zoom
+offset mid-move without changing endpoints. Tours allow at most 1000 stops.
+
+Tours persist with the board and snapshots, participate in undo, and clear with
+the board. A file containing `null` resets the tour: when none is saved, groups
+are sorted by y, then x, then ID. A saved empty `stops` array deliberately has no
+stops. SDK: `canvas.setTour(tourOrNull)` / `canvas.getTour()`.
+
+### Optional capture of the same tour
+
+`record` is an optional local utility, not a second presentation model. It reads
+the saved/derived tour, or the identical tour JSON supplied with `--tour-file`.
+Start the server first. Capture launches its own Bun.WebView Chrome session;
+it does not replace a server automation session or move other viewers' cameras.
+
+```bash
+# Capture the saved/derived board tour
+pmx-canvas record --mode deterministic --present --fps 30 --resolution 1920x1080 --output tour.mp4
+
+# Try the same tour model from a file without changing the saved tour
+pmx-canvas record --mode deterministic --tour-file tour.json --present --output frames
+
+# Alternatively, sample the live presentation while agents update the board
+pmx-canvas record --duration 10 --present --theme light --output activity.mp4
+
+# Keep recording until SIGINT (Ctrl+C) or SIGTERM, then encode
+pmx-canvas record --stop-on-signal --output live.mp4
+```
+
+Options: `--mode realtime|deterministic` (default realtime), `--resolution WIDTHxHEIGHT`
+(default 1280x720), `--fps` (1–120, default 30), `--theme`, `--present`,
+`--duration SECONDS` or `--stop-on-signal` for realtime, `--tour-file FILE`
+for deterministic mode, `--chrome-path PATH`, and required `--output PATH`.
+Global `--port` / `--server-url` work here too. Existing output paths are refused.
+
+An `.mp4` output uses ffmpeg/H.264; any other path is a PNG sequence directory.
+Frames and `recording.json` are retained at `<output>.frames` even after video
+encoding. If ffmpeg is missing, the command clearly reports the PNG fallback
+and returns that directory. Encoding failures retain frames and exit nonzero.
+
+Deterministic mode resolves target geometry once and writes
+`max(1, ceil(duration × fps))` frames per stop, including each endpoint. It sets
+the camera, waits for two animation frames, checks the applied camera, then
+captures. Duplicate a target to hold it. This makes **camera timing** deterministic,
+not animated iframe content, fonts loaded later, network assets, or concurrent
+board edits. Realtime mode samples the live board; slow captures repeat frames
+to preserve wall-clock speed, with the repeated-frame count in `recording.json`.
+Capture has no audio. Chrome and a Bun runtime with WebView support are required.
+Recording is a local CLI/file operation, not a remote HTTP/MCP file-writing API;
+HTTP/MCP manage tours and retain their existing screenshot/automation surfaces.
+
 ## pump — reactive steering for CLI agents
 
 `pmx-canvas pump` turns any CLI agent (Codex, Amp, a script) into a steerable
@@ -99,6 +197,10 @@ pmx-canvas node update <node-id> --width 840 --height 620
 pmx-canvas node update <node-id> --title "Renamed" --full
 ```
 
+Mermaid `node add` and `node update` accept `--fit contain|none`, stored as
+`data.fit`. Contain is the default and shrinks only overflowing diagrams;
+none keeps 100% with scrolling. [Sizing and readability](node-types.md#mermaid-nodes).
+
 `--from-search` / `--to-search` must each resolve to exactly one node — broad
 queries fail rather than guess. Use the full visible title.
 
@@ -173,6 +275,48 @@ 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)
+```
+
 ## Snapshots
 
 ```bash
@@ -186,6 +330,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.
@@ -209,6 +365,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

@@ -9,14 +9,207 @@ bodies are treated as an empty request. As of 0.4.0 every error response is a
 JSON envelope of that same shape (`{ ok: false, error }`, status unchanged) —
 no plain-text errors remain.
 
+Node-create responses include `sizeAdjustment` when a frame dimension was
+defaulted or raised to its node type's readability floor. It contains the
+`requested` dimensions (`null` when omitted), the final `applied` dimensions,
+and a `reason` (`defaulted`, `clamped-to-minimum`, or
+`defaulted-and-clamped-to-minimum`; groups also use `fit-to-children`). `strictSize: true`
+still bypasses the readability clamp, but omitted dimensions are reported as
+defaulted. MCP create actions return the same size report.
+Updates preserve explicit dimensions without applying creation floors; their
+returned node `size` is the applied size. Omitted update dimensions retain the
+existing size and are not reported as defaulted adjustments.
+
+Both group-create routes report defaults or final child-derived dimensions, including
+when children override supplied width/height because x/y were omitted. Explicit manual
+frames retain their existing semantics. Group child replacement reports `fit-to-children`
+when it changes the frame; `group.add` reports the previous frame as `requested` and
+the final frame as `applied`. Reports survive compact/full MCP and batch responses.
+External MCP app creation and web-artifact builds that open a node report their default
+frames too; reusing an existing app node or building without opening does not report a
+creation default. These reports describe the synchronous operation, not later browser
+content auto-height or indirect parent-group reflow after editing a child.
+
+## Board tours
+
+- `GET /api/canvas/tour` → `{ tour: { stops: [...] }, derived: boolean }`.
+- `POST /api/canvas/tour` with `{ "tour": { "stops": [...] } }` persists the tour;
+  `{ "tour": null }` resets to derived group reading order. Returns `{ "ok": true }`.
+- `GET /api/canvas/state` includes optional `tour`. Tour writes broadcast a layout
+  update and are included in snapshots/undo. They are board-wide writes under a scope fence.
+
+The [tour model and recording walkthrough](cli.md#tour-and-presentation) describes
+targets, duration, easing, padding, and pullback. Open `/workbench?present=1` to hide
+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
@@ -35,6 +228,10 @@ curl -X POST http://localhost:4313/api/canvas/json-render \
   -H "Content-Type: application/json" \
   -d '{"title":"Panel","nodeHeight":280,"spec":{"root":"card","elements":{"card":{"type":"Card","props":{"title":"Live"},"children":[]}}}}'
 
+# For graph nodes, `height` is the chart's plot height, not the node frame.
+# Set the frame with `nodeHeight` (`heightPx` in the SDK). A graph request that
+# supplies only `height` gets the default frame height and a response warning.
+
 # Validate an HTML primitive without creating a node
 curl -X POST http://localhost:4313/api/canvas/schema/validate \
   -H "Content-Type: application/json" \
@@ -70,6 +267,16 @@ 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%
+with scrolling. [Mermaid sizing and readability](node-types.md#mermaid-nodes).
+
 ### File node content and bytes
 
 A `file` node reads its file server-side. Text is stored on the node as
@@ -145,6 +352,31 @@ curl -X DELETE http://localhost:4313/api/canvas/annotation/ann-123
 Agent-readable context reports annotation IDs, targets, and bounds. Use WebView
 inspection or screenshots when the drawn shape matters.
 
+## Viewport
+
+```bash
+# Set the camera transform (screen = world * scale + {x,y})
+curl -X POST http://localhost:4313/api/canvas/viewport \
+  -H "Content-Type: application/json" \
+  -d '{"x":64,"y":96,"scale":0.8}'
+
+# Fit selected nodes (omit nodeIds to fit the whole canvas)
+curl -X POST http://localhost:4313/api/canvas/fit \
+  -H "Content-Type: application/json" \
+  -d '{"nodeIds":["node-1"],"width":1200,"height":700}'
+
+# Focus without moving the camera
+curl -X POST http://localhost:4313/api/canvas/focus \
+  -H "Content-Type: application/json" \
+  -d '{"id":"node-1","noPan":true}'
+```
+
+Viewport `x`/`y`, fit `width`/`height`, and fit padding are interpreted against
+the **canvas area**, excluding the tool rail, top bar, and other surrounding
+page chrome—not the full browser window. Camera, fit, and focus-only requests
+do not create or refresh agent writer presence. Use the explicit presence API
+when an agent should publish a cursor or `focusNodeId`.
+
 ## Pins
 
 ```bash
@@ -155,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
@@ -208,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" \
@@ -341,13 +605,20 @@ When that session ends (`attached: false`, `session-end`, or the idle expiry)
 the stream carries one `agent-session-ended` frame:
 
 ```json
-{ "label": "Copilot", "endedAt": "…", "counts": { "items": 4, "done": 3, "vetoed": 1 },
+{ "label": "Copilot", "parentAgentId": null, "endedAt": "…", "endedBy": "agent",
+  "unchanged": false, "counts": { "items": 4, "done": 3, "cancelled": 1, "rejected": 0, "held": 0 },
   "snapshot": { "id": "…", "name": "Before session · Copilot · 14:00" } }
 ```
 
-`items`/`done` count the work items on the board; `vetoed` counts cancelled
-items plus rejected or held gates. `snapshot` is null when the board was
-empty at attach. The browser renders this as the session receipt; its *View
+`items`/`done` count the work items on the board; cancelled items, rejected
+gates, and held gates have separate counts. `snapshot` is null when the board was
+empty at attach or unchanged at end (the redundant snapshot is removed).
+The browser shows a receipt only for a changed top-level session: `unchanged: true`
+and worker endings (`parentAgentId` set) never open or replace a popup. An empty
+board that stays empty is unchanged too. This only filters the popup: session-end
+events, timeline records, and changed-session snapshots remain available.
+There is at most one receipt, replaced by the next qualifying ending and kept until
+dismissed so restore/diff actions do not disappear on a timer. Its *View
 diff* is `GET /api/canvas/snapshots/<id>/diff` against that snapshot, and
 restoring the snapshot undoes the session. Adapters should end their session
 explicitly so the human gets the receipt promptly rather than after the idle