@linchpinagency/skills 0.1.0

package/skills/wordpress-blocks/references/core-blocks.md

@@ -0,0 +1,123 @@
+# Core block cheat sheet
+
+Copy-paste-correct markup for the core blocks you'll compose with most. Shapes drift slightly
+by WordPress version — always `validate_blocks` the result (see `validation.md`). Core blocks
+omit the `core/` namespace.
+
+## Text
+
+**Paragraph**
+```html
+<!-- wp:paragraph -->
+<p>Body copy goes here.</p>
+<!-- /wp:paragraph -->
+```
+
+**Heading** (default level is `h2`; set `{"level":N}` AND change the tag together)
+```html
+<!-- wp:heading -->
+<h2 class="wp-block-heading">Section title</h2>
+<!-- /wp:heading -->
+
+<!-- wp:heading {"level":3} -->
+<h3 class="wp-block-heading">Subsection</h3>
+<!-- /wp:heading -->
+```
+
+**List** (each item is its own `wp:list-item`)
+```html
+<!-- wp:list -->
+<ul class="wp-block-list"><!-- wp:list-item -->
+<li>First</li>
+<!-- /wp:list-item -->
+
+<!-- wp:list-item -->
+<li>Second</li>
+<!-- /wp:list-item --></ul>
+<!-- /wp:list -->
+```
+
+## Layout containers
+
+**Group** (constrained = respects theme content width; also `"flex"`, `"flow"`)
+```html
+<!-- wp:group {"layout":{"type":"constrained"}} -->
+<div class="wp-block-group">
+  <!-- child blocks -->
+</div>
+<!-- /wp:group -->
+```
+
+**Columns** (note nesting: `wp:columns` → `wp:column` → children)
+```html
+<!-- wp:columns -->
+<div class="wp-block-columns"><!-- wp:column -->
+<div class="wp-block-column">
+  <!-- column 1 children -->
+</div>
+<!-- /wp:column -->
+
+<!-- wp:column -->
+<div class="wp-block-column">
+  <!-- column 2 children -->
+</div>
+<!-- /wp:column --></div>
+<!-- /wp:columns -->
+```
+Set widths with `{"width":"33.33%"}` on each `wp:column`. Stacking on mobile is on by default;
+`{"isStackedOnMobile":false}` to disable.
+
+**Spacer** (has inner HTML — NOT self-closing)
+```html
+<!-- wp:spacer {"height":"40px"} -->
+<div style="height:40px" aria-hidden="true" class="wp-block-spacer"></div>
+<!-- /wp:spacer -->
+```
+
+## Media & actions
+
+**Image** (`id` ties to a real attachment; omit it for external/placeholder `src`)
+```html
+<!-- wp:image {"id":123,"sizeSlug":"large","linkDestination":"none"} -->
+<figure class="wp-block-image size-large"><img src="https://example.com/x.jpg" alt="" class="wp-image-123"/></figure>
+<!-- /wp:image -->
+```
+
+**Buttons** (always wrap a `wp:button` inside `wp:buttons`)
+```html
+<!-- wp:buttons -->
+<div class="wp-block-buttons"><!-- wp:button -->
+<div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="/contact">Get started</a></div>
+<!-- /wp:button --></div>
+<!-- /wp:buttons -->
+```
+
+**Cover** (background image/overlay with inner content; `dimRatio` = overlay opacity)
+```html
+<!-- wp:cover {"url":"https://example.com/bg.jpg","dimRatio":50,"minHeight":480} -->
+<div class="wp-block-cover" style="min-height:480px"><span aria-hidden="true" class="wp-block-cover__background has-background-dim"></span><img class="wp-block-cover__image-background" src="https://example.com/bg.jpg" alt=""/><div class="wp-block-cover__inner-container">
+  <!-- inner blocks: heading, paragraph, buttons -->
+</div></div>
+<!-- /wp:cover -->
+```
+
+## Using design tokens
+
+Prefer the site's theme.json slugs over hardcoded values (pull them from `get_theme_tokens()`):
+
+```html
+<!-- wp:heading {"textColor":"primary","fontSize":"x-large"} -->
+<h2 class="wp-block-heading has-primary-color has-text-color has-x-large-font-size">Title</h2>
+<!-- /wp:heading -->
+```
+The JSON attribute (`"textColor":"primary"`) and the generated classes
+(`has-primary-color has-text-color`) must agree — this is why validation matters.
+
+## Reuse references (not composition)
+
+These insert existing assets — see `patterns-and-parts.md`:
+```html
+<!-- wp:block {"ref":451} /-->                         ← synced pattern (wp_block #451)
+<!-- wp:pattern {"slug":"linchpin/pricing-3col"} /-->  ← registered pattern reference
+<!-- wp:template-part {"slug":"footer","theme":"linchpin"} /-->
+```

