@stablebaseline/sdk 0.4.1 → 0.4.2

package/dist/index.d.cts

@@ -434,7 +434,7 @@ interface paths {
         put?: never;
         /**
          * getDocument
-         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them.
+         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them. Pass includeDiagramDsl:true to inline each diagram's DSL and versionTimestamp directly into its DIAGRAM_OMITTED marker (saves a getDiagramInDocument call when you intend to read or edit diagrams).
          */
         post: operations["getDocument"];
         delete?: never;
@@ -474,7 +474,7 @@ interface paths {
         put?: never;
         /**
          * editDocument
-         * @description Edit a document with line-based patches. Call getDocument first for line numbers and versionTimestamp. Call getCdmdLanguageGuide if unfamiliar with CDMD syntax. Do not edit DIAGRAM/IMAGE markers manually — use dedicated diagram/image tools. To @-mention a person in your patch, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
+         * @description Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, add `before`/`after` (short nearby surrounding text) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:"" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument is required for optimistic locking, EXCEPT when dryRun:true. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
          */
         post: operations["editDocument"];
         delete?: never;
@@ -494,7 +494,7 @@ interface paths {
         put?: never;
         /**
          * findAndReplaceTextInDocument
-         * @description Find and replace text in a document. Searches for all occurrences and replaces them. Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
+         * @description Find and replace EXACT substrings in a document (NOT regex: wildcards and patterns are matched literally). Replaces EVERY occurrence and returns the replacement count; best for renames and repeated phrases. For a single targeted change at a known location, prefer editDocument (line patches with optimistic locking). Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
          */
         post: operations["findAndReplaceTextInDocument"];
         delete?: never;
@@ -554,7 +554,7 @@ interface paths {
         put?: never;
         /**
          * updateDiagramInDocument
-         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Requires documentVersionTimestamp from getDocument. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
+         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Provide a version lock: EITHER documentVersionTimestamp (from getDocument — locks the whole document) OR diagramVersionTimestamp (from getDiagramInDocument, or getDocument with includeDiagramDsl:true — locks just THIS diagram, so two agents can edit two different diagrams in the same document concurrently without a conflict). At least one is required; diagramVersionTimestamp is preferred for concurrency. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
          */
         post: operations["updateDiagramInDocument"];
         delete?: never;
@@ -5598,6 +5598,8 @@ interface operations {
                     offset?: number;
                     /** @description Max lines to return. Default: 200. */
                     limit?: number;
+                    /** @description If true, inline each diagram's full DSL (as diagramCode) and its versionTimestamp into the DIAGRAM_OMITTED markers, so you can inspect and then edit a diagram (updateDiagramInDocument with diagramVersionTimestamp) without a second read. Default false. Note: large DSL inflates the response. */
+                    includeDiagramDsl?: boolean;
                     /** @description Field projection. Valid fields: id, title, friendlyId, friendlyIdNumber, projectId, folderId, createdAt, updatedAt, versionTimestamp. */
                     fields?: string[];
                     /** @description Content field projection. Valid fields: offset, limit, totalLines, nextOffset, metadata, text. */
@@ -5779,19 +5781,30 @@ interface operations {
                     folderId?: string;
                     /** @description Sort position within the parent folder. Use to reposition a single document. For batch sibling reorder, use reorderDocuments. */
                     position?: number;
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    versionTimestamp: number;
+                    /** @description Version timestamp from getDocument() for optimistic locking. Required unless dryRun:true. */
+                    versionTimestamp?: number;
+                    /** @description If true, apply the patches and RETURN the resulting document text without saving — no version bump, no lock required. Use to preview/verify a patch before committing. Default false. */
+                    dryRun?: boolean;
                     /** @description Version history summary. */
                     changeSummary?: string;
-                    /** @description Line-based patches. Can be empty if only updating title, folderId, or position. */
-                    patches?: {
+                    /** @description Patches to apply. Use EITHER anchor patches OR line patches, not both in the same call. May be empty if only updating title, folderId, or position. */
+                    patches?: ({
+                        /** @description Exact existing text to replace. Must match the document byte-for-byte and be unique (or use before/after to disambiguate). */
+                        oldText: string;
+                        /** @description Replacement text. Empty string to delete the matched text. */
+                        newText: string;
+                        /** @description Optional. Text that appears immediately before oldText, used to disambiguate when oldText occurs more than once. */
+                        before?: string;
+                        /** @description Optional. Text that appears immediately after oldText, used to disambiguate. */
+                        after?: string;
+                    } | {
                         /** @description 1-based start line. */
                         startLine: number;
                         /** @description 1-based end line (inclusive). */
                         endLine: number;
                         /** @description Replacement text. Empty string to delete lines. */
                         replacement: string;
-                    }[];
+                    })[];
                 };
             };
         };
@@ -6192,8 +6205,10 @@ interface operations {
                             [key: string]: string;
                         };
                     };
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    documentVersionTimestamp: number;
+                    /** @description Document-level optimistic lock: versionTimestamp from getDocument(). Locks the whole document. Provide this OR diagramVersionTimestamp (at least one is required). */
+                    documentVersionTimestamp?: number;
+                    /** @description Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument, or getDocument with includeDiagramDsl:true). Pass this instead of documentVersionTimestamp to lock only this diagram, so concurrent edits to OTHER diagrams in the same document don't conflict. Preferred for multi-agent concurrency. The response returns the new diagram.diagramVersionTimestamp for chaining further edits. */
+                    diagramVersionTimestamp?: number;
                 };
             };
         };

