@sitecoreai-labs/sitecoreai-cli 0.1.2 → 0.2.1

package/dist/agents/tasks/agent.js

@@ -38,7 +38,7 @@ const runAgentGet = async (options) => {
 exports.runAgentGet = runAgentGet;
 const runAgentCreate = async (options) => {
     const { logger, session } = await (0, shared_1.prepare)(options);
-    const recipe = (0, sync_1.loadRecipe)(options.file, agent_schema_1.AgentRecipeSchema);
+    const recipe = await (0, sync_1.loadRecipe)(options.file, agent_schema_1.AgentRecipeSchema);
     if (findByName(await (0, agents_1.listAgents)(session), recipe.name)) {
         throw (0, errors_1.createScaiError)(`Agent "${recipe.name}" already exists.`, "INPUT_INVALID", {
             hint: "Use `scai agents agent update` to change it, or pick a different name.",
@@ -67,7 +67,7 @@ const runAgentCreate = async (options) => {
 exports.runAgentCreate = runAgentCreate;
 const runAgentUpdate = async (options) => {
     const { logger, session } = await (0, shared_1.prepare)(options);
-    const recipe = (0, sync_1.loadRecipe)(options.file, agent_schema_1.AgentRecipeSchema);
+    const recipe = await (0, sync_1.loadRecipe)(options.file, agent_schema_1.AgentRecipeSchema);
     const existing = await (0, agents_1.getAgent)(session, options.idOrSlug);
     if (!existing) {
         throw (0, errors_1.createScaiError)(`Agent "${options.idOrSlug}" not found.`, "INPUT_INVALID", {

package/dist/agents/tasks/resources.js

@@ -32,7 +32,7 @@ const makeResourceTasks = (config) => {
     };
     const runCreate = async (options) => {
         const { logger, session } = await (0, shared_1.prepare)(options);
-        const recipe = (0, sync_1.loadRecipe)(options.file, config.schema);
+        const recipe = await (0, sync_1.loadRecipe)(options.file, config.schema);
         if (await config.find(session, recipe.name)) {
             throw (0, errors_1.createScaiError)(`A ${config.resource} named "${recipe.name}" already exists.`, "INPUT_INVALID", { hint: `Pick a different name, or use \`scai agents ${config.resource} update\`.` });
         }
@@ -54,7 +54,7 @@ const makeResourceTasks = (config) => {
             (0, shared_1.requireUnverified)(options.unverified, config.resource, "update");
         }
         const { logger, session } = await (0, shared_1.prepare)(options);
-        const recipe = (0, sync_1.loadRecipe)(options.file, config.schema);
+        const recipe = await (0, sync_1.loadRecipe)(options.file, config.schema);
         let id;
         if (config.resolveById) {
             id = options.idOrName;

package/dist/agents/tasks/space.js

@@ -35,7 +35,7 @@ const runSpaceArtifacts = async (options) => {
 exports.runSpaceArtifacts = runSpaceArtifacts;
 const runSpaceUpdate = async (options) => {
     const { logger, session } = await (0, shared_1.prepare)(options);
-    const patch = (0, sync_1.loadRecipe)(options.file, SpaceConfigPatchSchema);
+    const patch = await (0, sync_1.loadRecipe)(options.file, SpaceConfigPatchSchema);
     const current = await (0, spaces_1.getSpaceConfig)(session, options.spaceId);
     const merged = { ...current, ...patch };
     if (options.whatIf) {

package/dist/brand/api/auth.d.ts

@@ -32,7 +32,12 @@ import type { BrandCredential } from "../../config/types";
 export declare const BRAND_REQUIRED_SCOPES: readonly ["ai.org.br:gen"];
 export interface AcquireBrandTokenOptions {
     orgId: string;
-    credential: BrandCredential;
+    /**
+     * The `brand[orgId]` config block, if present. Optional: serverless
+     * callers (showcase orchestrator) may have no config file at all and
+     * supply credentials via the `SITECOREAI_BRAND_*` env vars instead.
+     */
+    credential?: BrandCredential;
 }
 export declare const extractScopes: (token: string) => string[];
 export declare const hasBrandScopes: (token: string) => boolean;
@@ -45,14 +50,16 @@ export declare const hasBrandScopes: (token: string) => boolean;
  *      by a previous mint via this function. Reused while it still
  *      carries the required scopes; cleared on next 401 by callers.
  *   2. Fresh M2M mint against the `auth.sitecorecloud.io/oauth/token`
- *      endpoint with `audience=https://api.sitecorecloud.io`, using
- *      the org-scoped `clientId` from `brand[orgId]` and the
- *      matching secret from the keychain. Cached on success.
+ *      endpoint with `audience=https://api.sitecorecloud.io`. The
+ *      `clientId` + secret + authority + audience are resolved by
+ *      `resolveBrandSecrets`, which walks: (a) the
+ *      `SITECOREAI_BRAND_*` env vars (serverless override), then
+ *      (b) the `brand[orgId]` config block + OS keychain. Successful
+ *      mints are cached.
  *
- * Refuses with `AUTH_BRAND_REQUIRED` when none of these paths
- * produces a token carrying the required scopes. The error message
- * decodes the granted-scope set and infers the credential class so
- * operators know whether they need to provision a new AI APIs key or
- * just re-login.
+ * Refuses with `AUTH_BRAND_REQUIRED` when neither tier supplies a
+ * credential. The error message points operators at both the OS
+ * keychain login flow AND the serverless env-var path so the right
+ * fix is one re-read away.
  */
 export declare const acquireBrandToken: (options: AcquireBrandTokenOptions) => Promise<string>;

package/dist/brand/api/auth.js

@@ -4,6 +4,7 @@ exports.acquireBrandToken = exports.hasBrandScopes = exports.extractScopes = exp
 const auth_1 = require("../../serialization/api/auth");
 const errors_1 = require("../../shared/errors");
 const keychain_1 = require("../../shared/keychain");
+const credential_1 = require("../credential");
 /**
  * OAuth scopes scai's *currently shipped* Brand operations require.
  *
@@ -35,7 +36,7 @@ const keychain_1 = require("../../shared/keychain");
  * if their specific scope isn't present.
  */
 exports.BRAND_REQUIRED_SCOPES = ["ai.org.br:gen"];
-const NO_CREDENTIAL_HINT = "Run `scai setup login brand --env <env>` to provision the credential, or paste an existing AI APIs key into `brand.<orgId>` in sitecoreai.cli.json (clientId only; secret goes through the keychain via the login flow). Create the credential in Cloud Portal → Stream → Admin → AI APIs keys.";
+const NO_CREDENTIAL_HINT = "Run `scai setup login brand --env <env>` to provision the credential, or paste an existing AI APIs key into `brand.<orgId>` in sitecoreai.cli.json (clientId only; secret goes through the keychain via the login flow). Create the credential in Cloud Portal → Stream → Admin → AI APIs keys. In serverless contexts (Vercel functions, CI runners) without an OS keychain, set the SITECOREAI_BRAND_CLIENT_ID + SITECOREAI_BRAND_CLIENT_SECRET env vars instead — they take precedence over the config+keychain pair.";
 const decodeJwtPayload = (token) => {
     const parts = token.split(".");
     if (parts.length !== 3) {
@@ -67,7 +68,6 @@ const hasBrandScopes = (token) => {
     return exports.BRAND_REQUIRED_SCOPES.every((s) => granted.has(s));
 };
 exports.hasBrandScopes = hasBrandScopes;
-const DEFAULT_AUTHORITY = "https://auth.sitecorecloud.io";
 /**
  * Returns a Bearer JWT for the Sitecore Brand APIs.
  *
@@ -77,15 +77,17 @@ const DEFAULT_AUTHORITY = "https://auth.sitecorecloud.io";
  *      by a previous mint via this function. Reused while it still
  *      carries the required scopes; cleared on next 401 by callers.
  *   2. Fresh M2M mint against the `auth.sitecorecloud.io/oauth/token`
- *      endpoint with `audience=https://api.sitecorecloud.io`, using
- *      the org-scoped `clientId` from `brand[orgId]` and the
- *      matching secret from the keychain. Cached on success.
+ *      endpoint with `audience=https://api.sitecorecloud.io`. The
+ *      `clientId` + secret + authority + audience are resolved by
+ *      `resolveBrandSecrets`, which walks: (a) the
+ *      `SITECOREAI_BRAND_*` env vars (serverless override), then
+ *      (b) the `brand[orgId]` config block + OS keychain. Successful
+ *      mints are cached.
  *
- * Refuses with `AUTH_BRAND_REQUIRED` when none of these paths
- * produces a token carrying the required scopes. The error message
- * decodes the granted-scope set and infers the credential class so
- * operators know whether they need to provision a new AI APIs key or
- * just re-login.
+ * Refuses with `AUTH_BRAND_REQUIRED` when neither tier supplies a
+ * credential. The error message points operators at both the OS
+ * keychain login flow AND the serverless env-var path so the right
+ * fix is one re-read away.
  */
 const acquireBrandToken = async (options) => {
     const { orgId, credential } = options;
@@ -93,25 +95,33 @@ const acquireBrandToken = async (options) => {
     //    server-side scope enforcement happens on the API call itself,
     //    and gating here would skip a perfectly usable token whenever
     //    the operation it's used for doesn't need the validated scope.
+    //
+    //    NB: in a serverless context (no keychain) the cache lookup
+    //    silently returns undefined via the keychain wrapper's
+    //    fail-closed behaviour, so we drop straight to the mint path —
+    //    every invocation re-mints, which is correct: there is no
+    //    persistent process to hold a cached token across invocations.
     const cached = await (0, keychain_1.getBrandToken)(orgId);
     if (cached) {
         return cached;
     }
-    // 2. Fresh M2M mint via the AI APIs key.
-    const clientSecret = await (0, keychain_1.getBrandClientSecret)(orgId);
-    if (!credential.clientId || !clientSecret) {
+    // 2. Fresh M2M mint via the AI APIs key. `resolveBrandSecrets`
+    //    picks env-var vs config+keychain; partial-env states throw
+    //    inside the resolver (so the operator sees the malformed-env
+    //    hint, not a generic missing-credential one), an empty result
+    //    here means neither tier had anything to offer.
+    const secrets = await (0, credential_1.resolveBrandSecrets)({ orgId, credential });
+    if (!secrets) {
         throw (0, errors_1.createScaiError)(`No Brand credential is configured for org '${orgId}'.`, "AUTH_BRAND_REQUIRED", { hint: NO_CREDENTIAL_HINT });
     }
-    const authority = credential.authority ?? DEFAULT_AUTHORITY;
-    const audience = credential.audience ?? auth_1.DEFAULT_SITECORE_API_AUDIENCE;
     // Reuse the shared client-credentials helper. It accepts a
     // `SitecoreApiClientOptions`-shaped argument; we only need the
     // auth-relevant fields.
     const mintEnv = {
-        authority,
-        clientId: credential.clientId,
-        clientSecret,
-        audience,
+        authority: secrets.authority,
+        clientId: secrets.clientId,
+        clientSecret: secrets.clientSecret,
+        audience: secrets.audience,
     };
     let result;
     try {

package/dist/brand/credential.d.ts

@@ -2,11 +2,16 @@
  * Brand credential resolution shared by every `scai brand` surface and
  * by `scai setup login brand`.
  *
- * Two layers:
+ * Three layers:
  *   - `resolveBrandOrgId` — the pure orgId-resolution rule.
  *   - `resolveBrandClient` — reads the config, resolves the orgId, looks
  *     up the `brand[orgId]` credential, and returns the API client
  *     options a brand operation needs.
+ *   - `resolveBrandSecrets` — pulls the `{ clientId, clientSecret,
+ *     authority, audience }` quartet a token mint needs. Env-var
+ *     overrides take precedence over the config-and-keychain pair so
+ *     serverless callers (the showcase orchestrator) can drive brand
+ *     ops without an OS keychain.
  *
  * (`src/brand/recipe/client.ts` has a separate `resolveBrandClient` that
  * resolves from a sync `SyncContext` rather than CLI options — the sync
@@ -14,6 +19,7 @@
  * the fallbacks here.)
  */
 import type { BrandApiClientOptions } from "./api/client";
+import type { BrandCredential } from "../config/types";
 /**
  * Resolve the Sitecore `organizationId` for a Brand credential.
  * Resolution order:
@@ -53,3 +59,67 @@ export interface BrandClientResolveOptions {
  * first.
  */
 export declare const resolveBrandClient: (options: BrandClientResolveOptions) => BrandApiClientOptions;
+/**
+ * The `{ clientId, clientSecret, authority, audience }` a Brand-API
+ * client-credentials mint needs, plus the tier that supplied each
+ * field for diagnostics.
+ */
+export interface ResolvedBrandSecrets {
+    clientId: string;
+    clientSecret: string;
+    authority: string;
+    audience: string;
+    /**
+     * Which tier the **secret** came from. `"env"` means the
+     * orchestrator-style override; `"keychain"` is the developer-laptop
+     * default. The `clientId` / `authority` / `audience` may still come
+     * from the config when the secret is from the env (one-shot override
+     * of just the secret is supported and useful for short-lived CI
+     * secrets paired with a config-pinned client).
+     */
+    source: "env" | "keychain";
+}
+export interface ResolveBrandSecretsOptions {
+    /** Sitecore organization id — keys the `getBrandClientSecret` slot. */
+    orgId: string;
+    /** `brand[orgId]` block from the root config — may be absent in serverless. */
+    credential?: BrandCredential;
+}
+/**
+ * Resolve the secrets a Brand-API M2M mint needs, walking two tiers:
+ *
+ *   1. **Environment variables** (`SITECOREAI_BRAND_CLIENT_ID` +
+ *      `SITECOREAI_BRAND_CLIENT_SECRET`). Both must be present for this
+ *      tier to apply. `SITECOREAI_BRAND_AUTHORITY` and
+ *      `SITECOREAI_BRAND_AUDIENCE` are optional overrides that compose
+ *      with either tier.
+ *   2. **Config + OS keychain** — the developer-laptop default: client
+ *      id from the `brand[orgId]` config block, secret from the keychain
+ *      (`getBrandClientSecret`).
+ *
+ * **Precedence:** env wins. Rationale — the env-var path is the
+ * explicit, per-invocation override a serverless host (Vercel function,
+ * CI runner) sets right before calling scai; treating it as the
+ * higher-priority lookup means a host can swap credentials between
+ * invocations without touching disk or the keychain. The keychain path
+ * is the long-lived default for human developers.
+ *
+ * Error contract — `AUTH_BRAND_REQUIRED` in three flavors so operators
+ * know which knob to turn:
+ *
+ *   - **Partial env**: one of `SITECOREAI_BRAND_CLIENT_ID` /
+ *     `SITECOREAI_BRAND_CLIENT_SECRET` is set but the other isn't.
+ *     We treat that as malformed (operator intended env-tier but
+ *     missed a var) rather than silently falling through to the
+ *     keychain — silent fallthrough would mask a typo and hand the
+ *     wrong credential to the API.
+ *   - **No credential anywhere**: neither env nor keychain has the
+ *     secret, and the config has no `clientId` for the org.
+ *   - **Keychain only, no secret**: the config has a `clientId` but
+ *     the keychain lookup came back empty (re-login needed).
+ *
+ * Returns `undefined` only as a sentinel for the "no credential
+ * anywhere" case so the caller can build the right hint with the
+ * orgId in scope. Other malformed states throw immediately.
+ */
+export declare const resolveBrandSecrets: (options: ResolveBrandSecretsOptions) => Promise<ResolvedBrandSecrets | undefined>;

package/dist/brand/credential.js

@@ -3,11 +3,16 @@
  * Brand credential resolution shared by every `scai brand` surface and
  * by `scai setup login brand`.
  *
- * Two layers:
+ * Three layers:
  *   - `resolveBrandOrgId` — the pure orgId-resolution rule.
  *   - `resolveBrandClient` — reads the config, resolves the orgId, looks
  *     up the `brand[orgId]` credential, and returns the API client
  *     options a brand operation needs.
+ *   - `resolveBrandSecrets` — pulls the `{ clientId, clientSecret,
+ *     authority, audience }` quartet a token mint needs. Env-var
+ *     overrides take precedence over the config-and-keychain pair so
+ *     serverless callers (the showcase orchestrator) can drive brand
+ *     ops without an OS keychain.
  *
  * (`src/brand/recipe/client.ts` has a separate `resolveBrandClient` that
  * resolves from a sync `SyncContext` rather than CLI options — the sync
@@ -15,10 +20,11 @@
  * the fallbacks here.)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveBrandClient = exports.resolveBrandOrgId = void 0;
+exports.resolveBrandSecrets = exports.resolveBrandClient = exports.resolveBrandOrgId = void 0;
 const root_config_1 = require("../config/root-config");
 const errors_1 = require("../shared/errors");
 const cli_tasks_1 = require("../shared/cli-tasks");
+const keychain_1 = require("../shared/keychain");
 /**
  * Resolve the Sitecore `organizationId` for a Brand credential.
  * Resolution order:
@@ -85,3 +91,114 @@ const resolveBrandClient = (options) => {
     return { orgId, credential };
 };
 exports.resolveBrandClient = resolveBrandClient;
+/**
+ * Default Auth0 authority for Brand credentials. Kept aligned with the
+ * one `acquireBrandToken` previously hard-coded so callers that drop in
+ * `resolveBrandSecrets` see no behavioural change.
+ */
+const DEFAULT_BRAND_AUTHORITY = "https://auth.sitecorecloud.io";
+const DEFAULT_BRAND_AUDIENCE = "https://api.sitecorecloud.io";
+/**
+ * Env-var names the serverless fallback honors. The serverless caller —
+ * today the showcase orchestrator's `brandkit_deploy` handler — sets
+ * these per invocation: there is no shared OS keychain in a Vercel
+ * function, so the credential MUST come from the environment.
+ *
+ * Generic names (no per-org / per-env normalization) on purpose: a
+ * single function invocation is always scoped to one org, and the host
+ * sets the env vars right before calling scai. If a future caller needs
+ * multi-org concurrency in one process, this will need a key-normalized
+ * variant — but that day hasn't come.
+ */
+const BRAND_ENV_CLIENT_ID = "SITECOREAI_BRAND_CLIENT_ID";
+const BRAND_ENV_CLIENT_SECRET = "SITECOREAI_BRAND_CLIENT_SECRET";
+const BRAND_ENV_AUTHORITY = "SITECOREAI_BRAND_AUTHORITY";
+const BRAND_ENV_AUDIENCE = "SITECOREAI_BRAND_AUDIENCE";
+const trimmedEnv = (key) => {
+    const raw = process.env[key];
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+};
+/**
+ * Resolve the secrets a Brand-API M2M mint needs, walking two tiers:
+ *
+ *   1. **Environment variables** (`SITECOREAI_BRAND_CLIENT_ID` +
+ *      `SITECOREAI_BRAND_CLIENT_SECRET`). Both must be present for this
+ *      tier to apply. `SITECOREAI_BRAND_AUTHORITY` and
+ *      `SITECOREAI_BRAND_AUDIENCE` are optional overrides that compose
+ *      with either tier.
+ *   2. **Config + OS keychain** — the developer-laptop default: client
+ *      id from the `brand[orgId]` config block, secret from the keychain
+ *      (`getBrandClientSecret`).
+ *
+ * **Precedence:** env wins. Rationale — the env-var path is the
+ * explicit, per-invocation override a serverless host (Vercel function,
+ * CI runner) sets right before calling scai; treating it as the
+ * higher-priority lookup means a host can swap credentials between
+ * invocations without touching disk or the keychain. The keychain path
+ * is the long-lived default for human developers.
+ *
+ * Error contract — `AUTH_BRAND_REQUIRED` in three flavors so operators
+ * know which knob to turn:
+ *
+ *   - **Partial env**: one of `SITECOREAI_BRAND_CLIENT_ID` /
+ *     `SITECOREAI_BRAND_CLIENT_SECRET` is set but the other isn't.
+ *     We treat that as malformed (operator intended env-tier but
+ *     missed a var) rather than silently falling through to the
+ *     keychain — silent fallthrough would mask a typo and hand the
+ *     wrong credential to the API.
+ *   - **No credential anywhere**: neither env nor keychain has the
+ *     secret, and the config has no `clientId` for the org.
+ *   - **Keychain only, no secret**: the config has a `clientId` but
+ *     the keychain lookup came back empty (re-login needed).
+ *
+ * Returns `undefined` only as a sentinel for the "no credential
+ * anywhere" case so the caller can build the right hint with the
+ * orgId in scope. Other malformed states throw immediately.
+ */
+const resolveBrandSecrets = async (options) => {
+    const envClientId = trimmedEnv(BRAND_ENV_CLIENT_ID);
+    const envClientSecret = trimmedEnv(BRAND_ENV_CLIENT_SECRET);
+    const envAuthority = trimmedEnv(BRAND_ENV_AUTHORITY);
+    const envAudience = trimmedEnv(BRAND_ENV_AUDIENCE);
+    // Tier 1: env vars. Require BOTH the id and the secret — a partial
+    // pair is almost always a misconfiguration (forgot to set the other
+    // half), and silently falling through to a different credential
+    // tier would surface as a confusing 401 from Sitecore rather than
+    // the real "your env is malformed" message.
+    if (envClientId && envClientSecret) {
+        return {
+            clientId: envClientId,
+            clientSecret: envClientSecret,
+            authority: envAuthority ?? options.credential?.authority ?? DEFAULT_BRAND_AUTHORITY,
+            audience: envAudience ?? options.credential?.audience ?? DEFAULT_BRAND_AUDIENCE,
+            source: "env",
+        };
+    }
+    if (envClientId || envClientSecret) {
+        const missing = envClientId ? BRAND_ENV_CLIENT_SECRET : BRAND_ENV_CLIENT_ID;
+        throw (0, errors_1.createScaiError)(`Brand credential env vars are partially set: ${missing} is missing.`, "AUTH_BRAND_REQUIRED", {
+            hint: `Set both ${BRAND_ENV_CLIENT_ID} and ${BRAND_ENV_CLIENT_SECRET}, or unset both to fall back to the OS keychain.`,
+        });
+    }
+    // Tier 2: config + OS keychain. The config supplies the non-secret
+    // metadata (clientId / authority / audience); the keychain supplies
+    // the secret.
+    if (!options.credential?.clientId) {
+        return undefined;
+    }
+    const keychainSecret = await (0, keychain_1.getBrandClientSecret)(options.orgId);
+    if (!keychainSecret) {
+        return undefined;
+    }
+    return {
+        clientId: options.credential.clientId,
+        clientSecret: keychainSecret,
+        authority: envAuthority ?? options.credential.authority ?? DEFAULT_BRAND_AUTHORITY,
+        audience: envAudience ?? options.credential.audience ?? DEFAULT_BRAND_AUDIENCE,
+        source: "keychain",
+    };
+};
+exports.resolveBrandSecrets = resolveBrandSecrets;

package/dist/brand/recipe/diff.js

@@ -31,11 +31,16 @@ const diffBrandKit = (desired, current) => {
             meta: { stage: "kit", description: desired.description, industry: desired.industry },
         });
         desired.documents.forEach((document, index) => {
+            // The discriminated union has two shapes — `url` carries a URL,
+            // `registry-file` carries a `path`. The diff describes the
+            // change in human terms only; the apply step is where the
+            // registry-file → URL contract is enforced.
+            const label = document.kind === "url" ? document.url : `registry-file:${document.path}`;
             changes.push({
                 kind: "create",
                 path: `documents[${index}]`,
-                summary: `Upload + ingest ${document.url}`,
-                after: document.url,
+                summary: `Upload + ingest ${label}`,
+                after: label,
                 meta: { stage: "document", document },
             });
         });

package/dist/brand/recipe/schema.d.ts

@@ -5,7 +5,23 @@
  * This schema is the single source of truth for the `brand-kit` recipe
  * kind: it validates recipe files, drives the `sync` CLI, and becomes
  * the MCP tool input schema. Keep the `.describe()` text accurate — the
- * model reads it. See docs/recipe-sync-architecture.md.
+ * model reads it.
+ *
+ * Two authoring shapes share this schema:
+ *
+ *   - **scai-native** — flat object with `name`, `documents`, `sections`.
+ *     No `kind` / `schemaVersion` / `handle`. Used by hand-authored
+ *     `.brandkit.yaml` files and the `scai brand sync pull` capture
+ *     path. Stays valid: the discriminator fields are optional here.
+ *   - **registry-superset** — the richer shape the `@registry`
+ *     `sitecore-recipes.ts` exports use: adds `kind: "brandkit"`,
+ *     `schemaVersion: "1"`, `handle`, `displayName`, and a
+ *     discriminated `documents[]` shape (`url` | `registry-file`)
+ *     with `tags` / `sections` hints per document. The orchestrator
+ *     passes recipes through unchanged from the registry to scai;
+ *     scai's parser accepts the extra fields without stripping them.
+ *
+ * See docs/recipe-sync-architecture.md.
  */
 import { z } from "zod";
 /** A `richArray`-field entry: text plus optional tags and a constraint. */
@@ -24,31 +40,121 @@ export declare const BrandFieldValueSchema: z.ZodUnion<readonly [z.ZodString, z.
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     restrictions: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>]>;
-/** A brand document to ingest. Sitecore fetches the URL server-side. */
-export declare const BrandDocumentSchema: z.ZodObject<{
+/**
+ * Canonical Sitecore AI brand-kit section names — the seven buckets
+ * the EnrichSections pipeline produces. Mirrors
+ * `BRAND_KIT_CANONICAL_SECTIONS` in the registry's recipe definitions.
+ * Exported so callers building recipes have a stable list to bias
+ * `documents[].sections` against.
+ */
+export declare const BRAND_KIT_CANONICAL_SECTIONS: readonly ["Brand Context", "Global Goals", "Tone of Voice", "Glossary and Localization", "Do's and Don'ts", "Grammar Checklists", "Visual Guidelines"];
+export type BrandKitCanonicalSection = (typeof BRAND_KIT_CANONICAL_SECTIONS)[number];
+/**
+ * A brand document referenced by URL. Sitecore's Documents API fetches
+ * the URL server-side and copies the bytes into MMS. The default
+ * variant — what `scai brand sync pull` emits when capturing a live
+ * kit.
+ */
+export declare const BrandUrlDocumentSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"url">;
     url: z.ZodString;
+}, z.core.$strip>;
+/**
+ * A brand document stored alongside the recipe in the registry repo.
+ * The `path` is relative to the recipe file's directory. scai itself
+ * does **not** upload these — the Sitecore Documents API has no
+ * working bytes-upload path (see
+ * `src/brand/documents/upload.ts::LOCAL_UPLOAD_UNSUPPORTED_MESSAGE`),
+ * so the orchestrator (or whoever owns the recipe before scai sees
+ * it) MUST translate `registry-file` entries to `url` entries
+ * pointing at an HTTP-reachable host before invoking `scai brand
+ * sync push`. The seed runner rejects unresolved `registry-file`
+ * documents with a clear hint; this stays in the schema as an
+ * authoring-time shape so registry-side recipes round-trip cleanly.
+ */
+export declare const BrandRegistryFileDocumentSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     summary: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"registry-file">;
+    path: z.ZodString;
 }, z.core.$strip>;
+/**
+ * A brand document to ingest. Two variants — `{ kind: "url", url }` and
+ * `{ kind: "registry-file", path }` — sharing optional `title` /
+ * `summary` / `tags` / `sections` ingestion hints.
+ *
+ * Back-compat: scai-native recipes that pre-date the discriminator wrote
+ * documents as the flat `{ url, title?, summary? }` shape. The
+ * `z.preprocess` step defaults a missing `kind` to `"url"` whenever
+ * `url` is present, so legacy recipes keep parsing without a migration
+ * step. Zod 4's discriminated unions require the discriminator to be
+ * present BEFORE routing, so `.default("url")` inline on the literal
+ * doesn't work — preprocess is the correct seam.
+ */
+export declare const BrandDocumentSchema: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"url">;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"registry-file">;
+    path: z.ZodString;
+}, z.core.$strip>], "kind">>;
 /** The full brand-kit recipe. */
 export declare const BrandKitRecipeSchema: z.ZodObject<{
+    kind: z.ZodOptional<z.ZodLiteral<"brandkit">>;
+    schemaVersion: z.ZodOptional<z.ZodLiteral<"1">>;
+    handle: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     industry: z.ZodOptional<z.ZodString>;
-    documents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    documents: z.ZodDefault<z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        kind: z.ZodLiteral<"url">;
         url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         summary: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        kind: z.ZodLiteral<"registry-file">;
+        path: z.ZodString;
+    }, z.core.$strip>], "kind">>>>;
     sections: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         restrictions: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>]>>>>;
 }, z.core.$strip>;
-/** A validated brand-kit recipe. */
+/** A validated brand-kit recipe (parsed form — defaults materialised). */
 export type BrandKitRecipe = z.infer<typeof BrandKitRecipeSchema>;
+/**
+ * Input alias — the shape an *author* writes. Same as
+ * `BrandKitRecipe` minus the `.default(...)` clauses; useful for
+ * loaders and TypeScript-authored recipe modules.
+ */
+export type BrandKitRecipeInput = z.input<typeof BrandKitRecipeSchema>;
 /** A brand-kit field value (text / name list / rich entries). */
 export type BrandFieldValue = z.infer<typeof BrandFieldValueSchema>;
-/** A brand document reference within a recipe. */
+/** A brand document reference within a recipe (URL or registry-file). */
 export type BrandDocument = z.infer<typeof BrandDocumentSchema>;
+/** A URL-form brand document (post-parse — `kind` is the literal). */
+export type BrandUrlDocument = z.infer<typeof BrandUrlDocumentSchema>;
+/** A registry-file-form brand document (post-parse — `kind` is the literal). */
+export type BrandRegistryFileDocument = z.infer<typeof BrandRegistryFileDocumentSchema>;