@sitecoreai-labs/sitecoreai-cli 0.1.2 → 0.2.1

package/dist/brand/recipe/schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BrandKitRecipeSchema = exports.BrandDocumentSchema = exports.BrandFieldValueSchema = exports.BrandRichEntrySchema = void 0;
+exports.BrandKitRecipeSchema = exports.BrandDocumentSchema = exports.BrandRegistryFileDocumentSchema = exports.BrandUrlDocumentSchema = exports.BRAND_KIT_CANONICAL_SECTIONS = exports.BrandFieldValueSchema = exports.BrandRichEntrySchema = void 0;
 /**
  * `BrandKitRecipe` — the declarative definition of a Sitecore Brand
  * brand kit.
@@ -8,9 +8,26 @@ exports.BrandKitRecipeSchema = exports.BrandDocumentSchema = exports.BrandFieldV
  * This schema is the single source of truth for the `brand-kit` recipe
  * kind: it validates recipe files, drives the `sync` CLI, and becomes
  * the MCP tool input schema. Keep the `.describe()` text accurate — the
- * model reads it. See docs/recipe-sync-architecture.md.
+ * model reads it.
+ *
+ * Two authoring shapes share this schema:
+ *
+ *   - **scai-native** — flat object with `name`, `documents`, `sections`.
+ *     No `kind` / `schemaVersion` / `handle`. Used by hand-authored
+ *     `.brandkit.yaml` files and the `scai brand sync pull` capture
+ *     path. Stays valid: the discriminator fields are optional here.
+ *   - **registry-superset** — the richer shape the `@registry`
+ *     `sitecore-recipes.ts` exports use: adds `kind: "brandkit"`,
+ *     `schemaVersion: "1"`, `handle`, `displayName`, and a
+ *     discriminated `documents[]` shape (`url` | `registry-file`)
+ *     with `tags` / `sections` hints per document. The orchestrator
+ *     passes recipes through unchanged from the registry to scai;
+ *     scai's parser accepts the extra fields without stripping them.
+ *
+ * See docs/recipe-sync-architecture.md.
  */
 const zod_1 = require("zod");
