@wootsup/yt-builder-mcp 1.11.0 → 2.0.0

package/dist/tools/pages/builders.js

@@ -1,91 +1,30 @@
-/**
- * Page-tool builders — pure `defineTool` factory list.
- *
- * Split out of `src/tools/pages.ts` (Round-2 R2-A2-CRIT1). Handler
- * bodies live in `./handlers-read.ts` (pages_list, page_get_layout,
- * page_get_schema, get_etag, template_summary) and `./handlers-write.ts`
- * (page_save, page_publish, pages_create, pages_delete — 3-phase
- * progress contract).
- *
- * Surface: 9 page-level tools (pre-C4: 7; v1.2 C4 added pages_create +
- * pages_delete wrapping POST /pages and DELETE /pages/{id}).
- *
- * @license MIT
- */
 import { z } from 'zod';
-import { withSiteRetry, withWriteSiteRetry } from '../pool-resolve-helper.js';
-import { ETAG as ETAG_STRICT, POST_ID, RESOLVE_URL, SITE_ID_SCHEMA, TEMPLATE_ID, TEMPLATE_ID_OPTIONAL, } from '../shared-schemas.js';
+import { ETAG as ETAG_STRICT, ETAG_PREVIEW_OPTIONAL, INCLUDE_META_SCHEMA, RESOLVE_URL, SITE_ID_SCHEMA, LAYOUT_ID, LAYOUT_ID_OPTIONAL, } from '../shared-schemas.js';
 import { FIELDS, FLAT, MAX_CHARS } from '../sparse-fields.js';
