@wootsup/yt-builder-mcp 1.12.0 → 2.0.0

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

@@ -12,18 +12,20 @@ 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 catalogues 53 typed, scoped,
-idempotent tools (55 callable end-to-end with the two gateways). 42 of them
+`@wootsup/yt-builder-mcp` server. The server catalogues 60 typed, scoped
+tools (62 callable end-to-end with the two gateways). 49 of them
 advertised as first-class entries in `tools/list`
-(38 essential L1 forwards + 2 direct L3 entries + 2 gateways), and 13 advanced
+(45 essential L1 forwards + 2 direct L3 entries + 2 gateways), and 13 advanced
 tools reachable through the gateways. The write-capable
 `yootheme_builder_advanced` gateway routes all 13; the read-only
 `yootheme_builder_advanced_read` gateway routes only the read-only subset
-(page_get_schema, inspect_sublayout, layout_query, local_content_types,
+(inspect_sublayout, layout_query, local_content_types,
 local_content_read, pages_audit, heading_outline, navigation) 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.
+per-call write-approval prompt. This 3-lane split exists because Cursor (and
+similar hosts) cap a server at roughly 40 first-class `tools/list` entries —
+it keeps the advertised surface small while every catalogued tool stays
+fully reachable through the gateways.
 
 ## How to use this MCP server
 
@@ -54,7 +56,7 @@ Some clients (notably Claude Desktop with the `.mcpb` 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 42 first-class tools (38 essential, 2 direct, 2 gateways).
+  Provides the 49 first-class tools (45 essential, 2 direct, 2 gateways).
   The `yootheme_builder_advanced` gateway routes all 13 advanced tools; the
   read-only `yootheme_builder_advanced_read` gateway routes the read-only
   subset without a write-approval prompt.
@@ -82,39 +84,40 @@ 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.
-- **38 essential forwarded tools**: common reads + the most-used writes
-  (pages_list, pages_resolve, pages_create, pages_delete, page_dynamize, scaffold_section,
-  get_etag, element_list / add / update_settings / set_status / get / move / clone / delete,
+- **45 essential forwarded tools**: common reads + the most-used writes
+  (pages_list, pages_resolve, pages_create, pages_delete, pages_set_status, pages_restore, page_generate_dynamic, scaffold_section,
+  get_etag, get_skill, element_list / add / update_settings / set_status / get / move / clone / delete,
   page_get_layout, sources_list, source_get_schema, element_types_list, element_type_get_schema,
   template_summary, inspect_multi_items_binding, library_browse, library_get, library_insert,
-  image_search, image_import,
+  image_search, image_import, modules_delete,
   sites_list, sites_test,
-  use_site, the bind→verify→save→publish chain element_bind_source /
-  element_get_binding / page_save / page_publish, and the archive-rebind /
-  refactor surface render_preview / element_set_source / rename_source /
+  use_site, the bind→verify→save→publish→unbind chain element_bind_source /
+  element_get_binding / page_save / page_publish / element_unbind_source, and the archive-rebind /
+  refactor surface render_preview / element_set_source / repair_source_references /
   template_set_type). Always advertised in
   `tools/list` so AI clients see them first-class. `element_get_binding`
   (B4) is L1 so the verify half of a bind is a direct call, not a
   gateway hop. `source_get_schema` (U4-L1) is L1 so the archive/category
   binding entry-point — introspect a source's query methods + relations +
   the current-term archive-context convention before binding — is a direct
-  call too. `render_preview`, `element_set_source`, `rename_source` and
-  `template_set_type` (customer HANDOFF-4/5) are L1 so the core write/refactor +
+  call too. `render_preview`, `element_set_source`, `repair_source_references`
+  and `template_set_type` (customer HANDOFF-4/5) are L1 so the core write/refactor +
   render-verify tools an agent reaches for after a taxonomy/CPT rename — set a
   precomposed source at a pointer, render-verify the saved page is not silently
-  blank, rename a source/field template-wide, re-type an orphaned archive/single
+  blank, repair a source/field binding REFERENCE template-wide (the registered
+  source itself is untouched), re-type an orphaned archive/single
   template — are direct calls, not undiscoverable gateway hops. `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). `library_browse` (Task 2, Layout Library) is L1
+  structural-hierarchy guard). `library_browse` (Layout Library) is L1
   so browsing the YOOtheme Pro Library catalog — pre-designed page layouts and
   element presets, filterable by topic/type/role/website/element_type/query —
   is a direct call before hand-building a section from scratch. `library_get`
-  (Task 3, Layout Library) is L1 so fetching a SINGLE browsed item's full tree
+  (Layout Library) is L1 so fetching a SINGLE browsed item's full tree
   + derived section list (`{id, name, path, element_count}` per top-level
   section) — the natural next call once `library_browse` returns an `id` —
-  is a direct call too. `library_insert` (Task 6, Layout Library) is L1 so
+  is a direct call too. `library_insert` (Layout Library) is L1 so
   composing + persisting a browsed/fetched item (layout, section, or preset)
   onto a page or existing template — target `new_page` / `{template_id,
   element_path}` / `sublayout` — through the SAME hardened write chain as
@@ -124,24 +127,98 @@ The server exposes:
   the chosen photo into the site's Media Library, are direct calls — the
   step that turns a placeholder-filled skeleton into a finished-looking
   page (see "Fill image slots with real on-topic photos" under Layout
-  Library).
-- **13 advanced captured tools**: everything else (page_get_schema,
-  element_unbind_source, clean_implode_directives,
+  Library). `get_skill` (Design E2, 2026-08-10) is L1 because it is the
+  Rettungsanker back to this document: the connect-time `instructions`
+  field now carries only a short curated preamble instead of the full
+  SKILL.md, so without this tool being directly callable a cold agent
+  would have no way to reach the rest of the guide. Call it without
+  `topic` for the list of chapters, or with `topic: "<slug>"` for one
+  chapter verbatim. `element_unbind_source` is L1 so the write half of
+  the bind pair is discoverable the same way its siblings
+  (`element_bind_source`, `element_get_binding`, `element_set_source`)
+  already are — a customer looking for "how do I remove a binding" could
+  otherwise not find it by name in `tools/list`, nor from any of the
+  other three tools' own descriptions. `pages_restore` is L1 for the same
+  discoverability reason: two cold-customer runs each measured the same gap
+  from opposite ends — a trashed page/article could not be found, and even
+  once found there was no correct way back — and one caller searched
+  explicitly for "restore"/"untrash"/"recover" and found nothing, because a
+  gateway-only placement is discoverable only to a caller who already knows
+  the tool exists.
+- **13 advanced captured tools**: everything else (
+  clean_implode_directives,
   `inspect_sublayout`, `layout_query`, `library_save_as`, the two Local
   Content Read tools `local_content_types` / `local_content_read`,
   `pages_audit`, `library_delete` — the INVERSE of `library_save_as` —
   `heading_outline`, a real doc-order H1-H6 outline of one page,
-  `navigation`, the site's menus as a parent -> children tree, and
-  `header_transparency_set`, the transparent-header inspect/repair).
+  `navigation`, the site's menus as a parent -> children tree,
+  `header_transparency_set`, the transparent-header inspect/repair,
+  `modules_update`, the widget/module write surface, and
+  `modules_create`, the widget/module CREATE surface).
+  `modules_delete`, the widget/module DELETE surface, is first-class (L1) —
+  not one of these 14 (live-test-befunde, 2026-08-11): the one
+  gateway-only destructive tool that removes data OUTSIDE the layout tree (a
+  Joomla module row + its `#__modules_menu` assignments), so a host can gate
+  it individually instead of only via the all-or-nothing "Advanced Tool
+  Gateway" permission.
+  To remove a widget/module — the clean-up verb create/update lacked, so a
+  probe no longer leaves permanent litter on a customer site — pass the widget
+  `id` and PREVIEW first (`confirm` defaults FALSE and the call deletes
+  NOTHING, answering with the row plus `usage.element_refs` /
+  `usage.assigned_pages`):
+  `yootheme_builder_modules_delete({ id: "custom_html-2" })`,
+  then repeat with `confirm: true` AND an `intent` — a call missing or
+  misnaming it is refused with a 400 naming exactly which intents are
+  possible for the module's CURRENT state, each with its own
+  `effect`/`reversible`/`native_name`, so calling with neither `confirm` nor
+  `intent` doubles as that discovery step.
+  WHICH INTENTS ARE OFFERED DEPENDS ON THE PLATFORM AND STATE, because each
+  arm mirrors its own CMS rather than inventing a common one. `intent:
+  "permanent"` is offered on BOTH platforms and deletes the row for good —
+  irreversible, and `modules_create` makes a NEW id with default fields
+  rather than restoring this one. `intent: "trash"` exists ONLY on JOOMLA
+  and is REVERSIBLE: it sets `published = -2` — the module manager offers
+  `Trash` and no direct `Delete` at all, and its `Delete` button exists only
+  in the *Trashed* view. The row and its `#__modules_menu` assignments
+  survive and Joomla restores both; it does stop rendering at once (Joomla
+  loads modules with `published = 1`), so an element bound to it shows
+  nothing meanwhile. Joomla offers `"permanent"` directly too — trashing
+  first is no longer required to remove a module for good — but once a
+  module is ALREADY trashed, `"trash"` stops being offered (only
+  `"permanent"` empties it from there). On WORDPRESS widgets have no trash
+  step at all (`widgets.php` offers deactivate-by-drag and an immediate
+  `Delete` link, not a recoverable one), so only `"permanent"` is ever
+  offered there and the confirmed call is always the irreversible one. Read
+  the MEASURED `trashed` / `deleted` flags in the response rather than
+  assuming which happened.
+  Only wanted it off the page, not gone? That is not a removal at all, and
+  `modules_delete` is the wrong tool: `modules_update({ id, active: false })`
+  parks the widget in WordPress's **Inactive Widgets** area (settings stay
+  intact, dragging it back into a widget area restores it) or unpublishes the
+  module on Joomla (`published = 0`, position kept) — the same wording the
+  400 response's `notes` gives when you call `modules_delete` without an
+  `intent`.
+  A layout element that references the id DIRECTLY
+  (`usage.element_refs` with `via:"element"`) BLOCKS the IRREVERSIBLE step with
+  a 409 naming every stranded location, until you either remove those elements
+  with `element_delete` or pass `acknowledge_element_refs`: true. Joomla's
+  reversible `"trash"` step is never refused — a restore puts the reference
+  back in working order — so on that platform the 409 can only come from
+  `intent: "permanent"`. An INDIRECT
+  reference (`via:"position"`, a `module_position` element naming the POSITION
+  this module sits in) never blocks, because it points at a position rather
+  than at this module and stays valid for whatever else occupies it.
+  `assigned_pages` never blocks either: a Joomla module's `#__modules_menu`
+  rows are its OWN rows and go with it.
   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 } })`.
+  `yootheme_builder_advanced({ tool: "yootheme_builder_inspect_sublayout", arguments: { layout_id, element_path } })`.
   And to find elements by a structured filter (G5 — no expression language,
-  AND-combined `type`/`name_matches`/`has_binding`/`max_depth`/`under_section`):
-  `yootheme_builder_advanced({ tool: "yootheme_builder_layout_query", arguments: { template_id, type: "headline", has_binding: false, under_section: "Hero" } })`
+  AND-combined `element_type`/`name_matches`/`has_binding`/`max_depth`/`under_section`):
+  `yootheme_builder_advanced({ tool: "yootheme_builder_layout_query", arguments: { layout_id, element_type: "headline", has_binding: false, under_section: "Hero" } })`
   (it's read-only, so the read gateway `yootheme_builder_advanced_read({ tool: "yootheme_builder_layout_query", … })` works too).
-  And to save a page/subtree INTO "My Layouts" (Task 7 — the reverse of
+  And to save a page/subtree INTO "My Layouts" (the reverse of
   `library_insert`; omit `element_path` to save the whole page):
   `yootheme_builder_advanced({ tool: "yootheme_builder_library_save_as", arguments: { source: { template_id, element_path }, name: "Hero Section" } })`.
   It flags `invalid_source_possible: true` when the saved subtree carries
@@ -162,7 +239,7 @@ The server exposes:
   And to get a real, doc-order H1-H6 outline of ONE page (each heading with
   its source element and TEXT, plus the alt-status of every image) —
   read-only STRUCTURE inspection, not findings:
-  `yootheme_builder_advanced_read({ tool: "yootheme_builder_heading_outline", arguments: { template_id } })`
+  `yootheme_builder_advanced_read({ tool: "yootheme_builder_heading_outline", arguments: { layout_id } })`
   (or via the write gateway: `yootheme_builder_advanced({ tool: "yootheme_builder_heading_outline" })`).
   And to see the site's Haupt- + Sub-Menüstruktur as a parent -> children
   TREE (not a flat list) — for "which page sits under which menu item"
@@ -179,24 +256,55 @@ The server exposes:
   TRUE, so this call reports the current state, the theme-declared
   `--uk-inverse`, `risk_class`, `confidence` and `would_change` without
   touching anything:
-  `yootheme_builder_advanced({ tool: "yootheme_builder_header_transparency_set", arguments: { template_id } })`
+  `yootheme_builder_advanced({ tool: "yootheme_builder_header_transparency_set", arguments: { layout_id } })`
   Repeat with `mode: "auto", dry_run: false, etag` to write the theme-declared
   colour. See "Transparent header (the exception — never a default)".
+  And to update a widget's (WordPress) or module's (Joomla) title,
+  position, or theme_overlay — a WRITE, so the write gateway only.
+  `dry_run` defaults to TRUE, so this call previews the diff without
+  touching anything:
+  `yootheme_builder_advanced({ tool: "yootheme_builder_modules_update", arguments: { id: "custom_html-2", title: "New Title" } })`
+  Repeat with `dry_run: false` to persist. See "Now change what you found —
+  `modules_update`" above for the platform-specific field split.
+  And to CREATE a new widget/module — one of exactly five known types
+  (WordPress custom_html/text/block; Joomla mod_custom/mod_menu) — a WRITE,
+  so the write gateway only. `placement` is REQUIRED (`position` /
+  `module_element` / `position_element` — how the module reaches a page); a
+  call without it creates NOTHING and returns BOTH halves of the answer:
+  `ways`, every way for this platform with its reach and a summary, and
+  `notes`, what `modules_create` can build and when you need no module at all.
+  Which ways additionally need a `position` is a PLATFORM fact: all three on
+  WordPress, two on Joomla. It is never defaulted on either. `dry_run` defaults to TRUE, so once `placement` is chosen this call
+  previews (type, position, fields) without creating anything:
+  `yootheme_builder_advanced({ tool: "yootheme_builder_modules_create", arguments: { type: "custom_html", title: "New Widget", content: "<p>Hi</p>", placement: "module_element", position: "builder-1" } })`
+  Repeat with `dry_run: false` to persist — the response's `row` is the full
+  `local_content_read(kind:'modules')` shape and `next_step` is the exact
+  follow-up call **for the placement you chose**, which is an `element_add`
+  for only two of the three: `module_element` and `position_element` get one,
+  `position` gets `modules_update{assignment}` on Joomla and a read-only
+  `local_content_read{kind:"modules", include_usage:true}` on WordPress — the
+  widget is already live site wide (no write to narrow it with), but add
+  `verify_on_urls` to that same call to PROVE guest-visible rendering rather
+  than trust `active`/`builder_visible` alone. See "Create → wire in (the
+  two-step recipe)" below.
 
   The core write/refactor + render-verify tools the customer HANDOFF-4/5 ask for
   are now **L1 — call them directly by name**, not through a gateway:
   - To render-check a saved page over the authenticated channel (F5+N5 — does
     it render, with how many items, or is it silently blank? where an external
     cURL 401s behind staging Basic-Auth), call the now-L1
-    `yootheme_builder_render_preview({ template_id })` directly — or address it by
+    `yootheme_builder_render_preview({ layout_id })` directly — or address it by
     a public URL with `yootheme_builder_render_preview({ url })` (the URL is
     resolved to its template for you, exactly like `page_get_layout`), so if you
     only hold a resolved category/archive URL you can render-check it in ONE call
-    without first converting it to a template_id. It takes no post/term target: it
+    without first converting it to a layout_id. It takes no post/term target: it
     renders YOOtheme's implicit fallback context, so a source-bound template comes
     back non-empty. Treat a non-empty render as the success signal, not "blank
-    despite a binding". `item_count` counts the TOP-LEVEL repeat-source rows only
-    (a static grid/list nested in a repeated card no longer inflates it). Pass
+    despite a binding". `rendered_item_wrapper_count` counts the TOP-LEVEL repeat-item
+    wrappers the render emitted, BOUND OR NOT (a static grid/list nested in a repeated
+    card does not inflate it); `source_item_counts` is the per-source ROW count,
+    and `unresolved_sources` names any bound source the registry does not recognise
+    (the render still succeeds, only that source contributes nothing). Pass
     `expect: "<substring>"` to confirm a specific edit reached the HTML in one call
     (the response adds `matched` + `snippet`).
   - To surgically SET a precomposed `source` + the native item-level
@@ -204,30 +312,52 @@ The server exposes:
     leaving the rest of the layout byte-unchanged (F2 — the one-call source edit
     bind_source can't do because it cannot write `source_extended`), call the
     now-L1
-    `yootheme_builder_element_set_source({ template_id, element_path, source: { query: { name: "categoryFaqs.taxonomyCategoryFaq", field: { name: "faq" } } }, source_extended: { props: { title: { query: { name: "#node" }, name: "title" } } }, etag })` directly.
-  - To template-wide RENAME a source/type/field name across EVERY binding in
-    one ETag-locked write — after a taxonomy/CPT rename (faq→help) breaks every
-    bound layout, preserving each binding's arguments + props + field_mappings
-    (N1 — instead of a whole-layout page_save), call the now-L1
-    `yootheme_builder_rename_source({ template_id, from: "categoryFaqs", to: "categoryHelps", source_map: { taxonomyCategoryFaq: "taxonomyCategoryHelp", faq: "help" }, field_map: { faq_title: "help_title" }, etag })` directly.
+    `yootheme_builder_element_set_source({ layout_id, element_path, source: { query: { name: "categoryFaqs.taxonomyCategoryFaq", field: { name: "faq" } } }, source_extended: { props: { title: { query: { name: "#node" }, name: "title" } } }, etag })` directly.
+  - To template-wide REPAIR binding REFERENCES to a source/type/field name
+    across EVERY binding in one template, in one ETag-locked write — after
+    that name changed OUTSIDE the builder (a taxonomy/CPT rename such as
+    faq→help, a re-published flow), preserving each binding's arguments +
+    props + field_mappings — this does NOT rename the source itself,
+    `sources_list` stays unchanged; call the now-L1
+    `yootheme_builder_repair_source_references({ layout_id, from: "categoryFaqs", to: "categoryHelps", source_map: { taxonomyCategoryFaq: "taxonomyCategoryHelp", faq: "help" }, field_map: { faq_title: "help_title" }, etag })` directly.
+    `to` (and each `source_map` value landing at the top-level source
+    position) must be a currently registered source name — an unregistered
+    target is refused with the nearest matches, unless you pass
+    `allow_unregistered:true` for the case where the target only exists
+    after a flow republish.
+    That write is per-template, so find WHICH templates carry the binding FIRST —
+    `yootheme_builder_layout_query({ source_name: "categoryFaqs" })` with **no**
+    `layout_id` sweeps the whole site and answers per-source counts plus the
+    templates each one lives on (add `max_paths` for the individual element
+    paths). One call instead of one per template.
+    The sweep recognises a binding by the SAME rule `has_binding` uses per
+    template, so an unfiltered call splits its `total_bindings` three ways and
+    only the first is a source: `sources` (real source names — the ones
+    `sources_list` also knows), `inherited_context_bindings` (a `#`-prefixed
+    YOOtheme Pro self-reference such as `#parent`, i.e. a binding that INHERITS
+    the row context of an iterating ancestor — on real sites this is often the
+    majority of the count and it is NOT a source), and `unnamed_bindings`
+    (bound via field mappings or a query-field selector only, so there is no
+    name for `repair_source_references` to match). Repair covers the first
+    bucket; the third names the templates you still have to open by hand.
   - To reassign which archive/single a THEME template applies to — set its
     `type` condition (the value pages_list shows) in one ETag-locked write, the
     step a taxonomy rename leaves orphaned (N3 — re-type
     `taxonomy-category_faq` → `taxonomy-category_help`), call the now-L1
-    `yootheme_builder_template_set_type({ template_id, type: "taxonomy-category_help", etag })` directly.
+    `yootheme_builder_template_set_type({ layout_id, type: "taxonomy-category_help", etag })` directly.
 
   To introspect a source's query methods + relations + the current-term
   archive-context convention (U4-L1 — turns a ~25-call YOOtheme code-dive into
   one call before binding on an archive/category template), call the now-L1
   `yootheme_builder_source_get_schema({ name: "categoryFaqs" })` directly.
 - **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,
+  into delete, so hosts gate it) and `yootheme_builder_advanced_read`
+  (read-only; routes ONLY the read-only advanced subset —
   inspect_sublayout, layout_query, local_content_types, local_content_read,
   pages_audit, heading_outline, navigation —
   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 } })`.
+  `yootheme_builder_advanced_read({ tool: "yootheme_builder_pages_audit", arguments: { site_id } })`.
   Discover the site's NATIVE content the same way — the landscape then the records:
   `yootheme_builder_advanced_read({ tool: "yootheme_builder_local_content_types" })`
   then `yootheme_builder_advanced_read({ tool: "yootheme_builder_local_content_read", arguments: { kind: "terms", taxonomy: "category" } })`.
@@ -235,9 +365,9 @@ The server exposes:
   `yootheme_builder_advanced({ tool: "yootheme_builder_local_content_types" })` and
   `yootheme_builder_advanced({ tool: "yootheme_builder_local_content_read", arguments: { kind: "entities", type: "post" } })`.)
 
-`tools/list` therefore advertises 42 names (38 + 2 + 2). That's 38 L1
-essentials + 2 L3 direct + 2 gateways. The total callable surface is 55
-(42 advertised + 13 advanced reachable through the gateways). If the AI
+`tools/list` therefore advertises 49 names (45 + 2 + 2). That's 45 L1
+essentials + 2 L3 direct + 2 gateways. The total callable surface is 62
+(49 advertised + 13 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, arguments })` (or the read gateway for
@@ -248,10 +378,14 @@ read-only tools) instead.
 The server surfaces the connected site's URLs in two places so you never have to
 guess where the agent is pointing:
 
-- **`yootheme_builder_health` (Bearer-authenticated) and
-  `yootheme_builder_diagnose`** return `site_url` and `home_url` for the
-  connected install. Call one of them when the user asks "which site are you
-  on?" or before deep-linking the user back into wp-admin / Joomla administrator.
+- **`yootheme_builder_health` (Bearer-authenticated)** returns `site_url` for
+  the connected install, and on WordPress `home_url` as well, because WordPress
+  distinguishes the two; Joomla has a single site URL and sends only
+  `site_url`. Call it when the user asks "which site are you on?" or before
+  deep-linking the user back into wp-admin / Joomla administrator.
+  `yootheme_builder_diagnose` carries `site_url` too, so read it there when you
+  are already triaging an auth failure — but **only** `site_url`. `home_url` is
+  on health alone.
 - **`yootheme_builder_pages_list`** returns per-template `frontend_url`,
   `frontend_url_template`, and `frontend_url_description` columns when the
   host plugin can resolve them. Use these when the user asks for a verification
@@ -276,9 +410,37 @@ Do not hand-write a Joomla endpoint list from memory: the Joomla paths carry a
 `yt-builder-mcp` segment (`/v1/yt-builder-mcp/pages/audit`, not `/v1/pages/audit`)
 and the router rejects the short form.
 
+If the field is **missing** from a health answer, the host could not read its own
+route table for this request — read that as "not knowable here", never as "this
+install serves nothing". It is omitted rather than sent as an empty list for
+exactly that reason.
+
 Treat `frontend_url: null` as "host plugin could not resolve a public URL for
 this template". Surface that honestly rather than fabricating one.
 
+### What a write clears, and what it does not
+
+`page_save` and `page_publish` say they flush caches. They flush **the caches
+this plugin owns**, and that is a narrower set than "the caches on this site":
+
+| layer | who clears it after a write |
+|---|---|
+| YOOtheme's own render / schema cache | this plugin |
+| the option entries this plugin writes | this plugin |
+| the CMS object-cache entry for the page itself | **the CMS core**, on its own post/article save — not this plugin |
+| a full-page cache or CDN (WP Rocket, LiteSpeed, Cloudflare, a reverse proxy) | **nobody, from here** |
+
+The last row is the one that reaches visitors. **No full-page-cache or CDN
+plugin was measured**; what was measured is that the CMS core hooks such
+plugins register on do fire during a write. That is an indication, not a
+guarantee — and on Joomla there is no equivalent link at all.
+
+So after a publish that must be visible immediately: purge the page cache / CDN
+yourself, then prove it with `yootheme_builder_fetch_public_url`, which fetches
+the page as an anonymous visitor and reports whether a cache served the answer.
+`render_preview` cannot settle this — it renders the stored layout server-side
+and never touches the visitor's path.
+
 ## Resolve a URL back to the template that renders it
 
 The two sections above go template → URL (forward). To go the OTHER way — the
@@ -287,18 +449,35 @@ complementary tools.
 
 **`yootheme_builder_pages_resolve({ url })` — the direct reverse lookup.** Paste
 any public frontend URL and it returns
-`{ template_id, post_id, type, frontend_url, context, resolved_via }` (or a
+`{ layout_id, post_id, type, frontend_url, context, resolved_via }` (or a
 `url_not_resolvable` when it genuinely maps to no template — it degrades to an
 honest null rather than guessing a wrong one). It handles **SEF / pretty
 permalinks on BOTH WordPress and Joomla** (not just raw `?option=…&id=…` query
-URLs), including deep sub-category paths like `/matches/first-men-s-team`. For a
+URLs), including deep sub-category paths like `/matches/first-men-s-team` and
+the deep ARTICLE paths a Joomla site prints for an article routed below a
+category menu item (`/company/blog/9-news/36-my-article`) — the id and the alias
+in that last segment are both checked against the article, so an address whose
+alias belongs to something else is refused rather than guessed. For a
 **category or term URL it returns the SPECIFICALLY-ASSIGNED template** — the one
 whose YOOtheme `query.catid` (Joomla) / `query.terms` (WordPress) binds THAT
 category/term, honoring **include-child-categories** (a template assigned to a
 parent category with child-inclusion covers its subcategories; the nearest
 specific assignment wins). Only when nothing is specifically assigned does it
 fall back to the governing generic theme template. Then feed the returned
-`template_id` straight into `page_get_layout` / `element_list` / the write tools.
+`layout_id` straight into `page_get_layout` / `element_list` / the write tools.
+
+**The site's own front page resolves too, in every spelling** — bare host,
+trailing slash, `…/index.php`, and the subdirectory forms of an install served
+from one (`https://example.com/joomla/index.php`). It resolves to whatever
+renders it, which on Joomla is usually the single article the default menu item
+points at. `pages_list` hands out one of those spellings as the front page's
+`frontend_url`, so an address this server issues is one it accepts.
+
+A front page that resolves to NOTHING is answered by name, not as
+`url_not_resolvable`: the code is **`url_resolves_but_no_layout`** and the
+message says which page was identified and why nothing renders it. Re-spelling
+the URL will not help there — give that page a layout, or address the governing
+template by `layout_id`.
 
 **`serves_context_kind` + `serves_context_ids` on `pages_list` rows — resolve it
 yourself, zero extra calls.** Every `pages_list` row also carries these two Layer-C
@@ -351,7 +530,7 @@ this page". Supply **exactly ONE of** these five keys:
 
 | Key | Value | Example |
 |-----|-------|---------|
-| `template_id` | An exact template id | `{ template_id: "page:4816" }` |
+| `template_id` | An exact layout id | `{ template_id: "page:4816" }` |
 | `post_id` | The numeric WP post / Joomla article id | `{ post_id: 4816 }` |
 | `url` | A public frontend URL (same resolver as `pages_resolve({ url })`) | `{ url: "https://example.com/schedule-demo/" }` |
 | `special` | A semantic page ROLE (vocabulary below) | `{ special: "home" }` |
@@ -426,15 +605,18 @@ never a transport failure — report it verbatim rather than retrying blindly.
 | `unknown_audit_mode` | 400 | A `mode` value that is not `builder` or `rendered` (a typo, e.g. `render`). | Re-send with one of the two valid values. Refused rather than silently falling back to `builder`, for the same reason as `unknown_check_category`: nothing was scanned, so the previous answer is NOT a clean result. |
 | `unknown_heading_outline_mode` | 400 | The SAME `mode` vocabulary (`builder`/`rendered`), on `yootheme_builder_heading_outline` instead of `pages_audit` — a dedicated code so the two are never confused. | Re-send with `builder` or `rendered`. |
 | `no_template_matched_types` | 400 | A site-sweep `types` filter matched NO template on this site — a typo or, most often, a case variant (`PAGE` is not `page`). Unlike `checks`, the `types` vocabulary is **open and site-dependent** (`page`, `article`, `single-post`, `com_content.category`, …), so it cannot be validated against a fixed list — only a zero match is knowable, and it is knowable only after the sweep. | Re-send with one of the types the message lists (it names what this site actually has), or omit `types` to sweep everything. Refused for the same reason as `unknown_check_category`: a filter that selected nothing answered HTTP 200 with `findings: []` and an all-zero summary, which reads as CLEAN. **Never read such an answer as clean.** |
