@sitecoreai-labs/sitecoreai-cli 0.2.0 → 0.2.1

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>;

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

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.briefInstanceKind = void 0;
+/**
+ * The `brief` recipe kind — wires the Sitecore Content Operations
+ * Brief instance API into the `sync` engine.
+ *
+ * `ref.id` is the brief's display NAME — recipes identify a brief by
+ * name, not UUID, mirroring how `campaign` identifies a project. The
+ * brief type is referenced by its stable codename (`briefTypeName`)
+ * and resolved to a server id at push-time via `listBriefTypes`.
+ *
+ * `apply` is straight CRUD: `createBrief` when the brief is absent,
+ * `updateBrief` (partial PUT) to converge an existing one. Repointing
+ * an existing brief at a different brief type is refused — the Brief
+ * API has no verified path for that.
+ *
+ * See docs/recipe-sync-architecture.md.
+ */
+const brief_1 = require("../../brief");
+const errors_1 = require("../../shared/errors");
+const client_1 = require("./client");
+const instance_diff_1 = require("./instance-diff");
+const instance_schema_1 = require("./instance-schema");
+/**
+ * Find a brief by its display name, paging the list endpoint until a
+ * match is found or the cursor is exhausted. The Brief list endpoint
+ * supports no server-side name filter (see `ListBriefsQuery`), so the
+ * walk is unavoidable.
+ */
+const findBriefByName = async (client, name) => {
+    let cursor;
+    for (;;) {
+        const page = await (0, brief_1.listBriefs)(client, cursor ? { next: cursor } : undefined);
+        const match = page.data.find((brief) => brief.name === name);
+        if (match)
+            return match;
+        if (!page.next || page.data.length === 0)
+            return null;
+        cursor = page.next;
+    }
+};
+/** Find a brief type by its codename (mirrors `briefTypeKind`'s helper). */
+const findTypeByName = async (client, name) => {
+    const page = await (0, brief_1.listBriefTypes)(client);
+    return page.data.find((type) => type.name === name) ?? null;
+};
+/** Enumerate every brief on the remote — fans out into the aggregate sync. */
+const list = async (ctx) => {
+    const client = await (0, client_1.resolveBriefClient)(ctx);
+    const refs = [];
+    let cursor;
+    for (;;) {
+        const page = await (0, brief_1.listBriefs)(client, cursor ? { next: cursor } : undefined);
+        for (const brief of page.data) {
+            refs.push({ kind: "brief", id: brief.name });
+        }
+        if (!page.next || page.data.length === 0)
+            return refs;
+        cursor = page.next;
+    }
+};
+/** Project a live brief into the recipe shape, dropping server ids/metadata. */
+const toRecipe = (brief, briefTypeName) => ({
+    name: brief.name,
+    briefTypeName,
+    locale: brief.locale || undefined,
+    status: brief.status,
+    isTemplate: brief.isTemplate,
+    fields: brief.fields ?? {},
+});
+/**
+ * Capture a live brief as a recipe. `null` when no brief has the name.
+ *
+ * The list endpoint omits the full nested `fields` map on some
+ * envelopes, so the matched id is re-read via `getBrief` for fidelity.
+ */
+const readCurrent = async (ref, ctx) => {
+    const client = await (0, client_1.resolveBriefClient)(ctx);
+    const found = await findBriefByName(client, ref.id);
+    if (!found)
+        return null;
+    const brief = await (0, brief_1.getBrief)(client, found.id);
+    // Resolve the brief-type codename. The brief carries a `Link` to its
+    // type with the id but not the codename, so a follow-up listTypes
+    // resolves it. If the type has been deleted (orphan brief), surface
+    // the id verbatim so the pulled recipe still round-trips.
+    const types = await (0, brief_1.listBriefTypes)(client);
+    const briefTypeName = types.data.find((type) => type.id === brief.briefType.id)?.name ?? brief.briefType.id;
+    return toRecipe(brief, briefTypeName);
+};
+/** Resolve a recipe's `briefTypeName` to its server id, or fail with a hint. */
+const resolveBriefTypeId = async (client, briefTypeName) => {
+    const type = await findTypeByName(client, briefTypeName);
+    if (!type) {
+        throw (0, errors_1.createScaiError)(`Brief type "${briefTypeName}" not found.`, "INPUT_INVALID", {
+            hint: "Push the brief-type recipe first, or check the `briefTypeName` codename with `scai ops brief types list`.",
+        });
+    }
+    return type.id;
+};
+/** Apply a plan — create the brief, or PUT-patch it onto the desired state. */
+const apply = async (plan, ref, ctx) => {
+    const client = await (0, client_1.resolveBriefClient)(ctx);
+    const applied = [];
+    const skipped = [];
+    // The single `stage: "instance"` change carries the full desired
+    // recipe; per-element `stage: "field"` changes are descriptive only.
+    const instanceChange = plan.changes.find((change) => change.meta?.stage === "instance");
+    if (!instanceChange) {
+        // Nothing to write — an all-noop plan.
+        for (const change of plan.changes)
+            skipped.push(change);
+        return { applied, skipped };
+    }
+    const recipe = instanceChange.meta?.recipe;
+    if (!recipe) {
+        throw (0, errors_1.createScaiError)("Brief plan change is missing its recipe payload.", "INPUT_INVALID", {
+            hint: "This is an internal diff error — change.meta.recipe was not set.",
+        });
+    }
+    if (instanceChange.kind === "create") {
+        const briefTypeId = await resolveBriefTypeId(client, recipe.briefTypeName);
+        const input = {
+            name: recipe.name,
+            briefTypeId,
+            ...(recipe.locale !== undefined && { locale: recipe.locale }),
+            ...(Object.keys(recipe.fields ?? {}).length > 0 && { fields: recipe.fields }),
+            ...(recipe.isTemplate !== undefined && { isTemplate: recipe.isTemplate }),
+        };
+        ctx.logger?.info(`Creating brief "${recipe.name}".`);
+        const created = await (0, brief_1.createBrief)(client, input);
+        // `createBrief` accepts no `status` field — POSTs land in the
+        // server default ("Draft"). If the recipe pins a different status,
+        // converge with a follow-up PUT so the post-apply state matches.
+        if (recipe.status && recipe.status !== created.status) {
+            ctx.logger?.info(`Setting brief "${recipe.name}" status to "${recipe.status}".`);
+            await (0, brief_1.updateBrief)(client, created.id, { status: recipe.status });
+        }
+    }
+    else {
+        const existing = await findBriefByName(client, ref.id);
+        if (!existing) {
+            throw (0, errors_1.createScaiError)(`Brief "${ref.id}" not found.`, "INPUT_INVALID", {
+                hint: "The brief was expected to exist for an update — check the name or push a create.",
+            });
+        }
+        // The Brief API has no verified path to repoint a brief at a
+        // different type. Surface that loudly instead of silently dropping
+        // the change.
+        const types = await (0, brief_1.listBriefTypes)(client);
+        const existingTypeName = types.data.find((type) => type.id === existing.briefType.id)?.name ?? existing.briefType.id;
+        if (existingTypeName !== recipe.briefTypeName) {
+            throw (0, errors_1.createScaiError)(`Cannot repoint brief "${recipe.name}" from type "${existingTypeName}" to "${recipe.briefTypeName}".`, "INPUT_INVALID", {
+                hint: "The Brief API has no verified path to change a brief's type. Delete and recreate the brief, or correct the recipe's briefTypeName.",
+            });
+        }
+        const patch = {
+            name: recipe.name,
+            ...(recipe.locale !== undefined && { locale: recipe.locale }),
+            ...(recipe.isTemplate !== undefined && { isTemplate: recipe.isTemplate }),
+            ...(recipe.status !== undefined && { status: recipe.status }),
+            fields: recipe.fields ?? {},
+        };
+        ctx.logger?.info(`Updating brief "${recipe.name}" (${existing.id}).`);
+        await (0, brief_1.updateBrief)(client, existing.id, patch);
+    }
+    applied.push(instanceChange);
+    // Per-element changes are converged by the single PUT (or POST).
+    for (const change of plan.changes) {
+        if (change === instanceChange)
+            continue;
+        if (change.kind === "noop")
+            skipped.push(change);
+        else
+            applied.push(change);
+    }
+    return { applied, skipped };
+};
+/** Compute the plan to converge a brief onto `desired`. */
+const plan = async (desired, ref, ctx) => (0, instance_diff_1.diffBriefInstance)(desired, await readCurrent(ref, ctx));
+/** The `brief` recipe kind. */
+exports.briefInstanceKind = {
+    name: "brief",
+    schema: instance_schema_1.BriefInstanceRecipeSchema,
+    readCurrent,
+    plan,
+    apply,
+    list,
+};

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