-import { creating, defineTool, destructive, mutating, readOnly, withSiteMeta, } from '../tool-builder.js';
-import { handlePagesAudit } from './handlers-audit.js';
-import { handleGetEtag, handlePageGetLayout, handlePageGetSchema, handlePagesList, handlePagesResolve, handleRenderPreview, handleTemplateSummary, } from './handlers-read.js';
-import { handlePageDynamize, handlePagePublish, handlePagesCreate, handlePagesDelete, handlePageSave, handleTemplateSetType, TEMPLATE_SET_TYPE_OUTPUT_SCHEMA, } from './handlers-write.js';
-import { ETAG_OUTPUT_SCHEMA, PAGE_DYNAMIZE_INPUT, PAGES_AUDIT_INPUT, PAGES_AUDIT_OUTPUT_SCHEMA, PAGES_CREATE_INPUT, PAGES_DELETE_INPUT, PAGES_DELETE_OUTPUT_SCHEMA, PAGES_LIST_OUTPUT_SCHEMA, PAGES_RESOLVE_INPUT, PAGES_RESOLVE_OUTPUT_SCHEMA, RENDER_PREVIEW_OUTPUT_SCHEMA, SCHEMA_OUTPUT_SCHEMA, TEMPLATE_SUMMARY_OUTPUT_SCHEMA, } from './schemas.js';
-// F-14: page-level save/publish accept OPTIONAL ETag (no precondition lock
-// at template level — element/binding mutations REQUIRE one via the strict
-// ETAG in shared-schemas.ts). Schema and description now agree: optional
-// here, recommended for safety. When provided, 412 Precondition Failed is
-// raised on stale snapshots; when omitted, the save proceeds unconditionally.
-const ETAG = z
-    .string()
-    .optional()
-    .describe('Optimistic-lock ETag (from yootheme_builder_get_etag). ' +
-    'Optional; when provided, optimistic-lock is enforced (412 on conflict). ' +
-    'When omitted, last-write-wins applies. Recommended for collaborative edits.');
-/**
- * Build the {@link RenderContext} from the data reachable in a page
- * builder. Pure: no I/O, no `any`. Missing `parentTemplateId` / `locale`
- * collapse to `null`.
- */
-export function buildRenderContext(input) {
-    return {
-        parent_template_id: input.parentTemplateId ?? null,
-        locale: input.locale ?? null,
-        site_url: input.siteUrl,
-    };
-}
-/**
- * Best-effort locale extraction from a resolved site. The registry does
- * not (yet) carry an explicit locale, so we read it from the platform
- * descriptor when present; otherwise `null` (the consumer-stable
- * "unknown" value). Kept narrow + guarded so this stays `any`-free.
- */
-function localeForSite(site) {
-    const platform = site.platform;
-    if (typeof platform === 'object' && platform !== null && 'locale' in platform) {
-        const value = platform.locale;
-        if (typeof value === 'string' && value !== '') {
-            return value;
-        }
-    }
-    return null;
-}
-/**
- * Stamp a {@link RenderContext} into a tool result's free-form
- * result-level `_meta` (next to the site-meta `withSiteMeta` adds).
- * Never touches `structuredContent` — that stays schema-pure so it keeps
- * validating against the tool's `outputSchema`. Pure: returns a new
- * result, does not mutate the input.
- */
-function withRenderContext(result, ctx) {
-    const base = result._meta;
-    const mergedMeta = base !== undefined && base !== null && typeof base === 'object'
-        ? { ...base, render_context: ctx }
-        : { render_context: ctx };
-    return { ...result, _meta: mergedMeta };
-}
-export function buildPagesTools(pool) {
+import { creating, defineTool, destructive, mutating, readOnly, } from '../tool-builder.js';
+import { HEADER_TRANSPARENCY_SET_INPUT } from './header-transparency.js';
+import { PAGES_CREATE_OUTPUT_SCHEMA, PAGE_GENERATE_DYNAMIC_OUTPUT_SCHEMA, PAGE_PUBLISH_OUTPUT_SCHEMA, PAGE_SAVE_OUTPUT_SCHEMA, TEMPLATE_SET_TYPE_OUTPUT_SCHEMA, } from './write-output-schemas.js';
+import { ETAG_OUTPUT_SCHEMA, HEADING_OUTLINE_OUTPUT_SCHEMA, PAGE_GENERATE_DYNAMIC_INPUT, PAGE_GET_LAYOUT_OUTPUT_SCHEMA, PAGES_AUDIT_INPUT, PAGES_AUDIT_OUTPUT_SCHEMA, PAGES_CREATE_INPUT, PAGES_DELETE_INPUT, PAGES_DELETE_OUTPUT_SCHEMA, PAGES_LIST_OUTPUT_SCHEMA, PAGES_RESOLVE_INPUT, PAGES_RESOLVE_OUTPUT_SCHEMA, PAGES_RESTORE_INPUT, PAGES_RESTORE_OUTPUT_SCHEMA, PAGES_SET_STATUS_INPUT, PAGES_SET_STATUS_OUTPUT_SCHEMA, RENDER_PREVIEW_OUTPUT_SCHEMA, TEMPLATE_SUMMARY_OUTPUT_SCHEMA, } from './schemas.js';
+export function buildPagesTools() {
     return [
         defineTool({
             name: 'yootheme_builder_pages_list',
-            description: 'List pages, templates, and layouts in the YOOtheme Pro builder ' +
-                '(id, label, type, elements_count, frontend_url, builder_url, ' +
-                'serves_context_kind, serves_context_ids per row). ' +
-                'CALL THIS FIRST to discover template IDs before page_get_layout / element_list / ' +
-                'page_get_schema. Paginates: up to `limit` rows (default 50) plus `total` and a ' +
-                '`next_cursor` (pass it back as `cursor`) when more remain. Filter with ' +
-                '`label_contains`. Slim rows with `fields:["id","label"]`; bound output ' +
-                'with `max_chars`. Operates on the default site unless site_id is provided.',
+            description: 'List pages, templates and layouts. Each row returns `kind` ' +
+                '(content | theme_template) plus serves_context_kind, serves_context_ids and ' +
+                'page_role — the template ROLE (WHICH objects it renders for), NOT a data ' +
+                'binding; for who-binds-what call layout_query with no layout_id. The ' +
+                'envelope returns `totals`. Call first for layout_id ' +
+                '(page_get_layout/element_list). ' +
+                '`type` = PAGE type, not element type (those filter on `element_type`). ' +
+                'Rows with a CMS status carry `visibility`: public | hidden | undetermined, never ' +
+                'empty. Reads STORED FIELDS only — status, plus WordPress password protection ' +
+                '(`hidden`, with the reason). It does NOT read the menu route, the access level, ' +
+                'or whether the permalink resolves, so Joomla rows stay `undetermined`; for THAT ' +
+                'verdict read `cms_visibility.findable_by_visitor` from pages_set_status / ' +
+                'page_publish — a different, per-page question. ' +
+                'Page contents (SEO/structure/links/modules): yootheme_builder_pages_audit. ' +
+                '`is_public_homepage` marks the one row served at / (the site front page); ' +
+                'no tool here moves it.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 fields: FIELDS,
@@ -103,60 +42,80 @@ export function buildPagesTools(pool) {
                 label_contains: z
                     .string()
                     .optional()
-                    .describe('Case-insensitive substring filter on the page label / id / type (e.g. "blog").'),
+                    .describe('Case-insensitive substring filter on the page label / id / type / frontend_url ' +
+                    '(also matches a slug or URL fragment, e.g. "blog" or "product-launch").'),
+                visibility: z
+                    .enum(['public', 'hidden', 'undetermined', 'no_cms_status'])
+                    .optional()
+                    .describe('Keep only rows whose `visibility` reads this word (no_cms_status = a theme ' +
+                    'template, which has none). `totals.visibility` counts all four over the ' +
+                    'same filtered set, so one call answers how many are hidden without ' +
+                    'reading the rows.'),
                 max_chars: MAX_CHARS,
+                sort: z
+                    .enum(['recent'])
+                    .optional()
+                    .describe('Order the rows. "recent" = most recently modified first (rows with no '
+                    + 'timestamp go last, never first). Omit to keep the default order '
+                    + '(theme templates, then per-page). The answer reports `sorted_over` '
+                    + '("all" or "this_page") so a paged result cannot read as a site-wide '
+                    + 'verdict.'),
+                include_meta: INCLUDE_META_SCHEMA,
             },
             outputSchema: PAGES_LIST_OUTPUT_SCHEMA,
             annotations: readOnly('List Pages'),
-            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handlePagesList(client, rest), site)),
         }),
         defineTool({
             name: 'yootheme_builder_page_get_layout',
-            // B-1 (SEO-routing fix, 2026-07-21): a generic "SEO audit" prompt
-            // from a COLD agent (no SKILL.md) otherwise loops this tool
-            // page-by-page into its Max-Iterations limit instead of the one-call
-            // pages_audit sweep (empirically confirmed at glöckle —
-            // followup_pages_audit_routing_generic_seo_request). The negative
-            // steer at the tail routes a whole-site audit to pages_audit (an L2
-            // read-only tool reached via yootheme_builder_advanced_read). The
-            // per-arg details dropped from this prose (bindings-skeleton / force
-            // / cursor semantics) already live in each param's own .describe().
-            description: 'Get the layout tree for one template — address it by `template_id` ' +
-                '(from pages_list), `post_id`, or `url`. `mode:"bindings_only"` for ' +
-                'dynamize/bind; `mode:"full"` (default) is nested `{layout, etag}`, ' +
-                '`flat:true` a depth-first array. `max_chars` bounds the text; a clipped ' +
-                'read returns `next_cursor` to page the rest. For a site-wide ' +
-                'SEO/structure/content/links audit (h1, image alt, thin pages, dead ' +
-                'links) do NOT loop this tool page-by-page — call ' +
-                'yootheme_builder_pages_audit (one sweep via ' +
-                'yootheme_builder_advanced_read). Operates on the default site unless ' +
-                'site_id is provided.',
+            description: 'Get the layout tree for one layout — address by `layout_id` or `url`. `mode:"bindings_only"` for dynamize/bind. Over `max_chars` whole ' +
+                'entries DROP (`truncated`+`omitted_count`; outline cuts its text) and NOTHING ' +
+                'pages the rest — no cursor in any mode. Narrow instead: `mode:"outline"` to ' +
+                'map, then element_list(root_path). ' +
+                'For a site-wide SEO/structure ' +
+                'audit do NOT loop this tool page-by-page — call yootheme_builder_pages_audit ' +
+                '(gateway-only). ' +
+                'For ONE narrow question (e.g. "where is the binding" or "which elements have ' +
+                'type X") this whole-template read is heavier than it needs to be — prefer ' +
+                'yootheme_builder_layout_query (gateway-only; has_binding/element_type/' +
+                'name_matches filters) or element_list with `root_path` to scope the walk.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
-                // G-A (Track-C URL→layout): three interchangeable addressing modes
-                // (exactly one required) so ONE call reaches a layout from a
-                // template_id, a bare numeric post/article id, or a pasted URL.
-                template_id: TEMPLATE_ID_OPTIONAL,
-                post_id: POST_ID,
+                layout_id: LAYOUT_ID_OPTIONAL,
                 url: RESOLVE_URL,
-                // F195 (P0): bindings_only returns the trimmed binding skeleton —
-                // recommended for dynamize/bind workflows (token-efficient).
-                // G1 (V3): outline returns a token-efficient INDENTED semantic
-                // outline — one line per node, cheapest way to orient in a large
-                // layout before reading specifics.
                 mode: z
                     .enum(['full', 'bindings_only', 'outline'])
                     .optional()
                     .describe('full (default) = whole nested layout; bindings_only = trimmed ' +
                     'binding skeleton (path/type/name/has_binding/source/children, ' +
-                    'no style props); outline = a token-efficient INDENTED text ' +
-                    'tree (one line per node: label ▸ type (bound: …) [sN]) for ' +
-                    'cheap orientation in a large layout. Each outline line carries ' +
-                    'a per-read handle [sN] AND the node’s real JSON-Pointer ' +
-                    'path; the handle is a short alias that is STATE-SCOPED — re-read ' +
-                    'after any mutation. Prefer bindings_only for dynamize/bind, ' +
-                    'outline to first map an unfamiliar template.'),
-                // F195 (P0): bypass the per-process unchanged-read dedup.
+                    'no style props). It compares each binding SOURCE against the ' +
+                    'sources this site registers: one that is gone carries ' +
+                    '`unresolved:true` and is named once in `unresolved_sources`, with ' +
+                    '`unresolved_sources_note` beside it saying what to repair. That ' +
+                    'list is present but EMPTY when nothing is dead, and replaced by ' +
+                    '`unresolved_sources_not_checked` when the registered-source list ' +
+                    'could not be read at all (then an unmarked binding means ' +
+                    'nothing). The field ' +
+                    'VALUES inside a source that DOES resolve are not compared: one ' +
+                    'naming a field that does not exist looks exactly like one that ' +
+                    'does here, and renders blank — element_get_binding names those ' +
+                    'for ONE element. pages_audit reports the same dead sources ' +
+                    'site-wide as dangling-source. outline = an INDENTED text ' +
+                    'tree (one line per node: label ▸ type (bound: …) [sN] ' +
+                    '/children/…) for cheap orientation in a large layout — the tree ' +
+                    'arrives on ' +
+                    'BOTH legs: as the TEXT content, and as `outline_text` in ' +
+                    'structuredContent, the same string under the same `max_chars` ' +
+                    'cap. structuredContent also carries a SUMMARY beside it ' +
+                    '(named_sections with a node_count each, total_elements, etag) ' +
+                    'to pick WHICH section to open; the raw per-node array is not ' +
+                    'sent on either leg — call element_list(root_path, depth) for ' +
+                    'one section\'s actual nodes. Each outline line ENDS in that ' +
+                    'node\'s `element_path` — the RELATIVE address element_update_settings, ' +
+                    'element_move and element_delete take — so you can edit straight from ' +
+                    'this read. The [sN] handle before it is a per-read alias, ' +
+                    'STATE-SCOPED: re-read after any mutation. Prefer bindings_only for ' +
+                    'dynamize/bind, outline to first map an unfamiliar template. Neither ' +
+                    'cheap mode can be combined with include_modules:true — see that argument.'),
                 force: z
                     .boolean()
                     .optional()
@@ -164,148 +123,145 @@ export function buildPagesTools(pool) {
                     'already read this session (bypasses the [unchanged] dedup).'),
                 flat: FLAT,
                 fields: FIELDS,
-                max_chars: MAX_CHARS,
-                // B7 (Glöckle continuation cursor): resume a clipped full/
-                // bindings_only text leg from its char offset. Opaque
-                // base64url `o:<n>` — the SAME offset-cursor contract
-                // pages_list/sources_list use. Omit to read from the start.
-                cursor: z
-                    .string()
+                max_chars: MAX_CHARS.describe('Cap (chars) on the text output. For `mode:"full"`/`"bindings_only"` both ' +
+                    'legs carry the same shortened payload, so structuredContent is not a way ' +
+                    'around the cap. For `mode:"outline"` this bounds ONLY the outline text ' +
+                    '(the text content and `outline_text` in structuredContent) — the summary ' +
+                    'beside it (`named_sections`, `total_elements`, `etag`) is never shortened ' +
+                    'and always arrives complete, whatever this cap did to the outline text. ' +
+                    'A `[site @ host] ` prefix is added AFTER, so delivery is ' +
+                    'longer by it. ' +
+                    'Raising it stops helping at the limit your own client puts on a single tool ' +
+                    'result, which this server cannot see. ' +
+                    'Out of range, the cap that actually applied comes back as `max_chars`.'),
+                include_modules: z
+                    .boolean()
                     .optional()
-                    .describe('Char-offset cursor from a clipped response\'s next_cursor — resumes ' +
-                    'the same dump at that offset (use with max_chars).'),
+                    .describe('mode:"full" (the default) ONLY — including with flat:true, which is a ' +
+                    'projection of mode:"full" and serves it. In ' +
+                    'mode:"outline"/"bindings_only" the ' +
+                    'server cannot serve it and the response says so in ' +
+                    '`modules_on_page_unavailable` (it does NOT mean the page has no ' +
+                    'modules). When true, attach `modules_on_page` — the widgets/modules that render ' +
+                    'on THIS page, split into `from_elements` (a module/module_position ' +
+                    'element placed directly in this page\'s own layout) and ' +
+                    '`from_positions` (a site-wide theme position — navbar/header/footer ' +
+                    '— rendering here with no element in this page\'s own layout at all). ' +
+                    'On Joomla, a site-wide module can still be assignment-EXCLUDED from ' +
+                    'this specific page (`except`); when that decision cannot be resolved ' +
+                    '(no menu item addresses this page, or more than one does), the row ' +
+                    'lands in `from_positions_undecidable` instead of being guessed in or ' +
+                    'out. A builder-content module (Joomla mod_yootheme_builder, WP ' +
+                    'builderwidget) carries its embedded layout SUMMARIZED here as ' +
+                    '`{omitted_for_size:true, node_count:N}`, not the full tree (B25) — ' +
+                    '`layout_root` still names its root type; for the actual content call ' +
+                    'local_content_read(kind:"modules") on that id. Default false — omit ' +
+                    'for the pre-existing response shape, unchanged.'),
             },
-            // No outputSchema: the response shape is a union (nested OR flat with
-            // optional projection) and the JSON-Pointer-keyed nested shape is
-            // structurally open-ended — modelling it precisely buys nothing here.
+            outputSchema: PAGE_GET_LAYOUT_OUTPUT_SCHEMA,
             annotations: readOnly('Get Page Layout'),
-            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handlePageGetLayout(client, rest), site)),
-        }),
-        defineTool({
-            name: 'yootheme_builder_page_get_schema',
-            description: 'Get the flat schema for a template — nodes with their JSON-Pointer ' +
-                'paths and element types. Lighter than page_get_layout, enough to locate ' +
-                'elements before editing. Address by `template_id` (pages_list), `post_id`, ' +
-                'or `url`. `fields[]` slims each node; `max_chars` bounds output. ' +
-                'Operates on the default site unless site_id is provided.',
-            inputSchema: {
-                site_id: SITE_ID_SCHEMA,
-                // G-A (Track-C URL→layout): three interchangeable addressing modes.
-                template_id: TEMPLATE_ID_OPTIONAL,
-                post_id: POST_ID,
-                url: RESOLVE_URL,
-                fields: FIELDS,
-                max_chars: MAX_CHARS,
-            },
-            outputSchema: SCHEMA_OUTPUT_SCHEMA,
-            annotations: readOnly('Get Page Schema'),
-            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handlePageGetSchema(client, rest), site)),
         }),
