@wootsup/yt-builder-mcp 1.1.7 → 1.3.0

package/skills/yt-builder-mcp/SKILL.md

@@ -12,12 +12,17 @@ description: Drive the YOOtheme Pro Page Builder on WordPress or Joomla 5/6. Dis
 > WordPress and Joomla 5/6.
 
 This skill helps AI assistants drive the YOOtheme Pro Page Builder through the
-`@wootsup/yt-builder-mcp` server. The server exposes 27 typed, scoped, idempotent
-callable tools. 20 of them advertised as first-class entries in `tools/list`
-(17 essential L1 forwards + 2 direct L3 entries + 1 gateway), and 7 advanced
-tools reachable through the single `yootheme_builder_advanced` gateway. This
-3-lane split keeps `tools/list` well below the ~40-tool Cursor cap while every
-catalogued tool stays fully reachable.
+`@wootsup/yt-builder-mcp` server. The server catalogues 32 typed, scoped,
+idempotent tools (34 callable end-to-end with the two gateways). 29 of them
+advertised as first-class entries in `tools/list`
+(25 essential L1 forwards + 2 direct L3 entries + 2 gateways), and 5 advanced
+tools reachable through the gateways. The write-capable
+`yootheme_builder_advanced` gateway routes all 5; the read-only
+`yootheme_builder_advanced_read` gateway routes only the read-only subset
+(page_get_schema, element_get_binding, inspect_sublayout) and is itself
+read-only-annotated, so MCP hosts can auto-allow pure inspection without a
+per-call write-approval prompt. This 3-lane split keeps `tools/list` well below
+the ~40-tool Cursor cap while every catalogued tool stays fully reachable.
 
 ## How to use this MCP server
 
@@ -48,8 +53,10 @@ Some clients (notably Claude Desktop with the `.dxt` bundle) expose **two**
 entries when the user types "YT Builder MCP" into the picker:
 
 - **`YT Builder MCP for YOOtheme Pro (unofficial)`**: the MCP **server**.
-  Provides the 20 first-class tools (17 essential, 2 direct, 1 gateway).
-  The `yootheme_builder_advanced` gateway routes 7 additional tools.
+  Provides the 28 first-class tools (24 essential, 2 direct, 2 gateways).
+  The `yootheme_builder_advanced` gateway routes all 5 advanced tools; the
+  read-only `yootheme_builder_advanced_read` gateway routes the read-only
+  subset without a write-approval prompt.
 - **`Von YT Builder MCP for YOOtheme Pro`**: the bundled **skill** (this
   document). Gives the agent the workflow knowledge needed to drive those
   tools correctly on first try.
@@ -74,24 +81,37 @@ The server exposes:
 - **2 direct top-level tools**, always callable, always in `tools/list`:
   `yootheme_builder_health` and `yootheme_builder_diagnose`. These are
   the "the gateway itself might be broken" escape hatch.
-- **17 essential forwarded tools**: common reads + the most-used writes
-  (pages_list, get_etag, element_list / add / update_settings / get / move /
-  clone / delete, page_get_layout, sources_list, element_types_list,
-  element_type_get_schema, template_summary, inspect_multi_items_binding,
-  sites_list, sites_test). Always advertised in `tools/list` so AI clients
-  see them first-class.
-- **7 advanced captured tools**: everything else (page_save, page_publish,
-  page_get_schema, element_get_binding, element_bind_source,
-  element_unbind_source, clean_implode_directives). Reachable through one
-  gateway tool: `yootheme_builder_advanced({ tool: "<name>", input: { ... } })`.
-- **1 gateway tool**: `yootheme_builder_advanced`.
-
-`tools/list` therefore advertises 20 names (17 + 2 + 1). That's 17 L1
-essentials + 2 L3 direct + 1 gateway. The total callable surface is 27
-(20 advertised + 7 advanced reachable through the gateway). If the AI
+- **25 essential forwarded tools**: common reads + the most-used writes
+  (pages_list, pages_create, pages_delete, page_dynamize, scaffold_section,
+  get_etag, element_list / add / update_settings / get / move / clone / delete,
+  page_get_layout, sources_list, element_types_list, element_type_get_schema,
+  template_summary, inspect_multi_items_binding, sites_list, sites_test,
+  use_site, and the bind→save→publish chain element_bind_source /
+  page_save / page_publish). Always advertised in `tools/list` so AI
+  clients see them first-class. `scaffold_section` creates a valid
+  section → row → column hull in one call — the easiest correct way to
+  start a layout block (content placed anywhere else is rejected by the
+  structural-hierarchy guard).
+- **5 advanced captured tools**: everything else (page_get_schema,
+  element_get_binding, element_unbind_source, clean_implode_directives,
+  and `inspect_sublayout`). Reachable through one gateway tool:
+  `yootheme_builder_advanced({ tool: "<name>", arguments: { ... } })`. For
+  example, to inspect a panel/grid_item `< SUBLAYOUT`:
+  `yootheme_builder_advanced({ tool: "yootheme_builder_inspect_sublayout", arguments: { template_id, element_path } })`.
+- **2 gateway tools**: `yootheme_builder_advanced` (write-capable; can route
+  into delete/unbind, so hosts gate it) and `yootheme_builder_advanced_read`
+  (read-only; routes ONLY the read-only advanced subset — page_get_schema,
+  element_get_binding, inspect_sublayout — and is read-only-annotated so hosts
+  auto-allow it). Prefer the read gateway for pure inspection:
+  `yootheme_builder_advanced_read({ tool: "yootheme_builder_page_get_schema", arguments: { template_id } })`.
+
+`tools/list` therefore advertises 29 names (25 + 2 + 2). That's 25 L1
+essentials + 2 L3 direct + 2 gateways. The total callable surface is 34
+(29 advertised + 5 advanced reachable through the gateways). If the AI
 client reports "tool not found", you are almost certainly calling an
 advanced tool by its raw name. Wrap it in
