@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/recipe/schema/recipe.js

@@ -1,6 +1,6 @@
 "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;
+exports.RecipeSchema = exports.WorkflowRecipeSchema = exports.WebhookAuthorizationRecipeSchema = exports.EnumerationRecipeSchema = exports.EnumerationValueSchema = exports.SiteRecipeSchema = exports.SiteGroupingSchema = exports.SiteTemplateRecipeSchema = exports.SiteTemplateTaxonomyEntrySchema = exports.SiteTemplateDictionaryEntrySchema = exports.PageDesignRecipeSchema = exports.PartialDesignRecipeSchema = exports.PageRecipeSchema = exports.PageTemplateRecipeSchema = exports.LayoutSchema = exports.ComponentPlacementSchema = exports.ContentItemRecipeSchema = exports.ContentVersionSchema = exports.ContentVariantSchema = exports.ContentTranslationSchema = exports.ContentFieldValueSchema = exports.SectionDefinitionRecipeSchema = exports.DesignParametersTemplateRecipeSchema = exports.ContentTemplateRecipeSchema = exports.RecipeMetaSchema = exports.RecipeMetaTaxSchema = exports.ComponentTemplateRecipeSchema = exports.ComponentSectionRecipeSchema = exports.RecipeDatasourceSchema = exports.RenderingDatasourceLocationSchema = exports.PlaceholderRecipeSchema = exports.PlaceholderDefinitionSchema = exports.RenderingVariantDefinitionSchema = exports.DesignParameterSchema = exports.FieldDefinitionSchema = exports.SitecoreFieldAugmentSchema = void 0;
 const zod_1 = require("zod");
 const field_types_1 = require("./field-types");
 /**
@@ -112,6 +112,19 @@ exports.SitecoreFieldAugmentSchema = zod_1.z
      * not `params`/`variants`). Defaults to "Content".
      */
     section: zod_1.z.string().optional(),
