pmx-canvas 0.8.0 → 0.9.0

package/plugins/pmx-canvas/tools.json

@@ -218,7 +218,7 @@
     },
     {
       "name": "canvas_snapshot",
-      "description": "Canvas snapshots: save the current state, list saved snapshots, restore one, delete one, garbage-collect old ones, or diff the live canvas against one. Action \"save\" stores a named snapshot; \"list\" returns saved snapshots (newest first); \"restore\" replaces the live canvas with a snapshot; \"delete\" removes one; \"gc\" keeps the newest N and deletes the rest (dryRun to preview); \"diff\" shows added/removed/modified nodes and edges versus a snapshot (by name or id).",
+      "description": "Canvas snapshots: save the current state, list saved snapshots, restore one, delete one, garbage-collect old ones, or diff the live canvas against one. Action \"save\" stores a named snapshot; \"list\" returns saved snapshots (newest first); \"restore\" replaces the live canvas with a snapshot; \"delete\" removes one; \"gc\" keeps the newest N and deletes the rest (dryRun to preview); \"diff\" shows added/removed/modified nodes and edges versus a snapshot (by name or id); \"restore-node\" puts one card (nodeId) back to its content in a snapshot, leaving the rest of the board as it is.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -228,11 +228,12 @@
               "save",
               "list",
               "restore",
+              "restore-node",
               "delete",
               "gc",
               "diff"
             ],
-            "description": "Operation to perform: save | list | restore | delete | gc | diff."
+            "description": "Operation to perform: save | list | restore | restore-node | delete | gc | diff."
           },
           "name": {
             "type": "string",
@@ -265,6 +266,14 @@
             "description": "Snapshot ID or name to restore (from canvas_snapshot or snapshot list)",
             "type": "string"
           },
+          "nodeId": {
+            "description": "The card to put back as it was in that snapshot",
+            "type": "string"
+          },
+          "preserveHumanEdits": {
+            "description": "Skip a card whose latest editor is human (receipt Undo)",
+            "type": "boolean"
+          },
           "keep": {
             "description": "Number of newest snapshots to keep (default: 20)",
             "type": "number"
@@ -290,7 +299,7 @@
     },
     {
       "name": "canvas_board",
-      "description": "Boards in this workspace — the library of the human's and your working memory, filed in categories on Home. Your writes always go to the open board (activeBoardId); on Home (no board open) your first write opens the most recent board, or a new one when there are none. Action \"list\" returns every board (with its category), most recently opened first; \"get\" reads one (default: the open board); \"create\" makes a new empty board WITHOUT opening it (optional category); \"open\" explicitly switches the shared workbench to id (null or omitted opens Home), changing the visible board and subsequent write target. After creating a board, open its returned id and verify activeBoardId before writing; another participant can switch the board later. \"update\" renames a board, files it under a category (category \"\" removes it), or designates its README via readmeNodeId. As part of normal board authoring, read the board metadata; if readmeNodeId is null, choose or create a concise markdown introduction explaining its purpose and key context, then designate that node with \"update\". Preserve an existing README unless the human asks to change it; humans can override the designation manually. Only the human deletes boards.",
+      "description": "Knowledge data: knowledge-list reads categories/folders/shared relation presets; category-set replaces category (id/name/glyph/decayType/rate/triggers/revalidationMethod); category-remove deletes an unused category by id (explicit folder assignments, including empty folders, refuse deletion); relation-preset-set saves preset (id/name/vocabulary); relation-preset-remove deletes a template without changing existing board vocabularies; folder-set replaces path/categoryId/lifecycleOverride (null inherits). These workspace actions never open a board and are refused under agent scope fences. Boards in this workspace — the library of the human's and your working memory, filed in folders on Home. Your writes always go to the open board (activeBoardId); on Home (no board open) your first write opens the most recent board, or a new one when there are none. Action \"list\" returns every board (with its folder), most recently opened first; \"get\" reads one (default: the open board); \"create\" makes a new empty board WITHOUT opening it (optional folder); \"open\" explicitly switches the server active board to id (null or omitted opens Home), changing the subsequent write target. Humans browsing Map/Graph stay in the library until they explicitly open a board/card; do not infer activeBoardId from their visible library. After creating a board, open its returned id and verify activeBoardId before writing; another participant can switch the board later. \"update\" renames a board, files it under a folder (folder \"\" removes it), or designates its README via readmeNodeId. As part of normal board authoring, read the board metadata; if readmeNodeId is null, choose or create a concise markdown introduction explaining its purpose and key context, then designate that node with \"update\". Preserve an existing README unless the human asks to change it; humans can override the designation manually. \"pin\" adds a board to the working set (its README and pinned cards reach your brief whichever board is open; optional reason), \"unpin\" removes it; a pinned board is read-only context, never a write target. Only the human deletes boards.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -302,9 +311,17 @@
               "create",
               "create-from",
               "open",
-              "update"
+              "update",
+              "knowledge-list",
+              "category-set",
+              "category-remove",
+              "relation-preset-set",
+              "relation-preset-remove",
+              "folder-set",
+              "pin",
+              "unpin"
             ],
