@wootsup/yt-builder-mcp 1.2.0 → 1.3.0

package/README.md

@@ -63,22 +63,25 @@ The wizard auto-detects and configures the following clients:
 
 ## Tool surface (gateway model)
 
-The server registers **29 domain tools + 1 gateway = 30 reachable** tools,
-of which **23 are advertised in `tools/list`** (well under Cursor's ~40-tool
+The server registers **31 domain tools + 1 gateway = 32 reachable** tools,
+of which **27 are advertised in `tools/list`** (well under Cursor's ~40-tool
 cap):
 
 - **2 direct top-level tools** (always in `tools/list`):
   `yootheme_builder_health`, `yootheme_builder_diagnose`. The
   "the gateway itself might be broken" escape hatch.
-- **20 essential forwarded tools** (always in `tools/list`): the most-used
-  reads and writes (`pages_list`, `pages_create`, `pages_delete`, `get_etag`,
-  `element_list`, `element_add`, `element_update_settings`, `sources_list`,
-  `element_types_list`, `inspect_multi_items_binding`, and the multi-site
-  `sites_list` / `sites_test`, among others).
+- **24 essential forwarded tools** (always in `tools/list`): the most-used
+  reads and writes (`pages_list`, `pages_create`, `pages_delete`,
+  `page_dynamize`, `get_etag`, `element_list`, `element_add`,
+  `element_update_settings`, `sources_list`, `element_types_list`,
+  `inspect_multi_items_binding`, the multi-site `sites_list` / `sites_test` /
+  `use_site`, and the bind→save→publish chain `element_bind_source` /
+  `page_save` / `page_publish`, among others).
 - **1 gateway tool** (`yootheme_builder_advanced`): exposes the remaining
-  **7 advanced tools** behind a single entry. Call
-  `yootheme_builder_advanced({ tool: "<name>" })` for discovery (returns the
-  schema) or `({ tool, arguments })` to execute.
+  **5 advanced tools** behind a single entry (`page_get_schema`,
+  `element_get_binding`, `element_unbind_source`, `clean_implode_directives`,
+  `inspect_sublayout`). Call `yootheme_builder_advanced({ tool: "<name>" })`
+  for discovery (returns the schema) or `({ tool, arguments })` to execute.
 
 See `skills/yt-builder-mcp/SKILL.md` for the full catalog and canonical
 workflows, and `docs/TOOL-CATALOG.md` for an auto-generated reference.
@@ -93,6 +96,7 @@ workflows, and `docs/TOOL-CATALOG.md` for an auto-generated reference.
 | Elements    |     7 | `element_list`, `element_get`, `element_add`, `element_update_settings`, `element_move`, `element_clone`, `element_delete`                                          |
 | Sources     |     5 | `sources_list`, `element_get_binding`, `element_bind_source`, `element_unbind_source`, `inspect_multi_items_binding`                                                |
 | Inspection  |     3 | `element_types_list`, `element_type_get_schema`, `clean_implode_directives`                                                                                         |
+| Sublayout   |     1 | `inspect_sublayout` (F154 — fragment subtree + render-time inner-grid gate; advanced/gateway-routed)                                                                |
 | Gateway     |     1 | `advanced`                                                                                                                                                          |
 
 All tool names are prefixed with `yootheme_builder_` at the MCP server boundary.
@@ -120,7 +124,7 @@ client without per-client write logic.
 
 The skill ships with the 5 canonical workflows (build hero, bind
 source, clone section, diagnose 401, add custom element) plus a
-23-tool auto-generated catalog appendix.
+26-tool auto-generated catalog appendix.
 
 ## DXT bundle (Claude Desktop one-click install)
 

package/dist/catalog/build-catalog.d.ts

@@ -0,0 +1,63 @@
+/**
+ * packages/mcp/src/catalog/build-catalog.ts — net-new (Slice 0b Task 12).
+ *
+ * Builds the machine-readable tool catalogue (SSOT for the PHP-served MCP
+ * surface). Modelled on API Mapper's
+ * `packages/apimapper-mcp/src/catalog/build-catalog.ts`, adapted to yt-builder's
+ * `buildAllTools(pool)` entrypoint:
+ *
+ *  - yt-builder's tools carry `inputSchema` as a RAW Zod shape (ZodRawShape,
+ *    no `_zod` marker), so `toJsonSchema` always takes the raw-shape branch
+ *    (`z.object(inputSchema)`).
+ *  - `tier` is derived per-name from the gateway essentials lists
+ *    (`isEssential || isDirectTopLevel` ⇒ essential, else advanced). There is
+ *    NO separate advanced registry to query.
+ *  - The 32 catalogued tools are exactly what `buildAllTools` returns; the two
+ *    top-level gateways are registered at server level (server.ts), not here.
+ *
+ * @license MIT
+ */
+/**
+ * Convert a tool inputSchema to JSON Schema. yt-builder tools yield a RAW Zod
+ * shape (ZodRawShape) — the `_zod` guard keeps this a faithful port of the
+ * API Mapper utility, but for this server the raw-shape branch
+ * (`z.object(inputSchema)`) is the one that always fires. Native
+ * `z.toJSONSchema` (zod 4).
+ */
+export declare function toJsonSchema(inputSchema: unknown): object;
+/**
+ * Post-process a generated JSON Schema for MCP-client compatibility + semantic
+ * correctness, recursively at EVERY schema node. Two structural fixes:
+ *
+ *  A1 (#4): drop from a node's `required` array any property that carries a
+ *  `default`. Zod `.default()` lands the key in `required` (a zod4 toJSONSchema
+ *  quirk), but a field WITH a default is semantically OPTIONAL — advertising it
+ *  as required makes a strict client (and the PHP gateway validator) reject a
+ *  call that legitimately omits it.
+ *
+ *  A2 (#1): replace an EMPTY-object `additionalProperties: {}` (what
+ *  z.record(z.string(), z.unknown()) emits) with `true`. The Anthropic client
+ *  rejects an empty `{}` schema for additionalProperties; `true` is the
+ *  faithful "any value" equivalent. A boolean `false`
+ *  (z.object().strict()) is left untouched.
+ *
+ * Recurses through every schema-bearing position zod4 emits: `properties`
+ * values, `items` (object or tuple array), an object-valued
+ * `additionalProperties`, and the `oneOf`/`anyOf`/`allOf`/`prefixItems` branch
+ * arrays.
+ */
+export declare function normalizeJsonSchema(node: unknown): void;
+export interface CatalogTool {
+    name: string;
+    description: string;
+    jsonSchema: object;
+    annotations: Record<string, unknown>;
+    tier: 'essential' | 'advanced';
+}
+export interface Catalog {
+    version: string;
+    generatedFrom: 'zod';
+    tools: CatalogTool[];
+}
+export declare function buildCatalog(): Promise<Catalog>;
+//# sourceMappingURL=build-catalog.d.ts.map

package/dist/catalog/build-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-catalog.d.ts","sourceRoot":"","sources":["../../src/catalog/build-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,CAezD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CA+CvD;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC;CAClC;AACD,MAAM,WAAW,OAAO;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,KAAK,CAAC;IACrB,KAAK,EAAE,WAAW,EAAE,CAAC;CACxB;AA6BD,wBAAsB,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAiBrD"}

package/dist/catalog/build-catalog.js

@@ -0,0 +1,166 @@
+/**
+ * packages/mcp/src/catalog/build-catalog.ts — net-new (Slice 0b Task 12).
+ *
+ * Builds the machine-readable tool catalogue (SSOT for the PHP-served MCP
+ * surface). Modelled on API Mapper's
+ * `packages/apimapper-mcp/src/catalog/build-catalog.ts`, adapted to yt-builder's
+ * `buildAllTools(pool)` entrypoint:
+ *
+ *  - yt-builder's tools carry `inputSchema` as a RAW Zod shape (ZodRawShape,
+ *    no `_zod` marker), so `toJsonSchema` always takes the raw-shape branch
+ *    (`z.object(inputSchema)`).
+ *  - `tier` is derived per-name from the gateway essentials lists
+ *    (`isEssential || isDirectTopLevel` ⇒ essential, else advanced). There is
+ *    NO separate advanced registry to query.
+ *  - The 32 catalogued tools are exactly what `buildAllTools` returns; the two
+ *    top-level gateways are registered at server level (server.ts), not here.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { buildAllTools } from '../tools/index.js';
+import { isEssential, isDirectTopLevel } from '../gateway/essentials.js';
+import { SiteRegistry } from '../sites/registry.js';
+import { ClientPool } from '../sites/client-pool.js';
+import { PlainSecretResolver } from '../sites/secret-resolver.js';
+/**
+ * Convert a tool inputSchema to JSON Schema. yt-builder tools yield a RAW Zod
+ * shape (ZodRawShape) — the `_zod` guard keeps this a faithful port of the
+ * API Mapper utility, but for this server the raw-shape branch
+ * (`z.object(inputSchema)`) is the one that always fires. Native
+ * `z.toJSONSchema` (zod 4).
+ */
+export function toJsonSchema(inputSchema) {
+    try {
+        if (inputSchema && typeof inputSchema === 'object') {
+            const isZodObject = '_zod' in inputSchema;
+            const schema = isZodObject
+                ? inputSchema
+                : z.object(inputSchema);
+            const json = z.toJSONSchema(schema);
+            normalizeJsonSchema(json);
+            return json;
+        }
+    }
+    catch {
+        /* malformed/unsupported shape → safe fallback */
+    }
+    return { type: 'object' };
+}
+/**
+ * Post-process a generated JSON Schema for MCP-client compatibility + semantic
+ * correctness, recursively at EVERY schema node. Two structural fixes:
+ *
+ *  A1 (#4): drop from a node's `required` array any property that carries a
+ *  `default`. Zod `.default()` lands the key in `required` (a zod4 toJSONSchema
+ *  quirk), but a field WITH a default is semantically OPTIONAL — advertising it
+ *  as required makes a strict client (and the PHP gateway validator) reject a
+ *  call that legitimately omits it.
+ *
+ *  A2 (#1): replace an EMPTY-object `additionalProperties: {}` (what
+ *  z.record(z.string(), z.unknown()) emits) with `true`. The Anthropic client
+ *  rejects an empty `{}` schema for additionalProperties; `true` is the
+ *  faithful "any value" equivalent. A boolean `false`
+ *  (z.object().strict()) is left untouched.
+ *
+ * Recurses through every schema-bearing position zod4 emits: `properties`
+ * values, `items` (object or tuple array), an object-valued
+ * `additionalProperties`, and the `oneOf`/`anyOf`/`allOf`/`prefixItems` branch
+ * arrays.
+ */
+export function normalizeJsonSchema(node) {
+    if (Array.isArray(node)) {
+        for (const child of node)
+            normalizeJsonSchema(child);
+        return;
+    }
+    if (!node || typeof node !== 'object')
+        return;
+    const obj = node;
+    // A2: empty-object additionalProperties → true (recurse into a non-empty one).
+    if ('additionalProperties' in obj) {
+        const ap = obj.additionalProperties;
+        if (ap &&
+            typeof ap === 'object' &&
+            !Array.isArray(ap) &&
+            Object.keys(ap).length === 0) {
+            obj.additionalProperties = true;
+        }
+        else {
+            normalizeJsonSchema(ap);
+        }
+    }
+    // A1: drop default-bearing keys from THIS node's `required`.
+    const props = obj.properties;
+    if (Array.isArray(obj.required) && props && typeof props === 'object') {
+        const propMap = props;
+        const kept = obj.required.filter((key) => {
+            if (typeof key !== 'string')
+                return true;
+            const p = propMap[key];
+            return !(p && typeof p === 'object' && 'default' in p);
+        });
+        // An emptied required array is dropped (zod itself omits an empty `required`).
+        if (kept.length === 0)
+            delete obj.required;
+        else
+            obj.required = kept;
+    }
+    // Recurse into the standard schema-bearing positions.
+    if (props && typeof props === 'object') {
+        for (const v of Object.values(props)) {
+            normalizeJsonSchema(v);
+        }
+    }
+    if ('items' in obj)
+        normalizeJsonSchema(obj.items);
+    for (const kw of ['oneOf', 'anyOf', 'allOf', 'prefixItems']) {
+        if (kw in obj)
+            normalizeJsonSchema(obj[kw]);
+    }
+}
+/**
+ * One-site, in-memory, zero-IO {@link ClientPool}. Mirrors the stub
+ * `scripts/extract-tools.mjs` wires (a single `wordpress` site with an inline
+ * stub bearer), but importing the classes from `src/sites/*` rather than the
+ * compiled `dist/index.js` barrel. `buildAllTools` only reads `pool.registry`
+ * for tool registration and never resolves a bearer or hits the network at
+ * catalogue-build time.
+ */
+function stubPool() {
+    const stubFile = {
+        schema_version: 1,
+        default_site_id: 'build-catalog-stub',
+        sites: [
+            {
+                site_id: 'build-catalog-stub',
+                url: 'https://example.com',
+                platform: 'wordpress',
+                bearer: 'build-catalog-stub',
+                is_default: true,
+            },
+        ],
+    };
+    const registry = new SiteRegistry(stubFile);
+    const resolver = new PlainSecretResolver();
+    return new ClientPool(registry, resolver);
+}
+export async function buildCatalog() {
+    const tools = buildAllTools(stubPool()); // flat AnyToolDefinition[] — 32 entries
+    const catalogTools = tools.map((t) => ({
+        name: t.name,
+        description: t.description ?? '',
+        jsonSchema: toJsonSchema(t.inputSchema),
+        annotations: t.annotations ?? {},
+        tier: isEssential(t.name) || isDirectTopLevel(t.name) ? 'essential' : 'advanced',
+    }));
+    if (catalogTools.length === 0) {
+        throw new Error('buildCatalog produced 0 tools — registration likely failed');
+    }
+    return {
+        version: process.env.npm_package_version ?? '0.0.0',
+        generatedFrom: 'zod',
+        tools: catalogTools,
+    };
+}
+//# sourceMappingURL=build-catalog.js.map

package/dist/catalog/build-catalog.js.map

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

package/dist/gateway/advanced-read-tool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `yootheme_builder_advanced_read` — a READ-ONLY sibling of the
+ * `yootheme_builder_advanced` gateway (F200a, 2026-06-12).
+ *
+ * The Desktop-E2E #2 forensic showed approval-gates firing on EVERY advanced
+ * call. Root cause: the single `yootheme_builder_advanced` gateway is annotated
+ * `readOnlyHint:false` + `destructiveHint:true` (correctly — it can route into
+ * delete / unbind handlers), so spec-compliant MCP hosts gate it
+ * conservatively. The read-only L2 subtools (page_get_schema,
+ * element_get_binding, inspect_sublayout) inherited that gate even though they
+ * mutate nothing — a per-call approval tax on pure inspection.
+ *
+ * This second gateway WHITELISTS only read-only advanced entries (annotation
+ * `readOnlyHint:true`) and is itself annotated `readOnly()`, so hosts can
+ * auto-allow it. Writing subtools (unbind, clean-implode) stay reachable ONLY
+ * through the existing (gated) `yootheme_builder_advanced` — defense-in-depth:
+ * the read gateway physically cannot route to them (they are not in its
+ * registry view).
+ *
+ * Two modes mirror the write gateway:
+ *   { tool }            → discovery (target schema + annotations; no invoke).
+ *   { tool, arguments } → execution (strict-validated, then handler called).
+ *
+ * @license MIT
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AdvancedToolEntry } from './capturing-server.js';
+/** The pinned name — never rename (host configs + skill docs reference it). */
+export declare const ADVANCED_READ_TOOL_NAME = "yootheme_builder_advanced_read";
+/**
+ * Registers `yootheme_builder_advanced_read` on the real McpServer.
+ *
+ * @param realServer       the McpServer that exposes the read gateway tool
+ * @param advancedRegistry the captured non-essential tools (from CapturingServer)
+ */
+export declare function registerAdvancedReadTool(realServer: McpServer, advancedRegistry: Map<string, AdvancedToolEntry>): void;
+//# sourceMappingURL=advanced-read-tool.d.ts.map

