pmx-canvas 0.8.2 → 0.9.1

package/docs/mcp.md

@@ -1,7 +1,7 @@
 # MCP reference
 
 PMX Canvas ships an MCP stdio server with **24 tools**, **15 static canvas
-resources**, and one canvas resource template, plus per-skill resources at
+resources**, and two canvas resource templates, plus per-skill resources at
 `canvas://skills/<name>` and the `skill://{name}/{+path}` template. The server emits
 `notifications/resources/updated` when canvas state changes — humans pin
 nodes in the browser, agents are notified immediately.
@@ -16,11 +16,54 @@ nodes in the browser, agents are notified immediately.
 > (23 tools: 17 composites plus 6 standalones). The current import workflow
 > adds `canvas_import` (24 tools: 18 composites plus 6 standalones). **Prefer the composites.**
 
+## Knowledge lifecycle data
+
+`canvas_board` adds `knowledge-list`, `category-set` (`category`), `category-remove` (`id`), and `folder-set`
+(`path`, nullable `categoryId`, nullable `lifecycleOverride`). These workspace actions never
+open a board. `relation-preset-set` (`preset: {id, name, vocabulary}`) and `relation-preset-remove`
+(`id`) manage the shared Home template library without rewriting boards or connection kinds.
+Category removal refuses explicit folder assignments (including empty folders), naming the folders to reassign or clear first; it never clears inherited policies. Unknown IDs are 404; missing/blank IDs are invalid input. `canvas_node` adds `lifecycle-get` (`id`, optional `board`), `lifecycle-set`
+(`id`, nullable `lifecycleOverride`), `review` (`id`, `outcome`, `evidence`, `applied`), and
+`lifecycle-restore` (`id`, `evidence`). Writes accept `expectedBoardId` and obey scope/edit locks.
+See [the canonical fields and semantics](http-api.md#knowledge-lifecycle-data-plan-017-slice-1).
+Effective reads include qualification: due reasons, unknown/retired, separate clocks and source warnings.
+Retired cards leave briefs and pinned context, but direct reads/search retain them marked retired.
+Never mark applied without actually applying an outcome; only successful evidence-backed
+retain/revise/externalize with a matching `expectedContentRevision` validates. Capture that revision
+from the card content you actually checked: missing or stale preconditions refuse the review.
+For dependencies, capture `qualification.observations` with the checked sources and send it as
+`expectedSources`. Missing, changed or unavailable sources refuse validation; do not refresh the
+tokens without rechecking the evidence. Brief `lifecycle` snapshots update qualification independently
+of the content cursor; `complete: false` requires rechecking cached cards before reuse.
+Records retain the reviewed revision; content persistence failure adds no record.
+Restore never validates and only explicit restore reverses retirement.
+Newly authored cards start fresh, with no synthetic review. Medium first expires at
+creation plus its cadence; Fast/Slow at a later use/resumed session. Use
+`data.contentOrigin: "imported"` when creating historical text. Imports and existing
+undated cards keep unknown freshness; edits never reset it. Groups and board portals
+need an explicit lifecycle override for factual decay, but still carry source warnings.
+Moving/unfiling a board checks both the active scope and the target board's stored global
+scope or writer territory. Opening Home or another board cannot bypass the target's fence.
+
+`canvas_edge` add/update accept open `kind` and `reason`; update null clears either.
+`canvas_board` update accepts `relationVocabulary: [{kind, ink, directed}]`.
+Use `derived-from`, `contradicts`, `supersedes` source → dependent, and `depends-on`
+dependent → prerequisite. Other relations and wiki/portal links do not imply validation dependencies.
+Provenance may record source revision/observation separately from retrieval time, plus an inert
+recipe for a human-requested refresh. Reading or regenerating never validates.
+
+Create a board portal with `canvas_node { action: "add", type: "board", data: { boardId: "<target-board-id>" } }`
+on its source board. It appears as a `portal` edge in `canvas://graph`, independently of folder membership.
+
 ## Board tours
 
 `canvas_view { action: "get-tour" }` returns `{ tour, derived }`, using group
 reading order when there is no saved tour. `canvas_view { action: "set-tour",
 tour: { stops: [...] } }` persists an ordered tour; `tour: null` resets it.
+`canvas_view { action: "tour-go", stop: 0 }` (or `step: "next" | "previous"`)
+presents a stop in the workbench, `"tour-exit"` leaves presentation, and
+`canvas_view { action: "move", nodeId | rect | viewport, duration, easing, padding, pullback }`
+eases the camera. None of these enter undo history.
 See the [tour model and CLI walkthrough](cli.md#tour-and-presentation) for stop
 fields. Recording is a local CLI operation; no remote recording/file-writing
 tool is added.
@@ -240,13 +283,13 @@ its `action` to the same operation the legacy tool used, so results are identica
 | Composite | `action` values | Replaced (removed in v0.3.0) |
 |-----------|-----------------|----------|
 | `canvas_import` | `list` · `read` · `submit` · `unavailable` | Agent half of human-consented document import; request, cancel, and commit remain human-only HTTP/SDK actions |
-| `canvas_node` | `add` · `get` · `update` · `remove` | `canvas_add_node`, `canvas_get_node`, `canvas_update_node`, `canvas_remove_node`, `canvas_add_html_node` (`add` + `type:"html"`), `canvas_add_html_primitive` (`add` + `type:"html"`, `primitive:"<kind>"`), `canvas_refresh_webpage_node` (`update` + `refresh:true`) |
+| `canvas_node` | `add` · `get` · `update` · `remove` · `lifecycle-get` · `lifecycle-set` · `review` · `lifecycle-restore` | Node CRUD, effective lifecycle, audited reviews and explicit retirement restore |
 | `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` · `workboard` | `canvas_describe_schema`, `canvas_validate_spec`, `canvas_add_json_render_node`, `canvas_stream_json_render_node`, `canvas_add_graph_node` |
 | `canvas_edge` | `add` · `update` · `remove` | `canvas_add_edge`, `canvas_update_edge`, `canvas_remove_edge` |
 | `canvas_group` | `create` · `add` · `ungroup` | `canvas_create_group`, `canvas_group_nodes`, `canvas_ungroup` |
 | `canvas_history` | `undo` · `redo` | `canvas_undo`, `canvas_redo` |
-| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` · `get-tour` · `set-tour` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear`, `canvas_remove_annotation` |
-| `canvas_query` | `context` · `search` · `layout` · `validate` | `context` is new; the others replace `canvas_search`, `canvas_get_layout`, `canvas_validate` |
+| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` · `get-tour` · `set-tour` · `tour-go` · `tour-exit` · `move` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear`, `canvas_remove_annotation` |
+| `canvas_query` | `context` · `graph` · `search` · `layout` · `validate` | Budgeted context and summary-only connected memory; the others replace `canvas_search`, `canvas_get_layout`, `canvas_validate` |
 | `canvas_webview` | `status` · `start` · `stop` · `resize` · `evaluate` | `canvas_webview_status`, `canvas_webview_start`, `canvas_webview_stop`, `canvas_resize`, `canvas_evaluate` |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | `canvas_open_mcp_app`, `canvas_add_diagram`, `canvas_build_web_artifact` |
 | `canvas_ax_state` | `get` · `set-focus` · `set-policy` · `report-capability` · `presence` · `set-presence` | `canvas_get_ax`, `canvas_set_ax_focus`, `canvas_set_ax_policy`, `canvas_report_host_capability` |
@@ -255,11 +298,16 @@ its `action` to the same operation the legacy tool used, so results are identica
 | `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` · `reads` · `read-status` | `canvas_get_ax_timeline`, `canvas_record_ax_event`, `canvas_add_evidence`, `canvas_send_steering` (`reads` is the context read log; `read-status` is per node: last read, by whom, at which content revision) |
 | `canvas_ax_delivery` | `claim` (long-polls with `timeoutMs`) · `mark` | `canvas_claim_ax_delivery`, `canvas_mark_ax_delivery` |
 | `canvas_intent` | `signal` · `update` · `clear` | _(new — Ghost Cursor of Intent; no legacy standalone tool)_ |
-| `canvas_board` | `list` · `get` · `create` · `create-from` · `open` · `update` | Boards, explicit shared-workbench switching, README designation, and transactional inactive copies |
-| `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | `canvas_snapshot` (legacy save tool), `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`, `canvas_diff` — removed in v0.4.0 after one deprecated minor |
+| `canvas_board` | `list` · `get` · `create` · `create-from` · `open` · `update` · `pin` · `unpin` · `knowledge-list` · `category-set` · `category-remove` · `folder-set` · `relation-preset-set` · `relation-preset-remove` | Boards and explicit workspace category/folder/shared-preset data |
+| `canvas_snapshot` | `save` · `list` · `restore` · `restore-node` · `delete` · `gc` · `diff` | `canvas_snapshot` (legacy save tool), `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`, `canvas_diff` — removed in v0.4.0 after one deprecated minor |
+
+For receipt-safe single-card Undo, use `canvas_snapshot { action: "restore-node", id,
+nodeId, preserveHumanEdits: true }`. The server skips a card whose latest editor is human,
+returning `restored: false, skipped: "human-edit"`; only `restored: true` means it restored
+the content. Omitting the option permits an explicit restore over human content.
 
-Board categories are nested folder paths: `canvas_board { action: "update", id:
-"<id>", category: "Engineering/Canvas/Decisions" }`. Use `category: ""` to
+Board folders are nested folder paths: `canvas_board { action: "update", id:
+"<id>", folder: "Engineering/Canvas/Decisions" }`. Use `folder: ""` to
 unfile a board. Moving preserves its ID and content; list results expose the
 full path for navigating the memory library.
 
@@ -273,17 +321,56 @@ of the first markdown card. Humans can change the designation using **Set as REA
 clicking **README** clears it. Read-only tasks leave the board unchanged.
 
 `canvas_board { action: "create-from" }` accepts `sourceBoardId`, `name`, optional
-`category`, `nodeIds`, `includeReadme`, `includeStructure`, and `preview`. Preview
+`folder`, `nodeIds`, `includeReadme`, `includeStructure`, and `preview`. Preview
 first: `prompt`, `response`, `trace`, and `mcp-app` are not reusable. Creation is
 transactional and inactive, assigns fresh node/edge IDs, and copies no pins, AX
 state, or history. Groups and the designated README are opt-in.
 
+The copy records `previousBoardId` for its source. Board `update` accepts
+`mapPosition: { x, y }` or `null` to persist/reset a Home Map position.
+`canvas_edge { action: "add", from, to, toBoardId, type }` connects the open
+board's source card to a card on another board without opening the target.
+
+### Connected memory discovery
+
+`canvas_query { action: "graph", focus: "pins", depth: 2 }` and
+`canvas://graph{?focus,depth}` read connected-memory summaries for Home,
+links/backlinks, and brief discovery. The tool accepts `projection: "full" | "boards"`
+(default `full`); `boards` returns compact board-only summaries. The resource
+uses the default full projection. Omit focus for the whole library, or use
+a board ID, a JSON qualified node key `["board-id","card-id"]` (board key:
+`["board-id",null]`), or `pins`. Depth is an integer 0–4, default 2;
+traversal is undirected and includes membership hops. Explicit 0 is valid; empty
+depth values are rejected. URL-encode resource focus.
+The result has `nodes`, `edges`, `unresolvedLinks: [{ source, ref }]`, `focus`,
+and `depth`. Every node is `summaryOnly: true`, with summary at most 280
+characters. Reads count links seen on each owning board only when that node's
+incident relations are complete. A focused node with `linksComplete: false`
+does not acknowledge omitted links. Card nodes carry their captured `linksRevision`,
+so later changes are not acknowledged by an earlier delivered graph.
+`canvas://ax-context` and `pmx-current-context` deliver excerpts and annotation
+anchors, not complete incident relations; neither marks those relations seen.
+Single-card and layout reads record delivered content, not incident relations.
+Use a complete graph or brief relation entry to acknowledge those relations.
+Reads never mark full card content read or
+switch the workbench. Pull needed cards in full separately.
+No new tool is added: the tool count stays 24.
+
 Library search is `canvas_query { action: "search", query: "auth", scope:
 "library" }`. It returns board/card IDs and never switches the active board.
-
-To author a new board, create it, then call `canvas_board { action: "open",
-id: "<returned-board-id>" }` and verify `activeBoardId` in the response before
-writing. Opening changes the shared workbench the human sees and the target of
+Exact and whole-term matches rank ahead of embedded substrings; substring discovery
+still works, so `V2 platform` precedes `TV2 pictures` for `V2` without dropping the latter.
+
+Search also accepts intersecting `boardId` and `folder` filters. Folder includes
+exact and descendant paths, with `""` for unfiled boards. Filters default omitted
+scope to library; explicit `scope: "active"` remains constrained to the active
+board. Filtering happens before ranking/limit, and unknown selections return no
+results. These are selectors, not board switches.
+
+To author static cards on a new board without interrupting the human, create the
+board and pass its id as `destinationBoardId` to `canvas_node { action: "add" }`.
+For active-board operations, call `canvas_board { action: "open", id: "<returned-board-id>" }`
+and verify `activeBoardId` before writing. Opening changes the shared workbench the human sees and the target of
 subsequent writes; it is not a private agent selection. Another participant can
 switch it later, so recheck after interruptions. `id: null` opens Home. Deletion
 remains human-only.
@@ -312,6 +399,34 @@ board: "<id>" }` or `canvas_node { action: "get", id: "<node-id>", board:
 "<id>" }`. Unknown boards error, and full inactive-board reads resolve stored
 blob references.
 
+`canvas_node { action: "add", type: "markdown", destinationBoardId: "<id>",
+requestId: "<logical-operation-id>", content: "..." }` creates on that board without
+opening it. `expectedBoardId` still guards the active board. `requestId` is optional;
+reuse it only for identical retries, and use a new id for intentional identical new
+content. Receipts persist across restart and return the original creation payload
+even after the node is deleted; mismatched reuse fails. Either field restricts creation
+to static markdown/status/context/ledger/trace/diff/mermaid/plain-html nodes. Runtime
+types, primitives, intents and membership mutations fail explicitly. Both boards'
+scope fences apply conservatively. Batch entries support these fields and named refs;
+this does not add inactive-board update/remove support. See [the full creation/retry
+contract](http-api.md#nodes).
+
+`canvas_group { action: "create" }` and `canvas_edge { action: "add" }` accept
+the same `destinationBoardId`, `requestId` and active `expectedBoardId` guard.
+Create cards, group their IDs and connect them in one `canvas_batch` using named
+refs, without switching the human's board. Groups resolve children on the
+destination and preserve positions unless `childLayout` is supplied. Edge source
+ownership uses `destinationBoardId`; `toBoardId` remains an independent cross-board
+target. Retry receipts preserve edits/removals and survive restart. This extends
+creation, not background update/remove operations; runtime and intent restrictions
+on static node creation remain in force.
+
+`canvas_node { action: "update" }` accepts `expectedBoardId` and `expectedContentRevision`
+to refuse stale writes. Ordinary updates change the card only. File-backed Markdown may opt
+into `persistFile: true` with both preconditions and top-level `content` to save the existing
+workspace `.md` file and card together. In this mode, `data` accepts only the `rendered` preview;
+refused saves change neither. See [the file-save contract](http-api.md#nodes).
+
 For Mermaid nodes, `canvas_node` actions `add` and `update` accept
 `data: { fit: "contain" | "none" }`. Contain is the default, shrinking overflow
 uniformly; none keeps 100% with scrolling. Use Open as site for 100% without
@@ -461,8 +576,8 @@ migrating an older integration.
 
 ## Resources
 
-There are 15 static canvas resources below and one URI-template resource,
-`canvas://context{?budget,consumer,since}`. Bundled skills add the static
+There are 15 static canvas resources below and two URI-template resources,
+`canvas://context{?budget,consumer,since}` and `canvas://graph{?focus,depth}`. Bundled skills add the static
 `canvas://skills/<name>` resources and a separate `skill://{name}/{+path}` file
 template; those dynamic package entries are not part of the core count.
 
@@ -470,13 +585,14 @@ template; those dynamic package entries are not part of the core count.
 |----------|-------------|
 | `canvas://pinned-context` | Content of pinned nodes + nearby unpinned neighbors |
 | `canvas://context{?budget,consumer,since}` | Budgeted cross-board brief with a durable consumer cursor |
+| `canvas://graph{?focus,depth}` | Summary-only library or focused board/card graph; undirected membership-inclusive depth 0–4 (default 2) |
 | `canvas://ax` | PMX AX state: focus, work items, approval gates, review annotations |
 | `canvas://ax-context` | Agent-readable pinned and focused AX context, plus a compact `delivery` lead block (`pendingSteering` newest-first + `totalPending`/`omittedPending` counts), timeline summary, and host capability |
 | `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations, elicitations, mode requests, and tool/prompt policy |
 | `canvas://ax-timeline` | Bounded AX timeline: recent agent-events, evidence, and steering messages |
 | `canvas://ax-pending-steering` | Undelivered steering an adapterless MCP client can claim, act on, and mark delivered |
 | `canvas://ax-delivery` | Steering delivery state (delivered flag) for diagnostics |
-| `canvas://boards` | Boards with README summaries, resolved links/backlinks, target titles, and the open board id |
+| `canvas://boards` | Boards with README summaries, resolved links/backlinks, target titles, a layout `preview` (cards as 0–1 rectangles), `mapChars` (the rough size of a pinned board's map), and the open board id |
 | `canvas://schema` | Running-server create schemas and json-render catalog metadata |
 | `canvas://layout` | Full canvas state (all nodes, edges, viewport) |
 | `canvas://summary` | Compact overview: counts, pinned titles, viewport |
@@ -489,7 +605,19 @@ Read context at the start of work. For the cross-board brief, use a stable,
 unique `consumer` per agent/adapter only when durable incremental delivery is
 wanted. Omitting both `consumer` and `since` starts from the beginning; explicit
 `since` does not update a cursor. The budget is UTF-16 code units (default
-16,000; maximum 100,000), not model tokens. Pins are prioritized. If an entry is
+16,000; maximum 100,000), not model tokens. The brief is a map, not a dump: an
+`overview` of the open board (README summary, folder, links and backlinks), then each card as
+its title and a short summary (`summaryOnly`), with why it was pinned and its relations (edges to
+and from other cards); pinned cards lead, then the cards near each pin, then what changed.
+On a later read, a card that changed since the cursor says what changed in `changes`
+(`["text"]`, `["links"]` or both), and a relation drawn or changed since then ends with
+`(new, by codex)` / `(changed, by a person)`; generated code-graph links are never marked.
+Boards pinned into the working set (`canvas_board { action: "pin" }`) arrive as maps too (reason
+`pinned-board`): the board's summary and relations, and its pinned cards as summaries. Pull
+what you need in full with `canvas_node { action: "get", board, id, full: true }`; a summary
+does not mark a card read, a full pull does. A first read larger than the budget carries the
+overview and pins, then cards oldest first, and returns `cursor.next`; a `consumer` continues
+from it automatically, otherwise pass it as `since` to read on. If an entry is
 truncated, follow its source board/card IDs with `canvas_board get` and
 `canvas_node { action: "get", board, id, full: true }` rather than inferring the missing text.
 Full node reads record only that node's delivered content revision; compact metadata
@@ -581,7 +709,7 @@ changes:
 - AX timeline mutations (agent-events, evidence, steering) notify
   `canvas://ax-timeline` and `canvas://ax-context`
 - All mutations notify `canvas://layout`, `canvas://summary`,
-  `canvas://spatial-context`, `canvas://history`, and `canvas://code-graph`
+  `canvas://spatial-context`, `canvas://history`, `canvas://code-graph`, and `canvas://graph`
 
 This closes the human-to-agent loop: spatial curation in the browser becomes
 an immediate signal in the agent's context.

package/docs/node-types.md

@@ -1,6 +1,7 @@
 # Node types
 
-`board` is a native text-only link. Set `data.boardId` to the durable target ID.
+`board` is a native text-only link. Set `data.boardId` to the durable target ID. Its header pin pins the
+linked board into the agent's working set (`canvas_board { action: "pin" }`), not the portal card.
 Titles resolve from that ID, so renames and folder moves are safe; deleted
 targets render explicitly as missing. It is not an iframe or a cross-board card
 edge. Static exports lock the card and intentionally do not embed the target
@@ -50,8 +51,14 @@ conversation rendering and are not created through public APIs.
 Full node reads expose server-owned `createdBy`, `lastEditedBy`, and
 `contentRevision`. Authors distinguish human, agent, system, and unknown;
 legacy nodes remain unknown. The revision advances on semantic content changes,
-including group membership and undo, but not moves or resizes. These fields
-describe provenance, not permission, and caller-supplied author fields are ignored.
+including group membership and undo, but not moves or resizes. Links are tracked
+apart: `linksRevision` advances on both ends when a link is added, retyped,
+relabelled or removed, and never advances `contentRevision`. Each edge carries
+the `revision`, `changedBy` and `changedAt` of its latest such change — its author
+until someone changes it again — and the `createdBy` and `createdAt` of whoever first
+drew it (generated code-graph and board-map edges carry none). Undoing a deletion
+restores the link with its original author. These fields describe provenance, not permission, and
+caller-supplied author fields are ignored.
 
 ## Choosing the right visual tier
 
@@ -64,6 +71,12 @@ that fits the work — each step adds capability and bundle weight.
 | 2 | `html` | You have/can write self-contained HTML+JS (Chart.js, D3, custom widgets, interactive demos) | None — sandboxed iframe |
 | 3 | `web-artifact` | You need a full React/Tailwind app with shadcn components, routing, or shared state | Build step |
 
+## Markdown tasks
+
+Tick a task directly on its card, including quoted and nested tasks. A card click changes
+only that task's `[ ]` or `[x]` marker, preserving the rest of the source exactly.
+Task-shaped text in code examples and raw HTML checkboxes are not Markdown task controls.
+
 ## File nodes
 
 File nodes display project files with line numbers and language detection.
@@ -223,6 +236,17 @@ canvas_render({
 `outline`. Older saved specs using `label` or status variants such as
 `success`/`warning` are normalized during validation.
 
+Replacing a JSON form's spec keeps its existing card title unless a non-empty title is
+explicitly supplied, and reloads the viewer for the new spec. The viewer uses bundled IBM
+Plex Sans and Mono fonts, including hosted viewers and offline exports.
+During embedded JSON/graph refreshes, the previous viewer stays visible until its replacement
+has restored its tab-local state and committed the new UI; document load alone is not readiness.
+After document load, runtime readiness waits up to 10 seconds and retries a failed
+handoff once, keeping the last painted document. If that retry fails, the error
+toast and history say **Reload to retry**. A later healthy authored update can recover.
+This readiness limit is not an overall network-load timeout.
+Authored spec revisions still reset drafts to the spec's initial state.
+
 Specs preserve top-level `state` and element-level `repeat`, `watch`, and
 `slots`. Use `$bindState` with JSON Pointer paths for editable form values;
 `$state` only reads a value. Nested repeats can use `statePath: { "$item": "tasks" }`
@@ -379,6 +403,10 @@ canvas_node({
 A fragment without `<html>`/`<head>` is wrapped in a full document
 automatically. Default size is 720×640.
 
+Changing a mounted HTML card's `data.axCapabilities` reboots its iframe bridge, including
+late enable and disable/re-enable. Emits from the old document are rejected; enabling AX
+still cannot exceed the HTML node's capability ceiling.
+
 Presentation mode is opt-in. Raw HTML nodes do not show the browser `Present`
 button unless callers set `presentation: true`; prefer the `presentation`
 primitive when the user explicitly asks for a PowerPoint-like deck, pitch,
@@ -518,6 +546,33 @@ canvas_group({ action: 'create', title: 'Auth Module', childIds: ['node-1', 'nod
 
 All edges support labels, styles (solid/dashed/dotted), and animation.
 
+Native edges optionally carry `toBoardId`: `from` belongs to the open source
+board and `to` identifies a card on that target board. These connections appear
+in the visible source card footer with readable board/card titles; missing
+targets are disabled. The human **More** menu opens a remote-card picker.
+Auto-arrange remains local. Static exports omit remote lines but retain explicit
+external connection evidence.
+
+Markdown saves bind `[[Board]]`, `[[Board#Card]]`, and either form with `|alias`
+to durable board/card IDs in server-owned `data.wikiLinks`. Exact IDs take
+precedence; name/title matches must be unique. Saved bindings survive renames;
+ambiguous or missing targets stay explicit and never guess or silently retarget.
+Rendering follows saved bindings: unresolved links stay unresolved until an explicit
+save, and Undo or restore preserves the binding.
+Relation and target-availability updates refresh the Markdown preview without replacing
+an unsaved document or Source draft or its selection. Saving a file-backed draft also
+rejects an older in-flight draft render.
+Legacy Markdown without a binding record gets a one-time persisted backfill;
+saved empty or unresolved records are not reinterpreted on reads.
+Code spans and fenced code are ignored. An unresolved board-only link offers a
+human Create dialog: it creates exactly the authored board name and re-saves
+the source using its captured board and revision, refusing a stale source.
+Wiki links, backlinks, portals, native edges, and create-from's `previousBoardId`
+share the Home/agent memory projection. Native edges also carry open `kind` and `reason`,
+independently of their line type. Boards may set `relationVocabulary: [{kind, ink, directed}]`.
+Explicit dependency relations or provenance sources drive downstream review; ordinary navigation
+does not. See [lifecycle and source contracts](http-api.md#knowledge-lifecycle-data-plan-017-slice-1).
+
 | Type | Use case |
 |------|----------|
 | `flow` | Sequential steps, data flow |

package/docs/plans/design-gaps-2026-10-08.md

@@ -0,0 +1,53 @@
+# Design gaps — drawn, not built (audit 2026-10-08)
+
+Every drawing in `docs/design/` for waves 0 and 1 (plus the 600 px reference) was compared with
+the code, element by element. Waves 0 and 1 were thought done; these items were drawn and never
+built. Wave 2+ drawings are out of scope (not built by plan). Spot-checked items are marked ✓.
+
+## Wave 0 — the foundation (shipped in 0.8.0, these were missed)
+
+| # | Drawing | Gap | Size |
+|---|---|---|---|
+| 1 | Chrome §7 | Rail Settings menu — **built 2026-10-08**; the drawing now keeps the Eraser beside Text note (13 tools) | done |
+| 2 | Chrome §9 | Section labels: a markdown node shown as a heading — no titlebar, no footer, controls on hover. Not built. | M |
+| 3 | Chrome §10 | Floating-chrome lane: fit and focus keep a 44 px lane clear at the top; the Updates pill is a small rounded "Updates 1" chip, not today's uppercase edge tab. Fit/focus only clear the bottom chrome ✓, so titles land under the pill. | M |
+| 4 | Tokens §4 | Type scale with an 11 px floor: 66 sizes below 11 px remain in global.css ✓, more inline. | M |
+| 5 | Tokens §4 | Radii and elevation tokens barely used (174 raw radii; `--e-2` used once); ~15 chrome surfaces hard-code black shadows, so Daylight/Sepia shadows are not ink-tinted; glows remain on active/neighbour/search-match nodes. | M |
+| 6 | TokenSystem / Main / Themes | Harbor palette drift (`--c-panel-soft`, `--c-text-soft`, `--c-dim`, an accent-blue dot grid instead of neutral); `--c-on-accent` missing (`--c-contrast-fg` used); High-contrast `muted` #aaa vs #ccc. | S |
+| 7 | Main / HeaderMarks | Node header: a fill behind every titlebar (drawn: fill only when pinned); title in `--c-text-soft` (drawn: `--c-text`). | S |
+| 8 | Types1 / Types3 | Per-type foundation pass not done: markdown footer into ⋯; status (sentence case, progress bar, time); context (rows, one-line token meter); ledger (time column, UI font); trace (10 px card, running in agent violet); file (toolbar into the header, 12 px code); group label (sentence case, "3 nodes"); prompt key-hint chip; response role labels and violet agent turns; board "not found" relink state. | L |
+| 9 | Raw colours | 12 raw `rgba()` colours in node renderers; the hex guard skips `rgba()`. | S |
+
+## Wave 1 — context made visible (in progress)
+
+Already tracked: NearPin tethers and drag preview; Home pinned-boards panel; BoardPins category
+glyphs (move 13).
+
+| # | Drawing | Gap | Size |
+|---|---|---|---|
+| 10 | NearPin §3 | The moment it changes: the chip pulses once on drop, fades on leaving, and one Updates entry says "'X' is now near 'Y' — the agent gets its title and summary" / "…left… — it is out of the agent's brief". Not built. | M |
+| 11 | NearPin §2 | Hover card actions "Pin to put it first" and "Show pins". The hint has text only. | S |
+| 12 | HeaderMarks / LinksChanged | The amber word is "changed", not "changed since read" ✓; its hint should name what changed ("text changed · 1 new link"). | S |
+| 13 | AgentContext / HeaderMarks | **Decided 2026-10-08: pinned cards only.** "Read" only accumulates and the agent reads across boards, so on unpinned cards it would soon mark everything; the receipt and the dim-untouched lens answer "what did it read". The drawings show "read" on cards the agent read without a pin ("read anyway") and near + read / near + changed together. Today read state shows only on pinned cards, and design.md says "the one state chip (near, or the read state)". | M |
+| 14 | LinksChanged | **Decided 2026-10-08:** link authorship stays until a person edits or relabels the link, shown as a small ✦ on the label with the author's identity in the hint (the agent today, the person once boards are shared); "not seen by" stays as built. Waiting for the drawing. The drawing keeps "by <agent>" on a link until you edit it; the build clears it once a read carries either end (matching "not seen by"). | S |
+| 15 | LinksChanged | The brief marks changed cards "links changed" / "text changed, links changed" and new relations "(new, by Pepe)"; a pinned card is never sent as "changed"; a person's removed link writes an Updates entry. **Built 2026-10-10:** changed and pinned entries carry `changes` (`text`/`links`), relations drawn or changed since the cursor end "(new, by …)" / "(changed, by …)", a removed link writes "Link removed · “A” – “B” (type)". A person shows as "by a person": edges record no human name, so "by Pepe" waits for shared boards (hosted version, vision Part 4). | M |
+| 16 | ContextChip / 600 | Panel tags carry eye / eye-off / warn icons (text only today); the 600 px sheet drops "near <pin>" and shortens the caption; at 600 px the agent chip shrinks to a 24 px violet initial placed after the summary. | S |
+| 17 | AgentContext | "Suggested" state (dashed violet node, Accept / Dismiss, lens count, receipt row) — absent. Not named in wave 1's function list. **Dropped 2026-10-10** by the maintainer: the agent changes the canvas directly, and asks and suggestions go through the composer. | L |
+| 18 | AgentContext | Edited: violet bar for the session and "see change" (diff + undo); receipt: "Tell <agent>" on changed lines, Undo on Edited, per-edit descriptions, header "What <agent> did · This session · start–end"; a live per-session lens count. **Built 2026-10-10:** the header, "Tell <agent>", Undo on Edited (via `snapshot.restore-node`), per-edit descriptions, "See change" (Before / Now + Undo this card, on the receipt line; its open view awaits a drawing), the violet session bar, and the live count in the agent chip. | M |
+| 19 | Home | Beyond the pinned-boards panel: library tree with counts and pins, "Library · N boards", breadcrumb + folder README, "New board here", board cards (thumbnail, README line, "18 cards", "↔ 4 links"), a board-details pane (in context, README, pinned cards, links, Open). "nodes" should read "cards". **Built 2026-10-10:** tree with counts and pin dots, pinned boards with ≈ tokens, breadcrumb, "New board here", "+ New folder", subfolder cards with "N in context", board cards (thumbnail, README line, cards, ↔ links), details pane (in-context switch, README, pinned cards, links, Open board, ⋯ move/rename/create from/delete), "cards" not "nodes". Not built: the folder's README line (no folder README exists yet) and the Map/Graph tabs (wave 2). | L |
+| 20 | Pane600 | Minimap off by default under 700 px (always on today ✓); agent activity summary "Claude · 4 read · 1 edited" in the top bar; Home at 600 px ("In context: 3 boards ≈ 21k tokens", details as a bottom sheet). **Built 2026-10-10:** Home at 600 px (in-context banner, folder picker, subfolder chips, board rows, details bottom sheet) and the activity summary in the agent chip (at ≤ 760 px the chip shows only its initial, per ContextChip600). | M |
+| 21 | Context | Command-bar chips prefixed with ✦ ✓ — ✦ now means "an agent wrote this", so the pinned-context chips say the wrong thing; drawn as a plain blue chip with title + ×. | S |
+
+## Stale code found on the way
+
+- `global.css` `.node-title`: `min-width: 9ch` is cancelled by the next line, `min-width: 0` ✓.
+- A `global.css` comment still describes the context chip as a "share of its budget… clipped".
+- `CommandBar.tsx` comment says "gold ✦ chips".
+
+## Suggested order
+
+1. Small, unambiguous wave-1 fixes before 0.9.0: 12, 16, 21, the stale code; 20's minimap default.
+2. Decide 13 and 14 (design session draws the answer if needed).
+3. Close wave 1: 10, 11, 15, 18, the tracked tethers, and the Home redesign (19, 20) together.
+4. A wave-0 pass after 0.9.0: 2, 3, 7, then the token sweep (4, 5, 6, 9), then per-type (8).
+5. "Suggested" (17) needs a function first; plan it with wave 5 (agent output as nodes).