claude-plugin-wordpress-manager 1.4.0

package/skills/wp-migrate/references/cross-platform.md

@@ -0,0 +1,104 @@
+# Cross-Platform Migration Strategies
+
+## WordPress.com → Self-Hosted WordPress
+
+### Method 1: WXR Export (Content Only)
+1. WordPress.com Admin → Tools → Export → All content
+2. Download the .xml file (WXR format)
+3. On destination: Tools → Import → WordPress Importer
+4. Upload the WXR file
+5. Map authors and import attachments
+
+**Limitations**: Doesn't transfer themes, plugins, or custom settings
+
+### Method 2: WordPress.com MCP (if available)
+1. Use WordPress.com MCP to read content
+2. Use WP REST Bridge to write content to destination
+3. Advantage: More control over content transformation
+
+### Method 3: Guided Transfer (WordPress.com feature)
+WordPress.com Business/eCommerce plans offer guided transfer:
+1. Request transfer in WordPress.com settings
+2. WordPress.com packages site files and database
+3. Download package and import to new hosting
+
+## Self-Hosted → Self-Hosted
+
+### Method 1: Full Server Migration (Recommended)
+```bash
+# On source
+mysqldump -u root -p wordpress_db > backup.sql
+tar -czf wp-files.tar.gz -C /var/www/html .
+
+# Transfer
+scp backup.sql wp-files.tar.gz user@destination:/tmp/
+
+# On destination
+mysql -u root -p new_db < /tmp/backup.sql
+tar -xzf /tmp/wp-files.tar.gz -C /var/www/html/
+wp search-replace 'old-url.com' 'new-url.com' --all-tables
+```
+
+### Method 2: Plugin-Based Migration
+Plugins like All-in-One WP Migration, Duplicator, or UpdraftPlus:
+1. Install migration plugin on source
+2. Create migration package
+3. Install same plugin on destination
+4. Import package
+5. Update URLs
+
+### Method 3: API-Based Content Transfer
+For content-only migration between two accessible sites:
+1. Enumerate content on source via `list_content`
+2. For each content piece: `get_content` → transform → `create_content` on destination
+3. Handle media separately: download from source, upload to destination
+4. Update internal links
+
+## Content-Only Migrations
+
+### WXR (WordPress eXtended RSS)
+- Standard WordPress export format
+- Includes: posts, pages, comments, categories, tags, custom fields
+- Does NOT include: themes, plugins, settings, users (partial)
+- Good for: Moving content between WordPress installations
+
+### REST API Transfer
+- Programmatic content transfer via WP REST Bridge
+- Includes: any content accessible via API
+- Advantage: Can transform content during transfer
+- Advantage: Can selectively migrate (filter by date, category, etc.)
+
+### Database-Level Transfer
+- Direct database export/import
+- Includes: everything in the database
+- Requires: URL search-replace after transfer
+- Risk: Higher, as database structure must match
+
+## URL Search and Replace
+
+After any migration, URLs in the database need updating:
+
+### Serialized Data Safe Methods
+```bash
+# wp-cli (recommended)
+wp search-replace 'https://old.com' 'https://new.com' --all-tables --precise
+
+# Better Search Replace plugin (GUI-based)
+# Settings → Better Search Replace → search/replace in all tables
+```
+
+### Never Use Raw SQL for URL Replace
+```sql
+-- DON'T DO THIS — breaks serialized data
+UPDATE wp_posts SET post_content = REPLACE(post_content, 'old.com', 'new.com');
+```
+Serialized PHP data (in wp_options, wp_postmeta) contains string length prefixes. Raw SQL REPLACE corrupts these.
+
+## DNS Migration Checklist
+
+1. **48h before**: Lower TTL to 300 (5 minutes)
+2. **Migration day**: Perform migration, verify on new host
+3. **DNS switch**: Update A record to new host IP
+4. **Monitor**: Check propagation via DNS checker tools
+5. **48h after**: Raise TTL back to 3600 (1 hour)
+6. **1 week after**: Decommission old hosting (if confirmed working)

package/skills/wp-migrate/references/hostinger-migration.md

