@respira/wordpress-mcp-server 6.19.10 → 7.1.0

package/skills/respira-builder-edits/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: respira-builder-edits
+description: Use for any in-page content edit on a WordPress site with a page builder. Covers finding elements, applying surgical edits, duplicating before large changes, and verifying the result. Works across Elementor 3 + 4, Divi 4 + 5, Beaver Builder, Bricks, Oxygen Classic, Oxygen 6, Breakdance, WPBakery, Uncode, and Gutenberg.
+metadata:
+  short-description: Safe, builder-native in-page editing across all supported builders
+  version: 1.2.0
+  updated_at: 2026-05-17
+  respira_min_version: 7.1.0
+---
+
+# Respira Builder Edits
+
+## Common Mistakes
+
+| Mistake | Correct approach |
+|---|---|
+| Using `respira_update_page` to change a heading, image, or button | Use `respira_find_element` then `respira_update_element`. The page tool replaces the whole body and the builder loses every node. |
+| Calling `respira_update_page` without checking `respira_get_builder_info` | Always identify the builder first. Update_page destroys builder JSON on builder-managed pages. |
+| Editing raw builder JSON by guessing field names | Read the current structure with `respira_read_page`, `respira_find_element`, or `respira_get_builder_inline_schemas` before writing. |
+| Making large changes without a snapshot | Always call `respira_create_page_duplicate` before multi-element edits. |
+| Assuming Divi 5 uses the same field as Divi 4 | Divi 4 stores shortcodes in `post_content`. Divi 5 stores blocks plus a per-node `attrs._nodeId` minted by the complexifier. By-id matching needs the `_nodeId` fallback (added in v7.0.30). |
+| Passing nested Divi 5 payloads through `children` only | Divi 5 also accepts Divi-vocabulary aliases `rows / cols / modules` (folded in v7.0.32). Pre-v7.0.32 these silently dropped. |
+| Using a non-existent Beaver Builder module type | The `content_field_map` covers Heading, Text, Button, Image, HTML, Video, Sidebar, and Box (added in v7.0.13). Unknown types fall through without an error. |
+| Passing flat `updates` like `{"button_text": "Go"}` | Pass either flat OR `{settings: {button_text: "Go"}}`. v7.0.16 deep-merges both into the settings object. v7.0.19 extended this through Divi 4. v7.0.29 extended it through `update_module` and `apply_builder_patch`. |
+| Skipping `respira_get_page_outline` for "what is on this page" reads | The outline is lighter than `extract_builder_content` and ships per-row child counts plus a primary heading. Use it before deciding which element to edit. |
+
+## Inputs
+
+- The page or post URL, ID, or slug.
+- A description of what to change (text, image URL, color, style, link).
+- The builder in use, or unknown. Auto-detect with `respira_get_builder_info`.
+
+## Workflow
+
+1. **Understand the site.** Call `respira_get_site_context` and `respira_get_builder_info` if you haven't already.
+2. **Understand the page.** Call `respira_get_page_outline` for a fast structural read, or `respira_find_element` if you already know what to target.
+3. **Create a snapshot.** `respira_create_page_duplicate` before any edit that touches more than one element or that you're not 100% sure of.
+4. **Find the element.** `respira_find_element` with the most specific selector available: text content, CSS class, widget type, or element ID. Bricks 2.3.x + Divi 5 surface both `id` and `attrs._nodeId`; either works.
+5. **Apply the edit.** `respira_update_element` with only the fields that change. For multi-element edits on the same page, prefer `respira_batch_update`.
+6. **Verify.** Re-read the element and confirm the change is reflected. For Divi 5, also check the front-end if it's a CSS or style-driven change because the renderer has its own paths.
+7. **Report.** Tell the user what changed and where.
+
+## Builder-specific notes
+
+- **Elementor 3.** Content lives in `_elementor_data`. Each widget has `id`, `widgetType`, and `settings`. The base path is mature.
+- **Elementor 4 (Atomic Elements).** v7.1 added end-to-end write support across 9 atomic widgets (`e-heading`, `e-paragraph`, `e-button`, `e-image`, `e-svg`, `e-divider`, `e-youtube`, `e-self-hosted-video`, `e-component`) plus 11 atomic layout containers (`e-flexbox`, `e-div-block`, `e-grid`, the `e-tabs` family, the `e-form` family). Pre-v7.1 every atomic write returned 422 `respira_elementor_atomic_write_unsupported`. The v4 normaliser lifts shorthand to the canonical `$$type` envelopes; the v4 validator catches malformed nodes before they hit the DB. Unsupported atomic types still refuse fast with `supported_widgets` in the error body.
+- **Divi 4.** Shortcodes in `post_content`. v7.0.19 + v7.0.29 fixed update_element, batch_update, apply_builder_patch, remove_element, inject_builder_content, and update_module. The kses bypass survives so `<script>` and `<style>` inside `et_pb_code` are preserved. Custom post types are supported.
+- **Divi 5.** Blocks plus `attrs._nodeId`. v7.0.16 fixed the background overlay key (`overlay.enable` is what the renderer reads). v7.0.28 fixed the number-counter typed envelope and the button text colour dual-write. v7.0.30 added the `_nodeId` fallback for id matching. v7.0.32 added the children-aliases fold (`rows`, `cols`, `modules`) plus a hard-error on silent child drops.
+- **Beaver Builder.** v7.0.13 added Box module mappings. v7.0.16 fixed typed-node normalisation (`{type:'row', columns:[…]}`). v7.0.17 defaults missing column `size` to "100" so columns render full-width when the agent omits it. v7.0.25 fixed the top-level font-field stdClass fatal. v7.0.26 expanded that to typography containers. Custom HTML in modules survives the kses bypass.
+- **Bricks.** v7.0.23 fixed page-settings deep-merge and the CSS regen API. v7.0.24 closed the file-mode CSS regen gap. v7.0.26 fixed global-class id resolution and the `EDITABLE` route collision that was clobbering the registry. v7.0.27 unified settings normalisation: null deletes, `_background.color` and `_color` string lift to `{hex, raw}`, typography keys migrate into `_typography`, `_gap` fans out to `_columnGap` + `_rowGap`.
+- **Oxygen Classic.** v7.0.18 added the root-wrapped `_ct_builder_json` shape (`{id:0, name:"root", depth:0, children:[…]}`). Legacy bare-array pages self-heal on next read. v7.0.17 wraps inject in `try/catch \Throwable` so third-party plugins hooked into `oxy_save_ct_builder_json_meta` no longer fatal the REST request.
+- **Oxygen 6.** Storage is `_oxygen_data`, a different format from Classic. v7.0.7 brought deep-intelligence parity.
+- **Breakdance.** v7.0.20 added `resolve_breakdance_properties()` for every shape an agent emits. v7.0.21 added `nest_breakdance_content_section()` for the 15 element types whose renderer reads `content.content.*`. v7.0.22 fixed append unwrap and the replace-confirmation gate.
+- **WPBakery + Uncode.** v7.0.31 added the Uncode adapter pack (`uncode_*` and `tdb_*` shortcodes as first-class elements), pagination on `find_builder_targets`, populated labels via decoded content-bearing attrs, and `respira_get_page_outline` plus `respira_get_builder_inline_schemas`. Filterable via `respira_wpbakery_shortcode_prefixes` for site-specific extensions.
+
+## Rules
+
+- Never use `respira_update_page` for content edits. It replaces the entire page body and the builder treats the result as a single text blob.
+- Never guess builder JSON field names. Read first, then write.
+- Always run `respira_get_site_context` plus `respira_get_builder_info` before the first edit on a page you haven't touched in the current session.
+- For Divi 5, when matching by id, expect both `id` and `attrs._nodeId` to resolve.
+- For Bricks file-mode CSS (cssLoading=file), v7.0.24 primes the front-end state so per-element rules emit correctly. No workaround needed.
+- When the builder is unknown, call `respira_get_builder_info` and wait for confirmation before editing.
+
+## Verification
+
+After every edit:
+
+1. Call `respira_find_element` with the same selector used before the edit.
+2. Confirm the changed field matches the intended value.
+3. If the element is not found or unchanged, check whether `respira_update_element` returned an error or a structured soft-fail.
+
+For batch edits:
+
+1. Use `respira_diff_snapshots` to compare the before / after snapshot.
+2. Confirm all changed elements are reflected; flag any that are missing.
+
+## Escalation
+
+Stop and ask the user if:
+
+- `respira_get_builder_info` returns an unknown or unsupported builder.
+- `respira_update_element` returns a soft-fail on a Bricks, Oxygen, or Breakdance element after the v7.0.x fixes have been applied.
+- The page is protected by a WAF or security plugin that blocks the REST endpoint. `respira_diagnose_connection` detects Cloudflare-edge write blocks.
+- The edit would touch more than 20 elements. Confirm scope before proceeding.
+
+## Example
+
+Goal: change the hero heading text from "Welcome" to "Get started today."
+
+```
+1. respira_get_builder_info        → Elementor 3.21, supported
+2. respira_get_page_outline        → 4 sections, hero is row 0, primary heading "Welcome"
+3. respira_create_page_duplicate   → snapshot ID abc123
+4. respira_find_element            → selector: text="Welcome", type: heading
+   Result: element ID e7a2, widgetType: heading, settings.title: "Welcome"
+5. respira_update_element          → element ID e7a2, settings.title: "Get started today."
+6. respira_find_element            → element ID e7a2
+   Result: settings.title: "Get started today." ✓
+```

