@caelo-cms/shared 0.10.21 → 0.10.23

package/dist/ai-tools.js

@@ -10,7 +10,7 @@
  * silent drops in the handler.
  */
 import { z } from "zod";
-import { MODULE_CSS_MAX, MODULE_HTML_MAX, MODULE_JS_MAX } from "./content.js";
+import { contentInstanceCreateSchema, contentInstanceDeleteSchema, contentInstanceUpdateSchema, forkPlacementContentSchema, MODULE_CSS_MAX, MODULE_HTML_MAX, MODULE_JS_MAX, moduleFieldSchema, setPlacementContentSchema, slugSchema, } from "./content.js";
 /**
  * v0.6.2 — `position` argument shared across the three `add_module_to_*`
  * tools. Accepts either the literal string `"top"` / `"bottom"` OR a
@@ -22,15 +22,49 @@ import { MODULE_CSS_MAX, MODULE_HTML_MAX, MODULE_JS_MAX } from "./content.js";
  * description explicitly says to use bare integers; the coercion
  * removes that ergonomic gotcha while still rejecting non-numeric
  * strings (`"abc"` → still fails the int check cleanly).
+ *
+ * issue #106 (step-13 round-6) — an OUTER preprocess strips one layer of
+ * surrounding matching quotes first. The model occasionally over-quotes the
+ * literal: it emitted `position` as the JSON string `"\"bottom\""` (the
+ * 8-char value including the quote characters), which matched neither union
+ * branch and failed with a bare `Invalid input`. Unwrapping `"bottom"` →
+ * `bottom` (and `"\"0\""` → `0`, which the integer branch then coerces) turns
+ * that recurring first-call rejection into a clean accept. This is input
+ * NORMALISATION at the boundary (decoding a malformed encoding of a value the
+ * caller did supply), not a missing-data fallback — `undefined`/`null`/`""`
+ * still fall through to a loud rejection, per CLAUDE.md §2.
  */
