@stablebaseline/sdk 0.2.0 → 0.3.1

package/dist/index.d.cts

@@ -74,7 +74,7 @@ interface paths {
         put?: never;
         /**
          * listArchitectureIcons
-         * @description List icons for systemsarchitecture diagrams. Use returned iconPath as-is in D2 code (e.g. icon: dev/docker.svg).
+         * @description List curated software-architecture icons (AWS, Azure, GCP, Docker, Kubernetes, databases, message queues, etc.). 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).
          */
         post: operations["listArchitectureIcons"];
         delete?: never;
@@ -674,7 +674,7 @@ interface paths {
         put?: never;
         /**
          * updateWhiteboardScene
-         * @description Edit elements on a whiteboard's canvas WITHOUT dropping the rest of the scene. A board may hold many diagrams/elements, so prefer surgical edits: mode='patch' (DEFAULT) shallow-merges each incoming object into the existing element with the same `id` (send just {id, backgroundColor:'blue'} to recolour one box, or {id, x, y} to move one) and appends any elements whose id is new/absent — everything else is left untouched. `deleteIds` removes specific elements by id. mode='append' only adds. mode='replace' overwrites the ENTIRE scene (use ONLY when intentionally rewriting the whole board). To author NEW shapes/connectors from a high-level spec, prefer addWhiteboardElements. Optional appState/files are merged in. PROCESS: for a non-trivial edit call getWhiteboardGuide FIRST; after editing, ALWAYS call getWhiteboardImage to confirm the board still looks right (layout, labels, overlaps), and patch again if it doesn't.
+         * @description Edit elements on a whiteboard's canvas WITHOUT dropping the rest of the scene. A board may hold many diagrams/elements, so prefer surgical edits: mode='patch' (DEFAULT) shallow-merges each incoming object into the existing element with the same `id` (send just {id, backgroundColor:'blue'} to recolour one box, or {id, x, y} to move one) and appends any elements whose id is new/absent — everything else is left untouched. `deleteIds` removes specific elements by id. mode='append' only adds. mode='replace' overwrites the ENTIRE scene — to rebuild or edit only PART of a board, still use 'patch', because replace DELETES every element you don't resend (of ANY type). As a safeguard, a replace that would drop ANY existing element not in your payload is REJECTED unless you pass confirmReplace:true (or include those ids); diagrams/images/frames are flagged specially since they're inserted separately and costliest to lose. To author NEW shapes/connectors from a high-level spec, prefer addWhiteboardElements — and prefer library stencils / sticky notes / architecture icons over plain rectangles wherever a standard form fits (sticky notes, kanban/scrum, flowcharts, UML/ER, BPMN, org charts, wireframes). Optional appState/files are merged in. PROCESS: for a non-trivial edit call getWhiteboardGuide FIRST; after editing, ALWAYS call getWhiteboardImage to confirm the board still looks right (layout, labels, overlaps), and patch again if it doesn't.
          */
         post: operations["updateWhiteboardScene"];
         delete?: never;
@@ -694,7 +694,7 @@ interface paths {
         put?: never;
         /**
          * addWhiteboardElements
-         * @description Author shapes onto a whiteboard from high-level specs (you do NOT need the full Excalidraw element schema). Appends to the canvas. 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'|'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 (sticky notes, 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. yellow sticky note>', pack?:'<pack>', x, y } to fuzzy-match by name). STRONGLY prefer these over plain rectangles whenever the user asks for sticky notes, kanban/scrum/story boards, flowcharts, wireframes/mockups, org charts, etc. 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 solid-fill notes; type 'line' with no arrowheads + roughness:2 for sketchy mind-map spokes. 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.
+         * @description Author shapes onto a whiteboard from high-level specs (you do NOT need the full Excalidraw element schema). Appends to the canvas. 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'|'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. 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.
          */
         post: operations["addWhiteboardElements"];
         delete?: never;
@@ -703,6 +703,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/tools/duplicateWhiteboardElements": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * duplicateWhiteboardElements
+         * @description Copy-paste existing whiteboard elements — the MCP equivalent of selecting a group and pressing Ctrl/Cmd+D. Clones the given elements (plus their group peers + bound text/labels) with FRESH ids, offsets the copy by dx/dy, and by default groups it into ONE new unit so it moves together. Use it to build something once (a labelled stencil frame, a kanban card, a UML class) then stamp out consistent repeats fast — then retext/recolour each copy by its new id (via the returned idMap) with updateWhiteboardScene. Pass `groupId` to copy a whole group as a unit (e.g. a placed stencil's groupId from its placement result) and/or `ids` for specific elements. Internal references (group membership, bound text containerId, arrow start/end bindings) are remapped within the copied set; a binding to an element you did NOT copy is dropped. Returns { duplicated, idMap (old id → new id), groupId (the copy's new unit group), elementCount }. Render with getWhiteboardImage afterwards to verify.
+         */
+        post: operations["duplicateWhiteboardElements"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/tools/insertWhiteboardImage": {
         parameters: {
             query?: never;
@@ -754,7 +774,7 @@ interface paths {
         put?: never;
         /**
          * listWhiteboardStencils
-         * @description Search the built-in library of STRUCTURAL whiteboard stencils — ready-made, hand-drawn multi-element graphics: sticky notes (post-it), scrum-board columns, flowchart symbols, UML/ER, BPMN, org-chart nodes, gantt, lo-fi/UX wireframe widgets, charts, and stick figures. Returns matching stencils each with a `key`, name, pack and category, plus the full pack/category lists. Place one via addWhiteboardElements({type:'stencil', stencilKey:'<key>', x, y}). These look far richer and more on-brand than plain rectangles — use them when the user asks for sticky notes, kanban/scrum boards, flowcharts, wireframes, mockups, etc. SEARCH TIPS: prefer BROAD single words ('sticky', 'decision', 'actor', 'phone', 'process') — multi-word exact phrases often miss. If an exact query matches nothing the result is auto-broadened to close candidates (broadened:true is set); you can also pass pack/category to browse. When ANY returned stencil reasonably fits, PLACE it instead of drawing a plain rectangle — do not abandon stencils just because your first phrase returned 0. The library does NOT contain free-form 'cloud' / 'hat' / 'thought-bubble' shapes; approximate those with the closest stencil (e.g. a sticky note or a simple shape) or fall back to a plain shape only when nothing fits. For cloud/architecture ICONS (AWS/Azure/GCP/Docker/Kubernetes/databases) use listArchitectureIcons instead.
+         * @description Search the built-in library of structural whiteboard stencils — ready-made hand-drawn graphics: flowchart/UML/ER/BPMN symbols, scrum columns, org-chart nodes, gantt, lo-fi/UX wireframe widgets (buttons, forms, tables, alerts, navs), charts, device frames, stick figures. A stencil is a MINI-WHITEBOARD (a collection of elements), NOT a single shape. Each result returns: `key`, `title` (a real human name e.g. 'Alerts', not an index), `kind` ('symbol' | 'template'), `labels` (the TEXT it actually contains — its real content, e.g. an Alerts template's variant messages), `size` ({w,h} px), `summary`, `pack`, `category`; plus the full pack/category lists. The two kinds are used DIFFERENTLY: • SYMBOL = one atomic labelled node (flowchart Process/Decision, BPMN task, org node). Place + label + connect: addWhiteboardElements({type:'stencil', stencilKey, id:'n1', text:'Review', width, height}) — the text auto-fits its single slot and an arrow's start/end {id:'n1'} binds to it like any shape. A few symbols are text-less FRAMES (e.g. a UML class box = rectangle + divider line): place create-only, then use the placement result's `children` (shapes + x/y/w/h) and `groupId` to add type:'text' specs INTO the regions — pass that groupId so the text is one unit with the frame. • TEMPLATE = a multi-component layout (Alerts, Forms, Tables, Charts, device frames). Place the WHOLE thing: addWhiteboardElements({type:'stencil', stencilKey, x, y, width?, height?}); the placement RESULT returns `stencils[].children` (each child's id + text + colour + position x/y/w/h, so you can group children into rows/sections) so you then keep / retext / recolour / DELETE specific parts via updateWhiteboardScene (e.g. delete the info + error rows to keep only the green success alert). Do NOT pass a single `text` to a template — read its `labels` to see its parts, then edit them by id. To make several similar items, build one then duplicateWhiteboardElements({groupId, dx}) to stamp consistent copies (like copy-paste in the UI). SEARCH TIPS: prefer BROAD single words ('decision','alert','form','phone','process'); content words match the embedded `labels` too (searching 'success' finds the Alerts template). If nothing exact matches, results auto-broaden (broadened:true); pass pack/category to browse. For cloud/architecture ICONS (AWS/Azure/GCP/Docker/Kubernetes/databases) use listArchitectureIcons; for a sticky/post-it use addWhiteboardElements({type:'sticky'}), not a stencil.
          */
         post: operations["listWhiteboardStencils"];
         delete?: never;
@@ -6591,7 +6611,7 @@ interface operations {
                     /** @description Elements to write. For mode 'patch', each may be a partial { id, ...changedFields } merged into the matching element by id; full Excalidraw elements for 'replace'/'append' (or new ids in 'patch'). */
                     elements?: Record<string, never>[];
                     /**
-                     * @description patch (DEFAULT — merge by id, keep the rest), append (add only), or replace (overwrite the whole scene).
+                     * @description How to apply your `elements`. patch (DEFAULT — use this for ANY partial edit): merges each item into the element with the same id and leaves everything else untouched, like find-and-replace by id; new ids are added. append: only adds your items, changes nothing else. replace: OVERWRITES THE WHOLE CANVAS — every existing element you don't resend is DELETED — so use it ONLY to set an entire board at once. To change or rebuild just a SECTION, use patch (+ deleteIds to remove specific ids), NEVER replace. A replace that would drop any existing element is rejected unless confirmReplace:true.
                      * @enum {string}
                      */
                     mode?: "patch" | "append" | "replace";
@@ -6601,6 +6621,10 @@ interface operations {
                     appState?: Record<string, never>;
                     /** @description Optional Excalidraw BinaryFiles map (for embedded images), merged in. */
                     files?: Record<string, never>;
+                    /** @description Optional optimistic-locking token from getWhiteboard. Only used for mode 'replace': if the board changed since you read it, the replace is rejected so you don't overwrite a collaborator's newer edits — re-read with getWhiteboard and retry. Not needed for patch/append, which automatically merge onto the latest scene. */
+                    versionTimestamp?: number;
+                    /** @description Safety acknowledgement for mode 'replace' ONLY. A replace that would DELETE ANY existing element not present in your `elements` is rejected unless this is true. Leave it unset and use mode:'patch' to edit part of a board (it merges by id and keeps the rest); set true only when you truly intend to overwrite the WHOLE scene. */
+                    confirmReplace?: boolean;
                 };
             };
         };
@@ -6683,8 +6707,143 @@ interface operations {
             content: {
                 "application/json": {
                     documentId: string;
-                    /** @description Non-empty array of shape specs to append. */
-                    shapes: Record<string, never>[];
+                    /** @description Non-empty array of shape specs to append. Prefer stencils / sticky notes / architecture icons over raw rectangles wherever a standard form fits (see the `type` enum below and the tool description). */
+                    shapes: ({
+                        /**
+                         * @description Element kind. 'sticky' = a first-class sticky/post-it note (solid fill + auto-fitting bound label; set text + backgroundColor) — use this for sticky notes, NOT a stencil. 'stencil' = a hand-drawn library graphic from listWhiteboardStencils, of kind 'symbol' (one atomic labelled node — flowchart box, BPMN task, org node: set `id` + `text` + width/height, text auto-fits, connect arrows via start/end {id}) or 'template' (a multi-element layout — Alerts, Forms, Tables, Charts: place whole, then customise its returned children by id; do NOT set a single `text`). Set `stencil` (fuzzy name, one call) or `stencilKey` (exact). 'image' with `iconPath` = a software-architecture icon from listArchitectureIcons. Reserve rectangle/ellipse/diamond for when no standard form fits.
+                         * @enum {string}
+                         */
+                        type: "rectangle" | "ellipse" | "diamond" | "sticky" | "text" | "arrow" | "line" | "frame" | "image" | "stencil";
+                        /** @description For type:'stencil' — fuzzy-match a library stencil by name in ONE call, no prior listWhiteboardStencils needed (e.g. 'decision', 'actor', 'phone frame', 'kanban column'). NOTE: there is no sticky-note stencil — use type:'sticky' for sticky/post-it notes. */
+                        stencil?: string;
+                        /** @description For type:'stencil' — exact stencil key from listWhiteboardStencils (takes precedence over `stencil`). */
+                        stencilKey?: string;
+                        /** @description For type:'stencil' — optional pack to disambiguate a fuzzy `stencil` match (e.g. 'Flowchart', 'BPMN', 'UML & ER', 'Scrum Board'). */
+                        pack?: string;
+                        /** @description For type:'image' — a software-architecture icon path from listArchitectureIcons (e.g. 'dev/docker.svg'). */
+                        iconPath?: string;
+                        /** @description For type:'image' — any other public image URL (use iconPath for curated architecture icons). */
+                        imageUrl?: string;
+                        /** @description Optional id so connectors (arrows/lines) can reference this shape via start/end. On a type:'stencil' it adds a transparent bindable anchor covering the stencil, so an arrow's start/end {id} connects to the whole stencil as a unit. */
+                        id?: string;
+                        /** @description Join an existing group. Pass a placed stencil's `groupId` (returned in the placement result) on a type:'text' or shape spec to FILL that frame as part of the same unit — the text then moves, duplicates and renders together with the frame (e.g. a title in a UML class box's top band, members in its body). */
+                        groupId?: string;
+                        /** @description Top-left x on the canvas. OMIT both x and y to auto-place this element in clear empty space below the board's existing content. Strongly preferred when adding a note/shape to a board that already has content: a guessed coordinate usually lands ON TOP of existing shapes (the 'added a sticky but can't see it' bug). Set x/y only for deliberate layout among shapes you add in this same call. */
+                        x?: number;
+                        /** @description Top-left y on the canvas. Omit together with x to auto-place (see x). */
+                        y?: number;
+                        /** @description Shape width; for type:'stencil' it scales the whole stencil to fit this width. */
+                        width?: number;
+                        /** @description Shape height; for type:'stencil' it scales the whole stencil to fit this height. */
+                        height?: number;
+                        /** @description For type:'stencil' — uniform scale factor for the whole stencil (alternative to width/height). */
+                        scale?: number;
+                        /** @description Label/caption. On a shape it's a centered auto-wrapped bound label (prefer over a separate type:'text'); on a type:'sticky' it's the note text; on a type:'stencil' of kind 'symbol' it fills + re-fits its single label (IGNORED for 'template' stencils — customise their children by id instead). */
+                        text?: string;
+                        /** @description Fill colour: a name ('blue'/'green'/'yellow'/'pink'/'violet'/'orange'/'teal'/…) or a hex value. */
+                        backgroundColor?: string;
+                        /** @description For arrows/lines: { id } of the source shape (auto-clips to the edge + auto-routes around shapes in between). */
+                        start?: Record<string, never>;
+                        /** @description For arrows/lines: { id } of the target shape. */
+                        end?: Record<string, never>;
+                    } & {
+                        [key: string]: unknown;
+                    })[];
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    duplicateWhiteboardElements: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description The whiteboard's documentId. */
+                    documentId: string;
+                    /** @description Element ids to copy. Each id's full group + any bound text are auto-included. Use this and/or groupId. */
+                    ids?: string[];
+                    /** @description Copy EVERY element in this group as one unit — e.g. a placed stencil's `groupId` returned by addWhiteboardElements. */
+                    groupId?: string;
+                    /** @description Horizontal offset for the copy (default 40). Use the element width + a gap to place copies side by side. */
+                    dx?: number;
+                    /** @description Vertical offset for the copy (default 40). */
+                    dy?: number;
+                    /** @description Group the copy into one new unit so it moves/duplicates together (default true). */
+                    group?: boolean;
+                    /** @description Auto-include the full group of any id you pass (default true). */
+                    includeGroupPeers?: boolean;
                 };
             };
         };
@@ -6974,9 +7133,9 @@ interface operations {
         requestBody?: {
             content: {
                 "application/json": {
-                    /** @description Free-text search across name + pack + category (e.g. 'sticky note', 'decision', 'database table', 'phone frame', 'actor'). */
+                    /** @description Free-text search across name + pack + category (e.g. 'decision', 'database table', 'phone frame', 'actor', 'kanban column'). */
                     query?: string;
-                    /** @description Restrict to one pack, e.g. 'Sticky Notes', 'Flowchart', 'BPMN', 'UML & ER', 'Scrum Board', 'Lo-Fi Wireframes', 'Org Chart'. */
+                    /** @description Restrict to one pack, e.g. 'Flowchart', 'BPMN', 'UML & ER', 'Scrum Board', 'Lo-Fi Wireframes', 'Org Chart'. */
                     pack?: string;
                     /** @description Filter by category: 'Notes & Planning', 'Diagramming', 'UI & Wireframing', 'Data & Charts', 'People & Fun'. */
                     category?: string;

package/dist/index.d.ts

@@ -74,7 +74,7 @@ interface paths {
         put?: never;
         /**
          * listArchitectureIcons
-         * @description List icons for systemsarchitecture diagrams. Use returned iconPath as-is in D2 code (e.g. icon: dev/docker.svg).
+         * @description List curated software-architecture icons (AWS, Azure, GCP, Docker, Kubernetes, databases, message queues, etc.). 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).
          */
         post: operations["listArchitectureIcons"];
         delete?: never;
@@ -674,7 +674,7 @@ interface paths {
         put?: never;
         /**
          * updateWhiteboardScene
-         * @description Edit elements on a whiteboard's canvas WITHOUT dropping the rest of the scene. A board may hold many diagrams/elements, so prefer surgical edits: mode='patch' (DEFAULT) shallow-merges each incoming object into the existing element with the same `id` (send just {id, backgroundColor:'blue'} to recolour one box, or {id, x, y} to move one) and appends any elements whose id is new/absent — everything else is left untouched. `deleteIds` removes specific elements by id. mode='append' only adds. mode='replace' overwrites the ENTIRE scene (use ONLY when intentionally rewriting the whole board). To author NEW shapes/connectors from a high-level spec, prefer addWhiteboardElements. Optional appState/files are merged in. PROCESS: for a non-trivial edit call getWhiteboardGuide FIRST; after editing, ALWAYS call getWhiteboardImage to confirm the board still looks right (layout, labels, overlaps), and patch again if it doesn't.
+         * @description Edit elements on a whiteboard's canvas WITHOUT dropping the rest of the scene. A board may hold many diagrams/elements, so prefer surgical edits: mode='patch' (DEFAULT) shallow-merges each incoming object into the existing element with the same `id` (send just {id, backgroundColor:'blue'} to recolour one box, or {id, x, y} to move one) and appends any elements whose id is new/absent — everything else is left untouched. `deleteIds` removes specific elements by id. mode='append' only adds. mode='replace' overwrites the ENTIRE scene — to rebuild or edit only PART of a board, still use 'patch', because replace DELETES every element you don't resend (of ANY type). As a safeguard, a replace that would drop ANY existing element not in your payload is REJECTED unless you pass confirmReplace:true (or include those ids); diagrams/images/frames are flagged specially since they're inserted separately and costliest to lose. To author NEW shapes/connectors from a high-level spec, prefer addWhiteboardElements — and prefer library stencils / sticky notes / architecture icons over plain rectangles wherever a standard form fits (sticky notes, kanban/scrum, flowcharts, UML/ER, BPMN, org charts, wireframes). Optional appState/files are merged in. PROCESS: for a non-trivial edit call getWhiteboardGuide FIRST; after editing, ALWAYS call getWhiteboardImage to confirm the board still looks right (layout, labels, overlaps), and patch again if it doesn't.
          */
         post: operations["updateWhiteboardScene"];
         delete?: never;
@@ -694,7 +694,7 @@ interface paths {
         put?: never;
         /**
          * addWhiteboardElements
-         * @description Author shapes onto a whiteboard from high-level specs (you do NOT need the full Excalidraw element schema). Appends to the canvas. 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'|'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 (sticky notes, 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. yellow sticky note>', pack?:'<pack>', x, y } to fuzzy-match by name). STRONGLY prefer these over plain rectangles whenever the user asks for sticky notes, kanban/scrum/story boards, flowcharts, wireframes/mockups, org charts, etc. 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 solid-fill notes; type 'line' with no arrowheads + roughness:2 for sketchy mind-map spokes. 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.
+         * @description Author shapes onto a whiteboard from high-level specs (you do NOT need the full Excalidraw element schema). Appends to the canvas. 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'|'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. 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.
          */
         post: operations["addWhiteboardElements"];
         delete?: never;
@@ -703,6 +703,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/tools/duplicateWhiteboardElements": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * duplicateWhiteboardElements
+         * @description Copy-paste existing whiteboard elements — the MCP equivalent of selecting a group and pressing Ctrl/Cmd+D. Clones the given elements (plus their group peers + bound text/labels) with FRESH ids, offsets the copy by dx/dy, and by default groups it into ONE new unit so it moves together. Use it to build something once (a labelled stencil frame, a kanban card, a UML class) then stamp out consistent repeats fast — then retext/recolour each copy by its new id (via the returned idMap) with updateWhiteboardScene. Pass `groupId` to copy a whole group as a unit (e.g. a placed stencil's groupId from its placement result) and/or `ids` for specific elements. Internal references (group membership, bound text containerId, arrow start/end bindings) are remapped within the copied set; a binding to an element you did NOT copy is dropped. Returns { duplicated, idMap (old id → new id), groupId (the copy's new unit group), elementCount }. Render with getWhiteboardImage afterwards to verify.
+         */
+        post: operations["duplicateWhiteboardElements"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/tools/insertWhiteboardImage": {
         parameters: {
             query?: never;
@@ -754,7 +774,7 @@ interface paths {
         put?: never;
         /**
          * listWhiteboardStencils
-         * @description Search the built-in library of STRUCTURAL whiteboard stencils — ready-made, hand-drawn multi-element graphics: sticky notes (post-it), scrum-board columns, flowchart symbols, UML/ER, BPMN, org-chart nodes, gantt, lo-fi/UX wireframe widgets, charts, and stick figures. Returns matching stencils each with a `key`, name, pack and category, plus the full pack/category lists. Place one via addWhiteboardElements({type:'stencil', stencilKey:'<key>', x, y}). These look far richer and more on-brand than plain rectangles — use them when the user asks for sticky notes, kanban/scrum boards, flowcharts, wireframes, mockups, etc. SEARCH TIPS: prefer BROAD single words ('sticky', 'decision', 'actor', 'phone', 'process') — multi-word exact phrases often miss. If an exact query matches nothing the result is auto-broadened to close candidates (broadened:true is set); you can also pass pack/category to browse. When ANY returned stencil reasonably fits, PLACE it instead of drawing a plain rectangle — do not abandon stencils just because your first phrase returned 0. The library does NOT contain free-form 'cloud' / 'hat' / 'thought-bubble' shapes; approximate those with the closest stencil (e.g. a sticky note or a simple shape) or fall back to a plain shape only when nothing fits. For cloud/architecture ICONS (AWS/Azure/GCP/Docker/Kubernetes/databases) use listArchitectureIcons instead.
+         * @description Search the built-in library of structural whiteboard stencils — ready-made hand-drawn graphics: flowchart/UML/ER/BPMN symbols, scrum columns, org-chart nodes, gantt, lo-fi/UX wireframe widgets (buttons, forms, tables, alerts, navs), charts, device frames, stick figures. A stencil is a MINI-WHITEBOARD (a collection of elements), NOT a single shape. Each result returns: `key`, `title` (a real human name e.g. 'Alerts', not an index), `kind` ('symbol' | 'template'), `labels` (the TEXT it actually contains — its real content, e.g. an Alerts template's variant messages), `size` ({w,h} px), `summary`, `pack`, `category`; plus the full pack/category lists. The two kinds are used DIFFERENTLY: • SYMBOL = one atomic labelled node (flowchart Process/Decision, BPMN task, org node). Place + label + connect: addWhiteboardElements({type:'stencil', stencilKey, id:'n1', text:'Review', width, height}) — the text auto-fits its single slot and an arrow's start/end {id:'n1'} binds to it like any shape. A few symbols are text-less FRAMES (e.g. a UML class box = rectangle + divider line): place create-only, then use the placement result's `children` (shapes + x/y/w/h) and `groupId` to add type:'text' specs INTO the regions — pass that groupId so the text is one unit with the frame. • TEMPLATE = a multi-component layout (Alerts, Forms, Tables, Charts, device frames). Place the WHOLE thing: addWhiteboardElements({type:'stencil', stencilKey, x, y, width?, height?}); the placement RESULT returns `stencils[].children` (each child's id + text + colour + position x/y/w/h, so you can group children into rows/sections) so you then keep / retext / recolour / DELETE specific parts via updateWhiteboardScene (e.g. delete the info + error rows to keep only the green success alert). Do NOT pass a single `text` to a template — read its `labels` to see its parts, then edit them by id. To make several similar items, build one then duplicateWhiteboardElements({groupId, dx}) to stamp consistent copies (like copy-paste in the UI). SEARCH TIPS: prefer BROAD single words ('decision','alert','form','phone','process'); content words match the embedded `labels` too (searching 'success' finds the Alerts template). If nothing exact matches, results auto-broaden (broadened:true); pass pack/category to browse. For cloud/architecture ICONS (AWS/Azure/GCP/Docker/Kubernetes/databases) use listArchitectureIcons; for a sticky/post-it use addWhiteboardElements({type:'sticky'}), not a stencil.
          */
         post: operations["listWhiteboardStencils"];
         delete?: never;
@@ -6591,7 +6611,7 @@ interface operations {
                     /** @description Elements to write. For mode 'patch', each may be a partial { id, ...changedFields } merged into the matching element by id; full Excalidraw elements for 'replace'/'append' (or new ids in 'patch'). */
                     elements?: Record<string, never>[];
                     /**
-                     * @description patch (DEFAULT — merge by id, keep the rest), append (add only), or replace (overwrite the whole scene).
+                     * @description How to apply your `elements`. patch (DEFAULT — use this for ANY partial edit): merges each item into the element with the same id and leaves everything else untouched, like find-and-replace by id; new ids are added. append: only adds your items, changes nothing else. replace: OVERWRITES THE WHOLE CANVAS — every existing element you don't resend is DELETED — so use it ONLY to set an entire board at once. To change or rebuild just a SECTION, use patch (+ deleteIds to remove specific ids), NEVER replace. A replace that would drop any existing element is rejected unless confirmReplace:true.
                      * @enum {string}
                      */
                     mode?: "patch" | "append" | "replace";
@@ -6601,6 +6621,10 @@ interface operations {
                     appState?: Record<string, never>;
                     /** @description Optional Excalidraw BinaryFiles map (for embedded images), merged in. */
                     files?: Record<string, never>;
+                    /** @description Optional optimistic-locking token from getWhiteboard. Only used for mode 'replace': if the board changed since you read it, the replace is rejected so you don't overwrite a collaborator's newer edits — re-read with getWhiteboard and retry. Not needed for patch/append, which automatically merge onto the latest scene. */
+                    versionTimestamp?: number;
+                    /** @description Safety acknowledgement for mode 'replace' ONLY. A replace that would DELETE ANY existing element not present in your `elements` is rejected unless this is true. Leave it unset and use mode:'patch' to edit part of a board (it merges by id and keeps the rest); set true only when you truly intend to overwrite the WHOLE scene. */
+                    confirmReplace?: boolean;
                 };
             };
         };
@@ -6683,8 +6707,143 @@ interface operations {
             content: {
                 "application/json": {
                     documentId: string;
-                    /** @description Non-empty array of shape specs to append. */
-                    shapes: Record<string, never>[];
+                    /** @description Non-empty array of shape specs to append. Prefer stencils / sticky notes / architecture icons over raw rectangles wherever a standard form fits (see the `type` enum below and the tool description). */
+                    shapes: ({
+                        /**
+                         * @description Element kind. 'sticky' = a first-class sticky/post-it note (solid fill + auto-fitting bound label; set text + backgroundColor) — use this for sticky notes, NOT a stencil. 'stencil' = a hand-drawn library graphic from listWhiteboardStencils, of kind 'symbol' (one atomic labelled node — flowchart box, BPMN task, org node: set `id` + `text` + width/height, text auto-fits, connect arrows via start/end {id}) or 'template' (a multi-element layout — Alerts, Forms, Tables, Charts: place whole, then customise its returned children by id; do NOT set a single `text`). Set `stencil` (fuzzy name, one call) or `stencilKey` (exact). 'image' with `iconPath` = a software-architecture icon from listArchitectureIcons. Reserve rectangle/ellipse/diamond for when no standard form fits.
+                         * @enum {string}
+                         */
+                        type: "rectangle" | "ellipse" | "diamond" | "sticky" | "text" | "arrow" | "line" | "frame" | "image" | "stencil";
+                        /** @description For type:'stencil' — fuzzy-match a library stencil by name in ONE call, no prior listWhiteboardStencils needed (e.g. 'decision', 'actor', 'phone frame', 'kanban column'). NOTE: there is no sticky-note stencil — use type:'sticky' for sticky/post-it notes. */
+                        stencil?: string;
+                        /** @description For type:'stencil' — exact stencil key from listWhiteboardStencils (takes precedence over `stencil`). */
+                        stencilKey?: string;
+                        /** @description For type:'stencil' — optional pack to disambiguate a fuzzy `stencil` match (e.g. 'Flowchart', 'BPMN', 'UML & ER', 'Scrum Board'). */
+                        pack?: string;
+                        /** @description For type:'image' — a software-architecture icon path from listArchitectureIcons (e.g. 'dev/docker.svg'). */
+                        iconPath?: string;
+                        /** @description For type:'image' — any other public image URL (use iconPath for curated architecture icons). */
+                        imageUrl?: string;
+                        /** @description Optional id so connectors (arrows/lines) can reference this shape via start/end. On a type:'stencil' it adds a transparent bindable anchor covering the stencil, so an arrow's start/end {id} connects to the whole stencil as a unit. */
+                        id?: string;
+                        /** @description Join an existing group. Pass a placed stencil's `groupId` (returned in the placement result) on a type:'text' or shape spec to FILL that frame as part of the same unit — the text then moves, duplicates and renders together with the frame (e.g. a title in a UML class box's top band, members in its body). */
+                        groupId?: string;
+                        /** @description Top-left x on the canvas. OMIT both x and y to auto-place this element in clear empty space below the board's existing content. Strongly preferred when adding a note/shape to a board that already has content: a guessed coordinate usually lands ON TOP of existing shapes (the 'added a sticky but can't see it' bug). Set x/y only for deliberate layout among shapes you add in this same call. */
+                        x?: number;
+                        /** @description Top-left y on the canvas. Omit together with x to auto-place (see x). */
+                        y?: number;
+                        /** @description Shape width; for type:'stencil' it scales the whole stencil to fit this width. */
+                        width?: number;
+                        /** @description Shape height; for type:'stencil' it scales the whole stencil to fit this height. */
+                        height?: number;
+                        /** @description For type:'stencil' — uniform scale factor for the whole stencil (alternative to width/height). */
+                        scale?: number;
+                        /** @description Label/caption. On a shape it's a centered auto-wrapped bound label (prefer over a separate type:'text'); on a type:'sticky' it's the note text; on a type:'stencil' of kind 'symbol' it fills + re-fits its single label (IGNORED for 'template' stencils — customise their children by id instead). */
+                        text?: string;
+                        /** @description Fill colour: a name ('blue'/'green'/'yellow'/'pink'/'violet'/'orange'/'teal'/…) or a hex value. */
+                        backgroundColor?: string;
+                        /** @description For arrows/lines: { id } of the source shape (auto-clips to the edge + auto-routes around shapes in between). */
+                        start?: Record<string, never>;
+                        /** @description For arrows/lines: { id } of the target shape. */
+                        end?: Record<string, never>;
+                    } & {
+                        [key: string]: unknown;
+                    })[];
+                };
+            };
+        };
+        responses: {
+            /** @description Tool result (shape varies per tool — refer to the tool's docs for the exact return value). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation error. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Missing or invalid credentials. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Authenticated but lacking the required permission or feature flag. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Body did not match the tool's input schema. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Server error. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    duplicateWhiteboardElements: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description The whiteboard's documentId. */
+                    documentId: string;
+                    /** @description Element ids to copy. Each id's full group + any bound text are auto-included. Use this and/or groupId. */
+                    ids?: string[];
+                    /** @description Copy EVERY element in this group as one unit — e.g. a placed stencil's `groupId` returned by addWhiteboardElements. */
+                    groupId?: string;
+                    /** @description Horizontal offset for the copy (default 40). Use the element width + a gap to place copies side by side. */
+                    dx?: number;
+                    /** @description Vertical offset for the copy (default 40). */
+                    dy?: number;
+                    /** @description Group the copy into one new unit so it moves/duplicates together (default true). */
+                    group?: boolean;
+                    /** @description Auto-include the full group of any id you pass (default true). */
+                    includeGroupPeers?: boolean;
                 };
             };
         };
@@ -6974,9 +7133,9 @@ interface operations {
         requestBody?: {
             content: {
                 "application/json": {
-                    /** @description Free-text search across name + pack + category (e.g. 'sticky note', 'decision', 'database table', 'phone frame', 'actor'). */
+                    /** @description Free-text search across name + pack + category (e.g. 'decision', 'database table', 'phone frame', 'actor', 'kanban column'). */
                     query?: string;
-                    /** @description Restrict to one pack, e.g. 'Sticky Notes', 'Flowchart', 'BPMN', 'UML & ER', 'Scrum Board', 'Lo-Fi Wireframes', 'Org Chart'. */
+                    /** @description Restrict to one pack, e.g. 'Flowchart', 'BPMN', 'UML & ER', 'Scrum Board', 'Lo-Fi Wireframes', 'Org Chart'. */
                     pack?: string;
                     /** @description Filter by category: 'Notes & Planning', 'Diagramming', 'UI & Wireframing', 'Data & Charts', 'People & Fun'. */
                     category?: string;