package/dist/gateway/advanced-read-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced-read-tool.d.ts","sourceRoot":"","sources":["../../src/gateway/advanced-read-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAM/D,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAgExE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,UAAU,EAAE,SAAS,EACrB,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACjD,IAAI,CAwEN"}

package/dist/gateway/advanced-read-tool.js

@@ -0,0 +1,156 @@
+/**
+ * `yootheme_builder_advanced_read` — a READ-ONLY sibling of the
+ * `yootheme_builder_advanced` gateway (F200a, 2026-06-12).
+ *
+ * The Desktop-E2E #2 forensic showed approval-gates firing on EVERY advanced
+ * call. Root cause: the single `yootheme_builder_advanced` gateway is annotated
+ * `readOnlyHint:false` + `destructiveHint:true` (correctly — it can route into
+ * delete / unbind handlers), so spec-compliant MCP hosts gate it
+ * conservatively. The read-only L2 subtools (page_get_schema,
+ * element_get_binding, inspect_sublayout) inherited that gate even though they
+ * mutate nothing — a per-call approval tax on pure inspection.
+ *
+ * This second gateway WHITELISTS only read-only advanced entries (annotation
+ * `readOnlyHint:true`) and is itself annotated `readOnly()`, so hosts can
+ * auto-allow it. Writing subtools (unbind, clean-implode) stay reachable ONLY
+ * through the existing (gated) `yootheme_builder_advanced` — defense-in-depth:
+ * the read gateway physically cannot route to them (they are not in its
+ * registry view).
+ *
+ * Two modes mirror the write gateway:
+ *   { tool }            → discovery (target schema + annotations; no invoke).
+ *   { tool, arguments } → execution (strict-validated, then handler called).
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { readOnly } from '../tools/tool-builder.js';
+import { isEssential, isDirectTopLevel } from './essentials.js';
+import { discoveryResult } from './advanced-tool/discovery.js';
+import { renderGroupedList } from './advanced-tool/domains.js';
+import { errorResult, executeAdvancedTool } from './advanced-tool/execute.js';
+/** The pinned name — never rename (host configs + skill docs reference it). */
+export const ADVANCED_READ_TOOL_NAME = 'yootheme_builder_advanced_read';
+/**
+ * True iff a captured advanced entry advertises `readOnlyHint:true`. The
+ * single source of truth for "is this subtool safe to auto-allow" — the same
+ * annotation the host reads. No name allowlist to drift: adding a new
+ * read-only advanced tool surfaces here automatically.
+ */
+function isReadOnlyEntry(entry) {
+    const annotations = entry.config.annotations;
+    return annotations?.readOnlyHint === true;
+}
+/**
+ * Builds the read-gateway's input schema.
+ *
+ * F205 (P2): `tool` is a free z.string(), NOT a z.enum — same trap as the write
+ * gateway. The MCP SDK validates the inputSchema before the handler runs; an
+ * enum rejected first-class names with a raw McpError -32602 so the handler's
+ * not_read_only / first_class_tool / unknown steering never ran. A plain string
+ * lets every name reach the handler.
+ */
+function readGatewayInputSchema() {
+    return {
+        tool: z.string().describe('Read-only advanced tool to route to (e.g. "yootheme_builder_page_get_schema"). ' +
+            'Must be one of the read-only advanced tools listed in this description. ' +
+            'First-class tools (yootheme_builder_health, ...) are called DIRECTLY; ' +
+            'writing tools use yootheme_builder_advanced. ' +
+            'Omit `arguments` to discover its schema first.'),
+        arguments: z.record(z.string(), z.unknown()).optional().describe('Arguments for the target tool. Omit for discovery mode ' +
+            "(returns the tool's schema + annotations)."),
+        // `input` is a tolerated alias for `arguments` (same back-compat carve
+        // the write gateway makes — see register.ts F107).
+        input: z.record(z.string(), z.unknown()).optional().describe('Alias for `arguments` (tolerated for back-compat). Prefer `arguments`.'),
+    };
+}
+/** Builds the read-gateway's description, listing only the whitelisted read-only tools. */
+function buildReadDescription(readOnlyNames) {
+    const count = readOnlyNames.length;
+    return (`Routes to ${String(count)} READ-ONLY advanced YOOtheme Builder tool` +
+        `${count === 1 ? '' : 's'}. ` +
+        // F214: stop the model habitually routing first-class tools through the
+        // gateway (a wasted invalid_arguments cycle each time). State the scope
+        // boundary up front, before the grouped-tool list.
+        'ONLY for the read-only advanced tools listed below — every tool that ' +
+        'appears directly in tools/list is FIRST-CLASS: call it directly, never via this gateway. ' +
+        'Itself read-only (no write-approval gate) — prefer it over ' +
+        'yootheme_builder_advanced for inspection. Call { tool } for its ' +
+        'schema, or { tool, arguments } to run it.' +
+        '\n\nAvailable read-only advanced tools by domain:\n' +
+        `${renderGroupedList(readOnlyNames)}\n\n` +
+        'Writing tools (unbind, clean-implode): use yootheme_builder_advanced. ' +
+        'Connectivity: yootheme_builder_health / yootheme_builder_diagnose.');
+}
+/**
+ * Registers `yootheme_builder_advanced_read` on the real McpServer.
+ *
+ * @param realServer       the McpServer that exposes the read gateway tool
+ * @param advancedRegistry the captured non-essential tools (from CapturingServer)
+ */
+export function registerAdvancedReadTool(realServer, advancedRegistry) {
+    // Build the read-only view of the registry — the gateway literally cannot
+    // see (let alone route to) writing tools.
+    const readOnlyRegistry = new Map();
+    for (const [name, entry] of advancedRegistry) {
+        if (isReadOnlyEntry(entry)) {
+            readOnlyRegistry.set(name, entry);
+        }
+    }
+    const readOnlyNames = [...readOnlyRegistry.keys()].sort();
+    realServer.registerTool(ADVANCED_READ_TOOL_NAME, {
+        title: 'Advanced Read-Only Gateway',
+        description: buildReadDescription(readOnlyNames),
+        inputSchema: readGatewayInputSchema(),
+        // F200a: read-only annotation so hosts auto-allow. Unlike the write
+        // gateway, this one can never reach a mutating handler.
+        annotations: readOnly('Advanced Read-Only Gateway'),
+    }, async (args, extra) => {
+        const entry = readOnlyRegistry.get(args.tool);
+        if (!entry) {
+            // F205: a WRITE subtool name that exists in the FULL advanced
+            // registry but not the read whitelist gets a targeted steer to
+            // the write gateway. This branch MUST stay ahead of the
+            // first_class_tool check (an advanced write subtool is not a
+            // first-class tool).
+            if (advancedRegistry.has(args.tool)) {
+                return errorResult({
+                    message: `"${args.tool}" is not a read-only tool — it mutates state and is not ` +
+                        'reachable through yootheme_builder_advanced_read.',
+                    code: 'not_read_only',
+                    suggestion: `Call it through the full gateway instead: ` +
+                        `yootheme_builder_advanced({ tool: "${args.tool}", arguments: {...} }).`,
+                    details: { tool: args.tool },
+                });
+            }
+            // F205: a first-class tool (L1 essential or L3 direct
+            // top-level) is steered to a direct call rather than treated
+            // as a typo.
+            if (isEssential(args.tool) || isDirectTopLevel(args.tool)) {
+                return errorResult({
+                    message: `"${args.tool}" is a FIRST-CLASS tool — it appears directly in tools/list.`,
+                    code: 'first_class_tool',
+                    suggestion: `Call "${args.tool}" directly instead of routing it through ` +
+                        'yootheme_builder_advanced_read. This gateway only routes the read-only ' +
+                        'advanced tools listed in its description.',
+                    details: { tool: args.tool },
+                });
+            }
+            return errorResult({
+                message: `Unknown read-only advanced tool: "${args.tool}".`,
+                code: 'unknown_read_tool',
+                suggestion: 'This gateway routes ONLY read-only advanced tools. If you meant a ' +
+                    'WRITING tool (unbind, clean-implode), use yootheme_builder_advanced ' +
+                    'instead. Otherwise pick one of the valid read-only tools below.\n\n' +
+                    `Valid read-only advanced tools by domain:\n${renderGroupedList(readOnlyNames)}`,
+                details: { valid_read_tools_by_domain: renderGroupedList(readOnlyNames) },
+            });
+        }
+        // `arguments` is canonical; `input` is a tolerated alias (F107).
+        const callArgs = args.arguments ?? args.input;
+        if (callArgs === undefined)
+            return discoveryResult(args.tool, entry);
+        return executeAdvancedTool(args.tool, entry, callArgs, extra);
+    });
+}
+//# sourceMappingURL=advanced-read-tool.js.map

