@wootsup/yt-builder-mcp 1.12.0 → 2.0.0

package/dist/tools/inspection.js

@@ -1,59 +1,48 @@
-/**
- * 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 } 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 { 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, FIELD_NAMES, FIELD_NAME_CONTAINS, MAX_CHARS, applyMaxChars, projectFields, projectedFieldsEcho, projectionFeedback, projectionWarning, selectDescriptorsByName, } 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';
 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())),
     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(),
-    // 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`.'),
@@ -69,24 +58,6 @@ const TYPE_SCHEMA_OUTPUT_SCHEMA = z.object({
         '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()
@@ -101,28 +72,6 @@ const TYPE_SCHEMA_OUTPUT_SCHEMA = z.object({
         "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()
@@ -140,25 +89,6 @@ const TYPE_SCHEMA_OUTPUT_SCHEMA = z.object({
         .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()
@@ -170,25 +100,6 @@ const TYPE_SCHEMA_OUTPUT_SCHEMA = z.object({
         .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(),
@@ -201,18 +112,9 @@ const TYPE_SCHEMA_OUTPUT_SCHEMA = z.object({
         '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
-    // 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.
+    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']),
@@ -220,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',
@@ -288,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',
@@ -313,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];
@@ -328,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;
@@ -348,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.`,
@@ -400,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.',
             ],
         };
@@ -422,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 {
@@ -432,45 +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.
- *
- * `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) => {
         const name = field.name;
@@ -488,14 +302,6 @@ 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;
@@ -519,15 +325,6 @@ function narrowGroupsToSelection(raw, selected) {
     }
     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');
@@ -556,10 +353,6 @@ function extractRenderRules(schema) {
             };
         }
     }
-    // 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;
@@ -569,34 +362,6 @@ function extractRenderRules(schema) {
     }
     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))
@@ -614,33 +379,6 @@ function extractClaimProvenance(schema) {
         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 : [];
@@ -670,17 +408,10 @@ 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).',
+            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,
@@ -697,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
@@ -710,13 +437,15 @@ 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 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, {
@@ -726,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) {
@@ -742,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)
@@ -773,209 +488,135 @@ 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,
-        // 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,
+        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',
-        // 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.',
+            '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;
-                // 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
+                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;
-                // `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 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;
                 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 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);
-                // 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({
@@ -985,12 +626,12 @@ function buildElementTypeGetSchemaTool(pool) {
                         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.
+                        ...(fieldsParam !== undefined && fieldsParam.length > 0 && selected !== undefined
+                            ? {
+                                descriptorNames: selected.map((d) => typeof d.name === 'string' ? d.name : ''),
+                                projectedFields: fieldsParam,
+                            }
+                            : {}),
                         ...(bindingContract !== undefined
                             ? {
                                 bindingContract: {
@@ -1032,24 +673,24 @@ function buildElementTypeGetSchemaTool(pool) {
                     }),
                     includeMeta: false,
                 });
-                return withSiteMeta(structuredResult(applyMaxChars(toolkitResult, maxChars), {
+                return withSiteMeta(structuredResult(applyMaxChars(prependTextBlock(toolkitResult, descriptorNoteBlock), maxChars), {
                     name,
                     ...(label !== undefined ? { label } : {}),
                     ...(origin !== undefined ? { origin } : {}),
+                    ...(descriptorFeedback !== undefined
+                        ? {
+                            available_fields: [...descriptorFeedback.available_fields],
+                            unknown_fields: [...descriptorFeedback.unknown_fields],
+                            field_coverage: { ...descriptorFeedback.field_coverage },
+                        }
+                        : {}),
+                    ...(descriptorNote !== ''
+                        ? { projection_warning: descriptorNote }
+                        : {}),
+                    ...(fieldsParam !== undefined && fieldsParam.length > 0
+                        ? { projected_fields: [...fieldsParam] }
+                        : {}),
                     ...(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 }
                         : {}),
@@ -1059,33 +700,20 @@ function buildElementTypeGetSchemaTool(pool) {
                     ...(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,
+                    ...(nextStep !== undefined ? { next_step: nextStep } : {}),
                     ...(bindingContract !== undefined
                         ? { binding_contract: bindingContract }
                         : {}),