@wootsup/yt-builder-mcp 1.9.0 → 1.11.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 47 typed, scoped,
-idempotent tools (49 callable end-to-end with the two gateways). 41 of them
+`@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
 advertised as first-class entries in `tools/list`
-(37 essential L1 forwards + 2 direct L3 entries + 2 gateways), and 8 advanced
+(37 essential L1 forwards + 2 direct L3 entries + 2 gateways), and 10 advanced
 tools reachable through the gateways. The write-capable
-`yootheme_builder_advanced` gateway routes all 8; the read-only
+`yootheme_builder_advanced` gateway routes all 10; 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) and is itself
+local_content_read, pages_audit) 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.
@@ -55,7 +55,7 @@ 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 8 advanced tools; the
+  The `yootheme_builder_advanced` gateway routes all 10 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
@@ -125,10 +125,11 @@ 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).
-- **8 advanced captured tools**: everything else (page_get_schema,
+- **10 advanced captured tools**: everything else (page_get_schema,
   element_unbind_source, clean_implode_directives,
-  `inspect_sublayout`, `layout_query`, `library_save_as`, and the two Local
-  Content Read tools `local_content_types` / `local_content_read`).
+  `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`).
   Reachable through one gateway tool:
   `yootheme_builder_advanced({ tool: "<name>", arguments: { ... } })`. For
   example, to inspect a panel/grid_item `< SUBLAYOUT`:
@@ -143,6 +144,18 @@ The server exposes:
   It flags `invalid_source_possible: true` when the saved subtree carries
   bound dynamic sources that may not exist wherever it is later reloaded —
   re-bind after inserting it elsewhere.
+  And to clean up an experimental saved entry (PAGES_LIBRARY_MEDIA-16 — the
+  INVERSE of `library_save_as`; `source` defaults to `"ai"`, the ONLY deletable
+  store; the curated library is read-only):
+  `yootheme_builder_advanced({ tool: "yootheme_builder_library_delete", arguments: { id: "955bd3dc" } })`.
+  Pass the `id` from a `library_browse({ source: "ai" })` row; an unknown id
+  returns a 404, and `source: "catalog"` returns a 403 (read-only).
+  And to run a one-call site-wide SEO/structure/content/links audit
+  (read-only, severity-sorted findings + machine-executable fix_hints),
+  prefer the read gateway:
+  `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
   are now **L1 — call them directly by name**, not through a gateway:
@@ -184,7 +197,8 @@ The server exposes:
 - **2 gateway tools**: `yootheme_builder_advanced` (write-capable; can route
   into delete/unbind, so hosts gate it) and `yootheme_builder_advanced_read`
   (read-only; routes ONLY the read-only advanced subset — page_get_schema,
-  inspect_sublayout, layout_query, local_content_types, local_content_read —
+  inspect_sublayout, layout_query, local_content_types, local_content_read,
+  pages_audit —
   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 } })`.
@@ -196,8 +210,8 @@ The server exposes:
   `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 49
