pmx-canvas 0.8.0 → 0.9.0

package/skills/pmx-canvas/references/full-reference.md

@@ -384,16 +384,23 @@ draw visual attention to critical paths.
 
 ### Layout: spacing and groups
 
-Agents tend to pack boards too tightly. Give nodes room to breathe — readability beats density.
-
-- **Default spacing:** leave a clear gap between neighbors — roughly half a node's width
-  horizontally and half its height vertically. A 280×180 node reads well with ~360px between
-  column origins and ~260px between row origins.
-- **When nodes are connected by edges, space them further apart** so the edge line, its arrowhead,
-  and its label are clearly visible in the gap between nodes. Crowded nodes hide the flow — this is
-  the most common cause of an unreadable board.
-- **Inside a group, keep the same breathing room** (groups no longer auto-pack children, so the
-  spacing you set is what the human sees). Edges between grouped children especially need the gap.
+Use the smallest clear gap that serves the content and its relationships. Both crowded labels
+and oversized empty channels make a board harder to use.
+
+- **Unconnected notes and walkthroughs:** start compact, often a 40–80px clear gap. For a
+  280×180 node with a 40px gap, origins are 320px apart horizontally and 220px vertically.
+  This is an unconnected-card example, not a minimum for connected cards. Do not reserve
+  half a card's width or a large uniform channel where there is no edge.
+- **Connected cards:** provide enough room for the rendered edge line, arrowhead, label and
+  authorship marks. Short flow labels may need less room than long explanations. After content settles,
+  inspect the rendered relations at the intended viewing zoom, including after auto-arrange.
+  `validate` checks node non-overlap, not label/arrowhead clearance or relation readability;
+  widen or reroute crowded relations rather than relying on a fixed pixel gap.
+- **After rendering:** use settled card sizes, not just the requested creation heights. Close
+  gaps left by automatic shrinking, check the numbered reading order, and frame a readable
+  cluster or tour stop. A whole-board fit is orientation, not proof that body text is readable.
+- **Inside a group, apply the same distinction** between compact notes and clear relation
+  channels. Groups no longer auto-pack children, so the spacing you set is what the human sees.
 - **Size a group frame larger than its children's bounding box** so the group header — including the
   node-count badge — stays visible and isn't hidden under the top-left child. For an explicit
   (manual) group frame, add margin on every side (≈56px) plus room at the top for the header rather
@@ -438,15 +445,15 @@ single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) di
 | Composite | `action` values | What it does |
 |-----------|-----------------|--------------|
 | `canvas_import` | `list` · `read` · `submit` · `unavailable` | Process human-requested imports: inspect metadata/controlled bytes, submit reviewable Markdown with references/warnings/agent description, or report unavailable. Request/cancel/commit are human-only |
-| `canvas_node` | `add` · `get` · `update` · `remove` | Create / read / mutate / delete a node. **`add` covers html + primitives too**: `{ action:"add", type:"html", html:"…" }` and `{ action:"add", type:"html", primitive:"choice-grid", data:{} }` — no separate add-html tool needed |
+| `canvas_node` | `add` · `get` · `update` · `remove` · `lifecycle-get` · `lifecycle-set` · `review` · `lifecycle-restore` | Node CRUD, lifecycle qualification, evidence-backed review and reversible retirement; retired cards leave active context |
 | `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` · `workboard` | Schema introspection, spec dry-run validation, native json-render / graph node creation, and a live AX work-item board |
 | `canvas_edge` | `add` · `update` · `remove` | Connect / edit / disconnect nodes |
 | `canvas_group` | `create` · `add` · `ungroup` | Manage spatial group containers |
 | `canvas_history` | `undo` · `redo` | Time travel through the mutation ring buffer |