package/skills/respira-setup/SKILL.md

@@ -1,23 +1,28 @@
 ---
 name: respira-setup
-description: Use when setting up, checking, or repairing Respira for WordPress MCP in Codex, including dashboard install commands, Codex config checks, connection diagnostics, and safe first WordPress actions.
+description: Use when setting up, checking, or repairing Respira for WordPress MCP in Codex or Claude Code. Covers dashboard install commands, config checks, connection diagnostics, edge-layer write blocks, version mismatches, and safe first WordPress actions.
 metadata:
   short-description: Set up and diagnose Respira WordPress MCP
+  version: 1.2.0
+  updated_at: 2026-05-17
+  respira_min_version: 7.1.0
 ---
 
 # Respira Setup
 
-Use this skill when the user wants to install Respira for WordPress in Codex, check whether the MCP server is connected, diagnose errors, or start safe WordPress work through Respira.
+Use this skill when the user wants to install Respira for WordPress in Codex or Claude Code, check whether the MCP server is connected, diagnose errors, or start safe WordPress work through Respira.
 
 ## Setup Workflow
 
 1. Send the user to `https://www.respira.press/dashboard/mcp`.
-2. Tell them to select the intended access scope, then click `Install in Codex`.
+2. Tell them to select the intended access scope, then click `Install in Codex` or `Install in Claude Code`.
 3. Have them paste the copied command into Terminal.