-        // ─── G-A (Track-C URL→layout) — pages_resolve ─────────────────
-        // THE core "paste a URL → reach a layout in ≤1 MCP call" tool. An
-        // agent handed only a public page URL resolves it to the per-page
-        // template_id that every read tool accepts. L1 essential so a cold
-        // agent reaches it directly (the whole point of the gap fix).
         defineTool({
             name: 'yootheme_builder_pages_resolve',
-            description: 'Resolve a public page/article/archive URL to the template_id that renders it — ' +
-                'paste a URL, get the layout id. Pretty/SEF permalinks resolve on WordPress AND ' +
-                'Joomla (incl. deep sub-category paths), not only raw ?option= URLs. A singular page ' +
-                '→ its per-page layout; a category/tag/CPT/author archive → the governing THEME ' +
-                'TEMPLATE, and for a category/term the SPECIFICALLY-ASSIGNED template (honoring ' +
-                'include-child-categories), not a generic one. Or a `target`. Returns {template_id, ' +
-                'post_id, type, frontend_url, context, resolved_via}. ' +
-                'Operates on the default site unless site_id is provided.',
+            description: 'Resolve a page/article/archive URL to the layout_id that renders it. SEF/pretty ' +
+                'permalinks resolve on both WordPress and Joomla. A category/term resolves to the ' +
+                'SPECIFICALLY-ASSIGNED template (honoring include-child-categories), not a generic ' +
+                'one. Returns {layout_id, post_id, type, frontend_url, context, resolved_via}.',
             inputSchema: { site_id: SITE_ID_SCHEMA, ...PAGES_RESOLVE_INPUT },
             outputSchema: PAGES_RESOLVE_OUTPUT_SCHEMA,
             annotations: readOnly('Resolve URL to Template'),
-            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handlePagesResolve(client, rest), site)),
         }),
         defineTool({
             name: 'yootheme_builder_get_etag',
-            description: 'Get the current ETag (state revision) for the YOOtheme builder. Returns a ' +
-                'sha256+revision string for optimistic locking. This ETag is SITE-WIDE: it covers ' +
-                'the ENTIRE builder state, so ANY write to ANY template (by any client) bumps it — ' +
-                'a 412 means the site state advanced, not necessarily that YOUR template changed. ' +
-                'It is the SAME token the read tools (page_get_layout, element_list) return in ' +
-                'their `etag`. Pass it back as `etag` on any write tool; on 412, re-read and retry. ' +
-                'Operates on the default site unless site_id is provided.',
+            description: 'Get the current site-wide ETag for optimistic locking. ANY write to ANY ' +
+                'template bumps it — a 412 means the site state advanced, not necessarily ' +
+                'your template. Same token page_get_layout/element_list return. Pass back as ' +
+                '`etag` on writes; on 412, re-read and retry. The ETag is SITE-wide, not per ' +
+                'template — that is why this tool takes no `layout_id`.',
             inputSchema: { site_id: SITE_ID_SCHEMA },
             outputSchema: ETAG_OUTPUT_SCHEMA,
             annotations: readOnly('Get ETag'),
-            handler: async ({ site_id }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handleGetEtag(client), site)),
         }),
         defineTool({
             name: 'yootheme_builder_template_summary',
-            description: 'Token-efficient template overview: element counts by type, binding ' +
-                'count, max nesting depth, and named landmark sections — computed ' +
-                'server-side in one call. Use this to grasp a large template before ' +
-                'pulling element_list or page_get_layout. ' +
-                'template_id only — resolve a URL/post first via pages_resolve. ' +
-                // F206 (P3): concrete first-call example. The Desktop client
-                // rejected the first guessed call because no example showed the
-                // exact arg shape (the whole yt-builder package used none, while
-                // apimapper's schema.ts does). Mirrors apimapper's 'Example:'
-                // pattern.
-                'Example: yootheme_builder_template_summary({ template_id: "default" }). ' +
-                'Operates on the default site unless site_id is provided.',
-            inputSchema: { site_id: SITE_ID_SCHEMA, template_id: TEMPLATE_ID },
+            description: 'Token-efficient template overview: element counts by type, bindings, max ' +
+                'depth, named sections — computed server-side in one call. Use before ' +
+                'element_list/page_get_layout on a large template. `include_nodes:true` adds a ' +
+                '`content_nodes` per-node breakdown (status/effective_visible/headings/alts), ' +
+                'pageable via `limit`/`cursor`. `layout_ids:[...]` batches several: response ' +
+                'carries `summaries`, `not_found` and `forbidden`. ' +
+                'Example: yootheme_builder_template_summary({ layout_id: "default" }).',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                layout_id: LAYOUT_ID.optional().describe('Which layout: "page:42", "article:12", "default", or a bare id (42). ' +
+                    'Provide this OR `layout_ids` (batch) - exactly one, not both. ' +
+                    'Use yootheme_builder_pages_list to discover.'),
+                layout_ids: z
+                    .array(z.string().min(1))
+                    .min(1)
+                    .optional()
+                    .describe('Batch of layout ids (2+) - one call instead of N. Provide this OR ' +
+                    '`layout_id` (single) - exactly one, not both. Response carries ' +
+                    '`summaries` (keyed by id), `not_found` and `forbidden`.'),
+                include_nodes: z
+                    .boolean()
+                    .optional()
+                    .describe('When true, also return `content_nodes` (per-node status/' +
+                    'effective_visible/hidden_on_mobile/headings/alts). Default false ' +
+                    '(the compact aggregate-only shape).'),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(200)
+                    .optional()
+                    .describe('Page size for `content_nodes` when `include_nodes:true` (1-200). ' +
+                    'Omit for the full unpaged list. The response carries `next_cursor` ' +
+                    'when more remain.'),
+                cursor: z
+                    .string()
+                    .optional()
+                    .describe('Opaque cursor from a previous response\'s next_cursor - resumes ' +
+                    'content_nodes pagination (use with include_nodes:true + limit).'),
+            },
             outputSchema: TEMPLATE_SUMMARY_OUTPUT_SCHEMA,
             annotations: readOnly('Template Summary'),
-            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handleTemplateSummary(client, rest), site)),
         }),