-export const positionInputSchema = z.union([
+function stripSurroundingQuotes(v) {
+    if (typeof v !== "string")
+        return v;
+    // Only when BOTH ends are the same quote char and there is at least one
+    // inner character — so a bare `"bottom"` / `"0"` is untouched and an empty
+    // `""` is not collapsed into a match here.
+    const m = v.match(/^(["'])([\s\S]+)\1$/);
+    return m ? m[2] : v;
+}
+export const positionInputSchema = z.preprocess(stripSurroundingQuotes, z.union([
     z.enum(["top", "bottom"]),
     z.preprocess((v) => (typeof v === "string" && /^\d+$/.test(v) ? Number.parseInt(v, 10) : v), z.number().int().min(0).max(1000)),
-]);
+]));
 export const editModuleToolInput = z
     .object({
     moduleId: z.string().uuid(),
     displayName: z.string().min(1).max(128).optional(),
+    /**
+     * v0.12.0 — rewrite the module's purpose. Optional; passing it
+     * updates the `## Modules` block your future self will read.
+     */
+    description: z.string().max(1000).optional(),
+    /** v0.12.0 — re-classify the module's role tag. */
+    kind: z.enum(["chrome", "hero", "content", "cta", "utility"]).optional(),
+    /**
+     * v0.12.3 (issue #106) — re-classify the module's stable `type` (the
+     * class a parent's `allowedModuleTypes` whitelist matches against,
+     * e.g. `button`). Rarely needed; usually derived from displayName at
+     * create time. Set it to make this module satisfy a parent's allowlist.
+     */
+    type: slugSchema.optional(),
     html: z.string().max(MODULE_HTML_MAX).optional(),
     css: z.string().max(MODULE_CSS_MAX).optional(),
     js: z.string().max(MODULE_JS_MAX).optional(),
@@ -40,17 +74,9 @@ export const editModuleToolInput = z
      * fill these via `set_page_module_content`. Optional on edits — pass
      * to replace the declared schema.
      */
-    fields: z
-        .array(z
-        .object({
-        name: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/),
-        kind: z.enum(["text", "richtext", "url", "image", "number", "boolean", "link"]),
-        label: z.string().min(1).max(128),
-        default: z.unknown().optional(),
-    })
-        .strict())
-        .max(64)
-        .optional(),
+    fields: z.array(moduleFieldSchema).max(64).optional(),
+    /** issue #164 slice 2 — see addModuleToolInput.bindThemeLiterals. */
+    bindThemeLiterals: z.boolean().optional(),
 })
     .strict();
 /**
@@ -75,74 +101,140 @@ export const siteMemoryProposeToolInput = z
 })
     .strict();
 /**
- * The set of tools shipped in P5. Other phases extend by adding a new
- * entry; the dispatcher walks this map at registration time.
- */
-/**
- * P6.7.3 — `add_module_to_page` AI tool. Creates a new module and
- * inserts it into a target page's block at the requested position. The
- * AI passes html (and optionally css/js) and a sluggable displayName;
- * the tool generates a unique slug.
+ * Progressive-disclosure skill loading. The `## Skills` system-prompt block
+ * lists each active skill's slug + description; when a task matches one or
+ * more, the model calls `load_skill({slugs})` to pull their full instructions
+ * into the conversation (they persist as a tool result for the rest of the
+ * chat, so each skill loads at most once).
+ *
+ * Takes a LIST, not a single slug, per CLAUDE.md §11: a load is a routine
+ * operation and every routine operation ships in bulk form, with n=1 as its
+ * smallest case rather than a separate singular tool. Loading three skills was
+ * three provider round-trips whose only output was one tool call each.
+ *
+ * Capped at 5: skills are task-scoped, and a model that wants more than a
+ * handful at once has almost certainly matched the index too loosely — each
+ * body is a sizeable injection into history.
  */
-export const addModuleToPageToolInput = z
+export const loadSkillToolInput = z
     .object({
-    pageId: z.string().uuid(),
-    blockName: z.string().min(1).max(80),
-    /** "top" | "bottom" | a 0-based integer index. */
-    position: positionInputSchema,
-    displayName: z.string().min(1).max(128),
-    html: z.string().min(1).max(50_000),
-    css: z.string().max(50_000).optional(),
-    js: z.string().max(50_000).optional(),
-    /**
-     * v0.5.21 — module field schema (v0.4.0 module/content split). The
-     * AI declares fields here when creating a module that uses `{{name}}`
-     * substitutions; per-page content gets filled via
-     * `set_page_module_content` later. Optional — modules with no
-     * field schema are static HTML.
-     */
-    fields: z
+    slugs: z
         .array(z
-        .object({
-        name: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/),
-        kind: z.enum(["text", "richtext", "url", "image", "number", "boolean", "link"]),
-        label: z.string().min(1).max(128),
-        default: z.unknown().optional(),
-    })
-        .strict())
-        .max(64)
-        .optional(),
+        .string()
+        .min(1)
+        .max(120)
+        .regex(/^[a-z0-9-]+$/, "lowercase letters/digits/hyphens"))
+        .min(1)
+        .max(5),
 })
     .strict();
 /**
- * P6.7.3 — `add_module_to_template` AI tool. Same shape as
- * `add_module_to_page` but fans the new module out to every page using
- * the target template, inserting at the same block + position. Used
- * for "site-wide" content (a global footer, a header banner, etc.).
+ * The set of tools shipped in P5. Other phases extend by adding a new
+ * entry; the dispatcher walks this map at registration time.
+ */
+/**
+ * The ONE `add_module` input — consolidates add_module_to_{page,layout,template}
+ * (audit #2). `target` picks the destination; `targetRef` is a slug OR a uuid
+ * (resolved server-side — a slug is friendlier for the AI to hold than a uuid).
+ * Same two modes as before: `moduleId` reuses an existing module (now for ALL
+ * three targets — layout used to be mint-only), or the authoring fields mint a
+ * new one (raw html is fine — moduleize turns it into a proper module). Exactly
+ * one mode, enforced by the shared superRefine.
  */