-            "description": "Operation to perform: list | get | create | create-from | open | update."
+            "description": "Operation to perform: list | get | create | create-from | open | update | pin | unpin | knowledge-list | category-set | category-remove | relation-preset-set | relation-preset-remove | folder-set."
           },
           "id": {
             "description": "Board id (default: the open board)"
@@ -312,7 +329,7 @@
           "name": {
             "description": "Board name"
           },
-          "category": {
+          "folder": {
             "description": "Folder path on Home, e.g. Engineering/Canvas"
           },
           "sourceBoardId": {
@@ -335,6 +352,41 @@
             "description": "Return reusable cards and structure without creating",
             "type": "boolean"
           },
+          "relationVocabulary": {
+            "description": "Board relation vocabulary: open kinds with a meaning ink and direction",
+            "maxItems": 64,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 80
+                },
+                "ink": {
+                  "type": "string",
+                  "enum": [
+                    "supports",
+                    "contradicts",
+                    "cites",
+                    "derived",
+                    "informs",
+                    "related"
+                  ]
+                },
+                "directed": {
+                  "type": "boolean"
+                }
+              },
+              "required": [
+                "kind",
+                "ink",
+                "directed"
+              ],
+              "additionalProperties": false
+            }
+          },
           "readmeNodeId": {
             "description": "Markdown node id used as the board README",
             "anyOf": [
@@ -345,6 +397,214 @@
                 "type": "null"
               }
             ]