@@ -0,0 +1,61 @@
+/**
+ * `BriefInstanceRecipe` — the declarative definition of a Sitecore
+ * Content Operations *brief instance* (the unit of work — a populated
+ * brief built against a `BriefType` schema).
+ *
+ * Companion to `BriefTypeRecipeSchema` (this file's sibling `schema.ts`,
+ * which models the schema template). Brief instances reference their
+ * type by stable codename (`briefTypeName`) rather than UUID, exactly as
+ * a `campaign` recipe references nothing by id and identifies itself by
+ * `name`. See docs/recipe-sync-architecture.md.
+ *
+ * The schema captures the fields `createBrief` / `updateBrief` accept
+ * on the Brief API — `name`, `briefTypeName`, `locale`, `status`,
+ * `isTemplate`, and the per-field `fields` map. Sub-resources (tasks,
+ * comments, references, contributors, external mappings) are returned
+ * by the read endpoints but are not part of the brief write surface,
+ * so they stay out of the recipe.
+ */
+import { z } from "zod";
+/**
+ * Brief workflow status — the values the Brief API accepts on a write.
+ * Mirrors the `BriefStatus` wire type in `../api/schema.ts`; surfacing
+ * the literal set here means the model reads the enum directly off the
+ * recipe schema (and bad values fail at parse-time, not push-time).
+ *
+ * `InReview` is the wire form for the "In Review" UI label.
+ */
+export declare const BriefInstanceStatusSchema: z.ZodEnum<{
+    Draft: "Draft";
+    InReview: "InReview";
+    Approved: "Approved";
+    Canceled: "Canceled";
+    Archived: "Archived";
+}>;
+/**
+ * Field values on a brief instance, keyed by `BriefField.name`. The
+ * per-field shape varies by field `type` on the brief's type (RichText
+ * values are ProseMirror docs; DateTime is an ISO string; Timeline and
+ * Budget carry their own object shape). The shape is left as
+ * `z.unknown()` so any field type round-trips losslessly between
+ * `recipe pull` and `recipe push` without the recipe schema chasing
+ * the per-field encoding. Validation is deferred to the server.
+ */
+export declare const BriefInstanceFieldsSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+/** The full brief-instance recipe. */
+export declare const BriefInstanceRecipeSchema: z.ZodObject<{
+    name: z.ZodString;
+    briefTypeName: z.ZodString;
+    locale: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        Draft: "Draft";
+        InReview: "InReview";
+        Approved: "Approved";
+        Canceled: "Canceled";
+        Archived: "Archived";
+    }>>;
+    isTemplate: z.ZodOptional<z.ZodBoolean>;
+    fields: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** A validated brief-instance recipe. */
+export type BriefInstanceRecipe = z.infer<typeof BriefInstanceRecipeSchema>;

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

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BriefInstanceRecipeSchema = exports.BriefInstanceFieldsSchema = exports.BriefInstanceStatusSchema = void 0;
+/**
+ * `BriefInstanceRecipe` — the declarative definition of a Sitecore
+ * Content Operations *brief instance* (the unit of work — a populated
+ * brief built against a `BriefType` schema).
+ *
+ * Companion to `BriefTypeRecipeSchema` (this file's sibling `schema.ts`,
+ * which models the schema template). Brief instances reference their
+ * type by stable codename (`briefTypeName`) rather than UUID, exactly as
+ * a `campaign` recipe references nothing by id and identifies itself by
+ * `name`. See docs/recipe-sync-architecture.md.
+ *
+ * The schema captures the fields `createBrief` / `updateBrief` accept
+ * on the Brief API — `name`, `briefTypeName`, `locale`, `status`,
+ * `isTemplate`, and the per-field `fields` map. Sub-resources (tasks,
+ * comments, references, contributors, external mappings) are returned
+ * by the read endpoints but are not part of the brief write surface,
+ * so they stay out of the recipe.
+ */
+const zod_1 = require("zod");
+/**
+ * Brief workflow status — the values the Brief API accepts on a write.
+ * Mirrors the `BriefStatus` wire type in `../api/schema.ts`; surfacing
+ * the literal set here means the model reads the enum directly off the
+ * recipe schema (and bad values fail at parse-time, not push-time).
+ *
+ * `InReview` is the wire form for the "In Review" UI label.
+ */
+exports.BriefInstanceStatusSchema = zod_1.z
+    .enum(["Draft", "InReview", "Approved", "Canceled", "Archived"])
+    .describe('Brief workflow status. Wire form — "InReview" is the "In Review" UI label. A brief must leave "Draft" before it can be linked to a campaign.');
+/**
+ * Field values on a brief instance, keyed by `BriefField.name`. The
+ * per-field shape varies by field `type` on the brief's type (RichText
+ * values are ProseMirror docs; DateTime is an ISO string; Timeline and
+ * Budget carry their own object shape). The shape is left as
+ * `z.unknown()` so any field type round-trips losslessly between
+ * `recipe pull` and `recipe push` without the recipe schema chasing
+ * the per-field encoding. Validation is deferred to the server.
+ */
+exports.BriefInstanceFieldsSchema = zod_1.z
+    .record(zod_1.z.string(), zod_1.z.unknown())
+    .default({})
+    .describe("Field values keyed by BriefField.name. Per-field value shape follows the brief type's field definitions (e.g. RichText is a ProseMirror doc node).");
+/** The full brief-instance recipe. */
+exports.BriefInstanceRecipeSchema = zod_1.z.object({
+    name: zod_1.z
+        .string()
+        .min(1)
+        .describe("Display name of the brief. Identifies the brief when pushing. Briefs are matched by name; the recipe pushes through to `createBrief` / `updateBrief`."),
+    briefTypeName: zod_1.z
+        .string()
+        .min(1)
+        .regex(/^[A-Za-z][A-Za-z0-9_]*$/, "Must start with a letter and contain only letters, digits, or underscores.")
+        .describe("Codename of the brief type this brief is built against — looked up at push-time and resolved to its server id. The brief type must already exist (push the type's recipe first if it doesn't)."),
+    locale: zod_1.z
+        .string()
+        .optional()
+        .describe('Brief locale — BCP-47-ish, e.g. "en-us". Omit to let the server default apply.'),
+    status: exports.BriefInstanceStatusSchema.optional().describe('Brief workflow status. Omit to leave at the server default ("Draft" on creation).'),
+    isTemplate: zod_1.z
+        .boolean()
+        .optional()
+        .describe("Whether the brief is a template (omit to leave at the server default)."),
+    fields: exports.BriefInstanceFieldsSchema,
+});

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