-export const addModuleToTemplateToolInput = z
+export const addModuleToolInput = z
     .object({
-    templateId: z.string().uuid(),
+    target: z.enum(["page", "layout", "template"]),
+    /** Slug or uuid of the page / layout / template. Resolved server-side. */
+    targetRef: z.string().min(1).max(200),
     blockName: z.string().min(1).max(80),
     position: positionInputSchema,
-    displayName: z.string().min(1).max(128),
-    html: z.string().min(1).max(50_000),
+    /** Reuse an existing module by id (any target). Mutually exclusive with the
+     *  authoring fields. */
+    moduleId: z.string().uuid().optional(),
+    displayName: z.string().min(1).max(128).optional(),
+    description: z.string().max(1000).optional(),
+    kind: z.enum(["chrome", "hero", "content", "cta", "utility"]).optional(),
+    type: slugSchema.optional(),
+    html: z.string().min(1).max(50_000).optional(),
     css: z.string().max(50_000).optional(),
     js: z.string().max(50_000).optional(),
-    /** v0.5.21 — see addModuleToPageToolInput.fields for context. */
-    fields: z
-        .array(z
-        .object({
-        name: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/),
-        kind: z.enum(["text", "richtext", "url", "image", "number", "boolean", "link"]),
-        label: z.string().min(1).max(128),
-        default: z.unknown().optional(),
-    })
-        .strict())
-        .max(64)
-        .optional(),
+    fields: z.array(moduleFieldSchema).max(64).optional(),
+    bindThemeLiterals: z.boolean().optional(),
+    /**
+     * The placement's initial content, applied IN THE SAME CALL (2026-07
+     * — a freshly minted module must never land empty and wait for a
+     * second round-trip). ONE rule for every target: content goes in
+     * `values`. target='page': fills the placement's content_instance.
+     * target='template': every fanned-out placement gets these values.
+     * target='layout': chrome has no content_instance, so the handler
+     * stores the values as the minted module's `fields[].default` —
+     * which requires explicit `fields` (moduleize field names are
+     * unknowable up front) and is rejected for `moduleId` reuse (a
+     * shared module renders its stored defaults; edit_module changes
+     * them).
+     */
+    values: z.record(z.string(), z.unknown()).optional(),
 })