package/dist/gateway/advanced-read-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced-read-tool.js","sourceRoot":"","sources":["../../src/gateway/advanced-read-tool.ts"],"names":[],"mappings":"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"}

package/dist/gateway/advanced-tool/domains.d.ts

@@ -23,14 +23,19 @@ import type { AdvancedToolEntry } from '../capturing-server.js';
 export declare const DOMAIN_ORDER: readonly ["pages", "elements", "sources", "multi-items", "inspection"];
 /**
  * Prefix→domain routing table. Each domain accepts plural
- * (`pages_list`) + singular (`page_save`, `element_add`, `source_…`)
- * stems via `stem.startsWith(prefix + '_')` or full-equality. Anything
- * outside the taxonomy falls through to 'misc'.
+ * (`pages_list`) + singular (`page_get_schema`, `element_unbind_source`,
+ * `source_…`) stems via `stem.startsWith(prefix + '_')` or full-equality.
+ * Anything outside the taxonomy falls through to 'misc'.
  *
  * The `multi-items` domain captures the YT-Pro Multi-Items binding
  * pattern tools (inspect / clean-implode). Stems used:
  *  - `inspect_multi_items_binding` → starts with `inspect_multi_items`
  *  - `clean_implode_directives`    → starts with `clean_implode`
+ *
+ * The `inspection` domain captures layout inspectors that surface a
+ * YT-Pro footgun the raw layout tree hides. Stems used:
+ *  - `inspect_sublayout` (F154) → full-equality `inspect_sublayout`
+ *    (the YT5 `< SUBLAYOUT` fragment-subtree + inner-grid-gate inspector).
  */
 export declare const DOMAIN_PREFIX_MAP: Record<(typeof DOMAIN_ORDER)[number], readonly string[]>;
 export declare const TOOL_PREFIX = "yootheme_builder_";
