pmx-canvas 0.8.2 → 0.9.1

package/docs/http-api.md

@@ -3,6 +3,145 @@
 REST endpoints for all canvas operations + an SSE event stream. Works from
 any language. Default base URL: `http://localhost:4313`.
 
+## Knowledge lifecycle data (plan 017 slice 1)
+
+The slice-1 data contract now also drives the workbench, due engine and qualified agent context.
+Categories remain explicit; nothing classifies cards automatically.
+`Lifecycle` is `{ decayType: "reality"|"decision"|"dependency"|"relevance",
+rate: "fast"|"medium"|"slow"|"durable", triggers: string[], revalidationMethod: string, cadenceDays?: number }`.
+Strings in triggers and the method must be nonempty after trimming. `cadenceDays` is an integer,
+1–36500, required for Medium and optional for other rates. Category, folder and card policy writes
+refuse Medium without a cadence rather than saving a policy with no expiry. Fast checks at use in a
+new session, slow on resumed work, durable has no passive expiry. The latest attached session
+is the boundary, falling back to the active board's last-open time, then process start.
+A category is the same fields plus stable `id`, editable `name` and `glyph` (nonempty strings).
+
+Newly authored cards start fresh without a review record. Medium's first deadline is
+creation plus `cadenceDays`; Fast/Slow first require review in a later use/resumed
+session. Evidence validation stays null until an actual successful review. Concrete
+source changes and contradictions can still require review immediately. Edits, reads,
+undo/redo and snapshot restore never restart the initial freshness clock.
+Creation accepts `data.contentOrigin: "authored"|"imported"` (immutable afterward).
+Use `"imported"` for historical text pasted or extracted into a new Markdown card;
+attachments and externally sourced provenance are also treated as imports. Imports
+and pre-existing undated content do not acquire a synthetic freshness baseline.
+Groups and board portals skip inherited factual decay unless given an explicit
+card lifecycle override; explicit dependency/source warnings remain visible.
+
+| Route | Input / result |
+|---|---|
+| `GET /api/canvas/knowledge` | `{ok, categories, folders, relationPresets, cards, reviewCards, resolvedFolders}`; `cards` uses JSON `[boardId,cardId]` keys |
+| `POST /api/canvas/knowledge/category` | `{category}` creates or replaces by id; returns `{ok, category}` |
+| `DELETE /api/canvas/knowledge/category/:id` | Deletes an unused category; returns `{ok:true, id}`. Unknown id: 404; blank id: invalid input (400); omitted path id: no matching route (404). Explicit folder assignments, including empty folders, refuse deletion (409) and name the folders to reassign or clear first. Never clears folders or inherited policies. |
+| `POST /api/canvas/knowledge/folder` | `{path, categoryId: string|null, lifecycleOverride: Lifecycle|null}` replaces folder properties; returns `{ok, folder}` |
+| `POST /api/canvas/knowledge/relation-preset` | `{preset: {id, name, vocabulary: [{kind, ink, directed}]}}` creates or replaces a shared template; returns `{ok, preset}`. Duplicate names: 409. |
+| `DELETE /api/canvas/knowledge/relation-preset/:id` | Deletes the shared template; returns `{ok:true, id}`. Unknown id: 404. Existing board vocabularies and connections remain unchanged. |
+| `GET /api/canvas/node/:id/lifecycle?board=<board-id>` | Effective category/lifecycle and history, without opening that board |
+| `POST /api/canvas/node/:id/lifecycle` | `{lifecycleOverride: Lifecycle|null, expectedBoardId?}`; returns `{ok:true}` |
+| `POST /api/canvas/node/:id/review` | `{outcome, evidence: string, applied: boolean, expectedBoardId?, expectedContentRevision?, expectedSources?}`; returns `{ok, record}` |
+| `POST /api/canvas/node/:id/lifecycle/restore` | `{evidence: string, expectedBoardId?}`; returns `{ok, record}` |
+
+**Additive local contract, 2026-10-14 (validation ongoing):** `knowledge.list.reviewCards`
+is an array of `{boardId: string, cardId: string, boardTitle: string, folder: string|null,
+title: string}`. Titles and folder placement come from the authoritative board/card observation,
+not cached Home previews. Each nonretired card with `due === true` or nonempty `sources` appears
+once, including a card with both. Join to `cards[JSON.stringify([boardId, cardId])]` for reasons,
+source warnings and `lastValidatedAt`; missing validation is not a synthetic last-checked date.
+Unknown policy alone does not qualify, but explicit content or source warnings still do.
+The read covers the library without opening boards or writing validation. Consumers may filter
+to a canonical folder and its descendants; null folder is unfiled and included in whole-library
+scope. Opening a result is navigation, not a review record. The same additive result is returned
+by SDK `knowledge({action:"list"})`.
+
+Folder paths use the board-folder canonicalization (trimmed segments, at most eight levels).
+Null category inherits; null override clears that local override. An explicit child category
+starts its own defaults, discarding ancestor lifecycle overrides. A card's full override changes
+only lifecycle, never category. Unfiled/unclassified stays unknown. No defaults are inferred.
+The effective read returns `boardId`, `nodeId`, `contentRevision`, `category`, `categorySourceFolder`, `lifecycle`,
+`lifecycleSourceFolder`, `lifecycleSource` (`card`/`folder`/`unknown`), `records`, `retired`,
+`lastValidation` (record or null), and `qualification`. Source folders are canonical paths; null means no folder source.
+Qualification carries `retired`, `unknown`, `due`, `reasons`, `changedSinceRead`, `lastReadAt`,
+`contentChangedAt`, `lastValidatedAt`, `contentRevision`, `relevance`, source warnings in `sources`,
+and inspected source revision tokens in `observations`. Direct node reads and search results also
+carry qualification. Reads on an inactive board do not open it.
+
+Outcomes are `retain`, `revise`, `externalize`, `retire`, `unresolved`. Only an **applied**
+retain/revise/externalize with non-whitespace evidence renews validation. Reviews do not perform
+content edits or externalization for you: `applied` records whether the disposition was actually
+carried out. Validating outcomes require `expectedContentRevision` from the actual content checked;
+missing is 400, a stale version is 409. Never copy a newer metadata revision onto evidence for an older
+body. For cards with dependencies, also pass `expectedSources` from the checked lifecycle's
+`qualification.observations`. Changed, added, removed or unavailable sources refuse validation
+with 409; a later read is not permission to apply older evidence. The reviewed content is saved successfully before its record is appended; save failure adds
+no review. Applied retire persists until explicit restore, even after later successful reviews.
+Restore is audited with outcome `restore`, applied true, and never validates. Rows retain server
+id, board+node identity, evidence, application, actor `who`, server timestamp `when`, and reviewed
+`contentRevision` (null for legacy unversioned records, never backfilled as a current validation);
+append order resolves retirement even when timestamps coincide. Reload and board snapshots
+never erase this history. Restoring content is not restoring retirement.
+
+Workspace writes work on Home without opening/switching boards; agent workspace writes are
+refused under a scope fence. Moving or unfiling a board changes inherited lifecycle for all its
+cards, so agent folder changes are also refused under a fence; other board metadata is unaffected.
+This checks both the active board's applicable fence and the target board's stored global fence
+or the writer's assigned territory, even when another board or Home is open. It never opens the target.
+Category and folder-policy edits also check stored fences on every board whose effective
+inheritance would change. Unrelated folders and policies hidden by a child category remain editable.
+Card writes target the active board and use the existing expected
+board, scope and human edit-lock guards. Writes emit live knowledge/lifecycle notifications;
+metadata-only edits do not advance content revision or lastEditedBy. Read/delivery clocks,
+content revisions, evidence validation and task relevance remain separate; reading, editing,
+refreshing and restoration never validate. No synthetic content-change date is added to legacy cards.
+Generic node PATCH/SDK `updateNode` rejects `data.lifecycleOverride`; use the dedicated lifecycle
+setter (including to clear an override) so metadata cannot replay the body or resolve wiki links.
+
+Shared relation presets live in Home alongside Categories, not in per-board settings.
+Research, Dependencies, Decision and Flow are initial editable templates. Applying a saved
+preset explicitly copies its vocabulary through the existing board update contract; editing
+or deleting a template never silently rewrites boards. The canvas dropdown filters only the
+relation kinds actually present on that board, plus All relations, without a Custom vocabulary state.
+
+SDK (Bun): `canvas.knowledge({action:"list"|"category-set"|"category-remove"|"folder-set"|"relation-preset-set"|"relation-preset-remove", ...payload})`
+(`category-remove` takes `id`)
+and `canvas.lifecycle({action:"get"|"set"|"review"|"restore", id, ...payload})` use these
+same inputs/results. `get` accepts `board`; writes accept `expectedBoardId`, and validating
+reviews require `expectedContentRevision` and the matching `expectedSources` when dependencies exist.
+
+### Relations, source observations and active context
+
+Edge add/update accept open `kind` (1–80 characters) and `reason` (up to 4000), independently
+of the existing `type`, label, style and animation. Update with null clears kind/reason.
+Kinds/reasons survive undo, snapshots and restart and advance the links clock, not content.
+Board update accepts `relationVocabulary: [{kind, ink, directed}]` (up to 64 unique kinds,
+including an explicit empty list). `ink` is supports/contradicts/cites/derived/informs/related;
+pin, agent and warning colours are not relation inks. Unknown kinds remain legal.
+
+For lifecycle, `derived-from`, `contradicts` and `supersedes` point **source → dependent**;
+`depends-on` points **dependent → prerequisite**. `cites`, `supports`, `related`, wiki links
+and portals are navigational unless an explicit dependency or provenance source is also recorded.
+The server captures `sourceRevision` when a dependency is authored or retyped. A reason or
+style edit never resets that baseline. Source changes propagate through dependencies, including
+cycles, but not unrelated references. A new contradiction or superseding decision needs review.
+Folder defaults stop at links. Portal source warnings stay separate from the portal's own lifecycle.
+
+`data.provenance` accepts `sources: [{boardId, cardId, contentRevision?, observedAt?,
+availability?: "live"|"cached"|"unavailable"}]` and an inert `recipe: {tool, input?, prompt}`.
+Explicit provenance requires `sourceKind`, nonempty `sourceUri` and `refreshStrategy`;
+invalid or incomplete input returns 400 with field errors rather than being discarded.
+Omit provenance to use the normal inference for file, image and other sourced nodes.
+Keep `observedAt`/source revision distinct from retrieval `syncedAt`/`fetchedAt`; retrieval-only
+updates do not advance content or validation. Cached/unavailable warnings never claim a fresh check.
+The human's **Ask agent to refresh this board** sends steering; Canvas executes no recipe tool.
+
+Retired cards remain in raw layout, direct reads and search, marked retired. They leave briefs,
+pinned context, nearby active context and README summaries. Restore is audited, never validation.
+Brief entries carry qualification and board overviews carry `readmeQualification` separately.
+Every brief also carries a lifecycle snapshot independent of its content cursor. With
+`lifecycle.complete: true`, its retired/unknown/review lists replace cached qualification; keys
+are JSON `[boardId,cardId]`. If the snapshot exceeds a quarter of the budget, `complete: false`
+explicitly requires rechecking cached cards via lifecycle-get before reuse. Empty lists in an
+incomplete snapshot do not mean healthy or active. Delivered entries still carry qualification.
+
 `GET /health` includes `contracts: ["pmx-embedded-workbench-v4"]` when the daemon
 enforces `expectedBoardId` and `expectedContentRevision` preconditions, bulk-write
 fences/locks using validated geometry and affected automatic parent frames only,
