@caelo-cms/shared 0.11.5 → 0.11.7

package/dist/pool-budget.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Issue #1254 — the database connection budget of an install.
+ *
+ * Every Caelo process that talks to Postgres holds connection pools, and
+ * they all draw from ONE server-wide `max_connections` (cms_admin and
+ * cms_public live on the same server). Before #1254 every pool took Bun's
+ * default of 10, so the admin alone asked for `adminMaxInstances × 2 × 10`
+ * — exactly the 100 slots of a default install, with nothing left for the
+ * gateway, the static generator, migrations or the provider's own agents.
+ * Under load the last admin instance to scale up could not connect at all.
+ *
+ * The budget turns that around: provisioning states how many connections
+ * the server has and how many instances may run, every fixed consumer is
+ * named as a {@link PoolBudgetReserve}, and what is left is split across
+ * the admin instances' cms_admin pools — the pool the write path uses.
+ * The admin's cms_public pool is small and fixed: the admin only reads
+ * plugin data there and publishes the gateway projection.
+ *
+ * Why not simply raise the pool: a larger pool only moves the wait from
+ * the pool to the server. A pool sized past the budget fails with "too
+ * many clients" at the worst moment (scale-out under load) instead of
+ * waiting a bounded time for a free connection of its own pool
+ * (query-api pool-guard.ts). docs/dev/connection-budget.md has the long
+ * version.
+ *
+ * Pure module — no I/O. Used by the provisioning stacks (which set the
+ * resulting env on each service) and re-exported by `@caelo-cms/query-api`.
+ */
+/** Env var sizing every pool of a `DatabaseAdapter` (both pools, unless the next one is set). */
+export const DB_POOL_MAX_ENV = "CAELO_DB_POOL_MAX";
+/**
+ * Env var sizing the cms_public pool of a `DatabaseAdapter` on its own. It
+ * wins over {@link DB_POOL_MAX_ENV} for that pool, so the admin can run a
+ * large cms_admin pool next to a small cms_public one.
+ */
+export const DB_PUBLIC_POOL_MAX_ENV = "CAELO_DB_PUBLIC_POOL_MAX";
+/** Smallest pool a `DatabaseAdapter` accepts: one connection self-deadlocks it. */
+export const MIN_POOL_MAX = 2;
+/**
+ * Smallest cms_admin pool the budget hands an admin instance. Below it a
+ * handful of concurrent editors and agents queue on every write; an install
+ * whose server cannot afford it must get a larger tier or fewer instances,
+ * so {@link computePoolBudget} refuses instead of shipping a starved pool.
+ */
+export const ADMIN_POOL_FLOOR = 4;
+/** The admin's cms_public pool: plugin-data reads and the gateway projection. */
+export const ADMIN_PUBLIC_POOL_MAX = 4;
+/** The gateway's only pool (public_role on cms_public), per instance. */
+export const GATEWAY_POOL_MAX = 2;
+/**
+ * Each pool of one static-generator subprocess. A build runs in ONE
+ * transaction (pool-guard.ts LONG_TRANSACTION_ALLOWLIST) and takes no
+ * second checkout, so the minimum pool ({@link MIN_POOL_MAX}) is enough.
+ */
+export const GENERATOR_POOL_MAX = 2;
+/**
+ * #1267 — the dedicated connection each admin instance keeps open for
+ * `LISTEN` on the change journal's wake-up channel. A LISTEN connection is
+ * held for the instance's lifetime and can never serve a query of the pool,
+ * so it is budgeted outside the pools, one per admin instance.
+ */
+export const LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE = 1;
+/**
+ * The connection each gateway instance keeps open for `LISTEN
+ * caelo_gateway_settings` on cms_public (api-gateway server.ts): outside the
+ * gateway's pool, held for the instance's lifetime.
+ */
+export const LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE = 1;
+function positiveInteger(value, name, min) {
+    if (!Number.isInteger(value) || value < min) {
+        throw new Error(`pool budget: ${name} must be an integer >= ${min} (got ${value})`);
+    }
+}
+/**
+ * Split `maxConnections` across every process of the install.
+ *
+ * `adminPoolMax = floor((maxConnections − Σ reserves) / adminMaxInstances)`,
+ * where the reserves are the fixed consumers of {@link PoolBudgetInput} plus
+ * `gateway = gatewayMaxInstances × GATEWAY_POOL_MAX`,
+ * `generator = concurrentBuilds × 2 × GENERATOR_POOL_MAX`,
+ * `listen = adminMaxInstances × LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE`,
+ * `gateway-listen = gatewayMaxInstances × LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE` and
+ * `admin-public = adminMaxInstances × ADMIN_PUBLIC_POOL_MAX`.
+ *
+ * @throws Error naming what to change when the server cannot give every
+ *   admin instance at least {@link ADMIN_POOL_FLOOR} cms_admin connections.
+ *
+ * @example
+ *   computePoolBudget({ maxConnections: 100, adminMaxInstances: 5,
+ *     gatewayMaxInstances: 10, concurrentBuilds: 2, maintenanceReserve: 5,
+ *     migrationsReserve: 2, jobsReserve: 4 }).adminPoolMax // → 7
+ */
+export function computePoolBudget(input) {
+    positiveInteger(input.maxConnections, "maxConnections", 1);
+    positiveInteger(input.adminMaxInstances, "adminMaxInstances", 1);
+    positiveInteger(input.gatewayMaxInstances, "gatewayMaxInstances", 0);
+    positiveInteger(input.concurrentBuilds, "concurrentBuilds", 0);
+    positiveInteger(input.maintenanceReserve, "maintenanceReserve", 0);
+    positiveInteger(input.migrationsReserve, "migrationsReserve", 0);
+    positiveInteger(input.jobsReserve, "jobsReserve", 0);
+    const reserves = [
+        { name: "maintenance", connections: input.maintenanceReserve },
+        { name: "migrations", connections: input.migrationsReserve },
+        { name: "jobs", connections: input.jobsReserve },
+        { name: "generator", connections: input.concurrentBuilds * 2 * GENERATOR_POOL_MAX },
+        { name: "gateway", connections: input.gatewayMaxInstances * GATEWAY_POOL_MAX },
+        {
+            name: "listen",
+            connections: input.adminMaxInstances * LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE,
+        },
+        {
+            name: "gateway-listen",
+            connections: input.gatewayMaxInstances * LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE,
+        },
+        { name: "admin-public", connections: input.adminMaxInstances * ADMIN_PUBLIC_POOL_MAX },
+    ];
+    const reserved = reserves.reduce((sum, r) => sum + r.connections, 0);
+    const forAdmin = input.maxConnections - reserved;
+    const adminPoolMax = Math.floor(forAdmin / input.adminMaxInstances);
+    if (adminPoolMax < ADMIN_POOL_FLOOR) {
+        const needed = reserved + ADMIN_POOL_FLOOR * input.adminMaxInstances;
+        const breakdown = reserves.map((r) => `${r.name} ${r.connections}`).join(", ");
+        throw new Error(`pool budget: max_connections ${input.maxConnections} cannot give each of ${input.adminMaxInstances} admin instances the minimum of ${ADMIN_POOL_FLOOR} cms_admin connections ` +
+            `(reserved: ${breakdown}; ${needed} needed). Raise maxConnections to at least ${needed} (a larger database tier may be required), ` +
+            "or lower adminMaxInstances / gatewayMaxInstances.");
+    }
+    return {
+        adminPoolMax,
+        adminPublicPoolMax: ADMIN_PUBLIC_POOL_MAX,
+        gatewayPoolMax: GATEWAY_POOL_MAX,
+        generatorPoolMax: GENERATOR_POOL_MAX,
+        reserves,
+        unassigned: forAdmin - adminPoolMax * input.adminMaxInstances,
+    };
+}
+/**
+ * The env that sizes `service`'s pools from `budget`, for the stacks to set.
+ * The admin gets both pools; the gateway, whose only pool is cms_public,
+ * gets just that one.
+ */
+export function poolBudgetEnv(budget, service) {
+    if (service === "gateway") {
+        return [{ name: DB_PUBLIC_POOL_MAX_ENV, value: String(budget.gatewayPoolMax) }];
+    }
+    return [
+        { name: DB_POOL_MAX_ENV, value: String(budget.adminPoolMax) },
+        { name: DB_PUBLIC_POOL_MAX_ENV, value: String(budget.adminPublicPoolMax) },
+    ];
+}
+//# sourceMappingURL=pool-budget.js.map