-    .strict();
+    .strict()
+    .superRefine((input, ctx) => {
+    if (input.target === "layout" && input.values !== undefined) {
+        if (input.moduleId !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "Reusing a module on a layout renders the module's STORED field defaults — `values` has nothing to bind to. Drop `values` (the chrome shows the module as-is), or change the shared copy via edit_module.",
+            });
+        }
+        else if (input.fields === undefined || input.fields.length === 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "target='layout' with `values` needs explicit `fields` — chrome stores the values as field defaults, so the field names must be declared in this call (raw-HTML field inference can't know your value keys).",
+            });
+        }
+        else {
+            const known = new Set(input.fields.map((f) => f.name));
+            const unknown = Object.keys(input.values).filter((k) => !known.has(k));
+            if (unknown.length > 0) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `\`values\` keys [${unknown.join(", ")}] match no declared field — declared: [${[...known].join(", ")}].`,
+                });
+            }
+        }
+    }
+    // `moduleId` is PLACEMENT-ONLY (see the buildPageModuleSchema note): a
+    // placement that CAN succeed must not fail over an extra authoring field
+    // (§1A/§11), so we do NOT reject a moduleId call that also carries authoring
+    // fields. Those fields are not applied here; the tool HANDLER surfaces an
+    // INFO for any ignored field whose value DIFFERS from the module's stored
+    // one, pointing at edit_module — so a dropped change is never silent (§2).
+    if (input.moduleId !== undefined)
+        return;
+    if (input.displayName === undefined || input.html === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Pass either `moduleId` (place an existing module from ## Modules) " +
+                "or `displayName` + `html` (mint a new module).",
+        });
+    }
+    // 2026-07 — a freshly minted module must carry its initial copy IN
+    // THIS call, via `values` on every target (`fields[].default` also
+    // satisfies it — that's where layout values land anyway). Without
+    // either, the placement rendered EMPTY until a second round-trip —
+    // the exact two-step build_page was created to kill. Only enforced
+    // when the caller authored explicit fields; the raw-HTML path goes
+    // through moduleize, which enforces defaults itself.
+    if (input.fields !== undefined &&
+        input.fields.length > 0 &&
+        input.values === undefined &&
+        !input.fields.some((f) => "default" in f && f.default !== undefined)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "A minted module needs its initial content IN THIS CALL: pass `values` " +
+                "({fieldName: value, …}) for this placement, or give the fields `default`s. " +
+                "Without either, the module renders empty placeholders until a second call.",
+        });
+    }
+});
 /**
  * v0.2.16 — `add_plugin_to_page` AI tool. Inserts a plugin's
  * `<div data-caelo-plugin>` placeholder into a page's block via a
@@ -162,30 +254,69 @@ export const addPluginToPageToolInput = z
     position: positionInputSchema,
 })
     .strict();
+// ─── v0.12.0 — content_instances + placement AI tools ─────────────────
+/**
+ * `list_content_instances` — browse the content library. The `placementCount`
+ * returned per row is a blast-radius affordance: the AI can decide whether
+ * to edit a shared instance (propagates everywhere) or fork it first.
+ */
+export const listContentInstancesToolInput = z
+    .object({
+    moduleId: z.string().uuid().optional(),
+    slug: z.string().min(1).max(64).optional(),
+    /** Free-text matches against displayName + slug. Case-insensitive substring. */
+    search: z.string().min(1).max(128).optional(),
+    /** Narrow to "instances referenced from this page" for chat-runner planning. */
+    pageId: z.string().uuid().optional(),
+})
+    .strict();
+export const getContentInstanceToolInput = z
+    .object({
+    id: z.string().uuid(),
+})
+    .strict();
+export const createContentInstanceToolInput = contentInstanceCreateSchema;
+export const setContentInstanceValuesToolInput = contentInstanceUpdateSchema;
+export const deleteContentInstanceToolInput = contentInstanceDeleteSchema;
+export const setPlacementContentToolInput = setPlacementContentSchema;
+export const forkPlacementContentToolInput = forkPlacementContentSchema;
 export const AI_TOOLS = [
     "edit_module",
     "site_memory_propose",
-    "add_module_to_page",
-    "add_module_to_template",
+    "add_module",
     "create_page",
-    "rename_page",
-    "set_page_title",
-    "change_page_slug",
-    "delete_page",
-    "remove_module_from_page",
+    // audit #3 — page metadata (name/title/slug/template/status) is one tool for
+    // 1..200 pages: `update_pages_many`. The former rename_page / set_page_title
+    // / change_page_slug were single-field wrappers over the same pages.update.
+    "update_pages_many",
+    // audit #4 — one delete tool for 1..200 pages, disposition per page.
+    // The former singular delete_page folded in (n=1 is a one-item array).
+    "delete_pages_many",
+    // one remove-module tool routed by target (page|layout).
+    "remove_module_from",
     "set_structured_set",
     "update_theme",
-    "add_module_to_layout",
-    "remove_module_from_layout",
     "set_template_layout",
     "create_layout",
     "set_site_defaults",
     "duplicate_page",
-    "change_template",
+    "repoint_page_template",
     "move_module",
     "reorder_module",
     "set_nav_menu",
     "add_plugin_to_page",
+    // v0.12.0 — content_instances + placement binding
+    "list_content_instances",
+    "get_content_instance",
+    "create_content_instance",
+    "set_content_instance_values",
+    "delete_content_instance",
+    "set_placement_content",
+    "fork_placement_content",
+    // issue #299 — bulk-first build path (§11)
+    "build_page",
+    "create_content_instances",
+    "set_page_module_content_many",
 ];
 /** Chat ops input shapes — used by the SvelteKit form actions. */
 export const chatCreateSessionInput = z
@@ -201,10 +332,38 @@ export const chatCreateSessionInput = z
     parentChatSessionId: z.string().uuid().nullable().optional(),
 })
     .strict();
+/**
+ * issue #190 — an operator-attached image riding a user chat message.
+ * References a media_assets row (the upload endpoint owns validation
+ * + storage); image/* only in v1 so the provider mapping is always an
+ * image part.
+ */
+export const chatAttachmentSchema = z
+    .object({
+    /** Set for an operator upload — a `media_assets` row. */
+    assetId: z.string().uuid().optional(),
+    /**
+     * Set for an AI-produced chat image — an object-store key under
+     * `CHAT_IMAGE_PREFIX`. Deliberately not a media asset: see the prefix's
+     * doc comment. Exactly one of `assetId` / `storageKey` is present.
+     */
+    storageKey: z.string().min(1).max(512).optional(),
+    mime: z.enum(["image/png", "image/jpeg", "image/webp", "image/gif"]),
+    alt: z.string().max(2048).optional(),
+})
+    .strict()
+    .refine((a) => (a.assetId === undefined) !== (a.storageKey === undefined), {
+    message: "exactly one of assetId (operator upload) or storageKey (chat image) must be set",
+});
+/** issue #190 — attachments-per-message cap; bounds provider payload size. */
+export const CHAT_MAX_ATTACHMENTS = 4;
 export const chatSendMessageInput = z
     .object({
     chatSessionId: z.string().uuid(),
-    content: z.string().min(1).max(8000),
+    // Optional as of Plan B: a resume turn (see `resumeApproval`) carries no
+    // operator content — it re-runs the paused gated turn. A refine below
+    // requires exactly one of content / resumeApproval.
+    content: z.string().min(1).max(8000).optional(),
     /** Element-reference chips appended to the message. */
     chips: z
         .array(z
@@ -215,16 +374,45 @@ export const chatSendMessageInput = z
     })
         .strict())
         .default([]),
