@wootsup/yt-builder-mcp 1.11.0 → 1.12.0

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

@@ -12,15 +12,15 @@ 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 49 typed, scoped,
-idempotent tools (51 callable end-to-end with the two gateways). 41 of them
+`@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
 advertised as first-class entries in `tools/list`
-(37 essential L1 forwards + 2 direct L3 entries + 2 gateways), and 10 advanced
+(38 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 10; the read-only
+`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,
-local_content_read, pages_audit) and is itself
+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.
@@ -54,8 +54,8 @@ 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 41 first-class tools (37 essential, 2 direct, 2 gateways).
-  The `yootheme_builder_advanced` gateway routes all 10 advanced tools; the
+  Provides the 42 first-class tools (38 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.
 - **`Von YT Builder MCP for YOOtheme Pro`**: the bundled **skill** (this
@@ -82,9 +82,9 @@ 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.
-- **37 essential forwarded tools**: common reads + the most-used writes
+- **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 / get / move / clone / delete,
+  get_etag, 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,
@@ -99,7 +99,7 @@ The server exposes:
   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` (Glöckle HANDOFF-4/5) are L1 so the core write/refactor +
+  `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
@@ -125,11 +125,14 @@ The server exposes:
   step that turns a placeholder-filled skeleton into a finished-looking
   page (see "Fill image slots with real on-topic photos" under Layout
   Library).
-- **10 advanced captured tools**: everything else (page_get_schema,
+- **13 advanced captured tools**: everything else (page_get_schema,
   element_unbind_source, clean_implode_directives,
   `inspect_sublayout`, `layout_query`, `library_save_as`, the two Local
   Content Read tools `local_content_types` / `local_content_read`,
-  `pages_audit`, and `library_delete` — the INVERSE of `library_save_as`).
+  `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).
   Reachable through one gateway tool:
   `yootheme_builder_advanced({ tool: "<name>", arguments: { ... } })`. For
   example, to inspect a panel/grid_item `< SUBLAYOUT`:
@@ -156,8 +159,31 @@ The server exposes:
   `yootheme_builder_advanced_read({ tool: "yootheme_builder_pages_audit", arguments: { checks: ["seo", "structure"] } })`
   (the write gateway routes it too, if you prefer one entry point:
   `yootheme_builder_advanced({ tool: "yootheme_builder_pages_audit" })`).
-
-  The core write/refactor + render-verify tools the Glöckle HANDOFF-4/5 ask for
+  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 } })`
+  (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"
+  (product pages usually live in the main menu), each item carrying a
+  `page_role` facet (home/landing/product/legal/thankyou/blog/mockup/
+  template/generic, the SAME vocabulary `pages_list` uses) and, when
+  derivable at zero extra cost, a `target_page` (`page:<id>` /
+  `article:<id>`) ready for `page_get_layout`:
+  `yootheme_builder_advanced_read({ tool: "yootheme_builder_navigation" })`
+  (or via the write gateway: `yootheme_builder_advanced({ tool: "yootheme_builder_navigation" })`).
+  Pass `menu: "Footer"` to narrow to one menu by name.
+  And to inspect or repair the transparent header — the navigation pulled over
+  the first section — a WRITE, so the write gateway only. `dry_run` defaults to
+  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 } })`
+  Repeat with `mode: "auto", dry_run: false, etag` to write the theme-declared
+  colour. See "Transparent header (the exception — never a default)".
+
+  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
@@ -198,7 +224,7 @@ The server exposes:
   into delete/unbind, so hosts gate it) and `yootheme_builder_advanced_read`
   (read-only; routes ONLY the read-only advanced subset — page_get_schema,
   inspect_sublayout, layout_query, local_content_types, local_content_read,
-  pages_audit —
+  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 } })`.
@@ -209,9 +235,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 41 names (37 + 2 + 2). That's 37 L1
-essentials + 2 L3 direct + 2 gateways. The total callable surface is 51
-(41 advertised + 10 advanced reachable through the gateways). If the AI
+`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
 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
@@ -233,6 +259,23 @@ guess where the agent is pointing:
   template"): find the matching row, return `frontend_url` (resolved) or
   `frontend_url_template` (with placeholders the user fills in).
 
+### `available_endpoints` is request-ready, on both platforms
+
+`yootheme_builder_health` also returns `available_endpoints`: every REST path the
+host plugin actually serves. On **both** WordPress and Joomla this list is
+derived from the **live route registration** — WordPress enumerates
+`rest_get_server()->get_routes()`, Joomla reads the ApiRouter that matched the
+request — so it can never drift from what the server accepts.
+
+Use it as-is when documenting or probing a site's surface: **every path is
+request-ready as printed**, relative to the platform's REST root
+(`/wp-json` on WordPress, `/api/index.php` on Joomla). Captures appear as
+readable placeholders (`<templateId>`, `<path>`) that you substitute.
+
+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.
+
 Treat `frontend_url: null` as "host plugin could not resolve a public URL for
 this template". Surface that honestly rather than fabricating one.
 
@@ -280,6 +323,26 @@ serves_context_ids: [11] }`. Use `pages_resolve` when you just want the answer;
 use the `serves_context_*` columns when you already hold `pages_list` and want to
 match locally.
 
+**`page_role` on `pages_list` rows — a coarse content-role facet for filtering.**
+Every row also carries `page_role`, one of `home`, `landing`, `product`, `legal`,
+`thankyou`, `blog`, `mockup`, `template`, `generic`. It answers "which of these 80
+rows are actually PRODUCT pages?" without you guessing from names — filter the
+rows you already have by `page_role === "product"` instead of pattern-matching
+labels yourself. It is derived HEURISTICALLY from fields already on the row
+(URL slug, the raw YOOtheme type condition, the row's name) — a legal/thank-you/
+product/landing match comes from the URL path (`/impressum`, `/datenschutz`,
+`/danke`, `/produkt/…`); `home` comes from the site's authoritative front-page
+resolution OR the row's own URL being the bare site root; `blog` from a native
+WP post / Joomla article type; `mockup` from a designer's own "demo"/"mockup"/
+"placeholder" wording in the row's name; `template` from a bare internal
+condition. **`generic` is the honest default, not a bug** — exactly like an
+empty `serves_context_ids`, it means no signal fired, not that classification
+failed. Treat `page_role` as a filter/identification AID, not a guarantee: it
+never re-reads anything (zero extra calls), so it can occasionally miss a page
+whose role isn't visible from its URL/type/name — cross-check with
+`page_get_layout` when precision genuinely matters (e.g. before a destructive
+bulk action).
+
 ### Address a page WITHOUT its URL — the `target` object
 
 `pages_resolve` and `pages_audit` take the **same** `target` object, so one
@@ -359,7 +422,9 @@ never a transport failure — report it verbatim rather than retrying blindly.
 | `no_target` | 400 | A `target` WAS supplied but none of its members is a usable address — every member must be a **non-empty scalar**. `target[special][x]=y` (a nested value) and a templated `target[title]=` that rendered empty both land here. | Re-send with exactly one non-empty scalar key. Never re-send without a `target` "to see what happens": that is a whole-site sweep whose findings you would attribute to one page. |
 | `too_many_targets` | 400 | Two or more address keys, or `url` alongside `target`. | Pick one. Use `title` or `pages_list` when you only know the page by name. |
 | `types_conflicts_with_target` | 400 | `types` was sent with a `target`. | Drop `types` — a target already names exactly one page, so there is nothing for a type filter to narrow. |
-| `unknown_check_category` | 400 | A `checks` value that is not one of the four categories (`seo`, `structure`, `content`, `links`) — a typo, a finding CODE passed where a category belongs, or a case variant: the vocabulary is **case-sensitive**, so `SEO` is not `seo`. | Re-send with a real category (the message names both the unknown members and the valid set). This is refused rather than filtered because an unrecognised value selects ZERO checks, and zero checks over a normally-scanned site returns `findings: []` — a confident CLEAN verdict for a typo. **Never read such an answer as clean.** |
+| `unknown_check_category` | 400 | A `checks` value that is not one of the five categories (`seo`, `structure`, `content`, `links`, `design`) — a typo, a finding CODE passed where a category belongs, or a case variant: the vocabulary is **case-sensitive**, so `SEO` is not `seo`. | Re-send with a real category (the message names both the unknown members and the valid set). This is refused rather than filtered because an unrecognised value selects ZERO checks, and zero checks over a normally-scanned site returns `findings: []` — a confident CLEAN verdict for a typo. **Never read such an answer as clean.** |
+| `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. |
 | `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. |
@@ -714,6 +779,164 @@ section as the last child of the template root.
 
 ---
 
+## Transparent header (the exception — never a default)
+
+A transparent header pulls the page's **first** section up behind the site
+header and recolours the navigation over it. It only works over a hero medium
+that was made for it. **The default is: do not pull the section behind the
+header.**
+
+**Never turn `header_transparent` on by your own initiative** — not while
+scaffolding a hero, not while inserting a Library layout, not "because it looks
+more modern". Turn it on only when the customer asks for it, or when the
+template you inserted already ships a hero medium built for it. **When in
+doubt, leave it off.** That is always the safe answer, never a compromise.
+Whoever turns it on picks the colour deliberately; with no deliberate choice
+the colour is `""`, never `"light"`.
+
+### The three props (they live on a `section`)
+
+| Prop | Values | Read by YOOtheme only when |
+|---|---|---|
+| `header_transparent` | `true` / `false` | — (this is the master switch) |
+| `header_transparent_noplaceholder` | `true` / `false` | `header_transparent` is true |
+| `header_transparent_text_color` | `""` / `"light"` / `"dark"` | `header_transparent` is true |
+
+### Three traps that break pages silently
+
+1. **Only the FIRST section counts.** YOOtheme applies the transparent header
+   from the first section of the layout and ignores the props on every later
+   section — no error, no builder warning. "I set it and nothing happened" is
+   almost always this. Put the props on the first section, or remove them.
+2. **Setting the colour without the master switch does nothing.**
+   `header_transparent_text_color` / `header_transparent_noplaceholder` on a
+   section whose `header_transparent` is off are dead props. They read as
+   configuration and are never applied.
+3. **`"light"` is not a safe default — it is white navigation text.** The
+   recolour fires even when the section has no image, no video and no `style`,
+   so `"light"` over a light theme background is literally white-on-white. The
+   THEME already states which colour fits each section style (its compiled
+   `theme.css` declares `--uk-inverse` per style, e.g. `dark` for
+   `.uk-section-default`). Read that, or — where no image or video is in the way
+   — leave the colour at `""` and let the theme decide. Never assume `"light"`.
+
+**Over a hero image or video, no colour choice is provable from the layout
+alone.** The image hides the background the theme's declaration describes, and
+which part of a `cover` image ends up under the header depends on the viewport.
+
+Do not hand-write a colour there — and do **not** "play it safe" by pushing an
+existing one back to `""`. `""` is the theme's own default colour: a real
+rendered value, not an abstention. Over a dark hero on `.uk-section-default`
+(which declares `dark`) reverting to `""` puts dark navigation on a dark photo,
+which is the very break you were trying to avoid.
+
+Let the tool leave it alone — `mode: "auto"` writes NO colour over a medium —
+then LOOK at the rendered page (see "Look at what you built") at the customer's
+viewport — unscrolled AND after scrolling, because a
+sticky header drops its transparency on scroll. Then write what you SAW with
+`mode: "explicit"`. Do not guess a colour, and do
+not reason about "the top N% of the image".
+
+### Use `header_transparency_set` — do not hand-write these props
+
+`yootheme_builder_header_transparency_set` (advanced gateway) is the tool for
+all of this. It **always targets the first section**, touches only the three
+props, and **`dry_run` defaults to `true`** — so the first call is an
+inspection that writes nothing.
+
+```jsonc
+// 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" })
+
+// 2. REPAIR with the theme's own declared colour.
+yootheme_builder_header_transparency_set({
+  template_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>"
+})
+
+// 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",
+  dry_run: false, etag: "<latest>"
+})
+```
+
+`mode: "explicit"` refuses a colour the theme's declaration contradicts when no
+image or video hides that background (HTTP 409,
+`error_code: header_contrast_contradicts_theme`). Override with
+`acknowledge_contrast_risk: true` only after LOOKING at the rendered page.
+
+To undo it, call with `transparent: false` — the tool removes all three props,
+so no dead configuration is left behind. It is never refused —
+**turning transparency OFF is always safe and never needs a justification.**
+
+### Writing the props by hand — what `element_update_settings` refuses
+
+You *can* write the props by hand with `element_update_settings` (`merge: true`,
+on `/children/0`). That path now refuses the one mistake it can prove on its own,
+and quietly does the safe thing for the other:
+
+- **Dead props are rejected.** A `header_transparent_text_color` or
+  `header_transparent_noplaceholder` that this write leaves without a true
+  `header_transparent` comes back as
+  `error_code: header_transparent_dead_prop` and nothing is written. A prop
+  YOOtheme never reads is dead whatever the theme declares, so this needs no
+  theme knowledge. Note the merge semantics: `element_update_settings` REPLACES
+  props unless you pass `merge: true`, so a full-replace write that omits
+  `header_transparent` switches the header off.
+- **Turning it on without a colour writes `""`** — the theme's own default —
+  and tells you so. It is never defaulted to `"light"`. Under `merge: true` the
+  stored colour cannot be read from here, so nothing is seeded and you are
+  asked to state the colour yourself rather than have a guess clobber a value
+  you measured.
+- **Over a hero image or video the write is ALLOWED**, with a
+  `header_contrast_unverifiable_over_media` warning. Nothing is corrected there
+  — only your eyes can settle it (see "Look at what you built"). That warning
+  **only fires when THIS write states the `image`/`video` itself.** A medium
+  already stored on the section is not readable from here, so under
+  `merge: true` — the shape recommended just above — such a write goes through
+  **silently**. Read no warning as "there is no medium": the usual hand-write
+  (`merge: true` with only the header props, on a section that already has its
+  hero) is exactly that silent case. `pages_audit` and
+  `header_transparency_set` read the stored layout and do see it.
+
+**What that hand-write path still cannot check for you:** the **first-section
+rule** — a single element write does not know where its section sits in the
+layout — and the **theme declaration**, because the compiled `theme.css` is not
+readable from the MCP server. A colour that contradicts `--uk-inverse` therefore
+goes through untouched there. `header_transparency_set` and `pages_audit` are
+where both of those are checked.
+
+**You do not have to spot this by eye.** `pages_audit` carries two `design`
+codes for it. Both read the first section's props plus the theme's own
+`--uk-inverse` declaration for that section style out of the compiled
+`theme.css`:
+
+- **`header-contrast-risk`** (severity `warning`) — the layout forces a colour
+  the theme's declaration contradicts, and **no image or video covers** the
+  background that declaration describes. Provable from the props alone: the
+  recommended colour is the theme's own declared value, so it never guesses a colour.
+- **`header-contrast-unverifiable`** (severity `info`) — a transparent header
+  over a hero image or video, **whatever the colour**. The medium covers exactly
+  the background the declaration describes, so nothing is provable there and the
+  code recommends no colour at all: go and look at the page.
+
+The split is "is a medium in the way?", never "is the colour right?". Behind a
+hero medium no value is verifiable and none is safer than another — not even
+`""`, which is simply the theme's default colour. When `theme.css` cannot be
+read, both say nothing at all rather than judging on a hunch. See Workflow 6's
+remediation catalog.
+
+---
+
 ## Multi-column layouts (columns that sit side-by-side)
 
 **The single most common layout mistake: a `row` with several `column`
@@ -914,6 +1137,38 @@ version on a layout you read-modify-write is preserved, never overwritten.
 
 ---
 
+## Per-element render quirks (the single-element tail)
+
+The rules that apply to a whole CLASS of props ride in the schema itself:
+`element_type_get_schema` returns `renders_only_if`, `placeholder_fallback`,
+`blanked_by_parent`, `media_autoswap`, per-field `value_hint` / `no_effect` /
+`empty_means_inherit`, and a `rules` id list resolved by a `rule_notes` map
+(the `enable`-vs-render disagreements, the equal-height model, the `striptags`
+on link toggles, positional dependence, the collapse cascade, iframe video, the
+Maps API key, and link attributes under a lightbox). **Read those from the
+response, not from here.** The response also states which build they were read
+on — see `claims_verified_on` above.
+
+What follows is the tail: quirks that belong to ONE element and would cost more
+in schema bytes than they are worth. Each was read in the YOOtheme **5.0.37**
+source at the cited location — so on a site running a different build, treat
+this section the way `claims_verified_on: "differs"` asks you to treat the
+schema's own claims: a report to check, not a fact about your build.
+
+| Element / prop | The quirk |
+|---|---|
+| `grid.grid_divider` | The divider class is emitted only when the grid has **more than one child** (`grid/templates/template.php:44`, `=> count($children) > 1`). A one-item grid silently has no divider. |
+| `grid.grid_parallax_justify` | Setting it while `grid_parallax` is empty **forces `grid_parallax` to `'0'`** (`grid/templates/template.php:10-11`). You cannot have justify without parallax being on. |
+| `grid.panel_style: 'tile-checked'` | A **parent-only** value: the checked pattern comes from `uk-grid-checked` on the grid container, driven by the container's own `panel_style` (`grid/templates/template.php:56`; the render transform branches on it at `grid/element.php:118`). Setting it on an item does nothing. |
+| `grid_item.tags` | Inert unless the **parent grid's `filter`** is on: the whole tag-collection block runs inside `if (!empty($node->props['filter']))` (`grid/element.php:74`). Tags are also `strip_tags()`'d and their keys have **spaces replaced by dashes** (`:80-83`), so "New York" becomes the key `New-York`. |
+| `grid_item.title_color` vs `title_decoration` | `title_color: 'background'` and `title_decoration: 'line'` are decided by one `if`/`elseif` (`grid_item/templates/template-content.php:112-114`) — with `background` set, `line` never renders. Not additive. |
+| `grid.image_vertical_align` | Stops centering once `panel_expand` is active: the class carries `{@!panel_expand}` (`grid_item/templates/template.php:129`). |
+| `section` without `width` | Still emits a container when the section has a **video or an overlay** (`section/templates/template.php:158`), and that container then also gets `uk-panel` (`:167`) — which zeroes the last child's bottom margin. A width-less section is not always container-less. |
+| `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. |
+
+---
+
 ## Workflow 2: Bind a dynamic source to a grid
 
 **Goal:** Wire an existing Grid (or other multi-item element) to a
@@ -1109,6 +1364,12 @@ CMS-level template duplication (in wp-admin or Joomla administrator).
   REPLACES the entire `props` object on the element unless you pass
   `merge: true`. Read the existing shape via `yootheme_builder_element_get`
   first if you only want to tweak a subset and prefer not to use merge.
+- **Reading a prop's value never needs a second call.** `element_get`'s
+  output, both the JSON and the printed summary, lists every prop KEY
+  together with its VALUE (e.g. `title_element: "h1"`), each value capped
+  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.
 - **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
@@ -1169,7 +1430,8 @@ guessing, and without rotating the user's key unnecessarily.
    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? }`. Call this **before** any other tool when you see
+   summary?, capability_ok?, capability_warning?, effective_capabilities? }`.
+   Call this **before** any other tool when you see
    auth errors. (Takes no arguments. The schema is `{}`.)
 2. **Interpret the result:**
    - `plugin_reachable: false` → the WordPress / Joomla install is down
@@ -1191,6 +1453,14 @@ guessing, and without rotating the user's key unnecessarily.
      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` →
+     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
+     despite the write-scoped token. `capability_warning` carries the
+     exact remediation sentence. Re-mint the key under a user with edit
+     rights, or grant that user the capability. A write-scoped token
+     alone is not enough.
 3. **Walk the user through key rotation if needed:**
    - WordPress: "wp-admin → Tools → YT Builder MCP → Bearer Keys."
      Joomla: "Components → YT Builder MCP → Bearer Keys."
@@ -1393,11 +1663,23 @@ exposes. Never analyze findings by hand and never bulk-apply a fix.
    `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 })` drills into one
-   page a finding names. It carries the same `heading_levels`,
-   `images_missing_alt`, and `disabled_elements` counters the audit
-   used, so you can see exactly which nodes are affected before
-   writing.
+3. `yootheme_builder_template_summary({ template_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
+   the smaller default) a per-node `content_nodes` breakdown (`path`,
+   `type`, `status`, `effective_visible`, `hidden_on_mobile`, `headings`,
+   `alts`), so you can see exactly WHICH node is affected, whether it
+   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
+   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.
 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
@@ -1407,6 +1689,38 @@ exposes. Never analyze findings by hand and never bulk-apply a fix.
    with the same per-page codes, so you can confirm the fix landed
    without a second full sweep.
 
+**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:
+'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
+`props.status`/`disabled_elements`/`content_nodes.status` fields, so the fix
+is visible without a DB round-trip). Pass `status: true` to re-enable it,
+which restores the YOOtheme default (no status field means active) rather
+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 })`
+(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` —
+`headline`, or the `html`/`text`/`code` element for a raw-HTML heading), plus
+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" } })`
+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
+h1). Pass `mode: "rendered"` to read the ACTUAL rendered DOM instead of the
+saved layout tree (the same trade-off `pages_audit`'s own `mode` makes: sees
+module/widget output, but `element_type` degrades to `""` since there is no
+builder node to point at).
+
 **Common pitfalls:**
 
 - **Promising a full SEO audit.** `pages_audit` covers Builder structure
@@ -1418,6 +1732,51 @@ exposes. Never analyze findings by hand and never bulk-apply a fix.
   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.
+- **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
+  `title`/`image_alt`. A sticky-bar `<h1>` or an alt-less `<img>` buried
+  in raw markup is caught, not silently missed, unless the whole
+  `content` prop is dynamically bound (a bound value is a stale editor
+  preview and is skipped). Since T-A1, `code` joined `html`/`text` as a raw-HTML
+  carrier, and anchor text + heading length/order are ALSO detected the same
+  way: an empty/generic `<a>` link, a heading level skip, or an over-long
+  heading buried in raw markup is caught by `generic-alt-text`/
+  `anchor-text-quality`/`heading-skip`/`long-heading`, not just by
+  `missing-h1`/`multiple-h1`/`no-headings`/`images-missing-alt`/`dead-anchor`.
+  `module`/`module_position` (WordPress "Widget"/"Widget Area", Joomla
+  "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.
+- **`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
+  `yootheme_builder_render_preview` uses) and audit the ACTUAL rendered DOM.
+  This is the one way to catch a `module`/widget's own runtime output — a
+  newsletter-signup widget that itself renders an `<h1>`, dynamically-bound
+  content, anything a plugin injects only at render time — none of which the
+  builder-JSON walk above can see AT ALL. Only a curated subset of checks runs
+  in this mode (`no-headings`, `missing-h1`, `multiple-h1`, `heading-skip`,
+  `images-missing-alt`, `generic-alt-text`, `dead-anchor`, `anchor-text-quality`,
+  `long-heading`, plus the three `design-*` markup codes — every check whose
+  evidence is honestly derivable from a flat rendered document);
+  `thin-content`/`duplicate-layout`/`empty-page`/`heading-hidden-on-mobile`/
+  `non-pretty-url`/`stale-content` and both `header-contrast-*` codes still
+  need the builder tree and do not run here (`header_transparent*` are section
+  PROPS — they are gone by render time, so a rendered sweep can never produce
+  those two findings). **Locators carry NO builder element
+  path in this mode** — `breadcrumb`/`element_type` are empty strings BY
+  DESIGN (there is no builder node to point at, not a resolution failure) —
+  locate the hit by its `content_snippet` (the actual rendered text) or the
+  page's `builder_url`/`frontend_url` instead. A site-wide rendered sweep is
+  capped (rendering is expensive — each page runs the full YOOtheme Builder
+  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.
+  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.
 - **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`
@@ -1587,6 +1946,88 @@ exactly one page, so there is nothing for a type filter to narrow). A `title`
 that matches several pages returns `title_ambiguous` with a candidate list —
 show it, let the user choose.
 
+### Design-Consistency-Check (`checks: ["design"]`)
+
+A fifth audit category, alongside `seo`/`structure`/`content`/`links`, in the
+DEFAULT-ALL set (no opt-in flag needed — just call `pages_audit` normally, or
+narrow to it with `checks: ["design"]`). It flags markup that breaks OUT of
+the site's UIkit design system — most commonly a **plugin's own output**
+(Formidable, ACF, a shortcode-rendered form) carrying none of YOOtheme's
+`uk-*` classes, e.g. a form submit button with no `uk-button`. Native
+YOOtheme builder elements (grid_item, panel, button, …) are never checked —
+the theme always renders them with the right `uk-*` class; there is nothing
+to flag there.
+
+Three finding codes, all `warning` severity, none carrying a `fix_hint` (see
+below for why):
+
+- **`design-missing-uikit-class`** — a contract-bearing element
+  (button/select/textarea/input/`a[role=button]`/form/label-in-a-form) with
+  no class at all, or one that already carries a DIFFERENT real `uk-*` class
+  (on-system, just incomplete) — its expected class is simply absent.
+- **`design-foreign-class`** — the SAME element universe, but it carries
+  class(es) and NONE of them are real UIkit classes — positive evidence a
+  DIFFERENT framework (Bootstrap's `btn btn-primary`, a plugin's own
+  `form-control`) is actively styling it instead of UIkit.
+- **`design-inline-style`** — ANY element (no tag restriction) with a
+  non-empty `style=` attribute inside embedded content — bypasses the theme's
+  design system entirely.
+
+A FOURTH and FIFTH code share the `design` category but are not about markup at
+all — they read section props, not embedded HTML, so unlike the three above they
+are **builder-mode only** and never run in `mode: "rendered"` (the props do not
+exist in a rendered document):
+
+- **`header-contrast-risk`** (`warning`) — the first section pulls the
+  navigation over itself in a colour the theme's own `--uk-inverse` declaration
+  contradicts, with no image or video hiding the background that declaration
+  describes. Unlike the three above it DOES carry a `fix_hint`.
+- **`header-contrast-unverifiable`** (`info`) — the same transparent header over
+  a hero medium, whatever the colour: nothing there is provable from the props,
+  so no colour is recommended and readability is only verifiable by looking.
+
+See their remediation-catalog entries below.
+
+**Run the three markup codes in `mode: "rendered"` for the highest-value
+result.** A Formidable/ACF form's markup exists ONLY at render time — it is
+invisible to a builder-tree walk unless it happens to be typed static markup
+inside an `html`/`text`/`code` element. `mode: "rendered"` renders each page
+first (the SAME engine `render_preview` uses) and audits the ACTUAL output, so
+a plugin shortcode's real markup is exactly what gets checked. (The two
+`header-contrast-*` codes do NOT run in that mode — use the default
+`mode: "builder"` when you want them.)
+
+```jsonc
+yootheme_builder_advanced_read({
+  tool: "yootheme_builder_pages_audit",
+  arguments: { mode: "rendered", checks: ["design"], target: { special: "contact" } }
+})
+```
+
+**No `fix_hint` on any of the three codes — this is deliberate, not a gap.**
+The offending markup lives inside an opaque `props.content` string (an
+html/text/code element) or a plugin's own rendered output — there is no
+structured prop `element_update_settings` could merge a class into without
+string-surgery on customer HTML, which this server's read-only-analysis
+policy forbids on the write path. Report the locator's `content_snippet`
+(the offending element's OWN markup, e.g. `<button class="btn btn-primary">`
+— unlike every other finding's snippet, this one deliberately keeps the
+class/style attribute instead of stripping it, since that attribute IS the
+evidence) and tell the user to add the class by hand, or fix it in the
+plugin's own settings/template.
+
+**Design-consistency fixes: ground the exact class via Context7 when it is
+available.** A `design-missing-uikit-class` or `design-foreign-class` finding
+asks you to name a real UIkit class by hand; recalling one purely from
+training data risks a subtly wrong suggestion, since class names can drift
+across UIkit versions. When the user's client has Context7 (or an equivalent
+documentation-grounding MCP) configured, query it (library id
+`/websites/getuikit`) to confirm the exact class before naming it in the fix.
+Without Context7, degrade cleanly: keep working from the tool's own output
+(the locator's `content_snippet`) plus the class names already catalogued
+above, and never invent a class name you have not confirmed one way or the
+other.
+
 ### Remediation catalog — what each finding means and how to fix it
 
 The audit reports; YOU explain. Every finding below carries its fixed
@@ -1644,6 +2085,25 @@ second, independent heading channel), which is exactly what the raw path cannot.
 N times through an iterating container or a Multi-Items binding, so the fix is
 one edit on the item, not N edits; the locator's `×repeat` shows the multiplier.
 