@@ -40,6 +45,16 @@ export declare function domainOf(toolName: string): string;
 export declare function groupByDomain(toolNames: string[]): Map<string, string[]>;
 /** Renders the grouped tool list as readable text (used in description + errors). */
 export declare function renderGroupedList(toolNames: string[]): string;
+/**
+ * F176 (2026-06-12): the former "★ Bind a source" callout was removed. The
+ * bind tool (`yootheme_builder_element_bind_source`) plus `page_save` /
+ * `page_publish` were promoted to L1 by F116 and live in `tools/list` as
+ * first-class entries; the DISJOINT-LANE invariant guarantees they are NEVER
+ * in the advanced registry, so the gateway description must not advertise a
+ * gateway wrap for them (it would steer agents into an `unknown_tool` dead
+ * end on a current build). The binding workflow is now discoverable directly
+ * in `tools/list`.
+ */
 /** Builds the gateway tool's description, grouping every advanced tool by domain. */
 export declare function buildDescription(toolNames: string[]): string;
 /** Re-export the AdvancedToolEntry type so consumers don't need a second import path. */

package/dist/gateway/advanced-tool/domains.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../../../src/gateway/advanced-tool/domains.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,wEAAyE,CAAC;AAEnG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAMtF,CAAC;AAEF,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAE/C,8FAA8F;AAC9F,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAYxE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAO7D;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAe5D;AAED,yFAAyF;AACzF,YAAY,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../../../src/gateway/advanced-tool/domains.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,wEAAyE,CAAC;AAEnG;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAMtF,CAAC;AAEF,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAE/C,8FAA8F;AAC9F,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAYxE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAO7D;AAED;;;;;;;;;GASG;AAEH,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAmB5D;AAED,yFAAyF;AACzF,YAAY,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/gateway/advanced-tool/domains.js