+    /** issue #190 — operator-attached images (see chatAttachmentSchema). */
+    attachments: z.array(chatAttachmentSchema).max(CHAT_MAX_ATTACHMENTS).default([]),
+    /**
+     * issue #29 — provenance of this turn. 'system' marks an auto-injected
+     * message the operator did NOT type (crawl-completion nudge, post-
+     * approval continuation): the model still receives it as a user turn,
+     * but the UI renders it as a muted status note instead of "You:".
+     * Omitted / undefined = operator-authored.
+     */
+    origin: z.enum(["operator", "system"]).optional(),
     /**
      * P6.7.3 — the active /edit page id, threaded so the chat-runner can
      * compose a Current-page volatile chunk in the system prompt and so
-     * tools that operate on a page (add_module_to_page) know the target
+     * tools that operate on a page (add_module target='page') know the target
      * without a chip. Optional because the standalone chat editor at
      * /content/chat doesn't have a page context.
      */
     activePageId: z.string().uuid().optional(),
+    /**
+     * Plan B (SDK approval gate) — production resume of a paused gated turn.
+     * When set, this is NOT a new operator message: the runner appends the
+     * SDK tool-approval-response (the Owner's in-chat Approve/Reject) to the
+     * paused turn's history and re-runs so the SDK either executes the gated
+     * tool (approved) or lets the model react to the denial. `approvalId` is
+     * the SDK id surfaced on the tool-approval-request ClientEvent.
+     */
+    resumeApproval: z
+        .object({
+        approvalId: z.string().min(1).max(200),
+        approved: z.boolean(),
+        reason: z.string().max(2000).optional(),
+    })
+        .strict()
+        .optional(),
 })
-    .strict();
+    .strict()
+    .refine((d) => d.content !== undefined || d.resumeApproval !== undefined, {
+    message: "content or resumeApproval is required",
+});
 export const chatRenameSessionInput = z
     .object({
     chatSessionId: z.string().uuid(),
@@ -256,6 +444,10 @@ export const chatPublishInput = z
             "pageModuleContent",
             "layout",
             "structuredSet",
+            // v0.11.0 (#45) — themes primitive joins the publish/Stage
+            // surface so chat-branched theme edits replay into live
+            // on chat.publish.
+            "theme",
         ]),
         entityId: z.string().uuid(),
     })
@@ -292,25 +484,6 @@ export const aiProvidersSetInput = z
     apiKey: z.string().min(1).max(500).optional(),
 })
     .strict();