@@ -0,0 +1,86 @@
+# Hostinger Migration Reference
+
+## Using hosting_importWordpressWebsite
+
+The Hostinger MCP provides `hosting_importWordpressWebsite` for full site imports.
+
+### Input Requirements
+- **Archive file**: zip or tar.gz containing WordPress files
+- **SQL dump**: Database backup file
+
+### Preparation
+
+#### 1. Export Database from Source
+```bash
+# Via SSH on source server
+mysqldump -u [db_user] -p [db_name] > /tmp/site-backup.sql
+
+# Or via wp-cli
+wp db export /tmp/site-backup.sql
+```
+
+#### 2. Package WordPress Files
+```bash
+# From WordPress root directory
+tar -czf /tmp/wp-files.tar.gz -C /path/to/wordpress .
+
+# Or selective (wp-content only, faster)
+tar -czf /tmp/wp-content.tar.gz -C /path/to/wordpress/wp-content .
+```
+
+#### 3. Import to Hostinger
+Use `hosting_importWordpressWebsite` with:
+- The archive file path
+- The SQL dump file path
+
+**WARNING**: This overwrites the existing WordPress installation on the destination.
+
+## Post-Import Steps
+
+### URL Search and Replace
+After migration, update URLs in the database:
+
+```bash
+# Via wp-cli on Hostinger (SSH)
+wp search-replace 'https://old-domain.com' 'https://new-domain.com' --all-tables
+
+# Or using a plugin: Better Search Replace
+```
+
+### File Permissions
+Hostinger standard permissions:
+```
+Directories: 755
+Files: 644
+wp-config.php: 440
+```
+
+```bash
+# Fix permissions via SSH
+find /home/[user]/htdocs/[domain]/ -type d -exec chmod 755 {} \;
+find /home/[user]/htdocs/[domain]/ -type f -exec chmod 644 {} \;
+chmod 440 /home/[user]/htdocs/[domain]/wp-config.php
+```
+
+### DNS Configuration
+After import, update DNS to point to Hostinger:
+1. Get Hostinger's IP via `hosting_listWebsites`
+2. Update A record via `DNS_updateDNSRecordsV1`
+3. Verify with `DNS_validateDNSRecordsV1`
+
+## Hostinger-Specific Paths
+
+```
+Web root:   /home/[username]/htdocs/[domain]/
+Plugins:    /home/[username]/htdocs/[domain]/wp-content/plugins/
+Themes:     /home/[username]/htdocs/[domain]/wp-content/themes/
+Uploads:    /home/[username]/htdocs/[domain]/wp-content/uploads/
+wp-config:  /home/[username]/htdocs/[domain]/wp-config.php
+```
+
+## Rollback
+
+If migration fails:
+1. The original source site should still be intact (never delete source first)
+2. On Hostinger, re-import from a pre-migration backup
+3. Revert DNS changes if domain was already pointed to new host