-(41 advertised + 8 advanced reachable through the gateways). If the AI
+essentials + 2 L3 direct + 2 gateways. The total callable surface is 51
+(41 advertised + 10 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
@@ -266,6 +280,100 @@ 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.
 
+### Address a page WITHOUT its URL — the `target` object
+
+`pages_resolve` and `pages_audit` take the **same** `target` object, so one
+addressing vocabulary covers both "which template renders this?" and "audit just
+this page". Supply **exactly ONE of** these five keys:
+
+| Key | Value | Example |
+|-----|-------|---------|
+| `template_id` | An exact template id | `{ template_id: "page:4816" }` |
+| `post_id` | The numeric WP post / Joomla article id | `{ post_id: 4816 }` |
+| `url` | A public frontend URL (same resolver as `pages_resolve({ url })`) | `{ url: "https://example.com/schedule-demo/" }` |
+| `special` | A semantic page ROLE (vocabulary below) | `{ special: "home" }` |
+| `title` | Case-insensitive substring of the page NAME/label | `{ title: "SunWest" }` |
+
+**On the wire it stays one object.** MCP-native transports pass `target`
+through as the object above; the REST transport encodes it as **bracket params**
+— `?target[special]=home`, `?target[template_id]=page:4816`,
+`?target[url]=<url-encoded URL>` — which WordPress and Joomla both parse back
+into an array natively. Same key names either way, so what you read in the table
+is what goes over the wire on either CMS. You never build that querystring
+yourself; it matters when you read a server log or reproduce a call with `curl`.
+
+**The special vocabulary (all ten tokens):** `home` and `front-page` resolve
+through the platform's front-page configuration (WordPress `show_on_front` /
+`page_on_front`; Joomla's default menu item). `blog` resolves through
+WordPress's `page_for_posts` setting, and on Joomla through the site's blog
+**menu item** (see the caveat below). `search`, `404`, `category`, `tag`,
+`author` and `archive` resolve forward through the template type index.
+`date` is recognised but unsupported on
+BOTH platforms and returns
+`special_not_supported` — say so rather than guessing a date archive.
+
+**Three platform caveats worth stating up front:**
+
+- On **Joomla**, `author` maps to the **Contact** template
+  (`com_contact.contact`) — Joomla has no post-author archive, so the contact
+  view is the conventional analogue. Do not report it as a WordPress-style
+  author archive.
+- On **Joomla**, `blog` is a **menu item**, not a site setting.
+  There is no Joomla equivalent of `page_for_posts`, so the resolver reads the
+  published site menu: a `view=featured` item wins outright (it is the
+  site-wide news front); otherwise the `view=category&layout=blog` items
+  decide. Those items are reduced to the DISTINCT TEMPLATES they resolve to
+  before anything is reported: several menu items governed by one template are
+  one page, and a blog category governed by no template is dropped rather than
+  offered as a dead address. One template left resolves outright — even when a
+  dozen menu items led to it. **Two or more return `blog_ambiguous`** (HTTP
+  409) with the same `candidates` shape as `title_ambiguous` — one row per
+  distinct blog page, `label` being the menu title the user recognises and `id`
+  the governing template, always present and always usable. Show the list and
+  let the user choose; then re-address the page with
+  `target.template_id`, `target.url` or `target.title`.
+  Sites with no blog menu item at all fall back to the post-archive template.
+  `special: "home"` is unaffected — it still resolves the default menu item.
+- `date` is unsupported on both platforms (there is no date-archive vocabulary
+  yet), which is why it returns a precise `special_not_supported` instead of an
+  "unknown token" error.
+
+**Typed failures, so you never have to guess what went wrong:** two or more keys
+(or `url` alongside a `target`) → `too_many_targets`; a `title` matching nothing
+→ `title_no_match`; a `title` matching two or more pages → `title_ambiguous`, with
+a `candidates` list (max 10) to pick from — show that list to the user instead of
+choosing for them; `special: "blog"` on a Joomla site with several blog menu
+items → `blog_ambiguous`, carrying the same `candidates` list under the same
+rule. A token that is resolvable in principle but matches no
+template on this site → `special_not_resolvable`. Supplying NO address is not an
+error — it falls back to each tool's default: `pages_audit` sweeps the whole
+site, while `pages_resolve` needs one and answers `missing_url`.
+
+**Every typed code this error envelope carries, and what to do about it.** Most
+concern the ADDRESS; a couple concern the rest of the request shape. The code is
+the contract; the HTTP status only groups them. A code you do not recognise is
+never a transport failure — report it verbatim rather than retrying blindly.
+
+| Code | Status | What happened | What to do |
+|------|--------|---------------|------------|
+| `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.** |
+| `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. |
+| `url_no_match` | 404 | The URL is well-formed but resolves to no per-page layout — usually because a theme template renders it. | Use `pages_list` to find the governing template, or `pages_resolve({ url })` for the fuller hint. |
+| `title_no_match` | 404 | No page NAME contains that substring. | Try a shorter substring, or list with `pages_list`. |
+| `special_not_resolvable` | 404 | The token is in the vocabulary and resolvable in principle, but matches no template on THIS site. | Report which role was requested; do not silently fall back to another page. |
+| `title_ambiguous` | 409 | The substring matches two or more pages. | A `candidates` list (max 10) rides along — show it and let the user choose. |
+| `blog_ambiguous` | 409 | Joomla only: several distinct blog pages. | Same `candidates` shape; show it (see the Joomla caveat above). |
+| `special_not_supported` | 422 | The token is recognised but this platform has no such page role (today: `date`, on both). | Say so plainly instead of guessing an analogue. |
+| `target_not_scannable` | 422 | **The target resolved to a real page, but this site does not enumerate it as an auditable page** — a post type or status the page enumerator does not cover, or a trashed item. | **This is NOT a clean result.** An audit that answered 200 with zero findings would read as "your page is fine"; this code exists precisely so it cannot. Audit it via `template_summary`, or pick a page `pages_list` returns. |
+
+`server_too_old` is the one code the SERVER never sends — see
+[Audit ONE page instead of the whole site](#audit-one-page-instead-of-the-whole-site).
+
 ## Scopes (Bearer key permissions)
 
 Every Bearer key has a scope, set at key creation time:
@@ -474,6 +582,25 @@ templates are for), but confirm the intent — do not edit a `single-post` /
   templates are defined in the theme itself and are not created via this MCP;
   you edit the existing ones `pages_list` reports.
 
+**Reaching a theme template by ROLE instead of by id.** You rarely know a theme
+template's opaque id (`I99YS8Ii`). The `special` tokens of the shared `target`
+object address these templates by what they SERVE, on both `pages_resolve` and
+`pages_audit`:
+
+| `target` | Lands on |
+|----------|----------|
+| `target: { special: "home" }` | The configured front page (a `page:<n>` when the site serves a static front page, otherwise the posts/archive template) |
+| `target: { special: "blog" }` / `{ special: "archive" }` | The posts page / `archive-post` template |
+| `target: { special: "404" }` | The `error-404` template |
+| `target: { special: "search" }` | The `search` template (Joomla: `com_finder.search`) |
+| `target: { special: "category" }` / `{ special: "tag" }` | The `taxonomy-category` / `taxonomy-post_tag` template (Joomla: `com_content.category` / `com_tags.tag`) |
+| `target: { special: "author" }` | The author archive — on **Joomla** the Contact template |
+
+So "audit the 404 page" is one call with `target: { special: "404" }`, and the
+response's `resolved_target` tells you which template that actually was. The
+same safety rule still applies: a finding on a theme template is a finding on
+EVERY page that template renders.
+
 ## Workflow 1: Build a hero section
 
 **Goal:** Add a fresh hero section (heading + sub-heading + CTA button)
@@ -736,6 +863,12 @@ must have **exactly one** `<h1>`). Set it explicitly on every headline:
 for punch); a big stat number is `title_element: "div"` with
 `title_style: "heading-medium"`.
 
+**This `h1` default is specific to `headline`.** Container elements
+(`grid`, `panel`, `slideshow`, and the rest of the item-carrier family)
+default to `h3`, not `h1`, when `title_element` is left unset. See
+"Workflow 6 (SEO audit)" below for the full per-type default table
+`pages_audit` uses to find missing/multiple h1 issues across a whole site.
+
 ### Headline `content` is plain inline text — never wrapped in `<p>`
 
 A `headline` renders its `content` **inside** the heading tag, so wrapping it
@@ -1238,7 +1371,563 @@ and the props payload you passed.
 
 ---
 