-4. Ask them to restart Codex so the updated `~/.codex/config.toml` is loaded.
-5. Verify with `codex mcp list` when shell access is available.
+4. Ask them to restart the agent so the updated MCP config is loaded.
+5. Verify with `codex mcp list` or `claude mcp list` when shell access is available.
 
-Prefer the dashboard install command over manual TOML. It mints a short-lived token, preserves existing Codex MCP servers, and writes the `respira-wordpress` entry with the selected scope.
+The dashboard installer mints a short-lived token, preserves existing MCP servers in the config, and writes the `respira-wordpress` entry with the selected scope. Prefer it over manual TOML or JSON edits.
+
+For first-time WordPress plugin activation, the v7.1 default is the OAuth flow: the plugin's Setup screen offers `Connect respira.press account` which links the licence to the user's respira.press account so plan changes sync automatically. Manual licence-key paste stays available as a secondary link.
 
 ## Diagnostics
 
@@ -27,28 +32,41 @@ When shell access is available, run:
 npx -y @respira/wordpress-mcp-server@latest --doctor --json
 ```
 
+The doctor runs 9 checks in one pass: Node.js version, MCP config, connectivity, plugin version, API negotiation, npm update availability, version compatibility, edge-layer write blocks, and REST endpoint health.
+
 If the MCP tools are already available, call:
 
-- `respira_get_server_compatibility`
-- `respira_get_site_context`
+- `respira_diagnose_connection` returns a structured report including Cloudflare-edge "Bad Bot" write-block detection (added v7.0.16). Surface the CF allow-list snippet directly when the probe finds the pattern.
+- `respira_get_server_compatibility` returns plugin version, MCP server version, minimum-MCP requirement, and a compatibility verdict.
+- `respira_get_site_context` returns WordPress version, PHP version, active builder, active plugins, and theme.
 
 Use the results to report plugin version, MCP server version, API key status, WordPress version, PHP version, and whether the connection is ready.
 
 ## Common Fixes
 
-- No `respira-wordpress` MCP server: repeat the dashboard `Install in Codex` flow and restart Codex.
-- `401` or `Unauthorized`: create a fresh API key in WordPress under `Respira -> API Keys`, then rerun the dashboard installer.
-- `403` or REST API blocked: whitelist `/wp-json/respira/v1/` in the host, WAF, or security plugin.
+- No `respira-wordpress` MCP server in `mcp list`: repeat the dashboard `Install in...` flow and restart the agent.
+- `401` or `Unauthorized`: create a fresh API key in WordPress under `Respira > Settings > API Keys`, then rerun the dashboard installer. Older sites may still show `Respira > API Keys` as a top-level menu.
+- `403` or REST API blocked: whitelist `/wp-json/respira/v1/` in the host, WAF, or security plugin. `respira_diagnose_connection` flags this with a structured hint.
+- Cloudflare edge write block: the diagnose tool detects when `GET /wp-json/respira/v1/ping` succeeds but `OPTIONS` is blocked. The fix is a CF rule that allows PUT, PATCH, DELETE, and OPTIONS on the Respira REST namespace.
 - Timeout or fetch failure: confirm the site URL is reachable and that `https://example.com/wp-json/` returns JSON.