package/skills/wp-performance/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: wp-performance
+description: "Use when investigating or improving WordPress performance (backend-only agent): profiling and measurement (WP-CLI profile/doctor, Server-Timing, Query Monitor via REST headers), database/query optimization, autoloaded options, object caching, cron, HTTP API calls, and safe verification."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Backend-only agent; prefers WP-CLI (doctor/profile) when available."
+version: 1.0.0
+source: "WordPress/agent-skills (GPL-2.0-or-later)"
+---
+
+# WP Performance (backend-only)
+
+## When to use
+
+Use this skill when:
+
+- a WordPress site/page/endpoint is slow (frontend TTFB, admin, REST, WP-Cron)
+- you need a profiling plan and tooling recommendations (WP-CLI profile/doctor, Query Monitor, Xdebug/XHProf, APMs)
+- you’re optimizing DB queries, autoloaded options, object caching, cron tasks, or remote HTTP calls
+
+This skill assumes the agent cannot use a browser UI. Prefer WP-CLI, logs, and HTTP requests.
+
+## Inputs required
+
+- Environment and safety: dev/staging/prod, any restrictions (no writes, no plugin installs).
+- How to target the install:
+  - WP root `--path=<path>`
+  - (multisite/site targeting) `--url=<url>`
+- The performance symptom and scope:
+  - which URL/REST route/admin screen
+  - when it happens (always vs sporadic; logged-in vs logged-out)
+
+## Procedure
+
+### 0) Guardrails: measure first, avoid risky ops
+
+1. Confirm whether you may run write operations (plugin installs, config changes, cache flush).
+2. Pick a reproducible target (URL or REST route) and capture a baseline:
+   - TTFB/time with `curl` if possible
+   - WP-CLI profiling if available
+
+Read:
+- `references/measurement.md`
+
+### 1) Generate a backend-only performance report (deterministic)
+
+Run:
+
+- `node skills/wp-performance/scripts/perf_inspect.mjs --path=<path> [--url=<url>]`
+
+This detects:
+
+- WP-CLI availability and core version
+- whether `wp doctor` / `wp profile` are available
+- autoloaded options size (if possible)
+- object-cache drop-in presence
+
+### 2) Fast wins: run diagnostics before deep profiling
+
+If you have WP-CLI access, prefer:
+
+- `wp doctor check`
+
+It catches common production foot-guns (autoload bloat, SAVEQUERIES/WP_DEBUG, plugin counts, updates).
+
+Read:
+- `references/wp-cli-doctor.md`
+
+### 3) Deep profiling (no browser required)
+
+Preferred order:
+
+1. `wp profile stage` to see where time goes (bootstrap/main_query/template).
+2. `wp profile hook` (optionally with `--url=`) to find slow hooks/callbacks.
+3. `wp profile eval` for targeted code paths.
+
+Read:
+- `references/wp-cli-profile.md`
+
+### 4) Query Monitor (backend-only usage)
+
+Query Monitor is normally UI-driven, but it can be used headlessly via REST API response headers and `_envelope` responses:
+
+- Authenticate (nonce or Application Password).
+- Request REST responses and inspect headers (`x-qm-*`) and/or the `qm` property when using `?_envelope`.
+
+Read:
+- `references/query-monitor-headless.md`
+
+### 5) Fix by category (choose the dominant bottleneck)
+
+Use the profile output to pick *one* primary bottleneck category:
+
+- **DB queries** → reduce query count, fix N+1 patterns, improve indexes, avoid expensive meta queries.
+  - `references/database.md`
+- **Autoloaded options** → identify the biggest autoloaded options and stop autoloading large blobs.
+  - `references/autoload-options.md`
+- **Object cache misses** → introduce caching or fix cache key/group usage; add persistent object cache where appropriate.
+  - `references/object-cache.md`
+- **Remote HTTP calls** → add timeouts, caching, batching; avoid calling remote APIs on every request.
+  - `references/http-api.md`
+- **Cron** → reduce due-now spikes, de-duplicate events, move heavy tasks out of request paths.
+  - `references/cron.md`
+
+### 6) Verify (repeat the same measurement)
+
+- Re-run the same `wp profile` / `wp doctor` / REST request.
+- Confirm the performance delta and that behavior is unchanged.
+- If the fix is risky, ship behind a feature flag or staged rollout when possible.
+
+## WordPress 6.9 performance improvements
+
+Be aware of these 6.9 changes when profiling:
+
+**On-demand CSS for classic themes:**
+- Classic themes now get on-demand CSS loading (previously only block themes had this).
+- Reduces CSS payload by 30-65% by only loading styles for blocks actually used on the page.
+- If you're profiling a classic theme, this should already be helping.
+
+**Block themes with no render-blocking resources:**
+- Block themes that don't define custom stylesheets (like Twenty Twenty-Three/Four) can now load with zero render-blocking CSS.
+- Styles come from global styles (theme.json) and separate block styles, all inlined.
+- This significantly improves LCP (Largest Contentful Paint).
+
+**Inline CSS limit increased:**
+- The threshold for inlining small stylesheets has been raised, reducing render-blocking resources.
+
+Reference: https://make.wordpress.org/core/2025/11/18/wordpress-6-9-frontend-performance-field-guide/
+
+## Verification
+
+- Baseline vs after numbers are captured (same environment, same URL/route).
+- `wp doctor check` is clean (or improved) when applicable.
+- No new PHP errors or warnings in logs.
+- No cache flush is required for correctness (cache flush should be last resort).
+
+## Failure modes / debugging
+
+- “No change” after code changes:
+  - you measured a different URL/site (`--url` mismatch), caches masked results, or opcode cache is stale
+- Profiling data is noisy:
+  - eliminate background tasks, test with warmed caches, run multiple samples
+- `SAVEQUERIES`/Query Monitor causes overhead:
+  - don’t run in production unless explicitly approved
+
+## Escalation
+
+- If this is production and you don’t have explicit approval, do not:
+  - install plugins, enable `SAVEQUERIES`, run load tests, or flush caches during traffic
+- If you need system-level profiling (APM, PHP profiler extensions), coordinate with ops/hosting.

package/skills/wp-performance/references/autoload-options.md

