@wootsup/yt-builder-mcp 1.8.0 → 1.10.0

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

@@ -12,14 +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 39 typed, scoped,
-idempotent tools (41 callable end-to-end with the two gateways). 36 of them
+`@wootsup/yt-builder-mcp` server. The server catalogues 48 typed, scoped,
+idempotent tools (50 callable end-to-end with the two gateways). 41 of them
 advertised as first-class entries in `tools/list`
-(32 essential L1 forwards + 2 direct L3 entries + 2 gateways), and 5 advanced
+(37 essential L1 forwards + 2 direct L3 entries + 2 gateways), and 9 advanced
 tools reachable through the gateways. The write-capable
-`yootheme_builder_advanced` gateway routes all 5; the read-only
+`yootheme_builder_advanced` gateway routes all 9; the read-only
 `yootheme_builder_advanced_read` gateway routes only the read-only subset
-(page_get_schema, inspect_sublayout, layout_query) and is itself
+(page_get_schema, inspect_sublayout, layout_query, local_content_types,
+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.
@@ -49,12 +50,12 @@ Joomla 5/6 host plugin:
 
 ### Two picker entries (activate both)
 
-Some clients (notably Claude Desktop with the `.dxt` bundle) expose **two**
+Some clients (notably Claude Desktop with the `.mcpb` bundle) expose **two**
 entries when the user types "YT Builder MCP" into the picker:
 
 - **`YT Builder MCP for YOOtheme Pro (unofficial)`**: the MCP **server**.
-  Provides the 36 first-class tools (32 essential, 2 direct, 2 gateways).
-  The `yootheme_builder_advanced` gateway routes all 5 advanced tools; the
+  Provides the 41 first-class tools (37 essential, 2 direct, 2 gateways).
+  The `yootheme_builder_advanced` gateway routes all 9 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
@@ -81,11 +82,13 @@ The server exposes:
 - **2 direct top-level tools**, always callable, always in `tools/list`:
   `yootheme_builder_health` and `yootheme_builder_diagnose`. These are
   the "the gateway itself might be broken" escape hatch.
-- **32 essential forwarded tools**: common reads + the most-used writes
+- **37 essential forwarded tools**: common reads + the most-used writes
   (pages_list, pages_resolve, pages_create, pages_delete, page_dynamize, scaffold_section,
   get_etag, element_list / add / update_settings / get / move / clone / delete,
   page_get_layout, sources_list, source_get_schema, element_types_list, element_type_get_schema,
-  template_summary, inspect_multi_items_binding, sites_list, sites_test,
+  template_summary, inspect_multi_items_binding, library_browse, library_get, library_insert,
+  image_search, image_import,
+  sites_list, sites_test,
   use_site, the bind→verify→save→publish chain element_bind_source /
   element_get_binding / page_save / page_publish, and the archive-rebind /
   refactor surface render_preview / element_set_source / rename_source /
@@ -104,10 +107,29 @@ The server exposes:
   creates a valid
   section → row → column hull in one call — the easiest correct way to
   start a layout block (content placed anywhere else is rejected by the
-  structural-hierarchy guard).
-- **5 advanced captured tools**: everything else (page_get_schema,
+  structural-hierarchy guard). `library_browse` (Task 2, Layout Library) is L1
+  so browsing the YOOtheme Pro Library catalog — pre-designed page layouts and
+  element presets, filterable by topic/type/role/website/element_type/query —
+  is a direct call before hand-building a section from scratch. `library_get`
+  (Task 3, Layout Library) is L1 so fetching a SINGLE browsed item's full tree
+  + derived section list (`{id, name, path, element_count}` per top-level
+  section) — the natural next call once `library_browse` returns an `id` —
+  is a direct call too. `library_insert` (Task 6, Layout Library) is L1 so
+  composing + persisting a browsed/fetched item (layout, section, or preset)
+  onto a page or existing template — target `new_page` / `{template_id,
+  element_path}` / `sublayout` — through the SAME hardened write chain as
+  every element/page write, is a direct call as well. `image_search` and
+  `image_import` (Task D1, Image Sourcing) are L1 so searching Unsplash /
+  Pexels / YOOtheme Pro Images for on-topic photography, then sideloading
+  the chosen photo into the site's Media Library, are direct calls — the
+  step that turns a placeholder-filled skeleton into a finished-looking
+  page (see "Fill image slots with real on-topic photos" under Layout
+  Library).
+- **9 advanced captured tools**: everything else (page_get_schema,
   element_unbind_source, clean_implode_directives,
-  `inspect_sublayout`, and `layout_query`).
+  `inspect_sublayout`, `layout_query`, `library_save_as`, the two Local
+  Content Read tools `local_content_types` / `local_content_read`, and
+  `pages_audit`).
   Reachable through one gateway tool:
   `yootheme_builder_advanced({ tool: "<name>", arguments: { ... } })`. For
   example, to inspect a panel/grid_item `< SUBLAYOUT`:
@@ -116,18 +138,35 @@ The server exposes:
   AND-combined `type`/`name_matches`/`has_binding`/`max_depth`/`under_section`):
   `yootheme_builder_advanced({ tool: "yootheme_builder_layout_query", arguments: { template_id, type: "headline", has_binding: false, under_section: "Hero" } })`
   (it's read-only, so the read gateway `yootheme_builder_advanced_read({ tool: "yootheme_builder_layout_query", … })` works too).
+  And to save a page/subtree INTO "My Layouts" (Task 7 — the reverse of
+  `library_insert`; omit `element_path` to save the whole page):
+  `yootheme_builder_advanced({ tool: "yootheme_builder_library_save_as", arguments: { source: { template_id, element_path }, name: "Hero Section" } })`.
+  It flags `invalid_source_possible: true` when the saved subtree carries
+  bound dynamic sources that may not exist wherever it is later reloaded —
+  re-bind after inserting it elsewhere.
+  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:
   - To render-check a saved page over the authenticated channel (F5+N5 — does
     it render, with how many items, or is it silently blank? where an external
     cURL 401s behind staging Basic-Auth), call the now-L1
-    `yootheme_builder_render_preview({ template_id })` directly. It takes no
-    post/term target: it renders YOOtheme's implicit fallback context, so a
-    source-bound template comes back non-empty. Treat a non-empty render as the
-    success signal, not "blank despite a binding". Pass `expect: "<substring>"`
-    to confirm a specific edit reached the HTML in one call (the response adds
-    `matched` + `snippet`).
+    `yootheme_builder_render_preview({ template_id })` directly — or address it by
+    a public URL with `yootheme_builder_render_preview({ url })` (the URL is
+    resolved to its template for you, exactly like `page_get_layout`), so if you
+    only hold a resolved category/archive URL you can render-check it in ONE call
+    without first converting it to a template_id. It takes no post/term target: it
+    renders YOOtheme's implicit fallback context, so a source-bound template comes
+    back non-empty. Treat a non-empty render as the success signal, not "blank
+    despite a binding". `item_count` counts the TOP-LEVEL repeat-source rows only
+    (a static grid/list nested in a repeated card no longer inflates it). Pass
+    `expect: "<substring>"` to confirm a specific edit reached the HTML in one call
+    (the response adds `matched` + `snippet`).
   - To surgically SET a precomposed `source` + the native item-level
     `source_extended.props` carrier on one element at a pointer, ETag-locked,
     leaving the rest of the layout byte-unchanged (F2 — the one-call source edit
@@ -152,13 +191,21 @@ 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 — and is read-only-annotated
-  so hosts auto-allow it). Prefer the read gateway for pure inspection:
+  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 } })`.
-
-`tools/list` therefore advertises 36 names (32 + 2 + 2). That's 32 L1
-essentials + 2 L3 direct + 2 gateways. The total callable surface is 41
-(36 advertised + 5 advanced reachable through the gateways). If the AI
+  Discover the site's NATIVE content the same way — the landscape then the records:
+  `yootheme_builder_advanced_read({ tool: "yootheme_builder_local_content_types" })`
+  then `yootheme_builder_advanced_read({ tool: "yootheme_builder_local_content_read", arguments: { kind: "terms", taxonomy: "category" } })`.
+  (The write gateway routes them too, if you prefer one entry:
+  `yootheme_builder_advanced({ tool: "yootheme_builder_local_content_types" })` and
+  `yootheme_builder_advanced({ tool: "yootheme_builder_local_content_read", arguments: { kind: "entities", type: "post" } })`.)
+
+`tools/list` therefore advertises 41 names (37 + 2 + 2). That's 37 L1
+essentials + 2 L3 direct + 2 gateways. The total callable surface is 50
+(41 advertised + 9 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
@@ -183,6 +230,50 @@ guess where the agent is pointing:
 Treat `frontend_url: null` as "host plugin could not resolve a public URL for
 this template". Surface that honestly rather than fabricating one.
 
+## Resolve a URL back to the template that renders it
+
+The two sections above go template → URL (forward). To go the OTHER way — the
+user pastes a public URL and asks *"which layout renders this?"* — you have two
+complementary tools.
+
+**`yootheme_builder_pages_resolve({ url })` — the direct reverse lookup.** Paste
+any public frontend URL and it returns
+`{ template_id, post_id, type, frontend_url, context, resolved_via }` (or a
+`url_not_resolvable` when it genuinely maps to no template — it degrades to an
+honest null rather than guessing a wrong one). It handles **SEF / pretty
+permalinks on BOTH WordPress and Joomla** (not just raw `?option=…&id=…` query
+URLs), including deep sub-category paths like `/matches/first-men-s-team`. For a
+**category or term URL it returns the SPECIFICALLY-ASSIGNED template** — the one
+whose YOOtheme `query.catid` (Joomla) / `query.terms` (WordPress) binds THAT
+category/term, honoring **include-child-categories** (a template assigned to a
+parent category with child-inclusion covers its subcategories; the nearest
+specific assignment wins). Only when nothing is specifically assigned does it
+fall back to the governing generic theme template. Then feed the returned
+`template_id` straight into `page_get_layout` / `element_list` / the write tools.
+
+**`serves_context_kind` + `serves_context_ids` on `pages_list` rows — resolve it
+yourself, zero extra calls.** Every `pages_list` row also carries these two Layer-C
+fields so you can map a URL to its template WITHOUT a `pages_resolve` round-trip:
+
+- **`serves_context_kind`** is the normalized, cross-platform context the template
+  serves — one of `single-post`, `single-page`, `category`, `tag`, `author`,
+  `search`, `post-archive`, `error-404`, `internal`, `unknown`. A WordPress row and
+  a Joomla row that serve the same logical context report the SAME kind (WP
+  `taxonomy-category` and Joomla `com_content.category` both → `category`).
+- **`serves_context_ids`** is the SPECIFIC category/term ids that a category
+  template is assigned to (Joomla `query.catid`, WordPress `query.terms`). It is
+  **empty** for a generic archive or a generic category template that binds no
+  specific ids — that emptiness is honest, not a bug.
+
+Matching workflow: derive the URL's context (a `/category/<id-or-slug>` →
+`category` + its id; an article/post → `single-post`; etc.), then pick the
+`pages_list` row whose `serves_context_kind` matches and whose
+`serves_context_ids` contains that id — e.g. URL `/matches` (category 11) matches
+the row `{ label: "Match Index", serves_context_kind: "category",
+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.
+
 ## Scopes (Bearer key permissions)
 
 Every Bearer key has a scope, set at key creation time:
@@ -226,7 +317,7 @@ sites (WordPress and Joomla mixed). Without multi-site support you would need
 one MCP install per site, one set of env vars per site, and one AI-client
 restart per site you want to talk to. With multi-site:
 
-- One DXT install in Claude Desktop, one entry in your AI client config.
+- One MCPB install in Claude Desktop, one entry in your AI client config.
 - One conversation can edit elements on `acme.com` and `beta.io` back-to-back.
 - Each site keeps its own Bearer key, platform, label, and 1Password reference.
 - Adding a new client site does not require a new MCP install.
@@ -351,7 +442,7 @@ one conversation.
 2. For each site, the agent runs the same sequence with `site_id` set:
    - `yootheme_builder_pages_list({ site_id: "wp-acme", fields: ["id", "label"] })`
    - `yootheme_builder_get_etag({ site_id: "wp-acme" })`
-   - `yootheme_builder_element_update_settings({ site_id: "wp-acme", template_id: "home", element_path: "/0/children/0/children/0/children/0", props: { content: "New headline" }, merge: true, etag: "<etag>" })`
+   - `yootheme_builder_element_update_settings({ site_id: "wp-acme", template_id: "home", element_path: "/children/0/children/0/children/0/children/0", props: { content: "New headline" }, merge: true, etag: "<etag>" })`
    - `yootheme_builder_page_save({ site_id: "wp-acme", template_id: "home", etag: "<fresh>" })`
    - `yootheme_builder_page_publish({ site_id: "wp-acme", template_id: "home", etag: "<fresh>" })`
 3. The customer sees a stream of replies, each prefixed with the matching
@@ -364,6 +455,33 @@ for a focused diagnosis without touching the others.
 
 ---
 
+## Pages vs theme templates (know what you are editing)
+
+`pages_list` returns TWO different kinds of editable layout, and every tool
+takes a `template_id` that addresses either. Know which one you have before
+you write — they have very different blast radius.
+
+| Kind | `id` shape | `type` value(s) | What it is |
+|------|-----------|-----------------|------------|
+| **Page** | `page:<n>` (WP) / `article:<n>` (Joomla) | `page` | ONE individual page/article. Editing it changes only that page. Stored in the post/article content. |
+| **Theme template** | a bare id (e.g. `I99YS8Ii`) | `single-post`, `archive-post`, `taxonomy-category`, `taxonomy-post_tag`, `author-archive`, `search`, `error-404`, … | A REUSABLE theme-level layout that applies to EVERY matching item. Stored in the theme options. |
+
+**The safety rule: editing a theme template changes the layout for ALL
+matching content, not one page.** If the user says "restyle the blog post
+template", `pages_list` shows it as e.g. `{ id: "I99YS8Ii", label: "Post",
+type: "single-post" }` — editing that `template_id` restyles EVERY blog post
+on the site at once. That is often exactly what's wanted (that's what theme
+templates are for), but confirm the intent — do not edit a `single-post` /
+`taxonomy-*` / `archive-*` template when the user meant one specific page.
+`template_summary` also returns `is_theme_template` to disambiguate cheaply.
+
+- To edit ONE page, target a `page:<n>` / `article:<n>` id.
+- To edit a reusable template (the design of all posts, all category
+  archives, the 404, …), target the bare id and understand the reach.
+- `pages_create` creates a **page/article** (an individual layout). Theme
+  templates are defined in the theme itself and are not created via this MCP;
+  you edit the existing ones `pages_list` reports.
+
 ## Workflow 1: Build a hero section
 
 **Goal:** Add a fresh hero section (heading + sub-heading + CTA button)
@@ -379,24 +497,48 @@ to an existing page.
    named a specific page, match on `label` (exact then fuzzy).
 3. `yootheme_builder_get_etag()`: fetch the current top-level
    optimistic-lock ETag. Every write tool requires it via `etag`.
-4. `yootheme_builder_element_add({ template_id: "<id>", parent_path: "", element_type: "section", props: { background: "primary" }, etag: "<etag>" })`:
-   append a new section at the template root (`parent_path: ""`).
-   Returns `{ path: "/0/children/N", etag: "<fresh>" }`.
+4. `yootheme_builder_element_add({ template_id: "<id>", parent_path: "", element_type: "section", props: { style: "primary" }, etag: "<etag>" })`:
+   append a new section at the template root (`parent_path: ""`). The
+   section background is set with `style` (enum: `default` / `muted` /
+   `primary` / `secondary`) — there is NO `background` key (it hard-rejects
+   as an unknown prop). Always call `element_type_get_schema("section")`
+   first to confirm the real prop keys.
+   Returns `{ rel_path: "/children/0/children/N", etag: "<fresh>" }`.
 5. `yootheme_builder_element_add({ template_id, parent_path: "<section-path>", element_type: "row", etag: "<fresh-etag>" })`:
    add a row inside the section. Use the etag returned by the
    previous write (etags rotate every mutation).
-6. `yootheme_builder_element_add({ template_id, parent_path: "<row-path>", element_type: "headline", props: { content: "<h1 text>" }, etag })`:
-   add a headline.
+6. `yootheme_builder_element_add({ template_id, parent_path: "<row-path>", element_type: "headline", props: { content: "<h1 text>", title_style: "h1" }, etag })`:
+   add a headline. `title_style: "h1"` uses the semantic type scale (the
+   tasteful default). See "Typography & heading styles" below before
+   reaching for a `heading-*` display size.
 7. `yootheme_builder_element_add({ template_id, parent_path: "<row-path>", element_type: "text", props: { content: "<sub text>" }, etag })`:
    add a text element.
-8. `yootheme_builder_element_add({ template_id, parent_path: "<row-path>", element_type: "button", props: { content: "<cta>", link: "<url>" }, etag })`:
-   add the CTA button.
+8. `yootheme_builder_element_add({ template_id, parent_path: "<row-path>", element_type: "button", etag })`
+   then add a `button_item` CHILD for the actual label/link/style:
+   `yootheme_builder_element_add({ template_id, parent_path: "<button-path>", element_type: "button_item", props: { content: "<cta>", link: "<url>", button_style: "primary" }, etag })`.
+   The `button` element is a CONTAINER — its label, link and style live on
+   a `button_item` child, NOT on the button's own props. Adding a lone
+   `button` with `{content, link}` renders an empty button. (Same
+   container→item pattern as `grid`→`grid_item`, `list`→`list_item`.)
 9. `yootheme_builder_page_save({ template_id, etag })`:
    persist the working copy (visible in YOOtheme Customizer preview).
    `page_save` is a first-class L1 tool; call it directly.
 10. `yootheme_builder_page_publish({ template_id, etag })`:
     make the changes live on the front-end. Also a first-class L1 tool.
 
+> **Building a whole page? Prefer ONE atomic `page_save` over ~30 incremental
+> writes.** The step-by-step `element_add` sequence above is clearest for
+> learning and for small edits, but each write is ETag-locked, so building a
+> full multi-section page as 20-30 sequential writes invites `412` conflicts
+> (especially when other agents edit the same site — the builder ETag is a
+> single shared option). For a full page, assemble the complete
+> `{type:"layout",children:[...]}` tree in memory and persist it in ONE call:
+> `yootheme_builder_page_save({ template_id, layout: <full-tree> })` (ETag
+> optional → last-write-wins, scoped to this page). `dry_run:true` preflights
+> it first. A fast, robust pattern: `scaffold_section` one block, read it
+> back to learn the exact node shape, then build the rest of the tree from
+> that shape and `page_save` it whole.
+
 **Common pitfalls:**
 
 - **Wrong parameter names.** Every tool uses snake_case. Use
@@ -430,10 +572,10 @@ yootheme_builder_element_add({
   template_id: "home",
   parent_path: "",
   element_type: "section",
-  props: { background: "primary" },
+  props: { style: "primary" },   // section background = `style`, NOT `background`
   etag: "abc123"   // from yootheme_builder_get_etag
 })
-// Response: { path: "/0/children/3", etag: "def456" }
+// Response: { rel_path: "/children/0/children/3", etag: "def456" }
 // → next call uses etag "def456"
 
 // Step 9. page_save is a first-class L1 tool; call it directly.
@@ -453,6 +595,206 @@ section as the last child of the template root.
 
 ---
 
+## Multi-column layouts (columns that sit side-by-side)
+
+**The single most common layout mistake: a `row` with several `column`
+children that reads as gaps / a broken column in the builder — or renders
+STACKED (full-width, one under the other) on the front-end — instead of a
+clean set of side-by-side columns.** This is a silent, layout-only defect:
+the write succeeds (valid values), so you only catch it by looking at the
+builder's left panel or the rendered page, never from a successful save.
+
+**How a real YOOtheme layout defines columns — set BOTH, exactly like every
+shipped demo layout does:**
+
+1. **`row.props.layout` — the grid string. This is the primary, load-bearing
+   piece.** It is the value the builder's *"Select a grid layout"* picker
+   writes: a comma-separated width per column, e.g. `"1-2,1-2"` (Halves),
+   `"1-3,1-3,1-3"` (Thirds), `"2-3,1-3"` (Thirds 2-1), `"1-4,1-4,1-4,1-4"`
+   (Quarters), `"3-5,2-5"` (a 3/5 + 2/5 hero split). The builder reads
+   `row.layout` to know a row HAS N columns. **A multi-column row with no
+   `row.layout` is read by the builder's Layout picker as "Whole" (one
+   full-width column) and painted collapsed with a big empty gap where the
+   other columns belong** — the "lauter Lücken im Layout" a customer sees in
+   the builder. `layout` is a `row` prop (NOT a column prop).
+
+2. **Per-column responsive `width_*` — the breakpoint refinement.** On each
+   `column`, set `width_default: "1-1"` (stack on phone) and
+   `width_medium: "<token>"` (go side-by-side from ≥960px). This is the
+   factory responsive default: readable single-column on a phone, multi-column
+   on tablet/desktop. The full breakpoint set (each maps to
+   `uk-width-{value}@breakpoint`):
+
+   | Prop | Breakpoint |
+   |------|------------|
+   | `width_default` | all sizes (phone-up) |
+   | `width_small` | ≥ 640px |
+   | `width_medium` | ≥ 960px |
+   | `width_large` | ≥ 1200px |
+   | `width_xlarge` | ≥ 1600px |
+
+**Valid width tokens** (the same values used in the grid string; discover
+them on the `column` schema via `element_type_get_schema` — they carry an
+`enum`, so an invalid token is hard-rejected with a `422 invalid_enum_value`):
+`1-1 1-2 1-3 1-4 1-5 1-6 2-3 2-5 3-4 3-5 4-5 5-6` and
+`auto expand small medium large xlarge`. Match the row's grid string to the
+columns' `width_medium` tokens (grid `"2-3,1-3"` ↔ column 1 `width_medium:
+"2-3"`, column 2 `width_medium: "1-3"`).
+
+**Single-column rows are different: NO `row.layout`, NO column width.** A
+factory intro / testimonial / CTA is a full-width column (leave the column
+width-less) inside a row with no grid string, and the content is centred by
+setting `text_align: "center"` on the child `headline` / `text` elements —
+never by narrowing the column. Narrowing a single column WITHOUT a matching
+`row.layout` is exactly what leaves a gap in the builder.
+
+**Easiest correct way — `scaffold_section` builds the whole factory-shaped
+hull for you (row grid string + per-column responsive widths in one call):**
+
+- `scaffold_section({ template_id, columns: 3, etag })` → a section whose row
+  carries `layout: "1-3,1-3,1-3"` and whose 3 columns each carry
+  `width_default: "1-1"` + `width_medium: "1-3"` → clean, gap-free, side-by-side
+  from ≥960px. `columns: N` distributes equal widths (`1-N` for N ≤ 6,
+  `expand` for N > 6).
+- For an ASYMMETRIC row pass explicit tokens, one per column:
+  `scaffold_section({ template_id, columns: 2, column_widths: ["2-3", "1-3"], etag })`
+  → a row with `layout: "2-3,1-3"` and the matching column widths. A
+  wrong-length array or a bad token returns a friendly `400` before the write.
+- `scaffold_section({ template_id, columns: 1, etag })` → a single full-width
+  column with no `row.layout` and no column width (the factory single-column
+  shape).
+
+`scaffold_section` returns the column JSON-Pointer paths — drop your content
+into them with `element_add({ parent_path: "<column-path>", ... })`. If you
+build columns by hand with `element_add` instead, remember to set BOTH
+`row.props.layout` (the grid string) AND each column's `width_default` /
+`width_medium`, or the row reads as "Whole" and shows gaps in the builder.
+
+**Success criterion:** in the builder's left panel the row shows N distinct
+columns (not one column + an empty gap), and after publish the columns sit
+side-by-side at desktop width. Measure with `getBoundingClientRect` (columns
+share the same `top`, differ in `left`) — a fullPage screenshot hides both
+the gap and the stacking.
+
+---
+
+## Typography & heading styles (restraint is the professional signal)
+
+The `title_style` prop (on `headline`, and `title_style`/`content_style`/
+`meta_style` on `grid`) mixes TWO different scales that look alike but mean
+opposite things. Choosing the wrong one is the most common reason an
+AI-built page looks amateurish — a wall of oversized text with no hierarchy.
+
+- **`h1`–`h6` = the SEMANTIC type scale.** They follow the theme's designed
+  type ramp — tasteful, theme-consistent, restrained. **This is the default
+  a real YOOtheme designer uses.** A hero headline is typically `h1`; a
+  section title is `h2`; a card/feature title is `h3`. Reach for these
+  FIRST.
+- **`heading-small` … `heading-3xlarge` = DISPLAY / billboard type**
+  (≈2.6rem up to ~8rem; on the front-end `heading-2xlarge` can render
+  ~150–180px). They are decoupled from semantics — pure visual impact.
+  `heading-2xlarge` / `heading-3xlarge` are for a SINGLE deliberate hero
+  statement, used ONCE per page, if at all.
+- **`text-lead` / `text-large` / `text-meta` / `text-small`** are body-text
+  emphasis styles, not headings (e.g. an eyebrow label = `text-meta`, a lead
+  paragraph = `text-lead`).
+
+**The principle: hierarchy comes from CONTRAST, not from making everything
+large.** If every section title is `heading-2xlarge`, nothing stands out and
+the page reads as a shouting match. Display sizes are a spice, not a staple:
+give ONE hero moment the big display size and let everything else step down
+to the semantic scale (`h2`/`h3`). Concretely, for a typical landing page:
+
+| Element | Good default |
+|---------|-------------|
+| Eyebrow / overline label | `text-meta` |
+| Hero headline | `h1` (or at most `heading-medium`/`heading-large` for extra punch) |
+| Section title | `h2` |
+| Card / feature / metric title | `h3` (a big metric number can take `heading-medium`, not `2xlarge`) |
+| Lead paragraph | `text-lead` |
+
+Do NOT repeat a `heading-*` display size across multiple sections. When in
+doubt, use the semantic level (`h2`/`h3`) — it is always the safer,
+more professional choice.
+
+### `title_style` (visual size) vs `title_element` (HTML tag / SEO)
+
+These are **two independent axes** on a `headline`, and confusing them
+produces SEO-fatal pages:
+
+- **`title_style`** = how big the title *looks* (the section above).
+- **`title_element`** = the actual HTML tag it renders as: `h1`–`h6`, or
+  `div` for non-heading display text. This is the **semantic / SEO** axis. A
+  `div` styled `heading-2xlarge` looks huge but is *not* a heading; an `h2`
+  styled `text-small` is still a level-2 heading.
+
+**`title_element` DEFAULTS to `h1` when unset** — so if you leave it blank on
+every headline, every headline becomes an `<h1>`, which is SEO-fatal (a page
+must have **exactly one** `<h1>`). Set it explicitly on every headline:
+
+| Headline role | `title_element` |
+|---------------|-----------------|
+| Hero headline (once per page) | `h1` |
+| Section title | `h2` |
+| Card / feature title | `h3` |
+| Metric number / stat / other non-heading display text | `div` |
+
+`title_style` and `title_element` are set **independently** — e.g. a hero is
+`title_element: "h1"` with `title_style: "h1"` (or a `heading-*` display size
+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
+in a `<p>` produces invalid `<hN><p>…</p>`. The server **hard-rejects** a
+headline whose `content` is a sole `<p>…</p>` block (422
+`headline_content_block_p`). Store **bare inline text**, exactly like a
+factory headline:
+
+- ✅ `content: "Ready to get started?"`
+- ✅ inline emphasis is fine: `content: "Save <strong>40%</strong> today"`
+- ❌ `content: "<p>98%</p>"` — a `<p>` block belongs to the **`text`**
+  element, not a headline.
+
+For paragraph / body copy (which *should* be a `<p>`), use the `text`
+element, not a headline.
+
+---
+
+## Troubleshooting: builder panel is empty / "The builder is not available on this page"
+
+If the YOOtheme Customizer's left Builder panel is empty or shows *"The
+builder is not available on this page. It can only be used on pages, posts
+and categories"* on a page you KNOW has a layout, the usual cause is a
+**stale Customizer session**, NOT a broken layout. YOOtheme's Customizer
+preview cookie is derived from the WordPress login-session token; when that
+token rotates (re-login, session timeout, a different tab), the preview
+renders as a plain page without the builder-data injection and the panel
+reports "not available". **Fix: reload the Customizer tab** (or re-open the
+builder from Pages → the page → Builder). The stored layout is intact —
+confirm with `page_get_layout({ template_id })`, which reads it directly
+and is unaffected by the browser session.
+
+---
+
+## Layout versioning (handled automatically — informational)
+
+Every layout this server writes is stamped with the installed YOOtheme
+version at the layout root, exactly like the builder UI does. You do not
+need to set this. It prevents YOOtheme from treating a written layout as
+pre-versioning legacy content and running its migration chain (which would
+re-map current-schema values and bloat the tree) on every load. An existing
+version on a layout you read-modify-write is preserved, never overwritten.
+
+---
+
 ## Workflow 2: Bind a dynamic source to a grid
 
 **Goal:** Wire an existing Grid (or other multi-item element) to a
@@ -465,7 +807,7 @@ renders dynamic items.
 2. `yootheme_builder_pages_list({ fields: ["id", "label"] })` and
    `yootheme_builder_page_get_layout({ template_id: "<id>", flat: false })`:
    locate the target Grid. Note its JSON-Pointer `path` (e.g.
-   `/0/children/2/children/0`).
+   `/children/0/children/2/children/0`).
 3. `yootheme_builder_element_get({ template_id, element_path })`:
    fetch the Grid's current props so you can preserve them. Binding
    sets `props.source` and leaves the rest alone.
@@ -528,15 +870,15 @@ renders dynamic items.
 // is a first-class L1 tool — call it directly.
 yootheme_builder_element_bind_source({
   template_id: "home",
-  element_path: "/0/children/2/children/0",
+  element_path: "/children/0/children/2/children/0",
   source_name: "wp_posts",
   etag: "abc123"
   // source_id: "wordpress:wp_posts"   // pass ONLY when name collides
 })
-// Response: { path: "/0/children/2/children/0", etag: "def456", has_binding: true }
+// Response: { rel_path: "/children/0/children/2/children/0", etag: "def456", has_binding: true }
 // Verify (direct L1 call):
 yootheme_builder_element_get_binding({
-  template_id: "home", element_path: "/0/children/2/children/0"
+  template_id: "home", element_path: "/children/0/children/2/children/0"
 })
 // → { source_name: "wp_posts", source_config: { ... }, ... }
 ```
