@wootsup/yt-builder-mcp 1.1.7 → 1.3.0

package/dist/tools/layout-flatten.js

@@ -8,11 +8,13 @@
  *
  *   - Walk-order: depth-first, parent BEFORE children, original child
  *     order preserved (no sort).
- *   - `path` uses JSON-Pointer-style notation rooted at `/layout/<key>`
- *     and descends via `/children/<index>` segments. The root segments
- *     mirror the keys the REST plugin produces (string keys "0","1",…
- *     when the top-level layout is an object; numeric indices when it
- *     happens to be an array).
+ *   - `path` uses JSON-Pointer-style notation rooted at
+ *     `/layout/children/<key>` and descends via `/children/<index>`
+ *     segments (M5: the top-level anchor carries the real `children`
+ *     segment so `rel_path` mirrors the element-path input contract).
+ *     The root keys mirror what the REST plugin produces (string keys
+ *     "0","1",… when the top-level layout is an object; numeric indices
+ *     when it happens to be an array).
  *   - `parent_path` is `null` for top-level entries.
  *   - The emitted record's `children` field is REMOVED — children become
  *     their own emitted entries with their own `path`. Keeping the nested
@@ -46,7 +48,16 @@ export function flattenLayout(layout) {
         ? layout.map((v, i) => [String(i), v])
         : Object.entries(layout);
     for (const [key, node] of entries) {
-        walk(node, `/layout/${key}`, null, 0, out);
+        // M5: anchor top-level nodes under the real `/children/<key>` segment
+        // (not a bare `/layout/<key>`). The canonical storage pointer for a
+        // top-level element is `/templates/<id>/layout/children/<key>`, so this
+        // makes both `path` (→ `/layout/children/<key>`) and `rel_path`
+        // (→ `/children/<key>`, after the `/layout` strip on line below) mirror
+        // it. Previously the bare anchor produced rel_path `/<key>/...` which
+        // the element-path input normaliser rejects (it only lifts forms that
+        // start with `/children/`), contradicting the pointer_hint's promise
+        // that the emitted rel_path can be passed straight back.
+        walk(node, `/layout/children/${key}`, null, 0, out);
     }
     return out;
 }

package/dist/tools/layout-flatten.js.map

