@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/openapi.json CHANGED
@@ -29,7 +29,7 @@
29
29
  "bearerAuth": {
30
30
  "type": "http",
31
31
  "scheme": "bearer",
32
- "description": "Either an MCP API key (prefix `sta_`, mint at https://app.stablebaseline.io/settings/mcp-keys) or an OAuth 2.1 access token (authorize at https://app.stablebaseline.io/oauth/authorize, exchange at https://api.stablebaseline.io/oauth/token)."
32
+ "description": "Either an MCP API key (prefix `sta_`, mint at https://app.stablebaseline.io/settings/mcp-setup) or an OAuth 2.1 access token. Every OAuth endpoint lives under this function, and the authoritative list is at https://api.stablebaseline.io/functions/v1/cloud-serve/.well-known/oauth-authorization-server: authorize at https://api.stablebaseline.io/functions/v1/cloud-serve/oauth/authorize, exchange at https://api.stablebaseline.io/functions/v1/cloud-serve/oauth/token."
33
33
  }
34
34
  },
35
35
  "schemas": {
@@ -161,13 +161,14 @@
161
161
  },
162
162
  "category": {
163
163
  "type": "string",
164
- "description": "Category filter.",
164
+ "description": "Category filter. One of the 18 categories returned in each result's `category` field.",
165
165
  "enum": [
166
166
  "navigation",
167
167
  "folders",
168
168
  "documents",
169
169
  "diagrams",
170
170
  "images",
171
+ "whiteboards",
171
172
  "data",
172
173
  "improvements",
173
174
  "plans",
@@ -265,7 +266,7 @@
265
266
  "/tools/listDiagramTypes": {
266
267
  "post": {
267
268
  "summary": "listDiagramTypes",
268
- "description": "List supported diagram types. Use the returned `type` field when calling insertDiagramInDocument.",
269
+ "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.",
269
270
  "operationId": "listDiagramTypes",
270
271
  "tags": [
271
272
  "diagrams"
@@ -278,7 +279,8 @@
278
279
  "type": "object",
279
280
  "properties": {
280
281
  "query": {
281
- "type": "string"
282
+ "type": "string",
283
+ "description": "Keyword or intent, e.g. 'circuit', 'wiring harness', 'timing'. Semantic-backed: matches descriptions, not just names."
282
284
  },
283
285
  "enabledOnly": {
284
286
  "type": "boolean"
@@ -487,7 +489,7 @@
487
489
  "/tools/listArchitectureIcons": {
488
490
  "post": {
489
491
  "summary": "listArchitectureIcons",
490
- "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).",
492
+ "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).",
491
493
  "operationId": "listArchitectureIcons",
492
494
  "tags": [
493
495
  "diagrams"
@@ -917,10 +919,14 @@
917
919
  "type": "string",
918
920
  "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."
919
921
  },
920
- "q": {
922
+ "query": {
921
923
  "type": "string",
922
924
  "description": "Optional ILIKE search filter — matched against display_name + email (users) and team name (teams)."
923
925
  },
926
+ "q": {
927
+ "type": "string",
928
+ "description": "Deprecated alias for `query`, still accepted. Prefer `query` — that is the name every other list tool uses."
929
+ },
924
930
  "kind": {
925
931
  "type": "string",
926
932
  "enum": [
@@ -1044,10 +1050,14 @@
1044
1050
  "type": "string",
1045
1051
  "description": "Workspace UUID. The parent organization is resolved from v_workspaces."
1046
1052
  },
1047
- "q": {
1053
+ "query": {
1048
1054
  "type": "string",
1049
1055
  "description": "Optional ILIKE search on team name/slug."
1050
1056
  },
1057
+ "q": {
1058
+ "type": "string",
1059
+ "description": "Deprecated alias for `query`, still accepted. Prefer `query` — that is the name every other list tool uses."
1060
+ },
1051
1061
  "includeMembers": {
1052
1062
  "type": "boolean",
1053
1063
  "description": "When true, each team gets a `members` array (user_id, role, joined_at). Capped at 500 total members across the page. Default false."
@@ -1360,7 +1370,7 @@
1360
1370
  "/tools/listWorkspaces": {
1361
1371
  "post": {
1362
1372
  "summary": "listWorkspaces",
1363
- "description": "List workspaces you have access to. Supports query filtering by name/slug.",
1373
+ "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.",
1364
1374
  "operationId": "listWorkspaces",
1365
1375
  "tags": [
1366
1376
  "navigation"
@@ -1372,6 +1382,14 @@
1372
1382
  "schema": {
1373
1383
  "type": "object",
1374
1384
  "properties": {
1385
+ "organisationId": {
1386
+ "type": "string",
1387
+ "description": "Return only workspaces in this organisation. Use listOrganisations to find the id. (organizationId is accepted as a spelling alias.)"
1388
+ },
1389
+ "organizationId": {
1390
+ "type": "string",
1391
+ "description": "Spelling alias for organisationId."
1392
+ },
1375
1393
  "query": {
1376
1394
  "type": "string"
1377
1395
  },
@@ -2184,7 +2202,7 @@
2184
2202
  "/tools/listDocuments": {
2185
2203
  "post": {
2186
2204
  "summary": "listDocuments",
2187
- "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.",
2205
+ "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.",
2188
2206
  "operationId": "listDocuments",
2189
2207
  "tags": [
2190
2208
  "documents"
@@ -2229,7 +2247,12 @@
2229
2247
  "type": "number"
2230
2248
  },
2231
2249
  "offset": {
2232
- "type": "number"
2250
+ "type": "number",
2251
+ "description": "Pagination offset over the MATCHES. When searching, use scanOffset (not this) to reach documents the scan has not covered."
2252
+ },
2253
+ "scanOffset": {
2254
+ "type": "number",
2255
+ "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."
2233
2256
  },
2234
2257
  "fromDate": {
2235
2258
  "type": "string",
@@ -2460,7 +2483,7 @@
2460
2483
  "/tools/getFolderHierarchy": {
2461
2484
  "post": {
2462
2485
  "summary": "getFolderHierarchy",
2463
- "description": "Get the folder and document tree starting from a specific folder. Alias for getProjectHierarchy with folderId.",
2486
+ "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.",
2464
2487
  "operationId": "getFolderHierarchy",
2465
2488
  "tags": [
2466
2489
  "navigation"
@@ -2472,9 +2495,13 @@
2472
2495
  "schema": {
2473
2496
  "type": "object",
2474
2497
  "properties": {
2498
+ "projectId": {
2499
+ "type": "string",
2500
+ "description": "Return the whole project's folder tree from the root. Provide this or folderId."
2501
+ },
2475
2502
  "folderId": {
2476
2503
  "type": "string",
2477
- "description": "The folder ID to start from."
2504
+ "description": "The folder ID to start from. Omit and pass projectId to get the project root hierarchy."
2478
2505
  },
2479
2506
  "maxDepth": {
2480
2507
  "type": "number",
@@ -2500,10 +2527,7 @@
2500
2527
  "type": "string",
2501
2528
  "description": "Date field to filter. Default: updated_at."
2502
2529
  }
2503
- },
2504
- "required": [
2505
- "folderId"
2506
- ]
2530
+ }
2507
2531
  }
2508
2532
  }
2509
2533
  }
@@ -2598,9 +2622,13 @@
2598
2622
  "schema": {
2599
2623
  "type": "object",
2600
2624
  "properties": {
2625
+ "projectId": {
2626
+ "type": "string",
2627
+ "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."
2628
+ },
2601
2629
  "documentId": {
2602
2630
  "type": "string",
2603
- "description": "The document ID to read."
2631
+ "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."
2604
2632
  },
2605
2633
  "offset": {
2606
2634
  "type": "number",
@@ -2714,7 +2742,7 @@
2714
2742
  "/tools/createDocument": {
2715
2743
  "post": {
2716
2744
  "summary": "createDocument",
2717
- "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.",
2745
+ "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.",
2718
2746
  "operationId": "createDocument",
2719
2747
  "tags": [
2720
2748
  "documents"
@@ -2849,6 +2877,10 @@
2849
2877
  "schema": {
2850
2878
  "type": "object",
2851
2879
  "properties": {
2880
+ "projectId": {
2881
+ "type": "string",
2882
+ "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."
2883
+ },
2852
2884
  "documentId": {
2853
2885
  "type": "string"
2854
2886
  },
@@ -2857,17 +2889,24 @@
2857
2889
  "description": "New title."
2858
2890
  },
2859
2891
  "folderId": {
2860
- "type": "string",
2861
- "description": "Move to this folder."
2892
+ "type": [
2893
+ "string",
2894
+ "null"
2895
+ ],
2896
+ "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."
2862
2897
  },
2863
2898
  "position": {
2864
2899
  "type": "number",
2865
- "description": "Sort position within the parent folder. Use to reposition a single document. For batch sibling reorder, use reorderDocuments."
2900
+ "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."
2866
2901
  },
2867
2902
  "versionTimestamp": {
2868
2903
  "type": "number",
2869
2904
  "description": "Optimistic-lock token from getDocument() or any mutating tool's response. Required unless dryRun:true. (Alias accepted: documentVersionTimestamp.)"
2870
2905
  },
2906
+ "expectedVersion": {
2907
+ "type": "number",
2908
+ "description": "Legacy integer version guard, checked in addition to versionTimestamp. Prefer versionTimestamp — this exists for older clients and is optional."
2909
+ },
2871
2910
  "dryRun": {
2872
2911
  "type": "boolean",
2873
2912
  "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."
@@ -3031,6 +3070,10 @@
3031
3070
  "schema": {
3032
3071
  "type": "object",
3033
3072
  "properties": {
3073
+ "projectId": {
3074
+ "type": "string",
3075
+ "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."
3076
+ },
3034
3077
  "documentId": {
3035
3078
  "type": "string"
3036
3079
  },
@@ -3263,6 +3306,10 @@
3263
3306
  "schema": {
3264
3307
  "type": "object",
3265
3308
  "properties": {
3309
+ "projectId": {
3310
+ "type": "string",
3311
+ "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."
3312
+ },
3266
3313
  "documentId": {
3267
3314
  "type": "string"
3268
3315
  },
@@ -3705,6 +3752,10 @@
3705
3752
  "properties": {
3706
3753
  "documentId": {
3707
3754
  "type": "string"
3755
+ },
3756
+ "projectId": {
3757
+ "type": "string",
3758
+ "description": "Optional. Narrows a friendly-id lookup to one project. Ignored when documentId is a UUID."
3708
3759
  }
3709
3760
  },
3710
3761
  "required": [
@@ -4090,6 +4141,10 @@
4090
4141
  "type": "string",
4091
4142
  "description": "Optional URL of a reference image the component should match; the critic compares the render to it."
4092
4143
  },
4144
+ "brandKitId": {
4145
+ "type": "string",
4146
+ "description": "Optional brand kit id (from listBrandKits) to theme the component. If omitted, the organisation's effective brand is used."
4147
+ },
4093
4148
  "force": {
4094
4149
  "type": "boolean",
4095
4150
  "description": "Redesign even if a component with this key already exists (default false = reuse)."
@@ -4206,6 +4261,7 @@
4206
4261
  },
4207
4262
  "maskBase64": {
4208
4263
  "type": "string",
4264
+ "contentEncoding": "base64",
4209
4265
  "description": "A PNG mask (base64, with or without a data: prefix) the same shape as the image. WHITE pixels are regenerated; BLACK pixels are preserved."
4210
4266
  },
4211
4267
  "prompt": {
@@ -4305,7 +4361,7 @@
4305
4361
  "/tools/designDeckInWhiteboard": {
4306
4362
  "post": {
4307
4363
  "summary": "designDeckInWhiteboard",
4308
- "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.",
4364
+ "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.",
4309
4365
  "operationId": "designDeckInWhiteboard",
4310
4366
  "tags": [
4311
4367
  "whiteboards"
@@ -4323,7 +4379,7 @@
4323
4379
  },
4324
4380
  "message": {
4325
4381
  "type": "string",
4326
- "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."
4382
+ "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."
4327
4383
  },
4328
4384
  "sessionId": {
4329
4385
  "type": "string",
@@ -4353,7 +4409,19 @@
4353
4409
  },
4354
4410
  "slideCount": {
4355
4411
  "type": "number",
4356
- "description": "Optional target number of slides for a build turn (the composer adjusts to fit the story). Typical 6 to 12."
4412
+ "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)."
4413
+ },
4414
+ "imageCount": {
4415
+ "type": "number",
4416
+ "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)."
4417
+ },
4418
+ "advancedDeckBuilding": {
4419
+ "type": "boolean",
4420
+ "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."
4421
+ },
4422
+ "advancedDeckBuildingDepth": {
4423
+ "type": "number",
4424
+ "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."
4357
4425
  },
4358
4426
  "attachments": {
4359
4427
  "type": "array",
@@ -4377,6 +4445,10 @@
4377
4445
  "name": {
4378
4446
  "type": "string",
4379
4447
  "description": "Optional human-readable name for the image."
4448
+ },
4449
+ "type": {
4450
+ "type": "string",
4451
+ "description": "Optional attachment type hint, passed through to the design worker."
4380
4452
  }
4381
4453
  }
4382
4454
  }
@@ -4530,6 +4602,10 @@
4530
4602
  "name": {
4531
4603
  "type": "string",
4532
4604
  "description": "Optional human-readable name for the image."
4605
+ },
4606
+ "type": {
4607
+ "type": "string",
4608
+ "description": "Optional attachment type hint, passed through to the design worker."
4533
4609
  }
4534
4610
  }
4535
4611
  }
@@ -4625,7 +4701,7 @@
4625
4701
  "/tools/getDeckReplyInWhiteboard": {
4626
4702
  "post": {
4627
4703
  "summary": "getDeckReplyInWhiteboard",
4628
- "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.",
4704
+ "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.",
4629
4705
  "operationId": "getDeckReplyInWhiteboard",
4630
4706
  "tags": [
4631
4707
  "whiteboards"
@@ -4894,6 +4970,15 @@
4894
4970
  "id": {
4895
4971
  "type": "string",
4896
4972
  "description": "Optional stable id; one is minted if omitted."
4973
+ },
4974
+ "status": {
4975
+ "type": "string",
4976
+ "enum": [
4977
+ "pending",
4978
+ "active",
4979
+ "done"
4980
+ ],
4981
+ "description": "Optional starting status sticker. Default: pending."
4897
4982
  }
4898
4983
  },
4899
4984
  "required": [
@@ -5424,8 +5509,13 @@
5424
5509
  "schema": {
5425
5510
  "type": "object",
5426
5511
  "properties": {
5512
+ "projectId": {
5513
+ "type": "string",
5514
+ "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."
5515
+ },
5427
5516
  "documentId": {
5428
- "type": "string"
5517
+ "type": "string",
5518
+ "description": "Accepts either the UUID or the friendly id (e.g. WBD-12); friendly ids are resolved within your organisation."
5429
5519
  },
5430
5520
  "includeElements": {
5431
5521
  "type": "boolean",
@@ -5529,6 +5619,10 @@
5529
5619
  "schema": {
5530
5620
  "type": "object",
5531
5621
  "properties": {
5622
+ "projectId": {
5623
+ "type": "string",
5624
+ "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."
5625
+ },
5532
5626
  "documentId": {
5533
5627
  "type": "string"
5534
5628
  },
@@ -5657,7 +5751,7 @@
5657
5751
  "/tools/addWhiteboardElements": {
5658
5752
  "post": {
5659
5753
  "summary": "addWhiteboardElements",
5660
- "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.",
5754
+ "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.",
5661
5755
  "operationId": "addWhiteboardElements",
5662
5756
  "tags": [
5663
5757
  "whiteboards"
@@ -5669,6 +5763,10 @@
5669
5763
  "schema": {
5670
5764
  "type": "object",
5671
5765
  "properties": {
5766
+ "projectId": {
5767
+ "type": "string",
5768
+ "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."
5769
+ },
5672
5770
  "documentId": {
5673
5771
  "type": "string"
5674
5772
  },
@@ -6122,6 +6220,7 @@
6122
6220
  },
6123
6221
  "imageBase64": {
6124
6222
  "type": "string",
6223
+ "contentEncoding": "base64",
6125
6224
  "description": "Base64-encoded image bytes (a data: URL prefix is allowed). Best for small images."
6126
6225
  },
6127
6226
  "imageBinary": {
@@ -6167,6 +6266,15 @@
6167
6266
  "locked": {
6168
6267
  "type": "boolean",
6169
6268
  "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."
6269
+ },
6270
+ "nlDescription": {
6271
+ "type": "string",
6272
+ "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."
6273
+ },
6274
+ "customData": {
6275
+ "type": "object",
6276
+ "additionalProperties": true,
6277
+ "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."
6170
6278
  }
6171
6279
  },
6172
6280
  "required": [
@@ -6428,6 +6536,7 @@
6428
6536
  },
6429
6537
  "imageBase64": {
6430
6538
  "type": "string",
6539
+ "contentEncoding": "base64",
6431
6540
  "description": "Base64-encoded image bytes (a data: URL prefix is allowed). Use instead of imageUrl."
6432
6541
  },
6433
6542
  "mimeType": {
@@ -6561,6 +6670,10 @@
6561
6670
  "schema": {
6562
6671
  "type": "object",
6563
6672
  "properties": {
6673
+ "projectId": {
6674
+ "type": "string",
6675
+ "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."
6676
+ },
6564
6677
  "documentId": {
6565
6678
  "type": "string",
6566
6679
  "description": "The whiteboard's documentId."
@@ -6814,9 +6927,13 @@
6814
6927
  "schema": {
6815
6928
  "type": "object",
6816
6929
  "properties": {
6930
+ "projectId": {
6931
+ "type": "string",
6932
+ "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."
6933
+ },
6817
6934
  "documentId": {
6818
6935
  "type": "string",
6819
- "description": "The whiteboard's documentId."
6936
+ "description": "The whiteboard's documentId. Accepts either the UUID or the friendly id (e.g. WBD-12); friendly ids are resolved within your organisation."
6820
6937
  },
6821
6938
  "elementIds": {
6822
6939
  "type": "array",
@@ -6966,6 +7083,10 @@
6966
7083
  "properties": {
6967
7084
  "documentId": {
6968
7085
  "type": "string"
7086
+ },
7087
+ "projectId": {
7088
+ "type": "string",
7089
+ "description": "Optional. Narrows a friendly-id lookup to one project. Ignored when documentId is a UUID."
6969
7090
  }
6970
7091
  },
6971
7092
  "required": [
@@ -7416,7 +7537,7 @@
7416
7537
  "/tools/reorderDocuments": {
7417
7538
  "post": {
7418
7539
  "summary": "reorderDocuments",
7419
- "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.",
7540
+ "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).",
7420
7541
  "operationId": "reorderDocuments",
7421
7542
  "tags": [
7422
7543
  "documents"
@@ -7430,20 +7551,27 @@
7430
7551
  "properties": {
7431
7552
  "items": {
7432
7553
  "type": "array",
7433
- "description": "List of document position updates. All documents must belong to the same project.",
7554
+ "description": "Documents to file. All must belong to the same project (a batch spanning projects is rejected).",
7434
7555
  "items": {
7435
7556
  "type": "object",
7436
7557
  "properties": {
7437
7558
  "documentId": {
7438
7559
  "type": "string"
7439
7560
  },
7561
+ "folderId": {
7562
+ "type": [
7563
+ "string",
7564
+ "null"
7565
+ ],
7566
+ "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."
7567
+ },
7440
7568
  "position": {
7441
- "type": "number"
7569
+ "type": "number",
7570
+ "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…."
7442
7571
  }
7443
7572
  },
7444
7573
  "required": [
7445
- "documentId",
7446
- "position"
7574
+ "documentId"
7447
7575
  ]
7448
7576
  },
7449
7577
  "minItems": 1
@@ -7546,8 +7674,13 @@
7546
7674
  "schema": {
7547
7675
  "type": "object",
7548
7676
  "properties": {
7677
+ "projectId": {
7678
+ "type": "string",
7679
+ "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."
7680
+ },
7549
7681
  "documentId": {
7550
- "type": "string"
7682
+ "type": "string",
7683
+ "description": "Accepts either the UUID or the friendly id (e.g. DOC-815); friendly ids are resolved within your organisation."
7551
7684
  },
7552
7685
  "versionNumber": {
7553
7686
  "type": "number",
@@ -7784,6 +7917,10 @@
7784
7917
  "schema": {
7785
7918
  "type": "object",
7786
7919
  "properties": {
7920
+ "projectId": {
7921
+ "type": "string",
7922
+ "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."
7923
+ },
7787
7924
  "documentId": {
7788
7925
  "type": "string"
7789
7926
  },
@@ -7899,6 +8036,10 @@
7899
8036
  "schema": {
7900
8037
  "type": "object",
7901
8038
  "properties": {
8039
+ "projectId": {
8040
+ "type": "string",
8041
+ "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."
8042
+ },
7902
8043
  "documentId": {
7903
8044
  "type": "string"
7904
8045
  },
@@ -7908,6 +8049,7 @@
7908
8049
  },
7909
8050
  "imageBase64": {
7910
8051
  "type": "string",
8052
+ "contentEncoding": "base64",
7911
8053
  "description": "Base64-encoded image data. Mutually exclusive with imageBinary/imageUrl."
7912
8054
  },
7913
8055
  "imageBinary": {
@@ -8295,6 +8437,10 @@
8295
8437
  "schema": {
8296
8438
  "type": "object",
8297
8439
  "properties": {
8440
+ "projectId": {
8441
+ "type": "string",
8442
+ "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."
8443
+ },
8298
8444
  "documentId": {
8299
8445
  "type": "string"
8300
8446
  },
@@ -8405,6 +8551,10 @@
8405
8551
  "schema": {
8406
8552
  "type": "object",
8407
8553
  "properties": {
8554
+ "projectId": {
8555
+ "type": "string",
8556
+ "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."
8557
+ },
8408
8558
  "documentId": {
8409
8559
  "type": "string"
8410
8560
  },
@@ -9023,8 +9173,13 @@
9023
9173
  "schema": {
9024
9174
  "type": "object",
9025
9175
  "properties": {
9176
+ "projectId": {
9177
+ "type": "string",
9178
+ "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."
9179
+ },
9026
9180
  "improvementId": {
9027
- "type": "string"
9181
+ "type": "string",
9182
+ "description": "Accepts either the UUID or the friendly id (e.g. IMP-42); friendly ids are resolved within your organisation."
9028
9183
  }
9029
9184
  },
9030
9185
  "required": [
@@ -9112,7 +9267,7 @@
9112
9267
  "/tools/createImprovement": {
9113
9268
  "post": {
9114
9269
  "summary": "createImprovement",
9115
- "description": "Create an improvement item in a project. Requires projectId and title. Auto-assigns friendly ID.",
9270
+ "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.",
9116
9271
  "operationId": "createImprovement",
9117
9272
  "tags": [
9118
9273
  "improvements"
@@ -9132,7 +9287,7 @@
9132
9287
  },
9133
9288
  "type": {
9134
9289
  "type": "string",
9135
- "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)."
9290
+ "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)."
9136
9291
  },
9137
9292
  "priority": {
9138
9293
  "type": "string",
@@ -9173,18 +9328,38 @@
9173
9328
  "type": "array",
9174
9329
  "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 }`.",
9175
9330
  "items": {
9176
- "type": "object",
9177
- "properties": {
9178
- "id": {
9331
+ "anyOf": [
9332
+ {
9179
9333
  "type": "string",
9180
- "description": "Optional — server mints one if omitted. Preserve on edits."
9334
+ "description": "Shorthand for `{ text: \"...\" }`."
9181
9335
  },
9182
- "text": {
9183
- "type": "string"
9336
+ {
9337
+ "type": "object",
9338
+ "properties": {
9339
+ "id": {
9340
+ "type": "string",
9341
+ "description": "Optional — server mints one if omitted. Preserve on edits."
9342
+ },
9343
+ "text": {
9344
+ "type": "string"
9345
+ },
9346
+ "updated_at": {
9347
+ "type": "string",
9348
+ "description": "Server-stamped. Echo back unchanged; ignored on new rows."
9349
+ },
9350
+ "updated_by": {
9351
+ "type": "string",
9352
+ "description": "Server-stamped user id. Echo back unchanged."
9353
+ },
9354
+ "updated_by_credential_name": {
9355
+ "type": "string",
9356
+ "description": "Server-stamped credential label. Echo back unchanged."
9357
+ }
9358
+ },
9359
+ "required": [
9360
+ "text"
9361
+ ]
9184
9362
  }
9185
- },
9186
- "required": [
9187
- "text"
9188
9363
  ]
9189
9364
  }
9190
9365
  },
@@ -9208,6 +9383,30 @@
9208
9383
  "completed": {
9209
9384
  "type": "boolean",
9210
9385
  "description": "true = ticked, false/omitted = not done. Server stamps timestamp + actor."
9386
+ },
9387
+ "completed_at": {
9388
+ "type": "string",
9389
+ "description": "Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent."
9390
+ },
9391
+ "completed_by": {
9392
+ "type": "string",
9393
+ "description": "Server-stamped user id. Echo back unchanged."
9394
+ },
9395
+ "completed_by_credential_name": {
9396
+ "type": "string",
9397
+ "description": "Server-stamped credential label. Echo back unchanged."
9398
+ },
9399
+ "updated_at": {
9400
+ "type": "string",
9401
+ "description": "Server-stamped. Echo back unchanged; ignored on new rows."
9402
+ },
9403
+ "updated_by": {
9404
+ "type": "string",
9405
+ "description": "Server-stamped user id. Echo back unchanged."
9406
+ },
9407
+ "updated_by_credential_name": {
9408
+ "type": "string",
9409
+ "description": "Server-stamped credential label. Echo back unchanged."
9211
9410
  }
9212
9411
  },
9213
9412
  "required": [
@@ -9319,6 +9518,23 @@
9319
9518
  "percent_complete": {
9320
9519
  "type": "number",
9321
9520
  "description": "Progress percentage (0-100). Null means not tracked."
9521
+ },
9522
+ "source_channel": {
9523
+ "type": "string"
9524
+ },
9525
+ "impacted_repositories": {
9526
+ "type": "array",
9527
+ "items": {
9528
+ "type": "string"
9529
+ }
9530
+ },
9531
+ "relationships": {
9532
+ "type": "object",
9533
+ "description": "Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs)."
9534
+ },
9535
+ "metadata": {
9536
+ "type": "object",
9537
+ "description": "Free-form JSON stored alongside the item. On updateImprovement this MERGES rather than replaces."
9322
9538
  }
9323
9539
  },
9324
9540
  "required": [
@@ -9407,7 +9623,7 @@
9407
9623
  "/tools/updateImprovement": {
9408
9624
  "post": {
9409
9625
  "summary": "updateImprovement",
9410
- "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.",
9626
+ "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.",
9411
9627
  "operationId": "updateImprovement",
9412
9628
  "tags": [
9413
9629
  "improvements"
@@ -9419,6 +9635,10 @@
9419
9635
  "schema": {
9420
9636
  "type": "object",
9421
9637
  "properties": {
9638
+ "projectId": {
9639
+ "type": "string",
9640
+ "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."
9641
+ },
9422
9642
  "improvementId": {
9423
9643
  "type": "string"
9424
9644
  },
@@ -9492,18 +9712,38 @@
9492
9712
  "type": "array",
9493
9713
  "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 }`.",
9494
9714
  "items": {
9495
- "type": "object",
9496
- "properties": {
9497
- "id": {
9715
+ "anyOf": [
9716
+ {
9498
9717
  "type": "string",
9499
- "description": "Optional — server mints one if omitted. Preserve on edits."
9718
+ "description": "Shorthand for `{ text: \"...\" }`."
9500
9719
  },
9501
- "text": {
9502
- "type": "string"
9720
+ {
9721
+ "type": "object",
9722
+ "properties": {
9723
+ "id": {
9724
+ "type": "string",
9725
+ "description": "Optional — server mints one if omitted. Preserve on edits."
9726
+ },
9727
+ "text": {
9728
+ "type": "string"
9729
+ },
9730
+ "updated_at": {
9731
+ "type": "string",
9732
+ "description": "Server-stamped. Echo back unchanged; ignored on new rows."
9733
+ },
9734
+ "updated_by": {
9735
+ "type": "string",
9736
+ "description": "Server-stamped user id. Echo back unchanged."
9737
+ },
9738
+ "updated_by_credential_name": {
9739
+ "type": "string",
9740
+ "description": "Server-stamped credential label. Echo back unchanged."
9741
+ }
9742
+ },
9743
+ "required": [
9744
+ "text"
9745
+ ]
9503
9746
  }
9504
- },
9505
- "required": [
9506
- "text"
9507
9747
  ]
9508
9748
  }
9509
9749
  },
@@ -9527,6 +9767,30 @@
9527
9767
  "completed": {
9528
9768
  "type": "boolean",
9529
9769
  "description": "true = ticked, false/omitted = not done. Server stamps timestamp + actor."
9770
+ },
9771
+ "completed_at": {
9772
+ "type": "string",
9773
+ "description": "Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent."
9774
+ },
9775
+ "completed_by": {
9776
+ "type": "string",
9777
+ "description": "Server-stamped user id. Echo back unchanged."
9778
+ },
9779
+ "completed_by_credential_name": {
9780
+ "type": "string",
9781
+ "description": "Server-stamped credential label. Echo back unchanged."
9782
+ },
9783
+ "updated_at": {
9784
+ "type": "string",
9785
+ "description": "Server-stamped. Echo back unchanged; ignored on new rows."
9786
+ },
9787
+ "updated_by": {
9788
+ "type": "string",
9789
+ "description": "Server-stamped user id. Echo back unchanged."
9790
+ },
9791
+ "updated_by_credential_name": {
9792
+ "type": "string",
9793
+ "description": "Server-stamped credential label. Echo back unchanged."
9530
9794
  }
9531
9795
  },
9532
9796
  "required": [
@@ -9624,14 +9888,19 @@
9624
9888
  },
9625
9889
  "reopened_comment": {
9626
9890
  "type": "string",
9627
- "description": "Required when reopening from blocked/rejected/done/deferred."
9891
+ "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."
9628
9892
  },
9629
9893
  "relationships": {
9630
9894
  "type": "object",
9631
- "description": "Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs)."
9895
+ "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."
9632
9896
  },
9633
9897
  "metadata": {
9634
- "type": "object"
9898
+ "type": "object",
9899
+ "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.)"
9900
+ },
9901
+ "metadata_replace": {
9902
+ "type": "boolean",
9903
+ "description": "Opt out of the metadata merge: true means the object you send REPLACES everything stored, deleting any key you omit. Default false."
9635
9904
  },
9636
9905
  "plan_id": {
9637
9906
  "type": "string",
@@ -9754,6 +10023,10 @@
9754
10023
  "schema": {
9755
10024
  "type": "object",
9756
10025
  "properties": {
10026
+ "projectId": {
10027
+ "type": "string",
10028
+ "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."
10029
+ },
9757
10030
  "improvementId": {
9758
10031
  "type": "string"
9759
10032
  }
@@ -10421,6 +10694,10 @@
10421
10694
  "schema": {
10422
10695
  "type": "object",
10423
10696
  "properties": {
10697
+ "projectId": {
10698
+ "type": "string",
10699
+ "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."
10700
+ },
10424
10701
  "improvementId": {
10425
10702
  "type": "string"
10426
10703
  },
@@ -10547,6 +10824,10 @@
10547
10824
  "schema": {
10548
10825
  "type": "object",
10549
10826
  "properties": {
10827
+ "projectId": {
10828
+ "type": "string",
10829
+ "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."
10830
+ },
10550
10831
  "improvementId": {
10551
10832
  "type": "string"
10552
10833
  },
@@ -11163,8 +11444,13 @@
11163
11444
  "schema": {
11164
11445
  "type": "object",
11165
11446
  "properties": {
11447
+ "projectId": {
11448
+ "type": "string",
11449
+ "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."
11450
+ },
11166
11451
  "planId": {
11167
- "type": "string"
11452
+ "type": "string",
11453
+ "description": "Accepts either the UUID or the friendly id (e.g. PLN-3); friendly ids are resolved within your organisation."
11168
11454
  }
11169
11455
  },
11170
11456
  "required": [
@@ -11410,6 +11696,10 @@
11410
11696
  "schema": {
11411
11697
  "type": "object",
11412
11698
  "properties": {
11699
+ "projectId": {
11700
+ "type": "string",
11701
+ "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."
11702
+ },
11413
11703
  "planId": {
11414
11704
  "type": "string"
11415
11705
  },
@@ -11560,6 +11850,10 @@
11560
11850
  "schema": {
11561
11851
  "type": "object",
11562
11852
  "properties": {
11853
+ "projectId": {
11854
+ "type": "string",
11855
+ "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."
11856
+ },
11563
11857
  "planId": {
11564
11858
  "type": "string"
11565
11859
  }
@@ -11762,8 +12056,13 @@
11762
12056
  "schema": {
11763
12057
  "type": "object",
11764
12058
  "properties": {
12059
+ "projectId": {
12060
+ "type": "string",
12061
+ "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."
12062
+ },
11765
12063
  "phaseId": {
11766
- "type": "string"
12064
+ "type": "string",
12065
+ "description": "Accepts either the UUID or the friendly id (e.g. PHA-7); friendly ids are resolved within your organisation."
11767
12066
  }
11768
12067
  },
11769
12068
  "required": [
@@ -12009,6 +12308,10 @@
12009
12308
  "schema": {
12010
12309
  "type": "object",
12011
12310
  "properties": {
12311
+ "projectId": {
12312
+ "type": "string",
12313
+ "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."
12314
+ },
12012
12315
  "phaseId": {
12013
12316
  "type": "string"
12014
12317
  },
@@ -12159,6 +12462,10 @@
12159
12462
  "schema": {
12160
12463
  "type": "object",
12161
12464
  "properties": {
12465
+ "projectId": {
12466
+ "type": "string",
12467
+ "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."
12468
+ },
12162
12469
  "phaseId": {
12163
12470
  "type": "string"
12164
12471
  }
@@ -12377,6 +12684,10 @@
12377
12684
  "schema": {
12378
12685
  "type": "object",
12379
12686
  "properties": {
12687
+ "projectId": {
12688
+ "type": "string",
12689
+ "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."
12690
+ },
12380
12691
  "planId": {
12381
12692
  "type": "string"
12382
12693
  },
@@ -12704,7 +13015,7 @@
12704
13015
  "/tools/createTask": {
12705
13016
  "post": {
12706
13017
  "summary": "createTask",
12707
- "description": "Create a task in a plan. Requires planId and title.",
13018
+ "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.",
12708
13019
  "operationId": "createTask",
12709
13020
  "tags": [
12710
13021
  "plans"
@@ -12731,7 +13042,7 @@
12731
13042
  },
12732
13043
  "type": {
12733
13044
  "type": "string",
12734
- "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)."
13045
+ "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."
12735
13046
  },
12736
13047
  "status": {
12737
13048
  "type": "string",
@@ -12741,22 +13052,72 @@
12741
13052
  "type": "string",
12742
13053
  "description": "Priority. Default: medium."
12743
13054
  },
13055
+ "urgency": {
13056
+ "type": "string",
13057
+ "description": "e.g. this_week, this_month, this_quarter."
13058
+ },
13059
+ "source": {
13060
+ "type": "string",
13061
+ "description": "Where this task came from (free text, e.g. 'meeting', 'compliance-scan'). Stored for provenance and shown in the improvement/task record."
13062
+ },
13063
+ "source_channel": {
13064
+ "type": "string"
13065
+ },
13066
+ "category_id": {
13067
+ "type": "string",
13068
+ "description": "Category ID."
13069
+ },
13070
+ "problem_statement": {
13071
+ "type": "string"
13072
+ },
13073
+ "desired_outcome": {
13074
+ "type": "string"
13075
+ },
13076
+ "business_impact": {
13077
+ "type": "string"
13078
+ },
13079
+ "user_impact": {
13080
+ "type": "string"
13081
+ },
13082
+ "why_now": {
13083
+ "type": "string"
13084
+ },
12744
13085
  "acceptance_criteria": {
12745
13086
  "type": "array",
12746
13087
  "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 }`.",
12747
13088
  "items": {
12748
- "type": "object",
12749
- "properties": {
12750
- "id": {
13089
+ "anyOf": [
13090
+ {
12751
13091
  "type": "string",
12752
- "description": "Optional — server mints one if omitted. Preserve on edits."
13092
+ "description": "Shorthand for `{ text: \"...\" }`."
12753
13093
  },
12754
- "text": {
12755
- "type": "string"
13094
+ {
13095
+ "type": "object",
13096
+ "properties": {
13097
+ "id": {
13098
+ "type": "string",
13099
+ "description": "Optional — server mints one if omitted. Preserve on edits."
13100
+ },
13101
+ "text": {
13102
+ "type": "string"
13103
+ },
13104
+ "updated_at": {
13105
+ "type": "string",
13106
+ "description": "Server-stamped. Echo back unchanged; ignored on new rows."
13107
+ },
13108
+ "updated_by": {
13109
+ "type": "string",
13110
+ "description": "Server-stamped user id. Echo back unchanged."
13111
+ },
13112
+ "updated_by_credential_name": {
13113
+ "type": "string",
13114
+ "description": "Server-stamped credential label. Echo back unchanged."
13115
+ }
13116
+ },
13117
+ "required": [
13118
+ "text"
13119
+ ]
12756
13120
  }
12757
- },
12758
- "required": [
12759
- "text"
12760
13121
  ]
12761
13122
  }
12762
13123
  },
@@ -12780,6 +13141,30 @@
12780
13141
  "completed": {
12781
13142
  "type": "boolean",
12782
13143
  "description": "true = ticked, false/omitted = not done. Server stamps timestamp + actor."
13144
+ },
13145
+ "completed_at": {
13146
+ "type": "string",
13147
+ "description": "Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent."
13148
+ },
13149
+ "completed_by": {
13150
+ "type": "string",
13151
+ "description": "Server-stamped user id. Echo back unchanged."
13152
+ },
13153
+ "completed_by_credential_name": {
13154
+ "type": "string",
13155
+ "description": "Server-stamped credential label. Echo back unchanged."
13156
+ },
13157
+ "updated_at": {
13158
+ "type": "string",
13159
+ "description": "Server-stamped. Echo back unchanged; ignored on new rows."
13160
+ },
13161
+ "updated_by": {
13162
+ "type": "string",
13163
+ "description": "Server-stamped user id. Echo back unchanged."
13164
+ },
13165
+ "updated_by_credential_name": {
13166
+ "type": "string",
13167
+ "description": "Server-stamped credential label. Echo back unchanged."
12783
13168
  }
12784
13169
  },
12785
13170
  "required": [
@@ -12787,6 +13172,74 @@
12787
13172
  ]
12788
13173
  }
12789
13174
  },
13175
+ "constraints": {
13176
+ "type": "array",
13177
+ "items": {
13178
+ "type": "string"
13179
+ }
13180
+ },
13181
+ "non_goals": {
13182
+ "type": "array",
13183
+ "items": {
13184
+ "type": "string"
13185
+ }
13186
+ },
13187
+ "impacted_documents": {
13188
+ "type": "array",
13189
+ "items": {
13190
+ "type": "object"
13191
+ },
13192
+ "description": "Array of {id, title}."
13193
+ },
13194
+ "linked_document_ids": {
13195
+ "type": "array",
13196
+ "items": {
13197
+ "type": "string"
13198
+ },
13199
+ "description": "Document IDs to link. Titles resolved automatically."
13200
+ },
13201
+ "impacted_diagrams": {
13202
+ "type": "array",
13203
+ "items": {
13204
+ "type": "object"
13205
+ },
13206
+ "description": "Array of {id, name}."
13207
+ },
13208
+ "impacted_components": {
13209
+ "type": "array",
13210
+ "items": {
13211
+ "type": "string"
13212
+ }
13213
+ },
13214
+ "impacted_repositories": {
13215
+ "type": "array",
13216
+ "items": {
13217
+ "type": "string"
13218
+ }
13219
+ },
13220
+ "agent_ready": {
13221
+ "type": "boolean"
13222
+ },
13223
+ "agent_missing_info": {
13224
+ "type": "array",
13225
+ "items": {
13226
+ "type": "string"
13227
+ }
13228
+ },
13229
+ "agent_recommended_action": {
13230
+ "type": "string"
13231
+ },
13232
+ "agent_complexity": {
13233
+ "type": "string",
13234
+ "description": "low, medium, high, very_high."
13235
+ },
13236
+ "agent_confidence": {
13237
+ "type": "number",
13238
+ "description": "0.00 to 1.00."
13239
+ },
13240
+ "agent_brief": {
13241
+ "type": "string"
13242
+ },
12790
13243
  "owner_id": {
12791
13244
  "type": "string",
12792
13245
  "description": "User UUID to assign as owner. MUTUALLY EXCLUSIVE with owner_team_id. Use listAssignablePrincipals(projectId, kind='user') to look up valid UUIDs."
@@ -12816,6 +13269,14 @@
12816
13269
  "percent_complete": {
12817
13270
  "type": "number",
12818
13271
  "description": "Progress percentage (0-100). Null means not tracked."
13272
+ },
13273
+ "relationships": {
13274
+ "type": "object",
13275
+ "description": "Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs)."
13276
+ },
13277
+ "metadata": {
13278
+ "type": "object",
13279
+ "description": "Free-form JSON stored alongside the task. On updateTask this MERGES rather than replaces."
12819
13280
  }
12820
13281
  },
12821
13282
  "required": [
@@ -13057,8 +13518,13 @@
13057
13518
  "schema": {
13058
13519
  "type": "object",
13059
13520
  "properties": {
13521
+ "projectId": {
13522
+ "type": "string",
13523
+ "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."
13524
+ },
13060
13525
  "taskId": {
13061
- "type": "string"
13526
+ "type": "string",
13527
+ "description": "Accepts either the UUID or the friendly id (e.g. TAS-176); friendly ids are resolved within your organisation."
13062
13528
  }
13063
13529
  },
13064
13530
  "required": [
@@ -13146,7 +13612,7 @@
13146
13612
  "/tools/updateTask": {
13147
13613
  "post": {
13148
13614
  "summary": "updateTask",
13149
- "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.",
13615
+ "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.",
13150
13616
  "operationId": "updateTask",
13151
13617
  "tags": [
13152
13618
  "plans"
@@ -13158,6 +13624,10 @@
13158
13624
  "schema": {
13159
13625
  "type": "object",
13160
13626
  "properties": {
13627
+ "projectId": {
13628
+ "type": "string",
13629
+ "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."
13630
+ },
13161
13631
  "taskId": {
13162
13632
  "type": "string"
13163
13633
  },
@@ -13238,18 +13708,38 @@
13238
13708
  "type": "array",
13239
13709
  "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 }`.",
13240
13710
  "items": {
13241
- "type": "object",
13242
- "properties": {
13243
- "id": {
13711
+ "anyOf": [
13712
+ {
13244
13713
  "type": "string",
13245
- "description": "Optional — server mints one if omitted. Preserve on edits."
13714
+ "description": "Shorthand for `{ text: \"...\" }`."
13246
13715
  },
13247
- "text": {
13248
- "type": "string"
13716
+ {
13717
+ "type": "object",
13718
+ "properties": {
13719
+ "id": {
13720
+ "type": "string",
13721
+ "description": "Optional — server mints one if omitted. Preserve on edits."
13722
+ },
13723
+ "text": {
13724
+ "type": "string"
13725
+ },
13726
+ "updated_at": {
13727
+ "type": "string",
13728
+ "description": "Server-stamped. Echo back unchanged; ignored on new rows."
13729
+ },
13730
+ "updated_by": {
13731
+ "type": "string",
13732
+ "description": "Server-stamped user id. Echo back unchanged."
13733
+ },
13734
+ "updated_by_credential_name": {
13735
+ "type": "string",
13736
+ "description": "Server-stamped credential label. Echo back unchanged."
13737
+ }
13738
+ },
13739
+ "required": [
13740
+ "text"
13741
+ ]
13249
13742
  }
13250
- },
13251
- "required": [
13252
- "text"
13253
13743
  ]
13254
13744
  }
13255
13745
  },
@@ -13273,6 +13763,30 @@
13273
13763
  "completed": {
13274
13764
  "type": "boolean",
13275
13765
  "description": "true = ticked, false/omitted = not done. Server stamps timestamp + actor."
13766
+ },
13767
+ "completed_at": {
13768
+ "type": "string",
13769
+ "description": "Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent."
13770
+ },
13771
+ "completed_by": {
13772
+ "type": "string",
13773
+ "description": "Server-stamped user id. Echo back unchanged."
13774
+ },
13775
+ "completed_by_credential_name": {
13776
+ "type": "string",
13777
+ "description": "Server-stamped credential label. Echo back unchanged."
13778
+ },
13779
+ "updated_at": {
13780
+ "type": "string",
13781
+ "description": "Server-stamped. Echo back unchanged; ignored on new rows."
13782
+ },
13783
+ "updated_by": {
13784
+ "type": "string",
13785
+ "description": "Server-stamped user id. Echo back unchanged."
13786
+ },
13787
+ "updated_by_credential_name": {
13788
+ "type": "string",
13789
+ "description": "Server-stamped credential label. Echo back unchanged."
13276
13790
  }
13277
13791
  },
13278
13792
  "required": [
@@ -13370,14 +13884,19 @@
13370
13884
  },
13371
13885
  "reopened_comment": {
13372
13886
  "type": "string",
13373
- "description": "Required when reopening from a closed status."
13887
+ "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."
13374
13888
  },
13375
13889
  "relationships": {
13376
13890
  "type": "object",
13377
- "description": "Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs)."
13891
+ "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."
13378
13892
  },
13379
13893
  "metadata": {
13380
- "type": "object"
13894
+ "type": "object",
13895
+ "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.)"
13896
+ },
13897
+ "metadata_replace": {
13898
+ "type": "boolean",
13899
+ "description": "Opt out of the metadata merge: true means the object you send REPLACES everything stored, deleting any key you omit. Default false."
13381
13900
  },
13382
13901
  "plan_id": {
13383
13902
  "type": "string",
@@ -13486,8 +14005,13 @@
13486
14005
  "schema": {
13487
14006
  "type": "object",
13488
14007
  "properties": {
14008
+ "projectId": {
14009
+ "type": "string",
14010
+ "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."
14011
+ },
13489
14012
  "planId": {
13490
- "type": "string"
14013
+ "type": "string",
14014
+ "description": "Accepts either the UUID or the friendly id (e.g. PLN-3); friendly ids are resolved within your organisation."
13491
14015
  }
13492
14016
  },
13493
14017
  "required": [
@@ -14031,7 +14555,7 @@
14031
14555
  "/tools/deleteTaskDependency": {
14032
14556
  "post": {
14033
14557
  "summary": "deleteTaskDependency",
14034
- "description": "Remove a task-dependency edge. Neither item's dates are changed.",
14558
+ "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).",
14035
14559
  "operationId": "deleteTaskDependency",
14036
14560
  "tags": [
14037
14561
  "plans"
@@ -14559,7 +15083,7 @@
14559
15083
  "/tools/kg_search": {
14560
15084
  "post": {
14561
15085
  "summary": "kg_search",
14562
- "description": "Unified Knowledge Graph KNOWLEDGE retrieval — facts, themes and relationships from INSIDE document CONTENT. This is NOT an artefact finder: do NOT use it to locate a document / whiteboard / diagram / plan / task / improvement by its TITLE or friendly id (e.g. \"DOC-123\", \"find the GTM plan\"). For locating an artefact by name or id use listDocuments / listWhiteboards / listPlans / listTasks / searchImprovements (they match title + friendly id). Use kg_search only to ANSWER A QUESTION from the knowledge contained in the artefacts.\n\nPICK THE MODE THAT FITS THE QUERY:\n\n• mode='local' (default) — for SPECIFIC factual questions (\"what does §15 say about deposits?\", \"who is the Chief Counsel?\"). FTS+vector RRF over individual document chunks. Returns precise excerpts with citations.\n\n• mode='global' — for THEMATIC / OVERVIEW / SUMMARY questions (\"what are the main themes\", \"give me an overview of the project\", \"what topics does this cover\"). Returns Louvain community summaries + curated wiki pages — far better than 'local' for big-picture queries because community summaries already aggregate across many chunks. ALWAYS PREFER over 'local' when the user asks for themes / summary / overview / topic landscape.\n\n• mode='graph' — for RELATIONSHIP questions (\"what's connected to entity X?\", \"who cites Section 5?\"). 1-hop entity-neighbourhood walk. Pass query OR srcEntityId.\n\n• mode='path' — for CONNECTION questions (\"how does X relate to Y?\"). Shortest path between two entities. Pass srcEntityId AND dstEntityId.\n\n• mode='ppr' — for MULTI-HOP discovery (\"what's relevant to X, even indirectly?\"). Personalised PageRank over AUTHORED-vs-EXTRACTED weighted edges, seeded by query-similar entities. Best when 'local' returns too few results and the answer requires walking through several entity hops.\n\nQuick decision tree:\n- User asks for an overview/summary/themes → 'global'\n- User asks a specific question with a clear answer → 'local'\n- User asks 'how is X connected to Y' → 'path' (with both entity IDs)\n- User asks 'what's near entity X' → 'graph' (with srcEntityId)\n- 'local' returned nothing useful and the question is broad → retry with 'ppr'",
15086
+ "description": "Unified Knowledge Graph KNOWLEDGE retrieval — facts, themes and relationships from INSIDE document CONTENT. This is NOT an artefact finder: do NOT use it to locate a document / whiteboard / diagram / plan / task / improvement by its TITLE or friendly id (e.g. \"DOC-123\", \"find the GTM plan\"). For locating an artefact by name or id use listDocuments / listWhiteboards / listPlans / listTasks / searchImprovements (they match title + friendly id). Use kg_search only to ANSWER A QUESTION from the knowledge contained in the artefacts.\n\nPICK THE MODE THAT FITS THE QUERY:\n\n• mode='local' (default) — for SPECIFIC factual questions (\"what does section 15 say about deposits?\", \"who is the Chief Counsel?\"). FTS+vector RRF over individual document chunks. Returns precise excerpts with citations.\n\n• mode='global' — for THEMATIC / OVERVIEW / SUMMARY questions (\"what are the main themes\", \"give me an overview of the project\", \"what topics does this cover\"). Returns Louvain community summaries + curated wiki pages — far better than 'local' for big-picture queries because community summaries already aggregate across many chunks. ALWAYS PREFER over 'local' when the user asks for themes / summary / overview / topic landscape.\n\n• mode='graph' — for RELATIONSHIP questions (\"what's connected to entity X?\", \"who cites Section 5?\"). 1-hop entity-neighbourhood walk. Pass query OR srcEntityId.\n\n• mode='path' — for CONNECTION questions (\"how does X relate to Y?\"). Shortest path between two entities. Pass srcEntityId AND dstEntityId.\n\n• mode='ppr' — for MULTI-HOP discovery (\"what's relevant to X, even indirectly?\"). Personalised PageRank over AUTHORED-vs-EXTRACTED weighted edges, seeded by query-similar entities. Best when 'local' returns too few results and the answer requires walking through several entity hops.\n\nQuick decision tree:\n- User asks for an overview/summary/themes → 'global'\n- User asks a specific question with a clear answer → 'local'\n- User asks 'how is X connected to Y' → 'path' (with both entity IDs)\n- User asks 'what's near entity X' → 'graph' (with srcEntityId)\n- 'local' returned nothing useful and the question is broad → retry with 'ppr'",
14563
15087
  "operationId": "kg_search",
14564
15088
  "tags": [
14565
15089
  "knowledge_graph"
@@ -14588,10 +15112,12 @@
14588
15112
  "description": "Retrieval strategy. See tool description for when to use each — strongly prefer 'global' for thematic/overview questions."
14589
15113
  },
14590
15114
  "projectId": {
14591
- "type": "string"
15115
+ "type": "string",
15116
+ "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."
14592
15117
  },
14593
15118
  "workspaceId": {
14594
- "type": "string"
15119
+ "type": "string",
15120
+ "description": "Alternative to projectId — searches the whole workspace subtree. Give one of the two."
14595
15121
  },
14596
15122
  "srcEntityId": {
14597
15123
  "type": "string",
@@ -14815,6 +15341,10 @@
14815
15341
  },
14816
15342
  "name": {
14817
15343
  "type": "string"
15344
+ },
15345
+ "projectId": {
15346
+ "type": "string",
15347
+ "description": "Scope the lookup to one project. Recommended when resolving by `name`, since the same entity name can exist in several projects."
14818
15348
  }
14819
15349
  }
14820
15350
  }
@@ -17989,7 +18519,7 @@
17989
18519
  "/tools/createProject": {
17990
18520
  "post": {
17991
18521
  "summary": "createProject",
17992
- "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.",
18522
+ "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.",
17993
18523
  "operationId": "createProject",
17994
18524
  "tags": [
17995
18525
  "organization"
@@ -18019,7 +18549,7 @@
18019
18549
  "icon": {
18020
18550
  "type": "string",
18021
18551
  "maxLength": 32,
18022
- "description": "Optional emoji icon. Defaults to '📁' to match the UI."
18552
+ "description": "Optional emoji icon. Defaults to a folder emoji to match the UI."
18023
18553
  }
18024
18554
  },
18025
18555
  "required": [