@@ -666,20 +1008,20 @@ CMS-level template duplication (in wp-admin or Joomla administrator).
 // Step 5. Clone the section element as a sibling.
 yootheme_builder_element_clone({
   template_id: "home",
-  element_path: "/0/children/2",   // the hero section to duplicate
+  element_path: "/children/0/children/2",   // the hero section to duplicate
   etag: "abc123"
 })
-// Response: { path: "/0/children/3", etag: "def456" }
+// Response: { rel_path: "/children/0/children/3", etag: "def456" }
 
 // Step 7. Tweak the clone (replace props entirely, or pass merge: true).
 const current = yootheme_builder_element_get({
   template_id: "home",
-  element_path: "/0/children/3",
+  element_path: "/children/0/children/3",
 });
 yootheme_builder_element_update_settings({
   template_id: "home",
-  element_path: "/0/children/3",
-  props: { ...current.props, background: "secondary" },
+  element_path: "/children/0/children/3",
+  props: { ...current.props, style: "secondary" },   // section background = `style`
   etag: "def456"
 })
 ```
@@ -882,15 +1224,19 @@ yootheme_builder_element_types_list({
 yootheme_builder_element_type_get_schema({ element_type: "headline" })
 // Returns the field definitions for the headline's `props`.
 
-// Step 6. Place the element.
+// Step 6. Place the element. This is the HERO headline, so title_element:"h1"
+// — the ONE h1 the page is allowed. A section title would be "h2", a card
+// title "h3", a metric number "div". `content` is bare inline text (never a
+// <p> block — see "Typography & heading styles"). If you omit title_element it
+// DEFAULTS to h1, so set it explicitly on every headline to avoid multiple h1s.
 yootheme_builder_element_add({
   template_id: "home",
-  parent_path: "/0/children/2",     // row inside section
+  parent_path: "/children/0/children/2",     // row inside section
   element_type: "headline",
-  props: { content: "Welcome", tag: "h1" },
+  props: { content: "Welcome", title_element: "h1" },
   etag: "abc123"
 })
-// Response: { path: "/0/children/2/children/0", etag: "def456" }
+// Response: { rel_path: "/children/0/children/2/children/0", etag: "def456" }
 ```
 
 **Edge case:** A child theme can override a built-in element's