@@ -0,0 +1,24 @@
+# Autoloaded options
+
+Autoloaded options are loaded on *every request*, so large autoload payloads can hurt performance site-wide.
+
+## Quick checks
+
+- Total autoload bytes:
+  - `wp option list --autoload=on --format=total_bytes`
+- Find biggest autoloaded options:
+  - `wp option list --autoload=on --fields=option_name,size_bytes | sort -n -k 2 | tail`
+
+Docs:
+
+- `wp option list`: https://wpcli.dev/docs/option/list
+- `wp doctor` includes an `autoload-options-size` check:
+  - https://make.wordpress.org/cli/handbook/doctor-default-checks/
+
+## Fix patterns
+
+- Stop autoloading large blobs:
+  - store large data in non-autoload options (autoload=off)
+  - move large computed data to transients/object cache
+- Remove stale options left behind by removed plugins/themes (careful: confirm usage before deleting).
+

package/skills/wp-performance/references/cron.md

@@ -0,0 +1,20 @@
+# WP-Cron performance
+
+Use this file when cron causes spikes or request-time slowness.
+
+Backend-only tools:
+
+- `wp cron test` (spawning health)
+- `wp cron event list`
+- `wp cron event run --due-now`
+
+Reference:
+
+- WP-CLI cron command package: https://github.com/wp-cli/cron-command
+
+Fix patterns:
+
+- De-duplicate scheduled events and reduce frequency where possible.
+- Ensure tasks are idempotent and short.
+- Move heavy work off-request; cron that runs on page load can hurt TTFB.
+

package/skills/wp-performance/references/database.md

@@ -0,0 +1,20 @@
+# Database / query performance
+
+Use this file when profiling points to DB time or high query counts.
+
+Common fixes:
+
+- Avoid N+1 query patterns (batch queries, prime caches, avoid per-row lookups).
+- Prefer `fields => 'ids'` when you only need IDs.
+- Avoid expensive meta queries where possible; consider indexing or schema changes.
+- Use object caching for repeated reads.
+
+Tools (backend-only):
+
+- Query Monitor (REST headers/envelope) for query lists and stack traces.
+- `wp db query` for targeted SQL/explain (be careful in prod).
+
+References:
+
+- Query Monitor plugin: https://wordpress.org/plugins/query-monitor/
+

package/skills/wp-performance/references/http-api.md

@@ -0,0 +1,15 @@
+# HTTP API (remote requests)
+
+Use this file when profiling shows slow external requests (`wp_remote_get`, etc.).
+
+Fix patterns:
+
+- Add timeouts and fail-fast behavior.
+- Cache responses where appropriate (transients/object cache).
+- Batch requests and avoid calling remote APIs on every page load.
+- Move heavy remote work to async (cron/queue) where possible.
+
+Tooling:
+
+- Query Monitor can report HTTP API calls (including timing) via REST envelope info.
+

package/skills/wp-performance/references/measurement.md

@@ -0,0 +1,21 @@
+# Measurement (profiling vs benchmarking)
+
+Backend-only measurement options:
+
+- **WP-CLI profiling** (`wp profile`): best for pinpointing slow hooks/stages without a browser.
+- **WP-CLI doctor** (`wp doctor`): best for quick diagnostics (autoload bloat, debug constants, updates).
+- **Query Monitor via REST**: use authenticated REST requests and inspect `x-qm-*` headers / `qm` envelope data.
+- **Server-Timing** (Performance Lab): inspect `Server-Timing` headers via `curl -I` (when enabled).
+- **APM/profilers**: New Relic, Datadog, Blackfire, Tideways, XHProf/Xdebug (requires server support).
+
+Best practices:
+
+- Always capture a baseline first.
+- Keep the test scenario fixed (same URL/route, same user state, same data).
+- Prefer multiple samples and medians over single runs.
+
+References:
+
+- Measuring performance handbook: https://make.wordpress.org/performance/handbook/measuring-performance/
+- Benchmarking with Server-Timing: https://make.wordpress.org/performance/handbook/measuring-performance/benchmarking-server-timing/
+

package/skills/wp-performance/references/object-cache.md

@@ -0,0 +1,24 @@
+# Object caching
+
+Use this file when profiling indicates repeated queries or low cache hit rate.
+
+## Concepts
+
+- Default WP object cache is per-request memory only.
+- A persistent object cache “drop-in” (`wp-content/object-cache.php`) can persist cache across requests.
+
+WP-CLI cache commands:
+
+- https://wpcli.dev/docs/cache
+
+Guardrails:
+
+- `wp cache flush` can impact all sites in multisite and cause load spikes:
+  - https://wpcli.dev/docs/cache/flush
+
+## Fix patterns
+
+- Cache expensive computed results (transients or object cache) with explicit invalidation.
+- Avoid unbounded caches (set expirations or implement invalidation hooks).
+- If adding a persistent object cache, coordinate with infra (Redis/Memcached) and test cache flush behavior.
+