-- Version mismatch: update the WordPress plugin and rerun `npx -y @respira/wordpress-mcp-server@latest --doctor --json`.
+- Version mismatch: update the WordPress plugin to the latest available, then rerun the doctor. v7.1 requires MCP server 6.11.0 or later; the doctor reports the actual requirement.
+- `MCP server self-reports v6.11.4 after upgrade`: this was a stale-constant bug fixed in MCP v6.11.13. Update with `npm install -g @respira/wordpress-mcp-server@latest`.
+
+## Bundled skills
+
+Respira v7.1 ships its skills inside the Claude Code plugin at `respira-press/respira-wordpress`. The skill bundle covers builder edits, this setup flow, site audits, and WooCommerce operations. Two ways to get them:
+
+- **Claude Code plugin install** (recommended): pulls the skills plus the MCP config plus the AGENTS.md briefing in one step.
+- **npm command**: `npx @respira/wordpress-mcp-server install-skills` copies bundled `SKILL.md` files into `~/.claude/skills/` for users who manage their MCP config manually.
 
 ## Safe First Actions
 
-After setup succeeds, suggest low-risk checks before edits:
+After setup succeeds, suggest low-risk checks before any edit:
 
-- List pages or posts.
-- Inspect the active theme, plugins, and page builder.
-- Create or duplicate a draft before editing production content.
-- Use Respira snapshot and rollback tools before large changes.
+- List pages or posts to confirm the connection works end to end.
+- Inspect the active theme, plugins, and page builder via `respira_get_site_context` and `respira_get_builder_info`.
+- Create or duplicate a draft before editing production content. `respira_create_page_duplicate` is the canonical entry point.
+- Use `respira_get_page_outline` for a fast structural read before deciding what to edit.
+- Snapshot any page about to take more than one element change.
 
-Never ask the user to paste API keys into chat. Use the dashboard installer or local setup command for secrets.
+Never ask the user to paste API keys into chat. Use the dashboard installer for secrets.