-/**
- * P19 — `compose_from_import` AI tool input. Wraps
- * `imports.compose_from_run`. Single transaction synthesis: aggregates
- * theme tokens, creates one template bound to the default layout,
- * materialises every staged import_pages row into a draft page +
- * modules. Idempotent — pages already accepted skip cleanly.
- */
-export const composeFromImportToolInput = z
-    .object({
-    runId: z.string().uuid(),
-    templateSlug: z
-        .string()
-        .min(1)
-        .max(120)
-        .regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters/digits/hyphens, leading non-hyphen")
-        .optional(),
-    includeImportPageIds: z.array(z.string().uuid()).optional(),
-})
-    .strict();
 /**
  * Input for `ai_providers.clear_key` — Owner-only NULLs the encrypted
  * triplet so the resolver falls back to the env-var path for that
@@ -331,22 +504,6 @@ const slugInputSchema = z
     .min(1)
     .max(120)
     .regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters/digits/hyphens, leading non-hyphen");
-export const createPageToolInput = z
-    .object({
-    name: z.string().min(1).max(256),
-    title: z.string().min(1).max(256),
-    slug: slugInputSchema,
-    locale: z.string().min(2).max(10).default("en"),
-    /**
-     * Optional. When omitted, the underlying `pages.create` op resolves
-     * to `site_defaults.default_template_id` (P6.7.6). The AI should pass
-     * a UUID from `## Site defaults` / `## Templates → layouts` only when
-     * the user asks for a non-default template.
-     */
-    templateId: z.string().uuid().optional(),
-    status: z.enum(["draft", "published"]).default("draft"),
-})
-    .strict();
 /**
  * P18 AI-completeness — `create_template` AI tool input. Wraps
  * `templates.create` (widened to AI in this pass per CLAUDE.md §11
@@ -360,102 +517,51 @@ export const createTemplateToolInput = z
     html: z.string().min(1).max(2_000_000),
     css: z.string().max(2_000_000).default(""),
     layoutId: z.string().uuid().optional(),
+    // Optional block-set metadata, symmetric with create_layout. Omit to
+    // auto-derive blocks from <caelo-slot> tags; pass to set displayName /
+    // position (each name must match a slot). Enforced op-side in
+    // templates.create (loud reject on a slot-less block).
+    blocks: z
+        .array(z.object({
+        name: z.string().min(1).max(80),
+        displayName: z.string().min(1).max(200),
+        position: z.number().int().min(0).max(1000),
+    }))
+        .optional(),
 })
     .strict();
-export const renamePageToolInput = z
-    .object({
-    pageId: z.string().uuid(),
-    newName: z.string().min(1).max(256),
-})
-    .strict();
-export const setPageTitleToolInput = z
-    .object({
-    pageId: z.string().uuid(),
-    newTitle: z.string().min(1).max(256),
-})
-    .strict();
-export const changePageSlugToolInput = z
-    .object({
-    pageId: z.string().uuid(),
-    newSlug: slugInputSchema,
-    /**
-     * `auto` (default): create a 301 from the old slug → new slug.
-     * `skip`: only choose when the user explicitly says they don't
-     * want existing inbound links to redirect.
-     */
-    redirectFromOld: z.enum(["auto", "skip"]).default("auto"),
-})
-    .strict();
-export const deletePageToolInput = z
-    .object({
-    pageId: z.string().uuid(),
-    /** '404' returns a not-found; 'redirect' creates a 301 to redirectTo. */
-    disposition: z.enum(["404", "redirect"]),
-    redirectTo: z.string().min(1).max(500).optional(),
-})
-    .strict()
-    .refine((v) => v.disposition === "404" || (v.redirectTo !== undefined && v.redirectTo.length > 0), {
-    message: "redirectTo is required when disposition='redirect'",
-    path: ["redirectTo"],
-});
-export const removeModuleFromPageToolInput = z
+/**
+ * The ONE remove-module input — `target` picks page vs layout, `targetRef` is a
+ * slug OR a uuid (resolved server-side). Mirrors `add_module` so placement and
+ * un-placement share one shape. (No `template` target: there is no
+ * remove_module_from_template, matching the add-side history.)
+ */
+export const removeModuleFromToolInput = z
     .object({
-    pageId: z.string().uuid(),
+    target: z.enum(["page", "layout"]),
+    targetRef: z.string().min(1).max(200),
     moduleId: z.string().uuid(),
 })
     .strict();
 export const setStructuredSetToolInput = z
     .object({
-    kind: z.enum(["nav-menu", "taxonomy", "theme", "tags", "link-list"]),
+    // v0.10.22 — added "language-selector" to match @caelo-cms/shared
+    // structuredSetKind (the 6th kind that was previously unreachable
+    // from any AI tool — the kind-specific wrappers covered only
+    // nav-menu + theme).
+    kind: z.enum(["nav-menu", "taxonomy", "theme", "tags", "link-list", "language-selector"]),
     slug: slugInputSchema,
     displayName: z.string().min(1).max(200),
     items: z.array(z.unknown()),
 })
     .strict();