@@ -906,7 +1252,161 @@ 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`.
+
+**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.
+
+**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,
@@ -951,6 +1451,11 @@ and the props payload you passed.
   `yootheme_builder_advanced({ tool: "yootheme_builder_clean_implode_directives", arguments: { template_id, element_path, etag } })`.
   Returns the audit log + a fresh ETag; idempotent (`cleaned_count: 0` when
   there is nothing to remove).
+- **Start from a pre-designed layout or element preset instead of
+  hand-building** (the user wants a "Home"/"Contact"/"Services" page, or a
+  ready-made Accordion/Alert preset, not a section built element-by-element):
+  see "Layout Library" below (`library_browse` → `library_get` →
+  `library_insert` → adapt).
 
 If the user asks for something none of the above covers (e.g. global
 theme settings, menu management, media library), tell them clearly:
@@ -964,24 +1469,32 @@ Every element is addressed by a JSON-Pointer `path` (RFC-6901-style).
 The read tools hand you the path; the write tools consume it. Learn the
 grammar once and you never guess an address again.
 
-**The shape.** The canonical address is index-first: the first segment is a
-bare child index, then `/children/<index>` for each level down. A two-level
-path is `/0/children/1` (child 0 of the layout root, then child 1 of that); a
-three-level path is `/0/children/2/children/0`. Every Worked example in this
-skill and every write-tool response uses this index-first form.
+**The canonical shape (use this): rel_path.** A `rel_path` is a proper
+RFC-6901 pointer relative to the layout root: `/children/<index>` for each
+level down. A two-level path is `/children/0/children/1` (child 0 of the
+layout root, then child 1 of that); a three-level path is
+`/children/0/children/2/children/0`. Each `/children/N` descends one level
+into the Nth child (0-based). This is the form `element_list` emits as
+`rel_path`, and the form every worked example in this skill uses.
 
-- **Relative (rel_path):** `/0/children/2/children/0` is the path FROM the
-  layout root. Each `/children/N` descends one level into the Nth child
-  (0-based).
 - **Fully-qualified:** `/templates/<template_id>/layout/children/0/...` is the
-  same address with the template prefix.
-
-**Both forms are accepted.** `element_list` / `page_get_schema` emit `path`
-fully-qualified and `rel_path` with a leading `/children/0/...` (a `/children`
-prefix on the first segment too); write-tool responses use the index-first
-`/0/children/...` form. You may pass EITHER back as `element_path` /
-`parent_path`: the server normalizes them (the `normalizeElementPath` rule),
-and a leading slash is optional (`0/children/1` works too).
+  same address with the template prefix. Read/write tools return the
+  fully-qualified pointer as `path`; you can pass it straight back.
+
+**What the tools EMIT:** `element_list` / `page_get_schema` return both `path`
+(fully-qualified) and `rel_path` (the canonical `/children/0/...` form); every
+write-tool response (`element_add`, `element_update_settings`, `element_clone`,
+`element_move`, `element_bind_source`, `page_dynamize`, `scaffold_section`) and
+`element_get` return the fully-qualified `path` plus the canonical `rel_path`.
+Copy either straight back into the next call.
+
+**What the server ACCEPTS (be liberal):** as `element_path` / `parent_path`
+you may pass the canonical `rel_path` (`/children/0/...`), the fully-qualified
+pointer (`/templates/<id>/layout/...`), OR the terse index-first form
+(`/0/children/1`, where a leading bare index is the Nth layout-root child) —
+all three normalize to the same node, and a leading slash is optional. Prefer
+`rel_path`: it is the canonical, standards-correct form and what the tools
+hand you.
 
 **The two special roots:**
 
@@ -991,7 +1504,7 @@ and a leading slash is optional (`0/children/1` works too).
   layout node itself, which is not an addressable element. Use `""` for
   "the top".
 
-**Reading the index.** In `/0/children/2/children/1`: child 0 of the layout,
+**Reading the index.** In `/children/0/children/2/children/1`: child 0 of the layout,
 then child 2 of THAT, then child 1 of THAT. Indices are positional and shift
 when siblings are added or removed; re-read after a structural mutation before
 reusing a path (see the ETag handshake below).
@@ -1100,11 +1613,578 @@ styles, the `#parent` bindings) survives untouched.
 - **Reusing a stale etag.** Feed `new_etag` from the response into your
   next write.
 