package/skills/wordpress-blocks/references/patterns-and-parts.md

@@ -0,0 +1,70 @@
+# Patterns and template parts — what to reuse, and how
+
+The site already holds reusable design assets. Reusing them beats hand-composing core blocks:
+it matches the designer's intent, stays on-brand, and (for synced patterns) keeps content
+updatable in one place. Three distinct things get confused — here's the contract for each.
+
+## 1. Synced patterns (`wp_block` custom post type)
+
+The successor to "reusable blocks." A saved block stored once and **linked** wherever it's
+used — edit it in one place, every instance updates.
+
+- **Find:** `search_patterns(query)` returns synced patterns with a numeric `ref` (the
+  `wp_block` post ID).
+- **Emit:** a void reference block — do **not** inline its markup:
+  ```html
+  <!-- wp:block {"ref":451} /-->
+  ```
+- **Edit one instance only:** the user must *detach* it (turns it into normal blocks). If
+  they ask to "change just this one," fetch the expanded markup via `get_pattern(ref:451)`,
+  insert that instead of the reference, and tell them it's now detached.
+- **Best for:** repeated, centrally-managed content — a standard CTA band, a contact block,
+  a promo the client updates site-wide.
+
+## 2. Registered patterns (theme- or plugin-provided)
+
+Reusable **layout templates** registered in code (theme `patterns/*.php`, a plugin, or the
+Pattern Directory). Inserting one drops a **one-time copy** of its blocks — no live link.
+
+- **Find:** `search_patterns(query)` returns them with a `slug` and `type:"registered"`.
+- **Emit:** fetch and inline the expanded blocks, adapting the copy to the request:
+  ```
+  const { block_markup } = get_pattern(slug: "linchpin/pricing-3col")
+  // insert block_markup, then swap in the user's plan names/prices
+  ```
+  (Some hosts also accept the overlay form `<!-- wp:pattern {"slug":"…"} /-->`, but inlining
+  the expanded markup is the portable, editable choice.)
+- **Best for:** starting a section from a designed layout the user will then customize.
+
+## 3. Template parts (`wp_template_part` — block themes / FSE)
+
+Header, footer, and reusable section parts of a **block theme**. These belong to *templates*,
+not to a page/post body.
+
+- **Find:** `list_template_parts()` → `{slug, title, area, theme}`.
+- **Emit (templates only):**
+  ```html
+  <!-- wp:template-part {"slug":"footer","theme":"linchpin","tagName":"footer"} /-->
+  ```
+- **Do not** insert a template part into post/page content. If the user wants a footer-like
+  block *inside* a page, use a synced pattern or compose blocks instead.
+
+## How this maps to the pattern-first procedure
+
+```
+request → search_patterns(keywords)
+  ├─ synced match?      → <!-- wp:block {"ref":ID} /-->
+  ├─ registered match?  → get_pattern(slug) → insert expanded markup, adapt copy
+  ├─ template part?     → only if editing a template → wp:template-part
+  └─ no match           → compose core blocks (recipes/ + core-blocks.md) using get_theme_tokens()
+→ validate_blocks → insert
+```
+
+Prefer a **good** match over a forced one. A weak pattern match that needs heavy rewriting is
+worse than a clean core-block composition. Use judgment: does the matched asset actually serve
+what the user asked for, or just share a keyword?
+
+Upstream concepts: synced patterns
+<https://wordpress.org/documentation/article/reusable-blocks/>,
+theme patterns <https://developer.wordpress.org/themes/patterns/>,
+template parts <https://developer.wordpress.org/themes/block-themes/template-parts/>.

package/skills/wordpress-blocks/references/recipes/faq.md

