@wootsup/yt-builder-mcp 1.10.0 → 1.12.0

package/dist/tools/pages/handlers-read.js

@@ -9,13 +9,26 @@
  */
 import { detailResult, tableResult } from '@getimo/mcp-toolkit';
 import { encodeTemplateId } from '../../client.js';
+import { RestError } from '../../errors.js';
 import { flattenLayout } from '../layout-flatten.js';
 import { PAGES_COMPACT_COLUMNS, PAGES_TABLE_COLUMNS, SCHEMA_COMPACT_COLUMNS, SCHEMA_TABLE_COLUMNS, buildEtagDetail, buildOutlineText, buildRenderPreviewDetail, buildSchemaRows, mapPageRow, } from '../format/pages-format.js';
 import { DEFAULT_FIELDS_PAGES_LIST, DEFAULT_FIELDS_SCHEMA, applyMaxChars, clipTextWindow, columnsFromFields, decodeOffsetCursor, encodeOffsetCursor, projectFields, projectedFieldsEcho, projectionFeedback, projectionWarning, } from '../sparse-fields.js';
 import { errorResult, jsonResult, structuredResult, } from '../tool-builder.js';
+import { TARGET_KEYS } from './schemas.js';
+import { appendTargetParams, malformedTargetError, normalizeTarget, serverTooOldError, TARGET_FAILURE_HINT, targetKeysOf, tooManyTargetsError, } from './target.js';
 // ─── pages_list ─────────────────────────────────────────────────────
 /** Default page size for pages_list when `limit` is omitted (B2). */
 const DEFAULT_PAGES_LIMIT = 50;