-        // ─── Task 6 (pages_audit design, 2026-07-19) — pages_audit ────
-        // L2 (advanced_read): a site-wide, severity-sorted SEO/structure/
-        // content/links sweep computed server-side in ONE call. Deliberately
-        // NOT in ESSENTIAL_TOOLS (keeps first-class tools/list at 41) —
-        // `readOnly()` annotation routes it into the `advanced_read` gateway
-        // automatically (annotation-driven, no allowlist edit).
         defineTool({
             name: 'yootheme_builder_pages_audit',
-            description: 'One-call site-wide SEO/structure/content/links audit — severity-sorted findings ' +
-                'with fix_hints (each a props FRAGMENT to merge, not a ready-made call — supply ' +
-                'template_id + path from the finding locator). Covers h1/headings, thin pages, ' +
-                'image alt, duplicate layouts, title collisions, non-pretty URLs, dead anchors. ' +
-                'A SITE-wide sweep caps hits/page and drops per-hit content_snippet; scope to ONE ' +
-                'page via `target` for the full set (cap 100). Filter with `types`/`checks`. ' +
-                'Disclaimer: SEO-plugin meta (title/description/OG) NOT covered. ' +
-                'Operates on the default site unless site_id is provided.',
+            description: 'One-call site-wide SEO / structure / content / links / design audit — ' +
+                'severity-sorted findings with fix_hints (a props fragment to merge). Covers ' +
+                'heading structure and accessibility (h1/heading-skip), image alt text, thin ' +
+                'content, duplicate layouts, title collisions, broken in-page anchor links ' +
+                '(same-page `#id` jumps only — no external link is ever fetched or resolved), ' +
+                'and design consistency (markup outside the UIkit design system, header/' +
+                'navigation contrast). Only active (non-disabled) nodes produce findings. ' +
+                '`target` scopes to ONE page for the full set. SEO-plugin meta (title/' +
+                'description/OG) NOT covered.',
             inputSchema: { site_id: SITE_ID_SCHEMA, ...PAGES_AUDIT_INPUT },
             outputSchema: PAGES_AUDIT_OUTPUT_SCHEMA,
             annotations: readOnly('Pages Audit'),
-            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handlePagesAudit(client, rest), site)),
         }),