+          },
+          "mapPosition": {
+            "description": "Persist a Home Map position; null returns to the generated folder layout",
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "x": {
+                    "type": "number"
+                  },
+                  "y": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "x",
+                  "y"
+                ]
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "category": {
+            "type": "object",
+            "properties": {
+              "decayType": {
+                "type": "string",
+                "enum": [
+                  "reality",
+                  "decision",
+                  "dependency",
+                  "relevance"
+                ]
+              },
+              "rate": {
+                "type": "string",
+                "enum": [
+                  "fast",
+                  "medium",
+                  "slow",
+                  "durable"
+                ]
+              },
+              "triggers": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "revalidationMethod": {
+                "type": "string",
+                "minLength": 1
+              },
+              "cadenceDays": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 36500
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "name": {
+                "type": "string",
+                "minLength": 1
+              },
+              "glyph": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "decayType",
+              "rate",
+              "triggers",
+              "revalidationMethod",
+              "id",
+              "name",
+              "glyph"
+            ],
+            "additionalProperties": false
+          },
+          "preset": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 80
+              },
+              "vocabulary": {
+                "maxItems": 64,
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "kind": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 80
+                    },
+                    "ink": {
+                      "type": "string",
+                      "enum": [
+                        "supports",
+                        "contradicts",
+                        "cites",
+                        "derived",
+                        "informs",
+                        "related"
+                      ]
+                    },
+                    "directed": {
+                      "type": "boolean"
+                    }
+                  },
+                  "required": [
+                    "kind",
+                    "ink",
+                    "directed"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "required": [
+              "id",
+              "name",
+              "vocabulary"
+            ],
+            "additionalProperties": false
+          },
+          "path": {
+            "type": "string"
+          },
+          "categoryId": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "lifecycleOverride": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "decayType": {
+                    "type": "string",
+                    "enum": [
+                      "reality",
+                      "decision",
+                      "dependency",
+                      "relevance"
+                    ]
+                  },
+                  "rate": {
+                    "type": "string",
+                    "enum": [
+                      "fast",
+                      "medium",
+                      "slow",
+                      "durable"
+                    ]
+                  },
+                  "triggers": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "revalidationMethod": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "cadenceDays": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 36500
+                  }
+                },
+                "required": [
+                  "decayType",
+                  "rate",
+                  "triggers",
+                  "revalidationMethod"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "reason": {
+            "description": "Why this board matters; shown to the human on hover",
+            "type": "string"
           }
         },
         "required": [
@@ -359,7 +619,7 @@
     },
     {
       "name": "canvas_node",
-      "description": "Create, read, update, or remove a canvas node. One tool for node CRUD: action \"add\" creates a node (requires type — markdown, status, context, ledger, trace, file, image, webpage, html, group, etc.); \"get\" reads one node by id; \"update\" patches an existing node (title, content, position, size, data); \"remove\" deletes a node by id. For spec-driven content (json-render, graph) use canvas_render; for external/built apps use canvas_app (actions: open-mcp-app, diagram, build-artifact).",
+      "description": "Lifecycle data: lifecycle-get reads effective inheritance, due/source qualification and review history (optional board); lifecycle-set sets full lifecycleOverride or null; review requires outcome retain/revise/externalize/retire/unresolved, evidence and applied. Applied retain/revise/externalize with nonempty evidence also requires expectedContentRevision and expectedSources from the content and sources actually checked; stale reviews fail. Records keep those observations and persist content before evidence. lifecycle-restore requires evidence and explicitly restores retirement, never validation. Retired cards are excluded from active briefs by default. Writes accept expectedBoardId and obey edit locks/scope. Create, read, update, or remove a canvas node. One tool for node CRUD: action \"add\" creates a node (requires type — markdown, board with data.boardId for a portal, status, context, ledger, trace, file, image, webpage, html, group, etc.); \"get\" reads one node by id; \"update\" patches an existing node (title, content, position, size, data); \"remove\" deletes a node by id. For spec-driven content (json-render, graph) use canvas_render; for external/built apps use canvas_app (actions: open-mcp-app, diagram, build-artifact).",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -369,9 +629,23 @@
               "add",
               "get",
               "update",
-              "remove"
+              "remove",
+              "lifecycle-get",
+              "lifecycle-set",
+              "review",
+              "lifecycle-restore"
             ],
-            "description": "Operation to perform: add | get | update | remove."
+            "description": "Operation to perform: add | get | update | remove | lifecycle-get | lifecycle-set | review | lifecycle-restore."
+          },
+          "destinationBoardId": {
+            "description": "Create a static node on this board without opening it. expectedBoardId still guards the ACTIVE board.",
+            "type": "string",
+            "minLength": 1
+          },
+          "requestId": {
+            "description": "Persistent logical creation identity. Reuse only for retries with identical input and destination; new identical content needs a new id. Static types only.",
+            "type": "string",
+            "minLength": 1
           },
           "intentId": {
             "description": "Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.",
@@ -381,6 +655,7 @@
             "type": "string",
             "enum": [
               "markdown",
+              "board",
               "status",
               "context",
               "ledger",
@@ -389,8 +664,8 @@
               "diff",
               "mermaid",
               "image",
-              "webpage",
               "mcp-app",
+              "webpage",
               "html",
               "group"
             ],
@@ -534,8 +809,7 @@
             "description": "The node ID to retrieve"
           },
           "board": {
-            "description": "Board id to read without opening it.",
-            "type": "string"
+            "description": "Board id to read without opening it."
           },
           "includeBlobs": {
             "description": "Include full blob payloads instead of blob summaries."
@@ -546,6 +820,10 @@
             "minimum": 0,
             "maximum": 9007199254740991
           },