+const HANDLE_PATTERN = /^[a-z][a-z0-9-]*@\d+$/;
 /** A `richArray`-field entry: text plus optional tags and a constraint. */
 exports.BrandRichEntrySchema = zod_1.z.object({
     name: zod_1.z.string().min(1).describe("The entry's text."),
@@ -31,29 +48,141 @@ exports.BrandRichEntrySchema = zod_1.z.object({
 exports.BrandFieldValueSchema = zod_1.z
     .union([zod_1.z.string(), zod_1.z.array(zod_1.z.string()), zod_1.z.array(exports.BrandRichEntrySchema)])
     .describe("A text value, a list of names, or a list of rich entries.");
-/** A brand document to ingest. Sitecore fetches the URL server-side. */
-exports.BrandDocumentSchema = zod_1.z.object({
+/**
+ * Canonical Sitecore AI brand-kit section names — the seven buckets
+ * the EnrichSections pipeline produces. Mirrors
+ * `BRAND_KIT_CANONICAL_SECTIONS` in the registry's recipe definitions.
+ * Exported so callers building recipes have a stable list to bias
+ * `documents[].sections` against.
+ */
+exports.BRAND_KIT_CANONICAL_SECTIONS = [
+    "Brand Context",
+    "Global Goals",
+    "Tone of Voice",
+    "Glossary and Localization",
+    "Do's and Don'ts",
+    "Grammar Checklists",
+    "Visual Guidelines",
+];
+/**
+ * Optional ingestion hints — `tags` and `sections` — shared by both
+ * document variants. Hoisted into a shape so the URL and registry-file
+ * shapes stay in lockstep without duplicating field-by-field.
+ */
+const DocumentHints = {
+    title: zod_1.z.string().optional().describe('Document title. Defaults to "brand guidelines".'),
+    summary: zod_1.z.string().optional().describe("Short document summary."),
+    tags: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe('Free-form tags surfaced to the EnrichSections pipeline (e.g. "voice").'),
+    sections: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe('Canonical section names to bias ingestion toward (e.g. ["Tone of Voice"]). Prefer values from BRAND_KIT_CANONICAL_SECTIONS.'),
+};
+/**
+ * A brand document referenced by URL. Sitecore's Documents API fetches
+ * the URL server-side and copies the bytes into MMS. The default
+ * variant — what `scai brand sync pull` emits when capturing a live
+ * kit.
+ */
+exports.BrandUrlDocumentSchema = zod_1.z.object({
+    kind: zod_1.z.literal("url"),
     url: zod_1.z
         .string()
         .min(1)
         .describe("Publicly reachable URL of a brand document (PDF). Sitecore fetches it server-side."),
-    title: zod_1.z.string().optional().describe('Document title. Defaults to "brand guidelines".'),
-    summary: zod_1.z.string().optional().describe("Short document summary."),
+    ...DocumentHints,
 });
+/**
+ * A brand document stored alongside the recipe in the registry repo.
+ * The `path` is relative to the recipe file's directory. scai itself
+ * does **not** upload these — the Sitecore Documents API has no
+ * working bytes-upload path (see
+ * `src/brand/documents/upload.ts::LOCAL_UPLOAD_UNSUPPORTED_MESSAGE`),
+ * so the orchestrator (or whoever owns the recipe before scai sees
+ * it) MUST translate `registry-file` entries to `url` entries
+ * pointing at an HTTP-reachable host before invoking `scai brand
+ * sync push`. The seed runner rejects unresolved `registry-file`
+ * documents with a clear hint; this stays in the schema as an
+ * authoring-time shape so registry-side recipes round-trip cleanly.
+ */
+exports.BrandRegistryFileDocumentSchema = zod_1.z.object({
+    kind: zod_1.z.literal("registry-file"),
+    path: zod_1.z.string().min(1).describe("Path to the document, relative to the recipe file."),
+    ...DocumentHints,
+});
+/**
+ * A brand document to ingest. Two variants — `{ kind: "url", url }` and
+ * `{ kind: "registry-file", path }` — sharing optional `title` /
+ * `summary` / `tags` / `sections` ingestion hints.
+ *
+ * Back-compat: scai-native recipes that pre-date the discriminator wrote
+ * documents as the flat `{ url, title?, summary? }` shape. The
+ * `z.preprocess` step defaults a missing `kind` to `"url"` whenever
+ * `url` is present, so legacy recipes keep parsing without a migration
+ * step. Zod 4's discriminated unions require the discriminator to be
+ * present BEFORE routing, so `.default("url")` inline on the literal
+ * doesn't work — preprocess is the correct seam.
+ */
+exports.BrandDocumentSchema = zod_1.z.preprocess((raw) => {
+    if (raw !== null &&
+        typeof raw === "object" &&
+        !Array.isArray(raw) &&
+        !("kind" in raw) &&
+        "url" in raw) {
+        return { kind: "url", ...raw };
+    }
+    return raw;
+}, zod_1.z.discriminatedUnion("kind", [exports.BrandUrlDocumentSchema, exports.BrandRegistryFileDocumentSchema]));
 /** The full brand-kit recipe. */
 exports.BrandKitRecipeSchema = zod_1.z.object({
+    /**
+     * Registry-superset discriminator — `"brandkit"`. Optional: scai-
+     * native YAML/JSON recipes pre-date this field and don't carry it.
+     * Defaulting in (rather than requiring) keeps the legacy parse
+     * path intact. Registry-authored recipes set this explicitly.
+     */
+    kind: zod_1.z.literal("brandkit").optional(),
+    /**
+     * Registry-superset schema version pin — `"1"`. Optional for the
+     * same back-compat reason as `kind`. When set, the registry's
+     * discriminated-union loader picks this recipe up.
+     */
+    schemaVersion: zod_1.z.literal("1").optional(),
+    /**
+     * Stable handle of the form `<kebab-name>@<major>` (e.g.
+     * `acme-brand@1`). Registry-side identifier used to wire brand
+     * kits to themes. Optional in scai because scai-native recipes
+     * identify kits by `name`, not handle.
+     */
+    handle: zod_1.z
+        .string()
+        .regex(HANDLE_PATTERN, {
+        message: "handle must match `<kebab-name>@<major>` (e.g. acme-brand@1)",
+    })
+        .optional()
+        .describe("Stable handle `<kebab-name>@<major>`. Required for registry-authored recipes."),
     name: zod_1.z
         .string()
         .min(1)
         .describe("Display name of the brand kit. Identifies the kit when pushing."),
+    /**
+     * Author-facing label, mirrors the registry's superset. When absent
+     * the registry's loader treats it as identical to `name`; scai's
+     * `apply()` likewise ignores it (the API has no separate display
+     * name slot beyond `name`).
+     */
+    displayName: zod_1.z.string().min(1).optional().describe("Author-facing label; defaults to `name`."),
     description: zod_1.z.string().optional().describe("Human description of the kit."),
     industry: zod_1.z.string().optional().describe('Industry label, e.g. "retail" or "developer-tools".'),
     documents: zod_1.z
         .array(exports.BrandDocumentSchema)
         .default([])
-        .describe("Brand documents to ingest. On push, when the kit has no populated sections, each is uploaded and run through the ingestion + enrichment pipelines."),
+        .describe("Brand documents to ingest. On push, when the kit has no populated sections, each is uploaded and run through the ingestion + enrichment pipelines. `registry-file` variants must be translated to `url` variants before scai sees the recipe — the Sitecore Documents API has no working bytes-upload path."),
     sections: zod_1.z
         .record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), exports.BrandFieldValueSchema))
         .default({})
-        .describe("Desired field values, keyed by section name then field name. Sections and fields are created by enrichment; push converges their values."),
+        .describe("Desired field values, keyed by section name then field name. Prefer canonical names from BRAND_KIT_CANONICAL_SECTIONS for the outer key. Sections and fields are created by enrichment; push converges their values."),
 });

package/dist/brand/seed.d.ts

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

package/dist/brand/seed.js

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

package/dist/brief/api/briefs.d.ts

@@ -43,6 +43,14 @@ export type CreateBriefInput = {
     fields?: Record<string, unknown>;
     isTemplate?: boolean;
 };
+/**
+ * Validate an unknown value as a `CreateBriefInput`. Throws a typed
+ * `ScaiError` (`INPUT_INVALID`) on failure; returns the narrowed input
+ * on success. `createBrief` calls this itself, so direct SDK consumers
+ * are guarded without invoking it explicitly. Mirrors
+ * `assertCreateBriefTypeInput` in `./brief-types.ts`.
+ */
+export declare const assertCreateBriefInput: (value: unknown) => CreateBriefInput;
 /** Create a brief. Returns the persisted record (201). */
 export declare const createBrief: (options: BriefApiClientOptions, input: CreateBriefInput) => Promise<Brief>;
 /**

package/dist/brief/api/briefs.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deleteBrief = exports.setBriefStatus = exports.updateBrief = exports.createBrief = exports.getBrief = exports.listBriefs = void 0;
+exports.deleteBrief = exports.setBriefStatus = exports.updateBrief = exports.createBrief = exports.assertCreateBriefInput = exports.getBrief = exports.listBriefs = void 0;
+const errors_1 = require("../../shared/errors");
 const request_1 = require("./request");
 /** List all briefs in the tenant (paged). */
 const listBriefs = (options, query) => {
@@ -19,17 +20,54 @@ exports.listBriefs = listBriefs;
 /** Read a single brief by id. 404 surfaces as `BRIEF_API_FAILED` with `"Brief not found"`. */
 const getBrief = (options, briefId) => (0, request_1.briefRequest)(options, `/api/brief/v1/briefs/${encodeURIComponent(briefId)}`);
 exports.getBrief = getBrief;
+/** Required keys on a `CreateBriefInput` body. */
+const BRIEF_REQUIRED_KEYS = ["name", "briefTypeId"];
+/**
+ * Validate an unknown value as a `CreateBriefInput`. Throws a typed
+ * `ScaiError` (`INPUT_INVALID`) on failure; returns the narrowed input
+ * on success. `createBrief` calls this itself, so direct SDK consumers
+ * are guarded without invoking it explicitly. Mirrors
+ * `assertCreateBriefTypeInput` in `./brief-types.ts`.
+ */
+const assertCreateBriefInput = (value) => {
+    if (!value || typeof value !== "object") {
+        throw (0, errors_1.createScaiError)("Brief body must be a JSON object.", "INPUT_INVALID");
+    }
+    const obj = value;
+    const missing = BRIEF_REQUIRED_KEYS.filter((key) => obj[key] === undefined);
+    if (missing.length > 0) {
+        throw (0, errors_1.createScaiError)(`Brief body is missing required fields: ${missing.join(", ")}.`, "INPUT_INVALID", { hint: "Required: name (string), briefTypeId (UUID of the brief type)." });
+    }
+    if (typeof obj.name !== "string" || obj.name.length === 0) {
+        throw (0, errors_1.createScaiError)(`Invalid 'name': ${JSON.stringify(obj.name)}.`, "INPUT_INVALID", {
+            hint: "Brief name must be a non-empty string.",
+        });
+    }
+    if (typeof obj.briefTypeId !== "string" || obj.briefTypeId.length === 0) {
+        throw (0, errors_1.createScaiError)(`Invalid 'briefTypeId': ${JSON.stringify(obj.briefTypeId)}.`, "INPUT_INVALID", {
+            hint: "Pass the brief type's UUID. List types with `scai ops brief types list`.",
+        });
+    }
+    if (obj.fields !== undefined && (typeof obj.fields !== "object" || Array.isArray(obj.fields))) {
+        throw (0, errors_1.createScaiError)("'fields' must be an object keyed by field name.", "INPUT_INVALID");
+    }
+    return obj;
+};
+exports.assertCreateBriefInput = assertCreateBriefInput;
 /** Create a brief. Returns the persisted record (201). */
-const createBrief = (options, input) => (0, request_1.briefRequest)(options, "/api/brief/v1/briefs", {
-    method: "POST",
-    body: {
-        name: input.name,
-        briefTypeId: input.briefTypeId,
-        locale: input.locale,
-        fields: input.fields,
-        isTemplate: input.isTemplate,
-    },
-});
+const createBrief = (options, input) => {
+    (0, exports.assertCreateBriefInput)(input);
+    return (0, request_1.briefRequest)(options, "/api/brief/v1/briefs", {
+        method: "POST",
+        body: {
+            name: input.name,
+            briefTypeId: input.briefTypeId,
+            locale: input.locale,
+            fields: input.fields,
+            isTemplate: input.isTemplate,
+        },
+    });
+};
 exports.createBrief = createBrief;
 /**
  * Partial update of a brief (`PUT /api/brief/v1/briefs/{id}` — 204 No

package/dist/brief/index.d.ts

@@ -23,7 +23,7 @@ export type { BriefApiClientOptions, BriefRequestInit, BriefQueryValue, BriefQue
 export { BRIEF_API_HOST_TEMPLATE, DEFAULT_BRIEF_API_BASE } from "./api/types";
 export { briefRequest } from "./api/request";
 export type { PagedResult, LocalizedString, Link, ExternalLink, Reference, BriefField, BriefFieldBase, RichTextField, DateTimeField, TimelineField, BudgetField, BriefType, Brief, BriefStatus, BriefTask, BriefComment, ExternalMapping, } from "./api/schema";
-export { listBriefs, getBrief, createBrief, updateBrief, setBriefStatus, deleteBrief, type CreateBriefInput, type ListBriefsQuery, } from "./api/briefs";
+export { listBriefs, getBrief, createBrief, updateBrief, setBriefStatus, deleteBrief, assertCreateBriefInput, type CreateBriefInput, type ListBriefsQuery, } from "./api/briefs";
 export { listBriefTypes, getBriefType, createBriefType, updateBriefType, deleteBriefType, type CreateBriefTypeInput, } from "./api/brief-types";
 export { listBriefTasks, getBriefTask, type BriefTaskMetadata, type ListBriefTasksQuery, } from "./api/tasks";
 export { listBriefComments, createBriefComment, type ListBriefCommentsQuery, type CreateBriefCommentInput, } from "./api/comments";

package/dist/brief/index.js

@@ -21,7 +21,7 @@
  * (read+write). The Agents env client carries both by default.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveBriefClient = exports.BRIEF_SCOPES_REQUESTED = exports.acquireBriefToken = exports.createBriefComment = exports.listBriefComments = exports.getBriefTask = exports.listBriefTasks = exports.deleteBriefType = exports.updateBriefType = exports.createBriefType = exports.getBriefType = exports.listBriefTypes = exports.deleteBrief = exports.setBriefStatus = exports.updateBrief = exports.createBrief = exports.getBrief = exports.listBriefs = exports.briefRequest = exports.DEFAULT_BRIEF_API_BASE = exports.BRIEF_API_HOST_TEMPLATE = void 0;
+exports.resolveBriefClient = exports.BRIEF_SCOPES_REQUESTED = exports.acquireBriefToken = exports.createBriefComment = exports.listBriefComments = exports.getBriefTask = exports.listBriefTasks = exports.deleteBriefType = exports.updateBriefType = exports.createBriefType = exports.getBriefType = exports.listBriefTypes = exports.assertCreateBriefInput = exports.deleteBrief = exports.setBriefStatus = exports.updateBrief = exports.createBrief = exports.getBrief = exports.listBriefs = exports.briefRequest = exports.DEFAULT_BRIEF_API_BASE = exports.BRIEF_API_HOST_TEMPLATE = void 0;
 var types_1 = require("./api/types");
 Object.defineProperty(exports, "BRIEF_API_HOST_TEMPLATE", { enumerable: true, get: function () { return types_1.BRIEF_API_HOST_TEMPLATE; } });
 Object.defineProperty(exports, "DEFAULT_BRIEF_API_BASE", { enumerable: true, get: function () { return types_1.DEFAULT_BRIEF_API_BASE; } });
@@ -34,6 +34,7 @@ Object.defineProperty(exports, "createBrief", { enumerable: true, get: function
 Object.defineProperty(exports, "updateBrief", { enumerable: true, get: function () { return briefs_1.updateBrief; } });
 Object.defineProperty(exports, "setBriefStatus", { enumerable: true, get: function () { return briefs_1.setBriefStatus; } });
 Object.defineProperty(exports, "deleteBrief", { enumerable: true, get: function () { return briefs_1.deleteBrief; } });
+Object.defineProperty(exports, "assertCreateBriefInput", { enumerable: true, get: function () { return briefs_1.assertCreateBriefInput; } });
 var brief_types_1 = require("./api/brief-types");
 Object.defineProperty(exports, "listBriefTypes", { enumerable: true, get: function () { return brief_types_1.listBriefTypes; } });
 Object.defineProperty(exports, "getBriefType", { enumerable: true, get: function () { return brief_types_1.getBriefType; } });

package/dist/brief/recipe/index.d.ts

@@ -1,6 +1,12 @@
 /**
- * The `brief-type` recipe kind — declarative definition + `sync` support
- * for Sitecore Content Operations brief types.
+ * The brief recipe surface — declarative definitions + `sync` support
+ * for Sitecore Content Operations brief types AND brief instances.
+ *
+ * Two kinds:
+ *   - `briefTypeKind` ("brief-type") — the schema template a brief is
+ *     built against. Identified by stable codename.
+ *   - `briefInstanceKind` ("brief") — a populated brief instance.
+ *     Identified by display name; references its type by codename.
  *
  * See docs/recipe-sync-architecture.md.
  */
@@ -8,3 +14,6 @@ export { BriefTypeRecipeSchema, BriefFieldSchema, RichTextFieldSchema, DateTimeF
 export { diffBriefType } from "./diff";
 export { resolveBriefClient } from "./client";
 export { briefTypeKind } from "./kind";
+export { BriefInstanceRecipeSchema, BriefInstanceStatusSchema, BriefInstanceFieldsSchema, type BriefInstanceRecipe, } from "./instance-schema";
+export { diffBriefInstance } from "./instance-diff";
+export { briefInstanceKind } from "./instance-kind";

package/dist/brief/recipe/index.js

@@ -1,9 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.briefTypeKind = exports.resolveBriefClient = exports.diffBriefType = exports.LocalizedStringSchema = exports.BudgetFieldSchema = exports.TimelineFieldSchema = exports.DateTimeFieldSchema = exports.RichTextFieldSchema = exports.BriefFieldSchema = exports.BriefTypeRecipeSchema = void 0;
+exports.briefInstanceKind = exports.diffBriefInstance = exports.BriefInstanceFieldsSchema = exports.BriefInstanceStatusSchema = exports.BriefInstanceRecipeSchema = exports.briefTypeKind = exports.resolveBriefClient = exports.diffBriefType = exports.LocalizedStringSchema = exports.BudgetFieldSchema = exports.TimelineFieldSchema = exports.DateTimeFieldSchema = exports.RichTextFieldSchema = exports.BriefFieldSchema = exports.BriefTypeRecipeSchema = void 0;
 /**
- * The `brief-type` recipe kind — declarative definition + `sync` support
- * for Sitecore Content Operations brief types.
+ * The brief recipe surface — declarative definitions + `sync` support
+ * for Sitecore Content Operations brief types AND brief instances.
+ *
+ * Two kinds:
+ *   - `briefTypeKind` ("brief-type") — the schema template a brief is
+ *     built against. Identified by stable codename.
+ *   - `briefInstanceKind` ("brief") — a populated brief instance.
+ *     Identified by display name; references its type by codename.
  *
  * See docs/recipe-sync-architecture.md.
  */
@@ -21,3 +27,11 @@ var client_1 = require("./client");
 Object.defineProperty(exports, "resolveBriefClient", { enumerable: true, get: function () { return client_1.resolveBriefClient; } });
 var kind_1 = require("./kind");
 Object.defineProperty(exports, "briefTypeKind", { enumerable: true, get: function () { return kind_1.briefTypeKind; } });
+var instance_schema_1 = require("./instance-schema");
+Object.defineProperty(exports, "BriefInstanceRecipeSchema", { enumerable: true, get: function () { return instance_schema_1.BriefInstanceRecipeSchema; } });
+Object.defineProperty(exports, "BriefInstanceStatusSchema", { enumerable: true, get: function () { return instance_schema_1.BriefInstanceStatusSchema; } });
+Object.defineProperty(exports, "BriefInstanceFieldsSchema", { enumerable: true, get: function () { return instance_schema_1.BriefInstanceFieldsSchema; } });
+var instance_diff_1 = require("./instance-diff");
+Object.defineProperty(exports, "diffBriefInstance", { enumerable: true, get: function () { return instance_diff_1.diffBriefInstance; } });
+var instance_kind_1 = require("./instance-kind");
+Object.defineProperty(exports, "briefInstanceKind", { enumerable: true, get: function () { return instance_kind_1.briefInstanceKind; } });

package/dist/brief/recipe/instance-diff.d.ts

@@ -0,0 +1,4 @@
+import type { RecipePlan } from "../../sync";
+import type { BriefInstanceRecipe } from "./instance-schema";
+/** Diff a desired brief-instance recipe against captured current state. */
+export declare const diffBriefInstance: (desired: BriefInstanceRecipe, current: BriefInstanceRecipe | null) => RecipePlan;

package/dist/brief/recipe/instance-diff.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffBriefInstance = void 0;
+/**
+ * The pure diff for the `brief` recipe kind — desired recipe vs.
+ * captured current state → a `RecipePlan`. No I/O, so it is cheap to
+ * unit-test and is the testable core of the kind.
+ *
+ * Unlike `brief-type` (which is a single full-replacement PUT), brief
+ * instances support a partial PUT: the diff therefore emits two stages
+ * of changes:
+ *
+ *   - One `stage: "instance"` change carries the whole desired recipe.
+ *     `apply` consumes it to drive `createBrief` or `updateBrief`.
+ *   - Per-element `stage: "field"` changes describe the convergence
+ *     element-by-element so the rendered plan reads cleanly. They are
+ *     descriptive only — the single `stage: "instance"` change is what
+ *     `apply` writes.
+ *
+ * Identification is by `name` (the brief's display name). Brief
+ * instances are not enforced unique by name on the server; the diff and
+ * apply both treat "first match wins", matching the campaign-instance
+ * precedent. See docs/recipe-sync-architecture.md.
+ */
+const node_util_1 = require("node:util");
+/**
+ * The top-level recipe elements compared one-by-one when the brief
+ * exists. `briefTypeName` is included because the diff surfaces a
+ * type-change attempt — `apply` then refuses it (the Brief API has no
+ * verified path to repoint an existing brief at a different type).
+ */
+const COMPARED_ELEMENTS = ["briefTypeName", "locale", "status", "isTemplate", "fields"];
+/** Diff a desired brief-instance recipe against captured current state. */
+const diffBriefInstance = (desired, current) => {
+    const changes = [];
+    if (current === null) {
+        changes.push({
+            kind: "create",
+            path: "brief",
+            summary: `Create brief "${desired.name}"`,
+            after: desired.name,
+            meta: { stage: "instance", recipe: desired },
+        });
+        return { changes };
+    }
+    // The brief exists — compare each element so the plan reads
+    // element-by-element. `apply` acts on the lead `stage: "instance"`
+    // change, not on these per-element entries.
+    let anyElementChanged = false;
+    for (const element of COMPARED_ELEMENTS) {
+        const before = current[element];
+        const after = desired[element];
+        const path = `brief.${element}`;
+        const meta = { stage: "field", element };
+        if ((0, node_util_1.isDeepStrictEqual)(before, after)) {
+            changes.push({ kind: "noop", path, summary: `${element} unchanged`, meta });
+        }
+        else {
+            anyElementChanged = true;
+            changes.push({ kind: "update", path, summary: `${element}`, before, after, meta });
+        }
+    }
+    // A single PUT converges every changed element at once. Emitted as
+    // the lead change so `apply` finds it without scanning.
+    if (anyElementChanged) {
+        changes.unshift({
+            kind: "update",
+            path: "brief",
+            summary: `Update brief "${desired.name}"`,
+            before: current.name,
+            after: desired.name,
+            meta: { stage: "instance", recipe: desired },
+        });
+    }
+    return { changes };
+};
+exports.diffBriefInstance = diffBriefInstance;

package/dist/brief/recipe/instance-kind.d.ts

@@ -0,0 +1,4 @@
+import type { RecipeKind } from "../../sync";
+import { type BriefInstanceRecipe } from "./instance-schema";
+/** The `brief` recipe kind. */
+export declare const briefInstanceKind: RecipeKind<BriefInstanceRecipe>;