@dotcms/ai 26.8.10-1 → 26.8.10-1-next.2511

package/README.md

@@ -20,6 +20,34 @@ Safety isn't a setting you turn on; it's the shape of the runtime:
 npm install @dotcms/ai
 ```
 
+## Which SDK Version Should I Use?
+
+dotCMS SDKs are published in lockstep with dotCMS itself: every `@dotcms/*` package ships
+at the **exact same version number** as the dotCMS release it was built for (e.g. dotCMS
+`26.7.14-1` → `@dotcms/client@26.7.14-1`, `@dotcms/react@26.7.14-1`, and so on).
+
+**Simple rule of thumb: use the SDK version that matches your dotCMS instance's version.**
+
+You don't have to upgrade the SDK every time dotCMS releases a new version (or vice versa).
+Most releases don't change anything the SDKs rely on, so an older SDK usually keeps working
+fine against a newer dotCMS instance. Occasionally, though, a release does include a real
+breaking change — and if your SDK is older than that point, it will stop working correctly.
+
+You don't need to track this yourself: your dotCMS instance always knows the oldest SDK
+version it still supports, and the SDK checks itself against it automatically. If you're
+using an SDK that's too old, you'll see a clear warning in your console telling you to
+upgrade.
+
+**Recommendation:** pin your SDKs to the same version as your dotCMS instance, and only bump
+them when you upgrade dotCMS — or when the console tells you to.
+
+> **On an LTS release?** LTS releases don't currently get their own matching SDK version.
+> Until that's addressed, use the SDK version published for the closest regular release at
+> or before your LTS version.
+>
+> Want more background on how dotCMS releases and support windows work? See
+> [Release & Support Lifecycle](https://dev.dotcms.com/docs/release-support-lifecycle).
+
 ## The front door — one runtime, two verbs
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/ai",
-  "version": "26.08.10-01",
+  "version": "26.8.10-1-next.2511",
   "description": "The dotCMS agentic runtime — run model-written or human-written code safely against a dotCMS instance, with auth and policy owned in one place.",
   "repository": {
     "type": "git",

package/spec.cjs.js

@@ -3211,7 +3211,7 @@ var paths = {
 				"Folders"
 			],
 			summary: "Search folders",
-			description: "Returns folders within a site matching an optional name filter and/or path scope. Supports recursive depth control, standard pagination, and sorting. With no 'name' and default path '/' + recursive=true, all site folders are returned.",
+			description: "Returns folders within a site matching an optional name filter and/or path scope. Supports recursive depth control, standard pagination, and sorting. With no 'name' and default path '/' + recursive=true, all site folders are returned. Each folder carries the detail fields a folder-edit form needs (title, sortOrder, filesMasks, defaultFileType, showOnMenu, defaultBaseType). Set 'includePermissions=true' to also receive the permission types the requesting user holds on each folder; that flag caps 'perPage' (see the parameter description).",
 			operationId: "searchFolders",
 			parameters: [
 				{
@@ -3293,6 +3293,15 @@ var paths = {
 						format: "int32",
 						"default": 40
 					}
+				},
+				{
+					name: "includePermissions",
+					"in": "query",
+					description: "When true, each returned folder includes a 'permissions' array with the permission types the requesting user holds on it (READ, EDIT, PUBLISH, EDIT_PERMISSIONS, CAN_ADD_CHILDREN). When false (the default) 'permissions' is null — meaning 'not requested', which is not the same as an empty array ('requested, no grants'). Because permissions are resolved per page, enabling this flag caps 'perPage' at the value of the 'content.drive.folder.search.permissions.max.per.page' configuration property (default 200); a larger 'perPage' is rejected with a 400.",
+					schema: {
+						type: "boolean",
+						"default": false
+					}
 				}
 			],
 			responses: {
@@ -3304,7 +3313,7 @@ var paths = {
 					}
 				},
 				"400": {
-					description: "'siteId' is required; 'name' must be at least 2 characters if provided"
+					description: "'siteId' is required; 'name' must be at least 2 characters if provided; 'perPage' exceeds the maximum allowed when 'includePermissions' is true"
 				},
 				"401": {
 					description: "User is not authenticated"

package/spec.esm.js

@@ -3209,7 +3209,7 @@ var paths = {
 				"Folders"
 			],
 			summary: "Search folders",
-			description: "Returns folders within a site matching an optional name filter and/or path scope. Supports recursive depth control, standard pagination, and sorting. With no 'name' and default path '/' + recursive=true, all site folders are returned.",
+			description: "Returns folders within a site matching an optional name filter and/or path scope. Supports recursive depth control, standard pagination, and sorting. With no 'name' and default path '/' + recursive=true, all site folders are returned. Each folder carries the detail fields a folder-edit form needs (title, sortOrder, filesMasks, defaultFileType, showOnMenu, defaultBaseType). Set 'includePermissions=true' to also receive the permission types the requesting user holds on each folder; that flag caps 'perPage' (see the parameter description).",
 			operationId: "searchFolders",
 			parameters: [
 				{
@@ -3291,6 +3291,15 @@ var paths = {
 						format: "int32",
 						"default": 40
 					}
+				},
+				{
+					name: "includePermissions",
+					"in": "query",
+					description: "When true, each returned folder includes a 'permissions' array with the permission types the requesting user holds on it (READ, EDIT, PUBLISH, EDIT_PERMISSIONS, CAN_ADD_CHILDREN). When false (the default) 'permissions' is null — meaning 'not requested', which is not the same as an empty array ('requested, no grants'). Because permissions are resolved per page, enabling this flag caps 'perPage' at the value of the 'content.drive.folder.search.permissions.max.per.page' configuration property (default 200); a larger 'perPage' is rejected with a 400.",
+					schema: {
+						type: "boolean",
+						"default": false
+					}
 				}
 			],
 			responses: {
@@ -3302,7 +3311,7 @@ var paths = {
 					}
 				},
 				"400": {
-					description: "'siteId' is required; 'name' must be at least 2 characters if provided"
+					description: "'siteId' is required; 'name' must be at least 2 characters if provided; 'perPage' exceeds the maximum allowed when 'includePermissions' is true"
 				},
 				"401": {
 					description: "User is not authenticated"