-| `canvas_board` | `list` · `get` · `create` · `create-from` · `open` · `update` | Boards, shared-workbench switching, README designation, links/backlinks, and inactive copies |
-| `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | Named snapshots: save/list/restore/delete, garbage-collect old ones, diff current canvas vs a snapshot (`diff` takes `snapshot`, not `id`) |
-| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` · `get-tour` · `set-tour` | Auto-arrange, pan-to-node, fit viewport, clear the board, delete annotations, read/persist ordered presentation stops (`tour: null` derives group order) |
-| `canvas_query` | `context` · `search` · `layout` · `validate` | Read the budgeted cross-board brief, find nodes by keyword, read full layout, or **`validate`** the board for node collisions / group-containment / dangling edges |
+| `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 workspace categories/folder properties/shared relation templates; knowledge writes never open a board. Template edits/deletion never rewrite boards or connections. `category-remove` takes `id` and refuses explicit folder assignments, including empty folders; reassign or clear them first. |
+| `canvas_snapshot` | `save` · `list` · `restore` · `restore-node` · `delete` · `gc` · `diff` | Named snapshots: save/list/restore/delete, garbage-collect old ones, diff current canvas vs a snapshot (`diff` takes `snapshot`, not `id`); `restore-node` puts one card (`nodeId`) back to its content in snapshot `id` |
+| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` · `get-tour` · `set-tour` · `tour-go` · `tour-exit` · `move` | Auto-arrange, pan-to-node, fit viewport, clear the board, delete annotations, read/persist ordered presentation stops (`tour: null` derives group order), present a stop / exit, ease the camera to a node, rect or viewport (never an undo step) |
+| `canvas_query` | `context` · `graph` · `search` · `layout` · `validate` | Read the budgeted brief or summary-only connected memory graph, find nodes, read full layout, or **`validate`** collisions / containment / dangling edges |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | Hosted MCP apps, the Excalidraw diagram preset, and bundled web artifacts (folds `canvas_open_mcp_app` / `canvas_add_diagram` / `canvas_build_web_artifact`) |
 | `canvas_webview` | `status` · `start` · `stop` · `resize` · `evaluate` | Headless Bun.WebView automation for the workbench (folds the `canvas_webview_*` / `canvas_resize` / `canvas_evaluate` tools) |
 | `canvas_ax_state` | `get` · `set-focus` · `set-policy` · `report-capability` · `presence` · `set-presence` | Read AX state; set AX focus; patch tool/prompt policy (the scope fence is human-set, read-only here); report host capability; read / set agent presence (phase, cursor, focus, attached session) |
@@ -484,6 +491,88 @@ reads inactive boards without opening them. Board links are native text-only
 creation: `prompt`, `response`, `trace`, and `mcp-app` are excluded; README and
 group structure are optional; fresh IDs are allocated; pins, AX state, and
 history are not copied; the source remains unchanged and the new board inactive.
+The new board records `previousBoardId` pointing to its source.
+
+### Connected memory (wave 2)
+
+Home Folders, Map and Graph, wiki links/backlinks, and brief discovery share one
+board/card projection. Folders are neutral and independent of links. Map uses
+deterministic folder regions and saved draggable SQLite `mapPosition`; board
+update accepts `{ x, y }` or `null` to reset. Graph uses neutral circular clusters,
+not force simulation; labels are in selection details, filters in the shared
+toolbar, with no synthetic Home board, levels, or simulation sliders.
+
+Read it with `canvas_query { action: "graph", focus: "pins", depth: 2 }`,
+`canvas://graph{?focus,depth}`, `GET /api/canvas/memory-graph`, SDK
+`getMemoryGraph({ focus, depth })`, or CLI `pmx-canvas memory-graph`. Focus is
+a board ID, a JSON qualified key `["board-id","card-id"]` (or
+`["board-id",null]`), or `pins`; omitted means the library. URL-encode resource
+focus. Depth is an integer 0–4, default 2, traversing undirected links including
+membership. Explicit 0 is valid; empty depth and bare CLI `--depth` are rejected.
+HTTP, SDK and the MCP tool accept `projection: "full" | "boards"` (default `full`);
+CLI uses `--projection full|boards`. The graph resource uses the default full projection.
+Home Map uses compact `boards` summaries, loading depth-2 details on selection.
+Metadata edits and dragging do not refetch relationships; **Refresh** reloads them.
+Cross-board briefs give incoming and outgoing connections readable board/card titles.
+The result has `nodes`, `edges`, `unresolvedLinks: [{ source, ref }]`,
+`focus`, and `depth`. Nodes include qualified `key`, `boardId`, optional `cardId`,
+`kind`, `title`, `summary`, `folder`, `inContext`, and `summaryOnly: true`;
+summaries are capped at 280 characters. Edge projection kinds are `member`,
+`portal`, `wiki`, `card`, and `previous`, with qualified `from`/`to`,
+`source`/`target`, and explicit `missing`. Reads count links seen only when a node's
+incident relations are complete; focused nodes with `linksComplete: false` do
+not acknowledge omitted links. Brief entries with capped or omitted relations also
+carry `linksComplete: false`; near-pin, human, linked README and pinned-board
+summaries do not acknowledge unseen relations. Graph cards and complete brief
+relations carry their captured `linksRevision`, so later writes remain unseen;
+brief delivery is qualified by source board, never by a bare cross-board card ID.
+AX excerpts and annotation anchors, including `canvas://ax-context` and
+`pmx-current-context`, never mark incident relations seen; read a complete graph
+or brief relation entry instead.
+Single-card and layout reads record content delivery, not incident relations.
+Reads never switch boards or record full content reads. Pull cards in full
+when needed. Counts stay 24 tools, 15 static canvas resources; there are now two
+canvas templates, context and graph, besides the skill file template.
+
+Markdown save resolves `[[Board]]`, `[[Board#Card]]`, and `|alias` forms into
+server-owned `data.wikiLinks` ID bindings. IDs win; name/title matches must be
+unique. Existing bindings survive renames. Ambiguous/missing links stay explicit
+and never guess or silently retarget. Rendering follows saved bindings: unresolved
+links stay unresolved until an explicit save, and Undo/restore preserves bindings.
+Legacy Markdown without binding metadata gets a one-time persisted backfill;
+saved empty or unresolved records are not reinterpreted on reads.
+Code spans/fences are ignored. A human
+Create dialog for an unresolved board-only link creates exactly the authored
+name and re-saves its source using the captured board/revision, refusing stale
+source writes.
+
+Once the board list has loaded, all workbench context-pin writes send the captured
+`expectedBoardId`; a server-side board switch returns 409 instead of changing
+another board's pins. Receipt pin actions require reopening the owning board.
+
+Embedded JSON/graph runtime readiness waits up to 10 seconds after document load
+and retries a failed handoff once while retaining the last painted document.
+After another failure, the error toast/history say **Reload to retry**; a later
+healthy authored update can recover. This is not an overall network-load timeout.
+
+Native edge add accepts optional `toBoardId`: `from` is on the open source board,
+`to` is a card on the target board. CLI: `pmx-canvas edge add --from <source> --to <target>
+--to-board <board-id> --type references`. The human More menu offers a card
+picker and the source footer shows remote connections. Auto-arrange stays local;
+static export omits remote lines but shows explicit external connection evidence.
+Edges accept open `kind`/`reason`; update null clears them. Boards accept
+`relationVocabulary: [{kind, ink, directed}]`, with six fixed relation inks, never pin/agent/warning
+colours. `derived-from`, `contradicts`, `supersedes` point source → dependent; `depends-on` points
+dependent → prerequisite. Ordinary references/wiki links/portals do not propagate review due.
+Lifecycle reads return qualification, including source observations. Validating dependent cards
+requires `expectedSources` from the evidence checked, plus `expectedContentRevision`; stale or
+unavailable sources refuse. Retired cards leave briefs/pinned context but remain marked in search
+and direct reads. Brief `lifecycle.complete: false` requires rechecking cached cards before reuse;
+empty incomplete lists are not a health claim. Recipe metadata is inert and refresh never validates.
+For human review, Home's Review needed count filters to affected boards, and each Review button
+opens an affected card. More → Review offers one short note and Checked, still correct; Not now
+writes nothing. Settings and history discloses clocks, policies and advanced outcomes. The folder
+tree is navigation, and No review policy is informational rather than an outstanding task.
 
 Use `canvas_board { action: "open", id: "<board-id>" }` to open a created or
 existing board before authoring. Verify the returned `activeBoardId`; opening
