@wootsup/yt-builder-mcp 1.12.0 → 2.1.0

package/dist/tools/pages/schemas.js

@@ -1,122 +1,131 @@
-/**
- * Page-tool output-schemas (Wave G.2 §4 structuredContent contracts).
- *
- * Split out of `src/tools/pages.ts` (Round-2 R2-A2-CRIT1) so the
- * handler files stay focused on logic.
- *
- * @license MIT
- */
 import { z } from 'zod';
-import { INCLUDE_META_SCHEMA } from '../shared-schemas.js';
-import { MAX_CHARS } from '../sparse-fields.js';
+import { PAGE_KIND_WORDS, VISIBILITY_WORDS } from '../format/pages-format.js';
+import { RESOLVED_LAYOUT_ID_OUTPUT, ETAG_PREVIEW_OPTIONAL, INCLUDE_META_SCHEMA } from '../shared-schemas.js';
+import { FIELD_COVERAGE_SCHEMA, MAX_CHARS } from '../sparse-fields.js';
+import { HOST_PROMPT_PROMISE } from '../tool-builder/confirm-preview.js';
+import { HOST_PROMPT_ANSWERS } from '../../proxy/confirm-question-contract.js';
+import { CMS_VISIBILITY_SCHEMA } from './write-output-schemas.js';
+const PAGE_ROW_SCHEMA = z
+    .object({
+    id: z.string().optional(),
+    label: z.string().optional(),
+    type: z.string().optional(),
+    elements_count: z.number().optional(),
+    modified_at: z.string().nullable().optional(),
+    frontend_url: z.string().nullable().optional(),
+    frontend_url_template: z.string().nullable().optional(),
+    frontend_url_description: z.string().nullable().optional(),
+    builder_url: z.string().nullable().optional(),
+    serves_context_kind: z.string().optional(),
+    serves_context_ids: z.array(z.number()).optional(),
+    page_role: z.string().optional(),
+    is_theme_template: z.boolean().optional(),
+    is_public_homepage: z.boolean().optional(),
+    kind: z.enum(PAGE_KIND_WORDS).optional(),
+    cms_status: z.string().optional(),
+    visibility: z.enum(VISIBILITY_WORDS).optional(),
+    visibility_reason: z.string().optional(),
+    visibility_note: z.string().optional(),
+    frontend_url_provisional: z.boolean().optional(),
+    frontend_url_note: z.string().optional(),
+})
+    .catchall(z.unknown());
 export const PAGES_LIST_OUTPUT_SCHEMA = z.object({
-    // F-Frontend-URL (2026-05-25): each row carries `frontend_url`,
-    // `frontend_url_template`, `frontend_url_description` so an MCP-agent
-    // can answer "What is the URL of my <type> template?" without a
-    // follow-up REST call or operator input. Server-side resolvers
-    // (WordPress: get_permalink/get_term_link/get_author_posts_url; Joomla:
-    // RouteHelper::getArticleRoute/getCategoryRoute/getTagRoute) emit one
-    // of two shapes per row:
-    //   - `frontend_url: <permalink>` + `frontend_url_template: null`
-    //     when a canonical public URL exists (latest post / first category
-    //     / first author etc.).
-    //   - `frontend_url: null` + `frontend_url_template: <pattern>` when
-    //     the URL needs a runtime parameter (search, 404-test) or when no
-    //     public content of the matching type exists yet.
-    // `frontend_url_description` is a short human hint ("Append any non-
-    // existent path to test." / "Latest published post — rendered with
-    // this template.") so the agent can render an instruction to the
-    // end-user. All three keys are kept on the row-record (not an extra
-    // schema object) so per-item sparse-field projection works.
-    //
-    // F33 (2026-06-10): each row also carries `builder_url` — a version-
-    // aware (WP YT4/YT5) + platform-aware (Joomla com_ajax) "open in the
-    // YOOtheme Pro builder" deep-link (or null when the host could not
-    // resolve the admin base). Kept on the row-record so per-item sparse-
-    // field projection + available_fields discovery surface it.
-    items: z.array(z.record(z.string(), z.unknown())),
+    items: z.array(PAGE_ROW_SCHEMA),
     total: z.number(),
-    // 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.
+    totals: z
+        .object({
+        content: z.number(),
+        theme_template: z.number(),
+        all: z.number(),
+        visibility: z
+            .object({
+            public: z.number().optional(),
+            hidden: z.number().optional(),
+            undetermined: z.number().optional(),
+            no_cms_status: z.number().optional(),
+        })
+            .optional(),
+    })
+        .optional(),
+    counting_note: z.string().optional(),
+    trashed_note: z.string().optional(),
+    hidden_count: z.number().optional(),
+    hidden_reason: z.string().optional(),
     returned: z.number().optional(),
     next_cursor: z.string().optional(),
     etag: z.string().optional(),
     projected_fields: z.array(z.string()).optional(),
-    // F-004 fix (2026-05-25 exhaustive audit): projection-feedback —
-    // emitted ONLY when the caller passed `fields[]`. `available_fields`
-    // is the discovered top-level field vocabulary; `unknown_fields` is
-    // the subset of requested fields that did NOT appear in any item
-    // (previously: items came back as `[{}, {}, …]` silently).
     available_fields: z.array(z.string()).optional(),
+    available_fields_by_kind: z.record(z.string(), z.array(z.string())).optional(),
     unknown_fields: z.array(z.string()).optional(),
-    // F23 (2026-06-10): the LOUD unknown-projection warning also rides in
-    // structuredContent — hosts that surface structuredContent (not the
-    // text leg) to the model would otherwise never see it.
+    field_coverage: FIELD_COVERAGE_SCHEMA,
     projection_warning: z.string().optional(),
+    sorted_over: z
+        .string()
+        .optional()
+        .describe('Scope the `sort` actually covered: `all` (the whole filtered set) or ' +
+        '`this_page` (only the rows returned here). Present only when `sort` was passed.'),
+    sort_note: z
+        .string()
+        .optional()
+        .describe('Present only when `sorted_over` is `this_page`: says that the newest row here ' +
+        'is not necessarily the newest on the site.'),
+    visibility_note: z
+        .string()
+        .optional()
+        .describe('Present only when some row carries `visibility:"undetermined"`: explains that the ' +
+        'word means "the CMS status does not hide it", which is not proof a visitor ' +
+        'FINDS it. On Joomla an unrouted page is still served on its own direct URL.'),
+    visibility_filter_note: z.string().optional(),
+    default_row_note: z.string().optional(),
+    text_leg_note: z.string().optional(),
+    fields_hint: z
+        .string()
+        .optional()
+        .describe('Present only on a large, unfiltered answer: suggests narrowing with `fields` (see ' +
+        '`available_fields`) or paging with `limit`/`cursor`.'),
 });