package/dist/index.d.ts

@@ -434,7 +434,7 @@ interface paths {
         put?: never;
         /**
          * getDocument
-         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them.
+         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them. Pass includeDiagramDsl:true to inline each diagram's DSL and versionTimestamp directly into its DIAGRAM_OMITTED marker (saves a getDiagramInDocument call when you intend to read or edit diagrams).
          */
         post: operations["getDocument"];
         delete?: never;
@@ -474,7 +474,7 @@ interface paths {
         put?: never;
         /**
          * editDocument
-         * @description Edit a document with line-based patches. Call getDocument first for line numbers and versionTimestamp. Call getCdmdLanguageGuide if unfamiliar with CDMD syntax. Do not edit DIAGRAM/IMAGE markers manually — use dedicated diagram/image tools. To @-mention a person in your patch, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
+         * @description Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, add `before`/`after` (short nearby surrounding text) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:"" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument is required for optimistic locking, EXCEPT when dryRun:true. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
          */
         post: operations["editDocument"];
         delete?: never;
@@ -494,7 +494,7 @@ interface paths {
         put?: never;
         /**
          * findAndReplaceTextInDocument
-         * @description Find and replace text in a document. Searches for all occurrences and replaces them. Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
+         * @description Find and replace EXACT substrings in a document (NOT regex: wildcards and patterns are matched literally). Replaces EVERY occurrence and returns the replacement count; best for renames and repeated phrases. For a single targeted change at a known location, prefer editDocument (line patches with optimistic locking). Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
          */
         post: operations["findAndReplaceTextInDocument"];
         delete?: never;
@@ -554,7 +554,7 @@ interface paths {
         put?: never;
         /**
          * updateDiagramInDocument
-         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Requires documentVersionTimestamp from getDocument. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
+         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Provide a version lock: EITHER documentVersionTimestamp (from getDocument — locks the whole document) OR diagramVersionTimestamp (from getDiagramInDocument, or getDocument with includeDiagramDsl:true — locks just THIS diagram, so two agents can edit two different diagrams in the same document concurrently without a conflict). At least one is required; diagramVersionTimestamp is preferred for concurrency. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
          */
         post: operations["updateDiagramInDocument"];
         delete?: never;
@@ -5598,6 +5598,8 @@ interface operations {
                     offset?: number;
                     /** @description Max lines to return. Default: 200. */
                     limit?: number;
+                    /** @description If true, inline each diagram's full DSL (as diagramCode) and its versionTimestamp into the DIAGRAM_OMITTED markers, so you can inspect and then edit a diagram (updateDiagramInDocument with diagramVersionTimestamp) without a second read. Default false. Note: large DSL inflates the response. */
+                    includeDiagramDsl?: boolean;
                     /** @description Field projection. Valid fields: id, title, friendlyId, friendlyIdNumber, projectId, folderId, createdAt, updatedAt, versionTimestamp. */
                     fields?: string[];
                     /** @description Content field projection. Valid fields: offset, limit, totalLines, nextOffset, metadata, text. */
@@ -5779,19 +5781,30 @@ interface operations {
                     folderId?: string;
                     /** @description Sort position within the parent folder. Use to reposition a single document. For batch sibling reorder, use reorderDocuments. */
                     position?: number;
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    versionTimestamp: number;
+                    /** @description Version timestamp from getDocument() for optimistic locking. Required unless dryRun:true. */
+                    versionTimestamp?: number;
+                    /** @description If true, apply the patches and RETURN the resulting document text without saving — no version bump, no lock required. Use to preview/verify a patch before committing. Default false. */
+                    dryRun?: boolean;
                     /** @description Version history summary. */
                     changeSummary?: string;
-                    /** @description Line-based patches. Can be empty if only updating title, folderId, or position. */
-                    patches?: {
+                    /** @description Patches to apply. Use EITHER anchor patches OR line patches, not both in the same call. May be empty if only updating title, folderId, or position. */
+                    patches?: ({
+                        /** @description Exact existing text to replace. Must match the document byte-for-byte and be unique (or use before/after to disambiguate). */
+                        oldText: string;
+                        /** @description Replacement text. Empty string to delete the matched text. */
+                        newText: string;
+                        /** @description Optional. Text that appears immediately before oldText, used to disambiguate when oldText occurs more than once. */
+                        before?: string;
+                        /** @description Optional. Text that appears immediately after oldText, used to disambiguate. */
+                        after?: string;
+                    } | {
                         /** @description 1-based start line. */
                         startLine: number;
                         /** @description 1-based end line (inclusive). */
                         endLine: number;
                         /** @description Replacement text. Empty string to delete lines. */
                         replacement: string;
-                    }[];
+                    })[];
                 };
             };
         };
@@ -6192,8 +6205,10 @@ interface operations {
                             [key: string]: string;
                         };
                     };
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    documentVersionTimestamp: number;
+                    /** @description Document-level optimistic lock: versionTimestamp from getDocument(). Locks the whole document. Provide this OR diagramVersionTimestamp (at least one is required). */
+                    documentVersionTimestamp?: number;
+                    /** @description Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument, or getDocument with includeDiagramDsl:true). Pass this instead of documentVersionTimestamp to lock only this diagram, so concurrent edits to OTHER diagrams in the same document don't conflict. Preferred for multi-agent concurrency. The response returns the new diagram.diagramVersionTimestamp for chaining further edits. */
+                    diagramVersionTimestamp?: number;
                 };
             };
         };

