pmx-canvas 0.8.2 → 0.9.1

package/docs/api-reference.md

@@ -0,0 +1,109 @@
+## Canvas Types
+
+**Node types (18):** `markdown`, `status`, `context`, `ledger`, `trace`, `file`, `diff`, `image`, `html`, `mermaid`, `mcp-app`, `webpage`, `json-render`, `graph`, `group`, `board`, plus internal thread node types `prompt` and `response`
+
+**Edge types:** `flow`, `depends-on`, `relation`, `references` — all support labels, styles (solid/dashed/dotted), and animation.
+
+## MCP Server
+
+24 tools: 18 action-discriminated composites (`canvas_import`, `canvas_board`, `canvas_node`, `canvas_render`, `canvas_edge`, `canvas_group`, `canvas_history`, `canvas_view`, `canvas_query`, `canvas_webview`, `canvas_app`, `canvas_snapshot`, `canvas_ax_state`, `canvas_ax_work`, `canvas_ax_gate`, `canvas_ax_timeline`, `canvas_ax_delivery`, `canvas_intent`) plus 6 standalone tools (`canvas_batch`, `canvas_pin_nodes`, `canvas_invoke_command`, `canvas_ax_interaction`, `canvas_ingest_activity`, `canvas_screenshot`). `canvas_import` is the agent half of the human-consented attachment workflow: agents list/read requested imports, submit reviewable Markdown, or report unavailable; they cannot request, cancel, or commit. The 57 legacy single-purpose tools the composites replaced were removed in v0.3.0; v0.4.0 shipped the `canvas_snapshot` composite and removed the 6 deprecated snapshot standalones. Prefer composites for new MCP calls; see `docs/mcp.md` for the authoritative tool list and the legacy-to-composite migration reference.
+
+### Agent-assisted document imports
+
+PDF and Office drops retain the original (maximum 20 MiB) as a board-owned attachment. Nothing launches an agent automatically: a human explicitly consents and requests extraction, then reviews the returned sections, references, warnings, and `agentDescription` before committing source-linked Markdown. The agent reads controlled bytes through the returned HTTP download path, or inline base64 only at 2 MiB or below; a remote host may require manual byte transfer. Draft submission may happen while another board is active, but commit requires reopening the captured source board. PMX bundles no converter or OCR and makes no guarantee that a host can read every format, scan, chart, or diagram.
+
+Originals remain in SQLite until their board is deleted; snapshots/restores do not discard them, and database backups include them. Static export v1 never includes original bytes. Source-linked Markdown is excluded by default and is controlled by `includeDerivedText`, independently of `includeFiles`; editing the Markdown does not remove its source classification.
+
+The `diagram` action of `canvas_app` is a thin preset in `src/server/diagram-presets.ts` that proxies to the hosted [Excalidraw MCP app](https://github.com/excalidraw/excalidraw-mcp) (`https://mcp.excalidraw.com/mcp`). For any other MCP Apps server, use `canvas_app` action `open-mcp-app`.
+
+15 static canvas resources: `canvas://boards`, `canvas://pinned-context`, `canvas://schema`, `canvas://layout`, `canvas://summary`, `canvas://spatial-context`, `canvas://history`, `canvas://code-graph`, `canvas://ax`, `canvas://ax-context`, `canvas://ax-timeline`, `canvas://ax-work`, `canvas://ax-pending-steering`, `canvas://ax-delivery`, `canvas://skills`; two canvas resource templates: `canvas://context{?budget,consumer,since}` and `canvas://graph{?focus,depth}`. Bundled skills additionally register per-skill `canvas://skills/<name>` resources and the `skill://{name}/{+path}` file template.
+
+Resource change notifications: the MCP server emits `notifications/resources/updated` when canvas state changes. Pin changes notify `canvas://pinned-context`; all mutations notify `canvas://layout`, `canvas://summary`, `canvas://spatial-context`, `canvas://history`, `canvas://code-graph`, and `canvas://graph`. This enables real-time human→agent collaboration — humans pin nodes in the browser, agents are notified immediately.
+
+### AX Primitives (host-agnostic)
+
+Neutral, agent-agnostic agent-experience primitives. The core never imports a host SDK (e.g. `@github/copilot-sdk`); host adapters map onto these HTTP/MCP surfaces. State lives in three partitions:
+
+- **Canvas-bound** (`focus`, `work-item`, `approval-gate`, `review-annotation`): live in `PmxAxState`, participate in snapshots + restore, cleared by `canvas_view { action: "clear" }`. Read via `canvas_ax_state { action: "get" }` / `canvas://ax-work`.
+- **Timeline** (`agent-event`, `evidence-item`, `steering-message`): persist in dedicated DB tables for diagnostics/continuity, bounded by retention (500 rows/table), NOT restored by snapshots, NOT cleared by `canvas_view { action: "clear" }`. Read via `canvas_ax_timeline { action: "read" }` / `canvas://ax-timeline`.
+- **Host/session** (`host-capability`): reported by adapters into its own table, exposed for diagnostics, survives `canvas_view { action: "clear" }`. Read via `canvas_ax_state { action: "get" }`.
+
+Approval gates implement PMX approvals first (`pending → approved/rejected/held`); host permission hooks are mapped only where low-risk. **Unattended-approval policy** (`src/server/ax-gate-ttl.ts`): every gate carries `expiresAt` (`ttlMs`, default `PMX_CANVAS_GATE_TTL_MS` = 5 min); a 1s sweeper started with the server resolves unanswered gates to `held` (non-approval), records a `policy` agent-event, and re-emits presence; `POST /api/canvas/ax/approval/:id/reopen` (HTTP/SDK only — a human action) restarts the clock. **Scope fence** (`src/server/scope-fence.ts`): `policy.scope = { nodeIds, padding }` makes `executeOperation` refuse agent-originated mutations outside the fence with 403 (`meta.fromWorkbench` exempts the human; batch inner ops are always agent writes, so the fence cannot be keyed on `suppressAutoGhost`); unknown mutating ops are refused under a fence by default — add new layout ops to `checkScopeFence`.
+
+- **Agent presence** (`src/server/agent-presence.ts`, shape in `src/shared/agent-presence.ts`): in-memory and TTL-swept like `IntentRegistry`, never persisted. Derived from feeds that already exist — every agent-originated mutation through `executeOperation` (no `x-pmx-workbench` marker) touches its caller as `tooling`; `ax.activity.ingest` kinds `session-start`/`session-end` attach/detach and `tool-start`/`tool-result` drive the phase; `POST /api/canvas/ax/presence` (`canvas_ax_state { action: "set-presence" }`) is the explicit path for `thinking`, cursor, focus. Transport-labelled writes (`api`/`mcp`/`sdk`/`cli`, no `agentId`) are **attributed to the single attached session** so one agent writing through MCP keeps one cursor; identified writers and multi-session boards stay separate; a human-started `browser` session absorbs agent-less writes under any label and takes the writer's name (`HUMAN_STARTED_SESSION_LABEL`); an attach whose label matches an already-attached session twin-merges (one agent, two channels — Copilot's extension + its MCP server) with the channel aliased onto the session. One `agent-presence` SSE frame carries the full snapshot on every change including expiry, and it also carries `activity` — the last 50 agent writes with a `describeWrite` summary (the External Steering feed and the session panel's Update rows). An explicit `attached: false` removes the presence outright (an ended session never lingers as an external writer). **`sessionActive` (any attached presence) gates all agent chrome except presence cursors** — `AgentPresenceLayer` paints every live writer (external ones `is-external`/dashed) so a human always sees where an agent is working; panels/chips/composer still mount on `sessionActive`, and a board with no writers at all stays byte-clean. Contract: `docs/ax-state-contract.md` (Agent presence); design and build plan: `docs/design.md`.
+- **Human presence + user wins** (`src/server/human-presence.ts`, shape in `src/shared/human-presence.ts`): every open workbench tab heartbeats `POST /api/canvas/human-presence` (cursor, name, `grabbingNodeId`); one `human-presence` SSE frame per change. A held node is an **edit lock**: `executeOperation` refuses an agent write to it with 409 until release or the 8 s grab TTL (membership ops — dissolving its group, `group.add` — count as writes to the member), and the client vetoes a pending explicit intent on a grabbed node and records a `yield` timeline event. Human heartbeats are in `PRESENCE_EXEMPT_OPS` — they must never count as agent activity.
+- **Shared undo stack with actors** (`mutation-history.ts`): `executeOperation` tags every recorded entry `human` (workbench marker) or `agent`; `GET /api/canvas/history` exposes `top`. The session panel offers undo only while an agent edit tops the stack and posts steering when the human takes it. SDK writes bypass the registry and default to `agent`.
+
+Additional canvas-bound primitives: `elicitation` (request structured human input → respond), `mode-request` (request a plan/execute/autonomous transition → resolve), and a single `policy` singleton (tool/prompt policy: `tools.allowed|excluded|approvalRequired`, `prompt.systemAppend|mode`). All snapshot/restore with the rest of `PmxAxState` and are read via `canvas_ax_state { action: "get" }` / `canvas://ax-work` / `canvas://ax-context`.
+
+#### Node interactions (capability-gated)
+
+Eligible nodes emit one normalized, zod-validated `PmxAxInteraction` envelope (`{ type, sourceNodeId, payload, sourceSurface }`) that maps onto an AX operation. `applyAxInteraction` (`src/server/ax-interaction.ts`) is the single trust boundary and re-validates every interaction regardless of transport.
+
+- **Capabilities:** `DEFAULT_NODE_AX_CAPABILITIES` is the per-node-type ceiling; a node may opt in / narrow via `data.axCapabilities` (`{ enabled, allowed }`), clamped to the ceiling (a node can never escalate). `html`/`html-primitive`, `mcp-app`, and internal `prompt`/`response` are disabled by default.
+- **`sourceSurface` scoping:** sandboxed/opaque-origin iframe surfaces (`html-node`, `mcp-app`, `json-render`) are clamped to their OWN node — caller-supplied `nodeIds` are forced to `[sourceNodeId]`. Trusted surfaces (`native-node`, `adapter`) may target explicit nodeIds. **When adding a new sandboxed surface, add it to the `scoped` predicate** or it silently takes the permissive default.
+- **Transports:** native node controls call `POST /api/canvas/ax/interaction` directly; sandboxed surfaces postMessage a nonce-tagged emit to the parent canvas, which validates source + per-surface nonce + node id before submitting. `html`/`mcp-app` use `window.PMX_AX.emit(type, payload)`; the json-render/graph viewer forwards a spec action named after an AX type (e.g. `on.press → { action: "ax.work.create", params }`).
+- **Commands:** `ax.command.invoke` runs a registry command (`pmx.plan`, `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`) via `canvas_invoke_command`; unknown names are rejected (400) and a successful call records a `command` agent-event.
+- **Delivery:** steering can be claimed by adapterless MCP clients (`canvas_ax_delivery { action: "claim" }` / `canvas://ax-pending-steering`) and acknowledged (`canvas_ax_delivery { action: "mark" }`); loop-safe (a consumer never receives steering it originated).
+
+Interactions request PMX-AX primitives only — never arbitrary shell, tool, MCP, or host execution.
+
+#### AX flows (panel and graph)
+
+A task flow exists in two interchangeable forms. The `ax-flow` HTML primitive draws it as a panel;
+`ax.flow.materialize` lays the same steps out as native nodes joined by `flow` edges with a
+loop-back rail, each step linked to a work item. It is the only interaction that creates canvas
+nodes, so it is granted to the `html` ceiling alone.
+
+- Materialized steps carry `data.axStep` and render native Start/Done/Blocked controls
+  (`src/client/nodes/AxStepControls.tsx`) in both the node body and the expanded overlay — the
+  flow is drivable without the panel.
+- Work-item status mirrors onto node status chips (`mirrorAxWorkStatusToNodes`), which is what
+  makes the in-progress node visible on the board while an agent works.
+- `src/server/ax-flow-loop.ts` advances the loop server-side via `setWorkItemsChangedListener`
+  (see architecture rule 8), so it survives a browser reload and keeps running with the tab closed.
+  A module-level `advancing` guard prevents re-entrancy.
+- Step geometry and the shared flow shape live in `src/shared/ax-flow.ts` so server and client
+  cannot drift.
+
+### Spatial Semantics Layer
+
+The canvas exposes spatial intelligence to agents via `canvas://spatial-context`:
+- **Proximity clusters**: Automatically detects nodes grouped together on the canvas
+- **Reading order**: Nodes sorted top-left to bottom-right (how humans read)
+- **Pinned neighborhoods**: For each pinned node, lists nearby unpinned nodes (the human's implicit context)
+- **`canvas://pinned-context`** now includes neighborhood data — nearby unpinned nodes for each pin
+
+Use `canvas_query { action: "search" }` to find nodes by title/content keywords instead of parsing the full layout.
+
+### Time Travel (Undo/Redo + History)
+
+Every canvas mutation is recorded in an in-memory ring buffer (last 200 operations). Each entry captures forward/inverse closures for clean undo/redo.
+
+- **`canvas_history`** (`action: "undo" | "redo"`) — step through history, reversing operations cleanly
+- **`canvas://history`** — human-readable mutation timeline with cursor position
+- **`canvas_snapshot`** (`action: "diff", snapshot`) — compare current canvas vs any saved snapshot (shows added/removed/modified nodes and edges)
+- HTTP: `POST /api/canvas/undo`, `POST /api/canvas/redo`, `GET /api/canvas/history`
+
+Design notes:
+- History is session-scoped (in-memory, not persisted to disk)
+- `arrange()` records as a single compound mutation (not N individual moves)
+- Undo/redo emit SSE events so the browser updates immediately
+- The `_suppressRecording` flag prevents undo/redo from creating new history entries
+
+### Code Graph (Auto-Dependency Detection)
+
+When file nodes are on the canvas, the system auto-detects import dependencies and creates `depends-on` edges between related files. The code graph updates live when files change.
+
+- **`canvas://code-graph`** MCP resource — dependency structure: central files, isolated files, import/imported-by lists
+- HTTP: `GET /api/canvas/code-graph`
+- Supported languages: JS/TS (`import`/`require`), Python (`import`/`from`), Go (`import`), Rust (`mod`/`use crate`)
+- Auto-edges use the `codegraph-` ID prefix and are suppressed from mutation history
+- Recomputation is debounced (300ms) and triggered on file node add/remove and file content change
+
+## Integration Paths
+
+1. **MCP Server** (recommended) — `pmx-canvas --mcp`, auto-starts on first tool call
+2. **HTTP API** — REST + SSE at `localhost:4313`
+3. **JavaScript/TypeScript SDK (Bun runtime)** — `import { createCanvas } from 'pmx-canvas'`
+4. **Agent Skills** — `skills/pmx-canvas/SKILL.md`, `skills/web-artifacts-builder/SKILL.md`, `skills/playwright-cli/SKILL.md`, `skills/pmx-canvas-testing/SKILL.md`, `skills/pmx-canvas-orchestration/SKILL.md` (multi-agent choreography ON the canvas: host executes, canvas is the graph/state/steering surface), plus repo-local agnostic PMX skills such as `doc-coauthoring`, `data-analysis`, `frontend-design`, `web-design-guidelines`, and `json-render-*`

package/docs/ax-host-adapter-contract.md

@@ -35,7 +35,7 @@ surface each one binds to.
 | `ingestActivity(event)` | `POST /api/canvas/ax/activity` · `canvas_ingest_activity` — board auto-reacts | Forwarding the host's tool/session hooks |
 | `awaitGate(id)` | `GET /api/canvas/ax/{approval\|elicitation\|mode}/<id>?waitMs=` · `canvas_ax_gate { kind: "approval"\|"elicitation"\|"mode", action: "await" }` | Optionally surfacing a native modal; the agent must await PMX |
 | `mirrorLog(event)` *(optional)* | `GET /api/canvas/ax/timeline` · `canvas://ax-timeline` | Writing AX events into the host's own chat/session log |
-| `presence()` | `POST /api/canvas/ax/presence` · `canvas_ax_state { action: "set-presence" }` — or simply `ingestActivity` with `session-start` / `session-end` / `tool-start` / `tool-result` | Calling it from the host's session and tool hooks. Attach saves a pre-session snapshot; detach emits the `agent-session-ended` receipt — detach on shutdown (bounded, best-effort) so the human gets it promptly. If the host knows the model's token usage, report it as `contextUsage: { used, total }` — the top-bar meter then shows the real window instead of the pinned-context estimate |
+| `presence()` | `POST /api/canvas/ax/presence` · `canvas_ax_state { action: "set-presence" }` — or simply `ingestActivity` with `session-start` / `session-end` / `tool-start` / `tool-result` | Calling it from the host's session and tool hooks. Attach saves a pre-session snapshot; detach emits the `agent-session-ended` receipt — detach on shutdown (bounded, best-effort) so the human gets it promptly. If the host knows the model's token usage, report it as `contextUsage: { used, total }` — the context panel then names how many tokens the agent's whole context holds |
 
 ### Presence: the cursor works for every adapter
 

package/docs/ax-state-contract.md

@@ -105,9 +105,10 @@ constants, so they cannot drift); the registry is `src/server/agent-presence.ts`
   so clients never run their own ticker.
 - **Transport.** One SSE frame, `agent-presence`, carries the full snapshot on
   every change, including the last `MAX_ACTIVITY_ENTRIES` agent writes with a
-  one-line summary. `GET /api/canvas/ax/presence` for the connect-time read;
+  one-line summary. An attached presence also carries `session`
+  (`{ startedAt, read, created, edited, pinned }`, card ids on the open board
+  since it attached, counting every agent there, like the receipt): the agent
+  chip's "2 read · 1 edited" and the live lens. A recorded read re-emits the
+  frame. `GET /api/canvas/ax/presence` for the connect-time read;
   `POST /api/canvas/ax/presence` (`canvas_ax_state { action: "set-presence" }`)
   for explicit updates.
-- **Budget.** `used` = estimated tokens of the `pinned-context.get` payload;
-  `total` = `PMX_CANVAS_CONTEXT_BUDGET_TOKENS` (default
-  `CONTEXT_BUDGET_DEFAULT_TOKENS`).

package/docs/cli.md

@@ -1,5 +1,34 @@
 # CLI reference
 
+## Knowledge lifecycle data
+
+`pmx-canvas board knowledge list` reads workspace categories/folders and shared relation presets.
+`pmx-canvas board knowledge category-set '<JSON>'` accepts `{category: {...}}`;
+`pmx-canvas board knowledge category-remove '{"id":"unused-category"}'` deletes an unused category. Explicit folder assignments (even empty folders) refuse deletion and name the folders to reassign or clear first. Unknown IDs are 404; missing/blank IDs are invalid input. No folder settings or inherited policies are silently cleared.
+`board knowledge folder-set '<JSON>'` accepts `{path, categoryId, lifecycleOverride}`.
+`board knowledge relation-preset-set '<JSON>'` accepts `{preset: {id, name, vocabulary}}`;
+`board knowledge relation-preset-remove '{"id":"preset-id"}'` deletes a shared template.
+Vocabulary entries are `{kind, ink, directed}`. These templates are managed in Home;
+editing/deleting one does not rewrite boards. Applying a saved template explicitly copies
+its vocabulary to a selected board. The canvas dropdown only filters existing relation kinds.
+No workspace write opens a board; scope fences refuse agent workspace writes.
+Moving/unfiling a board also checks its stored global scope or writer territory alongside
+the active scope, without opening it. Home or an unfenced board does not bypass that policy.
+`pmx-canvas board lifecycle get|set|review|restore '<JSON>'` uses `id` and the
+[HTTP contract fields](http-api.md#knowledge-lifecycle-data-plan-017-slice-1).
+For example: `pmx-canvas board lifecycle review '{"id":"card-id","outcome":"retain",
+"evidence":"Checked source revision v2","applied":true,"expectedBoardId":"board-id",
+"expectedContentRevision":12}'` (replace 12 with the revision of the card content actually checked).
+Read supports `board`; writes target the open board. For dependencies also send `expectedSources`
+from the checked lifecycle result's `qualification.observations`; stale or unavailable sources refuse
+validation. Qualification includes due reasons, unknown/retired status and separate clocks.
+Retired cards leave active context but remain in direct reads and search, explicitly marked.
+
+`edge add` and `edge update` accept `--kind` and `--reason`; update also accepts `--clear-kind`
+and `--clear-reason`. `board vocabulary <board-id> '<JSON-array>'` sets an editable vocabulary
+of `{kind, ink, directed}`. These are semantic relations, independent of edge line type/style.
+Dependency directions and the bounded brief lifecycle snapshot are documented in the HTTP contract.
+
 The CLI is the shell-native way to run and control PMX Canvas. It targets
 `http://localhost:4313` by default — override with `PMX_CANVAS_URL` or
 `PMX_CANVAS_PORT` when the server runs elsewhere, or per invocation with the
@@ -34,9 +63,11 @@ The same stops and camera interpolation drive interactive presentation and optio
 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.
+embedded/capture view (no rail, top bar, minimap or composer). Right/Down/Space
+advances, Left/Up goes back, Esc exits. The presentation camera is local to the
+viewer and never written to the board; board content continues updating over SSE.
 Stops do not auto-advance. Missing targets show an error and can be skipped.
+With `prefers-reduced-motion: reduce`, every stop and camera move jumps instead of animating.
 
 Save this as `tour.json` (replace the IDs with IDs from `pmx-canvas node list`):
 
@@ -45,6 +76,7 @@ Save this as `tour.json` (replace the IDs with IDs from `pmx-canvas node list`):
   "stops": [
     { "target": { "nodeId": "overview-group" }, "duration": 1.5, "padding": 60 },
     { "target": { "nodeId": "detail-note" }, "duration": 2, "easing": "ease-in-out", "pullback": 0.7 },
+    { "target": { "rect": { "x": -400, "y": 200, "width": 1600, "height": 900 } }, "duration": 2 },
     { "target": { "viewport": { "x": 80, "y": 100, "scale": 0.5 } }, "duration": 1 }
   ]
 }
@@ -55,10 +87,11 @@ 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.
+A stop targets exactly one of: a node ID (including a group ID), a world-space
+`rect` (`x`/`y` is its top-left corner), 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`
+screen pixels around a node or rect 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.
@@ -68,6 +101,33 @@ 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()`.
 
+### Driving a tour (agents)
+
+The server keeps one tour cursor (in memory, not saved), tied to the board it was
+started on; starting a tour on another board replaces it. An agent steps it and
+every presenting viewer follows; a human's arrow keys move the same cursor,
+so `next` always continues from where the audience actually is.
+
+```bash
+pmx-canvas tour go 0                 # start presenting at the first stop
+pmx-canvas tour go next              # or: previous (clamped at the ends)
+pmx-canvas tour go 2 --no-present    # only move viewers already presenting
+pmx-canvas tour exit                 # leave presentation everywhere
+
+# Eased camera move, no tour needed (same fields as a stop)
+pmx-canvas camera move --node <id> --duration 2 --pullback 0.6
+pmx-canvas camera move --rect -400,200,1600,900 --easing ease-out
+pmx-canvas camera move --viewport 80,100,0.5 --duration 0
+```
+
+`tour go` starts presenting in idle workbenches unless `--no-present` is given.
+`camera move` animates every open workbench; outside a presentation its end camera
+becomes the board viewport. Camera moves and tour steps are navigation: they never
+enter undo history, never count as agent writes, and are allowed under a scope fence.
+A deterministic capture (`record --mode deterministic`) ignores both.
+SDK: `canvas.goToTourStop(indexOrStep, { present })`, `canvas.exitTour()`,
+`canvas.moveCamera(stop)`.
+
 ### Optional capture of the same tour
 
 `record` is an optional local utility, not a second presentation model. It reads
@@ -83,31 +143,47 @@ pmx-canvas record --mode deterministic --present --fps 30 --resolution 1920x1080
 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
+pmx-canvas record --duration 10 --present --theme daylight --output activity.mp4
 
 # Keep recording until SIGINT (Ctrl+C) or SIGTERM, then encode
 pmx-canvas record --stop-on-signal --output live.mp4
 ```
 
+A board walkthrough end to end: save the `tour.json` above, preview it with
+**Present**, then render it at video quality and record a live pass while an
+agent works:
+
+```bash
+pmx-canvas tour set --file tour.json
+pmx-canvas record --mode deterministic --present --theme midnight --resolution 1920x1080 --fps 30 --output walkthrough.mp4
+pmx-canvas record --duration 20 --present --resolution 1920x1080 --output agent-pass.mp4 &
+pmx-canvas node add --type markdown --title "Findings" --content "Added while recording"
+wait
+```
+
 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.
+An `.mp4` output uses ffmpeg/H.264; any other path is a frame sequence directory
+of `frame-000000.png` files.
 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.
+encoding. If ffmpeg is missing, the command clearly reports the frame-sequence
+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.
+board edits. Realtime mode records Chrome's screencast (a frame per paint) and
+writes the newest painted frame on every `--fps` tick while it records, so footage
+keeps wall-clock speed and a stop signal keeps every frame written so far; ticks
+with no new paint repeat the previous frame, counted as `duplicated` in
+`recording.json`. Capture has no audio. Chrome and a Bun runtime with WebView
+support are required; Chrome gets 60 seconds to cold-start.
 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.
 
@@ -209,6 +285,17 @@ none keeps 100% with scrolling. [Sizing and readability](node-types.md#mermaid-n
 `--from-search` / `--to-search` must each resolve to exactly one node — broad
 queries fail rather than guess. Use the full visible title.
 
+Background `group create` and `edge add` accept `--destination-board <id>`,
+`--request-id <logical-id>` and `--expected-board <active-id>`. The destination
+does not open in the workbench; `--to-board` on an edge independently selects its
+foreign endpoint. Reuse request IDs only for identical retries. See the
+[creation/retry contract](http-api.md#nodes).
+
+`search <query>` accepts `--board-id <id>`, `--folder <path>`, `--scope active|library`
+and `--limit <n>` (`--library` also selects library scope). Board/folder filters
+intersect; folders include descendants, and `--folder ""` selects unfiled boards.
+Filters default omitted scope to library; explicit active scope stays active.
+
 CLI create commands return the created node shape with normalized title,
 content, and geometry, which makes scripting stacked layouts and batch
 follow-ups easier.
@@ -282,14 +369,39 @@ node or fit the new ids — auto-placement is board-relative, not camera-relativ
 
 ## Boards
 
+Home has Folders, Map, and Graph views. Folder paths organize boards independently
+of links; dragging a board in Map persists its position in SQLite.
+
+Graph is one zoomable Library > Board > Card
+explorer. Library shows neutral, undirected, counted board-pair evidence bundles;
+Board shows internal card relations and external neighbor boards; Card shows exact
+one-hop qualified neighbors, incoming left and outgoing right. Click, Enter or Space
+on a node drills; an edge selects its exact evidence in the existing bottom inspector.
+Back restores the prior scene, camera, query, filters and selection; breadcrumbs go
+up the ownership hierarchy instead. Open board/card is a separate content action.
+Unconnected boards/cards have labelled clickable trays. Search and reveal actions
+expose large sets with explicit displayed/total/filtered/hidden counts. A deterministic
+bounded force solve supplies initial positions. Dragging a node pushes nearby nodes
+and lets connected neighbors respond, then the graph settles around its drop position.
+Link pull stays gentle even for highly connected nodes, with wider spacing between cards.
+Canceled drags restore all displaced nodes. Positions remain local to Graph; live
+updates alone preserve existing anchors. Graph's dock starts collapsed and compact.
+Hover highlights a node's connections without fading the other links.
+Entry and search preserve readable size; the header distinguishes off-screen nodes
+from filtered or not-yet-drawn nodes. Fit view shows the whole drawn extent. Home Map
+(including its 280 px default dock), Folders and server graph focus/depth contracts
+are unchanged.
+
 ```bash
 pmx-canvas board list                          # most recently opened first; activeBoardId null = Home
 pmx-canvas board create "Q4 planning"          # created, not opened
 pmx-canvas board open <board-id>               # open the returned ID before writing
 pmx-canvas board open --home                   # return the shared workbench to Home
 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 create "Q4 planning" --folder Planning
+pmx-canvas board folder <board-id> "Planning/Quarterly" # nested folders; --clear unfiles it
+pmx-canvas board pin <board-id> --reason "Q4 rests on it" # join the agent's working set
+pmx-canvas board unpin <board-id>
 pmx-canvas board from <source-id> "Follow-up" --preview
 pmx-canvas board from <source-id> "Follow-up" --nodes id1,id2 --readme --structure
 ```
@@ -297,11 +409,36 @@ pmx-canvas board from <source-id> "Follow-up" --nodes id1,id2 --readme --structu
 Commands write to the board open in the workbench. `board open` switches the
 shared visible board, not a private CLI target. Verify its returned
 `activeBoardId` before writing; another participant can switch it later.
-Deletion remains human-only. `board from`
+A pinned board's README and pinned cards reach the agent's brief whichever board is open; it
+is read-only context, never a write target. Deletion remains human-only. `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.
+does not inherit pins, AX state, or mutation history. Its `previousBoardId`
+records the source board.
+
+## Connected memory
+
+```bash
+pmx-canvas memory-graph
+pmx-canvas memory-graph --projection boards
+pmx-canvas memory-graph --focus pins --depth 2
+pmx-canvas memory-graph --focus '["board-id","card-id"]' --depth 1
+pmx-canvas edge add --from <source-card-id> --to <target-card-id> --to-board <target-board-id> --type references
+```
+
+Graph focus is a board ID, a JSON qualified key `[boardId,cardId|null]`, or
+`pins`; omit it for the library. Depth is an integer 0–4, default 2, counting
+undirected membership hops. Explicit `--depth 0` is valid; bare `--depth` and
+empty values are rejected. `--projection full|boards` defaults to `full`;
+`boards` returns compact board-only summaries. The projection returns `nodes`, `edges`,
+`unresolvedLinks: [{ source, ref }]`, `focus`, and `depth`; nodes are
+`summaryOnly: true` with summaries capped at 280 characters. It is the same
+projection used by Home, links/backlinks, and brief discovery. Reads mark links
+seen on their owning boards without switching or marking full content read.
+`--to-board` keeps the source on the open board and targets a remote card;
+auto-arrange stays local and static export shows external connection evidence,
+not remote lines.
 
 ## Backup and restore
 
@@ -383,6 +520,7 @@ 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
+pmx-canvas ax reads status --board <id>  # a board's last agent read, per-node reads, pin metadata
 
 # Work items (canvas-bound)
 pmx-canvas ax work add --title "Wire up auth" --status in-progress node-1

package/docs/design/AgentContext.dc.html

@@ -18,7 +18,7 @@ body{margin:0}
 <div style="display: flex; gap: 40px; align-items: flex-end">
 <div style="flex: 1">
 <h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.015em">What the agent did with context</h1>
-<p style="margin: 4px 0 0; font-size: 13px; color: #8ea3bd">Two questions, two colours. Every mark has a glyph and a word, so it reads without the colour, and every mark explains itself on hover.</p>
+<p style="margin: 4px 0 0; font-size: 13px; color: #8ea3bd">Two questions, two colours. Every mark has a glyph and a word, so it reads without the colour, and every mark explains itself on hover. <span style="color: #b9c6d6">Updated 2026-10-08: read, not read and changed show on pinned cards only — unpinned cards carry no read state; the session receipt and the dim-untouched lens say what the agent read. In headers, “by the agent” is the ✦ on the type icon (HeaderMarks).</span></p>
 </div>
 <div style="display: flex; gap: 10px">
 <div style="{{s.rule}} border-color: rgba(75,188,255,0.4)"><span style="{{s.ruleDot}} background: #4BBCFF"></span><span><b style="font-weight: 600; color: #4BBCFF">Blue</b> — what's in context<br><span style="color: #8ea3bd">You or the agent pinned it</span></span></div>
@@ -70,7 +70,7 @@ body{margin:0}
 
 <div style="{{sc.node}} left: 360px; top: 172px; border: 1.5px solid #4BBCFF"><div style="position: absolute; left: 0; right: 0; top: 0; height: 2.5px; background: #B388FF"></div><div style="{{sc.head}} background: rgba(75,188,255,0.10)"><span style="{{sc.title}}">SMB is price-sensitive</span><span style="{{sc.read}}"><svg width="12" height="12" viewBox="0 0 24 24" style="{{sc.ic}}"><path d="{{i.pen}}"></path></svg>edited</span><button aria-label="Expand (Enter)" style="width: 22px; height: 22px; border: 0; border-radius: 6px; padding: 0; background: transparent; color: #b9c6d6; display: flex; align-items: center; justify-content: center; flex-shrink: 0"><svg width="13" height="13" viewBox="0 0 24 24" style="fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round"><path d="M14 4h6v6M20 4l-7 7M10 20H4v-6M4 20l7-7"></path></svg></button><span style="{{sc.pin}}"><svg width="10" height="10" viewBox="0 0 24 24" style="fill: none; stroke: currentColor; stroke-width: 2.6; stroke-linecap: round; stroke-linejoin: round"><path d="{{i.pin}}"></path></svg></span></div><div style="{{sc.body}}">finding · edited 14:12 · <span style="color: #B388FF">see change</span></div></div>
 
-<div style="{{sc.node}} left: 640px; top: 172px"><div style="{{sc.head}}"><span style="{{sc.title}}">Competitor pricing</span><span style="{{sc.read}}"><svg width="12" height="12" viewBox="0 0 24 24" style="{{sc.ic}}"><path d="{{i.eye}}"></path></svg>read</span><button aria-label="Expand (Enter)" style="width: 22px; height: 22px; border: 0; border-radius: 6px; padding: 0; background: transparent; color: #b9c6d6; display: flex; align-items: center; justify-content: center; flex-shrink: 0"><svg width="13" height="13" viewBox="0 0 24 24" style="fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round"><path d="M14 4h6v6M20 4l-7 7M10 20H4v-6M4 20l7-7"></path></svg></button><button aria-label="Add to context (P)" style="width: 18px; height: 18px; box-sizing: border-box; border: 1.5px solid #6b7d94; border-radius: 999px; padding: 0; background: transparent; color: #b9c6d6; display: flex; align-items: center; justify-content: center; flex-shrink: 0"><svg width="10" height="10" viewBox="0 0 24 24" style="fill: none; stroke: currentColor; stroke-width: 2.4; stroke-linecap: round; stroke-linejoin: round"><path d="M9 4h6l-.8 5.5 2.8 3H7l2.8-3zM12 12.5V20"></path></svg></button></div><div style="{{sc.body}}">webpage · not pinned, read anyway</div></div>
+<div style="{{sc.node}} left: 640px; top: 172px"><div style="{{sc.head}}"><span style="{{sc.title}}">Competitor pricing</span><button aria-label="Expand (Enter)" style="width: 22px; height: 22px; border: 0; border-radius: 6px; padding: 0; background: transparent; color: #b9c6d6; display: flex; align-items: center; justify-content: center; flex-shrink: 0"><svg width="13" height="13" viewBox="0 0 24 24" style="fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round"><path d="M14 4h6v6M20 4l-7 7M10 20H4v-6M4 20l7-7"></path></svg></button><button aria-label="Add to context (P)" style="width: 18px; height: 18px; box-sizing: border-box; border: 1.5px solid #6b7d94; border-radius: 999px; padding: 0; background: transparent; color: #b9c6d6; display: flex; align-items: center; justify-content: center; flex-shrink: 0"><svg width="10" height="10" viewBox="0 0 24 24" style="fill: none; stroke: currentColor; stroke-width: 2.4; stroke-linecap: round; stroke-linejoin: round"><path d="M9 4h6l-.8 5.5 2.8 3H7l2.8-3zM12 12.5V20"></path></svg></button></div><div style="{{sc.body}}">webpage · not pinned · read shows in the receipt</div></div>
 
 <div style="{{sc.node}} left: 60px; top: 330px; border: 1.5px solid #4BBCFF"><div style="{{sc.head}} background: rgba(75,188,255,0.10)"><span style="{{sc.title}}">Churn by plan</span><span style="{{sc.read}}"><svg width="12" height="12" viewBox="0 0 24 24" style="{{sc.ic}}"><path d="{{i.eye}}"></path></svg>read</span><button aria-label="Expand (Enter)" style="width: 22px; height: 22px; border: 0; border-radius: 6px; padding: 0; background: transparent; color: #b9c6d6; display: flex; align-items: center; justify-content: center; flex-shrink: 0"><svg width="13" height="13" viewBox="0 0 24 24" style="fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round"><path d="M14 4h6v6M20 4l-7 7M10 20H4v-6M4 20l7-7"></path></svg></button><span style="{{sc.pin}} position: relative"><svg width="10" height="10" viewBox="0 0 24 24" style="fill: none; stroke: currentColor; stroke-width: 2.6; stroke-linecap: round; stroke-linejoin: round"><path d="{{i.pin}}"></path></svg><span style="position: absolute; right: -3px; bottom: -3px; width: 9px; height: 9px; border-radius: 999px; background: #B388FF; border: 2px solid #0f1d31"></span></span></div><div style="{{sc.body}}">chart · pinned by Claude</div></div>
 
@@ -146,7 +146,7 @@ class Component extends DCLogic {
     var key = [
       k({ name: 'In context — pinned by you', desc: 'Blue border, tinted header, pin badge.', title: 'Raise Pro to $24?', meta: 'question', pin: true }),
       k({ name: 'In context — pinned by the agent', desc: 'Same blue, with a violet dot on the pin; hover says why.', title: 'Churn by plan', meta: 'pinned by Claude · 14:04', pin: true, byAgent: true }),
-      k({ name: 'Read by the agent', desc: 'It loaded this into its context, pinned or not.', title: 'Competitor pricing', meta: 'read 14:11', icon: i.eye, markText: 'read' }),
+      k({ name: 'Read by the agent', desc: 'Pinned, and loaded by the agent. Unpinned cards show no read state.', title: 'Competitor pricing', meta: 'read 14:11', pin: true, icon: i.eye, markText: 'read' }),
       k({ name: 'Pinned, not read yet', desc: 'In context, but the agent hasn’t loaded it since you pinned it.', title: 'Pricing notes', meta: 'pinned 14:18', pin: true, icon: i.eyeOff, markText: 'not read', muted: true }),
       k({ name: 'Created by the agent', desc: 'Its byline stays until you edit the node.', title: 'Churn flat after last raise', meta: 'created 14:06', icon: i.spark, markText: 'by Claude' }),
       k({ name: 'Edited by the agent', desc: 'Violet bar for the session; “see change” opens the diff and undo.', title: 'SMB is price-sensitive', meta: 'edited 14:12 · see change', bar: true, icon: i.pen, markText: 'edited' }),