@stablebaseline/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -134,7 +134,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["listAssignablePrincipals"];
         delete?: never;
@@ -323,6 +323,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/tools/reorderFolders": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["reorderFolders"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/tools/listDocuments": {
         parameters: {
             query?: never;
@@ -414,7 +434,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["createDocument"];
         delete?: never;
@@ -434,7 +454,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["editDocument"];
         delete?: never;
@@ -454,7 +474,7 @@ interface paths {
         put?: never;
         /**
          * 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.
+         * @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.
          */
         post: operations["findAndReplaceTextInDocument"];
         delete?: never;
@@ -494,7 +514,7 @@ interface paths {
         put?: never;
         /**
          * insertDiagramInDocument
-         * @description Insert a new diagram into a document. Call listDiagramTypes to find your type, then getDiagramTypeGuide for DSL syntax before writing diagramCode.
+         * @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).
          */
         post: operations["insertDiagramInDocument"];
         delete?: never;
@@ -514,7 +534,7 @@ interface paths {
         put?: never;
         /**
          * 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.
+         * @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.
          */
         post: operations["updateDiagramInDocument"];
         delete?: never;
@@ -563,6 +583,306 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/tools/getWhiteboardGuide": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["getWhiteboardGuide"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/createWhiteboard": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["createWhiteboard"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/listWhiteboards": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * listWhiteboards
+         * @description List the whiteboards in a project (hidden whiteboard-kind documents). Returns documentId, diagramId, title and timestamps for each.
+         */
+        post: operations["listWhiteboards"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/getWhiteboard": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["getWhiteboard"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/updateWhiteboardScene": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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. 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.
+         */
+        post: operations["updateWhiteboardScene"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/addWhiteboardElements": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * addWhiteboardElements
+         * @description Author shapes onto a whiteboard from high-level specs (you do NOT need the full Excalidraw element schema). Appends to the canvas. 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 (sticky notes, 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. yellow sticky note>', pack?:'<pack>', x, y } to fuzzy-match by name). STRONGLY prefer these over plain rectangles whenever the user asks for sticky notes, kanban/scrum/story boards, flowcharts, wireframes/mockups, org charts, etc. 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 solid-fill notes; 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.
+         */
+        post: operations["addWhiteboardElements"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/insertWhiteboardImage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["insertWhiteboardImage"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/insertWhiteboardDiagram": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["insertWhiteboardDiagram"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/listWhiteboardStencils": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * listWhiteboardStencils
+         * @description Search the built-in library of STRUCTURAL whiteboard stencils — ready-made, hand-drawn multi-element graphics: sticky notes (post-it), scrum-board columns, flowchart symbols, UML/ER, BPMN, org-chart nodes, gantt, lo-fi/UX wireframe widgets, charts, and stick figures. Returns matching stencils each with a `key`, name, pack and category, plus the full pack/category lists. Place one via addWhiteboardElements({type:'stencil', stencilKey:'<key>', x, y}). These look far richer and more on-brand than plain rectangles — use them when the user asks for sticky notes, kanban/scrum boards, flowcharts, wireframes, mockups, etc. SEARCH TIPS: prefer BROAD single words ('sticky', 'decision', 'actor', 'phone', 'process') — multi-word exact phrases often miss. If an exact query matches nothing the result is auto-broadened to close candidates (broadened:true is set); you can also pass pack/category to browse. When ANY returned stencil reasonably fits, PLACE it instead of drawing a plain rectangle — do not abandon stencils just because your first phrase returned 0. The library does NOT contain free-form 'cloud' / 'hat' / 'thought-bubble' shapes; approximate those with the closest stencil (e.g. a sticky note or a simple shape) or fall back to a plain shape only when nothing fits. For cloud/architecture ICONS (AWS/Azure/GCP/Docker/Kubernetes/databases) use listArchitectureIcons instead.
+         */
+        post: operations["listWhiteboardStencils"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/getWhiteboardImage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["getWhiteboardImage"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/deleteWhiteboard": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * deleteWhiteboard
+         * @description Delete a whiteboard (the host document and its canvas).
+         */
+        post: operations["deleteWhiteboard"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/renderDiagram": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["renderDiagram"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/getDiagramImage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["getDiagramImage"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/rebuildPlatformCatalogEmbeddings": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["rebuildPlatformCatalogEmbeddings"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tools/reorderDocuments": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["reorderDocuments"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/tools/listDocumentVersions": {
         parameters: {
             query?: never;
@@ -1971,7 +2291,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["getSubscription"];
         delete?: never;
@@ -2111,7 +2431,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["listResourcePermissions"];
         delete?: never;
@@ -2131,7 +2451,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["getEffectivePermission"];
         delete?: never;
@@ -2351,7 +2671,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["inviteMember"];
         delete?: never;
@@ -2371,7 +2691,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["cancelInvitation"];
         delete?: never;
@@ -2391,7 +2711,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["resendInvitation"];
         delete?: never;
@@ -2411,7 +2731,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["updateMemberRole"];
         delete?: never;
@@ -2431,7 +2751,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["setMemberActive"];
         delete?: never;
@@ -2451,7 +2771,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["removeMember"];
         delete?: never;
@@ -2711,7 +3031,7 @@ interface paths {
         put?: never;
         /**
          * 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).
          */
         post: operations["upsertResourcePermission"];
         delete?: never;
@@ -2751,7 +3071,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["deleteResourcePermission"];
         delete?: never;
@@ -2791,7 +3111,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["previewSubscriptionChange"];
         delete?: never;
@@ -2811,7 +3131,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["applySubscriptionChange"];
         delete?: never;
@@ -2831,7 +3151,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["previewSubscriptionCancellation"];
         delete?: never;
@@ -2851,7 +3171,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["cancelSubscription"];
         delete?: never;
@@ -2871,7 +3191,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["quoteCreditPackage"];
         delete?: never;
@@ -2891,7 +3211,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["purchaseCreditPackage"];
         delete?: never;
@@ -2911,7 +3231,7 @@ interface paths {
         put?: never;
         /**
          * 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.
          */
         post: operations["reactivateSubscription"];
         delete?: never;
@@ -4704,6 +5024,92 @@ interface operations {
             };
         };
     };
+    reorderFolders: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description List of folder position updates. All folders must belong to the same project. */
+                    items: {
+                        folderId: string;
+                        position: number;
+                    }[];
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     listDocuments: {
         parameters: {
             query?: never;
@@ -5096,6 +5502,8 @@ interface operations {
                     folderId?: string;
                     title?: string;
                     cdmd: string;
+                    /** @description Sort position within the parent folder (or project root if no folderId). When omitted, the document is appended at the end. */
+                    position?: number;
                     /** @description Version history summary. */
                     changeSummary?: string;
                 };
@@ -5184,11 +5592,13 @@ interface operations {
                     title?: string;
                     /** @description Move to this folder. */
                     folderId?: string;
+                    /** @description Sort position within the parent folder. Use to reposition a single document. For batch sibling reorder, use reorderDocuments. */
+                    position?: number;
                     /** @description Version timestamp from getDocument() for optimistic locking. */
                     versionTimestamp: number;
                     /** @description Version history summary. */
                     changeSummary?: string;
-                    /** @description Line-based patches. Can be empty if only updating title or folderId. */
+                    /** @description Line-based patches. Can be empty if only updating title, folderId, or position. */
                     patches?: {
                         /** @description 1-based start line. */
                         startLine: number;
@@ -5480,6 +5890,20 @@ interface operations {
                             [key: string]: string;
                         };
                     };
+                    /** @description If true, also render the inserted diagram and return it as an image inline (one-call insert-and-get-image). Defaults false. */
+                    returnImage?: boolean;
+                    /**
+                     * @description Image format when returnImage:true (default png).
+                     * @enum {string}
+                     */
+                    imageFormat?: "png" | "jpeg" | "svg";
+                    /**
+                     * @description Raster resolution 1x/2x/3x when returnImage:true (default 2).
+                     * @enum {number}
+                     */
+                    imageScale?: 1 | 2 | 3;
+                    /** @description Background for the returned png/jpeg (e.g. '#ffffff' or 'transparent'). */
+                    imageBackground?: string;
                 };
             };
         };
@@ -5821,6 +6245,1349 @@ interface operations {
             };
         };
     };
+    getWhiteboardGuide: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": Record<string, never>;
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    createWhiteboard: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    projectId: string;
+                    /** @description Whiteboard title. Defaults to 'Untitled whiteboard'. */
+                    title?: string;
+                    /** @description Optional folder to file the whiteboard under. */
+                    folderId?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    listWhiteboards: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    projectId: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    getWhiteboard: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    documentId: string;
+                    /** @description When true, returns the full Excalidraw scene so it can be modified and written back. */
+                    includeElements?: boolean;
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    updateWhiteboardScene: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    documentId: string;
+                    /** @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'). */
+                    elements?: Record<string, never>[];
+                    /**
+                     * @description patch (DEFAULT — merge by id, keep the rest), append (add only), or replace (overwrite the whole scene).
+                     * @enum {string}
+                     */
+                    mode?: "patch" | "append" | "replace";
+                    /** @description Element ids to remove from the scene. */
+                    deleteIds?: string[];
+                    /** @description Optional Excalidraw appState fields to merge (e.g. viewBackgroundColor). */
+                    appState?: Record<string, never>;
+                    /** @description Optional Excalidraw BinaryFiles map (for embedded images), merged in. */
+                    files?: Record<string, never>;
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    addWhiteboardElements: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    documentId: string;
+                    /** @description Non-empty array of shape specs to append. */
+                    shapes: Record<string, never>[];
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    insertWhiteboardImage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description The whiteboard's documentId. */
+                    documentId: string;
+                    /** @description URL to fetch the image from, or an assetUrl returned by createImageUploadSession. */
+                    imageUrl?: string;
+                    /** @description Base64-encoded image bytes (a data: URL prefix is allowed). Best for small images. */
+                    imageBase64?: string;
+                    /** @description Raw image bytes as an array of 0-255 values (alternative to imageBase64). */
+                    imageBinary?: number[];
+                    /** @description Optional caption shown as a text label grouped beneath the image. */
+                    caption?: string;
+                    /** @description Display width in px (resize). Defaults to ~360. */
+                    width?: number;
+                    /** @description Display height in px. Derived from width at 4:3 if omitted. */
+                    height?: number;
+                    /** @description Top-left x on the canvas. Omit to auto-place. */
+                    x?: number;
+                    /** @description Top-left y on the canvas. Omit to auto-place. */
+                    y?: number;
+                    /**
+                     * @description Horizontal alignment relative to existing content (placed below it). Ignored if x/y are provided.
+                     * @enum {string}
+                     */
+                    align?: "left" | "center" | "right";
+                    /** @description Optional original filename (for storage + type hinting). */
+                    fileName?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    insertWhiteboardDiagram: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description The whiteboard's documentId. */
+                    documentId: string;
+                    /** @description Diagram language, e.g. 'bpmn', 'mermaid', 'd2', 'plantuml', 'graphviz'. See listDiagramTypes. */
+                    diagramType: string;
+                    /** @description The diagram DSL / code. */
+                    source: string;
+                    /** @description Optional caption shown beneath the diagram. */
+                    caption?: string;
+                    /** @description Display width in px (aspect ratio preserved). Defaults to a capped natural size. */
+                    width?: number;
+                    /** @description Display height in px (defaults from width + aspect). */
+                    height?: number;
+                    /** @description Top-left x on the canvas. Omit to auto-place. */
+                    x?: number;
+                    /** @description Top-left y on the canvas. Omit to auto-place. */
+                    y?: number;
+                    /**
+                     * @description Horizontal alignment relative to existing content (placed below it). Ignored if x/y given.
+                     * @enum {string}
+                     */
+                    align?: "left" | "center" | "right";
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    listWhiteboardStencils: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description Free-text search across name + pack + category (e.g. 'sticky note', 'decision', 'database table', 'phone frame', 'actor'). */
+                    query?: string;
+                    /** @description Restrict to one pack, e.g. 'Sticky Notes', 'Flowchart', 'BPMN', 'UML & ER', 'Scrum Board', 'Lo-Fi Wireframes', 'Org Chart'. */
+                    pack?: string;
+                    /** @description Filter by category: 'Notes & Planning', 'Diagramming', 'UI & Wireframing', 'Data & Charts', 'People & Fun'. */
+                    category?: string;
+                    /** @description Max results (default 60, max 200). */
+                    limit?: number;
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    getWhiteboardImage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description The whiteboard's documentId. */
+                    documentId: string;
+                    /**
+                     * @description png (default — a viewable raster) or svg (vector markup).
+                     * @enum {string}
+                     */
+                    format?: "png" | "svg";
+                    /** @description Render only these element ids (plus their bound labels + group peers) instead of the whole board. */
+                    elementIds?: string[];
+                    /** @description Canvas background colour (default white), e.g. '#ffffff' or 'transparent'. */
+                    background?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    deleteWhiteboard: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    documentId: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    renderDiagram: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description Diagram language, e.g. 'mermaid', 'd2', 'plantuml', 'graphviz', 'bpmn', 'vegalite'. See listDiagramTypes. */
+                    diagramType: string;
+                    /** @description The diagram DSL / code to render. */
+                    source: string;
+                    /**
+                     * @description png (default) or jpeg = raster; svg = vector.
+                     * @enum {string}
+                     */
+                    format?: "png" | "jpeg" | "svg";
+                    /**
+                     * @description Raster resolution multiplier 1x/2x/3x (default 2). Ignored for svg.
+                     * @enum {number}
+                     */
+                    scale?: 1 | 2 | 3;
+                    /** @description Background for png/jpeg, e.g. '#ffffff' or 'transparent' (png only). */
+                    background?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    getDiagramImage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description The diagram's id (from getDocument markers / getDiagramInDocument). */
+                    diagramId: string;
+                    /**
+                     * @description png (default) or jpeg = raster; svg = vector.
+                     * @enum {string}
+                     */
+                    format?: "png" | "jpeg" | "svg";
+                    /**
+                     * @description Raster resolution multiplier 1x/2x/3x (default 2). Ignored for svg.
+                     * @enum {number}
+                     */
+                    scale?: 1 | 2 | 3;
+                    /** @description Background for png/jpeg, e.g. '#ffffff' or 'transparent' (png only). */
+                    background?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    rebuildPlatformCatalogEmbeddings: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description Which catalogs to sync. Defaults to all three (tool, stencil, icon). */
+                    types?: ("tool" | "stencil" | "icon")[];
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    reorderDocuments: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description List of document position updates. All documents must belong to the same project. */
+                    items: {
+                        documentId: string;
+                        position: number;
+                    }[];
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     listDocumentVersions: {
         parameters: {
             query?: never;