@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/config/index.js

@@ -1,13 +1,53 @@
 "use strict";
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/config`.
+ *
+ * The scai root configuration model — reading, writing, validating, and
+ * environment-resolving `sitecoreai.cli.json`. SDK consumers that embed
+ * scai need this to resolve the same configuration the CLI does (which
+ * environment, which credentials, which recipe roots) instead of
+ * re-deriving it.
+ *
+ * Pure: no CLI dependencies, no stdout writes, no `process.exit`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readSerializationModules = exports.normalizeModuleConfiguration = exports.readRootConfiguration = exports.mergeEnvironmentConfigurations = exports.writeRootConfigurationFile = exports.readRootConfigurationFile = exports.resolveRootConfigurationPath = void 0;
-var paths_1 = require("./paths");
-Object.defineProperty(exports, "resolveRootConfigurationPath", { enumerable: true, get: function () { return paths_1.resolveRootConfigurationPath; } });
+exports.stripAuthenticationTokensFromConfig = exports.applyEnvOverrides = exports.readSerializationModules = exports.normalizeModuleConfiguration = exports.readJsonFile = exports.formatValidationErrors = exports.validateModuleConfig = exports.validateRootConfig = exports.resolveRootConfigurationPath = exports.readRootConfiguration = exports.mergeEnvironmentConfigurations = exports.writeRootConfigurationFile = exports.readRootConfigurationFile = void 0;
+// --- Configuration model -------------------------------------------------
+__exportStar(require("./types"), exports);
+// --- Read / write / merge ------------------------------------------------
 var root_config_1 = require("./root-config");
 Object.defineProperty(exports, "readRootConfigurationFile", { enumerable: true, get: function () { return root_config_1.readRootConfigurationFile; } });
 Object.defineProperty(exports, "writeRootConfigurationFile", { enumerable: true, get: function () { return root_config_1.writeRootConfigurationFile; } });
 Object.defineProperty(exports, "mergeEnvironmentConfigurations", { enumerable: true, get: function () { return root_config_1.mergeEnvironmentConfigurations; } });
 Object.defineProperty(exports, "readRootConfiguration", { enumerable: true, get: function () { return root_config_1.readRootConfiguration; } });
+// --- Path resolution -----------------------------------------------------
+var paths_1 = require("./paths");
+Object.defineProperty(exports, "resolveRootConfigurationPath", { enumerable: true, get: function () { return paths_1.resolveRootConfigurationPath; } });
+// --- Validation ----------------------------------------------------------
+var validation_1 = require("./validation");
+Object.defineProperty(exports, "validateRootConfig", { enumerable: true, get: function () { return validation_1.validateRootConfig; } });
+Object.defineProperty(exports, "validateModuleConfig", { enumerable: true, get: function () { return validation_1.validateModuleConfig; } });
+Object.defineProperty(exports, "formatValidationErrors", { enumerable: true, get: function () { return validation_1.formatValidationErrors; } });
+Object.defineProperty(exports, "readJsonFile", { enumerable: true, get: function () { return validation_1.readJsonFile; } });
+// --- Serialization modules ----------------------------------------------
 var modules_1 = require("./modules");
 Object.defineProperty(exports, "normalizeModuleConfiguration", { enumerable: true, get: function () { return modules_1.normalizeModuleConfiguration; } });
 Object.defineProperty(exports, "readSerializationModules", { enumerable: true, get: function () { return modules_1.readSerializationModules; } });
+// --- Environment overrides ----------------------------------------------
+var env_overrides_1 = require("./env-overrides");
+Object.defineProperty(exports, "applyEnvOverrides", { enumerable: true, get: function () { return env_overrides_1.applyEnvOverrides; } });
+Object.defineProperty(exports, "stripAuthenticationTokensFromConfig", { enumerable: true, get: function () { return env_overrides_1.stripAuthenticationTokensFromConfig; } });

package/dist/config/modules.d.ts

@@ -1,4 +1,3 @@
 import type { RootConfiguration, SerializationModuleConfiguration } from "./types";
 export declare const normalizeModuleConfiguration: (raw: Partial<SerializationModuleConfiguration>, moduleFile: string, rootConfig: RootConfiguration) => SerializationModuleConfiguration;
 export declare const readSerializationModules: (rootConfig: RootConfiguration, include?: string[], exclude?: string[]) => Promise<SerializationModuleConfiguration[]>;
-//# sourceMappingURL=modules.d.ts.map

package/dist/config/modules.js

@@ -109,7 +109,7 @@ const normalizeModuleConfiguration = (raw, moduleFile, rootConfig) => {
 exports.normalizeModuleConfiguration = normalizeModuleConfiguration;
 const readSerializationModules = async (rootConfig, include, exclude) => {
     if (!rootConfig.modules.length) {
-        throw (0, errors_1.createCliError)("Root configuration does not contain any module path definitions.", "CONFIG_INVALID");
+        throw (0, errors_1.createScaiError)("Root configuration does not contain any module path definitions.", "CONFIG_INVALID");
     }
     const rootDir = node_path_1.default.dirname(rootConfig.physicalPath);
     const moduleFiles = await (0, fast_glob_1.default)(rootConfig.modules, {
@@ -125,7 +125,7 @@ const readSerializationModules = async (rootConfig, include, exclude) => {
             const details = validation_1.validateModuleConfig.errors
                 ? (0, validation_1.formatValidationErrors)(validation_1.validateModuleConfig.errors)
                 : undefined;
-            throw (0, errors_1.createCliError)(`Invalid module configuration at ${moduleFile}.`, "CONFIG_INVALID", {
+            throw (0, errors_1.createScaiError)(`Invalid module configuration at ${moduleFile}.`, "CONFIG_INVALID", {
                 hint: "Fix the module JSON to match the serialization module schema.",
                 details,
             });

package/dist/config/paths.d.ts

@@ -1,2 +1 @@
 export declare const resolveRootConfigurationPath: (currentPath: string) => string;
-//# sourceMappingURL=paths.d.ts.map

package/dist/config/paths.js

@@ -25,6 +25,15 @@ const resolveRootConfigurationPath = (currentPath) => {
         if (node_fs_1.default.existsSync(candidate)) {
             return candidate;
         }
+        // Bound the upward walk at the nearest workspace marker (.git
+        // directory or package.json). This prevents silent pickup of an
+        // attacker-planted sitecoreai.cli.json from above an unrelated
+        // checkout (e.g. /tmp/sitecoreai.cli.json when the user is cd'd
+        // somewhere under /tmp). A weaponized config can redirect the
+        // recipes glob (.recipe.ts files are executed code, see io.ts).
+        if (node_fs_1.default.existsSync(node_path_1.default.join(dir, ".git")) || node_fs_1.default.existsSync(node_path_1.default.join(dir, "package.json"))) {
+            break;
+        }
         const parent = node_path_1.default.dirname(dir);
         if (parent === dir) {
             break;
@@ -32,8 +41,8 @@ const resolveRootConfigurationPath = (currentPath) => {
         dir = parent;
     }
     const cwd = process.cwd();
-    throw (0, errors_1.createCliError)(`Couldn't resolve a root configuration file (sitecoreai.cli.json) from ${cwd} or any parent directory.`, "CONFIG_NOT_FOUND", {
-        hint: "Run 'scai init' to create a configuration file, or pass --config <path> to a directory or a config file.",
+    throw (0, errors_1.createScaiError)(`Couldn't resolve a root configuration file (sitecoreai.cli.json) from ${cwd} or any parent directory.`, "CONFIG_NOT_FOUND", {
+        hint: "Run 'scai setup init' to create a configuration file, or pass --config <path> to a directory or a config file.",
     });
 };
 exports.resolveRootConfigurationPath = resolveRootConfigurationPath;