+/**
+ * SOURCES_BINDING-29 / DISCOVERY_AUDIT-18 — the STATIC pages_list field
+ * vocabulary. `mapPageRow` always emits the SAME key set on every row, so
+ * deriving it once from an empty-row projection gives the authoritative
+ * discoverable field list WITHOUT hard-coding a list that could drift from the
+ * mapper. Used to (a) validate a caller's `fields[]` against the real schema
+ * rather than against whatever rows a (possibly empty) result happened to carry,
+ * and (b) emit `available_fields` on every call. Sorted for a stable echo.
+ */
+const PAGES_LIST_KNOWN_FIELDS = Object.keys(mapPageRow({})).sort();
 /** Decode an offset cursor (`base64url("o:<n>")` or raw `o:<n>`) → offset, else 0. */
 function decodePagesCursor(cursor) {
     if (cursor === undefined || cursor === '')
@@ -35,14 +48,19 @@ function decodePagesCursor(cursor) {
 function encodePagesCursor(offset) {
     return Buffer.from(`o:${offset}`, 'utf8').toString('base64url');
 }
-/** Case-insensitive substring match across a page row's label / id / type. */
+/**
+ * Case-insensitive substring match across a page row's label / id / type /
+ * frontend_url. T-C2 (customer P1.2): frontend_url joined the haystack so a
+ * slug or URL fragment (e.g. "nkl-hauptspiel") matches even when it appears
+ * in none of label/id/type — mirrors PHP's `PageQuery::applyLabelFilter()`.
+ */
 function matchesPageFilter(row, needle) {
-    const hay = `${String(row.label ?? '')} ${String(row.id ?? '')} ${String(row.type ?? '')}`.toLowerCase();
+    const hay = `${String(row.label ?? '')} ${String(row.id ?? '')} ${String(row.type ?? '')} ${String(row.frontend_url ?? '')}`.toLowerCase();
     return hay.includes(needle);
 }
-export async function handlePagesList(client, { fields, limit, cursor, label_contains, max_chars, }) {
+export async function handlePagesList(client, { fields, limit, cursor, label_contains, max_chars, include_meta, }) {
     try {
-        // G-B (Glöckle 2026-06-26, P0): forward `limit`/`offset`/`filter` to the
+        // G-B (customer 2026-06-26, P0): forward `limit`/`offset`/`filter` to the
         // REST /pages endpoint so a site with hundreds of templates does not
         // serialize the full set every call (server-side pagination). The
         // server is BACKWARD-COMPATIBLE: with no params it returns the full set
@@ -66,7 +84,7 @@ export async function handlePagesList(client, { fields, limit, cursor, label_con
         let mapped = rawPages
             .filter((x) => x !== null && typeof x === 'object')
             .map(mapPageRow);
-        // B2 (Glöckle 2026-06-25) + G-B server-side fallback: a real site can
+        // B2 (customer 2026-06-25) + G-B server-side fallback: a real site can
         // have hundreds of templates. When the server already paged + filtered
         // (it echoes a `total`), the rows it returned ARE the page — do NOT
         // re-slice them. When the server ignored the params (no `total`, full
@@ -87,18 +105,40 @@ export async function handlePagesList(client, { fields, limit, cursor, label_con
         const nextCursor = nextOffset < total ? encodePagesCursor(nextOffset) : undefined;
         // B1: project the SLICE (text leg + structuredContent) when fields given.
         const items = projectFields(slice, fields, DEFAULT_FIELDS_PAGES_LIST);
-        const echo = projectedFieldsEcho(fields, DEFAULT_FIELDS_PAGES_LIST);
-        const feedback = projectionFeedback(slice, fields);
-        // F23 (2026-06-09): shared loud-warning helper.
-        const unknownNote = projectionWarning(feedback);
-        const useProjection = echo !== undefined && echo.length > 0;
-        const projectedColumns = useProjection ? columnsFromFields([...echo]) : undefined;
+        const hasExplicitFields = Array.isArray(fields) && fields.length > 0;
+        // SOURCES_BINDING-29: validate `fields[]` against the STATIC schema, not
+        // the returned rows — an EMPTY result set no longer makes every field
+        // look invalid (the "available: " with no fields bug). unknown = a
+        // requested field whose top-level segment is not a known key.
+        const unknownFields = hasExplicitFields
+            ? fields.filter((f) => !PAGES_LIST_KNOWN_FIELDS.includes(f.split('.')[0] ?? f))
+            : [];
+        // DISCOVERY_AUDIT-18: `available_fields` is the STATIC discoverable
+        // vocabulary, emitted on EVERY call (an empty page still tells the agent
+        // which fields exist). `projected_fields` reflects the keys ACTUALLY in
+        // the emitted rows — the full vocabulary in the default no-`fields` case,
+        // the requested subset otherwise (LAYOUT_READ-18: no longer the stale
+        // 5-key DEFAULT echo while rows carry 11).
+        const availableFields = [...PAGES_LIST_KNOWN_FIELDS];
+        const projectedFields = hasExplicitFields
+            ? [...fields]
+            : [...PAGES_LIST_KNOWN_FIELDS];
+        // SOURCES_BINDING-29: suppress the loud projection warning on an empty
+        // result (projection is moot) and when nothing is actually unknown.
+        const emitWarning = total > 0 && unknownFields.length > 0;
+        const unknownNote = emitWarning
+            ? ` (unknown projection fields ignored: ${unknownFields.join(', ')}` +
+                ` — available: ${availableFields.join(', ')})`
+            : '';
+        const useProjection = hasExplicitFields;
+        const projectedColumns = useProjection ? columnsFromFields([...fields]) : undefined;
         const pagedNote = total > slice.length ? ` of ${String(total)}${nextCursor !== undefined ? ', pass cursor for more' : ''}` : '';
         const toolkitResult = tableResult(useProjection ? items : slice, {
             columns: projectedColumns ?? [...PAGES_TABLE_COLUMNS],
             compactColumns: projectedColumns ?? [...PAGES_COMPACT_COLUMNS],
             header: (count) => `${String(count)}${pagedNote} pages${unknownNote}`,
             footer: 'Use yootheme_builder_page_get_schema <id> to inspect.',
+            includeMeta: include_meta,
         });
         return structuredResult(applyMaxChars(toolkitResult, max_chars), {
             items,
@@ -106,12 +146,13 @@ export async function handlePagesList(client, { fields, limit, cursor, label_con
             returned: slice.length,
             ...(nextCursor !== undefined ? { next_cursor: nextCursor } : {}),
             ...(typeof data.etag === 'string' ? { etag: data.etag } : {}),
-            ...(echo !== undefined ? { projected_fields: [...echo] } : {}),
-            ...(feedback !== undefined ? {
-                available_fields: [...feedback.available_fields],
-                unknown_fields: [...feedback.unknown_fields],
-                ...(unknownNote.trim() !== '' ? { projection_warning: unknownNote.trim() } : {}),
-            } : {}),
+            projected_fields: projectedFields,
+            available_fields: availableFields,
+            // Emit unknown_fields whenever the caller passed an explicit
+            // projection (empty [] = all valid; keeps the F-004 contract), omit
+            // it on the default no-`fields` call.
+            ...(hasExplicitFields ? { unknown_fields: unknownFields } : {}),
+            ...(emitWarning ? { projection_warning: unknownNote.trim() } : {}),
         });
     }
     catch (e) {
@@ -134,29 +175,126 @@ export async function handlePagesList(client, { fields, limit, cursor, label_con
 export async function resolveUrlToTemplate(client, url) {
     return client.get(`/pages/resolve?url=${encodeURIComponent(url)}`);
 }
-export async function handlePagesResolve(client, { url }) {
+/**
+ * A-6: resolve a semantic `target` — `GET /pages/resolve?target[special]=home`.
+ * The bracket encoding is the ONE wire form both CMS controllers parse (see
+ * `./target.ts`).
+ */
+async function resolveTargetToTemplate(client, target) {
+    const qs = new URLSearchParams();
+    appendTargetParams(qs, target);
+    return client.get(`/pages/resolve?${qs.toString()}`);
+}
+/**
+ * A-6: is this failure an OLD host rejecting the request because it still
+ * hard-requires `url`? WP core answers `rest_missing_callback_param` when the
+ * route arg is `required`; the pre-A-5 controller answered its own
+ * `missing_url`. Either way the fix is "update the plugin", not "fix your
+ * target" — and only ever on a target-only call.
+ */
+function isMissingUrlRejection(e) {
+    if (!(e instanceof RestError) || e.status !== 400)
+        return false;
+    const code = e.code ?? '';
+    return code.includes('rest_missing_callback_param') || code.includes('missing_url');
+}
+/** A-6: narrow an off-the-wire `matched_by` to the declared enum, else drop it. */
+function knownMatchedBy(value) {
+    return TARGET_KEYS.find((key) => key === value);
+}
+export async function handlePagesResolve(client, { url, target }) {
+    // A-6 / F205: the exactly-one-of(url, target) contract is validated HERE
+    // with typed results — a zod `.refine` would surface as a raw -32602 and
+    // strip every hint below. Mirrors the WP/Joomla controllers' own codes so
+    // the contract reads the same whether it fired locally or upstream.
+    const resolvedTarget = normalizeTarget(target);
+    // BUG-4 (shared rule, PHP `PageQuery::malformedTargetError()`): a target bag
+    // that survived nothing is a MALFORMED ADDRESS. Checked BEFORE the
+    // exactly-one-of(url, target) pair, exactly as both controllers do — so it
+    // is never reported as `missing_url` (which claims no address was passed)
+    // and, alongside a `url`, is never silently ignored.
+    const malformed = malformedTargetError(target, resolvedTarget, {
+        context: { url: url ?? null, target: target ?? null },
+        hint: 'Each target member must be a non-empty string or number — e.g. '
+            + 'target:{special:"home"} or target:{template_id:"page:4816"}. Or pass `url` instead.',
+    });
+    if (malformed !== null)
+        return malformed;
+    const targetKeys = targetKeysOf(resolvedTarget);
+    const hasUrl = typeof url === 'string' && url.trim() !== '';
+    const hasTarget = targetKeys.length > 0;
+    if (hasUrl && hasTarget) {
+        return tooManyTargetsError({
+            supplied: ['url', ...targetKeys.map((k) => `target.${k}`)],
+            context: { url: url ?? null, target: resolvedTarget },
+        });
+    }
+    if (targetKeys.length > 1) {
+        return tooManyTargetsError({
+            supplied: targetKeys,
+            context: { target: resolvedTarget },
+        });
+    }
+    if (!hasUrl && !hasTarget) {
+        return errorResult({
+            error: new RestError({
+                status: 400,
+                code: 'yootheme_builder_mcp.pages.missing_url',
+                message: 'A page address is required: pass `url` or `target`.',
+                body: null,
+            }),
+            context: { url: null, target: {} },
+            hint: 'Pass `url` (a public page/article URL), or `target` with exactly one of ' +
+                'template_id / post_id / url / special ("home", "blog", "404", "search", ' +
+                '"category", "tag", "author", "archive") / title.',
+        });
+    }
     try {
-        const data = await resolveUrlToTemplate(client, url);
+        const data = hasTarget
+            ? await resolveTargetToTemplate(client, resolvedTarget)
+            : await resolveUrlToTemplate(client, (url ?? '').trim());
+        const matchedBy = knownMatchedBy(data.matched_by);
         return structuredResult(jsonResult(data), {
             template_id: data.template_id,
             // G-A2: post_id is null for a theme-template resolution.
             post_id: data.post_id ?? null,
             type: data.type,
+            // Forwarded ONLY when the host sent one — a synthesised label would
+            // claim a page name this build has no way to know.
+            ...(typeof data.label === 'string' && data.label !== '' ? { label: data.label } : {}),
             frontend_url: data.frontend_url ?? null,
             // G-A2: context/resolved_via are additive. An OLDER plugin (pre-G-A2)
             // only ever resolved per-page layouts and omits both — default to the
             // per-page shape so a strict host still accepts the success.
             context: data.context ?? null,
             resolved_via: data.resolved_via ?? 'per_page',
+            // A-6: forwarded ONLY when the host sent a value this build knows.
+            // A `url` resolve and every pre-A-5 host omit it; an UNKNOWN token
+            // from a newer host is dropped rather than tripping the strict
+            // outputSchema and failing an otherwise perfect resolve.
+            ...(matchedBy !== undefined ? { matched_by: matchedBy } : {}),
         });
     }
     catch (e) {
+        // A-6 version-skew: an old host still hard-requires `url`, so a
+        // target-only call 400s before its controller ever sees the target.
+        // That is an "update the plugin" condition, not a bad address.
+        if (hasTarget && isMissingUrlRejection(e)) {
+            return serverTooOldError({
+                message: 'This site rejected a `target`-only resolve because it still requires `url`.',
+                context: { target: resolvedTarget },
+            });
+        }
         return errorResult({
             error: e,
-            context: { url },
-            hint: 'If this 404s, the URL renders via a theme template (not a ' +
-                'per-page layout) — use yootheme_builder_pages_list to find its ' +
-                'template_id. Verify the URL is a public, singular page/article.',
+            context: { url: url ?? null, target: resolvedTarget },
+            // BUG-3 / MM-5: the target-aware hint now lives in `target.js` so
+            // `pages_audit` answers the SAME error family with the SAME steer.
+            hint: hasTarget
+                ? TARGET_FAILURE_HINT
+                : 'If this 404s, the URL renders via a theme template (not a ' +
+                    'per-page layout) — use yootheme_builder_pages_list to find its ' +
+                    'template_id. Verify the URL is a public, singular page/article.',
         });
     }
 }
@@ -334,7 +472,7 @@ function parseOutlineNodes(raw) {
     return out;
 }
 /**
- * B7 (Glöckle continuation cursor) — build the full-dump TEXT leg windowed at
+ * B7 (customer continuation cursor) — build the full-dump TEXT leg windowed at
  * `[offset, offset+max_chars)` and, when more remains, append a `next_cursor`.
  *
  * The truncated full/bindings_only TEXT leg of page_get_layout had NO
@@ -381,7 +519,7 @@ export async function handlePageGetLayout(client, { template_id, post_id, url, f
             return effective.error;
         }
         const templateId = effective.templateId;
-        // B7 (Glöckle continuation cursor): an opaque char-offset cursor
+        // B7 (customer continuation cursor): an opaque char-offset cursor
         // (base64url `o:<n>`) resumes a previously-clipped full/bindings_only
         // text leg from the offset. A present cursor makes the read a
         // CONTINUATION — it is NEVER served from the [unchanged] dedup cache
@@ -451,7 +589,7 @@ export async function handlePageGetLayout(client, { template_id, post_id, url, f
         if (flat !== true) {
             // Default: nested passthrough — unchanged from pre-G.3, except an
             // OPTIONAL G-B `max_chars` caps the (potentially large) JSON text
-            // leg. B7 (Glöckle continuation cursor): when the dump is clipped
+            // leg. B7 (customer continuation cursor): when the dump is clipped
             // (by `max_chars` or resumed via `cursor`) it now also emits a
             // `next_cursor` so an agent can page through the REST of the
             // subtree instead of being stuck with the first slice. With no
@@ -461,7 +599,14 @@ export async function handlePageGetLayout(client, { template_id, post_id, url, f
             if (max_chars !== undefined || isContinuation) {
                 return windowedFullDump(data, charOffset, max_chars);
             }
-            return applyMaxChars(jsonResult(data), max_chars);
+            // Reaching here means `max_chars === undefined`, so the former
+            // `applyMaxChars(jsonResult(data), max_chars)` was a no-op by its own
+            // contract (`sparse-fields.ts`: undefined → return the result
+            // unchanged). Calling it read as "this leg is capped" when it never
+            // was, and it was the one character-cut call site with no
+            // `structuredContent` beside it — see
+            // `tests/contracts/char-cut-requires-structured-leg.test.ts`.
+            return jsonResult(data);
         }
         // flat: true → depth-first walk on the nested layout. Apply
         // pickFields per element when `fields[]` was passed; echo the
@@ -519,7 +664,10 @@ export async function handlePageGetLayout(client, { template_id, post_id, url, f
         // single-root-node envelope — collapse identically.
         const candidate = hasInnerLayoutField ? layoutObj.layout : dataLayout;
         const layoutRoot = unwrapToWalkableContainer(candidate);
-        const flatElements = flattenLayout(layoutRoot);
+        // LAYOUT_READ-7: pass the resolved template id so flat-mode `path`s are
+        // fully-qualified (`/templates/<id>/layout/children/0`) — matching the
+        // `path` element_list emits. `rel_path` stays the short `/children/0`.
+        const flatElements = flattenLayout(layoutRoot, templateId);
         // Non-silent fallback (C4) + F29 calibration: if the walk yields
         // ZERO elements AND the resolved walk container is an unrecognized
         // NON-EMPTY shape, surface a warning so it can never pass silently.
@@ -542,7 +690,14 @@ export async function handlePageGetLayout(client, { template_id, post_id, url, f
         // `projection_warning` (the shared F23 SSoT helper) so the agent can
         // self-correct on the next call. Default-all callers (no fields[])
         // get no audit overhead — projectionFeedback returns undefined.
-        const feedback = projectionFeedback(flatElements, fields);
+        // SOURCES_BINDING-29 (parallel site): an EMPTY flat result cannot
+        // observe a field vocabulary, so `projectionFeedback` over zero rows
+        // would report EVERY requested field as unknown against an empty
+        // `available_fields`. Suppress the feedback entirely on a zero-element
+        // flatten — the projection is moot when there is nothing to project.
+        const feedback = flatElements.length > 0
+            ? projectionFeedback(flatElements, fields)
+            : undefined;
         const projectionNote = projectionWarning(feedback);
         // 1.0.1 Wave-1.7 F-COLD-3: forward the canonical pointer base
         // through the flat-projection path too so cold agents iterating
@@ -579,7 +734,7 @@ export async function handlePageGetLayout(client, { template_id, post_id, url, f
     }
 }
 // ─── page_get_schema ────────────────────────────────────────────────
-export async function handlePageGetSchema(client, { template_id, post_id, url, fields, max_chars }) {
+export async function handlePageGetSchema(client, { template_id, post_id, url, fields, max_chars, include_meta }) {
     try {
         // G-A: resolve the effective template_id from template_id | post_id | url.
         const effective = await resolveEffectiveTemplateId(client, { template_id, post_id, url });
@@ -590,7 +745,7 @@ export async function handlePageGetSchema(client, { template_id, post_id, url, f
         const data = await client.get(`/pages/${encodeTemplateId(templateId)}/schema`);
         const rawNodes = Array.isArray(data.nodes) ? data.nodes : [];
         const rows = buildSchemaRows(rawNodes.filter((x) => x !== null && typeof x === 'object'));
-        // G-B (Glöckle 2026-06-26, P2): `fields[]` projection — DEFAULT_FIELDS_SCHEMA
+        // G-B (customer 2026-06-26, P2): `fields[]` projection — DEFAULT_FIELDS_SCHEMA
         // existed but was never wired. Mirror element_list: project both legs,
         // echo `projected_fields`, surface the F23 unknown-field feedback.
         const items = projectFields(rows, fields, DEFAULT_FIELDS_SCHEMA);
@@ -614,12 +769,14 @@ export async function handlePageGetSchema(client, { template_id, post_id, url, f
                 columns: columnsFromFields([...fields]),
                 header: (count) => `${String(count)} nodes in template "${templateId}"${unknownNote}`,
                 footer: 'Use yootheme_builder_element_get <path> for full element data.',
+                includeMeta: include_meta,
             }, 'compact')
             : tableResult(rows, {
                 columns: [...SCHEMA_TABLE_COLUMNS],
                 compactColumns: [...SCHEMA_COMPACT_COLUMNS],
                 header: (count) => `${String(count)} nodes in template "${templateId}"`,
                 footer: 'Use yootheme_builder_element_get <path> for full element data.',
+                includeMeta: include_meta,
             }, 'compact');
         return structuredResult(applyMaxChars(toolkitResult, max_chars), {
             items,
@@ -645,10 +802,13 @@ export async function handlePageGetSchema(client, { template_id, post_id, url, f
 export async function handleGetEtag(client) {
     try {
         const data = await client.get('/etag');
-        const toolkitResult = detailResult(buildEtagDetail({
-            etag: data.etag,
-            generated_at: data.generated_at,
-        }));
+        const toolkitResult = detailResult({
+            ...buildEtagDetail({
+                etag: data.etag,
+                generated_at: data.generated_at,
+            }),
+            includeMeta: false,
+        });
         return structuredResult(toolkitResult, {
             etag: data.etag,
             ...(typeof data.generated_at === 'string'
@@ -665,52 +825,124 @@ export async function handleGetEtag(client) {
     }
 }
 // ─── template_summary (T9 — Audit-v3 B.5 token-efficient overview) ────
+/**
+ * Task #46 Friction-3 (2026-05-29): PHP's `json_encode([])` emits `[]`
+ * (array), not `{}` (object). The REST handler emits `counts_by_type: []`
+ * for an empty template, but the outputSchema declares
+ * `z.record(z.string(), z.number())`, which requires an object. Normalize
+ * array->object here so the schema validates and the agent sees the
+ * (valid, empty) summary. T-C5 (mega-push plan 2026-07-24-02): factored out
+ * of `handleTemplateSummary` so it applies to BOTH the single-template
+ * response AND every per-id entry of a batch response's `summaries` map.
+ */
+function normalizeCountsByType(data) {
+    const normalized = { ...data };
+    if (Array.isArray(normalized.counts_by_type)) {
+        normalized.counts_by_type = {};
+    }
+    return normalized;
+}
+/**
+ * T-E2 + T-C5 (mega-push plan 2026-07-24-02, customer P1.5): build the shared
+ * `include_nodes`/`limit`/`cursor` query params both the single-template and
+ * batch REST calls forward verbatim to `PageQuery::summary()`'s `$options`.
+ */
+function summaryQueryParams(opts) {
+    const qs = new URLSearchParams();
+    if (opts.include_nodes === true)
+        qs.set('include_nodes', 'true');
+    if (typeof opts.limit === 'number')
+        qs.set('limit', String(opts.limit));
+    if (typeof opts.cursor === 'string' && opts.cursor !== '')
+        qs.set('cursor', opts.cursor);
+    return qs;
+}
 /**
  * T9: a one-call structured overview of a template — element counts by
  * type, binding count, max nesting depth, and named landmarks. Lets the
  * agent grasp a 96-node template for ~1 kB instead of pulling the full
  * element_list dump (20 kB+).
+ *
+ * T-E2 + T-C5 (mega-push plan 2026-07-24-02, Thomas-Entscheid C + customer
+ * P1.5): three additive changes, one coherent tool-behavior update:
+ *  - `include_nodes`/`limit`/`cursor` ride through to the REST query string
+ *    unconditionally opt-in (`content_nodes` no longer ships by default).
+ *  - `template_id` (single) XOR `template_ids` (batch) — exactly one,
+ *    validated HERE with typed results (mirrors `handlePagesResolve`'s
+ *    exactly-one-of(url, target) contract) rather than a zod `.refine`,
+ *    which would surface as a raw -32602 and strip every hint below.
+ *  - Batch hits the LITERAL `/pages/summary?template_ids=a,b,c` route (ONE
+ *    REST round-trip for N templates) and returns
+ *    `{summaries: {<id>: <summary>}, not_found: [...]}`.
  */
-export async function handleTemplateSummary(client, { template_id }) {
+export async function handleTemplateSummary(client, { template_id, template_ids, include_nodes, limit, cursor }) {
+    const hasTemplateId = typeof template_id === 'string' && template_id.trim() !== '';
+    const hasTemplateIds = Array.isArray(template_ids) && template_ids.length > 0;
+    if (hasTemplateId && hasTemplateIds) {
+        return errorResult({
+            error: new RestError({
+                status: 400,
+                code: 'yootheme_builder_mcp.pages.too_many_template_ids',
+                message: 'Provide EXACTLY ONE of template_id (single) or template_ids (batch), not both.',
+                body: null,
+            }),
+            context: { template_id: template_id ?? null, template_ids: template_ids ?? null },
+            hint: 'Pass template_id for a single template, or template_ids:[...] for a batch - not both.',
+        });
+    }
+    if (!hasTemplateId && !hasTemplateIds) {
+        return errorResult({
+            error: new RestError({
+                status: 400,
+                code: 'yootheme_builder_mcp.pages.missing_template_id',
+                message: 'A template_id or template_ids is required.',
+                body: null,
+            }),
+            context: {},
+            hint: 'Pass template_id (single) or template_ids:[...] (batch). Use yootheme_builder_pages_list to discover template IDs.',
+        });
+    }
+    const qs = summaryQueryParams({ include_nodes, limit, cursor });
     try {
-        const data = await client.get(`/pages/${encodeTemplateId(template_id)}/summary`);
-        // F-AUDIT-2 (2026-05-26): template_summary now declares
-        // TEMPLATE_SUMMARY_OUTPUT_SCHEMA. The SDK requires
-        // `structuredContent` when an outputSchema is present, otherwise
-        // it raises `-32602 Output validation error`. Wrap the raw body
-        // with `structuredResult` so the text leg (LLM-readable JSON)
-        // stays unchanged AND the structuredContent leg validates.
-        //
-        // Task #46 Friction-3 (2026-05-29): PHP's `json_encode([])` emits
-        // `[]` (array) — not `{}` (object). The REST handler emits
-        // `counts_by_type: []` for empty templates, but the outputSchema
-        // declares `z.record(z.string(), z.number())` which requires an
-        // object. The mismatch surfaces as `-32602 counts_by_type
-        // expected record, received array`, swallowing the entire response
-        // for any empty / freshly-created template. Normalize array→object
-        // here so the schema validates and the agent sees the (valid,
-        // empty) summary. Same defensive shape applies to any future
-        // map-typed REST field that might come back empty.
-        const normalized = {
-            ...data,
-        };
-        if (Array.isArray(normalized.counts_by_type)) {
-            normalized.counts_by_type = {};
+        if (hasTemplateIds) {
+            qs.set('template_ids', template_ids.join(','));
+            const data = await client.get(`/pages/summary?${qs.toString()}`);
+            const normalizedSummaries = {};
+            for (const [id, summary] of Object.entries(data.summaries ?? {})) {
+                normalizedSummaries[id] = normalizeCountsByType(summary);
+            }
+            const normalized = {
+                summaries: normalizedSummaries,
+                not_found: data.not_found ?? [],
+                ...(typeof data.etag === 'string' ? { etag: data.etag } : {}),
+            };
+            const toolkitResult = jsonResult(normalized);
+            return structuredResult({ content: toolkitResult.content }, normalized);
         }
+        const id = (template_id ?? '').trim();
+        const query = qs.toString();
+        const data = await client.get(`/pages/${encodeTemplateId(id)}/summary${query !== '' ? `?${query}` : ''}`);
+        // F-AUDIT-2 (2026-05-26): template_summary declares
+        // TEMPLATE_SUMMARY_OUTPUT_SCHEMA. The SDK requires
+        // `structuredContent` when an outputSchema is present, otherwise it
+        // raises `-32602 Output validation error`. Wrap the raw body with
+        // `structuredResult` so the text leg (LLM-readable JSON) stays
+        // unchanged AND the structuredContent leg validates.
+        const normalized = normalizeCountsByType(data);
         const toolkitResult = jsonResult(normalized);
         return structuredResult({ content: toolkitResult.content }, normalized);
     }
     catch (e) {
         return errorResult({
             error: e,
-            context: { template_id },
-            hint: 'Verify the template_id exists via yootheme_builder_pages_list.',
+            context: { template_id: template_id ?? null, template_ids: template_ids ?? null },
+            hint: 'Verify the template_id(s) exist via yootheme_builder_pages_list.',
         });
     }
 }
 // ─── render_preview (F5 + N5 — authenticated post-write render check) ──
 /**
- * F5 + N5 (Glöckle HANDOFF-4/5): the authenticated post-write render
+ * F5 + N5 (customer HANDOFF-4/5): the authenticated post-write render
  * HEALTHCHECK. Resolves the EFFECTIVE template_id from `template_id` OR `url`
  * (the SAME `resolveEffectiveTemplateId` precedence page_get_layout uses — a
  * pasted public URL is reverse-resolved via GET /pages/resolve first), then
@@ -723,15 +955,20 @@ export async function handleTemplateSummary(client, { template_id }) {
  * items, or that threw inside the Builder pipeline (the swallowed YOOtheme
  * render error surfaced as `error`), is a SUCCESS — not a tool error.
  */
-export async function handleRenderPreview(client, { template_id, url, expect }) {
+export async function handleRenderPreview(client, { template_id, post_id, url, expect }) {
     try {
-        // G-A precedence: template_id wins, else resolve `url` to its template_id.
-        const effective = await resolveEffectiveTemplateId(client, { template_id, url });
+        // WAVE-1 follow-up (a): render_preview now accepts `post_id` too, the SAME
+        // three-mode addressing page_get_layout uses — template_id wins, else a
+        // bare numeric post/article id, else a `url` reverse-resolved via
+        // /pages/resolve. (Cross-file: the RENDER_PREVIEW input schema in
+        // pages/builders.ts must also declare `post_id` + the native catalog must
+        // carry it — flagged for the coordinator regen.)
+        const effective = await resolveEffectiveTemplateId(client, { template_id, post_id, url });
         if ('error' in effective) {
             return effective.error;
         }
         const templateId = effective.templateId;
-        // Glöckle HANDOFF-6 #4: an `expect` substring is passed to the render
+        // customer HANDOFF-6 #4: an `expect` substring is passed to the render
         // endpoint as a query param (the server greps the rendered HTML and adds
         // {matched, snippet}). A blank value is treated as "no check".
         const wantMatch = typeof expect === 'string' && expect !== '';
@@ -759,7 +996,7 @@ export async function handleRenderPreview(client, { template_id, url, expect })
                 }
                 : {}),
         };
-        return structuredResult(detailResult(buildRenderPreviewDetail(payload)), {
+        return structuredResult(detailResult({ ...buildRenderPreviewDetail(payload), includeMeta: false }), {
             rendered: payload.rendered,
             item_count: payload.item_count,
             empty: payload.empty,
@@ -773,9 +1010,51 @@ export async function handleRenderPreview(client, { template_id, url, expect })
     catch (e) {
         return errorResult({
             error: e,
-            context: { template_id, url, expect },
+            context: { template_id, post_id, url, expect },
             hint: 'Verify the template_id exists via yootheme_builder_pages_list ' +
-                '(or that the url resolves). Run yootheme_builder_diagnose to check auth.',
+                '(or that post_id / the url resolves). Run yootheme_builder_diagnose to check auth.',
+        });
+    }
+}
+// ─── heading_outline (T-A5 — a real, doc-order H1-H6 outline) ──────────
+/**
+ * T-A5 (heading_outline tool, mega-push plan 2026-07-24-02): a real,
+ * doc-order H1-H6 outline of ONE template, each heading attributed to its
+ * source element (`element_type`/`path`), plus the alt-status of every
+ * image (including images living inside html/text/code raw markup).
+ * Read-only STRUCTURE inspection — no findings/severity (that is
+ * pages_audit's job).
+ *
+ * `template_id`-only addressing (no post_id/url sugar) — resolve via
+ * yootheme_builder_pages_resolve first, like the other per-page tools that
+ * need a bare template_id. The REST body already carries the HEADING_OUTLINE_
+ * OUTPUT_SCHEMA shape, so it is forwarded through structuredResult verbatim
+ * (a thin dispatch onto PageAuditService::headingOutline()).
+ */
+export async function handleHeadingOutline(client, { template_id, mode }) {
+    try {
+        const qs = new URLSearchParams();
+        if (mode !== undefined)
+            qs.set('mode', mode);
+        const query = qs.toString();
+        const data = await client.get(`/pages/${encodeTemplateId(template_id)}/heading-outline${query !== '' ? `?${query}` : ''}`);
+        return structuredResult(jsonResult(data), data);
+    }
+    catch (e) {
+        if (e instanceof RestError && e.status === 404) {
+            return errorResult({
+                error: e,
+                context: { template_id, mode: mode ?? null },
+                hint: 'GET /pages/{id}/heading-outline was not found on this site: the ' +
+                    'yt-builder-mcp host plugin predates heading_outline. Update the plugin on ' +
+                    'this site, or verify the template_id via yootheme_builder_pages_list.',
+            });
+        }
+        return errorResult({
+            error: e,
+            context: { template_id, mode: mode ?? null },
+            hint: 'Verify the template_id exists via yootheme_builder_pages_list. Run ' +
+                'yootheme_builder_diagnose to check auth.',
         });
     }
 }