@wootsup/yt-builder-mcp 1.10.0 → 1.12.0

package/dist/tools/navigation/index.js

@@ -0,0 +1,14 @@
+/**
+ * Navigation — tool barrel (proxy-mode arm).
+ *
+ *   yootheme_builder_navigation
+ *      → GET /navigation — the site's menus as a parent -> children tree,
+ *        each item carrying `page_role` + (when derivable for free)
+ *        `target_page`. Optional `menu` narrows to one menu by name.
+ *
+ * READ-ONLY; routed via the read-only advanced gateway, NOT first-class.
+ *
+ * @license MIT
+ */
+export { buildNavigationTools } from './builders.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/navigation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/navigation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/tools/navigation/schemas.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Navigation — zod input/output schema for `yootheme_builder_navigation`.
+ *
+ * T-C4 (mega-push plan 2026-07-24-02, customer P1.4). The proxy-mode arm of
+ * the Navigation Tree feature — the site's menus (WP nav menus / Joomla
+ * menus) as a parent -> children TREE, mirroring the WordPress REST
+ * controller ({@see \WootsUp\BuilderMcp\LocalContent\NavigationController})
+ * 1:1:
+ *
+ *   yootheme_builder_navigation → GET /navigation
+ *
+ * Each menu item node is a RECURSIVE tree ({id, title, url, parent_id, type,
+ * target_page, page_role, children}) — modelled as a free
+ * `z.record(z.string(), z.unknown())` (mirrors
+ * `LOCAL_CONTENT_READ_OUTPUT_SCHEMA.items`'s heterogeneous rows) rather than
+ * a `z.lazy()` self-referential schema: there is no precedent in this
+ * codebase's zod4 `z.toJSONSchema()` catalog pipeline for a recursive shape,
+ * and a menu's nesting depth is unbounded by design. The concrete per-node
+ * shape is documented here + in the shared PHP
+ * {@see \WootsUp\BuilderMcp\LocalContent\MenuTreeBuilder} /
+ * {@see \WootsUp\BuilderMcp\LocalContent\LocalContentProjection::menuItem()}.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+/**
+ * One MENU's already-nested tree. `items` is a list of recursive tree nodes:
+ * `{id: number, title: string, url: string|null, parent_id: number|null,
+ * type: string|null, target_page: string|null, page_role: string,
+ * children: <same shape>[]}`.
+ */
+export declare const NAVIGATION_MENU_SCHEMA: z.ZodObject<{
+    menu_id: z.ZodNullable<z.ZodNumber>;
+    menu_name: z.ZodString;
+    item_count: z.ZodNumber;
+    items: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const NAVIGATION_OUTPUT_SCHEMA: z.ZodObject<{
+    menus: z.ZodArray<z.ZodObject<{
+        menu_id: z.ZodNullable<z.ZodNumber>;
+        menu_name: z.ZodString;
+        item_count: z.ZodNumber;
+        items: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/tools/navigation/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/tools/navigation/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;iBAKjC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;iBAEnC,CAAC"}

package/dist/tools/navigation/schemas.js

@@ -0,0 +1,41 @@
+/**
+ * Navigation — zod input/output schema for `yootheme_builder_navigation`.
+ *
+ * T-C4 (mega-push plan 2026-07-24-02, customer P1.4). The proxy-mode arm of
+ * the Navigation Tree feature — the site's menus (WP nav menus / Joomla
+ * menus) as a parent -> children TREE, mirroring the WordPress REST
+ * controller ({@see \WootsUp\BuilderMcp\LocalContent\NavigationController})
+ * 1:1:
+ *
+ *   yootheme_builder_navigation → GET /navigation
+ *
+ * Each menu item node is a RECURSIVE tree ({id, title, url, parent_id, type,
+ * target_page, page_role, children}) — modelled as a free
+ * `z.record(z.string(), z.unknown())` (mirrors
+ * `LOCAL_CONTENT_READ_OUTPUT_SCHEMA.items`'s heterogeneous rows) rather than
+ * a `z.lazy()` self-referential schema: there is no precedent in this
+ * codebase's zod4 `z.toJSONSchema()` catalog pipeline for a recursive shape,
+ * and a menu's nesting depth is unbounded by design. The concrete per-node
+ * shape is documented here + in the shared PHP
+ * {@see \WootsUp\BuilderMcp\LocalContent\MenuTreeBuilder} /
+ * {@see \WootsUp\BuilderMcp\LocalContent\LocalContentProjection::menuItem()}.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+/**
+ * One MENU's already-nested tree. `items` is a list of recursive tree nodes:
+ * `{id: number, title: string, url: string|null, parent_id: number|null,
+ * type: string|null, target_page: string|null, page_role: string,
+ * children: <same shape>[]}`.
+ */
+export const NAVIGATION_MENU_SCHEMA = z.object({
+    menu_id: z.number().nullable(),
+    menu_name: z.string(),
+    item_count: z.number(),
+    items: z.array(z.record(z.string(), z.unknown())),
+});
+export const NAVIGATION_OUTPUT_SCHEMA = z.object({
+    menus: z.array(NAVIGATION_MENU_SCHEMA),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/tools/navigation/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/tools/navigation/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;CACpD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC;CACzC,CAAC,CAAC"}

package/dist/tools/pages/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/tools/pages/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAY7D,OAAO,EAOH,KAAK,iBAAiB,EACzB,MAAM,oBAAoB,CAAC;AAkD5B;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,GAAG,aAAa,CAMhB;AAyCD,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CAigB9E"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/tools/pages/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAa7D,OAAO,EAOH,KAAK,iBAAiB,EACzB,MAAM,oBAAoB,CAAC;AAwD5B;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,GAAG,aAAa,CAMhB;AAyCD,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CA8pB9E"}

package/dist/tools/pages/builders.js

@@ -14,13 +14,14 @@
  */
 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, INCLUDE_META_SCHEMA, POST_ID, RESOLVE_URL, SITE_ID_SCHEMA, TEMPLATE_ID, TEMPLATE_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 { handleHeaderTransparencySet, HEADER_TRANSPARENCY_SET_INPUT, } from './header-transparency.js';
+import { handleGetEtag, handleHeadingOutline, 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';
+import { ETAG_OUTPUT_SCHEMA, HEADING_OUTLINE_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
@@ -80,12 +81,12 @@ export function buildPagesTools(pool) {
             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). ' +
+                'serves_context_kind, serves_context_ids, page_role 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.',
+                'with `max_chars`.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 fields: FIELDS,
@@ -103,8 +104,10 @@ 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").'),
                 max_chars: MAX_CHARS,
+                include_meta: INCLUDE_META_SCHEMA,
             },
             outputSchema: PAGES_LIST_OUTPUT_SCHEMA,
             annotations: readOnly('List Pages'),
@@ -112,14 +115,24 @@ export function buildPagesTools(pool) {
         }),
         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 on a customer site —
+            // 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` (numeric post/article id), or `url`. For ' +
-                'dynamize/bind prefer `mode:"bindings_only"` (binding skeleton, no style ' +
-                'props). Default `mode:"full"` returns nested `{layout, etag}`; `flat:true` ' +
-                'gives a depth-first `{elements:[...]}` array (with `fields[]`). A repeated ' +
-                'unchanged read auto-skips (`force:true` re-fetches). `max_chars` bounds the ' +
-                'text; a clipped read returns `next_cursor` (pass back as `cursor`) to page ' +
-                'the rest. Operates on the default site unless site_id is provided.',
+                '(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).',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 // G-A (Track-C URL→layout): three interchangeable addressing modes
@@ -154,7 +167,7 @@ export function buildPagesTools(pool) {
                 flat: FLAT,
                 fields: FIELDS,
                 max_chars: MAX_CHARS,
-                // B7 (Glöckle continuation cursor): resume a clipped full/
+                // B7 (customer 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.
@@ -175,8 +188,7 @@ export function buildPagesTools(pool) {
             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.',
+                'or `url`. `fields[]` slims each node; `max_chars` bounds output.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 // G-A (Track-C URL→layout): three interchangeable addressing modes.
@@ -185,6 +197,7 @@ export function buildPagesTools(pool) {
                 url: RESOLVE_URL,
                 fields: FIELDS,
                 max_chars: MAX_CHARS,
+                include_meta: INCLUDE_META_SCHEMA,
             },
             outputSchema: SCHEMA_OUTPUT_SCHEMA,
             annotations: readOnly('Get Page Schema'),
@@ -202,9 +215,8 @@ export function buildPagesTools(pool) {
                 '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. Returns {template_id, post_id, type, ' +
-                'frontend_url, context, resolved_via}. ' +
-                'Operates on the default site unless site_id is provided.',
+                'include-child-categories), not a generic one. Or a `target`. Returns {template_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'),
@@ -212,13 +224,12 @@ export function buildPagesTools(pool) {
         }),
         defineTool({
             name: 'yootheme_builder_get_etag',
-            description: 'Get the current ETag (state revision) for the YOOtheme builder. ' +
-                'Returns sha256+revision string used for optimistic locking on writes. ' +
-                'Pass the returned value back as `etag` on any write tool (page_save, page_publish, ' +
-                'element_add, element_update_settings, element_clone, element_move, element_delete). ' +
-                'The server returns HTTP 412 if the ETag has changed since you read it. ' +
-                'Keywords: get etag, current etag, state revision, optimistic lock, version stamp. ' +
-                'Operates on the default site unless site_id is provided.',
+            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.',
             inputSchema: { site_id: SITE_ID_SCHEMA },
             outputSchema: ETAG_OUTPUT_SCHEMA,
             annotations: readOnly('Get ETag'),
@@ -227,17 +238,58 @@ export function buildPagesTools(pool) {
         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 ' +
+                '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. ' +
+                'pulling element_list or page_get_layout. Pass `include_nodes:true` for a ' +
+                '`content_nodes` per-node breakdown (status/effective_visible/headings/alts), ' +
+                'pageable via `limit`/`cursor`. Pass ' +
+                '`template_ids:[...]` for a batch: response carries `summaries` + ' +
+                '`not_found`. ' +
                 // 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 },
+                'Example: yootheme_builder_template_summary({ template_id: "default" }).',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                template_id: TEMPLATE_ID.optional().describe('Template ID (e.g. "default"). Provide this OR `template_ids` (batch) - ' +
+                    'exactly one, not both. Use yootheme_builder_pages_list to discover.'),
+                // T-C5 (mega-push plan 2026-07-24-02, customer P1.5): batch mode -
+                // one REST round-trip for N templates instead of N calls.
+                template_ids: z
+                    .array(z.string().min(1))
+                    .min(1)
+                    .optional()
+                    .describe('Batch of template IDs (2+) - one call instead of N. Provide this OR ' +
+                    '`template_id` (single) - exactly one, not both. Response carries ' +
+                    '`summaries` (keyed by id) + `not_found`.'),
+                // T-E2 (mega-push plan 2026-07-24-02, Thomas-Entscheid C):
+                // content_nodes is opt-in - omit for the compact aggregate-only
+                // shape, pass true to also get the per-node breakdown.
+                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).'),
+                // T-C5: page content_nodes when include_nodes:true (same
+                // limit/cursor contract as pages_list/element_list).
+                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)),
@@ -250,19 +302,19 @@ export function buildPagesTools(pool) {
         // 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 machine-executable fix_hints (missing/multiple h1, empty/thin ' +
-                'pages, missing image alt, duplicate layouts, title collisions, non-pretty ' +
-                'URLs, stale content, dead anchors). Filter with `types`/`checks`. Disclaimer: ' +
-                'SEO-plugin meta (title/description/OG) NOT covered. Drill in via ' +
-                "template_summary; fix one page at a time via each finding's fix_hint. " +
-                '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: supply template_id+path from the ' +
+                'locator). Covers h1/headings, thin pages, image alt, duplicate layouts, title ' +
+                'collisions, non-pretty URLs, dead anchors. Only active (non-disabled) nodes ' +
+                'produce findings. A site sweep caps hits/page, drops content_snippet; `target` ' +
+                'scopes to ONE page for the full set (cap 100). Filter with `types`/`checks`. ' +
+                'Disclaimer: 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 ───────────
+        // ─── F5 + N5 (customer 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
@@ -273,21 +325,23 @@ export function buildPagesTools(pool) {
         // template_id OR url (exactly one).
         defineTool({
             name: 'yootheme_builder_render_preview',
-            description: 'Render-check a saved template over the authenticated channel — does it ' +
-                'actually render, with how many items, or is it blank? Address by ' +
-                '`template_id` (from pages_list) OR `url` (resolved for you). Returns ' +
-                '{rendered, item_count, empty, error?, cache_purge_hint}; with `expect`, also ' +
-                '{matched, snippet}. Use AFTER a page_save / element_bind_source to catch a ' +
-                'silently-empty live page (a bad binding "saves" then renders blank); the ' +
-                'swallowed YOOtheme render error is surfaced in `error`. Read-only — renders ' +
-                'without persisting. Operates on the default site unless site_id is provided.',
+            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.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
-                // Exactly one of template_id / url — mirrors page_get_layout's
-                // TEMPLATE_ID_OPTIONAL + url addressing (resolveEffectiveTemplateId).
+                // 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,
                 url: RESOLVE_URL,
-                // Glöckle HANDOFF-6 #4: optional substring the rendered HTML must
+                // customer 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
@@ -295,7 +349,9 @@ export function buildPagesTools(pool) {
                     .min(1)
                     .optional()
                     .describe('Optional substring to find in the rendered HTML (e.g. a headline you ' +
-                    'just bound). When set, the response adds `matched` (bool) + ' +
+                    'just bound). Matched CASE-SENSITIVELY against the RAW, un-decoded ' +
+                    'response markup — pass raw HTML, not HTML-escaped text (search for ' +
+                    '"<h1", not "&lt;h1"). When set, the response adds `matched` (bool) + ' +
                     '`snippet` (≈200-char window, or null) — confirm an edit reached ' +
                     'the render in one call.'),
             },
@@ -303,16 +359,48 @@ export function buildPagesTools(pool) {
             annotations: readOnly('Render Preview'),
             handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handleRenderPreview(client, rest), site)),
         }),
+        // ─── T-A5 (heading_outline tool, mega-push plan 2026-07-24-02) ────
+        // L2 (advanced_read): a real, doc-order H1-H6 outline of ONE
+        // template attributed to its source element, plus the alt-status of
+        // every image. Deliberately NOT in ESSENTIAL_TOOLS — `readOnly()`
+        // routes it into the advanced_read gateway automatically, same as
+        // pages_audit/layout_query.
+        defineTool({
+            name: 'yootheme_builder_heading_outline',
+            description: 'A real, doc-order H1-H6 outline of ONE template: each heading with its TEXT ' +
+                'and the source element that carries it (`element_type`/`path`), plus the ' +
+                'alt-status of every image (including images inside html/text/code raw markup). ' +
+                'Read-only STRUCTURE inspection, not findings; use yootheme_builder_pages_audit ' +
+                'for severity-sorted SEO findings across the whole site. Returns ' +
+                '{outline, images, h1_count, has_level_skip, images_missing_alt}. Address by ' +
+                '`template_id` (from pages_list or pages_resolve).',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                template_id: TEMPLATE_ID,
+                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.'),
+            },
+            outputSchema: HEADING_OUTLINE_OUTPUT_SCHEMA,
+            annotations: readOnly('Heading Outline'),
+            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handleHeadingOutline(client, rest), site)),
+        }),
         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` — NOT the full ' +
-                'template node page_get_layout returns (rejected 422, would blank the page). ' +
-                'Validated + ETag-locked; on reject nothing persists. An unrenderable layout is ' +
-                'refused PRE-WRITE (422). `dry_run:true` preflights; the success response carries ' +
-                '`previous_layout` for 1-call rollback. Omit `layout` to re-run transforms only. ' +
-                'ETag optional (412 on conflict; else last-write-wins). ' +
-                'Operates on the default site unless site_id is provided.',
+                '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).',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 template_id: TEMPLATE_ID,
@@ -323,11 +411,13 @@ export function buildPagesTools(pool) {
                     .record(z.string(), z.unknown())
                     .optional()
                     .describe('Optional whole YT layout-node object — the INNER tree ' +
-                    '{type:"layout",children:[...]}, NOT the full template node ' +
-                    'page_get_layout returns (passing that is rejected as a double-nest). ' +
-                    'Replaces the template tree atomically. Validated + ETag-locked. ' +
-                    'Omit to just re-run save-transforms.'),
-                // U3/F3 (Glöckle HANDOFF-4): optional render preflight.
+                    '{type:"layout",children:[...]}, i.e. page_get_layout\'s `.layout` ' +
+                    '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 (customer HANDOFF-4): optional render preflight.
                 dry_run: z
                     .boolean()
                     .optional()
@@ -357,9 +447,11 @@ export function buildPagesTools(pool) {
         defineTool({
             name: 'yootheme_builder_page_publish',
             description: 'Publish a template — persist state, flush YT + WP caches, snapshot the ' +
-                'published-state ETag. ETag optional — when provided, 412 on conflict; when ' +
-                'omitted, last-write-wins. Recommended for collaborative edits. ' +
-                'Operates on the default site unless site_id is provided.',
+                '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.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 template_id: TEMPLATE_ID,
@@ -386,24 +478,23 @@ export function buildPagesTools(pool) {
                 locale: localeForSite(site),
             }))),
         }),
-        // ─── N3 (Glöckle HANDOFF-5) — template_set_type ───────────────
+        // ─── N3 (customer 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.
+        // `single-example_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.
+            // N3 (customer 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", "single-gloeckle_faq" ' +
-                '→ "single-gloeckle_help"). Returns {type, previous_type, new_etag} — ' +
-                'previous_type is the read of the prior assignment, folded in. THEME ' +
-                'templates only: a page:/article: layout is refused (422). ETag req. ' +
-                'Operates on the default site unless site_id is provided.',
+                '"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.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 template_id: TEMPLATE_ID,
@@ -412,12 +503,23 @@ export function buildPagesTools(pool) {
                     .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.
+                dry_run: z
+                    .boolean()
+                    .optional()
+                    .describe('Preflight ONLY. When true, validate the re-type (authz + ETag ' +
+                    'lock + 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 ' +
+                    'written, so preview first. Nothing is written (etag == new_etag); ' +
+                    'reversible anytime by re-calling with the returned previous_type.'),
             },
             outputSchema: TEMPLATE_SET_TYPE_OUTPUT_SCHEMA,
             annotations: mutating('Set Template Type'),
@@ -439,8 +541,7 @@ export function buildPagesTools(pool) {
                 '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.',
+                'at it — pass menu_item, else frontend_url may 404.',
             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.
@@ -465,10 +566,9 @@ export function buildPagesTools(pool) {
                 '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 (Played/Next/Later) dynamizes in ONE ' +
+                '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`. Requires page.title. ' +
-                'Operates on the default site unless site_id is provided.',
+                'key by "<subquery>.<leaf>". Returns page + `summary`. Preview with dry_run:true.',
             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
@@ -481,13 +581,45 @@ export function buildPagesTools(pool) {
                 locale: localeForSite(site),
             }))),
         }),
+        // ─── Task 5 (transparent-header plan) — header_transparency_set ───
+        // L2 (advanced): inspect + repair the three `header_transparent*`
+        // props on the section that actually governs the site header. NOT an
+        // L1 essential — it is the remediation for ONE specific
+        // misconfiguration, reached from a `header-contrast-*` finding's
+        // fix_hint or from an explicit customer request, not a hot path. The
+        // tool budget (~40 in `tools/list`) is spent on the workflow spine.
+        defineTool({
+            name: 'yootheme_builder_header_transparency_set',
+            description: 
+            // ≤600 chars (catalog constraint). Every clause is a behaviour
+            // an agent gets WRONG without it — see the behavior-truth pins.
+            'Inspect + repair the transparent header (nav over the hero). Always targets ' +
+                'the FIRST section — YOOtheme reads these props there only; later ones are ' +
+                'silently dead. dry_run defaults TRUE: returns current state, the ' +
+                'theme-declared --uk-inverse, risk_class, confidence, recommendation, ' +
+                'would_change. mode:"auto" writes the theme-declared colour; over a hero ' +
+                'image/video it writes NO colour and says to LOOK. mode:"explicit" refuses a ' +
+                'colour contradicting the theme (409) unless acknowledge_contrast_risk. ' +
+                'transparent:false is always allowed.',
+            inputSchema: HEADER_TRANSPARENCY_SET_INPUT,
+            // No outputSchema: the payload is a rich diagnosis object whose
+            // `changes` map is keyed by whichever props moved — a strict
+            // structuredContent schema would either be permissive to the point
+            // of uselessness or reject a legitimate response.
+            annotations: mutating('Set Header Transparency'),
+            handler: async ({ site_id, ...rest }, extra) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_header_transparency_set', async (client, site) => withRenderContext(withSiteMeta(await handleHeaderTransparencySet(client, rest, extra), site), buildRenderContext({
+                siteUrl: site.url,
+                parentTemplateId: rest.template_id,
+                locale: localeForSite(site),
+            }))),
+        }),
         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.',
+                'force_deleted, bumped etag.',
             inputSchema: { site_id: SITE_ID_SCHEMA, ...PAGES_DELETE_INPUT },
             outputSchema: PAGES_DELETE_OUTPUT_SCHEMA,
             // A page/article delete (force:true = PERMANENT, non-idempotent) is