@wootsup/yt-builder-mcp 1.11.0 → 1.12.0

package/dist/tools/inspection.js

@@ -8,15 +8,17 @@
  *
  * @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 { 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, MAX_CHARS, applyMaxChars, projectFields, projectedFieldsEcho, projectionFeedback, projectionWarning, selectDescriptorsByName, } from './sparse-fields.js';
 import { ITEM_CHILDREN_OF_CONTAINER } from './multi-items/item-container-map.js';
+import { budgetedTableResult } from "./budgeted-table.js";
+import { RESPONSE_BUDGET } from "./response-budget.js";
 // ─── outputSchemas (Wave G.2 §4) ─────────────────────────────────────
 const TYPES_LIST_OUTPUT_SCHEMA = z.object({
     items: z.array(z.record(z.string(), z.unknown())),
@@ -38,7 +40,173 @@ const TYPE_SCHEMA_OUTPUT_SCHEMA = z.object({
     // field descriptors — each `name` is a valid prop key for element_add /
     // _update_settings.
     fields: z.array(z.record(z.string(), z.unknown())).optional(),
+    // Task 7b (plan 2026-07-27-02): the fieldset groups' own sentences, stated
+    // ONCE each and joined on a field's `group`. YOOtheme parks the semantics of
+    // a whole class of fields there rather than on the field
+    // (grid.image_width/image_height carry the crop rule this way and declare
+    // nothing themselves), so a caller that reads only a descriptor's
+    // `description` misses the rule it needed. Narrows with the descriptor
+    // selection, so a `field_names` read carries only the groups it named.
+    //
+    // The RULE is stated here rather than in the 600-char tool description,
+    // which names only the key. Same carrier choice, and the same reason, as the
+    // `site_id` param description in `docs/mcp-response-budgets.md` §9.2: a
+    // schema `.describe()` rides in the wire `tools/list` payload (measured
+    // there at 19.2 % of it for `outputSchema`), so this states MORE while
+    // costing the tool-description budget nothing.
+    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.'),
+    // Task 7b Step 4 (plan 2026-07-27-02, inventory groups B, A, L). NOT narrowed
+    // by a field_names/name_contains selection: these describe the element TYPE,
+    // and the caller asking for two fields of a 154-field type is exactly the
+    // caller about to write those two fields.
+    //
+    // The `.describe()` texts below are deliberately terse. They carry ONLY what
+    // a caller cannot read off the arrays themselves — the CNF semantics, the
+    // deletion consequence, the `&&`/`parent.` grammar, and what each
+    // media_autoswap key means. Everything that IS in the data (which props, which
+    // flags, which elements invert the precedence) is stated per element in the
+    // RESPONSE, where it costs bytes once per call instead of once per session in
+    // every host's tools/list.
+    //
+    // MEASURED, 2026-07-28: a first draft of these describes added 1953 B to the
+    // wire tools/list (136422 B → 138375 B, `tests/perf/token-baseline.test.ts`)
+    // and made this tool the largest entry on the server. Spending ~2 KB of every
+    // session's discovery payload to narrate four keys defeats the point of
+    // shipping them as arrays, so the prose was cut to the non-derivable facts.
+    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.'),
+    // 2026-07-28. The shipped text said only "it BLANKS (not CSS-hide)", which
+    // rules out ONE wrong reading and leaves the other: a caller that turns off
+    // a container's `show_title`, watches its titles disappear, and reads
+    // "BLANKS" concludes its write was destroyed — and reaches for the one
+    // repair that cannot work, re-writing props that were never lost.
+    //
+    // MEASURED, YOOtheme Pro 5.0.37 (a two-item `grid`, written with
+    // element_update_settings + page_publish, read back with page_get_layout and
+    // from the published page): `show_title:false` took rendered `.el-title` from
+    // 2 to 0 with neither title string anywhere in the section HTML, while the
+    // grid's stored children subtree stayed byte-identical (equal sha256, 699 B,
+    // `diff` exit 0) and the whole-layout diff was ONE added line — the flag, on
+    // the GRID node, nothing on any child. Flipping it back restored the baseline
+    // render byte-for-byte. Stripped to `link` alone the items left the output
+    // entirely (`.el-item` 2 -> 0, `.uk-grid` 2 -> 1) while the read-back still
+    // carried `link` and `link_text` in full. The full measurement, including the
+    // source-bound case, is in SKILL.md; the pin is in
+    // tests/tools/inspection-blanked-by-parent-describe.test.ts.
+    //
+    // The two halves are BOTH here, and deliberately not split with SKILL.md,
+    // because the audience the defect reached is the cold agent reading one tool
+    // response with no skill installed.
+    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.'),
+    // Task 7b Steps 5-6 (plan 2026-07-27-02, inventory groups P/M/D/E/K/S/O/N/F).
+    // Two keys, one mechanism: an id list that costs ~14 B per reference, and the
+    // note texts stated ONCE per response. The alternative measured at 2.5-3.0 KB
+    // (the inventory's per-prop cost table) because `link_striptags` alone is
+    // referenced by 17 (type, prop) pairs.
+    //
+    // These two `.describe()` texts say only what a caller CANNOT read off one
+    // response: that `rules` is a POINTER (an opaque id is useless without knowing
+    // where it resolves), why the pointed-at rule is worth following, and the
+    // narrowing asymmetry (element-level ids always resolve, field-level ones only
+    // while their field is returned — invisible from a single response).
+    //
+    // MEASURED, 2026-07-28: a first draft of these two texts (495 chars) cost
+    // 704 B of the wire tools/list and made this tool the largest entry on the
+    // server. The full prose lives in SKILL.md's `rules` + `rule_notes` section
+    // instead, where it costs the wire nothing and is ledger-PINNED
+    // (skill-md-behavior-truth.test.ts) so it cannot silently vanish — the same
+    // carrier choice, and the same reason, as `placeholder`/`enum_labels` in the
+    // tool description above.
+    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.'),
+    // 2026-07-28. Found by LIVE verification: both 4.5.33 sites (wp-dev,
+    // joomla-dev — their own yootheme_builder_health says so) were served
+    // `no_effect: "No effect in YOOtheme Pro 5.0.37 …"`. The claim was read in a
+    // 5.0.37 tree; nobody read theirs. Every version-scoped key in this response
+    // now names the build it was read on, and `status` says whether that is the
+    // build you are running.
+    //
+    // `keys` is the BOUND, and it is why the describe below can say "those
+    // ONLY". This response also carries `binding_contract`, whose `child_type`
+    // comes from ItemContainerMap — read on YT-Pro 4.5.33, a DIFFERENT build,
+    // with a per-build difference recorded in that file's own docblock. The
+    // first draft described this record as covering "the version-scoped keys
+    // here", which vouched for it. Listing the covered keys ends that by
+    // construction rather than by prose kept in sync with a growing surface.
+    //
+    // The rule rides in this `.describe()` rather than the 600-char tool
+    // description for the same reason `groups` does — a schema describe is on the
+    // wire tools/list payload and costs the tool-description budget nothing
+    // (`docs/mcp-response-budgets.md` §9.2).
+    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.'),
+    // The descriptors the TYPE declares — unchanged by a selection, so a caller
+    // always knows the size of what it did not ask for (Task 4 / P2).
     field_count: z.number(),
+    // The descriptors THIS response carries. Equal to `field_count` when no
+    // `field_names`/`name_contains` selection was made.
+    returned_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
@@ -283,8 +451,25 @@ 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).
+ * pass through untouched.
+ *
+ * `group:'node-level'` OVERRIDES whatever group the descriptor arrived with.
+ * That is a change from "only fill an ABSENT group", and it is load-bearing:
+ * Task 7b Step 1 (plan 2026-07-27-02) taught the PHP projection to read
+ * YOOtheme's fieldset TREE, and YOOtheme does list some of these keys inside a
+ * UI group. MEASURED over the real element.php configs: `column.source` and
+ * `column.id` now arrive as `{"group":"Advanced"}`, which under the old
+ * fill-if-absent rule SUPPRESSED the node-level marker on exactly the two keys
+ * whose mis-write is silent (`props.source` is ignored; the real `source` is a
+ * sibling of `props`). "This key is not a prop" outranks "this key sits in the
+ * Advanced panel" — the first prevents a silent no-op, the second is navigation.
+ * The `value_hint` carried the warning either way, but a consumer branching on
+ * `group` would have lost it.
+ *
+ * Safe against the two synthetic groups the PHP side assigns
+ * (`runtime-accepted` on button.content/link, `responsive-width` on
+ * column.width_*): neither list contains any of these four names, so no
+ * deliberate group is clobbered.
  */
 function annotateNodeLevelFields(fields) {
     return fields.map((field) => {
@@ -294,7 +479,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,6 +488,184 @@ function annotateNodeLevelFields(fields) {
         };
     });
 }
+/**
+ * Narrow the root `groups` list to the groups the SELECTED descriptors name.
+ *
+ * Returns `undefined` when the backend sent no usable list, so a schema without
+ * groups (and a payload from an older backend) adds no key and the response
+ * stays byte-identical to before. The PHP transport's twin is
+ * `McpElementTypeGetSchemaHandler::narrowGroups()`.
+ */
+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));
+}
+/**
+ * Lift the three element-level render rules off the backend payload.
+ *
+ * Every branch is shape-VALIDATED rather than cast, so a malformed or older
+ * backend contributes no key and the response stays byte-identical to before —
+ * the same fail-quiet contract as `narrowGroupsToSelection`. A half-valid
+ * `media_autoswap` (no `precedence`) is dropped whole rather than forwarded
+ * partially: `precedence` is the fact, and the optional keys qualify it.
+ */
+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 } : {}),
+            };
+        }
+    }
+    // An EMPTY `fills` is meaningful (the merge fires but adds nothing non-empty,
+    // so the gate still drops the node) and is forwarded. A missing or malformed
+    // `suppressed_by` is absence: it is the half that decides absent-vs-empty, and
+    // half a rule here turns that decision into a guess.
+    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;
+}
+/**
+ * Which YOOtheme build the version-scoped keys in this response were READ on,
+ * versus what the site reports (2026-07-28).
+ *
+ * Found by live verification: `element_type_get_schema({element_type:'grid',
+ * field_names:['lightbox_image_orientation'], site_id:'wp-dev'})` returned
+ * `no_effect: "No effect in YOOtheme Pro 5.0.37 …"` on a site whose own
+ * `yootheme_builder_health` reports `"yootheme_version":"4.5.33"`. Same on
+ * `joomla-dev`. The PHP side now frames such a claim for the build it is
+ * actually talking to; this lifts the record onto the MCP surface so the
+ * framing survives the hop.
+ *
+ * Fail-quiet and shape-VALIDATED like {@link extractRenderRules}: a backend that
+ * predates the record (any deployed 1.11.0, which is every site today) sends no
+ * key, and the response stays byte-identical to before. `here` is `null` in the
+ * `unknown` stance — a real value, so it is validated as nullable rather than
+ * dropped, because "we could not resolve it" is exactly the fact worth shipping.
+ *
+ * ── `keys` IS REQUIRED, NOT OPTIONAL ───────────────────────────────────────
+ * `keys` is the record's BOUND: the response keys it vouches for. Without it the
+ * record is an unbounded statement about the whole response — and this function's
+ * own caller composes `binding_contract` into that response from
+ * `ItemContainerMap::MAP`, read on YT-Pro 4.5.33, a DIFFERENT build from the one
+ * the record names. A record that reached the wire unbounded would therefore
+ * assert exactly the thing it exists to prevent. No shipped plugin emits the
+ * unbounded shape (the record has never been released), so requiring the bound
+ * costs no compatibility and closes the hole by construction.
+ */
+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 };
+}
+/**
+ * Task 7b Steps 5-6 (plan 2026-07-27-02, inventory groups P, M, D, E, K, S, O, N,
+ * F) — the SHARED render-rule notes: `rules` (a list of ids, on the element and on
+ * each field) resolved by `rule_notes` (id → the one shared sentence set).
+ *
+ * Distinct from {@link extractRenderRules} above, which forwards the four
+ * machine-readable Step-4 arrays (`renders_only_if` & co.). These are the nine
+ * groups an agent cannot deduce and that have no array form — prose, paid for
+ * ONCE per response instead of once per referencing prop.
+ *
+ * Narrowing is the point of this function. `rule_notes` must carry exactly the
+ * ids the RESPONSE still references, so a `field_names` read of two descriptors
+ * out of 154 does not ship the notes of the 152 it dropped — that would undo
+ * Task 4 for the narrow reads it exists to serve, which is the same failure
+ * {@link narrowGroupsToSelection} exists to prevent. The element's OWN `rules`
+ * always survive: they describe the container the caller is about to write into,
+ * not any one descriptor.
+ *
+ * Read off `selected` (the descriptors this response carries) rather than the
+ * sub-key-projected `fields`, for the same reason `groups` is: `fields:["type"]`
+ * strips the `rules` key itself, and narrowing on the projected list would then
+ * delete every note the caller can still see referenced nowhere.
+ *
+ * A referenced id with no note is dropped rather than forwarded as a dangling
+ * pointer, and a note nobody references is dropped rather than forwarded as
+ * dead weight.
+ */
+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({
@@ -317,15 +680,15 @@ export function buildInspectionTools(pool) {
                 '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.',
+                'are aliases (same value).',
             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;
@@ -349,12 +712,13 @@ export function buildInspectionTools(pool) {
                     const feedback = projectionFeedback(mappedRecords, fields);
                     // F23 (2026-06-09): shared loud-warning helper.
                     const unknownNote = projectionWarning(feedback);
-                    const toolkitResult = tableResult(mappedRecords, {
+                    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.',
-                    });
+                        includeMeta: include_meta,
+                    }, RESPONSE_BUDGET.BULKY);
                     return withSiteMeta(structuredResult(toolkitResult, {
                         items,
                         total: items.length,
@@ -414,6 +778,13 @@ function buildElementTypeGetSchemaTool(pool) {
         // blob). `fields[]` sparse-projects each field descriptor to the requested
         // sub-keys; `max_chars` caps the text leg — mirroring the sibling reads.
         fields: FIELDS,
+        // Plan 2026-07-27-02 Task 4 (P1, closes F8): SELECT which descriptors
+        // come back, instead of receiving all 154 with 88.6 % of them cut off
+        // (measured: `docs/mcp-response-size-baseline.md` §2). Orthogonal to
+        // `fields[]` — that one picks sub-keys OF a descriptor, these pick the
+        // descriptors themselves, and a selected one is returned COMPLETE.
+        field_names: FIELD_NAMES,
+        name_contains: FIELD_NAME_CONTAINS,
         max_chars: MAX_CHARS,
     };
     const TYPE_SCHEMA_REFINED = z
@@ -425,14 +796,77 @@ function buildElementTypeGetSchemaTool(pool) {
     });
     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.',
+        // 544 chars — the per-tool budget is 600
+        // (`tests/gateway/description-length.test.ts`). Task 4 bought the room
+        // for the selector by tightening prose, not by dropping a fact; Task 6
+        // bought the room for `text?`/`description?` the same way. The five
+        // edits that paid for it are pure wording, no fact removed: "Returns
+        // each field as" → "Each field:", "prop keys are rejected" → "prop keys
+        // rejected", "hidden in the UI" → "hidden in UI", "for
+        // containers/items" → "(containers/items)", and "valid_prop_keys +
+        // did_you_mean" → "valid_prop_keys+did_you_mean" (the same `a+b` form
+        // "value_hint+enum" already uses two clauses later).
+        //
+        // Task 5b Step 3 (2026-07-28) — RESTORED "boolean". Task 4's tightening
+        // pass went one edit too far: `checkbox = boolean true/false` became
+        // `checkbox = true/false` (commit 139cb7d68). That deleted the word
+        // carrying the VALUE TYPE, and this clause was the only statement of a
+        // checkbox prop's type anywhere on the tool surface — an agent writing
+        // `element_update_settings({props:{image_expand:"1"}})` had nothing left
+        // to tell it the field wants a boolean rather than a truthy string.
+        // Naming the two values is not naming the type. Cost of the restore: 8
+        // chars, paid for many times over by dropping the repeated site_id
+        // sentence (57 chars here; the fact now rides in the `site_id` param
+        // description, which is where a host reads it while building the call).
+        // Pinned in tests/skills/skill-md-behavior-truth.test.ts (Task 5b block).
+        // Task 7b Steps 1+3 (plan 2026-07-27-02): the descriptor grew two
+        // DECISION-RELEVANT keys, so the illustrative shape names them.
+        //  - `groups[]` — the enclosing fieldset group's own sentence, at the
+        //    schema ROOT and joined on the field's `group`. YOOtheme parks the
+        //    semantics of a whole class of fields there rather than on the field
+        //    (grid.image_width/image_height carry the crop rule this way and
+        //    declare nothing themselves), so a caller that reads only
+        //    `description` misses the rule it needed. It is the one key of the
+        //    set NOT self-describing from a field descriptor — a field naming
+        //    `group:"Width/Height"` gives no reason to look at a root key — so
+        //    this is where the budget is spent. The RULE rides in the
+        //    `outputSchema` `.describe()`, which is on the wire and costs this
+        //    budget nothing (`docs/mcp-response-budgets.md` §9.2).
+        //    Was `group_description?` per field until the hoist measured 32
+        //    occurrences of 5 distinct strings.
+        //  - `no_effect` — the prop is declared and read by nothing. Naming it
+        //    here is what stops an agent treating the descriptor as writable
+        //    guidance; the VALUE carries the full read fact + the build it was
+        //    read on, so no further prose is spent in this budget.
+        // The shape list is illustrative, not exhaustive (it has never named
+        // `default`/`enable`/`show`/`filter`/`constraint`). `placeholder` and
+        // `enum_labels` are therefore documented in SKILL.md rather than
+        // here — the budget is nearly spent, and both are self-describing once
+        // seen in a response, sitting next to the key they qualify
+        // (`enum_labels` beside `enum`).
+        // Space for the two additions was earned inside this same description,
+        // not by raising the budget: "Fetch a type's prop schema before" →
+        // "Prop schema; read before", "unknown prop keys" → "unknown keys"
+        // (the word `prop` is already in the opening clause), and "Read
+        // value_hint+enum first" → "value_hint+enum first". MEASURED: 544 →
+        // 595 chars, inside the 600-char tool-description budget.
+        // No fact left: every clause the pre-change description carried is still
+        // here, and the pinned phrases are VERBATIM — "checkbox = boolean
+        // true/false", "Select descriptors: field_names/name_contains",
+        // "field_count/returned_count", "Bound size with fields[]/max_chars".
+        // ("Bound size:" was tried and correctly REJECTED by the P4 max_chars
+        // pin in tests/skills/skill-md-behavior-truth.test.ts — the four chars
+        // were found elsewhere rather than by weakening the pin.)
+        description: 'Prop schema; read before element_add/element_update_settings: ' +
+            'unknown keys rejected (error lists valid_prop_keys+' +
+            'did_you_mean). Field: {name,type,label?,text?,description?,enum?,' +
+            'value_hint?,group?,no_effect?} + groups[] + ' +
+            'field_count/returned_count + binding_contract ' +
+            '(containers/items). 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. Select ' +
+            'descriptors: field_names/name_contains. 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.
@@ -493,64 +927,165 @@ function buildElementTypeGetSchemaTool(pool) {
                     ? args.fields
                     : undefined;
                 const maxChars = typeof args.max_chars === 'number' ? args.max_chars : undefined;
-                const fields = annotatedFields !== undefined
-                    ? projectFields(annotatedFields, fieldsParam, [])
+                // Task 4 (P1): SELECT the descriptors first, THEN sub-key-project
+                // them. The order is load-bearing — `fields:["type"]` strips the
+                // very `name`/`label` the selector matches on, so projecting first
+                // would make the two arguments mutually exclusive instead of
+                // composable.
+                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 selected = annotatedFields !== undefined
+                    ? selectDescriptorsByName(annotatedFields, fieldNamesParam, nameContains)
+                    : undefined;
+                const fields = selected !== undefined
+                    ? projectFields(selected, fieldsParam, [])
                     : undefined;
+                // `field_count` keeps its meaning — the descriptors the TYPE has —
+                // so a call with no selector is unchanged. `returned_count` is what
+                // this response actually carries, so a selection is never silent
+                // (P2) and the caller can see what it did not ask for.
                 const fieldCount = annotatedFields !== undefined ? annotatedFields.length : 0;
+                const returnedCount = selected !== undefined ? selected.length : 0;
+                // Task 7b (plan 2026-07-27-02): each fieldset group's sentence is
+                // stated ONCE at the schema root and joined on the field's
+                // `group` (MEASURED: 32 occurrences of 5 distinct strings, 7334 B
+                // carrying 1204 B of payload). Narrow it with the selection —
+                // otherwise a two-descriptor read of a 154-field type ships every
+                // group sentence the type has, undoing Task 4 for exactly the
+                // narrow reads it exists to serve. Read off `selected`, i.e.
+                // BEFORE the `fields[]` sub-key whitelist: `fields:["type"]`
+                // strips the join key, and narrowing on the projected list would
+                // then delete every sentence. Same ordering rule, same reason, as
+                // selection-before-projection above.
+                const groups = narrowGroupsToSelection(schema.groups, selected);
+                // Task 7b Step 4: the element-level render rules. Read off
+                // `schema`, NOT narrowed by `selected` — see the pass-through
+                // comment at the structuredResult call below for why.
+                const renderRules = extractRenderRules(schema);
+                // Task 7b Steps 5-6: the shared rule notes, narrowed to the ids
+                // this response still references. See extractSharedRuleNotes().
+                const sharedRules = extractSharedRuleNotes(schema, selected);
+                // 2026-07-28: which build the version-scoped keys above were read
+                // on. Element-level like `renderRules`, and for the same reason —
+                // it qualifies claims the caller is about to act on, so a narrow
+                // field selection must not be able to drop it.
+                const claimProvenance = extractClaimProvenance(schema);
                 // 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 bindingContract = deriveBindingContract(name);
-                const toolkitResult = detailResult(buildTypeSchemaDetail({
-                    name,
-                    label,
-                    origin,
-                    fields,
-                    ...(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 }
-                                    : {}),
-                            },
-                        }
-                        : {}),
-                }));
+                const toolkitResult = detailResult({
+                    ...buildTypeSchemaDetail({
+                        name,
+                        label,
+                        origin,
+                        fields,
+                        fieldCount,
+                        returnedCount,
+                        // Deliberately NOT handed to the detail renderer: the TS
+                        // text leg is a NAME|TYPE|LABEL table and never carried
+                        // `group_description` either, so the hoist moves the fact
+                        // between root and field WITHOUT adding a new payload to
+                        // the text leg. Its carrier is unchanged —
+                        // `structuredContent` here, the JSON text leg on PHP.
+                        ...(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(toolkitResult, maxChars), {
                     name,
                     ...(label !== undefined ? { label } : {}),
                     ...(origin !== undefined ? { origin } : {}),
+                    ...(groups !== undefined ? { groups } : {}),
+                    // Task 7b Step 4 (plan 2026-07-27-02, inventory groups B/A/L):
+                    // element-level render rules, forwarded whole. Deliberately
+                    // NOT narrowed by the descriptor selection the way `groups`
+                    // is — a group sentence belongs to the fields it annotates,
+                    // but "this element is deleted at render when these props are
+                    // empty" is true of the element regardless of which
+                    // descriptors were asked for, and suppressing it on a narrow
+                    // read would hide it from exactly the caller about to write.
+                    //
+                    // Same carrier choice as `groups`: structuredContent here,
+                    // the JSON text leg on the PHP transport. The TS text leg is
+                    // a NAME|TYPE|LABEL table and never carried element-level
+                    // keys, so nothing is added to it.
+                    ...(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 }
+                        : {}),
+                    // Directly after the gate it qualifies: a caller that sees
+                    // `renders_only_if` alone concludes "absent props render
+                    // nothing", which is false on 27 of the 28 gated types.
+                    ...(renderRules.placeholder_fallback !== undefined
+                        ? { placeholder_fallback: renderRules.placeholder_fallback }
+                        : {}),
+                    // Task 7b Steps 5-6: the element's own rule ids, then the note
+                    // texts resolving every id the response still references
+                    // (element-level or on a returned field). Placed BEFORE
+                    // `fields` so a reader meets the vocabulary before the
+                    // descriptors that use it.
+                    ...(sharedRules.rules !== undefined ? { rules: sharedRules.rules } : {}),
+                    ...(sharedRules.rule_notes !== undefined
+                        ? { rule_notes: sharedRules.rule_notes }
+                        : {}),
+                    // 2026-07-28: LAST of the element-level keys and still BEFORE
+                    // `fields`, so a reader meets the provenance of the claims
+                    // before the descriptors that carry them — the same ordering
+                    // argument as `rule_notes` above. A `differs`/`unknown` status
+                    // is what tells a caller that `no_effect_unverified` on a
+                    // descriptor below is a report, not a fact about their site.
+                    ...(claimProvenance !== undefined
+                        ? { claims_verified_on: claimProvenance }
+                        : {}),
                     ...(fields !== undefined ? { fields } : {}),
                     field_count: fieldCount,
+                    returned_count: returnedCount,
                     ...(bindingContract !== undefined
                         ? { binding_contract: bindingContract }
                         : {}),