-| `template_not_found` | 404 | The `template_id` names no template carrying a YOOtheme layout on this site. | Re-read the id from `pages_list`; ids are site-specific and change when a page is recreated. |
+| `insufficient_capability` | 403 | The object EXISTS and this key may not read it — a permission answer, not a missing page. The message names the object (`page:5040` / `article:42`). **These tools answer this way**, the ones that read ONE layout: `page_get_layout`, `layout_query` (single template), `element_list`, `element_get`, `element_get_binding`, `inspect_multi_items_binding`, `inspect_sublayout`, `render_preview`, `template_summary`, `heading_outline`. **The others do NOT**, on purpose: `pages_list`, `pages_resolve`, `pages_audit`, `get_etag` and a site-wide `layout_query` sweep report a forbidden object as absent, because a half-sharpened sweep is more misleading than an honestly lenient one. **Never read their silence about an object as proof that it does not exist.** | Do not repeat the call: it gives the same answer while the key stays the same. Ask an administrator to open the object to this key, or use a key whose subject can read it. See [Scopes](#scopes-bearer-key-permissions). |
+| `template_not_found` | 404 | The `layout_id` names no template carrying a YOOtheme layout on this site. | Re-read the id from `pages_list`; ids are site-specific and change when a page is recreated. |
 | `post_not_found` | 404 | The `post_id` names no WP post / Joomla article with a per-page layout. | Same: confirm via `pages_list`. A post that exists but has no per-page layout is rendered by a THEME template — find that template instead. |
-| `url_no_match` | 404 | The URL is well-formed but resolves to no per-page layout — usually because a theme template renders it. | Use `pages_list` to find the governing template, or `pages_resolve({ url })` for the fuller hint. |
+| `url_no_match` | 404 | The URL is well-formed but this server could not map it to any page at all — neither a per-page layout nor an archive/term/author theme template matched. Note this is NOT the "page exists, has no layout" case: that one has its own code in the next row. | Check the address is this site's and names a public, singular page/article. A LIST view is usually reached with `target: { special: … }` instead. Failing both, browse `pages_list`. |
+| `url_resolves_but_no_layout` | 404 | The URL DID resolve to a page — WordPress mapped it to a post, this server read the Joomla article the address names, or the address is this site's front page — but that page carries no YOOtheme layout of its own; something else renders it. The message names the page. | Nothing here is fixed by re-spelling the address. Give that page a layout in the builder, or find the governing theme template in `pages_list` (its `serves_context_kind` column says which context each one serves) and address it by `layout_id`. |
 | `title_no_match` | 404 | No page NAME contains that substring. | Try a shorter substring, or list with `pages_list`. |
 | `special_not_resolvable` | 404 | The token is in the vocabulary and resolvable in principle, but matches no template on THIS site. | Report which role was requested; do not silently fall back to another page. |
 | `title_ambiguous` | 409 | The substring matches two or more pages. | A `candidates` list (max 10) rides along — show it and let the user choose. |
 | `blog_ambiguous` | 409 | Joomla only: several distinct blog pages. | Same `candidates` shape; show it (see the Joomla caveat above). |
 | `special_not_supported` | 422 | The token is recognised but this platform has no such page role (today: `date`, on both). | Say so plainly instead of guessing an analogue. |
 | `target_not_scannable` | 422 | **The target resolved to a real page, but this site does not enumerate it as an auditable page** — a post type or status the page enumerator does not cover, or a trashed item. | **This is NOT a clean result.** An audit that answered 200 with zero findings would read as "your page is fine"; this code exists precisely so it cannot. Audit it via `template_summary`, or pick a page `pages_list` returns. |
+| `render_failed` | 422 | `yootheme_builder_heading_outline` in `mode:"rendered"` — the target resolved to a real template, but rendering it genuinely failed (a broken binding or other structural problem — NOT a Joomla `module`/`module_position` gap, which the server tolerates transparently; see `render_fallback`/`render_fallback_used` below). | The page is real but cannot currently be rendered. Read the message for the underlying cause; fix the layout, or fall back to `mode:"builder"` (structural inspection over the layout tree, no render needed). |
 
 `server_too_old` is the one code the SERVER never sends — see
 [Audit ONE page instead of the whole site](#audit-one-page-instead-of-the-whole-site).
@@ -460,11 +642,35 @@ Do not loop on auth errors.
 > capabilities like `manage_options` gate the admin settings page only; the
 > REST API surface is Bearer-gated.
 
-> **Joomla L2 articles surface.** The Joomla plugin ships `/v1/articles*`
-> 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 a future release.
+> **Joomla L2 articles surface.** The Joomla plugin ships READ-ONLY
+> `/v1/articles*` REST endpoints (`GET /articles`, `GET /articles/<id>/page-layout`,
+> `GET /articles/<id>/elements/<path>`) for inspecting an article's Builder
+> state, but they are NOT exposed via MCP tools in v1.x. To read that
+> surface, call the REST endpoints directly with the Bearer key. To WRITE
+> an article's layout, address it the same way as any other page — target
+> `article:<id>` with the normal page-editing tools (`page_save`,
+> `element_add`, `element_update_settings`, …); there is no separate write
+> route for articles.
+
+### The write budget is attached to the KEY, not to you
+
+Writes are rate-limited **per bearer key**. Several clients — several agents,
+several editors, a script running alongside you — sharing one key share **one**
+budget, so a burst that is well within the cap for you alone can still be
+refused. This is reproducible: six agents on one key hit it.
+
+`yootheme_builder_health` publishes the cap as `write_rate_limit`
+(`{limit, window_seconds, scope: "kid", applies_to: "writes"}`), read from the
+limiter the site actually enforces. **Read it before a burst instead of
+discovering it as a refusal.** Two bounds worth knowing:
+
+- `limit` is the CAP, never the headroom you have left — no counter is read.
+- Reads are not capped, so there is no reason to slow a read loop down for it.
+
+Exceeding it answers HTTP 429 with `retry_after_seconds`, and **the write did
+not happen** — wait out the window and retry rather than treating it as a
+failed write to investigate. Anything throttling in FRONT of the site (a CDN,
+a WAF, the host) is invisible here and answers with its own status.
 
 ---
 
@@ -507,6 +713,16 @@ To verify a specific site before doing work on it, call
 and `/etag` in parallel and returns `plugin_reachable` + `bearer_valid`
 without mutating anything.
 
+For the whole fleet at once — "which of my sites are up, and how much is on
+them" — call `yootheme_builder_sites_overview()`. It answers in ONE call what
+`sites_list` plus one `sites_test` and one `pages_list` per site answered
+before, probing every site in parallel: one row per site with `reachable`,
+`bearer_valid` and the page counts. A site that is down becomes a row carrying
+`error`, never a failed call — which is the point: you want to see WHICH site
+is broken, not lose the answer for the others. Pass `include_pages: false` to
+skip the per-site page read. The content/theme-template split on a row is
+ABSENT on a host that does not report it; it is never reported as zero.
+
 ### Default-site mechanics
 
 The default site is set automatically on first add:
@@ -527,7 +743,9 @@ You can store the Bearer key two ways per site:
 - **1Password reference**: `bearer_ref: "op://Vault/Item/credential"` in
   `sites.json`. The plaintext token never touches disk. The MCP server shells
   out to the `op` CLI at first use per site to fetch the live token, then
-  caches it in memory for that process lifetime.
+  caches it in memory for that process lifetime. `op` itself does not cache
+  — restart the MCP client after rotating a key so the server re-resolves
+  the new value.
 
 **Recommendation for production sites**: use `bearer_ref`. You get rotation
 without editing `sites.json`, and your 1Password audit log captures every
@@ -535,6 +753,24 @@ fetch. The `op` CLI must be installed and signed in on the machine running
 the MCP server. If `op` is missing, the resolver returns a structured error
 (`op CLI not found in PATH`) pointing at the install docs.
 
+### Prompt friction depends on how the client was launched
+
+Per 1Password's own documentation, an app-integration session binds to a
+**TTY** (macOS/Linux) or PID + start time (Windows) — a GUI-launched process
+(Claude Desktop, Cursor) has neither, so the confirmation-free window a
+terminal session gets does not carry over there. Three environment classes,
+worst-first:
+
+| Class | Confirmation dialogs | Who |
+|---|---|---|
+| Service account (`OP_SERVICE_ACCOUNT_TOKEN`) | none | agencies, servers, CI |
+| Terminal + app integration | one per window, valid ~10 min | developers running the CLI |
+| **GUI-launched + app integration** | **per call** | **Claude Desktop, Cursor — the customer default** |
+
+**For multi-site customers a service account is the frictionless path** —
+worth setting up explicitly rather than discovering the per-call prompts one
+site at a time.
+
 ### `sites.json` location
 
 The registry lives at `~/.config/yt-builder-mcp/sites.json` (XDG-conform).
@@ -607,9 +843,9 @@ one conversation.
 2. For each site, the agent runs the same sequence with `site_id` set:
    - `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: "/children/0/children/0/children/0/children/0", props: { content: "New headline" }, merge: true, etag: "<etag>" })`
-   - `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>" })`
+   - `yootheme_builder_element_update_settings({ site_id: "wp-acme", layout_id: "home", element_path: "/children/0/children/0/children/0/children/0", props: { content: "New headline" }, merge: true, etag: "<etag>" })`
+   - `yootheme_builder_page_save({ site_id: "wp-acme", layout_id: "home", etag: "<fresh>" })`
+   - `yootheme_builder_page_publish({ site_id: "wp-acme", layout_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.
 
@@ -623,7 +859,7 @@ for a focused diagnosis without touching the others.
 ## Pages vs theme templates (know what you are editing)
 
 `pages_list` returns TWO different kinds of editable layout, and every tool
-takes a `template_id` that addresses either. Know which one you have before
+takes a `layout_id` that addresses either. Know which one you have before
 you write — they have very different blast radius.
 
 | Kind | `id` shape | `type` value(s) | What it is |
@@ -634,7 +870,7 @@ you write — they have very different blast radius.
 **The safety rule: editing a theme template changes the layout for ALL
 matching content, not one page.** If the user says "restyle the blog post
 template", `pages_list` shows it as e.g. `{ id: "I99YS8Ii", label: "Post",
-type: "single-post" }` — editing that `template_id` restyles EVERY blog post
+type: "single-post" }` — editing that `layout_id` restyles EVERY blog post
 on the site at once. That is often exactly what's wanted (that's what theme
 templates are for), but confirm the intent — do not edit a `single-post` /
 `taxonomy-*` / `archive-*` template when the user meant one specific page.
@@ -646,6 +882,33 @@ templates are for), but confirm the intent — do not edit a `single-post` /
 - `pages_create` creates a **page/article** (an individual layout). Theme
   templates are defined in the theme itself and are not created via this MCP;
   you edit the existing ones `pages_list` reports.