+#### `heading-hidden-on-mobile` - structure · warning
+
+**Why it matters.** Google indexes mobile-first: a heading that renders on
+desktop but is hidden at the base (phone) UIkit breakpoint is effectively
+invisible for ranking, even though it exists in the markup and a desktop
+review would never catch it.
+**How to fix.** No `fix_hint`. Hiding a heading on mobile is sometimes
+intentional (a duplicate mobile-only title elsewhere). Check the node's
+`props.visibility` (own or an ancestor's) and either remove the
+`hidden@`/`visible@` class or confirm an equivalent heading is visible on
+mobile some other way.
+**Severity.** Warning. Strict subset of ONLY the headline-TYPE portion of the
+pool `heading-skip` reads (since T-A1, `heading-skip` ALSO covers raw-HTML
+h1-h6 tags inside `html`/`text`/`code` elements - this check does not; a
+raw-HTML heading's mobile-visibility is not tracked): `hidden@<bp>` hides FROM
+that breakpoint upward (mobile stays visible), `visible@<bp>` is the mirror
+(hidden below it, mobile included), a bare `hidden` hides everywhere. Only the
+last two ever fire this check.
+
 #### `heading-skip` — structure · info
 
 **Why it matters.** Jumping h1 → h3 breaks the document outline: assistive tech
@@ -1652,9 +2112,12 @@ reports a missing level, and the hierarchy stops describing the real structure.
 the jumped-to heading (`element_update_settings`, `props.title_element`) or add
 the missing intermediate level. The evidence lists each skip as
 `{ path, from, to }`.
-**Severity.** Info: it is a real hierarchy defect but the page remains usable,
-and the check is deliberately `headline`-only, so container-started hierarchies
-are invisible to it. Do not present it as complete heading-hierarchy coverage.
+**Severity.** Info: it is a real hierarchy defect but the page remains usable.
+Reads BOTH `headline` elements AND raw-HTML h1-h6 tags inside `html`/`text`/
+`code` elements' `content` (interleaved in one true document-order sequence,
+since T-A1) - but container-STARTED hierarchies (e.g. a page whose only
+headings are 3× h3 grid-item titles with no h1/h2 anywhere) remain invisible
+to it. Do not present it as complete heading-hierarchy coverage.
 
 #### `images-missing-alt` — content · warning
 
@@ -1750,7 +2213,12 @@ prop is `title`. For an icon-only or image-only link, the right fix is
 `props.link_aria_label`, not invented visible text. Only link-bearing elements
 whose visible-text prop is known are checked — `button`, `button_item`,
 `grid_item`, `panel`, `headline`, `list_item`, `nav_item`, `subnav_item` — so
-this is an allowlist, not a sweep over every element carrying a `link`.
+this is an allowlist, not a sweep over every element carrying a `link`. Since
+T-A1, a raw `<a href>` tag inside an `html`/`text`/`code` element's `content` is
+ALSO checked - that path judges every anchor with a set `href` (any
+destination, not just in-page), exempting an empty one only when it carries an
+`aria-label` or a nested `<img alt>` (the raw-HTML mirror of the allowlist's
+icon/image/aria-label exemption).
 **Severity.** Warning. The locator's `reason` says which rule fired: `empty` or
 `generic` (an **exact match** against the DE+EN generic list — `mehr`, `hier`,
 `weiterlesen`, `click here`, `read more`, `learn more`, …). Exact match only, so
@@ -1779,7 +2247,9 @@ the image actually shows ("SunWest Büro in Manresa").
 the EMPTY case). Only an **exact match** against the generic list (`image`,
 `photo`, `picture`, `logo`, `icon`, `bild`, `foto`, `grafik`) fires, so
 `"ACME Logo"` is already a good alt text and is never flagged. Bound alt/image