-export const SCHEMA_OUTPUT_SCHEMA = z.object({
-    // F-006 (2026-05-26): `rel_path` is the agent-preferred path form
-    // (matches `element_list` + `page_get_layout` emit). `path` (the
-    // fully-qualified `/templates/<id>/layout/...` pointer) stays on the
-    // row for back-compat but is optional so callers reading the schema
-    // know `rel_path` is the canonical projection column.
-    //
-    // 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.
-    items: z.array(z
-        .object({
-        rel_path: z.string().optional(),
-        path: z.string().optional(),
-        element_type: z.string().optional(),
-        label: z.string().optional(),
-        has_binding: z.boolean().optional(),
-    })
-        .passthrough()),
-    total: z.number(),
-    template_id: z.string(),
-    // G-B: `fields[]` projection echo + the F23 unknown-field feedback,
-    // emitted ONLY when the caller passed `fields[]`.
-    projected_fields: z.array(z.string()).optional(),
+const PAGE_GET_LAYOUT_ENVELOPE = z
+    .object({
+    ...RESOLVED_LAYOUT_ID_OUTPUT,
+    layout_id: z.string().optional(),
+    etag: z.string().optional(),
+    layout_root_pointer: z.string().optional(),
+    pointer_hint: z.string().optional(),
+    layout: z.unknown().optional(),
+    elements: z.array(z.record(z.string(), z.unknown())).optional(),
+    named_sections: z.unknown().optional(),
+    outline_text: z.string().optional(),
+    mode: z.string().optional(),
+    unchanged: z.boolean().optional(),
+    note: z.string().optional(),
+    total_elements: z.number().optional(),
+    warning: z.string().optional(),
     available_fields: z.array(z.string()).optional(),
+    available_fields_by_kind: z.record(z.string(), z.array(z.string())).optional(),
     unknown_fields: z.array(z.string()).optional(),
+    field_coverage: FIELD_COVERAGE_SCHEMA,
     projection_warning: z.string().optional(),
+    projected_fields: z.array(z.string()).optional(),
+    label_note: z.string().optional(),
+    modules_on_page: z.unknown().optional(),
+    modules_on_page_unavailable: z.unknown().optional(),
+    fields_not_applied: z.unknown().optional(),
+})
+    .catchall(z.unknown());
+export const PAGE_GET_LAYOUT_OUTPUT_SCHEMA = PAGE_GET_LAYOUT_ENVELOPE.refine((value) => Object.keys(PAGE_GET_LAYOUT_ENVELOPE.shape).some((key) => value[key] !== undefined), {
+    message: 'a page_get_layout answer carries at least one declared envelope key — every measured '
+        + 'branch does (layout_id / elements / unchanged / mode). An answer made only of '
+        + 'catchall keys means the envelope was lost.',
 });
 export const ETAG_OUTPUT_SCHEMA = z.object({
     etag: z.string(),
     generated_at: z.string().optional(),
 });
-// F-AUDIT-2 (2026-05-26): template_summary outputSchema. The handler
-// passes the REST `/pages/{id}/summary` body through verbatim via
-// `jsonResult(data)`. Live shape verified against the WP+Joomla dev
-// hosts: `template_id`, `counts_by_type` (open-ended map element-type
-// → count), `bound_count`, `max_depth`, `total`, `named_sections` (each
-// `{path, name}`), and the `etag` string. NOTE: `_meta` is merged at
-// 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().optional(),
+    ...RESOLVED_LAYOUT_ID_OUTPUT,
+    layout_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(),
@@ -127,40 +136,13 @@ export const TEMPLATE_SUMMARY_OUTPUT_SCHEMA = z.object({
         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),
-    // unbound-image-alt-gap count, and disabled-element count. Reuses the
-    // SAME `LayoutAuditExtractor` pass `pages_audit` runs. `.optional()` so
-    // 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(),
-    // 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(),
@@ -172,40 +154,11 @@ export const TEMPLATE_SUMMARY_OUTPUT_SCHEMA = z.object({
         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(),
+    forbidden: z.array(z.string()).optional(),
 });
-// ─── C1 — pages_create + pages_delete (v1.2) ──────────────────────────
-//
-// MCP tool schemas wrapping the Phase B REST endpoints:
-//   POST   /pages           → yootheme_builder_pages_create
-//   DELETE /pages/{post_id} → yootheme_builder_pages_delete
-//
-// These schemas drive (a) input validation at the MCP boundary and (b)
-// the structured-content outputSchema for client introspection.
-/**
- * Input shape for `yootheme_builder_pages_create`.
- *
- * Mirrors the args of `POST /pages` (Phase B).
- *
- * Design pins:
- *   - `post_type` is intentionally NOT exposed. Layer 9 defensive guard
- *     on the REST side rejects it server-side; surfacing it at the MCP
- *     boundary would invite a footgun where an agent tries to set it
- *     and fails confusingly.
- *   - `status` defaults to `draft` on the server (Q6 design — no public
- *     empty page).
- *   - `dry_run` triggers validation Layers 1+2+4 without persisting.
- */
 export const PAGES_CREATE_INPUT = {
     title: z
         .string()
@@ -222,14 +175,6 @@ export const PAGES_CREATE_INPUT = {
         'WordPress accepts all five; Joomla maps draft→state 0 / publish→state 1 ' +
         '(the other three are WP-only). For the common make-it-live case prefer ' +
         'the `published` boolean below.'),
-    // F12 (2026-06-09): friendly one-boolean publish shortcut. A fresh
-    // draft on Joomla returns 404 to anonymous front-end visitors (state
-    // 0); there was no ergonomic MCP path to flip it live. `published`
-    // maps to the existing `status` field the PHP host already honours
-    // (WP post_status=publish, Joomla state=1) — see the handler. Default
-    // false keeps the safe "no public empty page" behaviour. When the
-    // caller sets an explicit `status`, that wins (published is the
-    // shortcut, not an override).
     published: z
         .boolean()
         .default(false)
@@ -237,20 +182,16 @@ export const PAGES_CREATE_INPUT = {
         'Joomla state=1) so anonymous visitors can render it immediately. ' +
         'Default false: created as a draft, visible only in the builder until ' +
         'you publish. Ignored when an explicit `status` is provided.'),
-    // F64 (2026-06-10): Joomla-only routing helper. A published Joomla
-    // article without a menu item has NO SEF route (anonymous 404). When
-    // truthy AND the article is published, the host creates a
-    // com_content single-article menu item via the Joomla Menu-Table API
-    // under a dedicated HIDDEN menutype (string value picks the
-    // menutype; `mainmenu` is rejected server-side so customer
-    // navigation is never polluted). Ignored on WordPress.
     menu_item: z
         .union([z.boolean(), z.string().min(1).max(64)])
         .optional()
         .describe('Joomla only: create a SEF route for the new article. true = ' +
         'hidden default menutype; a string picks the menutype ' +
         '("mainmenu" is rejected). Requires published/status=publish. ' +
-        'Without a route a published Joomla article 404s for visitors.'),
+        'Without a route the SEF url 404s, but the article still ' +
+        'answers 200 on its raw ?option=com_content&view=article&id=N ' +
+        'url: a missing menu item costs findability, never privacy. ' +
+        'To keep an article non-public set its state or its access level.'),
     layout: z
         .record(z.string(), z.unknown())
         .optional()
@@ -259,118 +200,58 @@ export const PAGES_CREATE_INPUT = {
         .boolean()
         .optional()
         .describe('When true, runs validation Layers 1+2+4 without persisting.'),
-    // post_type intentionally NOT exposed — Layer 9 defensive guard rejects
-    // it server-side. Exposing it would invite footgun attempts.
 };
-/**
- * Wire shape for `yootheme_builder_pages_create` on success (non-dry-run).
- *
- * Mirrors the REST 201 response shape.
- *
- * Design pins:
- *   - `frontend_url` is nullable: REST returns null for fresh drafts
- *     before publish.
- *   - `template_id` is a plain string. The "page:{post_id}" prefix is
- *     enforced server-side; adding a `.startsWith()` here would buy no
- *     MCP-client value while adding Zod complexity.
- *   - `warnings` is a lean string array (e.g. "slug_collision_resolved"
- *     when WP auto-appends `-2`). The REST surface may expand this to
- *     richer objects in v1.3; strings keep the v1.2 surface minimal.
- */
 export const PAGES_CREATE_OUTPUT_SCHEMA = z
     .object({
-    // E1 cross-platform divergence: WP returns `page_id`, Joomla returns
-    // `article_id`. Both are positive ints; at least one is always present.
     page_id: z.number().int().positive().optional(),
     article_id: z.number().int().positive().optional(),
     title: z.string(),
     slug: z.string(),
     status: z.string(),
     frontend_url: z.string().nullable(),
-    // F33 (2026-06-10): "open in the YOOtheme Pro builder" deep-link for
-    // the freshly-created page/article. Version-aware (WP YT4/YT5) +
-    // platform-aware (Joomla com_ajax). Nullable: null when the host
-    // could not resolve the admin base. `.optional()` keeps the schema
-    // back-compatible with an older host that predates the field.
     builder_url: z.string().nullable().optional(),
-    template_id: z
+    layout_id: z
         .string()
-        .describe('Synthetic per-page template id, e.g. "page:3275" (WP) or "article:42" (Joomla).'),
+        .describe('Synthetic per-page layout id, e.g. "page:3275" (WP) or "article:42" (Joomla).'),
     etag: z.string(),
     warnings: z
         .array(z.string())
         .describe('e.g. "slug_collision_resolved" when slug collision was resolved.'),
 })
     .refine((v) => typeof v.page_id === 'number' || typeof v.article_id === 'number', { message: 'response must contain either page_id (WP) or article_id (Joomla)' });
-/**
- * Wire shape for `yootheme_builder_pages_create` when `dry_run:true`.
- *
- * Design pin: NO `etag` field. The B6 fix-cycle decision was that
- * surfacing a "live" ETag with a dry-run response invites a stale-
- * If-Match footgun (caller pins the ETag, then non-dry-run mutates,
- * stale ETag rejected with 412). Dry-run is validation-only.
- *
- * `template_id_pattern` is a literal — the actual `template_id` cannot
- * be materialised before WP allocates the post_id.
- */
 export const PAGES_CREATE_DRY_RUN_OUTPUT_SCHEMA = z.object({
     dry_run: z.literal(true),
     would_create: z.object({
         title: z.string(),
         slug: z.string(),
         status: z.string(),
-        // E1 cross-platform divergence: WP returns 'page:{post_id}', Joomla returns 'article:{article_id}'.
-        template_id_pattern: z.enum(['page:{post_id}', 'article:{article_id}']),
+        layout_id_pattern: z.enum(['page:{post_id}', 'article:{article_id}']),
     }),
     validation_report: z.object({
         layer_1_structural: z.literal('passed'),
         layer_2_element_types: z.literal('passed'),
         layer_4_renderer: z.literal('passed'),
     }),
-    // No `etag` field — by design (see B6 fix-cycle: stale-If-Match footgun).
 });
-/**
- * Input shape for `yootheme_builder_pages_delete`.
- *
- * Mirrors the args of `DELETE /pages/{post_id}` (Phase B).
- *
- * Design pin: `confirm` is `z.literal(true)`. This is the Zod-side
- * enforcement of the confirm gate — the MCP boundary rejects requests
- * without `confirm:true` before they ever hit the REST layer.
- *
- * `force` defaults to false server-side → wp_delete_post(trash). When
- * true → hard delete (irrecoverable).
- */
 export const PAGES_DELETE_INPUT = {
-    post_id: z
-        .number()
-        .int()
-        .positive()
-        .describe('ID of the page/article to delete — WordPress post_id or Joomla article_id ' +
-        '(the numeric part of the template_id, e.g. 42 for "article:42").'),
+    layout_id: z
+        .union([z.string().min(1), z.number().int().positive()])
+        .describe('Which layout: "page:42", "article:12", "default", or a bare id (42). '
+        + 'Use yootheme_builder_pages_list to discover.'),
     confirm: z
-        .literal(true)
-        .describe('Must be true. Confirm gate prevents accidental deletes.'),
-    force: z
         .boolean()
         .optional()
-        .describe('If true, hard-deletes (wp_delete_post force=true). Default: trash (recoverable).'),
+        .describe('Must be true to actually delete. LEAVE IT OUT (or send false) to get a '
+        + 'preview instead: the server answers 200 with what would be lost (label, '
+        + 'elements_count, what happens to media) plus the intents this page\'s current '
+        + 'state allows, and deletes nothing. '
+        + HOST_PROMPT_PROMISE),
+    intent: z
+        .string()
+        .optional()
+        .describe('What "remove" means here. Call without it once and the server lists the intents ' +
+        'possible for this page\'s CURRENT state, in the words of its CMS.'),
 };
-// ─── P-G (Goldstandard wave 3) — page_dynamize ────────────────────────
-//
-// The composite "dynamize an existing designed layout" write. The recipe
-// of `dynamize-existing-layout.md` encoded server-side — the agent supplies
-// ONLY the language-level inputs (which list source, which leaf maps to
-// which flow field). F98 HYBRID EXECUTION: server runs the deterministic
-// steps (copy byte-identically, swap queries + leaf names, keep everything
-// else), reaching 85-95% compliance vs 60-70% for instruction-only.
-/**
- * A single `leaf_map` / `conditions` value — the F96 FieldMappingValue
- * shape reused verbatim (mirrors `field_mappings` in `sources/builders.ts`):
- * EITHER a plain string (the new flat field name) OR a structured
- * `{name, filters?}` carrying an explicit YT5 filters operator (e.g. a
- * `_condition` `{condition:'!!'}` or a date format `{date:'D, d.m.y'}`).
- */
 const FIELD_MAPPING_VALUE = z.union([
     z.string(),
     z
@@ -385,20 +266,18 @@ const FIELD_MAPPING_VALUE = z.union([
     })
         .strict(),
 ]);
-/**
- * Input shape for `yootheme_builder_page_dynamize`. Wraps
- * `POST /pages/dynamize`. Narrowest-schema rule: `template_id` +
- * `list_source_name` + `page.title` are required non-empty; `page` carries
- * the create-machinery passthrough; the reference selector is `section_name`
- * OR `element_path` (exactly-one is enforced server-side so a miss can list
- * the available named sections as remediation).
- */
-export const PAGE_DYNAMIZE_INPUT = {
-    template_id: z
+export const PAGE_GENERATE_DYNAMIC_INPUT = {
+    layout_id: z
         .string()
         .min(1)
-        .describe('Template holding the REFERENCE section (e.g. "default"). ' +
+        .describe('The layout holding the REFERENCE section (e.g. "default"). ' +
         'Use yootheme_builder_pages_list / yootheme_builder_template_summary to discover.'),
+    output: z
+        .enum(['new_page'])
+        .describe('Where the dynamized result lands. "new_page" (the only value today) creates a ' +
+        'NEW, unpublished, unlinked page from the reference — it never rewrites the ' +
+        'reference itself. A later "in_place" value (editing the reference page ' +
+        'directly) is not yet available.'),
     section_name: z
         .string()
         .min(1)
@@ -411,7 +290,9 @@ export const PAGE_DYNAMIZE_INPUT = {
         .min(1)
         .optional()
         .describe('JSON-Pointer / rel-path to the reference subtree (e.g. "/children/2"). ' +
-        'Provide THIS or `section_name` — exactly one.'),
+        'Provide THIS or `section_name` — exactly one. The path must satisfy the ' +
+        'same section→row→column hierarchy as a new page (`scaffold_section` ' +
+        'builds a hull).'),
     list_source_name: z
         .string()
         .min(1)
@@ -421,10 +302,6 @@ export const PAGE_DYNAMIZE_INPUT = {
         '(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
-    // leaf_map. Provide THIS or `list_source_name` — exactly one.
     source_map: z
         .array(z
         .object({
@@ -499,13 +376,7 @@ export const PAGE_DYNAMIZE_INPUT = {
             .describe('Joomla only: create a SEF route. true = hidden menutype; a string picks it.'),
     })
         .describe('Passthrough to the existing create machinery (slug-collision, menu_item routing).'),
-    etag: z
-        .string()
-        .min(1)
-        .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.
+    etag: ETAG_PREVIEW_OPTIONAL.optional(),
     dry_run: z
         .boolean()
         .optional()
@@ -514,57 +385,248 @@ export const PAGE_DYNAMIZE_INPUT = {
         '(etag == new_etag). Inspect summary.queries_swapped / unmatched_map_keys ' +
         'before the real call.'),
 };
-/**
- * Wire shape for `yootheme_builder_pages_delete` on success.
- *
- * `deleted` is `z.literal(true)` — the success-response invariant. A
- * failed delete surfaces as `isError:true` with a structured-error
- * envelope, not as `deleted:false`.
- */
 export const PAGES_DELETE_OUTPUT_SCHEMA = z
     .object({
-    deleted: z.literal(true),
-    // E1 cross-platform divergence: WP returns page_id, Joomla returns article_id.
+    ...RESOLVED_LAYOUT_ID_OUTPUT,
+    deleted: z.boolean(),
+    dry_run: z.literal(true).optional(),
+    already_trashed: z.literal(true).optional(),
+    note: z.string().optional(),
+    article_state: z.number().int().optional(),
     page_id: z.number().int().positive().optional(),
     article_id: z.number().int().positive().optional(),
-    force_deleted: z.boolean(),
-    etag: z.string(),
-    // G2 / C0 (changed-path-on-write): every successful mutation now also
-    // carries the post-write etag + the JSON-Pointer / template-id path(s)
-    // it touched. pages_delete forwards the PHP body VERBATIM via
-    // structuredResult, so these MUST be declared here — the host
-    // validates structuredContent under additionalProperties:false and a
-    // SUCCESS would otherwise trip -32602. Optional for back-compat.
+    post_id: z.number().int().positive().optional(),
+    post_type: z.string().optional(),
+    force_deleted: z.boolean().optional(),
+    etag: z.string().optional(),
     new_etag: z.string().optional(),
     changed_paths: z.array(z.string()).optional(),
+    label: z.string().nullable().optional(),
+    element_count: z.number().int().nonnegative().nullable().optional(),
+    has_dynamic_binding: z.boolean().optional(),
+    impact_note: z.string().optional(),
+    binding_note: z.string().nullable().optional(),
+    next_step: z.string().optional(),
+    preview: z.literal(true).optional(),
+    step_reversible: z.boolean().optional(),
+    host_prompt: z.enum(HOST_PROMPT_ANSWERS).optional(),
+    requires_confirm: z.literal(true).optional(),
+    requires_confirmation: z.literal(true).optional(),
+    operation: z.string().optional(),
+    warning: z.string().optional(),
+    hint: z.string().optional(),
+    received_confirm: z.unknown().optional(),
+    received_confirm_type: z.string().optional(),
+    expected_confirm: z.string().optional(),
+    layout_id: z.string().optional(),
+    elements_count: z.number().int().nonnegative().optional(),
+    elements_count_note: z.string().optional(),
+    media_note: z.string().optional(),
+    menu_item_ids: z.array(z.number().int().positive()).optional(),
+    menu_items_note: z.string().optional(),
+    applied: z.literal(false).optional(),
+    requires_intent: z.literal(true).optional(),
+    given_intent: z.string().optional(),
+    current_state: z.string().optional(),
+    intents: z
+        .array(z.object({
+        intent: z.string(),
+        effect: z.string(),
+        reversible: z.boolean(),
+        native_name: z.string(),
+        restore_call: z.string().nullable().optional(),
+        restore_state_note: z.string().nullable().optional(),
+        undo: z.string(),
+    }))
+        .optional(),
+    notes: z.array(z.string()).optional(),
+    instruction: z.string().optional(),
+    reads_degraded: z
+        .array(z.enum(['label', 'elements']))
+        .optional()
+        .describe('Reads that did not answer, so the fields they back are NOT measured. '
+        + '"label" backs `label` (null here means "could not read", not "no title"). '
+        + '"elements" backs `element_count`, `has_dynamic_binding` and `binding_note` '
+        + '(has_dynamic_binding defaults to false, so on a degraded read it reads as '
+        + '"no binding" rather than "unknown" — the more dangerous direction before a '
+        + 'delete). Absent when both reads answered.'),
 })
-    .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`.
- */
+    .superRefine((v, ctx) => {
+    if (v.requires_confirmation === true) {
+        if (v.deleted !== false) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['deleted'],
+                message: 'a confirm preview must report deleted:false — nothing was removed',
+            });
+        }
+        if (!Array.isArray(v.intents) || v.intents.length === 0) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['intents'],
+                message: 'a confirm preview must carry the intents this state allows — without them '
+                    + 'the caller cannot form the follow-up call it is being asked to make',
+            });
+        }
+        if (typeof v.page_id !== 'number' && typeof v.article_id !== 'number') {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['page_id'],
+                message: 'response must contain either page_id (WP) or article_id (Joomla)',
+            });
+        }
+        return;
+    }
+    if (v.dry_run === true) {
+        if (v.deleted !== false) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['deleted'],
+                message: 'a dry_run preview must report deleted:false — nothing was written',
+            });
+        }
+        if (typeof v.post_id !== 'number') {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['post_id'],
+                message: 'a dry_run preview must echo the post_id it previewed',
+            });
+        }
+        return;
+    }
+    if (v.requires_intent === true) {
+        if (v.deleted !== false) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['deleted'],
+                message: 'a discovery answer must report deleted:false — nothing was removed',
+            });
+        }
+        if (!Array.isArray(v.intents) || v.intents.length === 0) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['intents'],
+                message: 'a discovery answer must carry the options it was asked for',
+            });
+        }
+        return;
+    }
+    if (v.already_trashed === true) {
+        if (v.deleted !== false) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['deleted'],
+                message: 'an already-trashed report must say deleted:false — nothing was removed',
+            });
+        }
+        if (typeof v.note !== 'string' || v.note.length === 0) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['note'],
+                message: 'an already-trashed report must name the state and what to call next',
+            });
+        }
+        if (typeof v.page_id !== 'number' && typeof v.article_id !== 'number') {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['page_id'],
+                message: 'response must contain either page_id (WP) or article_id (Joomla)',
+            });
+        }
+        return;
+    }
+    if (v.deleted !== true) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['deleted'],
+            message: 'a carried-out delete must report deleted:true (a failure is isError, not deleted:false)',
+        });
+    }
+    if (typeof v.force_deleted !== 'boolean') {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['force_deleted'],
+            message: 'a carried-out delete must say whether it was permanent',
+        });
+    }
+    if (typeof v.page_id !== 'number' && typeof v.article_id !== 'number') {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['page_id'],
+            message: 'response must contain either page_id (WP) or article_id (Joomla)',
+        });
+    }
+    if (typeof v.etag !== 'string') {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['etag'],
+            message: 'a carried-out delete must carry the post-write etag',
+        });
+    }
+});
+export const PAGES_SET_STATUS_INPUT = {
+    layout_id: z
+        .union([z.string().min(1), z.number().int().positive()])
+        .describe('Which layout: "page:42", "article:12", "default", or a bare id (42). '
+        + 'Use yootheme_builder_pages_list to discover.'),
+    status: z
+        .enum([
+        'publish', 'draft', 'pending', 'private', 'future',
+        'published', 'unpublished', 'archived',
+    ])
+        .describe('The CMS status, in YOUR platform\'s own words. WordPress: publish, draft, '
+        + 'pending, private, future. Joomla: published, unpublished, archived. A status '
+        + 'from the other platform is refused (422) with the list valid HERE — no '
+        + 'translation happens. To trash or delete a page use '
+        + 'yootheme_builder_pages_delete (it carries the confirm gate); no status value '
+        + 'deletes anything. A page already IN the trash is refused (409) — restore it '
+        + 'in the CMS first, which is what puts its original URL back. '
+        + 'This write takes NO `etag` and is last-one-wins — nothing detects a competing '
+        + 'change. The `etag` it RETURNS is the post-write layout etag, for chaining into '
+        + 'your next LAYOUT write.'),
+};
+export const PAGES_SET_STATUS_OUTPUT_SCHEMA = z.object({
+    ...RESOLVED_LAYOUT_ID_OUTPUT,
+    post_id: z.number().int().positive(),
+    article_id: z.number().int().positive().optional(),
+    layout_id: z.string(),
+    post_type: z.string().optional(),
+    status: z.string(),
+    previous_status: z.string(),
+    changed: z.boolean(),
+    requested_status: z.string(),
+    warnings: z.array(z.string()),
+    changed_paths: z.array(z.string()).optional(),
+    etag: z.string(),
+    new_etag: z.string(),
+    findable_by_visitor: z.boolean().nullable(),
+    cms_visibility: CMS_VISIBILITY_SCHEMA.optional(),
+    cms_warning: z.string().optional(),
+    frontend_url: z.string().optional(),
+    frontend_url_provisional: z.boolean().optional(),
+    frontend_url_note: z.string().optional(),
+});
+export const PAGES_RESTORE_INPUT = {
+    layout_id: z
+        .union([z.string().min(1), z.number().int().positive()])
+        .describe('Which layout: "page:42", "article:12", "default", or a bare id (42). '
+        + 'Use yootheme_builder_pages_list to discover. Not currently trashed → refused (409).'),
+};
+export const PAGES_RESTORE_OUTPUT_SCHEMA = z.object({
+    ...RESOLVED_LAYOUT_ID_OUTPUT,
+    restored: z.boolean(),
+    post_id: z.number().int().positive(),
+    article_id: z.number().int().positive().optional(),
+    post_type: z.string().optional(),
+    status: z.string(),
+    restored_from: z.literal('trash').or(z.literal('trashed')),
+    changed_paths: z.array(z.string()).optional(),
+    etag: z.string(),
+    new_etag: z.string(),
+    note: z.string(),
+    frontend_url: z.string().optional(),
+});
 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',
@@ -617,9 +679,6 @@ export const PAGES_TARGET = z
     '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)
@@ -633,112 +692,49 @@ export const PAGES_RESOLVE_INPUT = {
         '"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`
-    // (page_get_layout, page_get_schema, element_*): a `page:<id>` (WP) /
-    // `article:<id>` (Joomla) token for a per-page layout, OR the raw
-    // `templates.<id>` key for a governing THEME TEMPLATE (G-A2).
-    template_id: z.string(),
-    // The resolved integer post-id (WP) / article-id (Joomla) for a per-page
-    // layout, or NULL for a theme template (an archive URL has no single post).
+    layout_id: z.string(),
     post_id: z.number().int().positive().nullable(),
-    // 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-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 (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
-// TEMPLATE_ID_OPTIONAL + RESOLVE_URL schemas, the same way pages_resolve /
-// page_get_layout do. Only the STRICT output schema lives here.
-/**
- * Wire shape for `yootheme_builder_render_preview` 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 (the structured-content-shape-pin guard
- * enforces this).
- *
- *   - rendered:   the in-process Builder render did NOT throw.
- *   - item_count: count of rendered repeat-source items (`el-item` rows).
- *   - empty:      the rendered HTML is empty / whitespace-only.
- *   - error:      OPTIONAL — present ONLY when the render threw; the otherwise-
- *                 swallowed YOOtheme render message.
- *   - 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 (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
- *                 validates under the strict schema.
- */
 export const RENDER_PREVIEW_OUTPUT_SCHEMA = z.object({
+    ...RESOLVED_LAYOUT_ID_OUTPUT,
     rendered: z.boolean(),
-    item_count: z.number().int().nonnegative(),
+    rendered_item_wrapper_count: z.number().int().nonnegative(),
+    rendered_item_wrapper_count_note: z.string().optional(),
     empty: z.boolean(),
+    fallback_used: z.boolean(),
+    dropped_count: z.number().int().nonnegative(),
+    dropped_count_note: z.string().optional(),
     error: z.string().optional(),
     cache_purge_hint: z.string(),
-    template_id: z.string(),
-    // 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).
+    layout_id: z.string(),
+    source_item_counts: z.record(z.string(), z.number().int().nonnegative()),
+    unresolved_sources: z.array(z.string()).optional(),
     matched: z.boolean().optional(),
     snippet: z.string().nullable().optional(),
+    match_conclusive: z.boolean().optional(),
+    match_note: z.string().optional(),
+    mismatch_hints: z.array(z.string()).optional(),
+    stored_but_not_rendered: z
+        .object({
+        elements: z.array(z.object({
+            path: z.string(),
+            source_name: z.string(),
+        })),
+        note: z.string(),
+    })
+        .optional(),
+    cms_status: z.string().optional(),
+    cms_status_note: z.string().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(),
+    ...RESOLVED_LAYOUT_ID_OUTPUT,
+    layout_id: z.string(),
     mode: z.enum(['builder', 'rendered']),
     etag: z.string(),
     outline: z.array(z.object({
@@ -756,35 +752,9 @@ export const HEADING_OUTLINE_OUTPUT_SCHEMA = z.object({
     h1_count: z.number().int().nonnegative(),
     has_level_skip: z.boolean(),
     images_missing_alt: z.number().int().nonnegative(),
+    render_fallback_used: z.boolean().optional(),
+    render_dropped_count: z.number().int().nonnegative().optional(),
 });
-// ─── Task 6 (pages_audit design, 2026-07-19) — shared FINDING/QUICK_CHECK ──
-//
-// Defined ONCE here — referenced by `pages_audit`'s own output schema AND
-// (Task 8) `page_publish` / `page_save`'s additive `quick_check` block, so
-// 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(),
@@ -798,64 +768,26 @@ export const FINDING_LOCATOR = z
     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', 'design']),
     severity: z.enum(['critical', 'warning', 'info']),
     title: z.string(),
-    count: z.number().int().nonnegative(),
+    affected_pages: z.number().int().nonnegative(),
     pages: z.array(z
         .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(),
+        occurrences_here: z.number().int().nonnegative().optional(),
+        bound_gaps_not_counted: 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
-    // NO safe auto-fix (duplicate-layout, title-collision — human decision).
+    finding_pages_truncated: z.boolean(),
     fix_hint: z
         .object({
         tool: z.string(),
@@ -864,46 +796,43 @@ export const FINDING = z.object({
     })
         .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}`
- * on zero findings, else `{findings, note}` pointing at `pages_audit` for
- * the site-wide (scope==='site') checks this per-page pass does not run.
- */
 export const QUICK_CHECK = z.object({
     clean: z.boolean().optional(),
     findings: z.array(FINDING).optional(),
     note: z.string().optional(),
 });
-/**
- * Input shape for `yootheme_builder_pages_audit` (design §5). `site_id` is
- * 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. ' +
+        'module/widget output and anything a plugin injects only at render time — the ' +
+        'response names the checks that blindness affects in ' +
+        '`checks_limited_to_saved_layout`, so a 0 from one of them reads as "0 in the ' +
+        'stored layout" rather than "0 on the page". ' +
         '"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 ' +
+        'audits the ACTUAL DOM. It runs a SUBSET of the checks, so a code that is not in ' +
+        'that subset reports nothing here — "0 found" and "0 checked" are different ' +
+        'answers, and the response says which one you got in `checks_not_run`. These do ' +
+        'NOT run in "rendered" (each needs the stored builder tree): ' +
+        'empty-page, dangling-source, unknown-source-fields, container-missing-item-child, ' +
+        'binding-renders-nothing, heading-hidden-on-mobile, thin-content, duplicate-layout, ' +
+        'title-collision, non-pretty-url, stale-content, header-contrast-risk, ' +
+        'header-contrast-unverifiable. ' +
+        '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`.
+        '{attempted, rendered, capped} always says so honestly and, when the cap engaged, ' +
+        'skipped_by_cap NAMES the templates it skipped, so the gap can be closed with a ' +
+        'types-narrowed re-run. render_errors lists any ' +
+        'page whose render failed (excluded from findings, never reported as a false clean). ' +
+        'A Joomla page with module/module_position is NOT a render failure — it renders via ' +
+        'a tolerant fallback (that subtree excluded) and shows up in render_fallback ' +
+        '{pages, suppressed_checks} instead, with no-headings/missing-h1/heading-skip ' +
+        'suppressed on just those pages (the only codes a hidden widget heading could fabricate).'),
     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 ' +
@@ -919,12 +848,21 @@ export const PAGES_AUDIT_INPUT = {
         .array(z.enum(['seo', 'structure', 'content', 'links', 'design']))
         .optional()
         .describe('Run only these check categories (default: all five). "seo" = title-collision, ' +
-        'non-pretty-url, stale-content. "structure" = empty-page, missing-h1, ' +
+        'non-pretty-url, stale-content. "structure" = empty-page, dangling-source, ' +
+        'unknown-source-fields (the bound source exists but a field_mappings value it ' +
+        'does not emit renders blank), ' +
+        'container-missing-item-child (a grid/button/slideshow with no *_item child ' +
+        'repeats nothing, so it renders nothing), missing-h1, ' +
         '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, ' +
+        '"links" = dead-anchor, anchor-text-quality — BOTH stay on the page they are ' +
+        'reading. No link TARGET is ever fetched or resolved: a link to a deleted page, a ' +
+        'wrong internal path, or an external URL that answers 404 is not checked by this ' +
+        'tool at all, so "no findings under links" must not be read as "no broken links". ' +
+        'dead-anchor only means a `#id` jump whose target id is missing on the SAME page. ' +
+        '"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 — ' +
@@ -952,50 +890,51 @@ 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.'),
-    // 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.'),
+        'evidence pages and the response carries structured_truncated:true. ' +
+        'It does NOT lift the per-page HIT cap: a site sweep lists at most 5 hits ' +
+        'per page (flagged hits_truncated) whatever you pass here — pass `target` ' +
+        'to audit ONE page, which raises that cap to 100. Raise max_chars for a ' +
+        'complete pathological page, lower it on a tight context budget. ' +
+        'Raising it stops helping at the limit your own client puts on a single tool ' +
+        'result, which this server cannot see. ' +
+        'Out of range, the cap that actually applied comes back as `max_chars`.'),
     include_meta: INCLUDE_META_SCHEMA,
+    include_modules: z
+        .boolean()
+        .optional()
+        .describe('When true, attach `modules_by_page[layout_id]` — the widgets/modules that ' +
+        'render on each SCANNED page, split into `from_elements` (a module/' +
+        'module_position element placed directly in this page\'s own layout) and ' +
+        '`from_positions` (a site-wide theme position — navbar/header/footer — ' +
+        'rendering here with no element in this page\'s own layout at all). On ' +
+        'Joomla, a site-wide module can still be assignment-EXCLUDED from a ' +
+        'specific page (`except`); when that decision cannot be resolved for a ' +
+        'page (no menu item addresses it, or more than one does), the row lands in ' +
+        '`from_positions_undecidable` instead of being guessed in or out. A ' +
+        'builder-content module (Joomla mod_yootheme_builder, WP builderwidget) ' +
+        'carries its embedded layout SUMMARIZED here as ' +
+        '`{omitted_for_size:true, node_count:N}`, not the full tree (B25) — ' +
+        '`layout_root` still names its root type; for the actual content call ' +
+        'local_content_read(kind:"modules") on that id. Costly across a site-wide ' +
+        'sweep otherwise: `layout` alone routinely dwarfs every other field on ' +
+        'the row. Default false — omit for the pre-existing response shape, ' +
+        'unchanged.'),
 };
-/**
- * Wire shape for `yootheme_builder_pages_audit` (design §5). `scanned.by_type`
- * is a `Record<string, number>` — the PHP side already normalizes an empty
- * sweep to `(object) []` (`{}` over the wire), matching this schema without
- * the array-vs-object workaround `template_summary` needed (Task #46).
- */
 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(),
+        layout_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(),
     })
@@ -1005,42 +944,68 @@ export const PAGES_AUDIT_OUTPUT_SCHEMA = z.object({
         by_type: z.record(z.string(), z.number().int().nonnegative()),
     }),
     summary: z.object({
-        critical: z.number().int().nonnegative(),
-        warning: z.number().int().nonnegative(),
-        info: z.number().int().nonnegative(),
+        critical_finding_kinds: z.number().int().nonnegative(),
+        warning_finding_kinds: z.number().int().nonnegative(),
+        info_finding_kinds: z.number().int().nonnegative(),
+        finding_kinds: z.number().int().nonnegative().optional(),
+        affected_pages_summed_across_findings: z.number().int().nonnegative().optional(),
     }),
     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.
+    occurrences_unit: z.string().optional(),
     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.
+    truncated_by: z.array(z.enum(['response_budget', 'per_page_hit_cap'])).optional(),
+    truncation_remedy: z.string().optional(),
     mode: z.enum(['rendered']).optional(),
     render_scan: z
         .object({
         attempted: z.number().int().nonnegative(),
         rendered: z.number().int().nonnegative(),
         capped: z.boolean(),
+        skipped_by_cap: z
+            .array(z.object({ id: z.string(), label: z.string() }))
+            .optional(),
+        skipped_by_cap_not_listed: z.number().int().nonnegative().optional(),
+    })
+        .optional(),
+    checks_not_run: z.array(z.string()).optional(),
+    checks_limited_to_saved_layout: z
+        .object({
+        codes: z.array(z.string()),
+        note: z.string(),
     })
         .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(),
+        error_class: z.string().optional(),
+        reason: z.string().optional(),
+    }))
+        .optional(),
+    render_fallback: z
+        .object({
+        pages: z.array(z.object({
+            id: z.string(),
+            label: z.string(),
+            dropped_count: z.number().int().nonnegative(),
+        })),
+        suppressed_checks: z.array(z.string()),
+    })
+        .optional(),
+    modules_by_page: z
+        .record(z.string(), z.object({
+        from_elements: z.array(z.record(z.string(), z.unknown())),
+        from_positions: z.array(z.record(z.string(), z.unknown())),
+        from_positions_undecidable: z.array(z.record(z.string(), z.unknown())),
+        unresolved_positions: z
+            .array(z.object({ position: z.string(), reason: z.string() }))
+            .optional(),
+        unresolved_module_universe: z.object({ reason: z.string() }).optional(),
     }))
         .optional(),
+    modules_by_page_omitted: z.boolean().optional(),
+    retry_hint: z.string().optional(),
 });
 //# sourceMappingURL=schemas.js.map