@@ -869,7 +958,7 @@ Useful workbench selectors:
   the eraser in the rail's Annotate popover; agents can remove a known annotation ID with
   `canvas_view { action: "remove-annotation" }`.
 - Canvas chrome (rail-chrome-v2): `.tool-rail`, `.top-bar` (`.connection-dot`, `.agent-chip`,
-  `.gate-badge`, `.context-budget`, `.external-indicator`, `.start-session-btn`),
+  `.gate-badge`, `.context-chip`, `.external-indicator`, `.start-session-btn`),
   `.connection-banner`, `.canvas-region`, `.session-panel`, `.command-bar`, `.selection-bar`,
   `.activity-feed`, `.writers-sheet`, `.session-receipt`, `.snapshot-panel` (the History
   drawer), `.minimap`, `.empty-state`, `.command-palette`, `.expanded-overlay-panel`.
@@ -1042,6 +1131,9 @@ what the human has set up and what they're focusing on.
 
 | Resource | What it provides |
 |----------|-----------------|
+| `canvas://context{?budget,consumer,since}` | Budgeted cross-board map brief with optional durable consumer cursor |
+| `canvas://graph{?focus,depth}` | Summary-only connected memory projection, library or focused undirected membership-inclusive exploration |
+| `canvas://boards` | Board library with README summaries, links/backlinks and previews |
 | `canvas://pinned-context` | Content of pinned nodes + nearby unpinned neighbors |
 | `canvas://schema` | Running-server create schemas and json-render catalog metadata |
 | `canvas://layout` | Full canvas state (viewport, nodes, edges) |
@@ -1165,10 +1257,16 @@ nodes.
 - **Session receipt:** attaching a session (`set-presence { attached: true }` or a
   `session-start` activity) over a non-empty board saves a `Before session · <label> · HH:MM`
   snapshot; ending it (`attached: false`, `session-end`, or idle expiry) emits one