-props are exempt.
+props are exempt. Since T-A1, a raw `<img alt="...">` inside an `html`/`text`/
+`code` element's `content` is checked the SAME way, judged against the
+identical generic list.
 
 #### `long-heading` — structure · info
 
@@ -1790,8 +2260,9 @@ keyword focus, get truncated in search results and wrap badly on mobile.
 detail into the body text below it. The locator carries the measured `length`.
 **Severity.** Info — a long heading is a quality signal, never a defect. The
 threshold is **70 characters**, measured multibyte-safely over the
-markup-stripped text, on unbound static text only. Scope is deliberately narrow:
-`headline` plus the standalone title carriers (`alert`, `overlay`, `panel`).
+markup-stripped text, on unbound static text only. Scope: `headline` plus the
+standalone title carriers (`alert`, `overlay`, `panel`), PLUS (since T-A1) every
+h1-h6 tag's own text inside an `html`/`text`/`code` element's raw `content`.
 Multi-Items containers keep their title text on the paired `*_item` children and
 are not measured — do not claim full heading-length coverage.
 
@@ -1799,6 +2270,157 @@ are not measured — do not claim full heading-length coverage.
 checks, so they also ride in the `quick_check` block on `page_publish` /
 `page_save` alongside the other per-page codes.
 
+#### `design-missing-uikit-class` — design · warning
+
+**Why it matters.** A contract-bearing element (a form's submit button, its
+text inputs, its labels) with no `uk-*` class at all renders unstyled — it
+visually breaks out of the site's design system, most visibly on a
+plugin-rendered form (Formidable, ACF) dropped onto an otherwise polished
+page.
+**How to fix.** No `fix_hint` — see "Design-Consistency-Check" above for why.
+Add the missing class by hand (`uk-button` on a submit button, `uk-input` on
+a text input, `uk-form-label` on a label inside a form, `uk-form-stacked` or
+`uk-form-horizontal` on the form itself) — via the plugin's own class/CSS
+settings when it is a plugin form, or by editing the raw markup when it is a
+custom html/text/code element.
+**Severity.** Warning — a visual/consistency defect, not a functional one.
+Fires when the element carries NO class at all, or already carries a
+DIFFERENT real UIkit class (on-system, just incomplete) — never confuse this
+with `design-foreign-class` below.
+
+#### `design-foreign-class` — design · warning
+
+**Why it matters.** The SAME contract-bearing universe as
+`design-missing-uikit-class`, but here the element DOES carry class(es) and
+NONE of them are real UIkit classes — positive evidence that a DIFFERENT
+framework (Bootstrap's `btn btn-primary`, a plugin's own `form-control`) is
+actively styling it instead of UIkit. This is a REPLACEMENT problem, not a
+silence: the fix is a class swap, not an addition.
+**How to fix.** No `fix_hint`. Replace the foreign class with UIkit's
+equivalent (`btn btn-primary` → `uk-button uk-button-primary`), typically in
+the plugin's own template/class settings rather than in YOOtheme.
+**Severity.** Warning. The locator's `content_snippet` shows the element's
+own markup WITH its class attribute — the exact evidence, never tag-stripped
+like every other snippet in this audit.
+
+#### `design-inline-style` — design · warning
+
+**Why it matters.** A `style=` attribute inside embedded content (a
+`<div style="color:red">` in an html/text/code element, or in a plugin's
+rendered output) hard-codes styling that bypasses the theme's design system
+entirely — it cannot be themed, cannot respond to a style/color-mode change,
+and is invisible to any CSS audit that only looks at stylesheets.
+**How to fix.** No `fix_hint`. Move the styling into a UIkit class or the
+theme's own CSS, or remove it if it was accidental (a rich-text editor
+sometimes injects one). ANY tag can carry this finding — there is no
+tag restriction, unlike the two class-based checks above.
+**Severity.** Warning.
+
+All three are `appliesTo: per-page` but — unlike `anchor-text-quality` /
+`generic-alt-text` / `long-heading` above — they deliberately do NOT ride the
+`quick_check` block on `page_publish` / `page_save`: `quick_check` is a
+publish-time advisory scoped to what a single-template pass can see without a
+live vocabulary, and design detection needs the site's actual compiled UIkit
+CSS. Run `pages_audit` (ideally `mode: "rendered"`) to see these three markup
+findings. The two `header-contrast-*` codes below skip `quick_check` for the
+same reason but are **builder-mode only** — `mode: "rendered"` never emits them.
+
+#### `header-contrast-risk` — design · warning
+
+**Why it matters.** The page's FIRST section pulls the navigation over itself
+(`header_transparent`) and forces a `header_transparent_text_color` the site's
+own theme does not declare for that section style. The forced colour wins —
+`.uk-inverse-light` / `.uk-inverse-dark` carry `!important` and beat the
+style's own declaration — so this is not a taste question: it is white
+navigation on a white hero, or dark navigation on a dark one. Nothing in the
+builder warns about it. See "Transparent header (the exception — never a
+default)" for the whole trap family.
+
+**One class only, and it is decidable.** The page entry carries `risk_class`,
+`confidence`, `text_color`, `recommended_text_color`, `style` and
+`media_backdrop`:
+
+- **`risk_class: "B"`, `confidence: "high"`** — no image or video covers the
+  section background, so the contradiction is decidable from the layout alone.
+  `recommended_text_color` is the theme's OWN declared inverse for that style
+  (READ from the compiled `theme.css` — not a guess, not a computed contrast
+  ratio).
+
+**`pages_audit` never emits this code over a hero image or video.** A medium
+covers exactly the background `--uk-inverse` describes, so there is nothing to
+contradict and nothing to recommend; that state is the
+`header-contrast-unverifiable` info finding below, at one severity whatever the
+colour. A transparent header you do not see reported here is therefore *not*
+endorsed — look for the info finding.
+
+**How to fix.** `fix_hint` → `header_transparency_set` with `mode: "auto"` and
+`dry_run: true`. The dry-run reports the current state, the theme-declared
+inverse, `risk_class`, `confidence` and exactly what would change; repeat with
+`dry_run: false` + an `etag` to write it. The tool resolves the FIRST section
+itself — you do not pass an `element_path`, and the repair therefore cannot
+land on a section whose props YOOtheme never reads. `mode: "auto"` writes the
+theme's own declared value, so no colour is ever guessed. Turning the
+transparent header off entirely is always the safe direction and is never
+refused (`transparent: false`).
+
+**Severity.** Warning. It never blocks a write, and it is per-page but does NOT
+ride `quick_check` (same reason as the three design codes above: the verdict
+needs the site's compiled `theme.css`, which the publish-time pass does not
+read). **When that CSS cannot be read, or the theme declares nothing for that
+style, there is no finding at all** — an unreadable theme yields silence, never
+a guess. It is also **builder-mode-only**: `header_transparent*` are section
+props, so `mode: "rendered"` never emits this code — a clean rendered audit is
+NOT evidence that the header is fine.
+
+**What it does NOT report.** A dead prop (a colour set while
+`header_transparent` is off) and props on a non-first section are not contrast
+risks and are not reported here — see the transparent-header section for those
+two traps.
+
+#### `header-contrast-unverifiable` — design · info
+
+**Why it matters.** The page's FIRST section pulls the navigation over itself
+AND carries a hero image or video —
+**whatever `header_transparent_text_color` holds**.
+Nothing here is provable: the theme's `--uk-inverse` declaration
+describes the section's BACKGROUND COLOUR, and the medium hides exactly that
+background, so "is the navigation readable?" cannot be answered from the layout
+at all. Which part of a `cover` image ends up under the header depends on the
+viewport.
+
+`risk_class: "C"`, `confidence: "low"`, `recommended_text_color: null`.
+
+**`null`, not `""` — this code recommends no colour at all.**
+`""` is not the humble answer: it is the theme's default colour, a concrete
+rendered value, so writing it back over a colour someone set deliberately (or
+measured in a browser) is a change, not an abstention. Over a dark hero photo
+on a `--uk-inverse: dark` style, `""` renders dark navigation on a dark image.
+
+**One severity for the whole media case, deliberately.** An earlier revision
+graded it — `""` info, any other colour a warning — and that punished the
+correct action: the colour a browser measurement finds readable over a dark
+hero is usually the one the theme does NOT declare, so an eyes-verified page
+scored a warning whose remedy was to revert it. Behind a medium there is no
+baseline to deviate from, so there is nothing to grade.
+
+**How to fix.** No `fix_hint`, because there is nothing to write. **Look at
+it** — render the page (see "Look at what you built") at the customer's
+viewport, unscrolled AND after scrolling, and read the navigation. If it is
+unreadable, set the colour that IS readable over that medium with
+`header_transparency_set({ mode: "explicit", text_color: … })` —
+a value you have seen, never one
+you inferred. `mode: "auto"` deliberately writes no colour here, so it cannot
+help you: it has not seen the page either. If it reads fine, say so and move on.
+
+**The finding stays at `info` afterwards, and that is correct.** A transparent
+header over a medium is never provable from props, so the honest end state is
+"no warning, still only verifiable by eye" — not "clean". Report it as verified
+and move on; do not go looking for a colour that makes it disappear.
+
+**Severity.** Info — an open question, not a defect. Same fail-open rule as the
+warning above: no readable `theme.css`, no finding. Same builder-mode-only
+restriction, same absence from `quick_check`.
+
 ### The report contract — how to present an audit
 
 The raw response is a machine payload. What you hand the user follows this