-`yootheme_builder_advanced({ tool, input })` instead.
+`yootheme_builder_advanced({ tool, arguments })` (or the read gateway for
+read-only tools) instead.
 
 ## Site and frontend URLs (for deep-linking and verification)
 
@@ -137,7 +157,7 @@ Do not loop on auth errors.
 > REST endpoints for per-article custom layouts, but they are NOT exposed
 > via MCP tools in v1.x. To use that surface, call the REST endpoints
 > directly with the Bearer key. MCP tool coverage for L2 articles is
-> planned for v1.2.0.
+> planned for a future release.
 
 ---
 
@@ -281,8 +301,8 @@ one conversation.
    - `yootheme_builder_pages_list({ site_id: "wp-acme", fields: ["id", "label"] })`
    - `yootheme_builder_get_etag({ site_id: "wp-acme" })`
    - `yootheme_builder_element_update_settings({ site_id: "wp-acme", template_id: "home", element_path: "/0/children/0/children/0/children/0", props: { content: "New headline" }, merge: true, etag: "<etag>" })`
-   - `yootheme_builder_advanced({ tool: "yootheme_builder_page_save", input: { site_id: "wp-acme", template_id: "home", etag: "<fresh>" } })`
-   - `yootheme_builder_advanced({ tool: "yootheme_builder_page_publish", input: { site_id: "wp-acme", template_id: "home", etag: "<fresh>" } })`
+   - `yootheme_builder_page_save({ site_id: "wp-acme", template_id: "home", etag: "<fresh>" })`
+   - `yootheme_builder_page_publish({ site_id: "wp-acme", template_id: "home", etag: "<fresh>" })`
 3. The customer sees a stream of replies, each prefixed with the matching
    `[label @ host]`, so it is obvious which site is at which step.
 
@@ -320,11 +340,11 @@ to an existing page.
    add a text element.
 8. `yootheme_builder_element_add({ template_id, parent_path: "<row-path>", element_type: "button", props: { content: "<cta>", link: "<url>" }, etag })`:
    add the CTA button.
-9. `yootheme_builder_advanced({ tool: "yootheme_builder_page_save", input: { template_id, etag } })`:
+9. `yootheme_builder_page_save({ template_id, etag })`:
    persist the working copy (visible in YOOtheme Customizer preview).
-   `page_save` is an advanced tool; call it through the gateway.
-10. `yootheme_builder_advanced({ tool: "yootheme_builder_page_publish", input: { template_id, etag } })`:
-    make the changes live on the front-end. Also an advanced tool.
+   `page_save` is a first-class L1 tool; call it directly.
+10. `yootheme_builder_page_publish({ template_id, etag })`:
+    make the changes live on the front-end. Also a first-class L1 tool.
 
 **Common pitfalls:**
 
@@ -345,9 +365,11 @@ to an existing page.
 - **Reusing a stale etag across many writes.** Every write returns a
   fresh etag in the response. Pass THAT etag into the next write.
   Don't hold the one from the original `get_etag` call.
-- **Calling page_save / page_publish by name.** Both are advanced
-  (L2) tools. Call them through `yootheme_builder_advanced({ tool, input })`,
-  not directly. The first sign you forgot is "tool not found".
+- **Forgetting to publish.** `page_save` and `page_publish` are both
+  first-class L1 tools (call them directly by name — they are advertised
+  in `tools/list`). Saving stages the change; only `page_publish` makes
+  it live. A saved-but-unpublished edit looks "done" in the Customizer
+  but visitors still see the old page.
 
 **Worked example (tool-call snippet):**
 
