@sitecoreai-labs/sitecoreai-cli 0.1.2 → 0.2.0

package/dist/brand/recipe/schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BrandKitRecipeSchema = exports.BrandDocumentSchema = exports.BrandFieldValueSchema = exports.BrandRichEntrySchema = void 0;
+exports.BrandKitRecipeSchema = exports.BrandDocumentSchema = exports.BrandRegistryFileDocumentSchema = exports.BrandUrlDocumentSchema = exports.BRAND_KIT_CANONICAL_SECTIONS = exports.BrandFieldValueSchema = exports.BrandRichEntrySchema = void 0;
 /**
  * `BrandKitRecipe` — the declarative definition of a Sitecore Brand
  * brand kit.
@@ -8,9 +8,26 @@ exports.BrandKitRecipeSchema = exports.BrandDocumentSchema = exports.BrandFieldV
  * 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.
  */
 const zod_1 = require("zod");
+const HANDLE_PATTERN = /^[a-z][a-z0-9-]*@\d+$/;
 /** A `richArray`-field entry: text plus optional tags and a constraint. */
 exports.BrandRichEntrySchema = zod_1.z.object({
     name: zod_1.z.string().min(1).describe("The entry's text."),
@@ -31,29 +48,141 @@ exports.BrandRichEntrySchema = zod_1.z.object({
 exports.BrandFieldValueSchema = zod_1.z
     .union([zod_1.z.string(), zod_1.z.array(zod_1.z.string()), zod_1.z.array(exports.BrandRichEntrySchema)])
     .describe("A text value, a list of names, or a list of rich entries.");
-/** A brand document to ingest. Sitecore fetches the URL server-side. */
-exports.BrandDocumentSchema = zod_1.z.object({
+/**
+ * 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.
+ */
+exports.BRAND_KIT_CANONICAL_SECTIONS = [
+    "Brand Context",
+    "Global Goals",
+    "Tone of Voice",
+    "Glossary and Localization",
+    "Do's and Don'ts",
+    "Grammar Checklists",
+    "Visual Guidelines",
+];
+/**
+ * Optional ingestion hints — `tags` and `sections` — shared by both
+ * document variants. Hoisted into a shape so the URL and registry-file
+ * shapes stay in lockstep without duplicating field-by-field.
+ */
+const DocumentHints = {
+    title: zod_1.z.string().optional().describe('Document title. Defaults to "brand guidelines".'),
+    summary: zod_1.z.string().optional().describe("Short document summary."),
+    tags: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe('Free-form tags surfaced to the EnrichSections pipeline (e.g. "voice").'),
+    sections: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe('Canonical section names to bias ingestion toward (e.g. ["Tone of Voice"]). Prefer values from BRAND_KIT_CANONICAL_SECTIONS.'),
+};
+/**
+ * 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.
+ */
+exports.BrandUrlDocumentSchema = zod_1.z.object({
+    kind: zod_1.z.literal("url"),
     url: zod_1.z
         .string()
         .min(1)
         .describe("Publicly reachable URL of a brand document (PDF). Sitecore fetches it server-side."),
-    title: zod_1.z.string().optional().describe('Document title. Defaults to "brand guidelines".'),
-    summary: zod_1.z.string().optional().describe("Short document summary."),
+    ...DocumentHints,
 });
+/**
+ * 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.
+ */
+exports.BrandRegistryFileDocumentSchema = zod_1.z.object({
+    kind: zod_1.z.literal("registry-file"),
+    path: zod_1.z.string().min(1).describe("Path to the document, relative to the recipe file."),
+    ...DocumentHints,
+});
+/**
+ * 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.
+ */
+exports.BrandDocumentSchema = zod_1.z.preprocess((raw) => {
+    if (raw !== null &&
+        typeof raw === "object" &&
+        !Array.isArray(raw) &&
+        !("kind" in raw) &&
+        "url" in raw) {
+        return { kind: "url", ...raw };
+    }
+    return raw;
+}, zod_1.z.discriminatedUnion("kind", [exports.BrandUrlDocumentSchema, exports.BrandRegistryFileDocumentSchema]));
 /** The full brand-kit recipe. */
 exports.BrandKitRecipeSchema = zod_1.z.object({
+    /**
+     * Registry-superset discriminator — `"brandkit"`. Optional: scai-
+     * native YAML/JSON recipes pre-date this field and don't carry it.
+     * Defaulting in (rather than requiring) keeps the legacy parse
+     * path intact. Registry-authored recipes set this explicitly.
+     */
+    kind: zod_1.z.literal("brandkit").optional(),
+    /**
+     * Registry-superset schema version pin — `"1"`. Optional for the
+     * same back-compat reason as `kind`. When set, the registry's
+     * discriminated-union loader picks this recipe up.
+     */
+    schemaVersion: zod_1.z.literal("1").optional(),
+    /**
+     * Stable handle of the form `<kebab-name>@<major>` (e.g.
+     * `acme-brand@1`). Registry-side identifier used to wire brand
+     * kits to themes. Optional in scai because scai-native recipes
+     * identify kits by `name`, not handle.
+     */
+    handle: zod_1.z
+        .string()
+        .regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>` (e.g. acme-brand@1)",
+    })
+        .optional()
+        .describe("Stable handle `<kebab-name>@<major>`. Required for registry-authored recipes."),
     name: zod_1.z
         .string()
         .min(1)
         .describe("Display name of the brand kit. Identifies the kit when pushing."),
+    /**
+     * Author-facing label, mirrors the registry's superset. When absent
+     * the registry's loader treats it as identical to `name`; scai's
+     * `apply()` likewise ignores it (the API has no separate display
+     * name slot beyond `name`).
+     */
+    displayName: zod_1.z.string().min(1).optional().describe("Author-facing label; defaults to `name`."),
     description: zod_1.z.string().optional().describe("Human description of the kit."),
     industry: zod_1.z.string().optional().describe('Industry label, e.g. "retail" or "developer-tools".'),
     documents: zod_1.z
         .array(exports.BrandDocumentSchema)
         .default([])
-        .describe("Brand documents to ingest. On push, when the kit has no populated sections, each is uploaded and run through the ingestion + enrichment pipelines."),
+        .describe("Brand documents to ingest. On push, when the kit has no populated sections, each is uploaded and run through the ingestion + enrichment pipelines. `registry-file` variants must be translated to `url` variants before scai sees the recipe — the Sitecore Documents API has no working bytes-upload path."),
     sections: zod_1.z
         .record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), exports.BrandFieldValueSchema))
         .default({})
-        .describe("Desired field values, keyed by section name then field name. Sections and fields are created by enrichment; push converges their values."),
+        .describe("Desired field values, keyed by section name then field name. Prefer canonical names from BRAND_KIT_CANONICAL_SECTIONS for the outer key. Sections and fields are created by enrichment; push converges their values."),
 });

package/dist/brand/seed.d.ts

@@ -2,6 +2,7 @@ import type { BrandApiClientOptions } from "./api/client";
 import { type BrandKitSectionSummary } from "./kits/sections";
 import { type UploadDocumentSource, type UploadedDocument } from "./documents/upload";
 import type { BrandKitSummary } from "./kits/list";
+import type { BrandDocument } from "./recipe/schema";
 /**
  * Stage labels emitted via `onProgress`. Useful for callers that
  * surface progress (CLI streaming output, MCP progress events).
@@ -30,12 +31,15 @@ export interface SeedBrandKitOptions {
     /**
      * Multiple source documents — uploaded before a single ingestion +
      * enrichment pass. Takes precedence over `source` when non-empty.
+     * Accepts the recipe-shaped `BrandDocument` union (URL or
+     * registry-file). The seed runner rejects `registry-file` entries
+     * with `INPUT_INVALID` and a clear hint — see the
+     * `LOCAL_UPLOAD_UNSUPPORTED_MESSAGE` rationale in
+     * `documents/upload.ts` for why bytes uploads don't work end-to-end.
+     * Callers (orchestrator's `brandkit_deploy` handler) must translate
+     * registry-file paths to public URLs before invoking scai.
      */
-    documents?: {
-        url: string;
-        title?: string;
-        summary?: string;
-    }[];
+    documents?: BrandDocument[];
     /** Optional kit metadata. */
     description?: string;
     industry?: string;

package/dist/brand/seed.js

@@ -49,12 +49,37 @@ const seedBrandKit = async (options) => {
     const kit = await (0, create_1.createBrandKit)(createInput);
     emit({ stage: "createKit", message: `Created kit ${kit.id}` });
     // 2. UPLOAD doc(s) — one or many, before a single ingestion pass.
+    //
+    // The `documents` list is the recipe-shaped discriminated union.
+    // `registry-file` entries arrive unresolved (path relative to the
+    // recipe file) and CANNOT be uploaded as bytes — the Sitecore
+    // Documents API has no working local-upload path (verified
+    // 2026-05-15; see documents/upload.ts). The caller (orchestrator's
+    // `brandkit_deploy` handler) must translate them to URL entries
+    // first. Failing fast here — with the path in the hint — beats
+    // a confusing 400 from `uploadDocument` minutes later.
+    if (options.documents) {
+        for (const doc of options.documents) {
+            if (doc.kind === "registry-file") {
+                throw (0, errors_1.createScaiError)(`Brand document "${doc.path}" is a registry-file path; scai cannot upload local bytes.`, "INPUT_INVALID", {
+                    hint: 'Host the file at an HTTPS URL Sitecore\'s edge can reach (S3, GitHub raw, a CDN) and pass it as a `{ kind: "url", url }` document. The Sitecore Documents API rejects local-file uploads — translation has to happen upstream of scai.',
+                });
+            }
+        }
+    }
     const uploadList = options.documents && options.documents.length > 0
-        ? options.documents.map((doc) => ({
-            source: { url: doc.url },
-            title: doc.title,
-            summary: doc.summary,
-        }))
+        ? options.documents.map((doc) => {
+            // After the registry-file guard above, every doc is a URL
+            // variant; the narrow keeps the TS surface clean.
+            if (doc.kind !== "url") {
+                throw (0, errors_1.createScaiError)("Unreachable: non-URL document survived the registry-file guard.", "INPUT_INVALID");
+            }
+            return {
+                source: { url: doc.url },
+                title: doc.title,
+                summary: doc.summary,
+            };
+        })
         : options.source
             ? [
                 {

package/dist/brief/recipe/schema.js

@@ -69,7 +69,10 @@ exports.BudgetFieldSchema = zod_1.z
     type: zod_1.z.literal("Budget").describe("Discriminator — a budget/currency field."),
     ...briefFieldBaseShape,
     currencies: zod_1.z
-        .array(zod_1.z.string())
+        .array(zod_1.z
+        .string()
+        .length(3)
+        .regex(/^[A-Z]{3}$/, "ISO-4217 currency code must be 3 uppercase letters (e.g. `USD`)."))
         .describe('ISO-4217 currency codes the field accepts, e.g. ["USD", "EUR"].'),
 })
     .describe("A budget/currency field.");

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

@@ -9,6 +9,21 @@
  * model reads it. See docs/recipe-sync-architecture.md.
  */
 import { z } from "zod";
+/**
+ * Server enum values **confirmed by observation** in HAR captures of the
+ * Sitecore Content Operations UI driving the Orchestrate API. Other
+ * values likely exist in the server's enum — `recipe pull` from a tenant
+ * with a live `IN_PROGRESS` campaign must still round-trip cleanly — so
+ * the schema accepts the known set as a strong hint and falls back to
+ * `z.string()`. JSON Schema renders this as `anyOf: [{ enum: [...] }, { type:
+ * "string" }]`, which the model reads as "prefer one of these values; new
+ * uppercase enums are acceptable too".
+ *
+ * Update the lists when more values are observed; the trailing
+ * `z.string()` keeps the schema permissive in the meantime.
+ */
+export declare const KNOWN_CAMPAIGN_STATUSES: readonly ["NOT_STARTED"];
+export declare const KNOWN_CAMPAIGN_FUNNEL_STAGES: readonly ["TOP"];
 /**
  * A task — the leaf work item of a campaign. Owned by a deliverable.
  * Identified within its deliverable by `name`; server ids are dropped
@@ -16,7 +31,9 @@ import { z } from "zod";
  */
 export declare const CampaignTaskSchema: z.ZodObject<{
     name: z.ZodString;
-    status: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        NOT_STARTED: "NOT_STARTED";
+    }>, z.ZodString]>>;
     dueDate: z.ZodOptional<z.ZodString>;
     priority: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
@@ -29,14 +46,20 @@ export declare const CampaignTaskSchema: z.ZodObject<{
  */
 export declare const CampaignDeliverableSchema: z.ZodObject<{
     name: z.ZodString;
-    status: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        NOT_STARTED: "NOT_STARTED";
+    }>, z.ZodString]>>;
     dueDate: z.ZodOptional<z.ZodString>;
-    funnelStage: z.ZodOptional<z.ZodString>;
+    funnelStage: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        TOP: "TOP";
+    }>, z.ZodString]>>;
     funnelTactics: z.ZodDefault<z.ZodArray<z.ZodString>>;
     labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
     tasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-        status: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            NOT_STARTED: "NOT_STARTED";
+        }>, z.ZodString]>>;
         dueDate: z.ZodOptional<z.ZodString>;
         priority: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
@@ -48,21 +71,29 @@ export declare const CampaignDeliverableSchema: z.ZodObject<{
 export declare const CampaignRecipeSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
-    status: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        NOT_STARTED: "NOT_STARTED";
+    }>, z.ZodString]>>;
     startDate: z.ZodOptional<z.ZodString>;
     dueDate: z.ZodOptional<z.ZodString>;
     brandKitId: z.ZodOptional<z.ZodString>;
     labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
     deliverables: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-        status: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            NOT_STARTED: "NOT_STARTED";
+        }>, z.ZodString]>>;
         dueDate: z.ZodOptional<z.ZodString>;
-        funnelStage: z.ZodOptional<z.ZodString>;
+        funnelStage: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            TOP: "TOP";
+        }>, z.ZodString]>>;
         funnelTactics: z.ZodDefault<z.ZodArray<z.ZodString>>;
         labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
         tasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
-            status: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+                NOT_STARTED: "NOT_STARTED";
+            }>, z.ZodString]>>;
             dueDate: z.ZodOptional<z.ZodString>;
             priority: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;

package/dist/campaigns/recipe/schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CampaignRecipeSchema = exports.CampaignDeliverableSchema = exports.CampaignTaskSchema = void 0;
+exports.CampaignRecipeSchema = exports.CampaignDeliverableSchema = exports.CampaignTaskSchema = exports.KNOWN_CAMPAIGN_FUNNEL_STAGES = exports.KNOWN_CAMPAIGN_STATUSES = void 0;
 /**
  * `CampaignRecipe` — the declarative definition of a Sitecore
  * Orchestrate campaign (a `project`, with its nested deliverables and
@@ -12,6 +12,33 @@ exports.CampaignRecipeSchema = exports.CampaignDeliverableSchema = exports.Campa
  * model reads it. See docs/recipe-sync-architecture.md.
  */
 const zod_1 = require("zod");
+/**
+ * ISO-8601 date-or-datetime — accepts `2026-05-26`, `2026-05-26T15:00:00Z`,
+ * or `2026-05-26T15:00:00.123+02:00`. Less strict than `z.string().datetime()`
+ * because the campaign API returns date-only values for some fields.
+ */
+const Iso8601 = zod_1.z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2}))?$/, {
+    message: "must be an ISO-8601 date or datetime (e.g. `2026-05-26` or `2026-05-26T15:00:00Z`)",
+});
+/**
+ * Server enum values **confirmed by observation** in HAR captures of the
+ * Sitecore Content Operations UI driving the Orchestrate API. Other
+ * values likely exist in the server's enum — `recipe pull` from a tenant
+ * with a live `IN_PROGRESS` campaign must still round-trip cleanly — so
+ * the schema accepts the known set as a strong hint and falls back to
+ * `z.string()`. JSON Schema renders this as `anyOf: [{ enum: [...] }, { type:
+ * "string" }]`, which the model reads as "prefer one of these values; new
+ * uppercase enums are acceptable too".
+ *
+ * Update the lists when more values are observed; the trailing
+ * `z.string()` keeps the schema permissive in the meantime.
+ */
+exports.KNOWN_CAMPAIGN_STATUSES = ["NOT_STARTED"];
+exports.KNOWN_CAMPAIGN_FUNNEL_STAGES = ["TOP"];
+const CampaignStatusSchema = zod_1.z.union([zod_1.z.enum(exports.KNOWN_CAMPAIGN_STATUSES), zod_1.z.string()]);
+const CampaignFunnelStageSchema = zod_1.z.union([zod_1.z.enum(exports.KNOWN_CAMPAIGN_FUNNEL_STAGES), zod_1.z.string()]);
 /**
  * A task — the leaf work item of a campaign. Owned by a deliverable.
  * Identified within its deliverable by `name`; server ids are dropped
@@ -19,9 +46,12 @@ const zod_1 = require("zod");
  */
 exports.CampaignTaskSchema = zod_1.z.object({
     name: zod_1.z.string().min(1).describe("Task name. Identifies the task within its deliverable."),
-    status: zod_1.z.string().optional().describe('Task status — a server enum, e.g. "NOT_STARTED".'),
-    dueDate: zod_1.z.string().optional().describe("Task due date (ISO-8601)."),
-    priority: zod_1.z.string().optional().describe("Task priority — a server enum."),
+    status: CampaignStatusSchema.optional().describe('Task status — a server enum. Confirmed values: "NOT_STARTED". Other UPPER_SNAKE values may exist on the server; the schema accepts them but agents should prefer the confirmed set.'),
+    dueDate: Iso8601.optional().describe("Task due date (ISO-8601 date or datetime)."),
+    priority: zod_1.z
+        .string()
+        .optional()
+        .describe("Task priority — a server enum. No values have been observed yet; convention follows project-management norms (e.g. UPPERCASE strings). Schema is `string` until the enum set is captured."),
     description: zod_1.z.string().optional().describe("Task description. HTML."),
     assignee: zod_1.z.string().optional().describe('Assignee — an Auth0 user subject (e.g. "auth0|...").'),
     labels: zod_1.z.array(zod_1.z.string()).default([]).describe("Free-form labels on the task."),
@@ -35,9 +65,9 @@ exports.CampaignDeliverableSchema = zod_1.z.object({
         .string()
         .min(1)
         .describe("Deliverable name. Identifies the deliverable within its campaign."),
-    status: zod_1.z.string().optional().describe('Deliverable status — a server enum, e.g. "NOT_STARTED".'),
-    dueDate: zod_1.z.string().optional().describe("Deliverable due date (ISO-8601)."),
-    funnelStage: zod_1.z.string().optional().describe('Funnel stage — a server enum, e.g. "TOP".'),
+    status: CampaignStatusSchema.optional().describe('Deliverable status — a server enum. Confirmed values: "NOT_STARTED". Other UPPER_SNAKE values may exist on the server; the schema accepts them but agents should prefer the confirmed set.'),
+    dueDate: Iso8601.optional().describe("Deliverable due date (ISO-8601 date or datetime)."),
+    funnelStage: CampaignFunnelStageSchema.optional().describe('Funnel stage — a server enum. Confirmed values: "TOP". Other values likely exist (e.g. middle / bottom of funnel); the schema accepts them but agents should prefer the confirmed set.'),
     funnelTactics: zod_1.z.array(zod_1.z.string()).default([]).describe("Funnel tactics for the deliverable."),
     labels: zod_1.z.array(zod_1.z.string()).default([]).describe("Free-form labels on the deliverable."),
     tasks: zod_1.z
@@ -52,9 +82,9 @@ exports.CampaignRecipeSchema = zod_1.z.object({
         .min(1)
         .describe("Display name of the campaign (project). Identifies the campaign when pushing."),
     description: zod_1.z.string().optional().describe("Human description of the campaign."),
-    status: zod_1.z.string().optional().describe('Campaign status — a server enum, e.g. "NOT_STARTED".'),
-    startDate: zod_1.z.string().optional().describe("Campaign start date (ISO-8601)."),
-    dueDate: zod_1.z.string().optional().describe("Campaign due date (ISO-8601)."),
+    status: CampaignStatusSchema.optional().describe('Campaign status — a server enum. Confirmed values: "NOT_STARTED". Other UPPER_SNAKE values may exist on the server; the schema accepts them but agents should prefer the confirmed set.'),
+    startDate: Iso8601.optional().describe("Campaign start date (ISO-8601 date or datetime)."),
+    dueDate: Iso8601.optional().describe("Campaign due date (ISO-8601 date or datetime)."),
     brandKitId: zod_1.z
         .string()
         .optional()

package/dist/commands/agents/sync.js

@@ -91,7 +91,7 @@ const createDiffCommand = () => {
         const logger = (0, cli_tasks_1.toLogger)(options);
         const kind = resolveKind(options.kind);
         const ctx = buildContext(options, logger);
-        const recipe = (0, sync_1.loadRecipe)(options.file ?? "", kind.schema);
+        const recipe = await (0, sync_1.loadRecipe)(options.file ?? "", kind.schema);
         const plan = await (0, sync_1.syncDiff)(kind, recipe, { kind: kind.name, id: recipeName(recipe) }, ctx);
         printPlan(logger, plan);
     });
@@ -110,7 +110,7 @@ const createPushCommand = () => {
         const logger = (0, cli_tasks_1.toLogger)(options);
         const kind = resolveKind(options.kind);
         const ctx = buildContext(options, logger);
-        const recipe = (0, sync_1.loadRecipe)(options.file ?? "", kind.schema);
+        const recipe = await (0, sync_1.loadRecipe)(options.file ?? "", kind.schema);
         const mode = options.allowWrite ? "apply" : "what-if";
         const outcome = await (0, sync_1.syncPush)(kind, recipe, { kind: kind.name, id: recipeName(recipe) }, ctx, {
             mode,

package/dist/commands/brand/seed.js

@@ -70,7 +70,7 @@ const seedFromFile = async (options, logger) => {
         configPath,
         logger,
     };
-    const recipe = (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.brandKitKind.schema);
+    const recipe = await (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.brandKitKind.schema);
     const outcome = await (0, sync_1.syncPush)(recipe_1.brandKitKind, recipe, { kind: recipe_1.brandKitKind.name, id: recipe.name }, ctx, { mode: "apply", prune: false });
     if (options.format === "json") {
         process.stdout.write(JSON.stringify({ recipe: recipe.name, plan: outcome.plan, result: outcome.result }, null, 2) +

package/dist/commands/brand/sync.js

@@ -77,7 +77,7 @@ const createDiffCommand = () => {
     command.action(async (options) => {
         const logger = (0, cli_tasks_1.toLogger)(options);
         const ctx = buildContext(options, logger);
-        const recipe = (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.brandKitKind.schema);
+        const recipe = await (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.brandKitKind.schema);
         const plan = await (0, sync_1.syncDiff)(recipe_1.brandKitKind, recipe, { kind: recipe_1.brandKitKind.name, id: recipe.name }, ctx);
         printPlan(logger, plan);
         if (hasPaidPipeline(plan)) {
@@ -98,7 +98,7 @@ const createPushCommand = () => {
     command.action(async (options) => {
         const logger = (0, cli_tasks_1.toLogger)(options);
         const ctx = buildContext(options, logger);
-        const recipe = (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.brandKitKind.schema);
+        const recipe = await (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.brandKitKind.schema);
         const mode = options.allowWrite ? "apply" : "what-if";
         const outcome = await (0, sync_1.syncPush)(recipe_1.brandKitKind, recipe, { kind: recipe_1.brandKitKind.name, id: recipe.name }, ctx, { mode, prune: options.prune });
         printPlan(logger, outcome.plan);

package/dist/commands/brief/sync.js

@@ -76,7 +76,7 @@ const createDiffCommand = () => {
     command.action(async (options) => {
         const logger = (0, cli_tasks_1.toLogger)(options);
         const ctx = buildContext(options, logger);
-        const recipe = (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.briefTypeKind.schema);
+        const recipe = await (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.briefTypeKind.schema);
         const plan = await (0, sync_1.syncDiff)(recipe_1.briefTypeKind, recipe, { kind: recipe_1.briefTypeKind.name, id: recipe.name }, ctx);
         printPlan(logger, plan);
     });
@@ -94,7 +94,7 @@ const createPushCommand = () => {
     command.action(async (options) => {
         const logger = (0, cli_tasks_1.toLogger)(options);
         const ctx = buildContext(options, logger);
-        const recipe = (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.briefTypeKind.schema);
+        const recipe = await (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.briefTypeKind.schema);
         const mode = options.allowWrite ? "apply" : "what-if";
         const outcome = await (0, sync_1.syncPush)(recipe_1.briefTypeKind, recipe, { kind: recipe_1.briefTypeKind.name, id: recipe.name }, ctx, { mode, prune: options.prune });
         printPlan(logger, outcome.plan);

package/dist/commands/campaign/sync.js

@@ -76,7 +76,7 @@ const createDiffCommand = () => {
     command.action(async (options) => {
         const logger = (0, cli_tasks_1.toLogger)(options);
         const ctx = buildContext(options, logger);
-        const recipe = (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.campaignKind.schema);
+        const recipe = await (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.campaignKind.schema);
         const plan = await (0, sync_1.syncDiff)(recipe_1.campaignKind, recipe, { kind: recipe_1.campaignKind.name, id: recipe.name }, ctx);
         printPlan(logger, plan);
     });
@@ -94,7 +94,7 @@ const createPushCommand = () => {
     command.action(async (options) => {
         const logger = (0, cli_tasks_1.toLogger)(options);
         const ctx = buildContext(options, logger);
-        const recipe = (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.campaignKind.schema);
+        const recipe = await (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.campaignKind.schema);
         const mode = options.allowWrite ? "apply" : "what-if";
         const outcome = await (0, sync_1.syncPush)(recipe_1.campaignKind, recipe, { kind: recipe_1.campaignKind.name, id: recipe.name }, ctx, { mode, prune: options.prune });
         printPlan(logger, outcome.plan);

package/dist/recipe/compile/design-parameters-template.js

@@ -6,6 +6,7 @@ const operations_1 = require("../ir/operations");
 const policy_1 = require("../runtime/policy");
 const sitecore_templates_1 = require("../ir/sitecore-templates");
 const recipe_1 = require("../schema/recipe");
+const component_section_1 = require("./component-section");
 const shared_1 = require("./shared");
 /**
  * Compile a standalone `DesignParametersTemplateRecipe` to an Operation IR.
@@ -22,9 +23,10 @@ function compileDesignParametersTemplateRecipe(input, context, emittedFolders =
     const policy = (0, policy_1.defaultPolicyForRecipe)(recipe.kind);
     const icon = recipe.icon ?? sitecore_templates_1.DEFAULT_ICON;
     const site = (0, shared_1.siteOf)(context);
-    (0, shared_1.ensureSectionFolder)(operations, context, recipe.section, emittedFolders);
-    const bucketRefKey = (0, shared_1.ensurePresentationDesignParametersBucket)(operations, context, recipe.section, emittedFolders);
-    const parentPath = (0, shared_1.resolvePresentationDesignParametersBucketPath)(context, recipe.section);
+    const sectionName = (0, component_section_1.resolveSectionRecipe)(recipe.handle, recipe.section.handle, context.sectionsByHandle).name;
+    (0, shared_1.ensureSectionFolder)(operations, context, sectionName, emittedFolders);
+    const bucketRefKey = (0, shared_1.ensurePresentationDesignParametersBucket)(operations, context, sectionName, emittedFolders);
+    const parentPath = (0, shared_1.resolvePresentationDesignParametersBucketPath)(context, sectionName);
     // The standalone parameters template lands at the same identity
     // (designParametersTemplateId) as inline-hoisted ones — keeps re-pushes
     // idempotent if a recipe migrates from inline to standalone.

package/dist/recipe/compile/enumeration.js

@@ -118,17 +118,12 @@ function compileEnumerationRecipe(input, context, emittedFolders = new Set()) {
         kind: "ref-path",
         value: context.enumerationsRoot,
     };
-    const folder = recipe.location?.folder;
-    if (folder) {
-        const folderSegments = folder
-            .split("/")
-            .map((s) => s.trim())
-            .filter(Boolean);
-        if (folderSegments.length === 0) {
-            throw (0, errors_1.createScaiError)(`Recipe '${recipe.handle}' declares location.folder that is empty after trimming.`, "INPUT_INVALID", {
-                hint: "Use a non-empty folder string like 'Theme' or 'Components/Card'.",
-            });
-        }
+    // `recipe.location.folder` is normalized to `string[]` by the schema
+    // (`FolderPath` in schema/recipe.ts) — both `"Theme/Color"` and
+    // `["Theme", "Color"]` input shapes land here as `["Theme", "Color"]`,
+    // already trimmed and non-empty.
+    const folderSegments = recipe.location?.folder;
+    if (folderSegments && folderSegments.length > 0) {
         const cumulativeSegments = [];
         for (const segment of folderSegments) {
             cumulativeSegments.push(segment);

package/dist/recipe/compile/shared.js

@@ -50,9 +50,12 @@ const resolveEnumFolderPath = (context, enumHandle, consumerHandle) => {
             hint: "Add an `EnumerationRecipe` (kind: 'enumeration') with the matching handle to the recipe set, or change the field's `sitecore.enumHandle` to point at an existing one.",
         });
     }
-    const folder = enumRecipe.location?.folder;
-    return folder
-        ? (0, exports.joinPath)((0, exports.joinPath)(context.enumerationsRoot, folder), enumRecipe.name)
+    // `location.folder` is a `string[]` of grouping segments after the
+    // schema's `FolderPath` normalisation — join with `/` here to build
+    // the cumulative path under enumerationsRoot.
+    const folderSegments = enumRecipe.location?.folder;
+    return folderSegments && folderSegments.length > 0
+        ? (0, exports.joinPath)((0, exports.joinPath)(context.enumerationsRoot, folderSegments.join("/")), enumRecipe.name)
         : (0, exports.joinPath)(context.enumerationsRoot, enumRecipe.name);
 };
 exports.resolveEnumFolderPath = resolveEnumFolderPath;
@@ -799,19 +802,16 @@ function encodeStandardValueDefault(raw, type) {
 function resolveFieldSource(field, type, site, recipeHandle, context) {
     const sc = field.sitecore;
     if (sc) {
-        const fields = {
-            sourceTypes: sc.sourceTypes,
-            sourceQuery: sc.sourceQuery,
-            sourceScope: sc.sourceScope,
-            sourceRaw: sc.sourceRaw,
-        };
+        const fields = (0, source_fields_1.augmentSourceToFields)(sc.source);
         if ((0, source_fields_1.sourceFieldsNeedHandleResolution)(fields)) {
+            // `types` is non-empty here because `sourceFieldsNeedHandleResolution`
+            // returned true; the cast is to satisfy the IR's `.min(1)` constraint.
             return {
                 kind: "ref-source-fields",
                 site,
-                sourceTypes: sc.sourceTypes,
-                sourceQuery: sc.sourceQuery,
-                sourceScope: sc.sourceScope,
+                sourceTypes: fields.sourceTypes,
+                sourceQuery: fields.sourceQuery,
+                sourceScope: fields.sourceScope,
             };
         }
         const rendered = (0, source_fields_1.renderSourceFields)(fields, () => {

package/dist/recipe/compile.js

@@ -720,10 +720,10 @@ const buildPlaceholderSettingsAggregate = (recipes, context, site) => {
     // parent ref + path the leaf placeholder item lands under.
     const emittedFolders = new Set();
     const resolveFolderParent = (folder) => {
-        const segments = (folder ?? "")
-            .split("/")
-            .map((segment) => segment.trim())
-            .filter(Boolean);
+        // `folder` is normalised to `string[]` at the schema boundary
+        // (`FolderPath` in schema/recipe.ts) — both array and legacy
+        // slash-string inputs land here as a clean segment list.
+        const segments = folder ?? [];
         let parentPath = root;
         let parentRef = { kind: "ref-path", value: root };
         let cumulative = "";