@@ -39,11 +178,25 @@ content auto-height or indirect parent-group reflow after editing a child.
 
 ## Board tours
 
-- `GET /api/canvas/tour` → `{ tour: { stops: [...] }, derived: boolean }`.
+- `GET /api/canvas/tour` → `{ tour: { stops: [...] }, derived: boolean, position: number | null }`
+  (`position` is the stop being presented, or `null`).
 - `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.
+- `POST /api/canvas/tour/go` with `{ "stop": 2 }` or `{ "step": "next" | "previous" }`
+  (plus optional `"present": false`) moves the shared tour cursor →
+  `{ ok, index, total, stop }`; 400 when the stop does not exist or the board has no stops.
+  Broadcasts `canvas-tour-step`; idle workbenches start presenting unless `present` is false.
+- `POST /api/canvas/tour/exit` leaves presentation in every viewer (`canvas-tour-exit`).
+- `POST /api/canvas/camera/move` with exactly one of `nodeId`, `rect: { x, y, width, height }`
+  or `viewport: { x, y, scale }`, plus optional `duration`, `easing`, `padding`, `pullback`
+  → `{ ok, stop, viewport }`. Broadcasts `canvas-camera-move`; browsers ease to the target in
+  their real canvas area. `viewport` is the server's estimate from the last reported window
+  size and is stored as the board viewport. 404 for an unknown node.
+
+Tour steps and camera moves are navigation: no undo entry, no agent-presence write, no
+scope-fence check.
 
 The [tour model and recording walkthrough](cli.md#tour-and-presentation) describes
 targets, duration, easing, padding, and pullback. Open `/workbench?present=1` to hide
@@ -62,16 +215,71 @@ trusted workbench deletes a board — deletion requires both `x-pmx-workbench: 1
 per-boot `x-pmx-workbench-token` embedded in the served `/workbench` HTML;
 the marker alone is not authority. Public HTTP integrations must not delete
 boards. In-process SDK embedding hosts retain deletion authority.