+- `yootheme_builder_pages_delete` removes one — an L1 tool, call it directly
+  (no gateway). `confirm: true` is REQUIRED on every call (a bare call is
+  refused, `pages.confirm_required`); there is no preview-by-omitting-confirm
+  the way `modules_delete` has. Preview instead with `dry_run: true`
+  (reports `element_count`, `has_dynamic_binding`, and whether the real call
+  would be refused for lacking an `intent`; nothing is written and no
+  request is sent). The real call additionally needs `intent`: call
+  `confirm: true` without it once and the server refuses with a 400 naming
+  which intents are possible for THIS page's/article's CURRENT status, each
+  with its own `effect`/`reversible`/`native_name` — the same
+  `intent_not_chosen` shape `modules_delete` uses. Unlike modules,
+  `intent: "trash"` is REVERSIBLE on BOTH platforms: it sets the WordPress
+  `post_status` to `trash` or the Joomla article `state` to `-2`;
+  `intent: "permanent"` removes the row and its layout for good on either
+  platform, and neither CMS can recreate them. There is a way back from the
+  trash step, but it is NOT this tool and NOT `pages_set_status` (see "Finding
+  and un-trashing a page" below).
+  `yootheme_builder_pages_delete({ layout_id: 42, confirm: true, intent: "trash" })`.
+  A page/article ALREADY in the trash short-circuits BEFORE the intent gate:
+  passing `intent: "permanent"` still deletes it for good (the only intent
+  offered there); passing anything else — no `intent`, `intent: "trash"`, or
+  an unrecognised one — instead answers `200 {deleted:false,
+  already_trashed:true}`, a MEASUREMENT, not an error, that names
+  `intent:"permanent"` or the way back (below) as the two ways forward. The
+  EXECUTED trash response (`confirm:true, intent:"trash"`) carries the same
+  pointer in its own `note` field — the caller who just trashed something and
+  regrets it never has to re-read the preview to find it.
 
 **Reaching a theme template by ROLE instead of by id.** You rarely know a theme
 template's opaque id (`I99YS8Ii`). The `special` tokens of the shared `target`
@@ -666,6 +929,40 @@ response's `resolved_target` tells you which template that actually was. The
 same safety rule still applies: a finding on a theme template is a finding on
 EVERY page that template renders.
 
+**Finding and un-trashing a page you cannot see in `pages_list`.** A trashed
+page/article never appears there, and by default `local_content_read`
+answers the same `total: 0` for "genuinely nothing" and "it's in the trash" —
+pass `kind: "entities", status: "trash"` for the EXCLUSIVE trashed view (never
+mixed into the default list), with the identifier in `id`. Even without
+asking: a plain `local_content_read({kind:"entities"})` call carries
+`trashed_total` in the response whenever a match exists in the trash, so the
+gap surfaces unasked. Then `yootheme_builder_pages_restore({ layout_id: <id> })`
+brings it back — the ONE correct way, do NOT try `pages_set_status`, which
+refuses a trashed page with a 409 pointing at this tool. **The two platforms
+genuinely diverge here, and the tool says so rather than hiding it**:
+WordPress' `wp_untrash_post()` reinstates BOTH the exact pre-trash status AND
+the pre-trash URL slug (a hand-rolled status write would leave the trash's
+`__trashed` slug suffix in place, silently changing the address) — Joomla
+stores no pre-trash status at all, so a restored article can only become
+`unpublished`; call `pages_set_status` with `status: "published"` afterwards
+to make it visible again.
+
+**A trashed Joomla MODULE has no restore tool of its own, and the way out is
+NOT the equivalent of the above — it lands on the opposite side.** Measured:
+`yootheme_builder_modules_update({active:true})` writes `published = 1`, so a
+module comes out of the trash **PUBLISHED** whatever it was before. Joomla
+keeps no pre-trash state for modules either (`#__modules` has one state column
+and the trash writes `-2` over it), but here the single reachable value is the
+VISIBLE one — an unpublished module you trash and bring back is live on the
+site. Its counterpart `{active:false}` is not a second way out: a trashed
+module already reads `active:false`, so that call writes nothing and leaves it
+in the trash, reporting only `changed: []`. Coming back unpublished is
+therefore two calls in order — `{active:true}` then `{active:false}` — and the
+tool says so in `restore_state_note` on the trash row, in the delete preview's
+notes, and in the `notes` of the restoring call itself.
+`local_content_read({kind:"modules"})` lists a trashed module unasked, marked
+`publish_state:"trashed"`.
+
 ## Workflow 1: Build a hero section
 
 **Goal:** Add a fresh hero section (heading + sub-heading + CTA button)
@@ -681,34 +978,124 @@ to an existing page.
    named a specific page, match on `label` (exact then fuzzy).
 3. `yootheme_builder_get_etag()`: fetch the current top-level
    optimistic-lock ETag. Every write tool requires it via `etag`.
-4. `yootheme_builder_element_add({ template_id: "<id>", parent_path: "", element_type: "section", props: { style: "primary" }, etag: "<etag>" })`:
-   append a new section at the template root (`parent_path: ""`). The
-   section background is set with `style` (enum: `default` / `muted` /
-   `primary` / `secondary`) — there is NO `background` key (it hard-rejects
-   as an unknown prop). Always call `element_type_get_schema("section")`
-   first to confirm the real prop keys.
-   Returns `{ rel_path: "/children/0/children/N", etag: "<fresh>" }`.
-5. `yootheme_builder_element_add({ template_id, parent_path: "<section-path>", element_type: "row", etag: "<fresh-etag>" })`:
-   add a row inside the section. Use the etag returned by the
-   previous write (etags rotate every mutation).
-6. `yootheme_builder_element_add({ template_id, parent_path: "<row-path>", element_type: "headline", props: { content: "<h1 text>", title_style: "h1" }, etag })`:
-   add a headline. `title_style: "h1"` uses the semantic type scale (the
-   tasteful default). See "Typography & heading styles" below before
-   reaching for a `heading-*` display size.
-7. `yootheme_builder_element_add({ template_id, parent_path: "<row-path>", element_type: "text", props: { content: "<sub text>" }, etag })`:
-   add a text element.
-8. `yootheme_builder_element_add({ template_id, parent_path: "<row-path>", element_type: "button", etag })`
+   **Chaining writes: every write answers with `etag` AND `new_etag`, and both
+   carry the value read AFTER that write.** They are interchangeable; pass
+   either into the next write. You only need `get_etag` again after a 412, or
+   when you did not just write.
+4. `yootheme_builder_scaffold_section({ layout_id: "<id>", columns: 1, etag: "<etag>" })`:
+   build a VALID `section → row → column` hull at the template root in ONE
+   atomic call — the correct way to start a layout block. Only `section` may
+   sit at the layout root; a bare section accepts only `row`; a bare row
+   accepts only `column`; content/leaf elements (headline, text, button, …)
+   are rejected anywhere except inside a `column`. `columns: 1` (the
+   default) is a single full-width column — the shape a hero needs.
+   Returns `{ section_path: "/children/0/children/N", row_path: "…/children/0",
+   column_paths: ["…/children/0/children/0"], etag: "<fresh>" }`. Drop every
+   content element below into `column_paths[0]`.
+5. (Optional) `yootheme_builder_element_update_settings({ layout_id, element_path: "<section-path>", props: { style: "primary" }, etag: "<fresh-etag>" })`:
+   `scaffold_section` does not take section `props`, so set the background
+   as a follow-up call when the hero needs one. `style` (enum: `default` /
+   `muted` / `primary` / `secondary`) — there is NO `background` key. Writing
+   one is ACCEPTED and stored; the answer names it under `warnings` with
+   `code: "unknown_prop_keys"`, and nothing renders. Always call
+   `element_type_get_schema("section")` first to confirm the real prop keys.
+6. `yootheme_builder_element_add({ layout_id, parent_path: "<column-path>", element_type: "headline", props: { content: "<h1 text>", title_style: "h1" }, etag })`:
+   add a headline INSIDE the column `scaffold_section` returned
+   (`column_paths[0]`) — never directly in the row or the section. `title_style:
+   "h1"` uses the semantic type scale (the tasteful default). See "Typography
+   & heading styles" below before reaching for a `heading-*` display size.
+7. `yootheme_builder_element_add({ layout_id, parent_path: "<column-path>", element_type: "text", props: { content: "<sub text>" }, etag })`:
+   add a text element into the SAME column.
+8. `yootheme_builder_element_add({ layout_id, parent_path: "<column-path>", element_type: "button", etag })`
    then add a `button_item` CHILD for the actual label/link/style:
-   `yootheme_builder_element_add({ template_id, parent_path: "<button-path>", element_type: "button_item", props: { content: "<cta>", link: "<url>", button_style: "primary" }, etag })`.
+   `yootheme_builder_element_add({ layout_id, parent_path: "<button-path>", element_type: "button_item", props: { content: "<cta>", link: "<url>", button_style: "primary" }, etag })`.
    The `button` element is a CONTAINER — its label, link and style live on
    a `button_item` child, NOT on the button's own props. Adding a lone
    `button` with `{content, link}` renders an empty button. (Same
    container→item pattern as `grid`→`grid_item`, `list`→`list_item`.)
-9. `yootheme_builder_page_save({ template_id, etag })`:
+9. `yootheme_builder_page_save({ layout_id, etag })`:
    persist the working copy (visible in YOOtheme Customizer preview).
    `page_save` is a first-class L1 tool; call it directly.
-10. `yootheme_builder_page_publish({ template_id, etag })`:
+> **`render_preview` cannot see an element whose rendering depends on CMS
+> runtime state.** On Joomla a `module` / `module_position` subtree is EXCLUDED
+> from every render probe, whatever the module's state, and a `newsletter`
+> element is excluded wherever its provider is unconfigured. The response says
+> so with `fallback_used:true` + `dropped_count:N`, and `dropped_count_note`
+> names WHICH types were excluded, why, and that they are still in the saved
+> layout. So an `expect` aimed at such output can never match: a `matched:false`
+> there is **not** evidence that the element fails to render, and
+> `match_conclusive:false` marks exactly that case. A HIT is always conclusive.
+> To check a MODULE, read its placement with
+> `local_content_read({kind:"modules", include_usage:true, verify_on_urls:[...]})`.
+> That read answers for modules only; for any other excluded type it returns
+> nothing, which is why the response points at it only when a module was
+> actually excluded.
+
+10. `yootheme_builder_page_publish({ layout_id, etag })`:
     make the changes live on the front-end. Also a first-class L1 tool.
+    **`published:true` is a statement about the LAYOUT, not about the page.**
+    A WordPress post left in `draft`, or a Joomla article at `state=0` /
+    trashed, or one whose `publish_up` is still in the future, is not served
+    to a visitor afterwards. Read `cms_visibility.findable_by_visitor` before you
+    tell anyone the page is live; `cms_warning` names the exact fix when it is
+    `false`.
+    **For the ordinary case — build it and make it live — pass the CMS status
+    in the same call**: `page_publish({ layout_id, cms_status: "publish" })` on
+    WordPress, `cms_status: "published"` on Joomla, and on Joomla add
+    `menu_item: true` when the article still needs a SEF route. Same words and
+    same refusals as `pages_set_status`; the other platform's word publishes
+    nothing. The response then carries `cms_status_applied` with the STORED
+    status, and `cms_visibility` reflects the new one. Omit `cms_status` and this
+    call changes nothing about who may see the page — that separation stays, it
+    is simply no longer the only way through.
+> **On Joomla, "not findable" and "not reachable" are two different things, and
+> only one of them is a privacy control.** Measured anonymously with curl on
+> 2026-08-04: the STATE decides the 404 (`state` 1 published and 2 archived both
+> answer **200**, `state` 0 unpublished and -2 trashed both answer **404**) and
+> the ACCESS LEVEL decides the 403 (a level a guest does not hold answers **403**
+> at state 1 and at state 2 alike). A missing menu item decides NEITHER: it
+> costs the SEF url, the breadcrumb and the navigation path, while the article
+> keeps answering 200 on its own
+> `?option=com_content&view=article&id=N` url for anyone. So `findable_by_visitor:
+> false` on a published article usually means "no visitor will FIND it", not
+> "no visitor can OPEN it". Two consequences worth saying out loud: **archiving
+> does not hide anything** (it is a 200), and if an article must not be public,
+> set its state with `yootheme_builder_pages_set_status` or give it an access
+> level a guest does not hold. Never leave the menu item off and call that
+> private.
+
+    **The `cms_visibility` block carries the facts, so you do not have to infer
+    them.** It rides on `page_publish`, `page_generate_dynamic` and `pages_set_status`.
+    Read the field that answers YOUR question:
+
+    | field | question it answers | platform |
+    |---|---|---|
+    | `findable_by_visitor` | will a visitor FIND this via a navigation path? (NOT the same as reaching it: an unrouted article still answers on its direct URL) | both |
+    | `status_permits_direct_url` | does the stored state ALONE serve the item's own direct URL? | both |
+    | `state_and_access_permit_direct_url` | state AND access level together: is it served? | Joomla |
+    | `access_is_guest_visible` | does an anonymous visitor hold this access level? | Joomla, when the probe ran |
+    | `article_access` / `post_status` / `article_state` | the raw stored values | per platform |
+    | `publish_up_in_future` | is it scheduled? | both |
+    | `has_route` | does a menu item route it? (WordPress: always equals published) | both |
+
+    > **One row of that table is NOT in the block, and it is the one people
+    > confuse it with:**
+    >
+    > | field | question it answers | where it rides |
+    > |---|---|---|
+    > | `visibility` | do the STORED FIELDS rule this page out for a visitor? | every `pages_list` row |
+    >
+    > `visibility` reads the CMS status plus, on WordPress, password
+    > protection. It never reads the menu route or the access level, so on
+    > Joomla it answers `undetermined` where `findable_by_visitor` gives a verdict.
+    > That is not a contradiction: the per-page field looked at two levers the
+    > listing never touched, so when they seem to disagree, believe the
+    > per-page one.
+
+    On WordPress the first three necessarily agree: a published page resolves at
+    its permalink and there is no separate route step. On Joomla they come
+    apart, and that divergence is the whole reason the extra fields exist. A
+    `null` in any of them means the input was not readable, never "no".
 
 > **Building a whole page? Prefer ONE atomic `page_save` over ~30 incremental
 > writes.** The step-by-step `element_add` sequence above is clearest for
@@ -717,8 +1104,8 @@ to an existing page.
 > (especially when other agents edit the same site — the builder ETag is a
 > single shared option). For a full page, assemble the complete
 > `{type:"layout",children:[...]}` tree in memory and persist it in ONE call:
-> `yootheme_builder_page_save({ template_id, layout: <full-tree> })` (ETag
-> optional → last-write-wins, scoped to this page). `dry_run:true` preflights
+> `yootheme_builder_page_save({ layout_id, layout: <full-tree> })` (ETag is
+> required — read it via `yootheme_builder_get_etag` first). `dry_run:true` preflights
 > it first. A fast, robust pattern: `scaffold_section` one block, read it
 > back to learn the exact node shape, then build the rest of the tree from
 > that shape and `page_save` it whole.
@@ -726,16 +1113,35 @@ to an existing page.
 **Common pitfalls:**
 
 - **Wrong parameter names.** Every tool uses snake_case. Use
-  `template_id` (not `pageId`), `parent_path` (not `parentPath`),
+  `layout_id` (not `pageId`), `parent_path` (not `parentPath`),
   `element_type` (not `type`), `props` (not `settings`), `etag`
   (not `ifMatch`). The MCP server rejects unknown keys with a
   Zod-validation error.
 - **Forgetting `etag`.** Every write tool needs the latest etag. The
   shared schema marks it required (min length 1). On `412 Precondition
-  Failed` re-fetch via `yootheme_builder_get_etag` and retry.
-- **Adding non-row elements directly to a section.** Sections expect a
-  row in between. The server returns a structured error with a
-  human-readable hint when you skip the row.
+  Failed`, RE-READ the element or page you were writing before you retry.
+  A fresh etag from `yootheme_builder_get_etag` makes the retry succeed,
+  but the etag is site-wide and its hash does not cover per-page layouts,
+  so a 412 cannot tell you whether the write that bumped it was on YOUR
+  page. Retrying on a fresh etag alone overwrites whatever landed.
+- **Adding content elements directly to a section or a row.** A section
+  accepts only `row`; a row accepts only `column`; headline/text/button and
+  every other content element are rejected anywhere except inside a
+  `column` — a `422 layout_invalid_hierarchy`. Use `scaffold_section` to
+  build the whole `section → row → column` hull in one call and drop content
+  into the returned `column_paths`; don't hand-build a section + row and add
+  content straight into the row. The server returns a structured error with a
+  human-readable hint when you skip a level.
+- **Adding a child to a leaf, or hitting an empty element registry.** A leaf
+  type — one that never accepts ANY child, e.g. `text`, `headline`, `button`
+  — refuses every child with `422 layout_leaf_has_children`, a distinct code
+  from the mismatch above. Separately, if YOOtheme's element registry answers
+  empty on the site (usually a transient boot-order state, not a fault in
+  your layout), the parent/child check cannot run at all and the write is
+  refused with `422 registry_unavailable` rather than guessed through —
+  section, row, column and the sublayout are decided without the registry
+  and keep working meanwhile. Both leave the tree untouched; for
+  `registry_unavailable`, give the site a moment and retry.
 - **Saving without publishing.** `page_save` is the equivalent of the
   YOOtheme Customizer "Save" button. Content lives in the staging
   copy. Visitors see nothing until `page_publish`.
@@ -751,19 +1157,27 @@ to an existing page.
 **Worked example (tool-call snippet):**
 
 ```jsonc
-// Step 4. Add the section. parent_path: "" means template root.
-yootheme_builder_element_add({
-  template_id: "home",
-  parent_path: "",
-  element_type: "section",
-  props: { style: "primary" },   // section background = `style`, NOT `background`
+// Step 4. Build the section → row → column hull in ONE call.
+yootheme_builder_scaffold_section({
+  layout_id: "home",
+  columns: 1,
   etag: "abc123"   // from yootheme_builder_get_etag
 })
-// Response: { rel_path: "/children/0/children/3", etag: "def456" }
-// → next call uses etag "def456"
+// Response: { section_path: "/children/0/children/3", row_path: "/children/0/children/3/children/0",
+//   column_paths: ["/children/0/children/3/children/0/children/0"], etag: "def456" }
+// → content goes into column_paths[0]; next call uses etag "def456"
+
+// Step 5 (optional). Set the section background — `style`, NOT `background`.
+yootheme_builder_element_update_settings({
+  layout_id: "home",
+  element_path: "/children/0/children/3",   // the section_path above
+  props: { style: "primary" },
+  etag: "def456"
+})
+// Response: { rel_path: "/children/0/children/3", etag: "ghi789" }
 
 // Step 9. page_save is a first-class L1 tool; call it directly.
-yootheme_builder_page_save({ template_id: "home", etag: "<latest>" })
+yootheme_builder_page_save({ layout_id: "home", etag: "<latest>" })
 ```
 
 **Edge case:** YOOtheme allows nested sections (rare). If the user
@@ -774,7 +1188,7 @@ section sits inside another section.
 **Success criterion:** After `page_publish`, navigating to the page
 URL on the front-end shows the new hero section above the previous
 content. Re-reading the layout via
-`yootheme_builder_page_get_layout({ template_id })` shows the new
+`yootheme_builder_page_get_layout({ layout_id })` shows the new
 section as the last child of the template root.
 
 ---
@@ -848,23 +1262,23 @@ inspection that writes nothing.
 // 1. INSPECT (writes nothing — dry_run defaults true, no etag needed).
 //    Returns the current state, the theme-declared --uk-inverse, risk_class,
 //    confidence, a recommendation and would_change/changes.
-yootheme_builder_header_transparency_set({ template_id: "home" })
+yootheme_builder_header_transparency_set({ layout_id: "home" })
 
 // 2. REPAIR with the theme's own declared colour.
 yootheme_builder_header_transparency_set({
-  template_id: "home", mode: "auto", dry_run: false, etag: "<latest>"
+  layout_id: "home", mode: "auto", dry_run: false, etag: "<latest>"
 })
 
 // 3. Turn it ON deliberately, without asserting a colour.
 //    mode "auto" derives it; over a hero medium it writes NO colour and tells
 //    you to look at the page instead.
 yootheme_builder_header_transparency_set({
-  template_id: "home", mode: "auto", transparent: true, dry_run: false, etag: "<latest>"
+  layout_id: "home", mode: "auto", transparent: true, dry_run: false, etag: "<latest>"
 })
 
 // 4. A colour you MEASURED over a hero medium (only mode "explicit" takes one).
 yootheme_builder_header_transparency_set({
-  template_id: "home", mode: "explicit", text_color: "light",
+  layout_id: "home", mode: "explicit", text_color: "light",
   dry_run: false, etag: "<latest>"
 })
 ```
@@ -993,16 +1407,16 @@ never by narrowing the column. Narrowing a single column WITHOUT a matching
 **Easiest correct way — `scaffold_section` builds the whole factory-shaped
 hull for you (row grid string + per-column responsive widths in one call):**
 
-- `scaffold_section({ template_id, columns: 3, etag })` → a section whose row
+- `scaffold_section({ layout_id, columns: 3, etag })` → a section whose row
   carries `layout: "1-3,1-3,1-3"` and whose 3 columns each carry
   `width_default: "1-1"` + `width_medium: "1-3"` → clean, gap-free, side-by-side
   from ≥960px. `columns: N` distributes equal widths (`1-N` for N ≤ 6,
   `expand` for N > 6).
 - For an ASYMMETRIC row pass explicit tokens, one per column:
-  `scaffold_section({ template_id, columns: 2, column_widths: ["2-3", "1-3"], etag })`
+  `scaffold_section({ layout_id, columns: 2, column_widths: ["2-3", "1-3"], etag })`
   → a row with `layout: "2-3,1-3"` and the matching column widths. A
   wrong-length array or a bad token returns a friendly `400` before the write.
-- `scaffold_section({ template_id, columns: 1, etag })` → a single full-width
+- `scaffold_section({ layout_id, columns: 1, etag })` → a single full-width
   column with no `row.layout` and no column width (the factory single-column
   shape).
 
@@ -1010,7 +1424,20 @@ hull for you (row grid string + per-column responsive widths in one call):**
 into them with `element_add({ parent_path: "<column-path>", ... })`. If you
 build columns by hand with `element_add` instead, remember to set BOTH
 `row.props.layout` (the grid string) AND each column's `width_default` /
-`width_medium`, or the row reads as "Whole" and shows gaps in the builder.
+`width_medium`, or the row reads as "Whole" and shows gaps in the builder:
+
+```jsonc
+// Hand-built alternative to scaffold_section — set the grid string on the row…
+yootheme_builder_element_add({
+  layout_id, parent_path: "<section-path>", element_type: "row",
+  props: { layout: "1-3,1-3,1-3" }, etag,
+})
+// …and the matching responsive width on EACH column.
+yootheme_builder_element_add({
+  layout_id, parent_path: "<row-path>", element_type: "column",
+  props: { width_default: "1-1", width_medium: "1-3" }, etag,
+})
+```
 
 **Success criterion:** in the builder's left panel the row shows N distinct
 columns (not one column + an empty gap), and after publish the columns sit
@@ -1121,7 +1548,7 @@ token rotates (re-login, session timeout, a different tab), the preview
 renders as a plain page without the builder-data injection and the panel
 reports "not available". **Fix: reload the Customizer tab** (or re-open the
 builder from Pages → the page → Builder). The stored layout is intact —
-confirm with `page_get_layout({ template_id })`, which reads it directly
+confirm with `page_get_layout({ layout_id })`, which reads it directly
 and is unaffected by the browser session.
 
 ---
@@ -1167,6 +1594,116 @@ schema's own claims: a report to check, not a fact about your build.
 | `slideshow` nav (not `thumbnav`) | Borrows the **slide's `title`** as the link text (`slideshow/templates/template-nav.php`: `$thumbnail ?: $child->props['title']`). An untitled slide gets an empty nav link. |
 | `accordion_item` | Declares **no `title_element`** at all (`grep -c title_element` = 0 in both `accordion_item/element.php` and `accordion/element.php`), so accordion titles can never carry a heading tag and never enter the heading outline. Do not try to write one. |
 
+## Placing a module or widget
+
+A module or widget can reach a page in three ways, and they are not
+interchangeable: they differ in how many pages the thing shows up on, in how
+many edits one change costs, and in what happens on a page nobody has thought
+about yet. `modules_create` therefore REQUIRES a `placement` argument and
+refuses a call without one as `placement_not_chosen`, answering with exactly
+the rows below for the platform in question, plus that platform's notes.
+
+The three ways are the same on both platforms. What differs is the vocabulary,
+and one behaviour: Joomla can narrow a site-wide placement to chosen pages,
+WordPress cannot.
+
+**Joomla** (module, template position):
+
+| `placement` | Reach | What it does |
+| --- | --- | --- |
+| `position` | every page | The module sits in a template position such as top and appears on EVERY page. Pass the position with this call. No layout edit, and one module serves the whole site. To narrow it to chosen pages, set the menu assignment with modules_update. |
+| `module_element` | one page | A Module element inside a column of ONE page layout embeds this module, and it appears on that page only. Call scaffold_section first for a valid column path. |
+| `position_element` | one page | The module goes into one of the positions builder-1 to builder-6. On its own it appears NOWHERE. A Position element placed in a page layout is what renders it, and it then appears on that page only. |
+
+Two notes travel with that answer:
+
+- modules_create builds two native module types (mod_custom, mod_menu). A
+  builder module (mod_yootheme_builder) must already exist. Once it does, all
+  three placements work for it exactly as they do for a native module.
+- You may not need a module at all: a YOOtheme element such as alert placed
+  straight into a page layout does the same job, at the cost of a separate copy
+  per page.
+
+**WordPress** (widget, widget area):
+
+| `placement` | Reach | What it does |
+| --- | --- | --- |
+| `position` | every page | The widget sits in a widget area and appears on EVERY page. Pass the area with this call. No layout edit, and one widget serves the whole site. WordPress has no built-in per-page control, so narrowing it to chosen pages needs a plugin. |
+| `module_element` | one page | A Widget element inside a column of ONE page layout embeds this widget, and it appears on that page only. Needs a position: builder-1 to builder-6, the areas that render nothing on their own. Call scaffold_section first for a valid column path. |
+| `position_element` | one page | The widget goes into one of the areas builder-1 to builder-6. On its own it appears NOWHERE. An Area element placed in a page layout is what renders it, and it then appears on that page only. |
+
+And its two notes:
+
+- modules_create builds three native widget types (custom_html, text, block). A
+  builder widget must already exist. Once it does, all three placements work
+  for it exactly as they do for a native widget.
+- You may not need a widget at all: a YOOtheme element such as alert placed
+  straight into a page layout does the same job, at the cost of a separate copy
+  per page.
+
+Which ways need a `position` argument is a PLATFORM fact since 2026-08-08. On
+JOOMLA it is two of the three: a real theme position (top, bottom, navbar) for
+`position`, one of builder-1 to builder-6 for `position_element`, and
+`module_element` takes none, because a module with no position is a native state
+there. On WORDPRESS it is ALL THREE — a widget exists only inside a registered
+area, so there is no positionless widget to create, and `module_element` takes
+builder-1 to builder-6. A real theme position under `module_element` stays
+refused on both, because the module would ALSO show site wide and render twice
+on that page. Every way that needs one is REQUIRED, never defaulted: omit it and
+the call creates NOTHING and comes back `placement_needs_a_position`. A position you DO name is checked against what
+this site declares or registers, and the two ways it can be wrong are answered
+by two different codes: a value this site has never heard of (or one too long
+to be a position at all) comes back as `placement_position_unknown`, and a
+value that is real but describes a different outcome than the way you chose
+comes back as `placement_position_conflict`. Each names which half of the call
+was meant, instead of guessing.
+
+Two things the layout itself will not let you do: a module or module_position
+element belongs inside a `column`, never on the layout root (the root takes
+`section` only, and a root-level module renders outside the section flow, over
+the navigation on a transparent header), and a `module_position` element renders
+with YOOtheme's own default layout (`stack`) when you leave the `layout` prop
+out. Set it only if you want `grid`. Never copy the `sidebar` value the element
+schema reports as that field's default: it is not one of the two accepted values
+and is rejected with a 422.
+
+**"Every page" above is the assignment a `position` placement makes. On
+Joomla it takes effect immediately: every module write evicts Joomla's own
+module-list cache exactly like the native module manager does. On WordPress
+the widget write goes through `update_option()`, which refreshes WordPress'
+own options cache the same way any core option save does - if the site runs
+a persistent object-cache drop-in, this server behaves exactly as WordPress
+itself does there, no better and no worse. If a write looks invisible
+anyway, you are almost certainly looking at one of two things. (1) On
+Joomla, the site caches aggressively and the module was written by an OLDER
+plugin version or by a tool that bypasses the module manager - Joomla's
+conservative cache then serves the pre-write module list for up to `cachetime`
+(15 minutes by default), while the database row is already correct. Clearing
+the site cache or waiting resolves it; nothing is wrong with the module. (2)
+The position is one of the `builder-N` slots, which never render standalone -
+they reach a page only through a Position/Area element. For a quick
+confirmation either way, call `local_content_read` with `include_usage:true`
+and `verify_on_urls:["<a page url>"]` and read `usage.observed.urls[].status`
+(`present`/`absent`/`not_detectable`/`error` - see T1.7 in the local-content
+chapter), or fetch the page as a guest and search for the module's own
+signature (`id="<widget-id>"` on WordPress, `id="module-<id>"` on Joomla).
+
+**Before doing N per-page edits, check whether one site-wide module already
+covers the need.** If a site-wide Builder module already sits in the header
+area, adding the new content to that ONE module can replace a separate edit
+on every page. A `local_content_read({kind:"modules"})` pass (T1.6 shows
+what `usage` returns) tells you what is already there before you start a
+per-page loop.
+
+**A module or widget placed BOTH in its position and as an element on the same
+page renders twice.** This is not a hypothetical: the T1.7 section of the
+local-content chapter documents it measured live on
+`dev5wp.wootsup.com/mcp-module-probe/`, where a widget carrying both an element
+reference and a position reference served its content twice on one document.
+Before adding a `module`/`module_position` element for something that is ALSO
+assigned a rendering position, check its `usage.element_refs` first (T1.6), or
+drop the position assignment.
+
 ---
 
 ## Workflow 2: Bind a dynamic source to a grid
@@ -1179,30 +1716,30 @@ renders dynamic items.
 
 1. `yootheme_builder_health`: confirm host plugin reachable.
 2. `yootheme_builder_pages_list({ fields: ["id", "label"] })` and
-   `yootheme_builder_page_get_layout({ template_id: "<id>", flat: false })`:
+   `yootheme_builder_page_get_layout({ layout_id: "<id>", flat: false })`:
    locate the target Grid. Note its JSON-Pointer `path` (e.g.
    `/children/0/children/2/children/0`).
-3. `yootheme_builder_element_get({ template_id, element_path })`:
+3. `yootheme_builder_element_get({ layout_id, element_path })`:
    fetch the Grid's current props so you can preserve them. Binding
    sets `props.source` and leaves the rest alone.
 4. `yootheme_builder_sources_list()`: enumerate available Sources.
    Each returns `{ name, label, origin, kind }`. Pick the one the
    user asked for.
-5. `yootheme_builder_element_get_binding({ template_id, element_path })`
+5. `yootheme_builder_element_get_binding({ layout_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 a first-class L1 tool (B4) — call it directly.
 6. `yootheme_builder_get_etag()`: fetch the optimistic-lock etag for
    the upcoming mutation.
-7. `yootheme_builder_element_bind_source({ template_id, element_path, source_name: "<name>", etag: "<etag>" })`
+7. `yootheme_builder_element_bind_source({ layout_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). 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>" })`.
+8. `yootheme_builder_page_save({ layout_id, etag: "<fresh>" })`
+   then `yootheme_builder_page_publish({ layout_id, etag: "<fresh>" })`.
 
 **Common pitfalls:**
 
@@ -1212,9 +1749,27 @@ renders dynamic items.
   `relation`/`field`, `arguments` and `directives`; see the Tool Catalog
   appendix for the full `element_bind_source` input-key list rather than
   guessing a subset.
-- **Wrong parameter names.** Use `template_id` (not `pageId`),
+- **Wrong parameter names.** Use `layout_id` (not `pageId`),
   `element_path` (not `path`), `source_name` (not `sourceName`),
   `etag` (not `ifMatch`).
+- **A misspelled `field_mappings` KEY is refused, and be glad it is.** The keys
+  are element PROPS; the values are source FIELDS. A key that is not a prop of
+  the target element is rejected with `422 unknown_prop_keys`, listing
+  `valid_prop_keys` and `did_you_mean`, and nothing is written. The reason is
+  the ASYMMETRY, and the honest form of it is two measurements that disagree:
+  on a native `articles` source, `{title, content}` rendered 10 rows while
+  `{titel, content}` rendered **0** — the untouched `content` included; on a
+  `grid_item` at an API-Mapper list source, the same substitution left all 5
+  rows standing and cost only that slot. So a misspelled key sometimes empties
+  the WHOLE binding and sometimes only its own slot, `element_get_binding`
+  reads either back as healthy, and which one you get is not established. A
+  wrong refusal costs you one call and tells you the valid names; a wrong
+  acceptance can cost the page in silence. If you genuinely need a prop this
+  build does not declare, `element_set_source` writes the carriers verbatim and
+  only warns.
+  (This is the opposite of the free `props` path — see Workflow 5, where an
+  undeclared key is stored with a warning, because there real layouts carry
+  such props and refusing them would refuse YOOtheme's own work.)
 - **Source not in the list.** API Mapper sources only appear once
   they're PUBLISHED in API Mapper (not just saved). If you bind an
   unknown `source_name`, `element_bind_source` rejects it and the error
@@ -1229,8 +1784,9 @@ renders dynamic items.
   Switcher, Table) accept a source binding. Binding a single-item
   element like Headline returns a structured `validation` error.
 - **Forgetting `etag`.** Every write requires the optimistic-lock
-  etag. On `412 Precondition Failed` re-fetch via
-  `yootheme_builder_get_etag` and retry.
+  etag. On `412 Precondition Failed`, re-read what you were writing
+  first — a fresh etag alone makes the retry succeed without telling you
+  whether someone else's change is what you are about to overwrite.
 - **Mis-routing bind vs the read helpers.** `element_bind_source` AND
   its verify sibling `element_get_binding` (B4) are both first-class L1
   tools — call them directly by name. Only `element_unbind_source` stays
@@ -1243,7 +1799,7 @@ renders dynamic items.
 // 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",
+  layout_id: "home",
   element_path: "/children/0/children/2/children/0",
   source_name: "wp_posts",
   etag: "abc123"
@@ -1252,16 +1808,55 @@ yootheme_builder_element_bind_source({
 // Response: { rel_path: "/children/0/children/2/children/0", etag: "def456", has_binding: true }
 // Verify (direct L1 call):
 yootheme_builder_element_get_binding({
-  template_id: "home", element_path: "/children/0/children/2/children/0"
+  layout_id: "home", element_path: "/children/0/children/2/children/0"
 })
 // → { source_name: "wp_posts", source_config: { ... }, ... }
 ```
 
-**Edge case:** A Source can render zero items at runtime (e.g. empty
-search filter). The bind call still succeeds; the front-end Grid just
-shows the YOOtheme "no items" placeholder. Don't treat empty render
-as a binding failure. Verify by re-reading
-`yootheme_builder_element_get_binding` directly.
+**Edge case:** A Source can render zero items at runtime (e.g. an empty
+search filter, or an archive source on a single page that has no term to
+scope to). The bind call still succeeds; the front-end Grid just shows the
+YOOtheme "no items" placeholder. That is a DATA state, not a broken binding.
+
+**But do not verify it by re-reading the binding.** `element_get_binding`
+answers "is a source attached", which is a different question from "does it
+deliver rows", and no amount of re-reading it will ever turn into the second
+answer. A customer once bound, published, looked, re-bound with `limit`,
+published, looked again, and only then ran `render_preview` — two full cycles
+for one fact.
+
+There is ONE thing the re-read does now answer, and it is the one a blank card
+sends you looking for: if a `field_mappings` VALUE names a source field the
+source does not emit, `element_get_binding` says so — the same three keys the
+bind answers with, under the same names: `unknown_source_field_values`,
+`unknown_source_field_values_available` (what you should have written) and
+`unknown_source_field_values_hint`. That warning used to appear exactly once, at the
+moment of writing, so whoever debugged a blank card LATER read the state back
+and saw a binding indistinguishable from a healthy one. Absence of the keys
+means "nothing to report OR the source's field set could not be resolved here",
+never "checked and fine" — and it says nothing about the KEY side: a misspelled
+element prop is still read back as healthy, which is why the bind refuses it up
+front instead.
+
+What the tools give you instead:
+
+- Every bind answers with a `checks` block: `source_exists`, `field_mappings`,
+  `field_mapping_props_checked`, `container_item_ok`. It costs nothing and is
+  always there. It also states its own limit — none of them says whether rows
+  arrive. Read the pair `field_mappings` + `field_mapping_props_checked`
+  together: the first is a COUNT, not a verdict (a customer read
+  `field_mappings: 2` as confirmation while one of the two was a typo), the
+  second says whether those keys were measured against the element's declared
+  props at all — `false` means the type's field list did not resolve here, not
+  that a check failed.
+- `element_bind_source({… , probe: true})` renders the binding and answers
+  `probe: {rows, rendered, empty, probed_path}`; at zero rows it adds a warning
+  naming the likely causes. It costs a real render (~0.3-0.6s), so it is off by
+  default. `probed_path` is the node that was rendered — the nearest container,
+  because a `grid_item` renders nothing outside its `grid`.
+- `page_publish` / `page_save` report `binding-renders-nothing` in `quick_check`
+  when the page's render produced zero rows and something on it was supposed to
+  iterate. That one is free: the publish already renders for its own precheck.
 
 **Success criterion:** After publish, the Grid on the front-end shows
 items from the Source (verify by item count and at least one
@@ -1322,44 +1917,50 @@ a row layout. (Cross-template duplication is **not** supported by
 `element_clone`. See "Important scope note" below.)
 
 **Important scope note:** `yootheme_builder_element_clone` is
-**sibling-only and intra-template**. Its real schema is
-`{ template_id, element_path, etag }`. There is **no** `destPageId`
-or `destParentPath`. The cloned element lands at the same parent,
-right after the source. To move the clone elsewhere in the SAME
-template, call `yootheme_builder_element_move` afterwards. To
-duplicate into a DIFFERENT template, flag to the user that
-cross-template clone is not currently supported and suggest a
-CMS-level template duplication (in wp-admin or Joomla administrator).
+**intra-template**. Its real schema is
+`{ layout_id, element_path, etag, to_parent_path?, to_index? }`.
+There is **no** `destPageId` and no cross-template argument. Omit
+`to_parent_path` and the copy lands at the same parent, right after
+the source; pass it and the copy lands under that parent instead
+(`to_index` picks the slot, default append) — the follow-up
+`element_move` this used to require is no longer needed. To duplicate
+into a DIFFERENT template, flag to the user that cross-template clone
+is not currently supported and suggest a CMS-level template
+duplication (in wp-admin or Joomla administrator).
 
 **Canonical tool-call sequence (real parameter names, snake_case):**
 
 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", 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.
+3. `yootheme_builder_element_list({ layout_id })`
+   returns a flat view (lighter than `page_get_layout`) showing every
+   element path + type + label + binding. Pick the JSON-Pointer path of the
+   section to clone. `element_list` is L1; call it directly, no gateway.
 4. `yootheme_builder_get_etag()`: fetch the optimistic-lock etag.
-5. `yootheme_builder_element_clone({ template_id, element_path: "<src-path>", etag: "<etag>" })`
+5. `yootheme_builder_element_clone({ layout_id, element_path: "<src-path>", etag: "<etag>" })`
    clones as sibling. Returns `{ path: "<new-path>", etag: "<fresh>" }`.
    The new path is at the same parent, immediately after the source.
-6. (Optional) `yootheme_builder_element_move({ template_id, element_path: "<new-path>", to_parent_path: "<other-parent>", to_index: 0, etag: "<fresh>" })`
-   re-parents the clone within the same template if needed.
-7. `yootheme_builder_element_update_settings({ template_id, element_path: "<final-path>", props: { ... }, etag: "<fresh>" })`
+6. (Optional) To land the copy somewhere other than beside its source,
+   pass the destination to step 5 directly:
+   `yootheme_builder_element_clone({ layout_id, element_path: "<src-path>", to_parent_path: "<other-parent>", to_index: 0, etag: "<etag>" })`.
+   `yootheme_builder_element_move` remains the way to relocate an
+   element that already exists.
+7. `yootheme_builder_element_update_settings({ layout_id, element_path: "<final-path>", props: { ... }, etag: "<fresh>" })`
    replaces the `props` on the clone. **Existing props NOT in the
    request are removed** (update_settings is a full replace by default;
    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_page_save({ template_id, etag })`
-   then `yootheme_builder_page_publish({ template_id, etag })`.
+8. `yootheme_builder_page_save({ layout_id, etag })`
+   then `yootheme_builder_page_publish({ layout_id, etag })`.
 
 **Common pitfalls:**
 
 - **Inventing destination parameters.** `element_clone` does NOT
-  accept `destPageId`, `destParentPath`, or any cross-template
-  argument. It's sibling-only within ONE template.
+  accept `destPageId` or any cross-template argument. Its destination
+  is optional and stays within ONE template: `to_parent_path` plus
+  `to_index`, both snake_case.
 - **Treating `element_update_settings` as a merge by default.** The handler
   REPLACES the entire `props` object on the element unless you pass
   `merge: true`. Read the existing shape via `yootheme_builder_element_get`
@@ -1370,16 +1971,422 @@ CMS-level template duplication (in wp-admin or Joomla administrator).
   at roughly 200 characters with a visible `…(+N chars)` marker when
   truncated, never a silent drop. There's no need to cross-check via
   `element_list` just to see what a specific prop is currently set to.
+- **A `module`/`module_position` element is not a dead end either (T1.4).**
+  On its own, a WordPress Widget or Joomla Module element's `props` are just
+  a reference (`{widget: "custom_html-1"}` / `{module: 42}`) — no title, no
+  content, no settings. `element_get` on that node ALSO carries a `resolved`
+  field: the referenced widget/module's own row (title/type/settings/
+  theme_overlay — the SAME shape `local_content_read(kind:"modules")`
+  returns), or `resolved: null` plus a `resolved_reason` string when it can't
+  be resolved (missing reference, deleted id, empty position) — never a
+  throw. A `module_position` node resolves to `{position, modules: [...]}`,
+  every widget assigned there. There's no need to separately call
+  `local_content_read` just to see what a module element actually shows.
+- **"Where does this widget/module appear?" — `include_usage:true` (T1.6).**
+  `local_content_read({ kind: "modules", include_usage: true })` adds a `usage`
+  object per row: `element_refs` is the EXACT `{layout_id, path,
+  via:"element"|"position"}` list of every layout location that reaches this
+  widget/module — `via:"element"` is a DIRECT `module` element reference,
+  `via:"position"` is an INDIRECT one (a `module_position` element pointing at
+  this row's own `position`) — so you know whether to edit the element or the
+  position assignment. `declared.position_visibility` classifies the row's
+  `position` into `site-wide` (a theme panel/area — appears wherever that
+  position renders), `never-standalone` (a `builder-1`..`builder-6` position —
+  RENDERS ONLY through a `module_position` element, never on its own — live
+  A/B-proven on Joomla), or `not-on-builder-pages` (`sidebar` — not rendered on
+  Builder pages); null when the row has no position at all.
+  `declared.assigned_pages` is Joomla-only real assignment info (`mode`
+  `all`/`except`/`selected`/`none` resolved to concrete menu-item titles); on
+  WordPress it is the explicit platform fact `{applicable:false, reason:
+  "WordPress widget areas are global — widgets are not assigned to individual
+  pages."}` — never simply absent. `declared` states what the CONFIGURATION
+  claims, not what a visitor actually sees — a visibility plugin (Advanced
+  Module Manager, Widget Context, …) or a time-gated rule can still override
+  it. Default `false`: the layout scan this costs is never paid unasked.
+  **A row with NO `usage` is not automatically a row you did not ask about.**
+  There are THREE states and the key `usage_unavailable` is what separates the
+  last two: neither `usage` nor `usage_unavailable` means `include_usage` was
+  not requested; `usage` present means the enrichment ran; `usage_unavailable`
+  present means it WAS requested and FAILED for that row. The row's primary
+  fields (id, title, position, active, ...) stay fully trustworthy either way:
+  an optional enrichment never deletes the answer it was decorating. Read
+  `usage_unavailable` before concluding "this widget is used nowhere": on such
+  a row nothing at all is known about where it appears.
+- **"What does a GUEST actually get served?" — `verify_on_urls` (T1.7).** Pair
+  it with `include_usage:true` to add `usage.observed.urls[]` per row: fetches
+  each url ONCE, anonymously, and checks whether this row's DOM signature
+  (`id="<widget-id>"` on WordPress, `id="module-<id>"` on Joomla) appears —
+  PLUGIN-AGNOSTIC, since it reads the rendered result, never any plugin's
+  rules, so every visibility mechanism is covered without a line of
+  plugin-specific code. Per url: `present`, `absent`, `not_detectable`, or
+  `error`. `not_detectable` — NOT `absent` — covers FOUR cases, all meaning a
+  missing signature proves nothing. **(1)** A `builder-1`..`builder-6`
+  (`never-standalone`) position with no `via:"position"` reference: such a
+  position renders EXCLUSIVELY through an explicit `module_position`
+  element, so with none swept, YOOtheme's element-bound (DOM-anonymous, no id
+  at all) rendering can't be ruled out. **(2)** The row sits in no position at
+  all (empty `position` — an unplaced WordPress widget, Joomla's "NONE"
+  group): nothing is expected on any url either way, so a missing signature
+  says nothing about it. **(3)** The row is ALSO placed as a `module` ELEMENT
+  **on the template THIS url renders**: that path carries no DOM id either, so
+  even on an otherwise checkable position a not-found signature cannot tell
+  "not rendered" from "rendered anonymously". MEASURED live on
+  `dev5wp.wootsup.com/mcp-module-probe/`: `custom_html-1` has both an
+  `element` and a `position` reference, and one document served its content
+  **twice** while `id="custom_html-1"` appeared **once** — the element-rendered
+  copy is `<div class="uk-panel widget widget_custom_html">`, with no instance
+  attribute at all. The signature is not widened to cover it because the only
+  token there is the widget TYPE class, which occurs 3× on that same page: a
+  wider match would trade a false `absent` for a false `present`.
+  **(4)** Where that element renders **could not be determined** — either the
+  url did not map to a template (`pages_resolve` declines it; a Joomla site
+  root served by a theme template is the common case), or the element sits on
+  a THEME template, which governs many urls and is not enumerated here.
+  **Cases (3) and (4) are decided PER URL, not per row.** An element reference
+  on ANOTHER page cannot render on this url — a per-page layout renders on
+  exactly its own page — so there you get the measured `present`/`absent`
+  instead of a withheld answer. MEASURED on both platforms: `custom_html-1`'s
+  element reference is on `page:2987` while the queried url was the site root
+  (`page:1`), an anonymous fetch found 0 signature hits and 0 content hits, and
+  `absent` is the correct decidable answer. The `reason` on every
+  `not_detectable` names which case applies and, for (3)/(4), which template.
+  Any OTHER
+  position (`site-wide` — a real theme panel like navbar/header/a template's
+  own `bottom`/`top` — or `not-on-builder-pages`) renders
+  DIRECTLY from the theme with no element needed at all, so it's checkable
+  even with completely empty `element_refs` — provided it has no `element`
+  reference either. `error` = no observation was
+  obtained from this url: a network failure, a timeout, a non-2xx, or a url
+  the same-origin guard refused (off-site host, private address, disallowed
+  scheme) — never treated as `absent`, never a throw. An `absent` result on a
+  row `declared` calls unconditionally
+  visible (`builder_visible:true`) adds a `discrepancy` — a named SUSPICION
+  (a visibility plugin, a time-gated rule, a stale cache), never phrased as a
+  diagnosis, and never attached to `not_detectable`/`error`.
+  **Redirects are followed by this tool, bounded, and REPORTED.** When a url
+  ends somewhere else, its entry carries `final_url` — the page whose markup
+  was actually searched. That changes what the result means: `/contact` → 301
+  → `/kontakt` scans the KONTAKT page, so a module assigned to `/contact`'s
+  own menu item is not expected in it, and the `discrepancy` then LEADS with
+  the measured redirect instead of naming a visibility plugin. Re-check with
+  the `final_url` before suspecting anything else. Every hop is re-checked
+  against the same-origin guard, so a redirect off-site is refused with its
+  own reason rather than silently fetched. Momentary
+  snapshot per url, a sample (max 10 urls) — never a full crawl. Omit
+  (default): zero requests, `observed` stays absent.
+- **"What's on THIS page from widgets/modules?" — `include_modules` (T1.8), the
+  reverse of T1.6/T1.7.** Where `local_content_read`'s `usage` answers "for
+  this ONE module, which pages?", `include_modules:true` on
+  `yootheme_builder_page_get_layout` (→ `modules_on_page`) and
+  `yootheme_builder_pages_audit` (→ `modules_by_page[layout_id]`) answers
+  "for THIS page, which modules?" — the SAME D11 index, read backwards, never
+  a second scan. Each result splits `from_elements` (a `module`/
+  `module_position` element placed DIRECTLY in this page's own layout) from
+  `from_positions` (a `site-wide` theme position — navbar/header/footer —
+  rendering here with NO element in this page's layout at all). On Joomla, a
+  `site-wide` module can still be assignment-EXCLUDED from one specific page
+  (`except`); when that decision can't be resolved for this page (no menu
+  item addresses it, or more than one does), the row lands in
+  `from_positions_undecidable` instead of being guessed in or out. Default
+  `false`: the layout sweep this costs is never paid unasked, and the
+  response is byte-identical without it.
+- **A short list is never silently a FAILED list — two presence-only keys say
+  so.** `unresolved_positions` appears when a `module_position` element on
+  that page could not be resolved (a database error, unavailable widget
+  APIs), and `unresolved_module_universe` appears when the site's module
+  store could not be read AT ALL — which makes `from_positions` unknowable
+  rather than empty. Both are emitted ONLY on failure, so a healthy answer
+  omits them and is byte-identical to before. If you see either, the answer
+  is INCOMPLETE: do not conclude "this page has no modules", and above all do
+  not create a replacement module to "fix" it.
+- **The same rule for reading, one level up: an empty `local_content_read` is
+  never a failed one.** A read that did not run to completion answers
+  `error_code: local_content_unavailable` (HTTP 503), never a 200 with
+  `{items:[], total:0}` — so an empty-and-OK response can only mean the site
+  genuinely has none of that kind. The landscape tool
+  (`local_content_types`) is the deliberate exception: it is a composite of
+  independent sub-reads, so instead of failing the whole call it keeps the
+  parts it could read and lists the rest under `degraded` — every count named
+  there is a placeholder, not a measurement.
+- **"Now change what you found" — `modules_update` (W2), the write
+  counterpart of `local_content_read(kind:"modules")` / `include_modules`.**
+  Updates a widget's (WordPress) or module's (Joomla) SAFE writable subset —
+  `title`, `position`, `active`, `theme_overlay` on BOTH platforms; `showtitle`,
+  `ordering`, `access`, `assignment` on JOOMLA ONLY (WordPress rejects those
+  four with a 400). `settings`/`params`/`content` are NOT in the schema at all
+  — content editing stays the CMS editor's job; this tool is the
+  display/placement layer.
+  `dry_run` DEFAULTS true: a bare call inspects and writes NOTHING, returning
+  the `{before, after, changed, notes, after_read_back}` diff of what a real
+  write WOULD do.
+  Every field you do NOT pass stays byte-identical — proven at the SQL/option-write
+  level, not merely "looks unchanged".
+  **A real write REPORTS WHAT IT READ BACK, not what you asked for.** After
+  committing, the Joomla arm re-reads the stored record and fills `after` and
+  `changed` from that read. So a field that did not land is reported at its
+  STORED value, with a `notes` entry naming the divergence — never echoed back
+  as if it had succeeded. This is the ONE way a dry run's answer and a real
+  write's answer can differ, and it is deliberate: measured on Joomla,
+  `modules_update({showtitle:false, ordering:3})` once answered
+  `after.showtitle:false` about a row that held `3`. If the verification read
+  itself fails, the write still stands and `notes` says the answer is
+  unverified rather than pretending it was checked. That holds per FIELD, not
+  only for the whole row: `assignment` is read back from a second table, and
+  when THAT read fails the requested assignment is kept and named unverified,
+  never replaced by the `none` an unread table looks like.
+  **`after_read_back` tells a MEASURED `changed` entry from a merely REQUESTED
+  one.** It lists exactly the keys whose `after` came out of storage. A key
+  named in `changed` but ABSENT from `after_read_back` is a transition this
+  call asked for and did not measure — the write committed, so `changed` keeps
+  naming it, but check it before treating it as landed. Measured on Joomla with
+  the `#__modules_menu` read-back failing after a committed write:
+  `changed: ["title","ordering","assignment"]` with
+  `after_read_back: ["title","ordering"]`. Before this field existed those three
+  were indistinguishable, and the only qualification was a `notes` sentence.
+  A DIVERGING read still counts as read back: this list answers "did we look?",
+  never "did we like what we saw?". It is `[]` for every dry run (nothing was
+  written, so nothing could be read back) and always `[]` on WordPress — a
+  plain statement, never a failure signal.
+  **On WORDPRESS there is no read-back, and `after` is what you REQUESTED.**
+  Not an oversight: a widget's instance is one serialised `wp_options` value,
+  so the per-field storage divergence the Joomla read-back exists to catch
+  cannot arise, and the failure that CAN arise, the write not reaching storage,
+  is raised as an ERROR rather than shown as a diverging `after`. So on
+  WordPress do not read `after` as "checked against storage"; read it as "this
+  is what was asked, and it did not fail".
+  **Every value is TYPE-CHECKED, never coerced.** Send real JSON types: the
+  string `"false"` is NOT the boolean `false` (PHP reads a non-empty string as
+  TRUE, so a coerced `"false"` would have PUBLISHED the module), `"7abc"` is
+  not the integer `7`, and an object is not a `title`. A wrong type is
+  REFUSED with a 400 naming the expected one — this tool never rewrites a
+  value it did not understand.
+  **`notes` is the channel for "correctly did nothing, and that is not the
+  end of it".** It is a list of plain sentences, usually empty. The case that
+  motivated it: a Joomla module with `published = 1` whose `publish_up` is in
+  the FUTURE reads `active:false`, so `{active:false}` is a genuine no-op with
+  `changed: []` — and the module still goes live on schedule. `notes` says so
+  instead of letting an empty `changed` read as "already handled".
+  **Read `notes` whenever it is NON-EMPTY — an empty `changed` is not the
+  trigger.** This used to say "read it whenever `changed` comes back empty",
+  and that sent readers past the note that matters most: the one saying a field
+  in a NON-empty `changed` was never read back. A note is attached exactly when
+  something needs saying, so its presence is the signal.
+  **One consequence is REPORTED in `notes`, not refused: the module will render
+  TWICE.** If a Module/Widget element already embeds this module and you move it
+  to a position that renders it on its own — a real theme position or widget
+  area, not `builder-1`..`builder-6` — it appears once through each element and
+  once through the position. `modules_create` refuses that same combination up
+  front (`placement_position_conflict`); this verb has no `placement` argument
+  to refuse it with, and both CMSs allow the move in their own UI, so blocking
+  it here would be this tool inventing a restriction. The note names the
+  elements and both ways back to one appearance. It rides on a `dry_run` too,
+  which is where it is worth most.
+  **`position_verified: false` reports on a check that did NOT happen, and it
+  means here exactly what it means on `modules_create`.** Both verbs ask the
+  same rule the same question, so the same site answers the same way: when the
+  site's position list could not be read from there AND the name is not one of
+  `builder-1` to `builder-6` (those are taken by name and need no list), the
+  position is WRITTEN and the answer carries this field. The move happened; the
+  check behind "an unknown position is refused BY NAME" did not, so a typo is
+  still a typo. The field is ABSENT in the two cases with nothing to report —
+  the value WAS vouched for, or this call wrote no position at all — so read
+  `after.position` to tell those apart. A `dry_run` never carries it, and
+  neither does an update that names no position: it reports on a position THIS
+  call wrote, never on the one the module already had.
+  On WordPress, `position` must be a REGISTERED widget area
+  (`$wp_registered_sidebars` — on a YOOtheme site that is the 13 theme
+  positions plus `builder-1`..`builder-6`); WordPress core does NOT validate
+  this itself, so a typo used to park the widget in a phantom area that
+  renders nowhere while the response reported success. `theme_overlay` MERGES onto the stored overlay: a
+  key you OMIT keeps its current value; only the keys you explicitly include
+  are written (so calling `theme_overlay:{style:"card-alt"}` never resets
+  `visibility` or any other already-set key). The overlay's key list is
+  PLATFORM-SPECIFIC — WordPress `_theme` (17 keys, incl. `showtitle`) vs.
+  Joomla `params.yoo_config` (18 keys, incl. `language_parent_icon`/
+  `language_icon` INSTEAD of `showtitle`) — an unknown or wrong-platform key
+  (or a wrong value type) is REJECTED with a 400 naming every allowed key,
+  never silently dropped, never coerced. Two further writes are REFUSED
+  outright rather than half-kept, because the stored state cannot be
+  expressed by the field you sent: a `title` on a WordPress `block` widget
+  (that type has NO title — its instance is `{content}` only, WordPress never
+  renders one, and storing it would additionally SUPPRESS the preview title
+  derived from the block markup), and an `active:true` on a Joomla module
+  whose publish window would still leave it `scheduled`/`expired`. On Joomla
+  `active` means the `published` column AND the `publish_up`/`publish_down`
+  window — the SAME derivation `local_content_read` uses — so a module
+  scheduled for the future already reads `active:false`, and "deactivating"
+  it is correctly a no-op instead of silently cancelling the schedule — with
+  a `notes` entry so the no-op is not mistaken for "already handled".
+  `access` (Joomla only) is the module's VIEW LEVEL, not a flag: Joomla
+  filters modules by `access IN (authorised view levels)`, and `access:0` is
+  in NOBODY's set — not even a Super User's — so such a module renders for no
+  one while looking published. That is what `local_content_read` reports as
+  `builder_visible:false`; `modules_update({access: 1})` is the repair.
+  `access:0` itself is refused, because 0 is the very state being repaired.
+  Advanced/gateway-only.
+- **"Build one from scratch" — `modules_create` (W3), then `element_add` —
+  the two-step recipe.** `modules_create` supports exactly FIVE known types:
+  WordPress `custom_html` (title+content), `text` (title+text), `block`
+  (content only, NO title); Joomla `mod_custom` (title+content COLUMN+
+  showtitle), `mod_menu` (title + the params keys menutype/base/startLevel/
+  endLevel/showAllChildren/tag_id/class_sfx/window_open/layout/
+  moduleclass_sfx/cache/cache_time/cachemode). An unknown type is rejected
+  with this exact list. `placement` is REQUIRED (`position`/`module_element`/
+  `position_element`, i.e. how the module reaches a page); a call that omits it
+  creates NOTHING and instead returns `ways`, every way for this platform with
+  its reach and a summary, plus `notes`. `content`/`text` are stored
+  byte-for-byte, same no-sanitization guarantee as `modules_update`.
+  **`position` is ONE argument with ONE meaning on both platforms**: the
+  template position or widget area the module goes into, validated SERVER-side
+  against the positions this site declares or registers, because the set of
+  areas is a property of the SITE and no schema here can know it. **Joomla
+  takes it AT CREATE TIME**, exactly as WordPress does; it stopped being a
+  `modules_update`-only concern on 2026-08-06. The value must agree with
+  `placement` or the call is refused BY NAME rather than guessed:
+  `placement_needs_a_position` for `placement:"position"` OR
+  `placement:"position_element"` with no position (both ways need one and they
+  need different values, so neither is defaulted),
+  `placement_position_conflict` for a `builder-N` position under
+  `placement:"position"` (a builder position renders nothing on its own), for a
+  REAL theme position under `placement:"module_element"` (measured on both
+  platforms: the module then renders TWICE on that page), or for a non-builder
+  position under `placement:"position_element"`; and
+  `placement_position_unknown` for a value this site does not declare at all,
+  or that could not be a position at all because it is longer than 50
+  characters. That 50 is the width of the JOOMLA column that stores a position;
+  WordPress keeps widget areas as option keys with no width of their own, and
+  the bound is enforced on both platforms anyway, because `position` is one
+  argument with one meaning and the narrower platform is what bounds it. That
+  last one is answered by the SAME
+  rule on both platforms, and when the site's list could be read the refusal
+  carries it as `declared_positions` as well as naming it in the message.
+  Under `placement:"module_element"` a Joomla module is created with no position
+  and assigned to ALL pages, so it is immediately visible to `element_add`. On
+  WordPress the same placement REQUIRES a builder area since 2026-08-08: a
+  widget exists only inside a registered area, and this tool asks which one
+  instead of picking `builder-1` for you.
+  **A `position` is not by itself a rendering.** `builder-1`..`builder-6` is
+  classified `never-standalone` on BOTH platforms (that is what
+  `local_content_read(include_usage:true)` reports back), so a `builder-N`
+  position means "it now has a home", not "it now shows up". The
+  live A/B that proved a `builder-N` module produces zero frontend output was
+  measured on Joomla; on WordPress the classifier reports the same value and
+  the same rule is what `next_step` assumes. Either way, step 2 (`element_add`)
+  is what actually puts it on a page. Do not read a freshly created row as
+  visible until an element references it.
+  **`builder_visible` can come back as the STRING `unknown_until_next_request`
+  on a real WordPress create.** WordPress builds `$wp_registered_widgets` once
+  per request, so the widget this very call just wrote is not in it yet: the
+  honest answer is neither `true` nor `false`. It is a timing artefact of the
+  same request, not a fault and not a warning. Read the row again (any later
+  request, e.g. `local_content_read({kind:"modules"})`) to get the real
+  boolean, and never branch on it as if it were `false`.
+  `dry_run` DEFAULTS true, same discipline as `modules_update`: once
+  `placement` is chosen, a bare call previews `{type, position, fields}` and
+  creates nothing. A REAL create
+  (`dry_run:false`) returns the full created `row` (the SAME
+  `local_content_read(kind:'modules')` D2 shape) PLUS `next_step` — the
+  EXACT follow-up call **for the placement you chose**, one shape per choice:
+  | `placement` | `next_step` |
+  |---|---|
+  | `module_element` | `element_add{element_type:"module", props:{widget:"custom_html-3"}}` on WordPress, `props:{module:"122"}` on Joomla |
+  | `position_element` | `element_add{element_type:"module_position", props:{content:"builder-1"}}` |
+  | `position` | Joomla: `modules_update{id, assignment}` to narrow it to chosen pages. WordPress: `local_content_read{kind:"modules", include_usage:true}` — read-only, because WordPress has no per-page control to narrow it with; add `verify_on_urls` to PROVE guest-visible rendering rather than trust `active`/`builder_visible` alone |
+  **Two live-measured details, both baked into `next_step` so you never have
+  to remember them:**
+  1. **Joomla's `props.module` is a STRING** (`"122"`), never a bare
+     integer — a mismatch here silently fails to resolve, it does not error.
+  2. **A `module_position` element names the POSITION, not one module** — it
+     renders every published entry sitting there. That element accepts an
+     optional `layout` prop from its own enum (`stack`/`grid`) — leaving it
+     out is safe and defaults to `stack`; set it only if you want `grid`.
+     `next_step` therefore leaves the key out. Never copy the `sidebar` value
+     the element schema reports as that field's default: it is not one of the
+     two accepted values and is rejected with a 422. This does NOT apply to
+     the `module` form.
+  Copy `next_step` verbatim, add `layout_id` + `etag` + `parent_path` when it
+  is an `element_add` (that tool REQUIRES `layout_id` and `etag`, and unlike
+  the fourteen tools that take an `element_path` it names its parent argument
+  `parent_path`), then make the call. A `null` here is an answer, not a gap:
+  the widget is already live site wide and nothing further is needed.
+  **One more field the answer can carry, and it is the only one that reports on
+  something that did NOT happen: `position_verified: false`.** It appears when a
+  position was STORED that the server could not vouch for — the site's position
+  list was not readable from there AND the name is not one of `builder-1` to
+  `builder-6`, which are taken by name and need no list. The write happened; the
+  check behind this tool's "an unknown position is refused BY NAME" promise did
+  not, so the value is in place unexamined and a typo is still a typo. The field
+  is ABSENT in the two cases where there is nothing to report — the stored
+  position WAS vouched for, or no position was stored at all — so absence alone
+  does not mean "checked". Read `preview.position` to tell those two apart: it
+  is empty only in the second. A `dry_run` never carries the field, so a preview
+  cannot warn you that the position it shows will be stored unverified.
+  **The answer also names what will render the module before you asked for
+  it: `element_refs`.** Each entry is `{layout_id, path, via}` and there are
+  exactly two ways to get one. `via: "element"` means a `module` element in
+  some layout ALREADY names the id this call just took — WordPress reuses a
+  deleted widget's number (the allocator is highest-instance-plus-one), so a
+  new widget can inherit a reference nobody meant for it. `via: "position"`
+  means a `module_position` element already renders the position you created
+  into; that needs no reuse at all, happens on both platforms, and is the
+  common one. The field is ALWAYS present, so `[]` is the answer "nothing
+  renders it yet" rather than a build without the concept. A `dry_run` carries
+  it too, and that is where it is worth most, since `dry_run` defaults to true
+  and is the first call you make. On JOOMLA a `dry_run` can report only
+  `via: "position"`: the module id is assigned by the database at insert time,
+  so on a preview there is no id for a layout to reference. That is a plain
+  statement about that arm, not a failure.
+  **One asymmetry to know about that resolution step:** on the plugin's own MCP
+  transport a large answer is trimmed to a response budget, top-level keys are
+  dropped largest first, and `preview` is one of the large ones while this flag
+  is the smallest. So a widget with several KB of content can hand you
+  `position_verified: false` and no `preview` to resolve it with. Every dropped
+  key is named in `omitted_keys`, so check there before reading an absent
+  `preview` as "no position was stored". (The `retry_hint` that comes with a
+  trimmed answer suggests raising `max_chars`; `modules_create` has no such
+  argument, so that hint does not apply here.)
+  Advanced/gateway-only.
+- **The fifteen typed failures of `modules_update` / `modules_create` /
+  `modules_delete`, and what each one licenses you to do next.** These are their
+  OWN family, separate from the `pages_audit`/`heading_outline` target-error
+  table above. Three of
+  the four `placement_*` codes belong to `modules_create` alone. The fourth,
+  `placement_position_unknown`, is also what `modules_update` answers for a
+  position this site does not declare, so that one mistake reads the same
+  whichever verb you sent it with. All four are the ones a caller meets first,
+  because they are decided before anything is written:
+
+  | `error_code` | HTTP | What it means | What to do |
+  | --- | --- | --- | --- |
+  | `modules.placement_not_chosen` | 400 | `modules_create` only. `placement` was missing or not one of `position` / `module_element` / `position_element`. Nothing was created, not even a preview: the check runs before `dry_run` is honoured. | The error carries BOTH halves of the answer, `ways` and `notes`. Read them, pick a way, resend with `placement` set. |
+  | `modules.placement_needs_a_position` | 400 | `modules_create` only. The way you chose needs a `position` and the call carried none. WHICH ways need one is a platform fact since 2026-08-08: all three on WordPress, where a widget exists only inside a registered area, and two on Joomla, where a module with no position is a native state. They take different values, and none is defaulted. | Resend the SAME `placement` with `position` set. Switching placement to get past this builds something other than what you asked for. |
+  | `modules.placement_position_unknown` | 400 | `modules_create` AND `modules_update`, the one code of this family both verbs send. The `position` named is not one this site declares, or could not be a position at all (longer than 50 characters, the width of the Joomla column that stores it; the bound is enforced on BOTH platforms so one argument keeps one meaning). The SAME code on both platforms and on both verbs. What DIFFERS is the offer inside the message, and with it the advice: `modules_update` has no `placement` argument, so its message names the positions this site declares plus `builder-1` to `builder-6` and its runtime `hint` says exactly that. The advice cell to the right is the `modules_create` one. | The MESSAGE already names the values this call can use, narrowed to the placement you chose, so take the next value from there: `placement: "position"` takes a template position this site declares that is at most 50 characters long, `placement: "position_element"` takes `builder-1` to `builder-6` and nothing else, and `placement: "module_element"` takes no template position at all and only `builder-1` to `builder-6` if you name one. `declared_positions` rides alongside as the raw fact of everything this site declares, which is more than any one placement takes: it can even hold a value no call accepts, because a site may declare a position wider than the column that stores it. So when the two differ the message is the shorter, safer list. A value taken from `declared_positions` under the wrong placement is refused again as `placement_position_conflict`. When the error carries no list, the site's list could not be read and the value has to come from the template itself. |
+  | `modules.placement_position_conflict` | 400 | `modules_create` only. `position` and `placement` are each fine alone and describe DIFFERENT outcomes together: a `builder-N` under `placement:"position"`, a real theme position under `placement:"module_element"`, a non-builder position under `placement:"position_element"`. | Change one of the two and resend. The message names the combination and the call that does what you asked for. |
+  | `modules.invalid_field` | 400 | A field is unknown, unwritable (`settings`/`params`/`content`), wrong-platform, or the wrong JSON TYPE. The message names the allowed keys or the expected type. | Fix the call. Nothing was written; the module is untouched. |
+  | `modules.field_value_invalid` | 400 | The KEY is right and the VALUE is not: a wrong JSON type (the string `"false"` is not the boolean `false`), a value outside a closed set (an unknown widget/module type, an unrecognised `assignment.mode`), or outside a permitted range (`menu_ids` must be positive). The largest of these classes. | Correct the VALUE of the named key and resend. Renaming the key will not help: the key is already right. The message names the expected type or the allowed values. |
+  | `modules.field_not_on_this_type` | 400 | The field name is fine and this tool can write it, but THIS widget/module type has no such field. Nothing to rename. | The message names the types that DO carry it, and where this type keeps the equivalent instead (block markup, `theme_overlay`, or the type-specific params). Pick another type, or put the value where this type keeps it. |
+  | `modules.field_combination_invalid` | 400 | Every field is valid ALONE; together they contradict each other, or one needs a partner the call did not carry. | Change the COMBINATION, not a value: add the missing field or drop one of the pair. The message names which of the two it is and in which direction. |
+  | `modules.position_not_clearable` | 400 | **WordPress only.** You sent `position: ""` to take the widget out of every area, and on WordPress a widget exists only while it sits in one. Joomla accepts the same value, because a module there can genuinely sit in none. So this is about the platform, not about the value being malformed. | Send `active: false` instead: it parks the widget in `wp_inactive_widgets`, and naming a position again brings it back. Nothing was written. |
+  | `modules.blocked_by_cms_state` | 409 | Name, value and combination are all correct. The CMS is in a state that would make the outcome untrue anyway, and this tool deliberately does not write the columns that would change it. | Nothing to fix in the call. The message names the exact field and value standing in the way; change it in the CMS module manager and repeat the call. |
+  | `modules.invalid_id` | 400 | Joomla only, and only for the id-addressed verbs: `moduleId` was not a positive integer. WordPress has no counterpart, because its widget ids are strings such as `custom_html-2`. | Read the id off `local_content_read({kind:"modules"})` rather than constructing it. |
+  | `modules.not_found` | 404 | The store WAS read and this id is genuinely not in it. | The module really is gone. Creating a replacement is legitimate here. |
+  | `modules.element_refs_present` | 409 | `modules_delete` only. The request is fine; the STATE is not. Layout elements still reference this module directly, and the message names each one. | Delete those elements with `element_delete`, or repeat with `acknowledge_element_refs: true` to accept the dangling references. Nothing was removed. |
+  | `modules.write_failed` | 500 | A write was ATTEMPTED and did not land. Every writing verb on both platforms answers this way: the create that stored nothing, the update whose change never reached the column, the delete that removed nothing. Reporting success would have been a positive false statement about the state of the store. | Re-read the module before retrying: the message names what did and did not reach storage. On Joomla the whole call shares one transaction, so it is all or nothing; on WordPress the widget instance and its placement are separate writes, so the message may report a half-applied call. |
+  | `modules.unavailable` | 503 | The widget/module store could not be reached AT ALL. | **Never create a replacement.** Absence of an answer is not absence of the module. Retry later, or tell the user the store is down. |
+
+  The 404-vs-503 split is the load-bearing one: before it existed, an
+  unreachable store answered 404 and an agent dutifully created a duplicate
+  for a module that was there the whole time.
 - **Clone-then-update path drift.** The clone returns a path that's
   correct at the moment of the call. If you fire off many ops in
   parallel, a concurrent edit may shift indices. Refresh via
-  `get_etag` + `page_get_schema` (via gateway) between independent batches.
+  `get_etag` + `element_list` between independent batches.
 - **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", arguments: { ... } })`
   on the new path afterwards.
-- **Wrong parameter names.** Use `template_id`, `element_path`,
+- **Wrong parameter names.** Use `layout_id`, `element_path`,
   `etag` (NOT `pageId`, `srcPath`, `ifMatch`).
 
 **Worked example (tool-call snippet):**
@@ -1387,7 +2394,7 @@ CMS-level template duplication (in wp-admin or Joomla administrator).
 ```jsonc
 // Step 5. Clone the section element as a sibling.
 yootheme_builder_element_clone({
-  template_id: "home",
+  layout_id: "home",
   element_path: "/children/0/children/2",   // the hero section to duplicate
   etag: "abc123"
 })
@@ -1395,11 +2402,11 @@ yootheme_builder_element_clone({
 
 // Step 7. Tweak the clone (replace props entirely, or pass merge: true).
 const current = yootheme_builder_element_get({
-  template_id: "home",
+  layout_id: "home",
   element_path: "/children/0/children/3",
 });
 yootheme_builder_element_update_settings({
-  template_id: "home",
+  layout_id: "home",
   element_path: "/children/0/children/3",
   props: { ...current.props, style: "secondary" },   // section background = `style`
   etag: "def456"
@@ -1413,7 +2420,7 @@ copy, follow up with
 on the new path. Verify with a direct `element_get_binding` call.
 
 **Success criterion:** After publish,
-`yootheme_builder_advanced({ tool: "yootheme_builder_page_get_schema", arguments: { template_id } })`
+`yootheme_builder_element_list({ layout_id })`
 shows the new section at the cloned path with the user's tweaks reflected in
 `element_get` on that path.
 
@@ -1426,34 +2433,91 @@ guessing, and without rotating the user's key unnecessarily.
 
 **Canonical tool-call sequence:**
 
-1. `yootheme_builder_diagnose` is a single probe that hits `/health` (no
-   auth) and then `/etag` (Bearer auth). Returns
-   `{ plugin_reachable, plugin_version, yootheme_loaded, yootheme_version,
-   endpoint_count, bearer_valid, bearer_error?, site_url?, home_url?,
-   summary?, capability_ok?, capability_warning?, effective_capabilities? }`.
-   Call this **before** any other tool when you see
-   auth errors. (Takes no arguments. The schema is `{}`.)
+1. `yootheme_builder_diagnose` is a single self-diagnostic. Returns
+   `{ platform, plugin_version, site_url, kid, scopes, token_scope,
+   served_areas, capabilities, auth_bound, etag_ok, resolved_user_id,
+   effective_capabilities, capability_ok, capability_warning, library_key,
+   active_site }`. EVERY field is optional: one is absent when the host does
+   not report it. Call this **before** any other tool when you see auth
+   errors. (Takes no arguments beyond the optional `site_id`.)
+
+   `served_areas` and `effective_capabilities` name similar-sounding, DIFFERENT
+   things: `served_areas` lists the tool AREAS this server serves (`pages`,
+   `elements`, `sources`, `inspection`) — a server property, the same list
+   `yootheme_builder_health` carries under the same name. `effective_capabilities`
+   is what THIS caller's resolved CMS user may actually do
+   (`can_create`/`can_edit`/`can_delete`) — see the bullet below. `capabilities`
+   is `served_areas`' RETIRING name, kept one release as a byte-identical alias.
+
+   This list used to be longer, and the extra names never arrived — measured on
+   four live installs. `plugin_error`, `yootheme_loaded`, `yootheme_version`,
+   `endpoint_count`, `bearer_valid`, `bearer_error`, `summary` and `home_url`
+   belonged to an older transport that assembled this report from two HTTP
+   probes; today the plugin answers it in-process. For install facts (YOOtheme
+   version, endpoint list, `home_url`) call `yootheme_builder_health`, which
+   does carry them. For the bearer verdicts, read `auth_bound` and `etag_ok`
+   right here — they are the successors of `bearer_valid` / `bearer_error`.
+
+   The two verdicts to read first are `auth_bound` (the Bearer key was accepted
+   and resolved to a user) and `etag_ok` (a layout state was readable with it).
+   There is no `plugin_reachable` field, and there is nothing to miss: the
+   diagnostic is assembled by the plugin that received your call, so an answer
+   at all IS the reachability answer. An unreachable plugin produces a
+   transport error, never a payload.
+
+   Four of those are easy to skip past and answer questions you would
+   otherwise take several calls to answer:
+
+   - `token_scope` (`read` / `write`). A `read` key fails every write tool
+     with `read_only_token`, and that is a key problem, not a permissions one.
+   - `effective_capabilities` + `capability_ok` + `capability_warning`. The
+     CMS user the key resolves to, and what that user may actually do. A
+     write-scoped key mapped to a user without edit rights still 403s;
+     `capability_ok: false` is the only field that says so before you try.
+   - `active_site` `{ site_id, via, process_scoped }`. Which site this call
+     actually reached, and by which decision: `explicit` (you passed `site_id`
+     — isolated from other clients of this server process), `use_site` (a
+     runtime switch this process is on) or `registry_default` (the default in
+     the sites file). The two inherited paths are kept apart deliberately: a
+     call that reaches the wrong install answers just as confidently as one
+     that reaches the right one. The field rides on EVERY tool call, not only
+     this one. It replaces `process_default_site_id` + `resolved_via`, which
+     this chapter kept naming after they had stopped shipping.
+   - `site_url`. WHICH install answered, as the plugin reports it. `kid` and
+     `auth_bound` cannot show that a perfectly valid key simply belongs to a
+     different install, and that is the commonest cause of the refusal you are
+     triaging. Read it against `active_site.site_id`, which names the registry
+     entry your own config picked: when those two disagree, the disagreement
+     is the finding.
+   - `library_key`. Why the Layout Library tools can or cannot reach
+     `api.yootheme.com`, as `{ configured, state, hint }`. Read `state`
+     before you tell anyone to check their apikey field: see the Layout
+     Library prerequisite section for the five states and who has to act on
+     each. Never contains the key.
 2. **Interpret the result:**
-   - `plugin_reachable: false` → the WordPress / Joomla install is down
-     OR the host plugin is deactivated. Send the user to **wp-admin →
-     Plugins → activate "YT Builder MCP"** (WordPress) or **Joomla
-     administrator → Extensions → Plugins → enable "System - YT Builder
-     MCP" and the matching webservices + component entries** (Joomla).
-     Do not retry until they confirm.
-   - `plugin_reachable: true, bearer_valid: false` → the Bearer key is
-     wrong (typo, revoked, or wrong key for this install). The
-     `bearer_error` field carries the upstream HTTP status. Send the
-     user to:
+   - **The call itself failed** (a transport error, not a payload) → the
+     WordPress / Joomla install is down OR the host plugin is deactivated.
+     Send the user to **wp-admin → Plugins → activate "YT Builder MCP"**
+     (WordPress) or **Joomla administrator → Extensions → Plugins → enable
+     "System - YT Builder MCP" and the matching webservices + component
+     entries** (Joomla). Do not retry until they confirm.
+   - `auth_bound: false` → the Bearer key is wrong (typo, revoked, or wrong
+     key for this install). Check `site_url` first: a key that is valid
+     somewhere else fails here for a reason nothing about the key will show.
+     For the upstream HTTP status call `yootheme_builder_sites_test`, which
+     probes `/etag` itself and answers `bearer_valid` + `summary`; diagnose
+     names no status of its own, because the request it is answering already
+     got through. Then send the user to:
      - **WordPress:** wp-admin → Tools → "YT Builder MCP" → Bearer Keys
        → copy the existing key into their MCP client config, or
        generate a new one.
      - **Joomla:** Components → YT Builder MCP → Bearer Keys → same.
-   - `plugin_reachable: true, bearer_valid: true` but the original
+   - `auth_bound: true, etag_ok: true` but the original
      tool returned a 403 → the key works but the scope is too low for
      the tool's required scope (`write` for mutations, `admin` for
      destructive operations). Ask the user to regenerate the key with
      a higher scope and restart the AI client.
-   - `plugin_reachable: true, bearer_valid: true, capability_ok: false` →
+   - `auth_bound: true, capability_ok: false` →
      the Bearer key's scope IS write, but the CMS user it resolves to
      (`effective_capabilities.can_edit`, `can_create`, `can_delete`, all
      false) has no write capability at all, so writes will still 403
@@ -1472,7 +2536,8 @@ guessing, and without rotating the user's key unnecessarily.
    - "Restart Claude / Cursor / Zed / Continue / Cline / Roo Code /
      Claude Code / Codex CLI."
    - "Confirm with `yootheme_builder_diagnose` that
-     `bearer_valid: true` before retrying the original task."
+     `auth_bound: true` and `etag_ok: true` before retrying the original
+     task."
 
 **Common pitfalls:**
 
@@ -1499,29 +2564,33 @@ guessing, and without rotating the user's key unnecessarily.
 yootheme_builder_diagnose({})
 // Response shape:
 // {
-//   plugin_reachable: true,
+//   platform: "wordpress",
 //   plugin_version: "1.2.0",
-//   yootheme_loaded: true,
-//   yootheme_version: "5.0.22",
-//   endpoint_count: 16,
-//   bearer_valid: false,           // ← key is bad
-//   bearer_error: "HTTP 401: invalid_token",
-//   site_url: "https://example.com",
-//   home_url: "https://example.com"
+//   kid: "5cb829a21f4d5e4f",
+//   scopes: ["read", "write"],
+//   token_scope: "write",
+//   auth_bound: false,             // ← key is bad
+//   etag_ok: false,
+//   site_url: "https://example.com",   // ← check this FIRST: right key, wrong install?
+//   active_site: { site_id: "default", via: "registry_default", process_scoped: true }
 // }
 // → diagnosis: rotate the key. Send user to Tools/Components → YT Builder MCP.
+// → for the upstream HTTP status: yootheme_builder_sites_test({ site_id: "default" }).
 ```
 
-**Edge case:** `plugin_reachable: true` but `yootheme_loaded: false`
-means the user installed the MCP host plugin but YOOtheme Pro itself
-isn't active. The MCP server still answers, but every tool that
+**Edge case:** `yootheme_builder_health` answers but reports
+`yootheme_loaded: false` — the user installed the MCP host plugin but YOOtheme
+Pro itself isn't active. Read that off **health**, not diagnose: diagnose used
+to declare the field and never filled it. (Health's WordPress arm reports it;
+the Joomla health answer is assembled before the builder bootstraps and does
+not carry it, so its absence there means "not knowable here", never `false`.) The MCP server still answers, but every tool that
 touches the YOOtheme layout returns an empty/error response. Surface
 the mismatch ("YOOtheme Pro is not active on this install") instead
 of retrying. On Joomla this can also surface as a "YOOtheme Pro
 required" admin notice in the component dashboard.
 
 **Success criterion:** A subsequent `yootheme_builder_diagnose`
-returns `plugin_reachable: true` AND `bearer_valid: true`. The
+returns `auth_bound: true` AND `etag_ok: true`. The
 original tool now returns a non-auth response.
 
 ---
@@ -1546,22 +2615,28 @@ an instance with a sensible default props payload.
    `element_type` (`type_name` is a DEPRECATED alias, kept only for
    1.0.x back-compatibility).
 4. `yootheme_builder_pages_list({ fields: ["id", "label"] })` and
-   `yootheme_builder_page_get_layout({ template_id, flat: false })`
+   `yootheme_builder_page_get_layout({ layout_id, flat: false })`
    locate the `parent_path` (JSON-Pointer) where the new element
-   should land.
+   should land. A content/leaf type is only accepted inside a `column`
+   (never directly in a `section` or a `row`) — if the layout has none yet,
+   call `yootheme_builder_scaffold_section` first and use its
+   `column_paths` as `parent_path` instead of hunting for one by hand.
 5. `yootheme_builder_get_etag()`: fetch the optimistic-lock etag.
-6. `yootheme_builder_element_add({ template_id, parent_path: "<path>", element_type: "<picked-name>", props: { ... }, etag })`
-   validates `props` against the live type schema. On a type with a
-   known schema, an unknown prop key is HARD-REJECTED (not silently
-   dropped): the error always lists `valid_prop_keys`, plus a
-   `did_you_mean` suggestion when a close field exists (e.g. `contnet`
-   to `content`). Read those from the error and retry; do not re-guess.
-7. (Optional) `yootheme_builder_element_update_settings({ template_id, element_path: "<new-path>", props: { ... }, etag })`
+6. `yootheme_builder_element_add({ layout_id, parent_path: "<path>", element_type: "<picked-name>", props: { ... }, etag })`
+   checks `props` against the live type schema. On a type with a known
+   schema, a prop key the type does not declare is ACCEPTED and stored —
+   the answer carries a `warnings` entry with `code: "unknown_prop_keys"`
+   naming the key, plus a `did_you_mean` suggestion when a close field
+   exists (e.g. `contnet` to `content`). Read that and correct; do not
+   re-guess. The VALUE side is stricter: an invalid enum member, an
+   emptied required field, or a `<p>`-wrapped headline `content` is
+   REFUSED with 422 before anything is written.
+7. (Optional) `yootheme_builder_element_update_settings({ layout_id, element_path: "<new-path>", props: { ... }, etag })`
    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_page_save({ template_id, etag })`
-   then `yootheme_builder_page_publish({ template_id, etag })`.
+8. `yootheme_builder_page_save({ layout_id, etag })`
+   then `yootheme_builder_page_publish({ layout_id, etag })`.
 
 **Common pitfalls:**
 
@@ -1570,14 +2645,22 @@ an instance with a sensible default props payload.
   still works as a DEPRECATED alias, but prefer `element_type` to match
   every other tool in this domain. The server's Zod schema rejects any
   other key.
-- **Unknown prop key = hard reject, not a silent drop.** On a type with a
-  known schema, a prop key that is not a real field is REJECTED before the
-  write. The error ALWAYS lists `valid_prop_keys` (your guaranteed anchor),
-  plus a `did_you_mean` suggestion only when a close field exists. The
-  reserved binding keys `source` / `source_extended` / `source_node` are
-  rejected too (bind a source with `yootheme_builder_element_bind_source`,
-  never via `props`). Correct from the error instead of retrying blind.
-- **Wrong parameter names on `element_add`.** Use `template_id`
+- **Unknown prop key = a warning, not a rejection — and not silence
+  either.** On a type with a known schema, a prop key the schema does not
+  declare is STORED and reported: `warnings: [{ code: "unknown_prop_keys",
+  message }]`, with a `did_you_mean` suggestion inside the message when a
+  close field exists. It is a warning rather than a refusal because an
+  undeclared key is not always wrong — YOOtheme itself stores props a type
+  does not declare (a `column`'s `order_first` is written by the ROW control
+  and is read at render), and a layout authored on a newer YOOtheme carries
+  props the installed build has not declared yet. Refusing them would refuse
+  layouts YOOtheme wrote. So: read the warning, and either fix the typo with
+  `unset: ["<key>"]` — valid WITHOUT a `props` body, in which case only those keys go and every other prop stays — or keep the key knowingly. To bind a source, use
+  `yootheme_builder_element_bind_source` rather than writing `source` /
+  `source_extended` through `props` — those carriers are not filtered out of
+  a props write, so a hand-written one silently competes with the bind
+  tool's.
+- **Wrong parameter names on `element_add`.** Use `layout_id`
   (not `pageId`), `parent_path` (not `parentPath`), `element_type`
   (not `type` / `name`), `props` (not `settings`), `etag` (not
   `ifMatch`).
@@ -1619,13 +2702,13 @@ yootheme_builder_element_type_get_schema({ element_type: "headline" })
 // <p> block — see "Typography & heading styles"). If you omit title_element it
 // DEFAULTS to h1, so set it explicitly on every headline to avoid multiple h1s.
 yootheme_builder_element_add({
-  template_id: "home",
-  parent_path: "/children/0/children/2",     // row inside section
+  layout_id: "home",
+  parent_path: "/children/0/children/2/children/0",     // a column inside a row inside a section
   element_type: "headline",
   props: { content: "Welcome", title_element: "h1" },
   etag: "abc123"
 })
-// Response: { rel_path: "/children/0/children/2/children/0", etag: "def456" }
+// Response: { rel_path: "/children/0/children/2/children/0/children/0", etag: "def456" }
 ```
 
 **Edge case:** A child theme can override a built-in element's
@@ -1657,13 +2740,14 @@ exposes. Never analyze findings by hand and never bulk-apply a fix.
    write-approval prompt). Omit `checks`/`types` to run every category
    against every scanned template.
 2. Read the response's `findings` array. Each finding carries a `code`,
-   `category`, `severity`, a `count`, up to 30 affected `pages`, and
+   `category`, `severity`, an `affected_pages` total, up to 30 affected
+   `pages`, and
    (where a safe automatic fix exists) a `fix_hint` naming the exact
    write tool and args template to run. `duplicate-layout` and
    `title-collision` never carry a `fix_hint` — they need a human
    decision (rename, merge, or intentionally keep as-is), not an
    automatic patch.
-3. `yootheme_builder_template_summary({ template_id, include_nodes: true })`
+3. `yootheme_builder_template_summary({ layout_id, include_nodes: true })`
    drills into one page a finding names. It carries the same
    `heading_levels`, `images_missing_alt`, and `disabled_elements` counters
    the audit used, plus (with `include_nodes:true` — opt-in, omit it for
@@ -1673,18 +2757,22 @@ exposes. Never analyze findings by hand and never bulk-apply a fix.
    is disabled or just hidden on mobile, in one call instead of pulling
    the raw `page_get_layout`. Page a large `content_nodes` list with
    `limit`/`cursor`; drill into several findings' pages in ONE call with
-   `template_ids:[...]` instead of `template_id` (returns `summaries` keyed
+   `layout_ids:[...]` instead of `layout_id` (returns `summaries` keyed
    by id + `not_found`). `heading_levels` rides alongside a
    `heading_levels_note` sibling stating exactly which sources feed the
    census: every element whose title/meta channel resolves to a heading
    level, PLUS real `<h1>`-`<h6>` tags found inside `html`/`text`/`code`
    element markup. It does NOT count `module`/widget output — a WordPress
    widget or Joomla module has no content field this counter can parse.
+   Since T1.4 that content is still readable, just not counted here:
+   `yootheme_builder_element_get` on the `module`/`module_position` element
+   resolves its referenced widget/module via a `resolved` field (see
+   Workflow 3) — this counter is unaffected either way.
 4. Fix that ONE page via the write tool named in `fix_hint.tool`, with
    `fix_hint.args_template` as a starting point (`element_update_settings`,
    `element_add`, etc), ETag-locked like every other write in this
    server.
-5. `yootheme_builder_page_publish({ template_id, etag })` republishes.
+5. `yootheme_builder_page_publish({ layout_id, etag })` republishes.
    The response's `quick_check` block (default on) re-checks THIS page
    with the same per-page codes, so you can confirm the fix landed
    without a second full sweep.
@@ -1692,7 +2780,7 @@ exposes. Never analyze findings by hand and never bulk-apply a fix.
 **Disabling instead of editing.** Sometimes the right remediation is to
 exclude an element entirely rather than edit its content (a stray leftover
 section, a duplicate block). `yootheme_builder_element_set_status({
-template_id, element_path, status: false, etag })` writes `props.status:
+layout_id, element_path, status: false, etag })` writes `props.status:
 'disabled'` — the SAME field YOOtheme's own native "Disable element"
 checkbox writes, so the element is excluded from BOTH the live frontend
 render AND the NEXT `pages_audit`/`template_summary` (both read the same
@@ -1703,7 +2791,7 @@ than persisting a fabricated `props.status`.
 
 **Need a real document outline instead of findings?** `pages_audit` tells you
 WHAT is wrong (a missing h1, a skipped level); it never shows you the whole
-heading tree in one look. `yootheme_builder_heading_outline({ template_id })`
+heading tree in one look. `yootheme_builder_heading_outline({ layout_id })`
 (read-only, reached via `yootheme_builder_advanced_read`) is a companion
 STRUCTURE view for ONE page: every H1-H6 heading in true document order, each
 carrying its TEXT and the element that carries it (`element_type`/`path` —
@@ -1712,7 +2800,7 @@ the alt-status of every image on the page (`alt: null` for missing, plus
 `is_generic_alt` for a lazy "Logo"/"Bild"-style alt). Use it BEFORE editing a
 page's heading hierarchy by hand, or to double-check a `heading-skip` finding
 in context rather than as an isolated hit:
-`yootheme_builder_advanced_read({ tool: "yootheme_builder_heading_outline", arguments: { template_id: "page:4816" } })`
+`yootheme_builder_advanced_read({ tool: "yootheme_builder_heading_outline", arguments: { layout_id: "page:4816" } })`
 returns `{outline, images, h1_count, has_level_skip, images_missing_alt}` —
 `has_level_skip` mirrors the `heading-skip` check's EXACT rule (a level more
 than one above the highest seen so far, including a document that opens below
@@ -1726,12 +2814,21 @@ builder node to point at).
 - **Promising a full SEO audit.** `pages_audit` covers Builder structure
   and CMS basics only: heading hierarchy, empty/thin pages, missing
   image alt text, duplicate layouts, title collisions, non-pretty URL
-  fallbacks, stale content, and dead in-page anchors. Every response
-  carries a fixed disclaimer field:
-  `"Meta title/description/OG live in your CMS SEO plugin — not covered here."`
-  It does not read or evaluate Yoast/RankMath/any SEO-plugin meta
-  title, meta description, or Open Graph tags. Say this scope boundary
-  out loud and point the user at their SEO plugin for that layer.
+  fallbacks, stale content, and dead in-page anchors. Every response carries
+  a `disclaimer` field naming what is out of scope, and that field says
+  itself that its list is **not exhaustive** — pass that on rather than
+  presenting it as the complete set of blind spots. It does not read or
+  evaluate Yoast/RankMath/any SEO-plugin meta title, meta description, or
+  Open Graph tags, and it does not see whether the page may be INDEXED at
+  all. Say this scope boundary out loud and point the user at their SEO
+  plugin for that layer.
+- **Answering "we don't show up on Google" from this tool alone.** The first
+  suspect is not a heading level — it is a `noindex`, which `pages_audit` has
+  no check for in any category. Staging sites often carry a site-wide
+  `<meta name="robots" content="noindex, nofollow">`, and until that is lifted
+  every other SEO finding is beside the point. Settle it first:
+  `yootheme_builder_fetch_public_url({ url, expect: "noindex" })` —
+  `expect_found: true` means the page asks search engines to stay away.
 - **Assuming builder props are the only content scanned.** Headings and
   image alt text are also detected inside raw HTML: an `html`/`text`
   element's markup content, not just builder props like
@@ -1748,7 +2845,16 @@ builder node to point at).
   "Module"/"Module Position") are NOT scanned - verified live that neither
   carries a markup-shaped `content` field on either platform; their actual
   content lives in an external WP widget instance / Joomla `#__modules` row,
-  outside the layout JSON entirely.
+  outside the layout JSON entirely. Since W1/T1.8 that content IS readable,
+  just not through THIS scanner: `include_modules:true` on
+  `yootheme_builder_pages_audit`/`yootheme_builder_page_get_layout` lists
+  every widget/module placed on this page (`modules_by_page`/
+  `modules_on_page`), and `yootheme_builder_advanced_read({ tool:
+  "yootheme_builder_local_content_read", arguments: { kind: "modules" } })`
+  returns each one's actual `title`/`settings`/`theme_overlay` plus a
+  `resolved` companion field on `element_get` for one `module`/
+  `module_position` element (see Workflow 3) — this scanner's blind spot is
+  unaffected either way.
 - **`mode:"rendered"` sees what the builder tree structurally cannot** (T-A2,
   2026-07-24) — pass `mode:"rendered"` (default is `"builder"`, the tree read
   above) to instead render each page first (the SAME engine
@@ -1774,9 +2880,39 @@ builder node to point at).
   pipeline, not a JSON walk): the response always carries
   `render_scan: {attempted, rendered, capped}`, even when the cap never
   engaged, so you can always see whether every page was actually rendered.
+  When the cap DID engage, `render_scan.skipped_by_cap` names the templates
+  it skipped (`{id, label}`), so a code found on the scanned subset is never
+  silently generalised to the rest — re-run narrowed with `types:[…]` to
+  reach them. That list is itself bounded at 30 entries and says so with
+  `skipped_by_cap_not_listed` when it had to stop.
   A page whose render failed is excluded from findings (never reported as a
   false "no headings") and listed in `render_errors` instead — check both
-  fields before trusting a clean rendered-mode result.
+  fields before trusting a clean rendered-mode result. Each `render_errors`
+  row carries `error_class` (the throwable's own class), and for an
+  engine-level failure (`TypeError` and friends — a component executed during
+  the render did not get something its own code requires) also a `reason`
+  saying the layout is not the place to look and that the template is
+  UNCHECKED rather than clean.
+- **A Joomla page carrying `module`/`module_position` is NOT a render
+  failure** (render-fallback follow-up, 2026-07-30) — it renders via a
+  tolerant fallback (the module/module-position subtree excluded, everything
+  else rendered normally) rather than falling into `render_errors`, because
+  Joomla's admin/REST context structurally cannot probe those two types (a
+  CMS-runtime gap, not a broken layout). When this happens, the response
+  carries `render_fallback: {pages: [{id, label, dropped_count}], suppressed_checks}`
+  — `dropped_count` is how many module(-position) subtrees were excluded from
+  THAT page's render, and `suppressed_checks` names which of `no-headings`,
+  `missing-h1`, `heading-skip` were skipped on those pages specifically (the
+  only three whose absence-based logic a hidden widget heading could
+  fabricate — every other check, e.g. `multiple-h1`, only ever reports
+  content that DID survive the fallback, so it keeps running). Same idea on
+  `yootheme_builder_heading_outline` in `mode:"rendered"`: the response
+  carries `render_fallback_used` (bool) + `render_dropped_count` (int),
+  always present in that mode — treat `h1_count`/`has_level_skip`/the outline
+  as possibly incomplete when `render_fallback_used` is true (content inside
+  the excluded widget is invisible to the outline too). `WordPress renders
+  these types successfully today, so this never engages there — WordPress
+  pages never carry `render_fallback` / never set `render_fallback_used`.
 - **Confusing the CONTENT count with `pages_list.elements_count`.**
   `pages_list.elements_count` counts every node, including
   `section`/`row`/`column`/`fragment` layout wrappers. `pages_audit`
@@ -1897,7 +3033,7 @@ What changes in the response:
   tool returns `target_not_scannable` (HTTP 422). Tell the user the page could
   not be audited and why; then audit it via `template_summary`, or pick a page
   `pages_list` returns. Never present it as a clean result.
-- **`resolved_target`** — `{ template_id, post_id, type, label, frontend_url,
+- **`resolved_target`** — `{ layout_id, post_id, type, label, frontend_url,
   context, resolved_via, matched_by }`. This is the echo of WHICH page a fuzzy
   address landed on. Always report it: `special: "home"` and
   `title: "SunWest"` are guesses until the server says what they resolved to.
@@ -1907,36 +3043,29 @@ What changes in the response:
 - **Richer per-hit evidence.** Single mode raises the per-page hit cap from 5 to
   **100 hits per check** and adds a `content_snippet` to every locator (the site
   sweep omits snippets to keep a whole-site payload small). The text leg also
-  gains a `Where to fix:` block with the locator lines; the site sweep keeps its
-  compact 5-column summary table, with the locators in `structuredContent` only.
-- **The summary table's count column counts HITS, and says so.** In a site sweep
-  that column is headed `COUNT` and holds the number of affected **pages**. A
-  single-page sweep scanned exactly one page, so that number would be `1` for
-  every finding and tell you nothing — there the column is headed **`HITS`** and
-  holds the number of individual occurrences **on that page** (19 alt-less
-  images ⇒ `19`, not `1`). It is the uncapped total: `hits_truncated` shortens
-  the listed locators, never this figure. Report the `HITS` number as the size
-  of the problem. `structuredContent.findings[].count` is unaffected by the
-  column — it stays the affected-PAGE count in every scope, so read the table
-  (or the page entry's own `hits`) when you want the per-page hit total.
-- **`hits` is the unambiguous field; `count` means two different things.** On
-  this wire `count` is level-dependent: on a FINDING it counts affected **pages**
-  (so it is `1` for every finding of a single-page audit), and on a **page entry**
-  it counts hits on that page. One name, two meanings — and that ambiguity has
-  already produced a live misread, an agent reporting "one image is affected"
-  when nineteen were. So the host emits **`hits`** next to a page entry's `count`
-  whenever that count really is a hit tally: `findings[].pages[].hits`. Prefer it.
-  It is an alias, never an invention — a page entry with no hit total (the PAGE
-  ITSELF is the hit: `thin-content`, `empty-page`, `duplicate-layout`) carries no
-  `hits` key at all, and a host plugin older than the alias sends only `count`.
-  Fall back to `pages[].count` in both cases, never to `findings[].count`.
-- **On the plugin-served transport there is no summary table at all.** The
-  `HITS`/`COUNT` column is rendered by the npm server. When the MCP server is the
-  CMS plugin itself, the response is the JSON payload — so nothing labels the
-  columns for you and the guidance above is the only thing standing between you
-  and the misread. Read `findings[].pages[].hits` (falling back to
-  `pages[].count`) and **never report `findings[].count` as the size of a
-  single-page problem**: in single-target mode it is structurally `1`.
+  keeps the per-hit locators under `findings[].pages[].locators` in both scopes.
+  Both legs of the answer are the same JSON payload — there is no rendered
+  summary table and no `Where to fix:` block on either, in either scope, so
+  nothing labels a column for you and the two counters below are the whole
+  story.
+- **Two counters, two levels, and neither is called `count`.**
+  `findings[].affected_pages` is how many PAGES that finding matched. In
+  single-target mode it is structurally `1` for every finding, so it is never
+  the size of the problem there. `findings[].pages[].occurrences_here` is how
+  many occurrences sit on THAT page — 19 alt-less images ⇒ `19`. It is the
+  uncapped total: `hits_truncated` shortens the listed locators, never this
+  figure. Report `occurrences_here` as the size of a single-page problem, and
+  never `affected_pages` — an agent once reported "one image is affected"
+  where nineteen were.
+- **A page entry with no `occurrences_here` is not a gap.** Some checks make the
+  PAGE ITSELF the hit — `thin-content`, `empty-page`, `duplicate-layout` — and
+  those entries carry no occurrence total at all, because there is nothing on
+  the page to count more than once.
+- **What `occurrences_here` counts, the response says once.** The top-level
+  `occurrences_unit` states it in words: matching ELEMENTS in the saved layout
+  tree, a FLOOR when a bound row repeats or content is conditional, since the
+  saved tree enumerates neither. Pass that caveat on rather than presenting the
+  number as what a visitor's browser renders.
 
 Two request shapes are refused up front, with a typed error rather than a
 round-trip: more than one address key → `too_many_targets` (pick one; use
@@ -2048,6 +3177,87 @@ on the CONTENT count (`elements_content`), so wrapper-only pages — three neste
 columns around nothing — are correctly flagged rather than passing as "not
 empty".
 
+#### `dangling-source` — structure · critical
+
+**Why it matters.** The page is not empty and nothing errored: an element IS
+there, bound to a source name that no longer exists. YOOtheme resolves the
+binding to nothing and renders nothing, so the gap looks identical to a layout
+problem while the cause sits in the source list. Without this finding the only
+way to spot it is to compare every binding on the site against
+`sources_list` by hand.
+**How to fix.** Compare each reported `source_name` against
+`yootheme_builder_sources_list`. Renamed elsewhere → repair the reference with
+`yootheme_builder_repair_source_references({from, to})` (that is the shipped
+`fix_hint`; `to` must be a currently registered name). Genuinely deleted →
+unbind the element instead, or rebuild the binding against a source that
+exists.
+**Severity.** Critical: the element renders nothing at all, and the page ships
+looking finished.
+
+#### `unknown-source-fields` — structure · critical
+
+**Why it matters.** The value-side sibling of `dangling-source`: the bound
+source EXISTS, but one or more `field_mappings` values name a source field the
+source does not emit, so that mapped slot binds to nothing and renders blank.
+Neither `empty-page` (an element IS there) nor `dangling-source` (the source
+name IS known) catches this — it falls through both rasters, and the same
+diagnosis is what `element_get_binding`/`inspect_multi_items_binding` already
+surface for a single element inspected by hand.
+**How to fix.** Compare each reported `unknown_source_field_values` entry
+against the `unknown_source_field_values_available` list that rides alongside
+it, then `element_bind_source` with a corrected `field_mappings` value (that is
+the shipped `fix_hint`).
+**Severity.** Critical: the mapped value renders nothing at all, and — unlike a
+typo'd element prop, which is refused before it writes — this one persists
+silently.
+
+#### `container-missing-item-child` — structure · warning
+
+**Why it matters.** A multi-item container (`grid`, `button`, `slideshow`,
+`accordion`, …) repeats its `*_item` child once per source row. With no such
+child there is nothing to repeat, so the container renders nothing — again with
+no error anywhere. `element_add` already says this at write time; this finding
+catches the states that write never saw, such as the child being deleted later
+or a library insert that dropped it.
+**How to fix.** `element_add` the type named in each locator's
+`expected_child_type` under the reported container path (that is the shipped
+`fix_hint`). Read its required props from `element_type_get_schema`, whose
+`minimal_layout` shows exactly this container-plus-child shape. If the container
+is meant to be bound to a source, bind the CHILD, never the container.
+**Severity.** Warning, not critical: the element genuinely renders nothing, but
+building the shell first and its child second is the order `minimal_layout`
+itself teaches — a page caught mid-build is half-finished, not broken.
+
+#### `binding-renders-nothing` — structure · warning (publish/save only)
+
+**Why it matters.** A bind that persisted is not a bind that delivers. The
+element is there, the source name is valid, the field mappings are in place, the
+save succeeded — and the page renders zero rows. Nothing on that path says so,
+which is why a customer once bound, published, looked, re-bound with `limit`,
+published, looked again, and only then ran `render_preview` and read
+`rendered_item_wrapper_count: 0`. This finding is that sentence, arriving two
+cycles earlier.
+**How to fix.** Each locator names the element AND its `source_name`. Usual
+causes in order: the source needs a context this template does not have (an
+archive source on a single page has no term to scope to — check with
+`source_get_schema` whether it takes a term/id argument), a filter or
+`query_arguments` narrowed it to nothing, or the source genuinely holds no
+entries yet. To check ONE binding as you make it rather than at publish, pass
+`probe: true` to `element_bind_source`.
+**Severity.** Warning: a source with no rows yet is a legitimate state (an empty
+category), and the page is not broken — it is empty where content was expected.
+
+> **Scope, and it is narrower than every other `per-page` code.** This check
+> needs a ROW COUNT, and nothing in this product can produce one without
+> rendering. It therefore reads the render report that `page_save` / `page_publish`
+> has ALREADY computed for its own render-precheck — so it rides `quick_check`
+> and **never appears in `pages_audit`**, not even with `checks: ["structure"]`.
+> Rendering every page of a site to run one check would turn a sweep into
+> minutes. It also stays silent when the render threw (the precheck owns that
+> verdict), when the render used its module fallback (a partial render cannot
+> settle a zero), and when nothing on the page was supposed to iterate at all —
+> a `headline` bound to one field renders content and zero rows by construction.
+
 #### `no-headings` — structure · critical
 
 **Why it matters.** With no heading of any level the page has no machine-readable
@@ -2427,7 +3637,7 @@ The raw response is a machine payload. What you hand the user follows this
 shape every time, so two audits of two sites read the same way:
 
 1. **Lead with the scope.** When `scope: "single"`, name the page the audit
-   actually ran on from `resolved_target` — label, `template_id`, and
+   actually ran on from `resolved_target` — label, `layout_id`, and
    `matched_by` when the address was fuzzy ("`special: "home"` resolved to
    *Startseite* (`page:4816`)"). When the response has no `scope`, it was a site
    sweep: lead with `scanned.templates` and the `summary` totals.
@@ -2475,7 +3685,7 @@ shape every time, so two audits of two sites read the same way:
    first (every field of `alt_paths` / `anchors` / … also rides on the locator
    for the same hit, so nothing is lost), then the locator detail — halved
    before it is dropped — then the remaining raw evidence, then whole evidence
-   pages (`pages_truncated`), so page ids and labels outlive the prose. Both
+   pages (`finding_pages_truncated`), so page ids and labels outlive the prose. Both
    transports shed in exactly that order; it is pinned by a contract test that
    derives the order from each implementation. Say so, and name the two ways
    back: raise `max_chars` (it bounds both legs on this tool), or
@@ -2487,9 +3697,10 @@ shape every time, so two audits of two sites read the same way:
    even for that floor, the plugin-served transport refuses with
    `max_chars_too_small` and tells you the minimum to ask for — it never returns
    a half-written payload.
-8. **Repeat the scope boundary.** Close with the response's `disclaimer` — meta
-   title/description/OG live in the CMS SEO plugin and are not covered here — so
-   nobody mistakes a clean audit for a clean SEO plugin.
+8. **Repeat the scope boundary.** Close with the response's `disclaimer`
+   verbatim, INCLUDING its own statement that the list is not exhaustive, so
+   nobody mistakes a clean audit for a clean SEO setup. On a search-visibility
+   question, check indexability first — see the pitfall above.
 
 Beyond that the prose is yours: group, summarise and prioritise however serves
 the user. Rules 2, 4, 5 and 6 are the parts that must not vary.
@@ -2506,7 +3717,7 @@ WARNING · structure · multiple-h1 — page renders 2 h1s          [open in bui
   • Willkommen bei SunWest (Hero ▸ Headline) · headline
       → keep this one as the page's h1
   • Unsere Standorte (Karten ▸ Panel "Standorte") · panel-title · "Unsere Standorte"
-      → Fix: element_update_settings({ template_id: "page:4816",
+      → Fix: element_update_settings({ layout_id: "page:4816",
         element_path: "/children/1/children/0", props: { title_element: "h2" } })
   Why: exactly one h1 anchors the page's topic; several dilute it.
 
@@ -2515,7 +3726,9 @@ WARNING · content · images-missing-alt — 1 image without alt text
       → Fix: element_update_settings({ …, props: { image_alt: "<what it shows>" } })
   Why: an empty alt makes the image invisible to screen readers and image search.
 
-Meta title/description/OG live in your CMS SEO plugin — not covered here.
+Not covered here, and not an exhaustive list: your CMS or SEO plugin owns meta
+title/description/OG, and whether search engines may index the page at all —
+check that with yootheme_builder_fetch_public_url({url, expect:"noindex"}).
 ```
 
 **Worked example (tool-call snippet):**
@@ -2527,62 +3740,80 @@ yootheme_builder_advanced_read({
   arguments: { checks: ["seo", "structure"] }
 })
 // A finding: { code: "missing-h1", category: "structure", severity: "warning",
-//   count: 3, pages: [{ id: "page:42", label: "About" }, ...],
+//   affected_pages: 3, pages: [{ id: "page:42", label: "About" }, ...],
 //   fix_hint: { tool: "element_update_settings",
 //     args_template: { props: { title_element: "h1" } }, note: "..." } }
 
 // Step 3. Drill into the flagged page.
-yootheme_builder_template_summary({ template_id: "page:42" })
+yootheme_builder_template_summary({ layout_id: "page:42" })
 // heading_levels: { h1: 0, h2: 2, h3: 5, div: 1 }, images_missing_alt: 2
 
 // Step 4. Fix that ONE page via the write tool the fix_hint named.
 yootheme_builder_element_update_settings({
-  template_id: "page:42",
+  layout_id: "page:42",
   element_path: "/children/0/children/0",
   props: { title_element: "h1" },
   etag: "abc123"
 })
 
 // Step 5. Republish; quick_check re-confirms this page is clean.
-yootheme_builder_page_publish({ template_id: "page:42", etag: "def456" })
+yootheme_builder_page_publish({ layout_id: "page:42", etag: "def456" })
 // Response: { ..., quick_check: { clean: true } }
 ```
 
 **Success criterion:** A re-run of `pages_audit` (or the `quick_check`
 block on the next publish) no longer lists the fixed finding for that
-page, and the response's `summary.critical`/`warning`/`info` totals go
-down.
+page, and the response's `summary.critical_finding_kinds` /
+`warning_finding_kinds` / `info_finding_kinds` totals go down. Those three
+count finding KINDS, not pages — `summary.affected_pages_summed_across_findings`
+is the page-level tally beside them.
 
 ---
 
 ## When something doesn't fit one of these 6 workflows
 
 - **Move an element** (intra-template reorder/reparent): use
-  `yootheme_builder_element_move({ template_id, element_path,
+  `yootheme_builder_element_move({ layout_id, element_path,
   to_parent_path, to_index, etag })`. Reorders or reparents without
   re-creating.
 - **Delete an element**: use `yootheme_builder_element_delete({
-  template_id, element_path, etag, confirm: true })`.
+  layout_id, element_path, etag, confirm: true })`.
   Elicitation-aware. Confirms via the AI client prompt before
   destroying state when `confirm` is omitted. On hosts without
   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", arguments: { template_id, element_path, etag, confirm: true } })`.
+  `yootheme_builder_advanced({ tool: "yootheme_builder_element_unbind_source", arguments: { layout_id, element_path, etag, confirm: true } })`.
   Same elicitation flow as delete.
 - **Orient in a large template before editing** (cheapest first read):
-  `yootheme_builder_page_get_layout({ template_id, mode: "outline" })`
+  `yootheme_builder_page_get_layout({ layout_id, mode: "outline" })`
   returns a token-efficient INDENTED text tree — one line per node,
-  `label ▸ type (bound: …) [sN]`. Each line carries a short handle
-  `[sN]` AND the node's real JSON-Pointer `path`. **The handle is
-  PER-READ (state-scoped): it is stable only at the etag you just read.
-  After ANY mutation (clone/move/delete/bind), re-read `mode:"outline"`
-  to get fresh handles.** Use the `path` (not the handle) as the write
-  address for `element_*` tools — the handle is only a readable alias.
-  For binding-focused work prefer `mode:"bindings_only"` instead.
+  `label ▸ type (bound: …) [sN]`. **The handle `[sN]` is a PER-READ
+  (state-scoped) reading alias only, never a write address — it is
+  stable only at the etag you just read, and re-reads after ANY
+  mutation (clone/move/delete/bind) get fresh handles.** The structured
+  leg carries a SUMMARY (which sections are named, how many nodes each
+  holds, the etag), not a path per node — for the actual write address
+  (a RELATIVE `element_path`) call `yootheme_builder_element_list`,
+  scoped to one named section with `root_path` from the outline's
+  `named_sections` if you already know which chunk you want. For
+  binding-focused work prefer `mode:"bindings_only"` instead — and read it as
+  an inventory that checks exactly ONE thing. It compares every binding's
+  SOURCE against the sources this site registers: a source that is gone gets
+  `unresolved: true` on that binding and is named once in
+  `unresolved_sources`, with an `unresolved_sources_note` beside it saying what
+  to repair. That list is present but EMPTY when the comparison ran and found
+  nothing, and is replaced
+  by `unresolved_sources_not_checked` when the registered-source list could not
+  be read at all — in that state an unmarked binding means nothing, so do not
+  read it as a clean bill. What it does NOT check is the field VALUES inside a
+  source that does resolve: a `props` value naming a field that does not exist
+  looks exactly like one that does and will render blank. `element_get_binding`
+  names those dead VALUES on one element; `pages_audit`'s `dangling-source`
+  finding reports the same dead sources across the whole site, with paths.
 - **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", arguments: { template_id } })`.
+  type without fetching the whole nested tree): call the L1 tool directly:
+  `yootheme_builder_element_list({ layout_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.
@@ -2593,13 +3824,26 @@ down.
   `frontend_url_template` (with placeholders the user fills in).
 - **Find out which site / install you are connected to**: call
   `yootheme_builder_health` (Bearer-authenticated payload includes
-  `site_url` + `home_url`) or `yootheme_builder_diagnose`.
+  `site_url` + `home_url`), or `yootheme_builder_diagnose` for `site_url`
+  alone. `active_site.site_id`, which rides on every answer, names the registry
+  entry your own config picked — a different question from which install the
+  plugin believes it is.
+- **Find WHERE `implode` directives sit on the site** (rows rendering as one
+  comma-joined string, and you do not know which page): call through the
+  read gateway
+  `yootheme_builder_advanced_read({ tool: "yootheme_builder_layout_query", arguments: { has_implode_directives: true, max_paths: 50 } })`
+  — no `layout_id`, so the sweep covers every page layout, and `paths[]`
+  gives you the `layout_id` + `path` pairs to act on. The detection is the
+  same one `inspect_multi_items_binding` reports as `has_implode_directives`,
+  so opening a hit confirms it. Every count in that answer describes the
+  matching subset, not the site.
 - **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", arguments: { template_id, element_path, etag } })`.
+  `yootheme_builder_advanced({ tool: "yootheme_builder_clean_implode_directives", arguments: { layout_id, element_path, etag } })`.
   Returns the audit log + a fresh ETag; idempotent (`cleaned_count: 0` when
-  there is nothing to remove).
+  there is nothing to remove). It also removes EMPTY `implode` stubs, which
+  the finder above does not report — an empty stub joins nothing.
 - **Start from a pre-designed layout or element preset instead of
   hand-building** (the user wants a "Home"/"Contact"/"Services" page, or a
   ready-made Accordion/Alert preset, not a section built element-by-element):
@@ -2626,14 +3870,14 @@ layout root, then child 1 of that); a three-level path is
 into the Nth child (0-based). This is the form `element_list` emits as
 `rel_path`, and the form every worked example in this skill uses.
 
-- **Fully-qualified:** `/templates/<template_id>/layout/children/0/...` is the
+- **Fully-qualified:** `/templates/<layout_id>/layout/children/0/...` is the
   same address with the template prefix. Read/write tools return the
   fully-qualified pointer as `path`; you can pass it straight back.
 
-**What the tools EMIT:** `element_list` / `page_get_schema` return both `path`
+**What the tools EMIT:** `element_list` returns both `path`
 (fully-qualified) and `rel_path` (the canonical `/children/0/...` form); every
 write-tool response (`element_add`, `element_update_settings`, `element_clone`,
-`element_move`, `element_bind_source`, `page_dynamize`, `scaffold_section`) and
+`element_move`, `element_bind_source`, `page_generate_dynamic`, `scaffold_section`) and
 `element_get` return the fully-qualified `path` plus the canonical `rel_path`.
 Copy either straight back into the next call.
 
@@ -2653,6 +3897,58 @@ hand you.
   layout node itself, which is not an addressable element. Use `""` for
   "the top".
 
+**What is NOT an element address.** The grammar above is exhaustive: an
+element is the layout root plus zero or more `/children/<index>` steps. These
+tools refuse anything else rather than writing into it — `element_add`,
+`element_delete`, `element_move`, `element_clone`, `element_update_settings`,
+`element_set_status`, `element_bind_source`, `element_unbind_source`,
+`element_set_source`, `clean_implode_directives`, `page_generate_dynamic`,
+`library_insert` (both `element_path` and `sublayout.element_path`) and
+`library_save_as`. In particular these resolve to real JSON but are **not**
+elements:
+
+- `…/children` — the LIST of a node's children, not a child. Drop the
+  trailing `/children` to name the element that should contain the child.
+- `…/props` — an element's settings. Pass the element's own path; the tool
+  writes into `props` for you. A props map that happens to carry a `type` key
+  (`props: {"type":"primary"}` is an ordinary element prop) is still props.
+- `…/type` — a scalar member of an element, not the element. Any member other
+  than `children` ends the element grammar; pass the element's own path.
+- `/templates/<id>` — the template record. Its element tree starts one
+  segment further down, at `/templates/<id>/layout`.
+- `…/children/007` — a leading-zero or gapped reference-token. Array positions
+  are canonical RFC-6901 §4 indices; anything else names no position.
+
+The layout root itself (`parent_path: ""`, or `/templates/<id>/layout`) is a
+valid **parent** for `element_add` / `element_move`, and never a thing to
+`element_delete`, `element_move` or `element_clone` — deleting it takes the
+whole page with it. Each refusal names the offending argument and what to
+pass instead; nothing is changed. (`page_generate_dynamic` is the one exception
+on the root: it COPIES rather than mutates, so `element_path` may name the
+whole page.)
+
+**`children` must be a JSON array.** `pages_create`, `page_save` and
+`element_add` refuse a `children` sent as an object with named keys — `{"0":…,"5":…}` — with
+`layout_children_not_a_list`. The Builder walks `children` by position, so a
+keyed object there renders in insertion order, makes every `/children/<index>`
+path address a different node than it reads, and can overwrite a sibling on the
+next append. A `{"0":…,"1":…}` object with contiguous keys is accepted: it
+re-encodes as a JSON array, which is what lands on disk either way.
+
+Only the layout root must declare `children`. An empty section, row or
+column may omit the key — that is how the builder itself stores them
+(YOOtheme's save-transforms remove an empty `children`). A `children` value
+that is present must be a JSON array, never an object.
+
+**Theme templates in `library_insert` / `library_save_as`.** Those two tools
+resolve their path against the template as stored, and a THEME template
+(a `pages_list` id with no `page:` / `article:` prefix) stores its tree one
+segment down. `element_path: ""` still means "the top of this template" and
+works on both kinds; a deeper path on a theme template starts at
+`/layout/children/<index>`. Pass a `page:<id>` / `article:<id>` path there and
+the refusal says so. (The `element_*` tools are unaffected — their `rel_path`
+is layout-relative for every template kind.)
+
 **Reading the index.** In `/children/0/children/2/children/1`: child 0 of the layout,
 then child 2 of THAT, then child 1 of THAT. Indices are positional and shift
 when siblings are added or removed; re-read after a structural mutation before
@@ -2660,10 +3956,12 @@ reusing a path (see the ETag handshake below).
 
 **Don't hand-build deep paths.** Enumerate with
 `yootheme_builder_element_list` (flat `{path, rel_path, element_type}`
-rows) or orient with `yootheme_builder_page_get_layout({ template_id,
-mode: "outline" })` (indented `label ▸ type [sN]` tree, each line
-carrying the real `path`). Copy the `path` from a row — never count
-`/children/` segments by eye on a big template.
+rows) — copy `path` from a row there, never count `/children/`
+segments by eye on a big template. `yootheme_builder_page_get_layout({
+layout_id, mode: "outline" })` only ORIENTS (an indented
+`label ▸ type [sN]` tree plus a per-section node-count summary); scope
+`element_list` to one named chunk with `root_path` from the outline's
+`named_sections` when you already know which one you want.
 
 ## ETag handshake and self-correcting errors
 
@@ -2681,9 +3979,12 @@ carrying the real `path`). Copy the `path` from a row — never count
    carrying `current_etag` — read it and retry.
 
 So a write never leaves you guessing: on a lock error the response hands
-you the etag to use next. On success, `changed_paths` tells you exactly
-which addresses moved, so you can re-target without re-reading the whole
-tree.
+you the etag to use next. On a `412` specifically, take that etag as
+permission to retry only AFTER re-reading — the site-wide hash does not
+cover per-page layouts, so the conflict may well be your own page under
+someone else's edit, and the error cannot tell the two apart. On success,
+`changed_paths` tells you exactly which addresses moved, so you can
+re-target without re-reading the whole tree.
 
 **Self-correcting path errors.** When a path-addressed read cannot find
 the element at the path you sent, the `element_not_found` error does NOT
@@ -2719,7 +4020,9 @@ to re-read the entire layout after a wrong-path error.
 
 Every high-volume read tool takes `max_chars`. When a response does not fit,
 it is **shortened by dropping whole entries, never by cutting the JSON**, and
-it tells you so. Read the verdict before you report a result as complete:
+it tells you so. Read the verdict before you report a result as complete
+(one read caps a text FIELD instead — last paragraph, where these flags are
+absent):
 
 - `truncated: true` — this response is not the whole answer.
 - `omitted_count: N` — exactly how many entries were left out.
@@ -2730,28 +4033,30 @@ it tells you so. Read the verdict before you report a result as complete:
   be rewound past the dropped entries is **removed, never left stale**, so a
   `next_cursor` you receive is always safe to follow.
 - `omitted_keys: [...]` — on a single-object response, which fields were shed
-  (the small identifying ones like `template_id` / `etag` are kept last).
+  (the small identifying ones like `layout_id` / `etag` are kept last).
 - `retry_hint` — the concrete lever: a higher `max_chars`, a narrower
   `fields[]` projection, or a smaller `limit`.
 
-The payload always parses — on the plugin's own `/mcp` endpoint the text leg
-itself is reduced entry by entry, and through this Node server a shortened text
-preview always travels beside a complete `structuredContent` leg carrying the
-full result. So read `structuredContent` when the text leg looks cut. If you
-ever receive a response where **neither** leg parses, that is a bug — report it
-rather than working around it.
-
-Both transports carry that structured leg, but **they do not put the same thing
-in it**. Over stdio it is the complete result. The plugin's own `/mcp` endpoint
-puts the **same shortened payload in both legs** — reading its `structuredContent`
-gives you exactly what its text leg already said, no more. That is a constraint,
-not a preference: on WordPress the host plugin's MCP adapter builds both legs
-from one returned value, so a bounded text leg beside a complete structured one
-cannot exist there. Decide whether an answer is whole from `truncated` /
-`omitted_count`, never from which leg you happened to read.
-
-The reverse is also true: **absence of `truncated` means the answer is
-complete.** Do not hedge a full response with "there may be more".
+The payload always parses — in this shape the text leg is reduced entry by
+entry rather than cut mid-string. If you ever receive a response where
+**neither** leg parses, that is a bug — report it rather than working around it.
+
+Here both legs carry the **same shortened payload**: reading `structuredContent`
+gives you exactly what the text leg already said, no more, so it is not a way
+around the cap. Decide whether an answer is whole from `truncated` /
+`omitted_count`, never from which leg you happened to read — and **absence of
+`truncated` means the answer is complete**, so do not hedge a full response with
+"there may be more".
+
+**`page_get_layout(mode:"outline")` shortens differently, and none of the three
+rules above holds for it.** The cap bounds ONLY the outline text (both legs
+carry that same string); the summary beside it in `structuredContent` —
+`named_sections`, `total_elements`, `etag` — is never shortened. So here a
+bounded text leg DOES sit beside a complete structured one, the text is
+cut mid-string, not entry by entry, and the cut is announced by a trailing
+`--- TRUNCATED (N chars total, showing first M) ---` line, with **no
+`truncated` field and no `omitted_count`**. Read that marker; a missing flag
+means nothing here.
 
 Two levers beat raising `max_chars`, because they reduce what is produced
 rather than what survives: ask for fewer fields (`fields[]`) and fewer rows
@@ -3208,44 +4513,58 @@ skipped (no geocoding); an empty `map.height` becomes 300; a non-numeric
 and make it data-driven — repeating over a source's items — WITHOUT
 rebuilding it node by node.
 
-Use `yootheme_builder_page_dynamize`. It copies the referenced layout
-byte-identically and swaps ONLY what you map, so the design (spacing,
-styles, the `#parent` bindings) survives untouched.
+Use `yootheme_builder_page_generate_dynamic`. It copies the referenced
+layout byte-identically and swaps ONLY what you map, so the design
+(spacing, styles, the `#parent` bindings) survives untouched. It always
+creates a NEW, unpublished, unlinked page from the reference — the
+reference itself is never modified.
 
 **Canonical tool-call sequence (snake_case):**
 
 1. `yootheme_builder_get_etag()`: current lock.
-2. `yootheme_builder_template_summary({ template_id })` (or
-   `yootheme_builder_page_get_layout({ template_id, mode: "outline" })`):
+2. `yootheme_builder_template_summary({ layout_id })` (or
+   `yootheme_builder_page_get_layout({ layout_id, mode: "outline" })`):
    find the REFERENCE you will dynamize — a `section_name` (a named
    section from the summary) or an `element_path`.
 3. `yootheme_builder_sources_list()`: get the `list_source_name` to bind
    (the published source that yields the items).
-4. `yootheme_builder_page_dynamize({ template_id, section_name: "<name>", list_source_name: "<source>", leaf_map: { "<original-leaf-field>": "<flat-flow-field>" }, etag })`.
+4. `yootheme_builder_page_generate_dynamic({ layout_id, output: "new_page", section_name: "<name>", list_source_name: "<source>", leaf_map: { "<original-leaf-field>": "<flat-flow-field>" }, etag })`.
 
 **How the mapping works:**
 
 - `leaf_map` keys are the ORIGINAL leaf field-names in the designed
   section; values are the flat flow field they should now read. The
-  `#parent` binding and any tuned props are kept.
+  `#parent` binding and any tuned props are kept. A KEPT (unmapped) leaf
+  whose original name is not a field the swapped source emits surfaces in
+  the response's `summary.unmapped_kept_fields_missing_in_target` — map
+  it or accept the empty render.
 - A section with SEVERAL source blocks dynamizes in ONE call via
   `source_map` — an array of `{ match, source_name, leaf_map }`, one
   entry per block.
 - For sub-query panels, key a `leaf_map` entry by
   `"<subquery>.<leaf>"`.
-- `page_dynamize` requires `page.title`. It returns the page plus a
-  `summary`, and (since v1.4) `changed_paths` + `new_etag` like every
-  other write.
+- `output` is REQUIRED — "new_page" is the only value available today; a
+  future "in_place" value (editing the reference directly) is not yet
+  available.
+- `page_generate_dynamic` requires `page.title`. It returns the page plus
+  a `summary`, and `changed_paths` + `new_etag` like every other write.
+- With `dry_run:true`, a `would_change:false` answer carries a `reason` —
+  most commonly "no bound exemplar element under the reference": the
+  reference has nothing to swap because none of its leaves are bound yet.
+  Bind one element first (`element_bind_source`), then retry.
 
 **Common pitfalls:**
 
 - **Binding Multi-Items on the container.** Bind the source + Multi-Items
   on the `*_item` CHILD, never on the grid/list container — see the
-  Multi-Items renderer truth table above. `page_dynamize` follows that
-  rule for you when you hand it the right reference.
+  Multi-Items renderer truth table above. `page_generate_dynamic` follows
+  that rule for you when you hand it the right reference.
 - **Hand-editing the JSON instead.** Don't reconstruct the section with
   `element_add` calls to "make it dynamic" — that loses the design.
-  `page_dynamize` is the supported one-call path.
+  `page_generate_dynamic` is the supported one-call path.
+- **Expecting the reference page to change.** It never does — the result
+  is always a NEW page. Publish the new page or copy its layout onto the
+  reference yourself if you actually want an in-place swap.
 - **Reusing a stale etag.** Feed `new_etag` from the response into your
   next write.
 
@@ -3285,12 +4604,71 @@ apikey). See "WootsUp AI Layouts" below.
 Browse, get, AND insert against the remote catalog (`source: "catalog"`,
 the default) all depend on a YOOtheme Pro Library API key configured on the
 connected site (the customer's own theme `apikey`, set once in the YOOtheme
-Customizer — not something this MCP server manages). If it's missing,
-`library_browse` does not error — it returns `{ items: [], total: 0 }`.
-Treat `total: 0` as "ask the customer to check the theme apikey field in the
-Customizer", not a network/auth failure to retry blindly. **This apikey
-requirement applies ONLY to the remote catalog** — the local AI-Layouts
-store (next subsection) needs no apikey at all.
+Customizer, not something this MCP server manages). If it's missing,
+`library_browse` does not error: it returns `{ items: [], total: 0 }` with
+`api_key_configured: false` and a `detail_note`. Read that boolean rather
+than guessing from the count. **This apikey requirement applies ONLY to the
+remote catalog.** The local AI-Layouts store (next subsection) needs no apikey
+at all.
+
+**Do NOT tell the customer to check the apikey field until you know that is the
+problem.** `api_key_configured: false` means no key could be READ, and the
+reader answers that for five different situations. One of them is OUR lookup
+missing the row rather than anything the customer did, and it needs the
+opposite action. Run `yootheme_builder_diagnose` and read `library_key.state`:
+
+| `state` | who has to act |
+|---|---|
+| `key_present` | nobody. The key is readable, so an empty catalog is a different problem. |
+| `update_site_without_key` (Joomla) | the customer, in the YOOtheme Customizer theme settings. |
+| `theme_config_empty` (WordPress) | the customer, same place. |
+| `theme_config_unavailable` (WordPress) | nobody yet: YOOtheme is not loaded at all. Check the theme is active, then run `yootheme_builder_health`. |
+| `update_site_not_found` (Joomla) | **nobody, in the key field.** No `pkg_yootheme` update site matched, so the Customizer would show that field empty too. Report the state instead of sending the customer to a field that cannot fix it. |
+
+`library_key.hint` carries the same verdict as a sentence you can pass on, and
+`library_key.configured` is the boolean. The key itself is never in the payload.
+
+**A REFUSED catalog fetch is NOT an empty catalog.** When the site HAS a key
+and the YOOtheme Pro Library rejects it (measured: HTTP 401 "Invalid API Key"),
+`library_browse` and `library_get` answer `error_code:
+"library_upstream_unavailable"` (HTTP 503) carrying `upstream_status` and
+`api_key_configured`. Do NOT respond to it by dropping filters, trying another
+id, or calling `library_get` to "verify" the id: nothing you send repairs a key
+the provider refuses, and `library_get` is refused by the same upstream. Only
+the site owner can take it up with YOOtheme. Meanwhile the keyless `source: "ai"`
+store and `page_get_layout` still work. A successful `total: 0` is a different
+thing entirely: the catalog was read and matched nothing, and that is now the
+only thing an empty page can mean.
+
+**Browse can succeed while get and insert fail, and that is normal, not a
+bug.** The LIST endpoint the browse call uses answers even with NO key at all;
+the DETAIL endpoint (`/v1/library/layout/<id>`) that `library_get` and
+`library_insert` need CHECKS the key. Measured on two independent installs:
+`api.yootheme.com` refused those installs' configured key on every
+key-checking endpoint, the detail endpoint included, while browsing kept
+working normally. So "I can browse hundreds of layouts but every `library_get`
+fails" is a REFUSED KEY, not a bad id and not a broken plugin.
+
+**Say what was measured, and stop there.** The refusal answers
+`library_upstream_unavailable` (HTTP 503) with `upstream_status: 401` and
+`api_key_configured: true`, and the honest report is exactly that: *the
+YOOtheme Pro Library refused this site's API key, so the call could not be
+made.* Then stop re-trying ids, because no id repairs a refused key.
+
+**Do NOT tell the customer WHY it was refused.** You cannot see why. A 401 is
+the same 401 for a plan that does not cover the endpoint, an expired key, a
+key that was replaced, a domain or host restriction, and a change on
+YOOtheme's side. If the customer asks what to check, offer those as
+POSSIBILITIES and point them at their YOOtheme account; never present one as
+the diagnosis. Telling a paying customer their plan is the reason is a claim
+about their account that we have not established and cannot withdraw once the
+assistant has said it. Never phrase it as a defect in their site either.
+
+**`library_item_unavailable` (404) is a DIFFERENT state.** It means the item
+could not be fetched at all: no Library API key is configured on the site, or
+the id is not in the catalog. A site whose key is configured and refused gets
+the 503 above, never this 404. Reading them as the same thing sends a customer
+who HAS a key off to configure one.
 
 ### WootsUp AI Layouts — your OWN local library (no apikey, save → reuse)
 
@@ -3564,8 +4942,16 @@ at fetch time, never persisted raw):
   the rest of the insert.
 
 The insert response's `images_resolved: { downloaded, placeholders }`
-tells you exactly what happened — check it rather than assuming every
-image round-tripped.
+tells you HOW MANY of each — check it rather than assuming every image
+round-tripped. It does not tell you WHICH, and a count on its own is not
+actionable: `image_import_failures` is. That field appears only when a
+curated insert actually failed to fetch something, and carries one entry
+per lost image with the `prop_path` inside the fetched item (e.g.
+`children[0].props.image`), the `exception_class`, and a `message`. Read it
+before reporting the insert as finished: a failure is often transient, so a
+second `library_insert` — or a searched-and-imported photo bound into that
+exact prop path — usually fixes it. Absent means nothing failed; on
+`images_mode: "as_saved"` or `"placeholder"` the curate step never ran.
 
 ### Fill image slots with real on-topic photos (search → import → bind)
 
@@ -3573,9 +4959,13 @@ The professionalism signal is on-brand IMAGERY (see "Make it the CUSTOMER's bran
 
 **The flow (three tools):**
 1. `yootheme_builder_image_search({ source, query, orientation })` returns candidate rows, each with a `full_url` (the image to import) plus dimensions and author. `source`: `unsplash` or `pexels` for real photography (the primary rich sources); `proimages` for YOOtheme's own curated decorative and background assets. Use `orientation: "landscape"` for heroes and banners, `"portrait"` for tall cards.
+   A search that could NOT be carried out is an ERROR, not an empty shelf: it comes back with `error_code: "image_search_unavailable"` (HTTP 503). Do NOT respond to it by broadening the query. It means the provider refused the request or never answered, most often an HTTP 401 on the site's YOOtheme Pro Library API key (`upstream_status: 401`), which only the site owner can resolve. When that happens, stop searching, keep honest placeholders, and tell the user what `error` said. A SUCCESSFUL `total: 0` is a different thing entirely and DOES mean the query matched nothing; `api_key_configured` tells you whether the key gate was even open.
+   **`api_key_configured: true` plus a 401 is a real, ordinary state: the site HAS a key and the upstream turned it down for this call.** That is the whole of what the two fields establish, and it is not a defect in the plugin or in the site. A YOOtheme Pro Library API key can be perfectly well configured and still be REFUSED. Measured on two independent installs: with such a key, EVERY key-checking endpoint at `api.yootheme.com` refused it, including `/v1/library/layout/<id>`, the DETAIL endpoint `library_get` and `library_insert` depend on. The LIST endpoint behind `library_browse` answers even WITHOUT a key, which is why browsing keeps working and only the detail reads and searches fail. So the honest reading of "browse fine, get and search refused" is: **the upstream refuses this site's key** for those calls. Report exactly that, and stop. **What you must NOT do is name the reason.** Whether it is the subscription behind the key, an expired or replaced key, a domain restriction, or something changed at YOOtheme, is not visible from here, and all of them look like the same 401. If the customer wants to act on it, list those as POSSIBILITIES to check in their YOOtheme account, never as a finding. Telling a paying customer their subscription is short when it is not is not a mistake you get to take back. Do NOT report it as a defect, do NOT retry with broader queries, and do NOT tell them the plugin is broken. Image search works on WordPress and Joomla alike.
 2. JUDGE the candidates by FIT and TONE, exactly like you choose a section, and never grab the first result. Search deliberately by the brief's INDUSTRY plus TONE: a coffee roaster searches `"coffee roasting"` / `"espresso pour"` / `"cafe interior"` (warm, editorial); a law firm searches `"modern office architecture"` (clean, restrained). A generic `query: "business"` returns generic stock that reads as filler.
-3. `yootheme_builder_image_import({ url: "<full_url>" })` sideloads the chosen photo into the site's OWN Media Library and returns `{ local_url }`. Only Unsplash, Pexels, and YOOtheme image hosts can be imported (a security allowlist); other URLs are rejected.
-4. Bind it: `yootheme_builder_element_update_settings({ template_id, element_path, props: { image: "<local_url>" }, merge: true })`.
+3. `yootheme_builder_image_import({ url: "<full_url>" })` sideloads the chosen photo into the site's OWN Media Library and returns `{ local_url }`. The argument is also accepted under the name `full_url`, so a row from step 1 can be passed on unchanged — give ONE of the two, never both with different values. Only Unsplash, Pexels, and YOOtheme image hosts can be imported (a security allowlist); other URLs are rejected.
+   **`local_url` has a PLATFORM-SPECIFIC shape, and both are correct.** WordPress returns a root-relative path WITH a leading slash (`/wp-content/uploads/2026/07/hero.jpg`); Joomla returns a JPATH_ROOT-relative path WITHOUT one (`images/yootheme/hero.jpg`, the same shape YOOtheme's own image dialog stores). Bind whatever came back VERBATIM. Adding a slash on Joomla or stripping one on WordPress produces a path the layout cannot resolve, and the element then renders empty with no error anywhere. Importing the same photo twice returns the FIRST attachment instead of creating a duplicate, as long as the earlier copy is still in the site's current upload folder (on WordPress that is `wp-content/uploads/YYYY/MM/`, so a copy imported in an earlier month is not matched and a second attachment is created).
+   A failure never throws: it comes back as `{ imported: false, reason, failure }`. Read `failure` before deciding what to do next. `failure: "rejected"` means THIS url did not import (blocked host, upstream error, the CMS refused the file type), so picking a different candidate is the right move. `failure: "unavailable"` means the SITE cannot import any image right now (no media runtime, no HTTP transport), so stop importing, keep the placeholder, and tell the user what the `reason` said. Trying twenty more photos against an `unavailable` site only wastes the user's time.
+4. Bind it: `yootheme_builder_element_update_settings({ layout_id, element_path, props: { image: "<local_url>" }, merge: true })`.
 
 **Real photo vs honest placeholder:**
 - A real, ON-TOPIC photo beats a placeholder every time; it is the single biggest lift from "template" to "finished". Fill the hero and feature-section image slots with searched photos that match the brief.
@@ -3597,7 +4987,9 @@ The most common way an AI-built page falls short of a real Pro layout: it defaul
 1. Compose from the real Library sections FIRST. The section corpus (`library_browse({kind:"section"})`) is about 2000 individually-designed, already-rich sections across every demo. Selecting well among them for fit, tone, and variety, and preserving their design, is the primary path to a varied Pro-quality page. Do NOT strip their rich features (below).
 2. When you hand-build a section (no corpus section fits, or you build from native elements), reach into the palette below and pick the rich pattern that fits. Never the bare-minimum version. Vary your choices across the page.
 
-**The polish features Pro sections use constantly (these ARE what "rich" means): preserve them when composing, apply them when hand-building. The `panel` props named below are VERIFIED against the LIVE YOOtheme Pro 5.x `panel` schema (`element_type_get_schema("panel")` → 81 fields). `element_type_get_schema` is the source of truth — always confirm the exact key AND its enum values there before writing; a guessed key is hard-rejected and a guessed VALUE silently no-ops.**
+**The polish features Pro sections use constantly (these ARE what "rich" means): preserve them when composing, apply them when hand-building. The `panel` props named below are VERIFIED against the LIVE YOOtheme Pro 5.x `panel` schema (`element_type_get_schema("panel")` → 81 fields). `element_type_get_schema` is the source of truth — always confirm the exact key AND its enum values there before writing; a guessed key is stored and reported back under `warnings` (`code:
+"unknown_prop_keys"`) rather than refused, and a guessed VALUE either
+no-ops silently or, on an enum field, is refused with 422.**
 - **Card styling — THE single biggest "flat vs rich" lever: `panel_style` on a `panel`.** A bare `panel` (or a plain column of text) is what makes a section look flat; a `panel_style` turns it into a real styled CARD. Verified enum: `card-default` / `card-primary` / `card-secondary` / `card-hover` (hover-lift card) / `card-overlay` / `tile-default` / `tile-muted` / `tile-primary` / `tile-secondary`. A feature / team / pricing "card" is a `panel` WITH a `panel_style`, not three bare text columns.
 - **Hover** (on a `panel`; the image-hover props require a `link` + `panel_link`/`image_link`, per the schema `enable` rules): `hover_image` (swap the image on hover), `image_transition: scale-up`|`scale-down` (image zoom on hover), `title_hover_style: reset`|`heading`. `panel_style: card-hover` also gives a hover lift on its own.
 - **Depth**: `image_box_shadow` (`small`…`xlarge`) and `image_box_decoration` (`default`/`primary`/`secondary`/`shadow`/`mask`) — these apply to a panel image only when NO `panel_style` is set (they are mutually gated: use a `panel_style` OR the box-shadow/decoration, not both).
@@ -3631,7 +5023,7 @@ ones are legal depends on `kind`:
 | `target` shape | Accepts `kind: "layout"` | Accepts `kind: "element"` (preset) |
 |---|---|---|
 | `{ new_page: { title, status? } }` | ✓ creates a page, layout's sections become its content | ✗ rejected — a preset is not a page |
-| `{ template_id, element_path? }` | ✓ ONLY the layout ROOT is section-accepting (`element_path: ""` or omitted) | ✓ ONLY a **Column** — every other node type is rejected |
+| `{ layout_id, element_path? }` | ✓ ONLY the layout ROOT is section-accepting (`element_path: ""` or omitted) | ✓ ONLY a **Column** — every other node type is rejected |
 | `{ sublayout: { template_id, element_path } }` | ✓ the fetched layout's sections are stripped to bare ROWS first (a sublayout/fragment accepts rows, not sections) | ✗ rejected — a sublayout is not a Column |
 
 **A preset (`kind: "element"`) MUST target a Column. There is no
@@ -3646,12 +5038,13 @@ first, then point `element_path` at ONE of the returned `column_paths`:
 yootheme_builder_library_insert({
   id: "8cf55920",
   kind: "element",
-  target: { template_id: "home", element_path: "" }
+  target: { template_id: "home", element_path: "" },
+  etag: "<etag>"
 })
 // → 422 target_not_a_column: 'target at "/" is a "layout"'.
 
 // Fix: scaffold a section->row->column hull, then target the new Column.
-yootheme_builder_scaffold_section({ template_id: "home", columns: 1, etag: "<etag>" })
+yootheme_builder_scaffold_section({ layout_id: "home", columns: 1, etag: "<etag>" })
 // Response includes column_paths: ["/children/4/children/0/children/0"]
 
 yootheme_builder_library_insert({
@@ -3670,6 +5063,63 @@ separate strip step. Point `element_path` at the actual sublayout/
 fragment node itself, not its parent — pointing at the wrong level is a
 `422 target_not_a_sublayout`.
 
+**The table above is about the TARGET. The ITEM is checked too.** The
+composed result — the preset, or the layout's sections, or the stripped
+rows — goes through the SAME layout grammar `page_save` runs, before any
+image is imported. Two refusals come out of that, and neither is about
+where you pointed:
+
+- `422 layout_invalid_hierarchy` — what would be stored is a shape the
+  Page Builder never builds. The common case is a spine node saved as a
+  preset: a Row or a Column put into your own library with
+  `library_save_as` comes back classified as an element, and a Row inside
+  a Column is refused. So is a whole layout spliced into a Column, and so
+  is a **sublayout fragment at a page or layout root** — 67 of the shipped
+  catalog layouts are fragments (the dropdown, search and dialog groups),
+  served under `kind: "layout"` like any other layout. **The one
+  destination that accepts them is a `sublayout` target — never a
+  Column.** The Column branch of the target table only ever opens for
+  `kind: "element"` presets; pointed at a Column, one of these fails
+  before the hierarchy check even runs, with
+  `422 target_not_section_accepting`, and that answer's own hint suggests
+  the layout root or a `new_page` target — both refuse it too, for the
+  same `layout_invalid_hierarchy` reason as the root case above. For this
+  one item type, skip that suggestion and go straight to
+  `target: { sublayout: { template_id, element_path } }`.
+- `422 library_item_kind_mismatch` — the item carries a different `kind`
+  than the call declared. The declared kind alone decides which branch
+  composes the item, so a layout handed over as `kind: "element"` would go
+  in through the preset branch. The answer names both kinds; retry with
+  the one the item carries. Items from your own library carry their own
+  classification; a catalog id is looked up per kind, so there a wrong
+  `kind` is already a `404 library_item_unavailable`.
+
+Both are raised BEFORE the write and before any image import, so a
+refused insert stores nothing and imports nothing.
+
+### `insert_mode` — and the confirm gate that guards its default
+
+An `existing`/`sublayout` target already has children whenever you insert
+into a page you (or a customer) already built. `insert_mode` decides what
+happens to them, mirroring the three choices the Library dialog itself
+offers:
+
+| `insert_mode` | effect |
+|---|---|
+| `"replace"` (default) | DROPS the target's existing children; the composed content becomes the whole list |
+| `"top"` | prepends the composed content before the existing children |
+| `"bottom"` | appends the composed content after the existing children |
+
+**`"replace"` on a non-empty target answers with a PREVIEW instead of
+writing, unless you pass `confirm: true`.** The preview reports
+`preview: true`, `applied: false`, `requires_confirmation: true`, and —
+so you know exactly what would be lost — `would_remove_count` (how many
+children) and `would_remove_types` (their `type`s, in order). Nothing is
+written on that call; re-send the SAME request with `confirm: true` to
+replace anyway, or switch to `insert_mode: "top"` / `"bottom"` to keep
+the existing content instead. An ALREADY-EMPTY target never needs
+`confirm`, whatever mode you pick — there is nothing there to lose.
+
 ### Adapting a Library insert is STATIC content editing, not dynamizing
 
 **Every Library layout and preset is authored STATIC** — no source
@@ -3683,7 +5133,7 @@ section.
 an archive-style listing) is a deliberate, separate follow-up call, not
 something insert does for you.** Use the existing dynamize workflow
 documented in "Dynamize an existing section" just above this one
-(`yootheme_builder_page_dynamize`) to re-target a Library-inserted
+(`yootheme_builder_page_generate_dynamic`) to re-target a Library-inserted
 section's leaf fields onto a Source, or bind a Multi-Items container
 directly with `yootheme_builder_element_bind_source` (Workflow 2) if the
 inserted item already has a grid/list container you want to re-point at
@@ -3705,7 +5155,7 @@ live data instead of its demo items.
 - **Stuffing placeholder copy into a field you have nothing for**, to
   defeat collapsing. Leave it empty; collapsing is the intended behavior.
 - **Expecting `library_insert` to make anything dynamic.** It composes
-  STATIC content only — dynamizing is the separate `page_dynamize` /
+  STATIC content only — dynamizing is the separate `page_generate_dynamic` /
   `element_bind_source` call.
 
 **Worked example (browse → get → insert → adapt):**
@@ -3735,7 +5185,7 @@ yootheme_builder_library_insert({
   images: "placeholder",
   etag: "<etag>"
 })
-// Response: { template_id: "home", inserted_path: "/children/3", element_count: 12,
+// Response: { layout_id: "home", inserted_path: "/children/3", element_count: 12,
 //   images_mode: "placeholder", images_resolved: { downloaded: 0, placeholders: 6 },
 //   new_etag: "<fresh>", frontend_url: null }
 
@@ -3743,7 +5193,7 @@ yootheme_builder_library_insert({
 // inserted section back first (page_get_layout / element_get) to find the
 // real headline's element_path, then edit CONTENT only — style untouched.
 yootheme_builder_element_update_settings({
-  template_id: "home",
+  layout_id: "home",
   element_path: "/children/3/children/0/children/0",
   props: { content: "<customer's real headline>" },
   merge: true,
@@ -3820,62 +5270,69 @@ perform.
 
 <!-- TOOL-CATALOG:BEGIN -->
 
-**53 catalogued tools** plus the `yootheme_builder_advanced` (write) + `yootheme_builder_advanced_read` (read-only) gateways = **55 callable** end to end, of which **42 are advertised in `tools/list`** (38 L1 + 2 L3 + 2 gateways); the remaining 13 advanced tools are reachable only through the gateways. 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.
+**60 catalogued tools** plus the `yootheme_builder_advanced` (write) + `yootheme_builder_advanced_read` (read-only) gateways = **62 callable** end to end, of which **49 are advertised in `tools/list`** (45 L1 + 2 L3 + 2 gateways); the remaining 13 advanced tools are reachable only through the gateways. 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` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | Use when a Multi-Items element renders rows as ONE comma-joined string instead of N repeated items — typically stale `implode` directives left by a plugin upgrade (detect via yootheme_builder_inspect_multi_items_binding). Strips `props.source.props.*.implode` directives from an element binding. Returns audit log + new ETag. Idempotent (cleaned_count: 0 when nothing to remove) but destructive: the binding can't be restored without re-mapping. Ask the user to confirm, then call with `confirm: true`. Requires ETag. |
-| `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. When a write-scoped key resolves to a CMS user with no write capability, the response adds `capability_warning` and `effective_capabilities.can_edit:false` instead of writes failing with a blind 403. |
-| `yootheme_builder_element_add` | mutating | `children`, `element_type`, `etag`, `index`, `name`, `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`. Content/leaf elements may only be added inside a `column`; only `section` is valid at the root — call yootheme_builder_scaffold_section first for a valid column path. Appends by default; pass `index` (0 = first) to insert. Inserting renumbers later siblings — re-read paths via element_list after any structural write. Returns the new element's JSON-Pointer path. Requires ETag. |
-| `yootheme_builder_element_bind_source` | idempotent | `arguments`, `bindingLevel`, `directives`, `element_path`, `etag`, `field`, `field_mappings`, `query_arguments`, `relation`, `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. |
-| `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. Cloning renumbers later siblings — re-read paths via element_list after any structural write. Requires ETag. |
-| `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. Deleting renumbers later siblings — re-read paths via element_list after any structural write. If `preview:true` returns despite confirm, check `details.received_confirm` — strings/numbers accepted, but boolean is canonical. |
-| `yootheme_builder_element_get` | read+idempotent | `element_path`, `fields`, `max_chars`, `site_id`, `template_id` | Get the full element object at a specific JSON-Pointer path, including props and a `children_count` (NOT the children themselves — use yootheme_builder_element_list with root_path to enumerate children). `fields[]` narrows the returned object; `max_chars` bounds the text output. Address by template_id only — resolve a URL/post first via pages_resolve. |
-| `yootheme_builder_element_get_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | Read the source binding attached to an element. Always returns {template_id, element_path, binding, has_binding, field_mapping_count, warning?}: `binding` is the raw source binding (bound source name, field-mappings, query args/directives); `has_binding` is false and `field_mapping_count` 0 when the element is not bound. |
-| `yootheme_builder_element_list` | read+idempotent | `cursor`, `depth`, `fields`, `include_meta`, `limit`, `max_chars`, `root_path`, `site_id`, `template_id` | List elements in a template as a flat array with JSON-Pointer paths + types + `label` (the builder-assigned name; "" when unset — not that the type lacks one). Scope with `root_path`/`depth` for a subtree, paginate with `limit`/`cursor` for large templates. `fields[]` narrows each row; `max_chars` bounds the text output. template_id only — resolve a URL/post first via pages_resolve. |
-| `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). Moving renumbers later siblings — re-read paths via element_list after any structural write. Requires ETag. |
-| `yootheme_builder_element_set_source` | idempotent | `element_path`, `etag`, `site_id`, `source`, `source_extended`, `template_id` | Surgically SET a precomposed `source` (+ optional `source_extended.props`) on ONE element at a pointer, ETag-locked (blast-radius 0). Use this — not element_bind_source — when you have the exact source shape OR need `source_extended.props`, the native Multi-Items item-mapping carrier bind_source cannot write. E.g. FAQ accordion scoped to term: query.name="categoryFaqs.taxonomyCategoryFaq", field={name:"faq"}, source_extended.props→#node. Element-prop keys the type does not render echo back as `unknown_prop_keys` (non-fatal). ETag req. |
-| `yootheme_builder_element_set_status` | idempotent | `element_path`, `etag`, `site_id`, `status`, `template_id` | Enable or disable an element via its `props.status` field — the SAME field YOOtheme's own native "Disable element" checkbox writes. status:false excludes the element and its descendants from BOTH the live render and live findings; pages_audit and template_summary content_nodes both honour it. status:true re-enables it, restoring the YOOtheme default (no status field means active). Requires ETag. |
-| `yootheme_builder_element_type_get_schema` | read+idempotent | `element_type`, `field_names`, `fields`, `max_chars`, `name_contains`, `site_id`, `type_name` | Prop schema; read before element_add/element_update_settings: unknown keys rejected (error lists valid_prop_keys+did_you_mean). Field: {name,type,label?,text?,description?,enum?,value_hint?,group?,no_effect?} + groups[] + field_count/returned_count + binding_contract (containers/items). value_hint+enum first: some defaults are SEO-fatal (headline.title_element→h1); checkbox = boolean true/false; no_effect = read by nothing, never write it; group:"runtime-accepted" = honoured at render, hidden in UI. Select descriptors: field_names/name_contains. Bound size with fields[]/max_chars. |
-| `yootheme_builder_element_types_list` | read+idempotent | `fields`, `include_meta`, `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. Container rows carry `requires_child_type` (grid→grid_item); `has_children`/`has_children_support` are aliases (same value). |
-| `yootheme_builder_element_unbind_source` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | Remove the source binding from an element. Clears the element's canonical top-level `source` key AND the legacy `props.source`. Destructive in the sense that it may break dynamic-content rendering — always ask the user to confirm. Requires ETag. |
-| `yootheme_builder_element_update_settings` | idempotent | `element_path`, `etag`, `merge`, `name`, `props`, `site_id`, `template_id`, `unset` | 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. Pass `unset:["key",…]` to reset props to their YOOtheme default by removing them. |
-| `yootheme_builder_get_etag` | read+idempotent | `site_id` | Get the current ETag (state revision) for the YOOtheme builder. Returns a sha256+revision string for optimistic locking. This ETag is SITE-WIDE: it covers the ENTIRE builder state, so ANY write to ANY template (by any client) bumps it — a 412 means the site state advanced, not necessarily that YOUR template changed. It is the SAME token the read tools (page_get_layout, element_list) return in their `etag`. Pass it back as `etag` on any write tool; on 412, re-read and retry. |
-| `yootheme_builder_header_transparency_set` | idempotent | `acknowledge_contrast_risk`, `dry_run`, `etag`, `mode`, `pull_content_behind`, `site_id`, `template_id`, `text_color`, `transparent` | Inspect + repair the transparent header (nav over the hero). Always targets the FIRST section — YOOtheme reads these props there only; later ones are silently dead. dry_run defaults TRUE: returns current state, the theme-declared --uk-inverse, risk_class, confidence, recommendation, would_change. mode:"auto" writes the theme-declared colour; over a hero image/video it writes NO colour and says to LOOK. mode:"explicit" refuses a colour contradicting the theme (409) unless acknowledge_contrast_risk. transparent:false is always allowed. |
-| `yootheme_builder_heading_outline` | read+idempotent | `mode`, `site_id`, `template_id` | A real, doc-order H1-H6 outline of ONE template: each heading with its TEXT and the source element that carries it (`element_type`/`path`), plus the alt-status of every image (including images inside html/text/code raw markup). Read-only STRUCTURE inspection, not findings; use yootheme_builder_pages_audit for severity-sorted SEO findings across the whole site. Returns {outline, images, h1_count, has_level_skip, images_missing_alt}. Address by `template_id` (from pages_list or pages_resolve). |
-| `yootheme_builder_health` | read+idempotent | `site_id` | Check plugin installed/reachable. Returns plugin version, YT Pro version, REST endpoints. available_endpoints is derived from the live route registration on both platforms, so every path listed is request-ready as printed. Authenticated payload adds site_url + home_url for deep-linking. See yootheme_builder_diagnose for Bearer-validity + connectivity summary. |
-| `yootheme_builder_image_import` | idempotent | `site_id`, `url` | Sideload a photo into the site's own Media Library. Accepts ANY public image URL — it does NOT require a Library API key, so it still works when image_search is unavailable (typically pass a `full_url` from yootheme_builder_image_search). Returns `{imported:true, local_url}` where local_url is a SITE-RELATIVE path (e.g. /wp-content/uploads/...). Bind it via element_update_settings({props:{image: local_url}, merge:true}). A caught import failure returns `{imported:false, reason}`, never a 500. |
-| `yootheme_builder_image_search` | read+idempotent | `color`, `include_meta`, `orientation`, `per_page`, `query`, `site_id`, `source` | Search real on-topic photos (Unsplash/Pexels) or YOOtheme Pro Images to fill layout image slots with REAL, on-brand photography instead of bare placeholders. Returns candidate rows with `full_url` (pass straight to yootheme_builder_image_import) plus dimensions/author/orientation. `total:0` usually means no Library API key is configured (the same theme apikey library_browse/insert use). |
-| `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, …), the binding level (none\|container\|item), and a recommended_fix when it sits on the container. 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). If rows render as ONE comma-joined string, see clean_implode_directives. |
-| `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. |
-| `yootheme_builder_layout_query` | read+idempotent | `content_contains`, `cursor`, `fields`, `has_binding`, `include_meta`, `limit`, `max_chars`, `max_depth`, `name_matches`, `site_id`, `template_id`, `type`, `under_section` | Find elements in a template via AND-combined filters: `type` (one type or a list), `name_matches` (case-insensitive substring of the name), `content_contains` (case-insensitive substring of `content`/`title`/`meta` props), `has_binding` (bound vs unbound), `max_depth` (cap descent — 0 = top-level), `under_section` (inside a named section). template_id only — resolve a URL/post first via pages_resolve. Returns rows {path, element_type, label, has_binding}; paginate `limit`/`cursor`, narrow `fields[]`, bound `max_chars`. |
-| `yootheme_builder_library_browse` | read+idempotent | `cursor`, `element_type`, `has_effects`, `include_meta`, `kind`, `limit`, `purpose`, `query`, `role`, `site_id`, `source`, `topic`, `type`, `website` | Browse the YOOtheme Pro Library catalog: pre-designed page LAYOUTS, element PRESETS, or purpose-classified SECTIONS (hero/features/cta/...). Filter with `kind` ("layout" default \| "element" \| "section"), `topic`, `type`/`role`, `element_type`, `purpose`/`has_effects` (sections only), `website`, `query`. Returns `{items, total, next_cursor}`; a "section" id is the composite "<layoutId>#<sectionIndex>" — feeds straight into library_get/library_insert. `total:0` usually means no Library API key configured. |
-| `yootheme_builder_library_delete` | destructive | `confirm`, `id`, `site_id`, `source` | Delete ONE saved entry from your "WootsUp AI Layouts" store (the isolated library yootheme_builder_library_save_as writes into) — clean up experimental sections/layouts the agent saved. Pass the `id` from a library_browse(source:"ai") row. `source` defaults to "ai", the ONLY deletable store; the curated library is read-only, so source:"catalog" returns a 403. IRREVERSIBLE — requires confirm:true. Returns `{deleted, id, deleted_count, source}`; an unknown id returns a 404. Advanced/gateway-only. |
-| `yootheme_builder_library_get` | read+idempotent | `id`, `include_thumbnail`, `kind`, `site_id`, `source` | Fetch a SINGLE YOOtheme Pro Library layout or element preset by `id` — call after yootheme_builder_library_browse (items[].id feeds this). Returns `{id, kind, name, version, tree, sections, images_manifest_count}`: `tree` is the raw JSON; `sections` lists `tree.children` (layouts only, presets return `[]`), each `{index, name, path, element_count}`. `include_thumbnail:true` also returns an image block (costs tokens — see its own description). Read-only; does not insert/bind. |
-| `yootheme_builder_library_insert` | mutating | `etag`, `id`, `images`, `kind`, `section_index`, `site_id`, `source`, `target` | Insert a YOOtheme Pro Library item (layout, section, or preset) onto a page — call after yootheme_builder_library_get/browse. `target`: new_page (creates a page), {template_id,element_path?} (splices onto the layout root, or a preset onto a Column), or sublayout (splices rows into a fragment). A preset (kind:"element") MUST target a Column — 422 otherwise; scaffold one first with yootheme_builder_scaffold_section. `images`: "placeholder" (default) or "curated" (downloads to Media Library). Optional `etag` locks (412 if stale). |
-| `yootheme_builder_library_save_as` | mutating | `destination`, `name`, `site_id`, `source` | Save a page or subtree into a reusable library — the REVERSE of yootheme_builder_library_insert. `source`: {template_id, element_path?} (omit element_path to save the WHOLE page). `destination`: "ai" (default — your isolated "WootsUp AI Layouts", reusable via library_browse/insert source:"ai") or "native" (YOOtheme's built-in My Layouts). Returns `{library_id, name, storage, invalid_source_possible}` (the last flags bound sources that may need re-binding after reload). Advanced/gateway-only. |
-| `yootheme_builder_local_content_read` | read+idempotent | `fields`, `include_children`, `include_meta`, `kind`, `limit`, `max_chars`, `offset`, `parent_id`, `search`, `site_id`, `status`, `taxonomy`, `type` | Read native records for one `kind`: entities (posts/pages/CPT/articles), terms (TERMS — ids that archive-scope a Grid), users, fields (ACF/com_fields defs), menus, or media. Published-only + paginated: {items,total,next_offset}; pass next_offset back as `offset`. Archive-scoping flow: read {kind:"terms",taxonomy:"category"} → pick a term id → bind a source, pass query_arguments:{id:<term_id>}. CALL local_content_types FIRST for valid type/taxonomy. E.g. {kind:"entities",type:"product",search:"shoe"}. Slim with `fields[]`. |
-| `yootheme_builder_local_content_types` | read+idempotent | `fields`, `kind`, `max_chars`, `site_id` | Discover the site's NATIVE content landscape — post types/articles, taxonomies and custom-field groups (ACF/com_fields), native to WP/Joomla (no API Mapper). Returns {content_types, taxonomies, field_groups, capabilities}; rows carry `bindable` + `source_name` (null for native types — bind those with element_bind_source by the content-type `name`, e.g. "post"). CALL FIRST, then local_content_read for records. Narrow with `kind`, slim with `fields[]`. E.g. {kind:"content_types"}. |
-| `yootheme_builder_navigation` | read+idempotent | `menu`, `site_id` | The site's navigation menus (WP nav menus / Joomla menus) as a parent -> children TREE, not a flat list, for "which page is under which menu item" (product pages usually live in the main menu). Each item carries a `page_role` facet (home\|landing\|product\|legal\|thankyou\|blog\|mockup\|template\|generic, same vocabulary as pages_list) and, when derivable at zero extra cost, a `target_page` (page:<id> / article:<id>) ready for yootheme_builder_page_get_layout. Read-only. Narrow to one menu with `menu`. |
-| `yootheme_builder_page_dynamize` | mutating | `conditions`, `dry_run`, `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 dynamizes in ONE call via source_map ({match, source_name, leaf_map?}[]). Sub-query panels: key by "<subquery>.<leaf>". Returns page + `summary`. Preview with dry_run:true. |
-| `yootheme_builder_page_get_layout` | read+idempotent | `cursor`, `fields`, `flat`, `force`, `max_chars`, `mode`, `post_id`, `site_id`, `template_id`, `url` | Get the layout tree for one template — address it by `template_id` (from pages_list), `post_id`, or `url`. `mode:"bindings_only"` for dynamize/bind; `mode:"full"` (default) is nested `{layout, etag}`, `flat:true` a depth-first array. `max_chars` bounds the text; a clipped read returns `next_cursor` to page the rest. For a site-wide SEO/structure/content/links audit (h1, image alt, thin pages, dead links) do NOT loop this tool page-by-page — call yootheme_builder_pages_audit (one sweep via yootheme_builder_advanced_read). |
-| `yootheme_builder_page_get_schema` | read+idempotent | `fields`, `include_meta`, `max_chars`, `post_id`, `site_id`, `template_id`, `url` | Get the flat schema for a template — nodes with their JSON-Pointer paths and element types. Lighter than page_get_layout, enough to locate elements before editing. Address by `template_id` (pages_list), `post_id`, or `url`. `fields[]` slims each node; `max_chars` bounds output. |
-| `yootheme_builder_page_publish` | idempotent | `etag`, `quick_check`, `site_id`, `template_id` | Publish a template — persist state, flush YT + WP caches, snapshot the published-state ETag. YOOtheme templates already publish on save, so this is a cache-flush + state-snapshot op. Neither publish nor save changes the CMS post status — a draft page stays invisible to visitors; set status at creation via pages_create/library_insert. ETag optional — when provided, 412 on conflict; when omitted, last-write-wins. |
-| `yootheme_builder_page_save` | idempotent | `dry_run`, `etag`, `layout`, `quick_check`, `site_id`, `template_id` | Re-run save-transforms + flush caches. Optionally REPLACE the template tree by passing the INNER {type:"layout",children:[...]} tree as `layout` — page_get_layout's `.layout` child, NOT the whole response it returns (rejected 422, would blank the page). Validated + ETag-locked; nothing persists on reject. Does NOT change CMS post status — a draft stays invisible to visitors; set status via pages_create. `dry_run:true` preflights; success carries `previous_layout` for rollback. ETag optional (412 on conflict; else last-write-wins). |
-| `yootheme_builder_pages_audit` | read+idempotent | `checks`, `include_meta`, `max_chars`, `mode`, `site_id`, `stale_after_months`, `target`, `thin_content_threshold`, `types` | One-call site-wide SEO/structure/content/links/design audit — severity-sorted findings with fix_hints (a props fragment to merge: supply template_id+path from the locator). Covers h1/headings, thin pages, image alt, duplicate layouts, title collisions, non-pretty URLs, dead anchors. Only active (non-disabled) nodes produce findings. A site sweep caps hits/page, drops content_snippet; `target` scopes to ONE page for the full set (cap 100). Filter with `types`/`checks`. Disclaimer: SEO-plugin meta (title/description/OG) NOT covered. |
-| `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. |
-| `yootheme_builder_pages_delete` | destructive | `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. |
-| `yootheme_builder_pages_list` | read+idempotent | `cursor`, `fields`, `include_meta`, `label_contains`, `limit`, `max_chars`, `site_id` | List pages, templates, and layouts in the YOOtheme Pro builder (id, label, type, elements_count, frontend_url, builder_url, serves_context_kind, serves_context_ids, page_role per row). CALL THIS FIRST to discover template IDs before page_get_layout / element_list / page_get_schema. Paginates: up to `limit` rows (default 50) plus `total` and a `next_cursor` (pass it back as `cursor`) when more remain. Filter with `label_contains`. Slim rows with `fields:["id","label"]`; bound output with `max_chars`. |
-| `yootheme_builder_pages_resolve` | read+idempotent | `site_id`, `target`, `url` | Resolve a public page/article/archive URL to the template_id that renders it — paste a URL, get the layout id. Pretty/SEF permalinks resolve on WordPress AND Joomla (incl. deep sub-category paths), not only raw ?option= URLs. A singular page → its per-page layout; a category/tag/CPT/author archive → the governing THEME TEMPLATE, and for a category/term the SPECIFICALLY-ASSIGNED template (honoring include-child-categories), not a generic one. Or a `target`. Returns {template_id, post_id, type, frontend_url, context, resolved_via}. |
-| `yootheme_builder_rename_source` | idempotent | `dry_run`, `etag`, `field_map`, `from`, `site_id`, `source_map`, `template_id`, `to` | Template-wide RENAME of a source / type / field name across EVERY binding in a template, in ONE ETag-locked write — preserving each binding's arguments, props and field_mappings. Use after a taxonomy/CPT rename (faq→help) breaks every bound layout. Pass `from`/`to` for one source, and/or `source_map`/`field_map` to rename a relation + its field tokens together; the dotted "<source>.<relation>" form is rewritten segment-by-segment. Returns {replaced_count, changed_paths, new_etag}. Preview with dry_run:true. ETag req. |
-| `yootheme_builder_render_preview` | read+idempotent | `expect`, `post_id`, `site_id`, `template_id`, `url` | Render-check a saved template — does it actually render, with how many items, or is it blank? Address by `template_id` (from pages_list), `post_id`, or `url` (resolved for you) — exactly one. `item_count` = items yielded by the template's dynamic/Multi-Items bindings (rendered repeat-source rows); 0 with empty:true means a binding returned nothing. Returns {rendered, item_count, empty, error?, cache_purge_hint}; with `expect`, also {matched, snippet}. Use AFTER a save/bind to catch a silently-empty page. Read-only. |
-| `yootheme_builder_scaffold_section` | mutating | `column_widths`, `columns`, `etag`, `site_id`, `template_id` | Create a VALID section → row → column hull in ONE call; returns the column JSON-Pointer path(s) for content. The correct way to start a layout block: only `section` may sit at the layout root; a bare section accepts `row`, a bare row accepts `column`; leaf/content elements are rejected anywhere except inside a `column`. Pass `columns` (1-12, default 1); columns get width tokens so they render side-by-side (hand-built columns default to full width), or `column_widths` (one token per column) for an asymmetric row. Requires ETag. |
-| `yootheme_builder_sites_list` | read+idempotent | `include_meta`, `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. The `default_site_id` is the write target when a call omits site_id. (site_id is accepted for schema-uniformity but ignored by this tool.) |
+| `yootheme_builder_clean_implode_directives` | write+destructive+idempotent | `confirm`, `element_path`, `etag`, `layout_id`, `site_id` | Use when a Multi-Items element renders rows as ONE comma-joined string instead of N repeated items — stale `implode` directives left by a plugin upgrade (detect via inspect_multi_items_binding). Destructive: the binding can't be restored without re-mapping. The clean requires confirm:true + ETag; the dry run neither. Without `confirm` the call runs a server-side DRY RUN and reports `would_clean_count` while writing nothing. Live at once. |
+| `yootheme_builder_diagnose` | read+idempotent | `site_id` | Why a call was refused: `auth_bound` (key accepted), `etag_ok` (layout readable), `site_url` (WHICH install; a key valid elsewhere fails here), `capability_ok` + `capability_warning` (the CMS user has no `can_edit`, so no blind 403). Install facts: health. |
+| `yootheme_builder_element_add` | write+non-idempotent | `children`, `element_type`, `etag`, `index`, `layout_id`, `name`, `parent_path`, `position`, `props`, `site_id`, `type_name` | Add a new element to a template. Provide `parent_path` (or "" for root), `element_type`, and optional `props`/`children`. Content/leaf elements may only be added inside a `column`; at the root only `section` — else call scaffold_section for a valid column path. Inserting renumbers later siblings: `renumbered_siblings` names each moved sibling address (absent if none). Requires ETag. Live at once in the stored tree — already save-transformed (defaults filled, empty children removed). Stage hidden with element_set_status(status:false). Prop names are snake_case. Common traps: `content` (not `title`) on button_item/headline/list_item/quotation/text; check `element_type_get_schema` first. The answer carries no `props`, only the new address. The stored node also carries the element's defaults — read it back with element_get. |
+| `yootheme_builder_element_bind_source` | write+destructive+idempotent | `arguments`, `bindingLevel`, `confirm`, `directives`, `element_path`, `etag`, `field`, `field_mappings`, `layout_id`, `probe`, `query_arguments`, `relation`, `site_id`, `source_id`, `source_name` | Bind 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); leaf under a #parent fragment → INHERIT (`__node_item__`); a standalone query renders empty. Map: bind `map_item`, map `location` to a "lat,lng" field or no markers. Requires ETag. Live at once. CONVENIENCE half of a pair — plain field names, but it REPLACES `source.props` whole, never merges; element_set_source is the CAPABILITY half. A re-bind that would drop anything already bound answers with a preview until you repeat it with `confirm: true`. To remove a binding, call element_unbind_source. |
+| `yootheme_builder_element_clone` | write+non-idempotent | `element_path`, `etag`, `layout_id`, `site_id`, `to_index`, `to_parent_path` | Clone an element. Default: as a sibling right after the source; pass `to_parent_path` to drop the copy elsewhere in the SAME template instead. Renumbers later siblings: `renumbered_siblings` names each moved sibling address (absent if none). Requires ETag. Live at once — stage hidden with element_set_status(status:false). |
+| `yootheme_builder_element_delete` | write+destructive+non-idempotent | `confirm`, `element_path`, `etag`, `layout_id`, `site_id` | PERMANENTLY delete an element + children. Cannot be undone. Pass `confirm: true` AND a fresh ETag. Preview: neither. A real delete returns `deleted:true` and NO `requires_confirmation` key; a returned `requires_confirmation:true` means NOTHING was deleted. `renumbered_siblings` names each moved sibling address (absent if none). Live at once. Hide instead: element_set_status(status:false). |
+| `yootheme_builder_element_get` | read+idempotent | `element_path`, `fields`, `layout_id`, `max_chars`, `site_id` | Get the full element object at a JSON-Pointer path, including props and a `children_count` (not the children — use element_list with root_path). On a `module`/`module_position` element it also returns `resolved` (the referenced widget/module row) plus `resolved_reason` when it could not be resolved. `max_chars` bounds the text output. |
+| `yootheme_builder_element_get_binding` | read+idempotent | `element_path`, `layout_id`, `max_chars`, `site_id` | Read the source binding on an element. Returns {layout_id, element_path, binding, has_binding, bound_via_item, item_binding?}: on a multi-item container (grid/slideshow/accordion/...) the binding sits on the `*_item` CHILD, so `has_binding:false` there does NOT mean static — read `bound_via_item`/`item_binding` first. Site-wide REVERSE question (which elements hang on a source): yootheme_builder_layout_query (gateway-only), OMIT layout_id. To remove what this returns, call element_unbind_source. |
+| `yootheme_builder_element_list` | read+idempotent | `cursor`, `depth`, `fields`, `include_meta`, `layout_id`, `limit`, `max_chars`, `root_path`, `site_id` | List elements in a template as a flat array with JSON-Pointer paths + types + `label`. Scope with `root_path`/`depth`, paginate with `limit`/`cursor`. Rows carry BOTH addresses: `path` (absolute) and `rel_path` — `rel_path` is the one write calls take as `element_path`. To find WHERE a module/widget is used, call local_content_read (gateway-only), never loop this per page. |
+| `yootheme_builder_element_move` | write+idempotent | `element_path`, `etag`, `layout_id`, `site_id`, `to_index`, `to_parent_path` | Move an element to a new parent + index in the tree — reordering or reparenting. Renumbers siblings at BOTH ends: `renumbered_siblings` names each moved sibling address (absent if none). Requires ETag. Live at once. |
+| `yootheme_builder_element_set_source` | write+destructive+idempotent | `confirm`, `element_path`, `etag`, `layout_id`, `site_id`, `source`, `source_extended` | Surgically SET a precomposed `source` (+ optional `source_extended.props`) on ONE element at a pointer, ETag-locked. Use this — not element_bind_source — when you need `source_extended.props`, which bind_source cannot write. CAPABILITY half of a pair — it also REPLACES `source.props` whole, never merges; element_bind_source is the CONVENIENCE half. Element-prop keys the type does not render echo back as `unknown_prop_keys`. WHOLE-NODE write: whatever you do not send is REMOVED. Omitting `source_extended` clears it exactly like passing `null`, and a `source` without `props` drops every prop mapping. Re-send what you want to keep. A call that would drop existing mappings answers with a preview until you repeat it with `confirm: true`. Live at once. To remove a binding entirely, call element_unbind_source. |
+| `yootheme_builder_element_set_status` | write+idempotent | `element_path`, `etag`, `layout_id`, `site_id`, `status` | Enable or disable an element via its `props.status` field — the SAME field YOOtheme's own native "Disable element" checkbox writes. status:false excludes the element and its descendants from BOTH the live render and live findings; pages_audit (gateway-only) and template_summary content_nodes both honour it. Requires ETag. Live at once. |
+| `yootheme_builder_element_type_get_schema` | read+idempotent | `element_type`, `field_names`, `fields`, `include_fields`, `max_chars`, `name_contains`, `site_id`, `type_name` | Prop schema; read before element_add/element_update_settings: undeclared keys are STORED, not refused: warns unknown_prop_keys. NO element_type: lists the types. With one: head only — binding_contract (containers/items) + groups[] + field_count. include_fields:true adds every descriptor {name,type,label?,text?,description?,enum?,value_hint?,group?,no_effect?}; Select descriptors: field_names/name_contains, answered with field_count/returned_count. value_hint+enum first: some defaults are SEO-fatal (headline.title_element→h1); checkbox = boolean true/false; no_effect = read by nothing, never write it; group:"runtime-accepted" = honoured at render, hidden in UI. Bound size with fields[]/max_chars. |
+| `yootheme_builder_element_types_list` | read+idempotent | `fields`, `include_meta`, `site_id` | List element types registered on this site (built-ins + YOOessentials extras). Names feed `element_type` of element_add. "slider"/"carousel" → `slideshow`/`panel-slider`/`overlay-slider`. Prop keys differ per element — use element_type_get_schema before element_add/bind. |
+| `yootheme_builder_element_unbind_source` | write+destructive+idempotent | `confirm`, `element_path`, `etag`, `layout_id`, `site_id` | Remove the source binding from an element — the counterpart to element_bind_source. Clears the canonical top-level `source` key AND the legacy `props.source` — may break dynamic-content rendering, always ask the user to confirm. ETag on the unbind only. Live at once. |
+| `yootheme_builder_element_update_settings` | write+idempotent | `element_path`, `etag`, `layout_id`, `merge`, `name`, `props`, `site_id`, `unset` | Update `props` on an element. Default replaces all props; pass `merge:true` for server-side deep-merge (only request keys overwritten). Requires ETag. `unset:["key",…]` resets props to their YOOtheme default and is valid ON ITS OWN: sent without `props`, it removes only those keys and touches nothing else. Send `props`, `unset`, or both — a call with neither is refused. Live at once. |
+| `yootheme_builder_fetch_public_url` | read+idempotent+openWorld | `expect`, `max_excerpt_chars`, `site_id`, `url` | The independent proof a publish reached visitors: fetches a page of the CONFIGURED site over the public network as an ANONYMOUS visitor — no login/cookies/Bearer — and reports http_status, page_title, an EXCERPT (never the whole document), html_bytes, and whether a cache served it (cache_verdict; "unknown" means no header said, NOT that nothing cached, and no re-fetch settles it — purge the cache instead). With `expect` it answers expect_found true/false. Refuses any address outside the configured site and never follows a redirect off it — an unrestricted fetcher is an open proxy. Get the url from `frontend_url` (pages_list / page_publish). Searches the WHOLE page (header, menu, footer too); a hit is no proof of THIS layout. render_preview renders ONLY that layout tree, never the theme wrapper. |
+| `yootheme_builder_get_etag` | read+idempotent | `site_id` | Get the current site-wide ETag for optimistic locking. ANY write to ANY template bumps it — a 412 means the site state advanced, not necessarily your template. Same token page_get_layout/element_list return. Pass back as `etag` on writes; on 412, re-read and retry. The ETag is SITE-wide, not per template — that is why this tool takes no `layout_id`. |
+| `yootheme_builder_get_skill` | read+idempotent | `site_id`, `topic` | Read a chapter of the full workflow guide. Without `topic`: the list of available topics, each with the SIZE of what it returns. With `topic`: that chapter. The connect-time `instructions` carry only a short preamble — this is how you reach the rest. A long chapter is served in PARTS: its row lists their slugs, and asking for the parent returns the chapter intro plus that list. A row carrying `oversized_note` is served whole and is large — read the note before asking for it. |
+| `yootheme_builder_header_transparency_set` | write+idempotent | `acknowledge_contrast_risk`, `dry_run`, `etag`, `layout_id`, `mode`, `pull_content_behind`, `site_id`, `text_color`, `transparent` | Inspect + repair the transparent header. Always targets the FIRST section — later ones are silently dead. dry_run defaults TRUE: returns current state + the theme-declared --uk-inverse, risk_class, recommendation. mode:"auto" writes the theme-declared colour; over a hero image/video it writes NONE and says LOOK. mode:"explicit" refuses a colour contradicting the theme (409) unless acknowledge_contrast_risk. transparent:false is always allowed. |
+| `yootheme_builder_heading_outline` | read+idempotent | `layout_id`, `max_chars`, `mode`, `site_id` | A real, doc-order H1-H6 outline of ONE template, each heading with its source element, plus alt-status of every image. Structure inspection, not findings — use pages_audit for site-wide SEO findings. One row per CARRIER: a container whose bound item repeats appears once, while template_summary.heading_levels counts it once per rendered row. |
+| `yootheme_builder_health` | read+idempotent | `site_id` | Check plugin installed/reachable. Returns plugin version, YT Pro version, REST endpoints, site_url, home_url on both platforms; wp_version + yooessentials_version are WordPress-only. available_endpoints is derived from the live route registration on both platforms; every path is request-ready as printed. served_areas lists the tool areas this server serves (was `capabilities` — kept one release as an alias). Multi-site: pass `site_id`, else this checks the active/default site. `write_rate_limit` = the write cap this site enforces, per BEARER KEY: everything sharing the key shares it. See diagnose for Bearer-validity + connectivity. |
+| `yootheme_builder_image_import` | write+idempotent | `full_url`, `site_id`, `url` | Sideload a photo into the site's Media Library. Only Unsplash, Pexels and the YOOtheme library CDN are accepted; other hosts are refused. Returns `{imported:true, local_url}`; shape is platform-specific: WordPress leads with a slash (/wp-content/uploads/...), Joomla does NOT (images/yootheme/...). Bind it VERBATIM via element_update_settings({props:{image: local_url}, merge:true}). Give the address as `url` OR as `full_url`, the field name an image_search row carries; one of the two is required. Identical re-imports reuse the existing file in the current upload folder. Failures return `{imported:false, reason, failure}`; `unavailable` = no url works now. |
+| `yootheme_builder_image_search` | read+idempotent | `color`, `include_meta`, `offset`, `orientation`, `per_page`, `query`, `site_id`, `source` | Search on-topic photos (Unsplash/Pexels), YOOtheme Pro Images, or (source:"local") this site's own media library. Rows carry `full_url` (feeds image_import) plus dimensions/author. `total:0` is the ONLY shape meaning the provider matched nothing; a search that never happened answers an `error_code` instead. No apikey gives `image_search_api_key_not_configured`; a provider that REFUSES gives `error_code: image_search_unavailable`, which no broader query can fix. A key can be CONFIGURED and still be REFUSED (401): report that the upstream refused it, never why (source:"local" is exempt — see its field description). Works on WordPress and Joomla. |
+| `yootheme_builder_inspect_multi_items_binding` | read+idempotent | `element_path`, `layout_id`, `site_id` | Reports Multi-Items binding state: container/item pair (grid↔grid_item, map↔map_item, …), binding level (none\|container\|item), recommended_fix. For map/map_item, a bound item without a `location` field is flagged as a blocking map_location_warning (0 markers). If rows render as ONE comma-joined string, see clean_implode_directives (gateway-only). |
+| `yootheme_builder_inspect_sublayout` | read+idempotent | `element_path`, `layout_id`, `max_chars`, `site_id` | Inspects a panel/grid_item `< SUBLAYOUT`: lists the `fragment` subtree bindable leaves and the render-time inner grid. Flags `ungated_grid_prop`: grid props set but the gate unsatisfied → silent no-op. For container↔item binding see inspect_multi_items_binding. |
+| `yootheme_builder_layout_query` | read+idempotent | `content_contains`, `cursor`, `element_type`, `fields`, `has_binding`, `has_implode_directives`, `include_meta`, `layout_id`, `limit`, `max_chars`, `max_depth`, `max_paths`, `name_matches`, `site_id`, `source_name`, `under_section` | TWO scopes. OMIT layout_id → SITE-WIDE: binding counts per `source_name` (COUNTED, never resolved — a source that no longer exists counts like a live one; pages_audit flags those as `dangling-source`, with paths), `max_paths` for individual paths, `has_implode_directives:true` to locate the comma-joining leftovers. WITH layout_id → ONE layout, AND-combined `element_type`, `name_matches`, `content_contains` (case-insensitive substring of `content`/`title`/`meta` props), `has_binding`, `under_section`; paginate `limit`/`cursor`. Mixing scope arguments is REFUSED, never dropped. To find WHERE a module/widget is used call local_content_read (kind:"modules"). On a module/module_position row `label` is the builder-assigned element name, NOT the module title: read element_get(.resolved). |
+| `yootheme_builder_library_browse` | read+idempotent | `cursor`, `element_type`, `has_effects`, `include_meta`, `kind`, `limit`, `purpose`, `query`, `role`, `site_id`, `source`, `topic`, `type`, `website` | Browse the YOOtheme Pro Library catalog: pre-designed page LAYOUTS, element PRESETS, or purpose-classified SECTIONS. Filter: `kind`, `topic`, `type`/`role`, `element_type`, `purpose`, `query`. A section id is the composite "<layoutId>#<sectionIndex>" — feeds library_get/insert. `source`: "catalog" (default) or "ai" — YOUR saved entries from library_save_as, which library_delete removes again — both gateway-only, call via yootheme_builder_advanced({tool, arguments}). `total:0` = the catalog matched nothing; a read with no data answers `library_upstream_unavailable` or `library_api_key_not_configured`, never an empty page. |
+| `yootheme_builder_library_delete` | write+destructive+non-idempotent | `confirm`, `id`, `site_id`, `source` | Delete ONE saved entry from your "WootsUp AI Layouts" store (library_save_as writes into it) — pass the `id` from a library_browse(source:"ai") row. `source` defaults to "ai", the ONLY deletable store; the curated library is read-only, source:"catalog" returns 403. IRREVERSIBLE — requires confirm:true. |
+| `yootheme_builder_library_get` | read+idempotent | `id`, `include_thumbnail`, `kind`, `max_chars`, `site_id`, `source` | Fetch ONE Library layout or element preset by `id` — call after library_browse (items[].id feeds this). `include_thumbnail:true` adds an image (costs tokens). This DETAIL endpoint checks the key, browse does not: no key gives 503 library_api_key_not_configured, a refused key 503 library_upstream_unavailable. Report the refusal, not a cause. `source`: "catalog" (default) or "ai" for your own library_save_as (gateway-only) entries. |
+| `yootheme_builder_library_insert` | write+destructive+non-idempotent | `confirm`, `etag`, `id`, `images`, `index`, `insert_mode`, `kind`, `section_index`, `site_id`, `source`, `target` | Insert a Library item onto a page — call after library_get/browse. `target`: new_page, {template_id,element_path?} (splices onto the layout root, or a preset onto a Column), or sublayout. A preset (kind:"element") MUST target a Column (422 otherwise) — scaffold one with scaffold_section. `images`: "placeholder" (default) or "curated" (downloads to Media Library). Placement: `insert_mode` for layouts, `index` for presets. `etag` locks (412 if stale). `source`: "catalog" (default) or "ai" to insert your own saved entry. |
+| `yootheme_builder_library_save_as` | write+non-idempotent | `destination`, `name`, `site_id`, `source` | Save a page or subtree into a reusable library — the REVERSE of library_insert. `source`: {template_id, element_path?} (omit element_path to save the WHOLE page). `destination`: "ai" (default — your isolated "WootsUp AI Layouts", reusable via library_browse source:"ai") or "native" (YOOtheme's built-in My Layouts). |
+| `yootheme_builder_local_content_read` | read+idempotent+openWorld | `fields`, `include_children`, `include_meta`, `include_usage`, `kind`, `limit`, `max_chars`, `offset`, `parent_id`, `search`, `site_id`, `status`, `taxonomy`, `type`, `verify_on_urls` | Read native records for one `kind`: entities, terms (ids that archive-scope a Grid), users, fields, menus, media, or modules (Builder widgets). Paginated {items,total,next_offset}, clamped to what the key may see. A deleted page/article is not in the default list; `status` (kind:"entities" only) gives the exclusive trashed view; the response carries `trashed_total` unasked when one exists. Archive-scoping: read {kind:"terms",taxonomy:"category"}, pick a term id, bind a source with query_arguments:{id:<term_id>}. Call local_content_types first. |
+| `yootheme_builder_local_content_types` | read+idempotent | `fields`, `kind`, `max_chars`, `site_id` | Discover the site's NATIVE content landscape, native to WP/Joomla (no API Mapper) — {content_types, taxonomies, field_groups, capabilities, positions}; taxonomies include ACF/com_fields groups. Content-type and taxonomy rows carry `bindable` + `source_name` (null for native types — bind via element_bind_source by content-type name); field-group rows carry neither. `positions` (B23) lists every valid widget-area / theme-position value for modules_create/modules_update's `position` argument — read it here BEFORE a write, not from a 400 refusal after one; null when not determinable, never `[]` as a claim that none exist. Call first, then local_content_read for records. |
+| `yootheme_builder_modules_create` | write+non-idempotent | `base`, `cache`, `cache_time`, `cachemode`, `class_sfx`, `content`, `dry_run`, `endLevel`, `layout`, `menutype`, `moduleclass_sfx`, `placement`, `position`, `showAllChildren`, `showtitle`, `site_id`, `startLevel`, `tag_id`, `text`, `title`, `type`, `window_open` | Create a widget (WordPress: custom_html/text/block) or module (Joomla: mod_custom/mod_menu), exactly five known types. REQUIRES placement (position, module_element or position_element): a call without it creates nothing and returns ways (every way this platform offers) plus notes. `position` is validated server-side against what this site declares and must agree with placement. content/text stored byte-for-byte, never sanitized. dry_run defaults TRUE, creates nothing; a real create returns the full row PLUS next_step, the exact follow-up call for the placement you chose. Gateway-only, not in tools/list — call via yootheme_builder_advanced. |
+| `yootheme_builder_modules_delete` | write+destructive+non-idempotent | `acknowledge_element_refs`, `confirm`, `id`, `intent`, `site_id` | Delete a widget (WordPress) or module (Joomla) — the clean-up verb create/update lacked. Needs `intent`: call once without it and the server lists which are possible for this module's CURRENT state, each with its own effect. confirm defaults FALSE: returns the row plus usage.element_refs and changes NOTHING. A DIRECT layout reference blocks the irreversible step (409) until acknowledge_element_refs:true. |
+| `yootheme_builder_modules_update` | write+idempotent | `access`, `active`, `assignment`, `content`, `dry_run`, `id`, `ordering`, `position`, `showtitle`, `site_id`, `theme_overlay`, `title` | Update a widget/module's writable subset: title, content (byte-identical), position, active, theme_overlay; plus showtitle, ordering, access, assignment on Joomla. dry_run defaults TRUE, returns {before, after, changed, notes}, writes nothing. Refused: title on a WordPress block widget (it has none), a position this site does not declare (either platform, same error_code as modules_create), and active:true while a Joomla publish window leaves it scheduled/expired — there active means published AND that window. Joomla: active:true also lifts a module out of the trash, PUBLISHED not as it was. position:"" clears the position on Joomla, refused on WordPress (deactivate with active:false instead). Gateway-only, not in tools/list — call via yootheme_builder_advanced. |
+| `yootheme_builder_navigation` | read+idempotent | `menu`, `site_id` | The site's navigation menus as a parent→children TREE, not a flat list — "which page is under which menu item". Each item carries a `page_role` facet and, when derivable, a `target_page` ready for page_get_layout. |
+| `yootheme_builder_page_generate_dynamic` | write+non-idempotent | `conditions`, `dry_run`, `element_path`, `etag`, `layout_id`, `leaf_map`, `list_source_name`, `output`, `page`, `remove_leaves`, `section_name`, `site_id`, `source_map` | Copies a designed section byte-identically into a NEW, unpublished, unlinked page and swaps only what you map — it never edits the reference. Requires output:"new_page" (today's only value; "in_place" is not yet available). Give a REFERENCE (section_name or element_path) + list_source_name + a leaf_map. A section with several source blocks dynamizes in ONE call via source_map. Preview with dry_run:true (a would_change:false answer carries `reason`). Live at once — stage hidden with element_set_status(status:false). The response carries `cms_visibility.findable_by_visitor`: can a visitor FIND this one page via a navigation path? It reads the menu route AND the access level, which the per-row `visibility` of pages_list does not. Cannot make it the site front page (a CMS menu setting). |
+| `yootheme_builder_page_get_layout` | read+idempotent | `fields`, `flat`, `force`, `include_modules`, `layout_id`, `max_chars`, `mode`, `site_id`, `url` | Get the layout tree for one layout — address by `layout_id` or `url`. `mode:"bindings_only"` for dynamize/bind. Over `max_chars` whole entries DROP (`truncated`+`omitted_count`; outline cuts its text) and NOTHING pages the rest — no cursor in any mode. Narrow instead: `mode:"outline"` to map, then element_list(root_path). For a site-wide SEO/structure audit do NOT loop this tool page-by-page — call yootheme_builder_pages_audit (gateway-only). For ONE narrow question (e.g. "where is the binding" or "which elements have type X") this whole-template read is heavier than it needs to be — prefer yootheme_builder_layout_query (gateway-only; has_binding/element_type/name_matches filters) or element_list with `root_path` to scope the walk. |
+| `yootheme_builder_page_publish` | write+idempotent | `cms_status`, `etag`, `layout_id`, `menu_item`, `quick_check`, `site_id` | Publish a template's LAYOUT — persist state, flush the plugin's own caches (a page-cache/CDN plugin is NOT purged: purge it yourself, then verify with fetch_public_url), snapshot the ETag; "publish" ALSO means the CMS post status, and this tool does not change that, so a draft page stays invisible. Step (2) of the three page_save describes; pages_set_status is step (3). ETag required — 412 on conflict. Answers `cms_visibility.findable_by_visitor`: can a visitor FIND this one page via a navigation path? It reads the menu route AND the access level, which the per-row `visibility` of pages_list does not. Optional `cms_status` folds step (3) into this call for the common build-it-and-make-it-live case; without it nothing about the CMS status changes. |
+| `yootheme_builder_page_save` | write+idempotent | `dry_run`, `etag`, `layout`, `layout_id`, `quick_check`, `site_id` | Re-run save-transforms + flush the plugin's own caches. Optional whole-tree replace via `layout` — the INNER {type:"layout",children:[...]} tree, NOT page_get_layout's whole response (rejected 422). THREE separate steps, and this is the first: (1) page_save replaces or re-normalises the stored tree — every write, element or whole-tree, runs the same save-transforms; (2) page_publish snapshots the ETag and flushes them; (3) pages_set_status decides whether a visitor may see the page at all. This call does NOT do (2) or (3). Response `previous_layout` is the tree right before THIS call, not before your edits (element writes already landed) — identical to what you just wrote is normal when the transforms change nothing. `dry_run:true` preflights, no ETag. ETag on the save (428/412). |
+| `yootheme_builder_pages_audit` | read+idempotent | `checks`, `include_meta`, `include_modules`, `max_chars`, `mode`, `site_id`, `stale_after_months`, `target`, `thin_content_threshold`, `types` | One-call site-wide SEO / structure / content / links / design audit — severity-sorted findings with fix_hints (a props fragment to merge). Covers heading structure and accessibility (h1/heading-skip), image alt text, thin content, duplicate layouts, title collisions, broken in-page anchor links (same-page `#id` jumps only — no external link is ever fetched or resolved), and design consistency (markup outside the UIkit design system, header/navigation contrast). Only active (non-disabled) nodes produce findings. `target` scopes to ONE page for the full set. SEO-plugin meta (title/description/OG) NOT covered. |
+| `yootheme_builder_pages_create` | write+non-idempotent | `dry_run`, `layout`, `menu_item`, `published`, `site_id`, `slug`, `status`, `title` | Create a page (WordPress) or article (Joomla 5/6) with a per-page layout. Required: title. Optional: status (default draft), layout, menu_item, dry_run (preflight, no persist). Joomla: a published article has NO SEF route until a menu item points at it — pass menu_item for a navigable url. Cannot make it the site front page: which page answers / is a CMS menu setting this server never writes. pages_list marks the current one with is_public_homepage. |
+| `yootheme_builder_pages_delete` | write+destructive+non-idempotent | `confirm`, `intent`, `layout_id`, `site_id` | Delete a page (WordPress) or article (Joomla 5/6). OMIT confirm to preview: returns 200 with label, elements_count, what happens to media, and the intents this page's state allows, and deletes nothing. confirm:true + an intent carries it out. Already-trashed returns 200 {deleted:false, already_trashed:true}, not an error. |
+| `yootheme_builder_pages_list` | read+idempotent | `cursor`, `fields`, `include_meta`, `label_contains`, `limit`, `max_chars`, `site_id`, `sort`, `visibility` | List pages, templates and layouts. Each row returns `kind` (content \| theme_template) plus serves_context_kind, serves_context_ids and page_role — the template ROLE (WHICH objects it renders for), NOT a data binding; for who-binds-what call layout_query with no layout_id. The envelope returns `totals`. Call first for layout_id (page_get_layout/element_list). `type` = PAGE type, not element type (those filter on `element_type`). Rows with a CMS status carry `visibility`: public \| hidden \| undetermined, never empty. Reads STORED FIELDS only — status, plus WordPress password protection (`hidden`, with the reason). It does NOT read the menu route, the access level, or whether the permalink resolves, so Joomla rows stay `undetermined`; for THAT verdict read `cms_visibility.findable_by_visitor` from pages_set_status / page_publish — a different, per-page question. Page contents (SEO/structure/links/modules): yootheme_builder_pages_audit. `is_public_homepage` marks the one row served at / (the site front page); no tool here moves it. |
+| `yootheme_builder_pages_resolve` | read+idempotent | `site_id`, `target`, `url` | Resolve a page/article/archive URL to the layout_id that renders it. SEF/pretty permalinks resolve on both WordPress and Joomla. A category/term resolves to the SPECIFICALLY-ASSIGNED template (honoring include-child-categories), not a generic one. Returns {layout_id, post_id, type, frontend_url, context, resolved_via}. |
+| `yootheme_builder_pages_restore` | write+non-idempotent | `layout_id`, `site_id` | Restore a TRASHED page (WordPress) or article (Joomla) — the one correct way back (pages_set_status refuses a trashed page with 409 naming this tool). WordPress: reinstates the EXACT pre-trash status (core defaults restores to draft since 5.6) and attempts to reclaim the pre-trash slug — a hand-rolled write leaves the "__trashed" suffix instead; a slug another page has since taken comes back different — check the response's frontend_url. Joomla stores no pre-trash status, so this can only set state to unpublished (visible to editors, not visitors); call yootheme_builder_pages_set_status with status:"published" afterwards to make it visible. Not currently trashed → refused (409). Find a trashed id with yootheme_builder_local_content_read({kind:"entities", status:"trash"}). |
+| `yootheme_builder_pages_set_status` | write+idempotent | `layout_id`, `site_id`, `status` | Change the CMS status of an EXISTING page (WordPress) or article (Joomla) — keeps its id and URL. Step (3) of the three page_save describes. Use YOUR platform's own words: WordPress publish, draft, pending, private, future; Joomla published, unpublished, archived — the other platform's word is refused (422). Status is RE-READ after the write. To trash or delete use yootheme_builder_pages_delete; a page already IN the trash is refused (409) — use yootheme_builder_pages_restore first. The response carries `cms_visibility.findable_by_visitor`: can a visitor FIND this one page via a navigation path? It reads the menu route AND the access level, which the per-row `visibility` of pages_list does not. |
+| `yootheme_builder_render_preview` | read+idempotent | `expect`, `layout_id`, `site_id`, `url` | Render-check a SAVED layout. Address by `layout_id` or `url`. rendered_item_wrapper_count counts the repeat-item wrappers rendered, BOUND OR NOT, so a 0 is not evidence a binding failed (per-source rows: `source_item_counts`). Distinct from pages_list `elements_count` (all tree nodes). A source the registry cannot resolve is named in `unresolved_sources`, not just a smaller count. Renders ONLY the page's own layout tree, never the theme wrapper: a MISS with `expect` proves nothing beyond the tree (adds {matched, snippet, match_conclusive, match_note, mismatch_hints, stored_but_not_rendered — the last names elements that DO store the text but rendered no rows}). A Joomla module/module_position element sharpens this — EXCLUDED (fallback_used:true) or silently empty (dropped_count:0) — but match_conclusive:false marks EVERY inconclusive miss. Reports CMS status in `cms_status`/`cms_status_note` (absent for a theme template); pages_set_status remains the tool that changes it. |
+| `yootheme_builder_repair_source_references` | write+idempotent | `allow_unregistered`, `dry_run`, `etag`, `field_map`, `from`, `layout_id`, `site_id`, `source_map`, `to` | Repairs binding REFERENCES to a source/type/field name in ONE template, in one ETag-locked write, after that name changed OUTSIDE the builder (a taxonomy/CPT rename, a re-published flow). Does NOT rename the source itself — sources_list stays unchanged. Pass `from`/`to` for one token, or `source_map`/`field_map` for several. Preview with dry_run:true. |
+| `yootheme_builder_scaffold_section` | write+non-idempotent | `column_widths`, `columns`, `etag`, `layout_id`, `site_id` | Create a VALID section → row → column hull in ONE call; returns the column path(s) for content. Only `section` may sit at the layout root; leaf/content elements are rejected anywhere except inside a `column`. Pass `columns` (1-12) or `column_widths` for an asymmetric row. Requires ETag. |
+| `yootheme_builder_sites_list` | read+idempotent | `include_meta`, `site_id` | List all sites configured in this multi-site MCP installation — site_id, URL, platform, DEFAULT + ACTIVE flag per row. Call first to discover site_ids. A call omitting site_id goes to `active_site_id` (set by use_site, process-wide) else to `default_site_id`. Pass `site_id` to FILTER to one site; omit it for all. IDs from any tool (layout_id, element ids, …) are PER-SITE, never global: the same id can exist on a different site naming something else entirely. Always keep an id paired with the site_id it came from. |
+| `yootheme_builder_sites_overview` | read+idempotent | `include_meta`, `include_pages`, `max_chars`, `site_id` | Every configured site in ONE call: reachability, Bearer validity and page counts per site, probed in parallel. Replaces sites_list plus one sites_test and one pages_list per site. A site that is down becomes a row with an `error`, never a failed call. Pass `site_id` to narrow to one site; `include_pages:false` skips the page read (one HTTP request per site less). The content/theme_template split is absent on hosts that do not report it — never reported as zero. |
 | `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_source_get_schema` | read+idempotent | `max_chars`, `name`, `site_id` | Introspect ONE data source: its query methods + arguments + RELATIONS (e.g. Term→Posts: categoryFaqs.taxonomyCategoryFaq → field "faq") + a provides_archive_context flag (id:0 = current archive term, auto-scoped). SOME arguments carry `enum_values` (the allowed values); when an arg has none it is a free string — pick from enum_values when present, never invent values. CALL BEFORE binding on an archive/category template. Keywords: source schema, relations, archive context, enum values. Get `name` from yootheme_builder_sources_list. |
-| `yootheme_builder_sources_list` | read+idempotent | `cursor`, `fields`, `group`, `include_meta`, `kind`, `limit`, `max_chars`, `name_contains`, `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. Keywords: list sources, list feeds, list bindings, dynamic content, what sources exist. Paginates (`limit`/`cursor`/`total`); scope with `group`/`kind`/`name_contains`; slim with `fields[]`; bound output with `max_chars`. |
-| `yootheme_builder_template_set_type` | idempotent | `dry_run`, `etag`, `site_id`, `template_id`, `type` | Reassign which archive/single a YOOtheme THEME template applies to — set its `type` condition (the value pages_list shows) in ONE ETag-locked write. Use after a taxonomy/CPT rename orphans a template (e.g. re-type "taxonomy-category_faq" → "taxonomy-category_help"). Returns {type, previous_type, new_etag}. Site-wide + immediate — preview with dry_run:true, reversible via previous_type. THEME templates only: page:/article: is refused (422). ETag req. |
-| `yootheme_builder_template_summary` | read+idempotent | `cursor`, `include_nodes`, `limit`, `site_id`, `template_id`, `template_ids` | 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. Pass `include_nodes:true` for a `content_nodes` per-node breakdown (status/effective_visible/headings/alts), pageable via `limit`/`cursor`. Pass `template_ids:[...]` for a batch: response carries `summaries` + `not_found`. Example: yootheme_builder_template_summary({ template_id: "default" }). |
-| `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. |
+| `yootheme_builder_source_get_schema` | read+idempotent | `max_chars`, `name`, `site_id`, `source_name` | Introspect ONE data source: query methods + arguments + RELATIONS (e.g. Term→Posts: categoryFaqs.taxonomyCategoryFaq → field "faq"). `is_archive_context_provider` says whether the source CAN follow the current archive term; it does NOT say whether the source returns rows here — only a render answers that (element_bind_source with probe:true, or render_preview). Some arguments carry `enum_values` — pick from those when present, never invent values. Call before binding on an archive/category template. Get `name` from sources_list. |
+| `yootheme_builder_sources_list` | read+idempotent | `cursor`, `fields`, `group`, `include_meta`, `kind`, `limit`, `max_chars`, `name_contains`, `site_id` | List data sources/feeds available in the builder — name + label + origin + `group` per source. Call before binding an element with element_bind_source. `group` is what a source answers FROM: a "Page"-group LIST source serves the CURRENT page/archive context, so a standalone page gets zero rows from it. Each row says so in `context_note` when it applies. A long list narrows with `group` (the ORIGIN bucket: apimapper \| wordpress \| joomla \| essentials — not the per-row `group` column above), `name_contains`, or `kind`. Reach for one before paging. WHERE a source is used, site-wide: yootheme_builder_layout_query (gateway-only), OMIT layout_id. |
+| `yootheme_builder_template_set_type` | write+idempotent | `dry_run`, `etag`, `layout_id`, `site_id`, `type` | Reassign which archive/single a YOOtheme THEME template applies to — set its `type` condition in ONE ETag-locked write. Use after a taxonomy/CPT rename orphans a template. Site-wide + immediate — preview with dry_run:true, reversible via previous_type. THEME templates only: page:/article: refused (422). |
+| `yootheme_builder_template_summary` | read+idempotent | `cursor`, `include_nodes`, `layout_id`, `layout_ids`, `limit`, `site_id` | Token-efficient template overview: element counts by type, bindings, max depth, named sections — computed server-side in one call. Use before element_list/page_get_layout on a large template. `include_nodes:true` adds a `content_nodes` per-node breakdown (status/effective_visible/headings/alts), pageable via `limit`/`cursor`. `layout_ids:[...]` batches several: response carries `summaries`, `not_found` and `forbidden`. Example: yootheme_builder_template_summary({ layout_id: "default" }). |
+| `yootheme_builder_use_site` | write+idempotent | `probe`, `site_id` | Switch the ACTIVE site for this session — subsequent calls that omit `site_id` target it. NOTE: this default is PROCESS-WIDE — concurrent clients sharing this MCP server inherit it; pass `site_id` per call for isolation. Runs a /health + /etag probe by default; `probe:false` switches offline. `site_id` is REQUIRED. |
 
 <!-- TOOL-CATALOG:END -->