-  `agent-session-ended` SSE frame — `{ label, endedAt, counts: { items, done, vetoed },
-  snapshot }` — which the browser shows as a receipt with *View diff* (the session's own
-  changes) and a restore path. End your session explicitly so the receipt is prompt. The
-  human's *Start agent session* button is the same attach with `source: "browser"`.
+  `agent-session-ended` SSE frame with `label`, `endedAt`, `snapshot`, `context` and counts
+  (`items`, `done`, `cancelled`, `rejected`, `held`). Changed top-level endings show a receipt;
+  worker and unchanged endings stay in History, and qualifying endings merge into an open receipt.
+  **See change** opens one stacked Before/After; whole-card Undo preserves geometry and links.
+  Receipt Undo sends `preserveHumanEdits: true` to `restore-node`, so the server skips latest-human
+  edits even when the browser is stale. Agent callers can pass that option to `canvas_snapshot`
+  too: `restored: false, skipped: "human-edit"` is not an undone card. Receipt Unpin only removes
+  its recorded pins, never re-pins them. Reopen a receipt's board before Undo or comparison;
+  Home dismisses it. End your session explicitly so the receipt is prompt. The human's
+  *Start agent session* button is the same attach with `source: "browser"`.
 - **Human collaborators / user wins:** every open workbench tab is a presence (`GET
   /api/canvas/human-presence`); a node a human is dragging is locked — an agent write to it is
   refused with 409 until release (requeue and retry), and a pending explicit intent on it is
@@ -1340,7 +1438,7 @@ All POST/PATCH endpoints accept `Content-Type: application/json`. Default base U
 | POST | `/api/canvas/snapshots` | Save snapshot |
 | POST | `/api/canvas/snapshots/<id>` | Restore snapshot |
 | DELETE | `/api/canvas/snapshots/<id>` | Delete snapshot |
-| POST | `/api/canvas/context-pins` | Replace pinned nodes |
+| POST | `/api/canvas/context-pins` | Set, add or remove pinned nodes (20 live pins; removal IDs are not capped) |
 | GET | `/api/canvas/pinned-context` | Get current pins with neighborhood context |
 | GET | `/api/canvas/search?q=...` | Search nodes |
 | POST | `/api/canvas/json-render` | Create a native json-render node |
@@ -1365,6 +1463,7 @@ All POST/PATCH endpoints accept `Content-Type: application/json`. Default base U
 | POST | `/api/canvas/redo` | Redo |
 | GET | `/api/canvas/history` | Mutation history |
 | GET | `/api/canvas/code-graph` | File dependency graph |
+| GET | `/api/canvas/memory-graph` | Summary-only board/card projection; optional focus and depth |
 | GET | `/api/workbench/events` | SSE event stream |
 
 ## Workflow Patterns

package/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -47,8 +47,8 @@ panel.
 
 The extension also reports Copilot's real context window: the SDK's `session.usage_info`
 event (`currentTokens` / `tokenLimit`, root agent only) is posted to the presence as
-`contextUsage`, so the board's top-bar meter reads **Context** with the live numbers rather
-than the pinned-context estimate (**Pins**).
+`contextUsage`, so the board's context panel names how many tokens Copilot's whole context holds,
+next to what the brief costs.
 
 The extension attaches a Copilot session to the canvas when it joins the host session, flips the
 phase to `thinking` on every submitted prompt, and detaches on exit. While attached the workbench

package/skills/pmx-canvas/references/importing-context.md