+          "persistFile": {
+            "description": "Save file-backed Markdown to disk and card together; requires board and content revision preconditions",
+            "type": "boolean"
+          },
           "spec": {
             "description": "New json-render spec, or a graph payload with graphType/data for graph nodes",
             "type": "object",
@@ -584,6 +862,104 @@
           },
           "refresh": {
             "description": "Webpage nodes: pass true to re-fetch the page instead of patching fields."
+          },
+          "expectedBoardId": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "lifecycleOverride": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "decayType": {
+                    "type": "string",
+                    "enum": [
+                      "reality",
+                      "decision",
+                      "dependency",
+                      "relevance"
+                    ]
+                  },
+                  "rate": {
+                    "type": "string",
+                    "enum": [
+                      "fast",
+                      "medium",
+                      "slow",
+                      "durable"
+                    ]
+                  },
+                  "triggers": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "revalidationMethod": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "cadenceDays": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 36500
+                  }
+                },
+                "required": [
+                  "decayType",
+                  "rate",
+                  "triggers",
+                  "revalidationMethod"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "outcome": {
+            "type": "string",
+            "enum": [
+              "retain",
+              "revise",
+              "externalize",
+              "retire",
+              "unresolved"
+            ]
+          },
+          "evidence": {
+            "type": "string"
+          },
+          "applied": {
+            "type": "boolean"
+          },
+          "expectedSources": {
+            "description": "Required when validating dependencies: observations from lifecycle-get after checking the sources.",
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
           }
         },
         "required": [
@@ -901,6 +1277,16 @@
             ],
             "description": "Operation to perform: add | remove."
           },
+          "destinationBoardId": {
+            "description": "Board owning the source and edge; does not activate it",
+            "type": "string",
+            "minLength": 1
+          },
+          "requestId": {
+            "description": "Logical creation identity for retry-safe edge creation",
+            "type": "string",
+            "minLength": 1
+          },
           "intentId": {
             "description": "Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.",
             "type": "string"
@@ -913,6 +1299,11 @@
             "description": "Target node ID",
             "type": "string"
           },
+          "toBoardId": {
+            "description": "Target board ID for a cross-board edge; independent of the source destinationBoardId",
+            "type": "string",
+            "minLength": 1
+          },
           "fromSearch": {
             "description": "Resolve the source node by exact or fuzzy title/content search",
             "type": "string"
@@ -924,6 +1315,17 @@
           "type": {
             "description": "Edge type: flow, depends-on, relation, or references"
           },
+          "kind": {
+            "description": "Open semantic kind, e.g. supports, contradicts, derived-from, supersedes",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 80
+          },
+          "reason": {
+            "description": "Why this relation exists",
+            "type": "string",
+            "maxLength": 4000
+          },
           "label": {
             "description": "Edge label text"
           },
@@ -967,6 +1369,16 @@
             ],
             "description": "Operation to perform: create | add | ungroup."
           },
+          "destinationBoardId": {
+            "description": "Create the group on this board without activating it",
+            "type": "string",
+            "minLength": 1
+          },
+          "requestId": {
+            "description": "Logical creation identity for retry-safe group creation",
+            "type": "string",
+            "minLength": 1
+          },
           "intentId": {
             "description": "Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.",
             "type": "string"
@@ -1057,7 +1469,7 @@
     },
     {
       "name": "canvas_view",
-      "description": "Canvas viewport and layout control. Action \"arrange\" auto-lays-out nodes (grid/columns/etc.); \"focus\" pans/zooms the viewport to a node; \"fit\" zooms to fit all nodes in view; \"clear\" removes every node and edge from the canvas; \"remove-annotation\" deletes a human-drawn annotation by id.",
+      "description": "Canvas viewport and layout control. Action \"arrange\" auto-lays-out nodes (grid/columns/etc.); \"focus\" pans/zooms the viewport to a node; \"fit\" zooms to fit all nodes in view; \"clear\" removes every node and edge from the canvas; \"remove-annotation\" deletes a human-drawn annotation by id; \"get-tour\"/\"set-tour\" read or persist the presentation tour; \"tour-go\" presents a stop (stop index or step next/previous); \"tour-exit\" leaves presentation; \"move\" eases the camera to a nodeId, world rect or viewport over a duration. Camera actions never enter undo history.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1066,13 +1478,16 @@
             "enum": [
               "get-tour",
               "set-tour",
+              "tour-go",
+              "tour-exit",
+              "move",
               "arrange",
               "focus",
               "fit",
               "clear",
               "remove-annotation"
             ],
-            "description": "Operation to perform: arrange | focus | fit | clear | remove-annotation | get-tour | set-tour."
+            "description": "Operation to perform: arrange | focus | fit | clear | remove-annotation | get-tour | set-tour | tour-go | tour-exit | move."
           },
           "tour": {
             "anyOf": [
@@ -1100,6 +1515,40 @@
                               ],
                               "additionalProperties": false
                             },
