@dotcms/ai 26.10.20-1 → 26.10.21-1

package/tools.esm.js

@@ -0,0 +1,3817 @@
+import { createRuntime } from './runtime.esm.js';
+import { A as AbortError, T as TimeoutError, H as HttpError, N as NetworkError, i as isDotCMSError, V as ValidationError } from './errors.esm.js';
+import { z } from 'zod';
+import 'node:worker_threads';
+import { f as formatSandboxResult } from './format-result.esm.js';
+import { a as CONTEXT_PATHS, t as toRequestPolicy } from './adapter.esm2.js';
+import * as fs from 'node:fs';
+import { constants } from 'node:fs';
+import { realpath, lstat, opendir, stat, access, mkdir, open, rename, rm } from 'node:fs/promises';
+import { sep, posix, resolve, relative, isAbsolute, dirname, join, extname, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Wall-clock deadline applied to every direct `dotcms.request()` a tool makes.
+ *
+ * `createRuntime`'s `timeout` bounds `run()` only; `request()` is documented as having no
+ * surrounding timeout of its own. Without a deadline a wedged instance hangs the tool call
+ * forever — the model gets no error, no result, and no way to tell the difference from slow
+ * work — and `TIMEOUT`, the one unambiguously retryable code, could never be produced.
+ */
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Cap on any single error string handed back to the model.
+ *
+ * A dotCMS 5xx returns its full HTML stack-trace page, tens to hundreds of KB, and
+ * `HttpError.message` embeds the body verbatim. A transfer manifest keeps one message PER
+ * FAILED FILE, so 200 files against a broken instance would otherwise carry 200 copies of
+ * that page in a single tool result.
+ */
+const MAX_ERROR_CHARS = 2_000;
+/**
+ * The tool host is misconfigured — a deployment problem, not a bad tool call.
+ *
+ * Carries its own `code` so it lands in {@link ToolFailure} as `CONFIGURATION` rather than
+ * `UNKNOWN`, which is what lets the model tell "I called this wrong" from "this server
+ * cannot serve anyone right now".
+ */
+class ConfigurationError extends Error {
+    /**
+     * `cause` carries the underlying error for the HOST (e.g. what a token resolver threw). It
+     * is never part of the message, which is what reaches the model.
+     */
+    constructor(message, options) {
+        super(message);
+        this.code = 'CONFIGURATION';
+        this.name = 'ConfigurationError';
+        if (options?.cause !== undefined) {
+            // Standard ES2022 `cause`, assigned defensively for older lib targets.
+            this.cause = options.cause;
+        }
+    }
+}
+/**
+ * Build the runtime one tool call runs against. One place owns the per-request deadline —
+ * so every tool constructs its runtime the same way instead of re-deriving it (and silently
+ * drifting on which options they set).
+ *
+ * Called once per tool invocation, deliberately: the runtime owns its context cache, so a
+ * fresh runtime is what lets the next call see sites, content types or languages the
+ * previous call created. That is also why no session id is threaded through — a runtime
+ * that lives for one call has nothing to key a cache on.
+ */
+function createToolRuntime(config, opts) {
+    let runtime;
+    try {
+        runtime = createRuntime({
+            ...config,
+            timeout: opts?.timeout,
+            includeSpec: opts?.includeSpec
+        });
+    }
+    catch (error) {
+        // `createRuntime` throws e.g. "token is required" when the host passed no token.
+        // Raw, that reads to a model as a problem with ITS call — and the transfer tools' own
+        // descriptions tell it "you do NOT need a dotCMS token, never go looking for them", so
+        // a host misconfiguration would push it toward exactly the credential-hunting those
+        // descriptions forbid. Say plainly whose problem it is.
+        throw new ConfigurationError(`The dotCMS tools are not configured: ${errorMessage(error)}. Whoever runs this ` +
+            `server or agent supplies the dotCMS URL and token, through the tools' dotCMS ` +
+            `connection. This is not a problem with the call and no argument can fix it — ` +
+            `report it and stop; do not look for credentials.`);
+    }
+    const requestTimeout = opts?.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    return {
+        ...runtime,
+        /**
+         * `request` with a default deadline. A caller that passes its own signal keeps full
+         * control and is left alone; otherwise the call is bounded and a deadline hit is
+         * reported as `TIMEOUT` rather than `ABORT`, because the two mean opposite things to
+         * the model — a timeout is worth retrying, a caller-initiated abort is not.
+         */
+        request: (options, reqOpts) => {
+            if (reqOpts?.signal) {
+                return runtime.request(options, reqOpts);
+            }
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), requestTimeout);
+            return runtime
+                .request(options, { signal: controller.signal })
+                .catch((error) => {
+                if (controller.signal.aborted && error instanceof AbortError) {
+                    throw new TimeoutError(`Request ${options.method ?? 'GET'} ${options.path} exceeded the ` +
+                        `${requestTimeout}ms deadline and was aborted. The instance may be ` +
+                        `overloaded or wedged; this is worth retrying.`, requestTimeout);
+                }
+                throw error;
+            })
+                .finally(() => clearTimeout(timer));
+        }
+    };
+}
+/**
+ * Normalize any thrown value to a message string, capped at {@link MAX_ERROR_CHARS}.
+ *
+ * The cap is the point: see MAX_ERROR_CHARS for why an uncapped `HttpError.message` is a
+ * real problem rather than a cosmetic one.
+ */
+function errorMessage(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return raw.length <= MAX_ERROR_CHARS
+        ? raw
+        : `${raw.slice(0, MAX_ERROR_CHARS)}… [truncated, ${raw.length} chars total]`;
+}
+/**
+ * Give a caught error a clearer message, and return that SAME error for the caller to throw.
+ *
+ * For an operation that explains a failure in its own terms ("the save was rejected as a
+ * net-loss conflict…") before rethrowing. Wrapping it in a new `Error` instead loses the
+ * error's class, and with it the `code`, the HTTP `status` and whether a retry can help: a 503
+ * worth retrying reaches the model as `UNKNOWN`, not retryable. Only a non-`Error` throw, which
+ * has no class to keep, becomes a plain `Error`.
+ */
+function withMessage(error, message) {
+    if (error instanceof Error) {
+        error.message = message;
+        return error;
+    }
+    return new Error(message);
+}
+/**
+ * Whether re-issuing the same call could plausibly succeed.
+ *
+ * This is the single most useful thing a tool can tell the calling model, and the one it
+ * cannot work out for itself: a 429 on file 3 of 200 and a permanent 403 read identically
+ * once flattened to a message, so the model either abandons a transfer that would have
+ * succeeded or retries one that never can.
+ */
+function isRetryable(error) {
+    // A deadline hit, or a request that never got a response (refused, reset, DNS): the
+    // instance may be restarting or briefly unreachable, and the same call can succeed.
+    if (error instanceof TimeoutError || error instanceof NetworkError) {
+        return true;
+    }
+    if (error instanceof HttpError) {
+        // 408 Request Timeout and 429 Too Many Requests are explicitly transient; 5xx is the
+        // instance failing rather than the request being wrong. Every other 4xx is the call
+        // itself being wrong, and retrying it unchanged cannot help.
+        return error.status === 408 || error.status === 429 || error.status >= 500;
+    }
+    // ABORT is caller-initiated, VALIDATION/POLICY are the call being wrong, and
+    // SANDBOX/RUNTIME are bugs. None of them improve on a retry.
+    return false;
+}
+/** Stable machine-readable code for any thrown value. */
+function errorCode(error) {
+    if (isDotCMSError(error)) {
+        return error.code;
+    }
+    return error instanceof ConfigurationError ? error.code : 'UNKNOWN';
+}
+/**
+ * Build the failure a tool returns instead of throwing.
+ *
+ * Owns the `[dotCMS - <operation>]` prefix convention in one place rather than as a
+ * template string at each throw site, and preserves the typed detail (`code`, `status`,
+ * `retryable`) that flattening to `.message` used to discard.
+ *
+ * Deliberately NOT a parallel error hierarchy: `formatSandboxResult` remains the layer for
+ * sandbox results (`execute`/`search` already use it). This is only for failures a tool
+ * call raises outside a sandbox result — a direct request, invalid arguments, a host
+ * misconfiguration.
+ */
+function toToolFailure(operation, error, extra) {
+    return {
+        // Caller context goes FIRST, so it can add fields but never overwrite `ok`, `code` or
+        // `retryable` — the fields a model and a host branch on.
+        ...extra,
+        ok: false,
+        operation,
+        error: `[dotCMS - ${operation}]: ${errorMessage(error)}`,
+        code: errorCode(error),
+        retryable: isRetryable(error),
+        ...(error instanceof HttpError ? { status: error.status } : {})
+    };
+}
+/** Whether a tool result is a {@link ToolFailure} rather than the tool's normal result. */
+function isToolFailure(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.ok === false &&
+        typeof value.code === 'string');
+}
+
+/**
+ * Describe the dotCMS instance and identity the tools act as.
+ *
+ * ```ts
+ * const dotcms = dotcmsConnection({ url, token: () => secrets.get('dotcms') });
+ * const tools = [searchTool(dotcms), pageVerifyTool(dotcms)];
+ * ```
+ *
+ * Nothing is read, validated or fetched here — the values are resolved on each tool call.
+ */
+function dotcmsConnection(config) {
+    return Object.freeze({
+        __dotcmsConnection: true,
+        config: Object.freeze({ ...config })
+    });
+}
+/** Whether `value` came from {@link dotcmsConnection}. */
+function isDotCMSConnection(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.__dotcmsConnection === true);
+}
+async function resolveValue(field, value, config) {
+    if (typeof value !== 'function') {
+        return value;
+    }
+    try {
+        return (await value()) ?? '';
+    }
+    catch (error) {
+        // The host's resolver failed (a secrets manager down, say). That is the host's problem,
+        // not the call's — reported as CONFIGURATION. The resolver's own error reaches the host
+        // only through `onResolveError`, never the message the model reads. (`cause` below
+        // stays inside the toolkit: the ToolFailure the tool returns does not carry it.)
+        try {
+            config.onResolveError?.(field, error);
+        }
+        catch {
+            // A throwing hook must not turn a readable CONFIGURATION failure into something else.
+        }
+        throw new ConfigurationError(`The dotCMS connection could not resolve its ${field}. The reason is withheld from ` +
+            `the tool result; whoever runs this server or agent can see it through the ` +
+            `connection's onResolveError hook. This is not a problem with the call and no ` +
+            `argument can fix it — report it and stop; do not look for credentials.`, { cause: error });
+    }
+}
+/**
+ * The URL and token for one call. Throws `ConfigurationError` when the tool was given no
+ * connection at all (a JavaScript caller, or a cast) or a resolver failed; an EMPTY value is
+ * left to `createToolRuntime`, which reports it the same way.
+ */
+async function resolveConnection(connection) {
+    if (!isDotCMSConnection(connection)) {
+        throw new ConfigurationError('The dotCMS tools are not configured: the tool was created without a dotCMS ' +
+            'connection. Whoever builds the tools passes one — searchTool(dotcmsConnection({ ' +
+            'url, token })). This is not a problem with the call and no argument can fix it ' +
+            '— report it and stop; do not look for credentials.');
+    }
+    const [url, token] = await Promise.all([
+        resolveValue('url', connection.config.url, connection.config),
+        resolveValue('token', connection.config.token, connection.config)
+    ]);
+    return { url, token, config: connection.config };
+}
+
+/**
+ * What loading instance context reads. The runtime does it on a tool's behalf, so every tool
+ * that touches context includes these — they are the one endpoint list the toolkit owns.
+ * Every other list lives next to the operation that makes those requests.
+ */
+const CONTEXT_ENDPOINTS = Object.values(CONTEXT_PATHS).map((path) => `GET ${path}`);
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function compile(endpoint) {
+    const space = endpoint.indexOf(' ');
+    const method = endpoint.slice(0, space);
+    const path = endpoint.slice(space + 1);
+    const deep = path.endsWith('/**');
+    const fixed = deep ? path.slice(0, -3) : path;
+    const body = fixed
+        .split(/(\{[^/}]+\})/)
+        .map((part) => (/^\{[^/}]+\}$/.test(part) ? '[^/]+' : escapeRegExp(part)))
+        .join('');
+    return { method, pattern: new RegExp(`^${body}${deep ? '(?:/.*)?' : ''}$`) };
+}
+/** Whether `req` is one of `endpoints`. */
+function matchesEndpoint(endpoints, req) {
+    return endpoints.some((endpoint) => {
+        const { method, pattern } = compile(endpoint);
+        return method === req.method.toUpperCase() && pattern.test(req.path);
+    });
+}
+/**
+ * The policy for a fixed-purpose tool: exactly the endpoints it owns, and nothing else.
+ *
+ * The consumer never configures this — the tool knows what it calls. It is least privilege by
+ * construction: a bug in `page_verify`, or a page path shaped to reach somewhere else, cannot
+ * get past the render and site-lookup endpoints the tool actually needs.
+ */
+function toolPolicy(toolName, endpoints, hint) {
+    return (req) => {
+        if (matchesEndpoint(endpoints, req)) {
+            return true;
+        }
+        // Thrown rather than returned `false`, so the model reads WHY instead of a bare
+        // "rejected by policy" — the request core turns this message into the PolicyError.
+        throw new Error(`The ${toolName} tool can only reach the endpoints it owns, and ${req.method} ` +
+            `${req.path} is not one of them.${hint ? ` ${hint}` : ''}`);
+    };
+}
+/**
+ * The policy for `execute`, where the MODEL chooses the endpoints: the consumer's `allow`
+ * bounds its code, plus the context reads the runtime makes on the tool's behalf — so a narrow
+ * `allow` never silently empties the `sites` / `contentTypes` globals the code relies on.
+ * Those reads expose nothing the code does not already hold as globals.
+ *
+ * No `allow` means no policy: the model's code may call anything the token permits.
+ */
+function modelChosenPolicy(allow) {
+    const consumer = toRequestPolicy(allow);
+    if (!consumer) {
+        return undefined;
+    }
+    return (req) => matchesEndpoint(CONTEXT_ENDPOINTS, req) || consumer(req);
+}
+
+/**
+ * How a tool shows one of its results to the model — the one place that is decided.
+ *
+ * `toText` is the TOOL's declaration that it has a text form, typed against its own result:
+ * nothing is inferred from the value's shape, so a result can never be mistaken for text
+ * because it happens to look like one. A tool without it is shown as structured JSON, and so
+ * is a failure from any tool.
+ */
+function renderToolOutput(toText, output) {
+    if (toText && !isToolFailure(output)) {
+        return { type: 'text', value: toText(output) };
+    }
+    return { type: 'json', value: toJSONValue(output) };
+}
+/**
+ * A value as the JSON it serializes to — what every transport sends and the model receives.
+ * A `Date` becomes its ISO string and an `undefined` field drops out, here rather than out of
+ * sight in the transport. Results are small plain-data manifests, so the round trip is cheap.
+ */
+function toJSONValue(value) {
+    const text = JSON.stringify(value);
+    return text === undefined ? null : JSON.parse(text);
+}
+/** A model output as the text a text-only transport (an MCP `content` block) carries. */
+function modelOutputText(output) {
+    return output.type === 'text' ? output.value : JSON.stringify(output.value, null, 2);
+}
+
+/** Identity helper that infers the generics, so each handler sees its own input type. */
+function defineTool(definition) {
+    return definition;
+}
+/**
+ * Turn a definition, a connection and a consumer's options into the tool a framework
+ * registers.
+ *
+ * Cheap and side-effect free: nothing is resolved or fetched here. The connection is resolved
+ * inside `execute`, on every call — so a host started without credentials still boots and
+ * lists its tools, and each call reports the `CONFIGURATION` problem instead of the host
+ * crashing at startup.
+ *
+ * The one thing checked here is the consumer's own static `allow` list (`executeTool`), which
+ * becomes the tool's policy now: an entry that is not a path throws a `ValidationError`, so a
+ * malformed security boundary fails at startup instead of opening the API (see
+ * `toRequestPolicy`).
+ */
+function createTool(definition, connection, options) {
+    // The tool owns its endpoints; only `execute`'s are the model's to choose and the
+    // consumer's to bound.
+    const policy = definition.endpoints === 'model-chosen'
+        ? modelChosenPolicy(options.allow)
+        : toolPolicy(definition.name, definition.endpoints, definition.endpointHint);
+    // One rendering, two views of it: `toModelOutput` for frameworks that take structured model
+    // output (the AI SDK), `toText` for text-only transports (MCP). They cannot disagree.
+    const render = (output) => renderToolOutput(definition.toText, output);
+    return {
+        name: definition.name,
+        title: definition.title,
+        description: definition.description,
+        inputSchema: definition.inputSchema,
+        annotations: definition.annotations,
+        toModelOutput: ({ output }) => render(output),
+        toText: (output) => modelOutputText(render(output)),
+        async execute(input) {
+            // The trust boundary, same as `defineAdapter`'s `input`: AI SDK and MCP validate
+            // before calling, but a hand-rolled agent loop may not, and a handler must never
+            // see input its schema did not accept. Re-parsing already-valid input is a no-op.
+            const parsed = definition.inputSchema.safeParse(input);
+            if (!parsed.success) {
+                return toToolFailure(definition.name, new ValidationError(`Invalid arguments for "${definition.name}":\n${z.prettifyError(parsed.error)}`, parsed.error.issues));
+            }
+            // A throw that escapes here reaches an MCP client as a PROTOCOL error, or an agent
+            // loop as an exception, rather than as a result the model can read and act on.
+            try {
+                const { url, token, config } = await resolveConnection(connection);
+                const ctx = {
+                    options,
+                    runtime: (runtimeOptions) => createToolRuntime({
+                        url,
+                        token,
+                        allow: policy,
+                        onCall: config.onCall,
+                        onContextError: config.onContextError,
+                        includeStacks: options.includeStacks
+                    }, { ...runtimeOptions, requestTimeout: options.requestTimeout })
+                };
+                return await definition.handler(parsed.data, ctx);
+            }
+            catch (error) {
+                return toToolFailure(definition.name, error);
+            }
+        }
+    };
+}
+
+/** Sandbox wall-clock timeout for `execute` when the factory is given none. */
+const DEFAULT_EXECUTE_TIMEOUT_MS = 45_000;
+const input$1 = z.object({
+    code: z
+        .string()
+        .max(100_000)
+        .describe('JavaScript async function body to execute against the dotCMS API. Use `api.request({ method, path, query, body, formData })` to make authenticated API calls. Use `formData` instead of `body` for multipart/form-data uploads. Return the result.')
+});
+/**
+ * The `execute` tool: the model writes JavaScript, and it runs in the sandbox against the
+ * dotCMS API. Resolves to `{ result }`, the capped text of the code's result (or its error).
+ */
+function executeTool(connection, options = {}) {
+    return createTool(definition$6, connection, options);
+}
+const definition$6 = defineTool({
+    name: 'execute',
+    title: 'Execute dotCMS API Call',
+    inputSchema: input$1,
+    description: `Execute code against the dotCMS REST API. Write JavaScript that runs in an isolated sandbox with the \`api\` adapter for making authenticated HTTP requests.
+
+Use api.request(options) where options is:
+  - method: HTTP method (GET, POST, PUT, DELETE) — default: GET
+  - path: API path (e.g., "/api/v1/content")
+  - query: Query parameters object
+  - body: Request body (auto-serialized to JSON)
+  - formData: Multipart form data object for file uploads (mutually exclusive with body).
+              String values become text fields. Object values { name, type, data|url } become file fields.
+  - headers: Additional headers
+
+Auth is handled automatically — tokens are never exposed to your code.
+
+This is a **JavaScript sandbox, NOT Velocity/VTL**:
+- Velocity variables like \`$dotcontent\`, \`$dotcontent.pull(...)\`, \`$date\`, \`#foreach\` do NOT exist here — referencing \`$dotcontent\` throws \`ReferenceError\`. To query content, call \`api.request({ method: 'POST', path: '/api/content/_search', body: { query, ... } })\`. Run VTL only via \`POST /api/vtl/dynamic\`.
+- **\`await\` every \`api.request\`** and return only JSON-serializable values (objects, arrays, strings, numbers). Returning an un-awaited Promise (or a function/class instance) throws \`DataCloneError\` — the result is structured-cloned out of the worker.
+- Watch string literals: a raw apostrophe inside a single-quoted JS string (e.g. \`'grandchild's'\`) is a \`SyntaxError\`. Use double quotes or escape it.
+
+Pre-loaded instance context (available as globals — no API calls needed to read these):
+  - contentTypes: Array<{ id, name, variable, baseType, host?, folder? }>
+  - sites: Array<{ identifier, hostname, isDefault, archived, live }> — all accessible non-system
+           sites, including stopped and archived states
+  - languages: Array<{ id, languageCode, countryCode, language, country, isoCode }>
+  - currentUser: { userId, email, givenName?, surname?, admin, roles? } | null
+  Examples:
+    const blog = contentTypes.find(c => c.variable === 'Blog');
+    const defaultSite = sites.find(s => s.isDefault);
+    const en = languages.find(l => l.languageCode === 'en');
+
+The pre-loaded globals are a snapshot taken at the start of one tool invocation and do not mutate
+halfway through the current script. Each tool invocation constructs fresh runtime context, so a
+subsequent call sees successful changes to sites, content types, or languages without maintaining
+resource-specific invalidation rules.
+
+Do not use \`PUT /api/v1/site/switch/{id}\` as a targeting mechanism. Tool API requests are
+independent and session-scoped site selection is not guaranteed to carry to the next request.
+Pass explicit site/host identifiers (for example \`host_id\` or \`contentHost\`) instead.
+
+Always use the \`search\` tool first to discover the correct endpoint path and request/response schema before calling \`execute\`.
+
+Transferring file assets? Do NOT use this tool. Use the dedicated \`upload_assets\` /
+\`download_assets\` tools instead — they stream file bytes between disk and dotCMS on the
+server side, so the content never enters your context (and you never need a token or \`.env\`).
+Reach for \`execute\` only for JSON/API work; inlining base64 file bytes here just bloats your
+context. The \`formData\`/base64 path below exists only for small, programmatic payloads — not
+for transferring real files, themes, or directories.
+
+Tips:
+- Output is hard-capped (~25k chars). Use \`pick(arr, fields)\` / \`first(arr, n)\` to return only the fields you need — responses can be very large and are truncated past the cap.
+- For a small programmatic upload (NOT real files — use \`upload_assets\` for those) use \`formData\` with \`{ name, type, data }\` (base64) or \`{ name, type, url }\` (remote URL)
+
+Binary responses (small/programmatic reads only — for real files use \`download_assets\`):
+- Endpoints that return non-text bodies (e.g. GET \`/api/v2/assets/{identifier}\` and \`/dA/{id}\`, content-type \`application/octet-stream\` or \`image/*\`) come back as an envelope: \`{ __dotcmsBinary: true, contentType, base64, byteLength }\`.
+- The \`base64\` field IS the raw file bytes — base64-decode it to recover the exact file. Do NOT treat it as text; the bytes are intact (not UTF-8-mangled).
+- JSON and textual responses (\`text/*\`, xml, js, \`+json\`/\`+xml\`) are returned as parsed objects / strings as before — only binary bodies use the envelope.
+
+Content field variables (the \`contentlet\` fire body):
+- The fire body's \`contentlet\` is keyed by each field's exact **field variable** (from the content type's \`fields[].variable\`) — casing is significant and a wrong-case key is silently ignored (its value is dropped, and a required field then 400s as "required").
+- Page (htmlpageasset) system fields are lowercase/camel exactly: \`contentHost\` (the SITE — NOT \`host\`), \`hostFolder\` (the folder id), \`cachettl\` (all lowercase — NOT \`cacheTTL\`/\`cacheTtl\`), \`template\`, \`url\`, \`title\`, \`friendlyName\`, \`pageTitle\`. \`contentHost\` must be a site **identifier UUID**, not a hostname. Prefer the \`page_create\` tool, which sets all of these correctly.
+- For any content type, read the real field variables first: \`GET /api/v1/contenttype/id/{idOrVar}\` → \`entity.fields[].variable\`. Don't guess.
+
+Block Editor (Story Block) fields:
+- A Story Block field stores a string. When creating or updating content via a fire endpoint, send the field value as an **HTML or Markdown string** — do NOT hand-author the ProseMirror/JSON document. The server converts it to the Block Editor structure **on save**, so the field immediately reads back as structured content.
+- Example: \`{ "contentType": "Blog", "title": "My Post", "body": "<h2>Intro</h2><p>Hello <strong>world</strong>.</p>" }\` — where \`body\` is the Story Block field.
+- Rich blocks are expressed in Markdown as fenced code blocks: the info string is a \`dotcms-*\` label, the body is one JSON object. All keys are lowercase; **bold** keys are required (a payload missing them, or with a wrong-typed required key, silently degrades to a plain code block):
+    - \`dotcms-content\` — embedded contentlet: \`{"identifier": "<contentlet-id>", "languageId": 1}\`. Required: **\`identifier\`**; optional \`languageId\` (default 1). The server rehydrates the full embed data from the identifier on read.
+    - \`dotcms-image\` — dotCMS-bound/decorated image. Required: one of **\`identifier\`** or **\`src\`**; optional \`alt\`, \`title\`, \`href\`, \`target\`, \`textWrap\`, \`textAlign\`, \`languageId\`. Plain external images need no fence — \`![alt](url "title")\` works.
+    - \`dotcms-video\` — Required: one of **\`identifier\`** or **\`src\`**; optional \`mimeType\`, \`width\`, \`height\`, \`languageId\`.
+    - \`dotcms-youtube\` — Required: **\`src\`**; optional \`start\` (seconds), \`width\`, \`height\`.
+    - \`dotcms-grid\` — verbatim \`gridBlock\` node JSON: \`{"type":"gridBlock","attrs":{"columns":[n,n]},"content":[<exactly two gridColumn nodes>]}\`.
+    - \`dotcms-node\` — any other node type verbatim: \`{"type": "<nodeType>", ...}\` (fallback for custom blocks).
+- In HTML, the same labels are custom elements. Scalar payloads ride as attributes with **hyphenated names** (HTML lowercases attribute names, so \`languageId\` is spelled \`language-id\`, \`mimeType\` is \`mime-type\`, etc.): \`<dotcms-content identifier="<contentlet-id>" language-id="1"></dotcms-content>\`. \`dotcms-grid\` and \`dotcms-node\` take the same JSON object as the element's **text body** instead: \`<dotcms-grid>{"type":"gridBlock",...}</dotcms-grid>\` (HTML-escape \`<\` and \`&\` inside JSON string values). Always write an explicit closing tag — HTML parsing ignores the \`/\` in \`<dotcms-video ... />\` and would swallow the content after it.
+- Block styling (e.g. alignment) is an HTML comment on its own line immediately before the block, in Markdown and HTML alike: \`<!-- dotcms:attrs {"textAlign":"center"} -->\`.
+- A Markdown/HTML write **fully replaces** the stored document. If the stored document has rich blocks your value does not carry, the save still succeeds (200) and the response \`messages\` field lists the replaced blocks — read \`messages\` after every fire and carry rich blocks over as \`dotcms-*\` fences (Markdown) or \`<dotcms-*>\` elements (HTML) to preserve them. Invalid payloads degrade to plain code blocks (or are dropped when there is no body to keep), never errors.
+- Identify Story Block fields from the content type (\`fields[].clazz\` is \`...ImmutableStoryBlockField\`).
+
+Workflow fires and Elasticsearch (indexPolicy):
+- All \`/fire\` and \`/firemultipart\` endpoints (e.g. \`/api/v1/workflow/actions/default/fire/PUBLISH\`)
+  accept an \`indexPolicy\` query parameter controlling when Elasticsearch reflects the change:
+    - \`DEFER\`    — default; returns immediately, index may lag by seconds
+    - \`WAIT_FOR\` — waits until the document is indexed before responding
+    - \`FORCE\`    — forces an immediate index flush; expensive, avoid in production
+
+- Use \`WAIT_FOR\` on **every** fire call when:
+    - Chaining multiple workflow actions on the same contentlet, or
+    - Reading state immediately after firing (via \`api.request\`, \`/api/content/_search\`, or GET by inode)
+  Without it, follow-up reads may return stale data.
+
+- Use \`DEFER\` for isolated, one-off fires where nothing depends on immediate index visibility.
+- Reserve \`FORCE\` for debugging and testing only — it is heavy on the cluster.
+
+Velocity \`$dotcontent.pull\` sorting:
+- Pass content field variables in canonical unsuffixed form, e.g. \`Book.title asc\`. The search
+  layer selects the keyword mapping by appending \`_dotraw\` internally.
+- Already-suffixed input such as \`Book.title_dotraw asc\` is accepted for compatibility and is
+  normalized without producing \`_dotraw_dotraw\`.
+
+Workflow action discovery (when you need a workflow action ID):
+- The 'fire' endpoints that take \`{actionId}\` in the path (e.g. PUT /api/v1/workflow/actions/{actionId}/fire and bulk fire) require a workflow action **UUID**, not the system action enum (NEW, EDIT, PUBLISH, …).
+- To find a UUID, call GET /api/v1/workflow/contentlet/{inode}/actions — returns actions firable on that contentlet right now.
+- Without an inode, GET /api/v1/workflow/contenttypes/{contentTypeVarOrId}/system/actions returns the system→action mapping for a content type.
+- To verify an action wires a Move actionlet (required before \`pathToMove\` does anything): GET /api/v1/workflow/actions/{actionId}/actionlets.
+- The /actions/{actionId}/fire endpoint bypasses scheme checks; use it for System Workflow actions (like Move) on content from custom schemes. The /contentlet/actions/bulk/fire endpoint enforces scheme association — input contentlets whose scheme does not own the supplied action are skipped (\`skippedCount\` populated, \`skipReason\` explains).
+
+Helper utilities available: pick(arr, fields), table(arr), count(arr, field), sum(arr, field), first(arr, n)`,
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+    },
+    // The model picks the endpoints here, so the consumer's `allow` bounds them.
+    endpoints: 'model-chosen',
+    // The result IS text (the capped output of the model's code): shown to the model as-is.
+    toText: ({ result }) => result,
+    async handler({ code }, ctx) {
+        // The front door absorbs the executor + adapter + context-cache wiring and injects
+        // dotCMS instance context automatically. Auth tokens never enter the sandbox.
+        const dotcms = ctx.runtime({ timeout: ctx.options.timeout ?? DEFAULT_EXECUTE_TIMEOUT_MS });
+        const result = await dotcms.run(code); // code === the model's output
+        return {
+            result: formatSandboxResult(result, {
+                truncationHint: 'Return only the fields you need — use pick(arr, fields) and first(arr, n).'
+            })
+        };
+    }
+});
+
+/**
+ * Search only reads the bundled spec plus the instance context, so it gets a short leash —
+ * a query that runs longer than this is walking far more of the spec than it should.
+ */
+const SEARCH_TIMEOUT_MS = 10_000;
+const input = z.object({
+    code: z
+        .string()
+        .max(100_000)
+        .describe('JavaScript async function body. The `spec` global contains the filtered dotCMS OpenAPI spec (`$ref`-based: `spec.paths` + `spec.components.schemas`). Return the data you need.')
+});
+/**
+ * The `search` tool: the model writes JavaScript that explores the bundled OpenAPI spec.
+ * Read-only. Resolves to `{ result }`, the capped text of the code's result (or its error).
+ */
+function searchTool(connection) {
+    return createTool(definition$5, connection, {});
+}
+const definition$5 = defineTool({
+    name: 'search',
+    title: 'Search dotCMS API Spec',
+    inputSchema: input,
+    description: `Explore the dotCMS REST API specification. Write JavaScript that runs in a sandbox with the \`spec\` global.
+
+Spec structure:
+- \`spec.paths\` — object keyed by path string (e.g. "/api/v1/contenttype")
+- Method keys are lowercase: get, post, put, delete
+- Each operation has: summary, parameters, requestBody, responses
+- \`requestBody.content\` / \`responses[status].content\` are keyed by MIME type (e.g. "application/json"), then \`.schema\` for the body shape — \`.schema\` is usually a \`$ref\` like \`{ $ref: '#/components/schemas/PageView' }\`, NOT an inline object
+- \`parameters\` is an array of { name, in, required, schema } — "in" is "query", "path", or "header"
+- \`responses\` keys are HTTP status codes
+- \`spec.components.schemas\` — every schema referenced by the kept endpoints, keyed by name
+
+Resolving \`$ref\`s: call \`resolveRef(schemaOrName, depth = 2)\` — it resolves a \`$ref\` (or a schema name) against \`spec.components.schemas\`, expanding nested refs \`depth\` levels and leaving deeper ones as \`$ref\` strings for a follow-up query. Use it instead of hand-walking refs.
+
+Helpers available here: \`resolveRef(schemaOrName, depth)\`, \`pick(arr, fields)\`, \`table(arr)\`, \`count(arr, field)\`, \`sum(arr, field)\`, \`first(arr, n)\`.
+
+Output is hard-capped (~25k chars). Return only what you need — resolve one schema at a bounded depth, not the whole spec.
+
+This spec is a CURATED allow-list of the supported authoring endpoints — not every dotCMS endpoint is present, and that is deliberate. Treat it as the set of endpoints you should use. So:
+- **Guard path access:** \`spec.paths['/x']\` may be \`undefined\`, and \`spec.paths['/x'].get\` on a missing path throws \`TypeError: Cannot read properties of undefined\`. Always use optional chaining: \`spec.paths['/x']?.get\`, or check \`if (!spec.paths['/x']) return 'not in spec'\` first.
+- **Discover before assuming:** to find a path, filter the keys — \`Object.keys(spec.paths).filter(p => p.includes('template'))\` — rather than guessing an exact string.
+- **Absent usually means "not the intended path."** If an endpoint isn't here, first look for a supported one that does the job (search the keys; a different path or verb often covers it). Reaching for an off-list endpoint should be a last resort for a genuine gap, not a reflex — the curated set is what these tools are designed and tested around.
+
+Pre-loaded instance context (also available as globals here):
+  - contentTypes, sites, languages, currentUser
+  Use these to cross-reference spec endpoints with what the connected instance actually has.
+
+Examples:
+  // endpoint summary + param names
+  const op = spec.paths['/api/v1/contenttype'].get
+  return { summary: op.summary, params: op.parameters?.map(p => p.name) }
+
+  // the request-body schema of an endpoint, one level deep
+  return resolveRef(spec.paths['/api/v1/contenttype'].post.requestBody.content['application/json'].schema, 1)
+
+  // a named schema, two levels deep
+  return resolveRef('ContentType', 2)
+
+When inspecting workflow \`fire\` operations, always check the \`indexPolicy\` query parameter and its allowed values. When the \`execute\` tool needs to chain multiple fire calls, or fire and then immediately read content, use \`indexPolicy=WAIT_FOR\` to ensure the index is updated before the next operation runs.
+
+Common recipes:
+- **Find a workflow action ID for a contentlet:** call GET /api/v1/workflow/contentlet/{inode}/actions — direct lookup of actions firable on this contentlet right now. The \`workflowActionId\` returned here is the UUID required by PUT /api/v1/workflow/actions/{actionId}/fire and PUT /api/v1/workflow/contentlet/actions/bulk/fire. **Do not** pass system-action enum values (NEW, EDIT, PUBLISH, …) as the action ID; those are only valid for the /default/fire/{systemAction} endpoints.
+- **Find actions for a content type when you don't have an inode:** GET /api/v1/workflow/contenttypes/{contentTypeVarOrId}/system/actions.
+- **Verify what an action actually does (e.g. whether it has a Move actionlet wired):** GET /api/v1/workflow/actions/{actionId}/actionlets.
+- **Move content:** the system action enum has no MOVE; \`pathToMove\` only works on actions with the Move actionlet. Discover the right action via the recipes above, then PUT /api/v1/workflow/actions/{actionId}/fire with \`pathToMove\` in the body, or use bulk fire with \`additionalParams.additionalParamsMap._path_to_move\`.`,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    },
+    // The sandbox hands the model's code the same `api` adapter `execute` gets, so without
+    // this a "read-only" search could write. It may read the context it is given, nothing more.
+    endpoints: CONTEXT_ENDPOINTS,
+    // The result IS text (the capped output of the model's code): shown to the model as-is.
+    toText: ({ result }) => result,
+    endpointHint: 'search is read-only: its code explores the bundled `spec` and the pre-loaded context. ' +
+        'Use the `execute` tool to call the dotCMS API.',
+    async handler({ code }, ctx) {
+        // Dynamic, like the runtime's own `includeSpec` load: the ~400KB spec is only pulled
+        // in by a host that actually calls search, not by every importer of the tools.
+        const { getSpec } = await import('./spec.esm2.js');
+        const spec = getSpec();
+        if (!spec || typeof spec !== 'object' || Object.keys(spec).length === 0) {
+            return {
+                result: 'Error: OpenAPI spec is not available. The server may not have been built with a generated spec (run the generate-spec step), so the search tool cannot run.'
+            };
+        }
+        // The front door injects the instance context AND the `spec` global (includeSpec).
+        const dotcms = ctx.runtime({ timeout: SEARCH_TIMEOUT_MS, includeSpec: true });
+        const result = await dotcms.run(code);
+        return {
+            result: formatSandboxResult(result, {
+                truncationHint: 'Use resolveRef(schemaOrName, depth) to expand one schema at a bounded depth.'
+            })
+        };
+    }
+});
+
+/**
+ * Whether a contentlet is published.
+ *
+ * THROWS on a failed read, and that is the contract callers depend on rather than an
+ * oversight. The two previous copies disagreed here: one swallowed every error into `false`,
+ * which conflates "this is not live" with "we could not find out" — and for the transfer
+ * manifest those are opposite conclusions, since a read failure reported as not-live sends
+ * the caller off to re-publish assets that were already fine. `upload-assets` needs the
+ * distinction, so the shared primitive is the honest one and the caller that wants a
+ * best-effort answer catches for itself.
+ */
+async function isContentLive(dotcms, identifier) {
+    const response = (await dotcms.request({
+        path: `/api/v1/content/${encodeURIComponent(identifier)}`,
+        query: { depth: 0 }
+    }));
+    const entity = response.entity;
+    // A fire response wraps the contentlet under `contentlets[0]`; a plain read does not.
+    const contentlet = entity?.contentlets?.[0] || entity;
+    return contentlet?.live === true;
+}
+
+/**
+ * Normalization for the page paths callers hand to the page tools.
+ *
+ * Shared because all three tools build a request URL by interpolating a caller-supplied path
+ * into an endpoint template — `/api/v1/page/render${uri}`, `/api/v1/page/json${uri}` — and
+ * only `page_create` was normalizing first. The two that were not had a live correctness bug
+ * and a latent security one:
+ *
+ *   - Live today: `page_verify({ path: '/a/../b' })` renders `/b` while the manifest reports
+ *     `/a/../b`, and a `#` silently truncates the path. The tool's whole job is to report on
+ *     the page it actually checked, so reporting a different path than it read is a
+ *     correctness failure, not a cosmetic one.
+ *   - Latent: `requestCore` policy-checks the RAW request string and normalizes afterwards,
+ *     so a path like `/../../../../api/v1/users/current` would pass an `/api/v1/page/` prefix
+ *     allowlist and then resolve somewhere else entirely. No `allow` policy is configured
+ *     today, which is the only reason this is not already exploitable — and adding one is the
+ *     natural next hardening step for this tool surface.
+ */
+/** The percent-decoded segments of a page path, with encoded separators refused. */
+function decodeSegments(pathname, original, label) {
+    const segments = pathname
+        .split('/')
+        .filter(Boolean)
+        .map((segment) => decodeSegment(segment, original, label));
+    // Splitting first does not make an encoded slash inert: every caller rebuilds a path by
+    // joining these segments, which turns it straight back into a path boundary. dotCMS
+    // folder names cannot contain a separator anyway, so nothing legitimate is refused.
+    const smuggled = segments.find((segment) => segment.includes('/'));
+    if (smuggled !== undefined) {
+        throw new ValidationError(`${label} segment "${smuggled}" contains an encoded path separator (%2F), which ` +
+            `would silently resolve to a DIFFERENT path than the one named: "${original}" ` +
+            `would behave as if the slash had been written literally. dotCMS folder names ` +
+            `cannot contain "/", so write the path out plainly instead.`);
+    }
+    return segments;
+}
+/**
+ * Percent-decode one segment. A malformed escape (`%zz`, a lone `%`) is the caller's input
+ * being wrong, so it is reported as that rather than as the bare `URIError` it throws.
+ */
+function decodeSegment(segment, original, label) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        throw new ValidationError(`${label} has a malformed percent-encoding in segment "${segment}": "${original}"`);
+    }
+}
+/** Run a path through the URL API, collapsing `.`/`..` and dropping any query or fragment. */
+function toPathname(trimmed, original, label) {
+    // Collapse a leading `//` FIRST. To the URL API a `//` prefix is scheme-relative, so it
+    // reads the next segment as a HOST: `new URL('//books/index', 'http://_').pathname` is
+    // `/index`, silently discarding `books` — a page path resolving to a different page with
+    // nothing to indicate it. (`///` does not even parse.) Callers reach this legitimately,
+    // since `//host/path` is how dotCMS writes a host-qualified path elsewhere.
+    const withoutSchemeRelative = trimmed.replace(/^\/+/, '/');
+    try {
+        // The base is a throwaway — only `pathname` is read back out, so the host never leaks
+        // into the result.
+        return new URL(withoutSchemeRelative, 'http://_').pathname;
+    }
+    catch {
+        throw new ValidationError(`${label} is not a valid path: "${original}"`);
+    }
+}
+/**
+ * The canonical form of a page path: leading slash, `.`/`..` collapsed, query and fragment
+ * dropped, percent-encoding decoded, encoded separators refused.
+ *
+ * Returned so the CALLER can report what it actually requested. A tool that normalizes for
+ * the request but echoes the raw input in its manifest is telling the model about a page it
+ * did not look at.
+ */
+function normalizePagePath(path, label = 'path') {
+    const trimmed = path.trim();
+    if (!trimmed) {
+        throw new ValidationError(`${label} must not be empty.`);
+    }
+    const withSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    const segments = decodeSegments(toPathname(withSlash, path, label), path, label);
+    if (segments.length === 0) {
+        return '/';
+    }
+    // Re-encode each segment so the result is a valid URL path again: decoding happened only
+    // to inspect the segments, and a space or `#` left raw here would break the request URL
+    // this feeds. `encodeURIComponent` escapes `/` too, which is exactly right — a slash
+    // inside a single segment is the case refused above.
+    return `/${segments.map((segment) => encodeURIComponent(segment)).join('/')}`;
+}
+/**
+ * Split a page-relative URL into the parent folder and the leaf url stored on the page.
+ *
+ *   "/books/index" → { folder: "/books", url: "index", fullPath: "/books/index" }
+ *   "/books"       → { folder: "/books", url: "index", fullPath: "/books/index" }
+ *   "/about-us/"   → { folder: "/about-us", url: "index", fullPath: "/about-us/index" }
+ *   "/"            → { folder: "/", url: "index", fullPath: "/index" }
+ *
+ * Shares its normalization with {@link normalizePagePath} but NOT its output: the folder-vs-leaf
+ * decision is page-create's alone. The URL API preserves a trailing slash but does not know that
+ * "/about-us/" means a folder index while "/about-us" means a leaf url, and dotCMS pages always
+ * have a leaf url (commonly "index"), so a path with no explicit leaf gets one — matching how the
+ * admin UI and the rest of the platform address a folder's default page.
+ *
+ * Segments are returned DECODED here, because they become folder and page names rather than
+ * parts of a URL.
+ */
+function splitUrlPath(urlPath) {
+    const trimmed = urlPath.trim();
+    if (!trimmed.startsWith('/')) {
+        throw new ValidationError(`urlPath must start with "/": "${urlPath}"`);
+    }
+    const pathname = toPathname(trimmed, urlPath, 'urlPath');
+    const segments = decodeSegments(pathname, urlPath, 'urlPath');
+    // No segments → the site root; the page is the root index.
+    if (segments.length === 0) {
+        return { folder: '/', url: 'index', fullPath: '/index' };
+    }
+    // A trailing slash means the whole path IS the folder and the page is its index. Otherwise the
+    // last segment is the leaf url and everything before it is the folder. (segments is non-empty
+    // here — the length===0 case returned above.)
+    if (!pathname.endsWith('/')) {
+        const url = segments[segments.length - 1];
+        const folderSegments = segments.slice(0, -1);
+        const folder = folderSegments.length ? `/${folderSegments.join('/')}` : '/';
+        const fullPath = `${folder === '/' ? '' : folder}/${url}`;
+        return { folder, url, fullPath };
+    }
+    const folder = `/${segments.join('/')}`;
+    return { folder, url: 'index', fullPath: `${folder}/index` };
+}
+
+/**
+ * Every endpoint this module calls. Each operation that resolves a site or language includes
+ * these in its own list. `resolve.spec.ts` checks every request against them.
+ */
+const RESOLVE_ENDPOINTS = [
+    'GET /api/v1/site',
+    'GET /api/v1/site/{identifier}',
+    'GET /api/v2/languages'
+];
+/**
+ * Resolution of the instance references a caller can name: sites and languages.
+ *
+ * ONE RULE runs through this file: **the session context cache is a fast path, never a
+ * gate.** `loadContext()` loads sites/languages/content-types once per session, and every
+ * loader inside it catches its own failure and returns an empty array (see
+ * `sdk/ai/src/adapter/context.ts`). So a transient 500, an expired token, or a permission
+ * quirk during that one load leaves the cache permanently empty for the session — and the
+ * tools that gated on it then rejected every call with "Available sites: (none found)",
+ * including for the default site and for a caller passing a correct site IDENTIFIER.
+ *
+ * That failure mode is worse than the problem the cache was solving. A cached list is a
+ * useful accelerator and a good source of candidate names for an error message; it is not
+ * evidence that something does not exist. Every resolver here therefore tries the cache
+ * first, falls back to asking dotCMS directly, and only fails when the instance itself says
+ * no — at which point the message distinguishes "this does not exist" from "the session
+ * context never loaded".
+ */
+/** A dotCMS identifier is a 36-char UUID; anything else a caller passes is a name. */
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function looksLikeIdentifier(value) {
+    return UUID_PATTERN.test(value.trim());
+}
+function asRecord$1(value) {
+    return value && typeof value === 'object' ? value : undefined;
+}
+function entityOf(response) {
+    const record = asRecord$1(response);
+    return record && 'entity' in record ? record['entity'] : response;
+}
+function readString(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' && value ? value : undefined;
+}
+/** Project a raw site payload onto {@link ResolvedSite}, or undefined if it has no identifier. */
+function toResolvedSite(raw) {
+    const record = asRecord$1(raw);
+    const identifier = readString(record, 'identifier');
+    if (!identifier) {
+        return undefined;
+    }
+    return {
+        identifier,
+        hostname: readString(record, 'hostname') ??
+            readString(record, 'hostName') ??
+            readString(record, 'siteName') ??
+            identifier
+    };
+}
+/**
+ * Resolve a site (hostname OR identifier) to its identifier + hostname.
+ *
+ * Order is deliberate — cheapest and least fallible first:
+ *   1. the session cache, when it actually has sites;
+ *   2. a direct `GET /api/v1/site/{id}` when the caller gave something UUID-shaped;
+ *   3. a filtered `GET /api/v1/site` lookup by hostname.
+ *
+ * Step 2 matters most for the reported failure: a caller who already knows the identifier
+ * should never be blocked by a cache, because the identifier is precisely what the
+ * downstream call needs and no lookup is required to use it.
+ */
+async function resolveSite(dotcms, site) {
+    const wanted = site.trim();
+    if (!wanted) {
+        throw new ValidationError('Site must be a non-empty hostname or identifier.');
+    }
+    const cached = await siteFromCache(dotcms, wanted);
+    if (cached) {
+        return cached;
+    }
+    const live = await siteFromApi(dotcms, wanted);
+    if (live) {
+        return live;
+    }
+    throw new ValidationError(await siteNotFoundMessage(dotcms, wanted));
+}
+/**
+ * The instance's default site — what a path with no `//host` prefix means.
+ *
+ * The session cache first; then `GET /api/v1/site/defaultSite`, so a failed context load does
+ * not leave the caller unscoped. A failure of that read propagates as the instance error it is:
+ * falling back to "no site" would silently widen whatever the caller was about to scope.
+ */
+async function resolveDefaultSite(dotcms) {
+    const { sites } = await safeContext(dotcms);
+    const cached = sites.find((entry) => entry.isDefault);
+    if (cached) {
+        return { identifier: cached.identifier, hostname: cached.hostname };
+    }
+    const live = toResolvedSite(entityOf(await dotcms.request({ path: '/api/v1/site/defaultSite' })));
+    if (!live) {
+        throw new Error('The instance did not return a default site (GET /api/v1/site/defaultSite).');
+    }
+    return live;
+}
+async function siteFromCache(dotcms, wanted) {
+    const { sites } = await safeContext(dotcms);
+    const match = sites.find((entry) => entry.identifier === wanted || entry.hostname?.toLowerCase() === wanted.toLowerCase());
+    return match ? { identifier: match.identifier, hostname: match.hostname } : undefined;
+}
+async function siteFromApi(dotcms, wanted) {
+    if (looksLikeIdentifier(wanted)) {
+        try {
+            const resolved = toResolvedSite(entityOf(await dotcms.request({ path: `/api/v1/site/${encodeURIComponent(wanted)}` })));
+            if (resolved) {
+                return resolved;
+            }
+        }
+        catch (error) {
+            // A 404 means this identifier genuinely does not exist — fall through to the
+            // hostname search, which will also miss, and report not-found properly. Any other
+            // failure is an instance problem and must not be reported as "site not found".
+            if (!(error instanceof HttpError) || error.status !== 404) {
+                throw error;
+            }
+        }
+    }
+    try {
+        const raw = entityOf(await dotcms.request({
+            path: '/api/v1/site',
+            query: { filter: wanted, per_page: 50, page: 1 }
+        }));
+        const candidates = Array.isArray(raw) ? raw : [];
+        // The endpoint filters by substring, so `demo` also returns `demo-backup`. Only an
+        // exact hostname (or identifier) match may be accepted — silently picking a
+        // near-miss would write content to the wrong site.
+        for (const candidate of candidates) {
+            const resolved = toResolvedSite(candidate);
+            if (resolved &&
+                (resolved.identifier === wanted ||
+                    resolved.hostname.toLowerCase() === wanted.toLowerCase())) {
+                return resolved;
+            }
+        }
+    }
+    catch (error) {
+        // Only a 404 is a miss, and falls through to the not-found message. Anything else — a
+        // 503, a rejected token, no response at all — says nothing about whether the site
+        // exists, and reported as "not found" it would be VALIDATION: the model told its input
+        // is wrong and not to retry, when retrying (or fixing credentials) is the answer.
+        if (!(error instanceof HttpError) || error.status !== 404) {
+            throw error;
+        }
+    }
+    return undefined;
+}
+/** Explain a miss WITHOUT implying the instance has no sites when the cache simply failed. */
+async function siteNotFoundMessage(dotcms, wanted) {
+    const { sites } = await safeContext(dotcms);
+    if (sites.length === 0) {
+        return (`Site "${wanted}" could not be resolved, and this session's site list is empty — ` +
+            `which usually means the one-time context load failed (a transient error or a ` +
+            `permissions problem), NOT that the instance has no sites. A direct lookup was ` +
+            `also tried and did not find it. Verify the site exists and that the configured ` +
+            `token can read it; if the site is correct, retrying the call reloads the ` +
+            `context — every tool call starts from a fresh runtime.`);
+    }
+    const available = sites.map((entry) => entry.hostname).join(', ');
+    return (`Site "${wanted}" was not found (neither a known hostname nor a site identifier), ` +
+        `and a direct lookup did not find it either. Available sites: ${available}.`);
+}
+/**
+ * Resolve a language id against the instance.
+ *
+ * dotCMS silently falls back to its default language for an unknown id rather than
+ * rejecting it, so an unrecognised id does not fail — it quietly writes to a DIFFERENT
+ * language than the caller named while the manifest echoes the id they asked for. That is
+ * worth catching, but ONLY when the language list actually loaded: with an empty list the
+ * caller's explicit id is better evidence than our missing cache, so it is passed through.
+ */
+async function resolveLanguageId(dotcms, languageId) {
+    const languages = await loadLanguages(dotcms);
+    if (languageId === undefined) {
+        // The instance's own default, not a hardcoded 1 — on some instances it is not 1.
+        return languages[0]?.id ?? 1;
+    }
+    if (languages.length === 0 || languages.some((language) => language.id === languageId)) {
+        return languageId;
+    }
+    const available = languages
+        .map((language) => `${language.id} (${language.isoCode})`)
+        .join(', ');
+    throw new ValidationError(`languageId ${languageId} does not exist on this instance. dotCMS would silently fall ` +
+        `back to the default language and write to the WRONG language rather than reject ` +
+        `it, so this is refused up front. Available languages: ${available}.`);
+}
+/** Languages from the cache, falling back to a direct read when the cache is empty. */
+async function loadLanguages(dotcms) {
+    const { languages } = await safeContext(dotcms);
+    if (languages.length > 0) {
+        return languages.map((language) => ({ id: language.id, isoCode: language.isoCode }));
+    }
+    try {
+        const raw = entityOf(await dotcms.request({ path: '/api/v2/languages' }));
+        return (Array.isArray(raw) ? raw : [])
+            .map((item) => {
+            const record = asRecord$1(item);
+            const id = record?.['id'];
+            return {
+                id: typeof id === 'number' ? id : Number(id) || 0,
+                isoCode: readString(record, 'isoCode') ?? ''
+            };
+        })
+            .filter((language) => language.id > 0);
+    }
+    catch {
+        // Unknown rather than empty — the caller's id is then taken at face value.
+        return [];
+    }
+}
+/**
+ * `loadContext()` with its own failure absorbed.
+ *
+ * A context load failing must never be the reason a tool call dies: the context is an
+ * accelerator, and every resolver here has a direct-lookup path that does not need it.
+ */
+async function safeContext(dotcms) {
+    try {
+        return await dotcms.loadContext();
+    }
+    catch (error) {
+        console.error(`[context] load failed during resolution: ${errorMessage(error)}`);
+        return { contentTypes: [], sites: [], languages: [], currentUser: null };
+    }
+}
+
+/**
+ * Every endpoint `createPage` calls — the `page_create` tool enforces exactly this list, and
+ * `page-create.spec.ts` checks every request against it. Add a request, add it here.
+ */
+const PAGE_CREATE_ENDPOINTS = [
+    ...CONTEXT_ENDPOINTS,
+    ...RESOLVE_ENDPOINTS,
+    'GET /api/v1/contenttype/id/{idOrVar}',
+    'GET /api/v1/templates/{identifier}/working',
+    'POST /api/v1/folder/createfolders/{site}',
+    'PUT /api/v1/workflow/actions/default/fire/PUBLISH',
+    'GET /api/v1/content/{identifier}'
+];
+/** The default page content type when the caller does not name one. */
+const DEFAULT_PAGE_CONTENT_TYPE = 'htmlpageasset';
+/** Cap on an interpolated response entity inside an error message (see describeEntity). */
+const MAX_ENTITY_CHARS = 1_000;
+/** Base type string the REST API reports for any page content type. */
+const PAGE_BASE_TYPE = 'HTMLPAGE';
+/**
+ * System field variables every page content type carries — mirrored by hand from
+ * dotCMS/.../contenttype/model/type/PageContentType.java (requiredFields() + the field-var
+ * constants). These are either set explicitly from typed args below or filled by the platform, so
+ * they are NOT treated as "unsatisfied user-required fields" during validation. Re-sync this set
+ * if those field variables change backend-side. (The fetched field's `fixed` flag also excludes
+ * platform fields at line ~`assertRequiredFieldsSatisfied`; this list is the belt-and-suspenders
+ * fallback for instances/versions where `fixed` isn't reliably serialized.)
+ */
+const SYSTEM_PAGE_FIELD_VARS = new Set([
+    'title',
+    'url',
+    'hostFolder',
+    'template',
+    'showOnMenu',
+    'sortOrder',
+    'cachettl',
+    'friendlyName',
+    'pageTitle',
+    'redirecturl',
+    'httpsreq',
+    'seodescription',
+    'seokeywords',
+    'pagemetadata'
+]);
+/**
+ * Create and publish a dotCMS page in one safe call.
+ *
+ * A "page" is a contentlet whose content type's base type is HTMLPAGE, fired through the generic
+ * workflow endpoint — there is no dedicated create-page endpoint. The content type defaults to
+ * `htmlpageasset` but can be any page type; custom page types may add their own (possibly required)
+ * fields, so we resolve the type and validate against its actual field set before firing.
+ *
+ * This wrapper absorbs the URL-collapse trap: dotCMS silently collapses a page `url` whose parent
+ * folder does not exist down to `/index`, which then 400s against the home page. We split `urlPath`
+ * into folder + leaf, create the folder first, then fire the page with `url: "<leaf>"` and
+ * `hostFolder: <created folder>` so the URL lands where the caller meant.
+ *
+ * This is the THIN tier: it does NOT place content. The page comes up live but blank — content
+ * placement and the re-publish that follows are a separate, explicit step for the caller. The
+ * manifest flags this so a successful create is never mistaken for a fully-populated page.
+ */
+async function createPage(options) {
+    const { folder, url, fullPath } = splitUrlPath(options.urlPath);
+    const warnings = [];
+    const extraFields = options.extraFields ?? {};
+    // Resolve the site to its identifier UUID up front. `contentHost` on the fire body MUST be a
+    // site UUID — a bare hostname makes the fire NPE ("Host.getIdentifier() because host is null"),
+    // which is exactly the root-page (`/`) trap where there is no folder to anchor the page on.
+    const siteId = await resolveSiteId(options.dotcms, options.site);
+    // Resolve the page content type and validate it BEFORE creating anything. A wrong type (not a
+    // page) or a missing user-required field would otherwise 400 the fire opaquely — and only after
+    // we'd already created the folder. Fail early with a precise message instead.
+    const contentType = await resolvePageContentType(options.dotcms, options.contentType);
+    assertRequiredFieldsSatisfied(contentType, extraFields);
+    // Validate the remaining caller inputs BEFORE anything is written. `site` and
+    // `contentType` are already resolved above against cached context; `template` and
+    // `languageId` were the two that were not, which made them the only inputs whose
+    // rejection arrived AFTER the folder had been created (see ensureFolder below).
+    const languageId = await resolveLanguageId(options.dotcms, options.languageId);
+    await assertTemplateExists(options.dotcms, options.template);
+    // Trap #1: the parent folder must exist before the page is fired, or dotCMS collapses the
+    // page url to /index. createfolders is idempotent — re-creating an existing folder is a no-op.
+    const folderId = await ensureFolder(options.dotcms, siteId, folder);
+    // Trap #3 (root/leaf page on a NON-default site): the page's HOST_OR_FOLDER field must carry a
+    // concrete location id, or the fire cannot resolve the host and 500s with
+    // "Host.getIdentifier() ... host is null". A nested page passes the folder id (which carries its
+    // host); a root page has no folder, so `folderId` is undefined and, left alone, `hostFolder`
+    // would be dropped from the JSON body — leaving only `contentHost`, which is not enough to
+    // anchor a root page. Fall the location back to the SITE id: HOST_OR_FOLDER accepts a host id
+    // and resolves it to that host's system folder. (This mirrors the working manual recovery:
+    // fire with hostFolder = site id.)
+    const hostFolder = folderId ?? siteId;
+    const title = options.title;
+    // Guarded: `ensureFolder` above has ALREADY COMMITTED a folder by this point, so a bare
+    // rethrow here leaves a folder nothing mentions. `page_create({urlPath:"/books/index"})`
+    // with a bad input would create `/books`, fail, and report only the HTTP error — and a
+    // corrected retry then operates on folder state the caller does not know exists.
+    const fired = await fireCreate(options.dotcms, folder, folderId, {
+        method: 'PUT',
+        path: '/api/v1/workflow/actions/default/fire/PUBLISH',
+        query: { indexPolicy: 'WAIT_FOR' },
+        body: {
+            contentlet: {
+                // User-added fields first, so the typed page fields below always win on the keys
+                // they own (a caller can't accidentally override `url`/`template` via extraFields).
+                ...extraFields,
+                contentType: contentType.variable,
+                contentHost: siteId,
+                hostFolder,
+                languageId,
+                title,
+                url,
+                template: options.template,
+                cachettl: options.cacheTtl ?? '0',
+                sortOrder: options.sortOrder ?? 0,
+                friendlyName: options.friendlyName ?? title,
+                pageTitle: options.pageTitle ?? title
+            }
+        }
+    });
+    const entity = extractPageEntity(fired);
+    const identifier = entity?.identifier;
+    const inode = entity?.inode;
+    const live = await isLive(options.dotcms, identifier);
+    if (!live) {
+        warnings.push(`Page created but not confirmed live. It may render blank until content is placed and the page is re-published.`);
+    }
+    return {
+        identifier,
+        inode,
+        contentType: contentType.variable,
+        folder,
+        url,
+        fullPath,
+        site: options.site,
+        live,
+        warnings
+    };
+}
+/**
+ * Resolve a site (given as a hostname OR an identifier UUID) to its identifier UUID.
+ *
+ * The fire body's `contentHost` must be a site UUID. Passing a bare hostname works for pages under
+ * a folder (the folder anchors the host) but NPEs for a root page, where there is no folder — dotCMS
+ * then can't resolve the host and throws "Host.getIdentifier() because host is null". Resolving to
+ * the UUID here makes every page (root included) fire cleanly. Uses the runtime's cached site
+ * context (already loaded), mirroring how resolvePageContentType uses cached content types.
+ */
+async function resolveSiteId(dotcms, site) {
+    return (await resolveSite(dotcms, site)).identifier;
+}
+/**
+ * Resolve the page content type by variable or id and confirm it is actually a page type.
+ *
+ * Defaults to `htmlpageasset`. We first match against the runtime's cached content-type summaries
+ * (cheap, already loaded) to give a precise "not found / not a page type" error, then fetch the
+ * full definition (with fields) so required-field validation can run. Firing a non-page type as a
+ * page produces a broken contentlet, so a wrong base type is a hard error, not a warning.
+ */
+async function resolvePageContentType(dotcms, requested) {
+    const wanted = (requested ?? DEFAULT_PAGE_CONTENT_TYPE).trim();
+    // The cache is consulted for the id and for a candidate list, but it does NOT decide
+    // whether the type exists: the definition fetch below is a live call that answers the
+    // same question authoritatively. Gating on the cache meant that when the one-time
+    // context load failed — leaving `contentTypes` empty for the whole session — even the
+    // default `htmlpageasset` was rejected as "not found".
+    const context = await safeLoadContext(dotcms);
+    const summary = context.contentTypes.find((ct) => ct.variable === wanted || ct.id === wanted);
+    // Computed lazily — the happy path never needs the list of page types for an error message.
+    const availablePageTypes = () => context.contentTypes
+        .filter((ct) => ct.baseType === PAGE_BASE_TYPE)
+        .map((ct) => ct.variable)
+        .join(', ') || '(unknown — the session content-type list did not load)';
+    let definition;
+    try {
+        definition = await fetchContentTypeDefinition(dotcms, summary?.id || wanted);
+    }
+    catch (error) {
+        if (!(error instanceof HttpError) || error.status !== 404) {
+            throw error;
+        }
+        // 404 → not found, handled below alongside the empty-entity case.
+    }
+    if (!definition) {
+        throw new ValidationError(`Content type "${wanted}" was not found on this instance. ` +
+            `Available page content types: ${availablePageTypes()}.`);
+    }
+    // Checked against the FETCHED definition, not the cached summary — the fetch is the
+    // authority and is present on every path.
+    if (definition.baseType !== PAGE_BASE_TYPE) {
+        throw new ValidationError(`Content type "${definition.variable}" is base type ${definition.baseType}, not a page ` +
+            `(HTMLPAGE). page_create only creates pages. Available page content types: ` +
+            `${availablePageTypes()}.`);
+    }
+    return definition;
+}
+/**
+ * `loadContext()` with its failure absorbed — the context is an accelerator here, and every
+ * caller below has a live path that does not need it. See lib/resolve.ts for the full
+ * rationale on why an empty cache must never be read as "this does not exist".
+ */
+async function safeLoadContext(dotcms) {
+    try {
+        return await dotcms.loadContext();
+    }
+    catch (error) {
+        console.error(`[context] load failed during content-type resolution: ${errorMessage(error)}`);
+        return { contentTypes: [], sites: [], languages: [], currentUser: null };
+    }
+}
+/** Fetch the full content-type definition (including fields) by id or variable. */
+async function fetchContentTypeDefinition(dotcms, idOrVar) {
+    const response = await dotcms.request({
+        path: `/api/v1/contenttype/id/${encodeURIComponent(idOrVar)}`
+    });
+    const entity = asRecord(responseEntity(response));
+    const rawFields = entity?.['fields'];
+    const fields = Array.isArray(rawFields)
+        ? rawFields
+            .map(asRecord)
+            .filter((f) => f !== undefined)
+            .map((f) => ({
+            variable: optionalString(f, 'variable'),
+            required: f['required'] === true,
+            fixed: f['fixed'] === true,
+            defaultValue: f['defaultValue']
+        }))
+        : [];
+    const variable = optionalString(entity, 'variable');
+    const baseType = optionalString(entity, 'baseType');
+    // An empty/unrecognised entity means the type was not resolved. Returning a shape that
+    // defaults `baseType` to HTMLPAGE would assert the very thing the caller is being
+    // checked for, so the base-type guard would pass on a type that does not exist.
+    if (!variable || !baseType) {
+        return undefined;
+    }
+    return {
+        id: optionalString(entity, 'id') ?? idOrVar,
+        variable,
+        baseType,
+        fields
+    };
+}
+/**
+ * Fail before firing if the type has a user-added required field we have no value for. dotCMS
+ * would reject the fire with a 400 anyway — but only after we've created the folder, and with a
+ * less actionable message. We skip system page fields (filled from typed args / the platform),
+ * fixed fields, and fields that carry a default value.
+ */
+function assertRequiredFieldsSatisfied(contentType, extraFields) {
+    // flatMap (not filter + map) so `variable` stays narrowed to string without a cast.
+    const missing = contentType.fields.flatMap((field) => {
+        const variable = field.variable;
+        if (!variable || !field.required || field.fixed)
+            return [];
+        if (SYSTEM_PAGE_FIELD_VARS.has(variable))
+            return [];
+        if (hasDefault(field.defaultValue))
+            return [];
+        return hasValue(extraFields[variable]) ? [] : [variable];
+    });
+    if (missing.length > 0) {
+        throw new ValidationError(`Content type "${contentType.variable}" has required field(s) with no value: ` +
+            `${missing.join(', ')}. Pass them via extraFields, e.g. ` +
+            `{ "${missing[0]}": <value> }.`);
+    }
+}
+/** A server-side default counts if non-null and (for strings) non-empty. */
+function hasDefault(defaultValue) {
+    return typeof defaultValue === 'string' ? defaultValue.length > 0 : defaultValue != null;
+}
+/** A caller-supplied value counts if non-null and (for strings) non-blank after trimming. */
+function hasValue(value) {
+    if (value == null)
+        return false;
+    if (typeof value === 'string')
+        return value.trim().length > 0;
+    return true;
+}
+/**
+ * Ensure the folder path exists on the site and return the id of the deepest (target) folder.
+ * createfolders creates the full path and is idempotent on existing folders.
+ */
+async function ensureFolder(dotcms, site, folder) {
+    if (folder === '/' || folder === '') {
+        // Root page: no folder to create. The caller falls hostFolder back to the site id (a root
+        // page fired with an undefined hostFolder 500s on a non-default site — see Trap #3).
+        return undefined;
+    }
+    const response = await dotcms.request({
+        method: 'POST',
+        path: `/api/v1/folder/createfolders/${encodeURIComponent(site)}`,
+        body: [folder]
+    });
+    const folderId = extractFolderId(response, folder);
+    // A nested page MUST be anchored on its real folder id. Falling back to the site id here
+    // (the root-page path below) would silently anchor the page at the site root and
+    // reintroduce the very /index URL-collapse trap this function exists to prevent, while the
+    // manifest still reported the intended folder/fullPath. Fail loudly instead.
+    if (!folderId) {
+        throw new Error(`Folder "${folder}" was requested on site "${site}" but createfolders returned no ` +
+            `resolvable folder id, so the page cannot be anchored to it. Refusing to fall ` +
+            `back to the site root (that would collapse the page url to /index). ` +
+            `Response entity: ${describeEntity(response)}`);
+    }
+    return folderId;
+}
+/**
+ * `dotcms.request()` is typed `unknown` — it speaks to a live instance whose payload we cannot
+ * prove at compile time. Rather than assert a shape with `as` (which type-checks a lie and then
+ * lets `undefined` surface deep in the caller), narrow the ONE thing every dotCMS REST envelope
+ * guarantees: an object with an optional `entity`. Callers keep their own per-endpoint guards for
+ * what lives inside it, so a shape change becomes a handled `undefined` rather than a crash.
+ */
+function responseEntity(response) {
+    if (typeof response !== 'object' || response === null) {
+        return undefined;
+    }
+    return response.entity;
+}
+/** Narrow a value to an indexable record, or undefined when it isn't one. */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Read an optional string property, ignoring non-string values. */
+function optionalString(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * createfolders returns the created/found folders. We want the id of the folder matching our
+ * target path. Shapes vary across versions (array vs object, identifier vs inode), so probe
+ * defensively and fall back to the deepest entry.
+ */
+function extractFolderId(response, folder) {
+    const entity = responseEntity(response);
+    const raw = Array.isArray(entity) ? entity : entity ? [entity] : [];
+    const list = raw.map(asRecord).filter((f) => f !== undefined);
+    if (list.length === 0) {
+        return undefined;
+    }
+    const normalized = folder.replace(/\/+$/, '');
+    const match = list.find((f) => optionalString(f, 'path')?.replace(/\/+$/, '') === normalized);
+    const chosen = match ?? list[list.length - 1];
+    return optionalString(chosen, 'identifier') ?? optionalString(chosen, 'inode');
+}
+/**
+ * Read the page fields out of a fire/read response.
+ *
+ * Every field is read through a checking accessor rather than asserted with `as`. The two
+ * casts that used to live here claimed `identifier`, `inode` and `live` existed with the
+ * right types off a `Record<string, unknown>` that nothing had checked — precisely the
+ * "type-check a lie and let `undefined` surface deep in the caller" failure that
+ * `responseEntity`/`asRecord`/`optionalString` were introduced to close.
+ */
+function extractPageEntity(response) {
+    const entity = asRecord(responseEntity(response));
+    if (!entity) {
+        return undefined;
+    }
+    // Fire responses sometimes wrap the contentlet under `contentlets[0]`.
+    const contentlets = entity['contentlets'];
+    if (Array.isArray(contentlets) && contentlets.length) {
+        const first = asRecord(contentlets[0]);
+        return first && toPageEntity(first);
+    }
+    return toPageEntity(entity);
+}
+/** Project a checked record onto {@link PageEntity} — unknown/mistyped fields stay undefined. */
+function toPageEntity(record) {
+    return {
+        identifier: optionalString(record, 'identifier'),
+        inode: optionalString(record, 'inode'),
+        live: optionalBoolean(record, 'live')
+    };
+}
+/** Read an optional boolean property, ignoring non-boolean values. */
+function optionalBoolean(record, key) {
+    const value = record?.[key];
+    return typeof value === 'boolean' ? value : undefined;
+}
+async function isLive(dotcms, identifier) {
+    if (!identifier) {
+        return false;
+    }
+    try {
+        return await isContentLive(dotcms, identifier);
+    }
+    catch {
+        // A failed liveness check is not a failed create — the page exists either way, so
+        // report it as not-verified-live rather than failing the whole operation. The
+        // shared probe deliberately throws; swallowing is this caller's choice, not the
+        // primitive's (see page-common.ts).
+        return false;
+    }
+}
+/**
+ * Confirm the template exists before anything is written.
+ *
+ * `template` is the one input a caller most often gets wrong — the schema says "the template
+ * UUID, not its name", which is exactly the mistake worth catching — and it was the only one
+ * whose rejection arrived from the fire, i.e. after the folder had already been created.
+ *
+ * A non-404 failure here is deliberately NOT fatal: the check is a courtesy, and refusing to
+ * create a page because the template lookup was briefly unavailable would be worse than
+ * letting the fire decide.
+ */
+async function assertTemplateExists(dotcms, template) {
+    try {
+        await dotcms.request({
+            path: `/api/v1/templates/${encodeURIComponent(template)}/working`
+        });
+    }
+    catch (error) {
+        if (error instanceof HttpError && error.status === 404) {
+            throw new ValidationError(`Template "${template}" was not found. This must be the template's IDENTIFIER ` +
+                `(a UUID), not its name — passing a human-readable title here is the most ` +
+                `common cause. Nothing has been created; fix the template and re-run.`);
+        }
+        // Anything else (403, 5xx, timeout): fall through and let the fire be the judge.
+    }
+}
+/**
+ * Fire the create, and on failure say what has ALREADY been committed.
+ *
+ * The folder write happens before this point and cannot be rolled back, so the recoverable
+ * outcome depends on the caller knowing three things: which inputs were used, that folder
+ * `<x>` now exists, and that re-running is safe because `createfolders` is idempotent. That
+ * last sentence is what turns an orphaned folder into a retryable operation.
+ */
+async function fireCreate(dotcms, folder, folderId, request) {
+    try {
+        return await dotcms.request(request);
+    }
+    catch (error) {
+        const created = folderId
+            ? `Folder "${folder}" (${folderId}) WAS created before this failure and still exists. `
+            : '';
+        const note = `${created}Re-running this call after fixing the input is SAFE: folder creation ` +
+            `is idempotent, so no duplicate folder is made.`;
+        // Add the note to the fire's OWN error rather than wrapping it: its class is what says
+        // whether to retry — a 503 or a timeout is worth another try, a 400 is not.
+        throw withMessage(error, `${errorMessage(error)}\n\n${note}`);
+    }
+}
+/**
+ * Render a response's entity for an error message.
+ *
+ * `JSON.stringify(undefined)` returns `undefined` (the value, not a string), so interpolating
+ * it printed the literal text "Response entity: undefined" — and an ABSENT entity is exactly
+ * the condition that triggers the branch using this, so that was the common case rather than
+ * the edge one. When an entity IS present it is capped: the raw blob can be arbitrarily large
+ * and this is going straight into an error the model has to read.
+ */
+function describeEntity(response) {
+    const entity = responseEntity(response);
+    if (entity === undefined || entity === null) {
+        return '(no entity in the response — the endpoint returned a body this tool could not read)';
+    }
+    const json = JSON.stringify(entity);
+    return json.length <= MAX_ENTITY_CHARS
+        ? json
+        : `${json.slice(0, MAX_ENTITY_CHARS)}… [truncated]`;
+}
+
+const definition$4 = defineTool({
+    name: 'page_create',
+    title: 'Create dotCMS Page',
+    inputSchema: z.object({
+        site: z
+            .string()
+            .min(1)
+            .describe('Site the page lives on — identifier (UUID) or hostname, e.g. "demo.dotcms.com"'),
+        urlPath: z
+            .string()
+            .min(1)
+            .describe('Page URL path on the site, e.g. "/books/index" or "/books". The parent folder is created automatically; the leaf segment becomes the page url (a bare folder or trailing slash defaults the leaf to "index").'),
+        title: z.string().min(1).describe('Page title'),
+        template: z
+            .string()
+            .min(1)
+            .describe('Template identifier the page renders with (the template UUID, not its name)'),
+        contentType: z
+            .string()
+            .optional()
+            .describe('Page content type — variable or id. Defaults to "htmlpageasset". Must be a content type whose base type is HTMLPAGE; a custom page type may add its own fields (pass values via extraFields).'),
+        extraFields: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('Values for content-type fields beyond the common page fields, keyed by field variable. Required for any user-added required field on a custom page type that has no default value (the tool validates this before firing and tells you which fields are missing).'),
+        friendlyName: z.string().optional().describe('Friendly name; defaults to the title'),
+        pageTitle: z.string().optional().describe('Browser <title>; defaults to the title'),
+        languageId: z.number().int().default(1).describe('Language id. Default 1'),
+        cacheTtl: z
+            .string()
+            .default('0')
+            .describe('Cache TTL in seconds, as a string. Default "0"'),
+        sortOrder: z.number().int().default(0).describe('Sort order within the folder. Default 0')
+    }),
+    description: `Create and publish a dotCMS page in one safe call.
+
+A dotCMS "page" is a contentlet whose content type's base type is HTMLPAGE, fired through the
+generic workflow endpoint — there is NO dedicated create-page endpoint. The content type defaults
+to \`htmlpageasset\`, but pass \`contentType\` to use a custom page type. The tool resolves the type,
+confirms it really is a page type, and validates its required fields BEFORE creating anything — so
+a custom page type's user-added required fields surface as a clear "pass extraFields: { … }" error
+instead of an opaque 400 after the folder was already created. Hand-rolling that fire with the
+\`execute\` tool is the path that hits two sharp edges; this tool exists to absorb the first one:
+
+  The URL-collapse trap. If you fire a page with \`url: "/books/index"\` but the \`/books\` folder
+  does not exist yet, dotCMS silently collapses the url down to \`/index\` — which then 400s with
+  "Page URL [/index] already exists" because the home page already owns it. This tool splits
+  \`urlPath\` into folder + leaf, creates the parent folder first (idempotent), then fires the
+  page with the leaf url under that folder — so the url lands exactly where you meant.
+
+WHAT THIS TOOL DOES NOT DO — read this. It creates the page; it does NOT place any content on it.
+The page comes up live but BLANK. Placing content is a separate, explicit step you take afterward
+with the \`page_place_content\` tool: it puts existing contentlets into the page's slots without
+emptying the slots you don't address. Then check the result with \`page_verify\`, which catches a
+blank slot or an edit that is not live yet. The returned manifest flags a \`live: false\` / warning
+case so a successful create is never mistaken for a fully-populated page.
+
+Returns a JSON manifest: { identifier, inode, folder, url, fullPath, site, live, warnings }.
+
+Custom page fields go in \`extraFields\` on this tool. Use the \`execute\` tool (not this one) only
+when you need a page variant or need to fire a non-PUBLISH workflow action.`,
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+    },
+    endpoints: PAGE_CREATE_ENDPOINTS,
+    async handler(args, ctx) {
+        return createPage({
+            dotcms: ctx.runtime(),
+            site: args.site,
+            urlPath: args.urlPath,
+            title: args.title,
+            template: args.template,
+            contentType: args.contentType,
+            extraFields: args.extraFields,
+            friendlyName: args.friendlyName,
+            pageTitle: args.pageTitle,
+            languageId: args.languageId,
+            cacheTtl: args.cacheTtl,
+            sortOrder: args.sortOrder
+        });
+    }
+});
+/**
+ * The `page_create` tool: creates and publishes a page, creating its parent folder first so
+ * the URL lands where it was asked for. Resolves to a {@link CreatePageManifest}.
+ */
+function pageCreateTool(connection, options = {}) {
+    return createTool(definition$4, connection, options);
+}
+
+/**
+ * Every endpoint `placeContent` calls — the `page_place_content` tool enforces exactly this
+ * list, and `page-place-content.spec.ts` checks every request against it. Add a request, add it
+ * here.
+ */
+const PAGE_PLACE_CONTENT_ENDPOINTS = [
+    ...CONTEXT_ENDPOINTS,
+    ...RESOLVE_ENDPOINTS,
+    'GET /api/v1/page/json/**',
+    'POST /api/v1/page/{pageId}/content'
+];
+/** The default variant when the caller does not name one. */
+const DEFAULT_VARIANT = 'DEFAULT';
+/** The default language id when the caller does not name one. */
+const DEFAULT_LANGUAGE_ID$1 = 1;
+/**
+ * Place content into a page's container slots without wiping the rest of the page.
+ *
+ * `POST /api/v1/page/{pageId}/content` is a FULL replacement of the page's container-to-contentlet
+ * map: any slot omitted from the body is emptied. A caller that means "add one contentlet to one
+ * slot" but sends only that slot silently clears every other slot. This wrapper absorbs that trap:
+ * it reads the page's current content first, applies the requested op(s) to the addressed slot(s)
+ * only, then POSTs the COMPLETE map back so untouched slots survive.
+ *
+ * It also removes the discovery friction: the caller addresses a slot by index or container name
+ * and we resolve it to the exact `identifier`+`uuid` the endpoint needs — sourced from the page's
+ * real layout, so a typo fails clearly instead of silently doing nothing. The returned manifest
+ * gives a before/after diff per slot and flags any slot that lost content.
+ */
+async function placeContent(options) {
+    const mode = options.mode ?? 'merge';
+    const variantName = options.variantName ?? DEFAULT_VARIANT;
+    const languageId = options.languageId ?? DEFAULT_LANGUAGE_ID$1;
+    const assignments = validateAssignments(options.slots);
+    const target = await resolvePageTarget(options.dotcms, options.path, options.site);
+    // Read the page's current content. This is the whole point of merge mode, but replace mode needs
+    // it too — to validate the addressed slots exist and to build the before/after diff.
+    const { pageId, url, slots } = await loadPageSlots(options.dotcms, target.path, target.siteId, languageId, variantName);
+    // Index the real slots two ways so a caller can address either by 1-based layout order or by
+    // container (+optional instance uuid). Resolution validates existence and disambiguates.
+    const resolved = assignments.map((assignment) => ({
+        assignment,
+        target: resolveSlot(assignment.slot, slots)
+    }));
+    // Start from the page's current map. In merge mode we mutate the addressed slots in place; in
+    // replace mode we start empty (every slot cleared) and set only what the caller specifies.
+    const desired = new Map();
+    for (const slot of slots) {
+        desired.set(slotKey(slot.identifier, slot.uuid), mode === 'replace' ? [] : [...slot.contentlets]);
+    }
+    for (const { assignment, target } of resolved) {
+        const key = slotKey(target.identifier, target.uuid);
+        const current = desired.get(key) ?? [];
+        desired.set(key, applyOp(current, assignment.contentlets, assignment.op ?? 'append'));
+    }
+    // The POST body is the FULL array — every slot on the page, with its desired contents.
+    const body = slots.map((slot) => ({
+        identifier: slot.identifier,
+        uuid: slot.uuid,
+        contentletsId: desired.get(slotKey(slot.identifier, slot.uuid)) ?? []
+    }));
+    await postContent(options.dotcms, pageId, body, variantName, languageId);
+    // Build the diff and warnings from before (page's current) vs after (what we sent).
+    const warnings = [];
+    const slotResults = slots.map((slot) => {
+        const after = desired.get(slotKey(slot.identifier, slot.uuid)) ?? [];
+        const before = slot.contentlets;
+        const lost = before.filter((id) => !after.includes(id));
+        if (lost.length > 0) {
+            warnings.push(`Slot ${slot.identifier} [uuid ${slot.uuid}] lost ${lost.length} contentlet(s): ` +
+                `${lost.join(', ')}.`);
+        }
+        return {
+            identifier: slot.identifier,
+            uuid: slot.uuid,
+            before,
+            after,
+            changed: !sameOrder(before, after)
+        };
+    });
+    return {
+        pageId,
+        site: target.hostname,
+        url,
+        variantName,
+        languageId,
+        mode,
+        slots: slotResults,
+        warnings
+    };
+}
+/** Resolve explicit or host-qualified page targeting without ever falling back to a default site. */
+async function resolvePageTarget(dotcms, rawPath, explicitSite) {
+    const trimmed = rawPath.trim();
+    const qualified = /^\/\/([^/]+)(\/.*)?$/.exec(trimmed);
+    const qualifiedHost = qualified?.[1];
+    const pagePath = qualified ? qualified[2] || '/' : trimmed;
+    const requestedSite = explicitSite?.trim();
+    if (!requestedSite && !qualifiedHost) {
+        throw new ValidationError('`site` is required for page placement when `path` is not host-qualified. ' +
+            'Pass a site hostname/identifier or use `//hostname/path`; refusing to choose the ' +
+            'default site prevents writes to the wrong page on multi-site instances.');
+    }
+    // Resolved through the shared resolver, which falls back to a direct lookup rather than
+    // treating an empty session cache as proof a site does not exist. Each resolver throws
+    // its own explanatory error, so an unknown site still fails here — just for the right
+    // reason, and before any request is made.
+    const explicit = requestedSite ? await resolveSite(dotcms, requestedSite) : undefined;
+    const embedded = qualifiedHost ? await resolveSite(dotcms, qualifiedHost) : undefined;
+    if (explicit && embedded && explicit.identifier !== embedded.identifier) {
+        throw new ValidationError(`Conflicting sites: path targets "${qualifiedHost}" but site targets ` +
+            `"${requestedSite}". Pass one site consistently; no request was made.`);
+    }
+    const site = explicit ?? embedded;
+    // The branches above make this unreachable, but keep the guard for type safety and future edits.
+    if (!site) {
+        throw new Error('Page placement site could not be resolved.');
+    }
+    // The manifest must echo the path actually operated on, not the raw input.
+    const normalizedPath = normalizePagePath(pagePath);
+    return { path: normalizedPath, siteId: site.identifier, hostname: site.hostname };
+}
+/**
+ * `slots` is required and must be non-empty. The tool schema also guards this, but the lib is
+ * called directly from tests, so it validates too.
+ */
+function validateAssignments(slots) {
+    if (!slots || slots.length === 0) {
+        throw new ValidationError('`slots` is required and must contain at least one slot assignment.');
+    }
+    return slots;
+}
+/** Apply an op to a slot's current contentlet list, preserving order and de-duplicating. */
+function applyOp(current, incoming, op) {
+    switch (op) {
+        case 'set':
+            return dedupe(incoming);
+        case 'remove': {
+            const remove = new Set(incoming);
+            return current.filter((id) => !remove.has(id));
+        }
+        case 'append':
+        default:
+            return dedupe([...current, ...incoming]);
+    }
+}
+function dedupe(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (id && !seen.has(id)) {
+            seen.add(id);
+            out.push(id);
+        }
+    }
+    return out;
+}
+function sameOrder(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+/** A stable key for a slot: a container can appear multiple times, so the uuid is part of it. */
+function slotKey(identifier, uuid) {
+    return `${identifier} ${uuid}`;
+}
+/**
+ * Resolve a caller-supplied slot address to a concrete slot on the page. Fails with the list of
+ * valid slots when the address does not match, and (for a container address with no instance) with
+ * the list of instances when the container occupies more than one slot.
+ */
+function resolveSlot(address, slots) {
+    if (typeof address === 'number') {
+        const index = address - 1; // 1-based, in layout order.
+        if (!Number.isInteger(address) || index < 0 || index >= slots.length) {
+            throw new ValidationError(`Slot index ${address} is out of range. The page has ${slots.length} slot(s): ` +
+                `${describeSlots(slots)}.`);
+        }
+        return slots[index];
+    }
+    const wanted = address.container.trim();
+    // Rank-filtered, like `findContainer`: keep only the slots matching at the BEST rank, so
+    // an exact/path-boundary hit on `.../default/` is never diluted by a loose substring hit on
+    // `.../default-banner/`. Without this, naming one container could report "appears in 2
+    // slots, pass slot.instance" about two DIFFERENT containers.
+    const bestRank = slots.reduce((rank, slot) => Math.max(rank, containerMatchRank(slot.identifier, wanted)), MATCH_NONE);
+    const matches = bestRank === MATCH_NONE
+        ? []
+        : slots.filter((slot) => containerMatchRank(slot.identifier, wanted) === bestRank);
+    if (matches.length === 0) {
+        throw new ValidationError(`No slot on the page uses container "${address.container}". Available slots: ` +
+            `${describeSlots(slots)}.`);
+    }
+    if (address.instance !== undefined) {
+        const exact = matches.find((slot) => slot.uuid === String(address.instance));
+        if (!exact) {
+            const instances = matches.map((slot) => `'${slot.uuid}'`).join(', ');
+            throw new ValidationError(`Container "${address.container}" has no slot with instance '${address.instance}'. ` +
+                `Available instances: ${instances}.`);
+        }
+        return exact;
+    }
+    if (matches.length > 1) {
+        const instances = matches.map((slot) => `'${slot.uuid}'`).join(', ');
+        throw new ValidationError(`Container "${address.container}" appears in ${matches.length} slots ` +
+            `(instances: ${instances}). Pass slot.instance to disambiguate.`);
+    }
+    return matches[0];
+}
+/**
+ * How well a layout container key matches what the caller asked for. Higher is better;
+ * `NONE` means no match at all.
+ *
+ * Ranked rather than boolean, because the previous "either string contains the other" test
+ * made resolution ORDER-DEPENDENT and therefore non-deterministic from the caller's side: a
+ * layout holding both `.../containers/default/` and `.../containers/default-banner/` would
+ * resolve a request for `.../default/` to whichever appeared FIRST in the object. Object keys
+ * iterate in insertion order, so which container won depended on layout authoring order — and
+ * in `merge` mode the tool would read the banner's contentlet list and write the merged result
+ * back under it, putting content in the wrong container and potentially replacing the banner's
+ * own contents.
+ */
+const MATCH_NONE = 0;
+/** One string contains the other anywhere — the loosest, most ambiguous signal. */
+const MATCH_SUBSTRING = 1;
+/** The key ends with the wanted value on a `/` boundary, e.g. `.../containers/default/`. */
+const MATCH_PATH_SUFFIX = 2;
+/** Byte-identical (case-insensitively). */
+const MATCH_EXACT = 3;
+function containerMatchRank(identifier, wanted) {
+    const key = identifier.toLowerCase();
+    const want = wanted.toLowerCase();
+    if (key === want) {
+        return MATCH_EXACT;
+    }
+    // Compare on `/`-delimited boundaries so `default` cannot match `default-banner`. Both
+    // sides are normalised for a trailing slash first, since container paths carry one and
+    // callers routinely omit it.
+    const keyTrimmed = key.replace(/\/+$/, '');
+    const wantTrimmed = want.replace(/\/+$/, '');
+    if (keyTrimmed === wantTrimmed || keyTrimmed.endsWith(`/${wantTrimmed}`)) {
+        return MATCH_PATH_SUFFIX;
+    }
+    if (key.includes(want) || want.includes(key)) {
+        return MATCH_SUBSTRING;
+    }
+    return MATCH_NONE;
+}
+/**
+ * The single best-matching key, or a hard error when the choice is genuinely ambiguous.
+ *
+ * Failing loudly with the candidates beats silently picking one: writing to the wrong
+ * container is not recoverable by the caller, whereas an error naming both candidates tells
+ * them exactly what to disambiguate with.
+ */
+function bestContainerKey(keys, wanted) {
+    let bestRank = MATCH_NONE;
+    let best = [];
+    for (const key of keys) {
+        const rank = containerMatchRank(key, wanted);
+        if (rank === MATCH_NONE || rank < bestRank) {
+            continue;
+        }
+        if (rank > bestRank) {
+            bestRank = rank;
+            best = [key];
+        }
+        else {
+            best.push(key);
+        }
+    }
+    if (best.length === 0) {
+        return undefined;
+    }
+    if (best.length > 1) {
+        throw new ValidationError(`Container "${wanted}" is ambiguous — it matches ${best.length} containers on this ` +
+            `page equally well: ${best.join(', ')}. Pass the full container path or id to ` +
+            `disambiguate; guessing here could write content into the wrong container.`);
+    }
+    return best[0];
+}
+function describeSlots(slots) {
+    if (slots.length === 0)
+        return '(none)';
+    return slots.map((slot, i) => `#${i + 1} ${slot.identifier} [uuid ${slot.uuid}]`).join('; ');
+}
+/**
+ * Fetch the page's current content and flatten it into the ordered list of slots we operate on.
+ *
+ * The slot order and the authoritative identifier+uuid come from `layout.body.rows[].columns[]
+ * .containers[]` — this is exactly what the endpoint expects back. The current contentlet ids come
+ * from `containers[identifier].contentlets[uuid]`, matched tolerantly because the layout key and the
+ * containers-map key can differ (shorty vs full id, host-relative vs host-qualified path) and the
+ * contentlets map is historically keyed as either "1" or "uuid-1".
+ */
+async function loadPageSlots(dotcms, path, siteId, languageId, variantName) {
+    // Normalized before interpolation — see lib/page-path.ts for why the raw form is unsafe.
+    const uri = normalizePagePath(path);
+    // Read the SAME variant the write targets. Omitting `variantName` here reads DEFAULT,
+    // so in `merge` mode on a non-DEFAULT variant the "before" slot map and the
+    // untouched-slot preservation would be computed from DEFAULT and then written into the
+    // target variant — clobbering its real contents and reporting a bogus before/after diff.
+    const response = (await dotcms.request({
+        path: `/api/v1/page/json${uri}`,
+        query: { variantName, language_id: languageId, host_id: siteId }
+    }));
+    const entity = response.entity;
+    if (!entity || !entity.page) {
+        throw new ValidationError(`Page "${path}" was not found (no page at this url for language ${languageId}).`);
+    }
+    const pageId = entity.page.identifier;
+    if (!pageId) {
+        throw new Error(`Page "${path}" resolved but has no identifier.`);
+    }
+    const url = entity.page.pageURI ?? entity.page.pageUrl ?? entity.page.url ?? uri;
+    const containers = entity.containers ?? {};
+    const rows = entity.layout?.body?.rows ?? [];
+    const slots = [];
+    for (const row of rows) {
+        for (const column of row.columns ?? []) {
+            for (const container of column.containers ?? []) {
+                const identifier = container.identifier;
+                const uuid = container.uuid;
+                if (!identifier || !uuid) {
+                    continue;
+                }
+                slots.push({
+                    identifier,
+                    uuid,
+                    contentlets: currentContentlets(containers, identifier, uuid)
+                });
+            }
+        }
+    }
+    return { pageId, url, slots };
+}
+/**
+ * Read the contentlet ids currently in a slot from the containers map. The layout `identifier` may
+ * not be byte-identical to the containers-map key, and the per-slot key may be "uuid" or "uuid-N",
+ * so both lookups are tolerant.
+ */
+function currentContentlets(containers, identifier, uuid) {
+    const raw = findContainer$1(containers, identifier);
+    if (!raw?.contentlets) {
+        return [];
+    }
+    const map = raw.contentlets;
+    const list = map[uuid] ??
+        map[`uuid-${uuid}`] ??
+        map[stripUuidPrefix$1(uuid)] ??
+        // Last resort: a key that ends with the uuid (covers other prefixings).
+        map[Object.keys(map).find((k) => stripUuidPrefix$1(k) === stripUuidPrefix$1(uuid)) ?? ''];
+    if (!Array.isArray(list)) {
+        return [];
+    }
+    return list.map((c) => c.identifier).filter((id) => Boolean(id));
+}
+function stripUuidPrefix$1(uuid) {
+    return uuid.startsWith('uuid-') ? uuid.slice('uuid-'.length) : uuid;
+}
+function findContainer$1(containers, identifier) {
+    if (containers[identifier]) {
+        return containers[identifier];
+    }
+    const key = bestContainerKey(Object.keys(containers), identifier);
+    return key ? containers[key] : undefined;
+}
+/**
+ * POST the full container map, translating the two documented non-200 outcomes into actionable
+ * messages: 409 is the net-loss conflict (someone else changed the page, or the write would
+ * remove too much), and a 400 usually means a contentlet's type is not allowed in its container.
+ *
+ * Both branches are keyed on `HttpError.status`, not on the text of the message. The 409 used to
+ * be sniffed with `/\b409\b|net content loss|conflict/i`, which both over-matched (any response
+ * body happening to contain "409" or "conflict") and under-matched (a real 409 whose body says
+ * neither). `cause` is threaded through so the original typed error — and with it `code` and
+ * `status` — still reaches the tool boundary instead of being flattened away here.
+ */
+async function postContent(dotcms, pageId, body, variantName, languageId) {
+    try {
+        await dotcms.request({
+            method: 'POST',
+            path: `/api/v1/page/${encodeURIComponent(pageId)}/content`,
+            query: { variantName, language_id: languageId },
+            body
+        });
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        // Each explanation is added to the save's own error (`withMessage`), never a new one:
+        // its class and status are what tell the model whether a retry can help.
+        if (error instanceof HttpError && error.status === 409) {
+            throw withMessage(error, 'Page content save was rejected as a net-loss conflict (the change would remove more ' +
+                'content than allowed, or the page changed underneath this write). Re-read the page ' +
+                `and retry. Original error: ${message}`);
+        }
+        // The 400 branch the docblock has always promised but never had. This is the single
+        // most common failure of this tool in a placement loop, and without naming the cause
+        // the model cannot tell that the fix is a different container or a different content
+        // type — so it retries the identical call and fails identically.
+        if (error instanceof HttpError && error.status === 400) {
+            throw withMessage(error, 'Page content save was rejected (HTTP 400). The usual cause is a contentlet whose ' +
+                'CONTENT TYPE is not permitted in the container it was placed in — check the ' +
+                "container's allowed content types and either place a permitted type or choose " +
+                'a different container. Retrying this same call unchanged will fail the same ' +
+                `way. Original error: ${message}`);
+        }
+        throw withMessage(error, `Failed to save page content: ${message}`);
+    }
+}
+
+// A slot address: a 1-based index into the page's real slots, OR a container reference. `instance`
+// (the slot uuid) is optional only when the container occupies exactly one slot on the page.
+const slotAddress = z.union([
+    z
+        .number()
+        .int()
+        .positive()
+        .describe('1-based index into the page’s slots, in layout order (the first slot is 1).'),
+    z
+        .object({
+        container: z
+            .string()
+            .min(1)
+            .describe('Container key as it appears on the page: a container id/shorty, a container ' +
+            'file path (e.g. "//demo.dotcms.com/application/containers/default/"), or a ' +
+            'recognizable fragment of either. "SYSTEM_CONTAINER" for the system container.'),
+        instance: z
+            .string()
+            .optional()
+            .describe('Slot instance uuid (e.g. "1", "10"). Required only when the container appears ' +
+            'in more than one slot; the tool errors and lists the instances if omitted.')
+    })
+        .strict()
+]);
+const definition$3 = defineTool({
+    name: 'page_place_content',
+    title: 'Place Content on a dotCMS Page',
+    inputSchema: z.object({
+        path: z
+            .string()
+            .min(1)
+            .describe('Page URL path, e.g. "/about-us", host-qualified path such as "//demo.dotcms.com/about-us", or a page identifier. Bare paths/identifiers require site.'),
+        // Conditionally required: a host-qualified path already supplies the site. Marking this field
+        // required in JSON Schema would incorrectly reject the supported `//hostname/path` form; the
+        // resolver enforces that exactly one source of site identity is present before any request.
+        site: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Site hostname or identifier (UUID). Required for a bare path or page identifier. Omit only when path is host-qualified as "//hostname/path".'),
+        slots: z
+            .array(z
+            .object({
+            slot: slotAddress,
+            contentlets: z
+                .array(z.string().min(1))
+                .describe('Contentlet identifiers to place, in order. For op "remove" these are ' +
+                'the ids to remove; to clear a slot use op "set" with [].'),
+            op: z
+                .enum(['append', 'set', 'remove'])
+                .optional()
+                .describe('How to combine with the slot’s current content. "append" (default) ' +
+                'adds after existing (de-duped), "set" replaces, "remove" removes.')
+        })
+            .strict())
+            .min(1)
+            .describe('One or more slot assignments applied in a single atomic write. Placing content in one ' +
+            'slot is just an array of one. Each entry: { slot, contentlets, op? }.'),
+        // ── scope ──
+        variantName: z.string().optional().describe('Variant to write to. Default "DEFAULT".'),
+        languageId: z.number().int().positive().optional().describe('Language id. Default 1.'),
+        mode: z
+            .enum(['merge', 'replace'])
+            .optional()
+            .describe('"merge" (default) preserves every slot you don’t touch. "replace" treats the slots ' +
+            'you pass as the complete page — every other slot is cleared.')
+    }),
+    description: `Place content into a dotCMS page's container slots — safely, without wiping the rest of the page.
+
+The underlying endpoint (POST /api/v1/page/{pageId}/content) is a FULL replacement: it rewrites the
+page's entire container-to-contentlet map, and any slot omitted from the body is emptied. Adding one
+contentlet "the raw way" therefore silently clears every other slot. This tool removes that footgun:
+it reads the page's current content, applies your change to the addressed slot(s) only, and writes
+the COMPLETE map back — so untouched slots survive.
+
+You do NOT need to call GET /api/v1/page/json first. Give the page \`path\` and address a slot by:
+  - a 1-based \`slot\` index (in layout order), or
+  - \`slot: { container, instance? }\` — a container id/path/fragment, plus the slot uuid when that
+    container appears in more than one slot (the tool lists the instances if you omit it).
+A slot that doesn't resolve fails with the list of valid slots, so a typo can't silently no-op.
+
+Ops (per entry in \`slots[]\`):
+  - append (default) — add the ids after what's already in the slot (de-duplicated)
+  - set              — replace the slot's content with exactly these ids ([] clears the slot)
+  - remove           — remove these ids from the slot
+
+Targeting: pass \`site\` with every bare path/identifier, or use a host-qualified path such as
+\`//awazon.dotcms.site/index\`. The tool resolves the hostname to \`host_id\` before reading the page
+and never silently falls back to the default site. If explicit and embedded sites conflict, it
+fails before making a request.
+
+Shape: { path, site?, slots: [{ slot, contentlets, op? }, ...] }. One atomic write across all listed slots
+— placing content in a single slot is just an array of one: slots: [{ slot, contentlets }].
+
+Modes: "merge" (default) keeps every slot you don't address. "replace" treats the slots you pass as
+the whole page and clears all others — use it only for deliberate whole-page authoring.
+
+Scope: \`variantName\` (default DEFAULT) and \`languageId\` (default 1) target a specific A/B variant
+and language.
+
+Returns a manifest: { pageId, site, url, variantName, languageId, mode, slots: [{ identifier, uuid,
+before[], after[], changed }], warnings[] }. \`warnings\` flags any slot that lost content and
+explains a net-loss 409 (refresh and retry). Contentlets whose type isn't allowed in a container are
+rejected by the backend; archived/missing ids are skipped and show up as a slot that didn't gain them.
+
+Typical flow: create the (blank) page with \`page_create\`, then populate it with this tool. The
+contentlets themselves are created separately (e.g. via the \`execute\` tool) — this tool only places
+existing contentlets into slots.`,
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+    },
+    endpoints: PAGE_PLACE_CONTENT_ENDPOINTS,
+    async handler(args, ctx) {
+        const options = {
+            dotcms: ctx.runtime(),
+            path: args.path,
+            site: args.site,
+            slots: args.slots,
+            variantName: args.variantName,
+            languageId: args.languageId,
+            mode: args.mode
+        };
+        return placeContent(options);
+    }
+});
+/**
+ * The `page_place_content` tool: places contentlets into a page's slots while preserving
+ * every slot it was not asked to touch. Resolves to a {@link PagePlaceContentManifest}.
+ */
+function pagePlaceContentTool(connection, options = {}) {
+    return createTool(definition$3, connection, options);
+}
+
+/**
+ * Every endpoint `verifyPage` calls — all reads. The `page_verify` tool enforces exactly this
+ * list, and `page-verify.spec.ts` checks every request against it. Add a request, add it here.
+ */
+const PAGE_VERIFY_ENDPOINTS = [
+    ...CONTEXT_ENDPOINTS,
+    ...RESOLVE_ENDPOINTS,
+    'GET /api/v1/page/render/**'
+];
+/** The default render mode when the caller does not name one. */
+const DEFAULT_MODE = 'LIVE';
+/**
+ * The `mode` the render endpoint is sent for each {@link VerifyMode}.
+ *
+ * dotCMS defines a `PageMode.WORKING`, but its velocity renderer (`VelocityModeHandler`)
+ * registers no handler for it, so `mode=WORKING` fails with a 500 — a NullPointerException —
+ * on every page. `PREVIEW_MODE` has the same flags (working versions, anonymous permissions
+ * respected) and renders. The caller still says `WORKING`, and the manifest reports it.
+ */
+const RENDER_MODE = { LIVE: 'LIVE', WORKING: 'PREVIEW_MODE' };
+/** The default language id when the caller does not name one. */
+const DEFAULT_LANGUAGE_ID = 1;
+const MAX_INCLUDED_HTML_CHARS = 20_000;
+/**
+ * Verify that a dotCMS page actually renders — the layer that catches a blank slot, a swallowed
+ * #dotParse error, a cache-stale page, or an unpublished edit, none of which a VTL-only check
+ * (/api/vtl/dynamic) can see because that runs in a request context, not a render context.
+ *
+ * Wraps GET /api/v1/page/render/{uri} and absorbs its sharp edges:
+ *   - Host: the caller passes a hostname (or nothing); the tool resolves it to a host_id. host_id is
+ *     required only for a NON-default site — omit `site` and the default site is used.
+ *   - 200 != rendered: #dotParse swallows a VTL error into an empty HTTP 200, so a 200 with an empty
+ *     body is a failure, surfaced as pageRendered=false, not success.
+ *   - Two rendered layers that can disagree: each slot's rendered HTML (containers[].rendered[uuid])
+ *     vs. the assembled page.rendered. The disagreement IS the diagnosis (cache-stale) as opposed to
+ *     an empty slot (VTL error or no content).
+ *
+ * Returns a structured verdict — per-slot classification plus a one-line diagnosis with the next
+ * action — instead of two JSON blobs the caller has to compare by hand.
+ */
+async function verifyPage(options) {
+    const mode = options.mode ?? DEFAULT_MODE;
+    const languageId = options.languageId ?? DEFAULT_LANGUAGE_ID;
+    // Resolve the site to a host_id ONLY when one was given. Absent → the backend uses the default
+    // site, and we send no host_id (the render endpoint's documented default behavior).
+    const resolvedSite = options.site ? await resolveSite(options.dotcms, options.site) : undefined;
+    // Normalized BEFORE it reaches the request URL: `/a/../b` used to render `/b` while the
+    // manifest reported `/a/../b`, and a `#` silently truncated the path.
+    const uri = normalizePagePath(options.path);
+    const query = {
+        language_id: languageId,
+        mode: RENDER_MODE[mode]
+    };
+    if (resolvedSite) {
+        query['host_id'] = resolvedSite.identifier;
+    }
+    const { status, body } = await renderPage(options.dotcms, uri, query);
+    return buildManifest({
+        path: options.path,
+        uri,
+        siteLabel: resolvedSite?.hostname ?? '(default)',
+        mode,
+        languageId,
+        status,
+        body,
+        includeHtml: options.includeHtml ?? false
+    });
+}
+/** Assemble the verdict manifest from a render response. Pure — no I/O, so it is unit-testable. */
+function buildManifest(input) {
+    const entity = input.body.entity ?? {};
+    const page = entity.page ?? {};
+    const containers = entity.containers ?? {};
+    const rows = entity.layout?.body?.rows ?? [];
+    const pageHtml = page.rendered ?? '';
+    const pageBytes = byteLength(pageHtml);
+    const pageRendered = !isBlank(pageHtml);
+    const url = page.pageURI ?? page.pageUrl ?? page.url ?? input.uri;
+    const slots = [];
+    for (const row of rows) {
+        for (const column of row.columns ?? []) {
+            for (const layoutContainer of column.containers ?? []) {
+                const container = layoutContainer.identifier;
+                const uuid = layoutContainer.uuid;
+                if (!container || !uuid) {
+                    continue;
+                }
+                slots.push(classifySlot(containers, container, uuid, pageHtml));
+            }
+        }
+    }
+    const urlMap = resolveUrlMap(entity.urlContentMap);
+    const warnings = collectWarnings(slots, pageRendered, input.status, urlMap, input.mode);
+    const diagnosis = diagnose(slots, pageRendered, input.status, urlMap, input.mode);
+    const manifest = {
+        path: input.path,
+        url,
+        site: input.siteLabel,
+        mode: input.mode,
+        languageId: input.languageId,
+        httpStatus: input.status,
+        pageRendered,
+        pageBytes,
+        slots,
+        urlMap,
+        warnings,
+        diagnosis
+    };
+    if (input.includeHtml) {
+        manifest.html = {
+            content: pageHtml.slice(0, MAX_INCLUDED_HTML_CHARS),
+            totalChars: pageHtml.length,
+            totalBytes: pageBytes,
+            truncated: pageHtml.length > MAX_INCLUDED_HTML_CHARS,
+            limit: MAX_INCLUDED_HTML_CHARS
+        };
+    }
+    return manifest;
+}
+/** Classify one slot from the render response. */
+function classifySlot(containers, container, uuid, pageHtml) {
+    const raw = findContainer(containers, container);
+    const html = lookupByUuid(raw?.rendered, uuid) ?? '';
+    const contentCount = (lookupByUuid(raw?.contentlets, uuid) ?? []).length;
+    const rendered = !isBlank(html);
+    const pageRendered = !isBlank(pageHtml);
+    const bytes = byteLength(html);
+    let verdict;
+    if (rendered) {
+        // The slot produced HTML. If the assembled page did NOT, that is a page-level cache problem.
+        if (!pageRendered) {
+            verdict = 'cache-stale';
+        }
+        else if (!slotEvidenceAppearsInPage(html, pageHtml)) {
+            verdict = 'not-assembled';
+        }
+        else {
+            verdict = 'ok';
+        }
+    }
+    else if (contentCount > 0) {
+        // Content is placed but rendered to nothing → the container/widget VTL failed.
+        verdict = 'empty-vtl-error';
+    }
+    else {
+        // Nothing placed → a placement gap, not a code bug.
+        verdict = 'empty-no-content';
+    }
+    return { container, uuid, rendered, bytes, contentCount, verdict };
+}
+function resolveUrlMap(urlContentMap) {
+    // The field is present (as null/absent) on every page; a non-null value with an identifier means
+    // the path resolved to a concrete detail contentlet via $URLMapContent.
+    if (urlContentMap === undefined) {
+        return null;
+    }
+    if (urlContentMap === null) {
+        // Present-but-null happens on URL-map-capable responses that did not resolve. We can't tell
+        // that apart from a plain page here, so treat absence of a match as "no url map".
+        return null;
+    }
+    const contentletId = urlContentMap.identifier;
+    return contentletId ? { resolved: true, contentletId } : { resolved: false };
+}
+function collectWarnings(slots, pageRendered, status, urlMap, mode) {
+    const warnings = [];
+    if (status === 200 && !pageRendered) {
+        warnings.push('HTTP 200 but page.rendered is empty — a #dotParse VTL error was likely swallowed into ' +
+            'an empty body. 200 does NOT mean the page rendered.');
+    }
+    for (const slot of slots) {
+        if (slot.verdict === 'empty-vtl-error') {
+            warnings.push(`Slot ${slot.container} [uuid ${slot.uuid}] has ${slot.contentCount} contentlet(s) ` +
+                'placed but rendered empty — the container/widget VTL failed. Re-run that VTL ' +
+                'through POST /api/vtl/dynamic to get the parse/eval error with line/column.');
+        }
+        else if (slot.verdict === 'empty-no-content') {
+            warnings.push(`Slot ${slot.container} [uuid ${slot.uuid}] is empty — no content placed. Use ` +
+                'page_place_content to add contentlets.');
+        }
+        else if (slot.verdict === 'cache-stale') {
+            warnings.push(`Slot ${slot.container} [uuid ${slot.uuid}] rendered content but the page did not — ` +
+                'page-level cache is stale. Set cachettl "0" and re-publish the page.');
+        }
+        else if (slot.verdict === 'not-assembled') {
+            warnings.push(`Slot ${slot.container} [uuid ${slot.uuid}] rendered content, but its HTML is ` +
+                'absent from the assembled page — the template/theme layout loop is not ' +
+                "emitting this container. Inspect the theme's row/column loop and use " +
+                '$render.eval($column.draw()).');
+        }
+    }
+    if (urlMap && !urlMap.resolved) {
+        warnings.push('This looks like a URL-mapped page but the path did not resolve to a detail contentlet ' +
+            '($URLMapContent hit the no-match branch). Check the detail-page slug.');
+    }
+    if (mode === 'WORKING' && pageRendered) {
+        warnings.push('Rendered in WORKING mode — this reflects unpublished edits. Re-verify with mode "LIVE" ' +
+            'to confirm what the public actually sees.');
+    }
+    return warnings;
+}
+/** Derive the one-line diagnosis + next action from the worst thing found. */
+function diagnose(slots, pageRendered, status, urlMap, mode) {
+    if (status !== 200) {
+        return `Render returned HTTP ${status}. The page did not render — check the path, site, and that the page exists in ${mode} mode.`;
+    }
+    if (urlMap && !urlMap.resolved) {
+        return 'URL-mapped page did not resolve to a detail contentlet — the slug hit the no-match branch. Verify the detail-page slug exists and is published.';
+    }
+    const vtlError = slots.find((s) => s.verdict === 'empty-vtl-error');
+    if (vtlError) {
+        return `Slot ${vtlError.container} [uuid ${vtlError.uuid}] has content but rendered empty (VTL error). Next: re-run that container's VTL through POST /api/vtl/dynamic to get the parse/eval error.`;
+    }
+    const stale = slots.find((s) => s.verdict === 'cache-stale');
+    if (stale || (!pageRendered && slots.some((s) => s.rendered))) {
+        return 'Slots rendered but the assembled page.rendered is empty — page-level cache is stale. Next: set cachettl "0" and re-publish the page.';
+    }
+    const notAssembled = slots.find((s) => s.verdict === 'not-assembled');
+    if (notAssembled) {
+        return `Slot ${notAssembled.container} [uuid ${notAssembled.uuid}] rendered in isolation but is absent from the assembled page. Next: inspect the theme's row/column loop and ensure it emits $render.eval($column.draw()).`;
+    }
+    if (!pageRendered) {
+        return `HTTP 200 but the page rendered empty (a swallowed #dotParse error, or nothing is placed). Next: check per-slot verdicts${mode === 'LIVE' ? ' and confirm the page is published' : ''}.`;
+    }
+    const noContent = slots.filter((s) => s.verdict === 'empty-no-content');
+    if (noContent.length > 0) {
+        return `Page rendered, but ${noContent.length} slot(s) are empty (no content placed). Next: use page_place_content to fill them if intended.`;
+    }
+    // Zero slots is NOT a clean bill of health. `collectWarnings` iterates `slots`, so an
+    // empty list yields no warnings, and the sentence below would interpolate to "all 0
+    // slot(s) produced content" — the tool built to catch blank slots declaring success over
+    // a page whose layout it could not read. Legacy/advanced templates, and any response with
+    // `entity.containers` populated but no `entity.layout.body.rows`, land exactly here.
+    if (slots.length === 0) {
+        return (`The page rendered in ${mode} mode, but NO slots could be parsed from its layout, ` +
+            `so per-slot verification did not run and this is not a clean result. The template ` +
+            `may be legacy/advanced (no layout.body.rows), or the response shape may be ` +
+            `unexpected. Next: inspect the page's template directly — do not read this as "the ` +
+            `page is fine".`);
+    }
+    return `Page rendered successfully in ${mode} mode — all ${slots.length} slot(s) produced content.`;
+}
+/** GET the render endpoint, capturing the HTTP status even on a non-2xx so verdicts can use it. */
+async function renderPage(dotcms, uri, query) {
+    try {
+        const body = (await dotcms.request({
+            path: `/api/v1/page/render${uri}`,
+            query
+        }));
+        return { status: 200, body };
+    }
+    catch (error) {
+        // A 404/403/etc. is a legitimate verify outcome, not a tool failure — surface it in the
+        // manifest with an empty body so the diagnosis explains the HTTP result.
+        //
+        // ONLY a real HttpError qualifies. The previous version fell back to scraping the
+        // first three-digit run out of the message, which turned any error containing a
+        // number into a fabricated verdict: `connect ETIMEDOUT 10.0.0.5:443` became status
+        // 443, and `buildManifest` then stated flatly that the page did not render and to
+        // check the path, site and existence — about a page that is very likely fine. The
+        // model's next move is to "fix" something that was never broken. A transport failure
+        // must surface AS a transport failure.
+        if (error instanceof HttpError) {
+            return { status: error.status, body: {} };
+        }
+        throw error;
+    }
+}
+/**
+ * The layout `identifier` may not be byte-identical to the containers-map key (shorty vs full id,
+ * host-relative vs host-qualified path). Match tolerantly, same as page_place_content.
+ */
+function findContainer(containers, identifier) {
+    if (containers[identifier]) {
+        return containers[identifier];
+    }
+    const key = Object.keys(containers).find((k) => containerMatches(k, identifier));
+    return key ? containers[key] : undefined;
+}
+function containerMatches(a, b) {
+    if (a === b)
+        return true;
+    const la = a.toLowerCase();
+    const lb = b.toLowerCase();
+    return la === lb || la.includes(lb) || lb.includes(la);
+}
+/** The per-slot maps are historically keyed as "1" or "uuid-1"; look up tolerantly. */
+function lookupByUuid(map, uuid) {
+    if (!map) {
+        return undefined;
+    }
+    const direct = map[uuid] ?? map[`uuid-${uuid}`] ?? map[stripUuidPrefix(uuid)];
+    if (direct !== undefined) {
+        return direct;
+    }
+    const key = Object.keys(map).find((k) => stripUuidPrefix(k) === stripUuidPrefix(uuid));
+    return key ? map[key] : undefined;
+}
+function stripUuidPrefix(uuid) {
+    return uuid.startsWith('uuid-') ? uuid.slice('uuid-'.length) : uuid;
+}
+/**
+ * Confirm assembly using several short, normalized pieces of evidence rather than an exact HTML
+ * substring. Theme assembly may rewrite whitespace and entity encoding, so exact matching would
+ * label healthy pages as broken. If no reliable evidence can be extracted, return true (unknown)
+ * instead of issuing a false failure.
+ */
+function slotEvidenceAppearsInPage(slotHtml, pageHtml) {
+    const candidates = assemblyEvidence(slotHtml);
+    if (candidates.length === 0) {
+        return true;
+    }
+    const normalizedPage = normalizeEvidence(pageHtml);
+    return candidates.some((candidate) => normalizedPage.includes(candidate));
+}
+function assemblyEvidence(html) {
+    const candidates = [];
+    const attributePattern = /\b(?:id|data-[\w:-]+)\s*=\s*["']([^"']+)["']/gi;
+    for (const match of html.matchAll(attributePattern)) {
+        addEvidence(candidates, match[1], 6);
+    }
+    const classPattern = /\bclass\s*=\s*["']([^"']+)["']/gi;
+    for (const match of html.matchAll(classPattern)) {
+        for (const className of match[1].split(/\s+/)) {
+            addEvidence(candidates, className, 8);
+        }
+    }
+    const visibleText = decodeEntities(html
+        .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ')
+        .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ')
+        .replace(/<[^>]+>/g, ' '));
+    for (const textRun of visibleText.split(/\s{2,}|[.!?]\s+/)) {
+        addEvidence(candidates, textRun, 12);
+    }
+    return [...new Set(candidates)].slice(0, 12);
+}
+function addEvidence(target, raw, minimumLength) {
+    const normalized = normalizeEvidence(raw);
+    if (normalized.length >= minimumLength) {
+        target.push(normalized);
+    }
+}
+function normalizeEvidence(value) {
+    return decodeEntities(value).replace(/\s+/g, ' ').trim().toLowerCase();
+}
+function decodeEntities(value) {
+    const named = {
+        amp: '&',
+        apos: "'",
+        gt: '>',
+        lt: '<',
+        nbsp: ' ',
+        quot: '"'
+    };
+    return value.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (entity, token) => {
+        if (token[0] !== '#') {
+            return named[token.toLowerCase()] ?? entity;
+        }
+        const hex = token[1]?.toLowerCase() === 'x';
+        const codePoint = Number.parseInt(token.slice(hex ? 2 : 1), hex ? 16 : 10);
+        return Number.isFinite(codePoint) ? String.fromCodePoint(codePoint) : entity;
+    });
+}
+/** Empty or whitespace-only (comments/blank lines count as "not rendered" for verdict purposes). */
+function isBlank(html) {
+    return html.trim().length === 0;
+}
+function byteLength(html) {
+    // Byte length, not char length — multibyte content should report its real size.
+    return typeof TextEncoder !== 'undefined'
+        ? new TextEncoder().encode(html).length
+        : Buffer.byteLength(html, 'utf8');
+}
+
+const definition$2 = defineTool({
+    name: 'page_verify',
+    title: 'Verify a dotCMS Page Renders',
+    inputSchema: z.object({
+        path: z
+            .string()
+            .min(1)
+            .describe('Page URL path, e.g. "/about-us". For a URL-mapped detail page, pass a concrete slug ' +
+            '(e.g. "/blog/my-post") — the tool reports whether $URLMapContent resolved.'),
+        site: z
+            .string()
+            .optional()
+            .describe('Site to render against — hostname or identifier (UUID). Omit for the default site. ' +
+            'Only a NON-default site needs this; the tool resolves it to the host_id the ' +
+            'endpoint requires.'),
+        languageId: z.number().int().positive().optional().describe('Language id. Default 1.'),
+        mode: z
+            .enum(['LIVE', 'WORKING'])
+            .optional()
+            .describe('Render mode. "LIVE" (default) = what the public sees (published). "WORKING" = latest ' +
+            'saved, for a pre-publish check. An unpublished edit renders stale in LIVE.'),
+        includeHtml: z
+            .boolean()
+            .optional()
+            .describe('Include a bounded prefix of the assembled page HTML for diagnosis. Default false; returns at most 20,000 characters with truncation metadata.')
+    }),
+    description: `Verify that a dotCMS page actually RENDERS — catch a blank slot, a swallowed VTL error, a cache-stale page, or an unpublished edit.
+
+This is the render-verification layer, distinct from VTL validation (POST /api/vtl/dynamic). VTL
+validation runs in a REQUEST context and is structurally blind to $URLMapContent, $CONTENTLETS,
+$dotContentMap, $dotTheme, and per-container vars. Only a real render exercises the full
+page-assembly pipeline — so this is the only layer that catches a slot that came out empty, a
+#dotParse error that got swallowed, or a page serving stale from cache.
+
+It wraps GET /api/v1/page/render/{uri} and absorbs its sharp edges:
+  - Host: pass a hostname in \`site\` (or nothing). The tool resolves it to the host_id the endpoint
+    needs. host_id is required only for a NON-default site; omit \`site\` for the default site.
+  - 200 != rendered: #dotParse swallows a VTL error into an empty HTTP 200. A 200 with an empty body
+    is a FAILURE here (pageRendered=false), not success.
+  - Two rendered layers that can disagree: each slot's HTML (containers[].rendered[uuid]) vs. the
+    assembled page.rendered. Their disagreement IS the diagnosis.
+
+Per-slot \`verdict\`:
+  - ok               — the slot produced rendered HTML.
+  - empty-vtl-error  — content is placed but the slot rendered empty → the container/widget VTL
+                       failed. The fix lives in the OTHER layer: re-run that container's VTL through
+                       POST /api/vtl/dynamic to get the parse/eval error with line/column.
+  - empty-no-content — the slot resolved but has no content placed (a placement gap, not a code bug).
+                       Use page_place_content to fill it.
+  - cache-stale      — the slot rendered HTML but page.rendered is empty → page-level cache. Set
+                       cachettl "0" and re-publish.
+  - not-assembled    — the slot rendered in isolation but distinctive HTML evidence is absent from
+                       page.rendered → inspect the theme row/column loop and emit
+                       $render.eval($column.draw()).
+
+LIVE vs WORKING: an unpublished edit renders stale in LIVE. Use mode "WORKING" for a pre-publish
+check; the result flags that it reflects unpublished edits.
+
+URL-mapped pages: for a detail slug, \`urlMap\` reports whether $URLMapContent resolved to a concrete
+contentlet (vs. the no-match/404 branch).
+
+Returns a manifest: { path, url, site, mode, languageId, httpStatus, pageRendered, pageBytes,
+slots: [{ container, uuid, rendered, bytes, contentCount, verdict }], urlMap, warnings, diagnosis }.
+The \`diagnosis\` is a one-line summary plus the next action to take — read it first.
+
+Set \`includeHtml: true\` to add \`html: { content, totalChars, totalBytes, truncated, limit }\`.
+The content is capped at 20,000 characters so a diagnostic call cannot flood model context.
+
+Out of scope: visual/screenshot checks, accessibility, performance, multi-page crawl (one page per
+call). This verifies DEFAULT-variant rendering — the render endpoint does not take a variant.`,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+    },
+    endpoints: PAGE_VERIFY_ENDPOINTS,
+    async handler(args, ctx) {
+        const options = {
+            dotcms: ctx.runtime(),
+            path: args.path,
+            site: args.site,
+            languageId: args.languageId,
+            mode: args.mode,
+            includeHtml: args.includeHtml
+        };
+        return verifyPage(options);
+    }
+});
+/**
+ * The `page_verify` tool: renders a page and diagnoses each slot — empty, swallowed VTL
+ * error, stale cache, not assembled. Read-only. Resolves to a {@link VerifyPageManifest}.
+ */
+function pageVerifyTool(connection, options = {}) {
+    return createTool(definition$2, connection, options);
+}
+
+/**
+ * What `uploadAssets` and `downloadAssets` share: the entries their manifests are made of, the
+ * dotCMS path form both accept, and how a manifest is finished.
+ */
+function normalizeDotCMSPath(input) {
+    const value = input.trim().replace(/\/+$/, '');
+    if (value.startsWith('//')) {
+        const firstSlash = value.slice(2).indexOf('/');
+        if (firstSlash < 0) {
+            throw new ValidationError(`Site-qualified path "${input}" must include a path`);
+        }
+        return { siteQualified: value, path: value.slice(firstSlash + 2) };
+    }
+    if (!value.startsWith('/')) {
+        throw new ValidationError(`dotCMS path "${input}" must start with "/" or "//host/"`);
+    }
+    return { path: value };
+}
+function sumBytes(files) {
+    return files.reduce((sum, file) => sum + file.bytes, 0);
+}
+function sortManifest(manifest) {
+    const byPath = (a, b) => a.path.localeCompare(b.path);
+    manifest.files.sort(byPath);
+    manifest.failures.sort(byPath);
+    manifest.skipped?.sort(byPath);
+    manifest.notLive?.sort(byPath);
+    return manifest;
+}
+
+/**
+ * The `include` glob filter the asset operations share: `upload_assets` matches it against
+ * local paths relative to `src`, `download_assets` against dotCMS paths relative to the folder.
+ */
+/**
+ * Split an `include` string into its comma-separated patterns — but NOT on commas inside a brace
+ * group, so `*.{png,webp,jpg}` stays one pattern while `*.vtl,*.scss` is two. Exported for tests.
+ */
+function splitIncludePatterns(include) {
+    if (!include) {
+        return [];
+    }
+    const patterns = [];
+    let current = '';
+    let braceDepth = 0;
+    for (const ch of include) {
+        if (ch === '{') {
+            braceDepth++;
+            current += ch;
+        }
+        else if (ch === '}') {
+            braceDepth = Math.max(0, braceDepth - 1);
+            current += ch;
+        }
+        else if (ch === ',' && braceDepth === 0) {
+            patterns.push(current);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    patterns.push(current);
+    return patterns.map((p) => p.trim()).filter(Boolean);
+}
+/**
+ * Build a matcher over relative POSIX paths from a comma-separated `include` string. A file matches
+ * if it matches ANY pattern. No `include` → matches everything. Exported for tests.
+ *
+ * Supports the glob features callers reasonably assume from a standard glob:
+ *   - `*`  matches any run of chars WITHIN a path segment (does not cross `/`)
+ *   - `**` matches across segments, including zero (so a leading globstar also matches a top-level file)
+ *   - `?`  matches a single non-`/` char
+ *   - `{png,webp,jpg}` brace expansion (alternation)
+ * A pattern with no `/` matches the file's basename anywhere in the tree; a pattern with a `/` is
+ * anchored at the root of `src`.
+ */
+function includeMatcher(include) {
+    const patterns = splitIncludePatterns(include);
+    if (!patterns.length) {
+        return () => true;
+    }
+    // Compile each pattern ONCE here, not per-file — this matcher runs on every asset/file.
+    const regexes = patterns.map(globToRegExp);
+    return (rel) => regexes.some((re) => re.test(rel));
+}
+/**
+ * Compile a single glob pattern to a RegExp with a single left-to-right character scan.
+ *
+ * A scanner (rather than chained `.replace()` passes) is used deliberately: it has no ordering
+ * hazard between `**` and `*`, needs no placeholder sentinels, and each glob token emits its regex
+ * exactly once. The old chained-replace version turned every `*` into `[^/]*`, so a `**` + `/*.png`
+ * pattern compiled to "exactly one subdirectory" and silently matched nothing for top-level files.
+ *
+ * Tokens:
+ *   - `**` (with an optional adjacent `/`) crosses directory boundaries, matching zero or more
+ *     segments, so a leading `**` also matches a top-level file.
+ *   - `*` matches any run of chars within one segment (never crosses `/`).
+ *   - `?` matches a single non-`/` char.
+ *   - `{png,webp,jpg}` expands to alternation `(?:png|webp|jpg)` (nested wildcards are honored).
+ * A pattern containing `/` is anchored at the root of `src`; otherwise it matches a basename
+ * anywhere in the tree.
+ */
+function globToRegExp(pattern) {
+    const normalized = pattern.split(sep).join(posix.sep);
+    const anchored = normalized.includes('/');
+    const source = compileGlob(normalized, 0, normalized.length);
+    return new RegExp(`${anchored ? '^' : '(^|/)'}${source}$`, 'i');
+}
+/** Regex-escape a single literal character. */
+function escapeRegexChar(ch) {
+    return /[|\\{}()[\]^$+.*?]/.test(ch) ? `\\${ch}` : ch;
+}
+/**
+ * Translate the glob in `input[start..end)` to a regex source string. Recurses into brace groups so
+ * `{a*,b}` honors the wildcard inside each alternative.
+ */
+function compileGlob(input, start, end) {
+    let out = '';
+    let i = start;
+    while (i < end) {
+        const ch = input[i];
+        if (ch === '*') {
+            if (input[i + 1] === '*') {
+                // `**` crosses directory boundaries. Consume it plus one adjacent `/` (leading or
+                // trailing) and emit an optional "any number of full segments" fragment.
+                i += 2;
+                const trailing = i >= end;
+                if (input[i] === '/') {
+                    i++;
+                }
+                else if (!trailing && out.endsWith('/')) {
+                    out = out.slice(0, -1);
+                }
+                if (trailing) {
+                    // A globstar with nothing after it — `themes/**` — means "everything
+                    // below here", so it has to be able to match a final FILENAME segment.
+                    // The general fragment below cannot: it only ever ends at a `/`, so
+                    // `themes/**` compiled to `^themes(?:.*/)?$` and matched nothing but the
+                    // bare string `themes`. Since `dir/**` is the common idiom, users writing
+                    // it hit the "matched 0 of N files, check the glob syntax" warning while
+                    // their syntax was perfectly reasonable.
+                    out += '.*';
+                }
+                else {
+                    out += '(?:.*/)?';
+                }
+            }
+            else {
+                out += '[^/]*';
+                i++;
+            }
+        }
+        else if (ch === '?') {
+            out += '[^/]';
+            i++;
+        }
+        else if (ch === '{') {
+            const close = input.indexOf('}', i);
+            if (close === -1 || close >= end) {
+                // Unbalanced brace: treat the `{` literally rather than throwing.
+                out += '\\{';
+                i++;
+            }
+            else {
+                const alternatives = splitTopLevelCommas(input.slice(i + 1, close)).map((alt) => compileGlob(alt, 0, alt.length));
+                out += `(?:${alternatives.join('|')})`;
+                i = close + 1;
+            }
+        }
+        else {
+            out += escapeRegexChar(ch);
+            i++;
+        }
+    }
+    return out;
+}
+/** Split on commas that are NOT inside a nested brace group (for brace-group alternatives). */
+function splitTopLevelCommas(group) {
+    const parts = [];
+    let current = '';
+    let depth = 0;
+    for (const ch of group) {
+        if (ch === '{') {
+            depth++;
+            current += ch;
+        }
+        else if (ch === '}') {
+            depth = Math.max(0, depth - 1);
+            current += ch;
+        }
+        else if (ch === ',' && depth === 0) {
+            parts.push(current);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    parts.push(current);
+    return parts;
+}
+
+/**
+ * The local-filesystem boundary for the asset operations.
+ *
+ * `src` and `dest` come from the model. In the local stdio server that is the user's own agent
+ * on the user's own machine, but in a hosted MCP server or a multi-user agent it is anyone who
+ * can reach the tool — and without a boundary `upload_assets` reads any directory the process
+ * can read (then readable back through `execute`) and `download_assets` writes into any
+ * directory it can write. Every check here compares REAL paths, after symlinks resolve: a
+ * symlink inside the root pointing out of it is outside, and `/tmp` is `/private/tmp` on macOS.
+ */
+function isInside(root, target) {
+    const back = relative(root, target);
+    return !(back === '..' || back.startsWith(`..${sep}`) || isAbsolute(back));
+}
+/**
+ * The real path of `path`, or of its nearest existing ancestor when it does not exist yet. The
+ * tail that does not exist cannot contain a symlink, so the ancestor decides containment —
+ * which is what lets a check run BEFORE `mkdir` creates anything.
+ */
+async function realpathOfNearest(path) {
+    let current = resolve(path);
+    for (;;) {
+        try {
+            return await realpath(current);
+        }
+        catch (error) {
+            const parent = dirname(current);
+            if (error.code !== 'ENOENT' || parent === current) {
+                throw error;
+            }
+            current = parent;
+        }
+    }
+}
+/**
+ * Refuse `path` when it resolves outside `root`. No `root` means no boundary — for trusted,
+ * direct callers of the operations; the tools always set one.
+ */
+async function assertInsideRoot(root, label, path) {
+    if (root === undefined) {
+        return;
+    }
+    const rootReal = await realpath(resolve(root));
+    if (!isInside(rootReal, await realpathOfNearest(path))) {
+        throw new ValidationError(`\`${label}\` must be inside ${rootReal}, the directory this tool is allowed to use, ` +
+            `and ${path} is not (symlinks are resolved before checking).`);
+    }
+}
+/**
+ * Refuse to write `file` when it would land outside `root`: its directory resolves elsewhere,
+ * or the file itself is a symlink — `writeFile` follows one, so a link planted inside the
+ * destination would otherwise redirect the write anywhere.
+ */
+async function assertWritableInsideRoot(root, file) {
+    if (root === undefined) {
+        return;
+    }
+    try {
+        if ((await lstat(file)).isSymbolicLink()) {
+            throw new ValidationError(`Refusing to write through a symlink: ${file}`);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    await assertInsideRoot(root, 'dest', dirname(file));
+}
+
+/**
+ * Every endpoint `uploadAssets` calls — the `upload_assets` tool enforces exactly this list,
+ * and `upload-assets.spec.ts` checks every request against it. Add a request, add it here.
+ */
+const UPLOAD_ASSETS_ENDPOINTS = [
+    // The upload itself: `publish` picks which one.
+    'PUT /api/v2/assets/publish',
+    'PUT /api/v2/assets/save',
+    // `verify`: read each uploaded asset's live status, and re-fire PUBLISH for one that is
+    // not live yet (see verifyLive).
+    'GET /api/v1/content/{identifier}',
+    'PUT /api/v1/workflow/actions/default/fire/PUBLISH'
+];
+const MIME_BY_EXT = {
+    '.css': 'text/css',
+    '.eot': 'application/vnd.ms-fontobject',
+    '.gif': 'image/gif',
+    '.html': 'text/html',
+    '.ico': 'image/x-icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'application/javascript',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.scss': 'text/x-scss',
+    '.svg': 'image/svg+xml',
+    '.ttf': 'font/ttf',
+    '.vtl': 'text/x-velocity',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2'
+};
+/**
+ * Upload every file under a local directory as dotCMS file assets, preserving relative
+ * paths. Files are saved or published one at a time; a failed file is recorded in the
+ * manifest rather than aborting the batch.
+ */
+async function uploadAssets(options) {
+    const src = await prepareReadableDir(options.src, options.root);
+    const dest = normalizeDotCMSPath(options.dest);
+    if (!dest.siteQualified) {
+        throw new ValidationError('Upload destination must be host-qualified, e.g. //demo.dotcms.com/application/themes/travel');
+    }
+    const { files: localFiles, totalSeen } = await collectLocalFiles(src, options.include, {
+        maxFiles: options.maxFiles,
+        maxScannedEntries: options.maxScannedEntries
+    });
+    const files = [];
+    const failures = [];
+    const skipped = [];
+    const warnings = [];
+    if (localFiles.length === 0) {
+        if (options.include && totalSeen > 0) {
+            // The source dir is NOT empty — the include pattern is the problem. Say so distinctly so
+            // this never reads as "nothing to upload" in an unattended run. The matcher supports
+            // *, ? , ** globstar, and {a,b,c} brace expansion, all relative to `src`.
+            warnings.push(`Include pattern "${options.include}" matched 0 of ${totalSeen} file(s) under ` +
+                `"${src}" — check the glob syntax. Patterns are relative to the source dir and ` +
+                `support *, ?, ** (globstar), and {png,webp,jpg} brace expansion (e.g. ` +
+                `"*.{png,webp,jpg}" or "**/*.png"). Nothing was uploaded.`);
+        }
+        else {
+            warnings.push(`No files found under "${src}".`);
+        }
+    }
+    for (const file of localFiles) {
+        if (options.maxFileBytes !== undefined && file.bytes > options.maxFileBytes) {
+            // Before the file is opened, so an oversized one costs nothing but this entry.
+            failures.push({
+                path: file.rel,
+                error: `File is ${file.bytes} bytes, over the ${options.maxFileBytes}-byte upload ` +
+                    `limit (${formatMB(options.maxFileBytes)}), so it was not read or sent. ` +
+                    `Retrying will not help: upload it another way, or ask whoever runs this ` +
+                    `server or agent to raise maxFileBytes.`
+            });
+            continue;
+        }
+        try {
+            // Every file in src lands in dotCMS as-is, 0-byte content included. We do not
+            // skip on empty content: an empty file that exists locally must exist remotely,
+            // otherwise the container can't assemble CONTENT bodies (the empty-skip was the
+            // root cause of a missing postloop.vtl). `skipped[]` is reserved for real skips
+            // (e.g. a glob matching nothing), never for empty content.
+            const uploaded = await uploadOneAsset(options.dotcms, file, `${dest.siteQualified}/${file.rel}`, options.publish);
+            files.push(uploaded.file);
+            if (uploaded.warning) {
+                warnings.push(uploaded.warning);
+            }
+        }
+        catch (error) {
+            failures.push({ path: file.rel, error: errorMessage(error) });
+        }
+    }
+    // Belt AND braces: `verifyLive` guards every await internally, but this call is the last
+    // thing standing between a completed set of writes and the manifest that reports them.
+    // If verification ever fails in a way it did not anticipate, the uploads still happened
+    // and the model still needs to be told exactly what landed — so the worst case here is a
+    // manifest with a warning, never a thrown error that erases the whole report.
+    let notLive = [];
+    if (options.publish && options.verify) {
+        try {
+            const verified = await verifyLive(options.dotcms, files);
+            notLive = verified.notLive;
+            warnings.push(...verified.warnings);
+        }
+        catch (error) {
+            warnings.push(`Upload succeeded but live-verification could not complete: ` +
+                `${errorMessage(error)}. The ${files.length} file(s) listed below WERE ` +
+                `uploaded — do not re-upload them; check their published state directly.`);
+        }
+    }
+    return sortManifest({
+        src,
+        dest: dest.siteQualified,
+        count: files.length,
+        bytes: sumBytes(files),
+        files,
+        failures,
+        skipped,
+        notLive,
+        warnings
+    });
+}
+async function uploadOneAsset(dotcms, file, destPath, publish) {
+    const type = mimeFor(file.rel);
+    // The file travels as a disk-backed Blob, so nothing here reads, copies or base64-encodes
+    // it. `fetch` still gathers the request body before sending, so each upload holds one
+    // copy of its file in memory — the documented upload size limitation. (It held about
+    // four: the read, its base64 string, the decode, and the Blob built from it.)
+    const put = (blob) => dotcms.request({
+        method: 'PUT',
+        path: publish ? '/api/v2/assets/publish' : '/api/v2/assets/save',
+        formData: {
+            path: destPath,
+            file: { name: basename(file.rel), type, blob }
+        }
+    });
+    let response;
+    let warning;
+    try {
+        // Upload the real content, 0-byte included.
+        response = await put(await fileBlob(file.abs, type));
+    }
+    catch (error) {
+        // Fallback: if (and only if) dotCMS rejects a 0-byte body, retry with a single
+        // newline so the file still lands instead of being dropped. The demo postloop.vtl
+        // indicates 0-byte is accepted, so this path is expected to be unused.
+        if (file.bytes === 0) {
+            response = await put(new Blob(['\n'], { type }));
+            // The remote asset now DIFFERS from the source: 1 byte where the source has 0.
+            // Reporting a clean success would leave the caller unable to see that, and for
+            // an empty VTL or CSS partial the difference is invisible until something
+            // downstream behaves oddly. Say it plainly and report the bytes actually sent.
+            warning =
+                `"${file.rel}" is 0 bytes and dotCMS rejected an empty body, so it was ` +
+                    `uploaded as a single newline (1 byte) instead. The remote file does NOT ` +
+                    `match the source exactly.`;
+        }
+        else {
+            throw error;
+        }
+    }
+    return {
+        file: {
+            path: file.rel,
+            bytes: warning ? 1 : file.bytes,
+            identifier: response.entity?.identifier
+        },
+        warning
+    };
+}
+/**
+ * Re-check that every uploaded asset is actually live, re-firing PUBLISH for any that
+ * aren't (up to 3 rounds), then confirming the last round's fires.
+ *
+ * Every await in here is individually guarded, for one reason: this is a READ-ONLY
+ * verification of writes that have ALREADY COMMITTED. A throw escaping this function would
+ * propagate out of `uploadAssets` and discard `files[]`, `failures[]` and `warnings[]` — so
+ * a 120-file theme that uploaded and published perfectly, then hit one flaky liveness GET,
+ * would be reported to the model as a failure. Its next move is to re-upload all 120.
+ *
+ * Verification can therefore only ever downgrade the manifest (add to `notLive`/`warnings`),
+ * never replace it with an exception.
+ */
+async function verifyLive(dotcms, files) {
+    const warnings = [];
+    // A file with no identifier CANNOT be checked, which is not the same as it being fine.
+    // Silently filtering these out meant that if the publish envelope ever stopped matching
+    // the expected shape, every identifier would be undefined, every file would drop out
+    // here, the round loop would never run, and the manifest would report
+    // `count: 120, notLive: [], warnings: []` — indistinguishable from a fully verified
+    // publish when in fact nothing at all was verified.
+    const unverifiable = files.filter((file) => !file.identifier);
+    if (unverifiable.length > 0) {
+        warnings.push(`${unverifiable.length} of ${files.length} uploaded file(s) returned no identifier, ` +
+            `so their live status could NOT be verified: ` +
+            `${unverifiable.map((file) => file.path).join(', ')}. ` +
+            `They may or may not be published — check them directly.`);
+    }
+    let pending = files.filter((file) => file.identifier);
+    for (let round = 0; round < 3 && pending.length > 0; round++) {
+        const notLive = await collectNotLive(dotcms, pending, warnings);
+        if (notLive.length === 0) {
+            return { notLive: [], warnings };
+        }
+        // Sequential, not concurrent: these fire workflow actions against content dotCMS is
+        // concurrently versioning and indexing. The per-item catch is the fix that matters —
+        // previously the first bad fire (locked by another workflow, or a token without
+        // PUBLISH on that folder) threw, so every remaining asset was never even attempted
+        // and nothing recorded which ones those were.
+        for (const file of notLive) {
+            try {
+                await dotcms.request({
+                    method: 'PUT',
+                    path: '/api/v1/workflow/actions/default/fire/PUBLISH',
+                    body: { contentlet: { identifier: file.identifier } }
+                });
+            }
+            catch (error) {
+                warnings.push(`Re-publish failed for "${file.path}" (${file.identifier}): ` +
+                    `${errorMessage(error)}. Remaining files were still attempted.`);
+            }
+        }
+        pending = notLive;
+    }
+    // The PUBLISH fired in the final round has not been verified yet — without this pass an
+    // asset that only goes live on its last re-fire would be reported as notLive despite
+    // having published successfully (a false negative in the transfer manifest).
+    return { notLive: await collectNotLive(dotcms, pending, warnings), warnings };
+}
+/**
+ * Which of `files` are not live yet.
+ *
+ * Pure GETs on distinct identifiers with no interdependence, so they run concurrently via
+ * `allSettled` — a 120-file theme was previously up to 3 rounds of 120 sequential round
+ * trips plus a final 120, and only the last round's results mattered.
+ *
+ * `allSettled` (not `all`) for the same reason the whole function is guarded: `all` fails
+ * fast and discards its settled siblings, and here those siblings ARE the answer. A single
+ * rejected read must not decide the fate of the other 119. A file whose check failed is
+ * treated as NOT-not-live — it is left out of `notLive` and reported as a warning, so an
+ * unreadable status never masquerades as a confirmed failure.
+ */
+async function collectNotLive(dotcms, files, warnings) {
+    const results = await Promise.allSettled(files.map((file) => isContentLive(dotcms, file.identifier)));
+    const notLive = [];
+    results.forEach((result, index) => {
+        const file = files[index];
+        if (result.status === 'rejected') {
+            warnings.push(`Could not check whether "${file.path}" (${file.identifier}) is live: ` +
+                `${errorMessage(result.reason)}.`);
+            return;
+        }
+        if (!result.value) {
+            notLive.push(file);
+        }
+    });
+    return notLive;
+}
+/**
+ * Walk `src` and return the files matching `include` (all files when no `include`), plus
+ * `totalSeen` — the count of files present regardless of the filter. `totalSeen` lets the caller
+ * distinguish "the source dir is empty" from "your include pattern matched none of N real files",
+ * so a mistyped glob is reported as a syntax problem instead of silent success.
+ */
+async function collectLocalFiles(src, include, limits) {
+    const matches = includeMatcher(include);
+    const files = [];
+    const { maxFiles, maxScannedEntries } = limits;
+    let totalSeen = 0;
+    let scanned = 0;
+    // An explicit queue, not recursion: each directory is read to the end and closed before
+    // the next one is opened, so the walk holds ONE directory handle however deep `src` goes.
+    // Recursing from inside the loop kept every ancestor open, and a deep tree hit EMFILE long
+    // before the scan limit. The queue itself is bounded by the scan limit, since every
+    // directory in it was counted as an entry.
+    const pending = [src];
+    for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
+        // Streamed with `opendir`, a few entries at a time: `readdir` would load a directory's
+        // whole listing before the scan limit could stop it, so one directory of millions of
+        // entries would cost unbounded time and memory. `for await` closes the directory when
+        // the loop ends, breaks or throws — the limit's throw included.
+        for await (const entry of await opendir(dir)) {
+            const abs = join(dir, entry.name);
+            // Every entry counts, directory or file, matched or not: the walk's cost is what
+            // it visits, and a narrow `include` does not make a vast tree any cheaper to walk.
+            scanned++;
+            if (maxScannedEntries !== undefined && scanned > maxScannedEntries) {
+                throw new ValidationError(`Stopped after it scanned ${maxScannedEntries} entries under "${src}" ` +
+                    `without reaching the end, over the upload's scan limit. Nothing was ` +
+                    `uploaded. Narrow \`src\` to a smaller directory — \`include\` filters ` +
+                    `what is uploaded, but not what is walked.`);
+            }
+            if (entry.isDirectory()) {
+                pending.push(abs);
+                continue;
+            }
+            if (!entry.isFile()) {
+                continue;
+            }
+            totalSeen++;
+            const rel = relative(src, abs).split(sep).join(posix.sep);
+            if (!matches(rel)) {
+                continue;
+            }
+            const info = await stat(abs);
+            files.push({ abs, rel, bytes: info.size });
+            // Thrown mid-walk, so a `src` far over the limit is not walked to the end first.
+            if (maxFiles !== undefined && files.length > maxFiles) {
+                throw new ValidationError(`"${src}" holds more than ${maxFiles} file(s) to upload${include ? ` matching "${include}"` : ''}, ` +
+                    `over the upload's file limit. Nothing was uploaded. Narrow \`src\` to a ` +
+                    `smaller directory or \`include\` to fewer files.`);
+            }
+        }
+    }
+    return { files: files.sort((a, b) => a.rel.localeCompare(b.rel)), totalSeen };
+}
+async function prepareReadableDir(src, root) {
+    if (!isAbsolute(src)) {
+        throw new ValidationError(`Source must be an absolute path: ${src}`);
+    }
+    const resolved = resolve(src);
+    const info = await stat(resolved);
+    if (!info.isDirectory()) {
+        throw new ValidationError(`Source must be a directory: ${src}`);
+    }
+    await assertInsideRoot(root, 'src', resolved);
+    await access(resolved, fs.constants.R_OK);
+    return resolved;
+}
+/** Bytes as a human-readable megabyte figure, for a limit message. */
+function formatMB(bytes) {
+    return `${Math.round((bytes / (1024 * 1024)) * 10) / 10} MB`;
+}
+function mimeFor(path) {
+    return MIME_BY_EXT[extname(path).toLowerCase()] || 'application/octet-stream';
+}
+/**
+ * A Blob whose bytes stay on disk until something reads them. Node has `fs.openAsBlob`
+ * (from 19.8; the package requires 20). Under Bun, `Bun.file` is the same thing and does
+ * not depend on how complete Bun's `node:fs` is.
+ */
+async function fileBlob(path, type) {
+    const bun = globalThis.Bun;
+    if (bun) {
+        return bun.file(path, { type });
+    }
+    return fs.openAsBlob(path, { type });
+}
+
+/**
+ * A boolean that also accepts the string forms tool-calling clients (MCP and others) often
+ * send ("true"/"false"/"1"/"0"). Plain `z.coerce.boolean()` is wrong here: it uses JS
+ * truthiness, so the string "false" becomes `true`. This maps the string forms to their
+ * intended value and leaves real booleans untouched.
+ *
+ * The default is declared twice, on purpose. The inner one covers a blank string, which the
+ * preprocess turns into `undefined` AFTER the outer wrapper has already let it through. The
+ * outer one is what marks the field optional in the generated JSON Schema: a preprocess hides
+ * the inner default from `z.toJSONSchema`, so without it the schema a model reads lists the
+ * field as REQUIRED even though omitting it is the normal case.
+ */
+const lenientBoolean = (defaultValue) => z
+    .preprocess((value) => {
+    if (typeof value === 'string') {
+        const v = value.trim().toLowerCase();
+        // An empty (or whitespace-only) string means "I did not set this", so it has to
+        // become `undefined` — `.default()` only substitutes on `undefined`, so returning
+        // the original `''` skipped the default entirely and failed validation with
+        // "Expected boolean, received string" for an argument the caller never set.
+        if (v === '')
+            return undefined;
+        if (v === 'false' || v === '0' || v === 'no')
+            return false;
+        if (v === 'true' || v === '1' || v === 'yes')
+            return true;
+    }
+    return value;
+}, z.boolean().default(defaultValue))
+    .default(defaultValue);
+
+const definition$1 = defineTool({
+    name: 'upload_assets',
+    title: 'Upload dotCMS Assets',
+    inputSchema: z.object({
+        src: z
+            .string()
+            .min(1)
+            .describe('Absolute local directory the server reads files from. Must be inside the directory the server allows; a path outside it fails and names that directory.'),
+        dest: z
+            .string()
+            .min(1)
+            .describe('Host-qualified dotCMS destination folder, e.g. //demo.dotcms.com/application/themes/travel'),
+        include: z
+            .string()
+            .optional()
+            .describe('Optional comma-separated glob filter, matched against each file path RELATIVE to `src`. ' +
+            'Supports *, ? (single non-slash char), ** (globstar, crosses directories), and ' +
+            '{a,b,c} brace expansion. A pattern with no "/" matches the basename anywhere in the ' +
+            'tree; a pattern with a "/" is anchored at the top of `src`. Examples: "*.vtl,*.scss", ' +
+            '"*.{png,webp,jpg}", "**/*.png". A comma inside {…} does not split patterns.'),
+        publish: lenientBoolean(true).describe('Use /api/v2/assets/publish when true, otherwise /api/v2/assets/save'),
+        verify: lenientBoolean(true).describe('After publishing, verify live status through /api/v1/content/{identifier}')
+    }),
+    description: `Upload one or more local files as dotCMS file assets (themes, VTL, CSS, JS, images, fonts, …).
+
+ALWAYS use this tool to put files into dotCMS — do NOT hand-roll uploads with the \`execute\`
+tool, a direct API call, or a custom script. This is the supported path and it is strictly
+better for two reasons:
+  1. File bytes are read from disk by the server and sent straight to dotCMS — they NEVER
+     pass through your context. Use this whenever you'd otherwise inline file content (e.g. large
+     VTL/CSS blobs) into a tool call; it keeps that content out of the conversation entirely.
+  2. Auth is already configured on the server. You do NOT need a dotCMS token, a \`.env\` file, or
+     any local credentials — never go looking for them.
+
+Use it whenever local files need to land in dotCMS — whether the user explicitly asks to
+"upload/push/publish," OR you decided to write files as part of a larger task and now need them
+in dotCMS. Example: the user says "create a theme"; you write the theme files to a local
+directory, then call this tool to upload them. Putting files in dotCMS is always a step you
+take with this tool — not something you wait to be told to do, and not something you improvise.
+
+Provide an absolute source directory (\`src\`) and a host-qualified destination (\`dest\`, e.g.
+\`//demo.dotcms.com/application/themes/travel\`). Optional \`include\` globs limit which files go.
+The tool preserves relative paths and returns only a JSON manifest — never the file bytes.
+
+Reserved-folder trap: \`assets\` is a RESERVED top-level folder name — a \`dest\` like
+\`//host/assets/...\` fails with "reserved folder name: assets". Put files under \`/application\`
+(the conventional home for themes, VTL, containers, e.g. \`//host/application/themes/<name>\`) or
+another non-reserved path. \`dest\` must be host-qualified (start with \`//<hostname>/\`).
+
+Tip: to avoid inlining large templates, write them to files on disk and upload them with this
+tool, then reference them from a container/template via \`#dotParse\`.`,
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+    },
+    endpoints: UPLOAD_ASSETS_ENDPOINTS,
+    async handler(args, ctx) {
+        return uploadAssets({
+            dotcms: ctx.runtime(),
+            root: ctx.options.root,
+            src: args.src,
+            dest: args.dest,
+            include: args.include,
+            publish: args.publish,
+            verify: args.verify,
+            maxFileBytes: ctx.options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES,
+            maxFiles: ctx.options.maxFiles ?? DEFAULT_MAX_FILES,
+            maxScannedEntries: ctx.options.maxScannedEntries ?? DEFAULT_MAX_SCANNED_ENTRIES
+        });
+    }
+});
+/** The `upload_assets` tool's per-file limit when the host sets none: 100 MB. */
+const DEFAULT_MAX_FILE_BYTES = 100 * 1024 * 1024;
+/** The `upload_assets` tool's file-count limit when the host sets none. */
+const DEFAULT_MAX_FILES = 1_000;
+/** The `upload_assets` tool's walk limit when the host sets none: 20× the file limit. */
+const DEFAULT_MAX_SCANNED_ENTRIES = 20_000;
+/**
+ * The `upload_assets` tool: uploads a local directory into dotCMS as file assets — the bytes
+ * never pass through the model. Needs Node or Bun. Resolves to an {@link UploadAssetsManifest}.
+ * `options.root` bounds which local directories the model may read from.
+ *
+ * The model chooses `src`, so the tool is bounded by default: `options.maxFileBytes` (100 MB),
+ * `options.maxFiles` (1,000) and `options.maxScannedEntries` (20,000 entries walked). Each file
+ * is held in memory once while it is sent (`fetch` buffers request bodies), so the file limit
+ * is also the upload's memory bound. Pass `Infinity` to lift any of them.
+ */
+function uploadAssetsTool(connection, options) {
+    return createTool(definition$1, connection, options);
+}
+
+/**
+ * Every endpoint `downloadAssets` calls — all reads. The `download_assets` tool enforces
+ * exactly this list, and `download-assets.spec.ts` checks every request against it.
+ */
+const DOWNLOAD_ASSETS_ENDPOINTS = [
+    // A folder search is scoped to one site, so the site is resolved first.
+    ...CONTEXT_ENDPOINTS,
+    ...RESOLVE_ENDPOINTS,
+    'POST /api/content/_search',
+    'GET /api/v2/assets',
+    'GET /api/v2/assets/{identifier}'
+];
+const SEARCH_LIMIT = 500;
+/**
+ * Bounds on a single enumeration: how many search results one walk reads, whether or not the
+ * filters select them. `/application` on a large site can hold tens of thousands of assets,
+ * and every one selected is then downloaded one at a time with an open file handle — so an
+ * unbounded walk is both an unbounded tool call and unbounded load on the instance. A
+ * realistic theme is 100–500 files, so this is far above any genuine use while still being a
+ * ceiling. Hitting it is reported, never silent.
+ */
+const MAX_ENUMERATED_ASSETS = 5_000;
+const MAX_SEARCH_PAGES = Math.ceil(MAX_ENUMERATED_ASSETS / SEARCH_LIMIT);
+/**
+ * Download a dotCMS asset, or every asset under a folder, to a local directory. Relative
+ * paths are preserved, and one failed file is recorded in the manifest rather than aborting
+ * the batch.
+ */
+async function downloadAssets(options) {
+    const input = normalizeDotCMSPath(options.path);
+    const dest = await prepareWritableDir(options.dest, options.root);
+    const files = [];
+    const failures = [];
+    const skipped = [];
+    const warnings = [];
+    const kind = options.kind ?? 'auto';
+    const reading = kind === 'auto' ? (looksLikeAssetPath(input.path) ? 'asset' : 'folder') : kind;
+    const record = (result) => {
+        if (result.kind === 'written')
+            files.push(result.file);
+        else
+            skipped.push(result.skip);
+    };
+    const target = (rel) => ({
+        dest,
+        rel,
+        overwrite: options.overwrite,
+        root: options.root
+    });
+    // Each download is wrapped in the same try/catch so one failure records a failure and
+    // doesn't abort the batch — both the single-asset path and the folder loop go through it.
+    const download = async (rel, source, identifier) => {
+        try {
+            record(await saveAsset(options.dotcms, target(rel), source(), identifier));
+        }
+        catch (error) {
+            failures.push({ path: rel, error: errorMessage(error) });
+        }
+    };
+    // `path` read as ONE asset. Resolves false only when there is no asset there (404), which
+    // is what lets `auto` try the folder reading instead; any other failure is recorded.
+    const oneAsset = async () => {
+        const rel = basename(input.path);
+        try {
+            record(await saveAsset(options.dotcms, target(rel), { path: '/api/v2/assets', query: { path: assetQueryPath(input) } }, undefined, 
+            // Only a guess needs dotCMS's word before a collision policy applies;
+            // `kind: 'asset'` is certain.
+            kind === 'auto'));
+        }
+        catch (error) {
+            if (error instanceof HttpError && error.status === 404) {
+                return false;
+            }
+            failures.push({ path: rel, error: errorMessage(error) });
+        }
+        return true;
+    };
+    // `path` read as a FOLDER, searched on its one site. Resolves false when it holds nothing.
+    const folder = async () => {
+        const site = await siteOf(options.dotcms, options.path, input);
+        const { assets, truncated } = await enumerateAssets(options.dotcms, site.identifier, input.path, options.recursive, options.include);
+        if (truncated) {
+            // `include` and `recursive` filter what the search returned, so they cannot get a
+            // walk past the cap; only a narrower folder can.
+            warnings.push(`Enumeration stopped before reaching the end of this folder (it reads at most ` +
+                `${MAX_ENUMERATED_ASSETS} assets), so the download is INCOMPLETE. Narrow it ` +
+                `with a subfolder path and run again.`);
+        }
+        for (const asset of assets) {
+            const assetPath = asset.path ? normalizeDotCMSPath(asset.path).path : '';
+            const rel = relativeAssetPath(input.path, assetPath) || assetPath || '(unknown)';
+            const identifier = asset.identifier;
+            await download(rel, () => {
+                if (!identifier || !relativeAssetPath(input.path, assetPath)) {
+                    throw new Error('Asset is missing identifier or path');
+                }
+                return { path: `/api/v2/assets/${encodeURIComponent(identifier)}` };
+            }, identifier);
+        }
+        // After a cap, the folder is not empty: it simply was not read to the end.
+        return assets.length > 0 || truncated;
+    };
+    let found;
+    if (reading === 'asset') {
+        found = (await oneAsset()) || (kind === 'auto' && (await folder()));
+    }
+    else {
+        found = (await folder()) || (kind === 'auto' && (await oneAsset()));
+    }
+    if (!found) {
+        warnings.push(zeroMatchWarning(options.path, input));
+    }
+    return sortManifest({
+        path: input.path,
+        dest,
+        count: files.length,
+        bytes: sumBytes(files),
+        files,
+        failures,
+        skipped,
+        warnings
+    });
+}
+/**
+ * Save one asset to disk, streaming its bytes straight from the response into the file.
+ *
+ * Everything that can refuse the write is decided BEFORE the request: the path, the root, and
+ * the overwrite mode — so `skip` never transfers bytes it would throw away.
+ *
+ * `confirmRemote` is for a GUESSED asset (`kind: 'auto'`). A local collision decided on local
+ * state alone — `skip` reporting success, `error` reporting "already exists" — would never
+ * ask dotCMS whether an asset is there, and the folder reading would never be tried. So before
+ * either policy applies, the read is made and its body discarded unread; a 404 from it
+ * propagates for the caller's fallback, and a confirmed asset gets the policy as usual.
+ */
+async function saveAsset(dotcms, target, source, identifier, confirmRemote = false) {
+    const outputPath = safeJoin(target.dest, target.rel);
+    // `safeJoin` keeps the path inside `dest` as a string; this keeps the WRITE inside the root
+    // — a symlinked directory or file already inside `dest` would otherwise redirect it.
+    await assertWritableInsideRoot(target.root, outputPath);
+    if (target.overwrite !== 'overwrite' && (await exists(outputPath))) {
+        if (confirmRemote) {
+            await dotcms.request({ ...source, onBody: (body) => body.cancel() });
+        }
+        if (target.overwrite === 'skip') {
+            return { kind: 'skipped', skip: { path: target.rel, reason: 'exists' } };
+        }
+        throw new Error('Destination file already exists');
+    }
+    const bytes = (await dotcms.request({
+        ...source,
+        onBody: (body) => writeBodyToFile(outputPath, body)
+    }));
+    return { kind: 'written', file: { path: target.rel, bytes, identifier } };
+}
+/**
+ * Write a response body to `outputPath` and return how many bytes it held.
+ *
+ * The bytes go to a temporary file beside the target, renamed over it only once the body is
+ * complete. Written in place, a transfer that broke halfway would leave the target truncated —
+ * and, with `overwrite`, would have already destroyed the good copy it was replacing. The
+ * temporary file is opened exclusively (`wx`), so it is never an existing file or a planted
+ * symlink; the rename replaces the target's directory entry rather than writing through it.
+ */
+async function writeBodyToFile(outputPath, body) {
+    await mkdir(dirname(outputPath), { recursive: true });
+    const partial = `${outputPath}.${randomUUID()}.part`;
+    const reader = body.getReader();
+    let bytes = 0;
+    try {
+        const file = await open(partial, 'wx');
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                // Awaiting each write is the backpressure: the next chunk is not read until
+                // this one is on disk, so memory holds one chunk, not the file. A write may
+                // store fewer bytes than it was given (`bytesWritten`), so it loops until the
+                // whole chunk is written — counting the chunk would report a truncated file
+                // as complete.
+                for (let offset = 0; offset < value.byteLength;) {
+                    const { bytesWritten } = await file.write(value, offset, value.byteLength - offset);
+                    offset += bytesWritten;
+                }
+                bytes += value.byteLength;
+            }
+        }
+        finally {
+            await file.close();
+        }
+        // An empty body is an empty asset (a 0-byte VTL partial is real), so it is written too.
+        await rename(partial, outputPath);
+        return bytes;
+    }
+    catch (error) {
+        await reader.cancel().catch(() => undefined);
+        await rm(partial, { force: true });
+        throw error;
+    }
+}
+async function enumerateAssets(dotcms, siteId, folder, recursive, include) {
+    const matches = includeMatcher(include);
+    const assets = [];
+    // Every identifier the search returned, selected or not. Progress is measured on this, not
+    // on `assets`: a full page the filters reject entirely still moved the walk forward.
+    const enumerated = new Set();
+    for (let page_ = 0; page_ < MAX_SEARCH_PAGES; page_++) {
+        const offset = page_ * SEARCH_LIMIT;
+        const response = await dotcms.request({
+            method: 'POST',
+            path: '/api/content/_search',
+            body: {
+                // `+conhost` keeps the walk on one site. Without it, `/shared` matched every
+                // site's `/shared`, and same-named files overwrote or skipped each other locally.
+                query: `+baseType:4 +conhost:${siteId} +path:${folder}/*`,
+                sort: 'path asc',
+                limit: SEARCH_LIMIT,
+                offset
+            }
+        });
+        const page = extractContentlets(response);
+        const enumeratedBefore = enumerated.size;
+        for (const asset of page) {
+            if (!asset.identifier || !asset.path || enumerated.has(asset.identifier)) {
+                continue;
+            }
+            enumerated.add(asset.identifier);
+            const rel = relativeAssetPath(folder, normalizeDotCMSPath(asset.path).path);
+            if (!rel || (!recursive && rel.includes('/')) || !matches(rel)) {
+                continue;
+            }
+            assets.push(asset);
+        }
+        // A short page is the end of the results: the only way the walk is complete.
+        if (page.length < SEARCH_LIMIT) {
+            return { assets, truncated: false };
+        }
+        // Termination guard, NOT an optimisation. If the backend ignores or clamps `offset`,
+        // every page comes back full of the same identifiers: the short-page exit never
+        // fires, and the loop spins forever issuing identical POSTs — a tool call that never
+        // returns while the instance takes sustained load. A page that returns nothing new
+        // means we are not advancing, whatever the backend thinks it is doing — and whatever
+        // lies past it was never read.
+        if (enumerated.size === enumeratedBefore) {
+            return { assets, truncated: true };
+        }
+    }
+    // Out of pages on a full one: there are results left that this walk did not read.
+    return { assets, truncated: true };
+}
+/** The path to send to the `/api/v2/assets?path=` query — host-qualified when available. */
+function assetQueryPath(normalized) {
+    return normalized.siteQualified || normalized.path;
+}
+/**
+ * Message for a folder enumeration that matched 0 assets. The common cause is the `//host/path`
+ * ambiguity: a `//`-prefixed input has its FIRST segment consumed as the site, so `//application/themes`
+ * searches the path `/themes` on site `application` — which usually doesn't exist. Surface exactly
+ * that so the agent can correct it instead of treating an empty result as success.
+ */
+function zeroMatchWarning(rawInput, parsed) {
+    return (`No assets matched "${parsed.path}" — check the path. The result is empty, not a ` +
+        `success.${siteReadingNote(rawInput, parsed)}`);
+}
+/** The hostname a `//host/path` input names. */
+function siteHost(parsed) {
+    return (parsed.siteQualified ?? '').slice(2, (parsed.siteQualified ?? '').length - parsed.path.length);
+}
+/**
+ * How a `//`-prefixed input was read, for a message about it — empty for any other input.
+ * `//application/themes` reads `application` as the SITE, the common mistake: saying so, and
+ * what to write instead, is what lets the caller correct it rather than retry it.
+ */
+function siteReadingNote(rawInput, parsed) {
+    const trimmed = rawInput.trim();
+    if (!trimmed.startsWith('//')) {
+        return '';
+    }
+    // The plain-path form is the input with one leading slash removed — i.e. the FULL path
+    // including the segment that "//" consumed as the site (e.g. "//application/themes" → "/application/themes").
+    const asPlainPath = trimmed.slice(1).replace(/\/+$/, '');
+    return (` Note: "${rawInput}" was read as site="${siteHost(parsed)}", path="${parsed.path}" ` +
+        `(a leading "//" treats the first segment as the dotCMS site). ` +
+        `If you meant a path on the default site, use "${asPlainPath}"; ` +
+        `if you meant a host-qualified path, keep "//<site>/<path>".`);
+}
+/**
+ * The one site a folder is searched on: the `//host` the input names, or the default site.
+ * An unknown host is the caller's input being wrong (VALIDATION), and says how it was read.
+ */
+async function siteOf(dotcms, rawInput, parsed) {
+    if (!parsed.siteQualified) {
+        return resolveDefaultSite(dotcms);
+    }
+    try {
+        return await resolveSite(dotcms, siteHost(parsed));
+    }
+    catch (error) {
+        if (error instanceof ValidationError) {
+            throw withMessage(error, `${error.message}${siteReadingNote(rawInput, parsed)}`);
+        }
+        throw error;
+    }
+}
+function relativeAssetPath(folder, assetPath) {
+    const prefix = `${folder.replace(/\/+$/, '')}/`;
+    return assetPath.startsWith(prefix) ? assetPath.slice(prefix.length) : '';
+}
+function looksLikeAssetPath(path) {
+    return extname(path) !== '';
+}
+async function prepareWritableDir(dest, root) {
+    if (!isAbsolute(dest)) {
+        throw new ValidationError(`Destination must be an absolute path: ${dest}`);
+    }
+    const resolved = resolve(dest);
+    // Checked BEFORE mkdir, so a refused `dest` creates nothing — not even its parents.
+    await assertInsideRoot(root, 'dest', resolved);
+    await mkdir(resolved, { recursive: true });
+    await access(resolved, constants.W_OK);
+    return resolved;
+}
+function safeJoin(root, rel) {
+    if (posix.isAbsolute(rel) || rel.split('/').includes('..')) {
+        throw new Error(`Unsafe relative path: ${rel}`);
+    }
+    const output = resolve(root, rel);
+    const back = relative(root, output);
+    if (back === '..' || back.startsWith(`..${sep}`) || isAbsolute(back)) {
+        throw new Error(`Resolved path escapes destination: ${rel}`);
+    }
+    return output;
+}
+function extractContentlets(response) {
+    const root = response;
+    const candidates = [
+        root.entity?.jsonObjectView?.contentlets,
+        root.entity?.contentlets,
+        root.entity?.results,
+        root.contentlets
+    ];
+    for (const candidate of candidates) {
+        if (Array.isArray(candidate)) {
+            return candidate;
+        }
+    }
+    return [];
+}
+async function exists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
+const definition = defineTool({
+    name: 'download_assets',
+    title: 'Download dotCMS Assets',
+    inputSchema: z.object({
+        path: z
+            .string()
+            .min(1)
+            .describe('dotCMS folder or asset path to download, e.g. /application/themes/travel or //demo.dotcms.com/application/themes/travel/css/styles.scss. A folder is searched on the one site the path names; a path with no //host means the default site.'),
+        kind: z
+            .enum(['auto', 'asset', 'folder'])
+            .default('auto')
+            .describe('Whether `path` is one asset or a folder. "auto" (default) guesses from the name — an extension means an asset — and tries the other reading when the first finds nothing. Pass "folder" for a folder whose name has a dot (e.g. /themes/v1.2), "asset" for a file with no extension (e.g. /robots).'),
+        dest: z
+            .string()
+            .min(1)
+            .describe('Absolute local directory the server writes files into. Must be inside the directory the server allows; a path outside it fails and names that directory.'),
+        recursive: z.boolean().default(true).describe('Include files in nested folders'),
+        overwrite: z
+            .enum(['skip', 'overwrite', 'error'])
+            .default('skip')
+            .describe('Behavior when a destination file already exists'),
+        include: z
+            .string()
+            .optional()
+            .describe('Optional comma-separated glob filter, e.g. *.vtl,*.scss')
+    }),
+    description: `Download one or more dotCMS file assets (themes, VTL, CSS, JS, images, fonts, …) to a local directory.
+
+ALWAYS use this tool to pull files out of dotCMS — do NOT hand-roll downloads with the
+\`execute\` tool, a direct API call, or a custom script. This is the supported path and it is
+strictly better for two reasons:
+  1. File bytes are written to disk by the server — they NEVER pass through your context. Use
+     this whenever you'd otherwise read file content into a tool call; it keeps that content
+     out of the conversation entirely.
+  2. Auth is already configured on the server. You do NOT need a dotCMS token, a \`.env\` file, or
+     any local credentials — never go looking for them.
+
+Use it whenever you need dotCMS files on the local disk — whether the user explicitly asks to
+"download/pull/export," OR you decided you need the existing files to inspect or edit them as
+part of a larger task. Example: the user says "update the theme's CSS"; you download the current
+theme files, edit them locally, then upload them back. Getting files out of dotCMS is always a
+step you take with this tool — not something you wait to be told to do, and not something you improvise.
+
+Provide the dotCMS folder or asset path and an absolute destination directory (\`dest\`). Optional
+\`include\` globs limit which files are fetched. The tool preserves relative paths and returns only
+a JSON manifest — never the file bytes.`,
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+    },
+    endpoints: DOWNLOAD_ASSETS_ENDPOINTS,
+    async handler(args, ctx) {
+        return downloadAssets({
+            dotcms: ctx.runtime(),
+            root: ctx.options.root,
+            path: args.path,
+            kind: args.kind,
+            dest: args.dest,
+            recursive: args.recursive,
+            overwrite: args.overwrite,
+            include: args.include
+        });
+    }
+});
+/**
+ * The `download_assets` tool: streams dotCMS file assets to a local directory — the bytes
+ * never pass through the model. Needs Node or Bun. Resolves to a {@link DownloadAssetsManifest}.
+ * `options.root` bounds which local directories the model may write into.
+ */
+function downloadAssetsTool(connection, options) {
+    return createTool(definition, connection, options);
+}
+
+export { createPage, dotcmsConnection, downloadAssets, downloadAssetsTool, executeTool, isToolFailure, pageCreateTool, pagePlaceContentTool, pageVerifyTool, placeContent, searchTool, uploadAssets, uploadAssetsTool, verifyPage };