@@ -22,21 +22,26 @@
 export const DOMAIN_ORDER = ['pages', 'elements', 'sources', 'multi-items', 'inspection'];
 /**
  * Prefix→domain routing table. Each domain accepts plural
- * (`pages_list`) + singular (`page_save`, `element_add`, `source_…`)
- * stems via `stem.startsWith(prefix + '_')` or full-equality. Anything
- * outside the taxonomy falls through to 'misc'.
+ * (`pages_list`) + singular (`page_get_schema`, `element_unbind_source`,
+ * `source_…`) stems via `stem.startsWith(prefix + '_')` or full-equality.
+ * Anything outside the taxonomy falls through to 'misc'.
  *
  * The `multi-items` domain captures the YT-Pro Multi-Items binding
  * pattern tools (inspect / clean-implode). Stems used:
  *  - `inspect_multi_items_binding` → starts with `inspect_multi_items`
  *  - `clean_implode_directives`    → starts with `clean_implode`
+ *
+ * The `inspection` domain captures layout inspectors that surface a
+ * YT-Pro footgun the raw layout tree hides. Stems used:
+ *  - `inspect_sublayout` (F154) → full-equality `inspect_sublayout`
+ *    (the YT5 `< SUBLAYOUT` fragment-subtree + inner-grid-gate inspector).
  */
 export const DOMAIN_PREFIX_MAP = {
     pages: ['pages', 'page'],
     elements: ['elements', 'element'],
     sources: ['sources', 'source'],
     'multi-items': ['inspect_multi_items', 'clean_implode'],
-    inspection: ['inspection'],
+    inspection: ['inspection', 'inspect_sublayout'],
 };
 export const TOOL_PREFIX = 'yootheme_builder_';
 /** Maps a tool name to its display domain (the first underscore-segment after the prefix). */
