@stablebaseline/sdk 0.4.4 → 0.5.0

package/openapi.json

@@ -606,7 +606,7 @@
         "description": "Semantic search over the 276 AntV Infographic templates — call this FIRST when building an `infographic` diagram so you pick the right structure for the content. Describe the intent (e.g. 'compare two options', 'show a process timeline', 'pyramid of priorities', 'org hierarchy', 'flow between systems', 'parts of a whole'); results are vector-ranked. Each result has `key` (use as line 1 `infographic <key>`), `name`, `family` (list|sequence|compare|relation|chart|hierarchy|quadrant), and `description`. The result's `usage` explains the family→data-field mapping for writing the DSL.",
         "operationId": "searchInfographicTemplates",
         "tags": [
-          "uncategorized"
+          "diagrams"
         ],
         "requestBody": {
           "required": false,
@@ -3876,11 +3876,11 @@
         }
       }
     },
-    "/tools/designWhiteboard": {
+    "/tools/autoDesignWhiteboard": {
       "post": {
-        "summary": "designWhiteboard",
-        "description": "Design a complete, visually polished whiteboard from a natural-language goal using the PREMIUM multi-agent pipeline (the same one the in-app assistant uses): it browses the stencil/icon library, composes the board, renders it, critiques the rendered image, and refines — far better than hand-placing shapes. COST + APPROVAL: this costs 50 credits per board and requires the user's explicit approval. Call it FIRST without `confirm` to get the exact cost + the workspace credit balance; show that to the user and only call again with `confirm: true` once they agree. If they decline (or lack credits), build the board directly with the standard whiteboard tools (addWhiteboardElements / insertWhiteboardDiagram / listWhiteboardStencils) at no extra charge. It runs in the BACKGROUND and returns immediately with a sessionId; the board fills in over 1-3 minutes. The 50 credits are refunded automatically if the design fails on our side. Optional `designProfile: 'branded-executive'` instead builds an ON-BRAND, fully-editable McKinsey-style SLIDE DECK themed by the org's brand kit (palette/fonts) — use it when the user wants polished branded business slides; it builds in-process and the board is ready on return. Optional `designProfile: 'illustrated'` instead builds an editable-illustration board: pick it for illustrated, image-based, picture-style, richly-drawn or educational explainer boards (e.g. illustrate photosynthesis, an illustrated diagram of the water cycle, a textbook-style visual). It generates a rich text-free vector illustration and overlays real, editable text labels with leader lines on top. It is gated per organisation; if it is not enabled the call returns a clear message, so fall back to the standard design. Optional `designProfile: 'image'` instead builds a single, polished, on-brand IMAGE board with all the text baked into the picture (no editable shapes): pick 'image' when the user wants a single finished image, poster or infographic they will refine by AI mask edits rather than by moving editable shapes. It is also gated per organisation; if it is not enabled the call returns a clear message.",
-        "operationId": "designWhiteboard",
+        "summary": "autoDesignWhiteboard",
+        "description": "Auto-design a complete, visually polished whiteboard from a natural-language goal using the PREMIUM multi-agent pipeline (the same one the in-app assistant uses): it browses the stencil/icon library, composes the WHOLE board, renders it, critiques the rendered image, and refines — far better than hand-placing shapes. This is the one-shot whole-board designer; it is NOT a conversation (for a deck you can chat with and refine turn by turn use designDeckInWhiteboard, and for a refinable illustration use designIllustrationInWhiteboard). COST + APPROVAL: this costs 50 credits per board and requires the user's explicit approval. Call it FIRST without `confirm` to get the exact cost + the workspace credit balance; show that to the user and only call again with `confirm: true` once they agree. If they decline (or lack credits), build the board directly with the standard whiteboard tools (addWhiteboardElements / insertWhiteboardDiagram / listWhiteboardStencils) at no extra charge. It runs in the BACKGROUND and returns immediately with a sessionId; the board fills in over 1-3 minutes. The 50 credits are refunded automatically if the design fails on our side. Optional `designProfile: 'branded-executive'` instead builds an ON-BRAND, fully-editable McKinsey-style SLIDE DECK themed by the org's brand kit (palette/fonts) — use it when the user wants polished branded business slides; it builds in-process and the board is ready on return. Optional `designProfile: 'illustrated'` instead builds an editable-illustration board: pick it for illustrated, image-based, picture-style, richly-drawn or educational explainer boards (e.g. illustrate photosynthesis, an illustrated diagram of the water cycle, a textbook-style visual). It generates a rich text-free vector illustration and overlays real, editable text labels with leader lines on top. It is available to every organisation and costs the same flat 50 credits (credits are the only gate). Optional `designProfile: 'image'` instead builds a single, polished, on-brand IMAGE board with all the text baked into the picture (no editable shapes): pick 'image' when the user wants a single finished image, poster or infographic they will refine by AI mask edits rather than by moving editable shapes. It is also available to every organisation at the same flat 50 credits.",
+        "operationId": "autoDesignWhiteboard",
         "tags": [
           "whiteboards"
         ],
@@ -3921,7 +3921,7 @@
                       "agentic",
                       "agentic-deck"
                     ],
-                    "description": "Optional. 'standard' (default) = the general multi-agent design. 'agentic' = an AI-chat-style agentic slide composer that drives the whiteboard tools and self-corrects from renders, composing ONE polished slide. 'agentic-deck' = the same agentic composer run over a planned storyline, building a multi-slide deck (each slide on its own frame, tiled left to right). 'branded-executive' = an on-brand, McKinsey-style editable SLIDE DECK themed by the org's brand kit (pair with brandKitId, or omit for the org default). 'illustrated' = an editable-illustration board: a rich text-free vector illustration with real editable text labels and leader lines placed on top. 'image' = a single polished, on-brand IMAGE board with all the text baked into the picture (no editable shapes), which the user then refines with AI mask edits. 'illustrated' and 'image' are each gated per organisation; if not enabled the call returns a clear message."
+                    "description": "Optional. 'standard' (default) = the general multi-agent design. 'agentic' = an AI-chat-style agentic slide composer that drives the whiteboard tools and self-corrects from renders, composing ONE polished slide. 'agentic-deck' = the same agentic composer run over a planned storyline, building a multi-slide deck (each slide on its own frame, tiled left to right). 'branded-executive' = an on-brand, McKinsey-style editable SLIDE DECK themed by the org's brand kit (pair with brandKitId, or omit for the org default). 'illustrated' = an editable-illustration board: a rich text-free vector illustration with real editable text labels and leader lines placed on top. 'image' = a single polished, on-brand IMAGE board with all the text baked into the picture (no editable shapes), which the user then refines with AI mask edits. Every profile is available to every organisation; the flat credit fee is the only gate."
                   },
                   "brandKitId": {
                     "type": "string",
@@ -4013,10 +4013,10 @@
     "/tools/designComponent": {
       "post": {
         "summary": "designComponent",
-        "description": "Design ONE reusable, on-brand SLIDE COMPONENT and add it to the org's component library so every future branded deck (designWhiteboard designProfile:'branded-executive') can use it. This is the self-improving design loop: an agent AUTHORS the component as a declarative template (a gradient/shadow/curve SVG skin + a native editable PPTX shape + reflowing bound-text slots), RENDERS it, a vision critic COMPARES the render to your brief and lists gaps, and it FIXES + re-renders until polished — then validates and stores it. Use it to grow the deck component catalogue beyond the built-ins (e.g. a 'kpi.delta' stat with an up/down arrow, a 'quote.card', a 'logo.strip'). Browse-first: if a component with this `key` already exists it is reused (pass force:true to redesign). Provide example `sampleSlots` so it can lay out real content, and a `projectId` for the small preview board it builds. Returns the stored component, the per-round critique trail, and the preview board id. It uses a few AI calls + renders (no flat credit charge); the new component is then free to reuse forever.",
+        "description": "Design ONE reusable, on-brand SLIDE COMPONENT and add it to the org's component library so every future branded deck (autoDesignWhiteboard designProfile:'branded-executive') can use it. This is the self-improving design loop: an agent AUTHORS the component as a declarative template (a gradient/shadow/curve SVG skin + a native editable PPTX shape + reflowing bound-text slots), RENDERS it, a vision critic COMPARES the render to your brief and lists gaps, and it FIXES + re-renders until polished — then validates and stores it. Use it to grow the deck component catalogue beyond the built-ins (e.g. a 'kpi.delta' stat with an up/down arrow, a 'quote.card', a 'logo.strip'). Browse-first: if a component with this `key` already exists it is reused (pass force:true to redesign). Provide example `sampleSlots` so it can lay out real content, and a `projectId` for the small preview board it builds. Returns the stored component, the per-round critique trail, and the preview board id. It uses a few AI calls + renders (no flat credit charge); the new component is then free to reuse forever.",
         "operationId": "designComponent",
         "tags": [
-          "uncategorized"
+          "whiteboards"
         ],
         "requestBody": {
           "required": false,
@@ -4163,7 +4163,7 @@
     "/tools/editWhiteboardImageRegion": {
       "post": {
         "summary": "editWhiteboardImageRegion",
-        "description": "Mask-edit (inpaint) one region of an image element on a whiteboard. Given the target image element id and a paint MASK (a PNG where WHITE marks the area to regenerate and BLACK is kept), it regenerates only the masked region using the prompt and replaces the image IN PLACE (same position + size). This is mainly used by the in-app image-board mask editor for boards designed with designProfile:'image'. It costs a small flat credit charge (refunded automatically if the edit fails on our side). It is gated per organisation behind the same 'whiteboard_design_image' feature as the image design profile; if that is not enabled the call returns a clear message.",
+        "description": "Mask-edit (inpaint) one region of an image element on a whiteboard. Given the target image element id and a paint MASK (a PNG where WHITE marks the area to regenerate and BLACK is kept), it regenerates only the masked region using the prompt and replaces the image IN PLACE (same position + size). This is mainly used by the in-app image-board mask editor for boards designed with designProfile:'image'. It is available to every organisation; the small flat credit charge is the only gate (refunded automatically if the edit fails on our side).",
         "operationId": "editWhiteboardImageRegion",
         "tags": [
           "whiteboards"
@@ -4281,13 +4281,13 @@
         }
       }
     },
-    "/tools/exportDeck": {
+    "/tools/designDeckInWhiteboard": {
       "post": {
-        "summary": "exportDeck",
-        "description": "Export an already-generated slide DECK (from the branded HTML-deck pipeline) to an editable PowerPoint (PPTX), PDF, PNG images, or raw HTML. Give it the deckId of a deck whose status is 'ready'; it downloads the deck's stored HTML and renders it in a headless browser via the export worker. 'pptx' = native, fully-editable PowerPoint (real shapes and text, not screenshots); 'pdf' = vector, one page per slide; 'png' = one image per slide (returned as a base64 array); 'html' = the self-contained deck HTML. Returns the file as base64 in `data` (pptx/pdf/html) or per-slide base64 in `slides` (png). The deck must be finished; a deck that is still generating, failed, or archived returns a clear message.",
-        "operationId": "exportDeck",
+        "summary": "designDeckInWhiteboard",
+        "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.",
+        "operationId": "designDeckInWhiteboard",
         "tags": [
-          "uncategorized"
+          "whiteboards"
         ],
         "requestBody": {
           "required": false,
@@ -4296,149 +4296,78 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "deckId": {
+                  "documentId": {
                     "type": "string",
-                    "description": "The id of an existing, finished ('ready') deck to export."
+                    "description": "The whiteboard the deck lives in. REQUIRED: a deck cannot exist without a whiteboard, and this is that whiteboard's id. If you do not already have a whiteboard id, ASK THE USER which whiteboard to design the deck in — never create one automatically. Only call createWhiteboard first if the user explicitly wants a new board."
                   },
-                  "format": {
+                  "message": {
                     "type": "string",
-                    "enum": [
-                      "pptx",
-                      "pdf",
-                      "png",
-                      "html"
-                    ],
-                    "description": "Output format. 'pptx' (default) = editable PowerPoint; 'pdf' = vector PDF; 'png' = one base64 image per slide; 'html' = the deck's self-contained HTML."
+                    "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."
                   },
-                  "brandKitId": {
-                    "type": "string",
-                    "description": "Optional brand kit id (reserved for future per-export theming; the deck is already branded, so this is usually unnecessary)."
-                  }
-                },
-                "required": [
-                  "deckId"
-                ]
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "additionalProperties": true
-                }
-              }
-            }
-          },
-          "400": {
-            "description": "Validation error.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            }
-          },
-          "401": {
-            "description": "Missing or invalid credentials.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            }
-          },
-          "403": {
-            "description": "Authenticated but lacking the required permission or feature flag.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            }
-          },
-          "404": {
-            "description": "Resource not found.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            }
-          },
-          "422": {
-            "description": "Body did not match the tool's input schema.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            }
-          },
-          "500": {
-            "description": "Server error.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/tools/generateIllustration": {
-      "post": {
-        "summary": "generateIllustration",
-        "description": "Generate a standalone, on-brand ILLUSTRATION (raw pixels) from a plain-language prompt, the one thing native shapes and diagrams cannot make. Returns a durable image URL you can insert into a whiteboard or document. Colour-conditioned to the organisation's brand (or a specific brandKitId) and rendered in a clean flat-vector editorial style with NO text, letters, or numbers baked in. Costs a small flat credit charge (refunded automatically if generation fails on our side); an identical prompt reuses a cached image at no charge.",
-        "operationId": "generateIllustration",
-        "tags": [
-          "uncategorized"
-        ],
-        "requestBody": {
-          "required": false,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "prompt": {
+                  "sessionId": {
                     "type": "string",
-                    "description": "Plain-language description of the illustration to generate (e.g. 'a friendly robot assistant helping a small team')."
+                    "description": "The design conversation to continue, as returned by an earlier designDeckInWhiteboard call. Pass it together with message to answer a question, make an edit, or send a follow-up. Omit on the very first call to start a new conversation."
                   },
-                  "width": {
-                    "type": "number",
-                    "description": "Optional output width in px (rounded to a multiple of 64, 512 to 2048). Default 1024."
+                  "deckId": {
+                    "type": "string",
+                    "description": "Optional. An existing deck to continue designing (usually you pass sessionId instead; when both are given the session's deck wins)."
                   },
-                  "height": {
-                    "type": "number",
-                    "description": "Optional output height in px (rounded to a multiple of 64, 512 to 2048). Default 1024."
+                  "kind": {
+                    "type": "string",
+                    "enum": [
+                      "deck",
+                      "illustration",
+                      "design",
+                      "express"
+                    ],
+                    "description": "Which engine. 'deck' (default) = the premium on-brand HTML deck (conversational, build + edit); 'illustration' and 'design' are conversational variants. 'express' = the native, deterministic branded-executive deck (faster, lower fidelity, one-shot, not conversational)."
                   },
-                  "style": {
+                  "title": {
                     "type": "string",
-                    "description": "Optional extra style hint appended to the prompt (e.g. 'isometric', 'soft gradients, pastel')."
+                    "description": "Optional title. If omitted, a clear one is derived from the brief."
                   },
                   "brandKitId": {
                     "type": "string",
-                    "description": "Optional brand kit id to colour-condition the illustration. Defaults to the organisation's effective brand."
+                    "description": "Optional brand kit id (from listBrandKits) to theme the deck. If omitted, the organisation's effective brand is used."
                   },
-                  "documentId": {
-                    "type": "string",
-                    "description": "Optional document this illustration is for (used only for usage logging and provenance)."
+                  "slideCount": {
+                    "type": "number",
+                    "description": "Optional target number of slides for a build turn (the composer adjusts to fit the story). Typical 6 to 12."
+                  },
+                  "attachments": {
+                    "type": "array",
+                    "description": "Optional reference images for THIS turn (up to 8; images only). The agent lifts palette, layout, and tone from them (it does not pixel-copy). Non-image attachments are ignored.",
+                    "items": {
+                      "type": "object",
+                      "description": "One reference image: give a public url, OR base64 data plus its mediaType.",
+                      "properties": {
+                        "url": {
+                          "type": "string",
+                          "description": "A public https URL to the image."
+                        },
+                        "data": {
+                          "type": "string",
+                          "description": "The image as base64 (no data: prefix). Provide mediaType alongside it."
+                        },
+                        "mediaType": {
+                          "type": "string",
+                          "description": "The image MIME type, e.g. 'image/png' or 'image/jpeg'."
+                        },
+                        "name": {
+                          "type": "string",
+                          "description": "Optional human-readable name for the image."
+                        }
+                      }
+                    }
+                  },
+                  "confirm": {
+                    "type": "boolean",
+                    "description": "Set true ONLY after the user has approved the cost (50 for a build, 10 for an edit). Leave unset/false on the first call of a turn to receive the cost quote plus balance. A clarifying question turn is never charged."
                   }
                 },
                 "required": [
-                  "prompt"
+                  "documentId",
+                  "message"
                 ]
               }
             }
@@ -4519,13 +4448,13 @@
         }
       }
     },
-    "/tools/designDeck": {
+    "/tools/designIllustrationInWhiteboard": {
       "post": {
-        "summary": "designDeck",
-        "description": "Design a complete, branded HTML slide deck from a plain-language goal using the premium agentic deck builder. COST-GATED (50 credits): the first call (confirm unset) returns the cost quote plus the workspace balance so you can ask the user; only a call with confirm:true charges the flat fee and builds the deck. The deck is themed to the organisation's brand (or a brandKitId), composed slide by slide, rendered and self-corrected, then saved as a finished deck you can export with exportDeck (pptx/pdf/png/html). The fee is auto-refunded if the build fails or produces nothing. If the user would rather not spend the credits, build slides another way. Requires a projectId for a new deck, or a deckId to rebuild an existing one.",
-        "operationId": "designDeck",
+        "summary": "designIllustrationInWhiteboard",
+        "description": "Create or refine a standalone ILLUSTRATION INSIDE an existing whiteboard by conversing with the AI design agent. This is the illustration sibling of designDeckInWhiteboard: same conversation, same follow-up flow, but it makes ONE on-brand illustration placed on the board (not a slide deck). Send a brief for a NEW illustration, a change to an existing one, or an answer to the agent's question. The agent generates the illustration, places it on the board, and if the brief is ambiguous it asks ONE clarifying question (answer with the same sessionId). Returns immediately; poll getDeckReplyInWhiteboard for the result. Use it when the user wants a picture they can talk about and refine turn by turn (e.g. 'draw a friendly robot onboarding a new team', then 'make it warmer', 'add a second robot'). For a quick one-shot illustration with no follow-up, use generateIllustrationInWhiteboard instead. WHITEBOARD IS REQUIRED: an illustration 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 illustration 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. 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 illustration's id), status, turnType, started, awaitingUser, needsConfirmation, insufficientCredits, and assistantMessage.",
+        "operationId": "designIllustrationInWhiteboard",
         "tags": [
-          "uncategorized"
+          "whiteboards"
         ],
         "requestBody": {
           "required": false,
@@ -4534,38 +4463,64 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "goal": {
+                  "documentId": {
                     "type": "string",
-                    "description": "The deck to build, in plain language (topic, audience, and what it should cover)."
+                    "description": "The whiteboard the illustration lives in. REQUIRED: an illustration cannot exist without a whiteboard, and this is that whiteboard's id. If you do not already have a whiteboard id, ASK THE USER which whiteboard to design the illustration in — never create one automatically. Only call createWhiteboard first if the user explicitly wants a new board."
                   },
-                  "projectId": {
+                  "message": {
                     "type": "string",
-                    "description": "The project to create the deck in. Required when no deckId is given (a deck must live in a project)."
+                    "description": "This turn's message in plain language: the illustration brief on the first turn, a change 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."
                   },
-                  "title": {
+                  "sessionId": {
                     "type": "string",
-                    "description": "Optional deck title. If omitted, a clear title is derived from the goal."
+                    "description": "The design conversation to continue, as returned by an earlier designIllustrationInWhiteboard call. Pass it together with message to answer a question, make a change, or send a follow-up. Omit on the very first call to start a new conversation."
                   },
                   "deckId": {
                     "type": "string",
-                    "description": "Optional. An existing deck to rebuild. If omitted, a new deck is created in projectId."
+                    "description": "Optional. An existing illustration to continue refining (usually you pass sessionId instead; when both are given the session's illustration wins). The id is called deckId because illustrations and decks share the same conversation spine."
+                  },
+                  "title": {
+                    "type": "string",
+                    "description": "Optional title. If omitted, a clear one is derived from the brief."
                   },
                   "brandKitId": {
                     "type": "string",
-                    "description": "Optional brand kit id (from listBrandKits) to theme the deck. If omitted, the organisation's effective brand is used. Create one from a logo or a .pptx/.docx via createBrandKit."
+                    "description": "Optional brand kit id (from listBrandKits) to colour-condition the illustration. If omitted, the organisation's effective brand is used."
                   },
-                  "slideCount": {
-                    "type": "number",
-                    "description": "Optional target number of slides (the composer adjusts to fit the story). Typical 6 to 12."
+                  "attachments": {
+                    "type": "array",
+                    "description": "Optional reference images for THIS turn (up to 8; images only). The agent lifts palette, layout, and tone from them (it does not pixel-copy). Non-image attachments are ignored.",
+                    "items": {
+                      "type": "object",
+                      "description": "One reference image: give a public url, OR base64 data plus its mediaType.",
+                      "properties": {
+                        "url": {
+                          "type": "string",
+                          "description": "A public https URL to the image."
+                        },
+                        "data": {
+                          "type": "string",
+                          "description": "The image as base64 (no data: prefix). Provide mediaType alongside it."
+                        },
+                        "mediaType": {
+                          "type": "string",
+                          "description": "The image MIME type, e.g. 'image/png' or 'image/jpeg'."
+                        },
+                        "name": {
+                          "type": "string",
+                          "description": "Optional human-readable name for the image."
+                        }
+                      }
+                    }
                   },
                   "confirm": {
                     "type": "boolean",
-                    "description": "Set true ONLY after the user has approved the 50-credit cost. Leave unset/false on the first call to receive the cost quote plus balance."
+                    "description": "Set true ONLY after the user has approved the cost (50 for a build, 10 for an edit). Leave unset/false on the first call of a turn to receive the cost quote plus balance. A clarifying question turn is never charged."
                   }
                 },
                 "required": [
-                  "goal",
-                  "projectId"
+                  "documentId",
+                  "message"
                 ]
               }
             }
@@ -4646,13 +4601,13 @@
         }
       }
     },
-    "/tools/editDeck": {
+    "/tools/getDeckReplyInWhiteboard": {
       "post": {
-        "summary": "editDeck",
-        "description": "Make a targeted change to an existing, finished deck using the agentic deck builder. COST-GATED (10 credits): the first call (confirm unset) returns the cost quote plus balance; only confirm:true charges the fee and applies the edit. Loads the deck's current HTML, makes ONLY the requested change (leaving other slides intact), renders to verify it, and re-saves. The fee is auto-refunded if the edit makes no change or fails.",
-        "operationId": "editDeck",
+        "summary": "getDeckReplyInWhiteboard",
+        "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.",
+        "operationId": "getDeckReplyInWhiteboard",
         "tags": [
-          "uncategorized"
+          "whiteboards"
         ],
         "requestBody": {
           "required": false,
@@ -4661,26 +4616,18 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "deckId": {
+                  "documentId": {
                     "type": "string",
-                    "description": "The id of the finished deck to edit."
+                    "description": "The whiteboard that hosts the deck or illustration (it lives inside the board). REQUIRED."
                   },
-                  "instruction": {
+                  "deckId": {
                     "type": "string",
-                    "description": "The change to make, in plain language (e.g. 'change the title slide subhead to ...', 'make slide 3 a bar chart of these numbers ...')."
-                  },
-                  "slideIndex": {
-                    "type": "number",
-                    "description": "Optional 1-based slide number to focus the edit on. Omit to let the builder find the right slide(s) from the instruction."
-                  },
-                  "confirm": {
-                    "type": "boolean",
-                    "description": "Set true ONLY after the user has approved the 10-credit cost. Leave unset/false on the first call to receive the cost quote plus balance."
+                    "description": "The deck or illustration to poll, as returned by designDeckInWhiteboard or designIllustrationInWhiteboard."
                   }
                 },
                 "required": [
-                  "deckId",
-                  "instruction"
+                  "documentId",
+                  "deckId"
                 ]
               }
             }
@@ -4761,11 +4708,11 @@
         }
       }
     },
-    "/tools/insertDeckIntoWhiteboard": {
+    "/tools/exportFromWhiteboard": {
       "post": {
-        "summary": "insertDeckIntoWhiteboard",
-        "description": "Render a FINISHED slide DECK's pages into framed images on a WHITEBOARD: one Excalidraw frame per slide, laid out as a horizontal row of pages so the whole deck appears on the board to pan across, annotate around, and edit beside. Give it the deckId of a deck whose status is 'ready'; it renders each slide to a PNG (via the export worker) and drops each image inside its own 1280x720 frame named 'Slide N'. Pass an existing whiteboard documentId to place the slides on it, or a projectId to create a new board (defaults to the deck's own project; the new board is named '<deck title> (deck)'). Returns the documentId, the number of slide frames placed, and the board title. The deck must be finished; a deck that is still generating, failed, or archived returns a clear message.",
-        "operationId": "insertDeckIntoWhiteboard",
+        "summary": "exportFromWhiteboard",
+        "description": "Export a design that lives in a whiteboard to an editable PowerPoint (PPTX), PDF, PNG images, or raw HTML. Give it the whiteboard documentId and the designId (the deck). kind:'deck' (default) renders the finished deck via the export worker: 'pptx' = native, fully-editable PowerPoint (real shapes and text, not screenshots); 'pdf' = vector, one page per slide; 'png' = one image per slide (returned as a base64 array); 'html' = the self-contained deck HTML. Returns the file as base64 in data (pptx/pdf/html) or per-slide base64 in slides (png). The design must be finished; one that is still generating, failed, or archived returns a clear message.",
+        "operationId": "exportFromWhiteboard",
         "tags": [
           "whiteboards"
         ],
@@ -4776,21 +4723,39 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "deckId": {
+                  "documentId": {
                     "type": "string",
-                    "description": "The id of an existing, finished ('ready') deck whose slides to place on a whiteboard."
+                    "description": "The whiteboard that hosts the design."
                   },
-                  "documentId": {
+                  "designId": {
                     "type": "string",
-                    "description": "Optional existing whiteboard to place the slides on. When omitted, a new whiteboard is created in projectId."
+                    "description": "The design to export (the deck id), as returned by designDeckInWhiteboard."
                   },
-                  "projectId": {
+                  "kind": {
                     "type": "string",
-                    "description": "Optional project to create the new whiteboard in when documentId is omitted. Defaults to the deck's own project."
+                    "enum": [
+                      "deck"
+                    ],
+                    "description": "Which engine. 'deck' (default)."
+                  },
+                  "format": {
+                    "type": "string",
+                    "enum": [
+                      "pptx",
+                      "pdf",
+                      "png",
+                      "html"
+                    ],
+                    "description": "Output format. 'pptx' (default) = editable PowerPoint; 'pdf' = vector PDF; 'png' = one base64 image per slide; 'html' = the design's self-contained HTML."
+                  },
+                  "brandKitId": {
+                    "type": "string",
+                    "description": "Optional brand kit id (reserved for future per-export theming; the design is already branded, so this is usually unnecessary)."
                   }
                 },
                 "required": [
-                  "deckId"
+                  "documentId",
+                  "designId"
                 ]
               }
             }
@@ -5546,6 +5511,11 @@
                               ]
                             }
                           }
+                        },
+                        "customData": {
+                          "type": "object",
+                          "description": "Arbitrary Excalidraw customData stored on the element (e.g. a slide frame's { deckId } so a board frame resolves back to its source deck). Merged with any builder-set customData.",
+                          "additionalProperties": true
                         }
                       },
                       "additionalProperties": true
@@ -5831,6 +5801,10 @@
                   "fileName": {
                     "type": "string",
                     "description": "Optional original filename (for storage + type hinting)."
+                  },
+                  "locked": {
+                    "type": "boolean",
+                    "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."
                   }
                 },
                 "required": [
@@ -6455,7 +6429,7 @@
     "/tools/getWhiteboardImage": {
       "post": {
         "summary": "getWhiteboardImage",
-        "description": "Render a whiteboard to an IMAGE so you can SEE it and confirm your edits look right, then iterate — like taking a screenshot. Returns the rendered board as a viewable image attached to the result. Pass elementIds to render only specific shapes (e.g. to inspect one section/slide), region:{x,y,width,height} to capture an exact scene-coordinate window (e.g. the user's viewport), theme:'light' for the fastest single-variant render, format:'svg' for vector markup, or background to set the canvas colour. Unchanged boards return instantly from a content-keyed cache. Call this after addWhiteboardElements/updateWhiteboardScene to check layout, overlaps, labels and alignment before continuing.",
+        "description": "Render a whiteboard to a raster IMAGE so you can SEE it and confirm your edits look right, then iterate — like taking a screenshot. Returns the rendered board as a viewable image attached to the result (always raster: a JPEG light variant and/or a PNG dark variant; there is no vector/SVG output, so for a vector export of a single diagram use getDiagramImage). Pass elementIds to render only specific shapes (e.g. to inspect one section/slide), region:{x,y,width,height} to capture an exact scene-coordinate window (e.g. the user's viewport), theme:'light' for the fastest single-variant render, or background to set the canvas colour. Unchanged boards return instantly from a content-keyed cache. Call this after addWhiteboardElements/updateWhiteboardScene to check layout, overlaps, labels and alignment before continuing.",
         "operationId": "getWhiteboardImage",
         "tags": [
           "whiteboards"
@@ -6471,14 +6445,6 @@
                     "type": "string",
                     "description": "The whiteboard's documentId."
                   },
-                  "format": {
-                    "type": "string",
-                    "enum": [
-                      "png",
-                      "svg"
-                    ],
-                    "description": "png (default — a viewable raster) or svg (vector markup)."
-                  },
                   "elementIds": {
                     "type": "array",
                     "items": {
@@ -22634,7 +22600,7 @@
         "description": "Create a per-org BRAND KIT so Stable Baseline outputs come out fully on-brand. Upload your branding and it is auto-applied: pass a `logoUrl` (as little as your logo, and the vision model AUTO-EXTRACTS your palette and fonts), or an `officeUrl` (an existing .pptx/.docx, from which it extracts theme colours, fonts, logo, watermark and the embedded font files), or explicit `tokens`. The kit themes branded-executive slides AND document exports (PDF, Word, PowerPoint). Auth: can_admin_org. Tiered: free 0, pro 1, enterprise unlimited. Optionally set it as the default at a scope in one call.",
         "operationId": "createBrandKit",
         "tags": [
-          "uncategorized"
+          "settings"
         ],
         "requestBody": {
           "required": false,
@@ -22771,7 +22737,7 @@
         "description": "List an organisation's BRAND KITS (palette/fonts/logo), newest first. Use a returned `id` as brandKitId for a design call or setDefaultBrandKit. Auth: can_admin_org.",
         "operationId": "listBrandKits",
         "tags": [
-          "uncategorized"
+          "settings"
         ],
         "requestBody": {
           "required": false,
@@ -22872,7 +22838,7 @@
         "description": "Set or clear the default BRAND KIT at a scope: organization, workspace, or project. Defaults cascade most-specific-first (a per-board/document override beats project beats workspace beats organization). Pass brandKitId:null to clear. Auth: org owner/admin.",
         "operationId": "setDefaultBrandKit",
         "tags": [
-          "uncategorized"
+          "settings"
         ],
         "requestBody": {
           "required": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stablebaseline/sdk",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "TypeScript SDK for the Stable Baseline REST API. End-to-end agent-managed company brain — docs, diagrams, plans, and a self-learning Knowledge Graph. 184 tools across 19 categories.",
   "homepage": "https://stablebaseline.io",
   "repository": {