@@ -0,0 +1,56 @@
+# Recipe: FAQ section (fallback)
+
+Use after `search_patterns("faq questions accordion")` finds no good match.
+
+## Preferred — Details block (native accordion, no plugin)
+
+Core `wp:details` renders an expand/collapse `<details>` natively. Each Q is its own block.
+
+```html
+<!-- wp:group {"layout":{"type":"constrained"}} -->
+<div class="wp-block-group">
+<!-- wp:heading -->
+<h2 class="wp-block-heading">Frequently asked questions</h2>
+<!-- /wp:heading -->
+
+<!-- wp:details -->
+<details class="wp-block-details"><summary>How does billing work?</summary>
+<!-- wp:paragraph -->
+<p>You're billed monthly and can cancel anytime.</p>
+<!-- /wp:paragraph -->
+</details>
+<!-- /wp:details -->
+
+<!-- wp:details -->
+<details class="wp-block-details"><summary>Do you offer support?</summary>
+<!-- wp:paragraph -->
+<p>Yes — email support on every plan.</p>
+<!-- /wp:paragraph -->
+</details>
+<!-- /wp:details -->
+</div>
+<!-- /wp:group -->
+```
+
+Set `{"showContent":true}` on a `wp:details` to render it open by default.
+
+## Simpler — heading + paragraph pairs (no interactivity)
+
+If `wp:details` isn't registered on the site (`list_registered_blocks`), or the user wants a
+flat list, alternate headings and paragraphs:
+
+```html
+<!-- wp:heading {"level":3} -->
+<h3 class="wp-block-heading">How does billing work?</h3>
+<!-- /wp:heading -->
+
+<!-- wp:paragraph -->
+<p>You're billed monthly and can cancel anytime.</p>
+<!-- /wp:paragraph -->
+```
+
+## Adapt
+
+- Generate one `wp:details` (or heading/paragraph pair) per Q&A from the user's content.
+- Don't reach for a third-party accordion block unless the user names one and
+  `list_registered_blocks` confirms it's installed — `wp:details` covers most needs.

package/skills/wordpress-blocks/references/recipes/hero.md

@@ -0,0 +1,74 @@
+# Recipe: hero / header section (fallback)
+
+Use after `search_patterns("hero banner header")` finds no good match. Two variants.
+
+## Variant A — Cover (background image + overlay)
+
+Best when the user wants an image or color behind the headline. `dimRatio` is overlay
+strength (0–100). Inner blocks: heading, paragraph, buttons.
+
+```html
+<!-- wp:cover {"url":"https://example.com/hero.jpg","dimRatio":50,"minHeight":520,"align":"full"} -->
+<div class="wp-block-cover alignfull" style="min-height:520px"><span aria-hidden="true" class="wp-block-cover__background has-background-dim"></span><img class="wp-block-cover__image-background" src="https://example.com/hero.jpg" alt=""/><div class="wp-block-cover__inner-container">
+<!-- wp:heading {"textAlign":"center","level":1,"fontSize":"xx-large"} -->
+<h1 class="wp-block-heading has-text-align-center has-xx-large-font-size">Build faster with Linchpin</h1>
+<!-- /wp:heading -->
+
+<!-- wp:paragraph {"align":"center"} -->
+<p class="has-text-align-center">A short, punchy subhead that explains the value in one line.</p>
+<!-- /wp:paragraph -->
+
+<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
+<div class="wp-block-buttons"><!-- wp:button -->
+<div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="/contact">Get started</a></div>
+<!-- /wp:button --></div>
+<!-- /wp:buttons -->
+</div></div>
+<!-- /wp:cover -->
+```
+
+## Variant B — Group + columns (text left, image right, no overlay)
+
+Best for a clean split layout.
+
+```html
+<!-- wp:group {"align":"wide","layout":{"type":"constrained"}} -->
+<div class="wp-block-group alignwide">
+<!-- wp:columns {"verticalAlignment":"center"} -->
+<div class="wp-block-columns are-vertically-aligned-center"><!-- wp:column {"verticalAlignment":"center"} -->
+<div class="wp-block-column is-vertically-aligned-center">
+<!-- wp:heading {"level":1,"fontSize":"xx-large"} -->
+<h1 class="wp-block-heading has-xx-large-font-size">A headline that sells</h1>
+<!-- /wp:heading -->
+
+<!-- wp:paragraph -->
+<p>One or two sentences of supporting copy.</p>
+<!-- /wp:paragraph -->
+
+<!-- wp:buttons -->
+<div class="wp-block-buttons"><!-- wp:button -->
+<div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="/contact">Get started</a></div>
+<!-- /wp:button --></div>
+<!-- /wp:buttons -->
+</div>
+<!-- /wp:column -->
+
+<!-- wp:column {"verticalAlignment":"center"} -->
+<div class="wp-block-column is-vertically-aligned-center">
+<!-- wp:image {"sizeSlug":"large"} -->
+<figure class="wp-block-image size-large"><img src="https://example.com/hero.jpg" alt=""/></figure>
+<!-- /wp:image -->
+</div>
+<!-- /wp:column --></div>
+<!-- /wp:columns -->
+</div>
+<!-- /wp:group -->
+```
+
+## Adapt
+
+- Use `level:1` for the headline only if this is the page's main hero; otherwise `level:2`.
+- Swap colors/sizes for `get_theme_tokens()` slugs. For a solid-color background instead of an
+  image, drop the `url`/`img` and add `{"customOverlayColor":"…"}` or a `backgroundColor` token.
+- `align:"full"` / `align:"wide"` only render edge-to-edge if the theme supports those widths
+  (`get_theme_tokens().layout`).