-export const updateThemeToolInput = z
-    .object({
-    /** Map of token name to value. Merges into the existing theme/site set. */
-    tokens: z.record(z.string(), z.string()),
-})
-    .strict();
-/**
- * P6.7.6 — layout-layer tools. Layouts are site-wide chrome (header /
- * footer / nav) that wraps every page on every template bound to the
- * layout. `add_module_to_layout` reaches every page across the site
- * with one call; `set_template_layout` re-points a template's chrome.
- * `create_layout` and `set_site_defaults` are Owner-only at the op
- * level — AI calls reject with ActorScopeRejected and the chat surfaces
- * the permission requirement.
- */
-export const addModuleToLayoutToolInput = z
-    .object({
-    layoutSlug: slugInputSchema,
-    blockName: z.string().min(1).max(80),
-    position: positionInputSchema,
-    displayName: z.string().min(1).max(128),
-    html: z.string().min(1).max(50_000),
-    css: z.string().max(50_000).optional(),
-    js: z.string().max(50_000).optional(),
-    /** v0.5.21 — see addModuleToPageToolInput.fields for context. */
-    fields: z
-        .array(z
-        .object({
-        name: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/),
-        kind: z.enum(["text", "richtext", "url", "image", "number", "boolean", "link"]),
-        label: z.string().min(1).max(128),
-        default: z.unknown().optional(),
-    })
-        .strict())
-        .max(64)
-        .optional(),
-})
-    .strict();
-export const removeModuleFromLayoutToolInput = z
-    .object({
-    layoutSlug: slugInputSchema,
-    moduleId: z.string().uuid(),
-})
-    .strict();
+// v0.10.22 — `updateThemeToolInput` removed. The kind-specific `update_theme`
+// wrapper was replaced by the unified `set_structured_set` surface.
+// v0.11.0 (#45) — theme moved out of structured_sets entirely into its
+// own `themes` primitive (DTCG-shaped jsonb). Theme edits are now
+// `set_theme_tokens` (loose-name patch) / `propose_create_theme`
+// (gated mint) / `propose_activate_theme` (gated flip) — see
+// packages/admin-core/src/ai/tools/{update-theme-tokens,get-theme,…}.ts.
 export const setTemplateLayoutToolInput = z
     .object({
     templateId: z.string().uuid(),
@@ -505,7 +611,7 @@ export const duplicatePageToolInput = z
     locale: z.string().min(2).max(10).optional(),
 })
     .strict();
-export const changeTemplateToolInput = z
+export const repointPageTemplateToolInput = z
     .object({
     pageId: z.string().uuid(),
     newTemplateId: z.string().uuid(),
@@ -544,20 +650,6 @@ export const reorderModuleToolInput = z
     direction: z.union([z.enum(["up", "down"]), z.number().int().min(0).max(1000)]),
 })
     .strict();
-/**
- * Convenience wrapper over `set_structured_set` for the `nav-menu`
- * kind specifically. Users say "edit the menu", not "set the
- * structured set kind=nav-menu" — this maps natural language to the
- * right tool. Items shape matches `navMenuItem` from
- * @caelo-cms/shared/structured-sets.
- */
-export const setNavMenuToolInput = z
-    .object({
-    slug: slugInputSchema,
-    displayName: z.string().min(1).max(200),
-    items: z.array(z.unknown()),
-})
-    .strict();
 /**
  * P7 — `find_media`. Searches the media library by alt-text /
  * filename / mime. Returns up to `limit` matches with the WebP-800
@@ -584,6 +676,22 @@ export const findMediaToolInput = z
     limit: z.number().int().min(1).max(50).default(15),
 })
     .strict();
+/**
+ * run #10 D4 — `regenerate_media_variants`. Recovery tool for the
+ * staging generator's "media references unresolved" failure: re-runs
+ * the image pipeline for the named assets (or every asset with an
+ * incomplete ladder) and reports per-asset what was added or why
+ * nothing could be.
+ */
+export const regenerateMediaVariantsToolInput = z
+    .object({
+    assetIds: z.array(z.string().uuid()).min(1).max(100).optional(),
+    allMissing: z.boolean().default(false),
+})
+    .strict()
+    .refine((v) => (v.assetIds !== undefined) !== v.allMissing, {
+    message: "pass either assetIds or allMissing: true (exactly one)",
+});
 /**
  * P7 — `set_media_alt`. AI may improve a11y on an existing asset
  * without a human round-trip (e.g. when the editor uploaded an image
@@ -596,6 +704,31 @@ export const setMediaAltToolInput = z
     alt: z.string().max(2048),
 })
     .strict();
+/**
+ * 0184 — `set_home_page`. AI designates a page as the site homepage (per
+ * locale, the locale root). Records `locales.home_page_id`; the page keeps
+ * its own slug but resolves to `/`.
+ */
+export const setHomePageToolInput = z
+    .object({
+    pageId: z.string().uuid(),
+    locale: z.string().min(2).max(10).optional(),
+})
+    .strict();
+/**
+ * 0181 — `set_media_source`. AI records an asset's provenance (source
+ * kind + origin detail) and licence when known. All fields but the
+ * assetId are optional; the op COALESCEs so omitted fields stay
+ * unchanged.
+ */
+export const setMediaSourceToolInput = z
+    .object({
+    assetId: z.string().uuid(),
+    sourceKind: z.enum(["upload", "ai_generated", "imported", "external"]).optional(),
+    sourceDetail: z.string().max(2048).optional(),
+    license: z.string().max(200).optional(),
+})
+    .strict();
 /**
  * P8 — `set_page_seo`. Manual / panel writes to the per-page SEO
  * sidecar. AI calls this only on explicit user intent
@@ -687,12 +820,6 @@ export const bulkCreateRedirectsToolInput = z
  * `status='published'`. Use the bulk form for "publish all drafts" or
  * any N>1 flip — saves N round-trips + N snapshot writes + N audit rows.
  */
