@wootsup/yt-builder-mcp 1.11.0 → 2.0.0

package/dist/tools/inspection.js

@@ -1,50 +1,120 @@
-/**
- * Element-type inspection tools.
- *
- *   yootheme_builder_element_types_list
- *      → catalogue of available element types (tableResult — Wave G.2)
- *   yootheme_builder_element_type_get_schema
- *      → field schema for a single element type (detailResult — Wave G.2)
- *
- * @license MIT
- */
-import { detailResult, tableResult } from '@getimo/mcp-toolkit';
+import { detailResult } from '@getimo/mcp-toolkit';
 import { z } from 'zod';
 import { BIND_VIA_GATEWAY_EXAMPLE } from './bind-guidance.js';
 import { TYPES_COMPACT_COLUMNS, TYPES_TABLE_COLUMNS, buildTypeSchemaDetail, flattenTypesPayload, mapTypeRow, } from './format/inspection-format.js';
-import { SITE_ID_SCHEMA } from './shared-schemas.js';
+import { INCLUDE_META_SCHEMA, SITE_ID_SCHEMA } from './shared-schemas.js';
+import { strictInputObject } from './strict-input.js';
 import { resolveSiteOrError } from './pool-resolve-helper.js';
 import { defineTool, errorResult, readOnly, structuredResult, withSiteMeta, } from './tool-builder.js';
-import { DEFAULT_FIELDS_TYPES_LIST, FIELDS, MAX_CHARS, applyMaxChars, projectFields, projectedFieldsEcho, projectionFeedback, projectionWarning, } from './sparse-fields.js';
+import { DEFAULT_FIELDS_TYPES_LIST, FIELDS, FIELD_NAMES, FIELD_NAME_CONTAINS, FIELD_COVERAGE_SCHEMA, MAX_CHARS, applyMaxChars, projectFields, prependTextBlock, projectedFieldsEcho, projectionCoverageBlock, projectionDetailBlock, projectionFeedback, projectionInlineNote, projectionNoteText, selectDescriptorsByName, } from './sparse-fields.js';
 import { ITEM_CHILDREN_OF_CONTAINER } from './multi-items/item-container-map.js';