-## When something doesn't fit one of these 5 workflows
+## Workflow 6: SEO audit (pages_audit)
+
+**Goal:** Run one deterministic, site-wide sweep for structure, content,
+SEO, and link issues, drill into the pages a finding names, and fix them
+one page at a time through the existing write tools this server already
+exposes. Never analyze findings by hand and never bulk-apply a fix.
+
+**Canonical tool-call sequence (real parameter names, snake_case):**
+
+1. `yootheme_builder_advanced_read({ tool: "yootheme_builder_pages_audit", arguments: { checks: ["seo", "structure"] } })`
+   sweeps the whole site in one call. `pages_audit` is a read-only
+   advanced tool, so reach it through the read gateway (the write
+   gateway routes it too, but the read gateway never triggers a
+   write-approval prompt). Omit `checks`/`types` to run every category
+   against every scanned template.
+2. Read the response's `findings` array. Each finding carries a `code`,
+   `category`, `severity`, a `count`, up to 30 affected `pages`, and
+   (where a safe automatic fix exists) a `fix_hint` naming the exact
+   write tool and args template to run. `duplicate-layout` and
+   `title-collision` never carry a `fix_hint` — they need a human
+   decision (rename, merge, or intentionally keep as-is), not an
+   automatic patch.
+3. `yootheme_builder_template_summary({ template_id })` 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.
+4. Fix that ONE page via the write tool named in `fix_hint.tool`, with
+   `fix_hint.args_template` as a starting point (`element_update_settings`,
+   `element_add`, etc), ETag-locked like every other write in this
+   server.
+5. `yootheme_builder_page_publish({ template_id, etag })` republishes.
+   The response's `quick_check` block (default on) re-checks THIS page
+   with the same per-page codes, so you can confirm the fix landed
+   without a second full sweep.
+
+**Common pitfalls:**
+
+- **Promising a full SEO audit.** `pages_audit` covers Builder structure
+  and CMS basics only: heading hierarchy, empty/thin pages, missing
+  image alt text, duplicate layouts, title collisions, non-pretty URL
+  fallbacks, stale content, and dead in-page anchors. Every response
+  carries a fixed disclaimer field:
+  `"Meta title/description/OG live in your CMS SEO plugin — not covered here."`
+  It does not read or evaluate Yoast/RankMath/any SEO-plugin meta
+  title, meta description, or Open Graph tags. Say this scope boundary
+  out loud and point the user at their SEO plugin for that layer.
+- **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`
+  instead uses a narrower CONTENT count (`elements_content` in the
+  evidence) that excludes `section`/`row`/`column`/`fragment`/`layout`
+  wrapper nodes: an empty section nested in three columns is correctly
+  `0` content elements, not "not empty" just because the wrappers
+  exist. Both numbers ride in the evidence (`elements_total` and
+  `elements_content`). `thin-content` fires when `elements_content` is
+  below `thin_content_threshold` (default 8); `empty-page` fires at
+  `elements_content === 0`.
+- **The h1-default trap.** Only `headline` defaults to `h1` when
+  `title_element` is unset. A container element (`grid`, `panel`,
+  `slideshow`, and the rest) left unset does NOT become an `<h1>` — it
+  becomes an `<h3>` (or stays a non-heading `div` for
+  `description_list`). See the per-type default table below and
+  "`title_style` vs `title_element`" above (that section's "defaults
+  to `h1`" rule is specific to `headline` only). `meta_element` is a
+  SECOND, independent heading channel on the same container types,
+  defaulting to `div` and counting only when explicitly set to
+  `h1`-`h6` with `show_meta` not `false`.
+- **Treating a bound-but-empty slot as missing.** Bound title/meta
+  slots count as filled even when the static prop text is empty — a
+  title bound to a dynamic source field is not "missing" just because
+  the builder-side prop is blank. The same exemption applies to
+  `image_alt`/`background_image_alt`: `images-missing-alt` never flags
+  a bound image-alt slot, only an unbound, empty, or whitespace-only
+  alt on a static image.
+- **Flagging every `#`-prefixed value as a dead anchor.** A
+  `dead-anchor` finding fires only for a genuinely dangling `#name`
+  link whose target element `id` does not exist anywhere on the same
+  page. It explicitly excludes a bare `#` (a placeholder, never a real
+  target), `mailto:`/`tel:` links, `http(s)://` external links, and
+  cross-page links like `?page_id=…#…` (that anchor lives on a
+  different page's render and cannot be verified from this page's own
+  `props.id` set).
+- **Treating `missing-h1` as critical, or double-flagging it.**
+  Severity is calibrated from live empirical review, not per-rule
+  guessing: `no-headings` (zero headings anywhere on the page) is
+  critical, but `missing-h1` (headings exist, but none is an effective
+  h1) is only a warning, and it is suppressed entirely when
+  `no-headings` already fired for the same page. Real sites
+  legitimately have h2/h3-only pages with no h1.
+- **Treating `quick_check` findings as a publish failure.** `quick_check`
+  is advisory only: publish and save always succeed regardless of what
+  it reports. This is not the blocking render-precheck (which still
+  gates on genuinely broken output) — SEO/structure findings are
+  hints, not corruption. `quick_check` only ever includes checks whose
+  `scope` is `"per-page"`; `duplicate-layout` and `title-collision`
+  need the whole site swept to mean anything, so they never appear
+  here — instead the block carries a fixed note:
+  `"run pages_audit for site-wide checks"`. `page_publish` attaches
+  `quick_check` by default (set `quick_check: false` to opt out, e.g.
+  scripted bulk publishes); `page_save` carries it only when you opt
+  in with `quick_check: true`.
+
+> **Changed: the advisory block got bigger and stricter.** Three Tier-2 checks
+> — `anchor-text-quality` (warning), `generic-alt-text` (info) and
+> `long-heading` (info) — are `per-page`, so they joined `quick_check`
+> automatically, and every finding now carries per-hit **locators** (breadcrumb,
+> element name, JSON-Pointer path, snippet). Measured on a page that trips them:
+> ~7.5 KB of `quick_check`, roughly 3.3 KB of it locators, against ~1.5 KB
+> before. It is BOUNDED, not open-ended — the per-page hit cap holds the block at
+> roughly 11 KB even on a 500-element page — and a clean page is still just
+> `{ clean: true }`.
+>
+> **What this means for you, not for the customer.** `anchor-text-quality`
+> matches the generic-CTA list EXACTLY, and that list is bilingual: `mehr`,
+> `hier`, `mehr erfahren`, `weiterlesen` alongside `click here` / `read more`.
+> On a German site those are ordinary house-style buttons, so a perfectly good
+> publish can come back carrying a `warning`. **Do not report a warning-severity
+> `anchor-text-quality` as a failed publish, and do not "fix" the customer's
+> button copy unasked** — say the publish succeeded, mention the advice once,
+> and move on. There is no per-check switch on the publish path today: the only
+> lever is `quick_check: false`, which also silences `missing-h1`,
+> `empty-page`, `images-missing-alt` and `dead-anchor`. Prefer living with the
+> advisory over turning the block off.
+
+**Per-type `title_element` default table (the correctness crux of every
+heading finding):**
+
+| Element type(s) | `title_element` default | Counts as heading? |
+|---|---|---|
+| `headline` | `h1` | Yes, unless explicitly overridden. |
+| `comments` (WP source) | `h2` | Yes, always active. |
+| `alert`, `gallery`, `grid`, `map`, `overlay`, `overlay-slider`, `panel`, `panel-slider`, `popover`, `slideshow`, `switcher` | `h3` | Yes, when `show_title` is not `false` and the title is non-empty or bound. |
+| `description_list` | `div` | No. |
+| `section` (Section Title) | (no field; hardcoded `<div class="tm-section-title">`) | No, ever (counted only as an informational `section_titles` tally). |
+
+`div` never counts as a heading whether it came from an explicit value
+or a type default.
+
+### Audit ONE page instead of the whole site
+
+Pass the shared `target` object (see "Address a page WITHOUT its URL" above) to
+scope the sweep to a single page — by `template_id`, `post_id`, `url`,
+`special` or `title`, exactly one of them:
+
+```jsonc
+yootheme_builder_advanced_read({
+  tool: "yootheme_builder_pages_audit",
+  arguments: { target: { special: "home" } }
+})
+```
+
+What changes in the response:
+
+- **`scope: "single"`** — the positive proof the sweep was scoped. If you sent a
+  `target` and the response is not scoped, the tool returns
+  `server_too_old` instead of handing you a site sweep dressed up as a page
+  audit: the site's host plugin predates single-target addressing and must be
+  updated. This is the ONE code the server never sends — the client raises it
+  after comparing what it asked for against what came back.
+- **`target_not_scannable` is a refusal, never a pass.** A `target` can resolve
+  to a real page that this site does not enumerate as an auditable one — a post
+  type or status the page enumerator does not cover, or a trashed item. Rather
+  than answer `200` with zero findings, which reads as "your page is clean", the
+  tool returns `target_not_scannable` (HTTP 422). Tell the user the page could
+  not be audited and why; then audit it via `template_summary`, or pick a page
+  `pages_list` returns. Never present it as a clean result.
+- **`resolved_target`** — `{ template_id, post_id, type, label, frontend_url,
+  context, resolved_via, matched_by }`. This is the echo of WHICH page a fuzzy
+  address landed on. Always report it: `special: "home"` and
+  `title: "SunWest"` are guesses until the server says what they resolved to.
+- **`note`** — the shared, verbatim sentence `run pages_audit for site-wide
+  checks`. A single page cannot be compared against other pages, so the two
+  site-scope checks (`duplicate-layout`, `title-collision`) self-filter out.
+- **Richer per-hit evidence.** Single mode raises the per-page hit cap from 5 to
+  **100 hits per check** and adds a `content_snippet` to every locator (the site
+  sweep omits snippets to keep a whole-site payload small). The text leg also
+  gains a `Where to fix:` block with the locator lines; the site sweep keeps its
+  compact 5-column summary table, with the locators in `structuredContent` only.
+- **The summary table's count column counts HITS, and says so.** In a site sweep
+  that column is headed `COUNT` and holds the number of affected **pages**. A
+  single-page sweep scanned exactly one page, so that number would be `1` for
+  every finding and tell you nothing — there the column is headed **`HITS`** and
+  holds the number of individual occurrences **on that page** (19 alt-less
+  images ⇒ `19`, not `1`). It is the uncapped total: `hits_truncated` shortens
+  the listed locators, never this figure. Report the `HITS` number as the size
+  of the problem. `structuredContent.findings[].count` is unaffected by the
+  column — it stays the affected-PAGE count in every scope, so read the table
+  (or the page entry's own `hits`) when you want the per-page hit total.
+- **`hits` is the unambiguous field; `count` means two different things.** On
+  this wire `count` is level-dependent: on a FINDING it counts affected **pages**
+  (so it is `1` for every finding of a single-page audit), and on a **page entry**
+  it counts hits on that page. One name, two meanings — and that ambiguity has
+  already produced a live misread, an agent reporting "one image is affected"
+  when nineteen were. So the host emits **`hits`** next to a page entry's `count`
+  whenever that count really is a hit tally: `findings[].pages[].hits`. Prefer it.
+  It is an alias, never an invention — a page entry with no hit total (the PAGE
+  ITSELF is the hit: `thin-content`, `empty-page`, `duplicate-layout`) carries no
+  `hits` key at all, and a host plugin older than the alias sends only `count`.
+  Fall back to `pages[].count` in both cases, never to `findings[].count`.
+- **On the plugin-served transport there is no summary table at all.** The
+  `HITS`/`COUNT` column is rendered by the npm server. When the MCP server is the
+  CMS plugin itself, the response is the JSON payload — so nothing labels the
+  columns for you and the guidance above is the only thing standing between you
+  and the misread. Read `findings[].pages[].hits` (falling back to
+  `pages[].count`) and **never report `findings[].count` as the size of a
+  single-page problem**: in single-target mode it is structurally `1`.
+
+Two request shapes are refused up front, with a typed error rather than a
+round-trip: more than one address key → `too_many_targets` (pick one; use
+`title` or `pages_list` when you only know the page by name), and `target`
+together with `types` → `types_conflicts_with_target` (a target already names
+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.
+
+### Remediation catalog — what each finding means and how to fix it
+
+The audit reports; YOU explain. Every finding below carries its fixed
+`category` and `severity` from the server (never re-rank them), and the entries
+whose fix is mechanical carry a `fix_hint` naming the write tool and an
+`args_template`. The rest need a human decision — say so instead of inventing a
+patch.
+
+#### `empty-page` — structure · critical
+
+**Why it matters.** A page with zero content elements is a dead end for readers
+and, once published, a soft-404 signal for crawlers: there is nothing to index,
+and internal links pointing at it leak crawl budget.
+**How to fix.** `element_add` at least one content element (headline, text,
+image). `fix_hint.tool = element_add`.
+**Severity.** Critical because the page fails at its only job. This is measured
+on the CONTENT count (`elements_content`), so wrapper-only pages — three nested
+columns around nothing — are correctly flagged rather than passing as "not
+empty".
+
+#### `no-headings` — structure · critical
+
+**Why it matters.** With no heading of any level the page has no machine-readable
+outline: search engines get no topical anchor, and screen-reader users lose the
+heading-jump navigation they rely on to skim a page.
+**How to fix.** `element_add` a `headline` with `props.title_element = "h1"`
+(that is the shipped `args_template`), then work down the hierarchy.
+**Severity.** Critical — it is an accessibility failure, not a style preference,
+and it is one element away from being fixed.
+
+#### `missing-h1` — structure · warning
+
+**Why it matters.** The h1 names what the page is about. Headings exist here but
+none resolves to an effective h1, so the page's main topic is never stated at the
+strongest available level.
+**How to fix.** `element_update_settings` with `props.title_element = "h1"` on
+the page's `first_headline_path` (the evidence carries it, and the locator points
+at it). When `first_headline_path` is `null` there is no `headline` element at
+all — the effective headings come from containers (`grid`, `panel`, …); add a
+headline rather than promoting a container title to h1 blindly.
+**Severity.** Only a warning, calibrated on live review: real, healthy sites run
+h2/h3-only pages. It is also suppressed entirely when `no-headings` already fired
+for the same page — never report both.
+
+#### `multiple-h1` — structure · warning
+
+**Why it matters.** Several h1s dilute the topical signal and flatten the outline
+a screen reader announces: everything looks equally important, so nothing is.
+**How to fix.** `element_update_settings` with `props.title_element = "h2"` on
+every hit except the one you keep. The locator's `heading_source` tells you WHICH
+channel produced each h1 (`panel-title` vs `panel-meta` — `meta_element` is a
+second, independent heading channel), which is exactly what the raw path cannot.
+**Severity.** Warning, not critical — the page still works. Read the evidence's
+`iterated` flag before you write: `iterated: true` means one authored h1 renders
+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-skip` — structure · info
+
+**Why it matters.** Jumping h1 → h3 breaks the document outline: assistive tech
+reports a missing level, and the hierarchy stops describing the real structure.
+**How to fix.** No `fix_hint` — the right level depends on intent. Either demote
+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.
+
+#### `images-missing-alt` — content · warning
+
+**Why it matters.** An image with a set source and empty alt text is invisible to
+screen readers and to image search — the content of the image simply does not
+exist for anyone not looking at it.
+**How to fix.** `element_update_settings` with `props.image_alt` (or
+`props.background_image_alt` on a `popover` — the locator's `prop` field names
+which one). Describe what the image SHOWS, not that it is an image.
+**Severity.** Warning. Two exemptions keep it honest: a **bound** alt slot is
+never flagged (a dynamically-bound alt is not missing just because the builder
+prop is blank), and a genuinely decorative image may legitimately keep an empty
+alt — mention that possibility instead of mass-filling every slot.
+
+#### `thin-content` — content · warning
+
+**Why it matters.** A page with very few content elements rarely answers the
+query that brought a visitor to it, and a site full of them dilutes topical
+authority.
+**How to fix.** No `fix_hint` — no tool can write substance. Report the
+`elements_content` count against the threshold and propose merging the page into
+a stronger one or expanding it.
+**Severity.** Warning, and threshold-driven (`thin_content_threshold`, default
+8): a deliberately minimal landing page can be perfectly healthy. Pages at zero
+are excluded here — `empty-page` owns that case.
+
+#### `duplicate-layout` — content · warning (site-wide)
+
+**Why it matters.** Several pages sharing an identical structural layout is
+usually a sign of near-duplicate content competing for the same query, or of a
+template that should have been a theme template.
+**How to fix.** No `fix_hint` — this needs a human decision: consolidate,
+differentiate, or accept it (a product-page family SHOULD look alike). Group the
+report by the evidence's `cluster_id`.
+**Severity.** Warning, and it compares pages against EACH OTHER, so it only runs
+in a site sweep — it never appears in a single-page audit or in `quick_check`.
+
+#### `title-collision` — seo · warning (site-wide)
+
+**Why it matters.** Two pages with the same title are indistinguishable in search
+results, in the browser's tab bar and in your own `pages_list` — and they
+cannibalise each other's ranking for the same term.
+**How to fix.** No `fix_hint` — renaming is an editorial call. Note that
+comparison is normalised (lowercased, punctuation collapsed), so "A – B" and
+"A — B" collide by design; that is not a false positive.
+**Severity.** Warning, site-scope only — same exclusion as `duplicate-layout`.
+
+#### `non-pretty-url` — seo · info
+
+**Why it matters.** A `?page_id=…` / `?p=…` URL carries no keywords, is ugly to
+share, and signals a permalink configuration that was never finished.
+**How to fix.** No `fix_hint`, and deliberately so: this is fixed in the CMS
+(WordPress Settings → Permalinks, Joomla SEF settings / a menu item), NOT with a
+builder write tool. Say that plainly. The evidence's `reason` reads `non-pretty`
+on every hit today: publication status is not yet surfaced by the page
+enumerator, so a DRAFT — which often has no pretty URL yet and needs no action —
+is reported exactly like a published page. Mention that possibility rather than
+presenting every hit as actionable.
+**Severity.** Info: it is a hygiene issue, and the page still resolves.
+
+#### `stale-content` — seo · info
+
+**Why it matters.** Content untouched for years drifts out of date; freshness is
+a weak ranking factor but a strong trust factor for readers.
+**How to fix.** No `fix_hint` — review and update, or deliberately mark it as
+evergreen. Report the `modified_at` date, not just the flag.
+**Severity.** Info, threshold-driven (`stale_after_months`, default 24). A page
+with an empty `modified_at` is never flagged, so absence of the finding is not
+proof of freshness.
+
+#### `dead-anchor` — links · warning
+
+**Why it matters.** An in-page `#name` link whose target id does not exist on the
+page silently does nothing when clicked — the visitor concludes the site is
+broken, and a jump-navigation is often exactly the thing that was supposed to
+make a long page usable.
+**How to fix.** No `fix_hint`, because there are two equally valid fixes and only
+you know which was intended: correct the link, or give the intended target
+element `props.id = <name>` via `element_update_settings`. The locator carries
+the missing `name`.
+**Severity.** Warning. The check is deliberately narrow — a bare `#`,
+`mailto:`/`tel:`, external `http(s)://` links and cross-page `?page_id=…#…`
+links are all excluded — so a hit is a genuine dangling anchor, not a heuristic.
+
+#### `anchor-text-quality` — links · warning
+
+**Why it matters.** Anchor text is the strongest on-page relevance signal a link
+can send, and screen-reader users navigate by a flat list of link texts — a
+screen full of "Mehr" and "Read more" is unusable out of context.
+**How to fix.** `element_update_settings` with `props.content` naming the
+destination ("Preise ansehen" instead of "Mehr"); on `grid_item` and `panel` the
+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`.
+**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
+"Mehr über SunWest" stays clean.
+
+`empty` states a precise rule, not "no accessible name at all": the type's
+**designated** text prop is empty AND the node carries no `icon`, `image`,
+`link_aria_label` or `link_text`, AND no sibling text that renders inside the
+same anchor — `content`/`meta` on `grid_item` and `panel` (both move the link
+onto the whole-card wrapper and render meta + content inside it), `meta` on
+`nav_item` (its `uk-nav-subtitle` sits inside the anchor). So a content-only
+linked card is NOT flagged. The remaining allowlisted types
+(`button`, `button_item`, `headline`, `list_item`, `subnav_item`) have no sibling
+text prop, so for them the designated prop is the only anchor text. A **bound**
+text prop is never flagged either, and `social_item` is icon-only by construction
+and is never checked at all.
+
+#### `generic-alt-text` — content · info
+
+**Why it matters.** Alt text like "Bild" or "Logo" names the MEDIUM, not the
+content: it passes an automated "has alt" check while telling a screen-reader
+user and an image crawler exactly nothing.
+**How to fix.** `element_update_settings` with `props.image_alt` describing what
+the image actually shows ("SunWest Büro in Manresa").
+**Severity.** Info, and strictly disjoint from `images-missing-alt` (which owns
+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.
+
+#### `long-heading` — structure · info
+
+**Why it matters.** A heading is a label, not a sentence. Long ones dilute the
+keyword focus, get truncated in search results and wrap badly on mobile.
+**How to fix.** `element_update_settings` shortening `props.content` (on
+`headline`) or `props.title` (on `panel`, `alert`, `overlay`) and moving the
+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`).
+Multi-Items containers keep their title text on the paired `*_item` children and
+are not measured — do not claim full heading-length coverage.
+
+`anchor-text-quality`, `generic-alt-text` and `long-heading` are all `per-page`
+checks, so they also ride in the `quick_check` block on `page_publish` /
+`page_save` alongside the other per-page codes.
+
+### The report contract — how to present an audit
+
+The raw response is a machine payload. What you hand the user follows this
+shape every time, so two audits of two sites read the same way:
+
+1. **Lead with the scope.** When `scope: "single"`, name the page the audit
+   actually ran on from `resolved_target` — label, `template_id`, and
+   `matched_by` when the address was fuzzy ("`special: "home"` resolved to
+   *Startseite* (`page:4816`)"). When the response has no `scope`, it was a site
+   sweep: lead with `scanned.templates` and the `summary` totals.
+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
+   code.
+4. **Render every hit from its locator**, in this shape:
+
+   ```
+   element_name (breadcrumb) · heading_source · ×repeat · snippet → Fix: <tool + args>
+   ```
+
+   Drop the parts a given finding does not carry (`heading_source` only exists on
+   the heading checks; `×repeat` only when it is greater than 1; `snippet` only
+   in single-page mode). Take `<tool + args>` from `fix_hint.tool` +
+   `fix_hint.args_template` when the finding has one, and say "needs a decision"
+   when it does not. The `path` is the write address — keep it for the tool call,
+   but it is not the human-facing part of the line.
+5. **Name the element. Always.** Every reported finding names the element TYPE
+   and its user-assigned name when one is set (`element_name`, falling back to
+   `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.
+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`
+   verbatim: `run pages_audit for site-wide checks`.
+7. **Be honest about truncation.** `hits_truncated: true` means the host's hit
+   cap dropped hits, so the listed evidence for that page is incomplete — a
+   single-page re-run returns up to 100 per check. `locators_stripped: true`
+   means the locator prose was shed (or halved) to fit the response budget.
+   They are not synonyms; do not report either as "that's all of them". A
+   top-level `structured_truncated: true` says the WHOLE payload was over its
+   char budget and the shed ladder ran, in this order: the DUPLICATE raw arrays
+   first (every field of `alt_paths` / `anchors` / … also rides on the locator
+   for the same hit, so nothing is lost), then the locator detail — halved
+   before it is dropped — then the remaining raw evidence, then whole evidence
+   pages (`pages_truncated`), so page ids and labels outlive the prose. Both
+   transports shed in exactly that order; it is pinned by a contract test that
+   derives the order from each implementation. Say so, and name the two ways
+   back: raise `max_chars` (it bounds both legs on this tool), or
+   re-run scoped to one page via `target`. `evidence_stripped: true` says the
+   raw per-hit arrays (`paths`, `alt_paths`, `anchors`, …) were dropped from
+   that entry while that page's id, label, hit count and `builder_url` were kept
+   — so the answer stays actionable (name the page, say how many hits, offer the
+   builder link) even when no per-hit detail survived. On a budget too small
+   even for that floor, the plugin-served transport refuses with
+   `max_chars_too_small` and tells you the minimum to ask for — it never returns
+   a half-written payload.
+8. **Repeat the scope boundary.** Close with the response's `disclaimer` — meta
+   title/description/OG live in the CMS SEO plugin and are not covered here — so
+   nobody mistakes a clean audit for a clean SEO plugin.
+
+Beyond that the prose is yours: group, summarise and prioritise however serves
+the user. Rules 2, 4, 5 and 6 are the parts that must not vary.
+
+A single-page report that follows the contract reads like this:
+
+```
+Audited: Startseite (page:4816) — matched by special:"home"
+2 findings — 0 critical / 2 warning / 0 info
+Site-wide checks (duplicate-layout, title-collision) did NOT run on a single
+page: run pages_audit for site-wide checks.
+
+WARNING · structure · multiple-h1 — page renders 2 h1s          [open in builder]
+  • Willkommen bei SunWest (Hero ▸ Headline) · headline
+      → keep this one as the page's h1
+  • Unsere Standorte (Karten ▸ Panel "Standorte") · panel-title · "Unsere Standorte"
+      → Fix: element_update_settings({ template_id: "page:4816",
+        element_path: "/children/1/children/0", props: { title_element: "h2" } })
+  Why: exactly one h1 anchors the page's topic; several dilute it.
+
+WARNING · content · images-missing-alt — 1 image without alt text
+  • Team photo (Über uns ▸ Grid ▸ Grid Item) · prop image_alt
+      → Fix: element_update_settings({ …, props: { image_alt: "<what it shows>" } })
+  Why: an empty alt makes the image invisible to screen readers and image search.
+
+Meta title/description/OG live in your CMS SEO plugin — not covered here.
+```
+
+**Worked example (tool-call snippet):**
+
+```jsonc
+// Step 1. Sweep the site for SEO + structure issues.
+yootheme_builder_advanced_read({
+  tool: "yootheme_builder_pages_audit",
+  arguments: { checks: ["seo", "structure"] }
+})
+// A finding: { code: "missing-h1", category: "structure", severity: "warning",
+//   count: 3, pages: [{ id: "page:42", label: "About" }, ...],
+//   fix_hint: { tool: "element_update_settings",
+//     args_template: { props: { title_element: "h1" } }, note: "..." } }
+
+// Step 3. Drill into the flagged page.
+yootheme_builder_template_summary({ template_id: "page:42" })
+// heading_levels: { h1: 0, h2: 2, h3: 5, div: 1 }, images_missing_alt: 2
+
+// Step 4. Fix that ONE page via the write tool the fix_hint named.
+yootheme_builder_element_update_settings({
+  template_id: "page:42",
+  element_path: "/children/0/children/0",
+  props: { title_element: "h1" },
+  etag: "abc123"
+})
+
+// Step 5. Republish; quick_check re-confirms this page is clean.
+yootheme_builder_page_publish({ template_id: "page:42", etag: "def456" })
+// Response: { ..., quick_check: { clean: true } }
+```
+
+**Success criterion:** A re-run of `pages_audit` (or the `quick_check`
+block on the next publish) no longer lists the fixed finding for that
+page, and the response's `summary.critical`/`warning`/`info` totals go
+down.
+
+---
+
+## When something doesn't fit one of these 6 workflows
 
 - **Move an element** (intra-template reorder/reparent): use
   `yootheme_builder_element_move({ template_id, element_path,
@@ -2016,56 +2705,58 @@ perform.
 
 <!-- TOOL-CATALOG:BEGIN -->
 
-**47 catalogued tools** plus the `yootheme_builder_advanced` (write) + `yootheme_builder_advanced_read` (read-only) gateways = **49 reachable via `tools/list`** (37 L1 + 2 L3 + 2 gateways = 41 advertised; the gateways route to 8 additional advanced tools, bringing the total to 49 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.
+**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.
 
 | Tool | Kind | Input keys | Description |
 | --- | --- | --- | --- |
-| `yootheme_builder_clean_implode_directives` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | Strips `props.source.props.*.implode` directives from an element binding. Returns audit log + new ETag. Idempotent at the server (cleaned_count: 0 when nothing to remove) but classed as destructive because the affected binding cannot be restored without re-mapping. Always ask the user to confirm first, then call again with `confirm: true`. Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_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`, `parent_path`, `position`, `props`, `site_id`, `template_id`, `type_name` | Add a new element to a template. Provide `parent_path` (or "" for root), `element_type` (e.g. "headline", "text", "grid"), and optional `props` / `children`. Appends by default; pass `index` (0 = first) to insert before siblings. Returns the new element's JSON-Pointer path. Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_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. Requires ETag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_delete` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | PERMANENTLY delete an element + children. Cannot be undone. Pass `confirm: true` (boolean) AND a fresh ETag. If `preview:true` returns despite confirm, check `details.received_confirm` — strings/numbers accepted, but boolean is canonical. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_get` | read+idempotent | `element_path`, `site_id`, `template_id` | Get the full element object at a specific JSON-Pointer path, including props and children. Use yootheme_builder_element_list to discover paths. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_get_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | Read the source binding attached to an element — the bound source name, the field-mappings (which source field feeds which element prop) and the query arguments/directives. Returns the empty object if the element is not bound. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_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. 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. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_move` | idempotent | `element_path`, `etag`, `site_id`, `template_id`, `to_index`, `to_parent_path` | Move an element to a new parent + index in the tree. Useful for reordering or reparenting (e.g. moving a card from one grid column to another). Requires ETag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_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, leaving every OTHER node unchanged (no 14 KB page_save). 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. an FAQ accordion scoped to the term: source.query.name="categoryFaqs.taxonomyCategoryFaq", field={name:"faq"}, source_extended.props maps title/content to #node. ETag req. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_type_get_schema` | read+idempotent | `element_type`, `site_id`, `type_name` | Fetch a type's prop schema before `element_add`/`element_update_settings`: an unknown prop key on a known schema is hard-rejected (not silently dropped); the error always lists `valid_prop_keys`, plus a `did_you_mean` hint when a close field exists. Returns `{name,type,label?}`. Use `element_type` (`type_name` is a deprecated alias). Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_types_list` | read+idempotent | `fields`, `site_id` | List element types registered on this site (built-ins + YOOessentials/uEssentials extras). Names feed `element_type` of element_add. Pass `fields[]` to narrow each row. Keywords: "slider"/"carousel" → `slideshow`/`panel-slider`/`overlay-slider`. Prop keys differ per element (grid_item `title` vs headline `content`) — use element_type_get_schema before element_add/bind. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_unbind_source` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | Remove the source binding from an element. Clears `props.source`. Destructive in the sense that it may break dynamic-content rendering — always ask the user to confirm. Requires ETag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_update_settings` | idempotent | `element_path`, `etag`, `merge`, `props`, `site_id`, `template_id`, `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 sha256+revision string used for optimistic locking on writes. Pass the returned value back as `etag` on any write tool (page_save, page_publish, element_add, element_update_settings, element_clone, element_move, element_delete). The server returns HTTP 412 if the ETag has changed since you read it. Keywords: get etag, current etag, state revision, optimistic lock, version stamp. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_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 chosen photo (typically a `full_url` from yootheme_builder_image_search) into the site's own Media Library. Returns `{imported:true, local_url}`. Bind local_url into an element 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_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, …), current binding level (none\|container\|item), and a recommended_fix when the binding sits on the container instead of the child. For map/map_item, a bound item without a `location` ("lat,lng") field is flagged as a blocking map_location_warning (renders 0 markers). A List on a grid_item with nested children → blocking iterator_is_leaf_renderer (children never render). Operates on the default site unless site_id is provided. |
+| `yootheme_builder_inspect_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 syntax, 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). 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_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 (categories/tags) and custom-field groups (ACF/com_fields) native to WordPress/Joomla (no API Mapper). Returns {content_types, taxonomies, field_groups, capabilities}; rows carry `bindable` + `source_name`. CALL FIRST to see WHAT exists, then local_content_read for records, then element_bind_source to wire the source. Narrow with `kind`, slim with `fields[]`. E.g. {kind:"content_types"} → [{name:"post",label:"Posts",bindable:true,source_name:"wp_posts"}]. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_dynamize` | mutating | `conditions`, `element_path`, `etag`, `leaf_map`, `list_source_name`, `page`, `remove_leaves`, `section_name`, `site_id`, `source_map`, `template_id` | One-call way to dynamize a designed section: copies the layout byte-identically and swaps only what you map. Use INSTEAD of hand-editing JSON. Give a REFERENCE (section_name from template_summary, or element_path) + list_source_name + a leaf_map (original leaf field-name → flat flow field; #parent + tuned props kept). A section with several source blocks (Played/Next/Later) dynamizes in ONE call via source_map ({match, source_name, leaf_map?}[]). Sub-query panels: key by "<subquery>.<leaf>". Returns page + `summary`. Requires page.title. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_get_layout` | read+idempotent | `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` (numeric post/article id), or `url`. For dynamize/bind prefer `mode:"bindings_only"` (binding skeleton, no style props). Default `mode:"full"` returns nested `{layout, etag}`; `flat:true` gives a depth-first `{elements:[...]}` array (with `fields[]`). A repeated unchanged read auto-skips (`force:true` re-fetches). `max_chars` bounds the text; a clipped read returns `next_cursor` (pass back as `cursor`) to page the rest. 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`, `site_id`, `template_id` | Publish a template — persist state, flush YT + WP caches, snapshot the published-state ETag. ETag optional — when provided, 412 on conflict; when omitted, last-write-wins. Recommended for collaborative edits. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_save` | idempotent | `dry_run`, `etag`, `layout`, `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` — NOT the full template node page_get_layout returns (rejected 422, would blank the page). Validated + ETag-locked; on reject nothing persists. An unrenderable layout is refused PRE-WRITE (422). `dry_run:true` preflights; the success response carries `previous_layout` for 1-call rollback. Omit `layout` to re-run transforms only. ETag optional (412 on conflict; else last-write-wins). 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`, `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. 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 | `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 (not a whole-layout page_save) — 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}. ETag req. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_render_preview` | read+idempotent | `expect`, `site_id`, `template_id`, `url` | Render-check a saved template over the authenticated channel — does it actually render, with how many items, or is it blank? Address by `template_id` (from pages_list) OR `url` (resolved for you). Returns {rendered, item_count, empty, error?, cache_purge_hint}; with `expect`, also {matched, snippet}. Use AFTER a page_save / element_bind_source to catch a silently-empty live page (a bad binding "saves" then renders blank); the swallowed YOOtheme render error is surfaced in `error`. Read-only — renders without persisting. 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 atomic call and return the column JSON-Pointer path(s) to drop content into. This is the EASIEST correct way to start a new layout block: YOOtheme content must live in section → row → column, and adding content anywhere else (root, bare section, bare row) is rejected. Pass `columns` (1-12, default 1) for a multi-column row; columns are auto-distributed equal-width so they render side-by-side, or pass `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. (site_id is accepted for schema-uniformity but ignored by this tool.) |
+| `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_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). Each argument may carry `enum_values` (allowed values, e.g. ["asc","desc"]); pick from those, don't guess. CALL BEFORE binding on an archive/category template — turns a ~25-call code-dive into one. 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_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 | `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", "single-gloeckle_faq" → "single-gloeckle_help"). Returns {type, previous_type, new_etag} — previous_type is the read of the prior assignment, folded in. THEME templates only: a page:/article: layout 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. Example: yootheme_builder_template_summary({ template_id: "default" }). 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_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 -->