-export const setPageStatusToolInput = z
-    .object({
-    pageId: z.string().uuid(),
-    status: z.enum(["draft", "published"]),
-})
-    .strict();
 export const setPagesStatusManyToolInput = z
     .object({
     pageIds: z.array(z.string().uuid()).min(1).max(200),
@@ -721,6 +848,7 @@ export const bulkOptimizeSeoToolInput = z
     context: z.string().max(4000).optional(),
 })
     .strict();
+// v0.10.22 — `SetNavMenuToolInput` removed alongside `set_nav_menu` tool.
 /**
  * P9 — locales propose tool schemas. Per CLAUDE.md §11.A all four
  * write paths are TWO-STEP (AI proposes → Owner clicks Approve);
@@ -873,66 +1001,6 @@ export const bootstrapSiteScaffoldToolInput = z
     setAsDefaults: z.boolean().optional(),
 })
     .strict();
-/**
- * v0.6.0 W4 (deferred) — composite tool. Creates a page and attaches N
- * modules to its content block in one tool call, mirroring the way the
- * AI naturally describes a multi-section page: a title + a series of
- * sections, each with its own HTML/CSS. The handler runs the chain
- * server-side so the AI doesn't have to orchestrate create_page +
- * N×add_module_to_page across N+1 round-trips.
- *
- * `sections[]` are placed on the block named in `blockName` (default
- * `content`) in the order given.
- */
-export const composePageFromSpecToolInput = z
-    .object({
-    /** Page identifiers (mirror create_page). */
-    slug: z
-        .string()
-        .min(1)
-        .max(120)
-        .regex(/^[a-z0-9][a-z0-9-]*$/),
-    name: z.string().min(1).max(256),
-    title: z.string().min(1).max(256),
-    locale: z.string().min(2).max(10).optional(),
-    /** Template UUID. Optional — resolves to site_defaults if absent,
-     * yielding the same nextAction recovery as create_page when missing. */
-    templateId: z.string().uuid().optional(),
-    status: z.enum(["draft", "published"]).optional(),
-    /** Block to place the sections in. Defaults to `content`. */
-    blockName: z.string().min(1).max(80).optional(),
-    /** Sections to place, in order. Each becomes a freshly-created module. */
-    sections: z
-        .array(z.object({
-        displayName: z.string().min(1).max(128),
-        html: z.string().min(1).max(50_000),
-        css: z.string().max(50_000).optional(),
-        js: z.string().max(50_000).optional(),
-    }))
-        .min(1)
-        .max(32),
-    /**
-     * v0.6.1 — optional SEO. When supplied, the composite calls
-     * `pages_seo.autofill` after the page is created. When omitted,
-     * the composite auto-derives a meta description from the page
-     * title + first section's displayName (capped at the recommended
-     * length). This is the "invisible-by-default" SEO step — caller
-     * never needs a separate set_page_seo round-trip.
-     *
-     * `metaDescription` overrides the auto-derived fallback. Set
-     * `skipSeo: true` to opt out entirely (e.g., stub pages where
-     * SEO would be noise).
-     */
-    seo: z
-        .object({
-        metaDescription: z.string().min(1).max(320).optional(),
-        ogImageAssetId: z.string().uuid().optional(),
-        skipSeo: z.boolean().optional(),
-    })
-        .strict()
-        .optional(),
-})
-    .strict();
 /**
  * v0.6.0 W4 (deferred) — composite revert. Undoes every snapshot tagged
  * with the given chat's branch_id. Per-entity revert ops handle the