pmx-canvas 0.8.2 → 0.9.1

package/docs/product-vision-review-2026-09.md

@@ -5,7 +5,19 @@
 **Scope:** An independent review of the long-term direction set by [`product-vision-2026-09.md`](product-vision-2026-09.md) and [`product-context-vision-2026-09.md`](product-context-vision-2026-09.md), checked against what has shipped since and against the real board in use today, plus a design sketch for boards as the wiki. Written against `main` `561e6ec5` (v0.6.3, clean tree, equal to `origin/main`).
 **Method:** Read all three September documents (review, vision, context vision) and the 0.6.0–0.6.3 changelog; re-checked the review's trust findings in current source; read the live board the globally installed MCP server writes to, read-only, titles and counts only. No code was run and no board was modified.
 
-## Where things stand
+## Current delivery alignment, 2026-10-13
+
+This is the September review, not a current defect inventory. Waves 1–3 and their acceptance
+follow-ups have implemented the local board/wiki, context, relations and lifecycle scope;
+see [the main vision's authoritative progress](product-vision-2026-09.md#current-plan).
+Owner feedback separates shared Home relation templates from each board's actual-kind filter,
+and keeps categories/lifecycle independent of relations. Manual rehearsal exposed five guide
+failures now corrected in the acceptance follow-up. Combined verification is tracked in
+[plan 018](plans/plan-018-connected-memory-wave-2.md), not inferred from this historical review.
+Owner acceptance, real-agent curation evaluation, remaining sketch parity and native-host
+checks are still open. No release or version bump is implied.
+
+## Where things stood at the September review
 
 - **Three vision documents in September; none of their 0.6 plan has shipped.** The vision's 0.6 was many boards, trust, the cheap tool surface, frame-host consolidation and a binary, in 2–3 weeks. Seventeen days and three releases later, 0.6.0–0.6.3 carried the Bun 1.4.2 upgrade, field-report fixes, the MCP Skills extension and json-render updates.
 - **The afternoon-sized trust defects are all still present.** `ax.approval.resolve` never checks the caller, so an agent can approve its own gate. `requestJson` never reads `res.ok`, so a human's failed write is silent. The webpage fetcher uses `redirect: 'follow'` with no host filter. There is no boards table.

package/docs/sdk.md

@@ -7,8 +7,59 @@ The published SDK entrypoint is Bun-first. Node.js consumers should use the
 bun add pmx-canvas
 ```
 
+## Knowledge lifecycle data
+
+`await canvas.knowledge({action: "list"})` reads the workspace category list and folder
+properties. `category-set` and `folder-set` use the [HTTP contract fields](http-api.md#knowledge-lifecycle-data-plan-017-slice-1)
+without opening a board. `await canvas.lifecycle({action: "get", id, board})` reads inherited
+policy and review history; `set`, `review` and `restore` write the active board and accept
+`expectedBoardId`. These registry-backed SDK writes obey the same scope and human edit locks
+as HTTP/MCP. New authored cards start fresh until their effective policy first requires
+review, without an evidence-validation record. Use `data: {contentOrigin: 'imported'}`
+on historical content; edits never reset its freshness or validate it. See the
+[lifecycle contract](http-api.md#knowledge-lifecycle-data-plan-017-slice-1).
+
+After actually checking the card and its evidence, capture its semantic version rather than
+acknowledging a newer body you have not read:
+
+```ts
+const reviewed = canvas.getNode(cardId)!;
+// Inspect this content and verify its source before recording success.
+await canvas.lifecycle({
+  action: 'review', id: cardId, expectedBoardId: boardId,
+  outcome: 'retain', evidence: 'Checked source revision v2', applied: true,
+  expectedContentRevision: reviewed.contentRevision ?? 0,
+});
+```
+
+Missing/stale validating preconditions fail. Reviewed content must persist before the audit
+record. Read, edit, refresh and explicit retirement restore never renew validation; historical
+records retain their reviewed revision, and legacy unversioned evidence remains unknown.
+
 ## Quick example
 
+`canvas.addNode` also accepts `destinationBoardId`, `requestId`, and
+`expectedBoardId` for [static destination creation and durable retries](http-api.md#nodes).
+The destination does not activate that board; `expectedBoardId` guards the active board.
+Use a new request id for a new logical creation, including intentional identical content.
+Retrying the same id/input/destination returns the original receipt, even after removal,
+and never resurrects the node. Mismatched reuse fails. Either destination/retry field
+restricts creation to markdown, status, context, ledger, trace, diff, mermaid and plain html;
+runtime types, primitives, intents and membership changes fail explicitly. Both boards'
+fences are conservatively enforced. This is creation-only, not background CRUD.
+
+`canvas.createGroup` and `canvas.addEdge` accept those same three fields, so a
+background import can create its cards, enclosing frame and relations without
+navigation. Group children and edge endpoints resolve on the destination;
+`toBoardId` still selects an independent foreign edge target. Both methods return
+IDs as before. Replaying a request returns its original ID, not a later edited
+value or a resurrected object.
+
+`canvas.search(query, { boardId, folder, scope, limit })` shares HTTP/MCP search
+ranking. Board and folder filters intersect; a folder includes its descendants
+(`""` means unfiled). Filters default omitted scope to library, while explicit
+active scope never widens. Filtering precedes limits and never opens boards.
+
 ```ts
 import { createCanvas } from 'pmx-canvas';
 
@@ -93,8 +144,8 @@ console.log(canvas.getAxContext());
 
 // Boards — agents may open boards; deletion is reserved for trusted embedding hosts.
 // Open the intended board before writing: this also switches the shared workbench.
-const board = await canvas.createBoard('Q4 planning', 'Planning'); // optional category
-await canvas.updateBoard(board.id, { category: 'Planning/Quarterly' }); // nested folders; null unfiles it
+const board = await canvas.createBoard('Q4 planning', 'Planning'); // optional folder
+await canvas.updateBoard(board.id, { folder: 'Planning/Quarterly' }); // nested folders; null unfiles it
 await canvas.openBoard(board.id);
 console.log(canvas.listBoards()); // { activeBoardId, boards }
 const intro = canvas.addNode({ type: 'markdown', title: 'README', content: '# Quarterly planning' });
@@ -104,11 +155,19 @@ console.log(await canvas.createBoardFrom({
   sourceBoardId: board.id, name: 'Q1 follow-up', nodeIds: [intro.id], includeReadme: true, preview: true,
 }));
 console.log(await canvas.getContextBrief({ consumer: 'my-adapter:workspace', budget: 16000 }));
+// The same summary-only board/card projection as Home Graph, without switching.
+console.log(await canvas.getMemoryGraph({ focus: 'pins', depth: 2 }));
+console.log(await canvas.getMemoryGraph({ focus: JSON.stringify([board.id, intro.id]), depth: 1 }));
+console.log(await canvas.getMemoryGraph({ projection: 'boards' })); // Compact board-only summaries; default is 'full'
+// Depth defaults to 2; explicit 0 is valid, bounded to integer values 0–4.
+await canvas.updateBoard(board.id, { mapPosition: { x: 200, y: 120 } }); // null resets to generated Map placement
 await canvas.openBoard(null); // Home
 
 // Read another board without opening it; unknown board IDs throw.
 console.log(canvas.getLayout({ board: board.id }));
 console.log(canvas.getNode('node-id', { board: board.id }));
+// With a source board open, connect a local card to a remote card by qualified identity.
+// canvas.addEdge({ from: intro.id, to: remoteCardId, toBoardId: remoteBoardId, type: 'references' });
 
 // Agent-assisted document import. attachDocument requires the target board open
 // and accepts at most 20 MiB. Human request/cancel/commit also require the
@@ -148,6 +207,7 @@ canvas.sendSteering('focus on the failing test first', { source: 'sdk' });
 console.log(canvas.getAxTimeline({ limit: 50 }));
 console.log(canvas.getContextReads(50)); // context read log + per-consumer delivery summary
 console.log(canvas.getNodeReadStatus()); // per node: last agent read, by whom, at which content revision
+console.log(canvas.getBoardLastRead(boardId)); // a board's last agent read (a pinned board's map counts), or null
 
 // Canvas-bound (rides snapshots + restore, cleared by canvas.clear())
 const work = canvas.addWorkItem({ title: 'Wire up auth', status: 'in-progress', nodeIds: [n1] }, { source: 'sdk' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/plugins/pmx-canvas/com.github.copilot/extensions/pmx-canvas/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.8.2"
+  "version": "0.9.1"
 }

package/plugins/pmx-canvas/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pmx-canvas",
   "description": "PMX Canvas spatial workbench and MCP tools, with a native canvas panel in the GitHub Copilot app.",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "author": {
     "name": "pskoett",
     "url": "https://github.com/pskoett"

package/plugins/pmx-canvas/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.8.2"
+  "version": "0.9.1"
 }