package/skills/wordpress-blocks/references/recipes/pricing-table.md

@@ -0,0 +1,77 @@
+# Recipe: pricing table (fallback)
+
+Use this **only after** `search_patterns("pricing plans tiers")` finds no good synced/registered
+pattern. This is a three-tier table composed from core blocks. Pull color/font slugs from
+`get_theme_tokens()` and swap them in; `validate_blocks` the result.
+
+## Structure
+
+A constrained `group` (section heading) followed by a `columns` block — one `column` per plan,
+each a bordered `group` holding: plan name (`heading`), price (`heading`), feature `list`, and a
+`buttons` CTA.
+
+```html
+<!-- wp:group {"layout":{"type":"constrained"}} -->
+<div class="wp-block-group">
+<!-- wp:heading {"textAlign":"center"} -->
+<h2 class="wp-block-heading has-text-align-center">Simple, transparent pricing</h2>
+<!-- /wp:heading -->
+
+<!-- wp:columns {"align":"wide"} -->
+<div class="wp-block-columns alignwide"><!-- wp:column -->
+<div class="wp-block-column">
+<!-- wp:group {"style":{"border":{"width":"1px","radius":"8px"},"spacing":{"padding":{"top":"2rem","right":"2rem","bottom":"2rem","left":"2rem"}}},"layout":{"type":"constrained"}} -->
+<div class="wp-block-group" style="border-width:1px;border-radius:8px;padding-top:2rem;padding-right:2rem;padding-bottom:2rem;padding-left:2rem">
+<!-- wp:heading {"level":3,"textAlign":"center"} -->
+<h3 class="wp-block-heading has-text-align-center">Starter</h3>
+<!-- /wp:heading -->
+
+<!-- wp:heading {"textAlign":"center","fontSize":"x-large"} -->
+<h2 class="wp-block-heading has-text-align-center has-x-large-font-size">$19<span>/mo</span></h2>
+<!-- /wp:heading -->
+
+<!-- wp:list -->
+<ul class="wp-block-list"><!-- wp:list-item -->
+<li>1 site</li>
+<!-- /wp:list-item -->
+
+<!-- wp:list-item -->
+<li>Community support</li>
+<!-- /wp:list-item --></ul>
+<!-- /wp:list -->
+
+<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
+<div class="wp-block-buttons"><!-- wp:button -->
+<div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="#">Choose Starter</a></div>
+<!-- /wp:button --></div>
+<!-- /wp:buttons -->
+</div>
+<!-- /wp:group -->
+</div>
+<!-- /wp:column -->
+
+<!-- wp:column -->
+<div class="wp-block-column">
+<!-- duplicate the bordered group; vary name/price/features (e.g. "Pro", "$49/mo") -->
+</div>
+<!-- /wp:column -->
+
+<!-- wp:column -->
+<div class="wp-block-column">
+<!-- third plan (e.g. "Business", "$99/mo") -->
+</div>
+<!-- /wp:column --></div>
+<!-- /wp:columns -->
+</div>
+<!-- /wp:group -->
+```
+
+## Adapt
+
+- Fill real plan names, prices, and features from the user's request.
+- Highlight a "most popular" tier with a token background: add
+  `{"backgroundColor":"primary","textColor":"white"}` to that column's inner `group` (and the
+  matching `has-…` classes — let `validate_blocks` reconcile them).
+- 2 plans → two columns; 4 → consider two rows of `columns` or narrower columns.
+- Replace inline border/padding `style` with theme spacing/border tokens when
+  `get_theme_tokens()` exposes them.

