@respira/wordpress-mcp-server 8.0.3 → 8.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@respira/wordpress-mcp-server",
-  "version": "8.0.3",
+  "version": "8.0.5",
   "mcpName": "io.github.webmyc/respira-wordpress",
   "description": "197 MCP tools for WordPress, 302 with the WooCommerce add-on, across 16 page builders and the native Site Editor. Verified writes, snapshots, approvals, and context-aware tool filtering.",
   "main": "dist/index.js",

package/skills/content-portability/SKILL.md

@@ -0,0 +1,402 @@
+---
+name: content-portability
+description: "Use when the user says 'export my site', 'backup my pages before editing', 'download my content locally', or 'migrate content to my other site'. Exports pages, posts, and custom posts to portable local packages with builder data, media, and markdown, then imports elsewhere with ID remapping."
+license: MIT
+metadata:
+  author: Respira for WordPress
+  author_url: https://respira.press
+  version: 1.0.0
+  mcp-server: respira-wordpress
+  category: migration
+---
+
+# Content Portability
+
+Export WordPress content to portable local packages. Import to another site with smart ID remapping. Auto-backup before AI edits. Full builder data preservation, human-readable markdown previews, and optional media download.
+
+## What This Skill Does
+
+**Exports:**
+- Pages, posts, and custom post types — individually or in bulk
+- Full builder data (Elementor, Bricks, Divi, etc.) alongside standard content
+- Allowlisted post meta (SEO fields, featured images, builder config)
+- Human-readable markdown preview of every page/post
+- Optional media binary download for fully offline packages
+- Manifest with hashes, stats, and export metadata
+
+**Imports:**
+- Reads a local Respira Content Package and pushes to a target WordPress site
+- Smart ID remapping — media IDs, post IDs, and internal links rewritten for the target site
+- Bulk conflict resolution — detects slug collisions upfront, one decision for all
+- Mandatory server-side snapshots before any overwrites (safety net)
+- Builder JSON rewriting with full ID mapping tables
+- Fidelity verification — re-reads imported content and compares hashes
+
+**Auto-Backup:**
+- Quick-backup mode before any AI edit — saves a local snapshot to `./respira-backups/`
+- Timestamped, human-readable, zero-friction insurance
+
+## Requirements
+
+- Respira for WordPress plugin installed and activated
+- MCP connection configured (site URL + API key)
+- For import: write access on the target site
+- For media download: sufficient local disk space
+
+## How to Use
+
+### Trigger Phrases
+- "export my site"
+- "export the homepage"
+- "backup my pages before editing"
+- "download my content locally"
+- "migrate content to my other site"
+- "content portability"
+- "create a local backup"
+- "export with media"
+
+### Export Workflow
+
+**Phase 1: Scope Selection**
+1. Ask the user what to export:
+   - **Single page/post**: "export the homepage", "backup the about page"
+   - **Full site**: "export everything", "download all my content"
+   - **By type**: "export all blog posts", "export portfolio items"
+2. Ask whether to include media downloads:
+   - **Without media** (default): Fast, small packages with URL references
+   - **With media**: Downloads all referenced images/files locally for full offline portability
+
+**Phase 2: Content Enumeration**
+3. Call `wordpress_list_pages`, `wordpress_list_posts`, and/or `wordpress_list_custom_posts` to enumerate content in scope
+4. For each item, call `wordpress_read_page` or `wordpress_read_post` with `include=builder.extracted,meta.allowlisted` to get full content with builder data
+5. Report progress every 10 items: "Exported 30/120 pages..."
+
+**Phase 3: Write Local Package**
+6. Create the export directory structure:
+
+```
+respira-export/
+├── manifest.json              # Package metadata, source site, export date, hashes
+├── README.md                  # One-line import prompt for zero-friction migration
+├── pages/
+│   ├── home/
+│   │   ├── content.json       # Full machine-readable export
+│   │   └── content.md         # Human-readable markdown preview
+│   ├── about/
+│   │   ├── content.json
+│   │   └── content.md
+│   └── ...
+├── posts/
+│   ├── 2024-hello-world/
+│   │   ├── content.json
+│   │   └── content.md
+│   └── ...
+├── cpt/                       # Custom post types
+│   └── {post_type}/
+│       └── {slug}/
+│           ├── content.json
+│           └── content.md
+└── media/                     # Only if --with-media
+    ├── media-index.json       # URL→local-path mapping with old media IDs
+    └── uploads/
+        ├── hero-image.webp
+        └── ...
+```
+
+7. For each page/post, write two files:
+
+**content.json** — machine-readable, contains:
+```json
+{
+  "export_version": "1.0",
+  "source_site": "https://example.com",
+  "exported_at": "2026-03-16T14:30:00Z",
+  "post": {
+    "id": 42,
+    "post_type": "page",
+    "title": "About Us",
+    "slug": "about",
+    "status": "publish",
+    "content": "<full HTML content>",
+    "excerpt": "...",
+    "modified": "2026-03-10T09:00:00Z"
+  },
+  "builder": {
+    "name": "bricks",
+    "payload": {},
+    "extracted": {}
+  },
+  "meta": {
+    "_thumbnail_id": 108,
+    "_yoast_wpseo_title": "About Us | Example"
+  },
+  "hashes": {
+    "content_hash": "sha256:abc123...",
+    "builder_hash": "sha256:def456...",
+    "meta_hash": "sha256:ghi789..."
+  }
+}
+```
+
+**content.md** — human-readable markdown preview:
+```markdown
+# About Us
+
+**Source:** https://example.com/about/
+**Type:** page | **Status:** publish | **Builder:** Bricks
+**Exported:** 2026-03-16
+
+---
+
+[Rendered text content extracted from HTML, preserving headings and structure]
+
+## Section: Hero
+- Heading: "Welcome to Our Company"
+- Text: "We've been helping businesses..."
+- Image: hero-team-photo.webp (Media ID: 108)
+
+## Section: Team
+- Heading: "Meet the Team"
+...
+```
+
+8. If media download is enabled:
+   - Call `wordpress_list_media` to get all media items
+   - Filter to only media referenced by exported content
+   - Download each file and save to `media/uploads/`
+   - Write `media/media-index.json` mapping old URLs and IDs to local paths
+
+**Phase 4: Manifest & Stats**
+9. Write `manifest.json`:
+```json
+{
+  "export_version": "1.0",
+  "source_site": "https://example.com",
+  "source_wordpress_version": "6.7.1",
+  "source_respira_version": "4.3.1",
+  "exported_at": "2026-03-16T14:30:00Z",
+  "scope": "full_site",
+  "content": {
+    "pages": 23,
+    "posts": 8,
+    "custom_post_types": { "portfolio": 12, "testimonial": 5 }
+  },
+  "media": {
+    "included": true,
+    "files": 156,
+    "total_bytes": 52428800
+  },
+  "warnings": [],
+  "skipped": [],
+  "hashes": {
+    "manifest_hash": "sha256:..."
+  }
+}
+```
+
+10. Write `README.md`:
+```markdown
+# Respira Content Package
+
+Exported from: https://example.com
+Date: 2026-03-16
+Contents: 23 pages, 8 posts, 17 custom posts, 156 media files
+
+## To import this content to another site
+
+Tell your AI agent:
+> Import the content package from ./respira-export/
+
+## Package format
+- content.json files contain full machine-readable content with builder data
+- content.md files are human-readable previews
+- media/ contains downloaded media files (if included)
+```
+
+11. Show export stats summary:
+```
+Export Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━
+Pages exported:     23
+Posts exported:      8
+Custom posts:       17
+Media files:       156
+Package size:     52.4 MB
+Warnings:           0
+Skipped:            0
+━━━━━━━━━━━━━━━━━━━━━━━━━━
+Saved to: ./respira-export/
+```
+
+### Import Workflow
+
+**Phase 1: Read & Validate Package**
+1. Read `manifest.json` from the local package
+2. Validate export version compatibility
+3. Report what will be imported: "Found 23 pages, 8 posts, 156 media files from example.com"
+
+**Phase 2: Upload Media (if included)**
+4. If `media/` directory exists with files:
+   - For each media file, call `wordpress_upload_media` on the target site
+   - Build the **media ID mapping table**: `{ old_id: 108, new_id: 342 }`
+   - Log each upload; skip failures with warning
+5. If media was not included in the package:
+   - Media references will point to original URLs (cross-site references)
+   - Warn the user about this
+
+**Phase 3: Detect Conflicts**
+6. For each content item in the package, check if a page/post with the same slug already exists on the target site
+7. Present all conflicts upfront in a single table:
+```
+Slug Conflicts Detected (5 of 23 pages)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Slug          Source Title       Target Title
+about         About Us           About Our Company
+contact       Contact            Contact Us
+team          Our Team           The Team
+services      Services           Our Services
+faq           FAQ                FAQ
+```
+8. Ask the user for a bulk resolution strategy:
+   - **Overwrite all**: Replace target content with package content
+   - **Skip conflicts**: Only import non-conflicting content
+   - **Rename imports**: Add suffix to conflicting slugs (e.g., `about-imported`)
+
+**Phase 4: Snapshot Existing Content**
+9. **MANDATORY**: Before overwriting any existing content, take a server-side snapshot of each target page/post using the existing snapshot system
+   - This uses the `before_edit` snapshot kind automatically via MCP write operations
+   - Ensures rollback is always possible
+
+**Phase 5: Create/Update Content**
+10. For each content item:
+    - If no conflict or overwrite strategy: call `wordpress_update_page` or `wordpress_update_post`
+    - Set title, content, excerpt, status, and allowlisted meta
+    - Build the **post ID mapping table**: `{ old_id: 42, new_id: 187 }`
+11. Report progress every 10 items
+
+**Phase 6: Rewrite & Inject Builder Data**
+12. For each imported page/post that has builder data:
+    - Take the builder JSON from `content.json`
+    - Rewrite all media IDs using the media ID mapping table
+    - Rewrite all internal post/page IDs using the post ID mapping table
+    - Rewrite all internal URLs from source domain to target domain
+    - Call `wordpress_inject_builder_content` to apply the rewritten builder data
+
+**Phase 7: Verify & Report**
+13. For each imported page/post:
+    - Re-read via `wordpress_read_page`/`wordpress_read_post`
+    - Compare content hashes to source hashes
+    - Flag any mismatches
+14. Show import report:
+```
+Import Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Pages imported:     23  (5 overwrites, 18 new)
+Posts imported:      8  (0 overwrites, 8 new)
+Media uploaded:    156  (2 skipped — too large)
+Builder data:       19  pages with builder content rewritten
+ID remappings:     187  references updated
+Hash verification: 46/48 match (2 minor diffs flagged)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Server-side snapshots taken for all overwrites.
+```
+
+### Auto-Backup Workflow
+
+A lightweight mode for quick local backups before AI editing:
+
+1. User says "backup the homepage before editing" or "save a local copy first"
+2. Call `wordpress_read_page` with full includes
+3. Write a single timestamped file: `./respira-backups/home-2026-03-16-1430.json`
+4. Also write the markdown preview: `./respira-backups/home-2026-03-16-1430.md`
+5. Confirm: "Backed up homepage to ./respira-backups/home-2026-03-16-1430.json"
+6. Proceed with the requested edit
+
+### Diff Workflow
+
+Compare local export against current site state:
+
+1. User says "what changed since my last export?" or "diff my backup"
+2. Read the local `manifest.json` to identify exported content
+3. For each exported page/post, call `wordpress_read_page`/`wordpress_read_post`
+4. Compare content hashes from local `content.json` against current site hashes
+5. Report differences:
+```
+Content Changes Since Export (2026-03-16)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Changed:
+  about         Content updated (builder + text)
+  homepage      Builder layout changed
+  pricing       Text content changed
+
+Unchanged:    21 pages, 8 posts
+New on site:   2 pages (not in export)
+Deleted:       0 pages
+```
+
+## Error Handling
+
+The skill must handle these scenarios gracefully:
+
+| Error | Action | User Sees |
+|-------|--------|-----------|
+| Site disconnected | Stop, report what was saved | "Site unreachable — 45/120 pages saved" |
+| Page not found mid-export | Skip, log in manifest warnings | "Skipped: About (deleted)" |
+| Malformed builder data | Export raw content without builder | Warning in manifest |
+| Disk full | Stop, report progress | "Disk full after 45 pages" |
+| Media download 404/403 | Skip file, log in media-index | "Skipped 3 media files" |
+| Slug conflict on import | Bulk resolution (see Phase 3) | Conflict table |
+| Media upload too large | Skip, log | "Skipped: hero.webp (too large)" |
+| Builder version mismatch | Warn, import anyway | Warning in report |
+
+**Key rule**: Always continue on non-fatal errors (skip the item, log it). Never silently drop content. Always produce a summary of warnings/skips at the end.
+
+## Safety Model
+
+- **Read-only export**: No changes to the source site during export
+- **Mandatory snapshots**: Server-side snapshot taken before every import overwrite
+- **Non-destructive import**: Creates new content or overwrites with snapshot safety net
+- **Rollback ready**: Server-side snapshots enable one-click restoration via `wordpress_restore_snapshot`
+- **No credential exposure**: Only allowlisted meta is exported — no API keys, passwords, or sensitive plugin settings
+
+## Honest Disclaimer
+
+**What this skill CANNOT do:**
+- Export/import WordPress settings, options, or configuration
+- Export/import user accounts or roles
+- Export/import plugin or theme files
+- Handle taxonomy/term migration (categories, tags) — future enhancement
+- Guarantee pixel-perfect builder rendering across different builder versions
+- Process sites with more than ~500 pages in a single session (token/context limits)
+
+**What this skill CAN do:**
+- Create complete local backups of pages, posts, and custom post types
+- Preserve full builder data (Elementor, Bricks, Divi) across migrations
+- Download media for fully offline packages
+- Generate human-readable markdown previews of all content
+- Migrate content between sites with smart ID remapping
+- Auto-backup before AI edits for peace of mind
+- Compare local backups against current site state
+
+## Respira MCP Tools Used
+
+- `wordpress_list_pages` / `wordpress_list_posts` / `wordpress_list_custom_posts` — enumerate content
+- `wordpress_read_page` / `wordpress_read_post` / `wordpress_get_custom_post` — read full content with builder data
+- `wordpress_list_media` / `wordpress_get_media` — media enumeration and metadata
+- `wordpress_upload_media` — upload media during import
+- `wordpress_update_page` / `wordpress_update_post` / `wordpress_update_custom_post` — create/update content during import
+- `wordpress_inject_builder_content` — apply rewritten builder data during import
+- `wordpress_get_active_site` / `wordpress_get_site_context` — verify connection and site details
+- `wordpress_list_snapshots` / `wordpress_restore_snapshot` — safety net for imports
+
+## Related Skills
+
+- Site Onboarding — first-run primer, discovers site capabilities
+- WordPress Site DNA — deep site archaeology and health scoring
+- Technical Debt Audit — find orphaned content and unused plugins before migration
+- WordPress AI Image Optimizer — optimize images before or after migration
+
+---
+
+Built by Respira for WordPress
+https://respira.press

