@stablebaseline/sdk 0.5.2 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -75,7 +75,7 @@ export interface paths {
75
75
  put?: never;
76
76
  /**
77
77
  * listArchitectureIcons
78
- * @description SOFTWARE & CLOUD architecture icons ONLY (AWS, Azure, GCP, Docker, Kubernetes, databases, message queues, dev tools, etc.). This catalog has NO general/nature/science/people/business icons — so for any NON-technical topic (e.g. photosynthesis, biology, history, marketing), do NOT use this tool; instead put a relevant emoji directly in the element's label (e.g. ☀️ Sunlight, 💧 Water, 🌿 Leaf). It returns nothing for off-domain queries by design — never force an unrelated tech logo onto a non-tech concept. Each result has an `iconPath` (e.g. 'dev/docker.svg'). TWO ways to use it: (1) on a WHITEBOARD, drop it via addWhiteboardElements({ type:'image', iconPath:'dev/docker.svg', x, y, width:96, height:96, text:'Docker' }); (2) in a D2 systems-architecture diagram, use the iconPath as-is in D2 code (e.g. icon: dev/docker.svg).
78
+ * @description SOFTWARE & CLOUD architecture icons ONLY (AWS, Azure, GCP, Docker, Kubernetes, databases, message queues, dev tools, etc.). This catalog has NO general/nature/science/people/business icons — so for any NON-technical topic (e.g. photosynthesis, biology, history, marketing), do NOT use this tool; instead put a relevant emoji directly in the element's label (for example a sun for sunlight, a droplet for water, a leaf for a plant). It returns nothing for off-domain queries by design — never force an unrelated tech logo onto a non-tech concept. Each result has an `iconPath` (e.g. 'dev/docker.svg'). TWO ways to use it: (1) on a WHITEBOARD, drop it via addWhiteboardElements({ type:'image', iconPath:'dev/docker.svg', x, y, width:96, height:96, text:'Docker' }); (2) in a D2 systems-architecture diagram, use the iconPath as-is in D2 code (e.g. icon: dev/docker.svg).
79
79
  */
80
80
  post: operations["listArchitectureIcons"];
81
81
  delete?: never;
@@ -855,7 +855,7 @@ export interface paths {
855
855
  put?: never;
856
856
  /**
857
857
  * listWhiteboards
858
- * @description List the whiteboards in a project (hidden whiteboard-kind documents). Returns documentId, diagramId, title and timestamps for each.
858
+ * @description List AND grep the whiteboards in a project (hidden whiteboard-kind documents). `query` searches the title and friendlyId (substring by default; set isRegex:true for a regular expression, caseSensitive:true for exact case). This is the tool to find a board by name — listDocuments deliberately excludes whiteboards. Returns documentId, diagramId, title and timestamps for each.
859
859
  */
860
860
  post: operations["listWhiteboards"];
861
861
  delete?: never;
@@ -915,7 +915,7 @@ export interface paths {
915
915
  put?: never;
916
916
  /**
917
917
  * addWhiteboardElements
918
- * @description Author shapes onto a whiteboard from high-level specs (you do NOT need the full Excalidraw element schema). Appends to the canvas. PLACEMENT ON AN EXISTING BOARD (critical): NEVER guess x/y onto a board that already has content — guessed coordinates land ON TOP of existing shapes and create an unreadable pile. Either (a) OMIT x/y entirely and the server auto-places the new elements together in clear space BELOW the current content, or (b) FIRST call getWhiteboard({ includeElements:true }) to see where existing shapes already are and choose a genuinely EMPTY region. Pass explicit x/y only for a deliberate layout in space you have confirmed is empty. PREFER THE RICHEST FORM THAT FITS, not plain rectangles: for a sticky/post-it note use { type:'sticky', text, backgroundColor } (a first-class note with an auto-fitting bound label — there is NO sticky-note stencil; OMIT x/y and it is auto-placed in clear space below existing content, so it doesn't land on top of the current drawing); for kanban/scrum/story boards, flowcharts, UML/ER, BPMN, org charts, wireframes/mockups, charts or people use a LIBRARY STENCIL in ONE call — { type:'stencil', stencil:'<name e.g. decision>', x, y } fuzzy-matches by name with no prior listWhiteboardStencils call (pass width/height to SCALE the whole stencil and text to fill its single label); for cloud/software-architecture use ICONS — { type:'image', iconPath:'dev/docker.svg', x, y } (paths from listArchitectureIcons); reserve raw rectangles/ellipses for when no standard form fits. Expressive enough to reproduce real Excalidraw templates (sticky-note brainstorm grids, sketchy mind maps, flowcharts). Each spec: { type: 'rectangle'|'ellipse'|'diamond'|'sticky'|'text'|'arrow'|'line'|'freedraw'|'frame'|'image'|'stencil', id?, x, y, width, height, text? (STRONGLY PREFER setting a shape's label via its own `text` — it becomes a centered, auto-WRAPPED bound label fitted to the shape; do NOT drop a separate type:'text' element on top of a shape as its label. Standalone type:'text' is for free-floating titles/notes and now also wraps to its width; Yes/No label on an arrow — emojis are fine, e.g. 'Risks ⚠️'), fontSize?, fontFamily? (1=hand-drawn default, 2=normal, 3=code), textAlign?, backgroundColor? (name 'blue'/'green'/'yellow'/'pink'/'violet'/'orange'/'teal'/… or hex), strokeColor?, fillStyle? ('solid'|'hachure'|'cross-hatch'), strokeStyle? ('solid'|'dashed'|'dotted' — use 'dashed' for grid/category borders), strokeWidth? (1 thin/2 bold/4 extra), roughness? (0 clean, 1 default, 2 very sketchy/hand-drawn — use 2 for organic mind maps), roundness? (number type or null for sharp), opacity?, name? (frame title), frameId? (put a shape inside a frame), start?:{id}, end?:{id} (connect arrows/lines to shapes by id — connectors AUTO-CLIP to the shape edges, never overrun to the centre, AUTO-ROUTE around any shapes in between so a decision's No/loop-back branch never cuts straight through the boxes between source and target, and bound text auto-wraps + centres), routing? ('straight' default | 'elbow' for clean right-angle flowchart/org-chart connectors | 'curved'), startArrowhead?/endArrowhead? (arrowheads are SOLID filled triangles by default — just OMIT them. Pass null for a plain mind-map spoke with no head. Do NOT pass 'arrow': that is Excalidraw's open 'V' and is auto-upgraded to a solid triangle anyway), points? ([[0,0],[dx,dy]] relative, only for manual geometry — almost never needed; binding by id is better), props? (escape hatch: any other Excalidraw field) }. ARCHITECTURE ICONS: to place a software-architecture icon (AWS/Azure/GCP/Docker/Kubernetes/databases/etc.), first call listArchitectureIcons to find one, then add a spec { type:'image', iconPath:'<relative_url e.g. dev/docker.svg>', x, y, width:96, height:96, text?:'<caption shown below>' } — the icon is stored as a URL reference (never base64). Use imageUrl instead of iconPath for any other public image. Combine icons with labelled boxes + elbow arrows for clean architecture diagrams. LIBRARY STENCILS: for hand-drawn, on-brand elements (scrum/kanban columns, flowchart symbols, UML/ER, BPMN, org-chart nodes, wireframe widgets, stick figures), FIRST call listWhiteboardStencils to find one, then add { type:'stencil', stencilKey:'<key from listWhiteboardStencils>', x, y } (or { type:'stencil', stencil:'<name e.g. decision>', pack?:'<pack>', x, y } to fuzzy-match by name). A stencil is a mini-whiteboard (a collection of elements) of kind 'symbol' or 'template' (listWhiteboardStencils returns the kind + its embedded `labels`). For a SYMBOL (one atomic labelled node — flowchart box, BPMN task, org node), pass id + text + width/height: the label auto-fits its single slot and arrows bind to it via start/end {id}. For a TEMPLATE (a multi-component layout — Alerts, Forms, Tables, Charts), place it WHOLE (no single text); the result returns its `children` (id + text + colour + position) so you retext, recolour, or DELETE specific parts by id via updateWhiteboardScene (cluster children by y to act on a whole row/variant). STRONGLY prefer stencils over plain rectangles for wireframes/mockups, kanban/scrum boards, UML/BPMN, org charts; for dense flowcharts, plain shapes with bound text + elbow arrows are equally reliable. (For a plain sticky/post-it note use type:'sticky', NOT a stencil — there is no sticky-note stencil.) FRAMES: a frame is a NON-DESTRUCTIVE, ANY-SIZE container. To enclose shapes that ALREADY exist, add ONE type:'frame' sized to cover them (Excalidraw auto-captures elements inside a frame's bounds) or set those shapes' frameId — never recreate or delete-and-redraw content just to frame it. If a frame doesn't fully cover its content, just RESIZE the frame (patch its width/height). Deleting a frame (deleteIds:[frameId]) leaves all its contents intact on the canvas — it only removes the frame border + title. PRESENTATION/SLIDES: when the user wants a presentation or slide deck, create type:'frame' slides sized width:1280,height:720 (16:9), laid out LEFT-TO-RIGHT at the same y (x: 0, then 1440, 2880, 4320, …), each with a `name` (the slide title). Put every slide's shapes/text/images INSIDE its frame by setting their frameId to that frame's id (give the frame an id and reference it). Slides play in order (left-to-right, then top-to-bottom) in the board's Present mode and export to PPTX, so one frame = one slide. FLOWCHART recipe: rectangles (roundness null for sharp process boxes), diamonds for decisions, arrows with routing:'elbow' and Yes/No as the arrow's text. Use type 'sticky' for sticky/post-it notes (a solid-fill note with an auto-fitting bound label — set text + backgroundColor); type 'line' with no arrowheads + roughness:2 for sketchy mind-map spokes. FREEHAND DOODLES: to actually draw/doodle/sketch freehand, use { type:'freedraw', points } where points is a RELATIVE [[x,y],…] path of the stroke (e.g. a squiggle, circling or annotating something, a hand-drawn star/heart/smiley/arrow, an organic blob) — it renders as one smooth freehand stroke. x/y is the origin; omit x/y to auto-place. Chain several freedraw specs for a multi-stroke doodle. NOTE: freehand is always SOLID (Excalidraw ignores strokeStyle on freedraw) — colour, strokeWidth and opacity DO apply; a freedraw with strokeStyle:'dashed' or 'dotted' is automatically rendered as a smooth dashed/dotted line so the dashes actually show. Give shapes ids and reference them from connectors. Connectors may also bind to shapes ALREADY on the board by their id (get them via getWhiteboard includeElements:true) — you do NOT need to resend existing shapes; the server reads the live scene to bind the arrow and route it around the other boxes. Great for brainstorms, mind maps, flowcharts, org charts, SWOT, retros. PROCESS: for any non-trivial board call getWhiteboardGuide FIRST to plan it; then after adding, ALWAYS call getWhiteboardImage to SEE the result and check layout, labels, spacing, overlaps and how shapes connect — if anything looks off, fix it with updateWhiteboardScene (patch by id) and render again, iterating until it looks right. RESULT: returns `added` (count), `placement` (bounding box {x,y,width,height} of what you just added) and `autoPlaced` (true when you omitted x/y so it was placed in clear space below existing content) — use placement/autoPlaced to tell the user WHERE the new elements landed, never invent a location.
918
+ * @description Author shapes onto a whiteboard from high-level specs (you do NOT need the full Excalidraw element schema). Appends to the canvas. PLACEMENT ON AN EXISTING BOARD (critical): NEVER guess x/y onto a board that already has content — guessed coordinates land ON TOP of existing shapes and create an unreadable pile. Either (a) OMIT x/y entirely and the server auto-places the new elements together in clear space BELOW the current content, or (b) FIRST call getWhiteboard({ includeElements:true }) to see where existing shapes already are and choose a genuinely EMPTY region. Pass explicit x/y only for a deliberate layout in space you have confirmed is empty. PREFER THE RICHEST FORM THAT FITS, not plain rectangles: for a sticky/post-it note use { type:'sticky', text, backgroundColor } (a first-class note with an auto-fitting bound label — there is NO sticky-note stencil; OMIT x/y and it is auto-placed in clear space below existing content, so it doesn't land on top of the current drawing); for kanban/scrum/story boards, flowcharts, UML/ER, BPMN, org charts, wireframes/mockups, charts or people use a LIBRARY STENCIL in ONE call — { type:'stencil', stencil:'<name e.g. decision>', x, y } fuzzy-matches by name with no prior listWhiteboardStencils call (pass width/height to SCALE the whole stencil and text to fill its single label); for cloud/software-architecture use ICONS — { type:'image', iconPath:'dev/docker.svg', x, y } (paths from listArchitectureIcons); reserve raw rectangles/ellipses for when no standard form fits. Expressive enough to reproduce real Excalidraw templates (sticky-note brainstorm grids, sketchy mind maps, flowcharts). Each spec: { type: 'rectangle'|'ellipse'|'diamond'|'sticky'|'text'|'arrow'|'line'|'freedraw'|'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. a warning sign in a 'Risks' label), fontSize?, fontFamily? (1=hand-drawn default, 2=normal, 3=code), textAlign?, backgroundColor? (name 'blue'/'green'/'yellow'/'pink'/'violet'/'orange'/'teal'/… or hex), strokeColor?, fillStyle? ('solid'|'hachure'|'cross-hatch'), strokeStyle? ('solid'|'dashed'|'dotted' — use 'dashed' for grid/category borders), strokeWidth? (1 thin/2 bold/4 extra), roughness? (0 clean, 1 default, 2 very sketchy/hand-drawn — use 2 for organic mind maps), roundness? (number type or null for sharp), opacity?, name? (frame title), frameId? (put a shape inside a frame), start?:{id}, end?:{id} (connect arrows/lines to shapes by id — connectors AUTO-CLIP to the shape edges, never overrun to the centre, AUTO-ROUTE around any shapes in between so a decision's No/loop-back branch never cuts straight through the boxes between source and target, and bound text auto-wraps + centres), routing? ('straight' default | 'elbow' for clean right-angle flowchart/org-chart connectors | 'curved'), startArrowhead?/endArrowhead? (arrowheads are SOLID filled triangles by default — just OMIT them. Pass null for a plain mind-map spoke with no head. Do NOT pass 'arrow': that is Excalidraw's open 'V' and is auto-upgraded to a solid triangle anyway), points? ([[0,0],[dx,dy]] relative, only for manual geometry — almost never needed; binding by id is better), props? (escape hatch: any other Excalidraw field) }. ARCHITECTURE ICONS: to place a software-architecture icon (AWS/Azure/GCP/Docker/Kubernetes/databases/etc.), first call listArchitectureIcons to find one, then add a spec { type:'image', iconPath:'<relative_url e.g. dev/docker.svg>', x, y, width:96, height:96, text?:'<caption shown below>' } — the icon is stored as a URL reference (never base64). Use imageUrl instead of iconPath for any other public image. Combine icons with labelled boxes + elbow arrows for clean architecture diagrams. LIBRARY STENCILS: for hand-drawn, on-brand elements (scrum/kanban columns, flowchart symbols, UML/ER, BPMN, org-chart nodes, wireframe widgets, stick figures), FIRST call listWhiteboardStencils to find one, then add { type:'stencil', stencilKey:'<key from listWhiteboardStencils>', x, y } (or { type:'stencil', stencil:'<name e.g. decision>', pack?:'<pack>', x, y } to fuzzy-match by name). A stencil is a mini-whiteboard (a collection of elements) of kind 'symbol' or 'template' (listWhiteboardStencils returns the kind + its embedded `labels`). For a SYMBOL (one atomic labelled node — flowchart box, BPMN task, org node), pass id + text + width/height: the label auto-fits its single slot and arrows bind to it via start/end {id}. For a TEMPLATE (a multi-component layout — Alerts, Forms, Tables, Charts), place it WHOLE (no single text); the result returns its `children` (id + text + colour + position) so you retext, recolour, or DELETE specific parts by id via updateWhiteboardScene (cluster children by y to act on a whole row/variant). STRONGLY prefer stencils over plain rectangles for wireframes/mockups, kanban/scrum boards, UML/BPMN, org charts; for dense flowcharts, plain shapes with bound text + elbow arrows are equally reliable. (For a plain sticky/post-it note use type:'sticky', NOT a stencil — there is no sticky-note stencil.) FRAMES: a frame is a NON-DESTRUCTIVE, ANY-SIZE container. To enclose shapes that ALREADY exist, add ONE type:'frame' sized to cover them (Excalidraw auto-captures elements inside a frame's bounds) or set those shapes' frameId — never recreate or delete-and-redraw content just to frame it. If a frame doesn't fully cover its content, just RESIZE the frame (patch its width/height). Deleting a frame (deleteIds:[frameId]) leaves all its contents intact on the canvas — it only removes the frame border + title. PRESENTATION/SLIDES: when the user wants a presentation or slide deck, create type:'frame' slides sized width:1280,height:720 (16:9), laid out LEFT-TO-RIGHT at the same y (x: 0, then 1440, 2880, 4320, …), each with a `name` (the slide title). Put every slide's shapes/text/images INSIDE its frame by setting their frameId to that frame's id (give the frame an id and reference it). Slides play in order (left-to-right, then top-to-bottom) in the board's Present mode and export to PPTX, so one frame = one slide. FLOWCHART recipe: rectangles (roundness null for sharp process boxes), diamonds for decisions, arrows with routing:'elbow' and Yes/No as the arrow's text. Use type 'sticky' for sticky/post-it notes (a solid-fill note with an auto-fitting bound label — set text + backgroundColor); type 'line' with no arrowheads + roughness:2 for sketchy mind-map spokes. FREEHAND DOODLES: to actually draw/doodle/sketch freehand, use { type:'freedraw', points } where points is a RELATIVE [[x,y],…] path of the stroke (e.g. a squiggle, circling or annotating something, a hand-drawn star/heart/smiley/arrow, an organic blob) — it renders as one smooth freehand stroke. x/y is the origin; omit x/y to auto-place. Chain several freedraw specs for a multi-stroke doodle. NOTE: freehand is always SOLID (Excalidraw ignores strokeStyle on freedraw) — colour, strokeWidth and opacity DO apply; a freedraw with strokeStyle:'dashed' or 'dotted' is automatically rendered as a smooth dashed/dotted line so the dashes actually show. Give shapes ids and reference them from connectors. Connectors may also bind to shapes ALREADY on the board by their id (get them via getWhiteboard includeElements:true) — you do NOT need to resend existing shapes; the server reads the live scene to bind the arrow and route it around the other boxes. Great for brainstorms, mind maps, flowcharts, org charts, SWOT, retros. PROCESS: for any non-trivial board call getWhiteboardGuide FIRST to plan it; then after adding, ALWAYS call getWhiteboardImage to SEE the result and check layout, labels, spacing, overlaps and how shapes connect — if anything looks off, fix it with updateWhiteboardScene (patch by id) and render again, iterating until it looks right. RESULT: returns `added` (count), `placement` (bounding box {x,y,width,height} of what you just added) and `autoPlaced` (true when you omitted x/y so it was placed in clear space below existing content) — use placement/autoPlaced to tell the user WHERE the new elements landed, never invent a location.
919
919
  */
920
920
  post: operations["addWhiteboardElements"];
921
921
  delete?: never;
@@ -1155,7 +1155,7 @@ export interface paths {
1155
1155
  put?: never;
1156
1156
  /**
1157
1157
  * reorderDocuments
1158
- * @description MOVE documents between folders and/or reorder them — the batch filing tool. Pass [{documentId, position, folderId?}, ...]: `position` is a non-negative integer (usually renumber siblings sequentially as 0, 1, 2…), and the optional per-item `folderId` MOVES that document into the given folder (use null to move it to the project root; omit it to leave the document where it is). Use this to reorganise a project — file loose documents into subfolders, restructure a folder tree, or reorder siblings — in one call. Filing is metadata only: it does NOT bump the document version and does NOT create a version-history snapshot, so tidying folders never shows up as a content revision. A bad folderId fails the whole call rather than half-applying it. For a single document you can also use editDocument({documentId, folderId, position}), which behaves identically (and likewise creates no version when only the filing changes).
1158
+ * @description MOVE documents between folders and/or reorder them — the batch filing tool. Pass [{documentId, folderId?, position?}, ...] and give at least one of folderId/position per item. `folderId` MOVES that document into the given folder; use null for the project root; omit it to leave the document in its current folder. `position` sets the sort order among siblings — OMIT IT to append the document to the end of wherever it lands (or to keep its current place if it is not moving), which is usually what you want when filing. Use this to reorganise a project — file loose documents into subfolders, restructure a folder tree, or reorder siblings — in one call. The whole batch is applied in a SINGLE atomic database write, so it either all lands or none of it does; a bad folderId or an unreachable documentId fails the call with nothing changed. Filing is metadata only: it does NOT bump the document version and does NOT create a version-history snapshot, so tidying folders never shows up as a content revision. The response echoes the position the server actually assigned to each document. For a single document you can also use editDocument({documentId, folderId, position}), which behaves identically (and likewise creates no version when only the filing changes).
1159
1159
  */
1160
1160
  post: operations["reorderDocuments"];
1161
1161
  delete?: never;
@@ -1675,11 +1675,11 @@ export interface paths {
1675
1675
  put?: never;
1676
1676
  /**
1677
1677
  * searchImprovements
1678
- * @description Locate any artefact (document / whiteboard / diagram / plan / task / improvement / compliance) by name or friendly id — AND ranked semantic search over improvements.
1678
+ * @description Ranked semantic search over IMPROVEMENTS AND TASKS — hybrid full-text + vector, so it matches meaning rather than just wording. Returns ranked { improvements }, each with a versionTimestamp you can pass straight to updateImprovement without a getImprovement round-trip.
1679
1679
  *
1680
- * • 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.
1680
+ * Improvements and tasks are one table (a task is an improvement with is_task=true), so both are searched by default. Pass types:["task"] or types:["improvement"] to narrow to one.
1681
1681
  *
1682
- * • IMPROVEMENT SEMANTIC MODE (omit `types`): hybrid full-text + vector search over improvements only. Returns ranked { improvements }.
1682
+ * This tool searches improvements and tasks ONLY. To find a document, whiteboard, plan or compliance item by name or friendly id, use kg_search({ query, artefactMetadataOnly: true }) — it matches title + friendly id + uuid across every artefact type and needs no knowledge graph. To search document CONTENT, use listDocuments.
1683
1683
  */
1684
1684
  post: operations["searchImprovements"];
1685
1685
  delete?: never;
@@ -2259,11 +2259,11 @@ export interface paths {
2259
2259
  put?: never;
2260
2260
  /**
2261
2261
  * kg_search
2262
- * @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.
2262
+ * @description Unified Knowledge Graph KNOWLEDGE retrieval — facts, themes and relationships from INSIDE document CONTENT. To LOCATE AN ARTEFACT BY NAME OR ID rather than answer a question, pass artefactMetadataOnly:true — see below. Without that flag this tool retrieves knowledge from inside content and will not reliably find a thing by its title.
2263
2263
  *
2264
2264
  * PICK THE MODE THAT FITS THE QUERY:
2265
2265
  *
2266
- * • 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.
2266
+ * • mode='local' (default) — for SPECIFIC factual questions ("what does section 15 say about deposits?", "who is the Chief Counsel?"). FTS+vector RRF over individual document chunks. Returns precise excerpts with citations.
2267
2267
  *
2268
2268
  * • 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.
2269
2269
  *
@@ -2279,6 +2279,9 @@ export interface paths {
2279
2279
  * - User asks 'how is X connected to Y' → 'path' (with both entity IDs)
2280
2280
  * - User asks 'what's near entity X' → 'graph' (with srcEntityId)
2281
2281
  * - 'local' returned nothing useful and the question is broad → retry with 'ppr'
2282
+ * - User wants to FIND a named artefact ("the GTM plan", "DOC-123", a uuid) → artefactMetadataOnly:true
2283
+ *
2284
+ * ARTEFACT-METADATA MODE (artefactMetadataOnly:true): ignores `mode` entirely and matches title + friendly id + uuid across EVERY artefact type — documents, whiteboards, plans, tasks, improvements, compliance frameworks. Returns a typed navigable list ({ artefacts: [{ result_type, id, friendly_id, title, snippet, document_id, project_id, href }] }). It reads no document content and needs no knowledge graph: unlike every other mode it is NOT limited to what has been ingested, so it still finds artefacts in projects where the KG is switched off. Narrow it with artefactTypes. To search inside document BODIES use listDocuments (full-content grep).
2282
2285
  */
2283
2286
  post: operations["kg_search"];
2284
2287
  delete?: never;
@@ -2918,7 +2921,7 @@ export interface paths {
2918
2921
  put?: never;
2919
2922
  /**
2920
2923
  * createProject
2921
- * @description Create a new project inside a workspace. Mirrors the UI Create Project dialog. Auth: write on workspace + credential's `can_lifecycle` capability. Validates name (1..200) and description (0..2000); icon defaults to '📁' if omitted. Server-side limit gate via `can_create_project_in_workspace`. Rate limit 30/min.
2924
+ * @description Create a new project inside a workspace. Mirrors the UI Create Project dialog. Auth: write on workspace + credential's `can_lifecycle` capability. Validates name (1..200) and description (0..2000); icon defaults to a folder emoji if omitted. Server-side limit gate via `can_create_project_in_workspace`. Rate limit 30/min.
2922
2925
  */
2923
2926
  post: operations["createProject"];
2924
2927
  delete?: never;
@@ -3985,10 +3988,10 @@ export interface operations {
3985
3988
  /** @description Natural language description of what you want to do. */
3986
3989
  query?: string;
3987
3990
  /**
3988
- * @description Category filter.
3991
+ * @description Category filter. One of the 18 categories returned in each result's `category` field.
3989
3992
  * @enum {string}
3990
3993
  */
3991
- category?: "navigation" | "folders" | "documents" | "diagrams" | "images" | "data" | "improvements" | "plans" | "knowledge_graph" | "organization" | "members" | "teams" | "permissions" | "billing" | "kg_admin" | "settings" | "signup";
3994
+ category?: "navigation" | "folders" | "documents" | "diagrams" | "images" | "whiteboards" | "data" | "improvements" | "plans" | "knowledge_graph" | "organization" | "members" | "teams" | "permissions" | "billing" | "kg_admin" | "settings" | "signup";
3992
3995
  };
3993
3996
  };
3994
3997
  };
@@ -7894,6 +7897,12 @@ export interface operations {
7894
7897
  content: {
7895
7898
  "application/json": {
7896
7899
  projectId: string;
7900
+ /** @description Grep across title and friendlyId. Substring by default; a regular expression when isRegex is true. */
7901
+ query?: string;
7902
+ /** @description Treat `query` as a regular expression. */
7903
+ isRegex?: boolean;
7904
+ /** @description Match case exactly. Default false. */
7905
+ caseSensitive?: boolean;
7897
7906
  };
7898
7907
  };
7899
7908
  };
@@ -9411,10 +9420,10 @@ export interface operations {
9411
9420
  /** @description Documents to file. All must belong to the same project (a batch spanning projects is rejected). */
9412
9421
  items: {
9413
9422
  documentId: string;
9414
- /** @description Sort position among siblings. Non-negative integer. */
9415
- position: number;
9416
- /** @description Optional. MOVE the document into this folder; null moves it to the project root. Omit to leave its current folder untouched. The folder must exist and belong to the same project. */
9423
+ /** @description MOVE the document into this folder; null moves it to the project root. Omit to leave its current folder untouched. The folder must exist and belong to the same project. */
9417
9424
  folderId?: string | null;
9425
+ /** @description Optional. Sort position among siblings (non-negative integer). OMIT to let the server place it: appended to the end of the target folder when the folder changes, otherwise left where it is. Omitting is the norm when filing; supply positions only when you are deliberately ordering siblings, usually renumbering them 0, 1, 2…. */
9426
+ position?: number;
9418
9427
  }[];
9419
9428
  };
9420
9429
  };
@@ -10723,7 +10732,7 @@ export interface operations {
10723
10732
  user_impact?: string;
10724
10733
  why_now?: string;
10725
10734
  /** @description Acceptance criteria — ordered list of pass/fail statements that define "done" for this item. Each row is `{ id, text }` with server-stamped `updated_at / updated_by / updated_by_credential_name`. REPLACES the whole array on update. Echo back existing `id`s on rows you keep so attribution stamps survive. Bare strings are accepted for convenience (e.g. `["row 1", "row 2"]`) and auto-converted to `{ id, text }`. */
10726
- acceptance_criteria?: {
10735
+ acceptance_criteria?: (string | {
10727
10736
  /** @description Optional — server mints one if omitted. Preserve on edits. */
10728
10737
  id?: string;
10729
10738
  text: string;
@@ -10733,7 +10742,7 @@ export interface operations {
10733
10742
  updated_by?: string;
10734
10743
  /** @description Server-stamped credential label. Echo back unchanged. */
10735
10744
  updated_by_credential_name?: string;
10736
- }[];
10745
+ })[];
10737
10746
  /** @description Tick-box checklist shown above acceptance_criteria. The full array REPLACES the stored list on update, and array order = display order — to edit, fetch via getTask/getImprovement, modify, and send back the whole list. Operations: mark done with `completed: true`; un-mark with `completed: false`; add rows by appending `{ text }` (id is auto-minted); remove by omitting; reorder by rearranging. Echo back each existing `id` you keep so per-row attribution (who added/completed it, when) survives. */
10738
10747
  checklist?: {
10739
10748
  /** @description Optional — server mints one if omitted. Preserve on edits. */
@@ -10909,7 +10918,7 @@ export interface operations {
10909
10918
  user_impact?: string;
10910
10919
  why_now?: string;
10911
10920
  /** @description Acceptance criteria — ordered list of pass/fail statements that define "done" for this item. Each row is `{ id, text }` with server-stamped `updated_at / updated_by / updated_by_credential_name`. REPLACES the whole array on update. Echo back existing `id`s on rows you keep so attribution stamps survive. Bare strings are accepted for convenience (e.g. `["row 1", "row 2"]`) and auto-converted to `{ id, text }`. */
10912
- acceptance_criteria?: {
10921
+ acceptance_criteria?: (string | {
10913
10922
  /** @description Optional — server mints one if omitted. Preserve on edits. */
10914
10923
  id?: string;
10915
10924
  text: string;
@@ -10919,7 +10928,7 @@ export interface operations {
10919
10928
  updated_by?: string;
10920
10929
  /** @description Server-stamped credential label. Echo back unchanged. */
10921
10930
  updated_by_credential_name?: string;
10922
- }[];
10931
+ })[];
10923
10932
  /** @description Tick-box checklist shown above acceptance_criteria. The full array REPLACES the stored list on update, and array order = display order — to edit, fetch via getTask/getImprovement, modify, and send back the whole list. Operations: mark done with `completed: true`; un-mark with `completed: false`; add rows by appending `{ text }` (id is auto-minted); remove by omitting; reorder by rearranging. Echo back each existing `id` you keep so per-row attribution (who added/completed it, when) survives. */
10924
10933
  checklist?: {
10925
10934
  /** @description Optional — server mints one if omitted. Preserve on edits. */
@@ -11943,18 +11952,16 @@ export interface operations {
11943
11952
  requestBody?: {
11944
11953
  content: {
11945
11954
  "application/json": {
11946
- /** @description Search query — a name fragment or a friendly id. */
11955
+ /** @description Search query — meaning, a name fragment, or a friendly id (e.g. "IMP-2", "TAS-7"). */
11947
11956
  query: string;
11948
- /** @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. */
11949
- types?: ("document" | "whiteboard" | "improvement" | "task" | "plan" | "compliance")[];
11957
+ /** @description Narrow to one kind. Omit (or pass both) to search improvements and tasks together. Other artefact types are NOT accepted here — use kg_search with artefactMetadataOnly:true for those. */
11958
+ types?: ("improvement" | "task")[];
11950
11959
  /** @description Limit to a project. */
11951
11960
  projectId?: string;
11952
11961
  /** @description Limit to a workspace. */
11953
11962
  workspaceId?: string;
11954
- /** @description Max results (default 20 semantic / 30 cross-artefact, max 50). */
11963
+ /** @description Max results (default 20, max 50). */
11955
11964
  limit?: number;
11956
- /** @description Pagination offset (cross-artefact mode). */
11957
- offset?: number;
11958
11965
  };
11959
11966
  };
11960
11967
  };
@@ -13338,7 +13345,7 @@ export interface operations {
13338
13345
  user_impact?: string;
13339
13346
  why_now?: string;
13340
13347
  /** @description Acceptance criteria — ordered list of pass/fail statements that define "done" for this item. Each row is `{ id, text }` with server-stamped `updated_at / updated_by / updated_by_credential_name`. REPLACES the whole array on update. Echo back existing `id`s on rows you keep so attribution stamps survive. Bare strings are accepted for convenience (e.g. `["row 1", "row 2"]`) and auto-converted to `{ id, text }`. */
13341
- acceptance_criteria?: {
13348
+ acceptance_criteria?: (string | {
13342
13349
  /** @description Optional — server mints one if omitted. Preserve on edits. */
13343
13350
  id?: string;
13344
13351
  text: string;
@@ -13348,7 +13355,7 @@ export interface operations {
13348
13355
  updated_by?: string;
13349
13356
  /** @description Server-stamped credential label. Echo back unchanged. */
13350
13357
  updated_by_credential_name?: string;
13351
- }[];
13358
+ })[];
13352
13359
  /** @description Tick-box checklist shown above acceptance_criteria. The full array REPLACES the stored list on update, and array order = display order — to edit, fetch via getTask/getImprovement, modify, and send back the whole list. Operations: mark done with `completed: true`; un-mark with `completed: false`; add rows by appending `{ text }` (id is auto-minted); remove by omitting; reorder by rearranging. Echo back each existing `id` you keep so per-row attribution (who added/completed it, when) survives. */
13353
13360
  checklist?: {
13354
13361
  /** @description Optional — server mints one if omitted. Preserve on edits. */
@@ -13706,7 +13713,7 @@ export interface operations {
13706
13713
  user_impact?: string;
13707
13714
  why_now?: string;
13708
13715
  /** @description Acceptance criteria — ordered list of pass/fail statements that define "done" for this item. Each row is `{ id, text }` with server-stamped `updated_at / updated_by / updated_by_credential_name`. REPLACES the whole array on update. Echo back existing `id`s on rows you keep so attribution stamps survive. Bare strings are accepted for convenience (e.g. `["row 1", "row 2"]`) and auto-converted to `{ id, text }`. */
13709
- acceptance_criteria?: {
13716
+ acceptance_criteria?: (string | {
13710
13717
  /** @description Optional — server mints one if omitted. Preserve on edits. */
13711
13718
  id?: string;
13712
13719
  text: string;
@@ -13716,7 +13723,7 @@ export interface operations {
13716
13723
  updated_by?: string;
13717
13724
  /** @description Server-stamped credential label. Echo back unchanged. */
13718
13725
  updated_by_credential_name?: string;
13719
- }[];
13726
+ })[];
13720
13727
  /** @description Tick-box checklist shown above acceptance_criteria. The full array REPLACES the stored list on update, and array order = display order — to edit, fetch via getTask/getImprovement, modify, and send back the whole list. Operations: mark done with `completed: true`; un-mark with `completed: false`; add rows by appending `{ text }` (id is auto-minted); remove by omitting; reorder by rearranging. Echo back each existing `id` you keep so per-row attribution (who added/completed it, when) survives. */
13721
13728
  checklist?: {
13722
13729
  /** @description Optional — server mints one if omitted. Preserve on edits. */
@@ -14715,8 +14722,17 @@ export interface operations {
14715
14722
  requestBody?: {
14716
14723
  content: {
14717
14724
  "application/json": {
14718
- /** @description Natural-language query. Required for local/global/ppr; optional for graph (use srcEntityId instead). */
14725
+ /** @description Natural-language query. Required for local/global/ppr; optional for graph (use srcEntityId instead). With artefactMetadataOnly:true this is the artefact name, friendly id or uuid to find. */
14719
14726
  query?: string;
14727
+ /**
14728
+ * @description Find artefacts BY NAME/ID instead of retrieving knowledge. Matches title + friendly id + uuid only — never document content — across all artefact types, and does not require the knowledge graph to be enabled. Default false.
14729
+ * @default false
14730
+ */
14731
+ artefactMetadataOnly?: boolean;
14732
+ /** @description Only with artefactMetadataOnly:true. Restrict the search to these artefact types. Omit to search all of them. Unknown values are rejected rather than ignored. */
14733
+ artefactTypes?: ("document" | "whiteboard" | "improvement" | "task" | "plan" | "compliance")[];
14734
+ /** @description Only with artefactMetadataOnly:true. Skip this many results for paging. */
14735
+ offset?: number;
14720
14736
  /**
14721
14737
  * @description Retrieval strategy. See tool description for when to use each — strongly prefer 'global' for thematic/overview questions.
14722
14738
  * @default local
@@ -17444,7 +17460,7 @@ export interface operations {
17444
17460
  name: string;
17445
17461
  /** @description Optional description. */
17446
17462
  description?: string;
17447
- /** @description Optional emoji icon. Defaults to '📁' to match the UI. */
17463
+ /** @description Optional emoji icon. Defaults to a folder emoji to match the UI. */
17448
17464
  icon?: string;
17449
17465
  };
17450
17466
  };