-Every change emits a
-`boards-changed` SSE frame with `{ activeBoardId, boards }`.
-
-`category` is a folder path, for example `Engineering/Canvas/Decisions`.
+Every change emits a `boards-changed` SSE frame with
+`{ activeBoardId, boards, catalogEpoch, catalogRevision, reloadRevision, boardGeneration }`.
+Board-list and board-mutation responses carry the same catalog fields. Within a server
+process, `catalogRevision` increases for every catalog snapshot; reject older or duplicate
+snapshots before changing board identity or camera. Only a current `connected` handshake
+authorizes a replacement `catalogEpoch`. `reloadRevision` is a sticky library-restore marker,
+retained by subsequent GETs so an overtaking response cannot hide a restore.
+`boardGeneration` identifies the loaded board incarnation, including revisits and restores.
+
+`folder` 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.
 
+Home offers Folders, Map, and Graph. Folders are neutral organization, independent
+of links. `PATCH /api/canvas/boards/<board-id>` accepts
+`mapPosition: { x, y }` (finite numbers) to persist a dragged Map position in
+SQLite, or `mapPosition: null` to return to the generated folder layout.
+Creating a copy records `previousBoardId` as its source board ID; it does not
+open either board.
+Board-list `links` expose qualified `boardId`/`cardId` targets; native card
+connections include `cardTitle` (null if missing), so footers need not display raw IDs.
+
+### Markdown previews and saved links
+
+`POST /api/render` accepts `{markdown, nodeId?, expectedBoardId?}` and returns `{html}`.
+For a card-aware preview, send its captured board ID with `nodeId`; a different active
+board returns 409 without HTML, so a delayed request cannot borrow another card's bindings.
+Workbench previews discard responses that no longer belong to the displayed board or draft.
+Plain Markdown without `nodeId` renders independently of a card.
+
+Saved text replays its durable wiki bindings, including unresolved targets. Changed drafts
+retain existing bindings and may resolve newly authored references by title; previews do not
+persist those bindings. An explicit save is required to bind a saved unresolved reference.
+
+### Connected memory projection
+
+`GET /api/canvas/memory-graph?focus=<focus>&depth=2&projection=full` returns the
+connected-memory projection used by Home and discovery in the context brief. Omit
+`focus` for the library; otherwise use a board ID, a JSON qualified node key
+`["board-id","card-id"]` (or `["board-id",null]`), or `pins`. URL-encode focus.
+`depth` is an integer from 0–4, default 2: undirected hops including board/card
+membership. Explicit 0 is valid; empty depth values are rejected. An unknown focus returns 404.
+`projection` is `full` (default) or `boards` (compact board-only summaries).
+Home Map uses `boards` and loads depth-2 details when you select a board.
+Map/Graph coalesce live catalog, layout, pin and reconnect updates. Failed reads preserve
+the last graph with **Retry**. Neither a refresh nor an agent board switch resets the
+human's library camera or selection; explicit Open board/card leaves the library.
+
+The response has `nodes`, `edges`, `unresolvedLinks: [{ source, ref }]`, `focus`,
+and `depth`. Nodes have board-qualified `key`, `boardId`, optional `cardId`,
+`kind` (`board` or `card`), `title`, `summary` (at most 280 characters), `folder`,
+`inContext`, and `summaryOnly: true`. Edges have qualified `from`/`to`,
+`source`/`target`, `missing`, and kind `member`, `portal`, `wiki`, `card`, or
+`previous`. These projection kinds are separate from a card edge's rich `relationKind` and `reason`.
+Graph reads mark delivered links seen on each owning board without switching
+boards; they do not count as full content reads. Card nodes carry `linksRevision`
+captured with the projection, so a later write is never acknowledged by an earlier read. In focused views,
+`linksComplete: false` means some incident relations fall outside the requested
+depth; that card's links are not acknowledged as seen. SDK: `getMemoryGraph({ focus,
+depth, projection })`; MCP: `canvas_query { action: "graph", focus, depth, projection }`.
+Cross-board briefs give incoming and outgoing connections readable board/card titles.
+
 ```bash
 # List boards (most recently opened first) and which is open (null = Home)
 curl http://localhost:4313/api/canvas/boards