@@ -1 +1 @@
-{"version":3,"file":"layout-flatten.js","sourceRoot":"","sources":["../../src/tools/layout-flatten.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"layout-flatten.js","sourceRoot":"","sources":["../../src/tools/layout-flatten.ts"],"names":[],"mappings":"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"}

package/dist/tools/multi-items/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAKH,KAAK,iBAAiB,EACzB,MAAM,oBAAoB,CAAC;AAW5B,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CA0DnF"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAKH,KAAK,iBAAiB,EACzB,MAAM,oBAAoB,CAAC;AAY5B,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CAyEnF"}

package/dist/tools/multi-items/builders.js

@@ -23,7 +23,13 @@ import { ELEMENT_PATH, ETAG, SITE_ID_SCHEMA, TEMPLATE_ID } from '../shared-schem
 import { defineTool, destructive, readOnly, withSiteMeta, } from '../tool-builder.js';
 import { CLEAN_IMPLODE_OUTPUT_SCHEMA, handleCleanImplodeDirectives, } from './clean-implode-handler.js';
 import { INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA, handleInspectMultiItemsBinding, } from './inspect-handler.js';
+import { InspectionCache } from './inspection-cache.js';
 export function buildMultiItemsTools(pool) {
+    // 6.2 — one shared inspection cache per tool-build, keyed on
+    // (template_id, element_path, global-etag) with a 60s TTL. Survives
+    // across calls within a server lifetime; a write bumps the global
+    // etag and naturally invalidates the entry.
+    const inspectionCache = new InspectionCache();
     // W6.3 — per-handler resolveSiteOrError. The handlers consume a
     // single-field `MultiItemsHandlerDeps`, so we synthesise it inline
     // with the resolved client.
@@ -31,8 +37,17 @@ export function buildMultiItemsTools(pool) {
         defineTool({
             name: 'yootheme_builder_inspect_multi_items_binding',
             description: 'Reports Multi-Items binding state: container/item pair (grid↔grid_item, ' +
-                'slideshow↔slideshow_item, …), current binding level (none|container|item), ' +
-                'and a recommended_fix when the binding sits on the container instead of the child. ' +
+                'slideshow↔slideshow_item, map↔map_item, …), current binding level ' +
+                '(none|container|item), and a recommended_fix when the binding sits on the ' +
+                'container instead of the child. ' +
+                // F39 (2026-06-10): a bound map_item with NO `location` field
+                // renders 0 markers → blocking map_location_warning.
+                'For map/map_item, a bound item without a `location` ("lat,lng") field is ' +
+                'flagged as a blocking map_location_warning (renders 0 markers). ' +
+                // F189 (2026-06-12): a `…List` on a grid_item with nested children
+                // is render-dead (leaf renderer) → blocking iterator_is_leaf_renderer.
+                'A List on a grid_item with nested children → blocking ' +
+                'iterator_is_leaf_renderer (children never render). ' +
                 'Operates on the default site unless site_id is provided.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
@@ -42,7 +57,7 @@ export function buildMultiItemsTools(pool) {
             outputSchema: INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA,
             annotations: readOnly('Inspect Multi-Items Binding'),
             handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => {
-                const deps = { client };
+                const deps = { client, cache: inspectionCache };
                 return withSiteMeta(await handleInspectMultiItemsBinding(deps, rest), site);
             }),
         }),

package/dist/tools/multi-items/builders.js.map

@@ -1 +1 @@
-{"version":3,"file":"builders.js","sourceRoot":"","sources":["../../../src/tools/multi-items/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EACH,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,GAEf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACH,2BAA2B,EAC3B,4BAA4B,GAC/B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACH,iCAAiC,EACjC,8BAA8B,GAEjC,MAAM,sBAAsB,CAAC;AAE9B,MAAM,UAAU,oBAAoB,CAAC,IAAgB;IACjD,gEAAgE;IAChE,mEAAmE;IACnE,4BAA4B;IAC5B,OAAO;QACH,UAAU,CAAC;YACP,IAAI,EAAE,8CAA8C;YACpD,WAAW,EACP,0EAA0E;gBAC1E,6EAA6E;gBAC7E,qFAAqF;gBACrF,0DAA0D;YAC9D,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;gBACvB,WAAW,EAAE,WAAW;gBACxB,YAAY,EAAE,YAAY;aAC7B;YACD,YAAY,EAAE,iCAAiC;YAC/C,WAAW,EAAE,QAAQ,CAAC,6BAA6B,CAAC;YACpD,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CACpC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;gBAChD,MAAM,IAAI,GAA0B,EAAE,MAAM,EAAE,CAAC;gBAC/C,OAAO,YAAY,CAAC,MAAM,8BAA8B,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;YAChF,CAAC,CAAC;SACT,CAAC;QAEF,UAAU,CAAC;YACP,IAAI,EAAE,2CAA2C;YACjD,WAAW,EACP,4EAA4E;gBAC5E,2EAA2E;gBAC3E,0EAA0E;gBAC1E,wEAAwE;gBACxE,sEAAsE;gBACtE,0DAA0D;YAC9D,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;gBACvB,WAAW,EAAE,WAAW;gBACxB,YAAY,EAAE,YAAY;gBAC1B,IAAI,EAAE,IAAI;gBACV,OAAO,EAAE,CAAC;qBACL,OAAO,EAAE;qBACT,QAAQ,EAAE;qBACV,QAAQ,CACL,iEAAiE;oBAC7D,+DAA+D;oBAC/D,4CAA4C,CACnD;aACR;YACD,YAAY,EAAE,2BAA2B;YACzC,WAAW,EAAE,WAAW,CAAC,0BAA0B,CAAC;YACpD,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CACpC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;gBAChD,MAAM,IAAI,GAA0B,EAAE,MAAM,EAAE,CAAC;gBAC/C,OAAO,YAAY,CAAC,MAAM,4BAA4B,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;YAC9E,CAAC,CAAC;SACT,CAAC;KACL,CAAC;AACN,CAAC"}
+{"version":3,"file":"builders.js","sourceRoot":"","sources":["../../../src/tools/multi-items/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EACH,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,GAEf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACH,2BAA2B,EAC3B,4BAA4B,GAC/B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACH,iCAAiC,EACjC,8BAA8B,GAEjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,UAAU,oBAAoB,CAAC,IAAgB;IACjD,6DAA6D;IAC7D,oEAAoE;IACpE,kEAAkE;IAClE,4CAA4C;IAC5C,MAAM,eAAe,GAAG,IAAI,eAAe,EAA2B,CAAC;IAEvE,gEAAgE;IAChE,mEAAmE;IACnE,4BAA4B;IAC5B,OAAO;QACH,UAAU,CAAC;YACP,IAAI,EAAE,8CAA8C;YACpD,WAAW,EACP,0EAA0E;gBAC1E,oEAAoE;gBACpE,4EAA4E;gBAC5E,kCAAkC;gBAClC,8DAA8D;gBAC9D,qDAAqD;gBACrD,2EAA2E;gBAC3E,kEAAkE;gBAClE,mEAAmE;gBACnE,uEAAuE;gBACvE,wDAAwD;gBACxD,qDAAqD;gBACrD,0DAA0D;YAC9D,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;gBACvB,WAAW,EAAE,WAAW;gBACxB,YAAY,EAAE,YAAY;aAC7B;YACD,YAAY,EAAE,iCAAiC;YAC/C,WAAW,EAAE,QAAQ,CAAC,6BAA6B,CAAC;YACpD,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CACpC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;gBAChD,MAAM,IAAI,GAA0B,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;gBACvE,OAAO,YAAY,CAAC,MAAM,8BAA8B,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;YAChF,CAAC,CAAC;SACT,CAAC;QAEF,UAAU,CAAC;YACP,IAAI,EAAE,2CAA2C;YACjD,WAAW,EACP,4EAA4E;gBAC5E,2EAA2E;gBAC3E,0EAA0E;gBAC1E,wEAAwE;gBACxE,sEAAsE;gBACtE,0DAA0D;YAC9D,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;gBACvB,WAAW,EAAE,WAAW;gBACxB,YAAY,EAAE,YAAY;gBAC1B,IAAI,EAAE,IAAI;gBACV,OAAO,EAAE,CAAC;qBACL,OAAO,EAAE;qBACT,QAAQ,EAAE;qBACV,QAAQ,CACL,iEAAiE;oBAC7D,+DAA+D;oBAC/D,4CAA4C,CACnD;aACR;YACD,YAAY,EAAE,2BAA2B;YACzC,WAAW,EAAE,WAAW,CAAC,0BAA0B,CAAC;YACpD,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CACpC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;gBAChD,MAAM,IAAI,GAA0B,EAAE,MAAM,EAAE,CAAC;gBAC/C,OAAO,YAAY,CAAC,MAAM,4BAA4B,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;YAC9E,CAAC,CAAC;SACT,CAAC;KACL,CAAC;AACN,CAAC"}

package/dist/tools/multi-items/clean-implode-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clean-implode-handler.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/clean-implode-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAKH,KAAK,UAAU,EAClB,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,2BAA2B;;;;;;;;;iBAWtC,CAAC;AAEH,MAAM,WAAW,uBAAuB;IACpC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC/B;AAED,wBAAsB,4BAA4B,CAC9C,EAAE,MAAM,EAAE,EAAE,uBAAuB,EACnC,EACI,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,GACV,EAAE;IACC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,GACF,OAAO,CAAC,UAAU,CAAC,CAgCrB"}
+{"version":3,"file":"clean-implode-handler.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/clean-implode-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAKH,KAAK,UAAU,EAClB,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,2BAA2B;;;;;;;;;iBAWtC,CAAC;AAEH,MAAM,WAAW,uBAAuB;IACpC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC/B;AAED,wBAAsB,4BAA4B,CAC9C,EAAE,MAAM,EAAE,EAAE,uBAAuB,EACnC,EACI,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,GACV,EAAE;IACC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,GACF,OAAO,CAAC,UAAU,CAAC,CAgCrB"}

package/dist/tools/multi-items/clean-implode-handler.js

@@ -12,7 +12,7 @@
  * @license MIT
  */
 import { z } from 'zod';
-import { encodeElementPath } from '../../client.js';
+import { encodeElementPath, encodeTemplateId } from '../../client.js';
 import { confirmGuard, errorResult, jsonResult, structuredResult, } from '../tool-builder.js';
 export const CLEAN_IMPLODE_OUTPUT_SCHEMA = z.object({
     template_id: z.string(),
@@ -37,7 +37,7 @@ export async function handleCleanImplodeDirectives({ client }, { template_id, el
     }
     const encoded = encodeElementPath(element_path);
     try {
-        const data = await client.post(`/pages/${encodeURIComponent(template_id)}/elements/${encoded}/multi-items/clean-implode`, { body: {}, etag });
+        const data = await client.post(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/multi-items/clean-implode`, { body: {}, etag });
         // The REST endpoint returns the canonical CLEAN_IMPLODE_OUTPUT_SCHEMA
         // shape ({template_id, element_path, cleaned_count, removed_directives,
         // new_etag}) — pass it through as structuredContent so the declared

package/dist/tools/multi-items/clean-implode-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"clean-implode-handler.js","sourceRoot":"","sources":["../../../src/tools/multi-items/clean-implode-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAmB,MAAM,iBAAiB,CAAC;AACrE,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,EACV,gBAAgB,GAEnB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,kBAAkB,EAAE,CAAC,CAAC,KAAK,CACvB,CAAC,CAAC,MAAM,CAAC;QACL,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;KAC/C,CAAC,CACL;IACD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAMH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAC9C,EAAE,MAAM,EAA2B,EACnC,EACI,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,GAMV;IAED,qEAAqE;IACrE,qEAAqE;IACrE,sEAAsE;IACtE,8EAA8E;IAC9E,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,YAAY,CAAC;YAChB,SAAS,EAAE,+CAA+C;YAC1D,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;SACzC,CAAC,CAAC;IACP,CAAC;IACD,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAChD,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAC1B,UAAU,kBAAkB,CAAC,WAAW,CAAC,aAAa,OAAO,4BAA4B,EACzF,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CACrB,CAAC;QACF,sEAAsE;QACtE,wEAAwE;QACxE,oEAAoE;QACpE,mEAAmE;QACnE,4DAA4D;QAC5D,OAAO,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,OAAO,WAAW,CAAC;YACf,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;YACtC,IAAI,EACA,4EAA4E;gBAC5E,iDAAiD;SACxD,CAAC,CAAC;IACP,CAAC;AACL,CAAC"}
+{"version":3,"file":"clean-implode-handler.js","sourceRoot":"","sources":["../../../src/tools/multi-items/clean-implode-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAmB,MAAM,iBAAiB,CAAC;AACvF,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,EACV,gBAAgB,GAEnB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,kBAAkB,EAAE,CAAC,CAAC,KAAK,CACvB,CAAC,CAAC,MAAM,CAAC;QACL,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;KAC/C,CAAC,CACL;IACD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAMH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAC9C,EAAE,MAAM,EAA2B,EACnC,EACI,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,GAMV;IAED,qEAAqE;IACrE,qEAAqE;IACrE,sEAAsE;IACtE,8EAA8E;IAC9E,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,YAAY,CAAC;YAChB,SAAS,EAAE,+CAA+C;YAC1D,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;SACzC,CAAC,CAAC;IACP,CAAC;IACD,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAChD,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAC1B,UAAU,gBAAgB,CAAC,WAAW,CAAC,aAAa,OAAO,4BAA4B,EACvF,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CACrB,CAAC;QACF,sEAAsE;QACtE,wEAAwE;QACxE,oEAAoE;QACpE,mEAAmE;QACnE,4DAA4D;QAC5D,OAAO,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,OAAO,WAAW,CAAC;YACf,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;YACtC,IAAI,EACA,4EAA4E;gBAC5E,iDAAiD;SACxD,CAAC,CAAC;IACP,CAAC;AACL,CAAC"}

package/dist/tools/multi-items/format/inspection-format.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Multi-Items inspection format-sidecar.
+ *
+ * Wave-16 #34 (6.1): the `inspect_multi_items_binding` report is passed
+ * through verbatim to `structuredContent` (which must stay schema-pure),
+ * but the human-readable text leg is serialized from the same payload.
+ * A deeply-nested report (e.g. a fully-qualified element subtree under
+ * `props` / `minimal_layout`, or a future `children` array) would balloon
+ * that text leg without bound. `capInspectionDepth` walks the value and
+ * truncates any object/array whose depth exceeds the cap, replacing it
+ * with an `…and N more` marker so the agent still sees that the subtree
+ * was elided rather than silently dropped.
+ *
+ * Pure / stateless. `structuredContent` is never passed through this —
+ * only the text-render copy — so output-schema validation is unaffected.
+ *
+ * @license MIT
+ */
+/**
+ * Default recursion cap for the inspect text render. Objects/arrays at a
+ * depth strictly greater than this are collapsed to the `…and N more`
+ * marker. The root value sits at depth 0.
+ */
+export declare const MAX_INSPECTION_DEPTH = 3;
+/**
+ * Recursively cap the depth of a JSON-serializable value.
+ *
+ * - Primitives (string / number / boolean / null / undefined) pass
+ *   through untouched at any depth.
+ * - An object or array sitting AT `maxDepth` is replaced by the
+ *   `…and N more` marker (N = its immediate child count) instead of
+ *   recursing further.
+ * - Otherwise the container is rebuilt with each child capped at
+ *   `depth + 1`.
+ *
+ * @param value    the value to cap.
+ * @param maxDepth recursion cap (defaults to {@link MAX_INSPECTION_DEPTH}).
+ * @param depth    current depth (internal; callers omit it).
+ */
+export declare function capInspectionDepth(value: unknown, maxDepth?: number, depth?: number): unknown;
+//# sourceMappingURL=inspection-format.d.ts.map

package/dist/tools/multi-items/format/inspection-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection-format.d.ts","sourceRoot":"","sources":["../../../../src/tools/multi-items/format/inspection-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAYtC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAA6B,EACvC,KAAK,SAAI,GACV,OAAO,CAeT"}

package/dist/tools/multi-items/format/inspection-format.js

@@ -0,0 +1,64 @@
+/**
+ * Multi-Items inspection format-sidecar.
+ *
+ * Wave-16 #34 (6.1): the `inspect_multi_items_binding` report is passed
+ * through verbatim to `structuredContent` (which must stay schema-pure),
+ * but the human-readable text leg is serialized from the same payload.
+ * A deeply-nested report (e.g. a fully-qualified element subtree under
+ * `props` / `minimal_layout`, or a future `children` array) would balloon
+ * that text leg without bound. `capInspectionDepth` walks the value and
+ * truncates any object/array whose depth exceeds the cap, replacing it
+ * with an `…and N more` marker so the agent still sees that the subtree
+ * was elided rather than silently dropped.
+ *
+ * Pure / stateless. `structuredContent` is never passed through this —
+ * only the text-render copy — so output-schema validation is unaffected.
+ *
+ * @license MIT
+ */
+/**
+ * Default recursion cap for the inspect text render. Objects/arrays at a
+ * depth strictly greater than this are collapsed to the `…and N more`
+ * marker. The root value sits at depth 0.
+ */
+export const MAX_INSPECTION_DEPTH = 3;
+/** Render the marker that replaces a truncated subtree. */
+function truncationMarker(childCount, maxDepth) {
+    return `…and ${String(childCount)} more (truncated at depth ${String(maxDepth)})`;
+}
+/** Number of immediate children an object/array exposes. */
+function childCountOf(value) {
+    return Array.isArray(value) ? value.length : Object.keys(value).length;
+}
+/**
+ * Recursively cap the depth of a JSON-serializable value.
+ *
+ * - Primitives (string / number / boolean / null / undefined) pass
+ *   through untouched at any depth.
+ * - An object or array sitting AT `maxDepth` is replaced by the
+ *   `…and N more` marker (N = its immediate child count) instead of
+ *   recursing further.
+ * - Otherwise the container is rebuilt with each child capped at
+ *   `depth + 1`.
+ *
+ * @param value    the value to cap.
+ * @param maxDepth recursion cap (defaults to {@link MAX_INSPECTION_DEPTH}).
+ * @param depth    current depth (internal; callers omit it).
+ */
+export function capInspectionDepth(value, maxDepth = MAX_INSPECTION_DEPTH, depth = 0) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (depth >= maxDepth) {
+        return truncationMarker(childCountOf(value), maxDepth);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => capInspectionDepth(item, maxDepth, depth + 1));
+    }
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        out[key] = capInspectionDepth(child, maxDepth, depth + 1);
+    }
+    return out;
+}
+//# sourceMappingURL=inspection-format.js.map

package/dist/tools/multi-items/format/inspection-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection-format.js","sourceRoot":"","sources":["../../../../src/tools/multi-items/format/inspection-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,2DAA2D;AAC3D,SAAS,gBAAgB,CAAC,UAAkB,EAAE,QAAgB;IAC1D,OAAO,QAAQ,MAAM,CAAC,UAAU,CAAC,6BAA6B,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;AACtF,CAAC;AAED,4DAA4D;AAC5D,SAAS,YAAY,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAC9B,KAAc,EACd,WAAmB,oBAAoB,EACvC,KAAK,GAAG,CAAC;IAET,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;QACpB,OAAO,gBAAgB,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QAC1E,GAAG,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/tools/multi-items/inspect-handler.d.ts

@@ -6,11 +6,27 @@
  * src/modules/builder-source-binding/src/MultiItemsInspector.php
  * for the report shape.
  *
+ * Wave-16 #34:
+ *   - 6.1 depth-cap: the human-readable text leg is capped at
+ *     {@link MAX_INSPECTION_DEPTH}; structuredContent stays verbatim so
+ *     it keeps validating against the output schema.
+ *   - 6.4 severity marker: the response carries a typed `hint.severity`
+ *     ("advisory" | "blocking") so the agent can tell a structural
+ *     container-level binding bug apart from informational guidance.
+ *
  * @license MIT
  */
 import { z } from 'zod';
 import { type RestClient } from '../../client.js';
 import { type ToolResult } from '../tool-builder.js';
+import { InspectionCache } from './inspection-cache.js';
+/**
+ * Severity of the advisory hint the inspector attaches to every report.
+ * `blocking` means the binding is structurally wrong (sits on the
+ * container instead of the `*_item` child) and the rendered output will
+ * be broken until fixed; `advisory` is informational guidance.
+ */
+export type HintSeverity = 'advisory' | 'blocking';
 export declare const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA: z.ZodObject<{
     template_id: z.ZodString;
     report: z.ZodObject<{
@@ -21,21 +37,53 @@ export declare const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA: z.ZodObject<{
         container_type: z.ZodNullable<z.ZodString>;
         item_type: z.ZodNullable<z.ZodString>;
         current_binding_level: z.ZodEnum<{
-            none: "none";
             container: "container";
             item: "item";
+            none: "none";
         }>;
+        item_child_binding_level: z.ZodOptional<z.ZodEnum<{
+            item: "item";
+            none: "none";
+        }>>;
+        is_bound: z.ZodOptional<z.ZodBoolean>;
         has_implode_directives: z.ZodBoolean;
+        bound_source_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        bound_source_exists: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        source_missing_warning: z.ZodOptional<z.ZodString>;
+        map_location_missing: z.ZodOptional<z.ZodBoolean>;
+        field_mapping_count: z.ZodOptional<z.ZodNumber>;
+        zero_field_mappings: z.ZodOptional<z.ZodBoolean>;
+        iterator_is_leaf_renderer: z.ZodOptional<z.ZodBoolean>;
+        map_location_warning: z.ZodOptional<z.ZodString>;
         warning: z.ZodOptional<z.ZodString>;
         recommended_fix: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     etag: z.ZodString;
+    hint: z.ZodOptional<z.ZodObject<{
+        severity: z.ZodEnum<{
+            advisory: "advisory";
+            blocking: "blocking";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
+/** The structured inspect payload the handler caches + emits. */
+type InspectStructured = Record<string, unknown>;
 export interface MultiItemsHandlerDeps {
     readonly client: RestClient;
+    /**
+     * 6.2 — optional inspection cache. When provided, the handler keys
+     * results on (template_id, element_path, global-etag) with a 60s TTL.
+     * The builder injects one shared instance so repeat inspects within
+     * the TTL skip the REST round-trip; a write bumps the global etag and
+     * naturally invalidates the entry. Omit it to disable caching (e.g.
+     * the cold-AI shape-pin tests that assert the raw round-trip).
+     */
+    readonly cache?: InspectionCache<InspectStructured>;
 }
-export declare function handleInspectMultiItemsBinding({ client }: MultiItemsHandlerDeps, { template_id, element_path }: {
+export declare function handleInspectMultiItemsBinding({ client, cache }: MultiItemsHandlerDeps, { template_id, element_path }: {
     template_id: string;
     element_path: string;
 }): Promise<ToolResult>;
+export {};
 //# sourceMappingURL=inspect-handler.d.ts.map

package/dist/tools/multi-items/inspect-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inspect-handler.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/inspect-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAA6C,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhG,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;iBAe5C,CAAC;AAEH,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC/B;AAED,wBAAsB,8BAA8B,CAChD,EAAE,MAAM,EAAE,EAAE,qBAAqB,EACjC,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,UAAU,CAAC,CAqBrB"}
+{"version":3,"file":"inspect-handler.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/inspect-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAA6C,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,UAAU,CAAC;AAEnD,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuD5C,CAAC;AAEH,iEAAiE;AACjE,KAAK,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;CACvD;AA0MD,wBAAsB,8BAA8B,CAChD,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,qBAAqB,EACxC,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,UAAU,CAAC,CAwCrB"}

package/dist/tools/multi-items/inspect-handler.js

@@ -6,11 +6,20 @@
  * src/modules/builder-source-binding/src/MultiItemsInspector.php
  * for the report shape.
  *
+ * Wave-16 #34:
+ *   - 6.1 depth-cap: the human-readable text leg is capped at
+ *     {@link MAX_INSPECTION_DEPTH}; structuredContent stays verbatim so
+ *     it keeps validating against the output schema.
+ *   - 6.4 severity marker: the response carries a typed `hint.severity`
+ *     ("advisory" | "blocking") so the agent can tell a structural
+ *     container-level binding bug apart from informational guidance.
+ *
  * @license MIT
  */
 import { z } from 'zod';
-import { encodeElementPath } from '../../client.js';
+import { encodeElementPath, encodeTemplateId } from '../../client.js';
 import { errorResult, jsonResult, structuredResult } from '../tool-builder.js';
+import { capInspectionDepth } from './format/inspection-format.js';
 export const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA = z.object({
     template_id: z.string(),
     report: z.object({
@@ -21,30 +30,248 @@ export const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA = z.object({
         container_type: z.string().nullable(),
         item_type: z.string().nullable(),
         current_binding_level: z.enum(['none', 'container', 'item']),
+        // C7 (2026-06-10) — binding level of the container's first `*_item`
+        // child. Optional so a pre-C7 backend's report still validates.
+        item_child_binding_level: z.enum(['none', 'item']).optional(),
+        // C7 — single honest "is anything bound (here or on the item child)"
+        // signal. Optional for back-compat with pre-C7 reports.
+        is_bound: z.boolean().optional(),
         has_implode_directives: z.boolean(),
+        // C7 — bound source name + live-registry existence cross-check.
+        // `bound_source_exists` is null when the registry is not wired.
+        bound_source_name: z.string().nullable().optional(),
+        bound_source_exists: z.boolean().nullable().optional(),
+        source_missing_warning: z.string().optional(),
+        // F143 — true when a bound map_item/map carries no resolved
+        // `location` leaf (the map renders 0 markers). Optional so reports
+        // for non-map elements (and pre-F143 backends) still validate.
+        map_location_missing: z.boolean().optional(),
+        // F174 — number of field mappings on the bound node (0 when unbound /
+        // mapping-less). Optional so a pre-F174 backend's report still validates.
+        field_mapping_count: z.number().int().nonnegative().optional(),
+        // F174 — true when the element IS bound but carries 0 field mappings
+        // (the N clones render only the template's static placeholder text).
+        // Optional for back-compat with pre-F174 reports.
+        zero_field_mappings: z.boolean().optional(),
+        // F189 — true when a `…List` source sits on a LEAF renderer (grid_item /
+        // any non-container) with non-empty children (the children never paint).
+        // Optional so reports for other shapes + pre-F189 backends still validate.
+        iterator_is_leaf_renderer: z.boolean().optional(),
+        // F39 (2026-06-10) — emitted when a map/map_item is bound without a
+        // `location` field mapping (renders 0 markers). Optional so non-map
+        // reports still validate. Companion human-readable signal to the
+        // structured `map_location_missing` boolean above.
+        map_location_warning: z.string().optional(),
         warning: z.string().optional(),
         recommended_fix: z.string().optional(),
     }),
     etag: z.string(),
+    // 6.4 — typed advisory/blocking marker. Optional so a verbatim REST
+    // passthrough that predates this field still validates, but the
+    // handler always populates it.
+    hint: z
+        .object({
+        severity: z.enum(['advisory', 'blocking']),
+        message: z.string(),
+    })
+        .optional(),
 });
-export async function handleInspectMultiItemsBinding({ client }, { template_id, element_path }) {
+/**
+ * Classify the report into an advisory/blocking hint.
+ *
+ * C7 (2026-06-10) — the verdict now reflects what is ACTUALLY bound, not
+ * just the container-node's own binding level. Three structural bugs the
+ * pre-C7 single-axis (`current_binding_level`) classifier produced:
+ *
+ *   1. A container bound *through* its `*_item` child reported "none" + a
+ *      reassuring "structurally correct" hint. Now `is_bound` /
+ *      `item_child_binding_level` make the child binding visible.
+ *   2. A fully-unbound element was called "structurally correct". Now a
+ *      false `is_bound` yields an honest "no source binding present" hint.
+ *   3. A binding to a since-deleted source looked fine. Now
+ *      `bound_source_exists === false` is `blocking` with the missing-
+ *      source message.
+ *
+ * Precedence: container-level binding (blocking) → deleted source
+ * (blocking) → nothing bound (advisory, honest) → bound + live (advisory,
+ * "structurally correct").
+ */
+function buildHint(report) {
+    const r = (report ?? {});
+    // F143 — a bound map with no resolved `location` leaf renders 0
+    // markers. That is a render-breaking bug, not advisory: surface it as
+    // `blocking` even though the binding level itself is "item". This is the
+    // structured-boolean entry point; the human-readable `map_location_warning`
+    // (F39, branch 1b below) is the companion signal a different backend emits.
+    if (r.map_location_missing === true) {
+        const fix = typeof r.recommended_fix === 'string' && r.recommended_fix !== ''
+            ? r.recommended_fix
+            : 'Map a single `location` field holding a combined "lat,lng" string.';
+        return {
+            severity: 'blocking',
+            message: 'Map is bound but no `location` field is mapped — no markers will ' +
+                `render. ${fix}`,
+        };
+    }
+    // F189 — a `…List` source on a LEAF renderer (grid_item / any non-container)
+    // that carries non-empty children: repeatSource clones it per row but the
+    // template renders ONLY its own slots, never its nested children → the
+    // children are render-dead and the grid shows placeholders. Render-breaking
+    // tier → blocking. The PHP inspector ships the human-readable `warning` with
+    // both recipes; surface it verbatim. Runs before the zero-mappings / generic
+    // branches so the iterator-shape bug is named first.
+    if (r.iterator_is_leaf_renderer === true) {
+        const msg = typeof r.warning === 'string' && r.warning !== ''
+            ? r.warning
+            : 'This element iterates a list source but is a LEAF renderer ' +
+                '(grid_item / *_item) — its nested children are never rendered. ' +
+                'Map fields onto the item\'s own slots (title/meta/content/image), ' +
+                'or move the List onto a container (column/fragment/row) with #parent leaves.';
+        return { severity: 'blocking', message: msg };
+    }
+    // F174 — a bound element with ZERO field mappings clones the container N
+    // times but every clone renders only the template's static placeholder
+    // text ("Title" / "Lorem ipsum"), not real data. The binding is
+    // structurally item-level so every other signal reports healthy. Same
+    // render-breaking tier as map_location_missing → blocking. The PHP
+    // inspector ships the human-readable `warning`; surface it verbatim.
+    if (r.zero_field_mappings === true) {
+        const msg = typeof r.warning === 'string' && r.warning !== ''
+            ? r.warning
+            : 'Bound to a source but with 0 field mappings — the cloned items ' +
+                'render the template\'s static placeholder text (Title / Lorem ipsum), ' +
+                'not real data. Re-bind with field_mappings AT THIS ITEM ' +
+                '(element_bind_source on this same element with non-empty ' +
+                'field_mappings). Do NOT bind the individual child leaves instead: ' +
+                'on YT5 a "#parent" leaf bind written directly under an iterating ' +
+                'item renders placeholder text.';
+        return { severity: 'blocking', message: msg };
+    }
+    // (1) Container-level binding — the original structural bug. Blocking.
+    if (r.current_binding_level === 'container') {
+        const fix = typeof r.recommended_fix === 'string' && r.recommended_fix !== ''
+            ? r.recommended_fix
+            : 'Move the binding to the first `*_item` child element.';
+        return { severity: 'blocking', message: fix };
+    }
+    // (1b) F39 — a map/map_item bound WITHOUT a `location` field mapping
+    // renders zero markers. The PHP inspector only emits map_location_warning
+    // for a genuinely-bound map pair, so its mere presence is the signal.
+    // Blocking, because the map looks healthy but shows nothing.
+    if (typeof r.map_location_warning === 'string' && r.map_location_warning !== '') {
+        return { severity: 'blocking', message: r.map_location_warning };
+    }
+    // (2) C7 bug 3 — bound source no longer exists in the live registry.
+    // `bound_source_exists` is only a hard `false` when the registry was
+    // wired AND the name was absent; `null`/`undefined` (unknown) never trips
+    // this branch.
+    if (r.bound_source_exists === false) {
+        const msg = typeof r.source_missing_warning === 'string' && r.source_missing_warning !== ''
+            ? r.source_missing_warning
+            : 'The bound source no longer exists in the live source registry — ' +
+                'the frontend will render empty. Re-bind to a current source.';
+        return { severity: 'blocking', message: msg };
+    }
+    // (3) C7 bug 2 — nothing is actually bound (neither this node nor, for a
+    // container, its item child). `is_bound` is the authoritative signal;
+    // when a pre-C7 backend omits it, fall back to current_binding_level.
+    const isBound = typeof r.is_bound === 'boolean'
+        ? r.is_bound
+        : r.current_binding_level === 'item';
+    if (!isBound) {
+        return {
+            severity: 'advisory',
+            message: 'No source binding present on this element' +
+                (r.current_binding_level !== 'item' && r.item_child_binding_level !== 'item'
+                    ? ' or its item child'
+                    : '') +
+                '. Bind a source directly: yootheme_builder_element_bind_source({ ' +
+                'template_id, element_path, source_name, field_mappings }) — for a ' +
+                'Multi-Items container, bind on the first `*_item` child.',
+        };
+    }
+    // (4) C7 bug 1 — bound through the item child. Surface that explicitly so
+    // the agent does not mistake the container's own "none" level for "unbound".
+    if (r.item_child_binding_level === 'item') {
+        return {
+            severity: 'advisory',
+            message: 'Binding looks structurally correct — the source is bound at the ' +
+                'item level (on the `*_item` child), which is the canonical ' +
+                'Multi-Items shape. Verify element_path via ' +
+                'yootheme_builder_element_list if the source still renders empty.',
+        };
+    }
+    // (5) Genuinely item-bound with a live (or unknown) source.
+    return {
+        severity: 'advisory',
+        message: 'Binding looks structurally correct. Verify element_path via ' +
+            'yootheme_builder_element_list if the source still renders empty.',
+    };
+}
+/**
+ * Render a structured inspect payload into the ToolResult envelope.
+ * Shared by the cache-hit and cache-miss paths so both legs (text +
+ * structuredContent) are built identically.
+ *
+ * 6.1 — the text leg is depth-capped so a deeply-nested report cannot
+ * balloon the LLM context. structuredContent stays verbatim so it keeps
+ * validating against INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA
+ * (additionalProperties:false).
+ */
+function renderInspectResult(structured) {
+    const text = jsonResult(capInspectionDepth(structured));
+    return structuredResult(text, structured);
+}
+export async function handleInspectMultiItemsBinding({ client, cache }, { template_id, element_path }) {
     const encoded = encodeElementPath(element_path);
     try {
-        const data = await client.get(`/pages/${encodeURIComponent(template_id)}/elements/${encoded}/multi-items/inspect`);
-        // The REST endpoint already returns the canonical
-        // {template_id, report, etag} shape — pass it through as
-        // structuredContent so the declared outputSchema is satisfied
-        // (a tool with an outputSchema MUST emit structuredContent, else
-        // the MCP SDK rejects the call with -32602).
-        return structuredResult(jsonResult(data), data);
+        // 6.2 — when a cache is wired, key on the GLOBAL state etag. Every
+        // write tool bumps it, so a mutated template surfaces a fresh etag
+        // → a new key → a guaranteed miss. Read-only repeats within the TTL
+        // skip the inspect round-trip below.
+        let cacheEtag;
+        if (cache !== undefined) {
+            cacheEtag = await fetchStateEtag(client);
+            if (cacheEtag !== undefined) {
+                const cached = cache.get(template_id, element_path, cacheEtag);
+                if (cached !== undefined) {
+                    return renderInspectResult(cached);
+                }
+            }
+        }
+        const data = await client.get(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/multi-items/inspect`);
+        // 6.4 — attach the typed severity marker to the structured payload.
+        const hint = buildHint(data.report);
+        const structured = { ...data, hint };
+        if (cache !== undefined && cacheEtag !== undefined) {
+            cache.set(template_id, element_path, cacheEtag, structured);
+        }
+        return renderInspectResult(structured);
     }
     catch (e) {
         return errorResult({
             error: e,
             context: { template_id, element_path },
             hint: 'Verify element_path via yootheme_builder_element_list. Paths are JSON-Pointer ' +
-                'style ("/templates/<id>/layout/children/0").',
+                '(RFC-6901) style: /0/children/1. Use yootheme_builder_element_list to enumerate ' +
+                'valid paths.',
         });
     }
 }
+/**
+ * Read the global state ETag used as the cache-invalidation token.
+ * Returns `undefined` (cache disabled for this call) if the etag probe
+ * fails or returns a non-string — a missing etag must never poison the
+ * cache key, and a probe failure should fall through to a live inspect
+ * rather than abort the whole call.
+ */
+async function fetchStateEtag(client) {
+    try {
+        const res = await client.get('/etag');
+        return typeof res.etag === 'string' && res.etag !== '' ? res.etag : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 //# sourceMappingURL=inspect-handler.js.map