package/dist/pool-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-budget.js","sourceRoot":"","sources":["../src/pool-budget.ts"],"names":[],"mappings":"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"}

package/dist/stage-status.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Issue #1288 — where a Stage's build stands, in one shape for every
+ * surface: the `deploy.stage_status` op returns it, the `get_stage_status`
+ * AI / MCP tool and the "still running" answers of `stage_changes` and
+ * `get_quality_audit` print it, and Settings → Deployments and the Live
+ * Edit Staging menu show it.
+ *
+ * The time left is an estimate with its basis named, never a default
+ * number (CLAUDE.md §2): `eta` is null with `etaUnavailable` saying why
+ * when nothing measured supports one.
+ */
+import { z } from "zod";
+/** Where a Stage run is: waiting, its three steps, or its end. */
+export declare const stagePhaseSchema: z.ZodEnum<{
+    succeeded: "succeeded";
+    failed: "failed";
+    queued: "queued";
+    preparing: "preparing";
+    building: "building";
+    publishing: "publishing";
+}>;
+export type StagePhase = z.infer<typeof stagePhaseSchema>;
+/**
+ * What an estimate of the time left rests on:
+ * - `this_run_rate`: the pages per second this run has built so far;
+ * - `last_successful_run`: how long the recent successful Stages took.
+ */
+export declare const stageEtaBasisSchema: z.ZodEnum<{
+    this_run_rate: "this_run_rate";
+    last_successful_run: "last_successful_run";
+}>;
+export type StageEtaBasis = z.infer<typeof stageEtaBasisSchema>;
+/** An estimate of the time a running Stage still needs. */
+export declare const stageEtaSchema: z.ZodObject<{
+    remainingMs: z.ZodNumber;
+    basis: z.ZodEnum<{
+        this_run_rate: "this_run_rate";
+        last_successful_run: "last_successful_run";
+    }>;
+    includesPublish: z.ZodBoolean;
+}, z.core.$strip>;
+export type StageEta = z.infer<typeof stageEtaSchema>;
+/** One Stage run (a staging site build) as every status surface shows it. */
+export declare const stageStatusRunSchema: z.ZodObject<{
+    runId: z.ZodString;
+    targetName: z.ZodString;
+    status: z.ZodEnum<{
+        running: "running";
+        succeeded: "succeeded";
+        failed: "failed";
+        queued: "queued";
+    }>;
+    phase: z.ZodEnum<{
+        succeeded: "succeeded";
+        failed: "failed";
+        queued: "queued";
+        preparing: "preparing";
+        building: "building";
+        publishing: "publishing";
+    }>;
+    pagesDone: z.ZodNullable<z.ZodNumber>;
+    pagesTotal: z.ZodNullable<z.ZodNumber>;
+    startedAt: z.ZodString;
+    finishedAt: z.ZodNullable<z.ZodString>;
+    elapsedMs: z.ZodNumber;
+    error: z.ZodNullable<z.ZodString>;
+    failedPhase: z.ZodNullable<z.ZodString>;
+    eta: z.ZodNullable<z.ZodObject<{
+        remainingMs: z.ZodNumber;
+        basis: z.ZodEnum<{
+            this_run_rate: "this_run_rate";
+            last_successful_run: "last_successful_run";
+        }>;
+        includesPublish: z.ZodBoolean;
+    }, z.core.$strip>>;
+    etaUnavailable: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type StageStatusRun = z.infer<typeof stageStatusRunSchema>;
+/** A duration for people: "45 s", "1 min 40 s", "12 min". */
+export declare function formatStageDuration(ms: number): string;
+/** "about 1 min 40 s left (from this run's pace)", or why there is no estimate. */
+export declare function describeStageEta(run: Pick<StageStatusRun, "eta" | "etaUnavailable">): string;
+/**
+ * One line for people and the AI, e.g. "Building pages 812 of 1,904 —
+ * about 1 min 40 s left (from this run's pace)" or "Failed in generator
+ * after 1 min 34 s: <reason>".
+ */
+export declare function describeStageRun(run: StageStatusRun): string;
+//# sourceMappingURL=stage-status.d.ts.map

package/dist/stage-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-status.d.ts","sourceRoot":"","sources":["../src/stage-status.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,kEAAkE;AAClE,eAAO,MAAM,gBAAgB;;;;;;;EAO3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;EAAmD,CAAC;AACpF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,2DAA2D;AAC3D,eAAO,MAAM,cAAc;;;;;;;iBAKzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkB/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,6DAA6D;AAC7D,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAOtD;AAOD,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,gBAAgB,CAAC,GAAG,MAAM,CAM5F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAgB5D"}

package/dist/stage-status.js

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Issue #1288 — where a Stage's build stands, in one shape for every
+ * surface: the `deploy.stage_status` op returns it, the `get_stage_status`
+ * AI / MCP tool and the "still running" answers of `stage_changes` and
+ * `get_quality_audit` print it, and Settings → Deployments and the Live
+ * Edit Staging menu show it.
+ *
+ * The time left is an estimate with its basis named, never a default
+ * number (CLAUDE.md §2): `eta` is null with `etaUnavailable` saying why
+ * when nothing measured supports one.
+ */
+import { z } from "zod";
+/** Where a Stage run is: waiting, its three steps, or its end. */
+export const stagePhaseSchema = z.enum([
+    "queued",
+    "preparing",
+    "building",
+    "publishing",
+    "succeeded",
+    "failed",
+]);
+/**
+ * What an estimate of the time left rests on:
+ * - `this_run_rate`: the pages per second this run has built so far;
+ * - `last_successful_run`: how long the recent successful Stages took.
+ */
+export const stageEtaBasisSchema = z.enum(["this_run_rate", "last_successful_run"]);
+/** An estimate of the time a running Stage still needs. */
+export const stageEtaSchema = z.object({
+    remainingMs: z.number().int().nonnegative(),
+    basis: stageEtaBasisSchema,
+    /** False when no successful Stage recorded how long publishing takes: the estimate covers the pages only. */
+    includesPublish: z.boolean(),
+});
+/** One Stage run (a staging site build) as every status surface shows it. */
+export const stageStatusRunSchema = z.object({
+    runId: z.string(),
+    targetName: z.string(),
+    status: z.enum(["queued", "running", "succeeded", "failed"]),
+    phase: stagePhaseSchema,
+    pagesDone: z.number().int().nonnegative().nullable(),
+    pagesTotal: z.number().int().nonnegative().nullable(),
+    startedAt: z.string(),
+    finishedAt: z.string().nullable(),
+    /** Run time so far (running) or in total (finished). */
+    elapsedMs: z.number().int().nonnegative(),
+    /** The failure reason of a failed run. */
+    error: z.string().nullable(),
+    /** The step a failed run stopped in (`generator`, `publish` …), when recorded. */
+    failedPhase: z.string().nullable(),
+    eta: stageEtaSchema.nullable(),
+    /** Why there is no estimate for a queued or running run; null otherwise. */
+    etaUnavailable: z.string().nullable(),
+});
+/** A duration for people: "45 s", "1 min 40 s", "12 min". */
+export function formatStageDuration(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s} s`;
+    const min = Math.floor(s / 60);
+    const rest = s % 60;
+    if (min >= 10 || rest === 0)
+        return `${min} min`;
+    return `${min} min ${rest} s`;
+}
+const BASIS_TEXT = {
+    this_run_rate: "from this run's pace",
+    last_successful_run: "from recent successful Stages",
+};
+/** "about 1 min 40 s left (from this run's pace)", or why there is no estimate. */
+export function describeStageEta(run) {
+    if (run.eta) {
+        const pagesOnly = run.eta.includesPublish ? "" : ", pages only — publishing time unknown";
+        return `about ${formatStageDuration(run.eta.remainingMs)} left (${BASIS_TEXT[run.eta.basis]}${pagesOnly})`;
+    }
+    return `no estimate: ${run.etaUnavailable ?? "nothing measured yet"}`;
+}
+/**
+ * One line for people and the AI, e.g. "Building pages 812 of 1,904 —
+ * about 1 min 40 s left (from this run's pace)" or "Failed in generator
+ * after 1 min 34 s: <reason>".
+ */
+export function describeStageRun(run) {
+    const n = (v) => v.toLocaleString("en-US");
+    switch (run.phase) {
+        case "queued":
+            return `Queued — ${describeStageEta(run)}`;
+        case "preparing":
+            return `Preparing the build (${formatStageDuration(run.elapsedMs)} so far) — ${describeStageEta(run)}`;
+        case "building":
+            return `Building pages ${n(run.pagesDone ?? 0)} of ${n(run.pagesTotal ?? 0)} — ${describeStageEta(run)}`;
+        case "publishing":
+            return `All ${n(run.pagesTotal ?? 0)} pages built, publishing to staging — ${describeStageEta(run)}`;
+        case "succeeded":
+            return `Succeeded in ${formatStageDuration(run.elapsedMs)}${run.pagesTotal === null ? "" : ` (${n(run.pagesTotal)} pages)`}`;
+        case "failed":
+            return `Failed${run.failedPhase ? ` in ${run.failedPhase}` : ""} after ${formatStageDuration(run.elapsedMs)}: ${run.error ?? "no reason recorded"}`;
+    }
+}
+//# sourceMappingURL=stage-status.js.map

package/dist/stage-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-status.js","sourceRoot":"","sources":["../src/stage-status.ts"],"names":[],"mappings":"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"}

package/dist/themes-errors.js

@@ -160,7 +160,7 @@ export class TokenCategoryMismatch extends Error {
     expected;
     got;
     constructor(canonicalPath, expected, got) {
-        super(`TokenCategoryMismatch: '${canonicalPath}' expects a ${expected} value, got a ${got} — re-send with a value matching ${expected}.`);
+        super(`TokenCategoryMismatch: '${canonicalPath}' expects a ${expected} value, got a ${got} — use a value matching ${expected}.`);
         this.name = "TokenCategoryMismatch";
         this.canonicalPath = canonicalPath;
         this.expected = expected;

package/dist/themes-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"themes-errors.js","sourceRoot":"","sources":["../src/themes-errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"themes-errors.js","sourceRoot":"","sources":["../src/themes-errors.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -19,7 +19,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export declare const CAELO_VERSION = "0.11.5";
+export declare const CAELO_VERSION = "0.11.7";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import
@@ -31,7 +31,7 @@ export declare const CAELO_VERSION = "0.11.5";
  *
  * @deprecated use CAELO_VERSION
  */
-export declare const CALEO_VERSION = "0.11.5";
+export declare const CALEO_VERSION = "0.11.7";
 /**
  * Parsed shape — major/minor/patch + optional pre-release tag.
  * Stable interface for callers that need to feature-gate (rare —

package/dist/version.js

@@ -20,7 +20,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export const CAELO_VERSION = "0.11.5";
+export const CAELO_VERSION = "0.11.7";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caelo-cms/shared",
-  "version": "0.11.5",
+  "version": "0.11.7",
   "private": false,
   "license": "MPL-2.0",
   "description": "Shared Zod schemas + types + the two-pass HTML composer used by every Caelo CMS workspace package. Stable enough for plugin authors and embedders to depend on directly.",

package/src/ai-tools.ts

@@ -19,6 +19,7 @@ import {
   forkPlacementContentSchema,
   type ModuleField,
   moduleFieldSchema,
+  newPageTypeSchema,
   pageShortTitleSchema,
   pageTypeSlugSchema,
   setPlacementContentSchema,
@@ -333,6 +334,13 @@ export const chatCreateSessionInput = z
      * draft: an explicit experiment ("try a redesign") or a site migration.
      */
     isolation: z.enum(["experiment", "migration"]).optional(),
+    /**
+     * Issue #1253 — the session is an external agent's (one chat per
+     * agent): the client app it works for ("Claude Code", a token's label).
+     * The chat list groups such chats per client, and Live Edit never picks
+     * one as the operator's own chat.
+     */
+    agentClient: z.string().min(1).max(200).optional(),
   })
   .strict();
 
@@ -584,8 +592,10 @@ export const createTemplateToolInput = z
     html: sourceTextArg(z.string().min(1).max(2_000_000), "html"),
     css: sourceTextArg(z.string().max(2_000_000), "css").default(""),
     layoutId: z.string().uuid().optional(),
-    /** Epic #1107 — the page type (slug) this template serves; omit for the site default. */
+    /** #1276 — exactly one of: the existing page type this template serves… */
     pageType: pageTypeSlugSchema.optional(),
+    /** …or a new page type created with this template as its default. */
+    newPageType: newPageTypeSchema.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
@@ -650,15 +660,12 @@ export const createLayoutToolInput = z
   })
   .strict();
 
+/** #1276 — the default layout only: there is no default template or page type. */
 export const setSiteDefaultsToolInput = z
   .object({
-    defaultLayoutSlug: slugInputSchema.optional(),
-    defaultTemplateSlug: slugInputSchema.optional(),
+    defaultLayoutSlug: slugInputSchema,
   })
-  .strict()
-  .refine((v) => v.defaultLayoutSlug !== undefined || v.defaultTemplateSlug !== undefined, {
-    message: "must provide at least one of defaultLayoutSlug, defaultTemplateSlug",
-  });
+  .strict();
 
 /**
  * P6.7.7 — content-ops follow-ups: clone a page, swap a page's
@@ -674,6 +681,8 @@ export const duplicatePageToolInput = z
     /** #1142 — the copy's breadcrumb label; omitted = newTitle when given, else the source's. */
     newShortTitle: pageShortTitleSchema.optional(),
     targetTemplateId: z.string().uuid().optional(),
+    /** #1276 — the copy's page type (slug); omitted = the source's. */
+    pageType: pageTypeSlugSchema.optional(),
     /** Where the copy sits: a parent page id, or null for the top level.
      *  Omitted = next to the source (same parent). */
     newParentPageId: z.string().uuid().nullable().optional(),
@@ -1073,7 +1082,13 @@ export const bootstrapSiteScaffoldToolInput = z
     templateSlug: z.string().min(1).max(120).optional(),
     /** Display name for the new template. Defaults to `Home template`. */
     templateDisplayName: z.string().min(1).max(256).optional(),
-    /** Whether to pin the new layout+template as site_defaults. Defaults to true. */
+    /**
+     * #1276 — the page type the new template serves (every template has
+     * one). An existing slug joins that type; else the type is created
+     * with the template. Defaults to the `home` page type.
+     */
+    templatePageType: newPageTypeSchema.optional(),
+    /** Whether to pin the new layout as the site's default layout. Defaults to true. */
     setAsDefaults: z.boolean().optional(),
   })
   .strict();