package/skills/wordpress-blocks/references/tool-contract.md

@@ -0,0 +1,167 @@
+# Tool contract — the live site interface
+
+The static knowledge in this skill is generic. The **dynamic** half — *this* site's synced
+patterns, registered patterns, template parts, registered blocks, and theme tokens — lives in
+WordPress and changes per site and over time. It can't be a markdown file; the host (the Mantle
+plugin) must expose it as **tools** the model calls at request time.
+
+Design goals:
+- **Index, then fetch.** `search_patterns` returns lightweight rows (title/slug/categories/
+  excerpt) so the model can choose cheaply; `get_pattern` pulls full markup only for the one
+  it picks. Never dump every pattern's full markup into the prompt.
+- **Function-calling friendly.** Schemas below are JSON Schema, usable directly as OpenAI
+  `tools[].function.parameters`.
+
+Implementation notes (host side): synced patterns come from the `wp_block` CPT; registered
+patterns from `WP_Block_Patterns_Registry`; registered blocks from `WP_Block_Type_Registry`;
+template parts from the `wp_template_part` source; tokens from the active theme's `theme.json`
+(`wp_get_global_settings()`).
+
+---
+
+## `search_patterns`
+
+> Search the site's reusable assets (synced + registered patterns and template parts). Call
+> this FIRST for any layout/section request, before composing core blocks.
+
+```json
+{
+  "name": "search_patterns",
+  "description": "Search the site's synced patterns, registered patterns, and template parts by keyword. Returns lightweight matches; call get_pattern to retrieve full markup.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "query": { "type": "string", "description": "Keywords from the user's intent, e.g. 'pricing plans tiers'." },
+      "types": {
+        "type": "array",
+        "items": { "type": "string", "enum": ["synced", "registered", "template_part"] },
+        "description": "Optional filter. Default: all three."
+      },
+      "limit": { "type": "integer", "minimum": 1, "maximum": 25, "default": 8 }
+    },
+    "required": ["query"]
+  }
+}
+```
+
+**Returns:** `{ "matches": Match[] }`
+```json
+{
+  "matches": [
+    {
+      "title": "Pricing — 3 column",
+      "type": "synced",
+      "ref": 451,
+      "slug": null,
+      "categories": ["pricing", "featured"],
+      "excerpt": "Three plan cards with monthly price and CTA.",
+      "score": 0.92
+    },
+    {
+      "title": "Pricing table (registered)",
+      "type": "registered",
+      "ref": null,
+      "slug": "linchpin/pricing-3col",
+      "categories": ["pricing"],
+      "excerpt": "Theme-provided 3-tier layout.",
+      "score": 0.78
+    }
+  ]
+}
+```
+- `ref` is set for `synced` (the `wp_block` post ID → emit `wp:block {"ref":…}`).
+- `slug` is set for `registered` and `template_part`.
+
+## `get_pattern`
+
+> Fetch the full block markup for one match. For synced patterns prefer emitting the
+> reference block; only fetch expanded markup when detaching/editing a single instance.
+
+```json
+{
+  "name": "get_pattern",
+  "description": "Return the full block markup for one pattern or template part, by ref or slug.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "ref": { "type": "integer", "description": "wp_block post ID for a synced pattern." },
+      "slug": { "type": "string", "description": "Slug for a registered pattern or template part." }
+    },
+    "oneOf": [{ "required": ["ref"] }, { "required": ["slug"] }]
+  }
+}
+```
+**Returns:** `{ "title": string, "type": "synced"|"registered"|"template_part", "block_markup": string, "ref": int|null, "slug": string|null }`
+
+## `list_template_parts`
+
+```json
+{
+  "name": "list_template_parts",
+  "description": "List the active block theme's template parts (FSE). For template editing, not post body.",
+  "parameters": { "type": "object", "properties": {} }
+}
+```
+**Returns:** `{ "parts": [{ "slug": string, "title": string, "area": "header"|"footer"|"uncategorized"|string, "theme": string }] }`
+
+## `list_registered_blocks`
+
+> Confirm a non-core block actually exists on this install before referencing it.
+
+```json
+{
+  "name": "list_registered_blocks",
+  "description": "List blocks registered on this site. Filter by namespace to check availability of a specific block.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "namespace": { "type": "string", "description": "e.g. 'linchpin' or 'core'. Omit for all." }
+    }
+  }
+}
+```
+**Returns:** `{ "blocks": [{ "name": string, "title": string, "category": string, "supports_inner_blocks": boolean }] }`
+
+## `get_theme_tokens`
+
+> Pull theme.json design tokens so generated markup matches the site's design system.
+
+```json
+{
+  "name": "get_theme_tokens",
+  "description": "Return the active theme's design tokens (colors, gradients, font sizes, spacing, layout widths) from theme.json.",
+  "parameters": { "type": "object", "properties": {} }
+}
+```
+**Returns:**
+```json
+{
+  "colors": [{ "slug": "primary", "name": "Primary", "color": "#0b5fff" }],
+  "gradients": [{ "slug": "brand", "name": "Brand", "gradient": "linear-gradient(...)" }],
+  "font_sizes": [{ "slug": "large", "name": "Large", "size": "1.5rem" }],
+  "spacing": { "spacingSizes": [{ "slug": "40", "name": "Large", "size": "2rem" }] },
+  "layout": { "contentSize": "840px", "wideSize": "1200px" }
+}
+```
+
+## `validate_blocks` (required before insert)
+
+```json
+{
+  "name": "validate_blocks",
+  "description": "Parse block markup the way the editor does and report validity. Optionally return a normalized/repaired version.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "block_markup": { "type": "string" },
+      "autofix": { "type": "boolean", "default": true, "description": "Return a normalized version with corrected wrappers/classes where possible." }
+    },
+    "required": ["block_markup"]
+  }
+}
+```
+**Returns:** `{ "valid": boolean, "issues": [{ "block": string, "message": string }], "fixed_markup": string|null }`
+
+> The host already has block validators available (e.g. the WordPress Studio MCP
+> `validate_and_fix_blocks` / `validate_html_blocks` tools) — wire `validate_blocks` to one of
+> those rather than reimplementing the parser.