@@ -76,6 +81,16 @@ export function renderGroupedList(toolNames) {
     }
     return lines.join('\n');
 }
+/**
+ * F176 (2026-06-12): the former "★ Bind a source" callout was removed. The
+ * bind tool (`yootheme_builder_element_bind_source`) plus `page_save` /
+ * `page_publish` were promoted to L1 by F116 and live in `tools/list` as
+ * first-class entries; the DISJOINT-LANE invariant guarantees they are NEVER
+ * in the advanced registry, so the gateway description must not advertise a
+ * gateway wrap for them (it would steer agents into an `unknown_tool` dead
+ * end on a current build). The binding workflow is now discoverable directly
+ * in `tools/list`.
+ */
 /** Builds the gateway tool's description, grouping every advanced tool by domain. */
 export function buildDescription(toolNames) {
     const toolCount = toolNames.length;
@@ -84,11 +99,15 @@ export function buildDescription(toolNames) {
     const domainList = domains.join(', ');
     return (`Routes to ${String(toolCount)} advanced YOOtheme Builder tools across ${String(domainCount)} ` +
         `domain${domainCount === 1 ? '' : 's'}${domainCount > 0 ? ` (${domainList})` : ''}. ` +
-        'Call with { tool } for a target\'s schema + annotations, or ' +
-        '{ tool, arguments } to run it. The target tool\'s own confirmation ' +
-        'guards and behavior stay in effect.\n\n' +
-        'Available advanced tools by domain:\n' +
+        // F214: stop the model habitually routing first-class tools through the
+        // gateway (a wasted invalid_arguments cycle each time). State the scope
+        // boundary up front, before the grouped-tool list.
+        'ONLY for the advanced tools listed below — every tool that appears ' +
+        'directly in tools/list is FIRST-CLASS: call it directly, never via this gateway. ' +
+        'Call { tool } for its schema, or { tool, arguments } to run it ' +
+        '(the target\'s own confirm guards stay in effect).' +
+        '\n\nAvailable advanced tools by domain:\n' +
         `${renderGroupedList(toolNames)}\n\n` +
-        'For connectivity diagnostics use yootheme_builder_health or yootheme_builder_diagnose (top-level).');
+        'Connectivity: yootheme_builder_health / yootheme_builder_diagnose.');
 }
 //# sourceMappingURL=domains.js.map

package/dist/gateway/advanced-tool/domains.js.map

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

package/dist/gateway/advanced-tool/register.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/gateway/advanced-tool/register.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAmBhE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAChC,UAAU,EAAE,SAAS,EACrB,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACjD,IAAI,CA+CN"}
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/gateway/advanced-tool/register.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA0ChE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAChC,UAAU,EAAE,SAAS,EACrB,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACjD,IAAI,CAyDN"}