@@ -1812,8 +2434,8 @@ shape every time, so two audits of two sites read the same way:
 2. **Order by severity: critical → warning → info.** The server already sorts
    that way; never re-rank findings by how easy they look to fix.
 3. **Group page → category → finding.** One block per affected page, its
-   findings grouped by `category` (`structure`, `content`, `seo`, `links`), so
-   the user can fix one page in one pass instead of hopping between pages per
+   findings grouped by `category` (`structure`, `content`, `seo`, `links`,
+   `design`), so the user can fix one page in one pass instead of hopping between pages per
    code.
 4. **Render every hit from its locator**, in this shape:
 
@@ -1832,7 +2454,13 @@ shape every time, so two audits of two sites read the same way:
    `element_type`) plus the `breadcrumb` that locates it in the builder. A **bare
    path list is NOT acceptable output** — `/children/0/children/2` tells the user
    nothing about which box on their page to click. Add the page's `builder_url`
-   as the "open in builder" link when the response carries one.
+   as the "open in builder" link and its `frontend_url` as the "view live" link,
+   whenever the response carries them — every finding page carries both today
+   (previously only the nine element-located checks carried `builder_url`, and
+   only `non-pretty-url` carried `frontend_url`). A theme/archive/internal
+   template with no public route or no resolvable admin base legitimately omits
+   one or both — that is not a bug, and it is not the agent's job to look the
+   URL up separately via pages_list/pages_resolve when it is missing here.
 6. **State what did and did not run.** On a site sweep, say the site-wide checks
    ran (`duplicate-layout`, `title-collision` compare pages against each other).
    On a single-page audit, say they did not — reuse the response's own `note`
