@prenta/mcp-server 0.23.0

package/dist/tools.js

@@ -0,0 +1,1920 @@
+/**
+ * MCP tool definitions for Prenta CMS.
+ *
+ * Each tool is a thin wrapper around an PrentaClient call. We expose a small
+ * but powerful set focused on the workflows AI agents actually need:
+ *   - discover collections and fields
+ *   - list / get / create / update / delete documents
+ *   - read / update globals (site settings)
+ *   - generate pages and blocks via the AI page builder
+ *   - create complete pages from a prompt in one shot
+ *
+ * We deliberately do not expose admin-only endpoints (user management,
+ * api-key CRUD, audit log) — the agent already has limited scope via its key.
+ */
+import { z } from 'zod';
+import { PrentaClientError } from './client.js';
+import { NAVIGATION_COLLECTION, addNavItem, buildDocPath, coerceNavItems, genNavItemId, removeNavItem, reorderNavLevel, validateNavTree, } from './navigation.js';
+// Convert a Zod object schema to a JSON Schema fragment understood by MCP.
+// The MCP spec accepts standard JSON Schema, but we only need a small subset.
+// Exported so unit tests can exercise nullable / optional / required logic
+// directly without having to fabricate a fake `buildTools()` registration.
+export function zodToJsonSchema(schema) {
+    const shape = schema.shape;
+    const properties = {};
+    const required = [];
+    for (const [key, value] of Object.entries(shape)) {
+        properties[key] = zodTypeToJsonSchema(value);
+        if (!value.isOptional())
+            required.push(key);
+    }
+    const result = { type: 'object', properties };
+    if (required.length > 0)
+        result.required = required;
+    return result;
+}
+function zodTypeToJsonSchema(schema) {
+    // Unwrap optionals / defaults so we look at the inner type. We capture
+    // nullable separately because it affects the emitted JSON Schema `type`
+    // (the field must accept `null` as well as the inner type) but does NOT
+    // affect requiredness — `.nullable()` alone keeps the field required.
+    let inner = schema;
+    let nullable = false;
+    while (inner?._def?.typeName === 'ZodOptional' ||
+        inner?._def?.typeName === 'ZodDefault' ||
+        inner?._def?.typeName === 'ZodNullable') {
+        if (inner._def.typeName === 'ZodNullable')
+            nullable = true;
+        inner = inner._def.innerType;
+    }
+    const typeName = inner?._def?.typeName;
+    const description = schema?._def?.description ?? inner?._def?.description;
+    const base = {};
+    if (description)
+        base.description = description;
+    // Helper: if a field is nullable, emit `type: [..., 'null']` so MCP-aware
+    // clients (and JSON-Schema validators) accept an explicit null. We mirror
+    // ZodNullable's parse-time semantics into the published schema; otherwise
+    // an agent passing `null` to e.g. `move_media_to_folder({ folderId: null })`
+    // would be rejected client-side before the tool handler ever sees it.
+    function withNull(t) {
+        return nullable ? [t, 'null'] : t;
+    }
+    switch (typeName) {
+        case 'ZodString':
+            return { ...base, type: withNull('string') };
+        case 'ZodNumber':
+            return { ...base, type: withNull('number') };
+        case 'ZodBoolean':
+            return { ...base, type: withNull('boolean') };
+        case 'ZodArray':
+            return {
+                ...base,
+                type: withNull('array'),
+                items: zodTypeToJsonSchema(inner._def.type),
+            };
+        case 'ZodObject': {
+            // Spread the inner object's properties/required, then re-apply
+            // `type` so a nullable ZodObject still publishes `["object", "null"]`
+            // (parity with every other branch via `withNull`).
+            const obj = zodToJsonSchema(inner);
+            return { ...base, ...obj, type: withNull('object') };
+        }
+        case 'ZodEnum':
+            return { ...base, type: withNull('string'), enum: inner._def.values };
+        case 'ZodLiteral': {
+            // JSON Schema convention: emit `enum: [value]` paired with the
+            // JS-level type. We avoid `const` because draft-07 was the first
+            // to support it and several MCP clients still target draft-06.
+            const value = inner._def.value;
+            const t = typeof value === 'boolean' ? 'boolean' : typeof value === 'number' ? 'number' : 'string';
+            return { ...base, type: withNull(t), enum: [value] };
+        }
+        case 'ZodUnion': {
+            // ZodUnion is most commonly used as a "literal-of-N" enum in this
+            // codebase (e.g. `statusCode: z.union([z.literal(301), …])`). When
+            // every option is a literal of the same JS type we collapse to
+            // `{ type, enum: [...] }` which every JSON-Schema validator
+            // understands; otherwise we fall back to `oneOf` with the inner
+            // sub-schemas so non-literal unions still publish a usable shape.
+            const options = inner._def.options ?? [];
+            const literals = options.filter((o) => o?._def?.typeName === 'ZodLiteral');
+            if (literals.length === options.length && literals.length > 0) {
+                const values = literals.map((l) => l._def.value);
+                const types = new Set(values.map((v) => typeof v === 'boolean' ? 'boolean' : typeof v === 'number' ? 'number' : 'string'));
+                if (types.size === 1) {
+                    const [t] = [...types];
+                    return { ...base, type: withNull(t), enum: values };
+                }
+                // Mixed-type literal union — keep enum but drop type since JSON
+                // Schema `type` is a single string (or array of types). Most
+                // validators allow `enum` without `type`.
+                return { ...base, enum: values };
+            }
+            return { ...base, oneOf: options.map((o) => zodTypeToJsonSchema(o)) };
+        }
+        case 'ZodRecord':
+            return { ...base, type: withNull('object'), additionalProperties: true };
+        case 'ZodAny':
+        case 'ZodUnknown':
+            return { ...base };
+        default:
+            return { ...base, type: withNull('string') };
+    }
+}
+export function buildTools(client) {
+    const tools = [];
+    function tool(name, description, schema, handler) {
+        tools.push({
+            name,
+            description,
+            inputSchema: zodToJsonSchema(schema),
+            handler: async (args) => {
+                const parsed = schema.parse(args ?? {});
+                return await handler(parsed);
+            },
+        });
+    }
+    tool('list_documents', 'List documents in a collection. Returns paginated results.', z.object({
+        collection: z.string().describe('Collection slug (e.g. "pages", "posts")'),
+        page: z.number().int().min(1).optional().describe('1-indexed page number'),
+        pageSize: z.number().int().min(1).max(100).optional().describe('Items per page (max 100)'),
+        status: z.string().optional().describe('Filter by status (DRAFT, PUBLISHED, SCHEDULED)'),
+        search: z.string().optional().describe('Free-text search against title and body'),
+    }), (args) => client.listDocuments(args.collection, args));
+    tool('get_document', 'Fetch a single document by ID.', z.object({
+        collection: z.string(),
+        id: z.string().describe('Document ID'),
+    }), (args) => client.getDocument(args.collection, args.id));
+    tool('create_document', 'Create a new document in a collection. Defaults to DRAFT status.', z.object({
+        collection: z.string(),
+        title: z.string().optional(),
+        slug: z.string().optional(),
+        status: z.enum(['DRAFT', 'PUBLISHED', 'SCHEDULED']).optional(),
+        data: z
+            .record(z.any())
+            .optional()
+            .describe('Arbitrary field data — depends on the collection schema'),
+        layout: z.any().optional().describe('Page-builder layout tree (for page collections)'),
+        pageSettings: z.record(z.any()).optional().describe('SEO and meta settings'),
+    }), (args) => {
+        const { collection, data, ...rest } = args;
+        return client.createDocument(collection, { ...(data ?? {}), ...rest });
+    });
+    tool('update_document', 'Update fields on an existing document. Only the provided top-level fields are changed (shallow merge). Nested objects of type `media` (e.g. `featuredImage`) are deep-merged so a partial `{ alt }` patch keeps `url`/`id`. Still prefer resending the full media object when you have it. A media object with neither `id` nor `url` is rejected as a likely partial-update accident.', z.object({
+        collection: z.string().describe('Collection slug (required).'),
+        id: z.string(),
+        title: z.string().optional(),
+        slug: z.string().optional(),
+        status: z.enum(['DRAFT', 'PUBLISHED', 'SCHEDULED']).optional(),
+        data: z.record(z.any()).optional(),
+        layout: z.any().optional(),
+        pageSettings: z.record(z.any()).optional(),
+    }), (args) => {
+        const { collection, id, data, ...rest } = args;
+        return client.updateDocument(collection, id, { ...(data ?? {}), ...rest });
+    });
+    tool('delete_document', 'Soft-delete a document. Destructive — requires `confirm: true` (the wrapper refuses otherwise).', z.object({
+        collection: z.string(),
+        id: z.string(),
+        confirm: z
+            .literal(true)
+            .describe('Must be `true` to acknowledge this destructive action. Confirm with the user first.'),
+    }), (args) => {
+        if (args.confirm !== true) {
+            throw new Error('delete_document requires confirm: true to acknowledge a destructive action.');
+        }
+        return client.deleteDocument(args.collection, args.id);
+    });
+    tool('get_global', 'Fetch a global (e.g. site settings).', z.object({ slug: z.string().describe('Global slug (e.g. "site-settings")') }), (args) => client.getGlobal(args.slug));
+    tool('update_global', 'Update a global.', z.object({ slug: z.string(), data: z.record(z.any()) }), (args) => client.updateGlobal(args.slug, args.data));
+    tool('list_media', 'List media assets in the CMS library.', z.object({
+        page: z.number().int().min(1).optional(),
+        pageSize: z.number().int().min(1).max(100).optional(),
+    }), (args) => client.listMedia(args));
+    // ── Media write tools (Phase 7 MCP-parity, PR A) ──────────────────────
+    //
+    // Five tools that mirror the existing /media/* admin endpoints. Together
+    // with `list_media` they give an agent a complete media-library surface:
+    // upload bytes, edit alt/title/focal point, recompress, move into a
+    // folder, delete.
+    //
+    // upload_media accepts the file as base64-encoded bytes. We keep the
+    // base64 boundary inside the tool wrapper so the underlying client
+    // method stays binary (Uint8Array) — this is the standard MCP pattern
+    // for binary payloads since JSON-RPC has no native binary type.
+    tool('upload_media', 'Upload a file (image, document, video, etc.) to the CMS media library. **Required first step for every image** — do not use /public/ or static paths in content. Images are auto-optimized on upload: resize when >4096px, compress to high-quality WebP (q82 photos, q86 transparent PNGs), keep original bytes if WebP would be larger. Pass skipOptimize=true only for brand logos/favicons. After upload, call `generate_media_alt` then `update_media` to set alt text. The server enforces a 50 MB hard cap and validates magic bytes. Byte-identical re-uploads (same final stored bytes, e.g. seed re-runs) return the existing record with `deduplicated: true` and `duplicateOf` instead of creating another blob — pass `forceUpload: true` to bypass.', z.object({
+        filename: z
+            .string()
+            .min(1)
+            .describe('Filename including extension (e.g. "hero.jpg"). Drives the stored extension.'),
+        mimeType: z
+            .string()
+            .min(1)
+            .describe('MIME type of the file (e.g. "image/jpeg", "image/png", "image/svg+xml", "application/pdf"). Must match the actual bytes — magic-byte mismatch returns HTTP 415.'),
+        dataBase64: z
+            .string()
+            .min(1)
+            .describe('Base64-encoded file bytes. Standard base64 (with or without padding). Decoded payload must be ≤ 50 MB.'),
+        skipOptimize: z
+            .boolean()
+            .optional()
+            .describe('When true, store the original bytes verbatim. Default false.'),
+        forceUpload: z
+            .boolean()
+            .optional()
+            .describe('When true, always create a new media row even if identical bytes already exist. Default false (dedupe).'),
+    }), (args) => {
+        // Strip whitespace + optional data-URL prefix that some agents emit.
+        // Use a lazy `[^,]*?` match so the regex tolerates parameterised
+        // media types (e.g. `data:text/plain;charset=utf-8;base64,...`).
+        // A greedy `[^;]+;base64,` pattern would fail on the second `;` and
+        // silently leave the prefix in place, causing `Buffer.from(...,
+        // 'base64')` to skip non-base64 chars and decode garbage instead.
+        const cleaned = args.dataBase64.replace(/\s+/g, '').replace(/^data:[^,]*?;base64,/i, '');
+        const bytes = Buffer.from(cleaned, 'base64');
+        if (bytes.length === 0) {
+            throw new Error('dataBase64 decoded to zero bytes — check the encoding.');
+        }
+        return client.uploadMedia({
+            filename: args.filename,
+            mimeType: args.mimeType,
+            bytes,
+            ...(args.skipOptimize !== undefined ? { skipOptimize: args.skipOptimize } : {}),
+            ...(args.forceUpload !== undefined ? { forceUpload: args.forceUpload } : {}),
+        });
+    });
+    tool('update_media', 'Update metadata on an existing media item. Only the supplied fields are written. Use this to set alt text (accessibility), title, description, caption, focus keyword, focal points (smart-crop hints; both in 0..1 normalised coordinates), or `isDecorative` for ornamental images that correctly use empty alt. Media SEO scoring weights these fields as alt 30, title 20, description 20, caption 10, descriptive filename 10, focus keyword 10 — so alt + title + a descriptive filename alone caps an asset at 60 ("needs-work"), and adding a description is what lifts it to a passing 80 ("good"). Decorative assets (`isDecorative: true`) earn the alt (+ description) weight with empty alt and must not be "fixed" by inventing alt text.', z.object({
+        id: z.string().describe('Media item ID.'),
+        alt: z.string().optional().describe('Alt text for accessibility. Stored as `altText`.'),
+        title: z.string().optional(),
+        filename: z.string().optional().describe('Rename the file without re-uploading.'),
+        description: z
+            .string()
+            .optional()
+            .describe('Longer-form context for search and reuse. Worth 20 points of the media SEO score — the usual difference between a "needs-work" and a "good" grade.'),
+        caption: z
+            .string()
+            .optional()
+            .describe('Display caption. Also used as the transcript/caption signal for video assets.'),
+        focusKeyword: z.string().optional().describe('Primary keyword this asset targets.'),
+        isDecorative: z
+            .boolean()
+            .optional()
+            .describe('When true, marks the image as WCAG-decorative: forces empty alt and awards media SEO alt credit. When false, clears the flag. A non-empty `alt` also clears the flag.'),
+        focalX: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe('Horizontal focal point, 0 (left) to 1 (right).'),
+        focalY: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe('Vertical focal point, 0 (top) to 1 (bottom).'),
+    }), (args) => {
+        const { id, ...body } = args;
+        return client.updateMedia(id, body);
+    });
+    tool('generate_media_alt', 'Generate WCAG-aligned alt text for a media-library image using a vision model (when configured). Requires `ai.features.mediaAltText` enabled in Settings → AI. Returns `{ alt, title, alternatives, isDecorative, confidence, usedVision }` as a **suggestion** — review it, then persist with `update_media({ id, alt })` or, when `isDecorative` is true, `update_media({ id, alt: "", isDecorative: true })`. Prefer `mediaId` over raw URLs. Workflow: `upload_media` → `generate_media_alt` → `update_media`.', z.object({
+        mediaId: z
+            .string()
+            .optional()
+            .describe('Media item ID from upload_media or list_media (preferred).'),
+        imageUrl: z
+            .string()
+            .optional()
+            .describe('Fallback: a storage-allowlisted image URL when mediaId is unknown.'),
+        pageTitle: z
+            .string()
+            .optional()
+            .describe('Page or post title where the image will appear — improves context.'),
+        surroundingText: z
+            .string()
+            .optional()
+            .describe('Nearby heading or caption text for context (max ~300 chars used).'),
+        purpose: z
+            .enum(['decorative', 'informative', 'functional'])
+            .optional()
+            .describe('Image role hint. Use decorative for purely ornamental images (returns empty alt).'),
+    }), (args) => {
+        if (!args.mediaId && !args.imageUrl) {
+            throw new Error('generate_media_alt requires mediaId or imageUrl.');
+        }
+        return client.generateMediaAlt(args);
+    });
+    tool('delete_media', 'Delete a media item AND its underlying blob storage object (best-effort). Destructive — requires `confirm: true` (the wrapper refuses otherwise). Returns `{ data: { success: true } }`.', z.object({
+        id: z.string().describe('Media item ID.'),
+        confirm: z
+            .literal(true)
+            .describe('Must be `true` to acknowledge this destructive action. Confirm with the user first.'),
+    }), (args) => {
+        if (args.confirm !== true) {
+            throw new Error('delete_media requires confirm: true to acknowledge a destructive action.');
+        }
+        return client.deleteMedia(args.id);
+    });
+    const mediaMetadataFields = {
+        alt: z.string().optional().describe('Alt text for accessibility. Stored as `altText`.'),
+        title: z.string().optional(),
+        filename: z.string().optional().describe('Rename the file without re-uploading.'),
+        description: z.string().optional().describe('Longer-form context for search and reuse.'),
+        caption: z.string().optional().describe('Display caption / video transcript signal.'),
+        focusKeyword: z.string().optional().describe('Primary keyword this asset targets.'),
+        isDecorative: z
+            .boolean()
+            .optional()
+            .describe('When true, marks the image as WCAG-decorative (forces empty alt).'),
+        focalX: z.number().min(0).max(1).optional(),
+        focalY: z.number().min(0).max(1).optional(),
+    };
+    tool('bulk_update_media', 'Update metadata on many media items in one round trip (max 50). Each item carries its own patch — unlike form bulk tools, there is no shared patch. Returns per-id `{ ok, data|error }` so a library backfill can land the successes even when a few ids fail. Prefer this over looping `update_media` for alt/title/description passes.', z.object({
+        items: z
+            .array(z.object({
+            id: z.string().describe('Media item ID.'),
+            ...mediaMetadataFields,
+        }))
+            .min(1)
+            .max(50)
+            .describe('Per-item metadata patches (1–50).'),
+    }), (args) => client.bulkUpdateMedia(args.items));
+    tool('bulk_delete_media', 'Delete many media items AND their blob storage objects (best-effort, max 50). Destructive — requires `confirm: true`. Returns per-id success/failure so missing ids do not abort the rest of the batch.', z.object({
+        ids: z.array(z.string()).min(1).max(50).describe('Media item IDs to delete (1–50).'),
+        confirm: z
+            .literal(true)
+            .describe('Must be `true` to acknowledge this destructive action. Confirm with the user first.'),
+    }), (args) => {
+        if (args.confirm !== true) {
+            throw new Error('bulk_delete_media requires confirm: true to acknowledge a destructive action.');
+        }
+        return client.bulkDeleteMedia(args.ids, true);
+    });
+    tool('optimize_media', 'Recompress an existing image to WebP. Returns the updated media row plus an `optimization` summary (`{ originalSize, optimizedSize, savings, ... }`). Already-WebP files and non-images short-circuit with `alreadyOptimized: true`. Useful for batch "shrink everything in this folder" workflows.', z.object({
+        id: z.string().describe('Media item ID.'),
+    }), (args) => client.optimizeMedia(args.id));
+    tool('move_media_to_folder', 'Move a media item into a folder, or out of every folder by passing folderId=null. The server validates that the target folder is in the media scope.', z.object({
+        id: z.string().describe('Media item ID.'),
+        folderId: z
+            .string()
+            .nullable()
+            .describe('Destination folder ID, or null to remove the item from any folder.'),
+    }), (args) => client.moveMediaToFolder(args.id, args.folderId));
+    // ── Folder tools (Phase 7 MCP-parity, PR A) ───────────────────────────
+    //
+    // Folders are scoped per-surface: "media" for the media library,
+    // "documents" / "collections" for document folders. A folder can only
+    // contain children that match its scope — the server enforces this.
+    tool('list_folders', 'List folders in a given scope as a nested tree. Each node is `{ id, name, scope, parentId, position, children: [...] }`. Scopes today: "media" for the media library, "documents" or "collections" for document folders. The scope arg is REQUIRED — there is no all-scopes endpoint.', z.object({
+        scope: z
+            .string()
+            .min(1)
+            .describe('Folder scope to list. Typical values: "media", "documents", "collections".'),
+    }), (args) => client.listFolders(args.scope));
+    tool('create_folder', 'Create a folder. If parentId is supplied it MUST already exist AND live in the same scope — the server refuses cross-scope reparenting.', z.object({
+        name: z.string().min(1).describe('Folder display name.'),
+        scope: z
+            .string()
+            .min(1)
+            .describe('Folder scope. Typical values: "media", "documents", "collections".'),
+        parentId: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Parent folder ID, or null/undefined for a root-level folder.'),
+    }), (args) => client.createFolder({
+        name: args.name,
+        scope: args.scope,
+        ...(args.parentId !== undefined ? { parentId: args.parentId } : {}),
+    }));
+    tool('update_folder', 'Rename, reparent, or reorder a folder. Pass any subset of { name, parentId, position }. Use parentId=null to promote to root. The server prevents self-parenting and cross-scope reparenting.', z.object({
+        id: z.string().describe('Folder ID.'),
+        name: z.string().optional(),
+        parentId: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('New parent folder ID, or null to promote to root. Omit to leave unchanged.'),
+        position: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe('Sort position within the parent. Omit to leave unchanged.'),
+    }), (args) => {
+        const { id, ...body } = args;
+        return client.updateFolder(id, body);
+    });
+    tool('delete_folder', 'Delete a folder. Refuses with HTTP 409 if the folder still contains documents, media, or sub-folders. Move or delete the contents first (use move_document_to_folder / move_media_to_folder, then delete_folder).', z.object({
+        id: z.string().describe('Folder ID.'),
+    }), (args) => client.deleteFolder(args.id));
+    tool('move_document_to_folder', 'Move a document into a folder, or out of every folder by passing folderId=null. The server validates that the target folder is in the documents / collections scope.', z.object({
+        id: z.string().describe('Document ID.'),
+        folderId: z
+            .string()
+            .nullable()
+            .describe('Destination folder ID, or null to remove the document from any folder.'),
+    }), (args) => client.moveDocumentToFolder(args.id, args.folderId));
+    // ── Version history tools (Phase 7 MCP-parity, PR B) ──────────────────
+    //
+    // Versions are immutable per-write snapshots living in `prenta_versions`.
+    // Listing is paged (default 20, max 50). Restore goes through the normal
+    // updateDocument path, which means it (a) runs hooks, (b) creates a NEW
+    // version row (history is never rewritten), (c) emits an audit log.
+    //
+    // Naming convention note: collection-scoped tools use `id` (matching
+    // `get_document`, `update_document`, `delete_document`, `audit_document`,
+    // `move_document_to_folder`). The collection slug disambiguates which
+    // `id` we mean, so `documentId` would be redundant and split the
+    // agent's mental model across two synonyms.
+    tool('list_versions', 'List the immutable change history of a document, newest first. Each version carries the full `data` payload at the time of write, plus the user who made the change. Paged: default 20 / max 50.', z.object({
+        collection: z.string().describe('Collection slug (e.g. "posts").'),
+        id: z.string().describe('Document ID.'),
+        page: z.number().int().min(1).optional(),
+        pageSize: z.number().int().min(1).max(50).optional(),
+    }), (args) => {
+        const { collection, id, ...query } = args;
+        return client.listVersions(collection, id, query);
+    });
+    tool('restore_version', 'Roll a document back to a prior version. The restore goes through the normal updateDocument path, which means hooks run, a NEW version row is created (history is never rewritten), and a `version_restored` event is appended to prenta_audit_logs. Pair with list_versions to discover restorable IDs.', z.object({
+        collection: z.string().describe('Collection slug.'),
+        id: z.string().describe('Document ID.'),
+        versionId: z.string().describe('Version row ID to roll back to.'),
+    }), (args) => client.restoreVersion(args.collection, args.id, args.versionId));
+    // ── Scheduling tools (Phase 7 MCP-parity, PR B) ───────────────────────
+    //
+    // Scheduling is intentionally a two-step model: this writes the future
+    // timestamps on the document, and the `/cron/publish` cron performs the
+    // actual status flip. That decoupling means a missed cron tick just
+    // delays the publish — it can never double-publish or skip a doc.
+    //
+    // Null semantics asymmetry (server-side, by design):
+    //   - scheduledUnpublishAt: null → clears any existing unpublish field.
+    //   - scheduledAt:          null → silently no-op. The way to clear a
+    //                                  pending publish is `unschedule_publish`.
+    // We only mark `scheduledUnpublishAt` as nullable in the schema so the
+    // published JSON Schema accurately reflects what the server accepts;
+    // promising `scheduledAt: null` would be misleading.
+    tool('schedule_publish', 'Schedule a document to publish and/or unpublish at a future timestamp. Pass at least one of `scheduledAt` (when to publish — forces status → SCHEDULED) or `scheduledUnpublishAt` (when to unpublish; pass null to clear an existing unpublish without cancelling the publish schedule). Both must be ISO 8601 strings AND in the future; `scheduledUnpublishAt` must be after `scheduledAt` when both are provided.', z.object({
+        collection: z.string().describe('Collection slug.'),
+        id: z.string().describe('Document ID.'),
+        scheduledAt: z
+            .string()
+            .optional()
+            .describe('ISO 8601 timestamp at which to publish. Must be in the future.'),
+        scheduledUnpublishAt: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('ISO 8601 timestamp at which to unpublish. Must be in the future AND after scheduledAt when both are set. Pass null to clear an existing unpublish timestamp without cancelling the publish schedule.'),
+    }), (args) => {
+        // The server returns HTTP 400 when neither field is present. Fail
+        // fast at the wrapper so an empty call doesn't burn a round-trip.
+        // We treat "field present with null" as a deliberate clear, so it
+        // counts as "provided" here (matches server semantics for unpublishAt).
+        if (args.scheduledAt === undefined && args.scheduledUnpublishAt === undefined) {
+            throw new Error('At least one of scheduledAt or scheduledUnpublishAt must be provided.');
+        }
+        const { collection, id, ...body } = args;
+        return client.schedulePublish(collection, id, body);
+    });
+    tool('unschedule_publish', 'Cancel any pending publish + unpublish schedule for the document. If the document was in SCHEDULED (not yet published) it drops back to DRAFT. Already-published documents stay live.', z.object({
+        collection: z.string().describe('Collection slug.'),
+        id: z.string().describe('Document ID.'),
+    }), (args) => client.unschedulePublish(args.collection, args.id));
+    // ── Editorial workflow tools (Phase 7 MCP-parity, PR B) ───────────────
+    //
+    // The workflow state machine lives in `packages/cms-core/src/workflow`:
+    //   DRAFT → IN_REVIEW → APPROVED → PUBLISHED → ARCHIVED
+    // Each transition is gated by both (a) the from→to edge being legal and
+    // (b) the caller's role allowing it. `get_workflow_state` returns the
+    // role-filtered list of legal next stages for the calling agent.
+    tool('get_workflow_state', 'Read the editorial workflow state of a document. Returns: { stage, transitions, reviewerId, reviewNote }. `transitions` is the list of next stages the *current API key holder* is allowed to move to — already filtered by role, so the agent can present them to a human as-is. Workflow stages: DRAFT → IN_REVIEW → APPROVED → PUBLISHED → ARCHIVED.', z.object({
+        collection: z.string().describe('Collection slug.'),
+        id: z.string().describe('Document ID.'),
+    }), (args) => client.getWorkflowState(args.collection, args.id));
+    tool('transition_workflow', "Move a document to a new workflow stage. The server validates that (a) the transition is allowed from the current stage and (b) the caller's role permits it; either failure returns HTTP 400 with the reason. Pair with get_workflow_state to discover which transitions are legal before calling.", z.object({
+        collection: z.string().describe('Collection slug.'),
+        id: z.string().describe('Document ID.'),
+        stage: z
+            .enum(['DRAFT', 'IN_REVIEW', 'APPROVED', 'PUBLISHED', 'ARCHIVED'])
+            .describe('Target workflow stage.'),
+        note: z.string().optional().describe('Optional reviewer note attached to the transition.'),
+    }), (args) => {
+        const { collection, id, ...body } = args;
+        return client.transitionWorkflow(collection, id, body);
+    });
+    // ── Comment tools (Phase 7 MCP-parity, PR D) ──────────────────────────
+    //
+    // Comments are how editors leave structured feedback on drafts. The
+    // server records each comment + reply with optional `anchor` (a text
+    // range that the comment pins to in the document), persists them in
+    // `prenta_document_comments`, fires an audit event, and dispatches a
+    // best-effort notification to mentioned users.
+    //
+    // Naming convention note: comment tools take `id` (the document ID),
+    // matching the PR B convention. No collection slug is needed because
+    // comments are attached to documents by ID alone — the underlying
+    // route is `/documents/:documentId/comments`, not collection-scoped.
+    tool('list_comments', 'List the comment thread attached to a document. By default returns only unresolved, non-deleted comments. Set `includeResolved: true` to widen the result to resolved threads. `includeDeleted` is admin-only and surfaces soft-deleted moderation history; non-admin API keys get HTTP 403.', z.object({
+        id: z.string().describe('Document ID.'),
+        includeResolved: z.boolean().optional().describe('Include resolved threads. Default false.'),
+        includeDeleted: z
+            .boolean()
+            .optional()
+            .describe('Include soft-deleted comments (admin-only — non-admin keys receive HTTP 403). Default false.'),
+        pageSize: z.number().int().min(1).max(200).optional(),
+    }), (args) => {
+        const { id, ...query } = args;
+        return client.listComments(id, query);
+    });
+    tool('create_comment', "Create a comment on a document. Pass `anchor` to pin the comment to a specific text range (used by the admin's rich-text selection UI). Pass `parentId` to reply to an existing comment. Posting a comment emits a `comment_created` audit event and triggers best-effort notification dispatch for any mentioned users.", z.object({
+        id: z.string().describe('Document ID.'),
+        body: z
+            .string()
+            .min(1)
+            .describe('Comment text. Required; empty strings are rejected by the server.'),
+        anchor: z
+            .object({
+            from: z
+                .string()
+                .max(4096)
+                .describe('Anchor start marker. Opaque to the server (≤ 4096 chars).'),
+            to: z
+                .string()
+                .max(4096)
+                .describe('Anchor end marker. Opaque to the server (≤ 4096 chars).'),
+        })
+            .nullable()
+            .optional()
+            .describe('Optional anchor pinning the comment to a text range. Pass null or omit for a thread-level comment.'),
+        parentId: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Parent comment ID for thread replies. Omit or pass null for top-level.'),
+    }), (args) => {
+        const { id, ...body } = args;
+        return client.createComment(id, body);
+    });
+    // ── Page-builder accessibility tools (Phase 7 MCP-parity, PR D) ───────
+    //
+    // The audit + fix pair operates on a page-builder tree (the JSON blob
+    // stored in a page document's `data.tree`). Both endpoints are
+    // deterministic — no LLM calls — so they're cheap to call on every
+    // save / debounced edit. `audit_page_a11y` is read-only; `fix_page_a11y`
+    // mutates the tree and emits a `settings_changed` audit event.
+    //
+    // Tree typing: we accept any JSON object (z.record(z.unknown())) —
+    // strings, numbers, arrays, and null are rejected at the Zod layer
+    // with a clear schema error. The page-builder schema itself is large
+    // and evolving, so we don't try to mirror it field-for-field; the
+    // server validates the top-level shape (`tree.type === 'page'`)
+    // before processing.
+    tool('audit_page_a11y', 'Run a deterministic accessibility audit over a page-builder tree. Detects missing alt text, heading-level skips, missing form labels, missing ARIA attributes, and undersized touch targets. Each returned issue carries `autoFixable: boolean` so the caller can decide whether to follow up with `fix_page_a11y` (auto-fix) or surface it for human review.', z.object({
+        tree: z
+            .record(z.unknown())
+            .describe('Page-builder tree (the JSON object from a page document\'s `data.tree`). Top-level node must have `type: "page"` or the server returns HTTP 400.'),
+    }), (args) => client.auditPageA11y(args.tree));
+    tool('fix_page_a11y', 'Auto-fix the accessibility issues marked `autoFixable: true` from `audit_page_a11y` and return the mutated tree plus a report (`fixedCount` / `remainingCount`). Non-auto-fixable issues are returned in `report.issues` so the caller can surface them for human follow-up. The server emits a `settings_changed` audit event with the fix counts.', z.object({
+        tree: z
+            .record(z.unknown())
+            .describe('Page-builder tree. Top-level node must have `type: "page"` or the server returns HTTP 400.'),
+    }), (args) => client.fixPageA11y(args.tree));
+    // ── Comment thread management (Phase 7 MCP-parity, PR E) ──────────────
+    //
+    // P1 follow-up to PR D's `list_comments` + `create_comment`. Lets agents
+    // run the full thread lifecycle: edit a typo, resolve a thread once
+    // addressed, re-open it if the fix was wrong, soft-delete a wayward
+    // comment.
+    //
+    // All four use `id` (the comment ID, not the document ID) — there is no
+    // ambiguity here because the URL path is `/comments/:id`, not nested
+    // under a document.
+    tool('edit_comment', 'Edit a comment body. Only the original author can edit. Resolved threads remain editable so a moderator can append clarifying context. The server emits an `updated_at` bump but does NOT create a version row (comments are not versioned the way documents are).', z.object({
+        id: z.string().describe('Comment ID.'),
+        body: z.string().min(1).describe('New comment text. Empty strings are rejected.'),
+    }), (args) => client.editComment(args.id, args.body));
+    tool('resolve_comment', "Mark a comment thread resolved. Requires write-role (admins, editors, authors). Emits a `comment_resolved` audit event and fires a best-effort notification dispatch for the thread's participants. Idempotent on the server side — resolving an already-resolved thread returns the existing state.", z.object({
+        id: z.string().describe('Comment ID.'),
+    }), (args) => client.resolveComment(args.id));
+    tool('reopen_comment', 'Re-open a previously resolved comment thread. Requires write-role. Emits a `comment_reopened` audit event. Pair with `resolve_comment` to bounce a thread back and forth as a fix iterates.', z.object({
+        id: z.string().describe('Comment ID.'),
+    }), (args) => client.reopenComment(args.id));
+    tool('delete_comment', 'Soft-delete a comment. Only the original author OR an admin can delete; the server returns HTTP 403 otherwise. Soft-deleted comments stay queryable via `list_comments({ includeDeleted: true })` for admins only — they hold moderation history that should not leak via a regular editor session.', z.object({
+        id: z.string().describe('Comment ID.'),
+    }), (args) => client.deleteComment(args.id));
+    // ── Redirects (Phase 7 MCP-parity, PR E) ──────────────────────────────
+    //
+    // Redirects are admin-only on the server side (create + delete return
+    // HTTP 403 for non-admin keys). The server enforces an open-redirect
+    // defence — absolute destinations must hit `NEXT_PUBLIC_SITE_URL` or a
+    // host explicitly listed in `redirects.allowedExternalHosts`. We let
+    // the server own that validation rather than re-implementing it here.
+    tool('list_redirects', 'List every redirect rule, newest first. Returns `{ data: Redirect[] }`. Each redirect carries `{ id, source, destination, statusCode, isRegex, notes, createdAt }`. Useful as the first call in a migration workflow ("what 301s are already in place?").', z.object({}), () => client.listRedirects());
+    tool('create_redirect', 'Create a redirect rule. **Admin-only** — non-admin API keys get HTTP 403. The server enforces an open-redirect defence: relative destinations (e.g. "/new-path") are always allowed; absolute URLs must point at `NEXT_PUBLIC_SITE_URL` or a host explicitly listed in `redirects.allowedExternalHosts` (CMS config). statusCode accepts 301 / 302 / 307 / 308 only and defaults to 301.', z.object({
+        source: z
+            .string()
+            .min(1)
+            .describe('The path or pattern that triggers the redirect (e.g. "/old-blog/:slug").'),
+        destination: z
+            .string()
+            .min(1)
+            .describe('Where to send the request. Relative path or absolute URL on an allowlisted host.'),
+        statusCode: z
+            .union([z.literal(301), z.literal(302), z.literal(307), z.literal(308)])
+            .optional()
+            .describe('HTTP redirect status. Default 301 (permanent).'),
+        isRegex: z
+            .boolean()
+            .optional()
+            .describe('When true, `source` is treated as a regex pattern. Default false.'),
+        notes: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Operator notes for why this redirect exists.'),
+    }), (args) => client.createRedirect(args));
+    tool('delete_redirect', 'Delete a redirect rule. **Admin-only**. Destructive — the source path will start returning the underlying page (or 404) again. Confirm with the human before invoking.', z.object({
+        id: z.string().describe('Redirect ID.'),
+    }), (args) => client.deleteRedirect(args.id));
+    // ── Page templates + saved sections (Phase 7 MCP-parity, PR E) ────────
+    //
+    // Discovery tools for the page-builder. Listed as P1 because most
+    // agents won't touch templates directly, but they're useful for
+    // generation flows that want to seed `generate_page` with a real
+    // starting structure. All three endpoints are admin-only on the
+    // server (templates are an authoring-power-tool, not a runtime concern).
+    tool('list_page_templates', 'List available page templates for the page-builder. **Admin-only**. Optional `category` filter narrows the result. Optional `collection` reorders the result so the suggested templates for that collection bubble to the top (e.g. "blog-post" for the `posts` collection); when supplied, the response also carries a top-level `suggestion` block. Useful as a discovery step before invoking `generate_page` or `create_page_from_prompt`.', z.object({
+        category: z
+            .string()
+            .optional()
+            .describe('Optional template category filter (e.g. "marketing", "blog").'),
+        collection: z
+            .string()
+            .optional()
+            .describe('Optional collection slug. Reorders results to surface templates suggested for this collection and annotates each row with `suggested` / `suggestionRank`.'),
+    }), (args) => client.listPageTemplates(args));
+    tool('get_page_template', 'Fetch a single page template by ID, including its full builder tree. **Admin-only**. Pair with `list_page_templates` to discover IDs, then use this to inspect the tree before applying it.', z.object({
+        id: z.string().describe('Page template ID (e.g. "builtin-blog-post" or a custom slug).'),
+    }), (args) => client.getPageTemplate(args.id));
+    tool('list_saved_sections', 'List saved page-builder sections (reusable blocks that authors have promoted to the section library). **Admin-only**. Optional `category` filter. Useful for "give me a starting point" workflows.', z.object({
+        category: z.string().optional().describe('Optional category filter.'),
+    }), (args) => client.listSavedSections(args));
+    // ── SEO aggregate tools (Phase 7 MCP-parity, PR E) ────────────────────
+    //
+    // `seo_summary` is cheap and dashboard-shaped. `seo_scan_run` is
+    // **expensive** (touches every published doc) so the audit recommended
+    // gating it behind a confirmation arg. We enforce that at the wrapper
+    // layer — calling without `confirm: true` throws before the HTTP call.
+    tool('seo_summary', 'Aggregate SEO health for the site dashboard. Returns counts of missing meta descriptions / missing alt text plus `topContent`: the recent published documents with light SEO scores. Cheap; safe to call on every dashboard refresh.', z.object({}), () => client.seoSummary());
+    tool('seo_scan_run', "Run a site-wide SEO scan over every published document. **Expensive** — the server walks every row in the published set. Returns `{ total, pagesWithIssues, totalProblems, issues[] }`. Requires `confirm: true` to invoke (the tool wrapper refuses to forward the request otherwise); this matches the audit's gate-behind-confirmation recommendation for expensive operations.", z.object({
+        confirm: z
+            .literal(true)
+            .describe('Must be `true` to acknowledge that this is an expensive site-wide scan. Calling without it is rejected at the wrapper.'),
+    }), (args) => {
+        // Defence-in-depth: Zod `.literal(true)` already rejects anything
+        // else, but we re-check so the failure mode is a clear runtime
+        // error if the schema ever drifts.
+        if (args.confirm !== true) {
+            throw new Error('seo_scan_run requires confirm: true to acknowledge expensive operation.');
+        }
+        return client.seoScanRun();
+    });
+    // ── SEO Operations Center (audit runs, issues, redirects) ─────────────
+    //
+    // These wrap the persistent audit/issue/redirect endpoints (distinct from
+    // the per-document `seo_*` analysis tools and the deterministic
+    // `seo_scan_run`). They let an agent inspect site SEO health, trigger an
+    // audit, triage issues, and review redirect hygiene.
+    tool('seo_overview', 'Aggregated SEO Overview: site score + grade + delta, headline metrics, open-issue summary, priority-ranked quick wins, and (gated) search-performance rows. Derived from the last completed audit run. Cheap read.', z.object({}), () => client.seoOverview());
+    tool('run_seo_audit', 'Start a persistent SEO audit run and return the created run (status, issue counts, before/after site score). `scope`: full (default), content, technical, or redirect. Heavier than seo_summary — persists issues queryable via list_seo_issues.', z.object({
+        scope: z
+            .enum(['full', 'content', 'technical', 'redirect'])
+            .optional()
+            .describe('Audit breadth. Defaults to full.'),
+    }), (args) => client.runSeoAudit(args.scope ?? 'full'));
+    tool('list_seo_audit_runs', 'List persisted SEO audit runs, newest first, with their status and issue counts.', z.object({}), () => client.listSeoAuditRuns());
+    tool('list_seo_issues', 'List SEO issues with optional filters. Use this to triage what needs fixing across the site.', z.object({
+        severity: z.enum(['critical', 'warning', 'info']).optional(),
+        category: z
+            .enum([
+            'content',
+            'technical',
+            'redirects',
+            'media',
+            'performance',
+            'schema',
+            'social',
+            'indexing',
+        ])
+            .optional(),
+        status: z.enum(['open', 'ignored', 'resolved', 'recurring']).optional(),
+        auditRunId: z.string().optional().describe('Scope issues to a single audit run.'),
+    }), (args) => client.listSeoIssues(args));
+    tool('get_seo_issue', 'Fetch a single SEO issue by ID, including its impact and recommendation.', z.object({ id: z.string().describe('SEO issue ID') }), (args) => client.getSeoIssue(args.id));
+    tool('set_seo_issue_status', 'Resolve, ignore, or reopen an SEO issue. Status changes are audit-logged server-side.', z.object({
+        id: z.string().describe('SEO issue ID'),
+        action: z.enum(['resolve', 'ignore', 'reopen']),
+    }), (args) => client.setSeoIssueStatus(args.id, args.action));
+    tool('export_seo_fix_brief', 'Export a markdown SEO fix brief for dev-team handoff. Groups manual/content issues by page, includes issue IDs, admin deep links, and embedded cached AI content briefs + topic research when available. Cheap read — use after batch-generating briefs or to pull the full queue into your workspace.', z.object({
+        severity: z.enum(['critical', 'warning', 'info']).optional(),
+        status: z.enum(['open', 'ignored', 'resolved', 'recurring']).optional(),
+        auditRunId: z.string().optional(),
+        manualOnly: z
+            .boolean()
+            .optional()
+            .describe('When true (default), omit inline metadata fixes that have Approve fix in admin.'),
+        includeContentBriefs: z
+            .boolean()
+            .optional()
+            .describe('Embed cached AI briefs (default true).'),
+        includeContentResearch: z
+            .boolean()
+            .optional()
+            .describe('Embed cached topic research (default true).'),
+    }), (args) => client.exportSeoFixBrief(args));
+    tool('suggest_seo_issue_fix', 'Preview an inline SEO fix for metadata/schema issues (meta title/desc, canonical, noindex, duplicates, structured data). Returns `{ suggestion }` with field changes, fingerprint, and `autoFixable`. Call `apply_seo_issue_fix` with the same fingerprint to apply. Does not modify page body content.', z.object({ id: z.string().describe('SEO issue ID from list_seo_issues') }), (args) => client.suggestSeoIssueFix(args.id));
+    tool('apply_seo_issue_fix', 'Apply a previously previewed inline SEO fix and mark the issue resolved. Writes SEO metadata fields only — never page body. Requires `confirm: true` and the exact `fingerprint` from `suggest_seo_issue_fix`.', z.object({
+        id: z.string().describe('SEO issue ID'),
+        fingerprint: z
+            .string()
+            .describe('Fingerprint from suggest_seo_issue_fix — prevents stale apply'),
+        confirm: z
+            .literal(true)
+            .describe('Must be true — confirms user approval to mutate SEO fields'),
+    }), (args) => {
+        if (args.confirm !== true) {
+            throw new Error('apply_seo_issue_fix requires confirm: true.');
+        }
+        return client.applySeoIssueFix(args.id, args.fingerprint);
+    });
+    tool('get_seo_issue_content_brief', 'Load a cached AI content brief for thin-content, heading, or alt-text issues. Returns `{ supported, brief, stale }`. Use `generate_seo_issue_content_brief` or `research_and_brief_seo_issue` to create one.', z.object({ id: z.string().describe('SEO issue ID') }), (args) => client.getSeoIssueContentBrief(args.id));
+    tool('generate_seo_issue_content_brief', 'Generate an AI content brief (topics, suggested H1, GEO takeaway) for manual content fixes. Suggestions only — does not write page body. Rate-limited server-side.', z.object({ id: z.string().describe('SEO issue ID') }), (args) => client.generateSeoIssueContentBrief(args.id));
+    tool('research_and_brief_seo_issue', 'For thin-content issues: run topic research (optional competitor URLs, SSRF-safe, max 3) then generate a content brief informed by that research. For other brief-eligible issues, generates a brief only. Rate-limited; caches results on the issue.', z.object({
+        id: z.string().describe('SEO issue ID'),
+        competitorUrls: z
+            .array(z.string().url())
+            .max(3)
+            .optional()
+            .describe('Optional public competitor pages to inform topic research'),
+    }), (args) => client.researchAndBriefSeoIssue(args.id, args.competitorUrls));
+    tool('batch_generate_seo_content_briefs', 'Pre-generate AI content briefs for up to 15 open issues (skips fresh cached briefs). **Expensive** — multiple AI calls. Requires `confirm: true`. Pair with `export_seo_fix_brief` to pull the full handoff doc.', z.object({
+        confirm: z.literal(true).describe('Must be true to acknowledge batch AI cost'),
+        severity: z.enum(['critical', 'warning', 'info']).optional(),
+        status: z.enum(['open', 'ignored', 'resolved', 'recurring']).optional(),
+        issueIds: z.array(z.string()).optional().describe('Limit to specific issue IDs'),
+        skipExisting: z
+            .boolean()
+            .optional()
+            .describe('Skip issues with fresh cached briefs (default true)'),
+        includeResearch: z
+            .boolean()
+            .optional()
+            .describe('Run topic research before briefs for thin-content issues'),
+        competitorUrls: z
+            .array(z.string().url())
+            .max(3)
+            .optional()
+            .describe('Competitor URLs for thin-content research'),
+    }), (args) => {
+        if (args.confirm !== true) {
+            throw new Error('batch_generate_seo_content_briefs requires confirm: true.');
+        }
+        const { confirm: _c, ...body } = args;
+        return client.batchGenerateSeoContentBriefs(body);
+    });
+    tool('list_redirect_rules', 'List redirect rules with hit counts, neverHit (no recorded hits), and stale flags (last hit 60+ days ago). Use to audit redirect hygiene.', z.object({}), () => client.listRedirectRules());
+    tool('seo_redirect_overview', 'Redirect overview counts: active redirects, stale redirects, tracked 404s, and chains/loops.', z.object({}), () => client.redirectOverview());
+    tool('seo_redirect_chains', 'List detected redirect chains and loops with safe-flatten suggestions. Chains hurt crawl budget and link equity.', z.object({}), () => client.redirectChains());
+    tool('flatten_redirect_chain', "Flatten a redirect chain to a single hop by updating the first rule's destination. Requires the `chainId` from `seo_redirect_chains`.", z.object({
+        chainId: z.string().describe('Chain ID from seo_redirect_chains.'),
+    }), (args) => client.flattenRedirectChain(args.chainId));
+    tool('list_redirect_suggestions', 'List AI-generated 404 recovery redirect suggestions awaiting review.', z.object({}), () => client.listRedirectSuggestions());
+    tool('get_redirect_recovery_settings', 'Fetch 404 recovery settings: AI rerank, auto-apply, and minimum confidence threshold.', z.object({}), () => client.getRedirectRecoverySettings());
+    tool('update_redirect_recovery_settings', 'Update 404 recovery settings (partial patch). Admin-only.', z.object({
+        aiRerank: z.boolean().optional(),
+        autoApply: z.boolean().optional(),
+        autoApplyMinConfidence: z.number().min(0).max(1).optional(),
+    }), (args) => client.updateRedirectRecoverySettings(args));
+    tool('generate_redirect_recovery_suggestions', 'Scan tracked 404s and generate recovery redirect suggestions. **Expensive** — may invoke AI reranking. Requires `confirm: true`.', z.object({
+        confirm: z
+            .literal(true)
+            .optional()
+            .describe('Must be true — acknowledges an expensive recovery scan.'),
+    }), (args) => {
+        if (args.confirm !== true) {
+            throw new Error('generate_redirect_recovery_suggestions requires confirm: true.');
+        }
+        return client.generateRedirectRecoverySuggestions();
+    });
+    tool('accept_redirect_suggestion', 'Accept a 404 recovery suggestion — creates the redirect rule. Requires suggestion `id` from `list_redirect_suggestions`.', z.object({ id: z.string().describe('Suggestion ID.') }), (args) => client.acceptRedirectSuggestion(args.id));
+    tool('dismiss_redirect_suggestion', 'Dismiss a 404 recovery suggestion without creating a redirect.', z.object({ id: z.string().describe('Suggestion ID.') }), (args) => client.dismissRedirectSuggestion(args.id));
+    tool('export_redirects_csv', 'Export all redirect rules as CSV for backup or migration.', z.object({}), () => client.exportRedirectsCsv());
+    tool('import_redirects_csv', 'Import redirect rules from CSV. **Bulk mutation** — requires `confirm: true`. Returns `{ imported, errors[] }`.', z.object({
+        csv: z.string().min(1).describe('CSV content (from export_redirects_csv format).'),
+        confirm: z.literal(true).optional().describe('Must be true — acknowledges bulk import.'),
+    }), (args) => {
+        if (args.confirm !== true) {
+            throw new Error('import_redirects_csv requires confirm: true.');
+        }
+        return client.importRedirectsCsv(args.csv);
+    });
+    tool('update_redirect_rule', 'Update an existing redirect rule by ID. Partial patch — only supplied fields change. Admin-only.', z.object({
+        id: z.string().describe('Redirect rule ID.'),
+        fromPath: z.string().optional(),
+        toPath: z.string().optional(),
+        type: z.union([z.literal(301), z.literal(302), z.literal(307), z.literal(308)]).optional(),
+        enabled: z.boolean().optional(),
+        preserveQuery: z.boolean().optional(),
+        notes: z.string().optional(),
+    }), (args) => {
+        const { id, ...body } = args;
+        return client.updateRedirectRule(id, body);
+    });
+    // ── SEO Links dashboard (Phase 1 MCP parity) ──────────────────────────
+    tool('seo_links_snapshot', 'Site-wide link graph snapshot: internal/external counts, orphan pages, under-linked content, broken links, and AI index readiness. Cheap read — mirrors the SEO Links tab.', z.object({}), () => client.seoLinkSnapshot());
+    tool('seo_link_health', 'Scan published content for broken or suspicious outbound links. Returns `{ issues[], checked, truncated }` — bounded to protect large sites.', z.object({}), () => client.seoLinkHealth());
+    tool('seo_link_suggest', 'Suggest contextual internal links TO a target page/post from other published content. Requires a built AI link index (`run_seo_link_ai_index`).', z.object({
+        targetEntityId: z.string().describe('Target document ID to receive inbound links.'),
+        targetEntityType: z.enum(['page', 'post']),
+        limit: z.number().int().min(1).max(20).optional(),
+    }), (args) => client.seoLinkSuggest(args));
+    tool('run_seo_link_ai_index', 'Build or refresh the AI link index for contextual link suggestions. **Expensive** — scans content and may call the AI provider. Requires `confirm: true`.', z.object({
+        confirm: z
+            .literal(true)
+            .optional()
+            .describe('Must be true — acknowledges expensive indexing.'),
+    }), (args) => {
+        if (args.confirm !== true) {
+            throw new Error('run_seo_link_ai_index requires confirm: true.');
+        }
+        return client.seoLinkAiIndex();
+    });
+    // ── SEO technical settings (Phase 1 MCP parity) ───────────────────────
+    tool('get_seo_crawl_settings', 'Fetch crawl/sitemap settings: indexEntireSite, sitemapEnabled, autoRegenerateSitemapOnPublish, pingSearchEnginesOnPublish, etc.', z.object({}), () => client.getCrawlSettings());
+    tool('update_seo_crawl_settings', 'Update crawl/sitemap settings (partial patch). Admin-only.', z.object({
+        indexEntireSite: z.boolean().optional(),
+        includeImagesInSitemap: z.boolean().optional(),
+        includePostsInSitemap: z.boolean().optional(),
+        sitemapEnabled: z.boolean().optional(),
+        autoRegenerateSitemapOnPublish: z.boolean().optional(),
+        pingSearchEnginesOnPublish: z.boolean().optional(),
+    }), (args) => client.updateCrawlSettings(args));
+    tool('get_seo_robots', 'Fetch robots.txt configuration: `{ body, generated }`.', z.object({}), () => client.getRobotsTxt());
+    tool('update_seo_robots', 'Replace robots.txt body. Admin-only — validate carefully; a bad robots.txt can deindex the site.', z.object({
+        body: z.string().describe('Full robots.txt content.'),
+    }), (args) => client.updateRobotsTxt(args.body));
+    tool('get_seo_sitemap_status', 'Fetch sitemap generation status: last run, URL count, errors.', z.object({}), () => client.getSitemapStatus());
+    tool('regenerate_seo_sitemap', 'Force sitemap regeneration. Requires `confirm: true`.', z.object({
+        confirm: z.literal(true).optional().describe('Must be true — acknowledges sitemap rebuild.'),
+    }), (args) => {
+        if (args.confirm !== true) {
+            throw new Error('regenerate_seo_sitemap requires confirm: true.');
+        }
+        return client.regenerateSitemap();
+    });
+    // ── SEO content records (Phase 1 MCP parity) ──────────────────────────
+    tool('list_seo_content', 'List all pages/posts with SEO scores and metadata summary. Use to find content needing optimization.', z.object({}), () => client.listSeoContentRecords());
+    tool('get_seo_content', 'Fetch full SEO fields for one page or post (`entityType`: page|post, `entityId`: document ID).', z.object({
+        entityType: z.enum(['page', 'post']),
+        entityId: z.string(),
+    }), (args) => client.getSeoContentRecord(args.entityType, args.entityId));
+    tool('update_seo_content', 'Update SEO metadata fields for a page or post. Writes meta title/desc, canonical, OG, robots flags, schema type, llms.txt curation — never page body content.', z.object({
+        entityType: z.enum(['page', 'post']),
+        entityId: z.string(),
+        metaTitle: z.string().optional().describe('Page-specific title (%page% slot).'),
+        metaDescription: z.string().optional(),
+        canonicalUrl: z.string().optional(),
+        focusKeyword: z.string().optional(),
+        keyTakeaway: z.string().optional(),
+        ogTitle: z.string().optional(),
+        ogDescription: z.string().optional(),
+        noindex: z.boolean().optional(),
+        nofollow: z.boolean().optional(),
+        structuredDataType: z.string().optional(),
+        llmsInclude: z.enum(['AUTO', 'ALWAYS', 'NEVER']).optional(),
+        llmsDescription: z.string().optional(),
+        llmsSection: z.string().optional(),
+        llmsOptional: z.boolean().optional(),
+    }), (args) => {
+        const { entityType, entityId, ...body } = args;
+        return client.updateSeoContentFields(entityType, entityId, body);
+    });
+    // ── AI SEO assistant (Phase 1 MCP parity) ─────────────────────────────
+    tool('ai_seo_generate_field', 'Generate an SEO field (metaTitle, metaDescription, ogTitle, ogDescription, focusKeyword, keyTakeaway) via AI. Returns suggestions or `{ unavailable: true }` when plugin-ai is not configured. Rate-limited.', z.object({
+        field: z.enum([
+            'metaTitle',
+            'metaDescription',
+            'ogTitle',
+            'ogDescription',
+            'focusKeyword',
+            'keyTakeaway',
+        ]),
+        entityType: z.enum(['page', 'post']),
+        entityId: z.string(),
+    }), (args) => client.aiSeoGenerateField(args));
+    tool('ai_seo_explain_issue', 'AI explanation of an SEO audit issue — impact, root cause, and fix guidance. Returns `{ unavailable: true }` when AI is not configured.', z.object({ issueId: z.string().describe('SEO issue ID from list_seo_issues.') }), (args) => client.aiSeoExplainIssue(args.issueId));
+    tool('ai_seo_generate_schema', 'Generate JSON-LD structured data for a page/post via AI. Review before saving with update_seo_content or apply_seo_issue_fix.', z.object({
+        entityType: z.enum(['page', 'post']),
+        entityId: z.string(),
+        schemaType: z.string().describe('Schema.org type (e.g. Article, WebPage, FAQPage).'),
+    }), (args) => client.aiSeoGenerateSchema(args));
+    tool('ai_seo_summarize_audit', 'AI summary of the latest SEO audit — headline findings and recommended priorities. Returns `{ unavailable: true }` when AI is not configured.', z.object({}), () => client.aiSeoSummarize());
+    // ── Forms + health (Phase 7 MCP-parity, PR E) ─────────────────────────
+    tool('list_form_submissions', 'List submissions for a specific form, paged (default 20). **PII-sensitive** — submissions typically contain names, emails, phone numbers, and free-form messages. The tool refuses to enumerate forms automatically; the caller MUST pass an explicit `formId`. Requires write-role on the API key. Pair with the existing `list_documents({ collection: "forms" })` to discover form IDs first.', z.object({
+        formId: z.string().describe('Form document ID. No enumeration — the caller must know it.'),
+        page: z.number().int().min(1).optional(),
+        pageSize: z.number().int().min(1).max(100).optional(),
+    }), (args) => {
+        const { formId, ...query } = args;
+        return client.listFormSubmissions(formId, query);
+    });
+    tool('list_form_entries', 'List entries from the submissions inbox for a specific form. Returns `{ data: { entries, total, page, pageSize } }` with decrypted field values, sender info, attribution, and read/star/archive state. **PII-sensitive** — entries contain names, emails, phone numbers, and free-form messages. The caller MUST pass an explicit `formId` (no enumeration). Use `list_documents({ collection: "forms" })` to discover form IDs first. Filter with `unread` / `starred` / `archived` / `spamStatus`.', z.object({
+        formId: z.string().describe('Form document ID. Required — no enumeration.'),
+        page: z.number().int().min(1).optional(),
+        pageSize: z.number().int().min(1).max(100).optional(),
+        unread: z.boolean().optional(),
+        starred: z.boolean().optional(),
+        archived: z.boolean().optional(),
+        spamStatus: z.enum(['clean', 'suspected', 'spam']).optional(),
+    }), (args) => client.listFormEntries(args));
+    tool('get_form_entry', 'Read a single submission inbox entry by id, including the schema fields it was captured against: `{ data: { entry, fields } }`. **PII-sensitive** — exposes decrypted field values; the server records a `form.entry.viewed` audit event for every read. Obtain the `entryId` from `list_form_entries`.', z.object({
+        entryId: z.string().describe('Submission entry id (from list_form_entries).'),
+    }), (args) => client.getFormEntry(args.entryId));
+    // ── Form authoring (WS-C C1) ──────────────────────────────────────────
+    //
+    // The tools above READ a form's submissions. These let an agent BUILD and
+    // MAINTAIN the form itself: discover/create/edit the definition, version
+    // its field schema, manage the submissions inbox, and export. All require
+    // a write-role API key server-side. With these an agent can stand up a
+    // working contact/lead form and wire it into a page end-to-end over MCP.
+    tool('list_forms', 'List form definitions (NOT submissions). Returns `{ data: Form[], total, page, pageSize }`; each form includes its field schema, `fieldCount`, and submission count. This is the canonical way to discover form IDs before reading entries (`list_form_entries`) or editing a schema (`save_form_schema`). Filter with `status` (active | draft | archived) and `search`.', z.object({
+        page: z.number().int().min(1).optional(),
+        pageSize: z.number().int().min(1).max(100).optional(),
+        status: z.enum(['active', 'draft', 'archived']).optional(),
+        search: z.string().optional().describe('Free-text search against form name.'),
+    }), (args) => client.listForms(args));
+    tool('get_form', 'Fetch a single form definition by ID — metadata plus the current field schema. Pair with `list_forms` to discover IDs.', z.object({ id: z.string().describe('Form ID.') }), (args) => client.getForm(args.id));
+    tool('create_form', 'Create a form. Only `name` is required; the slug is derived from the name when omitted. Pass `fields` to seed the field schema in one shot, or omit it and add the schema later with `save_form_schema`. New forms default to `draft` status — set `status: "active"` to make the form accept submissions. Returns the created form.', z.object({
+        name: z.string().min(1).describe('Human-facing form name (also seeds the slug).'),
+        slug: z.string().optional().describe('URL slug override. Auto-derived from name if omitted.'),
+        description: z.string().optional(),
+        status: z
+            .enum(['active', 'draft', 'archived'])
+            .optional()
+            .describe('Defaults to "draft". Only "active" forms accept public submissions.'),
+        fields: z
+            .array(z.record(z.any()))
+            .optional()
+            .describe('Initial field schema. Each field: { label, key, type, required, ... }. `type` is one of text|email|phone|textarea|select|multiselect|radio|checkbox|date|number|url|hidden|file|consent|richtext|divider|honeypot. Invalid schemas are rejected with field-level errors.'),
+        successMessage: z.string().optional().describe('Message shown after a successful submit.'),
+        redirectUrl: z.string().optional().describe('Optional post-submit redirect URL.'),
+    }), (args) => client.createForm(args));
+    tool('update_form', 'Update a form\'s metadata (name, description, status, success message, redirect). Only the supplied fields change. NOTE: the field SCHEMA is NOT editable here — use `save_form_schema` so every schema change is versioned. Set `status: "archived"` to stop accepting submissions without deleting the form.', z.object({
+        id: z.string().describe('Form ID.'),
+        name: z.string().optional(),
+        description: z.string().optional(),
+        status: z.enum(['active', 'draft', 'archived']).optional(),
+        successMessage: z.string().optional(),
+        redirectUrl: z.string().optional(),
+    }), (args) => {
+        const { id, ...body } = args;
+        return client.updateForm(id, body);
+    });
+    tool('delete_form', 'Delete a form. Destructive — confirm with the user first. By default the server refuses (HTTP 409) when the form has submissions; pass `force: true` to delete the form AND all its captured submissions (PII). Prefer `update_form({ status: "archived" })` if you only want to stop new submissions.', z.object({
+        id: z.string().describe('Form ID.'),
+        force: z
+            .boolean()
+            .optional()
+            .describe('When true, delete even if the form has submissions (also deletes them).'),
+        confirm: z
+            .literal(true)
+            .describe('Must be `true` to acknowledge this destructive action. Confirm with the user first.'),
+    }), (args) => {
+        if (args.confirm !== true) {
+            throw new Error('delete_form requires confirm: true to acknowledge a destructive action.');
+        }
+        return client.deleteForm(args.id, args.force);
+    });
+    tool('duplicate_form', 'Duplicate a form into a new draft copy with a fresh slug. The copy starts in "draft" and has no submissions. Useful as a starting point for a variant.', z.object({ id: z.string().describe('Form ID to duplicate.') }), (args) => client.duplicateForm(args.id));
+    tool('get_form_schema', "Read a form's field schema plus its version history: `{ fields, activeVersionId, versions }`. Call this BEFORE `save_form_schema` so you can mutate the existing `fields` array and write back the whole thing rather than clobbering the live schema.", z.object({ id: z.string().describe('Form ID.') }), (args) => client.getFormSchema(args.id));
+    tool('save_form_schema', "Replace a form's field schema. `fields` is the FULL ordered field list (partial patches are not supported — read with `get_form_schema`, mutate, write the whole array back). Creates a NEW schema version (history is never rewritten) and points the form at it. Invalid schemas are rejected with field-level errors. Each field: { label, key, type, required, options?, validationRules?, ... }.", z.object({
+        id: z.string().describe('Form ID.'),
+        fields: z
+            .array(z.record(z.any()))
+            .describe('Full ordered field list. `type` ∈ text|email|phone|textarea|select|multiselect|radio|checkbox|date|number|url|hidden|file|consent|richtext|divider|honeypot.'),
+        notes: z.string().optional().describe('Optional changelog note attached to this version.'),
+    }), (args) => client.saveFormSchema(args.id, args.fields, args.notes));
+    tool('set_form_entry_status', 'Update inbox state on a single submission entry: mark read/unread, star, or archive. Pass any subset of { unread, starred, archived }. Does NOT alter the captured field values. Obtain `entryId` from `list_form_entries`.', z.object({
+        entryId: z.string().describe('Submission entry ID (from list_form_entries).'),
+        unread: z.boolean().optional().describe('true = mark unread, false = mark read.'),
+        starred: z.boolean().optional(),
+        archived: z.boolean().optional(),
+    }), (args) => {
+        const { entryId, ...patch } = args;
+        if (patch.unread === undefined &&
+            patch.starred === undefined &&
+            patch.archived === undefined) {
+            throw new Error('Provide at least one of unread, starred, or archived.');
+        }
+        return client.updateFormEntry(entryId, patch);
+    });
+    tool('bulk_set_form_entry_status', 'Apply the same inbox-state patch (read/star/archive) to many entries at once. Pass a non-empty `ids` array and a `patch` with at least one of { unread, starred, archived }. Returns `{ updated: <count> }`. Use for "archive all spam" / "mark all read" workflows.', z.object({
+        ids: z.array(z.string()).min(1).describe('Entry IDs to update (non-empty).'),
+        unread: z.boolean().optional(),
+        starred: z.boolean().optional(),
+        archived: z.boolean().optional(),
+    }), (args) => {
+        const { ids, ...patch } = args;
+        if (patch.unread === undefined &&
+            patch.starred === undefined &&
+            patch.archived === undefined) {
+            throw new Error('Provide at least one of unread, starred, or archived in the patch.');
+        }
+        return client.bulkUpdateFormEntries(ids, patch);
+    });
+    tool('delete_form_entry', 'Permanently delete a single submission entry and its decrypted PII. Destructive and irreversible — requires `confirm: true` (the wrapper refuses otherwise). Prefer `set_form_entry_status({ archived: true })` to hide an entry without destroying it.', z.object({
+        entryId: z.string().describe('Submission entry ID to delete.'),
+        confirm: z
+            .literal(true)
+            .describe('Must be `true` to acknowledge this irreversible action. Confirm with the user first.'),
+    }), (args) => {
+        if (args.confirm !== true) {
+            throw new Error('delete_form_entry requires confirm: true to acknowledge an irreversible action.');
+        }
+        return client.deleteFormEntry(args.entryId);
+    });
+    tool('export_form_entries', 'Export EVERY submission for a form as CSV. **Bulk PII egress** — the CSV contains decrypted names, emails, phone numbers, and free-form messages, and the server records a `form.entries.exported` audit event. Requires `confirm: true` to acknowledge the bulk PII access (the wrapper refuses otherwise). Returns `{ filename, csv }`. Discover `formId` via `list_forms`.', z.object({
+        formId: z.string().describe('Form ID whose submissions to export. No enumeration.'),
+        confirm: z
+            .literal(true)
+            .describe('Must be `true` to acknowledge this exports decrypted PII in bulk.'),
+    }), (args) => {
+        // Defence-in-depth: Zod `.literal(true)` already rejects anything
+        // else, but re-check so the failure mode stays a clear runtime error
+        // if the schema ever drifts.
+        if (args.confirm !== true) {
+            throw new Error('export_form_entries requires confirm: true to acknowledge bulk PII export.');
+        }
+        return client.exportFormEntries(args.formId);
+    });
+    tool('health_check', 'Read deployment health: `{ status: "healthy" | "degraded" | "unhealthy", version, env (per-secret validation), models (per-table availability), databaseConnected, secretConfigured }`. The /health endpoint itself is unauthenticated on the server so this works even when the API key has zero scopes. Useful as an agent\'s first call — a `degraded` or `unhealthy` status surfaces operator-level config problems early instead of as cryptic errors deep in a later workflow.', z.object({}), () => client.healthCheck());
+    tool('search_users', "Resolve up to 10 active + approved users by name or email (case-insensitive `contains`). Returns `{ data: Array<{ id, name, email }> }`. Use this when drafting a comment that should `@`-mention a teammate: take the user-supplied name fragment, call `search_users`, and inject the resulting `id` as `@<userId>` into the comment body — the CMS's `extractMentionedUserIds` parser then routes a `comment_mention` notification to that user. The tool-level schema requires a non-empty `query` (the server-side endpoint additionally returns `[]` for empty or whitespace input, but the wrapper fails closed at the MCP boundary so an agent can't accidentally enumerate the directory).", z.object({
+        query: z
+            .string()
+            .min(1)
+            .describe('Name or email fragment to match. Required and non-empty; trimmed and capped at 64 chars server-side.'),
+    }), (args) => client.searchUsers(args.query));
+    tool('generate_page', 'Run the AI page builder to produce a page-builder tree from a prompt. Does NOT persist the result — use create_page_from_prompt for one-shot creation.', z.object({
+        prompt: z.string().describe('Plain-language description of the page to generate'),
+        template: z.string().optional().describe('Optional template slug to seed the structure'),
+        context: z.string().optional().describe('Additional context (brand voice, audience, etc.)'),
+        steps: z
+            .array(z.enum(['structure', 'content', 'seo', 'accessibility']))
+            .optional()
+            .describe('Which generation steps to run; defaults to all four'),
+        tone: z.string().optional(),
+    }), (args) => client.generatePage(args));
+    tool('create_page_from_prompt', 'One-shot page creation: generate a complete page via AI and persist it as a draft (or published) document. Returns the new document.', z.object({
+        prompt: z.string(),
+        collection: z
+            .string()
+            .optional()
+            .describe('Destination collection slug. Defaults to "pages".'),
+        template: z.string().optional(),
+        context: z.string().optional(),
+        steps: z.array(z.enum(['structure', 'content', 'seo', 'accessibility'])).optional(),
+        tone: z.string().optional(),
+        title: z.string().optional().describe('Override the AI-suggested title'),
+        slug: z.string().optional().describe('Override the auto-generated slug'),
+        publish: z
+            .boolean()
+            .optional()
+            .describe('When true, publish immediately instead of creating as DRAFT'),
+    }), (args) => client.createPageFromPrompt(args));
+    tool('generate_block', 'Generate a single page-builder block via AI.', z.object({
+        blockType: z.string().describe('Block type (e.g. "hero", "cta", "faq")'),
+        variant: z.string().optional(),
+        pageContext: z.any().optional(),
+        tone: z.string().optional(),
+    }), (args) => client.generateBlock(args));
+    // ── AI content authoring for non-page collections ────────────────────────
+    //
+    // Phase 7 PR F (audit stylistic note #1): collapsed the previous 6-tool
+    // bloat ("create_in_collection" + 5 per-type wrappers) into a single
+    // generic tool plus two type-specific tools that stay because they
+    // unlock genuinely different field-sets:
+    //
+    //   - `create_in_collection` — accepts an optional `template` arg that
+    //     selects a built-in prompt-enrichment recipe (service / location /
+    //     team / generic) AND a default collection slug. The recipe folds
+    //     structured fields (category, cityState, name+role) into the
+    //     prompt so the AI lands them in the right document fields.
+    //   - `create_blog_post` — most-common authoring path; kept because
+    //     "blog post" is a canonical agent intent.
+    //   - `create_case_study` — different enough field-set (client /
+    //     industry framing) that collapsing it would hurt the resulting
+    //     content quality.
+    //
+    // Removed: `create_service`, `create_location`, `create_team_member`.
+    // Their behaviour is identical to
+    // `create_in_collection({ template: 'service' | 'location' |
+    // 'team_member', ... })` so the migration is mechanical.
+    const aiContentInputBase = {
+        prompt: z.string().describe('Plain-language brief describing what to write.'),
+        context: z
+            .string()
+            .optional()
+            .describe('Optional reference material — existing related content, brand facts, etc.'),
+        tone: z
+            .string()
+            .optional()
+            .describe('Tone modifier (e.g. "conversational", "expert", "playful").'),
+        targetAudience: z.string().optional(),
+        title: z.string().optional().describe('Override the AI-suggested title.'),
+        slug: z.string().optional().describe('Override the auto-generated slug.'),
+        publish: z
+            .boolean()
+            .optional()
+            .describe('When true, publish immediately instead of creating as DRAFT.'),
+    };
+    const templateRecipes = {
+        service: {
+            defaultCollection: 'services',
+            enrich: (prompt, args) => typeof args.category === 'string' && args.category
+                ? `${prompt} Category: ${args.category}.`
+                : prompt,
+        },
+        location: {
+            defaultCollection: 'locations',
+            enrich: (prompt, args) => typeof args.cityState === 'string' && args.cityState
+                ? `${prompt} Service area: ${args.cityState}.`
+                : prompt,
+        },
+        team_member: {
+            defaultCollection: 'team',
+            enrich: (prompt, args) => [
+                prompt,
+                typeof args.name === 'string' && args.name ? `Name: ${args.name}.` : '',
+                typeof args.role === 'string' && args.role ? `Role: ${args.role}.` : '',
+            ]
+                .filter(Boolean)
+                .join(' '),
+        },
+    };
+    tool('create_in_collection', "Generate a complete document for ANY non-page collection via AI and persist it. The AI maps the prompt into the collection's field schema and returns the new document (default DRAFT status). Pass `template` to apply a built-in prompt-enrichment recipe — this is the supported migration path for the now-removed `create_service` / `create_location` / `create_team_member` tools. Omit `template` for plain generic generation; `collection` is then required.", z.object({
+        collection: z
+            .string()
+            .optional()
+            .describe('Destination collection slug. Required when `template` is omitted. When a template is supplied, `collection` overrides the template default.'),
+        template: z
+            .enum(['service', 'location', 'team_member'])
+            .optional()
+            .describe('Pre-built recipe. "service" folds `category` into the prompt and defaults to "services". "location" folds `cityState` and defaults to "locations". "team_member" folds `name` + `role` and defaults to "team". Omit for plain generic generation (then `collection` is required).'),
+        // Template-specific structured fields. All optional at the schema
+        // layer; the recipe is responsible for folding only the ones it
+        // understands. Unknown extras are ignored — agents that pass
+        // `category` with template "location" simply don't get it enriched.
+        category: z.string().optional().describe('Template "service": product/service category.'),
+        cityState: z
+            .string()
+            .optional()
+            .describe('Template "location": city and state/region, e.g. "Austin, TX".'),
+        name: z.string().optional().describe('Template "team_member": full name.'),
+        role: z.string().optional().describe('Template "team_member": job title / role.'),
+        ...aiContentInputBase,
+    }), async (args) => {
+        const { collection, template, category, cityState, name, role, prompt, ...rest } = args;
+        const recipe = template ? templateRecipes[template] : undefined;
+        const targetCollection = collection ?? recipe?.defaultCollection;
+        if (!targetCollection) {
+            // Defence-in-depth: Zod can't express "at least one of A or B"
+            // cleanly. Reject at the handler so the agent gets a clear
+            // message instead of a server-side 404 on `/collections//ai-create`.
+            throw new Error('create_in_collection requires either `collection` or a `template` that supplies a default.');
+        }
+        const enrichedPrompt = recipe
+            ? recipe.enrich(prompt, { category, cityState, name, role })
+            : prompt;
+        return await client.createDocumentFromPrompt(targetCollection, {
+            ...rest,
+            prompt: enrichedPrompt,
+        });
+    });
+    tool('create_blog_post', 'Generate a complete blog post via AI and save it as a DRAFT. Targets the conventional "posts" collection — use `create_in_collection` if your site uses a different slug.', z.object({
+        ...aiContentInputBase,
+        collection: z
+            .string()
+            .optional()
+            .describe('Override the destination collection (default "posts").'),
+    }), async (args) => {
+        const { collection, ...rest } = args;
+        return await client.createDocumentFromPrompt(collection ?? 'posts', rest);
+    });
+    tool('create_case_study', 'Generate a complete case study via AI. Targets "case-studies" by default. Kept as a dedicated tool (rather than a `create_in_collection` template) because the client/industry framing is distinctive enough to be a top-level agent intent.', z.object({
+        ...aiContentInputBase,
+        clientName: z.string().optional().describe('Client / customer name to feature.'),
+        industry: z.string().optional(),
+        collection: z.string().optional(),
+    }), async (args) => {
+        const { collection, clientName, industry, prompt, ...rest } = args;
+        const enriched = [
+            prompt,
+            clientName ? `Client: ${clientName}.` : '',
+            industry ? `Industry: ${industry}.` : '',
+        ]
+            .filter(Boolean)
+            .join(' ');
+        return await client.createDocumentFromPrompt(collection ?? 'case-studies', {
+            ...rest,
+            prompt: enriched,
+        });
+    });
+    tool('list_collections', 'Discover available collections, their labels, type (`page`|`post`), and field summary. Primary source is the dedicated `/collections` discovery endpoint (sourced directly from the runtime CMS config so it stays accurate when the OpenAPI spec is incomplete). Falls back to the OpenAPI spec on older CMS servers that don\'t yet expose `/collections`. Returns `{ data: CollectionSummary[], source: "collections" | "openapi" }` — `data` is ALWAYS an array (the OpenAPI fallback is normalised to the same shape) so callers get a consistent contract regardless of which path responded.', z.object({}), async () => {
+        // Phase 7 PR F (audit stylistic note #2): the previous
+        // implementation relied solely on /openapi.json and silently
+        // returned an empty map whenever the OpenAPI generator drifted.
+        // We now prefer the dedicated /collections endpoint and only
+        // fall back to OpenAPI on a real HTTP 404.
+        //
+        // Review fix (PR #155, Bugbot + Copilot): use the typed
+        // `PrentaClientError.status` instead of grepping the message
+        // string — a message-text regex could misclassify a server's
+        // unrelated "page not found"-style 500/400 as a missing
+        // endpoint, and could also fail to recognise a real 404 whose
+        // message doesn't contain the literal phrase.
+        //
+        // Also normalised: the OpenAPI fallback now returns the same
+        // CollectionSummary[] shape as the primary path so `data` is
+        // always an array. Callers no longer need to branch on `source`
+        // to know whether they got an object map or an array.
+        try {
+            const res = await client.listCollections();
+            return { data: res.data, source: 'collections' };
+        }
+        catch (err) {
+            const status = err instanceof PrentaClientError ? err.status : 0;
+            if (status !== 404) {
+                throw err;
+            }
+            const spec = await client.getOpenApi();
+            const data = [];
+            if (spec?.paths) {
+                for (const path of Object.keys(spec.paths)) {
+                    const m = /^\/collections\/([^/]+)$/.exec(path);
+                    if (!m)
+                        continue;
+                    const slug = m[1];
+                    const schemaRef = spec.paths[path]?.post?.requestBody?.content?.['application/json']?.schema?.$ref;
+                    const schemaName = schemaRef?.split('/').pop();
+                    const properties = spec.components?.schemas?.[schemaName]?.properties ?? {};
+                    const required = new Set(spec.components?.schemas?.[schemaName]?.required ?? []);
+                    const fields = Object.entries(properties).map(([name, def]) => ({
+                        name,
+                        type: typeof def?.type === 'string' ? def.type : 'unknown',
+                        required: required.has(name),
+                    }));
+                    data.push({
+                        slug,
+                        // OpenAPI doesn't carry the singular/plural label split,
+                        // so we fall back to the slug for both. Callers that care
+                        // about labels should target a CMS server with the new
+                        // /collections endpoint.
+                        labels: { singular: slug, plural: slug },
+                        type: 'page',
+                        urlPrefix: slug,
+                        hidden: false,
+                        fieldCount: fields.length,
+                        fields,
+                    });
+                }
+            }
+            return { data, source: 'openapi' };
+        }
+    });
+    tool('resolve_url', 'Resolve a public URL path (e.g. "/about") to its CMS document.', z.object({ path: z.string() }), (args) => client.resolveUrl(args.path));
+    // ── Relationship resolver (WS-C C2) ───────────────────────────────────
+    //
+    // Relationship fields store a TARGET DOCUMENT ID, but humans (and AI
+    // prompts) think in slugs ("link the author to jane-doe"). Without these
+    // tools an agent has to guess IDs. The flow is:
+    //   1. get_relationship_fields(collection)  → which fields are relationships
+    //      and which collection(s) each points at (`relationTo`).
+    //   2. resolve_relationship(relationTo, slug) → the concrete document ID.
+    //   3. update_document(..., data: { <field>: <id> }) to wire it up.
+    // `list_relationship_targets` is the browse fallback when the exact slug
+    // isn't known.
+    tool('get_relationship_fields', "Inspect a collection's schema and return only the fields that reference other content — relationship fields (with their `relationTo` target collection(s) and `hasMany`), media fields, and select fields (with their `options`). Use this FIRST to discover which collection a relationship field points at before resolving a slug to an ID. Requires a CMS new enough to expose field metadata on `GET /collections`.", z.object({
+        collection: z.string().describe('Collection slug to inspect (e.g. "posts").'),
+    }), async (args) => {
+        let res;
+        try {
+            res = await client.listCollections();
+        }
+        catch (err) {
+            const status = err instanceof PrentaClientError ? err.status : 0;
+            if (status === 404) {
+                throw new Error('This CMS server does not expose the /collections discovery endpoint, so relationship field metadata is unavailable. Upgrade @prenta/core.');
+            }
+            throw err;
+        }
+        const col = (res.data ?? []).find((c) => c.slug === args.collection);
+        if (!col) {
+            const slugs = (res.data ?? []).map((c) => c.slug).join(', ');
+            throw new Error(`Unknown collection "${args.collection}". Known collections: ${slugs || '(none)'}.`);
+        }
+        const relational = (col.fields ?? []).filter((f) => ['relationship', 'media', 'select'].includes(f.type));
+        return { data: { collection: col.slug, fields: relational } };
+    });
+    tool('resolve_relationship', 'Resolve a human-friendly slug to a document ID within a collection — the value you store in a relationship field. `slug` is matched exactly against the document `slug` column (unique per collection), so this returns at most one document: `{ id, slug, title, status }`. Throws if no document matches (use `list_relationship_targets` to browse). Discover the target collection with `get_relationship_fields`.', z.object({
+        collection: z
+            .string()
+            .describe("Collection to search — typically a relationship field's `relationTo`."),
+        slug: z.string().min(1).describe('Exact document slug to resolve.'),
+    }), async (args) => {
+        const res = await client.listDocuments(args.collection, { slug: args.slug, pageSize: 2 });
+        const docs = res.data?.docs ?? [];
+        const match = docs.find((d) => d?.slug === args.slug) ?? docs[0];
+        if (!match) {
+            throw new Error(`No document in "${args.collection}" with slug "${args.slug}". Use list_relationship_targets({ collection: "${args.collection}" }) to browse candidates.`);
+        }
+        return {
+            data: { id: match.id, slug: match.slug, title: match.title, status: match.status },
+        };
+    });
+    tool('list_relationship_targets', 'List candidate documents to link to in a collection, projected to the fields you need to pick one: `{ id, slug, title, status }`. Use when the exact slug isn\'t known (the browse fallback for `resolve_relationship`). Filter by `status` (e.g. "PUBLISHED") and page through with `page` / `pageSize`. Returns `{ data: Target[], total, page, pageSize }`.', z.object({
+        collection: z.string().describe('Collection to list candidates from.'),
+        status: z
+            .string()
+            .optional()
+            .describe('Filter by status (e.g. "PUBLISHED") — usually you only link to published content.'),
+        page: z.number().int().min(1).optional(),
+        pageSize: z.number().int().min(1).max(100).optional(),
+    }), async (args) => {
+        const { collection, ...query } = args;
+        const res = await client.listDocuments(collection, query);
+        const env = res.data ?? { docs: [], total: 0, page: 1, pageSize: 0 };
+        const docs = (env.docs ?? []).map((d) => ({
+            id: d?.id,
+            slug: d?.slug,
+            title: d?.title,
+            status: d?.status,
+        }));
+        return { data: docs, total: env.total, page: env.page, pageSize: env.pageSize };
+    });
+    /** Resolve a menu by slug (exact, cheap) or, failing that, by document id. */
+    async function loadNav(ref) {
+        const bySlug = await client.listDocuments(NAVIGATION_COLLECTION, { slug: ref, pageSize: 1 });
+        let doc = bySlug.data?.docs?.find((d) => d?.slug === ref) ?? bySlug.data?.docs?.[0];
+        if (!doc) {
+            try {
+                const res = await client.getDocument(NAVIGATION_COLLECTION, ref);
+                doc = res.data;
+            }
+            catch (err) {
+                const status = err instanceof PrentaClientError ? err.status : 0;
+                if (status !== 404)
+                    throw err;
+            }
+        }
+        if (!doc) {
+            throw new Error(`Navigation menu "${ref}" not found (looked up by slug, then by id).`);
+        }
+        const data = (doc.data ?? {});
+        return {
+            id: doc.id,
+            name: (typeof data.name === 'string' && data.name) ||
+                (typeof doc.title === 'string' && doc.title) ||
+                doc.slug ||
+                doc.id,
+            slug: doc.slug ?? (typeof data.slug === 'string' ? data.slug : ''),
+            location: typeof data.location === 'string' ? data.location : undefined,
+            items: coerceNavItems(data.items),
+        };
+    }
+    /** Persist a new items tree onto a menu (merge — other fields are preserved). */
+    function saveNavItems(navId, items) {
+        return client.updateDocument(NAVIGATION_COLLECTION, navId, { items });
+    }
+    /** Resolve a published-page reference to a `{ label, url }` for a menu link. */
+    async function resolvePageLink(page) {
+        const collection = page.collection ?? 'pages';
+        let doc;
+        if (page.slug) {
+            const res = await client.listDocuments(collection, { slug: page.slug, pageSize: 1 });
+            doc = res.data?.docs?.find((d) => d?.slug === page.slug) ?? res.data?.docs?.[0];
+        }
+        else if (page.id) {
+            const res = await client.getDocument(collection, page.id);
+            doc = res.data;
+        }
+        if (!doc) {
+            throw new Error(`Could not resolve a ${collection} document from ${JSON.stringify(page)}. Use list_relationship_targets to find a valid slug/id.`);
+        }
+        const data = (doc.data ?? {});
+        const slug = doc.slug ?? (typeof data.slug === 'string' ? data.slug : '');
+        if (!slug)
+            throw new Error('Target document has no slug, so its URL cannot be derived.');
+        // Look up the collection's urlPrefix + type from discovery so the URL
+        // matches the site's real routing.
+        let urlPrefix;
+        let collectionType;
+        try {
+            const cols = await client.listCollections();
+            const col = cols.data?.find((c) => c.slug === collection);
+            urlPrefix = col?.urlPrefix;
+            collectionType = col?.type;
+        }
+        catch {
+            // Discovery unavailable (older server) — fall back to no prefix.
+        }
+        const isHome = (collectionType === undefined || collectionType === 'page') && slug === 'home';
+        const url = buildDocPath(urlPrefix, slug, isHome, data);
+        const label = (typeof doc.title === 'string' && doc.title) ||
+            (typeof data.title === 'string' && data.title) ||
+            (typeof data.name === 'string' && data.name) ||
+            slug;
+        return { label, url };
+    }
+    tool('list_navigations', 'List navigation menus, projected to `{ id, name, slug, location, itemCount }`. Menus are documents in the `navigations` collection (requires the navigation plugin).', z.object({
+        location: z
+            .string()
+            .optional()
+            .describe('Filter by placement (e.g. "header", "footer", "sidebar", "mobile").'),
+        page: z.number().int().min(1).optional(),
+        pageSize: z.number().int().min(1).max(100).optional(),
+    }), async (args) => {
+        const res = await client.listDocuments(NAVIGATION_COLLECTION, {
+            page: args.page,
+            pageSize: args.pageSize,
+        });
+        const env = res.data ?? { docs: [], total: 0, page: 1, pageSize: 0 };
+        let docs = (env.docs ?? []).map((d) => {
+            const data = (d?.data ?? {});
+            return {
+                id: d?.id,
+                name: (typeof data.name === 'string' && data.name) ||
+                    (typeof d?.title === 'string' && d.title) ||
+                    d?.slug ||
+                    d?.id,
+                slug: d?.slug ?? null,
+                location: typeof data.location === 'string' ? data.location : null,
+                itemCount: coerceNavItems(data.items).length,
+            };
+        });
+        if (args.location)
+            docs = docs.filter((d) => d.location === args.location);
+        return { data: docs, total: env.total, page: env.page, pageSize: env.pageSize };
+    });
+    tool('get_navigation', 'Fetch one navigation menu (by slug or document id) including its full link tree: `{ id, name, slug, location, items }`.', z.object({
+        navigation: z.string().describe('Menu slug (e.g. "main-navigation") or document id.'),
+    }), async (args) => ({ data: await loadNav(args.navigation) }));
+    tool('create_navigation', 'Create a navigation menu. Provide a `name`; `slug` is derived from it if omitted. Optionally seed `location` and an `items` tree (validated before save — items missing ids get them generated). Created PUBLISHED so it is live immediately.', z.object({
+        name: z.string().min(1).describe('Menu name, e.g. "Main Navigation".'),
+        slug: z.string().optional().describe('URL-safe slug; derived from name if omitted.'),
+        location: z
+            .enum(['header', 'footer', 'sidebar', 'mobile'])
+            .optional()
+            .describe('Where the menu renders.'),
+        items: z
+            .array(z.record(z.any()))
+            .optional()
+            .describe('Initial link tree (NavItem[]). Each item: { label, url, target?, children? }.'),
+        status: z.enum(['DRAFT', 'PUBLISHED']).optional(),
+    }), async (args) => {
+        const items = coerceNavItems(args.items ?? []);
+        const validation = validateNavTree(items);
+        if (!validation.valid) {
+            throw new Error(`Invalid navigation tree: ${validation.errors.join('; ')}`);
+        }
+        const slug = args.slug ??
+            args.name
+                .toLowerCase()
+                .trim()
+                .replace(/[^a-z0-9]+/g, '-')
+                .replace(/^-+|-+$/g, '');
+        return client.createDocument(NAVIGATION_COLLECTION, {
+            name: args.name,
+            title: args.name,
+            slug,
+            location: args.location,
+            items,
+            status: args.status ?? 'PUBLISHED',
+        });
+    });
+    tool('update_navigation', "Update a menu's metadata (`name`, `location`) and/or replace its entire `items` tree. To add/remove/reorder single links without replacing the whole tree, prefer add_navigation_item / remove_navigation_item / reorder_navigation_items.", z.object({
+        navigation: z.string().describe('Menu slug or document id.'),
+        name: z.string().min(1).optional(),
+        location: z.enum(['header', 'footer', 'sidebar', 'mobile']).optional(),
+        items: z
+            .array(z.record(z.any()))
+            .optional()
+            .describe('Replacement link tree (validated before save).'),
+    }), async (args) => {
+        const nav = await loadNav(args.navigation);
+        const patch = {};
+        if (args.name !== undefined) {
+            patch.name = args.name;
+            patch.title = args.name;
+        }
+        if (args.location !== undefined)
+            patch.location = args.location;
+        if (args.items !== undefined) {
+            const items = coerceNavItems(args.items);
+            const validation = validateNavTree(items);
+            if (!validation.valid) {
+                throw new Error(`Invalid navigation tree: ${validation.errors.join('; ')}`);
+            }
+            patch.items = items;
+        }
+        if (Object.keys(patch).length === 0) {
+            throw new Error('Nothing to update — provide at least one of name, location, or items.');
+        }
+        return client.updateDocument(NAVIGATION_COLLECTION, nav.id, patch);
+    });
+    tool('delete_navigation', 'Soft-delete a navigation menu. Destructive — confirm with the user first.', z.object({ navigation: z.string().describe('Menu slug or document id.') }), async (args) => {
+        const nav = await loadNav(args.navigation);
+        return client.deleteDocument(NAVIGATION_COLLECTION, nav.id);
+    });
+    tool('add_navigation_item', 'Add a link to a menu. Provide an explicit `{ label, url }`, OR a `page` reference ({ collection?, slug? | id? }) to link a published page — its URL and label are resolved for you ("link page X into menu Y"). Optionally nest under `parentId`. Returns the updated menu.', z.object({
+        navigation: z.string().describe('Menu slug or document id.'),
+        label: z.string().optional().describe('Link text (required unless `page` is given).'),
+        url: z.string().optional().describe('Link href (required unless `page` is given).'),
+        target: z.enum(['_blank', '_self']).optional(),
+        parentId: z
+            .string()
+            .optional()
+            .describe('Nest under this existing item id; omit for a top-level link.'),
+        page: z
+            .object({
+            collection: z.string().optional().describe('Defaults to "pages".'),
+            slug: z.string().optional(),
+            id: z.string().optional(),
+        })
+            .optional()
+            .describe('Link a published page by slug or id instead of a raw url.'),
+    }), async (args) => {
+        let label = args.label;
+        let url = args.url;
+        if (args.page) {
+            if (!args.page.slug && !args.page.id) {
+                throw new Error('`page` requires a `slug` or `id`.');
+            }
+            const resolved = await resolvePageLink(args.page);
+            url = url ?? resolved.url;
+            label = label ?? resolved.label;
+        }
+        if (typeof label !== 'string' || label.trim().length === 0) {
+            throw new Error('A non-empty `label` is required (or pass a `page` to derive it).');
+        }
+        if (typeof url !== 'string' || url.trim().length === 0) {
+            throw new Error('A non-empty `url` is required (or pass a `page` to derive it).');
+        }
+        const item = { id: genNavItemId(), label, url };
+        if (args.target)
+            item.target = args.target;
+        const nav = await loadNav(args.navigation);
+        const nextItems = addNavItem(nav.items, item, args.parentId ?? null);
+        const validation = validateNavTree(nextItems);
+        if (!validation.valid) {
+            throw new Error(`Resulting navigation tree is invalid: ${validation.errors.join('; ')}`);
+        }
+        await saveNavItems(nav.id, nextItems);
+        return { data: { navigation: nav.id, addedItemId: item.id, items: nextItems } };
+    });
+    tool('remove_navigation_item', 'Remove a single link (and its sub-tree) from a menu by item id. Returns the updated menu.', z.object({
+        navigation: z.string().describe('Menu slug or document id.'),
+        itemId: z.string().describe('The id of the item to remove.'),
+    }), async (args) => {
+        const nav = await loadNav(args.navigation);
+        const { items, removed } = removeNavItem(nav.items, args.itemId);
+        if (!removed) {
+            throw new Error(`Item "${args.itemId}" not found in menu "${nav.slug || nav.id}".`);
+        }
+        await saveNavItems(nav.id, items);
+        return { data: { navigation: nav.id, removedItemId: args.itemId, items } };
+    });
+    tool('reorder_navigation_items', "Reorder the links at one level of a menu. `orderedIds` must be a permutation of exactly the item ids at that level. Omit `parentId` to reorder the top level, or pass it to reorder a parent's children.", z.object({
+        navigation: z.string().describe('Menu slug or document id.'),
+        orderedIds: z.array(z.string()).min(1).describe('Item ids in the desired order.'),
+        parentId: z
+            .string()
+            .optional()
+            .describe("Reorder this parent's children; omit for the top level."),
+    }), async (args) => {
+        const nav = await loadNav(args.navigation);
+        const items = reorderNavLevel(nav.items, args.orderedIds, args.parentId ?? null);
+        await saveNavItems(nav.id, items);
+        return { data: { navigation: nav.id, items } };
+    });
+    tool('validate_navigation_tree', 'Validate a navigation tree WITHOUT saving. Pass an existing menu (`navigation`) or a candidate `items` array. Returns `{ valid, errors, warnings, stats }` — errors are hard problems (missing label/url, duplicate ids, exceeding maxDepth); warnings include placeholder "#"/empty urls and (when target checking runs) internal URLs with no published document. Target checking runs by default for stored menus; for candidate `items` pass `checkPublishedTargets: true` (uses the network). Soft warnings never set `valid` to false.', z.object({
+        navigation: z.string().optional().describe('Existing menu slug or id to validate.'),
+        items: z
+            .array(z.record(z.any()))
+            .optional()
+            .describe('Candidate items tree to validate instead of a stored menu.'),
+        maxDepth: z
+            .number()
+            .int()
+            .min(1)
+            .max(10)
+            .optional()
+            .describe('Max nesting depth (default 5).'),
+        checkPublishedTargets: z
+            .boolean()
+            .optional()
+            .describe('When true, also warn on internal URLs with no published page (network). Default: true for stored `navigation`, false for candidate `items`.'),
+    }), async (args) => {
+        let items = args.items;
+        const loadedFromStore = items === undefined;
+        if (items === undefined) {
+            if (!args.navigation) {
+                throw new Error('Provide either `navigation` (an existing menu) or `items` to validate.');
+            }
+            const nav = await loadNav(args.navigation);
+            items = nav.items;
+        }
+        const structural = validateNavTree(items, args.maxDepth ?? 5);
+        const checkTargets = args.checkPublishedTargets === true ||
+            (args.checkPublishedTargets !== false && loadedFromStore);
+        if (!checkTargets || !Array.isArray(items)) {
+            return { data: structural };
+        }
+        try {
+            const res = await client.validateNavigationTargets(items);
+            const targetWarnings = res.data?.warnings ?? [];
+            return {
+                data: {
+                    ...structural,
+                    warnings: [...structural.warnings, ...targetWarnings],
+                    unresolved: res.data?.unresolved ?? [],
+                },
+            };
+        }
+        catch (err) {
+            // Older CMS builds lack the endpoint — keep structural result.
+            if (err instanceof PrentaClientError && (err.status === 404 || err.status === 501)) {
+                return { data: structural };
+            }
+            throw err;
+        }
+    });
+    // ── Page sections (flat Page Editor model) ────────────────────────────
+    //
+    // These let an AI agent (e.g. running in Cursor / VS Code) BUILD a page
+    // section-by-section so the result becomes a REAL Page Editor page:
+    // previewable, manually editable, reorderable, savable, and publishable
+    // through the same model the visual editor uses — not disposable HTML.
+    //
+    // Workflow: discover types (`list_section_types`) → optionally inspect a
+    // schema (`get_section_schema`) → add/update sections on a page document
+    // (`add_page_section` / `update_page_section`) → reorder / remove →
+    // publish via the normal `update_document({ status: 'PUBLISHED' })`.
+    //
+    // Sections live in a page document's `data.sections` array; the page is a
+    // document in a collection that declares a `sections` JSON field (default
+    // slug "pages"). All mutations are server-side validated + audited.
+    tool('list_section_types', 'Discover the registered section types and their schemas. Returns each type\'s `id` (e.g. "hero", "text", "feature", "stats", "cta", "article-body", "quote", "author-bio", "related-posts", "gallery", "embed", "widget-embed"), `name`, `description`, `category`, `scope` (which surfaces it works on: "page" and/or "post"), the inspector `fields` schema (which content keys exist + which are required), and `defaultContent` / `defaultSettings`. Call this FIRST before building a page or a post template so you only use types that have a working renderer (no dead sections). Pass `scope` to narrow to one surface.', z.object({
+        scope: z
+            .enum(['page', 'post'])
+            .optional()
+            .describe('Limit to types usable on this surface: "page" for the Page Editor, "post" for posts + post templates. Omit for all types.'),
+    }), (args) => client.listSectionTypes(args.scope));
+    tool('get_section_schema', 'Fetch the schema for a SINGLE section type by id (e.g. "hero"). Returns the same shape as one entry of `list_section_types`. Use this to see exactly which `content` fields a type accepts and which are required before calling `add_page_section`. Throws if the id is not a registered type.', z.object({
+        sectionType: z
+            .string()
+            .describe('Section type id, e.g. "hero" | "text" | "feature" | "stats" | "cta".'),
+    }), async (args) => {
+        const res = await client.listSectionTypes();
+        const match = (res.data ?? []).find((t) => t?.id === args.sectionType);
+        if (!match) {
+            const ids = (res.data ?? [])
+                .map((t) => t?.id)
+                .filter(Boolean)
+                .join(', ');
+            throw new Error(`Unknown section type "${args.sectionType}". Registered types: ${ids || '(none)'}.`);
+        }
+        return { data: match };
+    });
+    tool('validate_section_content', 'Validate section content against its type schema WITHOUT persisting. Deterministic (no LLM). Returns `{ valid, errors, warnings }` where each issue is `{ sectionType, field?, message }`. Use to check AI-authored content before adding it, or to explain why a publish is blocked. An unknown `sectionType` is a hard error.', z.object({
+        sectionType: z.string().describe('Section type id to validate against.'),
+        content: z
+            .record(z.any())
+            .describe("The section content object (keys match the type's field schema)."),
+        settings: z.record(z.any()).optional().describe('Optional section settings object.'),
+    }), (args) => client.validateSection({
+        sectionType: args.sectionType,
+        content: args.content,
+        ...(args.settings !== undefined ? { settings: args.settings } : {}),
+    }));
+    tool('list_page_sections', 'List the ordered sections on a page document (`data.sections`). Each section is `{ id, sectionType, name, visible, content, settings }`. Use to inspect the current page before editing, or to discover section ids for `update_page_section` / `remove_page_section` / `reorder_page_sections`.', z.object({
+        id: z.string().describe('Page document ID.'),
+        collection: z
+            .string()
+            .optional()
+            .describe('Collection slug of the page. Defaults to "pages".'),
+    }), (args) => client.listPageSections(args.collection ?? 'pages', args.id));
+    tool('add_page_section', "Add a section to a page. The server seeds the type's registry defaults, shallow-merges your `content` / `settings`, generates an id, inserts at `position` (0-based; omit to append), and persists through the audited update path. Returns `{ section, sections, validation }` — inspect `validation` for any content issues (the section is still added so you can fix it with `update_page_section`). Only registered `sectionType`s are accepted (see `list_section_types`).", z.object({
+        id: z.string().describe('Page document ID.'),
+        sectionType: z
+            .string()
+            .describe('Registered section type id (see list_section_types), e.g. "hero".'),
+        collection: z.string().optional().describe('Page collection slug. Defaults to "pages".'),
+        name: z
+            .string()
+            .optional()
+            .describe('Editor-facing display name. Defaults to the type name.'),
+        internalLabel: z.string().optional().describe('Optional internal-only label for the team.'),
+        visible: z.boolean().optional().describe('Whether the section renders. Defaults to true.'),
+        content: z
+            .record(z.any())
+            .optional()
+            .describe('Content overrides (merged over the type defaults). Keys match the field schema.'),
+        settings: z
+            .record(z.any())
+            .optional()
+            .describe('Settings overrides (backgroundType, backgroundColor, paddingY, anchorId, cssClass).'),
+        position: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe('0-based insert index. Omit to append at the end.'),
+    }), (args) => {
+        const { id, collection, ...body } = args;
+        return client.addPageSection(collection ?? 'pages', id, body);
+    });
+    tool('update_page_section', 'Update a section in place. Only supplied fields change; `content` and `settings` are shallow-merged (so you can patch a single key). Use `visible` to show/hide, `name` / `internalLabel` to relabel. Returns `{ section, sections, validation }`. Pair with `list_page_sections` to discover the `sectionId`.', z.object({
+        id: z.string().describe('Page document ID.'),
+        sectionId: z.string().describe('Section id within the page (from list_page_sections).'),
+        collection: z.string().optional().describe('Page collection slug. Defaults to "pages".'),
+        content: z.record(z.any()).optional().describe('Content fields to merge in.'),
+        settings: z.record(z.any()).optional().describe('Settings fields to merge in.'),
+        name: z.string().optional(),
+        internalLabel: z.string().optional(),
+        visible: z.boolean().optional().describe('Show (true) or hide (false) the section.'),
+    }), (args) => {
+        const { id, sectionId, collection, ...body } = args;
+        return client.updatePageSection(collection ?? 'pages', id, sectionId, body);
+    });
+    tool('reorder_page_sections', "Reorder a page's sections to an explicit id order. Pass the full list of section ids in the desired top-to-bottom order; any ids you omit are appended at the end (defensive — sections are never dropped). Returns the new ordered section array.", z.object({
+        id: z.string().describe('Page document ID.'),
+        orderedIds: z.array(z.string()).describe('Section ids in the desired order (top to bottom).'),
+        collection: z.string().optional().describe('Page collection slug. Defaults to "pages".'),
+    }), (args) => client.reorderPageSections(args.collection ?? 'pages', args.id, args.orderedIds));
+    tool('remove_page_section', 'Remove a section from a page. Destructive (the section content is dropped from the draft) — confirm with the user for published pages. Returns the remaining sections.', z.object({
+        id: z.string().describe('Page document ID.'),
+        sectionId: z.string().describe('Section id to remove (from list_page_sections).'),
+        collection: z.string().optional().describe('Page collection slug. Defaults to "pages".'),
+    }), (args) => client.removePageSection(args.collection ?? 'pages', args.id, args.sectionId));
+    tool('toggle_page_section_visibility', 'Show or hide a section without deleting it. Hidden sections stay in the draft but are excluded from the published page and from publish-time validation. Pass `visible` explicitly. Returns `{ section, sections, validation }`.', z.object({
+        id: z.string().describe('Page document ID.'),
+        sectionId: z.string().describe('Section id to toggle.'),
+        visible: z.boolean().describe('true to show, false to hide.'),
+        collection: z.string().optional().describe('Page collection slug. Defaults to "pages".'),
+    }), (args) => client.updatePageSection(args.collection ?? 'pages', args.id, args.sectionId, {
+        visible: args.visible,
+    }));
+    // ── Post templates ────────────────────────────────────────────────────
+    //
+    // A post type's template (one per type) defines the design-driven header
+    // layout + the default section list that NEW posts of that type inherit.
+    // Workflow for an external agent driving a frontend design into the CMS:
+    //   1. list_section_types({ scope: 'post' }) → see post-usable sections
+    //   2. get_post_template({ postType }) → read the current template
+    //   3. save_post_template({ postType, header, sections }) → write the design
+    //   4. create posts of that type (they start from this template)
+    tool('get_post_template', "Read a post type's template: `{ postType, docId, header, sections }`. `header` is the design-driven header layout (`{ layout, showFeaturedImage, showExcerpt, showAuthor, showDate, showCategory, showReadingTime }`); `sections` is the default `PageSection[]` new posts inherit. Returns an unsaved default (centered header, empty sections, `docId: null`) when the type has no template yet. Call before `save_post_template` to avoid clobbering an existing design.", z.object({
+        postType: z
+            .string()
+            .describe('Post-type collection slug, e.g. "blog" | "case-studies" | "news".'),
+    }), (args) => client.getPostTemplate(args.postType));
+    tool('save_post_template', "Create or replace a post type's template (header layout + default sections). Use ONLY section types whose `scope` includes \"post\" (see `list_section_types({ scope: 'post' })`) — unknown/page-only types are dropped server-side. `header` keys are coerced to a full config (missing keys filled with defaults). Each section is `{ sectionType, name?, visible?, content?, settings? }` (ids are generated if omitted). This sets the starting layout for FUTURE posts of this type; it does not retroactively change existing posts. Returns the saved `{ postType, docId, header, sections }`.", z.object({
+        postType: z.string().describe('Post-type collection slug to write the template for.'),
+        header: z
+            .record(z.any())
+            .optional()
+            .describe('Header layout config: { layout: "centered"|"left"|"overlay", showFeaturedImage, showExcerpt, showAuthor, showDate, showCategory, showReadingTime }.'),
+        sections: z
+            .array(z.any())
+            .optional()
+            .describe('Ordered default sections (post-scoped types only): [{ sectionType, name?, visible?, content?, settings? }].'),
+    }), (args) => {
+        const body = {};
+        if (args.header !== undefined)
+            body.header = args.header;
+        if (args.sections !== undefined)
+            body.sections = args.sections;
+        return client.savePostTemplate(args.postType, body);
+    });
+    // ── AI quality pass (Slice F) ─────────────────────────────────────────
+    //
+    // Both tools are deterministic — they do not call any LLM. They run the
+    // built-in scoring functions plus structural / link-graph analysis, so
+    // they're cheap enough that agents can call them on every edit cycle.
+    // Phase 7 PR F (audit stylistic note #3): split `audit_document` into
+    // two explicit tools so the agent picks the right mode at the tool
+    // boundary instead of constructing a half-filled `{collection?, id?,
+    // body?, title?, ...}` blob and discovering the server's "must
+    // provide either (collection,id) or body" rule the hard way.
+    //
+    // Both tools forward to the same `/ai/audit-document` endpoint; the
+    // split is purely a UX improvement for agents.
+    tool('audit_document_by_id', 'Run the composite content quality audit (SEO + readability + accessibility + freshness) against a stored document. Returns a letter grade, 0–100 per-dimension scores, and a prioritized list of actionable issues. Optional override fields let the agent audit a hypothetical mutation of the stored document (e.g. "score this doc IF I changed the metaTitle to X") without persisting. Use `audit_inline_content` for ad-hoc text that is not yet stored.', z.object({
+        collection: z.string().describe('Collection slug of the stored document.'),
+        id: z.string().describe('Document ID.'),
+        // Optional overrides forwarded to /ai/audit-document. The server
+        // accepts these on the stored-doc path too — they let the agent
+        // run "what-if" audits without committing changes. Removing them
+        // (as we initially did in PR F) would silently regress that
+        // capability for any tool consumer that relied on it.
+        title: z.string().optional().describe('Override the stored title for this audit only.'),
+        metaTitle: z.string().optional(),
+        metaDescription: z.string().optional(),
+        targetKeyword: z.string().optional(),
+        url: z.string().optional(),
+        headings: z.array(z.string()).optional(),
+        contentType: z
+            .string()
+            .optional()
+            .describe('Content type for freshness scoring: news, blog, tutorial, documentation, evergreen.'),
+    }), (args) => client.auditDocument(args));
+    tool('audit_inline_content', 'Run the composite content quality audit against ad-hoc text that is NOT (yet) a stored document — useful for previewing a draft before saving, or auditing user-supplied content. Pass `title` + `body` at minimum. Use `audit_document_by_id` to audit content that already lives in the CMS.', z.object({
+        title: z.string().describe('Document title (required for SEO scoring).'),
+        body: z.string().describe('Body / main content text.'),
+        metaTitle: z.string().optional(),
+        metaDescription: z.string().optional(),
+        targetKeyword: z.string().optional(),
+        url: z.string().optional(),
+        headings: z.array(z.string()).optional(),
+        contentType: z
+            .string()
+            .optional()
+            .describe('Content type for freshness scoring: news, blog, tutorial, documentation, evergreen.'),
+    }), (args) => client.auditDocument(args));
+    tool('coauthor_text', 'Inline AI co-author. Transform a chunk of text via one of four actions: rewrite (with optional style/tone), expand (lengthen with optional instructions), compress (shorten, optionally to a target length), or proofread (returns corrected text + list of changes).', z.object({
+        action: z
+            .enum(['rewrite', 'expand', 'compress', 'proofread'])
+            .describe('Which transformation to apply.'),
+        text: z.string().describe('Text to transform.'),
+        style: z.string().optional().describe('Style hint for rewrite (e.g. "formal", "casual").'),
+        tone: z
+            .string()
+            .optional()
+            .describe('Tone hint for rewrite (e.g. "friendly", "authoritative").'),
+        instructions: z.string().optional().describe('Free-form expansion instructions.'),
+        targetLength: z
+            .number()
+            .int()
+            .min(50)
+            .max(20000)
+            .optional()
+            .describe('Approximate character target for compress.'),
+        collectionSlug: z.string().optional(),
+        targetAudience: z.string().optional(),
+    }), (args) => client.coauthor(args));
+    tool('suggest_internal_links', 'Scan published CMS documents for phrases the supplied content could link to, returning ranked anchor-text + target-URL suggestions. Use to enrich a draft with relevant internal links before publish.', z.object({
+        content: z.string().describe('Body text to analyze for link opportunities.'),
+        collection: z
+            .string()
+            .optional()
+            .describe('Restrict candidates to a single collection (e.g. "services").'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe('Max suggestions to return. Defaults to 10.'),
+        excludeId: z
+            .string()
+            .optional()
+            .describe('Document ID to exclude (typically the doc being edited).'),
+    }), (args) => client.suggestInternalLinks(args));
+    // ── Per-document SEO analysis (Phase 7 MCP-parity, PR C) ───────────────
+    //
+    // Five read-only tools that wrap the existing GET /seo/<scope>/:documentId
+    // endpoints. All are deterministic — no LLM calls. Cheap enough for an
+    // agent to invoke as part of a "publish-readiness check" pipeline.
+    tool('seo_analyze_document', 'Run a deterministic SEO content analysis against a stored document. Returns checks for title length, meta description, headings, focus keyphrase, content length, internal/external link counts, and an overall score. Pair with audit_document for the broader SEO + readability + a11y + freshness audit.', z.object({
+        documentId: z.string().describe('Document ID to analyze.'),
+    }), (args) => client.seoAnalyzeDocument(args.documentId));
+    tool('seo_readability_score', 'Compute a Flesch-Kincaid reading-ease score and grade level for a document body. Returns wordCount, sentenceCount, avgSentenceLength, syllablesPerWord, and qualitative bands (easy / medium / hard). Use to spot drafts that are too dense or too sparse for the target audience.', z.object({
+        documentId: z.string().describe('Document ID whose body should be scored.'),
+    }), (args) => client.seoReadability(args.documentId));
+    tool('seo_internal_link_targets', 'Suggest up to 10 published documents that this document could link TO, based on shared title keywords. Use when you want link suggestions rooted in a SPECIFIC stored document. For content-rooted suggestions on raw text (e.g. a freshly drafted body), use suggest_internal_links instead.', z.object({
+        documentId: z
+            .string()
+            .describe('Document ID — the source page that should gain outbound links.'),
+    }), (args) => client.seoInternalLinks(args.documentId));
+    tool('seo_meta_preview', 'Build the resolved meta-tag preview for a document: title, description, canonical, OG (title/description/image/type/site_name/published_time/modified_time), Twitter card tags, and robots directives (resolved against per-page overrides and site-level defaults). Use to verify what search engines and social platforms will see before publish.', z.object({
+        documentId: z.string().describe('Document ID whose meta tags should be previewed.'),
+    }), (args) => client.seoMetaPreview(args.documentId));
+    tool('seo_schema_graph', 'Build the Schema.org JSON-LD graph for a document. Returns the @context + @graph array with WebSite, WebPage, and (for posts) Article nodes wired together via @id references. Drop the result into a <script type="application/ld+json"> tag, or use it to verify what structured data the site emits today.', z.object({
+        documentId: z.string().describe('Document ID whose JSON-LD graph should be built.'),
+    }), (args) => client.seoSchemaGraph(args.documentId));
+    return tools;
+}
+//# sourceMappingURL=tools.js.map