package/openapi.json

@@ -2569,7 +2569,7 @@
     "/tools/getDocument": {
       "post": {
         "summary": "getDocument",
-        "description": "Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them.",
+        "description": "Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them. Pass includeDiagramDsl:true to inline each diagram's DSL and versionTimestamp directly into its DIAGRAM_OMITTED marker (saves a getDiagramInDocument call when you intend to read or edit diagrams).",
         "operationId": "getDocument",
         "tags": [
           "documents"
@@ -2593,6 +2593,10 @@
                     "type": "number",
                     "description": "Max lines to return. Default: 200."
                   },
+                  "includeDiagramDsl": {
+                    "type": "boolean",
+                    "description": "If true, inline each diagram's full DSL (as diagramCode) and its versionTimestamp into the DIAGRAM_OMITTED markers, so you can inspect and then edit a diagram (updateDiagramInDocument with diagramVersionTimestamp) without a second read. Default false. Note: large DSL inflates the response."
+                  },
                   "fields": {
                     "type": "array",
                     "items": {
@@ -2812,7 +2816,7 @@
     "/tools/editDocument": {
       "post": {
         "summary": "editDocument",
-        "description": "Edit a document with line-based patches. Call getDocument first for line numbers and versionTimestamp. Call getCdmdLanguageGuide if unfamiliar with CDMD syntax. Do not edit DIAGRAM/IMAGE markers manually — use dedicated diagram/image tools. To @-mention a person in your patch, insert `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.",
+        "description": "Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, add `before`/`after` (short nearby surrounding text) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:\"\" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument is required for optimistic locking, EXCEPT when dryRun:true. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.",
         "operationId": "editDocument",
         "tags": [
           "documents"
@@ -2841,7 +2845,11 @@
                   },
                   "versionTimestamp": {
                     "type": "number",
-                    "description": "Version timestamp from getDocument() for optimistic locking."
+                    "description": "Version timestamp from getDocument() for optimistic locking. Required unless dryRun:true."
+                  },
+                  "dryRun": {
+                    "type": "boolean",
+                    "description": "If true, apply the patches and RETURN the resulting document text without saving — no version bump, no lock required. Use to preview/verify a patch before committing. Default false."
                   },
                   "changeSummary": {
                     "type": "string",
@@ -2849,34 +2857,64 @@
                   },
                   "patches": {
                     "type": "array",
-                    "description": "Line-based patches. Can be empty if only updating title, folderId, or position.",
+                    "description": "Patches to apply. Use EITHER anchor patches OR line patches, not both in the same call. May be empty if only updating title, folderId, or position.",
                     "items": {
-                      "type": "object",
-                      "properties": {
-                        "startLine": {
-                          "type": "number",
-                          "description": "1-based start line."
-                        },
-                        "endLine": {
-                          "type": "number",
-                          "description": "1-based end line (inclusive)."
+                      "oneOf": [
+                        {
+                          "type": "object",
+                          "description": "Anchor patch (recommended): replace an exact, unique snippet of existing text. Drift-proof — no line numbers needed.",
+                          "properties": {
+                            "oldText": {
+                              "type": "string",
+                              "description": "Exact existing text to replace. Must match the document byte-for-byte and be unique (or use before/after to disambiguate)."
+                            },
+                            "newText": {
+                              "type": "string",
+                              "description": "Replacement text. Empty string to delete the matched text."
+                            },
+                            "before": {
+                              "type": "string",
+                              "description": "Optional. Text that appears immediately before oldText, used to disambiguate when oldText occurs more than once."
+                            },
+                            "after": {
+                              "type": "string",
+                              "description": "Optional. Text that appears immediately after oldText, used to disambiguate."
+                            }
+                          },
+                          "required": [
+                            "oldText",
+                            "newText"
+                          ]
                         },
-                        "replacement": {
-                          "type": "string",
-                          "description": "Replacement text. Empty string to delete lines."
+                        {
+                          "type": "object",
+                          "description": "Line patch: 1-based inclusive line range. Requires fresh line numbers from getDocument().",
+                          "properties": {
+                            "startLine": {
+                              "type": "number",
+                              "description": "1-based start line."
+                            },
+                            "endLine": {
+                              "type": "number",
+                              "description": "1-based end line (inclusive)."
+                            },
+                            "replacement": {
+                              "type": "string",
+                              "description": "Replacement text. Empty string to delete lines."
+                            }
+                          },
+                          "required": [
+                            "startLine",
+                            "endLine",
+                            "replacement"
+                          ]
                         }
-                      },
-                      "required": [
-                        "startLine",
-                        "endLine",
-                        "replacement"
                       ]
                     }
                   }
                 },
                 "required": [
-                  "documentId",
-                  "versionTimestamp"
+                  "documentId"
                 ]
               }
             }
@@ -2960,7 +2998,7 @@
     "/tools/findAndReplaceTextInDocument": {
       "post": {
         "summary": "findAndReplaceTextInDocument",
-        "description": "Find and replace text in a document. Searches for all occurrences and replaces them. Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.",
+        "description": "Find and replace EXACT substrings in a document (NOT regex: wildcards and patterns are matched literally). Replaces EVERY occurrence and returns the replacement count; best for renames and repeated phrases. For a single targeted change at a known location, prefer editDocument (line patches with optimistic locking). Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.",
         "operationId": "findAndReplaceTextInDocument",
         "tags": [
           "documents"
@@ -3376,7 +3414,7 @@
     "/tools/updateDiagramInDocument": {
       "post": {
         "summary": "updateDiagramInDocument",
-        "description": "Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Requires documentVersionTimestamp from getDocument. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.",
+        "description": "Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Provide a version lock: EITHER documentVersionTimestamp (from getDocument — locks the whole document) OR diagramVersionTimestamp (from getDiagramInDocument, or getDocument with includeDiagramDsl:true — locks just THIS diagram, so two agents can edit two different diagrams in the same document concurrently without a conflict). At least one is required; diagramVersionTimestamp is preferred for concurrency. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.",
         "operationId": "updateDiagramInDocument",
         "tags": [
           "diagrams"
@@ -3435,12 +3473,15 @@
                   },
                   "documentVersionTimestamp": {
                     "type": "number",
-                    "description": "Version timestamp from getDocument() for optimistic locking."
+                    "description": "Document-level optimistic lock: versionTimestamp from getDocument(). Locks the whole document. Provide this OR diagramVersionTimestamp (at least one is required)."
+                  },
+                  "diagramVersionTimestamp": {
+                    "type": "number",
+                    "description": "Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument, or getDocument with includeDiagramDsl:true). Pass this instead of documentVersionTimestamp to lock only this diagram, so concurrent edits to OTHER diagrams in the same document don't conflict. Preferred for multi-agent concurrency. The response returns the new diagram.diagramVersionTimestamp for chaining further edits."
                   }
                 },
                 "required": [
-                  "diagramId",
-                  "documentVersionTimestamp"
+                  "diagramId"
                 ]
               }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stablebaseline/sdk",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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": {

package/src/types.generated.ts

@@ -435,7 +435,7 @@ export interface paths {
         put?: never;
         /**
          * getDocument
-         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them.
+         * @description Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them. Pass includeDiagramDsl:true to inline each diagram's DSL and versionTimestamp directly into its DIAGRAM_OMITTED marker (saves a getDiagramInDocument call when you intend to read or edit diagrams).
          */
         post: operations["getDocument"];
         delete?: never;
@@ -475,7 +475,7 @@ export interface paths {
         put?: never;
         /**
          * editDocument
-         * @description Edit a document with line-based patches. Call getDocument first for line numbers and versionTimestamp. Call getCdmdLanguageGuide if unfamiliar with CDMD syntax. Do not edit DIAGRAM/IMAGE markers manually — use dedicated diagram/image tools. To @-mention a person in your patch, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
+         * @description Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, add `before`/`after` (short nearby surrounding text) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:"" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument is required for optimistic locking, EXCEPT when dryRun:true. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {"type":"user","id":"<user_uuid>","label":"Name"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.
          */
         post: operations["editDocument"];
         delete?: never;
@@ -495,7 +495,7 @@ export interface paths {
         put?: never;
         /**
          * findAndReplaceTextInDocument
-         * @description Find and replace text in a document. Searches for all occurrences and replaces them. Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
+         * @description Find and replace EXACT substrings in a document (NOT regex: wildcards and patterns are matched literally). Replaces EVERY occurrence and returns the replacement count; best for renames and repeated phrases. For a single targeted change at a known location, prefer editDocument (line patches with optimistic locking). Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.
          */
         post: operations["findAndReplaceTextInDocument"];
         delete?: never;
@@ -555,7 +555,7 @@ export interface paths {
         put?: never;
         /**
          * updateDiagramInDocument
-         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Requires documentVersionTimestamp from getDocument. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
+         * @description Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Provide a version lock: EITHER documentVersionTimestamp (from getDocument — locks the whole document) OR diagramVersionTimestamp (from getDiagramInDocument, or getDocument with includeDiagramDsl:true — locks just THIS diagram, so two agents can edit two different diagrams in the same document concurrently without a conflict). At least one is required; diagramVersionTimestamp is preferred for concurrency. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.
          */
         post: operations["updateDiagramInDocument"];
         delete?: never;
@@ -5599,6 +5599,8 @@ export interface operations {
                     offset?: number;
                     /** @description Max lines to return. Default: 200. */
                     limit?: number;
+                    /** @description If true, inline each diagram's full DSL (as diagramCode) and its versionTimestamp into the DIAGRAM_OMITTED markers, so you can inspect and then edit a diagram (updateDiagramInDocument with diagramVersionTimestamp) without a second read. Default false. Note: large DSL inflates the response. */
+                    includeDiagramDsl?: boolean;
                     /** @description Field projection. Valid fields: id, title, friendlyId, friendlyIdNumber, projectId, folderId, createdAt, updatedAt, versionTimestamp. */
                     fields?: string[];
                     /** @description Content field projection. Valid fields: offset, limit, totalLines, nextOffset, metadata, text. */
@@ -5780,19 +5782,30 @@ export interface operations {
                     folderId?: string;
                     /** @description Sort position within the parent folder. Use to reposition a single document. For batch sibling reorder, use reorderDocuments. */
                     position?: number;
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    versionTimestamp: number;
+                    /** @description Version timestamp from getDocument() for optimistic locking. Required unless dryRun:true. */
+                    versionTimestamp?: number;
+                    /** @description If true, apply the patches and RETURN the resulting document text without saving — no version bump, no lock required. Use to preview/verify a patch before committing. Default false. */
+                    dryRun?: boolean;
                     /** @description Version history summary. */
                     changeSummary?: string;
-                    /** @description Line-based patches. Can be empty if only updating title, folderId, or position. */
-                    patches?: {
+                    /** @description Patches to apply. Use EITHER anchor patches OR line patches, not both in the same call. May be empty if only updating title, folderId, or position. */
+                    patches?: ({
+                        /** @description Exact existing text to replace. Must match the document byte-for-byte and be unique (or use before/after to disambiguate). */
+                        oldText: string;
+                        /** @description Replacement text. Empty string to delete the matched text. */
+                        newText: string;
+                        /** @description Optional. Text that appears immediately before oldText, used to disambiguate when oldText occurs more than once. */
+                        before?: string;
+                        /** @description Optional. Text that appears immediately after oldText, used to disambiguate. */
+                        after?: string;
+                    } | {
                         /** @description 1-based start line. */
                         startLine: number;
                         /** @description 1-based end line (inclusive). */
                         endLine: number;
                         /** @description Replacement text. Empty string to delete lines. */
                         replacement: string;
-                    }[];
+                    })[];
                 };
             };
         };
@@ -6193,8 +6206,10 @@ export interface operations {
                             [key: string]: string;
                         };
                     };
-                    /** @description Version timestamp from getDocument() for optimistic locking. */
-                    documentVersionTimestamp: number;
+                    /** @description Document-level optimistic lock: versionTimestamp from getDocument(). Locks the whole document. Provide this OR diagramVersionTimestamp (at least one is required). */
+                    documentVersionTimestamp?: number;
+                    /** @description Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument, or getDocument with includeDiagramDsl:true). Pass this instead of documentVersionTimestamp to lock only this diagram, so concurrent edits to OTHER diagrams in the same document don't conflict. Preferred for multi-agent concurrency. The response returns the new diagram.diagramVersionTimestamp for chaining further edits. */
+                    diagramVersionTimestamp?: number;
                 };
             };
         };