-        // ─── F5 + N5 (Glöckle HANDOFF-4/5) — render_preview ───────────
-        // The authenticated post-write render HEALTHCHECK. READ-ONLY: renders
-        // the template server-side over the existing Bearer channel and reports
-        // {rendered, item_count, empty, error?} + a cache_purge_hint — answering
-        // "does my saved page actually render, with how many items?" where an
-        // external cURL 401s behind QA Basic-Auth. L2 (advanced-read) — reached
-        // via yootheme_builder_advanced_read, NOT in ESSENTIAL_TOOLS, so the L1
-        // token-baseline stays at 32. Addressing mirrors page_get_layout:
-        // template_id OR url (exactly one).
         defineTool({
             name: 'yootheme_builder_render_preview',
-            description: 'Render-check a saved template — does it actually render, with how many items, or ' +
-                'is it blank? Address by `template_id` (from pages_list), `post_id`, or `url` ' +
-                '(resolved for you) — exactly one. `item_count` = items yielded by the ' +
-                'template\'s dynamic/Multi-Items bindings (rendered repeat-source rows); 0 with ' +
-                'empty:true means a binding returned nothing. Returns {rendered, item_count, empty, ' +
-                'error?, cache_purge_hint}; with `expect`, also {matched, snippet}. Use AFTER a ' +
-                'save/bind to catch a silently-empty page. Read-only. ' +
-                'Operates on the default site unless site_id is provided.',
+            description: 'Render-check a SAVED layout. Address by ' +
+                '`layout_id` or `url`. rendered_item_wrapper_count counts the ' +
+                'repeat-item wrappers rendered, BOUND OR NOT, so a 0 is not evidence a ' +
+                'binding failed (per-source rows: `source_item_counts`). Distinct from ' +
+                'pages_list `elements_count` (all tree nodes). A source the registry cannot ' +
+                'resolve is named in `unresolved_sources`, not just a smaller count. Renders ' +
+                'ONLY the page\'s own layout tree, never the theme wrapper: a MISS with ' +
+                '`expect` proves nothing beyond the tree (adds {matched, snippet, ' +
+                'match_conclusive, match_note, mismatch_hints, stored_but_not_rendered — the ' +
+                'last names elements that DO store the text but rendered no rows}). A Joomla ' +
+                'module/module_position element sharpens this — EXCLUDED (fallback_used:true) ' +
+                'or silently empty (dropped_count:0) — but match_conclusive:false marks EVERY ' +
+                'inconclusive miss. Reports CMS status in `cms_status`/`cms_status_note` (absent ' +
+                'for a theme template); pages_set_status remains the tool that changes it.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
-                // WAVE-1 follow-up (a): render_preview threads the SAME three
-                // addressing modes page_get_layout uses (template_id | post_id |
-                // url, exactly one) — the handler already resolved post_id via
-                // resolveEffectiveTemplateId; this exposes it at the MCP boundary.
-                template_id: TEMPLATE_ID_OPTIONAL,
-                post_id: POST_ID,
+                layout_id: LAYOUT_ID_OPTIONAL,
                 url: RESOLVE_URL,
-                // Glöckle HANDOFF-6 #4: optional substring the rendered HTML must
-                // contain. When set, the response adds {matched, snippet} so "did
-                // my edit reach the render?" is answerable in one call.
                 expect: z
                     .string()
                     .min(1)
@@ -319,24 +275,56 @@ export function buildPagesTools(pool) {
             },
             outputSchema: RENDER_PREVIEW_OUTPUT_SCHEMA,
             annotations: readOnly('Render Preview'),
-            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handleRenderPreview(client, rest), site)),
+        }),
+        defineTool({
+            name: 'yootheme_builder_heading_outline',
+            description: 'A real, doc-order H1-H6 outline of ONE template, each heading with its source ' +
+                'element, plus alt-status of every image. Structure inspection, not findings — ' +
+                'use pages_audit for site-wide SEO findings. ' +
+                'One row per CARRIER: a container whose bound item repeats appears once, ' +
+                'while template_summary.heading_levels counts it once per rendered row.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                layout_id: LAYOUT_ID,
+                max_chars: MAX_CHARS,
+                mode: z
+                    .enum(['builder', 'rendered'])
+                    .optional()
+                    .describe('Outline source. "builder" (default) reads the saved layout tree: fast, ' +
+                    'but blind to module/widget output and anything a plugin injects only ' +
+                    'at render time. "rendered" renders the page first (via the SAME ' +
+                    'engine render_preview / pages_audit use) and reads the ACTUAL DOM - ' +
+                    'element_type is empty ("") in this mode, since there is no builder ' +
+                    'node to point at; locate a heading by its `path` (a synthetic ' +
+                    '"rendered:heading:N" marker) or the page\'s frontend_url instead. A ' +
+                    'Joomla page with module/module_position renders via a tolerant ' +
+                    'fallback (that subtree excluded) rather than failing; the response ' +
+                    'then carries render_fallback_used:true + render_dropped_count:N — ' +
+                    'treat h1_count/has_level_skip/the outline as possibly incomplete when ' +
+                    'that flag is true. A genuine render failure returns error:"render_failed".'),
+            },
+            outputSchema: HEADING_OUTLINE_OUTPUT_SCHEMA,
+            annotations: readOnly('Heading Outline'),
         }),
         defineTool({
             name: 'yootheme_builder_page_save',
-            description: 'Re-run save-transforms + flush caches. Optionally REPLACE the template tree by ' +
-                'passing the INNER {type:"layout",children:[...]} tree as `layout` — page_get_layout\'s ' +
-                '`.layout` child, NOT the whole response it returns (rejected 422, would blank the ' +
-                'page). Validated + ETag-locked; nothing persists on reject. Does NOT change CMS ' +
-                'post status — a draft stays invisible to visitors; set status via pages_create. ' +
-                '`dry_run:true` preflights; success carries `previous_layout` for rollback. ETag ' +
-                'optional (412 on conflict; else last-write-wins). ' +
-                'Operates on the default site unless site_id is provided.',
+            description: 'Re-run save-transforms + flush the plugin\'s own caches. Optional whole-tree ' +
+                'replace via `layout` — ' +
+                'the INNER {type:"layout",children:[...]} tree, NOT page_get_layout\'s whole ' +
+                'response (rejected 422). ' +
+                'THREE separate steps, and this is the first: (1) page_save replaces or ' +
+                're-normalises the stored tree — every write, element or whole-tree, runs the ' +
+                'same save-transforms; (2) page_publish snapshots the ETag and flushes them; ' +
+                '(3) pages_set_status decides whether a visitor may see the page at all. This ' +
+                'call does NOT do (2) or (3). ' +
+                'Response `previous_layout` is the tree right before THIS call, not before your ' +
+                'edits (element writes already landed) — identical to what you just wrote is normal ' +
+                'when the transforms change nothing. ' +
+                '`dry_run:true` preflights, no ETag. ETag on the save (428/412).',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
-                template_id: TEMPLATE_ID,
-                etag: ETAG,
-                // F85: optional whole-layout atomic replacement (ARTICLE/page
-                // templates + theme templates). Same shape as pages_create.layout.
+                layout_id: LAYOUT_ID,
+                etag: ETAG_PREVIEW_OPTIONAL.optional(),
                 layout: z
                     .record(z.string(), z.unknown())
                     .optional()
@@ -345,9 +333,9 @@ export function buildPagesTools(pool) {
                     'child, NOT the whole response it returns (passing that is rejected ' +
                     'as a double-nest). Replaces the template tree atomically. Validated ' +
                     '+ ETag-locked, BUT prop KEYS are NOT schema-validated on a whole-tree ' +
-                    'save — YT-Pro silently drops unknown keys; use element_update_settings ' +
-                    'for validated per-element edits. Omit to just re-run save-transforms.'),
-                // U3/F3 (Glöckle HANDOFF-4): optional render preflight.
+                    'save — an unknown key is stored as sent, not dropped and not reported ' +
+                    'here; element_update_settings keeps it too, but reports it back as ' +
+                    '`unknown_prop_keys`. Omit to just re-run save-transforms.'),
                 dry_run: z
                     .boolean()
                     .optional()
@@ -355,7 +343,6 @@ export function buildPagesTools(pool) {
                     'render dry-run and return a validation_report WITHOUT persisting ' +
                     '(no write, no cache flush, no ETag bump). Use to verify a binding ' +
                     'renders before it can blank the live page. Omit to actually save.'),
-                // Task 8 (design §7): opt-in advisory quick_check on save.
                 quick_check: z
                     .boolean()
                     .optional()
@@ -367,26 +354,62 @@ export function buildPagesTools(pool) {
                     'Advisory only — the save always succeeds. Site-wide checks ' +
                     '(duplicate-layout, title-collision) need pages_audit.'),
             },