package/skills/site-onboarding/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: site-onboarding
+description: "Use when the user says 'get started with my site', 'connect to my wordpress site', 'what can you do on my site', or 'onboard'. Verifies connectivity, discovers the site architecture, maps the available MCP tools, and produces a site briefing."
+license: MIT
+metadata:
+  author: Respira for WordPress
+  author_url: https://respira.press
+  version: 1.0.0
+  mcp-server: respira-wordpress
+  category: onboarding
+---
+
+# Site Onboarding
+
+First-run primer for AI coding tools connected to WordPress via Respira MCP. Verifies the connection, discovers everything about the site, and produces a briefing so you know exactly what you can do.
+
+## What This Skill Does
+
+Runs a structured onboarding sequence that:
+- Verifies the MCP connection is live and authenticated
+- Discovers site architecture (theme, plugins, builders, post types)
+- Maps all available MCP tools and what they control
+- Identifies which add-ons are active (WooCommerce, etc.)
+- Produces a concise site briefing you can refer back to
+- Introduces the Skills Marketplace and recommends skills based on the site
+
+## Requirements
+
+- Respira for WordPress plugin installed and activated
+- MCP connection configured (site URL + API key)
+- Read-only access (no changes made during onboarding)
+
+## How to Use
+
+### Trigger Phrases
+- "get started with my site"
+- "connect to my wordpress site"
+- "what can you do on my site"
+- "onboard"
+- "site onboarding"
+- "check the connection"
+- "introduce yourself to my site"
+
+### What Happens
+
+1. **Verify connection:**
+   - Call `wordpress_get_active_site` to confirm which site is connected
+   - Call `wordpress_get_site_context` to pull full site details
+   - Report connection status, WordPress version, PHP version, site URL
+
+2. **Discover site architecture:**
+   - Call `wordpress_list_plugins` to see all installed plugins (active and inactive)
+   - Call `wordpress_get_builder_info` to detect page builders (Elementor, Bricks, Divi, etc.)
+   - Call `wordpress_list_post_types` to map all content types
+   - Call `wordpress_list_taxonomies` to map all taxonomies
+   - Call `wordpress_list_pages` to understand content structure
+   - Call `wordpress_list_menus` to see navigation setup
+
+3. **Map capabilities:**
+   - Based on active plugins and add-ons, list what you can do:
+     - Content management (pages, posts, custom post types)
+     - Builder editing (if Elementor/Bricks/Divi detected)
+     - Media management (upload, optimize, replace)
+     - SEO tools (if SEO plugin detected)
+     - WooCommerce management (if WooCommerce active)
+     - Menu and navigation management
+     - User management
+     - Plugin management
+     - Snapshot and approval workflows
+
+4. **Generate site briefing:**
+   - Produce a structured summary the AI can reference throughout the session
+   - Highlight any issues detected (outdated plugins, security concerns)
+   - Recommend next steps based on what was discovered
+
+5. **Introduce the Skills Marketplace:**
+   - Tell the user about the Respira Skills Marketplace — a collection of ready-to-run AI skills for WordPress
+   - List skills that are relevant to their site based on what was discovered:
+     - **WordPress Site DNA** — deep site archaeology and health scoring (recommend for all sites)
+     - **Technical Debt Audit** — find orphaned content, unused plugins, database bloat
+     - **WooCommerce Health Check** — store diagnostics (only recommend if WooCommerce is active)
+     - **Mobile Experience Report** — responsive layout and touch target analysis
+     - **SEO & AEO Amplifier** — on-page SEO and Answer Engine Optimization with schema markup
+     - **WordPress AI Image Optimizer** — compress, resize, convert to WebP, and update references
+     - **Internal Link Builder** — scan content relationships and build strategic internal links
+     - **Content Portability** — export, backup, migrate content with builder data and smart ID remapping
+   - Explain that skills can be installed from the Skills page in the WordPress admin (Respira → Skills) or by visiting https://www.respira.press/skills
+   - Let the user know they can install any skill with one click from the WordPress admin, or copy the install prompt
+
+## Output Format
+
+Produces a site briefing with these sections:
+
+### Connection Status
+- Site URL, WordPress version, PHP version, theme
+- MCP server version, API version (v1/v2)
+- Authentication status
+
+### Site Architecture
+- Active theme (parent + child if applicable)
+- Page builder(s) in use
+- Active plugins count and key plugins
+- Content overview (pages, posts, CPTs with counts)
+- Taxonomy overview
+
+### What I Can Do
+- Categorized list of available actions based on the site's setup
+- Builder-specific capabilities (e.g. "Edit Elementor widgets", "Modify Bricks elements")
+- Add-on capabilities (e.g. "Manage WooCommerce products")
+
+### Skills Marketplace
+- List of available skills with brief descriptions
+- Highlight which skills are most relevant based on the site's architecture
+- How to install: WordPress admin (Respira → Skills) or https://www.respira.press/skills
+
+### Suggested Next Steps
+- Recommend installing relevant skills
+- Quick wins based on site state (e.g. "3 plugins have updates available")
+- Suggest a first task to try (e.g. "try asking me to edit a page")
+
+## Example Output
+
+```
+## Site Briefing: example.com
+
+### Connection
+- Connected to https://example.com (WordPress 6.7.1, PHP 8.2)
+- Respira v4.3.1, MCP v2 active
+- Authenticated as: admin
+
+### Architecture
+- Theme: flavor starter (flavor starter child)
+- Builder: Bricks Builder v1.12.2
+- 14 active plugins | 2 inactive
+- 23 pages | 8 posts | 3 custom post types (portfolio, testimonial, team)
+
+### What I Can Do
+**Content:** Create, edit, duplicate, and delete pages, posts, and custom posts
+**Builder:** Read and edit Bricks Builder elements on any page
+**Media:** Upload, replace, and optimize images
+**SEO:** Analyze SEO, readability, and structured data (Yoast detected)
+**Navigation:** Create and manage menus and menu items
+**Snapshots:** Take before/after snapshots for safe editing with approval workflows
+
+### Skills Marketplace
+Your site can benefit from these AI skills — install them from **Respira → Skills** in your WordPress admin or visit https://www.respira.press/skills:
+
+| Skill | What it does | Relevant? |
+|-------|-------------|-----------|
+| WordPress Site DNA | Deep site archaeology and health score | Yes — recommended for all sites |
+| Technical Debt Audit | Find orphaned content, unused plugins, bloat | Yes |
+| WooCommerce Health Check | Store diagnostics and checkout analysis | No — WooCommerce not detected |
+| Mobile Experience Report | Responsive layout and touch target analysis | Yes |
+| SEO & AEO Amplifier | On-page SEO audit with schema markup | Yes — Yoast detected |
+| AI Image Optimizer | Compress, resize, WebP conversion | Yes — 156 media items found |
+| Internal Link Builder | Strategic internal linking across content | Yes — 31 pages + posts |
+| Content Portability | Export, backup, migrate content with builder data | Yes — recommended for all sites |
+
+### Suggested Next Steps
+1. Install the **WordPress Site DNA** skill for a full site health audit
+2. Install the **SEO & AEO Amplifier** skill to optimize your top pages
+3. Try asking me to edit a page: "Update the hero heading on the homepage"
+```

