@stablebaseline/sdk 0.5.1 → 0.5.3

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.
package/dist/index.d.cts CHANGED
@@ -34,7 +34,7 @@ interface paths {
34
34
  put?: never;
35
35
  /**
36
36
  * listDiagramTypes
37
- * @description List supported diagram types. Use the returned `type` field when calling insertDiagramInDocument.
37
+ * @description List supported diagram types. Pass `query` to search by name OR intent (keyword + semantic): e.g. 'circuit diagram', 'wiring harness', 'timing waveform', 'network topology', 'database schema'. Use the returned `type` field with getDiagramTypeGuide (DSL instructions + example) and insertDiagramInDocument / renderDiagram.
38
38
  */
39
39
  post: operations["listDiagramTypes"];
40
40
  delete?: never;
@@ -74,7 +74,7 @@ interface paths {
74
74
  put?: never;
75
75
  /**
76
76
  * listArchitectureIcons
77
- * @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).
77
+ * @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).
78
78
  */
79
79
  post: operations["listArchitectureIcons"];
80
80
  delete?: never;
@@ -234,7 +234,7 @@ interface paths {
234
234
  put?: never;
235
235
  /**
236
236
  * listWorkspaces
237
- * @description List workspaces you have access to. Supports query filtering by name/slug.
237
+ * @description List workspaces you have access to. Scope to one organisation with organisationId (a structural filter — use it rather than `query`, which only searches names/slugs). Supports query filtering by name/slug.
238
238
  */
239
239
  post: operations["listWorkspaces"];
240
240
  delete?: never;
@@ -374,7 +374,7 @@ interface paths {
374
374
  put?: never;
375
375
  /**
376
376
  * listDocuments
377
- * @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.
377
+ * @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. SCOPE HONESTY — read this before concluding something is absent: only documents that actually matched are returned (a document is never listed with matchCount 0 just because it was in scope), and the `grep` block reports `scannedDocuments` against `totalDocumentsInScope`. When `truncated` is true the search covered only part of the scope, so an absence is NOT proof; repeat with `scanOffset` set to the returned `nextScanOffset` until that field is gone, and union the results. A document too large to read is returned with `contentSearchSkipped: true` and NO matchCount, because its body was never searched.
378
378
  */
379
379
  post: operations["listDocuments"];
380
380
  delete?: never;
@@ -414,7 +414,7 @@ interface paths {
414
414
  put?: never;
415
415
  /**
416
416
  * getFolderHierarchy
417
- * @description Get the folder and document tree starting from a specific folder. Alias for getProjectHierarchy with folderId.
417
+ * @description Get the folder and document tree. Pass folderId for the subtree under one folder, or projectId for the project's ENTIRE folder tree from the root (no need to reassemble listFolders' flat list by parentId). Alias for getProjectHierarchy.
418
418
  */
419
419
  post: operations["getFolderHierarchy"];
420
420
  delete?: never;
@@ -454,7 +454,7 @@ interface paths {
454
454
  put?: never;
455
455
  /**
456
456
  * createDocument
457
- * @description Create a document from CDMD markdown (standard Markdown plus SB extensions — call getCdmdLanguageGuide if unfamiliar). The body goes in `cdmd` (`content` is accepted as an alias). Do not include DIAGRAM/IMAGE markers — insert them after with dedicated tools. Returns the new document's id and versionTimestamp (the optimistic-lock token for subsequent edits). Supports @-mentioning people: embed `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->` to notify a teammate. Use listAssignablePrincipals to look up the user_id from a name; mentions of users outside the project are silently dropped.
457
+ * @description Create a document from CDMD markdown (standard Markdown plus SB extensions — call getCdmdLanguageGuide if unfamiliar). The body goes in `cdmd` (`content` is accepted as an alias). A leading `---` YAML frontmatter block is stored and preserved: title/exported_at/generator are managed by the platform, and any other key you set (doc_type, authority_state, owner, conforms_to, …) round-trips untouched through reads and later edits. Do not include DIAGRAM/IMAGE markers — insert them after with dedicated tools. Returns the new document's id and versionTimestamp (the optimistic-lock token for subsequent edits). Supports @-mentioning people: embed `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->` to notify a teammate. Use listAssignablePrincipals to look up the user_id from a name; mentions of users outside the project are silently dropped.
458
458
  */
459
459
  post: operations["createDocument"];
460
460
  delete?: never;
@@ -694,7 +694,7 @@ interface paths {
694
694
  put?: never;
695
695
  /**
696
696
  * designDeckInWhiteboard
697
- * @description Create or refine a slide deck INSIDE an existing whiteboard by conversing with the AI design agent. Send a brief for a NEW deck, a change to an EXISTING one, or an answer to the agent's question. The agent builds a polished, on-brand deck and places it on the board; if the brief is ambiguous it asks ONE clarifying question (answer with the same sessionId). Returns immediately; poll getDeckReplyInWhiteboard for the result. Use for building or editing slide decks / presentations. WHITEBOARD IS REQUIRED: a deck always lives inside a whiteboard, so documentId (the whiteboard's id) is required. If you do NOT already have a whiteboard id, ASK THE USER which whiteboard they want the deck designed in — do NOT create a whiteboard automatically. Only call createWhiteboard first if the user explicitly asks for a brand-new board; otherwise use the id of the whiteboard they name. FIRST vs FOLLOW-UP: the first call (from nothing) builds; a follow-up call (an answer, a change, or a new instruction) passes the sessionId (or the deckId) plus the new message. kind:'deck' (default) is the premium on-brand HTML deck; kind:'express' builds the native, deterministic branded-executive deck directly on the whiteboard (faster, lower fidelity, one-shot, not conversational). COST + APPROVAL: a build costs 50 credits and an edit 10; a clarifying question is FREE. Call FIRST without confirm to get the exact cost plus the workspace balance, show it to the user, and only call again with confirm:true once they agree. The fee is auto-refunded if a turn produces no change or fails. Returns sessionId (the conversation), deckId (the deck), status, turnType, started, awaitingUser, needsConfirmation, insufficientCredits, and assistantMessage. Export the finished deck with exportFromWhiteboard.
697
+ * @description Create or refine a slide deck INSIDE an existing whiteboard by conversing with the AI design agent. Send a brief for a NEW deck, a change to an EXISTING one, or an answer to the agent's question. The agent builds a polished, on-brand deck and places it on the board; if the brief is ambiguous it asks ONE clarifying question (answer with the same sessionId). Returns immediately; poll getDeckReplyInWhiteboard for the result. Use for building or editing slide decks / presentations. WHITEBOARD IS REQUIRED: a deck always lives inside a whiteboard, so documentId (the whiteboard's id) is required. If you do NOT already have a whiteboard id, ASK THE USER which whiteboard they want the deck designed in — do NOT create a whiteboard automatically. Only call createWhiteboard first if the user explicitly asks for a brand-new board; otherwise use the id of the whiteboard they name. FIRST vs FOLLOW-UP: the first call (from nothing) builds; a follow-up call (an answer, a change, or a new instruction) passes the sessionId (or the deckId) plus the new message. kind:'deck' (default) is the premium on-brand HTML deck; kind:'express' builds the native, deterministic branded-executive deck directly on the whiteboard (faster, lower fidelity, one-shot, not conversational). COST + APPROVAL: a build costs 50 credits and an edit 10; a clarifying question is FREE. GENERATED IMAGES are extra and OFF by default: decks are type-only unless the user asks for visuals, in which case set imageCount (5 credits each, ceiling scales with slide count and plan tier, max 10) and the exact total is quoted before anything is charged — exactly that many images are produced, and the image surcharge auto-refunds if the build cannot deliver them. ADVANCED DECK BUILDING (optional, OFF by default): set advancedDeckBuilding:true to build the deck over several rounds of redraft and review by a panel of design, brand, accessibility and copy reviewers instead of one composer pass. It usually raises design quality, but it is not a guarantee. It is much slower and it costs more: a standard build takes roughly 2 to 8 minutes, advanced deck building takes roughly 15 to 20 minutes, and it adds 15 credits per depth level on top of the turn fee (advancedDeckBuildingDepth is 1 to 3, default 3, so +45 credits, making a 50-credit build cost 95). Only turn it on when the user asks for the highest quality and accepts the wait and the cost. Call FIRST without confirm to get the exact cost plus the workspace balance, show it to the user, and only call again with confirm:true once they agree. The fee is auto-refunded if a turn produces no change or fails. Returns sessionId (the conversation), deckId (the deck), status, turnType, started, awaitingUser, needsConfirmation, insufficientCredits, slideCount + slideCountClamped (the target the conversation now carries, and whether it was reduced to the maximum), advancedDeckBuilding (whether advanced deck building is on for this conversation), advancedDeckBuildingStatus, and assistantMessage. Export the finished deck with exportFromWhiteboard.
698
698
  */
699
699
  post: operations["designDeckInWhiteboard"];
700
700
  delete?: never;
@@ -734,7 +734,7 @@ interface paths {
734
734
  put?: never;
735
735
  /**
736
736
  * getDeckReplyInWhiteboard
737
- * @description Get the design agent's reply after calling designDeckInWhiteboard OR designIllustrationInWhiteboard: the status (thinking/building/ready) and EITHER the finished result (a deck's slide count + preview, or the placed illustration) OR a clarifying question to answer (call the SAME tool you started with, passing the sessionId + your answer). Poll until ready or a question appears. Give it the whiteboard documentId and the deckId (both returned by the tool you called). It returns the build status ('generating' while working, 'ready' when finished, 'failed' if it failed) plus, once ready, the slide count and a thumbnail image URL. IMPORTANT for the conversation: if the agent asked a CLARIFYING QUESTION instead of doing the work, this returns awaitingUser:true with pendingQuestion (and assistantMessage) — relay that question to the user, then call the SAME design tool again with the same sessionId and the user's answer as message to continue. It also returns the full conversation (history + status + pending question). A turn usually takes about 1 to 3 minutes, so poll every 15 to 30 seconds until it is 'ready' or awaitingUser is true. When ready, the deck or illustration has already been placed on the whiteboard; a deck can also be exported with exportFromWhiteboard. If a turn failed or produced no change, the user was not charged.
737
+ * @description Get the design agent's reply after calling designDeckInWhiteboard OR designIllustrationInWhiteboard: the status (thinking/building/ready) and EITHER the finished result (a deck's slide count + preview, or the placed illustration) OR a clarifying question to answer (call the SAME tool you started with, passing the sessionId + your answer). Poll until ready or a question appears. Give it the whiteboard documentId and the deckId (both returned by the tool you called). It returns the build status ('generating' while working, 'ready' when finished, 'failed' if it failed) plus, once ready, the slide count and a thumbnail image URL. IMPORTANT for the conversation: if the agent asked a CLARIFYING QUESTION instead of doing the work, this returns awaitingUser:true with pendingQuestion (and assistantMessage) — relay that question to the user, then call the SAME design tool again with the same sessionId and the user's answer as message to continue. It also returns the full conversation (history + status + pending question). While a turn is running it additionally returns live build state: stage, percent, feed (the agent's real per-step lines), slideTarget (the count it is building to), slides (the finished slides so far, each with a fetchable image url), partialHtml (the deck so far), and, when advanced deck building is on, advancedDeckBuildingProgress (the round-by-round reviewer scores; also emitted as the deprecated `jury` field for one release). Every one of those is optional and absent when there is nothing to report. A standard turn usually takes about 2 to 8 minutes, so poll every 15 to 30 seconds until it is 'ready' or awaitingUser is true; a turn running with advanced deck building takes roughly 15 to 20 minutes, so keep polling for that long before treating it as stuck. When ready, the deck or illustration has already been placed on the whiteboard; a deck can also be exported with exportFromWhiteboard. If a turn failed or produced no change, the user was not charged.
738
738
  */
739
739
  post: operations["getDeckReplyInWhiteboard"];
740
740
  delete?: never;
@@ -914,7 +914,7 @@ interface paths {
914
914
  put?: never;
915
915
  /**
916
916
  * addWhiteboardElements
917
- * @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.
917
+ * @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.
918
918
  */
919
919
  post: operations["addWhiteboardElements"];
920
920
  delete?: never;
@@ -1154,7 +1154,7 @@ interface paths {
1154
1154
  put?: never;
1155
1155
  /**
1156
1156
  * reorderDocuments
1157
- * @description Batch-reorder documents within a folder (or project root) by setting sibling positions. Pass [{documentId, position}, ...] where position is a non-negative integer; usually you renumber siblings sequentially as 0, 1, 2…. Position-only update — does not bump version or create a snapshot. To MOVE a document to a different folder, use editDocument({folderId, position}) instead.
1157
+ * @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).
1158
1158
  */
1159
1159
  post: operations["reorderDocuments"];
1160
1160
  delete?: never;
@@ -1434,7 +1434,7 @@ interface paths {
1434
1434
  put?: never;
1435
1435
  /**
1436
1436
  * createImprovement
1437
- * @description Create an improvement item in a project. Requires projectId and title. Auto-assigns friendly ID.
1437
+ * @description Create an improvement item in a project. Requires projectId and title. Auto-assigns friendly ID. Accepts every field updateImprovement accepts, so an item can be created complete in one call rather than create-then-update.
1438
1438
  */
1439
1439
  post: operations["createImprovement"];
1440
1440
  delete?: never;
@@ -1454,7 +1454,7 @@ interface paths {
1454
1454
  put?: never;
1455
1455
  /**
1456
1456
  * updateImprovement
1457
- * @description Update an improvement (or a task — tasks share this row, but prefer the symmetric updateTask alias when working from getTask). Supports the full field set including `checklist` (tick-boxes with due dates + completion attribution) and `acceptance_criteria` (objects with per-row updated_by/at attribution). Requires versionTimestamp from getImprovement for optimistic locking. Status transitions: blocked needs blocked_comment, rejected needs rejection_comment, done needs completion_comment. Assignment: pass `owner_id=<uuid>` to assign to a user, `owner_team_id=<uuid>` to assign to a team (mutually exclusive — a DB CHECK constraint enforces this). To unassign, pass `owner_id=null` AND `owner_team_id=null`. To switch from a user owner to a team owner, send `owner_id=null, owner_team_id=<uuid>` in the SAME call (sending only one side leaves the stale value and triggers the XOR check). Use listAssignablePrincipals or listTeams to discover valid IDs.
1457
+ * @description Update an improvement (or a task — tasks share this row, but prefer the symmetric updateTask alias when working from getTask). Supports the full field set including `checklist` (tick-boxes with due dates + completion attribution) and `acceptance_criteria` (objects with per-row updated_by/at attribution). Requires versionTimestamp from getImprovement for optimistic locking. Statuses are captured / in_progress / blocked / done / rejected / deferred, and FOUR of those are CLOSED: blocked, done, rejected, deferred. Entering one needs its comment (blocked needs blocked_comment, rejected needs rejection_comment, done needs completion_comment); leaving one for an open status needs reopened_comment — including blocked -> in_progress, which surprises people because `blocked` does not sound terminal. `metadata` MERGES into what is stored (null on a key deletes it); pass metadata_replace:true to overwrite the object wholesale. Assignment: pass `owner_id=<uuid>` to assign to a user, `owner_team_id=<uuid>` to assign to a team (mutually exclusive — a DB CHECK constraint enforces this). To unassign, pass `owner_id=null` AND `owner_team_id=null`. To switch from a user owner to a team owner, send `owner_id=null, owner_team_id=<uuid>` in the SAME call (sending only one side leaves the stale value and triggers the XOR check). Use listAssignablePrincipals or listTeams to discover valid IDs.
1458
1458
  */
1459
1459
  post: operations["updateImprovement"];
1460
1460
  delete?: never;
@@ -1978,7 +1978,7 @@ interface paths {
1978
1978
  put?: never;
1979
1979
  /**
1980
1980
  * createTask
1981
- * @description Create a task in a plan. Requires planId and title.
1981
+ * @description Create a task in a plan. Requires planId and title. Accepts every field updateTask accepts, so a task can be created complete in ONE call — no create-then-update, and no window in which other actors read a half-written record.
1982
1982
  */
1983
1983
  post: operations["createTask"];
1984
1984
  delete?: never;
@@ -2038,7 +2038,7 @@ interface paths {
2038
2038
  put?: never;
2039
2039
  /**
2040
2040
  * updateTask
2041
- * @description Update a task. Tasks share a row with improvements (`improvement_items` with `is_task=true`), so this is a thin alias over updateImprovement — every field on updateImprovement is supported, including `checklist`, `acceptance_criteria`, status transitions (blocked/rejected/done need their respective comments), dates, owner, percent_complete, etc. Requires versionTimestamp from getTask for optimistic locking. To edit checklist items: call getTask, modify the `checklist` array (preserving each row's `id` to keep its attribution stamps), and pass the full array back here — array order is the sort order. Assignment: pass `owner_id=<uuid>` to assign to a user, `owner_team_id=<uuid>` to assign to a team (mutually exclusive — the DB enforces with a CHECK constraint). To unassign, pass `owner_id=null` AND `owner_team_id=null`. To switch owner kind, send the new value AND null the old one in the SAME call.
2041
+ * @description Update a task. Tasks share a row with improvements (`improvement_items` with `is_task=true`), so this is a thin alias over updateImprovement — every field on updateImprovement is supported, including `checklist`, `acceptance_criteria`, dates, owner, percent_complete, etc. Requires versionTimestamp from getTask for optimistic locking. Statuses are captured / in_progress / blocked / done / rejected / deferred, and FOUR of those are CLOSED: blocked, done, rejected, deferred. Entering one needs its comment (blocked_comment / rejection_comment / completion_comment); leaving one for an open status needs reopened_comment — including blocked -> in_progress, which surprises people because `blocked` does not sound terminal. `metadata` MERGES into what is stored (null on a key deletes it); pass metadata_replace:true to overwrite the object wholesale. To edit checklist items: call getTask, modify the `checklist` array (preserving each row's `id` to keep its attribution stamps), and pass the full array back here — array order is the sort order. Assignment: pass `owner_id=<uuid>` to assign to a user, `owner_team_id=<uuid>` to assign to a team (mutually exclusive — the DB enforces with a CHECK constraint). To unassign, pass `owner_id=null` AND `owner_team_id=null`. To switch owner kind, send the new value AND null the old one in the SAME call.
2042
2042
  */
2043
2043
  post: operations["updateTask"];
2044
2044
  delete?: never;
@@ -2158,7 +2158,7 @@ interface paths {
2158
2158
  put?: never;
2159
2159
  /**
2160
2160
  * deleteTaskDependency
2161
- * @description Remove a task-dependency edge. Neither item's dates are changed.
2161
+ * @description Remove a task-dependency edge. Neither item's dates are changed. Needs the same 'write' plan permission as createTaskDependency, so an actor that can draw an edge can also undo it — the edge is fully recreatable from (predecessor, successor, type, lag).
2162
2162
  */
2163
2163
  post: operations["deleteTaskDependency"];
2164
2164
  delete?: never;
@@ -2262,7 +2262,7 @@ interface paths {
2262
2262
  *
2263
2263
  * PICK THE MODE THAT FITS THE QUERY:
2264
2264
  *
2265
- * • 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.
2265
+ * • 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.
2266
2266
  *
2267
2267
  * • 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.
2268
2268
  *
@@ -2917,7 +2917,7 @@ interface paths {
2917
2917
  put?: never;
2918
2918
  /**
2919
2919
  * createProject
2920
- * @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.
2920
+ * @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.
2921
2921
  */
2922
2922
  post: operations["createProject"];
2923
2923
  delete?: never;
@@ -3984,10 +3984,10 @@ interface operations {
3984
3984
  /** @description Natural language description of what you want to do. */
3985
3985
  query?: string;
3986
3986
  /**
3987
- * @description Category filter.
3987
+ * @description Category filter. One of the 18 categories returned in each result's `category` field.
3988
3988
  * @enum {string}
3989
3989
  */
3990
- category?: "navigation" | "folders" | "documents" | "diagrams" | "images" | "data" | "improvements" | "plans" | "knowledge_graph" | "organization" | "members" | "teams" | "permissions" | "billing" | "kg_admin" | "settings" | "signup";
3990
+ category?: "navigation" | "folders" | "documents" | "diagrams" | "images" | "whiteboards" | "data" | "improvements" | "plans" | "knowledge_graph" | "organization" | "members" | "teams" | "permissions" | "billing" | "kg_admin" | "settings" | "signup";
3991
3991
  };
3992
3992
  };
3993
3993
  };
@@ -4069,6 +4069,7 @@ interface operations {
4069
4069
  requestBody?: {
4070
4070
  content: {
4071
4071
  "application/json": {
4072
+ /** @description Keyword or intent, e.g. 'circuit', 'wiring harness', 'timing'. Semantic-backed: matches descriptions, not just names. */
4072
4073
  query?: string;
4073
4074
  enabledOnly?: boolean;
4074
4075
  limit?: number;
@@ -4579,6 +4580,8 @@ interface operations {
4579
4580
  /** @description Workspace UUID. Optional but recommended — when present, the result includes ALL org members; when omitted, only direct project grants + team-expanded users are returned. */
4580
4581
  workspaceId?: string;
4581
4582
  /** @description Optional ILIKE search filter — matched against display_name + email (users) and team name (teams). */
4583
+ query?: string;
4584
+ /** @description Deprecated alias for `query`, still accepted. Prefer `query` — that is the name every other list tool uses. */
4582
4585
  q?: string;
4583
4586
  /**
4584
4587
  * @description Filter to one principal kind. Default 'all' returns users first then teams.
@@ -4675,6 +4678,8 @@ interface operations {
4675
4678
  /** @description Workspace UUID. The parent organization is resolved from v_workspaces. */
4676
4679
  workspaceId?: string;
4677
4680
  /** @description Optional ILIKE search on team name/slug. */
4681
+ query?: string;
4682
+ /** @description Deprecated alias for `query`, still accepted. Prefer `query` — that is the name every other list tool uses. */
4678
4683
  q?: string;
4679
4684
  /** @description When true, each team gets a `members` array (user_id, role, joined_at). Capped at 500 total members across the page. Default false. */
4680
4685
  includeMembers?: boolean;
@@ -4934,6 +4939,10 @@ interface operations {
4934
4939
  requestBody?: {
4935
4940
  content: {
4936
4941
  "application/json": {
4942
+ /** @description Return only workspaces in this organisation. Use listOrganisations to find the id. (organizationId is accepted as a spelling alias.) */
4943
+ organisationId?: string;
4944
+ /** @description Spelling alias for organisationId. */
4945
+ organizationId?: string;
4937
4946
  query?: string;
4938
4947
  limit?: number;
4939
4948
  offset?: number;
@@ -5565,7 +5574,10 @@ interface operations {
5565
5574
  /** @description Cap on matching lines returned per document. 1-20, default 5. */
5566
5575
  maxMatchesPerDocument?: number;
5567
5576
  limit?: number;
5577
+ /** @description Pagination offset over the MATCHES. When searching, use scanOffset (not this) to reach documents the scan has not covered. */
5568
5578
  offset?: number;
5579
+ /** @description Search-only. Where to start the document scan within the scope. One call examines a bounded window; when the response reports truncated:true it also returns nextScanOffset — repeat with scanOffset set to that value until nextScanOffset is absent, and union the results, to search a scope larger than one window exhaustively. */
5580
+ scanOffset?: number;
5569
5581
  /** @description ISO 8601 date filter (from). */
5570
5582
  fromDate?: string;
5571
5583
  /** @description ISO 8601 date filter (to). */
@@ -5752,8 +5764,10 @@ interface operations {
5752
5764
  requestBody?: {
5753
5765
  content: {
5754
5766
  "application/json": {
5755
- /** @description The folder ID to start from. */
5756
- folderId: string;
5767
+ /** @description Return the whole project's folder tree from the root. Provide this or folderId. */
5768
+ projectId?: string;
5769
+ /** @description The folder ID to start from. Omit and pass projectId to get the project root hierarchy. */
5770
+ folderId?: string;
5757
5771
  /** @description Max nesting depth. Default: 10, max: 20. */
5758
5772
  maxDepth?: number;
5759
5773
  /** @description Include documents. Default: true. */
@@ -5847,7 +5861,9 @@ interface operations {
5847
5861
  requestBody?: {
5848
5862
  content: {
5849
5863
  "application/json": {
5850
- /** @description The document ID to read. */
5864
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
5865
+ projectId?: string;
5866
+ /** @description The document ID to read. Accepts either the UUID or the friendly id (e.g. DOC-815); friendly ids are resolved within your organisation. */
5851
5867
  documentId: string;
5852
5868
  /** @description Lines to skip from start. Default: 0. */
5853
5869
  offset?: number;
@@ -6032,15 +6048,19 @@ interface operations {
6032
6048
  requestBody?: {
6033
6049
  content: {
6034
6050
  "application/json": {
6051
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
6052
+ projectId?: string;
6035
6053
  documentId: string;
6036
6054
  /** @description New title. */
6037
6055
  title?: string;
6038
- /** @description Move to this folder. */
6039
- folderId?: string;
6040
- /** @description Sort position within the parent folder. Use to reposition a single document. For batch sibling reorder, use reorderDocuments. */
6056
+ /** @description MOVE the document into this folder (null moves it to the project root). Send it with patches:[] to file the document without touching its content — a folder-only move updates folder_id, creates NO version-history entry, and does not bump the document version. To move many documents at once use reorderDocuments, which takes folderId per item. */
6057
+ folderId?: string | null;
6058
+ /** @description Sort position within the parent folder. Use to reposition a single document; like folderId, a position-only change creates no version. For batch sibling reorder/move, use reorderDocuments. */
6041
6059
  position?: number;
6042
6060
  /** @description Optimistic-lock token from getDocument() or any mutating tool's response. Required unless dryRun:true. (Alias accepted: documentVersionTimestamp.) */
6043
6061
  versionTimestamp?: number;
6062
+ /** @description Legacy integer version guard, checked in addition to versionTimestamp. Prefer versionTimestamp — this exists for older clients and is optional. */
6063
+ expectedVersion?: number;
6044
6064
  /** @description If true, apply the patches and RETURN the resulting document text without saving — no version bump, no lock required. Use to preview/verify a patch before committing. Default false. */
6045
6065
  dryRun?: boolean;
6046
6066
  /** @description Version history summary. */
@@ -6144,6 +6164,8 @@ interface operations {
6144
6164
  requestBody?: {
6145
6165
  content: {
6146
6166
  "application/json": {
6167
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
6168
+ projectId?: string;
6147
6169
  documentId: string;
6148
6170
  /** @description Text to search for. */
6149
6171
  find: string;
@@ -6321,6 +6343,8 @@ interface operations {
6321
6343
  requestBody?: {
6322
6344
  content: {
6323
6345
  "application/json": {
6346
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
6347
+ projectId?: string;
6324
6348
  documentId: string;
6325
6349
  /** @description Optimistic-lock token: the document's versionTimestamp from getDocument() or any mutating tool's response. (Alias accepted: versionTimestamp.) */
6326
6350
  documentVersionTimestamp?: number;
@@ -6636,6 +6660,8 @@ interface operations {
6636
6660
  content: {
6637
6661
  "application/json": {
6638
6662
  documentId: string;
6663
+ /** @description Optional. Narrows a friendly-id lookup to one project. Ignored when documentId is a UUID. */
6664
+ projectId?: string;
6639
6665
  };
6640
6666
  };
6641
6667
  };
@@ -6924,6 +6950,8 @@ interface operations {
6924
6950
  tags?: string[];
6925
6951
  /** @description Optional URL of a reference image the component should match; the critic compares the render to it. */
6926
6952
  referenceImageUrl?: string;
6953
+ /** @description Optional brand kit id (from listBrandKits) to theme the component. If omitted, the organisation's effective brand is used. */
6954
+ brandKitId?: string;
6927
6955
  /** @description Redesign even if a component with this key already exists (default false = reuse). */
6928
6956
  force?: boolean;
6929
6957
  };
@@ -7100,7 +7128,7 @@ interface operations {
7100
7128
  "application/json": {
7101
7129
  /** @description The whiteboard the deck lives in. REQUIRED: a deck cannot exist without a whiteboard, and this is that whiteboard's id. If you do not already have a whiteboard id, ASK THE USER which whiteboard to design the deck in — never create one automatically. Only call createWhiteboard first if the user explicitly wants a new board. */
7102
7130
  documentId: string;
7103
- /** @description This turn's message in plain language: the design brief on the first turn, an edit instruction later, or the user's ANSWER to a clarifying question the agent asked. On a follow-up turn, pass this together with the sessionId (or deckId) from the earlier call. */
7131
+ /** @description This turn's message in plain language: the design brief on the first turn, an edit instruction later, or the user's ANSWER to a clarifying question the agent asked. On a follow-up turn, pass this together with the sessionId (or deckId) from the earlier call. If the user mentioned how many slides they want, ALSO pass slideCount with that number — never leave the count only in prose, and never outline more slides in this message than slideCount. */
7104
7132
  message: string;
7105
7133
  /** @description The design conversation to continue, as returned by an earlier designDeckInWhiteboard call. Pass it together with message to answer a question, make an edit, or send a follow-up. Omit on the very first call to start a new conversation. */
7106
7134
  sessionId?: string;
@@ -7115,8 +7143,14 @@ interface operations {
7115
7143
  title?: string;
7116
7144
  /** @description Optional brand kit id (from listBrandKits) to theme the deck. If omitted, the organisation's effective brand is used. */
7117
7145
  brandKitId?: string;
7118
- /** @description Optional target number of slides for a build turn (the composer adjusts to fit the story). Typical 6 to 12. */
7146
+ /** @description The number of slides to build — a hard requirement: the deck is built with exactly this many slides. SET THIS whenever the user states or implies a count, EXACT OR APPROXIMATE: '12 slides' → 12, 'about 15' / '15 or so' → 15, 'no more than 10' → 10. Never expand the user's number: if they said 'about 15', pass 15 and shape the brief to fit 15 — outlining 19 sections in the message does not raise the count, it just fights this parameter. It is PERSISTED on the conversation, so send it ONCE (on the turn that states it) and every later build turn of the same conversation carries it automatically; send it again only to CHANGE the target. It is honoured on edit turns too ('cut it to 8 slides'). Anything above the 30-slide maximum is reduced to 30 and the reduction is stated back in the response. Omit ONLY when the user gave no count at all; the designer then chooses (typical 6 to 12). */
7119
7147
  slideCount?: number;
7148
+ /** @description How many AI-GENERATED images this turn may produce. DEFAULT IS 0 — decks are type-only unless the user asks for visuals. SET THIS when the user wants imagery: 'a cover image' → 1, 'a few images' → 2, 'image-led / very visual' → omit nothing and pass a higher number. Each image costs 5 extra credits, quoted upfront in the confirmation (base fee + images), and EXACTLY this many are produced — never more, never fewer (the image surcharge is auto-refunded if the build cannot deliver them). The ceiling scales with the deck (about one image per three slides, so a 30-slide deck tops out at 10) and with the plan tier; anything above the ceiling is reduced and the reduction is stated back. If omitted, the count is derived conservatively from the user's wording (silence = 0). */
7149
+ imageCount?: number;
7150
+ /** @description Optional, OFF by default. Build the deck with ADVANCED DECK BUILDING: instead of one composer pass, the deck is redrafted and reviewed over several rounds by a panel of design, brand, accessibility and copy reviewers, each round scoring the deck and listing what must be fixed. It usually produces a higher-quality deck, but it is not a guarantee. TIME: a standard build takes roughly 2 to 8 minutes; advanced deck building takes roughly 15 to 20 minutes. COST: 15 extra credits per depth level on top of the turn fee, so the default depth of 3 adds 45 credits and makes a 50-credit build cost 95. This is the user's deliberate choice, so only switch it on when they have asked for the best possible deck and accepted the wait and the cost. Quote the turn FIRST (call without confirm) so the user sees the real total before approving. Set it once and it is remembered for the rest of the conversation; pass false to turn it off again. */
7151
+ advancedDeckBuilding?: boolean;
7152
+ /** @description Optional. How many redraft-and-review rounds advanced deck building may run: 1 to 3, default 3. Each round is a full redraft plus four reviews, adds roughly 5 minutes, and costs 15 credits (depth 1 = +15, depth 2 = +30, depth 3 = +45). Ignored unless advancedDeckBuilding is true. */
7153
+ advancedDeckBuildingDepth?: number;
7120
7154
  /** @description Optional reference images for THIS turn (up to 8; images only). The agent lifts palette, layout, and tone from them (it does not pixel-copy). Non-image attachments are ignored. */
7121
7155
  attachments?: {
7122
7156
  /** @description A public https URL to the image. */
@@ -7127,6 +7161,8 @@ interface operations {
7127
7161
  mediaType?: string;
7128
7162
  /** @description Optional human-readable name for the image. */
7129
7163
  name?: string;
7164
+ /** @description Optional attachment type hint, passed through to the design worker. */
7165
+ type?: string;
7130
7166
  }[];
7131
7167
  /** @description Set true ONLY after the user has approved the cost (50 for a build, 10 for an edit). Leave unset/false on the first call of a turn to receive the cost quote plus balance. A clarifying question turn is never charged. */
7132
7168
  confirm?: boolean;
@@ -7233,6 +7269,8 @@ interface operations {
7233
7269
  mediaType?: string;
7234
7270
  /** @description Optional human-readable name for the image. */
7235
7271
  name?: string;
7272
+ /** @description Optional attachment type hint, passed through to the design worker. */
7273
+ type?: string;
7236
7274
  }[];
7237
7275
  /** @description Set true ONLY after the user has approved the cost (50 for a build, 10 for an edit). Leave unset/false on the first call of a turn to receive the cost quote plus balance. A clarifying question turn is never charged. */
7238
7276
  confirm?: boolean;
@@ -7509,6 +7547,11 @@ interface operations {
7509
7547
  label: string;
7510
7548
  /** @description Optional stable id; one is minted if omitted. */
7511
7549
  id?: string;
7550
+ /**
7551
+ * @description Optional starting status sticker. Default: pending.
7552
+ * @enum {string}
7553
+ */
7554
+ status?: "pending" | "active" | "done";
7512
7555
  }[];
7513
7556
  /** @description Optional per-meeting settings: { language (BCP-47, e.g. 'en'), sttProvider ('assemblyai' default, or 'captions'), presentMode ('off' default, or 'camera'/'screenshare' to stream the live board back into the meeting), botName (override the default '{Org} Scribe (Stable Baseline)') }. */
7514
7557
  settings?: {
@@ -7931,6 +7974,9 @@ interface operations {
7931
7974
  requestBody?: {
7932
7975
  content: {
7933
7976
  "application/json": {
7977
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
7978
+ projectId?: string;
7979
+ /** @description Accepts either the UUID or the friendly id (e.g. WBD-12); friendly ids are resolved within your organisation. */
7934
7980
  documentId: string;
7935
7981
  /** @description When true, returns the full Excalidraw scene so it can be modified and written back. */
7936
7982
  includeElements?: boolean;
@@ -8015,6 +8061,8 @@ interface operations {
8015
8061
  requestBody?: {
8016
8062
  content: {
8017
8063
  "application/json": {
8064
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
8065
+ projectId?: string;
8018
8066
  documentId: string;
8019
8067
  /** @description Elements to write. For mode 'patch', each may be a partial { id, ...changedFields } merged into the matching element by id; full Excalidraw elements for 'replace'/'append' (or new ids in 'patch'). */
8020
8068
  elements?: Record<string, never>[];
@@ -8114,6 +8162,8 @@ interface operations {
8114
8162
  requestBody?: {
8115
8163
  content: {
8116
8164
  "application/json": {
8165
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
8166
+ projectId?: string;
8117
8167
  documentId: string;
8118
8168
  /** @description Non-empty array of shape specs to append. Prefer stencils / sticky notes / architecture icons over raw rectangles wherever a standard form fits (see the `type` enum below and the tool description). */
8119
8169
  shapes: ({
@@ -8405,6 +8455,12 @@ interface operations {
8405
8455
  fileName?: string;
8406
8456
  /** @description Lock the placed image so it cannot be moved, resized, or deleted by hand (e.g. a deck-owned framed slide image that changes only via the deck conversation). Defaults to false. */
8407
8457
  locked?: boolean;
8458
+ /** @description Optional plain-language description of the image, stored on the element for accessibility and so agents reading the board later know what it depicts. */
8459
+ nlDescription?: string;
8460
+ /** @description Arbitrary Excalidraw customData stored on the element (e.g. { deckId } so a board image resolves back to its source deck). Merged with any builder-set customData. */
8461
+ customData?: {
8462
+ [key: string]: unknown;
8463
+ };
8408
8464
  };
8409
8465
  };
8410
8466
  };
@@ -8699,6 +8755,8 @@ interface operations {
8699
8755
  requestBody?: {
8700
8756
  content: {
8701
8757
  "application/json": {
8758
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
8759
+ projectId?: string;
8702
8760
  /** @description The whiteboard's documentId. */
8703
8761
  documentId: string;
8704
8762
  /** @description Rows as arrays of cell strings. If headers is omitted, the first row is treated as the header row. */
@@ -8885,7 +8943,9 @@ interface operations {
8885
8943
  requestBody?: {
8886
8944
  content: {
8887
8945
  "application/json": {
8888
- /** @description The whiteboard's documentId. */
8946
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
8947
+ projectId?: string;
8948
+ /** @description The whiteboard's documentId. Accepts either the UUID or the friendly id (e.g. WBD-12); friendly ids are resolved within your organisation. */
8889
8949
  documentId: string;
8890
8950
  /** @description Render only these element ids (plus their bound labels + group peers) instead of the whole board. */
8891
8951
  elementIds?: string[];
@@ -8989,6 +9049,8 @@ interface operations {
8989
9049
  content: {
8990
9050
  "application/json": {
8991
9051
  documentId: string;
9052
+ /** @description Optional. Narrows a friendly-id lookup to one project. Ignored when documentId is a UUID. */
9053
+ projectId?: string;
8992
9054
  };
8993
9055
  };
8994
9056
  };
@@ -9345,10 +9407,13 @@ interface operations {
9345
9407
  requestBody?: {
9346
9408
  content: {
9347
9409
  "application/json": {
9348
- /** @description List of document position updates. All documents must belong to the same project. */
9410
+ /** @description Documents to file. All must belong to the same project (a batch spanning projects is rejected). */
9349
9411
  items: {
9350
9412
  documentId: string;
9351
- position: number;
9413
+ /** @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. */
9414
+ folderId?: string | null;
9415
+ /** @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…. */
9416
+ position?: number;
9352
9417
  }[];
9353
9418
  };
9354
9419
  };
@@ -9431,6 +9496,9 @@ interface operations {
9431
9496
  requestBody?: {
9432
9497
  content: {
9433
9498
  "application/json": {
9499
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
9500
+ projectId?: string;
9501
+ /** @description Accepts either the UUID or the friendly id (e.g. DOC-815); friendly ids are resolved within your organisation. */
9434
9502
  documentId: string;
9435
9503
  /** @description Filter to a specific version. */
9436
9504
  versionNumber?: number;
@@ -9611,6 +9679,8 @@ interface operations {
9611
9679
  requestBody?: {
9612
9680
  content: {
9613
9681
  "application/json": {
9682
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
9683
+ projectId?: string;
9614
9684
  documentId: string;
9615
9685
  /** @description Original filename (e.g. screenshot.png). */
9616
9686
  fileName: string;
@@ -9699,6 +9769,8 @@ interface operations {
9699
9769
  requestBody?: {
9700
9770
  content: {
9701
9771
  "application/json": {
9772
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
9773
+ projectId?: string;
9702
9774
  documentId: string;
9703
9775
  /** @description Optimistic-lock token: the document's versionTimestamp from getDocument() or any mutating tool's response. (Alias accepted: versionTimestamp.) */
9704
9776
  documentVersionTimestamp?: number;
@@ -9991,6 +10063,8 @@ interface operations {
9991
10063
  requestBody?: {
9992
10064
  content: {
9993
10065
  "application/json": {
10066
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
10067
+ projectId?: string;
9994
10068
  documentId: string;
9995
10069
  /** @description Original filename (e.g. sales-data.csv). Extension auto-detects content type. */
9996
10070
  fileName: string;
@@ -10077,6 +10151,8 @@ interface operations {
10077
10151
  requestBody?: {
10078
10152
  content: {
10079
10153
  "application/json": {
10154
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
10155
+ projectId?: string;
10080
10156
  documentId: string;
10081
10157
  /** @description Attachment ID to delete. */
10082
10158
  attachmentId: string;
@@ -10541,6 +10617,9 @@ interface operations {
10541
10617
  requestBody?: {
10542
10618
  content: {
10543
10619
  "application/json": {
10620
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
10621
+ projectId?: string;
10622
+ /** @description Accepts either the UUID or the friendly id (e.g. IMP-42); friendly ids are resolved within your organisation. */
10544
10623
  improvementId: string;
10545
10624
  };
10546
10625
  };
@@ -10625,7 +10704,7 @@ interface operations {
10625
10704
  "application/json": {
10626
10705
  projectId: string;
10627
10706
  title: string;
10628
- /** @description Type. Default: enhancement. Valid values: feature, bug, tech_debt, architecture_gap, documentation_gap, risk, enhancement, task. Setting type='task' makes the row a task (TAS- prefix); any other type makes it a non-task improvement (IMP- prefix). */
10707
+ /** @description Type. Default: enhancement. Valid values: feature, bug, tech_debt, architecture_gap, documentation_gap, risk, enhancement, task. Despite the tool's name there is no 'improvement' value — pass it and it is accepted as an alias for 'enhancement', which is also the default. Setting type='task' makes the row a task (TAS- prefix); any other type makes it a non-task improvement (IMP- prefix). */
10629
10708
  type?: string;
10630
10709
  /** @description Priority. Default: medium. */
10631
10710
  priority?: string;
@@ -10643,11 +10722,17 @@ interface operations {
10643
10722
  user_impact?: string;
10644
10723
  why_now?: string;
10645
10724
  /** @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 }`. */
10646
- acceptance_criteria?: {
10725
+ acceptance_criteria?: (string | {
10647
10726
  /** @description Optional — server mints one if omitted. Preserve on edits. */
10648
10727
  id?: string;
10649
10728
  text: string;
10650
- }[];
10729
+ /** @description Server-stamped. Echo back unchanged; ignored on new rows. */
10730
+ updated_at?: string;
10731
+ /** @description Server-stamped user id. Echo back unchanged. */
10732
+ updated_by?: string;
10733
+ /** @description Server-stamped credential label. Echo back unchanged. */
10734
+ updated_by_credential_name?: string;
10735
+ })[];
10651
10736
  /** @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. */
10652
10737
  checklist?: {
10653
10738
  /** @description Optional — server mints one if omitted. Preserve on edits. */
@@ -10657,6 +10742,18 @@ interface operations {
10657
10742
  due_date?: string;
10658
10743
  /** @description true = ticked, false/omitted = not done. Server stamps timestamp + actor. */
10659
10744
  completed?: boolean;
10745
+ /** @description Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent. */
10746
+ completed_at?: string;
10747
+ /** @description Server-stamped user id. Echo back unchanged. */
10748
+ completed_by?: string;
10749
+ /** @description Server-stamped credential label. Echo back unchanged. */
10750
+ completed_by_credential_name?: string;
10751
+ /** @description Server-stamped. Echo back unchanged; ignored on new rows. */
10752
+ updated_at?: string;
10753
+ /** @description Server-stamped user id. Echo back unchanged. */
10754
+ updated_by?: string;
10755
+ /** @description Server-stamped credential label. Echo back unchanged. */
10756
+ updated_by_credential_name?: string;
10660
10757
  }[];
10661
10758
  constraints?: string[];
10662
10759
  non_goals?: string[];
@@ -10696,6 +10793,12 @@ interface operations {
10696
10793
  wbs_code?: string;
10697
10794
  /** @description Progress percentage (0-100). Null means not tracked. */
10698
10795
  percent_complete?: number;
10796
+ source_channel?: string;
10797
+ impacted_repositories?: string[];
10798
+ /** @description Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs). */
10799
+ relationships?: Record<string, never>;
10800
+ /** @description Free-form JSON stored alongside the item. On updateImprovement this MERGES rather than replaces. */
10801
+ metadata?: Record<string, never>;
10699
10802
  };
10700
10803
  };
10701
10804
  };
@@ -10777,6 +10880,8 @@ interface operations {
10777
10880
  requestBody?: {
10778
10881
  content: {
10779
10882
  "application/json": {
10883
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
10884
+ projectId?: string;
10780
10885
  improvementId: string;
10781
10886
  /** @description Version timestamp from getImprovement() for optimistic locking. */
10782
10887
  versionTimestamp: number;
@@ -10803,11 +10908,17 @@ interface operations {
10803
10908
  user_impact?: string;
10804
10909
  why_now?: string;
10805
10910
  /** @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 }`. */
10806
- acceptance_criteria?: {
10911
+ acceptance_criteria?: (string | {
10807
10912
  /** @description Optional — server mints one if omitted. Preserve on edits. */
10808
10913
  id?: string;
10809
10914
  text: string;
10810
- }[];
10915
+ /** @description Server-stamped. Echo back unchanged; ignored on new rows. */
10916
+ updated_at?: string;
10917
+ /** @description Server-stamped user id. Echo back unchanged. */
10918
+ updated_by?: string;
10919
+ /** @description Server-stamped credential label. Echo back unchanged. */
10920
+ updated_by_credential_name?: string;
10921
+ })[];
10811
10922
  /** @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. */
10812
10923
  checklist?: {
10813
10924
  /** @description Optional — server mints one if omitted. Preserve on edits. */
@@ -10817,6 +10928,18 @@ interface operations {
10817
10928
  due_date?: string;
10818
10929
  /** @description true = ticked, false/omitted = not done. Server stamps timestamp + actor. */
10819
10930
  completed?: boolean;
10931
+ /** @description Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent. */
10932
+ completed_at?: string;
10933
+ /** @description Server-stamped user id. Echo back unchanged. */
10934
+ completed_by?: string;
10935
+ /** @description Server-stamped credential label. Echo back unchanged. */
10936
+ completed_by_credential_name?: string;
10937
+ /** @description Server-stamped. Echo back unchanged; ignored on new rows. */
10938
+ updated_at?: string;
10939
+ /** @description Server-stamped user id. Echo back unchanged. */
10940
+ updated_by?: string;
10941
+ /** @description Server-stamped credential label. Echo back unchanged. */
10942
+ updated_by_credential_name?: string;
10820
10943
  }[];
10821
10944
  constraints?: string[];
10822
10945
  non_goals?: string[];
@@ -10842,11 +10965,14 @@ interface operations {
10842
10965
  rejection_comment?: string;
10843
10966
  /** @description Required when status=done. */
10844
10967
  completion_comment?: string;
10845
- /** @description Required when reopening from blocked/rejected/done/deferred. */
10968
+ /** @description Required when moving OUT of a closed status. The closed set is blocked, done, rejected and deferred — note that `blocked` counts as closed, so blocked -> in_progress needs this comment. */
10846
10969
  reopened_comment?: string;
10847
- /** @description Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs). */
10970
+ /** @description Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs). REPLACES the stored object wholesale — read it first and send the complete set. */
10848
10971
  relationships?: Record<string, never>;
10972
+ /** @description Free-form JSON. MERGES into the stored object key by key: keys you don't send are left alone, and sending a key with value null deletes it. Send metadata_replace:true to overwrite the whole object instead. (Merging is the default so a partial write can never destroy a sibling key written by another actor.) */
10849
10973
  metadata?: Record<string, never>;
10974
+ /** @description Opt out of the metadata merge: true means the object you send REPLACES everything stored, deleting any key you omit. Default false. */
10975
+ metadata_replace?: boolean;
10850
10976
  /** @description Link to plan. Null to unlink. */
10851
10977
  plan_id?: string;
10852
10978
  /** @description Assign to phase. Null to unassign. */
@@ -10938,6 +11064,8 @@ interface operations {
10938
11064
  requestBody?: {
10939
11065
  content: {
10940
11066
  "application/json": {
11067
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
11068
+ projectId?: string;
10941
11069
  improvementId: string;
10942
11070
  };
10943
11071
  };
@@ -11452,6 +11580,8 @@ interface operations {
11452
11580
  requestBody?: {
11453
11581
  content: {
11454
11582
  "application/json": {
11583
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
11584
+ projectId?: string;
11455
11585
  improvementId: string;
11456
11586
  /** @description Summary of the evidence. */
11457
11587
  summary: string;
@@ -11546,6 +11676,8 @@ interface operations {
11546
11676
  requestBody?: {
11547
11677
  content: {
11548
11678
  "application/json": {
11679
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
11680
+ projectId?: string;
11549
11681
  improvementId: string;
11550
11682
  /** @description Type: comment, agent_update, field_change. Default: comment. */
11551
11683
  activityType?: string;
@@ -12005,6 +12137,9 @@ interface operations {
12005
12137
  requestBody?: {
12006
12138
  content: {
12007
12139
  "application/json": {
12140
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
12141
+ projectId?: string;
12142
+ /** @description Accepts either the UUID or the friendly id (e.g. PLN-3); friendly ids are resolved within your organisation. */
12008
12143
  planId: string;
12009
12144
  };
12010
12145
  };
@@ -12187,6 +12322,8 @@ interface operations {
12187
12322
  requestBody?: {
12188
12323
  content: {
12189
12324
  "application/json": {
12325
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
12326
+ projectId?: string;
12190
12327
  planId: string;
12191
12328
  /** @description Version timestamp from getPlan() for optimistic locking. */
12192
12329
  versionTimestamp: number;
@@ -12287,6 +12424,8 @@ interface operations {
12287
12424
  requestBody?: {
12288
12425
  content: {
12289
12426
  "application/json": {
12427
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
12428
+ projectId?: string;
12290
12429
  planId: string;
12291
12430
  };
12292
12431
  };
@@ -12451,6 +12590,9 @@ interface operations {
12451
12590
  requestBody?: {
12452
12591
  content: {
12453
12592
  "application/json": {
12593
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
12594
+ projectId?: string;
12595
+ /** @description Accepts either the UUID or the friendly id (e.g. PHA-7); friendly ids are resolved within your organisation. */
12454
12596
  phaseId: string;
12455
12597
  };
12456
12598
  };
@@ -12634,6 +12776,8 @@ interface operations {
12634
12776
  requestBody?: {
12635
12777
  content: {
12636
12778
  "application/json": {
12779
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
12780
+ projectId?: string;
12637
12781
  phaseId: string;
12638
12782
  /** @description Version timestamp from getPlanPhase() for optimistic locking. */
12639
12783
  versionTimestamp: number;
@@ -12733,6 +12877,8 @@ interface operations {
12733
12877
  requestBody?: {
12734
12878
  content: {
12735
12879
  "application/json": {
12880
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
12881
+ projectId?: string;
12736
12882
  phaseId: string;
12737
12883
  };
12738
12884
  };
@@ -12901,6 +13047,8 @@ interface operations {
12901
13047
  requestBody?: {
12902
13048
  content: {
12903
13049
  "application/json": {
13050
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
13051
+ projectId?: string;
12904
13052
  planId: string;
12905
13053
  /** @description Type: comment, agent_update, field_change. Default: comment. */
12906
13054
  activityType?: string;
@@ -13170,18 +13318,36 @@ interface operations {
13170
13318
  /** @description Phase to assign to. */
13171
13319
  phaseId?: string;
13172
13320
  description?: string;
13173
- /** @description Type. Default: task. Tasks created in plans are typed 'task' (friendly_id prefix TAS-). Override only if you want the row to appear as a non-task improvement (IMP- prefix). */
13321
+ /** @description Type. Default: task. Tasks created in plans are typed 'task' (friendly_id prefix TAS-). Override only if you want the row to appear as a non-task improvement (IMP- prefix). Valid values: feature, bug, tech_debt, architecture_gap, documentation_gap, risk, enhancement, task. */
13174
13322
  type?: string;
13175
13323
  /** @description Initial status. Default: captured. */
13176
13324
  status?: string;
13177
13325
  /** @description Priority. Default: medium. */
13178
13326
  priority?: string;
13327
+ /** @description e.g. this_week, this_month, this_quarter. */
13328
+ urgency?: string;
13329
+ /** @description Where this task came from (free text, e.g. 'meeting', 'compliance-scan'). Stored for provenance and shown in the improvement/task record. */
13330
+ source?: string;
13331
+ source_channel?: string;
13332
+ /** @description Category ID. */
13333
+ category_id?: string;
13334
+ problem_statement?: string;
13335
+ desired_outcome?: string;
13336
+ business_impact?: string;
13337
+ user_impact?: string;
13338
+ why_now?: string;
13179
13339
  /** @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 }`. */
13180
- acceptance_criteria?: {
13340
+ acceptance_criteria?: (string | {
13181
13341
  /** @description Optional — server mints one if omitted. Preserve on edits. */
13182
13342
  id?: string;
13183
13343
  text: string;
13184
- }[];
13344
+ /** @description Server-stamped. Echo back unchanged; ignored on new rows. */
13345
+ updated_at?: string;
13346
+ /** @description Server-stamped user id. Echo back unchanged. */
13347
+ updated_by?: string;
13348
+ /** @description Server-stamped credential label. Echo back unchanged. */
13349
+ updated_by_credential_name?: string;
13350
+ })[];
13185
13351
  /** @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. */
13186
13352
  checklist?: {
13187
13353
  /** @description Optional — server mints one if omitted. Preserve on edits. */
@@ -13191,7 +13357,37 @@ interface operations {
13191
13357
  due_date?: string;
13192
13358
  /** @description true = ticked, false/omitted = not done. Server stamps timestamp + actor. */
13193
13359
  completed?: boolean;
13360
+ /** @description Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent. */
13361
+ completed_at?: string;
13362
+ /** @description Server-stamped user id. Echo back unchanged. */
13363
+ completed_by?: string;
13364
+ /** @description Server-stamped credential label. Echo back unchanged. */
13365
+ completed_by_credential_name?: string;
13366
+ /** @description Server-stamped. Echo back unchanged; ignored on new rows. */
13367
+ updated_at?: string;
13368
+ /** @description Server-stamped user id. Echo back unchanged. */
13369
+ updated_by?: string;
13370
+ /** @description Server-stamped credential label. Echo back unchanged. */
13371
+ updated_by_credential_name?: string;
13194
13372
  }[];
13373
+ constraints?: string[];
13374
+ non_goals?: string[];
13375
+ /** @description Array of {id, title}. */
13376
+ impacted_documents?: Record<string, never>[];
13377
+ /** @description Document IDs to link. Titles resolved automatically. */
13378
+ linked_document_ids?: string[];
13379
+ /** @description Array of {id, name}. */
13380
+ impacted_diagrams?: Record<string, never>[];
13381
+ impacted_components?: string[];
13382
+ impacted_repositories?: string[];
13383
+ agent_ready?: boolean;
13384
+ agent_missing_info?: string[];
13385
+ agent_recommended_action?: string;
13386
+ /** @description low, medium, high, very_high. */
13387
+ agent_complexity?: string;
13388
+ /** @description 0.00 to 1.00. */
13389
+ agent_confidence?: number;
13390
+ agent_brief?: string;
13195
13391
  /** @description User UUID to assign as owner. MUTUALLY EXCLUSIVE with owner_team_id. Use listAssignablePrincipals(projectId, kind='user') to look up valid UUIDs. */
13196
13392
  owner_id?: string;
13197
13393
  /** @description Team UUID to assign as owner (assigns the whole team). MUTUALLY EXCLUSIVE with owner_id. Use listTeams or listAssignablePrincipals(kind='team') to look up valid UUIDs. */
@@ -13206,6 +13402,10 @@ interface operations {
13206
13402
  position?: number;
13207
13403
  /** @description Progress percentage (0-100). Null means not tracked. */
13208
13404
  percent_complete?: number;
13405
+ /** @description Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs). */
13406
+ relationships?: Record<string, never>;
13407
+ /** @description Free-form JSON stored alongside the task. On updateTask this MERGES rather than replaces. */
13408
+ metadata?: Record<string, never>;
13209
13409
  };
13210
13410
  };
13211
13411
  };
@@ -13389,6 +13589,9 @@ interface operations {
13389
13589
  requestBody?: {
13390
13590
  content: {
13391
13591
  "application/json": {
13592
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
13593
+ projectId?: string;
13594
+ /** @description Accepts either the UUID or the friendly id (e.g. TAS-176); friendly ids are resolved within your organisation. */
13392
13595
  taskId: string;
13393
13596
  };
13394
13597
  };
@@ -13471,6 +13674,8 @@ interface operations {
13471
13674
  requestBody?: {
13472
13675
  content: {
13473
13676
  "application/json": {
13677
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
13678
+ projectId?: string;
13474
13679
  taskId: string;
13475
13680
  /** @description Version timestamp from getTask() for optimistic locking. */
13476
13681
  versionTimestamp: number;
@@ -13500,11 +13705,17 @@ interface operations {
13500
13705
  user_impact?: string;
13501
13706
  why_now?: string;
13502
13707
  /** @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 }`. */
13503
- acceptance_criteria?: {
13708
+ acceptance_criteria?: (string | {
13504
13709
  /** @description Optional — server mints one if omitted. Preserve on edits. */
13505
13710
  id?: string;
13506
13711
  text: string;
13507
- }[];
13712
+ /** @description Server-stamped. Echo back unchanged; ignored on new rows. */
13713
+ updated_at?: string;
13714
+ /** @description Server-stamped user id. Echo back unchanged. */
13715
+ updated_by?: string;
13716
+ /** @description Server-stamped credential label. Echo back unchanged. */
13717
+ updated_by_credential_name?: string;
13718
+ })[];
13508
13719
  /** @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. */
13509
13720
  checklist?: {
13510
13721
  /** @description Optional — server mints one if omitted. Preserve on edits. */
@@ -13514,6 +13725,18 @@ interface operations {
13514
13725
  due_date?: string;
13515
13726
  /** @description true = ticked, false/omitted = not done. Server stamps timestamp + actor. */
13516
13727
  completed?: boolean;
13728
+ /** @description Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent. */
13729
+ completed_at?: string;
13730
+ /** @description Server-stamped user id. Echo back unchanged. */
13731
+ completed_by?: string;
13732
+ /** @description Server-stamped credential label. Echo back unchanged. */
13733
+ completed_by_credential_name?: string;
13734
+ /** @description Server-stamped. Echo back unchanged; ignored on new rows. */
13735
+ updated_at?: string;
13736
+ /** @description Server-stamped user id. Echo back unchanged. */
13737
+ updated_by?: string;
13738
+ /** @description Server-stamped credential label. Echo back unchanged. */
13739
+ updated_by_credential_name?: string;
13517
13740
  }[];
13518
13741
  constraints?: string[];
13519
13742
  non_goals?: string[];
@@ -13539,11 +13762,14 @@ interface operations {
13539
13762
  rejection_comment?: string;
13540
13763
  /** @description Required when status=done. */
13541
13764
  completion_comment?: string;
13542
- /** @description Required when reopening from a closed status. */
13765
+ /** @description Required when moving OUT of a closed status. The closed set is blocked, done, rejected and deferred — note that `blocked` counts as closed, so blocked -> in_progress needs this comment. */
13543
13766
  reopened_comment?: string;
13544
- /** @description Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs). */
13767
+ /** @description Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs). REPLACES the stored object wholesale — read it first and send the complete set. */
13545
13768
  relationships?: Record<string, never>;
13769
+ /** @description Free-form JSON. MERGES into the stored object key by key: keys you don't send are left alone, and sending a key with value null deletes it. Send metadata_replace:true to overwrite the whole object instead. (Merging is the default so a partial write can never destroy a sibling key written by another actor.) */
13546
13770
  metadata?: Record<string, never>;
13771
+ /** @description Opt out of the metadata merge: true means the object you send REPLACES everything stored, deleting any key you omit. Default false. */
13772
+ metadata_replace?: boolean;
13547
13773
  /** @description Link to plan. Null to unlink. */
13548
13774
  plan_id?: string;
13549
13775
  /** @description Assign to phase. Null to unassign. */
@@ -13629,6 +13855,9 @@ interface operations {
13629
13855
  requestBody?: {
13630
13856
  content: {
13631
13857
  "application/json": {
13858
+ /** @description Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID. */
13859
+ projectId?: string;
13860
+ /** @description Accepts either the UUID or the friendly id (e.g. PLN-3); friendly ids are resolved within your organisation. */
13632
13861
  planId: string;
13633
13862
  };
13634
13863
  };
@@ -14493,7 +14722,9 @@ interface operations {
14493
14722
  * @enum {string}
14494
14723
  */
14495
14724
  mode?: "local" | "global" | "graph" | "path" | "ppr";
14725
+ /** @description STRONGLY RECOMMENDED — in practice required. The KG is scoped per project/workspace and there is usually no organisation-wide default, so a call with no projectId and no workspaceId typically matches no scope rule and returns nothing useful. Use listProjects to find the id. */
14496
14726
  projectId?: string;
14727
+ /** @description Alternative to projectId — searches the whole workspace subtree. Give one of the two. */
14497
14728
  workspaceId?: string;
14498
14729
  /** @description Required for mode='path'. Optional source entity for mode='graph'. */
14499
14730
  srcEntityId?: string;
@@ -14672,6 +14903,8 @@ interface operations {
14672
14903
  "application/json": {
14673
14904
  entityId?: string;
14674
14905
  name?: string;
14906
+ /** @description Scope the lookup to one project. Recommended when resolving by `name`, since the same entity name can exist in several projects. */
14907
+ projectId?: string;
14675
14908
  };
14676
14909
  };
14677
14910
  };
@@ -17210,7 +17443,7 @@ interface operations {
17210
17443
  name: string;
17211
17444
  /** @description Optional description. */
17212
17445
  description?: string;
17213
- /** @description Optional emoji icon. Defaults to '📁' to match the UI. */
17446
+ /** @description Optional emoji icon. Defaults to a folder emoji to match the UI. */
17214
17447
  icon?: string;
17215
17448
  };
17216
17449
  };