@@ -79,23 +287,31 @@ 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
+# Create a board (optionally in a folder) — it is NOT opened
 curl -X POST http://localhost:4313/api/canvas/boards \
-  -H "Content-Type: application/json" -d '{"name":"Q4 planning","category":"Planning"}'
+  -H "Content-Type: application/json" -d '{"name":"Q4 planning","folder":"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)
+# Rename and/or file under a folder on Home ("folder": "" 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"}'
+  -H "Content-Type: application/json" -d '{"name":"Q4 planning (final)","folder":"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>"}'
 
+# Pin a board into the agent's working set (its README and pinned cards reach every
+# brief, whichever board is open; read-only context, never a write target), or unpin it.
+# A repeat pin keeps its first attribution. Every board carries `pin` ({pinnedBy,
+# pinnedAt, reason} or null).
+curl -X POST http://localhost:4313/api/canvas/boards/<board-id>/pin \
+  -H "Content-Type: application/json" -d '{"reason":"Q4 rests on it"}'
+curl -X POST http://localhost:4313/api/canvas/boards/<board-id>/unpin
+
 # Open a board, or Home with {"id":null} — also available to agents
 curl -X POST http://localhost:4313/api/canvas/boards/open \
   -H "Content-Type: application/json" -d '{"id":"<board-id>"}'
@@ -222,6 +438,9 @@ curl http://localhost:4313/api/canvas/state
 # Search the library (omit scope for the active board)
 curl "http://localhost:4313/api/canvas/search?q=auth&limit=10&scope=library"
 
+# Restrict to a board inside a folder subtree without opening it
+curl "http://localhost:4313/api/canvas/search?q=auth&boardId=<id>&folder=Research"
+
 # Validate the current layout. Reports collisions, groupFrameOverlaps (a group
 # frame covering a node that is not one of its members, nested members
 # included — e.g. after a group auto-fits around enlarged children),
@@ -254,6 +473,52 @@ curl -X POST http://localhost:4313/api/canvas/schema/validate \
 
 ## Nodes
 
