pmx-canvas 0.8.2 → 0.9.1

package/skills/pmx-canvas/evals/evals.json

@@ -834,6 +834,230 @@
           "type": "output_check"
         }
       ]
+    },
+    {
+      "id": 36,
+      "name": "folder-cli-without-removed-category",
+      "prompt": "In a verified disposable workspace, use the CLI to create Release notes under Engineering/Canvas, move it to Engineering/Release, then unfile it without opening it. An old script uses board create --category Engineering/Canvas. Check that obsolete command as a negative control; do not silently accept it or create a knowledge category instead. Leave the active board and its cards alone.",
+      "expected_output": "Executes board create \"Release notes\" --folder Engineering/Canvas, captures the returned board ID, uses board folder <id> Engineering/Release and board folder <id> --clear. Reads the library after each step to verify folder and stable identity/content. In the disposable target, --category exits nonzero with the removal diagnostic and creates no board. No board open or category-set substitute occurs; activeBoardId and the original board layout remain unchanged.",
+      "assertions": [
+        {
+          "name": "uses-current-folder-commands",
+          "description": "CLI trace uses --folder on create, the returned ID with positional board folder, and --clear to unfile; successful command results are required, not merely suggested commands",
+          "type": "output_check"
+        },
+        {
+          "name": "verifies-folder-and-identity",
+          "description": "Library reads show Engineering/Canvas, then Engineering/Release, then an empty folder on the same board ID without losing its content",
+          "type": "output_check"
+        },
+        {
+          "name": "rejects-obsolete-category-control",
+          "description": "The isolated --category control exits nonzero with 'The --category flag was removed.' and leaves the library count unchanged; no category-set is used to simulate filing",
+          "type": "output_check"
+        },
+        {
+          "name": "does-not-navigate-to-file",
+          "description": "Before/after reads show unchanged activeBoardId and active layout; the trace contains no board open to perform filing",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 37,
+      "name": "whole-library-map-versus-full-content-delivery",
+      "prompt": "On a disposable library, board A is active and inactive board B has pinned Markdown cards Target and Unread control. Target's decisive sentence is beyond character 280. Show the whole-board connection map, then use the actual Target text to answer its question without opening B. Use one stable consumer. After a human edits Target, refresh just that card. Do map summaries prove you read both cards in full?",
+      "expected_output": "Reads a whole-library graph with projection boards and omitted focus for orientation, then resolves B/Target and explicitly gets its full content with canvas_node {action:get, id, board:B, full:true}. Uses the sentence beyond the summary in its answer. Captures read status before and after graph/full deliveries, checks Target's delivered content revision, then fully rereads Target after the edit. Does not mark Unread control fully read from a graph/compact summary or confuse complete link delivery with full-content delivery. Active A remains unchanged.",
+      "assertions": [
+        {
+          "name": "requests-board-map-not-content-dump",
+          "description": "Trace requests canvas_query graph with projection boards and no focus (or equivalent memory-graph API), and observes board-qualified summaryOnly results rather than using a full layout as the map",
+          "type": "output_check"
+        },
+        {
+          "name": "fetches-and-uses-full-qualified-target",
+          "description": "Trace gets the resolved B/Target with full:true (or equivalent tracked full-node API); the answer uses its seeded sentence beyond 280 characters and read-status evidence records that delivered revision",
+          "type": "output_check"
+        },
+        {
+          "name": "refreshes-only-observed-stale-content",
+          "description": "After the human edit, a new full Target delivery advances its recorded read revision; status deltas show the unread control received no full-content read from map/compact discovery alone",
+          "type": "output_check"
+        },
+        {
+          "name": "preserves-active-board-and-read-boundaries",
+          "description": "Before/after activeBoardId and A layout match, no open/write occurs, and full-read claims are backed by deliveries rather than summaryOnly or link-seen state",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 38,
+      "name": "durable-background-create-replay",
+      "prompt": "In an isolated workspace, keep A active while populating inactive B with two static Markdown cards, a group containing them, and a references edge. Use durable request IDs per creation and batch named references. Simulate a lost response after a committed prefix, retry, and restart the disposable daemon before retrying again. With the harness, edit one created card and delete the other on B, return to A, then replay the original requests. Do not recreate deleted work or undo later edits.",
+      "expected_output": "Uses destinationBoardId:B and stable per-operation requestId inside each batch operation's args, resolving group/edge named references. Replays identical inputs after partial completion and restart and compares original receipts/IDs. Later edit/deletion controls are harness-owned, not unsupported background CRUD. Replay returns original receipts without duplicating, overwriting or resurrecting objects. Qualified reads show B's intended surviving state and unchanged A activeBoardId/layout/viewport throughout agent background writes.",
+      "assertions": [
+        {
+          "name": "targets-each-static-creation",
+          "description": "Batch trace puts destinationBoardId and distinct logical requestId in node/group/edge args, uses valid named references, and verifies group membership and qualified edge endpoints on B",
+          "type": "output_check"
+        },
+        {
+          "name": "replays-prefix-and-restart-durably",
+          "description": "Evidence includes a committed prefix with lost response, identical retry after it and after a real isolated daemon restart, stable returned IDs/receipts and no duplicate nodes/groups/edges",
+          "type": "output_check"
+        },
+        {
+          "name": "replay-is-not-reapplication",
+          "description": "After harness edit/deletion and original-input replay, qualified reads retain the later edit and deleted-card absence even though original creation receipts are returned",
+          "type": "output_check"
+        },
+        {
+          "name": "keeps-background-work-off-active-board",
+          "description": "Before/after reads around agent creation/replays show A stays active with identical layout/viewport; no agent board open, active update/remove, runtime creation or background intent is used",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 39,
+      "name": "background-create-conflicts-and-stale-active-guard",
+      "prompt": "In a disposable workspace with A active and B inactive, create a static note on B with requestId logical-note and expectedBoardId A. Test reusing logical-note with changed content and with destination A. Then have the harness switch the active board to C and send a new creation for B using stale expectedBoardId A. Do not force it through. Finally create a genuinely separate identical note with a fresh request ID after checking C. Also test a background file-node creation as an unsupported control.",
+      "expected_output": "Observes conflicts on changed-input and changed-destination reuse without mutating either destination. Stale expectedBoardId guards the actual active board, not B: the new request is refused after the switch to C. Rereads active identity before using expectedBoardId C with a fresh logical ID for the intentional duplicate. Unsupported background file creation fails without side effects. No clearing guards, board switching or blind retries to defeat rejection; C stays active.",
+      "assertions": [
+        {
+          "name": "changed-request-conflicts-without-writes",
+          "description": "Actual changed-content and changed-destination requests using logical-note fail with conflicts, and destination reads prove original content/counts are unchanged",
+          "type": "output_check"
+        },
+        {
+          "name": "stale-guard-requires-reread",
+          "description": "After the harness switch, expectedBoardId A is refused with no creation on B; trace rereads C before any fresh write and does not remove the guard or substitute B as the active identity",
+          "type": "output_check"
+        },
+        {
+          "name": "new-operation-gets-new-identity",
+          "description": "The intentional identical creation uses a new requestId and expectedBoardId C, returns a distinct node ID on B and leaves C active with unchanged layout",
+          "type": "output_check"
+        },
+        {
+          "name": "unsupported-background-control-has-no-effect",
+          "description": "A file-node creation with destinationBoardId B fails as unsupported and qualified reads show no new file or active-board side effect; no active-board fallback is attempted",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 40,
+      "name": "board-qualified-native-relations",
+      "prompt": "In a disposable library A is active, and A and B both contain a card with ID shared. The harness has given A/shared, A/Navigation and B/shared explicit durable lifecycle policies and validated their current content. From A/shared add a depends-on edge to B/shared with reason 'Capacity requires measured throughput'. Add an ordinary references edge from A/Navigation to the same remote source. Read the qualified graph, change B/shared with the harness, and check which dependents become review-due. Keep A active and do not replace the edge with a board portal.",
+      "expected_output": "Resolves the two board identities and uses canvas_edge add with from:shared, to:shared, toBoardId:B, type:depends-on for dependent to prerequisite, preserving reason. Uses a references edge for Navigation. Reads graph and lifecycle qualifications with explicit board identities: the dependency is remote, not a self-loop on A. With explicit durable lifecycle policies in the fixture, the source change makes the dependent due but not the ordinary-reference control. Reads do not open B or mutate its source.",
+      "assertions": [
+        {
+          "name": "writes-qualified-remote-edge",
+          "description": "Actual edge add uses A/shared as source and toBoardId B with target shared; graph endpoints are distinct qualified keys, not bare-ID self-loops or board portal nodes",
+          "type": "output_check"
+        },
+        {
+          "name": "preserves-direction-and-reason",
+          "description": "Readback shows depends-on from dependent A/shared to prerequisite B/shared with the exact supplied reason, independently of display style or label",
+          "type": "output_check"
+        },
+        {
+          "name": "distinguishes-navigation-from-validation-dependency",
+          "description": "Before/after lifecycle reads under explicit durable policies show B's semantic change makes A/shared due while the references-only Navigation control stays not due",
+          "type": "output_check"
+        },
+        {
+          "name": "reads-remote-source-without-navigation",
+          "description": "Tool trace and before/after board reads keep A active; agent does not open B, edit its source or create a portal as a substitute for the remote card relation",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 41,
+      "name": "wiki-bindings-survive-renames-without-guessing",
+      "prompt": "In a disposable library, save a source Markdown card on A containing [[Research#Result|evidence]], plus code-span and fenced-code copies of that link. Research uniquely names B and Result uniquely names B's target card. Record the binding, then let the harness rename B and Result and create new objects using the old names. Separately save [[Ambiguous]] when two boards share that name, and [[Future]] before that board exists. After the harness creates Future, read the source without saving, then explicitly save it. Do not open other boards or hand-author wikiLinks metadata.",
+      "expected_output": "Saves through the native Markdown path and inspects server-produced qualified wiki bindings/backlinks. The bound aliased link continues to target B's original card after renames despite old-name replacements; code samples add no relations. Ambiguous links stay unresolved instead of choosing a board. The saved missing Future link remains unresolved on read after creation and resolves only on explicit source save. Does not fabricate binding IDs or switch active boards to resolve references.",
+      "assertions": [
+        {
+          "name": "uses-server-bindings-and-ignores-code",
+          "description": "Save/read trace shows one real qualified Research/Result wiki relation with alias evidence, server-owned data.wikiLinks, and no extra relations for code-span/fenced examples",
+          "type": "output_check"
+        },
+        {
+          "name": "identity-wins-over-renamed-labels",
+          "description": "After harness renames and old-name replacements, graph/backlink or binding readback still identifies the original B/card IDs rather than silently retargeting to replacement names",
+          "type": "output_check"
+        },
+        {
+          "name": "does-not-guess-ambiguous-board",
+          "description": "The saved Ambiguous reference remains explicitly unresolved with no target selected; trace does not rewrite the source to an arbitrary candidate",
+          "type": "output_check"
+        },
+        {
+          "name": "resolution-requires-explicit-save",
+          "description": "Future remains unresolved after a read with the board now present, then resolves on explicit source save; A stays active and no invented wikiLinks metadata is submitted",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 42,
+      "name": "review-evidence-bound-to-checked-content-and-sources",
+      "prompt": "On disposable board A, review Conclusion against its explicit dependency on B/Source. Read the actual content and capture lifecycle observations. Before submission let the harness change Conclusion, then in a separate trial change Source. Submit the captured stale reviews as controls. Do not just copy fresh tokens onto the old note. Recheck the evidence for a successful retain review, and also test an unavailable source, applied:false and blank evidence. In a separate harness-seeded cached-provenance control, compare observedRevision and availability to the current live source rather than treating retrieval time as freshness. Does fetching or regenerating a card alone validate it?",
+      "expected_output": "Reads full qualified content and lifecycle-get, captures the checked content revision and qualification.observations, then supplies them as expectedContentRevision/expectedSources on canvas_node review with outcome retain, applied true and substantive evidence. Both stale trials conflict and leave validation unchanged. A successful review follows real rereads/recomparison, not token replacement, and its stored record identifies checked content/source revisions. Unavailable sources refuse validation; unapplied or empty-evidence outcomes do not renew it. Retrieval, editing and recipe refresh alone never validate.",
+      "assertions": [
+        {
+          "name": "checks-content-and-observed-sources-before-review",
+          "description": "Trace delivers full Conclusion and qualified B/Source content and lifecycle observations before sending retain/applied:true with nonempty evidence, expectedContentRevision and expectedSources from the checked versions",
+          "type": "output_check"
+        },
+        {
+          "name": "stale-evidence-cannot-renew-validation",
+          "description": "Separate harness content-change and source-change trials reject captured stale reviews with conflicts and preserve lastValidation; no unchecked new revision tokens are pasted onto the old evidence",
+          "type": "output_check"
+        },
+        {
+          "name": "successful-record-binds-rechecked-versions",
+          "description": "After actual full rereads and evidence comparison, successful review readback records the checked contentRevision and sourceRevisions; fetching/editing/refreshing alone leaves lastValidation unchanged",
+          "type": "output_check"
+        },
+        {
+          "name": "nonvalidating-controls-do-not-renew",
+          "description": "Unavailable-source review is refused, and applied:false and blank-evidence controls do not advance lastValidation; observed cached-source revision/availability is not misrepresented as a fresh live check",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 43,
+      "name": "retirement-excludes-context-until-audited-restore",
+      "prompt": "On disposable A, pin Obsolete and Keep. Give Obsolete an explicit durable lifecycle policy and validate its current content with evidence, then retire it. Check the brief, pinned context, search and direct read. Read and edit Obsolete and apply a retain review: should any of these unretire it? Finally make an unvalidated content edit, explicitly restore it with reason 'Needed for follow-up', and check its eligibility and review status. B has the same card ID as Obsolete; do not change B.",
+      "expected_output": "Uses canvas_node review outcome retire/applied true and expectedBoardId A. Retired Obsolete is absent from briefs and pinned-context delivery while search/direct reads retain it marked retired; Keep stays delivered. Read/edit/retain do not reverse retirement. Explicit lifecycle-restore with evidence reverses retirement, makes the still-pinned card eligible again, but leaves lastValidation bound to the older checked revision so the final edited content remains review-due. Board-qualified checks confirm B's same-ID card and lifecycle history are unchanged.",
+      "assertions": [
+        {
+          "name": "retirement-excludes-delivery-not-storage",
+          "description": "After retire/applied:true, brief and pinned-context results omit A/Obsolete while Keep remains; qualified direct read/search still find Obsolete marked retired rather than deleted",
+          "type": "output_check"
+        },
+        {
+          "name": "ordinary-actions-cannot-unretire",
+          "description": "Actual read, content edit and applied retain review leave the retirement flag set and Obsolete excluded from context delivery",
+          "type": "output_check"
+        },
+        {
+          "name": "restore-is-audited-not-validation",
+          "description": "After a final unvalidated semantic edit, lifecycle-restore records 'Needed for follow-up', clears retired and restores context eligibility without advancing lastValidation; the current revision remains due",
+          "type": "output_check"
+        },
+        {
+          "name": "lifecycle-identity-is-board-qualified",
+          "description": "Writes use expectedBoardId A; before/after reads of B's same-ID card show unchanged content, retirement and review records, with A still active",
+          "type": "output_check"
+        }
+      ]
     }
   ]
 }

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.