@@ -0,0 +1,132 @@
+# Importing context
+
+Use this workflow when bringing existing context into PMX Canvas from folders, repositories,
+documents, notes, backlogs, structured exports or knowledge bases. It guides organization and
+verification, not a universal file converter or live sync. PDF/Office attachments still require
+the human-consented extraction and review workflow; this guide does not bypass it.
+
+## Inspect the source before choosing the structure
+
+Inventory the requested scope, file types, existing categories, references and assets. Read
+representative content before mapping it: folder names alone do not establish board boundaries,
+and files may contain several independent items or one argument that should stay together.
+Identify duplicates, historical material, unsupported formats and inaccessible sources. Report
+gaps rather than silently skipping them or claiming extraction succeeded. Keep private context
+within the authorized destination; a folder import is not permission to include credentials.
+
+## Choose boards and cards by purpose
+
+Categories organize boards; boards hold coherent topics or workflows; cards hold useful content.
+Preserve useful categories and folder context without mechanically copying the directory tree.
+A project folder may become an overview board, a backlog with item cards, and a research board.
+Several small files may belong on one board; a single export may need several boards. Choose
+cards by useful units of meaning, not automatically one per file, heading or data row. Retain
+section context, nested details and useful source ordering when splitting content. These are
+examples, not a fixed taxonomy. Explain consequential grouping choices and make them easy to revise.
+Several boards in one category are fine. Keep an argument together when splitting would lose
+meaning. Group related cards and use the main skill's README and focus guidance for a readable start.
+
+Lead each card with the task, item, decision or document section the reader came to find.
+Retain ancestor headings, folder/repository context and source details below that content,
+not as repeated preambles that push every useful item below the card's visible area. Preserve
+meaning and source hierarchy without making the reader expand every card to identify it.
+
+## Preserve sources and stable targets
+
+Work in an isolated workspace for a test import. Preserve an existing import before replacing
+it, and leave source material unchanged unless editing it was requested. Record source paths,
+URLs or record IDs, revisions where available, and the source-item/section → board/card ID
+mapping so interruptions and retries can reuse created objects instead of duplicating them.
+Distinguish faithful imports from summaries; keep a path back to the original. Capture the active
+board before writes, separately from any explicit destination. Create destination boards and
+cards before rewriting internal references, use returned IDs rather than guessed titles, and
+preserve external links.
+
+Create supported static cards, groups and edges on an inactive board with `destinationBoardId`
+without switching the human's view. Static nodes are Markdown, status, context, ledger, trace,
+diff, Mermaid and plain HTML; images, runtime-backed nodes, generated primitives and intents
+are not supported by this path. Updates/removals still require the active board. In a named
+`canvas_batch`, each operation's `args` carries its destination and retry fields; group children
+and edge endpoints can use the existing named references. `toBoardId` independently chooses a
+remote edge endpoint, not the board that owns its source.
+
+Assign a stable `requestId` to each logical static node/group/edge creation and retain it in
+the source-to-canvas mapping. Retry with the same input and destination: the durable receipt
+returns the original result after interruption or restart, even if the object was subsequently
+edited or deleted. It does not restore deleted objects. Changed-input reuse conflicts; a new
+intentional creation gets a new ID even when its content is identical. Batch operations commit
+in sequence, not as one all-or-nothing import. Persist the mapping as receipts arrive.
+
+`expectedBoardId` guards the active board even with an explicit destination. A stale guard
+means refresh context, not substitute the destination ID or switch the human's view to retry.
+For active-only work, explicitly open the intended board and verify its returned ID first.
+Scope fences and human edit locks remain enforced. If Home is active, list/open a suitable
+board before reading board context; library discovery and background static creation can
+stay on Home. For retrieval, `canvas_query` search accepts intersecting `boardId` and `folder`
+filters. Folder includes slash-boundary descendants; `folder: ""` selects unfiled boards.
+Filters default omitted scope to library, while explicit active scope never widens. Search
+never changes the active board.
+
+Use native `references` edges for explicit source links and qualified remote endpoints for
+cross-board cards. Add semantic relations only when the source supports them; record the
+supporting passage or source reference in `reason`. Similar subjects alone do not establish
+dependency, causation or supersession. Follow the main skill's direction rules for dependency kinds.
+
+Preserve historical/draft status and source evidence dates. Importing, reading or rendering
+content does not revalidate it. Flag source contradictions separately from conversion errors
+and product bugs; do not silently rewrite uncertain facts or invent validation dates.
+
+## Markdown link conversion
+
+For content represented as Markdown, use returned IDs in `[[board-id#card-id|label]]` links
+and keep code spans/fences unchanged. In table cells, escape the alias pipe:
+`[[board-id#card-id\|label]]`. Otherwise the table parser can split the link before the wiki
+link parser sees it. Zero unresolved links is not sufficient: compare expected source link
+occurrences with rendered anchors. This is a Markdown rendering concern, not a source-format requirement.
+
+## Keep picture bytes out of long Markdown
+
+Prefer local asset references over large base64 image strings embedded in Markdown. The
+embedded bytes enlarge layout/render requests; inline pictures remain supported. Choosing
+file-backed assets is a representation choice, not proof that a parser or loading bug is fixed.
+Keep private pictures in the authorized workspace; do not upload them to a public image host.
+
+One supported approach is a file-backed image card in the document's board:
+
+```json
+{"action":"add","type":"image","content":"assets/diagram.png","title":"System diagram"}
+```
+
+Call `canvas_node` with that payload, then use the returned ID in the document:
+`![System diagram](/api/canvas/image/<image-node-id>)`. Keep the original alt text and connect
+the document to its figure card when useful. This route resolves nodes on the active board:
+keep the image card in the same board, and recheck references after copying or moving cards.
+
+Relative image creation paths resolve against the canvas workspace root, not the server's
+launch directory. An absolute path inside that workspace also works. Image creation requires
+opening its destination board; do not send `destinationBoardId` or `requestId` for image nodes.
+The database stores the path, not the file bytes: retain the assets alongside it, update paths
+if relocating the workspace, and verify images in exports rather than assuming the live URL
+is portable.
+
+## Verify the imported workspace, not just the API receipts
+
+1. Account for each in-scope source item as imported, summarized, intentionally excluded or
+   unresolved. Reconcile split items, references and assets with the mapping. Check edge endpoints,
+   group containment and collisions with `canvas_query { action: "validate" }`.
+2. Open representative boards for the content actually imported: for example a dense backlog,
+   long document, linked table or picture-heavy board. Wait for the correct board and populated
+   card bodies, not only titles or HTTP success. Images must load with nonzero natural dimensions.
+3. Wait for the intended card/group bounding rectangle after a camera update. Two animation
+   frames do not prove an asynchronous layout update arrived. Inspect screenshots at the
+   intended viewing zoom for readable cards, relations, labels and unobscured controls.
+4. Click local and cross-board links; verify the intended card becomes visible. On a disposable
+   test service, restart and verify persistence, including pictures. Compare asset bytes when
+   changing image representation to confirm originals were preserved.
+5. If loading is slow, measure board-open to rendered-content readiness on repeated equivalent
+   workloads. Include a text-only control; record payload sizes, cache conditions and whether
+   measurements used a local connection or the user's host. Separate observations from causes.
+
+Report coverage, unresolved issues and storage requirements. Distinguish an import workaround
+from a product fix, and a source snapshot from live synchronization. Keep private source paths,
+names and content out of reusable skills and public issue reports.