+Search accepts intersecting `boardId` (stable ID) and `folder` filters. A folder
+matches itself and slash-boundary descendants; `folder=` selects unfiled boards.
+Filters default an omitted scope to `library`. Explicit `scope=active` stays
+constrained to the active board, even when another board is selected. Unknown or
+nonmatching selections return no results. Filtering precedes ranking and limits;
+term-OR discovery and whole-term ranking remain unchanged. Search never navigates.
+
+`POST /api/canvas/node` accepts `destinationBoardId` to create on a stored board
+without opening it or changing the human's active board. `expectedBoardId` remains
+an **active-board** precondition, not a destination selector; stale values return 409.
+Unknown destinations return 404. This is creation-only, not background CRUD.
+
+Optional `requestId` identifies a logical creation within the workspace database.
+Use the same id, destination and creation input when retrying; a new intentional
+creation needs a new id even for identical content. Node and receipt commit in one
+transaction. Receipts survive restart, deletion, undo and snapshot restore; replay
+returns the original creation payload without recreating or updating anything.
+Reusing an id with different input/destination returns 409. Object key order and
+transport-only `full`, `verbose`, `agentId`, `expectedBoardId` do not affect identity.
+Receipts survive individual node removal but are deleted with their owning board.
+
+Either field opts into static creation only: `markdown`, `status`, `context`,
+`ledger`, `trace`, `diff`, `mermaid`, and plain `html`. Runtime-backed types, generated
+HTML primitives, ghost intents and membership mutations are explicitly refused (400),
+never redirected to the active board. Persistent workspace storage is required.
+New creations are conservatively refused (403) if either the active or destination
+board has a scope fence or per-agent territory. Inactive creation creates no ghost or
+undo entry on the active board and starts no runtime watcher. Only genuine changes
+to active cards' incoming link clocks can emit an active layout; the destination's
+layout is never substituted. Library metadata refreshes through `boards-changed`.
+Auto-placement uses the destination's nodes. Batch entries accept the same fields;
+batches still prefix-commit and assigned references work on receipts as on new nodes.
+
+`POST /api/canvas/group` and `POST /api/canvas/edge` also accept
+`destinationBoardId`, `requestId` and `expectedBoardId` under the same commit,
+retry, scope-fence and no-navigation contract. Groups resolve all `childIds` on
+the destination, preserve their positions by default, and support explicit frames
+and `childLayout`. Membership changes respect human edit locks, including moved
+descendants and affected parent frames. Edges resolve `from`/`fromSearch` and
+`to`/`toSearch` on the destination; `toBoardId` independently selects a foreign
+target board, not the owner of the edge. Both endpoints' relation clocks update
+without changing their content/freshness. A retry returns its original group or
+edge receipt, preserving later edits and not resurrecting removals. A request ID
+cannot be reused for a different creation operation. Inactive group membership
+updates/removals and other background CRUD remain unsupported.
+
 ```bash
 # Add a node
 curl -X POST http://localhost:4313/api/canvas/node \
@@ -294,6 +559,26 @@ against the node's top-level `contentRevision`; stale content returns `409`
 without changing the node. Conditional edits cannot request webpage refresh.
 The private MCP App uses these guards to reject stale board actions and note drafts.
 
+Native Markdown Save captures the currently observed revision for each attempt. Newer content
+arriving during rendering or network delivery refuses that attempt and keeps the draft; a later
+deliberate human Save may replace already-observed work. Queued saves advance their precondition
+only through successful acknowledgements of their own preceding saves, never through an external
+revision or an automatic retry after conflict. Acknowledgements from before a restart, restore,
+or board replacement cannot update canonical content, clear an unsaved draft or advance queued
+preconditions, even if the replacement reused the same card ID with a lower revision.
+Board switches detach the old cards until the
+replacement layout arrives, keeping unsaved drafts under their original board/card. The replacement
+`GET /api/canvas/state` supplies the captured `expectedBoardId` query (`null` for Home), so another
+tab switching boards before the read returns causes `409`, not a layout attributed to the wrong board.
+
+For file-backed Markdown, `PATCH /api/canvas/node/:id` accepts `persistFile: true` with top-level
+`content`, `expectedBoardId`, and `expectedContentRevision`. It checks both preconditions and
+validates the patch before synchronously writing the existing workspace `.md` file and card,
+normalizing line endings to LF. In this mode, `data` accepts only the `rendered` preview;
+change other metadata separately, never alongside the disk save.
+A stale/refused save changes neither disk nor card. Ordinary PATCH remains data-only, and the
+hosted MCP App still refuses file-linked edits. This is not a crash-recovery disk/SQLite transaction.
+
 Replacing a JSON-render node's `spec` preserves its current title; include `title`
 to rename it explicitly. A new authored spec still resets the viewer's local drafts.
 
@@ -336,6 +621,25 @@ workspace root returns `403`, and an unknown node id returns `404`.
 
 ## Edges
 
+Edge creation accepts optional `toBoardId` to target a card on another board;
+`from` stays on the open source board. For example:
+`{ "from": "source-card", "to": "remote-card", "toBoardId": "target-board", "type": "references" }`.
+The source footer and human More-menu card picker expose remote connections.
+Auto-arrange stays local; static export omits remote lines but preserves explicit
+external connection evidence.
+
+Markdown saves bind `[[Board]]`, `[[Board#Card]]`, and `|alias` variants to durable
+IDs in server-owned `data.wikiLinks`. IDs take precedence; names/titles must be
+unique. Existing bindings survive renames, while ambiguous or missing targets
+stay explicit and never guess or silently retarget. Rendering uses saved bindings:
+an unresolved link stays unresolved until an explicit save; Undo and restore preserve bindings.
+Rich-text editing preserves wiki references and aliases; editing a visible label changes
+the alias, not the bound target. Code spans/fences are ignored.
+The human Create dialog for an unresolved board-only link creates exactly its
+authored name and re-saves the source using its captured board/revision; a stale
+source is refused. Rich relationship kinds/reasons and source-driven lifecycle qualification
+use the [shared contract above](#relations-source-observations-and-active-context).
+
 ```bash
 # Add an edge
 curl -X POST http://localhost:4313/api/canvas/edge \
@@ -379,6 +683,11 @@ inspection or screenshots when the drawn shape matters.
 
 ## Viewport
 
+Workbench camera writes include an optional `clientId` (1–128 characters), echoed
+in `canvas-viewport-update`. The originating tab ignores that echo so an older
+Fit or zoom cannot cancel a newer local gesture. Other tabs and agent camera
+commands still update the view. The identifier is echo metadata, not authorization.
+
 ```bash
 # Set the camera transform (screen = world * scale + {x,y})
 curl -X POST http://localhost:4313/api/canvas/viewport \
@@ -437,16 +746,30 @@ curl http://localhost:4313/api/canvas/pinned-context
 curl 'http://localhost:4313/api/canvas/context?consumer=codex&budget=16000'
 ```
 
+At most 20 cards can be pinned at once. `remove` processes every supplied ID, even when
+a merged receipt has recorded more than 20 IDs across sessions; unrelated pins stay.
+
 `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 each pin's neighbours (reason `near`: up to five unpinned cards within
-600 px, nearest first, as title + a short summary with `near: { pinNodeId,
-pinTitle }`; pin a card to send its full content), 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.
+beginning. An explicit `since` never advances a cursor. The brief is a map,
+not a dump: an `overview` entry for the open board first, then pins, then each
+pin's neighbours (reason `near`: up to five unpinned cards within a 600 canvas-pixel
+edge-to-edge gap, nearest first, with `near: { pinNodeId, pinTitle }`), then relevant
+current-board changes and asks, then pinned boards (reason `pinned-board`: the board and its pinned
+cards), then compact linked or same-folder board context. Cards arrive as title,
+a short summary (`summaryOnly: true`) and their relations; a pin puts a card
+first, it does not send its full text. On a later read a changed card lists what changed in
+`changes` (`text`, `links` or both) and marks relations drawn or changed since the cursor,
+e.g. `(new, by a person)`. Every item carries source board/card IDs:
+use them with the board/node read route to pull a card in full when you need it,
+rather than guessing from the summary. Reading inactive boards does not open them.
+Entries with capped or omitted relations declare `linksComplete: false` and do
+not acknowledge that card's complete links revision as seen. Near-pin, human,
+linked README and pinned-board card summaries carry no card relations. Complete
+relation entries carry their captured `linksRevision`; delivery is qualified by
+`sourceBoardId`, never by a bare card ID across boards. Single-card and layout
+reads record delivered content but do not acknowledge incident relations. Read
+a complete graph or brief relation entry for relations; pull cards separately for full content.
 
 ## AX context and focus
 
@@ -454,6 +777,10 @@ 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.
 
+AX node excerpts declare `linksComplete: false`. AX reads, including annotation
+anchors, never acknowledge incident relations as seen; use a complete graph or
+brief relation entry for that acknowledgement.
+
 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.
@@ -516,7 +843,15 @@ curl "http://localhost:4313/api/canvas/ax/context-reads?limit=50"
 # read that delivered its content: when, who, and the content revision it had.
 # A node whose current contentRevision is newer was changed since it was read.
 # pins maps each pinned node with a known pinner to { pinnedBy, pinnedAt, reason }.
+# board is the latest agent read on that board of any kind ({ lastReadAt, lastReadBy } or
+# null): a pinned board whose map reached an agent reads as read even before any card is pulled.
+# A brief's card summaries mark nothing read; only a full pull of a card does.
+# links maps each node to the newest linksRevision any read carried (summaries count, since a
+# brief summary carries the card's relations). An edge whose revision is newer than both
+# ends' links value has not been seen by an agent; the workbench marks it on the link's pill.
 curl "http://localhost:4313/api/canvas/ax/context-status?board=<board-id>"
+# boards=<id>,<id> also returns boards: { <id>: { lastReadAt, lastReadBy } | null } for each
+# listed board, so the context chip reads every pinned board's status in one request.
 
 # 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
@@ -525,7 +860,11 @@ curl "http://localhost:4313/api/canvas/ax/context-status?board=<board-id>"
 # currently open board. MCP bytes measure the final formatted text response.
 # readNodeIds lists every serialized node in what the agent received (pinned or
 # not); the server keeps those on the board and stamps their revisions. Omitted,
-# it defaults to deliveredNodeIds.
+# it defaults to deliveredNodeIds. seenNodeIds adds the nodes that arrived only as
+# summaries, which marks their links seen; omitted, it defaults to readNodeIds.
+# For a captured graph/brief, also pass seenLinkRevisions: {"node-1": 12} from
+# the delivered linksRevision values, not revisions fetched after delivery.
+# Only seenNodeIds with captured entries are acknowledged when this map is supplied.
 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}'
