@sitecoreai-labs/sitecoreai-cli 0.0.4

package/dist/recipe/schema/recipe.js

@@ -0,0 +1,1175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecipeSchema = exports.EnumerationRecipeSchema = exports.EnumerationValueSchema = exports.SiteRecipeSchema = exports.SiteGroupingSchema = exports.SiteTemplateRecipeSchema = exports.SiteTemplateTaxonomyEntrySchema = exports.SiteTemplateDictionaryEntrySchema = exports.PageDesignRecipeSchema = exports.PartialDesignRecipeSchema = exports.LayoutSchema = exports.ComponentPlacementSchema = exports.ContentItemRecipeSchema = exports.ContentFieldValueSchema = exports.SectionDefinitionRecipeSchema = exports.ParametersTemplateRecipeSchema = exports.ContentTemplateRecipeSchema = exports.RecipeMetaSchema = exports.RecipeMetaTaxSchema = exports.ComponentTemplateRecipeSchema = exports.ComponentSectionRecipeSchema = exports.RecipeDatasourceSchema = exports.RenderingDatasourceLocationSchema = exports.PlaceholderDefinitionSchema = exports.RenderingVariantDefinitionSchema = exports.ParamDefinitionSchema = exports.FieldDefinitionSchema = exports.SitecoreFieldAugmentSchema = void 0;
+const zod_1 = require("zod");
+const field_types_1 = require("./field-types");
+/**
+ * Recipe author surface — what users hand-author for one Sitecore template.
+ *
+ * Two recipe kinds:
+ *
+ *   ComponentTemplateRecipe — Has a rendering. Becomes a placeable component
+ *                             on Sitecore pages. Owns its datasource template
+ *                             AND its rendering item.
+ *   ContentTemplateRecipe   — Fields only, no rendering. A data shape
+ *                             referenced by other recipes (Treelist source,
+ *                             child-item pattern, etc.). Not placeable on a
+ *                             page directly.
+ *
+ * Component recipes have three peer buckets reflecting the Sitecore mechanism
+ * each piece of state uses:
+ *
+ *   fields    Datasource fields — per-content, reusable across placements.
+ *   variants  SXA Rendering Variants — items under <Rendering>/Variants,
+ *             selected per-placement via the FieldNames parameter. Maps
+ *             to a CVA component's `variant` axis.
+ *   params    Plain Rendering Parameters — key/value on the placement,
+ *             not shared. Maps to orthogonal CVA modifiers (size, color).
+ *
+ * Both kinds may declare `insertOptions: string[]` — recipe handles whose
+ * templates are allowed as direct children of this datasource item (the
+ * child-item pattern, e.g. accordion → accordion-items).
+ *
+ * **This schema must stay in sync with the registry's working copy at
+ * `<registry>/src/lib/registry/sitecore-recipes.ts`.** Once scai exposes a
+ * typed recipe export, the registry imports from scai and the duplication
+ * goes away.
+ *
+ * The `handle` is load-bearing forever — a uuidv5 derives every item GUID
+ * from it (see `guids.ts`), so renaming a handle creates a *different*
+ * template.
+ */
+const HANDLE_PATTERN = /^[a-z][a-z0-9-]*@[0-9]+$/;
+/**
+ * Sitecore-side override on a field or param. Defaults apply when omitted.
+ *
+ * The picker-scope concept (Sitecore's `Source` field) is expressed as
+ * three composable structured fields rather than a stringly-typed
+ * mini-language. They combine: e.g. `sourceScope` + `sourceTypes` becomes
+ * `DataSource=<path>&IncludeTemplatesForSelection={GUID},...` on emit.
+ *
+ *   sourceTypes   — "picker filter": only items of these recipe handles.
+ *   sourceQuery   — "where to look": a Sitecore Query (e.g. `$site/...`).
+ *   sourceScope   — "where to look": a fixed content-tree path.
+ *   sourceRaw     — escape hatch; verbatim Source string (mutually exclusive
+ *                   with the structured fields).
+ */
+exports.SitecoreFieldAugmentSchema = zod_1.z
+    .object({
+    /** Override the default shape→Sitecore type mapping. */
+    type: field_types_1.SitecoreFieldTypeSchema.optional(),
+    /**
+     * Picker filter: restrict to items conforming to one of these recipe
+     * handles. Compiler resolves each handle to its deterministic template
+     * GUID and emits `IncludeTemplatesForSelection={GUID},{GUID}`.
+     */
+    sourceTypes: zod_1.z.array(zod_1.z.string()).optional(),
+    /**
+     * Where to look: a Sitecore Query (e.g. `$site/*[@@name='Data']`).
+     * Standalone, becomes the entire Source as `query:<query>` (the
+     * shorthand Sitecore evaluates directly for Droplist-style fields).
+     * Combined with `sourceTypes`, becomes `DataSource=query:<query>&...`.
+     */
+    sourceQuery: zod_1.z.string().optional(),
+    /**
+     * Where to look: a fixed Sitecore content-tree path. Emitted as
+     * `DataSource=<path>`, alone or combined with `sourceTypes`.
+     */
+    sourceScope: zod_1.z.string().optional(),
+    /**
+     * Escape hatch: verbatim Source string. Mutually exclusive with the
+     * structured fields above. Use when you need a Source form that
+     * doesn't fit the structured surface (e.g. a bare path Treelist
+     * source like `/sitecore/content/Tags`).
+     */
+    sourceRaw: zod_1.z.string().optional(),
+    /** Author-facing hint surfaced in the CMS. */
+    hint: zod_1.z.string().optional(),
+    /** Required marker (translates to a Sitecore validation rule). */
+    required: zod_1.z.boolean().optional(),
+    /** Default value via the template's __Standard Values item. */
+    defaultValue: zod_1.z.string().optional(),
+    /**
+     * For enum-shaped fields: handle of an `EnumerationRecipe` whose
+     * value items back this field's dropdown. When set, the compiler:
+     *   - emits `Type: Droplink` and `Source: <enum's content path>`
+     *     so the editor enumerates the shared enum's child items;
+     *   - resolves the field's `default` against that enum's value
+     *     items (so `default: "primary"` becomes a GUID reference to
+     *     the corresponding value item).
+     *
+     * Inline enums (no `enumHandle`) get value items emitted as
+     * children of the field-definition itself, scoped to the field.
+     * Use `enumHandle` for shared enums (color schemes, size scales,
+     * spacing scales) so adding/renaming a value updates every
+     * referencing field on the next push.
+     */
+    enumHandle: zod_1.z.string().regex(HANDLE_PATTERN).optional(),
+    /** Ordinal within the section/params block; auto-assigned 100/200/… if omitted. */
+    sortOrder: zod_1.z.number().int().optional(),
+    /**
+     * Section name to group this field under (only meaningful for `fields`,
+     * not `params`/`variants`). Defaults to "Content".
+     */
+    section: zod_1.z.string().optional(),
+})
+    .refine((v) => v.sourceRaw === undefined ||
+    (v.sourceTypes === undefined && v.sourceQuery === undefined && v.sourceScope === undefined), {
+    message: "sourceRaw is mutually exclusive with sourceTypes/sourceQuery/sourceScope",
+    path: ["sourceRaw"],
+});
+exports.FieldDefinitionSchema = zod_1.z.object({
+    name: zod_1.z.string().min(1),
+    shape: field_types_1.FieldShapeSchema,
+    /** Required when `shape === "enum"` — the enumerated values. */
+    values: zod_1.z.array(zod_1.z.string()).optional(),
+    /** For `shape === "reference"`: false = single (Droplink), true = multi (Treelist). */
+    multiple: zod_1.z.boolean().optional(),
+    /** Default value at the abstract layer (also passable via `sitecore.defaultValue`). */
+    default: zod_1.z.string().optional(),
+    sitecore: exports.SitecoreFieldAugmentSchema.optional(),
+});
+exports.ParamDefinitionSchema = zod_1.z.object({
+    name: zod_1.z.string().min(1),
+    shape: field_types_1.FieldShapeSchema,
+    values: zod_1.z.array(zod_1.z.string()).optional(),
+    default: zod_1.z.string().optional(),
+    sitecore: exports.SitecoreFieldAugmentSchema.optional(),
+});
+/**
+ * Phase 1 = Variants Lite: bare Variant item per `name`, no internal
+ * structure. Phase 2+ may add per-variant template-card bindings for full
+ * SXA NVELOPe authoring.
+ *
+ * `name` MUST be PascalCase. The Sitecore Content SDK looks up variants
+ * at render time via case-sensitive `component[name]` indexing on the
+ * component module's named exports, and React convention requires
+ * exported component identifiers to be PascalCase. Using lowercase or
+ * kebab-case here makes the SDK's variant lookup return `undefined` —
+ * Pages then renders the missing-component fallback.
+ *
+ * The `Default` variant is special-cased by the SDK
+ * (`DEFAULT_EXPORT_NAME = "Default"`): when `params.FieldNames` matches
+ * that, the SDK falls through to `component.default || component.Default
+ * || component`, so any of those export shapes work for the default
+ * variant. All OTHER variant names require an exact-match named export
+ * in the component file (e.g. `name: "FullWidth"` → `export function
+ * FullWidth(...)`).
+ */
+const VARIANT_NAME_PATTERN = /^[A-Z][A-Za-z0-9]*$/;
+exports.RenderingVariantDefinitionSchema = zod_1.z.object({
+    name: zod_1.z.string().regex(VARIANT_NAME_PATTERN, {
+        message: "Variant `name` must be PascalCase (e.g. `Default`, `FullWidth`) — the Content SDK uses it as a case-sensitive key into the component module's named exports.",
+    }),
+});
+exports.PlaceholderDefinitionSchema = zod_1.z.object({
+    /** Placeholder key string used in layout XML. */
+    key: zod_1.z.string().min(1),
+    /** Optional restriction: only these rendering handles may drop here. */
+    allowedRenderingHandles: zod_1.z.array(zod_1.z.string()).optional(),
+});
+/**
+ * One entry in the modern semantic-scope datasource locations list.
+ *
+ * Each entry compiles to a single Sitecore Source segment; the compiler
+ * pipe-joins entries into the rendering's `Datasource Location` field so
+ * one rendering can offer authors per-page auto-creation AND a shared
+ * site-level pool of datasources to pick from.
+ *
+ *   - `page` → relative `./Data` (no subfolder) or `./Data/<subfolder>`.
+ *     SXA materialises the `Data` and `<subfolder>` items lazily on first
+ *     datasource creation; no extra CreateItem op is emitted.
+ *   - `site` → absolute `<contentItemsRoot>` (no subfolder) or
+ *     `<contentItemsRoot>/<subfolder>`. With `subfolder` the compiler
+ *     emits a `CreateOnly` `CreateItem` for the data folder so the
+ *     shared pool exists before any rendering tries to read from it.
+ */
+exports.RenderingDatasourceLocationSchema = zod_1.z.discriminatedUnion("scope", [
+    zod_1.z.object({
+        scope: zod_1.z.literal("page"),
+        /** Optional `Data` subfolder; absent = `./Data`. */
+        subfolder: zod_1.z.string().min(1).optional(),
+    }),
+    zod_1.z.object({
+        scope: zod_1.z.literal("site"),
+        /**
+         * Optional subfolder under `<contentItemsRoot>`. When present the
+         * compiler emits a `CreateOnly` folder item so the shared pool is
+         * materialised once per recipe-set.
+         */
+        subfolder: zod_1.z.string().min(1).optional(),
+    }),
+]);
+/**
+ * Top-level datasource block on `ComponentTemplateRecipe`. Captures
+ * everything the rendering needs to know about its datasource:
+ *
+ *   - **template**: optional reference to a separate
+ *     `ContentTemplateRecipe`. When set, the compiler points the
+ *     rendering's Datasource Template field at that template (its
+ *     fields land under `Content Models/<group>/<name>`). When unset,
+ *     the component template itself is the datasource template (legacy
+ *     inline-`fields:` pattern).
+ *   - **autoCreate**: toggles `IsAutoDatasourceRendering=true` in the
+ *     rendering's `OtherProperties` URL-encoded blob. Default true.
+ *   - **openPropertiesAfterAdd**: opens the rendering parameters
+ *     dialog right after the rendering is dropped on a page. Default
+ *     false.
+ *   - **locations**: semantic page/site scope entries — each compiles
+ *     to one Sitecore Source segment (a relative `./Data/...` path or
+ *     an absolute `<contentItemsRoot>/...` path).
+ *   - **query**: raw Sitecore Source segments — included verbatim.
+ *     Use `"query:$site/*[@@name='Data']/CustomPath"`-style entries for
+ *     authors who need a Source shape that doesn't fit the semantic
+ *     `locations` model.
+ *
+ * The compiler pipe-joins `locations` (resolved to paths) and `query`
+ * (verbatim) into the rendering's `Datasource Location` field.
+ */
+exports.RecipeDatasourceSchema = zod_1.z.object({
+    /** Reference to a separate `ContentTemplateRecipe`. */
+    template: zod_1.z
+        .object({
+        handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+            message: "datasource.template.handle must match `<kebab-name>@<major>`",
+        }),
+    })
+        .optional(),
+    /** Sets `IsAutoDatasourceRendering` in `OtherProperties`. Default true. */
+    autoCreate: zod_1.z.boolean().default(true),
+    /** Open the properties dialog after add. Default false. */
+    openPropertiesAfterAdd: zod_1.z.boolean().default(false),
+    /**
+     * Semantic-scope locations that compile to a path-style Sitecore
+     * Source segment each. Empty when only `query` entries are needed.
+     */
+    locations: zod_1.z.array(exports.RenderingDatasourceLocationSchema).default([]),
+    /**
+     * Raw Sitecore Source segments — included verbatim in the joined
+     * `Datasource Location` field. Each entry should be a complete
+     * segment (e.g. `"query:$site/*[@@name='Data']/Custom"` or
+     * `"fast:/sitecore/content/...//*[@@templatename='Foo']"`). Empty
+     * when only `locations` entries are needed.
+     */
+    query: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+});
+/**
+ * Container for a related set of components in the Sitecore tree.
+ * Owns the SIX organisational items that previously emitted implicitly
+ * from `ComponentTemplateRecipe.section: string`:
+ *
+ *   1. Templates section folder        — `<componentsRoot>/<name>/`
+ *   2. Component Folders bucket        — `<componentsRoot>/<name>/Component Folders/`
+ *   3. Presentation Parameters bucket  — `<componentsRoot>/<name>/Presentation Parameters/`
+ *   4. Renderings-tree section folder  — `<renderingsRoot>/<name>/`
+ *   5. Headless Variants section       — `<headlessVariantsRoot>/<name>/`
+ *   6. Available Renderings section    — `<availableRenderingsRoot>/<name>` (built by
+ *                                        the cross-recipe aggregator from every
+ *                                        `ComponentTemplateRecipe` referencing this
+ *                                        section by handle)
+ *
+ * `ComponentTemplateRecipe.section` references this recipe by handle
+ * (`section: { handle: "ui-section@1" }`); the compiler errors at
+ * INPUT_INVALID time if a component points at a section handle no
+ * `ComponentSectionRecipe` in the set defines.
+ */
+exports.ComponentSectionRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("component-section"),
+    schemaVersion: zod_1.z.literal("1"),
+    /** Stable identifier of the form `<kebab-name>@<major>`, e.g. `ui-section@1`. */
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. ui-section@1",
+    }),
+    /** Folder name in the Sitecore tree (e.g. `"ui"`). */
+    name: zod_1.z.string().min(1),
+    /** Author-facing label (defaults to `name`). */
+    displayName: zod_1.z.string().min(1).optional(),
+    description: zod_1.z.string().optional(),
+    /** Defaults to `office/16x16/folder.png`. */
+    icon: zod_1.z.string().optional(),
+    /**
+     * Sort order across sections. Optional. Default = alphabetic by
+     * `name` (a–z). When `sortOrder` is set on any section in the set,
+     * sections with explicit values sort numerically first; ties and
+     * unset entries fall through to alphabetic by name.
+     */
+    sortOrder: zod_1.z.number().int().optional(),
+});
+exports.ComponentTemplateRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("component-template"),
+    schemaVersion: zod_1.z.literal("1"),
+    /** Stable identifier of the form `<kebab-name>@<major>`, e.g. `cta-button@1`. */
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. cta-button@1",
+    }),
+    /** Matches the React export name and the consumer's component-map.ts key. */
+    name: zod_1.z.string().min(1),
+    /** Author-facing label surfaced in the CMS tree and Pages experience. */
+    displayName: zod_1.z.string().min(1),
+    description: zod_1.z.string().optional(),
+    /** Defaults to "Office/32x32/document.png" if omitted. */
+    icon: zod_1.z.string().optional(),
+    /**
+     * Reference to a `ComponentSectionRecipe` whose section folders this
+     * component lives under. The referenced recipe owns the templates
+     * section folder, Component Folders bucket, Presentation Parameters
+     * bucket, renderings-tree section folder, Headless Variants section,
+     * and Available Renderings section item.
+     *
+     * Compile errors INPUT_INVALID if `section.handle` doesn't resolve to
+     * a `ComponentSectionRecipe` in the same recipe set.
+     *
+     * Optional: omit for the flat layout (component + rendering land
+     * directly at `<templatesRoot>` / `<renderingsRoot>` with no section
+     * scaffolding). Registry-driven recipes inject this from
+     * `meta.tax.subgroup` at registry build time.
+     */
+    section: zod_1.z
+        .object({
+        handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+            message: "section.handle must match `<kebab-name>@<major>`",
+        }),
+    })
+        .optional(),
+    fields: zod_1.z.array(exports.FieldDefinitionSchema).default([]),
+    /**
+     * Recipe handles whose templates are allowed as direct children of this
+     * datasource item. Maps to the datasource standard-values item's
+     * `Insert Options` field. Used for the **child-item pattern** — e.g.
+     * an accordion whose accordion-items live as Sitecore children of its
+     * own datasource rather than being referenced via a Treelist.
+     *
+     * Both reference patterns can coexist on the same recipe: declare a
+     * Treelist field with `template:<handle>` source AND list the same
+     * handle in `insertOptions`. Tenants pick which authoring flow they
+     * prefer; the React component handles either resolution path.
+     */
+    insertOptions: zod_1.z.array(zod_1.z.string()).optional(),
+    /**
+     * Datasource configuration — the rendering's data shape, picker
+     * locations, auto-create behaviour, and dialog UX. See
+     * `RecipeDatasourceSchema` for the full surface. Optional: omit
+     * for a rendering with no author-pickable datasource (e.g. a
+     * static component).
+     */
+    datasource: exports.RecipeDatasourceSchema.optional(),
+    /**
+     * Reference to a separate `ParametersTemplateRecipe`. When present,
+     * the rendering's Parameters Template field points at this template
+     * and the compiler does NOT synthesise an anonymous parameters
+     * template from inline `params:`.
+     *
+     * When this is absent and `params:` is non-empty, the compiler
+     * synthesises a section-local Parameters template at
+     * `Components/<section>/Presentation Parameters/<Component> Parameters`.
+     */
+    parameters: zod_1.z
+        .object({
+        handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+            message: "parameters.handle must match `<kebab-name>@<major>`",
+        }),
+    })
+        .optional(),
+    /**
+     * Children declaration — when present, the compiler emits a
+     * Component Folder template at
+     * `Components/<section>/Component Folders/<Component> Folder`. The
+     * folder template's `__Standard Values` carries an Insert Options
+     * field referencing the listed allowed handles, so author-side
+     * "Insert" UX surfaces the right children under each instance.
+     */
+    children: zod_1.z
+        .object({
+        allowedHandles: zod_1.z.array(zod_1.z.string().regex(HANDLE_PATTERN)).min(1),
+    })
+        .optional(),
+    /**
+     * `SectionDefinitionRecipe` handles whose `Available Renderings`
+     * multi-list field should include this rendering's GUID. Drives the
+     * Sitecore Pages "Toolbox" surface — adding to this list registers
+     * the rendering with one or more Available Rendering Section
+     * Definition items.
+     */
+    availableIn: zod_1.z.array(zod_1.z.string().regex(HANDLE_PATTERN)).optional(),
+    variants: zod_1.z.array(exports.RenderingVariantDefinitionSchema).default([]),
+    params: zod_1.z.array(exports.ParamDefinitionSchema).default([]),
+    /**
+     * SXA placeholder keys this rendering can be PLACED INTO — the
+     * allow-list. At apply time scai walks the configured Placeholder
+     * Settings roots, finds items whose `Placeholder Key` field matches
+     * each entry here, and appends this rendering's itemId to their
+     * `Allowed Controls` field. Without this, the rendering exists in
+     * CM but Pages won't offer it in any placeholder picker.
+     *
+     * Example: `["headless-main", "headless-main-{*}", "sxa-footer"]`.
+     *
+     * Distinct from `placeholders` (below), which declares slots THIS
+     * component EXPOSES for child renderings.
+     */
+    placedIn: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    /**
+     * Container slots — placeholders this component DEFINES for child
+     * renderings to drop into. Only meaningful for container components
+     * (e.g. a section wrapper that exposes a `headless-main-{*}` slot).
+     * Each entry carries the placeholder key + an optional restriction
+     * on which rendering handles may be dropped there.
+     *
+     * Distinct from `placedIn` (above), which lists placeholder keys
+     * this rendering can be placed INTO.
+     */
+    placeholders: zod_1.z.array(exports.PlaceholderDefinitionSchema).default([]),
+    /**
+     * First-class option for SXA "renderings with dynamic placeholders".
+     * When true, the compiler sets `IsRenderingsWithDynamicPlaceholders=true`
+     * in the rendering's `OtherProperties` blob — equivalent to passing
+     * `otherProperties: { IsRenderingsWithDynamicPlaceholders: "true" }`
+     * but typed and discoverable. Default false.
+     */
+    dynamicPlaceholders: zod_1.z.boolean().default(false),
+    /**
+     * Free-form key/value pairs encoded into the rendering's
+     * `OtherProperties` URL-encoded shared field. Common keys are
+     * surfaced as dedicated options elsewhere on the recipe
+     * (`autoCreate` → `IsAutoDatasourceRendering`, `dynamicPlaceholders`
+     * → `IsRenderingsWithDynamicPlaceholders`); use this for anything
+     * else that needs to land in OtherProperties without a first-class
+     * option.
+     *
+     * Explicitly-set keys here OVERRIDE the auto-set values from
+     * `autoCreate` / `dynamicPlaceholders` — useful for the rare case
+     * where you need to force a specific value.
+     */
+    otherProperties: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+});
+/**
+ * A content-only template. Has fields but no rendering — exists as a data
+ * shape referenced by other recipes via:
+ *
+ *   - A `reference` field with `sitecore.sourceTypes: ["<handle>"]`
+ *     (related-items pattern: items live wherever, picker filters by template)
+ *   - `insertOptions: ["<handle>"]` on a parent recipe (child-item pattern:
+ *     items live as children of the parent's datasource)
+ *
+ * Not placeable on a page directly. The compiler emits the template,
+ * sections, fields, and standard values — but no rendering item.
+ *
+ * Examples: accordion-item, tabs-item, faq-item — content shapes that
+ * appear as part of a parent component, never standalone.
+ */
+/**
+ * Optional taxonomy metadata, mirroring the registry's `meta.tax.*`
+ * namespace. `group` is the only field the compiler currently consumes
+ * — it drives `Content Models/<group>/<name>` nesting for content
+ * templates. Other fields (`section`, `subgroup`, `tag`) are accepted
+ * so registry → recipe pipelines can pass them through without
+ * losing data, but they're not load-bearing for compilation.
+ */
+exports.RecipeMetaTaxSchema = zod_1.z
+    .object({
+    section: zod_1.z.string().optional(),
+    group: zod_1.z.string().optional(),
+    subgroup: zod_1.z.string().optional(),
+    tag: zod_1.z.string().optional(),
+})
+    .partial()
+    .optional();
+exports.RecipeMetaSchema = zod_1.z
+    .object({
+    tax: exports.RecipeMetaTaxSchema,
+})
+    .partial()
+    .optional();
+exports.ContentTemplateRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("content-template"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. accordion-item@1",
+    }),
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    description: zod_1.z.string().optional(),
+    /**
+     * Optional taxonomy metadata. `meta.tax.group` drives Content Models
+     * folder nesting: when set, the template lands at
+     * `<contentModelsRoot>/<group>/<name>` instead of flat under
+     * `<contentModelsRoot>/<name>`. Other taxonomy fields pass through
+     * unmodified for downstream consumers.
+     */
+    meta: exports.RecipeMetaSchema,
+    fields: zod_1.z.array(exports.FieldDefinitionSchema).default([]),
+    /**
+     * Recipe handles allowed as children of this content template's items.
+     * Enables nested child-item patterns (e.g. a section content template
+     * that allows item content templates underneath).
+     */
+    insertOptions: zod_1.z.array(zod_1.z.string()).optional(),
+});
+/**
+ * A standalone Parameters Template — a Sitecore template item that holds
+ * rendering-parameter fields, referenced from one or more
+ * `ComponentTemplateRecipe.parameters`. Lands at
+ * `<componentsRoot>/<section>/Presentation Parameters/<name>`.
+ *
+ * Authoring shape mirrors a stripped-down ContentTemplateRecipe — the
+ * compiler emits a Template + Section + Field children + standard
+ * values, parented under the section's "Presentation Parameters"
+ * folder. Distinct from inline `params:` (which the compiler hoists
+ * into an anonymous parameters template owned by one component);
+ * standalone parameters templates are reusable across components.
+ *
+ * Identity: `paramsTemplateId(handle)` derives the deterministic GUID.
+ * Same identity scheme as the inline-hoisted variant — the seed is the
+ * recipe handle, and the namespace is `NAMESPACE_TEMPLATE`. The seed
+ * suffix is `::params`, identical between inline and standalone forms,
+ * which keeps re-pushes idempotent if a recipe migrates from inline to
+ * standalone (the GUID stays the same).
+ */
+exports.ParametersTemplateRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("parameters-template"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. cta-button-params@1",
+    }),
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    description: zod_1.z.string().optional(),
+    /** Defaults to "Office/32x32/document.png" if omitted. */
+    icon: zod_1.z.string().optional(),
+    /**
+     * Section name under which this parameters template lands —
+     * `Components/<section>/Presentation Parameters/<name>`. Required:
+     * presentation parameters are organised per-section by convention.
+     */
+    section: zod_1.z.string().min(1),
+    params: zod_1.z.array(exports.ParamDefinitionSchema).default([]),
+});
+/**
+ * Available Rendering Section Definition — declares an SXA section
+ * definition item that the registry uses as the target for
+ * `availableIn` bindings. Each section definition holds an `Available
+ * Renderings` multi-list field whose pipe-separated GUID list controls
+ * which renderings appear in the section's toolbox group.
+ *
+ * The section definition typically lives in the content tree under
+ * `/sitecore/content/<tenant>/<site>/Presentation/Available Renderings/<Section>`,
+ * but exact path is recipe-supplied via `sitePath` so the same recipe
+ * shape works across SXA Headless and classic SXA layouts.
+ *
+ * Identity: section definitions are referenced by deterministic GUID
+ * via `sectionDefinitionId(handle)`. The compiler currently does not
+ * emit CreateItem ops for section definitions (they're assumed to
+ * pre-exist on the tenant — they're SXA-shipped scaffolding). The
+ * recipe surface accepts them so cross-recipe validation of
+ * `availableIn` references can resolve.
+ */
+exports.SectionDefinitionRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("section-definition"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. showcase-section@1",
+    }),
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().optional(),
+    description: zod_1.z.string().optional(),
+    /**
+     * Sitecore content-tree path of the section definition item
+     * (e.g. `/sitecore/content/<tenant>/<site>/Presentation/Available
+     * Renderings/<Section>`). The compiler uses this as the lookup target
+     * when emitting `AppendToMultiList` ops for the section's
+     * `Available Renderings` field — the executor resolves the path to
+     * a Sitecore itemId at apply time.
+     */
+    sitePath: zod_1.z.string().min(1),
+});
+/**
+ * A single field value on a `ContentItemRecipe`. Tagged on `shape` so the
+ * Phase 4 compiler can dispatch each value to the right Sitecore wire
+ * encoder (image XML, link XML, pipe-separated GUID list, …) without
+ * cross-recipe shape lookup at parse time.
+ *
+ * Shapes mirror `FieldShape` from `field-types.ts`, with `link` split
+ * into `link-external` / `link-internal` and `reference` lifted to
+ * always-array (`refs: string[]`) — both differences reflect that the
+ * value-level form encodes the stored representation, not the abstract
+ * field shape on the template.
+ *
+ * Cross-recipe handle references (`link-internal.ref`, `reference.refs`)
+ * resolve via the same `templateId(handle)` / `contentItemId(handle)`
+ * derivation the rest of the recipe surface uses.
+ */
+exports.ContentFieldValueSchema = zod_1.z.discriminatedUnion("shape", [
+    zod_1.z.object({ shape: zod_1.z.literal("text"), value: zod_1.z.string() }),
+    zod_1.z.object({ shape: zod_1.z.literal("richText"), value: zod_1.z.string() }),
+    zod_1.z.object({ shape: zod_1.z.literal("boolean"), value: zod_1.z.boolean() }),
+    zod_1.z.object({ shape: zod_1.z.literal("number"), value: zod_1.z.number() }),
+    zod_1.z.object({ shape: zod_1.z.literal("integer"), value: zod_1.z.number().int() }),
+    /** ISO 8601 date (`YYYY-MM-DD`) — compiler converts to Sitecore's wire format. */
+    zod_1.z.object({ shape: zod_1.z.literal("date"), value: zod_1.z.string() }),
+    /** ISO 8601 datetime (`YYYY-MM-DDTHH:mm:ssZ`). */
+    zod_1.z.object({ shape: zod_1.z.literal("datetime"), value: zod_1.z.string() }),
+    /** One of the enum's declared values, by name. */
+    zod_1.z.object({ shape: zod_1.z.literal("enum"), value: zod_1.z.string() }),
+    zod_1.z.object({
+        shape: zod_1.z.literal("image"),
+        /** Sitecore media-library path. Compiler emits the image XML form. */
+        mediaPath: zod_1.z.string().min(1),
+        alt: zod_1.z.string().optional(),
+        width: zod_1.z.number().int().positive().optional(),
+        height: zod_1.z.number().int().positive().optional(),
+    }),
+    zod_1.z.object({
+        shape: zod_1.z.literal("link-external"),
+        href: zod_1.z.string().min(1),
+        text: zod_1.z.string().optional(),
+        target: zod_1.z.string().optional(),
+        title: zod_1.z.string().optional(),
+    }),
+    zod_1.z.object({
+        shape: zod_1.z.literal("link-internal"),
+        /** Recipe handle (page or content item). Compiler resolves to a GUID. */
+        ref: zod_1.z.string().min(1),
+        text: zod_1.z.string().optional(),
+        target: zod_1.z.string().optional(),
+    }),
+    zod_1.z.object({
+        shape: zod_1.z.literal("reference"),
+        /**
+         * One or more recipe handles. Always an array, even for single-ref
+         * fields — the value-level shape doesn't depend on whether the
+         * template field is `multiple: true`. Compiler emits one GUID
+         * (single-ref fields) or pipe-separated GUIDs (Treelist/Multilist).
+         */
+        refs: zod_1.z.array(zod_1.z.string().min(1)),
+    }),
+]);
+/**
+ * A concrete content item — one Sitecore item conforming to a content
+ * template, populated with the recipe's field values. The Phase 4
+ * companion to `ContentTemplateRecipe`: templates declare shape, content
+ * items declare instance.
+ *
+ * Used as the `kind: "shared"` datasource target for `PartialDesignRecipe`
+ * and `PageDesignRecipe` placements (e.g. `site-logo-content@1`,
+ * `primary-nav-content@1`). The handle is load-bearing — `contentItemId`
+ * derives the deterministic Sitecore GUID from it.
+ *
+ * Field-shape ↔ template-shape validation is deferred to the Phase 4
+ * compiler (it requires cross-recipe lookup; Zod can't enforce it alone).
+ */
+exports.ContentItemRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("content-item"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. site-logo-content@1",
+    }),
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    description: zod_1.z.string().optional(),
+    /**
+     * Handle of the content (or component) template this item conforms to.
+     * Compiler resolves via `templateId(handle)` to set the item's
+     * Template-Of GUID.
+     */
+    templateType: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "templateType must match `<kebab-name>@<major>`, e.g. nav-link@1",
+    }),
+    /** Field values keyed by field name on the template. */
+    fields: zod_1.z.record(zod_1.z.string(), exports.ContentFieldValueSchema).default({}),
+});
+/**
+ * One rendering placed into a placeholder, with its variant, parameters,
+ * and datasource binding. The Phase 4 compiler emits each ComponentPlacement
+ * as one `<r>` element in Sitecore's layout XML.
+ *
+ * The single shape used by anything that holds layout — `PartialDesignRecipe`,
+ * `PageDesignRecipe`, and (when Phase 3 lands) `PageRecipe`. The
+ * `componentHandle` resolves to a `ComponentTemplateRecipe`'s rendering
+ * GUID via `renderingId(handle)`.
+ *
+ * `datasourceRef` distinguishes how the rendering gets its content:
+ *
+ *   shared  — points at a `ContentItemRecipe` by handle (catalog-shipped
+ *             reusable content like `site-logo-content@1`).
+ *   scoped  — page-local content at `<page>/<slot>`. Used by `PageRecipe`;
+ *             `PartialDesignRecipe` and `PageDesignRecipe` typically don't
+ *             use this kind, but the shared schema accepts it.
+ *   none    — config-driven rendering with no datasource (rare).
+ */
+exports.ComponentPlacementSchema = zod_1.z.object({
+    /** Handle of a `ComponentTemplateRecipe`. */
+    componentHandle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "componentHandle must match `<kebab-name>@<major>`",
+    }),
+    /** SXA Rendering Variant name. Defaults to the component's first variant. */
+    variant: zod_1.z.string().optional(),
+    /** Rendering Parameters (URL-encoded into the placement's params blob). */
+    params: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+    /** How the rendering's content is bound. Omit for `kind: "none"` semantics. */
+    datasourceRef: zod_1.z
+        .discriminatedUnion("kind", [
+        zod_1.z.object({
+            kind: zod_1.z.literal("shared"),
+            /** Handle of a `ContentItemRecipe`. */
+            handle: zod_1.z.string().regex(HANDLE_PATTERN),
+        }),
+        zod_1.z.object({
+            kind: zod_1.z.literal("scoped"),
+            /** Slot path within the host item, e.g. `/main/0`. */
+            slot: zod_1.z.string().min(1),
+        }),
+        zod_1.z.object({ kind: zod_1.z.literal("none") }),
+    ])
+        .optional(),
+});
+/**
+ * Layout block keyed by placeholder. Each placeholder holds an ordered
+ * array of `ComponentPlacement`s — render order is array order.
+ */
+exports.LayoutSchema = zod_1.z.object({
+    placeholders: zod_1.z.record(zod_1.z.string(), zod_1.z.array(exports.ComponentPlacementSchema)).default({}),
+});
+/**
+ * A reusable layout chunk — header, footer, sidebar, byline. Lives at
+ * `/sitecore/.../Presentation/Partial Designs/<name>` on a tenant. Linked
+ * by 1..n `PageDesignRecipe`s. Owns its own placeholders and pre-placed
+ * renderings; the compiler emits the same layout XML form pages use.
+ *
+ * Identity: `partialDesignId(handle)` derives the deterministic GUID from
+ * the recipe handle.
+ */
+exports.PartialDesignRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("partial-design"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. standard-header@1",
+    }),
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    description: zod_1.z.string().optional(),
+    /** Defaults to the partial-design icon if omitted. */
+    icon: zod_1.z.string().optional(),
+    /** Placeholders this partial holds, with their pre-placed renderings. */
+    layout: exports.LayoutSchema,
+});
+/**
+ * Maps page templates to a layout. Lives at
+ * `/sitecore/.../Presentation/Page Designs/<name>` on a tenant. Establishes
+ * the templates-to-design mapping (the Sitecore SXA Page Designs root
+ * field), lists which partial designs wrap content, and optionally adds
+ * its own pre-placed renderings.
+ *
+ * Identity: `pageDesignId(handle)` derives the deterministic GUID from
+ * the recipe handle.
+ */
+exports.PageDesignRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("page-design"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. landing-design@1",
+    }),
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    description: zod_1.z.string().optional(),
+    icon: zod_1.z.string().optional(),
+    /**
+     * Page template handles this design applies to. Compiler builds the
+     * URL-string templates-to-designs mapping field on the Sitecore Page
+     * Designs root from this list, resolved via `templateId(handle)`.
+     */
+    appliesTo: zod_1.z.array(zod_1.z.string().regex(HANDLE_PATTERN)).default([]),
+    /**
+     * Partials linked into this design, in render order. Compiler emits the
+     * pipe-separated GUID list on the design's `PartialDesigns` field,
+     * resolved via `partialDesignId(handle)`.
+     */
+    partials: zod_1.z.array(zod_1.z.string().regex(HANDLE_PATTERN)).default([]),
+    /**
+     * Optional own layout — for designs that add page-design-level
+     * placements beyond just wrapping partials. Most designs leave this
+     * empty because the page itself owns its content placements.
+     */
+    layout: exports.LayoutSchema.optional(),
+});
+/**
+ * Default dictionary entry on a `SiteTemplateRecipe`. Every entry the
+ * template declares becomes a Sitecore dictionary phrase with the
+ * supplied default value. Sites instancing the template can override
+ * the value per-phrase via `SiteRecipe.dictionaryOverrides`; phrases
+ * not overridden read the template default.
+ */
+exports.SiteTemplateDictionaryEntrySchema = zod_1.z.object({
+    /** Phrase key — the dictionary item's name. Stable across overrides. */
+    phrase: zod_1.z.string().min(1),
+    /** Default value (the translated string for the template's primary language). */
+    defaultValue: zod_1.z.string(),
+});
+/**
+ * Default taxonomy bucket on a `SiteTemplateRecipe`. Each bucket has a
+ * root folder name (e.g. "Content Types") and a list of tag names that
+ * become the default children. Sites can override the tag list
+ * per-root via `SiteRecipe.taxonomyOverrides`.
+ */
+exports.SiteTemplateTaxonomyEntrySchema = zod_1.z.object({
+    root: zod_1.z.string().min(1),
+    /** Default tag names under this root. Empty list means "create the root, no tags". */
+    defaultTags: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+});
+/**
+ * A `SiteTemplateRecipe` defines a reusable brand/site shape — page
+ * templates, designs, partials (transitively), insert-options matrix,
+ * templates-to-designs mapping, dictionary structure, and taxonomy
+ * structure. The Sitecore SXA "site template" the registry's catalog
+ * ships as a single artifact.
+ *
+ * Many `SiteRecipe`s can reference one `SiteTemplateRecipe`. A
+ * customer with three brands has three Sites instancing one Template;
+ * that's the multi-brand demo pattern this kind enables.
+ *
+ * Identity: `templateId(handle)` derives the GUID — site templates
+ * are regular Sitecore template items under `/sitecore/templates/Project/<Module>`,
+ * not Sites-API-managed instances. Compile path goes through
+ * Authoring GraphQL, not the Sites API.
+ *
+ * Cross-recipe handle resolution: `pageTemplates` and
+ * `insertOptionsMatrix.*` resolve to `ContentTemplateRecipe` handles;
+ * `pageDesigns` and `templatesToDesigns.*` values resolve to
+ * `PageDesignRecipe` handles. The cross-recipe validator
+ * (`validateRecipeSet`) catches missing handles before push.
+ */
+exports.SiteTemplateRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("site-template"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. ccl-brand-template@1",
+    }),
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    description: zod_1.z.string().optional(),
+    icon: zod_1.z.string().optional(),
+    /**
+     * Page-template handles this brand offers (resolve to
+     * `ContentTemplateRecipe`). The site's content tree allows pages
+     * conforming to any of these.
+     */
+    pageTemplates: zod_1.z.array(zod_1.z.string().regex(HANDLE_PATTERN)).default([]),
+    /**
+     * Insert-options matrix — keyed by parent page-template handle,
+     * value is the list of child page-template handles allowed under it.
+     * Drives Sitecore's "Insert Options" UI for content authors.
+     * Empty / omitted means no constraints (any page template can have
+     * any other page template as a child).
+     */
+    insertOptionsMatrix: zod_1.z
+        .record(zod_1.z.string().regex(HANDLE_PATTERN), zod_1.z.array(zod_1.z.string().regex(HANDLE_PATTERN)))
+        .optional(),
+    /**
+     * Page-design handles this brand offers (resolve to
+     * `PageDesignRecipe`). Authors pick from these when creating a page
+     * unless `templatesToDesigns` provides a default for the page's
+     * template.
+     */
+    pageDesigns: zod_1.z.array(zod_1.z.string().regex(HANDLE_PATTERN)).default([]),
+    /**
+     * Default templates-to-designs mapping — keyed by page-template
+     * handle, value is the default page-design handle. Sites can
+     * override per-template at the SXA Page Designs root level
+     * (which scai's `compileRecipeSet` aggregates from
+     * `PageDesignRecipe.appliesTo`).
+     */
+    templatesToDesigns: zod_1.z
+        .record(zod_1.z.string().regex(HANDLE_PATTERN), zod_1.z.string().regex(HANDLE_PATTERN))
+        .optional(),
+    /**
+     * Default dictionary phrases. Sites can override values per-phrase;
+     * unoverridden phrases use the template default.
+     */
+    dictionary: zod_1.z.array(exports.SiteTemplateDictionaryEntrySchema).optional(),
+    /**
+     * Default taxonomy structure. Sites can override tag lists per-root.
+     */
+    taxonomy: zod_1.z.array(exports.SiteTemplateTaxonomyEntrySchema).optional(),
+});
+/**
+ * Site grouping — hostname + language binding. The Sitecore Sites API
+ * `NewSiteInput.hostName` field receives `hostName`; multi-host
+ * setups are configured via separate Site Hosts after creation
+ * (Sites API has its own hosts surface for that, not modelled here).
+ */
+exports.SiteGroupingSchema = zod_1.z.object({
+    /**
+     * Hostname this site responds to (e.g. `solterra.example.com`).
+     * Optional — Sites API defaults to `*` (matches any host) when
+     * omitted. Tenants with one site per environment can leave this
+     * blank; multi-brand tenants set it explicitly.
+     */
+    hostName: zod_1.z.string().min(1).optional(),
+    /**
+     * Language ISO code for this grouping. Defaults to the site's
+     * primary `language` if not set; provided here for forward-compat
+     * with multi-language groupings (e.g. one site responds to
+     * `en.example.com` and `de.example.com`).
+     */
+    language: zod_1.z.string().min(2).optional(),
+    /**
+     * Optional target host for hostname rewrites — used when the site
+     * lives behind a CDN/proxy that maps a public hostname to an
+     * internal one. SXA's `targetHostName` field; rarely set.
+     */
+    targetHostName: zod_1.z.string().min(1).optional(),
+});
+/**
+ * A `SiteRecipe` instances a `SiteTemplateRecipe` at a specific path
+ * with a specific hostname and language. Customers with multiple
+ * brands ship multiple SiteRecipes pointing at the same template;
+ * each gets its own hostname, content tree, taxonomy values, and
+ * dictionary overrides.
+ *
+ * Identity: `siteId(handle)` derives a stable refKey for IR purposes.
+ * The actual Sitecore site itemId is server-assigned by the Sites API
+ * `createSite` mutation (which runs as a job — callers poll
+ * `getJobStatus` until the site is materialised).
+ *
+ * Compile path: `SiteRecipe` execution goes through the Sites API
+ * (`src/sites/api/`), not Authoring GraphQL. The compiler emits a
+ * `CreateSiteFromTemplate` IR op that the executor dispatches to
+ * Sites API; site-grouping fields, dictionary overrides, and
+ * taxonomy overrides land via subsequent ops on the resulting site.
+ *
+ * Cross-recipe handle resolution: `siteTemplate` resolves to a
+ * `SiteTemplateRecipe`; `initialHome` (when present) resolves to a
+ * `PageRecipe` (Phase 6+ — schema accepts the handle now, executor
+ * support lands later).
+ */
+exports.SiteRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("site"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. solterra-co@1",
+    }),
+    /**
+     * Sitecore site item Name (becomes the `siteName` on Sites API
+     * `NewSiteInput`). Distinct from `handle` — handle is the recipe
+     * identity, name is what Sitecore stores.
+     */
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    description: zod_1.z.string().optional(),
+    /**
+     * The `SiteTemplateRecipe` this site instances. Compiler resolves
+     * to the template's Sitecore itemId (which Sites API
+     * `NewSiteInput.templateId` requires) via `templateId(handle)` +
+     * captured-itemId map at execute time.
+     */
+    siteTemplate: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "siteTemplate must reference a SiteTemplateRecipe by handle, e.g. ccl-brand-template@1",
+    }),
+    /**
+     * Primary language ISO code (e.g. `en`, `da`, `fr-CA`). Must be
+     * available on the environment — recipe push adds it via
+     * Sites API `addLanguage` if not already present.
+     */
+    language: zod_1.z.string().min(2),
+    /**
+     * Additional supported languages on this site. Each must be
+     * available on the environment (recipe push adds missing ones).
+     */
+    languages: zod_1.z.array(zod_1.z.string().min(2)).optional(),
+    /**
+     * Existing site collection ID to place the site in. Mutually
+     * exclusive with `collectionName` (cross-field constraint enforced
+     * by the compiler, not Zod — the discriminated union can't carry
+     * refinements). Look up via `listCollections`.
+     */
+    collectionId: zod_1.z.string().min(1).optional(),
+    /**
+     * Name of a NEW collection to create alongside the site. Mutually
+     * exclusive with `collectionId`. Exactly one of these must be
+     * provided — compiler validates.
+     */
+    collectionName: zod_1.z.string().min(1).optional(),
+    /** Display name for the new collection (only when `collectionName` is set). */
+    collectionDisplayName: zod_1.z.string().min(1).optional(),
+    /** Description for the new collection (only when `collectionName` is set). */
+    collectionDescription: zod_1.z.string().optional(),
+    /**
+     * Sitecore content-tree path of the collection, used to compose
+     * dictionary / taxonomy override target paths
+     * (`<collectionPath>/<siteName>/Dictionary/<phrase>` etc.). Optional —
+     * when unset, the compiler derives a path from `collectionName`
+     * (`/sitecore/content/<collectionName>`) per the SXA default
+     * convention. **Required** when `collectionId` is used AND the recipe
+     * declares any dictionary or taxonomy overrides — there's no way to
+     * resolve `collectionId` to a content-tree path at compile time.
+     * Without it, the compiler skips override emission entirely (push
+     * still creates the site, but the overrides don't apply).
+     *
+     * Operator-supplied. The compiler trims a trailing `/` defensively
+     * but otherwise treats this as the truth.
+     */
+    collectionPath: zod_1.z.string().min(1).optional(),
+    /**
+     * Site grouping — hostname binding. Sites API uses
+     * `NewSiteInput.hostName` for the primary host; multi-host setups
+     * use the separate Site Hosts surface.
+     */
+    siteGrouping: exports.SiteGroupingSchema.optional(),
+    /**
+     * Per-phrase override for dictionary values declared on the
+     * `SiteTemplateRecipe.dictionary`. Keys are phrase names; values
+     * replace the template default. Phrases not in this map use the
+     * template default.
+     */
+    dictionaryOverrides: zod_1.z.record(zod_1.z.string().min(1), zod_1.z.string()).optional(),
+    /**
+     * Per-root override for taxonomy default tags. Keys are taxonomy
+     * root names declared on the template; values replace the
+     * template's default tag list for that root.
+     */
+    taxonomyOverrides: zod_1.z.record(zod_1.z.string().min(1), zod_1.z.array(zod_1.z.string().min(1))).optional(),
+    /**
+     * Optional initial home page — a `PageRecipe` handle. Phase 6+
+     * concern; schema accepts the handle now so SiteRecipes can
+     * declare it; the executor will materialise it once page-recipe
+     * execution lands.
+     */
+    initialHome: zod_1.z.string().regex(HANDLE_PATTERN).optional(),
+});
+/**
+ * Discriminated union of recipe kinds. Compilers and validators can accept
+ * `Recipe` and dispatch on `kind`.
+ */
+/**
+ * One value in an `EnumerationRecipe`. Compiles to a Sitecore item that
+ * conforms to the per-site `Enumeration Value` template (NOT the
+ * `Enumeration` template — that one is for the per-enum container).
+ * `Enumeration Value` carries an `Enumeration` Template Section with a
+ * single `Value` Single-Line Text shared field — see
+ * `EnumerationRecipeSchema` for the full template structure.
+ *
+ *   `name`         — Sitecore item name and uuidv5 GUID seed for the
+ *                    value item. Load-bearing: renaming `name` creates
+ *                    a *different* value item and orphans every
+ *                    existing reference. Also written to the `Value`
+ *                    shared field on the value item, which is what
+ *                    SXA-aware consumers (XM Cloud Pages, JSS variants,
+ *                    custom Edge resolvers) read via the canonical
+ *                    "picked item's Value field" pattern.
+ *   `displayName`  — `__Display name` on the item, defaults to `name`.
+ *                    What the editor's Droplink dropdown shows. Use
+ *                    this to change the visible label without touching
+ *                    `name`.
+ */
+exports.EnumerationValueSchema = zod_1.z.object({
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1).optional(),
+});
+/**
+ * A reusable enumeration — backs Droplink fields whose options are
+ * shared across multiple components (color schemes, size scales,
+ * spacing scales, etc.). Each value lands as a child item under
+ * `<enumerationsRoot>/[<subfolder>/]<EnumName>/<ValueName>`.
+ *
+ * Reference from any field via `sitecore.enumHandle: "<handle>"`. On
+ * re-push, adding a value to the enumeration surfaces it on every
+ * referencing field automatically (the Droplink Source resolves by
+ * location at editor time, so consumer field-definitions don't need
+ * to change).
+ *
+ * Underlying template structure (emitted once per site by
+ * `ensureEnumerationTemplates` — three distinct templates, each with
+ * its own role; never collapsed):
+ *
+ *   Enumerations Folder            (Template — folder layers in the
+ *                                   enum content tree: site enumerations
+ *                                   root + per-folder grouping items)
+ *     └── __Standard Values        Insert Options:
+ *                                    Enumeration, Enumerations Folder
+ *
+ *   Enumeration                    (Template — per-enum CONTAINER items
+ *                                   like `Color Scheme`, `Heading Size`)
+ *     └── __Standard Values        Insert Options: Enumeration Value
+ *
+ *   Enumeration Value              (Template — leaf VALUE items like
+ *                                   `primary`, `accent`, `lg`)
+ *     └── Enumeration              (Template Section)
+ *           └── Value               (Single-Line Text, shared)
+ *
+ * Each value item conforms to `Enumeration Value` and stores its `name`
+ * on the `Value` shared field. That payload is what Droplink consumers
+ * read via the SXA "picked item's Value field" pattern — without it,
+ * components wired against the enum stay empty.
+ *
+ * The matching consumer-side surface is `Type=Droplink` (the default
+ * for `shape: "enum"`). Inline Droplink (`shape: "enum"` with `values`
+ * but no `enumHandle`) is unsupported — authors must either point at
+ * an EnumerationRecipe via `enumHandle` or override `sitecore.type` to
+ * `"droplist"` for an inline pipe-list dropdown.
+ */
+exports.EnumerationRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("enumeration"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN),
+    /** Item name under `<enumerationsRoot>` (e.g. `ColorScheme`). */
+    name: zod_1.z.string().min(1),
+    /** Author-facing label (defaults to `name` when omitted). */
+    displayName: zod_1.z.string().min(1).optional(),
+    description: zod_1.z.string().optional(),
+    /**
+     * Optional placement of the enum's items in the content tree. Mirrors
+     * the `scope` + `folder` shape used by component
+     * `rendering.datasource.locations`, but kept SINGULAR (`location`,
+     * not `locations`) — an enum's value items live in exactly one place
+     * by construction, so multi-location dual identity isn't a thing.
+     *
+     *   scope: "site"           → under the site's enumerations root.
+     *   scope: "siteCollection" → reserved for shared-vocabulary use
+     *                             (not yet implemented; throws
+     *                             INPUT_INVALID at compile time).
+     *   folder                  → optional grouping segment(s) under the
+     *                             scope root. Materialised as `CreateOnly`
+     *                             items conforming to the per-site
+     *                             `Enumerations Folder` template. Multiple
+     *                             recipes naming the same folder share it,
+     *                             not collide. Multi-segment paths like
+     *                             `"Theme/Color"` work too — splits on
+     *                             `/`, intermediate segments emit one
+     *                             grouping item each.
+     *
+     * Omit `location` entirely → enum lands flat at the site enumerations
+     * root, no grouping folder.
+     */
+    location: zod_1.z
+        .object({
+        scope: zod_1.z.enum(["site", "siteCollection"]),
+        folder: zod_1.z.string().min(1).optional(),
+    })
+        .optional(),
+    values: zod_1.z.array(exports.EnumerationValueSchema).min(1),
+    /**
+     * Default value for this enumeration. Compiled into the per-enum
+     * container item's `Value` shared field so Edge consumers querying
+     * the container directly receive a default when the picker hasn't
+     * been bound yet (the canonical Sitecore "carry the default on the
+     * enumeration item itself" pattern).
+     *
+     * Must match one of `values[].name`. Validated by
+     * `compileEnumerationRecipe` at compile time (cross-field validation
+     * can't go on the schema itself — `discriminatedUnion` doesn't accept
+     * `ZodEffects` members). Optional — omit to leave the default empty
+     * (consumers fall back to component-level defaults).
+     */
+    default: zod_1.z.string().min(1).optional(),
+});
+exports.RecipeSchema = zod_1.z.discriminatedUnion("kind", [
+    exports.ComponentSectionRecipeSchema,
+    exports.ComponentTemplateRecipeSchema,
+    exports.ContentTemplateRecipeSchema,
+    exports.ContentItemRecipeSchema,
+    exports.ParametersTemplateRecipeSchema,
+    exports.SectionDefinitionRecipeSchema,
+    exports.PartialDesignRecipeSchema,
+    exports.PageDesignRecipeSchema,
+    exports.SiteTemplateRecipeSchema,
+    exports.SiteRecipeSchema,
+    exports.EnumerationRecipeSchema,
+]);