@@ -2087,6 +2715,493 @@ to re-read the entire layout after a wrong-path error.
 > `{given, nearest_path, nearest_path_label, available_paths}` envelope is
 > byte-identical across WordPress and Joomla.
 
+## Response budgets — how a read tool shortens an oversized answer
+
+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:
+
+- `truncated: true` — this response is not the whole answer.
+- `omitted_count: N` — exactly how many entries were left out.
+- `next_cursor` — present whenever the resume point is derivable; pass it back
+  as `cursor` to read the entries that were dropped. It is **omitted rather
+  than guessed**: no cursor means the tool could not derive one, not that
+  nothing is missing. Use `omitted_count` in that case. A cursor that could not
+  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).
+- `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".
+
+Two levers beat raising `max_chars`, because they reduce what is produced
+rather than what survives: ask for fewer fields (`fields[]`) and fewer rows
+(`limit` + `cursor`). Reach for `max_chars` last.
+
+Every default is derived from measured response sizes, not chosen, and the same
+default applies on both transports — the proxy and the plugin's own `/mcp` are
+two paths to one tool (see `docs/mcp-response-budgets.md`). A derived class is
+applied **raise-only**: measurement may lift a default, never lower it, so no
+upgrade silently returns less than the version before it.
+
+### Ask for the fields you need — `element_type_get_schema`
+
+A big element type is the sharpest case: `grid` declares **154** field
+descriptors. Do not read all of them and do not raise the cap — **name what you
+want**:
+
+- `field_names: ["image_expand","grid_masonry"]` — exact names, case-insensitive.
+- `name_contains: "height"` — substring of the field's **name OR label**, so it
+  also finds `image_expand`, whose label is "Height".
+- Both together **UNION** — each argument names what you want; adding one never
+  removes what the other selected.
+
+A selected descriptor comes back **COMPLETE** — its `enable` condition, `enum`
+and `default` are all there, which is exactly what a truncated read destroyed.
+Every response carries `field_count` (what the type declares) and
+`returned_count` (what you received), so a narrowed answer is never silent and
+you always know the size of what you did not ask for. A pattern that matches
+nothing returns an **empty list plus the counts, not an error**.
+
+`field_names`/`name_contains` pick WHICH descriptors; `fields[]` picks the
+sub-keys of each one. They compose — selection runs first, so
+`name_contains:"height", fields:["name","enable"]` is a legitimate call.
+
+### Read a field's MEANING, not just its `label` — `text` and `description`
+
+A descriptor carries YOOtheme's own two meaning-bearing keys, and on a
+**checkbox** they are not optional reading:
+
+- **A checkbox's value is a boolean (`true`/`false`); its MEANING is in `text`,
+  because `label` on a checkbox is the GROUP heading, not the option.** `grid`'s
+  equal-height option is
+  `{"name":"image_expand","type":"checkbox","label":"Height","text":"Expand image","enable":"!grid_masonry"}`.
+  Read `label` alone and it says "Height: true/false" — which is not what the
+  option does. The caption rendered next to the box is `text`: "Expand image".
+  Same shape for `image_loading` ("Loading" / "Load image eagerly"), `panel_link`
+  ("Link" / "Link panel") and `panel_match` ("Height" / "Match panel heights").
+- **`description` is the Builder's own tooltip** for the field, e.g.
+  `grid.panel_content_width` → "Set an optional content width which doesn't
+  affect the image if there is just one column."
+
+Both keys are **absent when YOOtheme declares none**, so a descriptor without
+`text` means "this field has no caption", never "the caption was dropped".
+
+### When the field says nothing, the GROUP does — `group` and `groups[]`
+
+**YOOtheme parks the semantics of a whole class of fields on the enclosing
+fieldset GROUP, not on the field.** So a descriptor with no `label` and no
+`description` is not undocumented — you are reading at the wrong level.
+`group` names the nearest enclosing group (the heading the Builder renders beside
+the field), and the schema's **root `groups[]`** states that group's own sentence
+once. Join the two on the group name:
+
+`{"name":"image_width","type":"number","placeholder":"auto","enable":"show_image || show_video","group":"Width/Height"}`
+
+`"groups":[{"name":"Width/Height","description":"Setting just one value preserves the original proportions. The image will be resized and cropped automatically, and where possible, high resolution images will be auto-generated."}]`
+
+Read the field alone and `image_width` looks like a plain number. The rule you
+actually needed — **set only ONE of width/height and the proportions are kept;
+set BOTH and the image is CROPPED** — lives on the group shared by `image_width`
+and `image_height`. Same shape for the `lightbox_image_*` pair.
+
+- The sentence is the **group's**, never re-labelled as the field's, so a field
+  may carry its own `description` while its group carries another at once —
+  they are two different statements. It sits at the root because it is shared:
+  measured over nine element types, 32 fields carried only 5 distinct sentences,
+  one of them 20 times.
+- `groups[]` **narrows with your selection** — a `field_names` /`name_contains`
+  read carries only the groups its descriptors name, never the whole type's.
+- `placeholder` is `attrs.placeholder`, which for several fields IS the
+  documented fallback: `grid.image_width` → `"auto"`, `countdown.label_days` →
+  `"Days"`. An empty value renders the placeholder, it does not render empty.
+
+### What an enum VALUE does not say — `enum_labels`
+
+`enum` carries the values you write. `enum_labels` carries the Builder's label for
+a value **where the value does not already carry it**:
+
+`{"name":"grid_default","type":"select","label":"Phone Portrait","enum":["1","2","3","4","5","6","auto"],"default":"1","enum_labels":{"1":"1 Column","2":"2 Columns","3":"3 Columns","4":"4 Columns","5":"5 Columns","6":"6 Columns"}}`
+
+Without it, `["1"…"6"]` is six digits with nothing saying they are **column
+counts**; `grid_column_gap`'s `"collapse"` is a word with nothing saying the
+Builder calls it **None**.
+
+- **A value with no entry is not unlabelled.** Its label is the value itself, up
+  to case and punctuation — `"small"` is "Small", `"arrow-right"` is
+  "Arrow Right". Only genuine renamings are listed, which is why the key is
+  affordable: measured over nine element types, 611 of 2043 label/value pairs
+  (29.9 %) are genuine renamings and the other 1432 are silent.
+- **`""` is a real choice, not a gap.** YOOtheme uses the empty string as a
+  meaningful selection — `panel.video_autoplay` declares `'On' => ''`,
+  `switcher_item.item_element` declares `'div' => ''` — and since an empty value
+  carries no characters at all, its label is always in `enum_labels`
+  (`{"":"On"}`). So `""` in an `enum` is a selection to make.
+- **A missing entry can also mean "not decidable".** When two options collapse
+  onto the same value — `'On' => ''` beside `'No' => false`, because `false`
+  stringifies to `""` — neither label is emitted for that value rather than one
+  guessed. The same value in a DIFFERENT field may legitimately mean something
+  else: in `grid`, `""` carries twelve different labels across its fields, and
+  `"1-2"` is "50%" on one field and "Halves" on another. Read `enum_labels` per
+  field; never carry one field's label to another.
+
+### A prop that is declared and does nothing — `no_effect`
+
+A few props are declared in YOOtheme's config, ship a label and a tooltip, and
+are **read by no consumer**. For those the descriptor drops `text`/`description`
+— forwarding a promise nothing keeps is worse than silence — and carries
+`no_effect` with what was actually read instead:
+
+`{"name":"lightbox_image_orientation","type":"checkbox","label":"Image Orientation","no_effect":"No effect in YOOtheme Pro 5.0.37: declared in grid/element.php and gallery/element.php only, read by no template. Writing it changes nothing.","enable":"lightbox","group":"Lightbox"}`
+
+**A descriptor with `no_effect` is not a prop to set** — the write succeeds and
+nothing changes. The other one today is `panel-slider.show_hover_video`, dead
+because `panel-slider_item` lists `hover_image` twice and `hover_video` never.
+The prop stays writable on purpose: a stored layout may already carry the key,
+and rejecting it would break a round-trip. `enable` and `label` survive too —
+a Builder-UI condition and a UI name are not behaviour claims.
+
+### Which build a claim was read on — `claims_verified_on` and `no_effect_unverified`
+
+That evidence was read in **one** YOOtheme tree. A site running a different
+build is a site nobody has read, so the response says which is which:
+
+`"claims_verified_on":{"build":"5.0.37","here":"4.5.33","status":"differs","keys":["rule_notes","no_effect_unverified"]}`
+
+- **`status:"match"`** — the claims were read on the build you are running.
+  Take them as fact.
+- **`status:"differs"`** — read on `build`, not re-checked on `here`.
+- **`status:"unknown"`** — the site's YOOtheme version could not be resolved
+  (`here` is `null`). It never means "probably the same".
+
+`here` is resolved per host — from YOOtheme's runtime on WordPress, from the
+installed `yootheme` template manifest on Joomla — and on both it is the SAME
+value `yootheme_builder_health` reports as `yootheme_version`. So the two must
+agree: **if health names a build while this record says `unknown`, that is a
+resolver bug, not a fact about your site.** Check health first.
+
+Off a `match`, `no_effect` **is not emitted at all**. The finding ships under
+**`no_effect_unverified`** instead, naming both builds and ending in `UNKNOWN`,
+and `text`/`description` **stay** — those are YOOtheme's own words read from
+*your* build's live registry, so they are true for you, and only a verified
+deadness earns their removal. Every `rule_notes` entry is likewise prefixed
+`[Read in YOOtheme Pro <build>. … — unverified here.]`.
+
+**`differs` does not mean the claim is false on your build** — it means nobody
+looked. Treat `no_effect_unverified` as a strong reason to check before relying
+on the prop, not as permission to assume it works.
+
+**The record scopes exactly the keys it lists in `keys` — nothing else in the
+response.** It is emitted when, and only when, that list is non-empty, so scope
+and trigger are one thing and cannot drift apart. What can appear there:
+
+| Key | Why it is build-scoped |
+|---|---|
+| `renders_only_if`, `blanked_by_parent`, `media_autoswap` | render gates read in one tree |
+| `rule_notes` | the shared render-rule texts, all read in that same tree |
+| `no_effect` / `no_effect_unverified` | whichever of the two actually shipped |
+| `value_hint` | **only** when the hint is one of the render-template reads: a value-FORMAT trap (`countdown.date`, `map_item.location`, `map.width`/`height`, `popover_item.position_x`/`_y`, `table.table_order`) or `image_expand` |
+
+Everything else is **outside** it, whatever its own provenance — including
+`binding_contract`, whose `child_type` comes from a container/item table read on
+a *different* YOOtheme build, and `groups`, `enum_labels`, `semantic_role` and
+the descriptors themselves, which come from your own build's live registry.
+`placeholder_fallback` is outside for that second reason: it is derived from your
+own config, so it is true here by construction.
+
+A `value_hint` that is **not** named in `keys` carries no single-build scope — the
+image/icon shape hints, the grid-layout string and the type scale state a
+convention rather than a render reading, and `title_element`'s per-type defaults
+were verified against **both** the 4.5.33 and the YT5 element sources. Do not read
+`keys` as "these are the only claims in the response"; read it as "these are the
+claims this record vouches for."
+
+### Read what no field text can say — `value_hint`
+
+`text` and `description` are YOOtheme's own words. `value_hint` is ours, and it
+carries only what lives in the element's **render template** — a rule no field
+definition can state. The equal-height option is the sharpest case, and it is
+**per element**:
+
+- **A `grid` is ALREADY column-matched with no option set** — its container always
+  renders `uk-grid-match` (sole exception: `grid_masonry`). Switching
+  `image_expand` on to equalise the **columns** solves a solved problem: what it
+  expands is the **IMAGE**. The media element takes `flex:1`, and because every
+  `img` renders with `object-fit:cover`, the added height **crops** the picture.
+- **The order matters and the wrong order fails SILENTLY.** `image_expand` needs
+  its gate set FIRST: `panel_match` on `panel-slider`, `height_expand` on
+  `panel`, `grid_masonry` OFF on `grid` and `gallery`. Otherwise the element's
+  template **blanks the value at RENDER** — the write succeeds and the value stays
+  stored, so there is no error anywhere. **A field's `enable` condition does not
+  protect you**: it is a Builder-UI condition only — no render path reads it, so it
+  never guards an API write. Read the field's own `value_hint` for that element's exact condition
+  (most gates have an `image_align: left`/`right` escape; `gallery` has none).
+- On the two sliders the render can also **FORCE it on**. With `slider_width`
+  unset, `panel-slider` forces `panel_match` and `image_expand` to true, and
+  `overlay-slider` forces `image_expand` to true — as it also does whenever
+  `height_expand`, `slider_min_height` or `height_viewport` is set. There an
+  `image_expand: false` write is accepted and stays stored, then replaced by true
+  at **RENDER**: on those settings the option cannot be switched off at all.
+- **The fixed-size alternative:** set **BOTH** `image_width` and `image_height` —
+  both numeric crops server-side to exactly that box, one alone only resizes
+  proportionally.
+
+`name_contains: "expand"` returns that one descriptor with the whole rule set.
+
+### Will this element render at all? — `renders_only_if`, `placeholder_fallback` and `blanked_by_parent`
+
+The schema root carries three arrays that decide whether a write is visible **at
+all**. They are element-level, so they are present on **every** read of that type
+— a `field_names` selection does not narrow them away.
+
+**`renders_only_if` — an element with PRESENT-but-EMPTY required props is DELETED at render.**
+Not hidden, not empty: removed from the tree, with no error anywhere. It is a
+list of groups, and **ALL groups need at least one non-empty member**:
+
+`"renders_only_if":[["title","meta","content","image","video","icon"]]`  ← `grid_item`
+
+`"renders_only_if":[["title"],["content","image","link"]]`  ← `accordion_item`, which needs a title **and** one of the three
+
+> **Read `placeholder_fallback` before concluding "nothing renders".** For props
+> you simply never wrote, the answer on **27 of the 28 gated element types** is
+> not deletion — see the next subsection. `renders_only_if` alone over-states it.
+
+- **`link` is almost never a keeper.** It is absent from the gate of `grid_item`,
+  `gallery_item`, `list_item`, `table_item`, `description_list_item` and `panel`,
+  so a card carrying **only a link plus link text renders nothing at all**.
+  `social_item` is the one element where a bare `link` is the whole gate — which
+  is why this is a per-element read, never a blanket rule.
+- **The emptied parent goes too.** A container whose children all dropped is
+  itself dropped, cascading column → row → section. So one unsatisfied gate on a
+  repeated item can blank a whole section.
+- A member may be a `&&`-joined conjunction, and a `parent.` prefix addresses the
+  **container's** prop: `switcher_item`'s second group lists
+  `"title&&parent.show_title"`, i.e. with the container's `show_title` off a title
+  alone does not satisfy it — meta, content or image is then required.
+- Media-only elements are the mirror image: `overlay`, `overlay-slider_item`,
+  `slideshow_item` and `gallery_item` need an image or video and drop a text-only
+  item.
+
+**`placeholder_fallback` — an UNSET prop does not delete the element; it publishes
+YOOtheme's placeholder to the live page.** This is the difference between
+*absent* and *present-but-empty*, and absent is the normal shape of an MCP write:
+
+`"placeholder_fallback":{"suppressed_by":["title","meta","content","image","video","icon","hover_image","hover_video"],"fills":["title","content"]}`  ← `grid_item`
+
+- **`fills` is what your visitors see.** YOOtheme merges the element type's own
+  placeholder props *before* the gate is evaluated, on the **front end** as well
+  as in the customizer, so the gate is satisfied by content you never wrote:
+  lorem ipsum, the literal string `"Title"`, `"Headline"`, the icon `"star"`, a
+  demo date, or `assets/images/element-image-placeholder.png`. On `overlay`, for
+  instance, YOOtheme injects **both** its placeholder image **and** the literal
+  text `"Title"` into the published page.
+- **`suppressed_by` is your off switch.** Write **any** key in that list —
+  including to `""` — and the merge is skipped entirely for the whole element.
+  Only then does `renders_only_if` delete. It is all-or-nothing: one written key
+  suppresses every fill, not just its own.
+- **So there are three outcomes, not two.** Leave the props unset → placeholder
+  content ships. Write one gate prop with real content → your content ships.
+  Write a gate prop as `""` → the element is deleted. If you want an element
+  gone, delete it; do not rely on leaving props unset.
+- **`social_item` is the one gated type with no placeholder at all**, so no key
+  is present and an absent `link` really does drop the node. Absence of
+  `placeholder_fallback` therefore means the gate is literal.
+
+**`blanked_by_parent` — a container's `show_*` flag is NOT CSS visibility, and it
+is NOT a write either.** Both halves matter, and a reader who takes only one acts
+wrongly. It **empties the child's prop in the render transform**, so the value is
+gone from the **rendered HTML** while **the stored layout still holds it,
+unchanged** — flip the flag back and the render returns. The emptied value then
+feeds the child's own `renders_only_if`, in the same function, so clearing one
+flag can delete the **entire item**, not just the field you meant to hide:
+
+`"blanked_by_parent":{"show_title":["title"],"show_image":["image","icon"],"show_link":["link"], …}`
+
+- **MEASURED, YOOtheme Pro 5.0.37** — a two-item `grid`, written with
+  `element_update_settings` + `page_publish`, read back with `page_get_layout`
+  and from the published page. With `show_title: false` on the grid: rendered
+  `.el-title` **2 → 0**, neither title string anywhere in the section HTML, and
+  the grid's stored children subtree **byte-identical** before and after (equal
+  sha256, 699 B, `diff` exit 0) — the whole-layout diff was **one added line**,
+  `"show_title": false`, on the GRID node and nothing on any child. Setting it
+  back to `true` restored the byte-identical baseline render. So **re-writing the
+  props is never the fix; flipping the flag back is.**
+- **The whole item really does go — and takes its container.** In the state where
+  the blanking left only `link` (which is not in `grid_item`'s gate), `.el-item`
+  went **2 → 0** and the `.uk-grid` container with it (**2 → 1**; section HTML
+  2221 → 609 chars) — while the read-back still carried `link` and `link_text` in
+  full. Nothing rendered; nothing lost.
+- **A source-bound item behaves the same — measured, not assumed.** With
+  `grid_item[0]` bound to a native source and `grid_item[1]` left literal,
+  `show_title: false` blanked **both** (`.el-title` 4 → 0), and the read-back
+  still showed the binding intact (`source.props.title`) on the bound item and
+  the literal string on the static one. For a bound prop the surviving stored
+  value is the **binding**, and it survives exactly as a literal does. Measured
+  on the REST write path and the published page only — the customizer's own
+  tick-and-save path was not measured, and nothing here is claimed about it.
+- **Intersect the two arrays to see the blast radius.** Where a blanked prop also
+  appears in the gate, the item can vanish — true for nine of the thirteen item
+  types that blank. In `nav_item`, `subnav_item`, `slideshow_item` and `map_item`
+  it cannot: their gate is `content` / `content` / `image`+`video` / `location`,
+  which no `show_*` blanks.
+- **`show_image` also wipes `icon`** on `grid_item`, `panel-slider_item`,
+  `list_item`, `nav_item` and `subnav_item` — the array shows it, so read the
+  values rather than assuming one flag clears one prop.
+- **Some flags blank from the TEMPLATE, not the transform** — `map_item`'s five
+  and `switcher_item`'s `show_title`, which is why `switcher_item` carries seven
+  flags and not the six its transform loop enumerates. These empty the value for
+  **rendering** but do not feed the element's own gate, so do **not** intersect
+  them with `renders_only_if`: `switcher_item`'s gate reads `title` raw in its
+  first group and consults `show_title` itself in the second
+  (`"title&&parent.show_title"`), and `map_item`'s gate is `location`, which no
+  flag touches.
+- `table_item`, `social_item` and `button_item` have no blanking at all. They
+  still have gates.
+- On `description_list_item`, `link` renders **only** as a wrapper around
+  `content`, so losing `content` loses the link too — by a different route than
+  the flag.
+
+### `""` means INHERIT, not off — `empty_means_inherit`
+
+A descriptor with `"empty_means_inherit":true` merges over its **container's**
+value. Because the empty string is falsy, writing it — which is what the
+Builder's **"None"** option stores — **re-inherits the parent** instead of
+switching the feature off. Item overrides are therefore **add-only**: a single
+item cannot be forced back to plain inside a styled container. **To make one item
+plain you must restyle the container, not the item.**
+
+It is on **43 fields across 12 element types**, so read the flag rather than
+guessing the family: the styling props (`panel_style`, `*_text_color`, `media_*`)
+on `grid_item`, `gallery_item`, `panel-slider_item`, `overlay-slider_item` and
+`slideshow_item`, but also `link_text` on **ten** item types and
+`link_aria_label` on **eight** — **eleven** types carry one or the other,
+including `accordion_item`, `switcher_item` and `table_item` (`link_text` only)
+and `social_item` (`link_aria_label` only) — plus `list_item`'s `icon` and
+`image_svg_color` and `popover_item`'s `drop_position`. An empty `link_text` on a
+`table_item` shows the TABLE's link text, not no text.
+
+### Which media actually renders — `media_autoswap`
+
+Image/video collisions are resolved **per element, and YOOtheme is not
+consistent about it**. Read the key; there is no default to assume.
+
+`"media_autoswap":{"precedence":["video","image","icon"],"sniffed":["image","video","hover_image","hover_video"]}`
+
+- **`precedence`** — the first non-empty prop renders; the losers are simply not
+  drawn. All seven builder media elements (`grid_item`, `panel`,
+  `panel-slider_item`, `gallery_item`, `overlay`, `overlay-slider_item`,
+  `slideshow_item`) are **video-first**, so setting both image and video shows the
+  video.
+- **`sniffed`** — these props are re-classified by URL sniffing and the value is
+  **MOVED** between `image` and `video`, nulling the other. **The field you wrote
+  may not be the field that renders**: an `.mp4` in `image` ends up in `video`.
+- **`clears_on_conflict`** — `section` and `column` **invert** the precedence
+  (image-first) **and** are destructive: with an image set, `video` is set to
+  `false`, so anything derived from it downstream sees no video. These two are the
+  only elements that do this.
+
+### `rules` + `rule_notes` — the rules that need a sentence
+
+The four keys above are arrays you can evaluate. Nine more rules have no array
+form, so they ship as prose — **stated once per response and referenced by id**,
+never repeated per prop:
+
+```json
+{ "name": "slideshow",
+  "rules": ["expand_model", "positional", "enable_is_ui_only"],
+  "rule_notes": { "expand_model": "…", "positional": "…", "enable_is_ui_only": "…" },
+  "fields": [ { "name": "slideshow_max_height", "enable": "!height_viewport",
+                "rules": ["slideshow_max_height_vs_render"] } ] }
+```
+
+- `rules` on the **element** = rules about the container's own template. They
+  survive a `field_names` / `name_contains` selection, because they are true of
+  the element whichever descriptors you asked for.
+- `rules` on a **field** = rules about that prop. Their notes are narrowed away
+  when the field is not returned, so a two-descriptor read pays for two.
+- `rule_notes` resolves every id the response still references, and only those.
+
+**`enable` and `show` are Builder-UI conditions only — they are not enforced.**
+In YOOtheme 5.0.37 the word `enable` appears **0×** in the theme's
+`packages/builder/src`, so no PHP render path reads either key and neither one
+guards an API write. They are still projected verbatim (they are the best
+statement of intent available), but they are wrong in **both** directions: a
+value the UI would refuse to let you edit is still stored and can still take
+effect, and a value whose `enable` was satisfied can still be dropped or
+overridden at render. Every prop where the render is known to disagree carries
+its own rule id — `slideshow_max_height_vs_render`, `thumbnav_ui_locked`,
+`nav_grid_needs_two`, `overlay_slider_two_positions`,
+`panel_slider_show_hover_video_dead` — plus the five-way `image_expand` split,
+which is in that field's `value_hint`.
+
+That last one is the shape to expect from the rest: on `panel-slider`,
+`show_hover_video` is a **dead switch**. Its three sibling containers (`grid`,
+`gallery`, `overlay-slider`) blank the item's `hover_video` when it is off;
+`panel-slider`'s item lists `hover_image` twice and `hover_video` not at all, so
+the hover video keeps rendering. Prop, label and default are identical to the
+three that work — nothing in the descriptor can reveal it. Clear the item's
+`hover_video` prop instead.
+
+Four rules to know before you write anything:
+
+- **Equal height is not one switch** (`expand_model`). A `grid` already matches
+  its column heights with nothing set; a `row` **never** does; a `column` matches
+  only under a specific prop combination, and setting a row height **removes**
+  matching from every column. `image_expand` expands the image, not the layout —
+  the content-expand lever is a `*_margin_auto` checkbox.
+- **A link toggle silently strips HTML** (`link_striptags`). With `panel_link` /
+  `overlay_link` / `card_link` on and a `link` present, YOOtheme's own renderer
+  runs `striptags()` over `title`, `meta` **and** `content`. The stored value
+  keeps the markup, so the loss is invisible in a read-back. This is YOOtheme's
+  renderer, not this server's, and it cannot be switched off.
+  **`list_item` is worse and gets its own id** (`link_striptags_ungated`): there
+  is **no checkbox** to turn off — as soon as the item has a `link`, `content` is
+  stripped, on both the with-image and the without-image render branch. To keep
+  markup there, leave `link` empty or move the markup to an element that is not
+  link-wrapped.
+- **A lightbox or modal drops the four link attributes**
+  (`modal_drops_link_attrs`). `link_target`, `link_download`,
+  `link_rel_nofollow` and `link_rel_noreferrer` are emitted only in the
+  plain-link render branch. With `lightbox` on and a link present, an earlier
+  branch wins and all four vanish — on `image`, and on `grid` and `gallery`
+  (whose item templates have the identical shape; the four props are declared on
+  the container). `button_item` does the same for a `dialog` with
+  `dialog_layout` `modal`/`offcanvas` and no `link`. Open-in-new-tab, download
+  and rel hints cannot be combined with a lightbox.
+- **An emptied container disappears with it** (`collapse_cascade`). A container
+  that HAD children and ends up with none is removed — the mark is keyed on the
+  element type's own `container` flag, and **21 element types** declare it in
+  5.0.37, so `grid`, `gallery`, `slideshow` and the rest go exactly the way a
+  `column` does. Items dropped by their own render gates therefore cascade
+  upwards and a page can lose a whole section with no error anywhere. Only
+  `column` offers `prevent_collapse`.
+
+A field's **value format** is stated on the field itself, in `value_hint` — a
+value that does not parse is usually removed or defaulted silently, never
+rejected. `countdown.date` must be `strtotime()`-parseable or the element
+disappears; `map_item.location` must be numeric `"lat,lng"` or the marker is
+skipped (no geocoding); an empty `map.height` becomes 300; a non-numeric
+`popover_item.position_x`/`_y` becomes 50 %.
+
 ## Dynamize an existing section (designed layout → live data, one call)
 
 **Goal:** Take a section you (or the customer) already designed by hand
@@ -2705,58 +3820,62 @@ perform.
 
 <!-- TOOL-CATALOG:BEGIN -->
 
-**49 catalogued tools** plus the `yootheme_builder_advanced` (write) + `yootheme_builder_advanced_read` (read-only) gateways = **51 reachable via `tools/list`** (37 L1 + 2 L3 + 2 gateways = 41 advertised; the gateways route to 10 additional advanced tools, bringing the total to 51 callable). Generated by `scripts/extract-tools.mjs` from the compiled `buildAllTools()` registry. Do not hand-edit this section; re-run `npm run build && node scripts/extract-tools.mjs` after changing tool definitions.
+**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.
 
 | 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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_diagnose` | read+idempotent | `site_id` | Full diagnostic: /health + authenticated /etag probe. Returns site_url, home_url, plugin reachability, Bearer validity in one call. First call when you need to know where the site lives. For per-template URLs see pages_list. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_add` | mutating | `children`, `element_type`, `etag`, `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. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_clone` | mutating | `element_path`, `etag`, `site_id`, `template_id` | Clone an element as a sibling (same parent, immediately after the source). Returns the new element's path. Cloning renumbers later siblings — re-read paths via element_list after any structural write. Requires ETag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_delete` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | PERMANENTLY delete an element + children. Cannot be undone. Pass `confirm: true` (boolean) AND a fresh ETag. 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. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_get_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | Read the source binding attached to an element. 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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_list` | read+idempotent | `cursor`, `depth`, `fields`, `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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_move` | idempotent | `element_path`, `etag`, `site_id`, `template_id`, `to_index`, `to_parent_path` | Move an element to a new parent + index in the tree. Useful for reordering or reparenting (e.g. moving a card from one grid column to another). Moving renumbers later siblings — re-read paths via element_list after any structural write. Requires ETag. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_type_get_schema` | read+idempotent | `element_type`, `fields`, `max_chars`, `site_id`, `type_name` | Fetch a type's prop schema before element_add/element_update_settings: unknown prop keys are hard-rejected (error lists valid_prop_keys + did_you_mean). Returns each field as {name,type,label?,enum?,value_hint?,group?}, field_count, and a binding_contract for container/item types. Read value_hint+enum first — some defaults are SEO-fatal (headline.title_element→h1); checkbox = boolean true/false; group:"runtime-accepted" = honoured at render but hidden in the builder UI. Bound size with fields[]/max_chars. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_types_list` | read+idempotent | `fields`, `site_id` | List element types registered on this site (built-ins + YOOessentials/uEssentials extras). Names feed `element_type` of element_add. Pass `fields[]` to narrow each row. Keywords: "slider"/"carousel" → `slideshow`/`panel-slider`/`overlay-slider`. Prop keys differ per element (grid_item `title` vs headline `content`) — use element_type_get_schema before element_add/bind. Container rows carry `requires_child_type` (grid→grid_item); `has_children`/`has_children_support` are aliases (same value). Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_unbind_source` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | Remove the source binding from an element. Clears 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. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_get_etag` | read+idempotent | `site_id` | Get the current ETag (state revision) for the YOOtheme builder. Returns 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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_health` | read+idempotent | `site_id` | Check plugin installed/reachable. Returns plugin version, YT Pro version, REST endpoints. Authenticated payload adds site_url + home_url for deep-linking. See yootheme_builder_diagnose for Bearer-validity + connectivity summary. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_image_search` | read+idempotent | `color`, `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). Operates on the default site unless site_id is provided. |