+                            {
+                              "type": "object",
+                              "properties": {
+                                "rect": {
+                                  "type": "object",
+                                  "properties": {
+                                    "x": {
+                                      "type": "number"
+                                    },
+                                    "y": {
+                                      "type": "number"
+                                    },
+                                    "width": {
+                                      "type": "number",
+                                      "exclusiveMinimum": 0
+                                    },
+                                    "height": {
+                                      "type": "number",
+                                      "exclusiveMinimum": 0
+                                    }
+                                  },
+                                  "required": [
+                                    "x",
+                                    "y",
+                                    "width",
+                                    "height"
+                                  ]
+                                }
+                              },
+                              "required": [
+                                "rect"
+                              ],
+                              "additionalProperties": false
+                            },
                             {
                               "type": "object",
                               "properties": {
@@ -1170,6 +1619,101 @@
             ],
             "description": "Ordered camera stops, or null to derive from groups"
           },
+          "stop": {
+            "description": "Zero-based stop index to go to",
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "step": {
+            "description": "Step relative to the current stop (clamped at the ends)",
+            "type": "string",
+            "enum": [
+              "next",
+              "previous"
+            ]
+          },
+          "present": {
+            "description": "Start presenting in viewers that are not presenting yet (default true; false only moves presenting viewers)",
+            "type": "boolean"
+          },
+          "nodeId": {
+            "description": "Node or group id to frame",
+            "type": "string"
+          },
+          "rect": {
+            "description": "World-space box { x, y, width, height } to frame",
+            "type": "object",
+            "properties": {
+              "x": {
+                "type": "number"
+              },
+              "y": {
+                "type": "number"
+              },
+              "width": {
+                "type": "number",
+                "exclusiveMinimum": 0
+              },
+              "height": {
+                "type": "number",
+                "exclusiveMinimum": 0
+              }
+            },
+            "required": [
+              "x",
+              "y",
+              "width",
+              "height"
+            ]
+          },
+          "viewport": {
+            "description": "Exact screen-space camera { x, y, scale }",
+            "type": "object",
+            "properties": {
+              "x": {
+                "type": "number"
+              },
+              "y": {
+                "type": "number"
+              },
+              "scale": {
+                "type": "number",
+                "exclusiveMinimum": 0
+              }
+            },
+            "required": [
+              "x",
+              "y",
+              "scale"
+            ]
+          },
+          "duration": {
+            "description": "Move time in seconds (default 1; 0 jumps)",
+            "type": "number",
+            "minimum": 0,
+            "maximum": 3600
+          },
+          "easing": {
+            "description": "linear | ease-in-out (default) | ease-out",
+            "type": "string",
+            "enum": [
+              "linear",
+              "ease-in-out",
+              "ease-out"
+            ]
+          },
+          "padding": {
+            "description": "Screen pixels around a node/rect target (default 40)",
+            "type": "number",
+            "minimum": 0
+          },
+          "pullback": {
+            "description": "Mid-move log-zoom pull-back, 0–4 (default 0)",
+            "type": "number",
+            "minimum": 0,
+            "maximum": 4
+          },
           "layout": {
             "description": "Arrangement layout (default: grid)",
             "type": "string",
@@ -1194,10 +1738,6 @@
             "description": "Viewport height used for fit math (default 900)",
             "type": "number"
           },
-          "padding": {
-            "description": "World-space padding around fitted nodes (default 60)",
-            "type": "number"
-          },
           "maxScale": {
             "description": "Maximum zoom scale (default 1)",
             "type": "number"
@@ -1222,7 +1762,7 @@
     },
     {
       "name": "canvas_query",
-      "description": "Read the board cheapest-first. Action \"context\" returns a budgeted cross-board brief with a durable consumer cursor (budget is UTF-16 characters); \"search\" finds nodes by title/content keywords; \"layout\" returns the full layout; \"validate\" checks geometry and endpoints.",
+      "description": "Read the board cheapest-first. Action \"context\" returns a budgeted cross-board brief with a durable consumer cursor (budget is UTF-16 characters); \"graph\" explores the library relation graph (focus: board ID, qualified node key, or pins; depth: 0–4), summaries only; \"search\" finds nodes by title/content keywords; \"layout\" returns the full layout; \"validate\" checks geometry and endpoints.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1230,11 +1770,12 @@
             "type": "string",
             "enum": [
               "context",
+              "graph",
               "search",
               "layout",
               "validate"
             ],
-            "description": "Operation to perform: context | search | layout | validate."
+            "description": "Operation to perform: context | graph | search | layout | validate."
           },
           "consumer": {
             "description": "Stable consumer id used for the durable board-scoped cursor"
@@ -1245,6 +1786,32 @@
           "budget": {
             "description": "Maximum response size in UTF-16 code units"
           },
+          "projection": {
+            "default": "full",
+            "description": "Full board/card graph, or board-only Map summaries with qualified cross-board and missing relations",
+            "type": "string",
+            "enum": [
+              "full",
+              "boards"
+            ]
+          },
+          "focus": {
+            "description": "Board ID, board-qualified graph node key, or pins; omit for the library",
+            "type": "string"
+          },
+          "depth": {
+            "default": 2,
+            "description": "Undirected hops, including membership, 0–4 (default 2)",
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "string",
+                "minLength": 1
+              }
+            ]
+          },
           "q": {
             "description": "Search query — matches against node titles, content, and file paths"
           },