@@ -592,7 +931,7 @@ without a `session-end`.
 curl http://localhost:4313/api/canvas/ax/presence
 # → { ok, presences: [{ sessionId, source, agentId, label, phase, detail,
 #      focusNodeId, cursor, attached, opCount, contextUsage, lastSeenAt }],
-#     budget: { used, total }, sessionActive,
+#     sessionActive,
 #     activity: [{ id, at, sessionId, label, op, summary, nodeId }] }  # newest first, last 50
 
 # Attach a session and report a phase (idle | thinking | tooling | waiting-approval)
@@ -619,13 +958,13 @@ a transport writer folds into it), bounded to the last 50 and kept after a
 writer fades. Detaching (`attached: false`, `session-end`) removes the
 presence outright — an ended session never lingers as an external writer.
 
-**The context meter is an estimate unless the host says otherwise.** `budget`
-is a token estimate (chars ÷ 4) of the `pinned-context` payload against
-`PMX_CANVAS_CONTEXT_BUDGET_TOKENS` (default 32000) — what the human's pins
-would cost the agent, not the agent's live window; the top bar labels it
-**Pins**. A host that knows the agent's real usage reports it on the presence
-(`contextUsage: { used, total }` on `POST /api/canvas/ax/presence` /
-`set-presence`); the top bar then shows **Context** with those numbers. The
+**The context summary shows a cost, not a budget.** The top bar's context
+summary shows what the brief costs, as ≈ tokens (about four characters per
+token). There is no share, meter or clipped state: a brief longer than one page
+continues on the next read. A host that knows how many tokens its agent holds
+reports it on the presence (`contextUsage: { used, total }` on
+`POST /api/canvas/ax/presence` / `set-presence`); the context panel then also
+names that count ("Copilot’s whole context holds 42.8k tokens"). The
 bundled Copilot extension reports it from the SDK's `session.usage_info`
 event (root agent, coalesced to one report per 500 ms); the legacy
 `context-usage` workbench event feeds the single attached session the same