+---
+
+## Layout Library (browse → get → insert → adapt)
+
+**Goal:** Start a page or section from a pre-designed YOOtheme Pro Library
+layout or single-element preset instead of hand-building it with
+`element_add` calls — then adapt the demo content to the customer's brand.
+
+Four tools, always used in this order (the write-capable third step is
+the only one that mutates anything):
+
+1. `yootheme_builder_library_browse` (read) — search the catalog by
+   taxonomy filters, get back rows with an `id`.
+2. `yootheme_builder_library_get` (read) — fetch ONE item's full tree +
+   its section list, using the `id` a browse row gave you.
+3. `yootheme_builder_library_insert` (write) — compose + persist that
+   item onto a page or existing template through the same hardened
+   write chain every other element/page write goes through.
+4. `yootheme_builder_library_save_as` — the REVERSE direction (a page you
+   built → a reusable library). By default it saves into your OWN local
+   "WootsUp AI Layouts" store (`destination: "ai"`, no apikey — see the
+   dedicated subsection below), NOT YOOtheme's native My Layouts. Reachable
+   ONLY via the gateway:
+   `yootheme_builder_advanced({ tool: "yootheme_builder_library_save_as", arguments: { source: { template_id, element_path }, name: "Hero Section" } })`.
+   It is deliberately NOT a first-class `tools/list` entry (keeps the
+   tools/list token-budget clear); browse/get/insert ARE first-class.
+
+Two `source`s feed browse/get/insert: `"catalog"` (default — YOOtheme's
+remote Pro Library) and `"ai"` (your OWN local "WootsUp AI Layouts", no
+apikey). See "WootsUp AI Layouts" below.
+
+### Prerequisite: the REMOTE catalog needs a Library API key configured
+
+Browse, get, AND insert against the remote catalog (`source: "catalog"`,
+the default) all depend on a YOOtheme Pro Library API key configured on the
+connected site (the customer's own theme `apikey`, set once in the YOOtheme
+Customizer — not something this MCP server manages). If it's missing,
+`library_browse` does not error — it returns `{ items: [], total: 0 }`.
+Treat `total: 0` as "ask the customer to check the theme apikey field in the
+Customizer", not a network/auth failure to retry blindly. **This apikey
+requirement applies ONLY to the remote catalog** — the local AI-Layouts
+store (next subsection) needs no apikey at all.
+
+### WootsUp AI Layouts — your OWN local library (no apikey, save → reuse)
+
+The catalog above (`source: "catalog"`, the default) is YOOtheme's REMOTE
+Pro Library and needs the theme apikey. There is a SECOND source that is
+entirely LOCAL to the connected site: **"WootsUp AI Layouts"**, the plugin's
+own isolated store. It works WITHOUT any apikey and it NEVER touches
+YOOtheme's native "My Layouts". This is the loop that lets an agent build a
+section once and reuse it across pages — even on a site that has no Library
+apikey at all.
+
+- **`source` axis on `library_browse` / `library_get` / `library_insert`:**
+  `source: "catalog"` (default) is the remote Pro Library (needs the apikey);
+  `source: "ai"` is your OWN "WootsUp AI Layouts", served from the local
+  store with no apikey. The `id` you pass to `library_get` /
+  `library_insert` MUST come from a `library_browse` with the SAME `source`.
+  The `"ai"` source honours only `query` (name substring) + `kind`
+  (`layout` | `element`); the catalog layout/element taxonomy filters
+  (`topic`/`type`/`role`/`website`) and `kind: "section"` are REJECTED with
+  a 400 (an honest error, not a silent no-op) — the local store has no
+  taxonomy, only what you saved. (`purpose`/`has_effects` are section-only
+  filters that don't apply to a `layout`/`element` browse at all, so —
+  exactly as on the catalog path — they are silently ignored on
+  `source: "ai"`, never reaching the store; they are NOT rejected.)
+- **`destination` axis on `library_save_as`:** `destination: "ai"` (DEFAULT —
+  save into the isolated "WootsUp AI Layouts" store, reusable via
+  `library_browse` / `library_insert` with `source: "ai"`, and it NEVER
+  pollutes YOOtheme's native My Layouts) or `destination: "native"` (the
+  escape hatch — save into YOOtheme's built-in "My Layouts"). Because `"ai"`
+  is the default, a plain `library_save_as` already writes to YOUR store,
+  not the theme's.
+- **Composed AS-SAVED.** A `source: "ai"` insert replays the tree exactly as
+  you saved it — its images are NOT re-resolved (they are already the
+  customer's own images / placeholders), so `library_insert`'s `images`
+  param is a no-op for `source: "ai"`.
+
+**Round-trip (save your own layout, then reuse it — no apikey):**
+
+```jsonc
+// 1. Save a section you built (or adapted from the catalog) into YOUR store.
+//    destination:"ai" is the default, shown here for clarity. save_as is
+//    gateway-only.
+yootheme_builder_advanced({ tool: "yootheme_builder_library_save_as", arguments: {
+  source: { template_id: "home", element_path: "/children/2" },
+  name: "Candle Hero",
+  destination: "ai"
+} })
+// → { library_id: "a1b2c3d4", name: "Candle Hero", storage: "ai_library.a1b2c3d4", invalid_source_possible: false }
+
+// 2. Later, on ANY page (even one with no Library apikey) browse YOUR store …
+yootheme_builder_library_browse({ source: "ai", query: "hero" })
+// → { items: [{ id: "a1b2c3d4", name: "Candle Hero", kind: "layout" }], total: 1 }
+
+// 3. … and insert it — same hardened write chain as a catalog insert.
+yootheme_builder_library_insert({
+  id: "a1b2c3d4",
+  source: "ai",
+  target: { template_id: "about", element_path: "" },
+  etag: "<etag>"
+})
+```
+
+**When to use which store:** reach for `source: "catalog"` to START from
+YOOtheme's professionally-designed demos (needs the apikey); reach for
+`source: "ai"` to REUSE a layout you already saved on this site — your own
+reusable building blocks, apikey or not.
+
+### The taxonomy filters on `library_browse`
+
+`kind` picks which catalog you're browsing: `"layout"` (full pre-designed
+pages, the default), `"element"` (single-element presets), or **`"section"`
+(the SECTION CORPUS — every individual section of every Pro layout,
+classified by purpose)**. The remaining filters are exact-match taxonomy
+axes, and one of them has a name that does NOT match YOOtheme's own public
+vocabulary — know this before you guess a param name from the YOOtheme docs:
+
+| Param          | Axis (kind)              | Example values                               |
+|----------------|--------------------------|----------------------------------------------|
+| `topic`        | industry (all kinds)     | `"Health & Fitness"`, `"Beauty & Fashion"`   |
+| `type`         | site purpose (layout+section) | `"Company"`, `"E-commerce"`, `"Magazine"` |
+| `role`         | page role (layouts)      | `"Home"`, `"Contact"`, `"Services"`          |
+| `purpose`      | **section role (sections)** | `"hero"`, `"features"`, `"cta"`, `"gallery"`, `"pricing"`, `"faq"`, `"contact"`, `"team"`, `"stats"`, `"testimonial"`, `"logos"`, `"content"` |
+| `has_effects`  | **section has parallax/sticky/etc (sections, bool)** | `true` / `false`         |
+| `element_type` | preset element (presets) | `"accordion"`, `"alert"`, `"headline"`       |
+| `website`      | source demo (all)        | `"Makai"`, `"FC Greenfield"`, `"Balou"`      |
+| `query`        | substring on name (all)  | `"hero"`                                     |
+
+**`kind: "section"` is how you COMPOSE a page from individually-chosen
+sections** instead of dropping one whole demo layout. A section row's `id`
+is the composite `"<layoutId>#<sectionIndex>"` (e.g. `"955bd3dc#0"`); each
+row also carries `purpose`, `topic`/`type`/`website`, `visual_effects`, and
+a `thumbnail_url` (its parent layout's preview). Feed that composite `id`
+straight into `library_get` / `library_insert` with `kind: "section"`.
+
+**`role` is YOOtheme's "layout" taxonomy axis, renamed.** YOOtheme's own
+catalog calls this 4th axis "layout" (Home/Footer/Post/Services/Contact/…
+— the page's ROLE), but the MCP tool parameter is `role`, not `layout` —
+`kind: "layout"` already occupies that word for "which catalog". Passing
+`layout: "Home"` to `library_browse` is silently ignored (unknown key
+rejected by the schema); use `role: "Home"`.
+
+`limit` (1-100, default 25) + `cursor` (from a previous response's
+`next_cursor`) paginate; `total: 0` (with an otherwise-valid filter
+combination) usually means the filter combination matched nothing, not a
+missing key — narrow or drop filters to check.
+
+### Composing a PROFESSIONAL page — the selection ladder (do NOT grab the first result)
+
+The catalog returns rows in a FIXED order. The first rows are NOT "the
+best" — they are just first, and one demo (e.g. Balou) sits at the top of
+most loosely-filtered results. Grab the top row and you ship that one demo
+relabeled. A professional result comes from FIT, not position:
+
+1. **Read the brief for INDUSTRY + TONE.** "Handmade scented candles,
+   warm/boutique" → industry ≈ retail/e-commerce, tone ≈ warm, premium,
+   calm. "SaaS analytics dashboard" → type Company/Software, tone clean/
+   minimal/techy. Name the tone explicitly before you browse.
+2. **Filter to the relevant demos** with `type` (E-commerce/Company/
+   Magazine…) + `topic` (industry). This narrows hundreds of layouts to the
+   few that could fit.
+3. **EVALUATE MULTIPLE candidate websites — never take the first.** Scan the
+   distinct `website` values in the filtered rows (an E-commerce filter
+   surfaces Balou, Woolberry, Tech Space, …). For your 2-3 finalists pull the
+   thumbnail — `thumbnail_url` is free; `library_get({ include_thumbnail:
+   true })` returns the actual image block (~950 tokens, finalists ONLY) —
+   and JUDGE which demo's aesthetic matches the brief's TONE. A playful
+   kids-brand demo (cartoon mascots, bright primaries) is the WRONG base for
+   a premium/calm brand even when it is technically the right `type`.
+4. **Commit to ONE `website` for the whole page.** Sections from different
+   demos carry different spacing rhythm, type scale, and decorative
+   language; mixing them reads as inconsistent. Pick the single best-fit
+   `website` and compose from ITS sections (`kind: "section"`, `website:
+   "X"`), or load its whole matching layout. Mix websites only when you
+   deliberately need a section no single demo provides — then reconcile the
+   look by eye.
+5. **Whole layout vs section-compose.** If ONE demo layout already matches
+   the page you need (hero → features → about → contact), load it whole
+   (`kind: "layout"`) for guaranteed internal consistency. If you need a
+   bespoke structure (this demo's hero + that demo's pricing table),
+   assemble it from `kind: "section"` rows.
+
+### Make it the CUSTOMER's brand, not the demo's
+
+A loaded demo carries that demo's SPECIFIC identity. "Adapting" is NOT just
+rewriting headlines — you must strip the demo's fingerprints, or the page
+reads as an obviously-relabeled template:
+
+- **Off-brand decorative graphics.** Many demos scatter decorative SVG
+  illustrations (a kids-shop's cartoon rockets/planets/clouds; a hand-drawn
+  mascot). Those belong to THAT brand. A section row's `visual_effects`
+  listing `floating_decoration` is the signal it carries them. After
+  inserting, locate them (`page_get_layout({ mode: "outline" })` or
+  `layout_query`) and `element_delete` the ones that don't fit the
+  customer's brand. A premium candle shop with cartoon rockets drifting past
+  its hero is instantly "not real".
+- **Demo product/subject photography.** `curated` downloads the demo's OWN
+  photos — including its specific products (a knitwear demo's baby suits, a
+  realty demo's houses). You cannot honestly relabel a teddy-bear photo as
+  "Vanilla Candle". For product/subject slots, clear those images to
+  placeholder (awaiting the customer's real photos) rather than shipping a
+  mismatched photo. Atmospheric/texture shots (a calm interior, hands at
+  work) often transfer; product-identity shots do not.
+- **Copy.** Rewrite EVERY headline, subheading, button, and body string to
+  the customer's brand and offering — leave NO demo copy ("Knit & More",
+  "Inspired by our children") anywhere.
+- **The professionalism signal is the IMAGERY.** Structure and style come
+  from the Library for free; what separates "finished" from "template" is
+  on-brand images. A clean placeholder reads as "ready for your photos"; a
+  MISMATCHED demo photo reads as "broken". When you cannot supply the
+  customer's real image, prefer the honest placeholder over the wrong photo
+  — and TELL the customer which slots need their photography.
+- **Not every section degrades gracefully to a placeholder — CHOOSE ONES
+  THAT DO.** This is decisive for the hero, which sets the whole first
+  impression. A single `image` element renders YOOtheme's clean placeholder
+  graphic when empty (looks intentional). But an image-DRIVEN section —
+  a `slideshow` / `gallery` / full-bleed background-image hero — renders
+  BLANK (an empty white void, not even a placeholder graphic) when its
+  images are placeholders. A blank slideshow hero reads as broken, not
+  "ready for photos". So when you will leave a section on placeholders
+  (i.e. you don't have the customer's photos yet), PREFER sections whose
+  design holds up WITHOUT a photo: a text-on-solid-`style` hero (dark or
+  muted section + headline + CTA), a typographic/`content` section, an
+  icon/feature grid. AVOID committing to a `slideshow`/`gallery`/full-bleed
+  photo hero unless you actually have images to fill it. Check a candidate
+  section's `element_signature` (a `slideshow`/`gallery`/`overlay-slider`
+  signature = image-driven) before you make it your imageless hero. A calm
+  text hero with clean type beats a blank photo slot every time.
+- **CONTRAST is non-negotiable — dark text on a dark panel is invisible.**
+  A section originally designed as text-over-a-photo often carries dark text
+  meant to sit on a light image. When you clear that image and the section
+  falls back to a dark `style` (`secondary` / `primary` resolve dark on most
+  themes), the text stays dark → dark-on-dark → the hero looks empty/broken.
+  Whenever a section sits on a DARK background, set the SECTION's
+  `text_color: "light"` (it cascades to all descendants) so the headline,
+  subhead and CTA read; on a LIGHT/`muted` background leave `text_color`
+  default (dark). This is a section-level prop and the ONE style token you
+  DO adjust when re-theming a hero (it is a legibility fix, not a brand
+  override). After building an imageless hero, sanity-check: is the headline
+  clearly readable against its background? If you cannot tell, the customer
+  can't either — fix the contrast. For a hero over a real PHOTO (not a solid
+  style), text_color alone is not enough; see "A photo hero needs a scrim"
+  under the image-sourcing subsection.
+
+### `library_get`: the natural next call
+
+`library_get({ id })` (the `id` comes straight off a `library_browse`
+row) returns `{ id, kind, name, version, tree, sections,
+images_manifest_count }`. `sections` lists the item's top-level
+`tree.children` as `{ index, name, path, element_count }` — layouts only;
+a preset (`kind: "element"`) always returns `sections: []` because a
+preset IS one element, not a container of sections. Use a `sections[]`
+entry's `index` as `library_insert`'s `section_index` to splice in ONE
+section instead of the whole layout (e.g. just the "Hero" section from a
+6-section Home layout).
+
+### Load-semantics: what you get is NOT the demo thumbnail
+
+**A Library item ADOPTS the connected site's currently-active Style**
+(the YOOtheme Customizer's global UIkit theming) when it renders — it
+does **not** carry the demo site's colors with it. The catalog item's
+props are semantic UIkit tokens (`style: "primary"` / `"muted"` /
+`"secondary"`, `text_color: "light"`, UIkit utility classes), never
+hardcoded hex colors. Those tokens resolve against whatever style the
+CONNECTED site currently has active, so the same "Balou Home" layout
+renders in the customer's own brand colors, not Balou's. Do not tell a
+customer "this will look like the screenshot" — it will look like their
+site.
+
+**When you adapt the inserted content, preserve those semantic tokens —
+never replace them with a hardcoded color.** Swapping `style: "primary"`
+for a literal `#1a73e8` (or similar) breaks themeability: the section
+stops following the site's Customizer style entirely, and a future
+Customizer style change silently skips it. "Adapting" a Library item
+means changing CONTENT (copy, images, links) — never the style/
+`text_color` tokens, the responsive `width_*` props, or any of the other
+structural/authoring props documented above (Multi-column layouts,
+Typography). If a specific override is genuinely wanted, that's a
+deliberate `element_update_settings` call the customer asked for, not a
+default step of "adapting" a Library insert.
+
+**Collapsing is a feature — don't defeat it with dummy content.** An
+empty/unbound field in an inserted section collapses cleanly at
+render-time (Element → Column → Row → Section cascade; a 3-column grid
+with 2 empty columns renders as one full-width column). Leave a field you
+have nothing to put there GENUINELY empty rather than stuffing placeholder
+text into it "so it doesn't look broken" — the collapsing behavior is
+what makes a Library section adapt gracefully to less content than the
+demo had.
+
+### Images: `placeholder` (default) vs `curated`
+
+`library_insert`'s `images` param controls what happens to the item's
+demo image references (`image`, `image_svg`, `poster`, and several
+element-specific media props — all point at short-lived signed CDN URLs
+at fetch time, never persisted raw):
+
+- **`"placeholder"` (the default — zero network I/O).** Every image prop
+  is cleared to an empty value; YOOtheme's own placeholder graphic renders
+  in its place. This is the right choice for a REAL customer site — the
+  agent (or the customer) fills the placeholders with the customer's own
+  photos afterward. Nothing is downloaded, nothing sideloads into the
+  Media Library.
+- **`"curated"` — downloads every UNIQUE demo image once into the site's
+  Media Library** (a signed URL reused across multiple props/nodes, e.g.
+  the same hero photo as both a section background and a card thumbnail,
+  is imported exactly once, not N times). Use this for a QUICK DEMO where
+  looking finished immediately matters more than using the customer's own
+  photography. Requires the same Library API key as browse/get/insert —
+  no separate key. A per-image download failure degrades ONLY that one
+  image to a placeholder and is counted in the response; it never aborts
+  the rest of the insert.
+
+The insert response's `images_resolved: { downloaded, placeholders }`
+tells you exactly what happened — check it rather than assuming every
+image round-tripped.
+
+### Fill image slots with real on-topic photos (search → import → bind)
+
+The professionalism signal is on-brand IMAGERY (see "Make it the CUSTOMER's brand"). You are not limited to leaving placeholders: you can pull REAL, on-topic photography from the SAME sources the YOOtheme Pro image dialog uses (Unsplash, Pexels, and YOOtheme Pro Images) and bind it into the layout. This is what turns a correct-but-bare skeleton into a RICH, finished-looking page.
+
+**The flow (three tools):**
+1. `yootheme_builder_image_search({ source, query, orientation })` returns candidate rows, each with a `full_url` (the image to import) plus dimensions and author. `source`: `unsplash` or `pexels` for real photography (the primary rich sources); `proimages` for YOOtheme's own curated decorative and background assets. Use `orientation: "landscape"` for heroes and banners, `"portrait"` for tall cards.
+2. JUDGE the candidates by FIT and TONE, exactly like you choose a section, and never grab the first result. Search deliberately by the brief's INDUSTRY plus TONE: a coffee roaster searches `"coffee roasting"` / `"espresso pour"` / `"cafe interior"` (warm, editorial); a law firm searches `"modern office architecture"` (clean, restrained). A generic `query: "business"` returns generic stock that reads as filler.
+3. `yootheme_builder_image_import({ url: "<full_url>" })` sideloads the chosen photo into the site's OWN Media Library and returns `{ local_url }`. Only Unsplash, Pexels, and YOOtheme image hosts can be imported (a security allowlist); other URLs are rejected.
+4. Bind it: `yootheme_builder_element_update_settings({ template_id, element_path, props: { image: "<local_url>" }, merge: true })`.
+
+**Real photo vs honest placeholder:**
+- A real, ON-TOPIC photo beats a placeholder every time; it is the single biggest lift from "template" to "finished". Fill the hero and feature-section image slots with searched photos that match the brief.
+- A MISMATCHED photo is worse than a placeholder. If you cannot find a genuinely on-topic image for a slot (for example a specific product the customer sells), leave the honest placeholder and tell the customer that slot needs their own photography. Never bind an off-topic photo just to fill space.
+- This does not change imageless-resilience: still avoid committing a slideshow / gallery / full-bleed-photo hero UNLESS you are filling it with real images. If you ARE filling it, a photo hero is now a strong choice.
+- CONTRAST still applies: a photo hero with overlaid text needs a legible contrast (a dark overlay, or the section `text_color`), the same check as an imageless hero.
+
+Real photos are the customer's brand made visible: search for THEIR industry and tone, import the best fit, and leave honest placeholders only where a real photo genuinely cannot be found.
+
+**A photo hero needs a scrim, not just `text_color: light`.** When a hero uses a real PHOTO as its background (not a solid section `style`), `text_color: "light"` alone is often not enough: a photo with bright regions (a flame, a bright sky, a white wall) leaves overlaid text unreadable where a line crosses that bright area. Real photo heroes need a SCRIM: a semi-transparent dark overlay between the photo and the text, so light text reads across the WHOLE block. Set it via the section/image element's own overlay/gradient prop (discover the exact key with `element_type_get_schema` on the element type carrying the image, e.g. an `overlay` or image-modifier prop), or place the headline group inside an inner panel with a translucent dark background. After binding a photo hero, sanity-check EVERY line (headline AND subheadline/meta), not just the top line: if any line sits over a bright part of the photo, add or darken the scrim. A headline that reads but a subheadline that washes out over the bright center is still a fail.
+
+**If you write labels into a photo-only component, turn the labels ON.** Some Library sections are image-ONLY by design: a slideshow/carousel/grid/gallery with `show_title: false` and `show_content: false` (the demo shows only the photos, with any titles hidden or hover-only). If you repurpose such a section as a LABELED grid (named specialties, services, team, each with a caption under its photo), the titles and descriptions you write are STORED in the layout but NOT DISPLAYED until you set `show_title: true` (and `show_content: true` for descriptions) on that element. After filling such a section with real photos AND written labels, read the element back (`element_get`) and check `show_title` / `show_content`: if you added captions, enable them; if you genuinely want image-only, leave them off. Never leave written labels invisible.
+
+### Composing RICH, VARIED sections: the Pro-DNA palette (choose and vary, never default to bare)
+
+The most common way an AI-built page falls short of a real Pro layout: it defaults to the SAME bare shape for every section (`section -> row -> column -> a grid of 3 plain text cards`, default props). Real Pro layouts are RICH and VARIED. This is a PALETTE plus a set of polish features so you CHOOSE the pattern that fits each brief and VARY it. It is NOT a fixed template. Two different briefs, and two different sections of the same page, should look different. Sameness is a failure here just as much as bareness.
+
+**Where the variety comes from (in this order):**
+1. Compose from the real Library sections FIRST. The section corpus (`library_browse({kind:"section"})`) is about 2000 individually-designed, already-rich sections across every demo. Selecting well among them for fit, tone, and variety, and preserving their design, is the primary path to a varied Pro-quality page. Do NOT strip their rich features (below).
+2. When you hand-build a section (no corpus section fits, or you build from native elements), reach into the palette below and pick the rich pattern that fits. Never the bare-minimum version. Vary your choices across the page.
+
+**The polish features Pro sections use constantly (these ARE what "rich" means): preserve them when composing, apply them when hand-building. The `panel` props named below are VERIFIED against the LIVE YOOtheme Pro 5.x `panel` schema (`element_type_get_schema("panel")` → 81 fields). `element_type_get_schema` is the source of truth — always confirm the exact key AND its enum values there before writing; a guessed key is hard-rejected and a guessed VALUE silently no-ops.**
+- **Card styling — THE single biggest "flat vs rich" lever: `panel_style` on a `panel`.** A bare `panel` (or a plain column of text) is what makes a section look flat; a `panel_style` turns it into a real styled CARD. Verified enum: `card-default` / `card-primary` / `card-secondary` / `card-hover` (hover-lift card) / `card-overlay` / `tile-default` / `tile-muted` / `tile-primary` / `tile-secondary`. A feature / team / pricing "card" is a `panel` WITH a `panel_style`, not three bare text columns.
+- **Hover** (on a `panel`; the image-hover props require a `link` + `panel_link`/`image_link`, per the schema `enable` rules): `hover_image` (swap the image on hover), `image_transition: scale-up`|`scale-down` (image zoom on hover), `title_hover_style: reset`|`heading`. `panel_style: card-hover` also gives a hover lift on its own.
+- **Depth**: `image_box_shadow` (`small`…`xlarge`) and `image_box_decoration` (`default`/`primary`/`secondary`/`shadow`/`mask`) — these apply to a panel image only when NO `panel_style` is set (they are mutually gated: use a `panel_style` OR the box-shadow/decoration, not both).
+- **Parallax** on section background images: the strongest single signal (~85% of feature/gallery/team sections carry it). Keep it when a Library section has it; on a hand-built image hero, add it (discover the section's parallax/image props via `element_type_get_schema("section")`).
+- **Entrance animation**: `animation` on the `section` (verified on the live section schema). Grids/galleries carry a per-item entrance-animation prop too — confirm its exact key on the `grid` / `gallery` schema before writing (do not assume `item_animation`).
+- **Deliberate spacing rhythm**: a panel's OWN margin props — `title_margin` / `meta_margin` / `content_margin` / `image_margin` (enum `xsmall`…`xlarge` / `remove`) — plus the `grid` element's row/column gap props. Never ship default spacing everywhere; confirm the exact keys on each element's schema.
+- **Section contrast**: alternate section `style` (`default` / `muted` / `primary` / `secondary`) so adjacent sections do not blur together; `text_color: light` on a dark section.
+- **Precise image control** (verified on the panel): `image_focal_point`, `image_align`, `image_width`, `image_border` (`rounded`/`circle`/`pill`).
+- **SVG shape dividers** between sections where it fits.
+
+**Per-purpose PALETTE: a menu of rich options to CHOOSE from, not a mandate. Pick what fits the brief, and vary.**
+- Hero: a headline-stack over a parallax image, OR a `slideshow`, OR an `overlay`. Often full viewport-height with `text_color:light`. (Not: a lone headline on a flat solid.)
+- Features or Services: a grid of `panel`s each with a `panel_style` (e.g. `card-default` or `card-hover`), an icon or image, a `title` + `content`, and hover (`hover_image` / `image_transition`); OR a `slideshow` of feature panels; OR an alternating image-and-text rhythm. (Not: 3 plain text columns.)
+- Gallery or Portfolio: a filterable `gallery`, OR an overlay-panel grid with hover, OR a `slideshow`. (Not: a plain image grid.)
+- Testimonials: a quotation with image, OR an `overlay`, OR a `panel` slider. (Not: one flat quote.)
+- Team: a card grid of `panel`s with `panel_style: card-*` (photo=`image`, name=`title`, role=`meta`, hover). (Not: bare photos with captions.)
+- Pricing: a row of `panel`s with `panel_style: card-*` + a button, OR a comparison table.
+- FAQ: an `accordion`.
+- Stats: `countdown` or big-number panels.
+- Logos: a `gallery` or `list` of many logo items.
+
+**The vary-mandate:** do not apply the same option to every section or every brief. A calm premium brand and a bold sporty brand get different patterns and different intensity of motion. Match the pattern, the polish, and the density to THIS brief.
+
+**This pays off only on the right foundation:** a rich active Customizer Style (fonts and colors) and a matching YOOtheme version (the Library is authored for YOOtheme 5.x; build and test on a 5.x site). On a bare Style or an old version the polish cannot render.
+
+### `target`: where an item lands (and the strict Preset → Column rule)
+
+`library_insert`'s `target` is EXACTLY ONE of three shapes, and which
+ones are legal depends on `kind`:
+
+| `target` shape | Accepts `kind: "layout"` | Accepts `kind: "element"` (preset) |
+|---|---|---|
+| `{ new_page: { title, status? } }` | ✓ creates a page, layout's sections become its content | ✗ rejected — a preset is not a page |
+| `{ template_id, element_path? }` | ✓ ONLY the layout ROOT is section-accepting (`element_path: ""` or omitted) | ✓ ONLY a **Column** — every other node type is rejected |
+| `{ sublayout: { template_id, element_path } }` | ✓ the fetched layout's sections are stripped to bare ROWS first (a sublayout/fragment accepts rows, not sections) | ✗ rejected — a sublayout is not a Column |
+
+**A preset (`kind: "element"`) MUST target a Column. There is no
+auto-wrap.** Pointing a preset at a section, row, layout root, new_page,
+or sublayout returns a `422 target_not_a_column` naming what the target
+actually is. The fix is always the same: scaffold a fresh
+`section → row → column` hull with `yootheme_builder_scaffold_section`
+first, then point `element_path` at ONE of the returned `column_paths`:
+
+```jsonc
+// A preset pointed at the layout root — REJECTED, no auto-wrap.
+yootheme_builder_library_insert({
+  id: "8cf55920",
+  kind: "element",
+  target: { template_id: "home", element_path: "" }
+})
+// → 422 target_not_a_column: 'target at "/" is a "layout"'.
+
+// Fix: scaffold a section->row->column hull, then target the new Column.
+yootheme_builder_scaffold_section({ template_id: "home", columns: 1, etag: "<etag>" })
+// Response includes column_paths: ["/children/4/children/0/children/0"]
+
+yootheme_builder_library_insert({
+  id: "8cf55920",
+  kind: "element",
+  target: { template_id: "home", element_path: "/children/4/children/0/children/0" },
+  etag: "<fresh>"
+})
+```
+
+**Sublayout targets accept only rows.** A sublayout/fragment element
+(see "JSON-Pointer path grammar" and the Multi-Items material above)
+holds row-groups, not sections — `library_insert` handles the strip for
+you automatically when `target.sublayout` is used; you never call a
+separate strip step. Point `element_path` at the actual sublayout/
+fragment node itself, not its parent — pointing at the wrong level is a
+`422 target_not_a_sublayout`.
+
+### Adapting a Library insert is STATIC content editing, not dynamizing
+
+**Every Library layout and preset is authored STATIC** — no source
+bindings, no `#parent` parent-source, no multiplication, no conditions.
+Adapting one after insert means editing copy/images/links on the fixed
+nodes it already has (`element_update_settings` on the specific
+headline/text/image `element_path`s), the same as editing any hand-built
+section.
+
+**Making an inserted section DATA-DRIVEN (repeat over a Source's items —
+an archive-style listing) is a deliberate, separate follow-up call, not
+something insert does for you.** Use the existing dynamize workflow
+documented in "Dynamize an existing section" just above this one
+(`yootheme_builder_page_dynamize`) to re-target a Library-inserted
+section's leaf fields onto a Source, or bind a Multi-Items container
+directly with `yootheme_builder_element_bind_source` (Workflow 2) if the
+inserted item already has a grid/list container you want to re-point at
+live data instead of its demo items.
+
+**Common pitfalls:**
+
+- **Assuming the inserted layout will look like the demo screenshot.**
+  It adopts the connected site's active Style — different fonts, colors,
+  spacing than the catalog thumbnail. Tell the customer that up front.
+- **Hardcoding a color while "adapting" content.** Keep `style` /
+  `text_color` / UIkit classes exactly as inserted; only touch copy,
+  images, and links.
+- **Pointing a preset (`kind: "element"`) at anything but a Column** and
+  expecting an auto-wrap. There isn't one — scaffold first.
+- **Choosing `images: "curated"` for a production customer site.** That's
+  for quick demos; a real site wants `placeholder` + the customer's own
+  photography.
+- **Stuffing placeholder copy into a field you have nothing for**, to
+  defeat collapsing. Leave it empty; collapsing is the intended behavior.
+- **Expecting `library_insert` to make anything dynamic.** It composes
+  STATIC content only — dynamizing is the separate `page_dynamize` /
+  `element_bind_source` call.
+
+**Worked example (browse → get → insert → adapt):**
+
+```jsonc
+// 1. Browse: filter by industry + page-role, layouts only (kind default).
+yootheme_builder_library_browse({ topic: "Health & Fitness", role: "Home", limit: 10 })
+// Response: { items: [{ id: "955bd3dc", name: "Home", kind: "layout",
+//   meta: { topic: "Health & Fitness", type: "Company", role: "Home", website: "Makai", image: "<cdn-image-url>" },
+//   thumbnail_url: "<cdn-thumbnail-url>" }], total: 64, next_cursor: null }
+
+// 2. Fetch the chosen item's tree + section list.
+yootheme_builder_library_get({ id: "955bd3dc" })
+// Response: { id: "955bd3dc", kind: "layout", name: "Home", version: "5.0.9",
+//   tree: { type: "layout", children: [ /* ... */ ] },
+//   sections: [
+//     { index: 0, name: "Hero", path: "/children/0", element_count: 12 },
+//     { index: 1, name: "Services", path: "/children/1", element_count: 18 }
+//   ],
+//   images_manifest_count: 9 }
+
+// 3. Insert only the "Hero" section onto an existing page's layout root.
+yootheme_builder_library_insert({
+  id: "955bd3dc",
+  target: { template_id: "home", element_path: "" },
+  section_index: 0,
+  images: "placeholder",
+  etag: "<etag>"
+})
+// Response: { template_id: "home", inserted_path: "/children/3", element_count: 12,
+//   images_mode: "placeholder", images_resolved: { downloaded: 0, placeholders: 6 },
+//   new_etag: "<fresh>", frontend_url: null }
+
+// 4. Adapt: swap the demo headline for the customer's own copy. Read the
+// inserted section back first (page_get_layout / element_get) to find the
+// real headline's element_path, then edit CONTENT only — style untouched.
+yootheme_builder_element_update_settings({
+  template_id: "home",
+  element_path: "/children/3/children/0/children/0",
+  props: { content: "<customer's real headline>" },
+  merge: true,
+  etag: "<fresh>"
+})
+```
+
+**Success criterion:** the inserted section renders in the CONNECTED
+site's active Style (not the catalog demo's colors), every field the
+customer supplied content for shows that content, and every field they
+did not touch either shows a clean placeholder (`images: "placeholder"`)
+or collapses (empty unbound field) — never a broken image icon or a
+dangling demo string.
+
+## Look at what you built — the visual check (and two capture traps)
+
+`render_preview` proves the page RENDERED and that a string reached the
+HTML. It does **not** prove it LOOKS right. Text can be present and
+invisible (muted grey on white); a section can be structurally perfect and
+still read as a dead band. **If your client has a browser tool, screenshot
+the page's `frontend_url` and LOOK at it before you call the work done.**
+That is not optional polish — it is the step that catches the failures
+every structural check reports as fine.
+
+Two capture traps make a CORRECT page look broken. Both are artifacts of
+the SCREENSHOT, not of the layout — verified live against YOOtheme Pro:
+
+**Trap 1 — scrollspy + lazy-load: a no-scroll full-page shot is mostly
+blank.** YOOtheme animates sections in with `uk-scrollspy`: elements sit at
+`opacity: 0` until scrolled into view, and images lazy-load. A full-page
+screenshot that never scrolls captures them at opacity 0 — you get a long
+white page with only the hero visible. **Fix: scroll the full document
+height in viewport-sized steps first (that fires scrollspy + lazy-load),
+then capture.**
+
+**Trap 2 — `fixed` parallax bands can never be stitched.** A section using
+`image_effect: "fixed"` (CSS `background-attachment: fixed`) does not
+survive a stitched full-page capture at all — scrolling does NOT help. It
+comes out as a pure white void. **Fix: for any fixed-effect section, scroll
+it into view and capture the VIEWPORT only (a band shot).**
+
+**Never judge — and never DELETE — a section based on a full-page
+thumbnail.** A real agent came within one call of deleting a page's best
+section (a full-bleed parallax band carrying the founder quote) because the
+full-page shot showed it as an empty white gap.
+
+Once you can actually see the page, hunt the defects no tool reports:
+
+- **Invisible / low-contrast text** — e.g. a caption left on muted grey
+  over white. Fix with an explicit contrast prop (e.g. `meta_color:
+  "emphasis"`), never by deleting the caption.
+- **Reading order** — a column that leads with a tall image buries its own
+  headline, so the neighbouring column reads first and the story inverts.
+  Fix with `element_move` so both columns start with their headline at the
+  same height.
+- **No display moment** — every headline semantic and same-sized reads
+  flat. Give exactly ONE hero headline a display `title_style` while
+  KEEPING its `title_element` (size ≠ tag — see Typography; SEO untouched).
+- **Section rhythm** — two adjacent same-background sections blur together;
+  alternate one (`style: "muted"`).
+- **Idiom coherence** — a section borrowed from a different demo can carry
+  a foreign visual language (e.g. hairline SaaS metric cards inside warm
+  editorial photography). Cut it or restyle it; do not leave the seam.
+- **Copy contradictions** — check the page's own facts against each other
+  ("Fifteen years" under a "SINCE 2014" eyebrow) and drop claims repeated
+  in three sections.
+
+**If you have no browser tool, say so plainly.** Report that you verified
+the page structurally (`render_preview` + `expect`) but did NOT see it, and
+ask the customer to eyeball it. Never imply a visual check you did not
+perform.
+
 ## Appendix: Tool Catalog (auto-generated)
 
 <!-- TOOL-CATALOG:BEGIN -->
 
-**39 catalogued tools** plus the `yootheme_builder_advanced` (write) + `yootheme_builder_advanced_read` (read-only) gateways = **41 reachable via `tools/list`** (32 L1 + 2 L3 + 2 gateways = 36 advertised; the gateways route to 5 additional advanced tools, bringing the total to 41 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.
+**48 catalogued tools** plus the `yootheme_builder_advanced` (write) + `yootheme_builder_advanced_read` (read-only) gateways = **50 reachable via `tools/list`** (37 L1 + 2 L3 + 2 gateways = 41 advertised; the gateways route to 9 additional advanced tools, bringing the total to 50 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 |
 | --- | --- | --- | --- |
@@ -1122,24 +2202,33 @@ styles, the `#parent` bindings) survives untouched.
 | `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` | Update `props` on an element. Default replaces all props; pass `merge:true` for server-side deep-merge (only request keys overwritten, others survive — avoids read-modify-write races). Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_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_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_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_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_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_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_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. 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`, `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` — 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_pages_audit` | read+idempotent | `checks`, `max_chars`, `site_id`, `stale_after_months`, `thin_content_threshold`, `types` | One-call site-wide SEO/structure/content/links audit — severity-sorted findings with machine-executable fix_hints (missing/multiple h1, empty/thin pages, missing image alt, duplicate layouts, title collisions, non-pretty URLs, stale content, dead anchors). Filter with `types`/`checks`. Disclaimer: SEO-plugin meta (title/description/OG) NOT covered. Drill in via template_summary; fix one page at a time via each finding's fix_hint. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_pages_create` | idempotent | `dry_run`, `layout`, `menu_item`, `published`, `site_id`, `slug`, `status`, `title` | Create a page (WordPress) or article (Joomla 5/6) with a YOOtheme per-page layout. Required: title. Optional: slug, status (default draft), published (default false → live on true: WP publish / Joomla state 1), layout (JSON), menu_item (Joomla SEF route), dry_run (preflight, no persist). Returns page_id (WP) / article_id (Joomla), slug, template_id (page:{id} or article:{id}), etag, warnings. Joomla: a published article has NO SEF route until a menu item points at it — pass menu_item, else frontend_url may 404. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_pages_delete` | idempotent | `confirm`, `force`, `post_id`, `site_id` | Delete a page (WordPress) or article (Joomla 5/6) with its YOOtheme per-page layout. Requires confirm:true (gate against accidental deletion). Default: trash (recoverable). force:true: permanent delete. Refuses non-page/article types with 403 (Layer 9 defense). Returns deleted:true, page_id (WP) / article_id (Joomla), force_deleted, bumped etag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_pages_list` | read+idempotent | `cursor`, `fields`, `label_contains`, `limit`, `max_chars`, `site_id` | List pages, templates, and layouts in the YOOtheme Pro builder (template_id, label, type, element count, frontend_url, builder_url 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 OR archive URL to the template_id that renders it — paste a URL, get a layout-addressable id in one call. A singular page resolves to its per-page layout; a CPT archive (/faq/), taxonomy/category/tag term, or author archive resolves to the governing THEME TEMPLATE. Returns {template_id, post_id (null for theme templates), type, frontend_url, context (matched YT type), resolved_via (per_page\|theme_template)}. Only home/search/date 404 (use pages_list). page_get_layout/page_get_schema also accept `url`. 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 | `columns`, `etag`, `site_id`, `template_id` | Create a VALID section → row → column hull in ONE atomic call and return the column JSON-Pointer path(s) to drop content into. This is the EASIEST correct way to start a new layout block: YOOtheme content must live in section → row → column, and adding content anywhere else (root, bare section, bare row) is rejected. Pass `columns` (1-12, default 1) for a multi-column row. Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_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_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. |