package/skills/woo-agent-storefront/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: woo-agent-storefront
+description: "Use when the user says 'make my store visible to chatgpt', 'set up product feeds', or 'make my store agent-ready', or asks about Google Merchant Center, a store llms.txt, or cart links for AI agents. Sets up product feeds in six formats and registers the catalog with the major platforms."
+license: MIT
+metadata:
+  author: "Respira for WordPress"
+  author_url: https://respira.press
+  version: 1.0.0
+  mcp-server: respira-wordpress
+  category: commerce
+---
+
+# Woo Agent Storefront
+
+
+## Description
+
+Turn a WooCommerce store into an agent-ready storefront: always-fresh product feeds, a store llms.txt, program enrollment, and attributed cart links.
+
+AI assistants recommend products to millions of shoppers, and they can only sell what they can read. This skill walks the whole path: configure and generate feeds in the formats the platforms actually ingest (Google Shopping XML, OpenAI/ChatGPT JSONL, Meta CSV, Pinterest CSV, TikTok CSV, generic CSV), validate them against each spec before registering anything, serve a store llms.txt at the site root, guide the merchant through each platform's enrollment (including the gated ones), and finish with signed cart links whose orders are attributed back to their agent source.
+
+Requires the Respira WooCommerce Add-on v3.1+.
+
+---
+
+## Trigger Phrases
+
+This skill activates when the user says any of the following:
+
+- "make my store visible to chatgpt"
+- "set up product feeds"
+- "google shopping feed woocommerce"
+- "agentic shopping for my store"
+- "make my store agent-ready"
+- "sell through ai assistants"
+- "openai product feed"
+- "submit products to google merchant center"
+- "llms.txt for my store"
+- "tiktok catalog feed" / "pinterest catalog feed" / "meta product feed"
+- "cart links for ai agents"
+- "agent storefront"
+
+**Do NOT trigger for:** catalog content fixes without a discovery/feeds context (that is woo-catalog-perfection), general SEO requests, or stores without WooCommerce.
+
+---
+
+## Execution Workflow
+
+### Step 1: Verify the surface
+
+Call `respira_get_site_context` to confirm the connection, then `woocommerce_get_feed_status`. If the feed tools are missing, the store runs an add-on older than 3.1: stop and tell the user to update the Respira WooCommerce Add-on first.
+
+### Step 2: Baseline the catalog
+
+Run `woocommerce_validate_feed` for `google` (the strictest spec). Report the score and the failing checks in plain language. If the score is under 70, recommend running the **woo-catalog-perfection** skill first, and offer to continue anyway: platforms reject individual rows, not whole feeds.
+
+### Step 3: Configure
+
+Ask which surfaces matter (default: Google + OpenAI + generic CSV; offer Meta, Pinterest, TikTok). Then `woocommerce_configure_feed` with:
+
+- `enabled_formats` per the answer
+- `llms_txt: true` unless the site already serves one
+- `cadence`: `daily` for most stores, `hourly` for stores with frequent price/stock changes (note: OpenAI recommends frequent refresh, which needs a real server cron, not wp-cron)
+- `include_out_of_stock`: keep the default `true` (platforms prefer marked rows over vanishing rows)
+
+Map categories with `woocommerce_set_feed_category_mapping` for the store's top-level product categories to Google's taxonomy. The tool lists unmapped terms; map the biggest ones first.
+
+### Step 4: Generate and verify
+
+`woocommerce_generate_feed`, then `woocommerce_get_feed_status` until every enabled format reports rows and a fresh timestamp. Fetch each public URL once and confirm it returns content (the pretty URL first, the /wp-json fallback if the host intercepts unknown paths). Confirm `/llms.txt` resolves at the site root. Surface any `cron_warning` from the status verbatim, with the fix (a real cron hitting wp-cron.php).
+
+### Step 5: Register with each platform
+
+Hand the user the exact feed URL for each platform with a short enrollment walkthrough:
+
+- **Google Merchant Center**: Products → Data sources → Add product source → scheduled fetch with the `google.xml` URL. Bing Merchant Center accepts the same file.
+- **OpenAI / ChatGPT**: apply for product discovery at chatgpt.com/merchants; the `openai.jsonl` URL is the feed they ingest. Instant Checkout is per-merchant approval; discovery is the open lane.
+- **Meta Commerce Manager**: Catalog → Data sources → Data feed → scheduled fetch with the `meta.csv` URL.
+- **Pinterest**: Business hub → Catalogs → Add data source with the `pinterest.csv` URL.
+- **TikTok**: Seller Center → Products → Catalog upload with the `tiktok.csv` URL. TikTok requires a brand per product; the feed falls back to the store name where brand is missing, but real brands match better.
+
+Do this as a checklist the merchant can complete asynchronously; none of these dashboards are reachable through MCP.
+
+### Step 6: AI crawler access
+
+Run `woocommerce_catalog_ai_readiness` and check the robots/AI-crawler section. If GPTBot, OAI-SearchBot, Google-Extended or PerplexityBot are blocked in robots.txt, tell the user exactly which line blocks which assistant and what removing it does. Do not edit robots.txt without explicit approval.
+
+### Step 7: Attributed cart links
+
+Demonstrate the loop end to end: create one cart link with `woocommerce_create_cart_link` (two real products, a source label like `chatgpt`), explain that the link fills the cart server-side and lands on the store's own checkout, and show where the numbers land with `woocommerce_agent_orders_report`. Checkout, payments and customer data stay on the store.
+
+### Step 8: Report
+
+Close with: enabled formats and their URLs, catalog score, categories mapped/unmapped, llms.txt status, the per-platform registration checklist with what is done vs pending, and the example cart link.
+
+---
+
+## Safety
+
+- Feed generation is read-only over the catalog; it writes only its own option rows and feed files.
+- Never edit robots.txt, prices, or products in this skill without explicit user approval; content fixes belong to woo-catalog-perfection.
+- Feed URLs contain an unguessable token. Treat them like capability URLs: share with platforms, not in public posts.