@@ -1256,6 +1823,14 @@
               "library"
             ]
           },
+          "boardId": {
+            "description": "Stable board ID to search; defaults scope to library when supplied",
+            "type": "string"
+          },
+          "folder": {
+            "description": "Folder and descendants; empty string selects unfiled boards",
+            "type": "string"
+          },
           "limit": {
             "description": "Max results to return (default: 10)",
             "type": "number"
@@ -1574,7 +2149,7 @@
     },
     {
       "name": "canvas_ax_state",
-      "description": "Read or set host-agnostic PMX AX state. Action \"get\" reads the AX state + agent-ready context (pinned/focused context, focus field); \"set-focus\" places node IDs in the AX focus field (nodeIds); \"set-policy\" patches the tool/prompt policy (tools.allowed|excluded|approvalRequired, prompt.systemAppend|mode — merges with existing); \"report-capability\" records a host/session capability for diagnostics; \"presence\" reads agent presence (who is writing, phase, attached session, context budget); \"set-presence\" updates this caller's presence (phase idle|thinking|tooling|waiting-approval, detail, focusNodeId, cursor, attached — attached:true starts a session, false ends it; contextUsage {used,total} reports the agent's real token window so the board's meter shows it instead of the pinned-context estimate). Adapters may pass a source label (e.g. codex).",
+      "description": "Read or set host-agnostic PMX AX state. Action \"get\" reads the AX state + agent-ready context (pinned/focused context, focus field); \"set-focus\" places node IDs in the AX focus field (nodeIds); \"set-policy\" patches the tool/prompt policy (tools.allowed|excluded|approvalRequired, prompt.systemAppend|mode — merges with existing); \"report-capability\" records a host/session capability for diagnostics; \"presence\" reads agent presence (who is writing, phase, attached session); \"set-presence\" updates this caller's presence (phase idle|thinking|tooling|waiting-approval, detail, focusNodeId, cursor, attached — attached:true starts a session, false ends it; contextUsage {used,total} reports the agent's real token usage, which the board's context panel names). Adapters may pass a source label (e.g. codex).",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1763,7 +2338,7 @@
             "type": "boolean"
           },
           "contextUsage": {
-            "description": "The agent's real token window as {used,total} — shown on the board's context meter instead of the pinned-context estimate (null clears it)",
+            "description": "The agent's real token usage as {used,total} — the board's context panel names how many tokens its whole context holds (null clears it)",
             "anyOf": [
               {
                 "type": "object",
@@ -2074,6 +2649,10 @@
           "board": {
             "description": "Board id; defaults to the open board.",
             "type": "string"
+          },
+          "boards": {
+            "description": "Comma-separated board ids: also return each one's latest agent read (pinned boards, in one request).",
+            "type": "string"
           }
         },
         "required": [