package/skills/pmx-canvas/references/installing-pmx-canvas.md

@@ -4,7 +4,7 @@ Use this reference when the `pmx-canvas` skill is installed but the `pmx-canvas`
 
 ## Prerequisites and version
 
-The examples pin **PMX Canvas 0.8.0**, which requires **Bun >=1.4.2** even when
+The examples pin **PMX Canvas 0.9.0**, which requires **Bun >=1.4.2** even when
 installed through npm: the CLI runs through Bun, not Node. Check `bun --version`
 first. If missing or older, follow the [Bun installation instructions](https://bun.sh/docs/installation)
 with the user's authorization. Ensure Bun is on the MCP host's PATH as well as the
@@ -17,11 +17,11 @@ in `SKILL.md`. Do not pair newer checkout guidance with an older runtime unknowi
 ## Install from npm
 
 ```bash
-npm install -g pmx-canvas@0.8.0
+npm install -g pmx-canvas@0.9.0
 pmx-canvas --version
 ```
 
-Without a global install, use `bunx pmx-canvas@0.8.0` in place of `pmx-canvas` in
+Without a global install, use `bunx pmx-canvas@0.9.0` in place of `pmx-canvas` in
 the commands below. Do not use unpinned `bunx pmx-canvas` for a version-specific check.
 
 ## Choose the workspace and target
@@ -91,7 +91,7 @@ discards empty env values, remove `PMX_CANVAS_URL` from its launch environment i
   "mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.8.0", "--mcp"],
+      "args": ["pmx-canvas@0.9.0", "--mcp"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
         "PMX_CANVAS_PORT": "14313",
@@ -135,7 +135,7 @@ Amp executes, not only on the user's laptop. Merge this into that workspace's
   "amp.mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.8.0", "--mcp"],
