@stablebaseline/sdk 0.4.2 → 0.4.3

package/openapi.json

@@ -2184,7 +2184,7 @@
     "/tools/listDocuments": {
       "post": {
         "summary": "listDocuments",
-        "description": "List documents in a project, workspace, or folder. Supports query search and date filtering.",
+        "description": "List AND grep documents in a project, workspace, or folder. `query` does a full-content search across each document's body (not just the title) and returns the matching lines — like grep across your docs. Each returned document includes `contentMatches: [{line, text, context?}]` and `matchCount`; the `text` is anchor-ready (paste it straight into editDocument's oldText). Use isRegex:true for regular-expression search (e.g. \"TODO\\(.*\\)\", \"ACME-\\d+\"), caseSensitive for exact case, and contextLines for surrounding lines (grep -C). versionTimestamp is returned per document so you can edit straight from the results without a getDocument round-trip. Also supports date filtering.",
         "operationId": "listDocuments",
         "tags": [
           "documents"
@@ -2206,7 +2206,24 @@
                     "type": "string"
                   },
                   "query": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "Search text. Matched against title, friendlyId AND full document content. Returns the matching lines per document (grep). Case-insensitive unless caseSensitive:true; treated as a regex if isRegex:true."
+                  },
+                  "isRegex": {
+                    "type": "boolean",
+                    "description": "Treat `query` as a JavaScript regular expression (grep -E). Default false (literal substring). Regex search requires a project/workspace/folder scope and scans a bounded window of documents."
+                  },
+                  "caseSensitive": {
+                    "type": "boolean",
+                    "description": "Case-sensitive matching. Default false."
+                  },
+                  "contextLines": {
+                    "type": "number",
+                    "description": "Lines of surrounding context to include with each match (grep -C). 0-5, default 0."
+                  },
+                  "maxMatchesPerDocument": {
+                    "type": "number",
+                    "description": "Cap on matching lines returned per document. 1-20, default 5."
                   },
                   "limit": {
                     "type": "number"
@@ -2231,7 +2248,7 @@
                     "items": {
                       "type": "string"
                     },
-                    "description": "Field projection. Valid fields: id, title, friendlyId, friendlyIdNumber, projectId, folderId, createdAt, updatedAt, href."
+                    "description": "Field projection for the document metadata. Valid fields: id, title, friendlyId, friendlyIdNumber, projectId, folderId, createdAt, updatedAt, href. (contentMatches/matchCount are always included when query is set.)"
                   }
                 }
               }