-| `yootheme_builder_inspect_multi_items_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | Reports Multi-Items binding state: container/item pair (grid↔grid_item, slideshow↔slideshow_item, map↔map_item, …), 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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_inspect_sublayout` | read+idempotent | `element_path`, `site_id`, `template_id` | Inspects a panel/grid_item `< SUBLAYOUT`: lists the `fragment` subtree bindable leaves (with JSON-Pointer paths to bind on — NOT the container) and the render-time inner grid. Flags `ungated_grid_prop` (blocking): grid props set but the gate (title_align=left / image_align=left\|right) unsatisfied → silent no-op. For container↔item binding see inspect_multi_items_binding. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_layout_query` | read+idempotent | `cursor`, `fields`, `has_binding`, `limit`, `max_chars`, `max_depth`, `name_matches`, `site_id`, `template_id`, `type`, `under_section` | Find elements in a template by a structured filter (no expression language). AND-combine any of: `type` (one type or a list), `name_matches` (case-insensitive substring of the element name), `has_binding` (bound vs unbound), `max_depth` (cap descent — 0 = top-level), `under_section` (only nodes inside a named section). template_id only — resolve a URL/post first via pages_resolve. Returns matching rows {path, element_type, label, has_binding}; paginate with `limit`/`cursor`, narrow rows with `fields[]`, bound text with `max_chars`. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_library_browse` | read+idempotent | `cursor`, `element_type`, `has_effects`, `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. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `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). Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_local_content_read` | read+idempotent | `fields`, `include_children`, `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[]`. Operates on the default site unless site_id is provided. |
-| `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"}. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `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). Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_get_schema` | read+idempotent | `fields`, `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. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `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). Operates on the default site unless site_id is provided. |
-| `yootheme_builder_pages_audit` | read+idempotent | `checks`, `max_chars`, `site_id`, `stale_after_months`, `target`, `thin_content_threshold`, `types` | One-call site-wide SEO/structure/content/links audit — severity-sorted findings with fix_hints (each a props FRAGMENT to merge, not a ready-made call — supply template_id + path from the finding locator). Covers h1/headings, thin pages, image alt, duplicate layouts, title collisions, non-pretty URLs, dead anchors. A SITE-wide sweep caps hits/page and drops per-hit content_snippet; scope to ONE page via `target` for the full set (cap 100). Filter with `types`/`checks`. Disclaimer: SEO-plugin meta (title/description/OG) NOT covered. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_pages_create` | idempotent | `dry_run`, `layout`, `menu_item`, `published`, `site_id`, `slug`, `status`, `title` | Create a page (WordPress) or article (Joomla 5/6) with a YOOtheme per-page layout. Required: title. Optional: slug, status (default draft), published (default false → live on true: WP publish / Joomla state 1), layout (JSON), menu_item (Joomla SEF route), dry_run (preflight, no persist). Returns page_id (WP) / article_id (Joomla), slug, template_id (page:{id} or article:{id}), etag, warnings. Joomla: a published article has NO SEF route until a menu item points at it — pass menu_item, else frontend_url may 404. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_pages_delete` | 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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_pages_list` | read+idempotent | `cursor`, `fields`, `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 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`. Operates on the default site unless site_id is provided. |
-| `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}. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_sites_list` | read+idempotent | `site_id` | List all sites configured in this multi-site MCP installation. Returns site_id + URL + platform (wordpress\|joomla) + default flag per row. CALL THIS FIRST when working with a fresh MCP connection to discover available site_ids before targeting one with any other tool. Read-only, no REST calls. Keywords: list sites, list connections, list installations, discover site_id, available sites, configured sites, what sites exist, multi-site index. 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` | 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_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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_sources_list` | read+idempotent | `cursor`, `fields`, `group`, `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`. Operates on the default site unless site_id is provided. |
-| `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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_template_summary` | read+idempotent | `site_id`, `template_id` | Token-efficient template overview: element counts by type, binding count, max nesting depth, and named landmark sections — computed server-side in one call. Use this to grasp a large template before pulling element_list or page_get_layout. template_id only — resolve a URL/post first via pages_resolve. Example: yootheme_builder_template_summary({ template_id: "default" }). Operates on the default site unless site_id is provided. |
+| `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. |
 
 <!-- TOOL-CATALOG:END -->