@@ -663,21 +1002,27 @@ When that session ends (`attached: false`, `session-end`, or the idle expiry)
 the stream carries one `agent-session-ended` frame:
 
 ```json
-{ "label": "Copilot", "parentAgentId": null, "endedAt": "…", "endedBy": "agent",
+{ "label": "Copilot", "writer": "copilot", "parentAgentId": null, "startedAt": "…", "endedAt": "…", "endedBy": "agent",
   "unchanged": false, "counts": { "items": 4, "done": 3, "cancelled": 1, "rejected": 0, "held": 0 },
-  "snapshot": { "id": "…", "name": "Before session · Copilot · 14:00" },
-  "context": { "read": [{ "id": "…", "title": "Brief" }], "pinned": [{ "id": "…", "title": "Chart", "reason": "…" }],
-               "created": [], "edited": [], "changedSinceRead": [{ "id": "…", "title": "Brief" }] } }
+  "snapshot": { "id": "…", "name": "Before session · Copilot · 14:00", "boardId": "…" },
+  "context": { "read": [{ "id": "…", "boardId": "…", "title": "Brief" }], "pinned": [{ "id": "…", "boardId": "…", "title": "Chart", "reason": "…" }],
+               "created": [], "edited": [{ "id": "…", "boardId": "…", "title": "SMB", "change": "rewrote the second paragraph", "before": "…", "after": "…" }],
+               "changedSinceRead": [{ "id": "…", "boardId": "…", "title": "Brief" }] } }
 ```
 
 `context` is what the session did with the board's context: nodes whose content an
 agent read since the session attached, pins the agent made (with their reason), nodes
-it created and edited (against the pre-session snapshot), and pinned nodes changed
+it created and edited (against the pre-session snapshot; each edit says what it did in
+`change` and keeps bounded `before`/`after` excerpts around the first difference), and pinned nodes changed
 after their latest read. A session that only read or pinned is not `unchanged`.
+Every touch carries its `boardId` (null with no active board); receipt identities are
+board + node ID, so equal IDs on different boards are not merged.
 
 `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).
+Its `boardId` identifies the owning board: a retained receipt offers to reopen it before
+comparing, including sessions that only added or removed cards. Snapshot access remains board-scoped.
 The browser shows a receipt only for a changed top-level session: `unchanged: true`
 and worker endings (`parentAgentId` set) never open, replace, or extend a popup —
 the orchestrator's receipt covers the board since it attached. An empty
@@ -687,8 +1032,26 @@ There is at most one receipt. Qualifying endings that arrive while it is up merg
 into it ("3 sessions ended", their labels, the union of their context); a merged
 receipt has no *View diff* and points to History, which keeps each session's
 snapshot. The receipt is kept until dismissed so restore/diff actions do not
-disappear on a timer. A single session's *View diff* is `GET /api/canvas/snapshots/<id>/diff` against that
-snapshot, and restoring the snapshot undoes the session. Adapters should end their session
+disappear on a timer. It also stays across direct board switches, with a button to
+reopen an edited card's board; Home dismisses it. Undo and Unpin are unavailable
+on another board, and the lens and edit marks only apply to the active board's touches.
+The browser shows one stacked Before/After at a time, marking removed and added words;
+its Undo restores the whole card, not just the excerpt, and leaves cards whose latest edit is human alone.
+The caption distinguishes clipped excerpts ("undoes the whole card"), an already restored card
+("the card shows Before again"), and a protected human edit ("undo would lose your edit").
+A single session's *View diff* is `GET /api/canvas/snapshots/<id>/diff` against that
+snapshot, and restoring the snapshot undoes the session. *Undo* on one edited card is
+`POST /api/canvas/snapshots/<id>/restore-node` with `{ "nodeId": "…", "preserveHumanEdits": true }`:
+the server checks the latest editor at the write boundary, so an unseen human edit is safe even
+before polling delivers it. A skipped restore returns `{ "ok": true, "id": "…", "restored": false,
+"skipped": "human-edit" }`; a successful restore returns `restored: true`. Without
+`preserveHumanEdits`, explicit restore can replace human content. The same option is available on
+`canvas_snapshot { action: "restore-node", id, nodeId, preserveHumanEdits: true }` and
+`canvas.restoreSnapshotNode(id, nodeId, { preserveHumanEdits: true })`. That card's content goes
+back to the snapshot's, as one undoable edit; position, group, links and pins stay (file cards
+refuse, they follow their file; a card whose type changed since answers 409).
+The receipt's Unpin removes only its recorded pins and is safe to repeat; pins added later stay.
+Adapters should end their session
 explicitly so the human gets the receipt promptly rather than after the idle
 expiry. The browser's *Start agent session* button is this same endpoint
 (`source: "browser"`, `attached: true`) — subsequent agent-less writes are
@@ -898,6 +1261,25 @@ curl -N http://localhost:4313/api/workbench/events
 The browser, the CLI `watch` command, and the MCP resource notifications
 all consume this stream. Auto-reconnect with exponential backoff.
 
+The direct workbench's `connected` snapshot renews its per-process
+`workbenchToken` (also embedded in boot HTML) over both SSE and polling.
+A same-bundle daemon restart does not reload the page or discard an open draft.
+Registered writes and file saves marked as workbench calls with a supplied stale capability
+return 409 until reconnect renews it; they are never silently recorded as agent
+edits. A refused Markdown save retains its draft and enabled Save control for
+retry after reconnect. Drafts and complete save queues are qualified by board + card in the
+current tab, surviving close/reopen and board switches (not a page reload); superseded drafts
+cannot resume an older render and overwrite newer text. Do not log or forward this human capability: hosted MCP
+workbench polling strips it from tool results, including hydration metadata.
+
+`canvas-layout-update` carries its owning `boardId` (null for Home), `catalogEpoch`
+and `boardGeneration`; accept its baseline only for the activation in the accepted catalog.
+`context-pins-changed` carries the owning `boardId`. A board transition is a new baseline,
+not a deletion or unpin. Same-board reconnects install a fresh baseline without closing
+the editor or discarding its draft and selection, whichever snapshot arrives first.
+Remote-edge endpoint changes also publish `boards-changed` so card titles and
+missing-target states update; ordinary geometry changes do not refresh the catalog.
+
 `agent-presence` frames carry the full presence snapshot (the same body as
 `GET /api/canvas/ax/presence`) on every change, including TTL expiry — a
 client never needs its own expiry timer. `agent-session-ended` carries the
@@ -922,12 +1304,24 @@ through any proxy:
 # current cursor. With `since=<seq>`: only events after that cursor.
 curl "http://localhost:4313/api/workbench/poll"
 curl "http://localhost:4313/api/workbench/poll?since=42"
+# Optional long poll: return when an event arrives, or after at most 1000 ms.
+curl "http://localhost:4313/api/workbench/poll?since=42&waitMs=1000"
 ```
 