@@ -2816,7 +2833,7 @@
     "/tools/editDocument": {
       "post": {
         "summary": "editDocument",
-        "description": "Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, add `before`/`after` (short nearby surrounding text) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:\"\" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument is required for optimistic locking, EXCEPT when dryRun:true. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.",
+        "description": "Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, either expand oldText until it is unique, or add `before`/`after` (the EXACT text immediately before/after the match) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:\"\" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument is required for optimistic locking, EXCEPT when dryRun:true. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.",
         "operationId": "editDocument",
         "tags": [
           "documents"
@@ -3862,7 +3879,7 @@
     "/tools/designWhiteboard": {
       "post": {
         "summary": "designWhiteboard",
-        "description": "Design a complete, visually polished whiteboard from a natural-language goal using the PREMIUM multi-agent pipeline (the same one the in-app assistant uses): it browses the stencil/icon library, composes the board, renders it, critiques the rendered image, and refines — far better than hand-placing shapes. COST + APPROVAL: this costs 50 credits per board and requires the user's explicit approval. Call it FIRST without `confirm` to get the exact cost + the workspace credit balance; show that to the user and only call again with `confirm: true` once they agree. If they decline (or lack credits), build the board directly with the standard whiteboard tools (addWhiteboardElements / insertWhiteboardDiagram / listWhiteboardStencils) at no extra charge. It runs in the BACKGROUND and returns immediately with a sessionId; the board fills in over 1-3 minutes. The 50 credits are refunded automatically if the design fails on our side.",
+        "description": "Design a complete, visually polished whiteboard from a natural-language goal using the PREMIUM multi-agent pipeline (the same one the in-app assistant uses): it browses the stencil/icon library, composes the board, renders it, critiques the rendered image, and refines — far better than hand-placing shapes. COST + APPROVAL: this costs 50 credits per board and requires the user's explicit approval. Call it FIRST without `confirm` to get the exact cost + the workspace credit balance; show that to the user and only call again with `confirm: true` once they agree. If they decline (or lack credits), build the board directly with the standard whiteboard tools (addWhiteboardElements / insertWhiteboardDiagram / listWhiteboardStencils) at no extra charge. It runs in the BACKGROUND and returns immediately with a sessionId; the board fills in over 1-3 minutes. The 50 credits are refunded automatically if the design fails on our side. Optional `designProfile: 'branded-executive'` instead builds an ON-BRAND, fully-editable McKinsey-style SLIDE DECK themed by the org's brand kit (palette/fonts) — use it when the user wants polished branded business slides; it builds in-process and the board is ready on return. Optional `designProfile: 'illustrated'` instead builds an editable-illustration board: pick it for illustrated, image-based, picture-style, richly-drawn or educational explainer boards (e.g. illustrate photosynthesis, an illustrated diagram of the water cycle, a textbook-style visual). It generates a rich text-free vector illustration and overlays real, editable text labels with leader lines on top. It is gated per organisation; if it is not enabled the call returns a clear message, so fall back to the standard design. Optional `designProfile: 'image'` instead builds a single, polished, on-brand IMAGE board with all the text baked into the picture (no editable shapes): pick 'image' when the user wants a single finished image, poster or infographic they will refine by AI mask edits rather than by moving editable shapes. It is also gated per organisation; if it is not enabled the call returns a clear message.",
         "operationId": "designWhiteboard",
         "tags": [
           "whiteboards"
@@ -3893,6 +3910,22 @@
                   "confirm": {
                     "type": "boolean",
                     "description": "Set true ONLY after the user has approved the 50-credit cost. Leave unset/false on the first call to receive the cost quote + balance."
+                  },
+                  "designProfile": {
+                    "type": "string",
+                    "enum": [
+                      "standard",
+                      "branded-executive",
+                      "illustrated",
+                      "image",
+                      "agentic",
+                      "agentic-deck"
+                    ],
+                    "description": "Optional. 'standard' (default) = the general multi-agent design. 'agentic' = an AI-chat-style agentic slide composer that drives the whiteboard tools and self-corrects from renders, composing ONE polished slide. 'agentic-deck' = the same agentic composer run over a planned storyline, building a multi-slide deck (each slide on its own frame, tiled left to right). 'branded-executive' = an on-brand, McKinsey-style editable SLIDE DECK themed by the org's brand kit (pair with brandKitId, or omit for the org default). 'illustrated' = an editable-illustration board: a rich text-free vector illustration with real editable text labels and leader lines placed on top. 'image' = a single polished, on-brand IMAGE board with all the text baked into the picture (no editable shapes), which the user then refines with AI mask edits. 'illustrated' and 'image' are each gated per organisation; if not enabled the call returns a clear message."
+                  },
+                  "brandKitId": {
+                    "type": "string",
+                    "description": "Optional brand kit id (from listBrandKits) to theme a branded-executive deck. If omitted, the org's built-in default is used."
                   }
                 },
                 "required": [
@@ -3977,6 +4010,277 @@
         }
       }
     },
+    "/tools/designComponent": {
+      "post": {
+        "summary": "designComponent",
+        "description": "Design ONE reusable, on-brand SLIDE COMPONENT and add it to the org's component library so every future branded deck (designWhiteboard designProfile:'branded-executive') can use it. This is the self-improving design loop: an agent AUTHORS the component as a declarative template (a gradient/shadow/curve SVG skin + a native editable PPTX shape + reflowing bound-text slots), RENDERS it, a vision critic COMPARES the render to your brief and lists gaps, and it FIXES + re-renders until polished — then validates and stores it. Use it to grow the deck component catalogue beyond the built-ins (e.g. a 'kpi.delta' stat with an up/down arrow, a 'quote.card', a 'logo.strip'). Browse-first: if a component with this `key` already exists it is reused (pass force:true to redesign). Provide example `sampleSlots` so it can lay out real content, and a `projectId` for the small preview board it builds. Returns the stored component, the per-round critique trail, and the preview board id. It uses a few AI calls + renders (no flat credit charge); the new component is then free to reuse forever.",
+        "operationId": "designComponent",
+        "tags": [
+          "uncategorized"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "key": {
+                    "type": "string",
+                    "description": "The component key, lowercase dotted, e.g. 'kpi.delta'. This is how decks reference it; reused if it already exists."
+                  },
+                  "title": {
+                    "type": "string",
+                    "description": "A short human title, e.g. 'KPI with delta arrow'."
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "What the component IS, WHEN to use it, and what it should LOOK like (the richer the better — this drives both the designer and the critic)."
+                  },
+                  "projectId": {
+                    "type": "string",
+                    "description": "Project to create the small preview board in (where the render iterations are shown)."
+                  },
+                  "sampleSlots": {
+                    "type": "object",
+                    "description": "Example slot content to render with, e.g. { value: '47%', label: 'Revenue growth', delta: '+12 pts' }. The slot keys become the component's editable fields.",
+                    "additionalProperties": true
+                  },
+                  "boxCols": {
+                    "type": "number",
+                    "description": "Optional width in grid columns (2-12, default 4)."
+                  },
+                  "boxRows": {
+                    "type": "number",
+                    "description": "Optional height in grid rows (2-12, default 5)."
+                  },
+                  "category": {
+                    "type": "string",
+                    "description": "Optional catalogue category (e.g. 'data', 'narrative', 'comparison')."
+                  },
+                  "tags": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Optional search tags."
+                  },
+                  "referenceImageUrl": {
+                    "type": "string",
+                    "description": "Optional URL of a reference image the component should match; the critic compares the render to it."
+                  },
+                  "force": {
+                    "type": "boolean",
+                    "description": "Redesign even if a component with this key already exists (default false = reuse)."
+                  }
+                },
+                "required": [
+                  "key",
+                  "title",
+                  "description",
+                  "projectId",
+                  "sampleSlots"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/editWhiteboardImageRegion": {
+      "post": {
+        "summary": "editWhiteboardImageRegion",
+        "description": "Mask-edit (inpaint) one region of an image element on a whiteboard. Given the target image element id and a paint MASK (a PNG where WHITE marks the area to regenerate and BLACK is kept), it regenerates only the masked region using the prompt and replaces the image IN PLACE (same position + size). This is mainly used by the in-app image-board mask editor for boards designed with designProfile:'image'. It costs a small flat credit charge (refunded automatically if the edit fails on our side). It is gated per organisation behind the same 'whiteboard_design_image' feature as the image design profile; if that is not enabled the call returns a clear message.",
+        "operationId": "editWhiteboardImageRegion",
+        "tags": [
+          "whiteboards"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "documentId": {
+                    "type": "string",
+                    "description": "The whiteboard document that holds the image element."
+                  },
+                  "elementId": {
+                    "type": "string",
+                    "description": "The id of the image element on the board to edit (from getWhiteboard includeElements=true)."
+                  },
+                  "maskBase64": {
+                    "type": "string",
+                    "description": "A PNG mask (base64, with or without a data: prefix) the same shape as the image. WHITE pixels are regenerated; BLACK pixels are preserved."
+                  },
+                  "prompt": {
+                    "type": "string",
+                    "description": "What to put in the masked area, in plain language (e.g. 'replace the car with a red bicycle')."
+                  },
+                  "strength": {
+                    "type": "number",
+                    "description": "Optional 0..1 — how far the regenerated area may diverge from the original. Ignored by FLUX Fill (which balances via the prompt); leave unset unless using a non-Fill inpaint model."
+                  }
+                },
+                "required": [
+                  "documentId",
+                  "elementId",
+                  "maskBase64",
+                  "prompt"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/tools/createWhiteboard": {
       "post": {
         "summary": "createWhiteboard",
@@ -4471,9 +4775,11 @@
                             "doodle",
                             "frame",
                             "image",
-                            "stencil"
+                            "stencil",
+                            "chart",
+                            "table"
                           ],
-                          "description": "Element kind. 'sticky' = a first-class sticky/post-it note (solid fill + auto-fitting bound label; set text + backgroundColor) — use this for sticky notes, NOT a stencil. 'stencil' = a hand-drawn library graphic from listWhiteboardStencils, of kind 'symbol' (one atomic labelled node — flowchart box, BPMN task, org node: set `id` + `text` + width/height, text auto-fits, connect arrows via start/end {id}) or 'template' (a multi-element layout — Alerts, Forms, Tables, Charts: place whole, then customise its returned children by id; do NOT set a single `text`). Set `stencil` (fuzzy name, one call) or `stencilKey` (exact). 'image' with `iconPath` = a software-architecture icon from listArchitectureIcons. Reserve rectangle/ellipse/diamond for when no standard form fits."
+                          "description": "Element kind. 'sticky' = a first-class sticky/post-it note (solid fill + auto-fitting bound label; set text + backgroundColor) — use this for sticky notes, NOT a stencil. 'stencil' = a hand-drawn library graphic from listWhiteboardStencils, of kind 'symbol' (one atomic labelled node — flowchart box, BPMN task, org node: set `id` + `text` + width/height, text auto-fits, connect arrows via start/end {id}) or 'template' (a multi-element layout — Alerts, Forms, Tables, Charts: place whole, then customise its returned children by id; do NOT set a single `text`). Set `stencil` (fuzzy name, one call) or `stencilKey` (exact). 'image' with `iconPath` = a software-architecture icon from listArchitectureIcons. 'chart' = a NATIVE, fully-editable data chart (column/bar/line/area/pie/donut/scatter/sparkline/combo/stackedColumn/groupedColumn/radar/gauge) built from real Excalidraw shapes — bars/lines/wedges plus axes, gridlines and a legend — for ANY data, metric, KPI, trend, comparison or breakdown: set chartType + series (+ categories + options). ALWAYS prefer a 'chart' over hand-drawing bars/lines or a wireframe 'chart' stencil. 'table' = a NATIVE, fully-editable GRID (real rectangles + bound, word-wrapped cells, auto-sized columns + rows, a header band, optional zebra striping / per-column colours) for ANY tabular data, list or matrix — set columns + rows (+ options). ALWAYS prefer a 'table' over hand-drawing a grid of boxes. Reserve rectangle/ellipse/diamond for when no standard form fits."
                         },
                         "stencil": {
                           "type": "string",
@@ -4529,23 +4835,127 @@
                         },
                         "text": {
                           "type": "string",
-                          "description": "Label/caption. On a shape it's a centered auto-wrapped bound label (prefer over a separate type:'text'); on a type:'sticky' it's the note text; on a type:'stencil' of kind 'symbol' it fills + re-fits its single label (IGNORED for 'template' stencils — customise their children by id instead)."
+                          "description": "Label/caption. To label a shape, set `text` on the SHAPE itself — it becomes a BOUND label that the server word-wraps with real font metrics, auto-fits, and positions (centred by default) INSIDE the shape. Never drop a separate type:'text' element on top of a shape, and never hand-compute a label's x/y/width — the server does the geometry (like the editor does when you type into a shape). On a type:'sticky' it's the note text; on a type:'stencil' of kind 'symbol' it fills + re-fits its single label (IGNORED for 'template' stencils — customise their children by id instead). Use a standalone type:'text' only for free-floating text that belongs to no shape."
                         },
                         "fitText": {
                           "type": "boolean",
                           "description": "Auto-shrink the bound label's font size so the text always fits inside the shape — no overflow (default true). Set false to keep your exact fontSize even if it spills."
                         },
-                        "backgroundColor": {
+                        "fontSize": {
+                          "type": "number",
+                          "description": "Text size in px. Establish HIERARCHY: titles ~28-40, section headings ~22-28, body/labels ~16-20. Applies to a standalone text, a shape's bound label, a sticky, or an icon caption. Bound labels still auto-shrink to fit unless fitText:false."
+                        },
+                        "fontFamily": {
                           "type": "string",
-                          "description": "Fill colour: a name ('blue'/'green'/'yellow'/'pink'/'violet'/'orange'/'teal'/…) or a hex value."
+                          "description": "Font style: 'hand-drawn' (sketchy Excalidraw look, the default), 'sans' (clean/professional — use for business, dashboards, formal diagrams), or 'code' (monospace). Pass this to control the look instead of leaving everything hand-drawn."
                         },
-                        "start": {
-                          "type": "object",
-                          "description": "For arrows/lines: { id } of the source shape (auto-clips to the edge + auto-routes around shapes in between)."
+                        "strokeColor": {
+                          "type": "string",
+                          "description": "TEXT colour (for text/labels) or line/border colour (for shapes, arrows, lines, doodles): a name ('blue'/'green'/'red'/'orange'/'violet'/'teal'/…) or a hex value. Use a brand or theme colour for titles/emphasis; default is near-black."
+                        },
+                        "textAlign": {
+                          "type": "string",
+                          "enum": [
+                            "left",
+                            "center",
+                            "right"
+                          ],
+                          "description": "Horizontal alignment of the text within its box — the equivalent of the toolbar's align buttons. Bound labels default to 'center'."
+                        },
+                        "verticalAlign": {
+                          "type": "string",
+                          "enum": [
+                            "top",
+                            "middle",
+                            "bottom"
+                          ],
+                          "description": "Vertical alignment of a bound label inside its shape (toolbar parity). Defaults to 'middle' (centred)."
+                        },
+                        "backgroundColor": {
+                          "type": "string",
+                          "description": "Fill colour: a name ('blue'/'green'/'yellow'/'pink'/'violet'/'orange'/'teal'/…) or a hex value."
+                        },
+                        "start": {
+                          "type": "object",
+                          "description": "For arrows/lines: { id } of the source shape (auto-clips to the edge + auto-routes around shapes in between)."
                         },
                         "end": {
                           "type": "object",
                           "description": "For arrows/lines: { id } of the target shape."
+                        },
+                        "title": {
+                          "type": "string",
+                          "description": "For type:'chart' — the chart's title, drawn at the top of the chart."
+                        },
+                        "chartType": {
+                          "type": "string",
+                          "enum": [
+                            "column",
+                            "bar",
+                            "line",
+                            "area",
+                            "pie",
+                            "donut",
+                            "scatter",
+                            "sparkline",
+                            "combo",
+                            "stackedColumn",
+                            "groupedColumn",
+                            "radar",
+                            "gauge"
+                          ],
+                          "description": "For type:'chart' — the chart family. column=vertical bars (default), bar=horizontal bars, line/area=trends, pie/donut=parts-of-whole, scatter=points, sparkline=tiny inline trend (no axes/legend), combo=bars+line (dual axis via a series with axis:'right'), stackedColumn/groupedColumn=multi-series, radar, gauge."
+                        },
+                        "categories": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          },
+                          "description": "For type:'chart' — x-axis category labels, e.g. ['Jan','Feb','Mar','Apr']."
+                        },
+                        "series": {
+                          "type": "array",
+                          "description": "For type:'chart' — one or more data series. Each: { name:string, data:number[], type?:'bar'|'line'|'area' (per-series, for combo), color?:string (hex), axis?:'left'|'right' (dual axis), markers?:boolean (line point markers) }. For pie/donut use ONE series whose data maps to categories.",
+                          "items": {
+                            "type": "object",
+                            "additionalProperties": true
+                          }
+                        },
+                        "options": {
+                          "type": "object",
+                          "description": "For type:'chart' — { legend?:boolean|'top'|'bottom'|'right', gridlines?:boolean|'x'|'y'|'both'|'none', dataLabels?:boolean, yAxis?:boolean, xAxis?:boolean, yMin?:number, yMax?:number, smooth?:boolean, valueFormat?:'%'|'$'|'k', palette?:string[] (hex), donutHole?:number }. For type:'table' — { headerFill?:string (hex), headerTextColor?:string, zebra?:boolean, rowFill?:string, altRowFill?:string, columnColors?:string[] (per-column hex), fontSize?:number, headerFontSize?:number, borderColor?:string, align?:'left'|'center'|'right' }.",
+                          "additionalProperties": true
+                        },
+                        "columns": {
+                          "type": "array",
+                          "description": "For type:'table' — column headers: string[] (e.g. ['Task','Owner','Status']) or [{ header:string, width?:number, align?:'left'|'center'|'right' }].",
+                          "items": {
+                            "oneOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "type": "object"
+                              }
+                            ]
+                          }
+                        },
+                        "rows": {
+                          "type": "array",
+                          "description": "For type:'table' — data rows; each row is an array of cell values (string|number) aligned to columns, e.g. [['T-1','Sam','Done'],['T-2','Lee','WIP']].",
+                          "items": {
+                            "type": "array",
+                            "items": {
+                              "oneOf": [
+                                {
+                                  "type": "string"
+                                },
+                                {
+                                  "type": "number"
+                                }
+                              ]
+                            }
+                          }
                         }
                       },
                       "required": [
@@ -7502,7 +7912,7 @@
     "/tools/listImprovements": {
       "post": {
         "summary": "listImprovements",
-        "description": "List improvements in a project. Supports filtering by status, type, priority, and query.",
+        "description": "List AND grep improvements in a project. `query` searches the title, friendlyId and problem statement, not just the title (substring by default; set isRegex:true for a regular expression, caseSensitive:true for exact case). Supports filtering by status, type, priority. For ranked semantic + text search use searchImprovements.",
         "operationId": "listImprovements",
         "tags": [
           "improvements"
@@ -7555,7 +7965,15 @@
                   },
                   "query": {
                     "type": "string",
-                    "description": "Search title, friendly_id, problem_statement."
+                    "description": "Grep across title, friendlyId and problem_statement. Substring by default; a regular expression when isRegex:true; case-insensitive unless caseSensitive:true."
+                  },
+                  "isRegex": {
+                    "type": "boolean",
+                    "description": "Treat query as a regular expression (grep -E), e.g. \"ACME-\\d+\". Default false (literal substring)."
+                  },
+                  "caseSensitive": {
+                    "type": "boolean",
+                    "description": "Case-sensitive matching. Default false."
                   },
                   "sortField": {
                     "type": "string",
@@ -9529,7 +9947,7 @@
     "/tools/searchImprovements": {
       "post": {
         "summary": "searchImprovements",
-        "description": "Search improvements using hybrid text + semantic search. Returns ranked results.",
+        "description": "Locate any artefact (document / whiteboard / diagram / plan / task / improvement / compliance) by name or friendly id — AND ranked semantic search over improvements.\n\n• CROSS-ARTEFACT FINDER MODE (pass `types`): matches title + friendly id (e.g. \"DOC-123\", \"WBD-9\", \"PLN-4\", \"TAS-7\", \"IMP-2\") + description across every artefact type. Returns a typed navigable list ({ artefacts: [{ result_type, id, friendly_id, title, snippet, document_id, project_id, href }] }). This is the tool to use to find an artefact by its name or id — NOT kg_search (which retrieves knowledge from inside content). Pass types:[\"document\",\"whiteboard\",\"plan\",\"task\",\"improvement\",\"compliance\"] (or a subset) to search those types; an empty or all-inclusive list searches everything.\n\n• IMPROVEMENT SEMANTIC MODE (omit `types`): hybrid full-text + vector search over improvements only. Returns ranked { improvements }.",
         "operationId": "searchImprovements",
         "tags": [
           "improvements"
@@ -9543,7 +9961,22 @@
                 "properties": {
                   "query": {
                     "type": "string",
-                    "description": "Search query."
+                    "description": "Search query — a name fragment or a friendly id."
+                  },
+                  "types": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "enum": [
+                        "document",
+                        "whiteboard",
+                        "improvement",
+                        "task",
+                        "plan",
+                        "compliance"
+                      ]
+                    },
+                    "description": "Switches on the cross-artefact finder. Artefact types to search (subset of document, whiteboard, improvement, task, plan, compliance). Empty / all = every type. Omit entirely for the improvements-only semantic search."
                   },
                   "projectId": {
                     "type": "string",
@@ -9555,7 +9988,11 @@
                   },
                   "limit": {
                     "type": "number",
-                    "description": "Max results (default 20, max 50)."
+                    "description": "Max results (default 20 semantic / 30 cross-artefact, max 50)."
+                  },
+                  "offset": {
+                    "type": "number",
+                    "description": "Pagination offset (cross-artefact mode)."
                   }
                 },
                 "required": [
@@ -9643,7 +10080,7 @@
     "/tools/listPlans": {
       "post": {
         "summary": "listPlans",
-        "description": "List plans in a project. Supports filtering by status, priority, and query.",
+        "description": "List AND grep plans in a project. `query` searches the title, friendlyId and description, not just the title (substring by default; set isRegex:true for a regular expression, caseSensitive:true for exact case). Supports filtering by status and priority.",
         "operationId": "listPlans",
         "tags": [
           "plans"
@@ -9668,7 +10105,15 @@
                   },
                   "query": {
                     "type": "string",
-                    "description": "Search title, friendly_id, description."
+                    "description": "Grep across title, friendlyId and description. Substring by default; a regular expression when isRegex:true; case-insensitive unless caseSensitive:true."
+                  },
+                  "isRegex": {
+                    "type": "boolean",
+                    "description": "Treat query as a regular expression (grep -E), e.g. \"ACME-\\d+\". Default false (literal substring)."
+                  },
+                  "caseSensitive": {
+                    "type": "boolean",
+                    "description": "Case-sensitive matching. Default false."
                   },
                   "sortField": {
                     "type": "string",
@@ -11532,7 +11977,7 @@
     "/tools/listTasks": {
       "post": {
         "summary": "listTasks",
-        "description": "List tasks in a plan. Supports filtering by status, priority, phaseId, and query.",
+        "description": "List AND grep tasks in a plan. `query` searches the title, friendlyId and description, not just the title (substring by default; set isRegex:true for a regular expression, caseSensitive:true for exact case). Supports filtering by status, priority and phaseId.",
         "operationId": "listTasks",
         "tags": [
           "plans"
@@ -11561,7 +12006,15 @@
                   },
                   "query": {
                     "type": "string",
-                    "description": "Search title and friendly_id."
+                    "description": "Grep across title, friendlyId and description. Substring by default; a regular expression when isRegex:true; case-insensitive unless caseSensitive:true."
+                  },
+                  "isRegex": {
+                    "type": "boolean",
+                    "description": "Treat query as a regular expression (grep -E), e.g. \"ACME-\\d+\". Default false (literal substring)."
+                  },
+                  "caseSensitive": {
+                    "type": "boolean",
+                    "description": "Case-sensitive matching. Default false."
                   },
                   "sortField": {
                     "type": "string",
@@ -13179,7 +13632,7 @@
     "/tools/kg_search": {
       "post": {
         "summary": "kg_search",
-        "description": "Unified Knowledge Graph retrieval. PICK THE MODE THAT FITS THE QUERY:\n\n• mode='local' (default) — for SPECIFIC factual questions (\"what does §15 say about deposits?\", \"who is the Chief Counsel?\"). FTS+vector RRF over individual document chunks. Returns precise excerpts with citations.\n\n• mode='global' — for THEMATIC / OVERVIEW / SUMMARY questions (\"what are the main themes\", \"give me an overview of the project\", \"what topics does this cover\"). Returns Louvain community summaries + curated wiki pages — far better than 'local' for big-picture queries because community summaries already aggregate across many chunks. ALWAYS PREFER over 'local' when the user asks for themes / summary / overview / topic landscape.\n\n• mode='graph' — for RELATIONSHIP questions (\"what's connected to entity X?\", \"who cites Section 5?\"). 1-hop entity-neighbourhood walk. Pass query OR srcEntityId.\n\n• mode='path' — for CONNECTION questions (\"how does X relate to Y?\"). Shortest path between two entities. Pass srcEntityId AND dstEntityId.\n\n• mode='ppr' — for MULTI-HOP discovery (\"what's relevant to X, even indirectly?\"). Personalised PageRank over AUTHORED-vs-EXTRACTED weighted edges, seeded by query-similar entities. Best when 'local' returns too few results and the answer requires walking through several entity hops.\n\nQuick decision tree:\n- User asks for an overview/summary/themes → 'global'\n- User asks a specific question with a clear answer → 'local'\n- User asks 'how is X connected to Y' → 'path' (with both entity IDs)\n- User asks 'what's near entity X' → 'graph' (with srcEntityId)\n- 'local' returned nothing useful and the question is broad → retry with 'ppr'",
+        "description": "Unified Knowledge Graph KNOWLEDGE retrieval — facts, themes and relationships from INSIDE document CONTENT. This is NOT an artefact finder: do NOT use it to locate a document / whiteboard / diagram / plan / task / improvement by its TITLE or friendly id (e.g. \"DOC-123\", \"find the GTM plan\"). For locating an artefact by name or id use listDocuments / listWhiteboards / listPlans / listTasks / searchImprovements (they match title + friendly id). Use kg_search only to ANSWER A QUESTION from the knowledge contained in the artefacts.\n\nPICK THE MODE THAT FITS THE QUERY:\n\n• mode='local' (default) — for SPECIFIC factual questions (\"what does §15 say about deposits?\", \"who is the Chief Counsel?\"). FTS+vector RRF over individual document chunks. Returns precise excerpts with citations.\n\n• mode='global' — for THEMATIC / OVERVIEW / SUMMARY questions (\"what are the main themes\", \"give me an overview of the project\", \"what topics does this cover\"). Returns Louvain community summaries + curated wiki pages — far better than 'local' for big-picture queries because community summaries already aggregate across many chunks. ALWAYS PREFER over 'local' when the user asks for themes / summary / overview / topic landscape.\n\n• mode='graph' — for RELATIONSHIP questions (\"what's connected to entity X?\", \"who cites Section 5?\"). 1-hop entity-neighbourhood walk. Pass query OR srcEntityId.\n\n• mode='path' — for CONNECTION questions (\"how does X relate to Y?\"). Shortest path between two entities. Pass srcEntityId AND dstEntityId.\n\n• mode='ppr' — for MULTI-HOP discovery (\"what's relevant to X, even indirectly?\"). Personalised PageRank over AUTHORED-vs-EXTRACTED weighted edges, seeded by query-similar entities. Best when 'local' returns too few results and the answer requires walking through several entity hops.\n\nQuick decision tree:\n- User asks for an overview/summary/themes → 'global'\n- User asks a specific question with a clear answer → 'local'\n- User asks 'how is X connected to Y' → 'path' (with both entity IDs)\n- User asks 'what's near entity X' → 'graph' (with srcEntityId)\n- 'local' returned nothing useful and the question is broad → retry with 'ppr'",
         "operationId": "kg_search",
         "tags": [
           "knowledge_graph"
@@ -21585,6 +22038,362 @@
         }
       }
     },
+    "/tools/createBrandKit": {
+      "post": {
+        "summary": "createBrandKit",
+        "description": "Create a per-org BRAND KIT (palette/fonts/logo) that themes branded-executive slides and document exports. Build it from one of: a `logoUrl` (AUTO-EXTRACT palette/fonts via the vision model), an `officeUrl` (an existing .pptx/.docx — extracts theme colours, fonts, logo, watermark + embedded font files), or explicit `tokens`. Auth: can_admin_org. Tiered: free 0, pro 1, enterprise unlimited. Optionally set it as the default at a scope in one call.",
+        "operationId": "createBrandKit",
+        "tags": [
+          "uncategorized"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "organizationId": {
+                    "type": "string",
+                    "description": "Org that owns the kit."
+                  },
+                  "name": {
+                    "type": "string",
+                    "description": "Display name (e.g. the brand/company name)."
+                  },
+                  "logoUrl": {
+                    "type": "string",
+                    "description": "Image URL of the logo to extract palette/fonts from (PNG/JPG/SVG). Omit if passing officeUrl or tokens."
+                  },
+                  "officeUrl": {
+                    "type": "string",
+                    "description": "URL of an existing .pptx or .docx to extract the brand from (theme colours + fonts + logo + watermark + embedded fonts). Max 25MB. Omit if passing logoUrl or tokens."
+                  },
+                  "tokens": {
+                    "type": "object",
+                    "description": "Explicit DTCG brand tokens { color:{brand:{primary,primaryText,ink,bg,surface,muted,border,positive,warning,negative}}, font:{heading,body} }. Omit to extract from logoUrl/officeUrl.",
+                    "additionalProperties": true
+                  },
+                  "guidance": {
+                    "type": "string",
+                    "description": "Optional extra guidance for the extractor (e.g. 'use the teal, not the grey')."
+                  },
+                  "setDefaultScope": {
+                    "type": "string",
+                    "enum": [
+                      "organization",
+                      "workspace",
+                      "project"
+                    ],
+                    "description": "Optionally set the new kit as default at this scope."
+                  },
+                  "setDefaultScopeId": {
+                    "type": "string",
+                    "description": "Workspace/project id when setDefaultScope is workspace/project."
+                  }
+                },
+                "required": [
+                  "organizationId",
+                  "name"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/listBrandKits": {
+      "post": {
+        "summary": "listBrandKits",
+        "description": "List an organisation's BRAND KITS (palette/fonts/logo), newest first. Use a returned `id` as brandKitId for a design call or setDefaultBrandKit. Auth: can_admin_org.",
+        "operationId": "listBrandKits",
+        "tags": [
+          "uncategorized"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "organizationId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "organizationId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/setDefaultBrandKit": {
+      "post": {
+        "summary": "setDefaultBrandKit",
+        "description": "Set or clear the default BRAND KIT at a scope: organization, workspace, or project. Defaults cascade most-specific-first (a per-board/document override beats project beats workspace beats organization). Pass brandKitId:null to clear. Auth: org owner/admin.",
+        "operationId": "setDefaultBrandKit",
+        "tags": [
+          "uncategorized"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "scope": {
+                    "type": "string",
+                    "enum": [
+                      "organization",
+                      "workspace",
+                      "project"
+                    ]
+                  },
+                  "scopeId": {
+                    "type": "string",
+                    "description": "The org/workspace/project id for the chosen scope."
+                  },
+                  "brandKitId": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "description": "Brand kit to make default, or null to clear."
+                  }
+                },
+                "required": [
+                  "scope",
+                  "scopeId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authenticated but lacking the required permission or feature flag.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Body did not match the tool's input schema.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/tools/updateOrgFeatureFlags": {
       "post": {
         "summary": "updateOrgFeatureFlags",
@@ -21769,35 +22578,55 @@
                             "object",
                             "array",
                             "null"
-                          ]
+                          ],
+                          "items": {
+                            "type": "string"
+                          },
+                          "description": "Visible column ids (string[]) when an array."
                         },
                         "column_widths": {
                           "type": [
                             "object",
                             "array",
                             "null"
-                          ]
+                          ],
+                          "items": {
+                            "type": "number"
+                          },
+                          "description": "Column widths — a { colId: px } map, or a number[] when an array."
                         },
                         "column_order": {
                           "type": [
                             "object",
                             "array",
                             "null"
-                          ]
+                          ],
+                          "items": {
+                            "type": "string"
+                          },
+                          "description": "Ordered column ids (string[]) when an array."
                         },
                         "sort_config": {
                           "type": [
                             "object",
                             "array",
                             "null"
-                          ]
+                          ],
+                          "items": {
+                            "type": "object"
+                          },
+                          "description": "Sort rules — array of { id, desc } when an array."
                         },
                         "filter_config": {
                           "type": [
                             "object",
                             "array",
                             "null"
-                          ]
+                          ],
+                          "items": {
+                            "type": "object"
+                          },
+                          "description": "Filter state — usually a { pageSize, tab, filters } object."
                         }
                       },
                       "required": [