package/dist/config/root-config.d.ts

@@ -7,4 +7,27 @@ export declare const readRootConfigurationFile: (configPath: string) => {
 export declare const writeRootConfigurationFile: (configPath: string, config: RootConfigurationFile) => void;
 export declare const mergeEnvironmentConfigurations: (primary?: Record<string, EnvironmentConfiguration>, fallback?: Record<string, EnvironmentConfiguration>) => Record<string, EnvironmentConfiguration>;
 export declare const readRootConfiguration: (configPath: string, activeEnvironmentName?: string) => RootConfiguration;
-//# sourceMappingURL=root-config.d.ts.map
+/**
+ * Resolve the environment profile a command should act on.
+ *
+ * Resolution order:
+ *   1. An explicitly named env (`--environment-name` / `-n`).
+ *   2. The configured `defaultEnvProfile`.
+ *   3. The sole env profile, when exactly one is configured — a
+ *      single-environment config then works without anyone having to
+ *      designate a default. Declining "set as default" during
+ *      `setup init` must not strand the only environment.
+ *
+ * Throws `INPUT_INVALID` when none applies — no profiles configured, or
+ * several with no default to disambiguate them — and `ENV_NOT_FOUND`
+ * when the resolved name has no matching profile (a stale
+ * `--environment-name` or `defaultEnvProfile`).
+ *
+ * `root` is returned read with the resolved name as the active env, so
+ * callers see correct env-override layering without re-reading.
+ */
+export declare const resolveActiveEnvironment: (configPath: string, explicitEnvName: string | undefined) => {
+    envName: string;
+    env: EnvironmentConfiguration;
+    root: RootConfiguration;
+};

package/dist/config/root-config.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readRootConfiguration = exports.mergeEnvironmentConfigurations = exports.writeRootConfigurationFile = exports.readRootConfigurationFile = void 0;
+exports.resolveActiveEnvironment = exports.readRootConfiguration = exports.mergeEnvironmentConfigurations = exports.writeRootConfigurationFile = exports.readRootConfigurationFile = void 0;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const errors_1 = require("../shared/errors");
@@ -11,8 +11,29 @@ const types_1 = require("./types");
 const env_overrides_1 = require("./env-overrides");
 const validation_1 = require("./validation");
 const paths_1 = require("./paths");
+/**
+ * Surface the resolved config path under `--verbose` so an operator can spot
+ * a `sitecoreai.cli.json` picked up from an unexpected ancestor directory.
+ * The upward walk is already bounded at the nearest `.git`/`package.json`
+ * (see `resolveRootConfigurationPath`) — this is the observability half of
+ * that defense. Deduped per process: config is re-read by many tasks within
+ * a single command. Stays silent unless `--verbose` is passed (CLI sets the
+ * env flag); SDK consumers never see it.
+ */
+const announcedConfigPaths = new Set();
+const announceResolvedConfigPath = (rootPath) => {
+    if (process.env.SITECOREAI_VERBOSE !== "1" || process.env.SITECOREAI_QUIET === "1") {
+        return;
+    }
+    if (announcedConfigPaths.has(rootPath)) {
+        return;
+    }
+    announcedConfigPaths.add(rootPath);
+    process.stderr.write(`Resolved configuration: ${rootPath}\n`);
+};
 const readRootConfigurationFile = (configPath) => {
     const rootPath = (0, paths_1.resolveRootConfigurationPath)(configPath);
+    announceResolvedConfigPath(rootPath);
     const rootDir = node_path_1.default.dirname(rootPath);
     let rootJson;
     try {
@@ -20,8 +41,8 @@ const readRootConfigurationFile = (configPath) => {
     }
     catch (error) {
         const details = error instanceof Error && error.message ? [error.message] : undefined;
-        throw (0, errors_1.createCliError)(`Invalid configuration file at ${rootPath}.`, "CONFIG_INVALID", {
-            hint: "Fix the configuration or re-run 'scai init' to regenerate it.",
+        throw (0, errors_1.createScaiError)(`Invalid configuration file at ${rootPath}.`, "CONFIG_INVALID", {
+            hint: "Fix the configuration or re-run 'scai setup init' to regenerate it.",
             details,
         });
     }
@@ -30,8 +51,8 @@ const readRootConfigurationFile = (configPath) => {
         const details = validation_1.validateRootConfig.errors
             ? (0, validation_1.formatValidationErrors)(validation_1.validateRootConfig.errors)
             : undefined;
-        throw (0, errors_1.createCliError)(`Invalid configuration file at ${rootPath}.`, "CONFIG_INVALID", {
-            hint: "Fix the configuration or re-run 'scai init' to regenerate it.",
+        throw (0, errors_1.createScaiError)(`Invalid configuration file at ${rootPath}.`, "CONFIG_INVALID", {
+            hint: "Fix the configuration or re-run 'scai setup init' to regenerate it.",
             details,
         });
     }
@@ -76,12 +97,65 @@ const readRootConfiguration = (configPath, activeEnvironmentName) => {
         },
         settings,
         environments: envWithOverrides,
+        // `aiSkills` is the pre-rename name; read it as a fallback so configs
+        // written by older CLI versions keep working. New writes use `brand`.
+        brand: rootJson.brand ?? rootJson.aiSkills ?? {},
+        orgClients: rootJson.orgClients ?? {},
         physicalPath: rootPath,
         defaultEnvironment: rootJson.defaultEnvProfile ?? types_1.DEFAULT_ENVIRONMENT,
+        defaultEnvProfile: rootJson.defaultEnvProfile,
         recipes: rootJson.recipes ?? types_1.DEFAULT_RECIPES_GLOBS,
     };
 };
 exports.readRootConfiguration = readRootConfiguration;
+/**
+ * Resolve the environment profile a command should act on.
+ *
+ * Resolution order:
+ *   1. An explicitly named env (`--environment-name` / `-n`).
+ *   2. The configured `defaultEnvProfile`.
+ *   3. The sole env profile, when exactly one is configured — a
+ *      single-environment config then works without anyone having to
+ *      designate a default. Declining "set as default" during
+ *      `setup init` must not strand the only environment.
+ *
+ * Throws `INPUT_INVALID` when none applies — no profiles configured, or
+ * several with no default to disambiguate them — and `ENV_NOT_FOUND`
+ * when the resolved name has no matching profile (a stale
+ * `--environment-name` or `defaultEnvProfile`).
+ *
+ * `root` is returned read with the resolved name as the active env, so
+ * callers see correct env-override layering without re-reading.
+ */
+const resolveActiveEnvironment = (configPath, explicitEnvName) => {
+    const { config } = (0, exports.readRootConfigurationFile)(configPath);
+    const profileNames = Object.keys(config.envProfiles ?? {});
+    let envName = explicitEnvName ?? config.defaultEnvProfile;
+    if (!envName) {
+        if (profileNames.length === 1) {
+            envName = profileNames[0];
+        }
+        else if (profileNames.length === 0) {
+            throw (0, errors_1.createScaiError)("No environment is configured.", "INPUT_INVALID", {
+                hint: "Run `scai setup init` to create one.",
+            });
+        }
+        else {
+            throw (0, errors_1.createScaiError)("No environment specified and no defaultEnvProfile is set.", "INPUT_INVALID", {
+                hint: `Pass an environment name (one of: ${profileNames.join(", ")}), or set a default with \`scai setup init -n <name> --set-default\`.`,
+            });
+        }
+    }
+    const root = (0, exports.readRootConfiguration)(configPath, envName);
+    const env = root.environments[envName];
+    if (!env) {
+        throw (0, errors_1.createScaiError)(`Environment '${envName}' is not configured.`, "ENV_NOT_FOUND", {
+            hint: `Configured environments: ${profileNames.join(", ") || "(none)"}. Run \`scai setup init\` to add it.`,
+        });
+    }
+    return { envName, env, root };
+};
+exports.resolveActiveEnvironment = resolveActiveEnvironment;
 /**
  * Pairing of nested-form key (under `recipeRoots`) and its flat-form
  * counterpart on `EnvironmentConfiguration`. The flatten step copies
@@ -94,11 +168,14 @@ const RECIPE_ROOT_PAIRS = [
     ["contentModels", "contentModelsRoot"],
     ["partialDesigns", "partialDesignsRoot"],
     ["pageDesigns", "pageDesignsRoot"],
+    ["pageTemplates", "pageTemplatesRoot"],
+    ["pages", "pagesRoot"],
     ["contentItems", "contentItemsRoot"],
     ["headlessVariants", "headlessVariantsRoot"],
     ["availableRenderings", "availableRenderingsRoot"],
     ["enumerations", "enumerationsRoot"],
     ["placeholderSettings", "placeholderSettingsRoots"],
+    ["placeholderSettingsCreate", "placeholderSettingsRoot"],
 ];
 /**
  * Flatten `env.recipeRoots.<x>` entries into the matching flat
@@ -133,13 +210,13 @@ const resolveEnvironmentReferences = (environments) => {
     const resolving = new Set();
     const resolveOne = (name) => {
         if (resolving.has(name)) {
-            throw (0, errors_1.createCliError)(`Environment references are circular for '${name}'.`, "CONFIG_INVALID", {
+            throw (0, errors_1.createScaiError)(`Environment references are circular for '${name}'.`, "CONFIG_INVALID", {
                 hint: "Remove circular refs in envProfiles.",
             });
         }
         const current = environments[name];
         if (!current) {
-            throw (0, errors_1.createCliError)(`Referenced environment '${name}' was not found.`, "CONFIG_INVALID", {
+            throw (0, errors_1.createScaiError)(`Referenced environment '${name}' was not found.`, "CONFIG_INVALID", {
                 hint: "Update envProfiles to reference a valid environment name.",
             });
         }

package/dist/config/schema.json

@@ -5,7 +5,6 @@
     "type": "object",
     "description": "Defines the Sitecore AI CLI root configuration",
     "additionalProperties": false,
-    "required": ["modules"],
     "properties": {
         "$schema": { "type": "string" },
         "defaultEnvProfile": {
@@ -21,13 +20,12 @@
         },
         "modules": {
             "type": "array",
-            "description": "Sitecore module file resolution globs",
-            "minItems": 1,
+            "description": "Sitecore module file resolution globs. Optional — only used by serialization-driven workflows (`scai provision ser …`, `scai provision recipe …`). Brief / Pages / publish-only configs can omit it.",
             "items": { "type": "string" }
         },
         "recipes": {
             "type": "array",
-            "description": "Globs locating .recipe.ts / .recipe.json files for `scai recipe compile|plan|push`. Defaults to `recipes/**/*.recipe.ts` if unset.",
+            "description": "Globs locating .recipe.ts / .recipe.json files for `scai provision recipe compile|plan|push`. Defaults to `recipes/**/*.recipe.ts` if unset.",
             "items": { "type": "string" }
         },
         "serialization": {
@@ -37,6 +35,27 @@
         "settings": {
             "description": "Cli settings",
             "oneOf": [{ "$ref": "#/definitions/Settings" }]
+        },
+        "brand": {
+            "type": "object",
+            "description": "Brand credentials (Brand Management, Brand Review, Documents, Pipeline) keyed by Sitecore organizationId — the credential `scai brand` uses. Backed by AI APIs keys, which are one-org-per-credential and use scopes separate from the env automation client.",
+            "additionalProperties": {
+                "$ref": "#/definitions/BrandCredential"
+            }
+        },
+        "aiSkills": {
+            "type": "object",
+            "description": "Deprecated: legacy name for `brand` (the block was called `aiSkills` before the rename). Accepted for back-compat with older configs; the CLI writes `brand`.",
+            "additionalProperties": {
+                "$ref": "#/definitions/BrandCredential"
+            }
+        },
+        "orgClients": {
+            "type": "object",
+            "description": "Non-secret metadata of the scai-minted org-scoped automation clients, keyed by Sitecore organizationId. One per org, shared by every env profile in it. The matching secret lives in the OS keychain, never on disk.",
+            "additionalProperties": {
+                "$ref": "#/definitions/AutomationClientMetadata"
+            }
         }
     },
     "definitions": {
@@ -85,14 +104,61 @@
                 "description": { "type": "string" }
             }
         },
+        "BrandCredential": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["clientId"],
+            "properties": {
+                "clientId": {
+                    "type": "string",
+                    "description": "Client ID of the AI APIs key created in Cloud Portal → Stream → Admin → AI APIs keys. The matching secret lives in the OS keychain, never on disk."
+                },
+                "audience": {
+                    "type": "string",
+                    "description": "OAuth audience to request. Defaults to https://api.sitecorecloud.io."
+                },
+                "authority": {
+                    "type": "string",
+                    "description": "OAuth authority. Defaults to https://auth.sitecorecloud.io."
+                },
+                "tokenExpiresIn": {
+                    "type": ["integer", "null"],
+                    "description": "Last-known expires_in (seconds) of the cached access token. Advisory only — actual cached token lives in the keychain."
+                },
+                "tokenLastUpdated": {
+                    "type": ["string", "null"],
+                    "description": "ISO timestamp of the last token mint. Advisory only."
+                }
+            }
+        },
+        "AutomationClientMetadata": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["clientId"],
+            "description": "Non-secret metadata of a scai-minted automation client. The matching client secret lives in the OS keychain, never on disk.",
+            "properties": {
+                "clientId": {
+                    "type": "string",
+                    "description": "OAuth client id of the scai-minted automation client."
+                },
+                "name": {
+                    "type": "string",
+                    "description": "Display name of the client in the Cloud Portal (the scai-* name)."
+                },
+                "mintedAt": {
+                    "type": "string",
+                    "description": "ISO timestamp the client was minted."
+                }
+            }
+        },
         "Settings": {
             "type": "object",
             "additionalProperties": false,
             "properties": {
                 "telemetryEnabled": {
                     "type": "boolean",
-                    "description": "Determines if telemetry is enabled in cli.",
-                    "default": false
+                    "description": "Determines if anonymous usage telemetry is sent. Enabled by default; opt out with 'scai cli telemetry disable', SITECOREAI_TELEMETRY=false, or DO_NOT_TRACK=1.",
+                    "default": true
                 },
                 "cacheAuthenticationToken": {
                     "type": "boolean",
@@ -134,6 +200,10 @@
                     "type": "boolean",
                     "description": "Whether writing data to this endpoint is allowed (i.e. to prevent accidental writes to production)"
                 },
+                "denyMcpElevation": {
+                    "type": "boolean",
+                    "description": "When true, MCP write tools refuse to operate against this environment regardless of the host's write-confirmation UX. Use for production-shaped envs where destructive ops must originate from a human CLI call (--allow-write) and never an MCP-elevated context. Defaults to false."
+                },
                 "host": {
                     "type": "string",
                     "description": "Base URL to the Sitecore instance to connect to (i.e. http://{my-sitecore-instance}.sitecorecloud.io)",
@@ -148,7 +218,7 @@
                 },
                 "useClientCredentials": {
                     "type": ["boolean", "null"],
-                    "description": "If true, use client credentials (client ID and secret) instead of interactive device login. Recommended for CI."
+                    "description": "Bring-your-own-client escape hatch: when true, scai uses the operator-supplied clientId + SITECOREAI_ENV_<ENV>_CLIENT_SECRET client-credentials grant instead of an interactive device login. Use this only when supplying your own automation client; otherwise let `scai setup client create` mint one."
                 },
                 "accessToken": {
                     "type": "string",
@@ -175,16 +245,16 @@
                 },
                 "deployToken": {
                     "type": "string",
-                    "description": "SitecoreAI access token (Deploy + CM/admin scopes). Cached in the OS keychain."
+                    "description": "Deprecated: token-cache metadata. The deploy token is stored in the OS keychain; this field is read only for back-compat with older configs."
                 },
                 "deployTokenExpiresIn": {
                     "type": ["integer", "null"],
-                    "description": "Deploy token lifetime in seconds",
+                    "description": "expires_in (seconds) of the cached deploy token. Freshness metadata recorded so the auto-wizard can decide whether a re-login is due. The token string itself lives in the OS keychain.",
                     "format": "int32"
                 },
                 "deployTokenLastUpdated": {
-                    "type": ["null", "string"],
-                    "description": "Last time the deploy token was updated",
+                    "type": ["string", "null"],
+                    "description": "ISO timestamp of the last deploy-token mint. Paired with deployTokenExpiresIn.",
                     "format": "date-time"
                 },
                 "editingHostEnvironmentIds": {
@@ -192,10 +262,13 @@
                     "description": "Editing host environment IDs associated with this CM environment",
                     "items": { "type": "string" }
                 },
-                "clientId": { "type": "string", "description": "OAuth client ID for this endpoint" },
-                "clientSecret": {
+                "clientId": {
                     "type": "string",
-                    "description": "OAuth client secret for this endpoint (when useClientCredentials is true). Prefer environment variables."
+                    "description": "Bring-your-own-client escape hatch: the OAuth client ID of an automation client you supply yourself instead of letting `scai setup client create` mint one. Pair with useClientCredentials. The matching secret is supplied via SITECOREAI_ENV_<ENV>_CLIENT_SECRET and is never stored in the config file."
+                },
+                "automationClient": {
+                    "description": "Non-secret metadata of the env-scoped automation client scai minted for this environment (`scai setup client create <env>`). The matching secret lives in the OS keychain, never on disk. Distinct from the bring-your-own-client clientId/useClientCredentials hatch.",
+                    "oneOf": [{ "$ref": "#/definitions/AutomationClientMetadata" }]
                 },
                 "variables": {
                     "type": "object",
@@ -208,49 +281,61 @@
                 },
                 "templatesRoot": {
                     "type": "string",
-                    "description": "Sitecore parent path under which `scai recipe compile|push` creates template items (e.g. /sitecore/templates/Project/<site>/Components). Tenant-specific. Used as fallback when --templates-root is not passed."
+                    "description": "Sitecore parent path under which `scai provision recipe compile|push` creates template items (e.g. /sitecore/templates/Project/<site>/Components). Tenant-specific. Used as fallback when --templates-root is not passed."
                 },
                 "componentsRoot": {
                     "type": "string",
-                    "description": "Sitecore parent path under which `scai recipe compile|push` creates component template items in the per-site folder layout (`<componentsRoot>/<section>/<Component>`). When unset, the compiler falls back to `templatesRoot` and emits the legacy flat layout. Used as fallback when --components-root is not passed."
+                    "description": "Sitecore parent path under which `scai provision recipe compile|push` creates component template items in the per-site folder layout (`<componentsRoot>/<section>/<Component>`). When unset, the compiler falls back to `templatesRoot` and emits the legacy flat layout. Used as fallback when --components-root is not passed."
                 },
                 "contentModelsRoot": {
                     "type": "string",
-                    "description": "Sitecore parent path under which `scai recipe compile|push` creates content-template items (`<contentModelsRoot>/<group>/<name>` when grouped, flat otherwise). When unset, content templates fall back to `templatesRoot` and land mixed in with components. Used as fallback when --content-models-root is not passed."
+                    "description": "Sitecore parent path under which `scai provision recipe compile|push` creates content-template items (`<contentModelsRoot>/<group>/<name>` when grouped, flat otherwise). When unset, content templates fall back to `templatesRoot` and land mixed in with components. Used as fallback when --content-models-root is not passed."
                 },
                 "renderingsRoot": {
                     "type": "string",
-                    "description": "Sitecore parent path under which `scai recipe compile|push` creates rendering items (e.g. /sitecore/layout/Renderings/Project/<site>). Tenant-specific. Used as fallback when --renderings-root is not passed."
+                    "description": "Sitecore parent path under which `scai provision recipe compile|push` creates rendering items (e.g. /sitecore/layout/Renderings/Project/<site>). Tenant-specific. Used as fallback when --renderings-root is not passed."
                 },
                 "partialDesignsRoot": {
                     "type": "string",
-                    "description": "Sitecore parent path under which `scai recipe compile|push` creates partial-design items (e.g. /sitecore/content/<site>/Presentation/Partial Designs). Required for PartialDesignRecipe compilation."
+                    "description": "Sitecore parent path under which `scai provision recipe compile|push` creates partial-design items (e.g. /sitecore/content/<site>/Presentation/Partial Designs). Required for PartialDesignRecipe compilation."
                 },
                 "pageDesignsRoot": {
                     "type": "string",
-                    "description": "Sitecore parent path under which `scai recipe compile|push` creates page-design items (e.g. /sitecore/content/<site>/Presentation/Page Designs). Required for PageDesignRecipe compilation; also seeds crossRecipeRefs for the cross-recipe TemplatesMapping aggregate."
+                    "description": "Sitecore parent path under which `scai provision recipe compile|push` creates page-design items (e.g. /sitecore/content/<site>/Presentation/Page Designs). Required for PageDesignRecipe compilation; also seeds crossRecipeRefs for the cross-recipe TemplatesMapping aggregate."
                 },
                 "contentItemsRoot": {
                     "type": "string",
-                    "description": "Sitecore parent path under which `scai recipe compile|push` creates shared content items (e.g. /sitecore/content/<site>/Data). Required for ContentItemRecipe compilation."
+                    "description": "Sitecore parent path under which `scai provision recipe compile|push` creates shared content items (e.g. /sitecore/content/<site>/Data). Required for ContentItemRecipe compilation."
                 },
                 "headlessVariantsRoot": {
                     "type": "string",
-                    "description": "Sitecore parent path under which `scai recipe compile|push` creates SXA Headless rendering variants (e.g. /sitecore/content/<siteCollection>/<site>/Presentation/Headless Variants). Required when any recipe in the set declares variants."
+                    "description": "Sitecore parent path under which `scai provision recipe compile|push` creates SXA Headless rendering variants (e.g. /sitecore/content/<siteCollection>/<site>/Presentation/Headless Variants). Required when any recipe in the set declares variants."
                 },
                 "availableRenderingsRoot": {
                     "type": "string",
-                    "description": "Sitecore parent path under which `scai recipe compile|push` creates SXA Available Renderings section items (e.g. /sitecore/content/<siteCollection>/<site>/Presentation/Available Renderings). One section per `recipe.section` is emitted with all renderings in that section listed in the Renderings field."
+                    "description": "Sitecore parent path under which `scai provision recipe compile|push` creates SXA Available Renderings section items (e.g. /sitecore/content/<siteCollection>/<site>/Presentation/Available Renderings). One section per `recipe.section` is emitted with all renderings in that section listed in the Renderings field."
                 },
                 "enumerationsRoot": {
                     "type": "string",
-                    "description": "Sitecore parent path under which `scai recipe compile|push` creates EnumerationRecipe items (e.g. /sitecore/content/<siteCollection>/<site>/Presentation/Enumerations). Each enum lands as `<enumerationsRoot>/<EnumName>` with one child item per declared value. Required for EnumerationRecipe compilation, and for any recipe whose fields carry `sitecore.enumHandle`."
+                    "description": "Sitecore parent path under which `scai provision recipe compile|push` creates EnumerationRecipe items (e.g. /sitecore/content/<siteCollection>/<site>/Presentation/Enumerations). Each enum lands as `<enumerationsRoot>/<EnumName>` with one child item per declared value. Required for EnumerationRecipe compilation, and for any recipe whose fields carry `sitecore.enumHandle`."
                 },
                 "placeholderSettingsRoots": {
                     "type": "array",
                     "items": { "type": "string" },
                     "description": "Sitecore content-tree paths to walk when resolving recipe-declared `placeholders` to Placeholder Settings items (matched by their `Placeholder Key` field). Typically the per-site Presentation/Placeholder Settings AND the Layout/Placeholder Settings/Project/<site> path."
                 },
+                "placeholderSettingsRoot": {
+                    "type": "string",
+                    "description": "Sitecore content-tree root under which `scai provision recipe compile|push` CREATES recipe-defined Placeholder Settings items (e.g. /sitecore/content/<site>/Presentation/Placeholder Settings). Distinct from placeholderSettingsRoots (the plural walk list)."
+                },
+                "pageTemplatesRoot": {
+                    "type": "string",
+                    "description": "Sitecore templates root under which `scai provision recipe compile|push` creates PageTemplateRecipe items (e.g. /sitecore/templates/Project/<site>). Optional; falls back to templatesRoot."
+                },
+                "pagesRoot": {
+                    "type": "string",
+                    "description": "Sitecore content-tree root under which `scai provision recipe compile|push` creates PageRecipe items (e.g. /sitecore/content/<tenant>/<site>/Home). Required for PageRecipe compilation."
+                },
                 "recipeRoots": {
                     "type": "object",
                     "description": "Preferred nested form of the *Root fields. Flattened into the matching flat fields at config-load time (recipeRoots wins when both are set; a warning fires).",
@@ -262,6 +347,8 @@
                         "contentModels": { "type": "string" },
                         "partialDesigns": { "type": "string" },
                         "pageDesigns": { "type": "string" },
+                        "pageTemplates": { "type": "string" },
+                        "pages": { "type": "string" },
                         "contentItems": { "type": "string" },
                         "headlessVariants": { "type": "string" },
                         "availableRenderings": { "type": "string" },
@@ -269,7 +356,8 @@
                         "placeholderSettings": {
                             "type": "array",
                             "items": { "type": "string" }
-                        }
+                        },
+                        "placeholderSettingsCreate": { "type": "string" }
                     }
                 }
             }