+            outputSchema: PAGE_SAVE_OUTPUT_SCHEMA,
             annotations: mutating('Save Page'),
-            handler: async ({ site_id, ...rest }, extra) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_page_save', async (client, site) => withRenderContext(withSiteMeta(await handlePageSave(client, rest, extra), site), buildRenderContext({
-                siteUrl: site.url,
-                parentTemplateId: rest.template_id,
-                locale: localeForSite(site),
-            }))),
         }),
         defineTool({
             name: 'yootheme_builder_page_publish',
-            description: 'Publish a template — persist state, flush YT + WP caches, snapshot the ' +
-                'published-state ETag. YOOtheme templates already publish on save, so this is a ' +
-                'cache-flush + state-snapshot op. Neither publish nor save changes the CMS post ' +
-                'status — a draft page stays invisible to visitors; set status at creation via ' +
-                'pages_create/library_insert. ETag optional — when provided, 412 on conflict; when ' +
-                'omitted, last-write-wins. Operates on the default site unless site_id is provided.',
+            description: 'Publish a template\'s LAYOUT — persist state, flush the plugin\'s own caches ' +
+                '(a page-cache/CDN plugin is NOT purged: purge it yourself, then verify with ' +
+                'fetch_public_url), snapshot the ETag; ' +
+                '"publish" ALSO means the CMS post status, and this tool does not change that, ' +
+                'so a draft page stays invisible. ' +
+                'Step (2) of the three page_save describes; pages_set_status is step (3). ' +
+                'ETag required — 412 on conflict. ' +
+                'Answers `cms_visibility.findable_by_visitor`: can a visitor FIND this one page via ' +
+                'a navigation path? It reads the menu route AND the access level, which the ' +
+                'per-row `visibility` of pages_list does not. ' +
+                'Optional `cms_status` folds step (3) into this call for the common ' +
+                'build-it-and-make-it-live case; without it nothing about the CMS status changes.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
-                template_id: TEMPLATE_ID,
-                etag: ETAG,
-                // Task 8 (design §7): the publish QuickCheck is DEFAULT-ON.
+                layout_id: LAYOUT_ID,
+                etag: ETAG_STRICT,
+                cms_status: z
+                    .enum([
+                    'publish',
+                    'draft',
+                    'pending',
+                    'private',
+                    'future',
+                    'published',
+                    'unpublished',
+                    'archived',
+                ])
+                    .optional()
+                    .describe('Optional. Also set the CMS status in THIS call, so the common ' +
+                    '"build it and make it live" case is one call instead of three. Same ' +
+                    'words and same refusals as yootheme_builder_pages_set_status — ' +
+                    'WordPress publish/draft/pending/private/future, Joomla ' +
+                    'published/unpublished/archived; the other platform\'s word is refused ' +
+                    'and NOTHING is published. Needs a page:/article: template (a theme ' +
+                    'template has no single page). To trash or delete use ' +
+                    'yootheme_builder_pages_delete; no status value here removes anything. ' +
+                    'Omit to leave the CMS status untouched. ' +
+                    'The response carries `cms_status_applied` with the STORED status after ' +
+                    'the write, and `cms_visibility` then reflects the NEW status.'),
+                menu_item: z
+                    .union([z.boolean(), z.string().min(1).max(64)])
+                    .optional()
+                    .describe('Joomla only. Also create a SEF route for the article: true = the ' +
+                    'dedicated hidden menutype, a string picks the menutype ("mainmenu" is ' +
+                    'refused so generated routes never enter the site navigation). The ' +
+                    'article must end up published — pass cms_status:"published" here or ' +
+                    'publish it first; otherwise the call is refused rather than handing ' +
+                    'back a route to an unpublished article, whose url no visitor can ' +
+                    'open. Response carries `menu_item_id`. On WordPress this argument is ' +
+                    'REFUSED, never ignored: a WP page is served at its permalink as soon ' +
+                    'as its status is publish, so there is no route to create.'),
                 quick_check: z
                     .boolean()
                     .optional()
@@ -396,56 +419,38 @@ export function buildPagesTools(pool) {
                     'report for THIS page, with fix_hints, or `{clean:true}`. Set false to ' +
                     'OPT OUT (e.g. bulk publishes). Advisory only — publish ALWAYS ' +
                     'succeeds; findings never block it. Site-wide checks (duplicate-layout, ' +
-                    'title-collision) still need pages_audit.'),
+                    'title-collision) still need pages_audit. `render_check:{ok,worst,' +
+                    'findings}` rides next to `published` with the render verdict — ' +
+                    '`ok:false` names a QUALITY finding, not a failed publish: the ' +
+                    'publish above it already succeeded regardless.'),
             },
-            // Stream D3 T3: publish is idempotent — re-running on an
-            // unchanged template snapshots the same ETag and flushes
-            // the same caches. Matrix marks `idempotentHint:true`.
+            outputSchema: PAGE_PUBLISH_OUTPUT_SCHEMA,
             annotations: mutating('Publish Page'),