+    /**
+     * Sitecore field storage axis — how a value is scoped on items
+     * conforming to the template:
+     *  - `versioned` (default) — a value per language *and* per numbered
+     *    version.
+     *  - `unversioned` — a value per language, shared across numbered
+     *    versions.
+     *  - `shared` — a single value for the whole item, every language and
+     *    version.
+     * Omit for the Sitecore default (`versioned`). Determines whether
+     * per-language / per-version content is meaningful for this field.
+     */
+    storage: zod_1.z.enum(["versioned", "unversioned", "shared"]).optional(),
 })
     .refine((v) => v.sourceRaw === undefined ||
     (v.sourceTypes === undefined && v.sourceQuery === undefined && v.sourceScope === undefined), {
@@ -129,7 +142,7 @@ exports.FieldDefinitionSchema = zod_1.z.object({
     default: zod_1.z.string().optional(),
     sitecore: exports.SitecoreFieldAugmentSchema.optional(),
 });
-exports.ParamDefinitionSchema = zod_1.z.object({
+exports.DesignParameterSchema = 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(),
@@ -162,11 +175,108 @@ exports.RenderingVariantDefinitionSchema = zod_1.z.object({
         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.",
     }),
 });
+/**
+ * An inline placeholder slot a container component EXPOSES for child
+ * renderings to drop into. The hybrid placeholder model's component-owned
+ * half: a Section / Grid / Tabs component declares the slots it owns
+ * here; site-level chrome slots (`/header`, `/footer`) that belong to no
+ * single component are authored as a standalone `PlaceholderRecipe`
+ * instead.
+ *
+ * Both forms compile to the same artifact — one Sitecore Placeholder
+ * Settings item per unique `key` — emitted by the cross-recipe
+ * `buildPlaceholderSettingsAggregate` (see `compile.ts`). Identity is the
+ * `key`, so an inline slot and a `PlaceholderRecipe` MUST NOT name the
+ * same key; `validateRecipeSet` flags the collision.
+ */
 exports.PlaceholderDefinitionSchema = zod_1.z.object({
-    /** Placeholder key string used in layout XML. */
+    /**
+     * Sitecore Placeholder Key — the string layout XML references in its
+     * `placeh` attribute (e.g. `headless-main`, `grid-content`). For a
+     * `dynamic` placeholder this is the static PREFIX; SXA appends the
+     * `-{uid}-{index}` suffix at render time.
+     */
+    key: zod_1.z.string().min(1),
+    /** Author-facing label on the Placeholder Settings item. Defaults to `key`. */
+    displayName: zod_1.z.string().min(1).optional(),
+    /**
+     * Optional grouping folder path under the placeholder settings root —
+     * the Placeholder Settings item lands at
+     * `<placeholderSettingsRoot>/<folder>/<name>`. Multi-segment paths
+     * (`"Partial Design/Header"`) split on `/`; each segment is
+     * materialised once as a `CreateOnly` folder conforming to the SXA
+     * `Placeholder Settings Folder` template, so it inherits the right
+     * Insert Options. Recipes naming the same folder share it. Omit → the
+     * item lands flat at the root.
+     */
+    folder: zod_1.z.string().min(1).optional(),
+    /**
+     * SXA dynamic placeholder. When true the host rendering must also set
+     * `dynamicPlaceholders: true` so SXA generates per-instance keys; the
+     * Placeholder Settings item is still keyed by the static prefix here.
+     */
+    dynamic: zod_1.z.boolean().optional(),
+    /**
+     * Restriction: only renderings of these `ComponentTemplateRecipe`
+     * handles may be dropped into this slot. Compiles to the slot's
+     * `Allowed Controls` whitelist, unioned with any component that names
+     * this `key` in its `placedIn`. Empty/omitted = no slot-side
+     * restriction (the union is then driven entirely by `placedIn`).
+     */
+    allowedComponents: zod_1.z.array(zod_1.z.string().regex(HANDLE_PATTERN)).optional(),
+});
+/**
+ * A standalone placeholder — the hybrid model's site-chrome half. Slots
+ * like `/header`, `/footer`, `/main`, or a page-design CTA band belong to
+ * no single component; they're authored as their own recipe so partials
+ * and page designs have a typed, validated target to place renderings
+ * into.
+ *
+ * Compiles (via `buildPlaceholderSettingsAggregate`) to one Sitecore
+ * Placeholder Settings item under the tenant's `placeholderSettingsRoot`,
+ * carrying the `Placeholder Key` and an `Allowed Controls` whitelist =
+ * `allowedComponents` ∪ every component whose `placedIn` names this
+ * `key`.
+ *
+ * Identity: `placeholderSettingsId(site, key)` — keyed by `key`, not
+ * `handle`. The `handle` is the authoring-surface identity used for
+ * cross-recipe references and validation messages.
+ */
+exports.PlaceholderRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("placeholder"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. site-header-slot@1",
+    }),
+    /**
+     * Sitecore Placeholder Key — the string layout XML references. For a
+     * `dynamic` placeholder this is the static prefix. Load-bearing: the
+     * emitted item's GUID derives from `key`, so renaming it creates a
+     * different placeholder.
+     */
     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(),
+    /** Sitecore item name under the Placeholder Settings root. */
+    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(),
+    /**
+     * Optional grouping folder path under the placeholder settings root —
+     * the item lands at `<placeholderSettingsRoot>/<folder>/<name>`.
+     * Multi-segment (`"Partial Design/Header"`) splits on `/`; each
+     * segment is a `CreateOnly` folder conforming to the SXA `Placeholder
+     * Settings Folder` template (inheriting its Insert Options). Recipes
+     * naming the same folder share it. Omit → flat at the root.
+     */
+    folder: zod_1.z.string().min(1).optional(),
+    /** SXA dynamic placeholder — see `PlaceholderDefinitionSchema.dynamic`. */
+    dynamic: zod_1.z.boolean().default(false),
+    /**
+     * `ComponentTemplateRecipe` handles whose renderings may be dropped
+     * here. Unioned with any component naming this `key` in `placedIn` to
+     * form the `Allowed Controls` whitelist.
+     */
+    allowedComponents: zod_1.z.array(zod_1.z.string().regex(HANDLE_PATTERN)).default([]),
 });
 /**
  * One entry in the modern semantic-scope datasource locations list.
@@ -354,7 +464,7 @@ exports.ComponentTemplateRecipeSchema = zod_1.z.object({
      */
     datasource: exports.RecipeDatasourceSchema.optional(),
     /**
-     * Reference to a separate `ParametersTemplateRecipe`. When present,
+     * Reference to a separate `DesignParametersTemplateRecipe`. 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:`.
@@ -392,16 +502,23 @@ exports.ComponentTemplateRecipeSchema = zod_1.z.object({
      */
     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([]),
+    params: zod_1.z.array(exports.DesignParameterSchema).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.
+     * placement allow-list. Each key contributes this rendering to that
+     * placeholder's `Allowed Controls` whitelist; without it the rendering
+     * exists in CM but Pages won't offer it in the slot's picker.
+     *
+     * Resolution is split by whether the key is recipe-defined:
+     *   - Keys that match a `PlaceholderRecipe` or an inline
+     *     `placeholders` slot in the same set → folded into the
+     *     `buildPlaceholderSettingsAggregate` IR write (one-push
+     *     convergence on a fresh tenant).
+     *   - Keys with no recipe declaration → resolved post-IR by
+     *     `applyPlaceholderAllowControls`, which walks the tenant's
+     *     existing Placeholder Settings items and patches the match.
      *