package/skills/wp-performance/references/query-monitor-headless.md

@@ -0,0 +1,38 @@
+# Query Monitor (headless / backend-only)
+
+Query Monitor is UI-first, but it can expose useful data to backend-only tooling.
+
+## What it can show
+
+Query Monitor can help debug:
+
+- DB queries (slow/dupes/errors), hooks/actions, HTTP API calls, PHP errors
+
+Plugin page:
+
+- https://wordpress.org/plugins/query-monitor/
+
+Configuration constants:
+
+- https://querymonitor.com/help/configuration-constants/
+
+## REST API requests (no browser needed)
+
+Query Monitor can add performance/error info to authenticated REST responses.
+
+Docs:
+
+- https://querymonitor.com/wordpress-debugging/rest-api-requests/
+
+High-level approach:
+
+1. Authenticate (nonce or Application Password).
+2. Make a REST request and inspect response headers like `x-qm-overview-*`.
+3. If you request an enveloped response (`?_envelope`), you can get a `qm` property with:
+   - DB queries details, cache stats, HTTP API request details, etc.
+
+## Guardrails
+
+- Query Monitor adds some overhead; don’t enable it in production without approval.
+- If it’s already installed by your platform (e.g. VIP), you may need to grant `view_query_monitor`.
+

package/skills/wp-performance/references/server-timing.md

@@ -0,0 +1,22 @@
+# Server-Timing (Performance Lab)
+
+Use this file when you can enable Server-Timing metrics and want backend-only inspection via HTTP headers.
+
+Performance Lab plugin:
+
+- https://wordpress.org/plugins/performance-lab/
+
+Benchmarking guidance:
+
+- https://make.wordpress.org/performance/handbook/measuring-performance/benchmarking-server-timing/
+
+Backend-only approach:
+
+- Enable the relevant module/standalone plugin.
+- Request a URL and inspect the `Server-Timing` header:
+  - `curl -sS -D - https://example.test/ -o /dev/null | rg -i \"^server-timing:\"`
+
+Guardrails:
+
+- Don’t enable experimental modules in production without approval.
+

package/skills/wp-performance/references/wp-cli-doctor.md

@@ -0,0 +1,24 @@
+# WP-CLI doctor (`wp doctor`)
+
+Use this for quick “production readiness” checks.
+
+## Install (if missing)
+
+- `wp package install wp-cli/doctor-command`
+
+Docs:
+
+- Default checks: https://make.wordpress.org/cli/handbook/doctor-default-checks/
+- Customize checks: https://make.wordpress.org/cli/handbook/guides/doctor/doctor-customize-config/
+
+## Recommended usage
+
+- `wp doctor check`
+- `wp doctor list` (to see available checks)
+
+Especially relevant to performance:
+
+- `autoload-options-size` (autoloaded options threshold)
+- `constant-savequeries-falsy` / `constant-wp-debug-falsy` (avoid perf-costly debug flags in prod)
+- cron checks (count/duplicates)
+

package/skills/wp-performance/references/wp-cli-profile.md

@@ -0,0 +1,32 @@
+# WP-CLI profiling (`wp profile`)
+
+Use this when you need actionable profiling without a browser.
+
+## Install (if missing)
+
+`wp profile` comes from a WP-CLI package:
+
+- `wp package install wp-cli/profile-command`
+
+Docs:
+
+- https://wpcli.dev/docs/profile/stage
+- https://wpcli.dev/docs/profile/hook
+- https://wpcli.dev/docs/profile/eval
+
+## Recommended sequence
+
+1. Stage overview:
+   - `wp profile stage --fields=stage,time,cache_ratio [--url=<url>]`
+2. Hooks hotspot:
+   - `wp profile hook --spotlight [--url=<url>]`
+   - then drill into a specific hook:
+     - `wp profile hook init --spotlight [--url=<url>]`
+3. Targeted evaluation:
+   - `wp profile eval 'do_action(\"init\");' --hook=init`
+
+Tips:
+
+- Use `--url` to profile specific site/route behavior.
+- Use `--skip-plugins` / `--skip-themes` to isolate culprit components (careful: behavior changes).
+