package/skills/respira-site-audit/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: respira-site-audit
+description: Use when asked to audit, score, or health-check a WordPress site or page. Runs SEO, AEO, readability, accessibility, performance, RankMath, and Core Web Vitals analyzers and presents a unified report with prioritised fixes.
+metadata:
+  short-description: Full site health check across SEO, AEO, accessibility, readability, and performance
+  version: 1.1.0
+  updated_at: 2026-05-17
+  respira_min_version: 7.1.0
+---
+
+# Respira Site Audit
+
+## Common Mistakes
+
+| Mistake | Correct approach |
+|---|---|
+| Running analyzers without knowing which page to audit | Always confirm the target. Site-wide (all public pages) or a specific page URL or ID. |
+| Reporting raw analyzer output without prioritising | Group findings by severity (CRITICAL, WARNING, SUGGESTION) and surface quick wins first. |
+| Running all analyzers in sequence when only one is needed | Match the analyzer to the question. If the user asks about SEO only, run `respira_analyze_seo` and skip the rest. |
+| Skipping `respira_get_builder_info` before reporting element-level issues | Builder type affects which fixes are possible. Elementor, Divi 4, Divi 5, Bricks, Beaver, and Oxygen all have different fix paths. |
+| Treating AEO and SEO as interchangeable | SEO targets search rankings. AEO targets AI-generated answers. Both analyzers cover different signals and you usually want both. |
+| Not checking whether the page is published before auditing | Drafts and private pages may produce incomplete results. Confirm `status: publish` first. |
+| Using `extract_builder_content` when you only need structure | Use `respira_get_page_outline` for the "what is on this page" read. It is lighter and includes the primary heading per row. |
+
+## Inputs
+
+- Target: a specific page URL, page ID, or "the whole site".
+- Scope: which analyzers to run. Default is all eight.
+- Output format: a summary for the user, or JSON for a CI / CD pipeline.
+
+## Workflow
+
+### Single-page audit
+
+1. `respira_get_site_context`. Confirm site URL, active SEO plugin (RankMath, Yoast, AIOSEO, SEOPress), active builder, WooCommerce presence.
+2. `respira_get_builder_info`. Note builder type for element-level fix recommendations.
+3. `respira_get_page_outline` if the structure needs to be discussed.
+4. Run analyzers in parallel where possible:
+   - `respira_analyze_seo`. Title, meta description, headings, internal links, canonical.
+   - `respira_analyze_aeo`. Structured content, FAQ schema, answer-box signals.
+   - `respira_analyze_readability`. Flesch score, sentence length, passive voice.
+   - `respira_analyze_performance`. Load time, image sizes, render-blocking resources.
+   - `respira_scan_page_accessibility`. WCAG 2.1 AA violations, alt text, contrast.
+   - `respira_analyze_images`. Per-image weight, format, oversize-by-X factor.
+   - `respira_check_structured_data`. Schema.org presence per page.
+   - `respira_get_core_web_vitals`. CrUX-backed LCP, INP, CLS where available.
+5. Aggregate findings by severity: CRITICAL → WARNING → SUGGESTION.
+6. Build a prioritised fix list: quick wins first (alt text, missing meta) before structural changes.
+7. Report: headline score per area plus top 3 fixes per area.
+
+### Site-wide audit
+
+1. `respira_list_pages` with `status: publish`. Collect all published page IDs.
+2. For each page, or a representative sample, run the single-page workflow above.
+3. Aggregate into a site-level summary: worst-performing pages, most common issue types, overall score bands.
+
+### RankMath / Yoast integration
+
+If RankMath, Yoast, AIOSEO, or SEOPress is active (visible in `respira_get_site_context`):
+
+- `respira_analyze_rankmath` reads RankMath's own focus keyword scores and suggestions.
+- Use these scores alongside `respira_analyze_seo` for a richer picture. Don't run them as alternatives.
+- `respira_check_seo_issues` returns the active SEO plugin's own issue feed.
+
+## Rules
+
+- Always run `respira_get_site_context` first. Plugin presence (RankMath, Yoast, WooCommerce, ACF, WPML) changes which tools are relevant.
+- Severity taxonomy: every finding must be CRITICAL (broken or missing, hurts rankings or UX), WARNING (suboptimal, addressable), or SUGGESTION (optional improvement).
+- Do not recommend changes that bypass the builder. For element-level SEO fixes (alt text, heading hierarchy), use `respira_find_element` plus `respira_update_element` after confirming the builder.
+- For accessibility fixes, prefer `respira_apply_accessibility_fixes` over manual element edits where the tool covers the finding.
+- Performance findings are informational. Do not modify theme files or plugins to address them. Surface the issue and recommend the appropriate plugin or hosting action.
+- For WPML-active sites, the audit is per-language. Pass the `lang` parameter to scope the run.
+
+## Verification
+
+After applying a fix:
+
+1. Re-run the analyzer that flagged the issue.
+2. Confirm the finding no longer appears at the same severity level.
+3. For SEO fixes, note that index refresh and ranking changes are delayed. Tell the user.
+
+For site-wide audits, re-audit the 3 worst-performing pages after fixes to confirm score movement.
+
+## Escalation
+
+Stop and ask the user if:
+
+- The site has more than 200 published pages and the request is "audit the whole site". Confirm how many pages to sample.
+- A CRITICAL finding requires a structural change (no H1 on any page, no `<html lang>` attribute). These often need theme or plugin changes beyond Respira's scope.
+- `respira_analyze_performance` returns LCP > 4s or CLS > 0.25. Flag as high priority and ask whether to involve a developer.
+- The site is on a multi-site network and the audit target wasn't specified. Confirm whether the run is per-subsite or network-wide.
+
+## Example
+
+Goal: audit the homepage for SEO and AEO readiness.
+
+```
+1. respira_get_site_context        → WordPress 6.9, RankMath active, Elementor 3.21
+2. respira_get_builder_info        → Elementor, supported
+3. respira_analyze_seo             → CRITICAL: no meta description | WARNING: 3 images missing alt
+4. respira_analyze_aeo             → WARNING: no FAQ schema | SUGGESTION: add HowTo schema
+5. respira_analyze_rankmath        → Focus keyword score: 62/100, improve keyword density
+6. respira_scan_page_accessibility → WARNING: 2 buttons have no accessible label
+7. respira_get_core_web_vitals     → LCP 2.8s (needs improvement), INP 180ms (good), CLS 0.05 (good)
+
+Report:
+  CRITICAL  → Add meta description (missing entirely)
+  CRITICAL  → Add alt text to 3 hero images
+  WARNING   → Add FAQ schema block for AEO (AI answer-box eligibility)
+  WARNING   → 2 buttons need aria-label for screen readers
+  WARNING   → LCP at 2.8s, target sub-2.5s by deferring the hero video
+  SUGGESTION → Increase focus keyword density from 0.4% to 0.8%
+```