package/skills/wordpress-blocks/references/validation.md

@@ -0,0 +1,38 @@
+# Validation — always, before insert
+
+Block markup that *looks* right can still be rejected by the editor (a drifted wrapper class,
+a void/open mismatch, attribute JSON that doesn't match the saved HTML). A rejected block
+shows as *"This block contains unexpected or invalid content"* and the user loses the layout.
+So validation is not optional — it's the last step of every content generation.
+
+## The contract
+
+1. Generate the block markup (reused asset or composed core blocks).
+2. Call `validate_blocks({ block_markup, autofix: true })` (see `tool-contract.md`).
+3. Branch on the result:
+   - `valid: true` → insert the markup (use `fixed_markup` if present — it's normalized).
+   - `valid: false` → read `issues`, repair, and re-validate. Common repairs:
+     - void/open mismatch (`/-->` vs `-->`) — see `block-grammar.md`
+     - missing/wrong `wp-block-*` wrapper class or tag
+     - attribute JSON not matching generated classes (e.g. `textColor` set but `has-…-color`
+       class missing)
+     - a referenced block that isn't registered (`list_registered_blocks` to confirm) — drop
+       to a core-block equivalent
+   - Still invalid after a repair pass → **simplify**. Fall back to a plainer composition
+     (e.g. paragraphs + a single columns block) rather than shipping invalid markup. A simpler
+     layout that renders beats a fancy one that breaks.
+4. Never return un-validated markup to the editor, and never paper over failure with prose.
+
+## Why repair instead of guess
+
+Saved-HTML shapes drift across WordPress/Gutenberg versions, so the exact classes in this
+skill's examples won't be byte-perfect on every site. The validator reflects *this* site's
+actual block versions — trust it over hand-written markup. Prefer `fixed_markup` from the
+validator when it's offered; it's the site's own normalization of your intent.
+
+## Host wiring
+
+Point `validate_blocks` at a real WordPress parser so "valid" means what the editor means.
+The WordPress Studio MCP server exposes `validate_html_blocks` and `validate_and_fix_blocks`
+for exactly this; reuse one instead of writing a parser. The `autofix`/`fixed_markup` path
+maps to `validate_and_fix_blocks`.