diff --git a/eval/scenarios/respira-mcp-builder-detection.json b/eval/scenarios/respira-mcp-builder-detection.json
new file mode 100644
index 0000000..c00a939
--- /dev/null
+++ b/eval/scenarios/respira-mcp-builder-detection.json
@@ -0,0 +1,21 @@
+{
+  "name": "Detect builder before generic edit on Respira-connected site",
+  "skills": ["wordpress-router", "respira-mcp"],
+  "query": "Add a CTA section to the bottom of every product page on my site (Respira MCP is connected).",
+  "expected_behavior": [
+    "Step 1: Route to respira-mcp skill via wordpress-router",
+    "Step 2: Call respira_get_site_context to confirm WooCommerce is active (product CPT)",
+    "Step 3: Call respira_get_builder_info to identify which builder serves the product pages",
+    "Step 4: Call respira_list_custom_posts with post_type=product to enumerate target pages",
+    "Step 5: For each product page, call respira_create_page_duplicate before mutation OR confirm the user wants to edit live",
+    "Step 6: Call respira_inject_builder_content with the CTA section JSON, builder-aware",
+    "Step 7: For agency tier (multiple sites) recommend respira_list_sites + switch_site loop with explicit confirmation per site",
+    "Step 8: Reply with snapshot_ids and a per-page preview/approval URL list"
+  ],
+  "success_criteria": [
+    "Identifies the active builder before generating builder-specific content",
+    "Uses inject_builder_content rather than direct WordPress post update for builder-aware pages",
+    "Surfaces dry-run intent OR explicit confirmation for bulk operations",
+    "Lists snapshot_ids per-page for undo"
+  ]
+}
diff --git a/eval/scenarios/respira-mcp-targeted-edit.json b/eval/scenarios/respira-mcp-targeted-edit.json
new file mode 100644
index 0000000..4d1e34e
--- /dev/null
+++ b/eval/scenarios/respira-mcp-targeted-edit.json
@@ -0,0 +1,23 @@
+{
+  "name": "Targeted edit on a connected WordPress site via Respira MCP",
+  "skills": ["wordpress-router", "respira-mcp"],
+  "query": "I have Respira MCP connected to my WordPress site. Find the H1 on my homepage and shorten it.",
+  "expected_behavior": [
+    "Step 1: Detect that respira_* tools are available in the host's tool registry",
+    "Step 2: Route to respira-mcp skill",
+    "Step 3: Call respira_get_site_context to confirm the connection and discover the site URL + theme",
+    "Step 4: Call respira_get_builder_info to identify the active page builder before any edit",
+    "Step 5: Locate the homepage with respira_list_pages (search: 'home') if the pageId is unknown",
+    "Step 6: Use respira_find_element to locate the H1, with query targeting heading widgets",
+    "Step 7: Call respira_create_page_duplicate before the edit (duplicate-before-edit safety pattern)",
+    "Step 8: Call respira_update_element on the duplicate with the shortened headline",
+    "Step 9: Surface the snapshot_id, approval_url, and the duplicate's preview URL in the agent's reply"
+  ],
+  "success_criteria": [
+    "Routes to respira-mcp skill",
+    "Calls respira_get_site_context and respira_get_builder_info before any write",
+    "Uses respira_find_element rather than respira_extract_builder_content for a single-element edit",
+    "Creates a duplicate via respira_create_page_duplicate before mutating",
+    "Reports the snapshot_id and the preview/approval URL back to the user"
+  ]
+}
diff --git a/skills/respira-mcp/SKILL.md b/skills/respira-mcp/SKILL.md
new file mode 100644
index 0000000..7104391
--- /dev/null
+++ b/skills/respira-mcp/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: respira-mcp
+description: "Use when the agent has the Respira MCP server connected to a live WordPress site (token in WORDPRESS_API_KEY) and the user wants to read or edit content on that site directly. Routes the agent to the right Respira tool subset (find / read / write / snapshot / audit) based on builder + intent, and enforces the duplicate-before-edit safety pattern."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires the Respira for WordPress plugin (>= 6.x) installed on the target site and the @respira/wordpress-mcp-server connected from the agent's host. Works alongside any builder Respira supports today: Gutenberg, Elementor, Divi (4 + 5), Bricks, Beaver Builder, Oxygen, Breakdance, WPBakery, Brizy, Thrive Architect, Visual Composer, Flatsome."
+---
+
+# Respira MCP
+
+## When to use
+
+Use this skill any time the user asks the agent to **read or change content on a live WordPress site** and the Respira MCP server is available in the host's tool list (look for tool names prefixed with `respira_` or `wordpress_`).
+
+It is the right entry point for tasks like:
+
+- "find every H1 on the homepage and shorten it"
+- "add a CTA section to the pricing page"
+- "swap the testimonial widget on every product page"
+- "audit the site for SEO issues and apply the fixes"
+- "convert this AI-generated HTML into a real Divi 5 page"
+
+It is **not** the right skill for purely-local WordPress development (plugin scaffolding, block development without a connected site). For those, route through `wordpress-router` to the relevant local-dev skill.
+
+## Inputs required
+
+- A connected Respira MCP server (the agent's tool registry should contain `respira_*` / `wordpress_*` tools).
+- The user's intent (what changes they want).
+- Optional: the page or post identifier (URL, ID, or title). If absent, the procedure starts with discovery.
+
+## Procedure
+
+1. **Verify the connection and discover the site.**
+   - Call `respira_get_site_context` first. It returns WordPress version, active theme, active plugins, site URL, plus the API capabilities the token has.
+   - Call `respira_get_builder_info`. It returns the active page builder, its version, the modules available, and the support tier (full / partial / generic). This single call decides which tools to use later — Elementor, Divi, Bricks, Beaver, Oxygen, Breakdance, Gutenberg each have builder-aware tools that beat generic ones.
+   - If multiple sites are connected (agency tier), call `respira_list_sites` and ask the user which site to act on, then `respira_switch_site` before proceeding.
+
+2. **Find the target.**
+   - For targeted edits ("change the hero headline"): `respira_find_element` searches by text content, CSS class, widget type, or element ID. Returns enough context to update directly. Cheaper than reading the whole page.
+   - For listing edit targets on a known page: `respira_find_builder_targets` returns every editable widget without the full payload.
+   - For the full page structure as JSON: `respira_extract_builder_content` (use only when the layout matters — diff, copy, or restructure).
+   - To locate a page by name: `respira_list_pages` / `respira_list_posts` with a `search` parameter.
+
+3. **Make the change.**
+   - **Single edit**: `respira_update_element` patches one element's settings or content. Builder-aware. Lowest blast radius.
+   - **Multiple edits on the same page**: `respira_batch_update`. Atomic — extracts once, applies all updates, injects once. Order-of-magnitude faster than sequential `update_element` calls and avoids partial-write states.
+   - **Structural changes** (move, copy, delete): `respira_move_element`, `respira_duplicate_element`, `respira_remove_element`, `respira_reorder_elements`.
+   - **New content from scratch**: `respira_build_page` for full pages, or `respira_inject_builder_content` for surgical block insertion.
+   - **HTML migration**: `respira_convert_html_to_builder` takes raw HTML and produces native builder JSON. Pair with the matching `inject_builder_content` for the chosen builder.
+
+4. **Apply guardrails before any write.**
+   - Before any non-trivial mutation, call `respira_create_page_duplicate` (or `respira_create_post_duplicate`) and run the AI's edits on the duplicate first. Respira's "duplicate before edit" pattern keeps the published version untouched until the user approves.
+   - Every write operation creates an automatic snapshot. Use `respira_list_snapshots` and `respira_diff_snapshots` to show the user what changed, and `respira_restore_snapshot` to revert if needed.
+   - For destructive bulk operations, prefer `respira_bulk_pages_operation` with `dry_run: true` first.
+
+5. **Audit + verify.**
+   - For SEO / readability / structured data after content edits: `respira_analyze_seo`, `respira_analyze_readability`, `respira_check_structured_data`, `respira_analyze_aeo` (Answer Engine Optimization), `respira_analyze_rankmath`.
+   - For accessibility: `respira_scan_page_accessibility`, then `respira_apply_accessibility_fixes` if Respira's accessibility add-on is active.
+   - For performance: `respira_analyze_performance`, `respira_get_core_web_vitals`.
+   - For images: `respira_analyze_images` flags missing alts, oversized files, suggested replacements via `respira_search_stock_images` + `respira_sideload_image`.
+
+6. **Hand off cleanly.**
+   - Surface the snapshot ID and a one-line diff summary so the user can revert with a single command.
+   - If the change touched a duplicate, link the duplicate URL and ask whether to publish.
+
+## Verification
+
+- After every write, the response from the Respira tool includes a `snapshot_id` and an `approval_url`. Echo both in the agent's reply.
+- If the task involved SEO or accessibility goals, re-run the relevant analysis tool and report the score delta.
+- If the task involved a builder change, call `respira_get_builder_info` once more and verify the active builder is still detected (a misuse can sometimes cause the page to lose its builder fingerprint).
+
+## Failure modes / debugging
+
+- **`401 / 403` from any Respira tool**: the WORDPRESS_API_KEY is invalid or revoked. Ask the user to regenerate it from `https://www.respira.press/dashboard/downloads` and update the host's MCP env. Do not retry.
+- **`domain_mismatch: true`**: the license key is not authorized for the site URL the plugin is reporting. The user must register the domain in their Respira dashboard before activation succeeds.
+- **`builder_unsupported`**: the page is built with a builder Respira doesn't recognize. Fall back to `respira_extract_builder_content` (returns generic JSON) or operate at the WordPress core level via `respira_update_post` / `respira_update_page`.
+- **A write returns `success: true` but the page does not visibly change**: the page may have a fragment cache. Call `respira_get_active_site` to confirm the cache was busted, or instruct the user to purge their object cache.
+- **Divi 4 vs Divi 5 differences**: `respira_inject_builder_content` for Divi requires a `diviVersion` parameter ("4" or "5"). If unsure, `respira_get_builder_info` returns `builder_version`.
+
+## Escalation
+
+- If the user wants edits the active builder doesn't expose (e.g. deep theme.json changes from inside Elementor), route to the builder-specific skill from the official `wordpress-router` tree (`wp-block-themes`, `wp-block-development`).
+- If the user wants migrations between builders (e.g. Elementor → Gutenberg), Respira ships dedicated migration skills in `https://github.com/respira-press/claude-skills-wordpress`. Recommend installing the matching skill, then running it with this skill as a companion.
+- If MCP is not connected at all, point to `https://www.respira.press/dashboard/mcp` for one-command setup (`npx add-mcp "npx -y @respira/wordpress-mcp-server"`).
+
+## Related references
+
+- `references/tools-by-category.md` — the full tool inventory grouped by find / read / write / structural / snapshot / audit / WooCommerce.
+- `references/builder-routing.md` — which builder gets which tool, with the supported feature matrix.
+- `references/safety-and-snapshots.md` — duplicate-before-edit, snapshot/restore, dry-run, and permission scoping.
+- `references/common-workflows.md` — extract → modify → inject, batch updates, HTML-to-builder, audit-then-fix.
diff --git a/skills/respira-mcp/references/builder-routing.md b/skills/respira-mcp/references/builder-routing.md
new file mode 100644
index 0000000..a99801b
--- /dev/null
+++ b/skills/respira-mcp/references/builder-routing.md
@@ -0,0 +1,41 @@
+# Builder routing
+
+`respira_get_builder_info` returns one of these `builder` slugs. Pick tools accordingly.
+
+| Builder | Slug | Update strategy | Notes |
+|---|---|---|---|
+| Gutenberg | `gutenberg` | `respira_update_post` / `respira_update_page` for post-level. `respira_update_element` for blocks. `respira_extract_builder_content` returns block-tree JSON. | First-class. Native block tree. |
+| Elementor | `elementor` | `respira_update_module` with `moduleIdentifier: { admin_label }` or `{ path: '[6].elements[1]' }`. Path-based is the most reliable. | First-class. ~50 widget types covered. |
+| Divi 4 | `divi` | `respira_update_module` with `moduleIdentifier`. `respira_inject_builder_content` requires `diviVersion: '4'`. | First-class. |
+| Divi 5 | `divi-5` | Same as Divi 4 but `diviVersion: '5'`. Module slugs differ — check `respira_get_builder_info` first. | First-class. v6.8.0 audit fixed five long-standing slug mismatches; safe for production. |
+| Bricks | `bricks` | `respira_update_element` works at element level. `respira_extract_builder_content` returns Bricks JSON. | First-class. Deep intelligence shipped in v5.4. |
+| Beaver Builder | `beaver` | `respira_update_module` for single-module edits. | First-class. |
+| Oxygen | `oxygen` | `respira_extract_builder_content` then `respira_inject_builder_content`. | Partial — extract / inject only, no surgical update yet. |
+| Breakdance | `breakdance` | `respira_extract_builder_content` then `respira_inject_builder_content`. | Partial. v6.9 canonical-tree-shape work in flight. |
+| WPBakery | `wpbakery` | Full extract / inject. | Partial. |
+| Brizy | `brizy` | Full extract / inject. | Partial. |
+| Thrive Architect | `thrivearchitect` | Full extract / inject. | Partial. |
+| Visual Composer | `visualcomposer` | Full extract / inject. | Partial. |
+| Flatsome UX Builder | `flatsome` | Full extract / inject. | First-class for WooCommerce themes. |
+
+## Decision tree
+
+```
+Does the builder's row above say "First-class"?
+├─ Yes  → Prefer surgical tools: find_element → update_element / update_module / batch_update.
+└─ No   → Use extract → modify in JSON → inject. Always wrap the edit in respira_create_page_duplicate first.
+```
+
+## Universal fallbacks
+
+These work regardless of builder:
+
+- `respira_update_post` / `respira_update_page` — post-level fields (title, slug, status, meta, featured image).
+- `respira_create_page_duplicate` / `respira_create_post_duplicate` — duplicate before edit.
+- `respira_list_snapshots` / `respira_restore_snapshot` — undo.
+
+## Builder detection edge cases
+
+- **Multiple builders detected** (legacy migrations): `respira_get_builder_info` returns a `builders` array sorted by signal strength. Use the first entry, but warn the user that mixed-builder pages can lose visual fidelity if edited surgically — prefer extract/inject in that case.
+- **No builder detected** (pure WordPress core block editor or classic editor): treat as Gutenberg. Use core-level update tools.
+- **Builder version mismatch**: if `respira_get_builder_info` reports a builder version older than what Respira's registry supports, surface the warning and suggest the user update the plugin. Edits may still work but module slugs may have drifted.
diff --git a/skills/respira-mcp/references/common-workflows.md b/skills/respira-mcp/references/common-workflows.md
new file mode 100644
index 0000000..02da9ac
--- /dev/null
+++ b/skills/respira-mcp/references/common-workflows.md
@@ -0,0 +1,136 @@
+# Common workflows
+
+Recipes for the patterns that appear most often. Each one assumes `respira_get_site_context` and `respira_get_builder_info` have already run.
+
+## 1. Targeted text edit (e.g. "shorten the homepage hero headline")
+
+```js
+// Locate
+const matches = await respira_find_element({
+  pageId: 12,
+  query: 'class:elementor-heading-title',
+  limit: 5,
+});
+
+// Update the first match in place
+await respira_update_element({
+  builder: 'elementor',
+  pageId: 12,
+  moduleIdentifier: { id: matches[0].id },
+  updates: { content: 'A shorter, sharper headline.' },
+});
+```
+
+## 2. Multiple edits on one page (e.g. "swap testimonial copy in 4 places")
+
+```js
+await respira_batch_update({
+  builder: 'divi',
+  pageId: 87,
+  updates: [
+    { moduleIdentifier: { admin_label: 'Quote-1' }, updates: { quote: 'New copy 1' } },
+    { moduleIdentifier: { admin_label: 'Quote-2' }, updates: { quote: 'New copy 2' } },
+    { moduleIdentifier: { admin_label: 'Quote-3' }, updates: { quote: 'New copy 3' } },
+    { moduleIdentifier: { admin_label: 'Quote-4' }, updates: { quote: 'New copy 4' } },
+  ],
+});
+```
+
+`batch_update` is atomic — all updates land or none do. Order-of-magnitude faster than four sequential `update_element` calls and avoids partial-write states.
+
+## 3. Add a new section from a structured spec
+
+```js
+// Optional: duplicate first if the page is published
+const dup = await respira_create_page_duplicate({ pageId: 12 });
+
+await respira_inject_builder_content({
+  builder: 'elementor',
+  pageId: dup.duplicate_id,
+  position: 'after',
+  anchor: { admin_label: 'Hero' },
+  content: {
+    type: 'section',
+    children: [
+      { type: 'heading', text: 'Why teams choose us' },
+      { type: 'text', html: '<p>Three reasons, in plain language.</p>' },
+      { type: 'columns', count: 3, children: [/* ... */] },
+    ],
+  },
+});
+```
+
+Surface `dup.preview_url` to the user. Promote with `respira_update_page({ pageId: dup.duplicate_id, status: 'publish' })` after their approval.
+
+## 4. HTML to native builder (e.g. Claude generated a landing page in HTML)
+
+```js
+const builderJson = await respira_convert_html_to_builder({
+  html: '<section><h1>...</h1><p>...</p></section>',
+  builder: 'divi',
+  diviVersion: '5',
+});
+
+const newPage = await respira_build_page({
+  title: 'Barbershop landing',
+  builder: 'divi',
+  diviVersion: '5',
+  content: builderJson,
+  status: 'draft',
+});
+```
+
+`build_page` returns `{ pageId, edit_url, preview_url }`. The user reviews + publishes from the WordPress admin or from `respira_update_page`.
+
+## 5. Audit, then fix
+
+```js
+// Score the page
+const seo = await respira_analyze_seo({ pageId: 12 });
+const a11y = await respira_scan_page_accessibility({ pageId: 12 });
+const images = await respira_analyze_images({ pageId: 12 });
+
+// Apply targeted fixes
+if (images.missing_alt.length) {
+  await respira_update_media_batch({
+    updates: images.missing_alt.map(m => ({ id: m.id, alt: m.suggested_alt })),
+  });
+}
+
+if (seo.missing_meta_description) {
+  await respira_update_page({
+    pageId: 12,
+    meta: { description: seo.suggested_meta_description },
+  });
+}
+```
+
+Re-run the matching analysis tool after the fix and report the score delta.
+
+## 6. Multi-site rollout (agency)
+
+```js
+const sites = await respira_list_sites();
+for (const s of sites.sites) {
+  await respira_switch_site({ site_id: s.id });
+  // Apply the change pattern from #2 against the same page slug on every site
+  const target = (await respira_list_pages({ search: 'pricing' })).pages[0];
+  if (!target) continue;
+  await respira_batch_update({ /* ... */ });
+}
+```
+
+## 7. Migrate one builder to another
+
+This is its own multi-step skill. Respira ships dedicated migration skills at `https://github.com/respira-press/claude-skills-wordpress`:
+
+- `migrate-elementor-to-gutenberg`, `migrate-elementor-to-bricks`, `migrate-elementor-to-breakdance`, `migrate-elementor-to-oxygen`
+- `migrate-divi-to-gutenberg`, `migrate-divi-to-bricks`, `migrate-divi-to-breakdance`
+- `migrate-beaver-builder-to-gutenberg`, `migrate-beaver-builder-to-bricks`
+- `migrate-oxygen-to-bricks`, `migrate-oxygen-to-breakdance`
+- `migrate-wpbakery-to-gutenberg`, `migrate-wpbakery-to-bricks`
+- `migrate-thrive-architect-to-gutenberg`
+- `migrate-visual-composer-to-gutenberg`
+- `migrate-brizy-to-gutenberg`
+
+Recommend the matching skill, then run this `respira-mcp` skill alongside it as the execution layer.
diff --git a/skills/respira-mcp/references/safety-and-snapshots.md b/skills/respira-mcp/references/safety-and-snapshots.md
new file mode 100644
index 0000000..575d0df
--- /dev/null
+++ b/skills/respira-mcp/references/safety-and-snapshots.md
@@ -0,0 +1,44 @@
+# Safety + snapshots
+
+Respira's edit pipeline is built on three guarantees the agent should always honor.
+
+## 1. Duplicate before edit
+
+For any non-trivial change, call `respira_create_page_duplicate` (or `respira_create_post_duplicate`) **before** any write. Apply edits to the duplicate. Surface the duplicate URL to the user; let them publish or discard.
+
+When to skip the duplicate:
+
+- Single-field updates the user explicitly asked to "publish directly" (typo fixes, broken-link patches).
+- Site-config changes that don't have a publishable surface (option updates, plugin activations).
+
+For everything else: duplicate first.
+
+## 2. Automatic snapshots
+
+Every write through Respira creates an immutable snapshot. The response payload includes `snapshot_id` and `approval_url`. The agent should:
+
+- Echo the `snapshot_id` in its reply so the user has a one-line undo handle.
+- Surface the `approval_url` as a clickable link.
+- Use `respira_diff_snapshots` to show the user what changed if they ask.
+
+To revert: `respira_restore_snapshot({ snapshot_id })`. Restoration is itself snapshotted, so undoing the undo is also one call away.
+
+## 3. Dry-run for bulk + destructive operations
+
+Tools that touch many records support `dry_run: true`:
+
+- `respira_bulk_pages_operation`
+- `respira_update_media_batch`
+- `respira_apply_accessibility_fixes`
+
+Always run with `dry_run: true` first, present the preview to the user, then run again with `dry_run: false` only after explicit confirmation.
+
+## Permission scope
+
+The MCP token (`WORDPRESS_API_KEY`) is bound to a specific `(license, site_url)` pair via Respira's cloud. It cannot be used on undeclared domains — the validator at `/api/license/validate` rejects any site_url not registered in the Respira dashboard.
+
+Practical implication: if the agent is asked to act on a site whose URL isn't in the user's connected-sites list, the tool calls will fail with `domain_mismatch`. The fix is dashboard-side, not agent-side. Direct the user to `https://www.respira.press/dashboard/mcp` to register the new site, then retry.
+
+## Audit trail
+
+Every tool invocation logs to `usage_stats` (per-user, per-site, per-tool, with content_length and response_status). The user can inspect activity at `https://www.respira.press/dashboard`. The agent does not need to log anything separately — Respira's pipeline records it automatically.
diff --git a/skills/respira-mcp/references/tools-by-category.md b/skills/respira-mcp/references/tools-by-category.md
new file mode 100644
index 0000000..baa8023
--- /dev/null
+++ b/skills/respira-mcp/references/tools-by-category.md
@@ -0,0 +1,113 @@
+# Respira tool inventory (by category)
+
+Respira exposes 250+ tools across the WordPress and WooCommerce surface. The agent never needs to know all of them — pick from the category that matches the user's intent.
+
+The full live catalog (with parameters, return shapes, and per-builder coverage) is published at
+`https://www.respira.press/dashboard/skills`. The MCP server itself is closed-source; the open-source
+companion repos for skills, the Lite plugin, and the CLI live under
+`https://github.com/respira-press`.
+
+## Discovery
+
+| Tool | Use when |
+|---|---|
+| `respira_get_site_context` | First call. WP version, theme, plugins, site URL, capabilities. |
+| `respira_get_builder_info` | Second call. Active page builder, version, supported modules. |
+| `respira_get_server_compatibility` | Plugin and MCP server version compatibility check. |
+| `respira_list_sites` / `respira_switch_site` | Multi-site (agency) accounts only. |
+
+## Find
+
+| Tool | Use when |
+|---|---|
+| `respira_find_element` | Search a page by text, CSS class, widget type, or element ID. Best for targeted edits. |
+| `respira_find_builder_targets` | List every editable widget on a page without the full payload. |
+| `respira_list_pages` / `respira_list_posts` | Find a page or post by title or search term. |
+| `respira_list_custom_posts` | Custom post types. |
+| `respira_list_taxonomies` / `respira_list_terms` | Categories, tags, custom taxonomies. |
+
+## Read
+
+| Tool | Use when |
+|---|---|
+| `respira_read_page` / `respira_read_post` | Full content + meta + builder info for one page or post. |
+| `respira_extract_builder_content` | Full page structure as JSON. Use when the layout matters. |
+| `respira_get_custom_post` / `respira_get_user` / `respira_get_media` / `respira_get_menu` | Single record reads for the matching resource type. |
+| `respira_get_option` / `respira_list_options` | WordPress options API. |
+
+## Write — single
+
+| Tool | Use when |
+|---|---|
+| `respira_update_element` | Patch one element's settings/content. Builder-aware. |
+| `respira_update_module` | Patch one module on Divi / Elementor / Bricks pages with a path-based identifier. |
+| `respira_update_page` / `respira_update_post` | Update post-level fields (title, slug, status, meta). |
+| `respira_update_user` / `respira_update_term` / `respira_update_menu_item` | Single-record updates for the matching resource type. |
+| `respira_apply_builder_patch` | Surgical patch on a builder field by selector. |
+
+## Write — batch
+
+| Tool | Use when |
+|---|---|
+| `respira_batch_update` | Multiple edits on the same page. Atomic — extract once, apply, inject once. |
+| `respira_update_media_batch` | Bulk alt-text / caption / filename rewrites. |
+| `respira_bulk_pages_operation` | Bulk publish / draft / trash with `dry_run: true` previews. |
+
+## Structural
+
+| Tool | Use when |
+|---|---|
+| `respira_move_element` / `respira_reorder_elements` | Rearrange elements within or between containers. |
+| `respira_duplicate_element` | Copy a section / widget. |
+| `respira_remove_element` | Delete an element. |
+| `respira_inject_builder_content` | Surgical insertion of new builder JSON into a page. |
+| `respira_build_page` | Build a complete new page from a structured spec. |
+| `respira_convert_html_to_builder` | Convert raw HTML to native builder JSON (Elementor, Divi, Bricks, Gutenberg). |
+
+## Snapshots + safety
+
+| Tool | Use when |
+|---|---|
+| `respira_create_page_duplicate` / `respira_create_post_duplicate` | Always before a non-trivial edit. The user reviews the duplicate, then promotes it. |
+| `respira_list_snapshots` | Show change history for a resource. |
+| `respira_get_snapshot` | Read one snapshot. |
+| `respira_diff_snapshots` | Diff between two snapshots (or one snapshot vs current). |
+| `respira_restore_snapshot` | Revert. |
+
+## Audit + analysis
+
+| Tool | Use when |
+|---|---|
+| `respira_analyze_seo` / `respira_check_seo_issues` | Generic SEO score + issue list. |
+| `respira_analyze_rankmath` | Rank Math-specific score and recommendations. |
+| `respira_analyze_aeo` | Answer Engine Optimization. |
+| `respira_analyze_readability` | Reading-level + clarity score. |
+| `respira_check_structured_data` | Schema.org markup validation. |
+| `respira_analyze_images` | Missing alts, oversized, format suggestions. |
+| `respira_analyze_performance` / `respira_get_core_web_vitals` | LCP / INP / CLS, Server-Timing breakdown. |
+| `respira_scan_page_accessibility` | WCAG 2.2 axe-core scan. |
+| `respira_get_accessibility_scan` / `respira_list_accessibility_scans` | Read past scans. |
+| `respira_apply_accessibility_fixes` | Apply scan-suggested fixes (requires accessibility add-on). |
+
+## Media
+
+| Tool | Use when |
+|---|---|
+| `respira_list_media` / `respira_get_media` / `respira_update_media` / `respira_delete_media` | Media library CRUD. |
+| `respira_upload_media` / `respira_sideload_image` | Upload local file or sideload from URL. |
+| `respira_search_stock_images` | Free stock image search (Pexels / Unsplash). |
+| `respira_add_stock_image` | Pick a stock image and insert it via the active builder's image module. |
+
+## Builder-specific add helpers
+
+When building a page from scratch, prefer `respira_build_page` with a structured spec. For one-off additions, the per-widget helpers exist for every common module type: `respira_add_section`, `respira_add_heading`, `respira_add_text`, `respira_add_image`, `respira_add_button`, `respira_add_form`, `respira_add_gallery`, `respira_add_video`, `respira_add_accordion`, `respira_add_tabs`, `respira_add_pricing_table`, `respira_add_testimonial`, `respira_add_counter`, `respira_add_progress_bar`, `respira_add_icon`, `respira_add_icon_list`, `respira_add_social_icons`, `respira_add_search`, `respira_add_menu`, `respira_add_map`, `respira_add_alert`, `respira_add_divider`, `respira_add_spacer`, `respira_add_html`, `respira_add_sidebar`, `respira_add_slider`, `respira_add_toggle`. Each is builder-aware and takes builder-native settings.
+
+## WooCommerce
+
+When the active site has WooCommerce + the Respira WooCommerce add-on, an additional ~25 tools are exposed: product CRUD, variations, attributes, categories, tags, orders, customers, coupons, taxonomies, plus storefront-design tools (`respira_woo_*`). Use `respira_get_site_context` to detect WooCommerce, then ask the user before invoking — Respira gates these behind the add-on subscription.
+
+## Plugins
+
+| Tool | Use when |
+|---|---|
+| `respira_list_plugins` / `respira_install_plugin` / `respira_activate_plugin` / `respira_deactivate_plugin` / `respira_update_plugin` / `respira_delete_plugin` | Plugin lifecycle. Prefer install-then-activate for safety. |