@stablebaseline/sdk 0.1.0 → 0.3.0

package/openapi.json

@@ -487,7 +487,7 @@
     "/tools/listArchitectureIcons": {
       "post": {
         "summary": "listArchitectureIcons",
-        "description": "List icons for systemsarchitecture diagrams. Use returned iconPath as-is in D2 code (e.g. icon: dev/docker.svg).",
+        "description": "List curated software-architecture icons (AWS, Azure, GCP, Docker, Kubernetes, databases, message queues, etc.). Each result has an `iconPath` (e.g. 'dev/docker.svg'). TWO ways to use it: (1) on a WHITEBOARD, drop it via addWhiteboardElements({ type:'image', iconPath:'dev/docker.svg', x, y, width:96, height:96, text:'Docker' }); (2) in a D2 systems-architecture diagram, use the iconPath as-is in D2 code (e.g. icon: dev/docker.svg).",
         "operationId": "listArchitectureIcons",
         "tags": [
           "diagrams"
@@ -700,7 +700,7 @@
         "description": "Return the calling user's identity (user_id, display_name, full_name, email, avatar_url). Use this when the user says 'me' / 'mine' / 'I' so you can resolve to their UUID before passing it to tools like updateImprovement(owner_id=…) or filtering by owner. Read-only.",
         "operationId": "getCurrentUser",
         "tags": [
-          "uncategorized"
+          "members"
         ],
         "requestBody": {
           "required": false,
@@ -791,10 +791,10 @@
     "/tools/listAssignablePrincipals": {
       "post": {
         "summary": "listAssignablePrincipals",
-        "description": "Server-side searchable, paginated list of USERS and TEAMS that can be assigned as the owner of an improvement/task in a project. Returns two arrays — `users` (with user_id, display_name, email, avatar_url, has_explicit_permission) and `teams` (with team_id, name, member_count, has_explicit_permission). Sources: project-level grants + workspace members + organization members + members of teams granted access. Use BEFORE updateImprovement/updateTask when you need to discover an `owner_id` (kind='user') or `owner_team_id` (kind='team') by name. Supports `q` for ILIKE search on names/emails (users) or team names. Pass `kind='user'` or `kind='team'` to scope to a single section, or 'all' (default) for both. Pagination via limit (1-100, default 20) + offset.",
+        "description": "Server-side searchable, paginated list of USERS and TEAMS that can be assigned as the owner of an improvement/task in a project — and the canonical source for resolving a person's user_id when @-mentioning them in a document. Returns two arrays — `users` (with user_id, display_name, email, avatar_url, has_explicit_permission) and `teams` (with team_id, name, member_count, has_explicit_permission). Sources: project-level grants + workspace members + organization members + members of teams granted access. Use BEFORE: (1) updateImprovement/updateTask when you need an `owner_id` (kind='user') or `owner_team_id` (kind='team'); (2) inserting a `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"…\",\"label\":\"…\"} -->` mention in document content via createDocument / editDocument / findAndReplaceTextInDocument. Supports `q` for ILIKE search on names/emails (users) or team names. Pass `kind='user'` or `kind='team'` to scope to a single section, or 'all' (default) for both. Pagination via limit (1-100, default 20) + offset.",
         "operationId": "listAssignablePrincipals",
         "tags": [
-          "uncategorized"
+          "members"
         ],
         "requestBody": {
           "required": false,
@@ -1957,6 +1957,124 @@
         }
       }
     },
+    "/tools/reorderFolders": {
+      "post": {
+        "summary": "reorderFolders",
+        "description": "Batch-reorder folders within a parent (or project root) by setting sibling positions. Pass [{folderId, position}, ...] where position is a non-negative integer; usually you renumber siblings sequentially as 0, 1, 2…. To MOVE a folder to a different parent and set its position there, use updateFolder({parentId, position}) instead.",
+        "operationId": "reorderFolders",
+        "tags": [
+          "folders"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "items": {
+                    "type": "array",
+                    "description": "List of folder position updates. All folders must belong to the same project.",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "folderId": {
+                          "type": "string"
+                        },
+                        "position": {
+                          "type": "number"
+                        }
+                      },
+                      "required": [
+                        "folderId",
+                        "position"
+                      ]
+                    },
+                    "minItems": 1
+                  }
+                },
+                "required": [
+                  "items"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/tools/listDocuments": {
       "post": {
         "summary": "listDocuments",
@@ -2469,7 +2587,7 @@
     "/tools/createDocument": {
       "post": {
         "summary": "createDocument",
-        "description": "Create a document from CDMD markdown. Call getCdmdLanguageGuide first if unfamiliar with syntax. Do not include DIAGRAM/IMAGE markers — insert them after with dedicated tools.",
+        "description": "Create a document from CDMD markdown. Call getCdmdLanguageGuide first if unfamiliar with syntax. Do not include DIAGRAM/IMAGE markers — insert them after with dedicated tools. Supports @-mentioning people: embed `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->` to notify a teammate. Use listAssignablePrincipals to look up the user_id from a name; mentions of users outside the project are silently dropped.",
         "operationId": "createDocument",
         "tags": [
           "documents"
@@ -2493,6 +2611,10 @@
                   "cdmd": {
                     "type": "string"
                   },
+                  "position": {
+                    "type": "number",
+                    "description": "Sort position within the parent folder (or project root if no folderId). When omitted, the document is appended at the end."
+                  },
                   "changeSummary": {
                     "type": "string",
                     "description": "Version history summary."
@@ -2584,10 +2706,2086 @@
     "/tools/editDocument": {
       "post": {
         "summary": "editDocument",
-        "description": "Edit a document with line-based patches. Call getDocument first for line numbers and versionTimestamp. Call getCdmdLanguageGuide if unfamiliar with CDMD syntax. Do not edit DIAGRAM/IMAGE markers manually — use dedicated diagram/image tools.",
+        "description": "Edit a document with line-based patches. Call getDocument first for line numbers and versionTimestamp. Call getCdmdLanguageGuide if unfamiliar with CDMD syntax. Do not edit DIAGRAM/IMAGE markers manually — use dedicated diagram/image tools. To @-mention a person in your patch, insert `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.",
         "operationId": "editDocument",
         "tags": [
-          "documents"
+          "documents"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "documentId": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string",
+                    "description": "New title."
+                  },
+                  "folderId": {
+                    "type": "string",
+                    "description": "Move to this folder."
+                  },
+                  "position": {
+                    "type": "number",
+                    "description": "Sort position within the parent folder. Use to reposition a single document. For batch sibling reorder, use reorderDocuments."
+                  },
+                  "versionTimestamp": {
+                    "type": "number",
+                    "description": "Version timestamp from getDocument() for optimistic locking."
+                  },
+                  "changeSummary": {
+                    "type": "string",
+                    "description": "Version history summary."
+                  },
+                  "patches": {
+                    "type": "array",
+                    "description": "Line-based patches. Can be empty if only updating title, folderId, or position.",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "startLine": {
+                          "type": "number",
+                          "description": "1-based start line."
+                        },
+                        "endLine": {
+                          "type": "number",
+                          "description": "1-based end line (inclusive)."
+                        },
+                        "replacement": {
+                          "type": "string",
+                          "description": "Replacement text. Empty string to delete lines."
+                        }
+                      },
+                      "required": [
+                        "startLine",
+                        "endLine",
+                        "replacement"
+                      ]
+                    }
+                  }
+                },
+                "required": [
+                  "documentId",
+                  "versionTimestamp"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/findAndReplaceTextInDocument": {
+      "post": {
+        "summary": "findAndReplaceTextInDocument",
+        "description": "Find and replace text in a document. Searches for all occurrences and replaces them. Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.",
+        "operationId": "findAndReplaceTextInDocument",
+        "tags": [
+          "documents"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "documentId": {
+                    "type": "string"
+                  },
+                  "find": {
+                    "type": "string",
+                    "description": "Text to search for."
+                  },
+                  "replace": {
+                    "type": "string",
+                    "description": "Replacement text. Empty string to delete occurrences."
+                  },
+                  "caseSensitive": {
+                    "type": "boolean",
+                    "description": "Case-sensitive matching. Default: true."
+                  },
+                  "changeSummary": {
+                    "type": "string",
+                    "description": "Version history summary."
+                  }
+                },
+                "required": [
+                  "documentId",
+                  "find",
+                  "replace"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/getDiagramInDocument": {
+      "post": {
+        "summary": "getDiagramInDocument",
+        "description": "Get a diagram's full details including raw DSL source code. Use diagramId from DIAGRAM_OMITTED markers in getDocument output. Returns diagramCode, type, name, nlDescription, and versionTimestamp.",
+        "operationId": "getDiagramInDocument",
+        "tags": [
+          "diagrams"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "diagramId": {
+                    "type": "string",
+                    "description": "Diagram ID from DIAGRAM_OMITTED markers."
+                  },
+                  "fields": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Field projection. Valid fields: diagramId, documentId, type, name, diagramCode, nlDescription, colorPlan, renderStatus, renderError, createdAt, updatedAt, versionTimestamp."
+                  }
+                },
+                "required": [
+                  "diagramId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/insertDiagramInDocument": {
+      "post": {
+        "summary": "insertDiagramInDocument",
+        "description": "Insert a new diagram into a document. Call listDiagramTypes to find your type, then getDiagramTypeGuide for DSL syntax before writing diagramCode. Always set prompt + nlDescription to describe what the diagram shows (they are its saved description) and keep them accurate. After inserting, VERIFY the render — set returnImage:true (or call getDiagramImage) to actually SEE it — and if it is wrong or ugly, correct it with updateDiagramInDocument (provide the full updated diagramCode).",
+        "operationId": "insertDiagramInDocument",
+        "tags": [
+          "diagrams"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "documentId": {
+                    "type": "string"
+                  },
+                  "documentVersionTimestamp": {
+                    "type": "number",
+                    "description": "Version timestamp from getDocument() for optimistic locking."
+                  },
+                  "type": {
+                    "type": "string",
+                    "description": "Diagram type (e.g. mermaid, plantuml, bpmn, d2). Call listDiagramTypes for all types."
+                  },
+                  "diagramCode": {
+                    "type": "string",
+                    "description": "Diagram DSL code. Call getDiagramTypeGuide for syntax."
+                  },
+                  "prompt": {
+                    "type": "string",
+                    "description": "Short description of what the diagram shows (1-2 sentences)."
+                  },
+                  "nlDescription": {
+                    "type": "string",
+                    "description": "Extended description of the diagram (2-4 sentences)."
+                  },
+                  "align": {
+                    "type": "string",
+                    "description": "Alignment.",
+                    "enum": [
+                      "left",
+                      "center",
+                      "right"
+                    ]
+                  },
+                  "caption": {
+                    "type": "string",
+                    "description": "Caption below the diagram."
+                  },
+                  "afterLine": {
+                    "type": "number",
+                    "description": "Insert after this line number (1-based)."
+                  },
+                  "colorPlan": {
+                    "type": "object",
+                    "description": "BPMN only. Color plan: { byElementId: { ElementId: SwatchName } }.",
+                    "properties": {
+                      "byElementId": {
+                        "type": "object",
+                        "description": "Map of element IDs to color swatch names.",
+                        "additionalProperties": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "required": [
+                      "byElementId"
+                    ]
+                  },
+                  "returnImage": {
+                    "type": "boolean",
+                    "description": "If true, also render the inserted diagram and return it as an image inline (one-call insert-and-get-image). Defaults false."
+                  },
+                  "imageFormat": {
+                    "type": "string",
+                    "enum": [
+                      "png",
+                      "jpeg",
+                      "svg"
+                    ],
+                    "description": "Image format when returnImage:true (default png)."
+                  },
+                  "imageScale": {
+                    "type": "number",
+                    "enum": [
+                      1,
+                      2,
+                      3
+                    ],
+                    "description": "Raster resolution 1x/2x/3x when returnImage:true (default 2)."
+                  },
+                  "imageBackground": {
+                    "type": "string",
+                    "description": "Background for the returned png/jpeg (e.g. '#ffffff' or 'transparent')."
+                  }
+                },
+                "required": [
+                  "documentId",
+                  "documentVersionTimestamp",
+                  "type",
+                  "diagramCode",
+                  "prompt",
+                  "nlDescription",
+                  "align",
+                  "caption",
+                  "afterLine"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/updateDiagramInDocument": {
+      "post": {
+        "summary": "updateDiagramInDocument",
+        "description": "Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Requires documentVersionTimestamp from getDocument. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.",
+        "operationId": "updateDiagramInDocument",
+        "tags": [
+          "diagrams"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "diagramId": {
+                    "type": "string",
+                    "description": "Diagram ID from DIAGRAM_OMITTED markers."
+                  },
+                  "diagramCode": {
+                    "type": "string",
+                    "description": "New diagram DSL source code. REQUIRED to change what the diagram visually renders. Call getDiagramTypeGuide for syntax. Must provide the COMPLETE updated DSL, not just the changed parts."
+                  },
+                  "prompt": {
+                    "type": "string",
+                    "description": "New short description (metadata only — does NOT change the rendered diagram)."
+                  },
+                  "nlDescription": {
+                    "type": "string",
+                    "description": "New extended description (metadata only — does NOT change the rendered diagram)."
+                  },
+                  "align": {
+                    "type": "string",
+                    "description": "Alignment.",
+                    "enum": [
+                      "left",
+                      "center",
+                      "right"
+                    ]
+                  },
+                  "caption": {
+                    "type": "string",
+                    "description": "New caption."
+                  },
+                  "colorPlan": {
+                    "type": "object",
+                    "description": "BPMN only. Updated color plan. Set to null to remove.",
+                    "properties": {
+                      "byElementId": {
+                        "type": "object",
+                        "description": "Map of element IDs to color swatch names.",
+                        "additionalProperties": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "required": [
+                      "byElementId"
+                    ]
+                  },
+                  "documentVersionTimestamp": {
+                    "type": "number",
+                    "description": "Version timestamp from getDocument() for optimistic locking."
+                  }
+                },
+                "required": [
+                  "diagramId",
+                  "documentVersionTimestamp"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/deleteDiagramInDocument": {
+      "post": {
+        "summary": "deleteDiagramInDocument",
+        "description": "Delete a diagram from a document.",
+        "operationId": "deleteDiagramInDocument",
+        "tags": [
+          "diagrams"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "diagramId": {
+                    "type": "string",
+                    "description": "Diagram ID from DIAGRAM_OMITTED markers."
+                  }
+                },
+                "required": [
+                  "diagramId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/deleteDocument": {
+      "post": {
+        "summary": "deleteDocument",
+        "description": "Delete a document.",
+        "operationId": "deleteDocument",
+        "tags": [
+          "documents"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "documentId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "documentId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/getWhiteboardGuide": {
+      "post": {
+        "summary": "getWhiteboardGuide",
+        "description": "Get the Stable Baseline whiteboarding guide (Markdown): when to use stencils vs architecture icons vs code/BPMN diagrams vs plain shapes vs real images vs frames/presentations, how to lay out and verify a board, and how to edit a large board safely (patch by id, never replace). Call before authoring a non-trivial whiteboard.",
+        "operationId": "getWhiteboardGuide",
+        "tags": [
+          "whiteboards"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {}
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/createWhiteboard": {
+      "post": {
+        "summary": "createWhiteboard",
+        "description": "Create a whiteboard — an infinite Excalidraw canvas. A whiteboard is a hidden document (it won't appear in listDocuments) that hosts a single freeform canvas, and opens in the immersive whiteboard editor in the app. Returns documentId + diagramId. Author shapes afterwards with addWhiteboardElements (high-level specs) or updateWhiteboardScene. For anything beyond a blank board, call getWhiteboardGuide first to plan the layout (stencils vs architecture icons vs code/BPMN diagrams vs plain shapes), and render with getWhiteboardImage to verify as you go.",
+        "operationId": "createWhiteboard",
+        "tags": [
+          "whiteboards"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "projectId": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string",
+                    "description": "Whiteboard title. Defaults to 'Untitled whiteboard'."
+                  },
+                  "folderId": {
+                    "type": "string",
+                    "description": "Optional folder to file the whiteboard under."
+                  }
+                },
+                "required": [
+                  "projectId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/listWhiteboards": {
+      "post": {
+        "summary": "listWhiteboards",
+        "description": "List the whiteboards in a project (hidden whiteboard-kind documents). Returns documentId, diagramId, title and timestamps for each.",
+        "operationId": "listWhiteboards",
+        "tags": [
+          "whiteboards"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "projectId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "projectId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/getWhiteboard": {
+      "post": {
+        "summary": "getWhiteboard",
+        "description": "Read a whiteboard: its metadata plus a summary of the canvas (element count, element types, and text labels on the board). Pass includeElements=true to also return the full Excalidraw scene ({elements, appState, files}) — needed if you intend to modify it and send it back via updateWhiteboardScene. FOR BEST RESULTS, also call getWhiteboardImage to render the board to an image and actually SEE it: the visual layout (positions, spacing, overlaps, colours, how shapes connect) is far easier to understand from the rendered picture than from the element list, so view it first to truly understand the board and to propose or verify edits accurately.",
+        "operationId": "getWhiteboard",
+        "tags": [
+          "whiteboards"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "documentId": {
+                    "type": "string"
+                  },
+                  "includeElements": {
+                    "type": "boolean",
+                    "description": "When true, returns the full Excalidraw scene so it can be modified and written back."
+                  }
+                },
+                "required": [
+                  "documentId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/updateWhiteboardScene": {
+      "post": {
+        "summary": "updateWhiteboardScene",
+        "description": "Edit elements on a whiteboard's canvas WITHOUT dropping the rest of the scene. A board may hold many diagrams/elements, so prefer surgical edits: mode='patch' (DEFAULT) shallow-merges each incoming object into the existing element with the same `id` (send just {id, backgroundColor:'blue'} to recolour one box, or {id, x, y} to move one) and appends any elements whose id is new/absent — everything else is left untouched. `deleteIds` removes specific elements by id. mode='append' only adds. mode='replace' overwrites the ENTIRE scene (use ONLY when intentionally rewriting the whole board). To author NEW shapes/connectors from a high-level spec, prefer addWhiteboardElements — and prefer library stencils / sticky notes / architecture icons over plain rectangles wherever a standard form fits (sticky notes, kanban/scrum, flowcharts, UML/ER, BPMN, org charts, wireframes). Optional appState/files are merged in. PROCESS: for a non-trivial edit call getWhiteboardGuide FIRST; after editing, ALWAYS call getWhiteboardImage to confirm the board still looks right (layout, labels, overlaps), and patch again if it doesn't.",
+        "operationId": "updateWhiteboardScene",
+        "tags": [
+          "whiteboards"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "documentId": {
+                    "type": "string"
+                  },
+                  "elements": {
+                    "type": "array",
+                    "description": "Elements to write. For mode 'patch', each may be a partial { id, ...changedFields } merged into the matching element by id; full Excalidraw elements for 'replace'/'append' (or new ids in 'patch').",
+                    "items": {
+                      "type": "object"
+                    }
+                  },
+                  "mode": {
+                    "type": "string",
+                    "enum": [
+                      "patch",
+                      "append",
+                      "replace"
+                    ],
+                    "description": "patch (DEFAULT — merge by id, keep the rest), append (add only), or replace (overwrite the whole scene)."
+                  },
+                  "deleteIds": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Element ids to remove from the scene."
+                  },
+                  "appState": {
+                    "type": "object",
+                    "description": "Optional Excalidraw appState fields to merge (e.g. viewBackgroundColor)."
+                  },
+                  "files": {
+                    "type": "object",
+                    "description": "Optional Excalidraw BinaryFiles map (for embedded images), merged in."
+                  },
+                  "versionTimestamp": {
+                    "type": "number",
+                    "description": "Optional optimistic-locking token from getWhiteboard. Only used for mode 'replace': if the board changed since you read it, the replace is rejected so you don't overwrite a collaborator's newer edits — re-read with getWhiteboard and retry. Not needed for patch/append, which automatically merge onto the latest scene."
+                  }
+                },
+                "required": [
+                  "documentId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/addWhiteboardElements": {
+      "post": {
+        "summary": "addWhiteboardElements",
+        "description": "Author shapes onto a whiteboard from high-level specs (you do NOT need the full Excalidraw element schema). Appends to the canvas. PREFER THE RICHEST FORM THAT FITS, not plain rectangles: for a sticky/post-it note use { type:'sticky', text, backgroundColor } (a first-class note with an auto-fitting bound label — there is NO sticky-note stencil; OMIT x/y and it is auto-placed in clear space below existing content, so it doesn't land on top of the current drawing); for kanban/scrum/story boards, flowcharts, UML/ER, BPMN, org charts, wireframes/mockups, charts or people use a LIBRARY STENCIL in ONE call — { type:'stencil', stencil:'<name e.g. decision>', x, y } fuzzy-matches by name with no prior listWhiteboardStencils call (pass width/height to SCALE the whole stencil and text to fill its single label); for cloud/software-architecture use ICONS — { type:'image', iconPath:'dev/docker.svg', x, y } (paths from listArchitectureIcons); reserve raw rectangles/ellipses for when no standard form fits. Expressive enough to reproduce real Excalidraw templates (sticky-note brainstorm grids, sketchy mind maps, flowcharts). Each spec: { type: 'rectangle'|'ellipse'|'diamond'|'sticky'|'text'|'arrow'|'line'|'frame'|'image'|'stencil', id?, x, y, width, height, text? (STRONGLY PREFER setting a shape's label via its own `text` — it becomes a centered, auto-WRAPPED bound label fitted to the shape; do NOT drop a separate type:'text' element on top of a shape as its label. Standalone type:'text' is for free-floating titles/notes and now also wraps to its width; Yes/No label on an arrow — emojis are fine, e.g. 'Risks ⚠️'), fontSize?, fontFamily? (1=hand-drawn default, 2=normal, 3=code), textAlign?, backgroundColor? (name 'blue'/'green'/'yellow'/'pink'/'violet'/'orange'/'teal'/… or hex), strokeColor?, fillStyle? ('solid'|'hachure'|'cross-hatch'), strokeStyle? ('solid'|'dashed'|'dotted' — use 'dashed' for grid/category borders), strokeWidth? (1 thin/2 bold/4 extra), roughness? (0 clean, 1 default, 2 very sketchy/hand-drawn — use 2 for organic mind maps), roundness? (number type or null for sharp), opacity?, name? (frame title), frameId? (put a shape inside a frame), start?:{id}, end?:{id} (connect arrows/lines to shapes by id — connectors AUTO-CLIP to the shape edges, never overrun to the centre, AUTO-ROUTE around any shapes in between so a decision's No/loop-back branch never cuts straight through the boxes between source and target, and bound text auto-wraps + centres), routing? ('straight' default | 'elbow' for clean right-angle flowchart/org-chart connectors | 'curved'), startArrowhead?/endArrowhead? (arrowheads are SOLID filled triangles by default — just OMIT them. Pass null for a plain mind-map spoke with no head. Do NOT pass 'arrow': that is Excalidraw's open 'V' and is auto-upgraded to a solid triangle anyway), points? ([[0,0],[dx,dy]] relative, only for manual geometry — almost never needed; binding by id is better), props? (escape hatch: any other Excalidraw field) }. ARCHITECTURE ICONS: to place a software-architecture icon (AWS/Azure/GCP/Docker/Kubernetes/databases/etc.), first call listArchitectureIcons to find one, then add a spec { type:'image', iconPath:'<relative_url e.g. dev/docker.svg>', x, y, width:96, height:96, text?:'<caption shown below>' } — the icon is stored as a URL reference (never base64). Use imageUrl instead of iconPath for any other public image. Combine icons with labelled boxes + elbow arrows for clean architecture diagrams. LIBRARY STENCILS: for hand-drawn, on-brand elements (scrum/kanban columns, flowchart symbols, UML/ER, BPMN, org-chart nodes, wireframe widgets, stick figures), FIRST call listWhiteboardStencils to find one, then add { type:'stencil', stencilKey:'<key from listWhiteboardStencils>', x, y } (or { type:'stencil', stencil:'<name e.g. decision>', pack?:'<pack>', x, y } to fuzzy-match by name). A stencil is a mini-whiteboard (a collection of elements) of kind 'symbol' or 'template' (listWhiteboardStencils returns the kind + its embedded `labels`). For a SYMBOL (one atomic labelled node — flowchart box, BPMN task, org node), pass id + text + width/height: the label auto-fits its single slot and arrows bind to it via start/end {id}. For a TEMPLATE (a multi-component layout — Alerts, Forms, Tables, Charts), place it WHOLE (no single text); the result returns its `children` (id + text + colour + position) so you retext, recolour, or DELETE specific parts by id via updateWhiteboardScene (cluster children by y to act on a whole row/variant). STRONGLY prefer stencils over plain rectangles for wireframes/mockups, kanban/scrum boards, UML/BPMN, org charts; for dense flowcharts, plain shapes with bound text + elbow arrows are equally reliable. (For a plain sticky/post-it note use type:'sticky', NOT a stencil — there is no sticky-note stencil.) FRAMES: a frame is a NON-DESTRUCTIVE, ANY-SIZE container. To enclose shapes that ALREADY exist, add ONE type:'frame' sized to cover them (Excalidraw auto-captures elements inside a frame's bounds) or set those shapes' frameId — never recreate or delete-and-redraw content just to frame it. If a frame doesn't fully cover its content, just RESIZE the frame (patch its width/height). Deleting a frame (deleteIds:[frameId]) leaves all its contents intact on the canvas — it only removes the frame border + title. PRESENTATION/SLIDES: when the user wants a presentation or slide deck, create type:'frame' slides sized width:1280,height:720 (16:9), laid out LEFT-TO-RIGHT at the same y (x: 0, then 1440, 2880, 4320, …), each with a `name` (the slide title). Put every slide's shapes/text/images INSIDE its frame by setting their frameId to that frame's id (give the frame an id and reference it). Slides play in order (left-to-right, then top-to-bottom) in the board's Present mode and export to PPTX, so one frame = one slide. FLOWCHART recipe: rectangles (roundness null for sharp process boxes), diamonds for decisions, arrows with routing:'elbow' and Yes/No as the arrow's text. Use type 'sticky' for sticky/post-it notes (a solid-fill note with an auto-fitting bound label — set text + backgroundColor); type 'line' with no arrowheads + roughness:2 for sketchy mind-map spokes. Give shapes ids and reference them from connectors. Connectors may also bind to shapes ALREADY on the board by their id (get them via getWhiteboard includeElements:true) — you do NOT need to resend existing shapes; the server reads the live scene to bind the arrow and route it around the other boxes. Great for brainstorms, mind maps, flowcharts, org charts, SWOT, retros. PROCESS: for any non-trivial board call getWhiteboardGuide FIRST to plan it; then after adding, ALWAYS call getWhiteboardImage to SEE the result and check layout, labels, spacing, overlaps and how shapes connect — if anything looks off, fix it with updateWhiteboardScene (patch by id) and render again, iterating until it looks right. RESULT: returns `added` (count), `placement` (bounding box {x,y,width,height} of what you just added) and `autoPlaced` (true when you omitted x/y so it was placed in clear space below existing content) — use placement/autoPlaced to tell the user WHERE the new elements landed, never invent a location.",
+        "operationId": "addWhiteboardElements",
+        "tags": [
+          "whiteboards"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "documentId": {
+                    "type": "string"
+                  },
+                  "shapes": {
+                    "type": "array",
+                    "description": "Non-empty array of shape specs to append. Prefer stencils / sticky notes / architecture icons over raw rectangles wherever a standard form fits (see the `type` enum below and the tool description).",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "enum": [
+                            "rectangle",
+                            "ellipse",
+                            "diamond",
+                            "sticky",
+                            "text",
+                            "arrow",
+                            "line",
+                            "frame",
+                            "image",
+                            "stencil"
+                          ],
+                          "description": "Element kind. 'sticky' = a first-class sticky/post-it note (solid fill + auto-fitting bound label; set text + backgroundColor) — use this for sticky notes, NOT a stencil. 'stencil' = a hand-drawn library graphic from listWhiteboardStencils, of kind 'symbol' (one atomic labelled node — flowchart box, BPMN task, org node: set `id` + `text` + width/height, text auto-fits, connect arrows via start/end {id}) or 'template' (a multi-element layout — Alerts, Forms, Tables, Charts: place whole, then customise its returned children by id; do NOT set a single `text`). Set `stencil` (fuzzy name, one call) or `stencilKey` (exact). 'image' with `iconPath` = a software-architecture icon from listArchitectureIcons. Reserve rectangle/ellipse/diamond for when no standard form fits."
+                        },
+                        "stencil": {
+                          "type": "string",
+                          "description": "For type:'stencil' — fuzzy-match a library stencil by name in ONE call, no prior listWhiteboardStencils needed (e.g. 'decision', 'actor', 'phone frame', 'kanban column'). NOTE: there is no sticky-note stencil — use type:'sticky' for sticky/post-it notes."
+                        },
+                        "stencilKey": {
+                          "type": "string",
+                          "description": "For type:'stencil' — exact stencil key from listWhiteboardStencils (takes precedence over `stencil`)."
+                        },
+                        "pack": {
+                          "type": "string",
+                          "description": "For type:'stencil' — optional pack to disambiguate a fuzzy `stencil` match (e.g. 'Flowchart', 'BPMN', 'UML & ER', 'Scrum Board')."
+                        },
+                        "iconPath": {
+                          "type": "string",
+                          "description": "For type:'image' — a software-architecture icon path from listArchitectureIcons (e.g. 'dev/docker.svg')."
+                        },
+                        "imageUrl": {
+                          "type": "string",
+                          "description": "For type:'image' — any other public image URL (use iconPath for curated architecture icons)."
+                        },
+                        "id": {
+                          "type": "string",
+                          "description": "Optional id so connectors (arrows/lines) can reference this shape via start/end. On a type:'stencil' it adds a transparent bindable anchor covering the stencil, so an arrow's start/end {id} connects to the whole stencil as a unit."
+                        },
+                        "groupId": {
+                          "type": "string",
+                          "description": "Join an existing group. Pass a placed stencil's `groupId` (returned in the placement result) on a type:'text' or shape spec to FILL that frame as part of the same unit — the text then moves, duplicates and renders together with the frame (e.g. a title in a UML class box's top band, members in its body)."
+                        },
+                        "x": {
+                          "type": "number",
+                          "description": "Top-left x on the canvas. OMIT both x and y to auto-place this element in clear empty space below the board's existing content. Strongly preferred when adding a note/shape to a board that already has content: a guessed coordinate usually lands ON TOP of existing shapes (the 'added a sticky but can't see it' bug). Set x/y only for deliberate layout among shapes you add in this same call."
+                        },
+                        "y": {
+                          "type": "number",
+                          "description": "Top-left y on the canvas. Omit together with x to auto-place (see x)."
+                        },
+                        "width": {
+                          "type": "number",
+                          "description": "Shape width; for type:'stencil' it scales the whole stencil to fit this width."
+                        },
+                        "height": {
+                          "type": "number",
+                          "description": "Shape height; for type:'stencil' it scales the whole stencil to fit this height."
+                        },
+                        "scale": {
+                          "type": "number",
+                          "description": "For type:'stencil' — uniform scale factor for the whole stencil (alternative to width/height)."
+                        },
+                        "text": {
+                          "type": "string",
+                          "description": "Label/caption. On a shape it's a centered auto-wrapped bound label (prefer over a separate type:'text'); on a type:'sticky' it's the note text; on a type:'stencil' of kind 'symbol' it fills + re-fits its single label (IGNORED for 'template' stencils — customise their children by id instead)."
+                        },
+                        "backgroundColor": {
+                          "type": "string",
+                          "description": "Fill colour: a name ('blue'/'green'/'yellow'/'pink'/'violet'/'orange'/'teal'/…) or a hex value."
+                        },
+                        "start": {
+                          "type": "object",
+                          "description": "For arrows/lines: { id } of the source shape (auto-clips to the edge + auto-routes around shapes in between)."
+                        },
+                        "end": {
+                          "type": "object",
+                          "description": "For arrows/lines: { id } of the target shape."
+                        }
+                      },
+                      "required": [
+                        "type"
+                      ],
+                      "additionalProperties": true
+                    },
+                    "minItems": 1
+                  }
+                },
+                "required": [
+                  "documentId",
+                  "shapes"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/duplicateWhiteboardElements": {
+      "post": {
+        "summary": "duplicateWhiteboardElements",
+        "description": "Copy-paste existing whiteboard elements — the MCP equivalent of selecting a group and pressing Ctrl/Cmd+D. Clones the given elements (plus their group peers + bound text/labels) with FRESH ids, offsets the copy by dx/dy, and by default groups it into ONE new unit so it moves together. Use it to build something once (a labelled stencil frame, a kanban card, a UML class) then stamp out consistent repeats fast — then retext/recolour each copy by its new id (via the returned idMap) with updateWhiteboardScene. Pass `groupId` to copy a whole group as a unit (e.g. a placed stencil's groupId from its placement result) and/or `ids` for specific elements. Internal references (group membership, bound text containerId, arrow start/end bindings) are remapped within the copied set; a binding to an element you did NOT copy is dropped. Returns { duplicated, idMap (old id → new id), groupId (the copy's new unit group), elementCount }. Render with getWhiteboardImage afterwards to verify.",
+        "operationId": "duplicateWhiteboardElements",
+        "tags": [
+          "uncategorized"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "documentId": {
+                    "type": "string",
+                    "description": "The whiteboard's documentId."
+                  },
+                  "ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Element ids to copy. Each id's full group + any bound text are auto-included. Use this and/or groupId."
+                  },
+                  "groupId": {
+                    "type": "string",
+                    "description": "Copy EVERY element in this group as one unit — e.g. a placed stencil's `groupId` returned by addWhiteboardElements."
+                  },
+                  "dx": {
+                    "type": "number",
+                    "description": "Horizontal offset for the copy (default 40). Use the element width + a gap to place copies side by side."
+                  },
+                  "dy": {
+                    "type": "number",
+                    "description": "Vertical offset for the copy (default 40)."
+                  },
+                  "group": {
+                    "type": "boolean",
+                    "description": "Group the copy into one new unit so it moves/duplicates together (default true)."
+                  },
+                  "includeGroupPeers": {
+                    "type": "boolean",
+                    "description": "Auto-include the full group of any id you pass (default true)."
+                  }
+                },
+                "required": [
+                  "documentId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/insertWhiteboardImage": {
+      "post": {
+        "summary": "insertWhiteboardImage",
+        "description": "Insert a real IMAGE (photo, screenshot, logo, picture) into a whiteboard — the storage-backed equivalent of insertImageInDocument. Provide the image as imageUrl (fetched and re-hosted), imageBase64, or imageBinary; for large files call createImageUploadSession(documentId) first then pass the returned assetUrl as imageUrl. The bytes are stored in the document-images bucket and the scene only holds a reference (never base64), exactly like pasted images. Options: caption (a text label placed + grouped beneath the image), width/height in px to RESIZE (if only one is given the other follows a 4:3 ratio; ~360px wide if neither), and placement via x/y (top-left) OR align ('left'|'center'|'right', positioned just below existing content) — omit both to auto-place to the right of the current content. After inserting, call getWhiteboardImage to verify. To move or resize the image later, patch its element via updateWhiteboardScene (mode:'patch' with {id, x, y, width, height}). For curated software-architecture ICONS (AWS/Docker/etc.) use addWhiteboardElements with an {type:'image', iconPath} spec instead.",
+        "operationId": "insertWhiteboardImage",
+        "tags": [
+          "whiteboards"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "documentId": {
+                    "type": "string",
+                    "description": "The whiteboard's documentId."
+                  },
+                  "imageUrl": {
+                    "type": "string",
+                    "description": "URL to fetch the image from, or an assetUrl returned by createImageUploadSession."
+                  },
+                  "imageBase64": {
+                    "type": "string",
+                    "description": "Base64-encoded image bytes (a data: URL prefix is allowed). Best for small images."
+                  },
+                  "imageBinary": {
+                    "type": "array",
+                    "items": {
+                      "type": "number"
+                    },
+                    "description": "Raw image bytes as an array of 0-255 values (alternative to imageBase64)."
+                  },
+                  "caption": {
+                    "type": "string",
+                    "description": "Optional caption shown as a text label grouped beneath the image."
+                  },
+                  "width": {
+                    "type": "number",
+                    "description": "Display width in px (resize). Defaults to ~360."
+                  },
+                  "height": {
+                    "type": "number",
+                    "description": "Display height in px. Derived from width at 4:3 if omitted."
+                  },
+                  "x": {
+                    "type": "number",
+                    "description": "Top-left x on the canvas. Omit to auto-place."
+                  },
+                  "y": {
+                    "type": "number",
+                    "description": "Top-left y on the canvas. Omit to auto-place."
+                  },
+                  "align": {
+                    "type": "string",
+                    "enum": [
+                      "left",
+                      "center",
+                      "right"
+                    ],
+                    "description": "Horizontal alignment relative to existing content (placed below it). Ignored if x/y are provided."
+                  },
+                  "fileName": {
+                    "type": "string",
+                    "description": "Optional original filename (for storage + type hinting)."
+                  }
+                },
+                "required": [
+                  "documentId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/insertWhiteboardDiagram": {
+      "post": {
+        "summary": "insertWhiteboardDiagram",
+        "description": "Insert a real DIAGRAM (BPMN, Diagrams-as-Code / any DSL: mermaid, d2, plantuml, graphviz, …) into a whiteboard as an editable SB diagram element. Provide documentId, diagramType (call listDiagramTypes / getDiagramTypeGuide), and source (the DSL). The diagram is rendered to an image stored like a pasted image, and its editable source is kept in a sidecar so it stays a live, re-openable diagram on the board (double-click on the canvas opens the BPMN / code / AI editor). Options: caption (label beneath it), width/height to size it, and x/y or align ('left'|'center'|'right') to place it (defaults to the right of existing content). After inserting, call getWhiteboardImage to see it and verify it rendered correctly (fix the source and re-insert if it is wrong). For a plain picture (not a diagram) use insertWhiteboardImage; to generate a diagram image WITHOUT inserting use renderDiagram.",
+        "operationId": "insertWhiteboardDiagram",
+        "tags": [
+          "whiteboards"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "documentId": {
+                    "type": "string",
+                    "description": "The whiteboard's documentId."
+                  },
+                  "diagramType": {
+                    "type": "string",
+                    "description": "Diagram language, e.g. 'bpmn', 'mermaid', 'd2', 'plantuml', 'graphviz'. See listDiagramTypes."
+                  },
+                  "source": {
+                    "type": "string",
+                    "description": "The diagram DSL / code."
+                  },
+                  "caption": {
+                    "type": "string",
+                    "description": "Optional caption shown beneath the diagram."
+                  },
+                  "width": {
+                    "type": "number",
+                    "description": "Display width in px (aspect ratio preserved). Defaults to a capped natural size."
+                  },
+                  "height": {
+                    "type": "number",
+                    "description": "Display height in px (defaults from width + aspect)."
+                  },
+                  "x": {
+                    "type": "number",
+                    "description": "Top-left x on the canvas. Omit to auto-place."
+                  },
+                  "y": {
+                    "type": "number",
+                    "description": "Top-left y on the canvas. Omit to auto-place."
+                  },
+                  "align": {
+                    "type": "string",
+                    "enum": [
+                      "left",
+                      "center",
+                      "right"
+                    ],
+                    "description": "Horizontal alignment relative to existing content (placed below it). Ignored if x/y given."
+                  }
+                },
+                "required": [
+                  "documentId",
+                  "diagramType",
+                  "source"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/listWhiteboardStencils": {
+      "post": {
+        "summary": "listWhiteboardStencils",
+        "description": "Search the built-in library of structural whiteboard stencils — ready-made hand-drawn graphics: flowchart/UML/ER/BPMN symbols, scrum columns, org-chart nodes, gantt, lo-fi/UX wireframe widgets (buttons, forms, tables, alerts, navs), charts, device frames, stick figures. A stencil is a MINI-WHITEBOARD (a collection of elements), NOT a single shape. Each result returns: `key`, `title` (a real human name e.g. 'Alerts', not an index), `kind` ('symbol' | 'template'), `labels` (the TEXT it actually contains — its real content, e.g. an Alerts template's variant messages), `size` ({w,h} px), `summary`, `pack`, `category`; plus the full pack/category lists. The two kinds are used DIFFERENTLY: • SYMBOL = one atomic labelled node (flowchart Process/Decision, BPMN task, org node). Place + label + connect: addWhiteboardElements({type:'stencil', stencilKey, id:'n1', text:'Review', width, height}) — the text auto-fits its single slot and an arrow's start/end {id:'n1'} binds to it like any shape. A few symbols are text-less FRAMES (e.g. a UML class box = rectangle + divider line): place create-only, then use the placement result's `children` (shapes + x/y/w/h) and `groupId` to add type:'text' specs INTO the regions — pass that groupId so the text is one unit with the frame. • TEMPLATE = a multi-component layout (Alerts, Forms, Tables, Charts, device frames). Place the WHOLE thing: addWhiteboardElements({type:'stencil', stencilKey, x, y, width?, height?}); the placement RESULT returns `stencils[].children` (each child's id + text + colour + position x/y/w/h, so you can group children into rows/sections) so you then keep / retext / recolour / DELETE specific parts via updateWhiteboardScene (e.g. delete the info + error rows to keep only the green success alert). Do NOT pass a single `text` to a template — read its `labels` to see its parts, then edit them by id. To make several similar items, build one then duplicateWhiteboardElements({groupId, dx}) to stamp consistent copies (like copy-paste in the UI). SEARCH TIPS: prefer BROAD single words ('decision','alert','form','phone','process'); content words match the embedded `labels` too (searching 'success' finds the Alerts template). If nothing exact matches, results auto-broaden (broadened:true); pass pack/category to browse. For cloud/architecture ICONS (AWS/Azure/GCP/Docker/Kubernetes/databases) use listArchitectureIcons; for a sticky/post-it use addWhiteboardElements({type:'sticky'}), not a stencil.",
+        "operationId": "listWhiteboardStencils",
+        "tags": [
+          "whiteboards"
         ],
         "requestBody": {
           "required": false,
@@ -2596,56 +4794,23 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "documentId": {
-                    "type": "string"
-                  },
-                  "title": {
+                  "query": {
                     "type": "string",
-                    "description": "New title."
+                    "description": "Free-text search across name + pack + category (e.g. 'decision', 'database table', 'phone frame', 'actor', 'kanban column')."
                   },
-                  "folderId": {
+                  "pack": {
                     "type": "string",
-                    "description": "Move to this folder."
-                  },
-                  "versionTimestamp": {
-                    "type": "number",
-                    "description": "Version timestamp from getDocument() for optimistic locking."
+                    "description": "Restrict to one pack, e.g. 'Flowchart', 'BPMN', 'UML & ER', 'Scrum Board', 'Lo-Fi Wireframes', 'Org Chart'."
                   },
-                  "changeSummary": {
+                  "category": {
                     "type": "string",
-                    "description": "Version history summary."
+                    "description": "Filter by category: 'Notes & Planning', 'Diagramming', 'UI & Wireframing', 'Data & Charts', 'People & Fun'."
                   },
-                  "patches": {
-                    "type": "array",
-                    "description": "Line-based patches. Can be empty if only updating title or folderId.",
-                    "items": {
-                      "type": "object",
-                      "properties": {
-                        "startLine": {
-                          "type": "number",
-                          "description": "1-based start line."
-                        },
-                        "endLine": {
-                          "type": "number",
-                          "description": "1-based end line (inclusive)."
-                        },
-                        "replacement": {
-                          "type": "string",
-                          "description": "Replacement text. Empty string to delete lines."
-                        }
-                      },
-                      "required": [
-                        "startLine",
-                        "endLine",
-                        "replacement"
-                      ]
-                    }
+                  "limit": {
+                    "type": "number",
+                    "description": "Max results (default 60, max 200)."
                   }
-                },
-                "required": [
-                  "documentId",
-                  "versionTimestamp"
-                ]
+                }
               }
             }
           }
@@ -2725,13 +4890,13 @@
         }
       }
     },
-    "/tools/findAndReplaceTextInDocument": {
+    "/tools/getWhiteboardImage": {
       "post": {
-        "summary": "findAndReplaceTextInDocument",
-        "description": "Find and replace text in a document. Searches for all occurrences and replaces them. Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected.",
-        "operationId": "findAndReplaceTextInDocument",
+        "summary": "getWhiteboardImage",
+        "description": "Render a whiteboard to an IMAGE so you can SEE it and confirm your edits look right, then iterate — like taking a screenshot. Returns the rendered board as a viewable PNG (default) attached to the result. Pass elementIds to render only specific shapes (e.g. to inspect one section/slide), format:'svg' for vector markup instead of a raster, or background to set the canvas colour. Call this after addWhiteboardElements/updateWhiteboardScene to check layout, overlaps, labels and alignment before continuing.",
+        "operationId": "getWhiteboardImage",
         "tags": [
-          "documents"
+          "whiteboards"
         ],
         "requestBody": {
           "required": false,
@@ -2741,29 +4906,31 @@
                 "type": "object",
                 "properties": {
                   "documentId": {
-                    "type": "string"
-                  },
-                  "find": {
                     "type": "string",
-                    "description": "Text to search for."
+                    "description": "The whiteboard's documentId."
                   },
-                  "replace": {
+                  "format": {
                     "type": "string",
-                    "description": "Replacement text. Empty string to delete occurrences."
+                    "enum": [
+                      "png",
+                      "svg"
+                    ],
+                    "description": "png (default — a viewable raster) or svg (vector markup)."
                   },
-                  "caseSensitive": {
-                    "type": "boolean",
-                    "description": "Case-sensitive matching. Default: true."
+                  "elementIds": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Render only these element ids (plus their bound labels + group peers) instead of the whole board."
                   },
-                  "changeSummary": {
+                  "background": {
                     "type": "string",
-                    "description": "Version history summary."
+                    "description": "Canvas background colour (default white), e.g. '#ffffff' or 'transparent'."
                   }
                 },
                 "required": [
-                  "documentId",
-                  "find",
-                  "replace"
+                  "documentId"
                 ]
               }
             }
@@ -2844,13 +5011,13 @@
         }
       }
     },
-    "/tools/getDiagramInDocument": {
+    "/tools/deleteWhiteboard": {
       "post": {
-        "summary": "getDiagramInDocument",
-        "description": "Get a diagram's full details including raw DSL source code. Use diagramId from DIAGRAM_OMITTED markers in getDocument output. Returns diagramCode, type, name, nlDescription, and versionTimestamp.",
-        "operationId": "getDiagramInDocument",
+        "summary": "deleteWhiteboard",
+        "description": "Delete a whiteboard (the host document and its canvas).",
+        "operationId": "deleteWhiteboard",
         "tags": [
-          "diagrams"
+          "whiteboards"
         ],
         "requestBody": {
           "required": false,
@@ -2859,20 +5026,12 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "diagramId": {
-                    "type": "string",
-                    "description": "Diagram ID from DIAGRAM_OMITTED markers."
-                  },
-                  "fields": {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    },
-                    "description": "Field projection. Valid fields: diagramId, documentId, type, name, diagramCode, nlDescription, colorPlan, renderStatus, renderError, createdAt, updatedAt, versionTimestamp."
+                  "documentId": {
+                    "type": "string"
                   }
                 },
                 "required": [
-                  "diagramId"
+                  "documentId"
                 ]
               }
             }
@@ -2953,11 +5112,11 @@
         }
       }
     },
-    "/tools/insertDiagramInDocument": {
+    "/tools/renderDiagram": {
       "post": {
-        "summary": "insertDiagramInDocument",
-        "description": "Insert a new diagram into a document. Call listDiagramTypes to find your type, then getDiagramTypeGuide for DSL syntax before writing diagramCode.",
-        "operationId": "insertDiagramInDocument",
+        "summary": "renderDiagram",
+        "description": "Generate a diagram from its DSL/code and get the IMAGE back — WITHOUT inserting it into any document or whiteboard. For acting as a pure diagram generator. Provide diagramType (e.g. 'mermaid', 'd2', 'plantuml', 'graphviz', 'bpmn', 'vegalite'; call listDiagramTypes for the full set) and source (the diagram code). Choose format 'png' (default), 'jpeg', or 'svg'; for raster choose scale 1/2/3 for 1x/2x/3x; optional background (png only). Returns a TEMPORARY signed imageUrl that expires in 1 hour (then auto-deleted), and for png/jpeg the image inline so you can see it. To render a diagram that already lives in a document/whiteboard use getDiagramImage; to persist a new one use insertDiagramInDocument or insertWhiteboardDiagram.",
+        "operationId": "renderDiagram",
         "tags": [
           "diagrams"
         ],
@@ -2968,73 +5127,40 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "documentId": {
-                    "type": "string"
-                  },
-                  "documentVersionTimestamp": {
-                    "type": "number",
-                    "description": "Version timestamp from getDocument() for optimistic locking."
-                  },
-                  "type": {
-                    "type": "string",
-                    "description": "Diagram type (e.g. mermaid, plantuml, bpmn, d2). Call listDiagramTypes for all types."
-                  },
-                  "diagramCode": {
-                    "type": "string",
-                    "description": "Diagram DSL code. Call getDiagramTypeGuide for syntax."
-                  },
-                  "prompt": {
+                  "diagramType": {
                     "type": "string",
-                    "description": "Short description of what the diagram shows (1-2 sentences)."
+                    "description": "Diagram language, e.g. 'mermaid', 'd2', 'plantuml', 'graphviz', 'bpmn', 'vegalite'. See listDiagramTypes."
                   },
-                  "nlDescription": {
+                  "source": {
                     "type": "string",
-                    "description": "Extended description of the diagram (2-4 sentences)."
+                    "description": "The diagram DSL / code to render."
                   },
-                  "align": {
+                  "format": {
                     "type": "string",
-                    "description": "Alignment.",
                     "enum": [
-                      "left",
-                      "center",
-                      "right"
-                    ]
-                  },
-                  "caption": {
-                    "type": "string",
-                    "description": "Caption below the diagram."
+                      "png",
+                      "jpeg",
+                      "svg"
+                    ],
+                    "description": "png (default) or jpeg = raster; svg = vector."
                   },
-                  "afterLine": {
+                  "scale": {
                     "type": "number",
-                    "description": "Insert after this line number (1-based)."
+                    "enum": [
+                      1,
+                      2,
+                      3
+                    ],
+                    "description": "Raster resolution multiplier 1x/2x/3x (default 2). Ignored for svg."
                   },
-                  "colorPlan": {
-                    "type": "object",
-                    "description": "BPMN only. Color plan: { byElementId: { ElementId: SwatchName } }.",
-                    "properties": {
-                      "byElementId": {
-                        "type": "object",
-                        "description": "Map of element IDs to color swatch names.",
-                        "additionalProperties": {
-                          "type": "string"
-                        }
-                      }
-                    },
-                    "required": [
-                      "byElementId"
-                    ]
+                  "background": {
+                    "type": "string",
+                    "description": "Background for png/jpeg, e.g. '#ffffff' or 'transparent' (png only)."
                   }
                 },
                 "required": [
-                  "documentId",
-                  "documentVersionTimestamp",
-                  "type",
-                  "diagramCode",
-                  "prompt",
-                  "nlDescription",
-                  "align",
-                  "caption",
-                  "afterLine"
+                  "diagramType",
+                  "source"
                 ]
               }
             }
@@ -3115,11 +5241,11 @@
         }
       }
     },
-    "/tools/updateDiagramInDocument": {
+    "/tools/getDiagramImage": {
       "post": {
-        "summary": "updateDiagramInDocument",
-        "description": "Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Requires documentVersionTimestamp from getDocument. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram.",
-        "operationId": "updateDiagramInDocument",
+        "summary": "getDiagramImage",
+        "description": "Render a diagram that ALREADY exists in a document to an IMAGE (svg/png/jpeg @1x/2x/3x) and return it — a temporary signed URL (expires in 1 hour) plus, for png/jpeg, the image inline so you can see it. Pass the diagramId (from getDocument's DIAGRAM markers or getDiagramInDocument). Reuses the diagram's cached server render when available (pixel-identical to the editor). Use renderDiagram instead to generate from raw DSL without an existing diagram.",
+        "operationId": "getDiagramImage",
         "tags": [
           "diagrams"
         ],
@@ -3132,57 +5258,33 @@
                 "properties": {
                   "diagramId": {
                     "type": "string",
-                    "description": "Diagram ID from DIAGRAM_OMITTED markers."
-                  },
-                  "diagramCode": {
-                    "type": "string",
-                    "description": "New diagram DSL source code. REQUIRED to change what the diagram visually renders. Call getDiagramTypeGuide for syntax. Must provide the COMPLETE updated DSL, not just the changed parts."
-                  },
-                  "prompt": {
-                    "type": "string",
-                    "description": "New short description (metadata only — does NOT change the rendered diagram)."
+                    "description": "The diagram's id (from getDocument markers / getDiagramInDocument)."
                   },
-                  "nlDescription": {
+                  "format": {
                     "type": "string",
-                    "description": "New extended description (metadata only — does NOT change the rendered diagram)."
+                    "enum": [
+                      "png",
+                      "jpeg",
+                      "svg"
+                    ],
+                    "description": "png (default) or jpeg = raster; svg = vector."
                   },
-                  "align": {
-                    "type": "string",
-                    "description": "Alignment.",
+                  "scale": {
+                    "type": "number",
                     "enum": [
-                      "left",
-                      "center",
-                      "right"
-                    ]
+                      1,
+                      2,
+                      3
+                    ],
+                    "description": "Raster resolution multiplier 1x/2x/3x (default 2). Ignored for svg."
                   },
-                  "caption": {
+                  "background": {
                     "type": "string",
-                    "description": "New caption."
-                  },
-                  "colorPlan": {
-                    "type": "object",
-                    "description": "BPMN only. Updated color plan. Set to null to remove.",
-                    "properties": {
-                      "byElementId": {
-                        "type": "object",
-                        "description": "Map of element IDs to color swatch names.",
-                        "additionalProperties": {
-                          "type": "string"
-                        }
-                      }
-                    },
-                    "required": [
-                      "byElementId"
-                    ]
-                  },
-                  "documentVersionTimestamp": {
-                    "type": "number",
-                    "description": "Version timestamp from getDocument() for optimistic locking."
+                    "description": "Background for png/jpeg, e.g. '#ffffff' or 'transparent' (png only)."
                   }
                 },
                 "required": [
-                  "diagramId",
-                  "documentVersionTimestamp"
+                  "diagramId"
                 ]
               }
             }
@@ -3263,13 +5365,13 @@
         }
       }
     },
-    "/tools/deleteDiagramInDocument": {
+    "/tools/rebuildPlatformCatalogEmbeddings": {
       "post": {
-        "summary": "deleteDiagramInDocument",
-        "description": "Delete a diagram from a document.",
-        "operationId": "deleteDiagramInDocument",
+        "summary": "rebuildPlatformCatalogEmbeddings",
+        "description": "Internal maintenance (requires write). Syncs gte-small (384-dim) vector embeddings for the MCP tool, whiteboard stencil, and architecture icon catalogs into platform_catalog_embeddings, so searchTools, listWhiteboardStencils, and listArchitectureIcons can do semantic search. Incremental: scans every catalog, diffs by content hash, and re-embeds ONLY changed rows (cheap no-op when nothing changed). This normally runs automatically every hour (the platform-catalog-sync cron), so manual calls are rarely needed — use it to force an immediate sync after changing tools/stencils/icons. Embeds up to ~120 changed rows per call; if more changed, call again until allDone is true. Not part of normal authoring flows.",
+        "operationId": "rebuildPlatformCatalogEmbeddings",
         "tags": [
-          "diagrams"
+          "uncategorized"
         ],
         "requestBody": {
           "required": false,
@@ -3278,14 +5380,19 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "diagramId": {
-                    "type": "string",
-                    "description": "Diagram ID from DIAGRAM_OMITTED markers."
+                  "types": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "enum": [
+                        "tool",
+                        "stencil",
+                        "icon"
+                      ]
+                    },
+                    "description": "Which catalogs to sync. Defaults to all three (tool, stencil, icon)."
                   }
-                },
-                "required": [
-                  "diagramId"
-                ]
+                }
               }
             }
           }
@@ -3365,11 +5472,11 @@
         }
       }
     },
-    "/tools/deleteDocument": {
+    "/tools/reorderDocuments": {
       "post": {
-        "summary": "deleteDocument",
-        "description": "Delete a document.",
-        "operationId": "deleteDocument",
+        "summary": "reorderDocuments",
+        "description": "Batch-reorder documents within a folder (or project root) by setting sibling positions. Pass [{documentId, position}, ...] where position is a non-negative integer; usually you renumber siblings sequentially as 0, 1, 2…. Position-only update — does not bump version or create a snapshot. To MOVE a document to a different folder, use editDocument({folderId, position}) instead.",
+        "operationId": "reorderDocuments",
         "tags": [
           "documents"
         ],
@@ -3380,12 +5487,29 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "documentId": {
-                    "type": "string"
+                  "items": {
+                    "type": "array",
+                    "description": "List of document position updates. All documents must belong to the same project.",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "documentId": {
+                          "type": "string"
+                        },
+                        "position": {
+                          "type": "number"
+                        }
+                      },
+                      "required": [
+                        "documentId",
+                        "position"
+                      ]
+                    },
+                    "minItems": 1
                   }
                 },
                 "required": [
-                  "documentId"
+                  "items"
                 ]
               }
             }
@@ -4439,7 +6563,7 @@
         "description": "Step 1 of file ingest. Mint a single-use PUT upload URL for a large file (PDF, DOCX, plain text, or markdown — up to 150 MB). Returns { sessionId, uploadUrl, expiresAt, maxBytes }. Upload the raw bytes to uploadUrl with PUT, then call createDocumentFromUpload({ sessionId, projectId }) to start the conversion. The file is auto-deleted once the document is created.",
         "operationId": "createDocumentIngestSession",
         "tags": [
-          "uncategorized"
+          "documents"
         ],
         "requestBody": {
           "required": false,
@@ -4559,7 +6683,7 @@
         "description": "Step 2 of file ingest. After the file is uploaded via the PUT URL from createDocumentIngestSession, call this to start the async conversion. Returns { jobId, documentId } immediately — the document is created as a draft and progressively populated as the worker processes the file. Poll getDocumentIngestJob({ jobId }) to track progress. Idempotent: calling twice with the same sessionId returns the same job/document.",
         "operationId": "createDocumentFromUpload",
         "tags": [
-          "uncategorized"
+          "documents"
         ],
         "requestBody": {
           "required": false,
@@ -4678,7 +6802,7 @@
         "description": "Read the current status of an ingest job. Returns { status, stage, processedImages, totalImages, documentId, error?, lastHeartbeatAt }. Stages: pending → downloaded → extracted → draft_saved → images_processing → finalized → cleaned_up. Status: queued, running, succeeded, failed, cancelled. The associated document_id is populated immediately and progressively filled in as images are processed.",
         "operationId": "getDocumentIngestJob",
         "tags": [
-          "uncategorized"
+          "documents"
         ],
         "requestBody": {
           "required": false,
@@ -9043,7 +11167,7 @@
         "description": "Update a task. Tasks share a row with improvements (`improvement_items` with `is_task=true`), so this is a thin alias over updateImprovement — every field on updateImprovement is supported, including `checklist`, `acceptance_criteria`, status transitions (blocked/rejected/done need their respective comments), dates, owner, percent_complete, etc. Requires versionTimestamp from getTask for optimistic locking. To edit checklist items: call getTask, modify the `checklist` array (preserving each row's `id` to keep its attribution stamps), and pass the full array back here — array order is the sort order. Assignment: pass `owner_id=<uuid>` to assign to a user, `owner_team_id=<uuid>` to assign to a team (mutually exclusive — the DB enforces with a CHECK constraint). To unassign, pass `owner_id=null` AND `owner_team_id=null`. To switch owner kind, send the new value AND null the old one in the SAME call.",
         "operationId": "updateTask",
         "tags": [
-          "uncategorized"
+          "plans"
         ],
         "requestBody": {
           "required": false,
@@ -10590,7 +12714,7 @@
         "description": "Phase 5 / E3 — Provenance-aware assessor for a set of chunk_ids returned by kg_search. Returns per-chunk bucket (authored-grounded | extracted-high-conf | extracted-low-conf | no-support), overall distribution, dominant_bucket, and recommend_refusal. Pure metadata read - no LLM cost. Used by the agent's response policy to decide whether to answer confidently, caveat, or refuse.",
         "operationId": "kg_evaluate_retrieval",
         "tags": [
-          "uncategorized"
+          "knowledge_graph"
         ],
         "requestBody": {
           "required": false,
@@ -12074,7 +14198,7 @@
     "/tools/getSubscription": {
       "post": {
         "summary": "getSubscription",
-        "description": "Read the subscription state for an organisation. Returns tier, status, current billing period, seat count, member count, cancellation flag, trial end. Stripe IDs are stripped. Pair with listPaymentMethods/listInvoices for the full billing dashboard.",
+        "description": "Read the subscription state for an organisation. Returns tier, status, current billing period, seat count, member count, cancellation flag, trial end. Stripe IDs are stripped. Pair with listPaymentMethods/listInvoices for the full billing dashboard. Use when the user asks 'what plan am I on', 'how many seats do I have', 'when does my subscription renew', or to check current billing status.",
         "operationId": "getSubscription",
         "tags": [
           "billing"
@@ -12801,7 +14925,7 @@
     "/tools/listResourcePermissions": {
       "post": {
         "summary": "listResourcePermissions",
-        "description": "List explicit permission grants on a resource (workspace/project/folder/document/improvement/plan), including principal type (user|team), level (none|read|write|admin), and 3-state overrides for documents/improvements/plans. Read-only.",
+        "description": "List explicit permission grants on a resource (workspace/project/folder/document/improvement/plan), including principal type (user|team), level (none|read|write|admin), and 3-state overrides for documents/improvements/plans. Read-only. Use when the user asks 'who can see this', 'who has access', 'what permissions are set on this', or to audit existing access on a resource.",
         "operationId": "listResourcePermissions",
         "tags": [
           "permissions"
@@ -12916,7 +15040,7 @@
     "/tools/getEffectivePermission": {
       "post": {
         "summary": "getEffectivePermission",
-        "description": "Compute a user's effective permission level on a resource (taking team grants, inheritance, and 3-state overrides into account) and the source. Asking about another user requires can_manage_perms on the org.",
+        "description": "Compute a user's effective permission level on a resource (taking team grants, inheritance, and 3-state overrides into account) and the source. Asking about another user requires can_manage_perms on the org. Use when the user asks 'can X access this', 'what level of access does X have', 'why can X see this', or to debug an unexpected permission outcome.",
         "operationId": "getEffectivePermission",
         "tags": [
           "permissions"
@@ -14125,7 +16249,7 @@
     "/tools/inviteMember": {
       "post": {
         "summary": "inviteMember",
-        "description": "Invite a person by email to the credential's organisation. Auth: org id must match the credential AND credential must hold can_manage_members. Rate limit 10/h. Returns invitation_id, expiry, and a seat-billing-impact summary. Email-existence is opaque: the response shape never reveals whether the email is already a member, already invited, or new.",
+        "description": "Invite a person by email to the credential's organisation. Auth: org id must match the credential AND credential must hold can_manage_members. Rate limit 10/h. Returns invitation_id, expiry, and a seat-billing-impact summary. Email-existence is opaque: the response shape never reveals whether the email is already a member, already invited, or new. Use when the user asks to invite a teammate, friend, colleague, or new user to their organisation, or to onboard someone.",
         "operationId": "inviteMember",
         "tags": [
           "members"
@@ -14247,7 +16371,7 @@
     "/tools/cancelInvitation": {
       "post": {
         "summary": "cancelInvitation",
-        "description": "Cancel a pending invitation by id. Sets status='revoked'. Server resolves the organisation_id from the invitation row; the credential must match that org AND hold can_manage_members. Idempotent. Rate limit 30/min.",
+        "description": "Cancel a pending invitation by id. Sets status='revoked'. Server resolves the organisation_id from the invitation row; the credential must match that org AND hold can_manage_members. Idempotent. Rate limit 30/min. Use when the user asks to cancel, revoke, or undo a pending invitation — for example to correct a typo'd email address before re-inviting.",
         "operationId": "cancelInvitation",
         "tags": [
           "members"
@@ -14349,7 +16473,7 @@
     "/tools/resendInvitation": {
       "post": {
         "summary": "resendInvitation",
-        "description": "Resend a pending invitation: extends expires_at by 7 days and re-triggers the invitation email. Server resolves the organisation_id from the invitation row. Rate limit 6/h per invitation_id.",
+        "description": "Resend a pending invitation: extends expires_at by 7 days and re-triggers the invitation email. Server resolves the organisation_id from the invitation row. Rate limit 6/h per invitation_id. Use when the user asks to resend, re-send, or re-trigger an invitation email — typically because the recipient lost it or the original expired.",
         "operationId": "resendInvitation",
         "tags": [
           "members"
@@ -14451,7 +16575,7 @@
     "/tools/updateMemberRole": {
       "post": {
         "summary": "updateMemberRole",
-        "description": "Update an organisation member's role (admin or member). Owners cannot be changed via this tool. Refuses self-promotion. Rate limit 30/min.",
+        "description": "Update an organisation member's role (admin or member). Owners cannot be changed via this tool. Refuses self-promotion. Rate limit 30/min. Use when the user asks to promote someone to admin, demote an admin to member, or change a teammate's role.",
         "operationId": "updateMemberRole",
         "tags": [
           "members"
@@ -14567,7 +16691,7 @@
     "/tools/setMemberActive": {
       "post": {
         "summary": "setMemberActive",
-        "description": "Soft-deactivate or reactivate an organisation member. Refuses self-deactivation, last-admin/owner deactivation, and deactivation of an owner. Rate limit 30/min.",
+        "description": "Soft-deactivate or reactivate an organisation member. Refuses self-deactivation, last-admin/owner deactivation, and deactivation of an owner. Rate limit 30/min. Use when the user asks to deactivate, suspend, freeze, reactivate, or unfreeze a member without fully removing them.",
         "operationId": "setMemberActive",
         "tags": [
           "members"
@@ -14677,7 +16801,7 @@
     "/tools/removeMember": {
       "post": {
         "summary": "removeMember",
-        "description": "Hard-remove a member from an organisation, cascading to workspace and team memberships and resource permissions. Refuses self-removal and last-owner removal. Stripe seat downgrade is NOT performed here — pair with a Phase 6 billing tool. Rate limit 5/min.",
+        "description": "Hard-remove a member from an organisation, cascading to workspace and team memberships and resource permissions. Refuses self-removal and last-owner removal. Stripe seat downgrade is NOT performed here — pair with a Phase 6 billing tool. Rate limit 5/min. Use when the user asks to remove, kick out, fire, offboard, or fully terminate a member's access to the organisation.",
         "operationId": "removeMember",
         "tags": [
           "members"
@@ -16122,7 +18246,7 @@
     "/tools/upsertResourcePermission": {
       "post": {
         "summary": "upsertResourcePermission",
-        "description": "Insert or update a resource_permissions row for a user OR team on a workspace/project/folder/document/improvement/plan. Refuses self-escalation. Rate limit 30/min.",
+        "description": "Insert or update a resource_permissions row for a user OR team on a workspace/project/folder/document/improvement/plan. Refuses self-escalation. Rate limit 30/min. Use when the user asks to give access to, share with, grant access, add a permission, make accessible, or invite someone to a specific workspace/project/folder/document — i.e. resource-level access (not org-level membership; that's inviteMember).",
         "operationId": "upsertResourcePermission",
         "tags": [
           "permissions"
@@ -16373,7 +18497,7 @@
     "/tools/deleteResourcePermission": {
       "post": {
         "summary": "deleteResourcePermission",
-        "description": "Delete a resource_permissions row. Refuses if the row is the LAST admin grant on the resource. Rate limit 30/min.",
+        "description": "Delete a resource_permissions row. Refuses if the row is the LAST admin grant on the resource. Rate limit 30/min. Use when the user asks to revoke access, remove access, take away access, unshare, or delete a permission grant on a specific resource.",
         "operationId": "deleteResourcePermission",
         "tags": [
           "permissions"
@@ -16604,7 +18728,7 @@
     "/tools/previewSubscriptionChange": {
       "post": {
         "summary": "previewSubscriptionChange",
-        "description": "Preview a subscription tier or seat change. Returns confirmation_token (10-min TTL) plus proration and next-invoice math. Cross-tier upgrades from Free return requires_checkout=true; the apply step creates a hosted Stripe Checkout session. Rate limit 30/h.",
+        "description": "Preview a subscription tier or seat change. Returns confirmation_token (10-min TTL) plus proration and next-invoice math. Cross-tier upgrades from Free return requires_checkout=true; the apply step creates a hosted Stripe Checkout session. Rate limit 30/h. Use when the user asks to upgrade their plan (free→pro), downgrade, add seats, increase seats, or change subscription tier — ALWAYS call this preview first, then applySubscriptionChange with the returned token after the user confirms.",
         "operationId": "previewSubscriptionChange",
         "tags": [
           "billing"
@@ -16719,7 +18843,7 @@
     "/tools/applySubscriptionChange": {
       "post": {
         "summary": "applySubscriptionChange",
-        "description": "Apply a previously previewed subscription change. Same-tier seat changes update Stripe in place; cross-tier upgrades from Free return a hosted Checkout URL. Refuses target=free (use cancelSubscription) and target=enterprise (sales-led). Rate limit 5/h.",
+        "description": "Apply a previously previewed subscription change. Same-tier seat changes update Stripe in place; cross-tier upgrades from Free return a hosted Checkout URL. Refuses target=free (use cancelSubscription) and target=enterprise (sales-led). Rate limit 5/h. Use only AFTER previewSubscriptionChange and after the user confirms the preview's pricing — never call apply without the user seeing the preview first.",
         "operationId": "applySubscriptionChange",
         "tags": [
           "billing"
@@ -16821,7 +18945,7 @@
     "/tools/previewSubscriptionCancellation": {
       "post": {
         "summary": "previewSubscriptionCancellation",
-        "description": "Preview the consequences of cancelling. Returns confirmation_token plus summary {remaining_credits, prepaid_days, prepaid_value_aud, feature_loss[], at_risk_seats}. Soft cancel only. Rate limit 30/h.",
+        "description": "Preview the consequences of cancelling. Returns confirmation_token plus summary {remaining_credits, prepaid_days, prepaid_value_aud, feature_loss[], at_risk_seats}. Soft cancel only. Rate limit 30/h. Use when the user asks to cancel, end, or stop their subscription — ALWAYS call this first to show the cost of cancelling before passing the token to cancelSubscription.",
         "operationId": "previewSubscriptionCancellation",
         "tags": [
           "billing"
@@ -16923,7 +19047,7 @@
     "/tools/cancelSubscription": {
       "post": {
         "summary": "cancelSubscription",
-        "description": "Apply a previewed soft cancellation (cancel_at_period_end=true). Customer keeps full access until period end. Rate limit 5/h.",
+        "description": "Apply a previewed soft cancellation (cancel_at_period_end=true). Customer keeps full access until period end. Rate limit 5/h. Use only AFTER previewSubscriptionCancellation and after the user confirms — never cancel without showing the preview first.",
         "operationId": "cancelSubscription",
         "tags": [
           "billing"
@@ -17025,7 +19149,7 @@
     "/tools/quoteCreditPackage": {
       "post": {
         "summary": "quoteCreditPackage",
-        "description": "Quote a credit-package purchase (first half of the human-in-the-loop ritual). Returns quote_token (10-min TTL) plus package + total_aud. Caller must invoke purchaseCreditPackage(quote_token) within the TTL.",
+        "description": "Quote a credit-package purchase (first half of the human-in-the-loop ritual). Returns quote_token (10-min TTL) plus package + total_aud. Caller must invoke purchaseCreditPackage(quote_token) within the TTL. Use when the user asks to buy credits, purchase credits, top up credits, or add more credits — ALWAYS call this first then purchaseCreditPackage after the user confirms.",
         "operationId": "quoteCreditPackage",
         "tags": [
           "billing"
@@ -17132,7 +19256,7 @@
     "/tools/purchaseCreditPackage": {
       "post": {
         "summary": "purchaseCreditPackage",
-        "description": "Apply a credit-package quote by creating a hosted Stripe Checkout session. Returns checkout_url + session_id. Refuses if catalogued price has drifted. Rate limit 5/h.",
+        "description": "Apply a credit-package quote by creating a hosted Stripe Checkout session. Returns checkout_url + session_id. Refuses if catalogued price has drifted. Rate limit 5/h. Use only AFTER quoteCreditPackage and after the user confirms — never start a checkout without the quote step first.",
         "operationId": "purchaseCreditPackage",
         "tags": [
           "billing"
@@ -17234,7 +19358,7 @@
     "/tools/reactivateSubscription": {
       "post": {
         "summary": "reactivateSubscription",
-        "description": "Reactivate a subscription that was scheduled to cancel at period end (clears cancel_at_period_end). Rate limit 5/h.",
+        "description": "Reactivate a subscription that was scheduled to cancel at period end (clears cancel_at_period_end). Rate limit 5/h. Use when the user asks to reactivate, uncancel, restore, or keep their subscription after they previously cancelled but before the period ends.",
         "operationId": "reactivateSubscription",
         "tags": [
           "billing"