-Responses are `{ ok, transport: "poll", snapshot, seq, events }` — poll again
-with `since=<seq>` every couple of seconds. A `since` from a previous server
-run or one that fell off the bounded event ring recovers with a fresh
-snapshot. The browser client uses this automatically: if the SSE stream
+Responses are `{ ok, transport: "poll", snapshot, seq, sessionId, events }`.
+Poll again with `since=<seq>`. Without `waitMs`, the response is immediate;
+with it, a caught-up cursor waits for the next event. The wait is clamped to
+0–1000 ms and ends on request cancellation or server shutdown. A cursor with
+pending events or needing a full snapshot never waits. The direct HTTP browser
+client requests a 1000 ms wait and pauses 80 ms between completed requests:
+cursor movement arrives promptly without fast empty polling while idle.
+Hosted MCP-app tool polling retains its two-second cadence; SSE is unchanged.
+
+A cursor that fell off the bounded event ring recovers with a fresh snapshot.
+After a server restart, an out-of-range cursor receives a snapshot; if the old
+cursor happens to fit the new ring, the browser detects the changed `sessionId`
+and requests a new snapshot without `since`. The browser client uses polling
+automatically: if the SSE stream
 produces no event within 3 seconds of connecting, it switches to polling (and
 tells the boot screen to wait for the fallback instead of alarming). Pages
 served by an Amp orb (`AMP_ORB` set — the same stamp that drives srcdoc mode)
@@ -935,6 +1329,34 @@ skip SSE entirely and default straight to polling. Force a transport with
 `/workbench?transport=poll` (or `transport=sse` to disable the fallback /
 override the orb default).
 
+## Workspace UI beta settings
+
+`GET /api/canvas/settings` returns `{ ok: true, workspaceSettings: {
+agentSessions: false, knowledgeLifecycle: false } }`. Both switches default to
+false, including existing libraries with no saved settings.
+
+`POST /api/canvas/settings` accepts a partial object such as
+`{ "agentSessions": true }`. Values must be booleans (not strings, numbers,
+or null); omitted switches are preserved. Success returns the full canonical
+`workspaceSettings` only after SQLite persistence; writes without a workspace
+database fail. Settings are workspace-wide SQLite metadata, independent of
+boards and snapshots, and included in whole-library backups/restores.
+
+The HTTP-only operations `settings.get` / `settings.set` are UI preferences,
+not agent MCP tools or restrictions on session/knowledge APIs. Writes never
+create a board or attribute agent activity. POST requires the workbench's
+`X-PMX-Workbench: 1` UI marker; unmarked API writes receive 403. The hosted
+app-only bridge supplies that marker for this preferences operation alone,
+without forwarding the daemon's human-author token or exempting subsequent
+canvas edits from agent protections. The marker is a UI-policy convention,
+not authentication against a caller deliberately forging HTTP headers; hosted
+UI isolation relies on the host honoring app-only tool visibility.
+
+`settings-changed` carries `{ workspaceSettings: { agentSessions,
+knowledgeLifecycle } }`, including after a full-library restore. The `connected`
+snapshot includes `workspaceSettings` for SSE reconnect and polling recovery.
+Clients use these ordered events/snapshots as canonical, not late POST replies.
+
 ## Session theme override (host-default theming)
 
 `/workbench?theme=<name>` gives that browser session its own theme without