@@ -1,3 +1,4 @@
+import { type CreateBriefInput } from "../api/briefs";
 import { type CreateBriefTypeInput } from "../api/brief-types";
 import type { Brief, BriefComment, BriefStatus, BriefTask, BriefType, PagedResult } from "../api/schema";
 /**
@@ -100,6 +101,40 @@ export declare const runBriefCommentsList: (options: RunBriefBaseOptions & {
     briefId?: string;
     limit?: number;
 }) => Promise<PagedResult<BriefComment>>;
+/**
+ * Create a brief instance from a `CreateBriefInput`. Mirrors
+ * `runBriefTypeCreate` — honours `whatIf` for a plan-only dry run. The
+ * SDK `createBrief` is verified against the Agents tenant.
+ */
+export declare const runBriefCreate: (options: RunBriefBaseOptions & {
+    input: CreateBriefInput;
+    whatIf?: boolean;
+}) => Promise<Brief | {
+    plan: CreateBriefInput;
+}>;
+/**
+ * Update a brief instance by id with a partial patch (`PUT`). Accepts
+ * any subset of `CreateBriefInput` plus an optional `status`. Mirrors
+ * `runBriefTypeUpdate` — honours `whatIf` for a plan-only dry run. The
+ * status-only PUT path is verified (2026-05-15); other partial fields
+ * are wired the same way but not smoke-tested.
+ */
+export declare const runBriefUpdate: (options: RunBriefBaseOptions & {
+    briefId: string;
+    patch: Partial<CreateBriefInput> & {
+        status?: BriefStatus;
+    };
+    whatIf?: boolean;
+}) => Promise<{
+    id: string;
+} | {
+    plan: {
+        id: string;
+        patch: Partial<CreateBriefInput> & {
+            status?: BriefStatus;
+        };
+    };
+}>;
 /**
  * Delete a brief instance. Mirrors `runBriefTypeDelete` — honours
  * `whatIf` for a plan-only dry run. SDK `deleteBrief` is verified