@wootsup/yt-builder-mcp 1.9.0 → 1.10.0

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

@@ -12,15 +12,15 @@ description: Drive the YOOtheme Pro Page Builder on WordPress or Joomla 5/6. Dis
 > WordPress and Joomla 5/6.
 
 This skill helps AI assistants drive the YOOtheme Pro Page Builder through the
-`@wootsup/yt-builder-mcp` server. The server catalogues 47 typed, scoped,
-idempotent tools (49 callable end-to-end with the two gateways). 41 of them
+`@wootsup/yt-builder-mcp` server. The server catalogues 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`
-(37 essential L1 forwards + 2 direct L3 entries + 2 gateways), and 8 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 8; 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, local_content_types,
-local_content_read) and is itself
+local_content_read, pages_audit) and is itself
 read-only-annotated, so MCP hosts can auto-allow pure inspection without a
 per-call write-approval prompt. This 3-lane split keeps `tools/list` well below
 the ~40-tool Cursor cap while every catalogued tool stays fully reachable.
@@ -55,7 +55,7 @@ entries when the user types "YT Builder MCP" into the picker:
 
 - **`YT Builder MCP for YOOtheme Pro (unofficial)`**: the MCP **server**.
   Provides the 41 first-class tools (37 essential, 2 direct, 2 gateways).
-  The `yootheme_builder_advanced` gateway routes all 8 advanced tools; the
+  The `yootheme_builder_advanced` gateway routes all 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
@@ -125,10 +125,11 @@ The server exposes:
   step that turns a placeholder-filled skeleton into a finished-looking
   page (see "Fill image slots with real on-topic photos" under Layout
   Library).
-- **8 advanced captured tools**: everything else (page_get_schema,
+- **9 advanced captured tools**: everything else (page_get_schema,
   element_unbind_source, clean_implode_directives,
-  `inspect_sublayout`, `layout_query`, `library_save_as`, and the two Local
-  Content Read tools `local_content_types` / `local_content_read`).
+  `inspect_sublayout`, `layout_query`, `library_save_as`, the two Local
+  Content Read tools `local_content_types` / `local_content_read`, and
+  `pages_audit`).
   Reachable through one gateway tool:
   `yootheme_builder_advanced({ tool: "<name>", arguments: { ... } })`. For
   example, to inspect a panel/grid_item `< SUBLAYOUT`:
@@ -143,6 +144,12 @@ The server exposes:
   It flags `invalid_source_possible: true` when the saved subtree carries
   bound dynamic sources that may not exist wherever it is later reloaded —
   re-bind after inserting it elsewhere.
+  And to run a one-call site-wide SEO/structure/content/links audit
+  (read-only, severity-sorted findings + machine-executable fix_hints),
+  prefer the read gateway:
+  `yootheme_builder_advanced_read({ tool: "yootheme_builder_pages_audit", arguments: { checks: ["seo", "structure"] } })`
+  (the write gateway routes it too, if you prefer one entry point:
+  `yootheme_builder_advanced({ tool: "yootheme_builder_pages_audit" })`).
 
   The core write/refactor + render-verify tools the Glöckle HANDOFF-4/5 ask for
   are now **L1 — call them directly by name**, not through a gateway:
@@ -184,7 +191,8 @@ The server exposes:
 - **2 gateway tools**: `yootheme_builder_advanced` (write-capable; can route
   into delete/unbind, so hosts gate it) and `yootheme_builder_advanced_read`
   (read-only; routes ONLY the read-only advanced subset — page_get_schema,
-  inspect_sublayout, layout_query, local_content_types, local_content_read —
+  inspect_sublayout, layout_query, local_content_types, local_content_read,
+  pages_audit —
   and is read-only-annotated so hosts auto-allow it). Prefer the read gateway
   for pure inspection:
   `yootheme_builder_advanced_read({ tool: "yootheme_builder_page_get_schema", arguments: { template_id } })`.
@@ -196,8 +204,8 @@ The server exposes:
   `yootheme_builder_advanced({ tool: "yootheme_builder_local_content_read", arguments: { kind: "entities", type: "post" } })`.)
 
 `tools/list` therefore advertises 41 names (37 + 2 + 2). That's 37 L1
-essentials + 2 L3 direct + 2 gateways. The total callable surface is 49
-(41 advertised + 8 advanced reachable through the gateways). If the AI
+essentials + 2 L3 direct + 2 gateways. The total callable surface is 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
@@ -736,6 +744,12 @@ must have **exactly one** `<h1>`). Set it explicitly on every headline:
 for punch); a big stat number is `title_element: "div"` with
 `title_style: "heading-medium"`.
 
+**This `h1` default is specific to `headline`.** Container elements
+(`grid`, `panel`, `slideshow`, and the rest of the item-carrier family)
+default to `h3`, not `h1`, when `title_element` is left unset. See
+"Workflow 6 (SEO audit)" below for the full per-type default table
+`pages_audit` uses to find missing/multiple h1 issues across a whole site.
+
 ### Headline `content` is plain inline text — never wrapped in `<p>`
 
 A `headline` renders its `content` **inside** the heading tag, so wrapping it
@@ -1238,7 +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,
@@ -2016,7 +2184,7 @@ perform.
 
 <!-- TOOL-CATALOG:BEGIN -->
 
-**47 catalogued tools** plus the `yootheme_builder_advanced` (write) + `yootheme_builder_advanced_read` (read-only) gateways = **49 reachable via `tools/list`** (37 L1 + 2 L3 + 2 gateways = 41 advertised; the gateways route to 8 additional advanced tools, bringing the total to 49 callable). Generated by `scripts/extract-tools.mjs` from the compiled `buildAllTools()` registry. Do not hand-edit this section; re-run `npm run build && node scripts/extract-tools.mjs` after changing tool definitions.
+**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 |
 | --- | --- | --- | --- |
@@ -2051,8 +2219,9 @@ perform.
 | `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` | 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. |