-            handler: async ({ site_id, ...rest }, extra) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_page_publish', async (client, site) => withRenderContext(withSiteMeta(await handlePagePublish(client, rest, extra), site), buildRenderContext({
-                siteUrl: site.url,
-                parentTemplateId: rest.template_id,
-                locale: localeForSite(site),
-            }))),
         }),
-        // ─── N3 (Glöckle HANDOFF-5) — template_set_type ───────────────
-        // L2 (advanced): set which archive/single a YOOtheme theme template
-        // is assigned to (the `templates.<id>.type` condition pages_list
-        // reads). The #1 missing step in a taxonomy/CPT-rename workflow —
-        // after categoryFaq→categoryHelp the `taxonomy-category_faq` /
-        // `single-gloeckle_faq` templates are orphaned and must be re-typed.
         defineTool({
             name: 'yootheme_builder_template_set_type',
-            description: 
-            // N3 (Glöckle HANDOFF-5) — archive/single TYPE reassignment.
-            'Reassign which archive/single a YOOtheme THEME template applies to — ' +
-                'set its `type` condition (the value pages_list shows) in ONE ETag-locked ' +
-                'write. Use after a taxonomy/CPT rename orphans a template (e.g. re-type ' +
-                '"taxonomy-category_faq" → "taxonomy-category_help"). Returns ' +
-                '{type, previous_type, new_etag}. Site-wide + immediate — preview with ' +
-                'dry_run:true, reversible via previous_type. ' +
-                'THEME templates only: page:/article: is refused (422). ETag req. ' +
-                'Operates on the default site unless site_id is provided.',
+            description: 'Reassign which archive/single a YOOtheme THEME template applies to — set its ' +
+                '`type` condition in ONE ETag-locked write. Use after a taxonomy/CPT rename ' +
+                'orphans a template. Site-wide + immediate — preview with dry_run:true, ' +
+                'reversible via previous_type. THEME templates only: page:/article: refused (422).',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
-                template_id: TEMPLATE_ID,
+                layout_id: LAYOUT_ID,
                 type: z
                     .string()
                     .min(1)
                     .describe('The new archive/single TYPE assignment (the `type` condition ' +
                     'pages_list surfaces), e.g. "taxonomy-category_help", ' +
-                    '"single-gloeckle_help", "archive-post", or the bare "template". ' +
+                    '"single-example_help", "archive-post", or the bare "template". ' +
                     'Read the current value via pages_list (the `type` column) or ' +
                     'GET the template first. `page`/`article` are NOT valid here.'),
-                // Required strict ETag (the re-type is a real mutation; the PHP
-                // controller enforces If-Match → 428 if omitted, 412 on stale).
-                etag: ETAG_STRICT,
-                // PAGES_LIBRARY_MEDIA-14: preflight the re-type without persisting.
+                etag: ETAG_PREVIEW_OPTIONAL.optional(),
                 dry_run: z
                     .boolean()
                     .optional()
                     .describe('Preflight ONLY. When true, validate the re-type (authz + ETag ' +
-                    'lock + theme-template-only + type validity + template-exists) ' +
+                    'staleness, though a missing ETag is fine on a preview + ' +
+                    'theme-template-only + type validity + template-exists) ' +
                     'and return {previous_type, would_change, dry_run:true} WITHOUT ' +
                     'persisting — the template TYPE assignment governs which items ' +
                     'render this layout SITE-WIDE and applies immediately once ' +
@@ -454,82 +459,91 @@ export function buildPagesTools(pool) {
             },
             outputSchema: TEMPLATE_SET_TYPE_OUTPUT_SCHEMA,
             annotations: mutating('Set Template Type'),
-            handler: async ({ site_id, ...rest }, extra) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_template_set_type', async (client, site) => withRenderContext(withSiteMeta(await handleTemplateSetType(client, rest, extra), site), buildRenderContext({
-                siteUrl: site.url,
-                parentTemplateId: rest.template_id,
-                locale: localeForSite(site),
-            }))),
         }),
-        // ─── C4 (v1.2) — pages_create + pages_delete ──────────────────
-        // First-class customer-facing page-level mutations. Both wrap
-        // Phase B REST endpoints (POST /pages, DELETE /pages/{id}) and
-        // are L1 essentials (see gateway/essentials.ts).
         defineTool({
             name: 'yootheme_builder_pages_create',
-            description: 'Create a page (WordPress) or article (Joomla 5/6) with a YOOtheme per-page ' +
-                'layout. Required: title. Optional: slug, status (default draft), published ' +
-                '(default false → live on true: WP publish / Joomla state 1), layout (JSON), ' +
-                'menu_item (Joomla SEF route), dry_run (preflight, no persist). Returns page_id ' +
-                '(WP) / article_id (Joomla), slug, template_id (page:{id} or article:{id}), etag, ' +
-                'warnings. Joomla: a published article has NO SEF route until a menu item points ' +
-                'at it — pass menu_item, else frontend_url may 404. ' +
-                'Operates on the default site unless site_id is provided.',
+            description: 'Create a page (WordPress) or article (Joomla 5/6) with a per-page layout. ' +
+                'Required: title. Optional: status (default draft), layout, menu_item, ' +
+                'dry_run (preflight, no persist). Joomla: a published article has NO SEF route ' +
+                'until a menu item points at it — pass menu_item for a navigable url. ' +
+                'Cannot make it the site front page: which page answers / is a CMS menu ' +
+                'setting this server never writes. pages_list marks the current one with ' +
+                'is_public_homepage.',
             inputSchema: { site_id: SITE_ID_SCHEMA, ...PAGES_CREATE_INPUT },
-            // No outputSchema: the response shape is a discriminated union
-            // (201 wet vs 200 dry-run). page_get_layout uses the same pattern.
-            annotations: mutating('Create Page'),
-            handler: async ({ site_id, ...rest }, extra) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_pages_create', async (client, site) => withRenderContext(withSiteMeta(await handlePagesCreate(client, rest, extra), site), buildRenderContext({
-                siteUrl: site.url,
-                // A new page has no caller-supplied parent
-                // template; null until the REST response carries
-                // one (kept stable rather than absent).
-                parentTemplateId: null,
-                locale: localeForSite(site),
-            }))),
+            outputSchema: PAGES_CREATE_OUTPUT_SCHEMA,
+            annotations: creating('Create Page'),
         }),