package/skills/respira-woocommerce/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: respira-woocommerce
+description: Use for WooCommerce operations on a WordPress site. Listing, reading, creating, updating, and duplicating products. Managing categories and tags. Reading orders and updating order status. Stock management. Sales reports. Storefront layout edits. Builder-aware throughout. Requires the Respira WooCommerce add-on (paid).
+metadata:
+  short-description: Builder-aware WooCommerce product, category, order, stock, and storefront management
+  version: 1.2.0
+  updated_at: 2026-05-17
+  respira_min_version: 7.1.0
+  requires_addon: respira-woocommerce-addon
+---
+
+# Respira WooCommerce
+
+## What this skill covers
+
+The Respira WooCommerce add-on (v2.1.0+) exposes 21 abilities through the WordPress Abilities API, plus a storefront layout surface for Elementor, Divi, Flatsome UX Builder, Bricks, and Gutenberg shop / product templates. The add-on is paid and license-gated; if the add-on isn't active, every Woo tool returns a clear `respira_webmcp_woo_unavailable` error and the user should be sent to `respira.press/addons/woocommerce`.
+
+The 21 abilities namespace under `respira-woocommerce/*`:
+
+- **Products**: get-products, get-product, create-product, update-product, duplicate-product.
+- **Categories**: get-categories, get-category, create-category, update-category, delete-category.
+- **Tags**: get-tags, get-tag, create-tag, update-tag, delete-tag.
+- **Orders**: get-orders, get-order, update-order-status.
+- **Stock**: get-stock-status, update-stock.
+- **Reporting**: get-sales-report.
+
+The storefront surface (under `/respira/v1/woocommerce/storefront/`) covers `analyze-shop`, `analyze-product`, `update-card-layout`, and `add-low-stock-badge`. These act on builder-managed product card templates rather than the WC core data.
+
+## Common Mistakes
+
+| Mistake | Correct approach |
+|---|---|
+| Using `respira_update_page` on a WooCommerce product page | Use the WooCommerce update-product ability for product data. Use `respira_find_element` plus `respira_update_element` for builder-managed visual content on the page. |
+| Editing product price or stock directly in the page content | These are post meta fields. Use the update-product or update-stock abilities. |
+| Running get-products without pagination on a large catalog | Always set `per_page` (max 100) and paginate. Large catalogs cause timeouts. |
+| Applying a coupon via post meta | Coupons should go through the canonical WooCommerce coupon mutation (or the WC admin). Direct meta edits bypass WC validation. |
+| Editing a builder-managed shop archive template via update_page | Use `respira_get_builder_info` to identify the template type first. The storefront tools cover product-card layout changes; visual edits go through `respira_update_element`. |
+| Not checking whether WooCommerce is active before calling Woo tools | Confirm with `respira_get_site_context`. Woo tools return a structured error if the plugin is inactive or the add-on isn't licensed. |
+| Forgetting that update-order-status only changes status | Updating the rest of the order (line items, totals, addresses) needs the WC admin or a dedicated tool. The ability is narrow on purpose. |
+
+## Inputs
+
+- Product ID, SKU, or search term.
+- Category or tag slug or ID.
+- Order ID or order status filter (pending, processing, on-hold, completed, cancelled, refunded, failed).
+- Coupon code or coupon ID.
+- The fields to read or update.
+
+## Workflow
+
+### Product operations
+
+1. `respira_get_site_context`. Confirm WooCommerce active + add-on licensed.
+2. `get-products`. Find the product by name, SKU, or filter. Set `per_page` and paginate.
+3. `update-product`. Apply changes (price, stock, status, title, description, images).
+4. For visual / builder content on the product page: `respira_get_builder_info` plus `respira_find_element` plus `respira_update_element`.
+
+### Category and tag operations
+
+1. `get-categories` or `get-tags`. Find the target by slug or name.
+2. `create-`, `update-`, or `delete-`. Mutations gated by capability checks.
+3. Reorder or reparent through `update-category` (parent + display order).
+
+### Order operations
+
+1. `get-orders` with a status filter.
+2. `get-order` for a specific record.
+3. `update-order-status` for status transitions. Anything more invasive needs the WC admin.
+
+### Stock operations
+
+1. `get-stock-status` for a snapshot.
+2. `update-stock` for quantity or status mutations. The ability respects `manage_stock` per product.
+
+### Storefront layout
+
+1. `analyze-shop` or `analyze-product`. Returns the active builder and the editable card / template paths.
+2. `update-card-layout` to mutate the product card structure.
+3. `add-low-stock-badge` to insert the conditional badge widget.
+4. Always snapshot the page first with `respira_create_page_duplicate`.
+
+### Batch product updates
+
+For updating multiple products (a price increase across a category):
+
+1. `get-products` with the category filter. Collect target IDs.
+2. `respira_batch_update`. Apply the same field change across all collected IDs in a single call.
+
+## Rules
+
+- Always check WooCommerce is active and the add-on is licensed before calling Woo tools.
+- Never use `respira_update_page` on a product page to change price, stock, or product meta. Those are WC data fields.
+- For product description: if the product page uses a builder, the visual description may live in the builder JSON. Use `respira_find_element` to locate it. The WC `description` field is the fallback (non-builder) description.
+- `respira_batch_update` accepts a maximum of 100 items per call. Chunk larger operations.
+- Never create or modify coupons without confirming the discount type with the user. A percent coupon applied as fixed_cart can cause significant revenue loss.
+- Currency is per-site. Don't assume USD or EUR; read it from `respira_get_site_context`.
+
+## Verification
+
+After `update-product`:
+
+1. Call `get-product` and confirm the changed fields match.
+2. For price changes, verify both `regular_price` and `sale_price` are correct.
+3. For stock changes, verify `stock_quantity` and `stock_status`.
+
+After `update-order-status`:
+
+1. Call `get-order` and confirm the status transition.
+2. Note that WC emails fire automatically on certain transitions; tell the user.
+
+After a batch update:
+
+1. Sample 2-3 products from the batch and verify the changed field.
+2. Report the total number of products updated and any that returned errors.
+
+## Escalation
+
+Stop and ask the user if:
+
+- The product catalogue has more than 1,000 items and the request is "update all products". Confirm scope and batch strategy first.
+- A coupon update would affect unlimited use or a site-wide discount. Confirm before applying.
+- WooCommerce Subscriptions, Memberships, or Bookings are involved. These have their own data models. Check available tools before proceeding.
+- The update would change a product's `status` from `publish` to `draft`. Confirm the user intends to unpublish.
+- An order has been paid and shipped, and the request would modify it. WC stores immutable history on paid orders; ask before mutating.
+
+## Example
+
+Goal: update the regular price of "Merino Wool Tee" from €49 to €59.
+
+```
+1. respira_get_site_context        → WooCommerce 8.7 active, Woo add-on licensed ✓
+2. get-products                    → search "Merino Wool Tee" → ID 2847
+3. update-product                  → ID 2847, regular_price: "59"
+4. get-product                     → ID 2847 → regular_price: "59.00" ✓
+```