+      "args": ["pmx-canvas@0.9.0", "--mcp"],
       "includeTools": ["canvas_*"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
@@ -169,7 +169,7 @@ The agent must not run this approval itself or move the command to global settin
 `--mcp-config` to bypass workspace trust. Approval authorizes execution of this MCP
 command; it is not a new Canvas import consent or permission to mutate arbitrary boards.
 After approval, reload MCP connections (`reload_mcp` in Amp) and require `connected`.
-Discover `canvas` tools with `tool_search`; for the full unfiltered 0.8.0 server there
+Discover `canvas` tools with `tool_search`; for the full unfiltered 0.9.0 server there
 are 24 tools. If still absent, inspect the server status, command/PATH and target instead
 of reinstalling blindly. See [Amp MCP documentation](https://ampcode.com/docs/customize/mcp).
 

package/skills/pmx-canvas/references/tours-and-recording.md

@@ -19,10 +19,11 @@ Persist a tour with `canvas_view { action: "set-tour", tour: { stops: [...] } }`
 ```
 
 - `nodeId` may identify a card or group. Its persisted position and size determine the camera.
+- `rect` is a world-space box `{ x, y, width, height }` (top-left corner plus size).
 - An explicit viewport is `{ x, y, scale }`, with positive `scale`. Translation is screen-space:
   `screen = world * scale + offset`.
 - `duration` is transition time in seconds (default 1; zero jumps). Valid values are 0–3600.
-- `padding` is screen pixels around a node target (default 40).
+- `padding` is screen pixels around a node or rect target (default 40).
 - `easing` is `linear`, `ease-in-out` (default), or `ease-out`.
 - `pullback` is 0–4 (default 0). It zooms out during the move without changing either endpoint.
 - A tour contains at most 1000 stops.
@@ -39,6 +40,20 @@ ID. A saved `{ "stops": [] }` intentionally has no stops; it does not enable gro
 Preserve the tour of each board when working across boards and target the intended board before
 setting or reading it.
 
+## Drive a tour
+
+The server holds one in-memory tour cursor, tied to the board it was started on (a tour on another board replaces it). `canvas_view { action: "tour-go", stop: 0 }`
+starts presenting in open workbenches; `step: "next" | "previous"` moves relative to wherever the
+audience is (a human's arrow keys move the same cursor) and clamps at the ends. Pass
+`present: false` to move only viewers already presenting. `canvas_view { action: "tour-exit" }`
+leaves presentation everywhere. `get-tour` reports `position` (the current stop, or null).
+
+`canvas_view { action: "move", nodeId | rect | viewport, duration, easing, padding, pullback }`
+eases the camera without a tour. Outside a presentation the end camera becomes the board
+viewport. Tour steps and moves never enter undo history, never count as agent writes, and are
+allowed under a scope fence. Viewers with reduced motion jump instead of animating; a
+deterministic capture ignores both.
+
 ## Capture prerequisites and behavior
 
 Start and verify the matching PMX daemon first: its `/health` workspace and version must match the

package/skills/pmx-canvas-testing/SKILL.md

@@ -53,6 +53,10 @@ and check `$?`, then read the file.
 - Test-only changes: run `bun run test` and `bun run test:coverage` if coverage matters
 - Client/UI/browser interaction changes: run `bun run test:web-canvas`
 - Cross-stack or non-trivial changes: run `bun run test:all`
+- Bundled skill/documentation-only changes: run
+  `bun test tests/unit/bundled-skills.test.ts tests/unit/no-native-tooltips.test.ts`
+  and `git diff --check`; inspect public-contract prose against source. No client rebuild or
+  full browser suite is needed when executable behavior has not changed.
 - Before changing browser-visible behavior under `src/client/`: rebuild with `bun run build`
   Manual browser validation also requires a fresh client bundle. `bun run test:web-canvas`
   already does this for you.
@@ -146,6 +150,13 @@ Four ways a test silently stops discriminating in this repo:
   between those assertions. Separately verify a real spec revision resets to authored state,
   and that local drafts never entered the server spec. See `tests/e2e/json-render-forms.pw.ts`.
   Eval definitions are not evidence of executing this browser regression or a model benchmark.
+- For viewer refreshes, run `tests/e2e/viewer-refresh-frames.pw.ts`: it delays the runtime-state
+  restore beyond document load and checks every captured frame for blank/white flashes in
+  Harbor with light/dark OS settings and Daylight with dark OS settings. Keep the frame assertions;
+  a settled DOM check cannot prove the handoff stayed painted. Reset canvas-bound work as well as
+  nodes between cases. The inert replacement renders behind the active iframe, so select the
+  foreground with `iframe:not([inert])`, not `iframe:visible`. Keep capturing until the last
+  update is actually in the foreground; a momentary one-iframe count may precede the next poll.
 - When checking embedded frame fit manually, start from a clean seeded state, rebuild stale bundles,
   and inspect the actual iframe document in a browser. Server dimensions can look correct while the
   embedded content is still clipped.
@@ -158,6 +169,15 @@ Four ways a test silently stops discriminating in this repo:
 - User-facing creation flows must end with the new nodes visible: after the create (plus the
   skill-mandated focus/fit), a screenshot must show them without any manual pan. A `panned: true`
   API result alone is not proof — verify the frame is on-screen and unobscured.
+- Layout validation proves node non-overlap, not relation readability. After content settles,
+  inspect edge lines, labels, arrowheads and authorship marks at the intended viewing zoom,
+  including after auto-arrange; do not prescribe one universal gap.
+- Context/receipt checks must distinguish map delivery (seen links and board read status) from
+  full card-content reads. Check one-open stacked See change, clipped-excerpt captions and
+  whole-card Undo with a latest-human-edit negative control. Retain a receipt across a board
+  switch: snapshot comparison must reopen its owning board, Undo/Unpin must not affect the
+  foreign board, and lens marks must use only active-board touches. Check the narrow agent
+  initial's counts/lens/panel interaction separately. Use disposable boards for these checks.
 
 ## Failure Handling
 

package/src/cli/agent.ts

@@ -52,6 +52,8 @@ Usage:
 
 Presentation and capture:
   pmx-canvas tour get|set             Read or persist ordered camera stops
+  pmx-canvas tour go <n|next|previous> Present a stop; tour exit leaves presentation
+  pmx-canvas camera move --node <id>  Ease the camera to a node, --rect or --viewport
   pmx-canvas record --help            Optionally capture the same board tour or live presentation
 
 Server:

package/src/cli/commands/ax.ts

@@ -397,6 +397,18 @@ cmd(
   },
 );
 
+cmd(
+  'ax reads status',
+  'Read status for a board: its last agent read, per-node reads and revisions, and pin metadata',
+  ['pmx-canvas ax reads status', 'pmx-canvas ax reads status --board <board-id>'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('ax reads status');
+
+    output(await invokeOperation('ax.reads.status', typeof flags.board === 'string' ? { board: flags.board } : {}));
+  },
+);
+
 cmd(
   'ax work add',
   'Add a canvas-bound AX work item',

package/src/cli/commands/boards.ts

@@ -2,6 +2,55 @@
 
 import { cmd, die, getStringFlag, invokeOperation, output, parseFlags, showCommandHelp } from '../shared.js';
 
+cmd(
+  'board vocabulary',
+  'Set a board relation vocabulary from JSON',
+  ['pmx-canvas board vocabulary <id> \'[{"kind":"supports","ink":"supports","directed":true}]\''],
+  async (args) => {
+    const [id, json] = args;
+    if (!id || !json) die('Expected board id and vocabulary JSON.');
+    output(await invokeOperation('board.update', { id, relationVocabulary: JSON.parse(json) }));
+  },
+);
+
+cmd(
+  'board knowledge',
+  'Workspace knowledge actions with a JSON payload',
+  [
+    'pmx-canvas board knowledge list',
+    'pmx-canvas board knowledge category-remove \'{"id":"unused-category"}\'',
+    'pmx-canvas board knowledge folder-set \'{"path":"A","categoryId":null,"lifecycleOverride":null}\'',
+  ],
+  async (args) => {
+    const [action, payload = '{}'] = args;
+    if (
+      ![
+        'list',
+        'category-set',
+        'category-remove',
+        'folder-set',
+        'relation-preset-set',
+        'relation-preset-remove',
+      ].includes(action ?? '')
+    )
+      die('Expected list, category-set, category-remove, folder-set, relation-preset-set or relation-preset-remove.');
+    output(await invokeOperation(`knowledge.${action}`, JSON.parse(payload)));
+  },
+);
+
+cmd(
+  'board lifecycle',
+  'Card lifecycle and audited reviews with a JSON payload',
+  ['pmx-canvas board lifecycle get \'{"id":"card"}\''],
+  async (args) => {
+    const [action, payload = '{}'] = args;
+    if (!['get', 'set', 'review', 'restore'].includes(action ?? '')) die('Expected get, set, review or restore.');
+    output(
+      await invokeOperation(action === 'review' ? 'node.review' : `node.lifecycle-${action}`, JSON.parse(payload)),
+    );
+  },
+);
+
 cmd('board list', 'List boards, most recently opened first', ['pmx-canvas board list'], async (args) => {
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('board list');
@@ -49,14 +98,41 @@ cmd(
 cmd(
   'board create',
   'Create an empty board (use board open with its returned id before writing)',
-  ['pmx-canvas board create "Q4 planning"', 'pmx-canvas board create "Q4 planning" --category Planning'],
+  ['pmx-canvas board create "Q4 planning"', 'pmx-canvas board create "Q4 planning" --folder Planning'],
   async (args) => {
     const { positional, flags } = parseFlags(args);
     if (flags.help || flags.h) return showCommandHelp('board create');
     const name = positional.join(' ').trim();
-    if (!name) die('Usage: pmx-canvas board create <name> [--category <category>]');
-    const category = getStringFlag(flags, 'category');
-    output(await invokeOperation('board.create', { name, ...(category ? { category } : {}) }));
+    if (!name) die('Usage: pmx-canvas board create <name> [--folder <folder>]');
+    const folder = getStringFlag(flags, 'folder');
+    output(await invokeOperation('board.create', { name, ...(folder ? { folder } : {}) }));
+  },
+);
+
+cmd(
+  'board pin',
+  "Pin a board into the agent's working set (its README and pinned cards reach every brief)",
+  ['pmx-canvas board pin board-abc123', 'pmx-canvas board pin board-abc123 --reason "Q4 rests on it"'],
+  async (args) => {
+    const { positional, flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('board pin');
+    const [id] = positional;
+    if (!id || positional.length > 1) die('Usage: pmx-canvas board pin <board-id> [--reason <why>]');
+    const reason = getStringFlag(flags, 'reason');
+    output(await invokeOperation('board.pin', { id, ...(reason ? { reason } : {}) }));
+  },
+);
+
+cmd(
+  'board unpin',
+  "Remove a board from the agent's working set",
+  ['pmx-canvas board unpin board-abc123'],
+  async (args) => {
+    const { positional, flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('board unpin');
+    const [id] = positional;
+    if (!id || positional.length > 1) die('Usage: pmx-canvas board unpin <board-id>');
+    output(await invokeOperation('board.unpin', { id }));
   },
 );
 
@@ -70,15 +146,15 @@ cmd('board rename', 'Rename a board', ['pmx-canvas board rename board-abc123 "Q4
 });
 
 cmd(
-  'board category',
-  'File a board under a category on Home (--clear removes it)',
-  ['pmx-canvas board category board-abc123 "Planning"', 'pmx-canvas board category board-abc123 --clear'],
+  'board folder',
+  'File a board under a folder on Home (--clear removes it)',
+  ['pmx-canvas board folder board-abc123 "Planning"', 'pmx-canvas board folder board-abc123 --clear'],
   async (args) => {
     const { positional, flags } = parseFlags(args);
-    if (flags.help || flags.h) return showCommandHelp('board category');
+    if (flags.help || flags.h) return showCommandHelp('board folder');
     const [id, ...rest] = positional;
-    const category = flags.clear ? '' : rest.join(' ').trim();
-    if (!id || (!category && !flags.clear)) die('Usage: pmx-canvas board category <board-id> <category> | --clear');
-    output(await invokeOperation('board.update', { id, category }));
+    const folder = flags.clear ? '' : rest.join(' ').trim();
+    if (!id || (!folder && !flags.clear)) die('Usage: pmx-canvas board folder <board-id> <folder> | --clear');
+    output(await invokeOperation('board.update', { id, folder }));
   },
 );