-        // ─── P-G (Goldstandard wave 3) — page_dynamize ────────────────
-        // THE one-call canonical path to dynamize an existing designed
-        // section. L1 essential: an agent must reach it directly INSTEAD
-        // of hand-editing layout JSON (the recipe is CODE, server-side).
         defineTool({
-            name: 'yootheme_builder_page_dynamize',
-            description: 'One-call way to dynamize a designed section: copies the layout ' +
-                'byte-identically and swaps only what you map. Use INSTEAD of ' +
-                'hand-editing JSON. Give a REFERENCE (section_name from ' +
-                'template_summary, or element_path) + list_source_name + a leaf_map ' +
-                '(original leaf field-name → flat flow field; #parent + tuned props kept). ' +
-                'A section with several source blocks dynamizes in ONE ' +
-                'call via source_map ({match, source_name, leaf_map?}[]). Sub-query panels: ' +
-                'key by "<subquery>.<leaf>". Returns page + `summary`. Preview with dry_run:true. ' +
-                'Operates on the default site unless site_id is provided.',
-            inputSchema: { site_id: SITE_ID_SCHEMA, ...PAGE_DYNAMIZE_INPUT },
-            // No outputSchema: the response is the create wire-shape (WP
-            // page_id / Joomla article_id discriminated union) plus the
-            // `summary` object — pages_create uses the same no-outputSchema
-            // pattern for its discriminated union.
-            annotations: creating('Dynamize Page'),
-            handler: async ({ site_id, ...rest }, extra) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_page_dynamize', async (client, site) => withRenderContext(withSiteMeta(await handlePageDynamize(client, rest, extra), site), buildRenderContext({
-                siteUrl: site.url,
-                parentTemplateId: null,
-                locale: localeForSite(site),
-            }))),
+            name: 'yootheme_builder_page_generate_dynamic',
+            description: 'Copies a designed section byte-identically into a NEW, unpublished, unlinked ' +
+                'page and swaps only what you map — it never edits the reference. Requires ' +
+                'output:"new_page" (today\'s only value; "in_place" is not yet available). Give ' +
+                'a REFERENCE (section_name or element_path) + list_source_name + a leaf_map. A ' +
+                'section with several source blocks dynamizes in ONE call via source_map. ' +
+                'Preview with dry_run:true (a would_change:false answer carries `reason`). Live ' +
+                'at once — stage hidden with element_set_status(status:false). The response ' +
+                'carries `cms_visibility.findable_by_visitor`: can a visitor FIND this one page ' +
+                'via a navigation path? It reads the menu route AND the access level, which the ' +
+                'per-row `visibility` of pages_list does not. ' +
+                'Cannot make it the site front page (a CMS menu setting).',
+            inputSchema: { site_id: SITE_ID_SCHEMA, ...PAGE_GENERATE_DYNAMIC_INPUT },
+            outputSchema: PAGE_GENERATE_DYNAMIC_OUTPUT_SCHEMA,
+            annotations: creating('Generate Dynamic Page'),
+        }),
+        defineTool({
+            name: 'yootheme_builder_header_transparency_set',
+            description: 'Inspect + repair the transparent header. Always targets the FIRST section — ' +
+                'later ones are silently dead. dry_run defaults TRUE: returns current state + ' +
+                'the theme-declared --uk-inverse, risk_class, recommendation. mode:"auto" writes ' +
+                'the theme-declared colour; over a hero image/video it writes NONE and says LOOK. ' +
+                'mode:"explicit" refuses a colour contradicting the theme (409) unless ' +
+                'acknowledge_contrast_risk. transparent:false is always allowed.',
+            inputSchema: HEADER_TRANSPARENCY_SET_INPUT,
+            annotations: mutating('Set Header Transparency'),
         }),
         defineTool({
             name: 'yootheme_builder_pages_delete',
-            description: 'Delete a page (WordPress) or article (Joomla 5/6) with its YOOtheme per-page ' +
-                'layout. Requires confirm:true (gate against accidental deletion). Default: trash ' +
-                '(recoverable). force:true: permanent delete. Refuses non-page/article types with ' +
-                '403 (Layer 9 defense). Returns deleted:true, page_id (WP) / article_id (Joomla), ' +
-                'force_deleted, bumped etag. Operates on the default site unless site_id is provided.',
+            description: 'Delete a page (WordPress) or article (Joomla 5/6). OMIT confirm to preview: ' +
+                'returns 200 with label, elements_count, what happens to media, and the intents ' +
+                'this page\'s state allows, and deletes nothing. confirm:true + an intent carries ' +
+                'it out. Already-trashed returns 200 {deleted:false, already_trashed:true}, ' +
+                'not an error.',
             inputSchema: { site_id: SITE_ID_SCHEMA, ...PAGES_DELETE_INPUT },
             outputSchema: PAGES_DELETE_OUTPUT_SCHEMA,
-            // A page/article delete (force:true = PERMANENT, non-idempotent) is
-            // destructive — annotate it so, matching yootheme_builder_element_delete
-            // and so an MCP host's destructive-approval gate fires (audit fix F9,
-            // 2026-07-16). The confirm:z.literal(true) guard already satisfies the
-            // destructive()+confirm contract.
             annotations: destructive('Delete Page'),
-            handler: async ({ site_id, ...rest }, extra) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_pages_delete', async (client, site) => withSiteMeta(await handlePagesDelete(client, rest, extra), site)),
+        }),
+        defineTool({
+            name: 'yootheme_builder_pages_set_status',
+            description: 'Change the CMS status of an EXISTING page (WordPress) or article (Joomla) — ' +
+                'keeps its id and URL. Step (3) of the three page_save describes. ' +
+                'Use YOUR platform\'s own words: WordPress publish, draft, ' +
+                'pending, private, future; Joomla published, unpublished, archived — the other ' +
+                'platform\'s word is refused (422). Status is RE-READ after the write. To trash ' +
+                'or delete use yootheme_builder_pages_delete; a page already IN the trash is ' +
+                'refused (409) — use yootheme_builder_pages_restore first. ' +
+                'The response carries `cms_visibility.findable_by_visitor`: can a visitor FIND ' +
+                'this one page via a navigation path? It reads the menu route AND the access ' +
+                'level, which the per-row `visibility` of pages_list does not.',
+            inputSchema: { site_id: SITE_ID_SCHEMA, ...PAGES_SET_STATUS_INPUT },
+            outputSchema: PAGES_SET_STATUS_OUTPUT_SCHEMA,
+            annotations: mutating('Set Page Status'),
+        }),
+        defineTool({
+            name: 'yootheme_builder_pages_restore',
+            description: 'Restore a TRASHED page (WordPress) or article (Joomla) — the one correct way ' +
+                'back (pages_set_status refuses a trashed page with 409 naming this tool). ' +
+                'WordPress: reinstates the EXACT pre-trash status (core defaults restores to ' +
+                'draft since 5.6) and attempts to reclaim the pre-trash slug — a hand-rolled ' +
+                'write leaves the "__trashed" suffix instead; a slug another page has since ' +
+                'taken comes back different — check the response\'s frontend_url. Joomla stores ' +
+                'no pre-trash status, so this can only set state to unpublished (visible to ' +
+                'editors, not visitors); call yootheme_builder_pages_set_status with ' +
+                'status:"published" afterwards to make it visible. Not currently trashed → ' +
+                'refused (409). Find a trashed id with ' +
+                'yootheme_builder_local_content_read({kind:"entities", status:"trash"}).',
+            inputSchema: { site_id: SITE_ID_SCHEMA, ...PAGES_RESTORE_INPUT },
+            outputSchema: PAGES_RESTORE_OUTPUT_SCHEMA,
+            annotations: creating('Restore Page'),
         }),
     ];
 }