@wootsup/yt-builder-mcp 1.10.0 → 1.12.0

package/dist/tools/pages/schemas.js

@@ -7,6 +7,7 @@
  * @license MIT
  */
 import { z } from 'zod';
+import { INCLUDE_META_SCHEMA } from '../shared-schemas.js';
 import { MAX_CHARS } from '../sparse-fields.js';
 export const PAGES_LIST_OUTPUT_SCHEMA = z.object({
     // F-Frontend-URL (2026-05-25): each row carries `frontend_url`,
@@ -35,7 +36,7 @@ export const PAGES_LIST_OUTPUT_SCHEMA = z.object({
     // field projection + available_fields discovery surface it.
     items: z.array(z.record(z.string(), z.unknown())),
     total: z.number(),
-    // B2 (Glöckle 2026-06-25): pagination. `total` is the (filtered) count;
+    // B2 (customer 2026-06-25): pagination. `total` is the (filtered) count;
     // `returned` is how many rows this page carries; `next_cursor` (present
     // only when more remain) is passed back as `cursor` for the next page.
     returned: z.number().optional(),
@@ -61,7 +62,7 @@ export const SCHEMA_OUTPUT_SCHEMA = z.object({
     // row for back-compat but is optional so callers reading the schema
     // know `rel_path` is the canonical projection column.
     //
-    // G-B (Glöckle 2026-06-26): every row-field is now `.optional()` +
+    // G-B (customer 2026-06-26): every row-field is now `.optional()` +
     // `.passthrough()` so a `fields[]` projection (which drops the unrequested
     // keys) still validates — exactly the relaxation `element_list`'s output
     // schema uses. The default (no fields) full row still carries all keys.
@@ -96,16 +97,36 @@ export const ETAG_OUTPUT_SCHEMA = z.object({
 // the RESULT-LEVEL by `withSiteMeta`, NEVER into `structuredContent`
 // (see results.ts W12-R2 commentary) — this schema therefore validates
 // only the inner template-summary shape.
+//
+// T-C5 (mega-push plan 2026-07-24-02, customer P1.5): `template_summary` is now
+// BIMODAL — a single-`template_id` call returns these fields at the TOP LEVEL
+// (unchanged wire shape, back-compat preserved); a `template_ids` BATCH call
+// instead returns `{summaries: {<id>: <that SAME per-template shape>},
+// not_found: [...]}` and omits every top-level field below. The 7 fields that
+// used to be REQUIRED (template_id/counts_by_type/bound_count/max_depth/total/
+// named_sections/etag) are now `.optional()` too, SPECIFICALLY so one strict
+// Zod object can validate BOTH response variants without a `z.union()` — the
+// codebase's established alternative for a bimodal MCP response is dropping
+// `outputSchema` entirely (see page_get_layout / page_dynamize in
+// builders.ts), which would lose validation for the (overwhelmingly common)
+// single-template case too. Declaring every possible field of BOTH shapes as
+// optional on one object keeps `additionalProperties:false` catching
+// genuinely unexpected keys while tolerating "this variant's fields are
+// absent" — the SAME relaxation `resolved_target`/`FINDING` already use
+// elsewhere in this file for the identical reason (different response
+// variants omit different keys).
 export const TEMPLATE_SUMMARY_OUTPUT_SCHEMA = z.object({
-    template_id: z.string(),
-    counts_by_type: z.record(z.string(), z.number().int().nonnegative()),
-    bound_count: z.number().int().nonnegative(),
-    max_depth: z.number().int().nonnegative(),
-    total: z.number().int().nonnegative(),
-    named_sections: z.array(z.object({
+    template_id: z.string().optional(),
+    counts_by_type: z.record(z.string(), z.number().int().nonnegative()).optional(),
+    bound_count: z.number().int().nonnegative().optional(),
+    max_depth: z.number().int().nonnegative().optional(),
+    total: z.number().int().nonnegative().optional(),
+    named_sections: z
+        .array(z.object({
         path: z.string(),
         name: z.string(),
-    })),
+    }))
+        .optional(),
     // pages_audit impl plan Task 7 (2026-07-19): additive enrichment —
     // heading-level census (h1-h6 + div — `div` counts `description_list`
     // elements, the one type whose title_element defaults to div),
@@ -114,9 +135,54 @@ export const TEMPLATE_SUMMARY_OUTPUT_SCHEMA = z.object({
     // a NEW MCP client talking to an OLD (pre-1.10.0) host plugin — which
     // doesn't emit these fields yet — still validates.
     heading_levels: z.record(z.string(), z.number().int().nonnegative()).optional(),
+    // T-A3 (mega-push plan 2026-07-24-02): a static, always-present sibling
+    // stating which sources feed heading_levels above — html/text/code
+    // raw-HTML elements count (T-A1 widened the shared LayoutAuditExtractor
+    // pass to read them), module/widget output does NOT (no content field to
+    // parse). `.optional()` for the same pre-1.10.0-host back-compat reason
+    // as heading_levels itself.
+    heading_levels_note: z.string().optional(),
     images_missing_alt: z.number().int().nonnegative().optional(),
     disabled_elements: z.number().int().nonnegative().optional(),
-    etag: z.string(),
+    // F191 (2026-06-12) source-transparency flags the PHP summary() has emitted
+    // since June but this schema never declared, so a strict SDK parse silently
+    // stripped them. `already_dynamized` = the layout already binds an API Mapper
+    // source (demo/clone vs pristine theme); `is_theme_template` = a real YOOtheme
+    // theme template vs a per-page/per-article layout. `.optional()` for the same
+    // pre-1.10.0-host back-compat reason as the fields above.
+    already_dynamized: z.boolean().optional(),
+    is_theme_template: z.boolean().optional(),
+    etag: z.string().optional(),
+    // Task 6 (Wave 1 audit, F4, 2026-07-24): one entry per content-bearing
+    // node (structural wrappers section/row/column/fragment/layout excluded).
+    // Disabled/render-dead nodes ARE included, unlike disabled_elements above:
+    // this is the field that says WHICH node and WHY, not just a count.
+    // T-E2 (mega-push plan 2026-07-24-02, Thomas-Entscheid C): OPT-IN now —
+    // absent unless the caller passed `include_nodes:true` (previously
+    // unconditional). `.optional()` covers BOTH that opt-out-by-default case
+    // AND the pre-1.10.0-host back-compat reason the three fields above share.
+    content_nodes: z
+        .array(z.object({
+        path: z.string(),
+        type: z.string(),
+        status: z.boolean(),
+        effective_visible: z.boolean(),
+        hidden_on_mobile: z.boolean(),
+        headings: z.array(z.string()),
+        alts: z.array(z.string()),
+    }))
+        .optional(),
+    // T-C5: page 2+ of content_nodes when `include_nodes:true` + `limit` were
+    // supplied. Present ONLY while more content_nodes rows remain (mirrors
+    // pages_list / element_list — never an always-present nullable field).
+    next_cursor: z.string().optional(),
+    // T-C5 (customer P1.5) batch shape — present ONLY when the caller passed
+    // `template_ids` instead of `template_id`. One entry per id that resolved
+    // (SAME per-template shape as the single-mode top-level fields above,
+    // left as an open record here rather than nesting the whole shape a
+    // second time); `not_found` lists ids that did not.
+    summaries: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+    not_found: z.array(z.string()).optional(),
 });
 // ─── C1 — pages_create + pages_delete (v1.2) ──────────────────────────
 //
@@ -350,9 +416,11 @@ export const PAGE_DYNAMIZE_INPUT = {
         .string()
         .min(1)
         .optional()
-        .describe('SINGLE-block path: the published flow LIST source the one iterating column ' +
-        'query is rewritten to (e.g. "apiMapperFlowAbcList"). Provide THIS or ' +
-        '`source_map` — exactly one. Use yootheme_builder_sources_list to discover.'),
+        .describe('SINGLE-block path: the LIST source the one iterating column query is rewritten ' +
+        'to. Accepts ANY list source — a published API Mapper flow ' +
+        '(apiMapperFlow…List, e.g. "apiMapperFlowAbcList") OR a native source/relation ' +
+        '(e.g. "posts.customPosts", "articles"). Provide THIS or `source_map` — exactly ' +
+        'one. Use yootheme_builder_sources_list to discover.'),
     // F201 (multi-block): a section with SEVERAL source blocks (Played / Next /
     // Later) dynamizes in ONE call. Each entry keys the EXISTING iterating
     // column query (`match`) to its flow list source (`source_name`) + its own
@@ -437,6 +505,14 @@ export const PAGE_DYNAMIZE_INPUT = {
         .optional()
         .describe('Optimistic-lock ETag from yootheme_builder_get_etag. Optional; when provided, ' +
         '412 on conflict. Recommended for collaborative edits.'),
+    // SOURCES_BINDING-27: preflight the dynamize without creating a page.
+    dry_run: z
+        .boolean()
+        .optional()
+        .describe('Preflight ONLY. When true, compute the dynamize and return {summary, ' +
+        'would_change, dry_run:true} WITHOUT creating a page — nothing persists ' +
+        '(etag == new_etag). Inspect summary.queries_swapped / unmatched_map_keys ' +
+        'before the real call.'),
 };
 /**
  * Wire shape for `yootheme_builder_pages_delete` on success.
@@ -464,13 +540,97 @@ export const PAGES_DELETE_OUTPUT_SCHEMA = z
 })
     .refine((v) => typeof v.page_id === 'number' || typeof v.article_id === 'number', { message: 'response must contain either page_id (WP) or article_id (Joomla)' });
 // ─── G-A (Track-C URL→layout) — pages_resolve ───────────────────────
+// ─── A-6 (single-page audit plan, 2026-07-22-02) — semantic `target` ──────
+//
+// The shared addressing object BOTH `pages_resolve` and `pages_audit` accept.
+// It is deliberately PERMISSIVE (every member optional, no `.refine`): the
+// exactly-one-of contract is enforced in the HANDLERS as a typed
+// `too_many_targets` result. F205 (`gateway/advanced-read-tool.ts`): an
+// SDK-level zod rejection surfaces as a raw -32602 and bypasses every piece of
+// typed steering the tool provides.
+//
+// The VOCABULARY lives in these field `.describe()` strings on purpose — the
+// tool descriptions are pinned at MAX_DESCRIPTION_LENGTH=600 by
+// `tests/gateway/description-length.test.ts` and pages_resolve already sits at
+// 577, so there is no room there. Field describes carry no length pin.
+/**
+ * The five addressing keys, in the order they are documented + put on the
+ * wire. SSOT for both the `matched_by` echo enum and the runtime iteration in
+ * `./target.ts`.
+ */
+export const TARGET_KEYS = ['template_id', 'post_id', 'url', 'special', 'title'];
+/**
+ * The semantic-special vocabulary, byte-identical to PHP `SpecialTargetMap`'s
+ * key set. `date` is IN the vocabulary but unsupported on both platforms — it
+ * resolves to a clean `special_not_supported` error rather than "unknown
+ * special", which is why it is listed here.
+ */
+export const SPECIAL_TARGET_TOKENS = [
+    'home',
+    'front-page',
+    'blog',
+    'search',
+    '404',
+    'category',
+    'tag',
+    'author',
+    'archive',
+    'date',
+];
+export const PAGES_TARGET = z
+    .object({
+    template_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('An exact template id (e.g. "page:4816", "article:12", "helpArchiveTpl").'),
+    post_id: z
+        .union([z.number().int().positive(), z.string().min(1)])
+        .optional()
+        .describe('The numeric WordPress post / Joomla article id (e.g. 4816).'),
+    url: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('A public frontend URL (e.g. "https://site.com/schedule-demo/").'),
+    special: z
+        .enum(SPECIAL_TARGET_TOKENS)
+        .optional()
+        .describe('A semantic page role: "home" / "front-page" / "blog" (the configured ' +
+        'front page or posts page), "search", "404", "category", "tag", ' +
+        '"author" (Joomla: the Contact template), "archive" (the post ' +
+        'archive). "date" is recognised but not supported on either platform ' +
+        'yet and returns special_not_supported. DISCOVERY_AUDIT-17: a special ' +
+        'resolves ONLY when the site has a theme template assigned to that role, ' +
+        'so search/tag/author/archive availability is SITE-SPECIFIC — a role with ' +
+        'no template returns special_not_resolvable (e.g. "archive" resolves on ' +
+        'one site but not another).'),
+    title: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Case-insensitive substring of the page NAME/label (e.g. "SunWest"). ' +
+        'Zero matches → title_no_match; two or more → title_ambiguous with a ' +
+        'candidate list to choose from.'),
+})
+    .describe('Address exactly ONE page. Supply exactly one of template_id / post_id / url / ' +
+    'special / title — supplying two returns a typed too_many_targets error, ' +
+    'supplying none runs the unscoped default.');
 export const PAGES_RESOLVE_INPUT = {
+    // A-6: OPTIONAL since a target-only resolve must be expressible. The
+    // exactly-one-of(url, target) contract lives in `handlePagesResolve`
+    // (typed too_many_targets / missing_url), not in the schema.
     url: z
         .string()
         .min(1)
+        .optional()
         .describe('A public frontend URL of the page/article (e.g. ' +
         '"https://site.com/schedule-demo/"). Resolved to the per-page ' +
-        'template_id that renders it — paste a URL, get a layout-addressable id.'),
+        'template_id that renders it — paste a URL, get a layout-addressable id. ' +
+        'Omit when addressing the page via `target` instead.'),
+    target: PAGES_TARGET.optional().describe('Resolve a page WITHOUT knowing its URL — by template_id, post_id, url, a ' +
+        'semantic special ("home", "blog", "404", "search", "category", "tag", ' +
+        '"author", "archive") or a title substring. Mutually exclusive with `url`.'),
 };
 export const PAGES_RESOLVE_OUTPUT_SCHEMA = z.object({
     // The read-tool-addressable id every read tool accepts as `template_id`
@@ -484,17 +644,27 @@ export const PAGES_RESOLVE_OUTPUT_SCHEMA = z.object({
     // Content type — `get_post_type`/archive post-type/taxonomy on WP,
     // "article"/"category" on Joomla.
     type: z.string(),
+    // The page's human display name. Load-bearing for the fuzzy addresses: a
+    // `special`/`title` resolve is only checkable if the caller can see WHICH
+    // page it landed on without a second round-trip. `.optional()` because a
+    // host predating the label fill omits it and this is a STRICT object.
+    label: z.string().optional(),
     // Canonical permalink (null when the platform cannot re-derive one).
     frontend_url: z.string().nullable(),
     // G-A2: the matched YT type/condition for a theme template
-    // (e.g. "archive-gloeckle_help", "taxonomy-category_faq"), else null for a
+    // (e.g. "archive-example_help", "taxonomy-category_faq"), else null for a
     // per-page layout.
     context: z.string().nullable(),
     // G-A2: which kind was resolved — a per-page layout vs. the governing theme
     // template — so the agent knows it reached the right surface.
     resolved_via: z.enum(['per_page', 'theme_template']),
+    // A-6: WHICH branch of the `target` object matched, echoed so the caller can
+    // tell the user how a fuzzy address (a title substring, a semantic special)
+    // was interpreted. `.optional()` is load-bearing: a `url` resolve and every
+    // host predating A-5 omit it, and this is a STRICT object.
+    matched_by: z.enum(TARGET_KEYS).optional(),
 });
-// ─── F5 + N5 (Glöckle HANDOFF-4/5) — render_preview ──────────────────
+// ─── F5 + N5 (customer HANDOFF-4/5) — render_preview ──────────────────
 //
 // The input shape (`template_id` OR `url`, exactly one — mirroring
 // page_get_layout's addressing) is assembled in `builders.ts` from the shared
@@ -516,7 +686,7 @@ export const PAGES_RESOLVE_OUTPUT_SCHEMA = z.object({
  *   - cache_purge_hint: the constant operator steer (purge Rocket/CDN after save).
  *   - template_id: echoed back (the resolved id the render ran on).
  *   - matched:    OPTIONAL — present ONLY when the caller passed `expect`; did the
- *                 rendered HTML contain that substring (Glöckle HANDOFF-6 #4).
+ *                 rendered HTML contain that substring (customer HANDOFF-6 #4).
  *   - snippet:    OPTIONAL — present ONLY when the caller passed `expect`; a
  *                 ~200-char window around the first match (or null when not
  *                 matched / the render threw). NULLABLE so the no-match case
@@ -529,13 +699,64 @@ export const RENDER_PREVIEW_OUTPUT_SCHEMA = z.object({
     error: z.string().optional(),
     cache_purge_hint: z.string(),
     template_id: z.string(),
-    // F5 + N5 / Glöckle HANDOFF-6 #4 — the optional `expect` substring check.
+    // F5 + N5 / customer HANDOFF-6 #4 — the optional `expect` substring check.
     // Both keys are emitted ONLY when the caller passed `expect`; declared here
     // (strict ZodObject → additionalProperties:false) so a strict host does not
     // -32602-reject the `expect` variant. `snippet` is nullable (null on a miss).
     matched: z.boolean().optional(),
     snippet: z.string().nullable().optional(),
 });
+// ─── 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 INPUT shape is assembled directly in `builders.ts` (template_id + a
+// local `mode` enum), mirroring render_preview/template_summary — only the
+// STRICT output schema lives here.
+/**
+ * Wire shape for `yootheme_builder_heading_outline` on success.
+ *
+ * STRICT (additionalProperties:false default ZodObject) — every field the
+ * handler puts in structuredContent MUST be declared here, or a strict MCP
+ * host -32602-rejects the SUCCESS.
+ *
+ *   - outline: every H1-H6 heading, in TRUE document order, each carrying its
+ *     TEXT and the source element that carries it (`element_type`/`path`).
+ *   - images: every image this pass sees (populated OR empty alt) — `alt` is
+ *     null for a missing/empty alt, the raw string otherwise; `is_generic_alt`
+ *     flags an exact match against the same generic-phrase list pages_audit's
+ *     `generic-alt-text` check uses ("logo", "image", "photo", ...).
+ *   - h1_count / has_level_skip / images_missing_alt: derived flags —
+ *     has_level_skip mirrors pages_audit's `heading-skip` check EXACTLY (a
+ *     level more than one above the highest seen so far, including a
+ *     document that OPENS below h1).
+ */
+export const HEADING_OUTLINE_OUTPUT_SCHEMA = z.object({
+    template_id: z.string(),
+    mode: z.enum(['builder', 'rendered']),
+    etag: z.string(),
+    outline: z.array(z.object({
+        level: z.string(),
+        text: z.string(),
+        element_type: z.string(),
+        path: z.string(),
+    })),
+    images: z.array(z.object({
+        alt: z.string().nullable(),
+        is_generic_alt: z.boolean(),
+        element_type: z.string(),
+        path: z.string(),
+    })),
+    h1_count: z.number().int().nonnegative(),
+    has_level_skip: z.boolean(),
+    images_missing_alt: z.number().int().nonnegative(),
+});
 // ─── Task 6 (pages_audit design, 2026-07-19) — shared FINDING/QUICK_CHECK ──
 //
 // Defined ONCE here — referenced by `pages_audit`'s own output schema AND
@@ -543,21 +764,94 @@ export const RENDER_PREVIEW_OUTPUT_SCHEMA = z.object({
 // the finding shape has exactly one source of truth across all three
 // surfaces (design §5-§7). Mirrors the PHP wire shape verbatim
 // (`PageAuditService::audit()` / `AuditCheck`'s partial-finding contract).
+/**
+ * The human-locatable address of ONE audit hit (B-3/B-5) — mirrors the PHP
+ * `FindingLocator::toArray()` wire shape. `path` stays the machine write
+ * address; `breadcrumb`/`element_type`/`element_name` are what a HUMAN needs
+ * to find the element in the customizer. Per the PHP null-key policy the
+ * optional members are OMITTED rather than sent as null.
+ *
+ * FAIL-SOFT BY CONSTRUCTION. `pages[]` rows used to ride through
+ * `.catchall(z.unknown())` untyped; now that `locators` is a typed array, a
+ * mismatch is no longer stripped — the MCP SDK THROWS `McpError`
+ * (InvalidParams) on an outputSchema violation, which fails the WHOLE audit
+ * call. So the optional members are `.nullish()` (an explicit `null` from a
+ * host that does not honour the omit-nulls policy must not be fatal) and the
+ * object carries a `.catchall`, so a field a future host version adds can
+ * never hard-fail an otherwise perfectly good audit.
+ *
+ * `repeat` is the one deliberately STRICT member: PHP emits it clamped to
+ * `>= 1` (`repeat: 0` is meaningless — a hit that renders zero times is not a
+ * hit), so `min(1)` states the real contract rather than tolerating a value
+ * that could only mean a producer bug.
+ */
+export const FINDING_LOCATOR = z
+    .object({
+    path: z.string(),
+    breadcrumb: z.string(),
+    element_type: z.string(),
+    element_name: z.string().nullish(),
+    heading_source: z.string().nullish(),
+    content_snippet: z.string().nullish(),
+    repeat: z.number().int().min(1),
+    prop: z.string().nullish(),
+    name: z.string().nullish(),
+})
+    .catchall(z.unknown());
 /**
  * One audit finding. `pages` carries per-page mini-evidence whose KEYS vary
  * by check code (`first_headline_path`, `alt_paths`, `cluster_id`,
  * `iterated`, `disabled_elements`, `elements_content`, ...) — `.catchall`
  * keeps every row's base `{id, label}` typed while tolerating the
  * check-specific extras without a per-code union.
+ *
+ * The ADDITIVE B-3/B-5 keys (`locators`, `hits_truncated`,
+ * `locators_stripped`, `builder_url`) are declared EXPLICITLY for
+ * self-documentation — the `.catchall` already tolerated them, but a named
+ * member states the contract. All stay `.optional()`: a host plugin predating
+ * B-3 emits none of them.
+ *
+ * `frontend_url` (T-B1, 2026-07-24) rides alongside `builder_url` on EVERY
+ * page entry now, not just the nine element-located "hit" checks — a
+ * theme/archive template with no public route legitimately omits it (never
+ * emitted as `null`), same convention as `builder_url`.
+ *
+ * `hits_truncated` and `locators_stripped` mean DIFFERENT things and are never
+ * interchangeable: the former says the upstream `hit_cap` dropped hits (so the
+ * raw `paths`/`alt_paths`/`skips`/`dead_anchors` arrays are incomplete), the
+ * latter says the transport's shrink-to-fit shed locator PROSE while leaving
+ * those arrays complete.
+ *
+ * FORWARD-COMPAT `.catchall`, for the same reason `FINDING_LOCATOR` carries one:
+ * the handler forwards each finding VERBATIM, and a strict object generates
+ * `additionalProperties:false`, so ONE additive field on the PHP side (an
+ * explicit hit total, a new evidence key) would make a strict host -32602-reject
+ * an otherwise perfect audit. Every declared member is still validated; only
+ * UNDECLARED ones ride through untyped.
  */
 export const FINDING = z.object({
     code: z.string(),
-    category: z.enum(['seo', 'structure', 'content', 'links']),
+    category: z.enum(['seo', 'structure', 'content', 'links', 'design']),
     severity: z.enum(['critical', 'warning', 'info']),
     title: z.string(),
     count: z.number().int().nonnegative(),
     pages: z.array(z
-        .object({ id: z.string(), label: z.string() })
+        .object({
+        id: z.string(),
+        label: z.string(),
+        locators: z.array(FINDING_LOCATOR).optional(),
+        // NAME-2: `count` is ambiguous ACROSS levels on this wire — it
+        // means PAGES on the finding and HITS on a page entry. The host
+        // therefore emits an unambiguous `hits` alias next to a page
+        // entry's `count` whenever that count really is a hit tally.
+        // Declared (not merely tolerated via `.catchall`) so the field
+        // is part of the contract and `hitCountOf` may prefer it.
+        hits: z.number().int().nonnegative().optional(),
+        hits_truncated: z.boolean().optional(),
+        locators_stripped: z.boolean().optional(),
+        builder_url: z.string().nullable().optional(),
+        frontend_url: z.string().nullable().optional(),
+    })
         .catchall(z.unknown())),
     pages_truncated: z.boolean(),
     // Machine-executable remediation (design §5): absent for findings with
@@ -569,7 +863,7 @@ export const FINDING = z.object({
         note: z.string(),
     })
         .optional(),
-});
+}).catchall(z.unknown());
 /**
  * The advisory block `page_publish` (default on) / `page_save`
  * (opt-in via `quick_check:true`) attach (Task 8). Design §7: `{clean:true}`
@@ -586,6 +880,35 @@ export const QUICK_CHECK = z.object({
  * spread in separately by `builders.ts` (mirrors PAGES_RESOLVE_INPUT).
  */
 export const PAGES_AUDIT_INPUT = {
+    // T-A2 (mega-push plan 2026-07-24-02): opt-in rendered-DOM audit. Default
+    // omitted = "builder", byte-identical to the pre-T-A2 sweep (reads the
+    // saved layout JSON tree; no `mode`/`render_scan`/`render_errors` keys on
+    // the response).
+    mode: z
+        .enum(['builder', 'rendered'])
+        .optional()
+        .describe('Audit 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 each page first (via the SAME engine render_preview uses) and ' +
+        'audits the ACTUAL DOM: a curated subset of checks (headings/alt/anchor-text/' +
+        'dead-anchor/design; NOT thin-content/duplicate-layout/empty-page, which need the ' +
+        'builder tree). This is the MOST valuable mode for the "design" category, since a ' +
+        'plugin form (Formidable/ACF) only exists at render time. Findings carry no builder ' +
+        'element path in this mode (empty breadcrumb/' +
+        'element_type by design, there is no builder node to point at); locate the hit by ' +
+        'its content_snippet or the page\'s builder_url/frontend_url instead. A SITE-wide ' +
+        'rendered sweep is capped (rendering is expensive); the response\'s render_scan ' +
+        '{attempted, rendered, capped} always says so honestly, and render_errors lists any ' +
+        'page whose render failed (excluded from findings, never reported as a false clean).'),
+    // A-6: scope the whole sweep to ONE page. Omit for the site-wide default.
+    // Site-wide checks that compare pages against EACH OTHER (duplicate-layout,
+    // title-collision) cannot run on a single page and self-filter out; the
+    // response says so in its `note`.
+    target: PAGES_TARGET.optional().describe('Audit ONE page instead of the whole site — by template_id, post_id, url, a ' +
+        'semantic special ("home", "blog", "404", "search", "category", "tag", ' +
+        '"author", "archive") or a title substring. The response then carries ' +
+        'scope:"single" + resolved_target (which page was actually audited) and ' +
+        'per-hit locators. Cannot be combined with `types`.'),
     types: z
         .array(z.string().min(1))
         .optional()
@@ -593,12 +916,28 @@ export const PAGES_AUDIT_INPUT = {
         'same `type` values yootheme_builder_pages_list rows carry). Default: every ' +
         'scanned template/page is included.'),
     checks: z
-        .array(z.enum(['seo', 'structure', 'content', 'links']))
+        .array(z.enum(['seo', 'structure', 'content', 'links', 'design']))
         .optional()
-        .describe('Run only these check categories (default: all four). "seo" = title-collision, ' +
+        .describe('Run only these check categories (default: all five). "seo" = title-collision, ' +
         'non-pretty-url, stale-content. "structure" = empty-page, missing-h1, ' +
-        'multiple-h1, no-headings, heading-skip. "content" = images-missing-alt, ' +
-        'thin-content, duplicate-layout. "links" = dead-anchor.'),
+        'multiple-h1, no-headings, heading-skip, heading-hidden-on-mobile (hidden at ' +
+        'the mobile-first UIkit breakpoint; Google indexes mobile-first, so this is ' +
+        'effectively invisible for ranking), long-heading. "content" = ' +
+        'images-missing-alt, generic-alt-text, thin-content, duplicate-layout. ' +
+        '"links" = dead-anchor, anchor-text-quality. "design" = design-missing-uikit-class, ' +
+        'design-foreign-class, design-inline-style: markup breaking out of the UIkit ' +
+        'design system (e.g. a plugin form submit button with no uk-button); most ' +
+        'valuable in mode:"rendered", where a plugin\'s own output actually exists — ' +
+        'plus header-contrast-risk (warning): the first section pulls the navigation ' +
+        'over itself (header_transparent) in a colour the theme\'s own --uk-inverse ' +
+        'declaration contradicts, with no image or video hiding the background that ' +
+        'declaration describes; and header-contrast-unverifiable (info): the same ' +
+        'transparent header over a hero image/video, whatever the colour — the medium ' +
+        'hides that background, so no colour is verifiable from the props, none is ' +
+        'recommended, and readability is only verifiable by looking at the rendered ' +
+        'page. Both are builder-mode only (section props do not exist ' +
+        'in a rendered document). Headings and image alt are also read from raw HTML ' +
+        '(html/text element content), not just builder props.'),
     thin_content_threshold: z
         .number()
         .int()
@@ -613,7 +952,17 @@ export const PAGES_AUDIT_INPUT = {
         .optional()
         .describe('Months since a page\'s `modified_at` after which it is flagged `stale-content`. ' +
         'Pages with an empty modified_at are never flagged. Default: 24.'),
-    max_chars: MAX_CHARS,
+    // PERF-4 / PROD-2: on THIS tool `max_chars` bounds BOTH legs — the shared
+    // describe's "structuredContent stays complete" is true everywhere else,
+    // but an audit's structured leg was measured at 349 KB (~89k tokens) for a
+    // site sweep, so it carries its own default ceiling
+    // ({@see STRUCTURED_BUDGET_CHARS}) that this argument raises or lowers.
+    max_chars: MAX_CHARS.describe('Optional cap (chars) on this result. Bounds BOTH the text leg and the ' +
+        'structuredContent payload (default: 48000 chars for structuredContent). ' +
+        'When the structured leg has to shrink, locator detail is shed before ' +
+        'evidence pages and the response carries structured_truncated:true. Raise ' +
+        'it for a complete pathological page, lower it on a tight context budget.'),
+    include_meta: INCLUDE_META_SCHEMA,
 };
 /**
  * Wire shape for `yootheme_builder_pages_audit` (design §5). `scanned.by_type`
@@ -623,6 +972,34 @@ export const PAGES_AUDIT_INPUT = {
  */
 export const PAGES_AUDIT_OUTPUT_SCHEMA = z.object({
     etag: z.string(),
+    // B-5 — the three single-target keys. `.optional()` is LOAD-BEARING, not
+    // decoration: this is a strict object, and both a site sweep and every
+    // host predating single-target mode omit all three, so a non-optional
+    // member would make every such (perfectly valid) response fail validation.
+    scope: z.string().optional(),
+    note: z.string().optional(),
+    // Every member of `PageQuery::descriptorFromRow()` /
+    // `augmentResolverDescriptor()` must be declared here — the audit handler
+    // forwards `resolved_target` VERBATIM, and this object generates
+    // `additionalProperties:false`, so an undeclared key makes a strict host
+    // -32602-reject a SUCCESSFUL call (W12-R2). All eight are `.optional()`
+    // because a host predating single-target mode sends none of them.
+    resolved_target: z
+        .object({
+        template_id: z.string().optional(),
+        post_id: z.union([z.number(), z.string()]).nullable().optional(),
+        type: z.string().optional(),
+        label: z.string().optional(),
+        frontend_url: z.string().nullable().optional(),
+        // The matched YT type/condition for a theme template
+        // (e.g. "taxonomy-category_faq"); null for a per-page layout.
+        context: z.string().nullable().optional(),
+        // `per_page` | `theme_template` — kept a plain string rather than an
+        // enum so a newer host's additional kind is forwarded, not rejected.
+        resolved_via: z.string().optional(),
+        matched_by: z.string().optional(),
+    })
+        .optional(),
     scanned: z.object({
         templates: z.number().int().nonnegative(),
         by_type: z.record(z.string(), z.number().int().nonnegative()),
@@ -634,5 +1011,36 @@ export const PAGES_AUDIT_OUTPUT_SCHEMA = z.object({
     }),
     findings: z.array(FINDING),
     disclaimer: z.string(),
+    // PERF-4 / PROD-2 — set by the TS handler (never by a host) when the shed
+    // ladder had to run to bring `structuredContent` under its char budget.
+    // Its PRESENCE is the whole signal: a complete payload omits the key
+    // entirely, so a reader can never mistake a shrunk audit for a full one.
+    // Which entries lost what is flagged in place — `locators_stripped` on the
+    // page rows whose locator prose went, `pages_truncated` on the findings
+    // whose evidence pages were capped or dropped.
+    structured_truncated: z.boolean().optional(),
+    // T-A2 — present ONLY when `mode:"rendered"` was requested (absent on the
+    // default builder sweep, matching `scope`'s own "absent means the old
+    // behaviour" convention). `render_scan` is ALWAYS present alongside it,
+    // even when the cap never engaged — Design-Nut 4's "never silent" rule:
+    // a caller can always see attempted vs. actually-rendered.
+    mode: z.enum(['rendered']).optional(),
+    render_scan: z
+        .object({
+        attempted: z.number().int().nonnegative(),
+        rendered: z.number().int().nonnegative(),
+        capped: z.boolean(),
+    })
+        .optional(),
+    // Present only when at least one template's render threw — excluded from
+    // findings entirely (a render failure must never masquerade as a content
+    // finding), surfaced here instead so nothing is silently dropped.
+    render_errors: z
+        .array(z.object({
+        id: z.string(),
+        label: z.string(),
+        error: z.string(),
+    }))
+        .optional(),
 });
 //# sourceMappingURL=schemas.js.map