-// ─── outputSchemas (Wave G.2 §4) ─────────────────────────────────────
+import { budgetedTableResult } from "./budgeted-table.js";
+import { RESPONSE_BUDGET } from "./response-budget.js";
 const TYPES_LIST_OUTPUT_SCHEMA = z.object({
     items: z.array(z.record(z.string(), z.unknown())),
     total: z.number(),
     projected_fields: z.array(z.string()).optional(),
-    // F-004 fix (2026-05-25 exhaustive audit): see sparse-fields::projectionFeedback.
     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(),
 });
 const TYPE_SCHEMA_OUTPUT_SCHEMA = z.object({
-    name: z.string(),
+    name: z.string().optional(),
+    element_types: z
+        .array(z.object({
+        name: z.string(),
+        label: z.string().optional(),
+        requires_child_type: z.string().optional(),
+        origin: z.string().optional(),
+        has_children: z.boolean().optional(),
+    }))
+        .optional(),
+    total: z.number().optional(),
     label: z.string().optional(),
     origin: z.string().optional(),
-    // The REST endpoint returns `fields` as a list of {name,type,label?}
-    // field descriptors — each `name` is a valid prop key for element_add /
-    // _update_settings.
+    has_children: z.boolean().optional(),
+    semantic_role: z.string().nullable().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(),
     fields: z.array(z.record(z.string(), z.unknown())).optional(),
-    field_count: z.number(),
-    // Wave-6 R3 (2026-05-29): binding contract annotation. Surfaces the
-    // Multi-Items binding pattern for container types (grid/slider/switcher/
-    // list/accordion/gallery/panel/overlay), and identifies content-binding
-    // prop keys for leaf types (headline/text/button/image). Cold-AI #4 had
-    // to reverse-engineer this from inspect_multi_items_binding + page
-    // layout — this annotation eliminates that step.
+    groups: z
+        .array(z.object({
+        name: z.string().describe('Matches a field descriptor\'s `group`.'),
+        description: z
+            .string()
+            .describe("The fieldset group's own sentence, as YOOtheme ships it."),
+    }))
+        .optional()
+        .describe('Fieldset groups that carry a rule of their own, stated once each. ' +
+        'YOOtheme parks the semantics of a whole class of fields on the ' +
+        'GROUP rather than on the field — grid.image_width/image_height ' +
+        'declare no description and the crop rule lives here — so a ' +
+        'descriptor with no `description` is not undocumented, you are ' +
+        'reading at the wrong level. Join on the field\'s `group`. ' +
+        'Narrows with field_names/name_contains.'),
+    renders_only_if: z
+        .array(z.array(z.string()))
+        .optional()
+        .describe('ALL groups need >=1 non-empty member or YOOtheme DELETES this element at ' +
+        'render (no error; an emptied parent then collapses too). Applies to ' +
+        'PRESENT-but-empty props; for ABSENT ones see placeholder_fallback. A ' +
+        "member may be `a&&b`; `parent.` prefixes the container's prop."),
+    placeholder_fallback: z
+        .object({ suppressed_by: z.array(z.string()), fills: z.array(z.string()) })
+        .optional()
+        .describe('Why renders_only_if often does NOT delete: leave every suppressed_by key ' +
+        "UNSET and YOOtheme merges its placeholder (prerender, front end too), so " +
+        'fills render as lorem ipsum/"Title"/a placeholder image on the LIVE page. ' +
+        'Write any suppressed_by key, even "", to suppress the merge and get deletion.'),
+    blanked_by_parent: z
+        .record(z.string(), z.array(z.string()))
+        .optional()
+        .describe('Container show_* flag -> props of THIS element the RENDER blanks (not ' +
+        'CSS-hide). Blanks the OUTPUT only: your stored value survives and the ' +
+        'flag is reversible. Runs before renders_only_if, so clearing one can ' +
+        'drop the whole item — intersect the two to see which.'),
+    media_autoswap: z
+        .object({
+        precedence: z.array(z.string()),
+        sniffed: z.array(z.string()).optional(),
+        clears_on_conflict: z.array(z.string()).optional(),
+    })
+        .optional()
+        .describe('Image/video collision, per element — not uniform across YOOtheme. ' +
+        'precedence: first non-empty renders. sniffed: URL-sniffed, value MOVED ' +
+        'between image/video. clears_on_conflict: prop SET FALSE, not just skipped.'),
+    rules: z
+        .array(z.string())
+        .optional()
+        .describe('Shared render-rule ids — resolve each in `rule_notes`. Each marks a case ' +
+        'where the write succeeds and the render differs; read before writing ' +
+        'that prop.'),
+    rule_notes: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('id -> rule text, for the ids this response references. Element-level ids ' +
+        'always resolve; a field-level one only while its field is returned.'),
+    claims_verified_on: z
+        .object({
+        build: z.string(),
+        here: z.string().nullable(),
+        status: z.enum(['match', 'differs', 'unknown']),
+        keys: z.array(z.string()),
+    })
+        .optional()
+        .describe('Build the keys named in `keys` were READ on vs this site — those ' +
+        'ONLY, never the whole response. "differs"/"unknown" = NOT ' +
+        're-checked here, so they are reports, not facts, and no_effect ' +
+        'ships as no_effect_unverified.'),
+    field_count: z.number().optional(),
+    returned_count: z.number().optional(),
+    next_step: z.string().optional(),
     binding_contract: z
         .object({
         kind: z.enum(['container', 'item', 'leaf', 'none']),
@@ -52,67 +122,40 @@ const TYPE_SCHEMA_OUTPUT_SCHEMA = z.object({
         child_type: z.string().optional(),
         child_required: z.boolean().optional(),
         binding_target_props: z.array(z.string()).optional(),
-        // F151 (2026-06-11): the single canonical text prop for this
-        // element type (e.g. grid_item → "title", list_item/headline →
-        // "content"). Names the right key so the agent does not guess.
         canonical_text_prop: z.string().optional(),
-        // F143 (2026-06-11): map_item's single combined "lat,lng"
-        // location prop contract — present only for location-bearing
-        // item types.
         location_prop: z
             .object({ prop: z.string(), format: z.string() })
             .optional(),
         minimal_layout: z.record(z.string(), z.unknown()).optional(),
         set_via_tool: z.string().optional(),
         discover_source_tool: z.string().optional(),
-        // Wave-7 (2026-05-29): explicit anti-patterns. Cold-AI #5 misread
-        // the minimal_layout and produced `props.source` nesting instead of
-        // sibling — YT-Pro silently ignored the binding and rendered 0 rows.
         do_not: z.array(z.string()).optional(),
     })
         .optional(),
+})
+    .superRefine((v, ctx) => {
+    if (v.element_types !== undefined)
+        return;
+    for (const key of ['name', 'field_count', 'returned_count']) {
+        if (v[key] === undefined) {
+            ctx.addIssue({
+                code: 'custom',
+                path: [key],
+                message: `${key} is required when a single element type was read`,
+            });
+        }
+    }
 });
-// Wave-6 R3 (2026-05-29): Binding-contract derivation.
-//
-// Container types are the Multi-Items hosts — when bound to a source they
-// clone their *_item child once per source row. The binding LIVES on the
-// child item, not the container.
-//
-// Wave-13 A5 (2026-05-31): the canonical 16-pair map lives in
-// `multi-items/item-container-map.ts` (TypeScript mirror of the PHP
-// `ItemContainerMap` constant, pinned via Joomla/WP cross-platform tests).
-// Re-aliased here as CONTAINER_TO_ITEM_TYPE so the binding-contract derivation
-// always agrees with the rest of the surface. The previous inline 10-entry
-// map had drifted (missing button/description_list/nav/popover/social/subnav/
-// table; routed `slider`/`panel`/`overlay` to non-existent item types).
-//
-// Leaf types (headline, text, image) cannot host Multi-Items but they DO
-// accept per-prop source bindings (e.g. `content` of a headline maps to a
-// single source field). We surface the canonical prop keys below so the
-// agent knows which keys to bind without guessing.
 const CONTAINER_TO_ITEM_TYPE = ITEM_CHILDREN_OF_CONTAINER;
 const ITEM_TO_CONTAINER_TYPE = Object.fromEntries(Object.entries(CONTAINER_TO_ITEM_TYPE).map(([k, v]) => [v, k]));
-/** Canonical binding-target props per leaf type. Empty array → leaf type has no clear single-field binding. */
 const LEAF_BINDING_TARGETS = {
-    headline: ['content', 'title_dynamic'],
+    headline: ['content'],
     text: ['content'],
     button: ['content', 'link'],
     image: ['image'],
     icon: ['icon'],
-    quote: ['content'],
-    subtitle: ['content'],
+    quotation: ['content'],
 };
-// F151 (2026-06-11): the SINGLE canonical text prop per element type.
-//
-// Prop names diverge across types — a `grid_item` carries its primary
-// text on `title`, while `list_item`/`headline`/`text` carry it on
-// `content`. A cold agent that guesses one key consistently writes a
-// DEAD prop (silent placeholder, no error). The F129 bind-time validator
-// (Wave 4) already WARNS on unknown prop keys after the fact; this map is
-// the SCHEMA side — it names the right key UP FRONT so the agent never
-// guesses. Only types with an unambiguous single text carrier are listed;
-// types with no clear single text prop are simply omitted (no
-// `canonical_text_prop` emitted).
 const CANONICAL_TEXT_PROP = {
     grid_item: 'title',
     list_item: 'content',
@@ -120,21 +163,13 @@ const CANONICAL_TEXT_PROP = {
     slideshow_item: 'title',
     switcher_item: 'title',
     gallery_item: 'title',
-    panel_item: 'title',
+    'panel-slider_item': 'title',
     headline: 'content',
     text: 'content',
-    quote: 'content',
-    subtitle: 'content',
+    quotation: 'content',
     button: 'content',
     button_item: 'content',
 };
-// F143 (2026-06-11): `map_item` renders a marker off a SINGLE `location`
-// prop that wants ONE combined "lat,lng" string. Sources almost always
-// supply latitude and longitude as two separate fields, so the natural
-// (wrong) move is to map two props — which leaves the map with zero pins
-// and no error. Surface the contract on the schema so the agent maps one
-// combined value instead. See also the inspect_multi_items_binding hard
-// warning (PHP MultiItemsInspector) for the post-bind safety net.
 const LOCATION_PROP_CONTRACT = {
     map_item: {
         prop: 'location',
@@ -145,12 +180,6 @@ const LOCATION_PROP_CONTRACT = {
             'location binding the map renders 0 markers.',
     },
 };
-/**
- * F151/F143 — attach the canonical single text prop and (for map_item)
- * the location-prop contract to whatever contract `deriveBindingContract`
- * built. Pure: returns a new object, only sets the keys when a mapping
- * exists for `elementType`.
- */
 function withPropContracts(contract, elementType) {
     const textProp = CANONICAL_TEXT_PROP[elementType];
     const location = LOCATION_PROP_CONTRACT[elementType];
@@ -160,6 +189,10 @@ function withPropContracts(contract, elementType) {
         ...(location !== undefined ? { location_prop: { ...location } } : {}),
     };
 }
+const DISCOVER_SOURCE_TOOL = 'apimapper_yootheme_binding_for_flow({ flow_id }) — a tool of the SEPARATE API Mapper ' +
+    'MCP server, available only when that server is connected alongside this one. If it ' +
+    'is not, read the published source and its fields with yootheme_builder_sources_list ' +
+    'and yootheme_builder_source_get_schema instead.';
 function deriveBindingContract(elementType) {
     const built = deriveBindingContractBase(elementType);
     return built !== undefined ? withPropContracts(built, elementType) : built;
@@ -180,40 +213,24 @@ function deriveBindingContractBase(elementType) {
                 `N siblings.`,
             child_type: itemType,
             child_required: true,
-            // F132 (Wave 4a): the example shows a BARE container + child —
-            // NO populated `source` block. element_add's children-guard now
-            // rejects a hand-authored `source` anywhere in the tree (it
-            // silently renders 0 rows in a stored layout), so teaching the
-            // populated shape here would hand the agent a guaranteed reject /
-            // broken render. Build this bare structure first, THEN bind the
-            // source through the dedicated bind tool — see `set_via_tool`
-            // and `do_not` below. The binding lands on the *_item as a
-            // SIBLING of `props`/`children`; the bind tool writes it at the
-            // correct nesting level so you never hand-author it.
             minimal_layout: {
                 type: elementType,
-                // Container is bare — it never holds a `source` of its own.
                 children: [
                     {
                         type: itemType,
-                        // `props` stays minimal — settings only. NO `source`
-                        // here: add the structure first, then bind via
-                        // yootheme_builder_element_bind_source (see set_via_tool).
                         props: {},
                         children: [],
                     },
                 ],
-                // After this structure exists, bind the source:
                 bind_after_create: 'Call yootheme_builder_element_bind_source on the *_item child ' +
-                    '(NOT this container). Discover the binding shape with ' +
-                    'apimapper_yootheme_binding_for_flow({ flow_id }). Do NOT add `source` ' +
-                    'to this layout by hand.',
+                    '(NOT this container). Discover the binding shape via ' +
+                    '`discover_source_tool` below. Do NOT add `source` to this layout by hand.',
             },
-            set_via_tool: 'yootheme_builder_element_bind_source({ template_id, element_path, ' +
+            set_via_tool: 'yootheme_builder_element_bind_source({ layout_id, element_path, ' +
                 'source_name, field_mappings }) — REQUIRED. The bind tool is a first-class ' +
                 'tool in tools/list (since F116); call it directly. Hand-authoring source via ' +
                 'element_update_settings is rejected (props-schema does not include source).',
-            discover_source_tool: 'apimapper_yootheme_binding_for_flow({ flow_id }) — returns ready-to-paste binding shapes.',
+            discover_source_tool: DISCOVER_SOURCE_TOOL,
             do_not: [
                 `Do NOT set \`source\` on the container (${elementType}) itself — only on the *_item child.`,
                 `Do NOT nest \`source\` under \`props\` on the ${itemType} — it must be a sibling of props.`,
@@ -232,16 +249,16 @@ function deriveBindingContractBase(elementType) {
                 `— do NOT hand-author the source via element_update_settings.** The source must ` +
                 `be set on THIS element (as a SIBLING of \`props\`/\`children\`, not nested ` +
                 `inside \`props\`), not on the parent ${containerType}.`,
-            set_via_tool: 'yootheme_builder_element_bind_source({ template_id, element_path, ' +
+            set_via_tool: 'yootheme_builder_element_bind_source({ layout_id, element_path, ' +
                 'source_name, field_mappings }) — REQUIRED. The bind tool is a first-class ' +
                 'tool in tools/list (since F116); call it directly. Hand-authoring source via ' +
                 'element_update_settings is rejected (props-schema does not include source).',
-            discover_source_tool: 'apimapper_yootheme_binding_for_flow({ flow_id })',
+            discover_source_tool: DISCOVER_SOURCE_TOOL,
             do_not: [
                 `Do NOT set \`source\` on the parent ${containerType} — only on this ${elementType}.`,
                 'Do NOT nest `source` under `props` — it must be a sibling of `props`/`children`.',
                 'Do NOT call element_update_settings with {source} or {source_extended} — bind via ' +
-                    'yootheme_builder_element_bind_source({ template_id, element_path, source_name, field_mappings }).',
+                    'yootheme_builder_element_bind_source({ layout_id, element_path, source_name, field_mappings }).',
                 'Do NOT add child leaves with their own per-prop `source` + `${builder.source}` placeholders.',
             ],
         };
@@ -254,7 +271,7 @@ function deriveBindingContractBase(elementType) {
                 `listed in \`binding_target_props\`. NOT a Multi-Items host.`,
             binding_target_props: [...leafTargets],
             set_via_tool: BIND_VIA_GATEWAY_EXAMPLE,
-            discover_source_tool: 'apimapper_yootheme_binding_for_flow({ flow_id })',
+            discover_source_tool: DISCOVER_SOURCE_TOOL,
         };
     }
     return {
@@ -264,28 +281,10 @@ function deriveBindingContractBase(elementType) {
             '(the bind tool is a first-class tool in tools/list since F116).',
     };
 }
-/**
- * Test-only re-export of the module-private `deriveBindingContract`. Kept
- * out of the public tool surface; consumed by the F132 minimal_layout pin
- * (tests/tools/inspection-minimal-layout-bare.test.ts).
- */
 export const __test_deriveBindingContract = deriveBindingContract;
-/**
- * ELEMENT_WRITE-4 (part 1) — the node-level keys the YT schema serializer lists
- * in `fields[]` even though they are SIBLINGS of `props` on the node, not props.
- * Writing `props.name` via element_add is silently accepted (the key IS in
- * fields[]) but never renders as the builder label. Annotating them steers the
- * agent to set them OUTSIDE props (a first-class `name` arg is the cross-file
- * follow-up owned by the element_add builder schema).
- */
+export const __test_CANONICAL_TEXT_PROP = CANONICAL_TEXT_PROP;
+export const __test_LEAF_BINDING_TARGETS = LEAF_BINDING_TARGETS;
 const NODE_LEVEL_FIELD_KEYS = new Set(['name', 'status', 'source', 'id']);
-/**
- * Annotate node-level descriptors (`name`/`status`/`source`/`id`) with
- * `group:'node-level'` + a value_hint so the agent knows they live OUTSIDE
- * `props`. Non-destructive: returns a shallow-cloned array; other descriptors
- * pass through untouched, and a descriptor that already declares a group keeps
- * it (we only fill an ABSENT group).
- */
 function annotateNodeLevelFields(fields) {
     return fields.map((field) => {
         const name = field.name;
@@ -294,7 +293,7 @@ function annotateNodeLevelFields(fields) {
         }
         return {
             ...field,
-            ...(field.group === undefined || field.group === '' ? { group: 'node-level' } : {}),
+            group: 'node-level',
             value_hint: typeof field.value_hint === 'string' && field.value_hint !== ''
                 ? field.value_hint
                 : 'builder label / node metadata — lives OUTSIDE `props` (a SIBLING of ' +
@@ -303,29 +302,124 @@ function annotateNodeLevelFields(fields) {
         };
     });
 }
+function narrowGroupsToSelection(raw, selected) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const groups = [];
+    for (const entry of raw) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const { name, description } = entry;
+        if (typeof name === 'string' && name !== '' && typeof description === 'string') {
+            groups.push({ name, description });
+        }
+    }
+    if (groups.length === 0)
+        return undefined;
+    if (selected === undefined)
+        return groups;
+    const named = new Set();
+    for (const field of selected) {
+        if (typeof field.group === 'string')
+            named.add(field.group);
+    }
+    return groups.filter((g) => named.has(g.name));
+}
+function extractRenderRules(schema) {
+    const out = {};
+    const isStringList = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+    const gate = schema.renders_only_if;
+    if (Array.isArray(gate) && gate.length > 0 && gate.every(isStringList)) {
+        out.renders_only_if = gate;
+    }
+    const blanked = schema.blanked_by_parent;
+    if (blanked !== null && typeof blanked === 'object' && !Array.isArray(blanked)) {
+        const map = {};
+        for (const [flag, props] of Object.entries(blanked)) {
+            if (isStringList(props))
+                map[flag] = props;
+        }
+        if (Object.keys(map).length > 0)
+            out.blanked_by_parent = map;
+    }
+    const media = schema.media_autoswap;
+    if (media !== null && typeof media === 'object' && !Array.isArray(media)) {
+        const { precedence, sniffed, clears_on_conflict } = media;
+        if (isStringList(precedence) && precedence.length > 0) {
+            out.media_autoswap = {
+                precedence,
+                ...(isStringList(sniffed) ? { sniffed } : {}),
+                ...(isStringList(clears_on_conflict) ? { clears_on_conflict } : {}),
+            };
+        }
+    }
+    const fallback = schema.placeholder_fallback;
+    if (fallback !== null && typeof fallback === 'object' && !Array.isArray(fallback)) {
+        const { suppressed_by, fills } = fallback;
+        if (isStringList(suppressed_by) && suppressed_by.length > 0 && isStringList(fills)) {
+            out.placeholder_fallback = { suppressed_by, fills };
+        }
+    }
+    return out;
+}
+function extractClaimProvenance(schema) {
+    const raw = schema.claims_verified_on;
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const { build, here, status, keys } = raw;
+    if (typeof build !== 'string' || build === '')
+        return undefined;
+    if (status !== 'match' && status !== 'differs' && status !== 'unknown')
+        return undefined;
+    if (here !== null && typeof here !== 'string')
+        return undefined;
+    if (!Array.isArray(keys) || keys.length === 0)
+        return undefined;
+    if (!keys.every((k) => typeof k === 'string'))
+        return undefined;
+    return { build, here, status, keys };
+}
+function extractSharedRuleNotes(schema, selected) {
+    const isStringList = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+    const elementRules = isStringList(schema.rules) ? schema.rules : [];
+    const referenced = new Set(elementRules);
+    for (const field of selected ?? []) {
+        const refs = field.rules;
+        if (isStringList(refs)) {
+            for (const id of refs)
+                referenced.add(id);
+        }
+    }
+    const rawNotes = schema.rule_notes;
+    const notes = {};
+    if (rawNotes !== null && typeof rawNotes === 'object' && !Array.isArray(rawNotes)) {
+        for (const [id, text] of Object.entries(rawNotes)) {
+            if (typeof text === 'string' && text !== '' && referenced.has(id)) {
+                notes[id] = text;
+            }
+        }
+    }
+    return {
+        ...(elementRules.length > 0 ? { rules: elementRules } : {}),
+        ...(Object.keys(notes).length > 0 ? { rule_notes: notes } : {}),
+    };
+}
 export function buildInspectionTools(pool) {
     return [
         defineTool({
             name: 'yootheme_builder_element_types_list',
-            description: 'List element types registered on this site (built-ins + ' +
-                'YOOessentials/uEssentials extras). Names feed `element_type` of ' +
-                'element_add. Pass `fields[]` to narrow each row. ' +
-                // F61: "slider"/"carousel" are customer words, not element
-                // names. F62: prop keys are per-element (grid_item `title` vs
-                // headline `content`) — call element_type_get_schema first.
-                'Keywords: "slider"/"carousel" → `slideshow`/`panel-slider`/`overlay-slider`. ' +
-                'Prop keys differ per element (grid_item `title` vs headline `content`) — ' +
-                'use element_type_get_schema before element_add/bind. Container rows carry ' +
-                '`requires_child_type` (grid→grid_item); `has_children`/`has_children_support` ' +
-                'are aliases (same value). ' +
-                'Operates on the default site unless site_id is provided.',
+            description: 'List element types registered on this site (built-ins + YOOessentials extras). ' +
+                'Names feed `element_type` of element_add. ' +
+                '"slider"/"carousel" → `slideshow`/`panel-slider`/`overlay-slider`. Prop keys ' +
+                'differ per element — use element_type_get_schema before element_add/bind.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 fields: FIELDS,
+                include_meta: INCLUDE_META_SCHEMA,
             },
             outputSchema: TYPES_LIST_OUTPUT_SCHEMA,
             annotations: readOnly('List Element Types'),
-            handler: async ({ site_id, fields }) => {
+            handler: async ({ site_id, fields, include_meta }) => {
                 const r = await resolveSiteOrError(pool, site_id);
                 if (!r.ok)
                     return r.error;
@@ -334,10 +428,6 @@ export function buildInspectionTools(pool) {
                     const data = await siteClient.get('/element-types');
                     const flat = flattenTypesPayload(data);
                     const mapped = flat.map(mapTypeRow);
-                    // ELEMENT_WRITE-26: surface the container→item pairing per row
-                    // (grid→grid_item, button→button_item) so the Multi-Items child
-                    // requirement is visible WITHOUT opening each type's schema.
-                    // Present only on container rows; leaf/item rows stay unchanged.
                     const mappedRecords = mapped.map((row) => {
                         const child = CONTAINER_TO_ITEM_TYPE[row.name];
                         return child !== undefined
@@ -347,14 +437,17 @@ export function buildInspectionTools(pool) {
                     const items = projectFields(mappedRecords, fields, DEFAULT_FIELDS_TYPES_LIST);
                     const echo = projectedFieldsEcho(fields, DEFAULT_FIELDS_TYPES_LIST);
                     const feedback = projectionFeedback(mappedRecords, fields);
-                    // F23 (2026-06-09): shared loud-warning helper.
-                    const unknownNote = projectionWarning(feedback);
-                    const toolkitResult = tableResult(mappedRecords, {
+                    const unknownNote = projectionInlineNote(feedback, fields);
+                    const coverageBlock = projectionCoverageBlock(feedback?.field_coverage, feedback?.unknown_fields);
+                    const projectionNote = projectionNoteText(coverageBlock, unknownNote);
+                    const toolkitResult = budgetedTableResult(mappedRecords, {
                         columns: [...TYPES_TABLE_COLUMNS],
                         compactColumns: [...TYPES_COMPACT_COLUMNS],
-                        header: (count) => `${String(count)} element types${unknownNote}`,
-                        footer: 'Use yootheme_builder_element_type_get_schema <name> for fields.',
-                    });
+                        header: (count) => `${coverageBlock}${String(count)} element types${unknownNote}`,
+                        footer: 'Fields of a type: yootheme_builder_element_type_get_schema(' +
+                            '{element_type: "<NAME column>"}).',
+                        includeMeta: include_meta,
+                    }, RESPONSE_BUDGET.BULKY);
                     return withSiteMeta(structuredResult(toolkitResult, {
                         items,
                         total: items.length,
@@ -362,8 +455,9 @@ export function buildInspectionTools(pool) {
                         ...(feedback !== undefined ? {
                             available_fields: [...feedback.available_fields],
                             unknown_fields: [...feedback.unknown_fields],
-                            ...(unknownNote.trim() !== '' ? { projection_warning: unknownNote.trim() } : {}),
+                            field_coverage: { ...feedback.field_coverage },
                         } : {}),
+                        ...(projectionNote !== '' ? { projection_warning: projectionNote } : {}),
                     }), site);
                 }
                 catch (e) {
@@ -378,24 +472,9 @@ export function buildInspectionTools(pool) {
         buildElementTypeGetSchemaTool(pool),
     ];
 }
-/**
- * F-203 follow-up (Audit 2026-05-26 reviewer Gap 2): factored out of
- * `buildInspectionTools` so the shape + refined ZodObject pair lives in
- * one place. The SDK's pre-handler validator honours the top-level
- * `.refine()` on `TYPE_SCHEMA_REFINED` and raises
- * JSON-RPC `-32602 InvalidParams` when violated — hosts see the
- * failure BEFORE the handler ever runs. The raw shape stays for
- * handler-type inference (see `inputSchema`).
- */
 function buildElementTypeGetSchemaTool(pool) {
     const TYPE_SCHEMA_SHAPE = {
         site_id: SITE_ID_SCHEMA,
-        // 1.0.1 cross-tool parameter naming alignment: every other
-        // tool in this domain uses `element_type` (element_add,
-        // element_update_settings, element_list rows). This tool
-        // originally shipped with `type_name`; we accept BOTH for
-        // backward-compatibility but the canonical key going
-        // forward is `element_type`.
         element_type: z
             .string()
             .min(1)
@@ -409,148 +488,232 @@ function buildElementTypeGetSchemaTool(pool) {
             .describe('DEPRECATED alias of `element_type` — use `element_type` ' +
             'instead. Kept for 1.0.x backward-compatibility; will be ' +
             'removed in a future major.'),
-        // ELEMENT_WRITE-17 / SOURCES_BINDING-23: this was the only read tool with
-        // NO way to bound its response (grid returns ~154 field descriptors in one
-        // blob). `fields[]` sparse-projects each field descriptor to the requested
-        // sub-keys; `max_chars` caps the text leg — mirroring the sibling reads.
         fields: FIELDS,
+        field_names: FIELD_NAMES,
+        name_contains: FIELD_NAME_CONTAINS,
+        include_fields: z
+            .boolean()
+            .optional()
+            .describe('Return the full field-descriptor list (e.g. 147 for `grid`). ' +
+            'Default: head data only — binding_contract, minimal_layout ' +
+            'and field_count. `field_names`/`name_contains` also return ' +
+            'descriptors, narrowed to what they select.'),
         max_chars: MAX_CHARS,
     };
-    const TYPE_SCHEMA_REFINED = z
-        .object(TYPE_SCHEMA_SHAPE)
-        .refine((args) => (typeof args.element_type === 'string' && args.element_type !== '') ||
-        (typeof args.type_name === 'string' && args.type_name !== ''), {
-        message: 'Provide either `element_type` (canonical) or ' +
-            '`type_name` (deprecated alias).',
-    });
+    const TYPE_SCHEMA_REFINED = strictInputObject('yootheme_builder_element_type_get_schema', TYPE_SCHEMA_SHAPE);
     return defineTool({
         name: 'yootheme_builder_element_type_get_schema',
-        description: 'Fetch a type\'s prop schema before element_add/element_update_settings: ' +
-            'unknown prop keys are hard-rejected (error lists valid_prop_keys + ' +
-            'did_you_mean). Returns each field as {name,type,label?,enum?,value_hint?,' +
-            'group?}, field_count, and a binding_contract for container/item types. Read ' +
-            'value_hint+enum first — some defaults are SEO-fatal (headline.title_element' +
-            '→h1); checkbox = boolean true/false; group:"runtime-accepted" = honoured at ' +
-            'render but hidden in the builder UI. Bound size with fields[]/max_chars. ' +
-            'Operates on the default site unless site_id is provided.',
+        description: 'Prop schema; read before element_add/element_update_settings: ' +
+            'undeclared keys are STORED, not refused: warns unknown_prop_keys. ' +
+            'NO element_type: lists the types. With one: head only ' +
+            '— binding_contract (containers/items) + groups[] + field_count. ' +
+            'include_fields:true adds every descriptor {name,type,label?,text?,' +
+            'description?,enum?,value_hint?,group?,no_effect?}; ' +
+            'Select descriptors: field_names/name_contains, answered with ' +
+            'field_count/returned_count. value_hint+enum first: some ' +
+            'defaults are SEO-fatal (headline.title_element→h1); checkbox = boolean ' +
+            'true/false; no_effect = read by nothing, never write it; ' +
+            'group:"runtime-accepted" = honoured at render, hidden in UI. ' +
+            'Bound size with fields[]/max_chars.',
         inputSchema: TYPE_SCHEMA_SHAPE,
-        // F-203 follow-up: the refined object is what the SDK actually
-        // validates. The raw shape above stays for handler-type inference.
         inputObjectSchema: TYPE_SCHEMA_REFINED,
         outputSchema: TYPE_SCHEMA_OUTPUT_SCHEMA,
         annotations: readOnly('Get Element Type Schema'),
         handler: async (args) => {
-            // Defensive re-assert of the refine — should never fire when
-            // reached through the SDK (the boundary rejects with -32602
-            // first), but in-process tests bypass the SDK and call the
-            // handler directly, so the structured error path stays
-            // reachable for unit-test coverage.
             const typeNameInput = typeof args.element_type === 'string' && args.element_type !== ''
                 ? args.element_type
                 : typeof args.type_name === 'string'
                     ? args.type_name
                     : '';
-            if (typeNameInput === '') {
-                return errorResult({
-                    error: new Error('Provide either `element_type` (canonical) or ' +
-                        '`type_name` (deprecated alias).'),
-                    context: { site_id: typeof args.site_id === 'string' ? args.site_id : null },
-                    hint: 'Pass `element_type` (e.g. "headline"). Use ' +
-                        'yootheme_builder_element_types_list to discover valid values.',
-                });
-            }
-            const type_name = typeNameInput;
             const r = await resolveSiteOrError(pool, typeof args.site_id === 'string' ? args.site_id : undefined);
             if (!r.ok)
                 return r.error;
             const { client: siteClient, site } = r;
+            if (typeNameInput === '') {
+                try {
+                    const listData = await siteClient.get('/element-types');
+                    const rows = flattenTypesPayload(listData).map(mapTypeRow);
+                    const types = rows.map((row) => {
+                        const child = CONTAINER_TO_ITEM_TYPE[row.name];
+                        return {
+                            name: row.name,
+                            ...(typeof row.label === 'string' && row.label !== ''
+                                ? { label: row.label }
+                                : {}),
+                            ...(child !== undefined ? { requires_child_type: child } : {}),
+                        };
+                    });
+                    const lines = types
+                        .map((t) => t.requires_child_type !== undefined
+                        ? `${t.name} (needs a ${t.requires_child_type} child)`
+                        : t.name)
+                        .join('\n');
+                    return withSiteMeta(structuredResult({
+                        content: [
+                            {
+                                type: 'text',
+                                text: `${String(types.length)} element types. Read one ` +
+                                    'with yootheme_builder_element_type_get_schema(' +
+                                    '{ element_type: "<NAME>" }) — that returns the ' +
+                                    'binding contract and the field COUNT; add ' +
+                                    'include_fields:true for the descriptors.' +
+                                    `\n\n${lines}`,
+                            },
+                        ],
+                    }, { element_types: types, total: types.length }), site);
+                }
+                catch (e) {
+                    return withSiteMeta(errorResult({
+                        error: e,
+                        context: { site_id: site.id },
+                        hint: 'Use yootheme_builder_health to check connectivity + auth.',
+                    }), site);
+                }
+            }
+            const type_name = typeNameInput;
             try {
                 const data = await siteClient.get(`/element-types/${encodeURIComponent(type_name)}/schema`);
-                // The REST endpoint nests the type schema under `schema`:
-                // {type_name, schema:{name,label,origin,has_children,fields:[…]}}.
-                // Fall back to the top-level object for older backends.
                 const schema = data.schema !== null && typeof data.schema === 'object'
                     ? data.schema
                     : data;
                 const name = typeof schema.name === 'string' ? schema.name : type_name;
                 const label = typeof schema.label === 'string' ? schema.label : undefined;
                 const origin = typeof schema.origin === 'string' ? schema.origin : undefined;
-                // `fields` is a list of {name,type,label?} field descriptors.
                 const rawFields = Array.isArray(schema.fields)
                     ? schema.fields
                     : undefined;
-                // ELEMENT_WRITE-4 (part 1): the node-level keys {name,status,
-                // source,id} are siblings of `props`, NOT props — but they render
-                // in the Fields table with no group, so an agent writes props.name
-                // via element_add and it is silently accepted (name is a fields[]
-                // entry). Annotate them so the agent knows they live OUTSIDE props.
                 const annotatedFields = rawFields !== undefined ? annotateNodeLevelFields(rawFields) : undefined;
-                // ELEMENT_WRITE-17 / SOURCES_BINDING-23: project each descriptor to
-                // the requested sub-keys when `fields[]` was passed (bounds the
-                // structured leg); `max_chars` bounds the text leg below.
                 const fieldsParam = Array.isArray(args.fields) &&
                     args.fields.every((f) => typeof f === 'string')
                     ? args.fields
                     : undefined;
                 const maxChars = typeof args.max_chars === 'number' ? args.max_chars : undefined;
-                const fields = annotatedFields !== undefined
-                    ? projectFields(annotatedFields, fieldsParam, [])
+                const fieldNamesParam = Array.isArray(args.field_names) &&
+                    args.field_names.every((f) => typeof f === 'string')
+                    ? args.field_names
                     : undefined;
+                const nameContains = typeof args.name_contains === 'string' ? args.name_contains : undefined;
+                const wantsDescriptors = args.include_fields === true ||
+                    fieldsParam !== undefined ||
+                    fieldNamesParam !== undefined ||
+                    nameContains !== undefined;
+                const selected = annotatedFields !== undefined && wantsDescriptors
+                    ? selectDescriptorsByName(annotatedFields, fieldNamesParam, nameContains)
+                    : undefined;
+                const fields = selected !== undefined
+                    ? projectFields(selected, fieldsParam, [])
+                    : undefined;
+                const descriptorFeedback = projectionFeedback(selected ?? [], fieldsParam);
+                const descriptorNote = projectionNoteText(projectionCoverageBlock(descriptorFeedback?.field_coverage, descriptorFeedback?.unknown_fields), projectionInlineNote(descriptorFeedback, fieldsParam));
+                const descriptorNoteBlock = projectionDetailBlock(descriptorFeedback, fieldsParam);
                 const fieldCount = annotatedFields !== undefined ? annotatedFields.length : 0;
-                // Wave-6 R3 (2026-05-29): attach a binding contract so
-                // the agent doesn't have to reverse-engineer the
-                // Multi-Items pattern from layout + inspection probes.
+                const returnedCount = selected !== undefined ? selected.length : 0;
+                const nextStep = wantsDescriptors
+                    ? undefined
+                    : `yootheme_builder_element_type_get_schema({ element_type: "${name}", ` +
+                        `include_fields: true }) returns all ${String(fieldCount)} field ` +
+                        'descriptors; field_names/name_contains return a subset.';
+                const groups = narrowGroupsToSelection(schema.groups, selected);
+                const renderRules = extractRenderRules(schema);
+                const sharedRules = extractSharedRuleNotes(schema, selected);
+                const claimProvenance = extractClaimProvenance(schema);
                 const bindingContract = deriveBindingContract(name);
-                const toolkitResult = detailResult(buildTypeSchemaDetail({
+                const toolkitResult = detailResult({
+                    ...buildTypeSchemaDetail({
+                        name,
+                        label,
+                        origin,
+                        fields,
+                        fieldCount,
+                        returnedCount,
+                        ...(fieldsParam !== undefined && fieldsParam.length > 0 && selected !== undefined
+                            ? {
+                                descriptorNames: selected.map((d) => typeof d.name === 'string' ? d.name : ''),
+                                projectedFields: fieldsParam,
+                            }
+                            : {}),
+                        ...(bindingContract !== undefined
+                            ? {
+                                bindingContract: {
+                                    kind: bindingContract.kind,
+                                    pattern: bindingContract.pattern,
+                                    ...(bindingContract.child_type !== undefined
+                                        ? { child_type: bindingContract.child_type }
+                                        : {}),
+                                    ...(bindingContract.binding_target_props !== undefined
+                                        ? {
+                                            binding_target_props: bindingContract.binding_target_props,
+                                        }
+                                        : {}),
+                                    ...(bindingContract.canonical_text_prop !== undefined
+                                        ? {
+                                            canonical_text_prop: bindingContract.canonical_text_prop,
+                                        }
+                                        : {}),
+                                    ...(bindingContract.location_prop !== undefined
+                                        ? { location_prop: bindingContract.location_prop }
+                                        : {}),
+                                    ...(bindingContract.set_via_tool !== undefined
+                                        ? { set_via_tool: bindingContract.set_via_tool }
+                                        : {}),
+                                    ...(bindingContract.discover_source_tool !== undefined
+                                        ? {
+                                            discover_source_tool: bindingContract.discover_source_tool,
+                                        }
+                                        : {}),
+                                    ...(bindingContract.do_not !== undefined
+                                        ? { do_not: bindingContract.do_not }
+                                        : {}),
+                                    ...(bindingContract.minimal_layout !== undefined
+                                        ? { minimal_layout: bindingContract.minimal_layout }
+                                        : {}),
+                                },
+                            }
+                            : {}),
+                    }),
+                    includeMeta: false,
+                });
+                return withSiteMeta(structuredResult(applyMaxChars(prependTextBlock(toolkitResult, descriptorNoteBlock), maxChars), {
                     name,
-                    label,
-                    origin,
-                    fields,
-                    ...(bindingContract !== undefined
+                    ...(label !== undefined ? { label } : {}),
+                    ...(origin !== undefined ? { origin } : {}),
+                    ...(descriptorFeedback !== undefined
                         ? {
-                            bindingContract: {
-                                kind: bindingContract.kind,
-                                pattern: bindingContract.pattern,
-                                ...(bindingContract.child_type !== undefined
-                                    ? { child_type: bindingContract.child_type }
-                                    : {}),
-                                ...(bindingContract.binding_target_props !== undefined
-                                    ? {
-                                        binding_target_props: bindingContract.binding_target_props,
-                                    }
-                                    : {}),
-                                ...(bindingContract.canonical_text_prop !== undefined
-                                    ? {
-                                        canonical_text_prop: bindingContract.canonical_text_prop,
-                                    }
-                                    : {}),
-                                ...(bindingContract.location_prop !== undefined
-                                    ? { location_prop: bindingContract.location_prop }
-                                    : {}),
-                                ...(bindingContract.set_via_tool !== undefined
-                                    ? { set_via_tool: bindingContract.set_via_tool }
-                                    : {}),
-                                ...(bindingContract.discover_source_tool !== undefined
-                                    ? {
-                                        discover_source_tool: bindingContract.discover_source_tool,
-                                    }
-                                    : {}),
-                                ...(bindingContract.do_not !== undefined
-                                    ? { do_not: bindingContract.do_not }
-                                    : {}),
-                                ...(bindingContract.minimal_layout !== undefined
-                                    ? { minimal_layout: bindingContract.minimal_layout }
-                                    : {}),
-                            },
+                            available_fields: [...descriptorFeedback.available_fields],
+                            unknown_fields: [...descriptorFeedback.unknown_fields],
+                            field_coverage: { ...descriptorFeedback.field_coverage },
                         }
                         : {}),
-                }));
-                return withSiteMeta(structuredResult(applyMaxChars(toolkitResult, maxChars), {
-                    name,
-                    ...(label !== undefined ? { label } : {}),
-                    ...(origin !== undefined ? { origin } : {}),
+                    ...(descriptorNote !== ''
+                        ? { projection_warning: descriptorNote }
+                        : {}),
+                    ...(fieldsParam !== undefined && fieldsParam.length > 0
+                        ? { projected_fields: [...fieldsParam] }
+                        : {}),
+                    ...(groups !== undefined ? { groups } : {}),
+                    ...(renderRules.renders_only_if !== undefined
+                        ? { renders_only_if: renderRules.renders_only_if }
+                        : {}),
+                    ...(renderRules.blanked_by_parent !== undefined
+                        ? { blanked_by_parent: renderRules.blanked_by_parent }
+                        : {}),
+                    ...(renderRules.media_autoswap !== undefined
+                        ? { media_autoswap: renderRules.media_autoswap }
+                        : {}),
+                    ...(renderRules.placeholder_fallback !== undefined
+                        ? { placeholder_fallback: renderRules.placeholder_fallback }
+                        : {}),
+                    ...(sharedRules.rules !== undefined ? { rules: sharedRules.rules } : {}),
+                    ...(sharedRules.rule_notes !== undefined
+                        ? { rule_notes: sharedRules.rule_notes }
+                        : {}),
+                    ...(claimProvenance !== undefined
+                        ? { claims_verified_on: claimProvenance }
+                        : {}),
                     ...(fields !== undefined ? { fields } : {}),
                     field_count: fieldCount,
+                    returned_count: returnedCount,
+                    ...(nextStep !== undefined ? { next_step: nextStep } : {}),
                     ...(bindingContract !== undefined
                         ? { binding_contract: bindingContract }
                         : {}),