-     * Example: `["headless-main", "headless-main-{*}", "sxa-footer"]`.
+     * Example: `["headless-main", "sxa-footer"]`.
      *
      * Distinct from `placeholders` (below), which declares slots THIS
      * component EXPOSES for child renderings.
@@ -409,10 +526,11 @@ exports.ComponentTemplateRecipeSchema = zod_1.z.object({
     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.
+     * renderings to drop into. The hybrid placeholder model's
+     * component-owned half: only meaningful for container components
+     * (a Section / Grid / Tabs wrapper). Each entry compiles to a
+     * Sitecore Placeholder Settings item via
+     * `buildPlaceholderSettingsAggregate`.
      *
      * Distinct from `placedIn` (above), which lists placeholder keys
      * this rendering can be placed INTO.
@@ -503,6 +621,16 @@ exports.ContentTemplateRecipeSchema = zod_1.z.object({
      * that allows item content templates underneath).
      */
     insertOptions: zod_1.z.array(zod_1.z.string()).optional(),
+    /**
+     * Optional `WorkflowRecipe` handle to bind on the template's
+     * `__Standard Values` item. When set, the compiler emits a
+     * `SetField` writing `__Default workflow` to the workflow's refKey,
+     * so new items conforming to this template enter the workflow at
+     * its initial state automatically. Equivalent to declaring the same
+     * handle in the workflow recipe's `bindings.templates[]` — pick
+     * whichever side is more natural to author.
+     */
+    defaultWorkflow: zod_1.z.string().regex(HANDLE_PATTERN).optional(),
 });
 /**
  * A standalone Parameters Template — a Sitecore template item that holds
@@ -517,15 +645,15 @@ exports.ContentTemplateRecipeSchema = zod_1.z.object({
  * into an anonymous parameters template owned by one component);
  * standalone parameters templates are reusable across components.
  *
- * Identity: `paramsTemplateId(handle)` derives the deterministic GUID.
+ * Identity: `designParametersTemplateId(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"),
+exports.DesignParametersTemplateRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("design-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",
@@ -541,7 +669,7 @@ exports.ParametersTemplateRecipeSchema = zod_1.z.object({
      * presentation parameters are organised per-section by convention.
      */
     section: zod_1.z.string().min(1),
-    params: zod_1.z.array(exports.ParamDefinitionSchema).default([]),
+    params: zod_1.z.array(exports.DesignParameterSchema).default([]),
 });
 /**
  * Available Rendering Section Definition — declares an SXA section
@@ -642,6 +770,54 @@ exports.ContentFieldValueSchema = zod_1.z.discriminatedUnion("shape", [
         refs: zod_1.z.array(zod_1.z.string().min(1)),
     }),
 ]);
+/** Per-language field values — a simple-mode translation of a content item. */
+exports.ContentTranslationSchema = zod_1.z.object({
+    /** Field values for this language, keyed by field name. */
+    fields: zod_1.z.record(zod_1.z.string(), exports.ContentFieldValueSchema).default({}),
+});
+/**
+ * A personalization variant within a numbered version — an
+ * audience-conditional alternative. Carries a partial field delta (and an
+ * optional layout) against the version's default.
+ *
+ * The exact XM Cloud personalization wire model is unverified; the compiler
+ * mapping for `variants` is deferred — see docs/recipe-sync-architecture.md,
+ * "Personalization variants".
+ */
+exports.ContentVariantSchema = zod_1.z.object({
+    /** Audience / variant identifier the personalization rule targets. */
+    audience: zod_1.z.string().min(1),
+    /** Field-value delta against the version's default. */
+    fields: zod_1.z.record(zod_1.z.string(), exports.ContentFieldValueSchema).default({}),
+    /** Optional per-variant layout override. */
+    layout: zod_1.z.lazy(() => exports.LayoutSchema).optional(),
+});
+/**
+ * One numbered version of a content item in a single language — the unit a
+ * story-seed recipe authors. See docs/recipe-sync-architecture.md,
+ * "Content versioning — seeding a story".
+ */
+exports.ContentVersionSchema = zod_1.z.object({
+    /** Sitecore numbered version (1-based). */
+    version: zod_1.z.number().int().positive(),
+    /** Field values for this version, keyed by field name. */
+    fields: zod_1.z.record(zod_1.z.string(), exports.ContentFieldValueSchema).default({}),
+    /**
+     * Workflow STATE this version sits in (e.g. "Draft", "Approved") — the
+     * item's `__Workflow state`. Distinct from the item-level `workflow`,
+     * which names the workflow *definition* the item is attached to.
+     */
+    workflowState: zod_1.z.string().min(1).optional(),
+    /** ISO 8601 timestamp narrating when this version lands in the story. */
+    date: zod_1.z.string().optional(),
+    /**
+     * Per-version layout. Writes to the item's `__Final Renderings`
+     * (per-version) field — not the shared `__Renderings`.
+     */
+    layout: zod_1.z.lazy(() => exports.LayoutSchema).optional(),
+    /** Personalization variants for this version. */
+    variants: zod_1.z.array(exports.ContentVariantSchema).optional(),
+});
 /**
  * A concrete content item — one Sitecore item conforming to a content
  * template, populated with the recipe's field values. The Phase 4
@@ -673,16 +849,49 @@ exports.ContentItemRecipeSchema = zod_1.z.object({
     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. */