@@ -363,11 +385,8 @@ yootheme_builder_element_add({
 // Response: { path: "/0/children/3", etag: "def456" }
 // → next call uses etag "def456"
 
-// Step 9. page_save is L2; call via the gateway.
-yootheme_builder_advanced({
-  tool: "yootheme_builder_page_save",
-  input: { template_id: "home", etag: "<latest>" }
-})
+// Step 9. page_save is a first-class L1 tool; call it directly.
+yootheme_builder_page_save({ template_id: "home", etag: "<latest>" })
 ```
 
 **Edge case:** YOOtheme allows nested sections (rare). If the user
@@ -402,21 +421,21 @@ renders dynamic items.
 4. `yootheme_builder_sources_list()`: enumerate available Sources.
    Each returns `{ name, label, origin, kind }`. Pick the one the
    user asked for.
-5. `yootheme_builder_advanced({ tool: "yootheme_builder_element_get_binding", input: { template_id, element_path } })`
+5. `yootheme_builder_advanced({ tool: "yootheme_builder_element_get_binding", arguments: { template_id, element_path } })`
    check whether the Grid is already bound (idempotency: skip step
    7 if `source_name` already matches the user's intent).
    `element_get_binding` is an advanced (L2) tool. Call via the gateway.
 6. `yootheme_builder_get_etag()`: fetch the optimistic-lock etag for
    the upcoming mutation.
-7. `yootheme_builder_advanced({ tool: "yootheme_builder_element_bind_source", input: { template_id, element_path, source_name: "<name>", etag: "<etag>" } })`
+7. `yootheme_builder_element_bind_source({ template_id, element_path, source_name: "<name>", etag: "<etag>" })`
    applies the binding. Returns `{ path, etag, has_binding: true }`.
    Pass `source_id: "<origin>:<name>"` as well **only** when two
    plugins register a source with the same `source_name` (the server
    surfaces the ambiguity as an elicitation prompt; if the host
    doesn't support elicitation you'll see a structured error listing
-   the candidates). Also an advanced tool.
-8. `yootheme_builder_advanced({ tool: "yootheme_builder_page_save", input: { template_id, etag: "<fresh>" } })`
-   then `yootheme_builder_advanced({ tool: "yootheme_builder_page_publish", input: { template_id, etag: "<fresh>" } })`.
+   the candidates). This is a first-class L1 tool — call it directly.
+8. `yootheme_builder_page_save({ template_id, etag: "<fresh>" })`
+   then `yootheme_builder_page_publish({ template_id, etag: "<fresh>" })`.
 
 **Common pitfalls:**
 
@@ -439,29 +458,29 @@ renders dynamic items.
 - **Forgetting `etag`.** Every write requires the optimistic-lock
   etag. On `412 Precondition Failed` re-fetch via
   `yootheme_builder_get_etag` and retry.
-- **Calling bind/unbind directly.** Both `element_bind_source` and
-  `element_get_binding` are L2 advanced. Wrap in
-  `yootheme_builder_advanced({ tool, input })`.
+- **Mis-routing bind vs the read helpers.** `element_bind_source` is
+  now a first-class L1 tool — call it directly by name. The binding
+  *read* helpers `element_get_binding` and `element_unbind_source` stay
+  L2 advanced; reach those through
+  `yootheme_builder_advanced({ tool, arguments })`.
 
 **Worked example (tool-call snippet):**
 
 ```jsonc
-// Step 7. Bind a Posts source onto a Grid element via the gateway.
-yootheme_builder_advanced({
-  tool: "yootheme_builder_element_bind_source",
-  input: {
-    template_id: "home",
-    element_path: "/0/children/2/children/0",
-    source_name: "wp_posts",
-    etag: "abc123"
-    // source_id: "wordpress:wp_posts"   // pass ONLY when name collides
-  }
+// Step 7. Bind a Posts source onto a Grid element. element_bind_source
+// is a first-class L1 tool — call it directly.
+yootheme_builder_element_bind_source({
+  template_id: "home",
+  element_path: "/0/children/2/children/0",
+  source_name: "wp_posts",
+  etag: "abc123"
+  // source_id: "wordpress:wp_posts"   // pass ONLY when name collides
 })
 // Response: { path: "/0/children/2/children/0", etag: "def456", has_binding: true }
 // Verify (via gateway):
 yootheme_builder_advanced({
   tool: "yootheme_builder_element_get_binding",
-  input: { template_id: "home", element_path: "/0/children/2/children/0" }
+  arguments: { template_id: "home", element_path: "/0/children/2/children/0" }
 })
 // → { source_name: "wp_posts", source_config: { ... }, ... }
 ```
@@ -477,6 +496,50 @@ items from the Source (verify by item count and at least one
 field-value spot-check). `yootheme_builder_element_get_binding`
 (via gateway) returns the new `source_name`.
 
+### Multi-Items renderer truth table (read before binding rich cards)
+
+The YT5 renderer (`SourceTransform`) follows ONE rule:
+
+> A `…List` source renders nested children **only** when the element
+> carrying it is a **CONTAINER** whose template renders its children
+> (`column`, `fragment`, `row`, `section`, `grid`). `grid_item` and every
+> `*_item` atom are **LEAF renderers**: the list iterates them per row, but
+> their template paints **only their own slots** and **never** renders nested
+> children — so any elements nested inside an iterating `grid_item` are
+> dropped and you see placeholders.
+
+What the renderer consumes from `item.source.props`: it maps each row field
+onto the element's **own** display slots (`grid_item`:
+title/meta/content/image/video/hover_image/hover_video/link/icon; `panel`:
+title/meta/content/image). It is **last-write-wins** — two fields mapped to
+the same slot silently lose one.
+
+Two canonical forms (both live-verified):
+
+- **(a) Simple card, N ≤ slots — iterate ON the `grid_item`:**
+  `grid_item{ source:{ query:{name:"…List"}, props:{ title:{name:F1}, meta:{name:F2}, image:{name:F3} } } }`.
+  No nested children. Renders because the data lands on the item's own slots.
+
+- **(b) Rich / arbitrary card, any N — iterate ON a CONTAINER:**
+  `column{ source:{query:{name:"…List"}} > fragment{#parent} > leaves{ source:{query:{name:"#parent"}, props:{<slot>:{name:Fk}}} }`.
+  One leaf per field, **no leaf limit**. `<slot>` is `content` for
+  headline/text, or title/meta/image for panel. The `fragment` wrapper is
+  **optional** (it may carry `source.query.name="#parent"` or no source —
+  both work because a fragment renders its children either way).
+
+**Guards (the tool enforces these):**
+
+- Binding a leaf that is a **DIRECT child of an iterating `grid_item`** (no
+  `fragment` between) auto-**consolidates** the field onto the item's own
+  slots (form (a)) and leaves the leaf source-free (`consolidated_to_parent`).
+- A consolidation that targets an **occupied slot** OR a key that is **not a
+  slot** of the item type is **rejected** with `slot_collision` (HTTP 409) —
+  give each field its own leaf / a distinct slot.
+- Binding a `…List` source ONTO a `grid_item` that already has nested
+  children surfaces a blocking `iterator_is_leaf_renderer` warning (the
+  children are render-dead): map the fields onto the item's slots, or move
+  the List onto a container.
+
 ---
 
 ## Workflow 3: Clone & modify a section within a template
@@ -501,7 +564,7 @@ CMS-level template duplication (in wp-admin or Joomla administrator).
 1. `yootheme_builder_health`: confirm host plugin reachable.
 2. `yootheme_builder_pages_list({ fields: ["id", "label"] })`:
    locate the template by `label`. Note its `id`.
-3. `yootheme_builder_advanced({ tool: "yootheme_builder_page_get_schema", input: { template_id } })`
+3. `yootheme_builder_advanced({ tool: "yootheme_builder_page_get_schema", arguments: { template_id } })`
    returns a flat schema view (lighter than `page_get_layout`) showing every
    element path + type. Pick the JSON-Pointer path of the section
    to clone. `page_get_schema` is L2; call via the gateway.
@@ -517,8 +580,8 @@ CMS-level template duplication (in wp-admin or Joomla administrator).
    pass `merge: true` to apply a server-side deep-merge instead).
    Read the current props first via `yootheme_builder_element_get`
    if you only want to tweak a subset.
-8. `yootheme_builder_advanced({ tool: "yootheme_builder_page_save", input: { template_id, etag } })`
-   then `yootheme_builder_advanced({ tool: "yootheme_builder_page_publish", input: { template_id, etag } })`.
+8. `yootheme_builder_page_save({ template_id, etag })`
+   then `yootheme_builder_page_publish({ template_id, etag })`.
 
 **Common pitfalls:**
 
@@ -536,7 +599,7 @@ CMS-level template duplication (in wp-admin or Joomla administrator).
 - **Cloning a bound element keeps the binding.** `element_clone`
   copies the entire element including `props.source`. If the user
   wanted a "data-free" copy, call
-  `yootheme_builder_advanced({ tool: "yootheme_builder_element_unbind_source", input: { ... } })`
+  `yootheme_builder_advanced({ tool: "yootheme_builder_element_unbind_source", arguments: { ... } })`
   on the new path afterwards.
 - **Wrong parameter names.** Use `template_id`, `element_path`,
   `etag` (NOT `pageId`, `srcPath`, `ifMatch`).
@@ -568,11 +631,11 @@ yootheme_builder_element_update_settings({
 **Edge case:** When cloning a Grid with a source binding, the binding
 is preserved (same `source_name`). If the user wants a "data-free"
 copy, follow up with
-`yootheme_builder_advanced({ tool: "yootheme_builder_element_unbind_source", input: { ... } })`
+`yootheme_builder_advanced({ tool: "yootheme_builder_element_unbind_source", arguments: { ... } })`
 on the new path. Verify with the gateway `element_get_binding` call.
 
 **Success criterion:** After publish,
-`yootheme_builder_advanced({ tool: "yootheme_builder_page_get_schema", input: { template_id } })`
+`yootheme_builder_advanced({ tool: "yootheme_builder_page_get_schema", arguments: { template_id } })`
 shows the new section at the cloned path with the user's tweaks reflected in
 `element_get` on that path.
 
@@ -650,7 +713,7 @@ yootheme_builder_diagnose({})
 // Response shape:
 // {
 //   plugin_reachable: true,
-//   plugin_version: "1.1.0",
+//   plugin_version: "1.2.0",
 //   yootheme_loaded: true,
 //   yootheme_version: "5.0.22",
 //   endpoint_count: 16,
@@ -707,8 +770,8 @@ an instance with a sensible default props payload.
    iterates on the props. **Note: this REPLACES `props` entirely by
    default; pass `merge: true` for a server-side deep-merge.** When
    replacing, include every key you want to keep.
-8. `yootheme_builder_advanced({ tool: "yootheme_builder_page_save", input: { template_id, etag } })`
-   then `yootheme_builder_advanced({ tool: "yootheme_builder_page_publish", input: { template_id, etag } })`.
+8. `yootheme_builder_page_save({ template_id, etag })`
+   then `yootheme_builder_page_publish({ template_id, etag })`.
 
 **Common pitfalls:**
 
@@ -788,11 +851,11 @@ and the props payload you passed.
   elicitation, it returns a preview-with-confirm-required response;
   call again with `confirm: true`.
 - **Unbind a source**: call through the gateway:
-  `yootheme_builder_advanced({ tool: "yootheme_builder_element_unbind_source", input: { template_id, element_path, etag, confirm: true } })`.
+  `yootheme_builder_advanced({ tool: "yootheme_builder_element_unbind_source", arguments: { template_id, element_path, etag, confirm: true } })`.
   Same elicitation flow as delete.
 - **Flat schema inspection** (e.g. enumerate every element path +
   type without fetching the whole nested tree): call through the
-  gateway: `yootheme_builder_advanced({ tool: "yootheme_builder_page_get_schema", input: { template_id } })`.
+  gateway: `yootheme_builder_advanced({ tool: "yootheme_builder_page_get_schema", arguments: { template_id } })`.
 - **Etag-only fetch** (e.g. polling for concurrent edits): use
   `yootheme_builder_get_etag()` (takes no arguments) is cheaper than
   fetching the full layout.
@@ -807,7 +870,7 @@ and the props payload you passed.
 - **Strip legacy `implode` directives** from an element binding (audit-clean
   source props that pre-date the wrapper-source refactor): call through the
   gateway:
-  `yootheme_builder_advanced({ tool: "yootheme_builder_clean_implode_directives", input: { template_id, element_path, etag } })`.
+  `yootheme_builder_advanced({ tool: "yootheme_builder_clean_implode_directives", arguments: { template_id, element_path, etag } })`.
   Returns the audit log + a fresh ETag; idempotent (`cleaned_count: 0` when
   there is nothing to remove).
 
@@ -821,35 +884,41 @@ Joomla administrator access." Don't fabricate tool calls.
 
 <!-- TOOL-CATALOG:BEGIN -->
 
-**26 catalogued tools** plus the `yootheme_builder_advanced` gateway = **27 reachable via `tools/list`** (17 L1 + 2 L3 + 1 gateway = 20 advertised; the gateway routes to 7 additional advanced tools, bringing the total to 27 callable). Generated by `scripts/extract-tools.mjs` from the compiled `buildAllTools()` registry. Do not hand-edit this section; re-run `npm run build && node scripts/extract-tools.mjs` after changing tool definitions.
+**32 catalogued tools** plus the `yootheme_builder_advanced` (write) + `yootheme_builder_advanced_read` (read-only) gateways = **34 reachable via `tools/list`** (25 L1 + 2 L3 + 2 gateways = 29 advertised; the gateways route to 5 additional advanced tools, bringing the total to 34 callable). Generated by `scripts/extract-tools.mjs` from the compiled `buildAllTools()` registry. Do not hand-edit this section; re-run `npm run build && node scripts/extract-tools.mjs` after changing tool definitions.
 
 | Tool | Kind | Input keys | Description |
 | --- | --- | --- | --- |
-| `yootheme_builder_clean_implode_directives` | idempotent | `element_path`, `etag`, `site_id`, `template_id` | Strips `props.source.props.*.implode` directives from an element binding. Returns audit log + new ETag. Idempotent (cleaned_count: 0 when nothing to remove). Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_clean_implode_directives` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | Strips `props.source.props.*.implode` directives from an element binding. Returns audit log + new ETag. Idempotent at the server (cleaned_count: 0 when nothing to remove) but classed as destructive because the affected binding cannot be restored without re-mapping. Always ask the user to confirm first, then call again with `confirm: true`. Requires ETag. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_diagnose` | read+idempotent | `site_id` | Full diagnostic: /health + authenticated /etag probe. Returns site_url, home_url, plugin reachability, Bearer validity in one call. First call when you need to know where the site lives. For per-template URLs see pages_list. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_add` | mutating | `children`, `element_type`, `etag`, `parent_path`, `props`, `site_id`, `template_id` | Add a new element to a template. Provide `parent_path` (or "" for root), `element_type` (e.g. "headline", "text", "grid"), and optional `props` / `children`. Returns the new element's JSON-Pointer path. Requires ETag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_bind_source` | idempotent | `bindingLevel`, `element_path`, `etag`, `field_mappings`, `site_id`, `source_id`, `source_name`, `template_id` | Binds a Builder source to an element (sets `props.source`). Use bindingLevel "item" on Multi-Items containers (grid/slideshow/switcher/…) to bind on the first *_item child instead of the container itself. Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_add` | mutating | `children`, `element_type`, `etag`, `index`, `parent_path`, `position`, `props`, `site_id`, `template_id`, `type_name` | Add a new element to a template. Provide `parent_path` (or "" for root), `element_type` (e.g. "headline", "text", "grid"), and optional `props` / `children`. Appends by default; pass `index` (0 = first) to insert before siblings. Returns the new element's JSON-Pointer path. Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_bind_source` | idempotent | `bindingLevel`, `element_path`, `etag`, `field_mappings`, `site_id`, `source_id`, `source_name`, `template_id` | Binds a Builder source to an element (canonical shape: `source` top-level). Pass `field_mappings` in the SAME call; bindingLevel "item" binds a container's first *_item child. Leaf under an iterating *_item → CONSOLIDATE onto item slots (409 slot_collision if taken/not a slot); leaf under a #parent fragment → INHERIT (`__node_item__`); standalone renders empty. List on a grid_item with children → iterator_is_leaf_renderer. Map: bind `map_item`, map `location` to a "lat,lng" field or no markers. Requires ETag. Call directly. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_element_clone` | mutating | `element_path`, `etag`, `site_id`, `template_id` | Clone an element as a sibling (same parent, immediately after the source). Returns the new element's path. Requires ETag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_delete` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | PERMANENTLY delete an element and all its children. Cannot be undone. Always ask the user to confirm first, then call again with `confirm: true`. Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_delete` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | PERMANENTLY delete an element + children. Cannot be undone. Pass `confirm: true` (boolean) AND a fresh ETag. If `preview:true` returns despite confirm, check `details.received_confirm` — strings/numbers accepted, but boolean is canonical. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_element_get` | read+idempotent | `element_path`, `site_id`, `template_id` | Get the full element object at a specific JSON-Pointer path, including props and children. Use yootheme_builder_element_list to discover paths. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_get_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | Read the source binding attached to an element: the bound source name, the field-mappings (which source field feeds which element prop) and the query arguments/directives. Returns the empty object if the element is not bound. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_get_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | Read the source binding attached to an element — the bound source name, the field-mappings (which source field feeds which element prop) and the query arguments/directives. Returns the empty object if the element is not bound. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_element_list` | read+idempotent | `cursor`, `depth`, `fields`, `limit`, `root_path`, `site_id`, `template_id` | List elements in a template as a flat array with JSON-Pointer paths + types. Scope with `root_path`/`depth` for a subtree, paginate with `limit`/`cursor` for large templates. `fields[]` narrows each row. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_element_move` | idempotent | `element_path`, `etag`, `site_id`, `template_id`, `to_index`, `to_parent_path` | Move an element to a new parent + index in the tree. Useful for reordering or reparenting (e.g. moving a card from one grid column to another). Requires ETag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_type_get_schema` | read+idempotent | `element_type`, `site_id`, `type_name` | **Call before every `element_add` / `_update_settings`.** Unknown prop keys are silently dropped server-side, so guessing fails quietly. Returns `{name,type,label?}` field descriptors. Use `element_type`; `type_name` is DEPRECATED. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_types_list` | read+idempotent | `fields`, `site_id` | 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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_unbind_source` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | Remove the source binding from an element. Clears `props.source`. Destructive in the sense that it may break dynamic-content rendering, so always ask the user to confirm. Requires ETag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_update_settings` | idempotent | `element_path`, `etag`, `merge`, `props`, `site_id`, `template_id` | Update `props` on an element. Default replaces all props; pass `merge:true` for server-side deep-merge (only request keys overwritten, others survive, which avoids read-modify-write races). Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_type_get_schema` | read+idempotent | `element_type`, `site_id`, `type_name` | **Call before every `element_add` / `_update_settings`** — unknown prop keys are silently dropped server-side, so guessing fails quietly. Returns `{name,type,label?}` field descriptors. Use `element_type`; `type_name` is DEPRECATED. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_types_list` | read+idempotent | `fields`, `site_id` | 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. 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. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_unbind_source` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | Remove the source binding from an element. Clears `props.source`. Destructive in the sense that it may break dynamic-content rendering — always ask the user to confirm. Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_update_settings` | idempotent | `element_path`, `etag`, `merge`, `props`, `site_id`, `template_id` | Update `props` on an element. Default replaces all props; pass `merge:true` for server-side deep-merge (only request keys overwritten, others survive — avoids read-modify-write races). Requires ETag. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_get_etag` | read+idempotent | `site_id` | Get the current ETag (state revision) for the YOOtheme builder. Returns sha256+revision string used for optimistic locking on writes. Pass the returned value back as `etag` on any write tool (page_save, page_publish, element_add, element_update_settings, element_clone, element_move, element_delete). The server returns HTTP 412 if the ETag has changed since you read it. Keywords: get etag, current etag, state revision, optimistic lock, version stamp. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_health` | read+idempotent | `site_id` | Check plugin installed/reachable. Returns plugin version, YT Pro version, REST endpoints. Authenticated payload adds site_url + home_url for deep-linking. See yootheme_builder_diagnose for Bearer-validity + connectivity summary. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_inspect_multi_items_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | 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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_get_layout` | read+idempotent | `fields`, `flat`, `site_id`, `template_id` | Get full layout tree for one template. Default nested `{layout, etag}`. Set `flat:true` for depth-first array `{elements:[...], etag}`; combine with `fields[]` to project per-element. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_get_schema` | read+idempotent | `site_id`, `template_id` | Get the flat schema for a template: a list of nodes with their JSON-Pointer paths and element types. Best entry-point for navigation: lighter than page_get_layout, sufficient to locate elements before editing. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_publish` | idempotent | `etag`, `site_id`, `template_id` | Publish a template: persist state, flush YT + WP caches, snapshot the published-state ETag. ETag optional. When provided, 412 on conflict; when omitted, last-write-wins. Recommended for collaborative edits. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_save` | idempotent | `etag`, `site_id`, `template_id` | Re-run save-transforms and persist. ETag optional. When provided, 412 on conflict; when omitted, last-write-wins. Recommended for collaborative edits. No-op when state is byte-identical (returns `no_changes:true`, ETag unchanged). Operates on the default site unless site_id is provided. |
-| `yootheme_builder_pages_list` | read+idempotent | `fields`, `site_id` | List all pages, templates, and layouts in the YOOtheme Pro builder. Returns template_id, label, type, element count, and frontend_url per row. CALL THIS FIRST to discover available template IDs before any tool that needs a template_id (page_get_layout, element_list, page_get_schema, etc.). Keywords: list pages, list templates, list layouts, discover template_id, index, available templates, what pages exist. Pass `fields:["id","label"]` to slim. Returns ALL pages in one call (no pagination, typically <50 templates per site). Operates on the default site unless site_id is provided. |
+| `yootheme_builder_inspect_multi_items_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | Reports Multi-Items binding state: container/item pair (grid↔grid_item, 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. For map/map_item, a bound item without a `location` ("lat,lng") field is flagged as a blocking map_location_warning (renders 0 markers). 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. |
+| `yootheme_builder_inspect_sublayout` | read+idempotent | `element_path`, `site_id`, `template_id` | Inspects a panel/grid_item `< SUBLAYOUT`: lists the `fragment` subtree bindable leaves (with JSON-Pointer paths to bind on — NOT the container) and the render-time inner grid. Flags `ungated_grid_prop` (blocking): grid props set but the gate (title_align=left / image_align=left\|right) unsatisfied → silent no-op. For container↔item binding see inspect_multi_items_binding. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_page_dynamize` | mutating | `conditions`, `element_path`, `etag`, `leaf_map`, `list_source_name`, `page`, `remove_leaves`, `section_name`, `site_id`, `source_map`, `template_id` | One-call way to dynamize a designed section: copies the layout byte-identically and swaps only what you map. Use INSTEAD of hand-editing JSON. Give a REFERENCE (section_name from template_summary, or element_path) + list_source_name + a leaf_map (original leaf field-name → flat flow field; #parent + tuned props kept). A section with several source blocks (Played/Next/Later) dynamizes in ONE call via source_map ({match, source_name, leaf_map?}[]). Sub-query panels: key by "<subquery>.<leaf>". Returns page + `summary`. Requires page.title. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_page_get_layout` | read+idempotent | `fields`, `flat`, `force`, `mode`, `site_id`, `template_id` | Get the layout tree for one template. For dynamize/bind work prefer `mode:"bindings_only"` — just the binding skeleton (path, element_type, name, has_binding, source{query_name,props,has_condition}, children), no style props, typically <=15% of full size. Default `mode:"full"` returns nested `{layout, etag}`. `flat:true` gives a depth-first `{elements:[...], etag}` array (combine with `fields[]`). A repeated full read of an unchanged template auto-skips with `[unchanged]` — `force:true` re-fetches. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_page_get_schema` | read+idempotent | `site_id`, `template_id` | Get the flat schema for a template — a list of nodes with their JSON-Pointer paths and element types. Best entry-point for navigation: lighter than page_get_layout, sufficient to locate elements before editing. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_page_publish` | idempotent | `etag`, `site_id`, `template_id` | Publish a template — persist state, flush YT + WP caches, snapshot the published-state ETag. ETag optional — when provided, 412 on conflict; when omitted, last-write-wins. Recommended for collaborative edits. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_page_save` | idempotent | `etag`, `layout`, `site_id`, `template_id` | Re-run save-transforms + flush caches. Optionally pass a whole `layout` to REPLACE the template tree ATOMICALLY (F85) — ideal for wholesale dynamization (read layout → swap query → remap fields → write back). A supplied layout is validated + ETag-locked; on rejection nothing is persisted. Omit `layout` to just re-run transforms (no-op if byte-identical) — for incremental edits use element_add/update/bind/delete first. New pages: pages_create. Publish: page_publish. ETag optional (412 on conflict; else last-write-wins). Operates on the default site unless site_id is provided. |
+| `yootheme_builder_pages_create` | idempotent | `dry_run`, `layout`, `menu_item`, `published`, `site_id`, `slug`, `status`, `title` | Create a page (WordPress) or article (Joomla 5/6) with a YOOtheme per-page layout. Required: title. Optional: slug, status (default draft), published (default false → live on true: WP publish / Joomla state 1), layout (JSON), menu_item (Joomla SEF route), dry_run (preflight, no persist). Returns page_id (WP) / article_id (Joomla), slug, template_id (page:{id} or article:{id}), etag, warnings. Joomla: a published article has NO SEF route until a menu item points at it — pass menu_item, else frontend_url may 404. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_pages_delete` | idempotent | `confirm`, `force`, `post_id`, `site_id` | Delete a page (WordPress) or article (Joomla 5/6) with its YOOtheme per-page layout. Requires confirm:true (gate against accidental deletion). Default: trash (recoverable). force:true: permanent delete. Refuses non-page/article types with 403 (Layer 9 defense). Returns deleted:true, page_id (WP) / article_id (Joomla), force_deleted, bumped etag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_pages_list` | read+idempotent | `fields`, `site_id` | List all pages, templates, and layouts in the YOOtheme Pro builder. Returns template_id, label, type, element count, frontend_url, and builder_url (deep-link to open it in the builder) per row. CALL THIS FIRST to discover available template IDs before any tool that needs a template_id (page_get_layout, element_list, page_get_schema, etc.). Keywords: list pages, list templates, discover template_id. Pass `fields:["id","label"]` to slim. Returns ALL pages in one call (no pagination, typically <50 templates per site). Operates on the default site unless site_id is provided. |
+| `yootheme_builder_scaffold_section` | mutating | `columns`, `etag`, `site_id`, `template_id` | Create a VALID section → row → column hull in ONE atomic call and return the column JSON-Pointer path(s) to drop content into. This is the EASIEST correct way to start a new layout block: YOOtheme content must live in section → row → column, and adding content anywhere else (root, bare section, bare row) is rejected. Pass `columns` (1-12, default 1) for a multi-column row. Requires ETag. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_sites_list` | read+idempotent | `site_id` | List all sites configured in this multi-site MCP installation. Returns site_id + URL + platform (wordpress\|joomla) + default flag per row. CALL THIS FIRST when working with a fresh MCP connection to discover available site_ids before targeting one with any other tool. Read-only, no REST calls. Keywords: list sites, list connections, list installations, discover site_id, available sites, configured sites, what sites exist, multi-site index. (site_id is accepted for schema-uniformity but ignored by this tool.) |
 | `yootheme_builder_sites_test` | read+idempotent | `site_id` | Verify connectivity to ONE site: probes /health (no auth) + /etag (auth) in parallel; returns plugin_reachable + bearer_valid. `site_id` is REQUIRED. Use sites_list to find IDs. |
-| `yootheme_builder_sources_list` | read+idempotent | `fields`, `site_id` | List all data sources, feeds, and dynamic content sources available in the YOOtheme Pro builder. Returns name + label + origin (apimapper / wordpress / joomla / essentials) per source. CALL THIS BEFORE binding any element to a data source. Pick a source name from the list and pass it to `element_bind_source`. Keywords: list sources, list data sources, list feeds, list bindings, dynamic content, available data, what sources exist. Pass `fields[]` to narrow each row. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_template_summary` | read+idempotent | `site_id`, `template_id` | Token-efficient template overview: element counts by type, binding count, max nesting depth, and named landmark sections, computed server-side in one call. Use this to grasp a large template before pulling element_list or page_get_layout. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_sources_list` | read+idempotent | `fields`, `site_id` | List all data sources, feeds, and dynamic content sources available in the YOOtheme Pro builder. Returns name + label + origin (apimapper / wordpress / joomla / essentials) per source. CALL THIS BEFORE binding any element to a data source. Then bind directly with yootheme_builder_element_bind_source (a first-class tool in tools/list). Keywords: list sources, list data sources, list feeds, list bindings, dynamic content, available data, what sources exist. Pass `fields[]` to narrow each row. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_template_summary` | read+idempotent | `site_id`, `template_id` | Token-efficient template overview: element counts by type, binding count, max nesting depth, and named landmark sections — computed server-side in one call. Use this to grasp a large template before pulling element_list or page_get_layout. Example: yootheme_builder_template_summary({ template_id: "default" }). Operates on the default site unless site_id is provided. |
+| `yootheme_builder_use_site` | idempotent | `probe`, `site_id` | Switch the ACTIVE site for this multi-site session. After this call, every tool that omits `site_id` targets the site you picked here. NOTE: this default is PROCESS-WIDE — concurrent clients sharing this MCP server inherit it; pass `site_id` per call for isolation between parallel agents. Runs a /health + /etag probe by default; pass `probe: false` to switch offline. A degraded site is a soft warning (the switch still happens). `site_id` is REQUIRED. Keywords: switch/change/set active/target site, select installation, use profile. Use yootheme_builder_sites_list first to find IDs. |
 
 <!-- TOOL-CATALOG:END -->