+    /**
+     * Field values keyed by field name — the primary language, single
+     * version. The simple-mode common case; mutually exclusive with
+     * `versions` (story mode). The compiler enforces the exclusivity.
+     */
     fields: zod_1.z.record(zod_1.z.string(), exports.ContentFieldValueSchema).default({}),
+    /**
+     * Simple mode — additional languages, one version each, keyed by ISO
+     * language code (`fr`, `de`, …). Additive and backward-compatible: omit
+     * for a single-language item. Mutually exclusive with `versions`.
+     */
+    translations: zod_1.z.record(zod_1.z.string(), exports.ContentTranslationSchema).optional(),
+    /**
+     * Story mode — explicit numbered versions for seeding a narrative, keyed
+     * by ISO language code, each an ordered list of `ContentVersion`s.
+     * Mutually exclusive with `fields` / `translations` — a recipe is simple
+     * OR a story. See docs/recipe-sync-architecture.md, "Content versioning".
+     */
+    versions: zod_1.z.record(zod_1.z.string(), zod_1.z.array(exports.ContentVersionSchema)).optional(),
+    /**
+     * Item-level `storage: shared` field values — one value for the whole
+     * item, no language or version. In story mode these have no version to
+     * live under, so they sit here.
+     */
+    shared: zod_1.z.record(zod_1.z.string(), exports.ContentFieldValueSchema).optional(),
+    /**
+     * Optional `WorkflowRecipe` handle to attach this item to. When set,
+     * the compiler emits a `SetField` writing the item's `__Workflow`
+     * field to the workflow's refKey. Use this to override the template's
+     * `__Default workflow` for a single item, or to put items under a
+     * workflow without a template-level default. The item's
+     * `__Workflow state` is not written here — Sitecore initialises new
+     * items at the workflow's initial state from the workflow definition.
+     */
+    workflow: zod_1.z.string().regex(HANDLE_PATTERN).optional(),
 });
 /**
  * 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
+ * The single shape used by anything that holds layout —
+ * `PartialDesignRecipe`, `PageDesignRecipe`, and `PageRecipe`. The
  * `componentHandle` resolves to a `ComponentTemplateRecipe`'s rendering
  * GUID via `renderingId(handle)`.
  *
@@ -690,9 +899,10 @@ exports.ContentItemRecipeSchema = zod_1.z.object({
  *
  *   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.
+ *   scoped  — page-local content materialised at `<page>/Data/<slot>`.
+ *             Only valid in a `PageRecipe` layout (a page has a content
+ *             home to scope under); `PartialDesignRecipe` and
+ *             `PageDesignRecipe` reject it — they have no host page.
  *   none    — config-driven rendering with no datasource (rare).
  */
 exports.ComponentPlacementSchema = zod_1.z.object({
@@ -714,7 +924,13 @@ exports.ComponentPlacementSchema = zod_1.z.object({
         }),
         zod_1.z.object({
             kind: zod_1.z.literal("scoped"),
-            /** Slot path within the host item, e.g. `/main/0`. */
+            /**
+             * Page-local datasource name. `compilePageRecipe` materialises
+             * a datasource item at `<page>/Data/<slot>` (conforming to the
+             * placed component's datasource template) and points the
+             * placement's `ds` at it. Must be a valid Sitecore item name.
+             * Only valid in a `PageRecipe` layout.
+             */
             slot: zod_1.z.string().min(1),
         }),
         zod_1.z.object({ kind: zod_1.z.literal("none") }),
@@ -728,6 +944,138 @@ exports.ComponentPlacementSchema = zod_1.z.object({
 exports.LayoutSchema = zod_1.z.object({
     placeholders: zod_1.z.record(zod_1.z.string(), zod_1.z.array(exports.ComponentPlacementSchema)).default({}),
 });
+/**
+ * A page template — a Sitecore data template that items in a site's
+ * content tree conform to in order to BE authorable pages. The
+ * page-level peer of `ComponentTemplateRecipe`: where a component
+ * template backs a placeable rendering, a page template backs a
+ * navigable page.
+ *
+ * Unlike `ContentTemplateRecipe` (a plain data shape), a page template
+ * inherits the SXA Headless page base set (`SXA_HEADLESS_PAGE_BASE_TEMPLATES`
+ * — Base Page + _Navigable + _Taggable + _Designable + _Sitemap) so
+ * items conforming to it pick up the layout/presentation fields, the
+ * navigation facet, taxonomy tagging, the page-design binding, and
+ * sitemap metadata. The compiler also stamps the template's
+ * `__Standard Values` `__Renderings` with a JSON-layout shell
+ * (`<r><d id="{device}" l="{jsonLayout}" /></r>`), optionally seeded
+ * with `layout` placements.
+ *
+ * Page templates are the resolution target for `PageDesignRecipe.appliesTo`,
+ * `SiteTemplateRecipe.pageTemplates`, `insertOptionsMatrix`, and
+ * `templatesToDesigns` keys. The default template→design binding is the
+ * `TemplatesMapping` aggregate on the Page Designs root (driven by
+ * `PageDesignRecipe.appliesTo`); the per-page `Page Design` override
+ * field is left unset.
+ *
+ * Identity: `templateId(site, handle)` — a page template IS a Sitecore
+ * template, same GUID family as component/content templates.
+ */
+exports.PageTemplateRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("page-template"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. article-page@1",
+    }),
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    description: zod_1.z.string().optional(),
+    /** Defaults to the SXA page icon if omitted. */
+    icon: zod_1.z.string().optional(),
+    /**
+     * Optional taxonomy metadata. `meta.tax.group` nests the template one
+     * folder level deep: when set, the template lands at
+     * `<pageTemplatesRoot>/<group>/<name>` (the group folder is emitted
+     * once per recipe set as a `CreateOnly` op) instead of flat under
+     * `<pageTemplatesRoot>/<name>`. Other taxonomy fields pass through
+     * unmodified for downstream consumers.
+     */
+    meta: exports.RecipeMetaSchema,
+    /**
+     * Page-specific fields beyond the inherited SXA base — SEO copy,
+     * hero overrides, structured metadata. Grouped into sections the
+     * same way component/content template fields are.
+     */
+    fields: zod_1.z.array(exports.FieldDefinitionSchema).default([]),
+    /**
+     * Page-template handles allowed as child pages under items of this
+     * template — the Sitecore Insert Options surface for content authors.
+     * Resolve to other `PageTemplateRecipe` handles.
+     */
+    insertOptions: zod_1.z.array(zod_1.z.string().regex(HANDLE_PATTERN)).optional(),
+    /**
+     * Optional default presentation baked into the template's
+     * `__Standard Values` layout. Most page templates leave this empty —
+     * page chrome comes from the page design's partials, and page-local
+     * content lands on the page item's own `__Final Renderings`. Set it
+     * only for renderings every page of this template should carry
+     * regardless of design.
+     */
+    layout: exports.LayoutSchema.optional(),
+    /**
+     * Optional `WorkflowRecipe` handle bound on the template's
+     * `__Standard Values` `__Default workflow` — new pages of this
+     * template enter the workflow automatically. Mirrors
+     * `ContentTemplateRecipe.defaultWorkflow`.
+     */
+    defaultWorkflow: zod_1.z.string().regex(HANDLE_PATTERN).optional(),
+});
+/**
+ * A page — a concrete, navigable item in the site content tree. The
+ * page-level peer of `ContentItemRecipe`: where a content item is a
+ * shared datasource shape, a `PageRecipe` is an authorable page.
+ *
+ * It conforms to a `PageTemplateRecipe` (inheriting the SXA page
+ * presentation facets), carries field values for the page's own
+ * fields, and may declare a `layout` — written to the page item's
+ * `__Final Renderings` (the per-version final layout), distinct from a
+ * page design's `__Renderings`.
+ *
+ * Layout placements bind via `datasourceRef`: `shared` (a
+ * `ContentItemRecipe`), `scoped` (a page-local datasource item the
+ * compiler materialises at `<page>/Data/<slot>`), or `none`. Pages
+ * currently land flat under `pagesRoot` — page-tree nesting (a `parent`
+ * page handle) is the one deferred follow-up.
+ *
+ * Identity: `pageItemId(site, handle)`. `SiteRecipe.initialHome`
+ * resolves to a `PageRecipe` handle.
+ */
+exports.PageRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("page"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. home@1",
+    }),
+    /** Sitecore item name under the pages root. */
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    description: zod_1.z.string().optional(),
+    /**
+     * Handle of the `PageTemplateRecipe` this page conforms to. Compiler
+     * resolves via `templateId(handle)` to set the item's Template-Of.
+     */
+    template: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "template must reference a PageTemplateRecipe by handle, e.g. article-page@1",
+    }),
+    /**
+     * Field values keyed by field name on the page template. Same
+     * encoding surface as `ContentItemRecipe.fields` (`link-internal`
+     * is deferred — use `reference` or `link-external`).
+     */
+    fields: zod_1.z.record(zod_1.z.string(), exports.ContentFieldValueSchema).default({}),
+    /**
+     * Optional page-local presentation, written to the page item's
+     * `__Final Renderings`. Placements use `datasourceRef` `shared`
+     * (a `ContentItemRecipe`), `scoped` (a page-local datasource at
+     * `<page>/Data/<slot>`, materialised by the compiler), or `none`.
+     */
+    layout: exports.LayoutSchema.optional(),
+    /**
+     * Optional `WorkflowRecipe` handle — sets the page item's
+     * `__Workflow` field. Mirrors `ContentItemRecipe.workflow`.
+     */
+    workflow: zod_1.z.string().regex(HANDLE_PATTERN).optional(),
+});
 /**
  * A reusable layout chunk — header, footer, sidebar, byline. Lives at
  * `/sitecore/.../Presentation/Partial Designs/<name>` on a tenant. Linked
@@ -831,7 +1179,7 @@ exports.SiteTemplateTaxonomyEntrySchema = zod_1.z.object({
  * Authoring GraphQL, not the Sites API.
  *
  * Cross-recipe handle resolution: `pageTemplates` and
- * `insertOptionsMatrix.*` resolve to `ContentTemplateRecipe` handles;
+ * `insertOptionsMatrix.*` resolve to `PageTemplateRecipe` handles;
  * `pageDesigns` and `templatesToDesigns.*` values resolve to
  * `PageDesignRecipe` handles. The cross-recipe validator
  * (`validateRecipeSet`) catches missing handles before push.
@@ -848,7 +1196,7 @@ exports.SiteTemplateRecipeSchema = zod_1.z.object({
     icon: zod_1.z.string().optional(),
     /**
      * Page-template handles this brand offers (resolve to
-     * `ContentTemplateRecipe`). The site's content tree allows pages
+     * `PageTemplateRecipe`). 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([]),
@@ -937,8 +1285,7 @@ exports.SiteGroupingSchema = zod_1.z.object({
  *
  * 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).
+ * `PageRecipe`.
  */
 exports.SiteRecipeSchema = zod_1.z.object({
     kind: zod_1.z.literal("site"),
@@ -1027,10 +1374,8 @@ exports.SiteRecipeSchema = zod_1.z.object({
      */
     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.
+     * Optional initial home page — a `PageRecipe` handle. Cross-recipe
+     * validation resolves it to a `page` recipe in the set.
      */
     initialHome: zod_1.z.string().regex(HANDLE_PATTERN).optional(),
 });
@@ -1160,16 +1505,210 @@ exports.EnumerationRecipeSchema = zod_1.z.object({
      */
     default: zod_1.z.string().min(1).optional(),
 });
+// ─────────────────────────────────────────────────────────────────────
+// Workflow + webhook recipes
+//
+// Full reference (behavior, payload, endpoint contract, auth types,
+// failure modes, troubleshooting): docs/recipes/workflow.md
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Stable, kebab-case key for a workflow state or command. Used as part
+ * of the deterministic GUID seed — renaming a key creates a different
+ * item (and orphans transitions that pointed at the old key). Format
+ * is restricted to lowercase letters, digits, and hyphens so the
+ * generated content-tree paths stay URL-safe across all Sitecore
+ * tenants without re-quoting.
+ */
+const WorkflowKeyPattern = /^[a-z][a-z0-9-]*$/;
+const WorkflowKey = zod_1.z.string().regex(WorkflowKeyPattern, {
+    message: "key must match `^[a-z][a-z0-9-]*$` (lowercase, kebab)",
+});
+/** `$ENV:VAR_NAME` reference — secrets never inline in the recipe file. */
+const SecretRef = zod_1.z.string().regex(/^\$ENV:[A-Z_][A-Z0-9_]*$/, {
+    message: "use $ENV:NAME for secret values; never inline plaintext credentials",
+});
+/**
+ * Webhook authorization recipe — declares a reusable `Webhook
+ * Authorization` item under `/sitecore/system/Settings/Webhooks/Authorizations`.
+ * Workflow webhook actions and event handlers reference one of these
+ * via `authorizationRef: <handle>`.
+ *
+ * The authorization templates live under
+ * `/sitecore/templates/System/Webhooks/Authorizations/...`. The
+ * compiler emits `templateOf: { kind: "ref-path", value: ... }` so the
+ * push pipeline resolves the template GUID at apply time — these
+ * GUIDs aren't published as a public contract.
+ *
+ * Secrets are always by `$ENV:VAR_NAME` reference; the apply step
+ * resolves the env var at push time. Missing env vars surface as a
+ * plan-phase error before any item write.
+ */
+const WebhookAuthorizationApiKeySchema = zod_1.z.object({
+    type: zod_1.z.literal("ApiKey"),
+    /** Header name to attach (e.g. `X-Api-Key`, `Authorization`). */
+    headerName: zod_1.z.string().min(1),
+    /** `$ENV:VAR_NAME` reference to the key/token. */
+    key: SecretRef,
+});
+const WebhookAuthorizationBasicSchema = zod_1.z.object({
+    type: zod_1.z.literal("Basic"),
+    username: zod_1.z.string().min(1),
+    password: SecretRef,
+});
+const WebhookAuthorizationOAuth2Schema = zod_1.z.object({
+    type: zod_1.z.literal("OAuth2ClientCredentialsGrant"),
+    tokenEndpoint: zod_1.z.string().url(),
+    clientId: zod_1.z.string().min(1),
+    clientSecret: SecretRef,
+    scope: zod_1.z.string().optional(),
+    audience: zod_1.z.string().optional(),
+});
+exports.WebhookAuthorizationRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("webhook-authorization"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. ci-bearer@1",
+    }),
+    /** Sitecore item name. */
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    description: zod_1.z.string().optional(),
+    auth: zod_1.z.discriminatedUnion("type", [
+        WebhookAuthorizationApiKeySchema,
+        WebhookAuthorizationBasicSchema,
+        WebhookAuthorizationOAuth2Schema,
+    ]),
+});
+/**
+ * Either an intra-recipe reference to a `webhook-authorization` recipe
+ * (`authorizationRef: <handle>`) or an absolute content-tree path
+ * (`authorizationPath: /sitecore/system/Settings/Webhooks/Authorizations/...`)
+ * to an existing tenant-side Authorization item. Exactly one of the two
+ * (enforced via superRefine on the workflow recipe).
+ */
+const WebhookActionAuthRefSchema = zod_1.z.object({
+    authorizationRef: zod_1.z.string().regex(HANDLE_PATTERN).optional(),
+    authorizationPath: zod_1.z.string().startsWith("/sitecore/").optional(),
+});
+const WebhookActionBaseSchema = WebhookActionAuthRefSchema.extend({
+    /**
+     * Sitecore item name for the action item. Derived from the action's
+     * key within its state/command (e.g. `notify-reviewer`) — must be
+     * unique among siblings under that state or command.
+     */
+    key: WorkflowKey,
+    url: zod_1.z.string().url(),
+    displayName: zod_1.z.string().min(1).optional(),
+    description: zod_1.z.string().optional(),
+    serializationType: zod_1.z.enum(["JSON", "XML"]).default("JSON"),
+    enabled: zod_1.z.boolean().default(true),
+});
+const WebhookSubmitActionSchema = WebhookActionBaseSchema.extend({
+    kind: zod_1.z.literal("webhook-submit"),
+});
+const WebhookValidationActionSchema = WebhookActionBaseSchema.extend({
+    kind: zod_1.z.literal("webhook-validation"),
+});
+const WorkflowActionSchema = zod_1.z.discriminatedUnion("kind", [
+    WebhookSubmitActionSchema,
+    WebhookValidationActionSchema,
+]);
+const AppearanceEvaluatorSchema = zod_1.z.enum(["default", "lock", "unlock"]);
+const WorkflowCommandSchema = zod_1.z.object({
+    key: WorkflowKey,
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    nextState: WorkflowKey,
+    /** Maps to the standard `__Auto Publish` field on a workflow Command. */
+    autoPublish: zod_1.z.boolean().default(false),
+    /** Maps to the standard `Suppress comment` field — silences the comment prompt. */
+    suppressComment: zod_1.z.boolean().default(false),
+    /** Maps to `Appearance Evaluator Type`. */
+    appearanceEvaluator: AppearanceEvaluatorSchema.default("default"),
+    /**
+     * When true, the compiler emits a `SetField` to restrict the command
+     * to administrators (sets the standard `__Security` field with a
+     * deny-everyone ACL plus an allow-admin ACL). Suitable for sensitive
+     * commands like "Publish to Production" that shouldn't be available
+     * to all reviewers.
+     */
+    secured: zod_1.z.boolean().default(false),
+    /** Validation actions attached to this command (synchronous gates). */
+    validations: zod_1.z.array(WebhookValidationActionSchema).default([]),
+});
+const WorkflowStateSchema = zod_1.z.object({
+    key: WorkflowKey,
+    name: zod_1.z.string().min(1),
+    displayName: zod_1.z.string().min(1),
+    /** Maps to the standard `Final` checkbox on the State item. */
+    final: zod_1.z.boolean().default(false),
+    /** Maps to `Preview` — items in this state appear in the preview database. */
+    preview: zod_1.z.boolean().default(false),
+    /** Submit or validation actions that fire on entry into this state. */
+    actions: zod_1.z.array(WorkflowActionSchema).default([]),
+    commands: zod_1.z.array(WorkflowCommandSchema).default([]),
+});
+const WorkflowBindingsSchema = zod_1.z
+    .object({
+    /**
+     * Templates to bind this workflow to. Each entry is either an
+     * intra-recipe content-template handle (resolves via refKey) or an
+     * absolute path to a tenant-existing template (resolves via
+     * `crossRecipeRefs`). The compiler emits a `SetField` op against
+     * each template's `__Standard Values` item setting the
+     * `__Default workflow` field.
+     */
+    templates: zod_1.z
+        .array(zod_1.z.union([zod_1.z.string().regex(HANDLE_PATTERN), zod_1.z.string().startsWith("/sitecore/templates/")]))
+        .default([]),
+})
+    .default({ templates: [] });
+/**
+ * Cross-field validations (`initialState` must match a declared state,
+ * `nextState` refs must resolve, at least one final state, action auth
+ * is `Ref` XOR `Path`) live in `compileWorkflowRecipe` — not on the
+ * schema — because Zod's `discriminatedUnion` rejects `ZodEffects`
+ * members and we need this schema in `RecipeSchema`. Same pattern
+ * `EnumerationRecipeSchema` uses for its `default ∈ values` check.
+ */
+exports.WorkflowRecipeSchema = zod_1.z.object({
+    kind: zod_1.z.literal("workflow"),
+    schemaVersion: zod_1.z.literal("1"),
+    handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>`, e.g. blog-article-approval@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(),
+    /**
+     * Optional taxonomy metadata. `meta.tax.group` is the only field
+     * the compiler currently consumes — it drives a one-level Workflow
+     * Folder under `/sitecore/system/Workflows/<group>/<name>`. Other
+     * fields are accepted for registry → recipe pipeline compatibility
+     * but aren't load-bearing.
+     */
+    meta: exports.RecipeMetaSchema,
+    /** State key of the workflow's initial state (must match one of `states`). */
+    initialState: WorkflowKey,
+    states: zod_1.z.array(WorkflowStateSchema).min(1),
+    bindings: WorkflowBindingsSchema,
+});
 exports.RecipeSchema = zod_1.z.discriminatedUnion("kind", [
     exports.ComponentSectionRecipeSchema,
     exports.ComponentTemplateRecipeSchema,
     exports.ContentTemplateRecipeSchema,
     exports.ContentItemRecipeSchema,
-    exports.ParametersTemplateRecipeSchema,
+    exports.PageTemplateRecipeSchema,
+    exports.PageRecipeSchema,
+    exports.PlaceholderRecipeSchema,
+    exports.DesignParametersTemplateRecipeSchema,
     exports.SectionDefinitionRecipeSchema,
     exports.PartialDesignRecipeSchema,
     exports.PageDesignRecipeSchema,
     exports.SiteTemplateRecipeSchema,
     exports.SiteRecipeSchema,
     exports.EnumerationRecipeSchema,
+    exports.WorkflowRecipeSchema,
+    exports.WebhookAuthorizationRecipeSchema,
 ]);