claude-plugin-wordpress-manager 1.8.0 → 2.0.0

package/skills/wp-e2e-testing/SKILL.md

@@ -184,3 +184,7 @@ After completing the setup, verify:
 ## Recommended Agent
 
 For hands-on test execution, debugging, and CI setup, use the **`wp-test-engineer`** agent.
+
+### CI/CD Integration
+
+For integrating WordPress tests into CI/CD pipelines (GitHub Actions, GitLab CI, Bitbucket Pipelines), see the `wp-cicd` skill and `wp-cicd-engineer` agent.

package/skills/wp-multisite/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: wp-multisite
+description: |
+  This skill should be used when the user asks about "multisite", "network admin",
+  "sub-sites", "domain mapping", "super admin", "network activate",
+  "WordPress Multisite network", or any multisite network management operations.
+version: 1.0.0
+---
+
+## Overview
+
+WordPress Multisite network management via WP-CLI (10 MCP tools). Covers sub-site CRUD, network plugin management, Super Admin listing, network settings, and domain mapping guidance. Uses a hybrid approach: REST API where available, WP-CLI for network-only operations.
+
+## When to Use
+
+- User mentions multisite, network, sub-sites, or domain mapping
+- User needs to create, activate, deactivate, or delete sub-sites
+- User wants to network-activate or network-deactivate plugins
+- User needs Super Admin listing or network settings
+- User asks about migrating single-site to multisite or vice versa
+
+## Prerequisites
+
+WP-CLI access and multisite flag must be configured in `WP_SITES_CONFIG`:
+
+```json
+{
+  "id": "mynetwork",
+  "url": "https://network.example.com",
+  "username": "superadmin",
+  "password": "xxxx xxxx xxxx xxxx",
+  "wp_path": "/var/www/wordpress",
+  "ssh_host": "network.example.com",
+  "ssh_user": "deploy",
+  "ssh_key": "~/.ssh/id_rsa",
+  "is_multisite": true
+}
+```
+
+- `wp_path` — required for all wp-cli operations
+- `ssh_host` / `ssh_user` — required for remote sites (omit for local)
+- `is_multisite: true` — required flag to enable ms_* tools
+
+## Detection
+
+Run the detection script to check multisite presence:
+
+```bash
+node skills/wp-multisite/scripts/multisite_inspect.mjs
+```
+
+## Multisite Operations Decision Tree
+
+1. **Sub-site management?**
+   - List all sub-sites → `ms_list_sites`
+   - Get sub-site details → `ms_get_site`
+   - Create new sub-site → `ms_create_site`
+   - Activate/deactivate → `ms_activate_site`
+   - Delete sub-site → `ms_delete_site`
+
+2. **Network plugin management?**
+   - List all plugins (with network status) → `ms_list_network_plugins`
+   - Network-activate plugin → `ms_network_activate_plugin`
+   - Network-deactivate plugin → `ms_network_deactivate_plugin`
+
+3. **Network administration?**
+   - List Super Admins → `ms_list_super_admins`
+   - Get network settings → `ms_get_network_settings`
+
+4. **Domain mapping / network setup / migration?**
+   - See reference files below (no dedicated MCP tool — use wp-cli via Bash)
+
+## Recommended Agent
+
+For complex multi-step multisite operations, use the `wp-site-manager` agent (which has a dedicated Multisite Network Management section).
+
+## Additional Resources
+
+### Reference Files
+
+- **`references/network-setup.md`** — Sub-directory vs sub-domain, wp-config constants, installation
+- **`references/site-management.md`** — CRUD sub-sites, templates, bulk operations
+- **`references/domain-mapping.md`** — Custom domains, SSL, DNS CNAME, sunrise.php
+- **`references/network-plugins.md`** — Network-activated vs per-site plugins, must-use plugins
+- **`references/user-roles.md`** — Super Admin capabilities, site-level roles
+- **`references/migration-multisite.md`** — Single to multisite and back, database tables
+
+### Related Skills
+
+- `wp-wpcli-and-ops` — WP-CLI command reference and multisite flags
+- `wp-security` — Super Admin capabilities and multisite security
+- `wp-deploy` — Deploy to multisite network

package/skills/wp-multisite/references/domain-mapping.md

@@ -0,0 +1,70 @@
+# Domain Mapping
+
+Domain mapping allows each sub-site in a WordPress Multisite network to use its own custom domain instead of the default sub-directory or sub-domain URL.
+
+## Overview
+
+| Default URL | Mapped Domain |
+|-------------|---------------|
+| `network.com/shopA/` | `shopA.com` |
+| `shopB.network.com` | `shopB.com` |
+
+Since WordPress 4.5+, domain mapping is built into core (no plugin required for basic mapping).
+
+## Setup Procedure
+
+### 1. DNS Configuration
+
+For each custom domain, create a DNS record pointing to the network server:
+
+| Record Type | Name | Value |
+|-------------|------|-------|
+| A | `shopA.com` | `<server-ip>` |
+| CNAME | `www.shopA.com` | `shopA.com` |
+
+### 2. WordPress Configuration
+
+In Network Admin > Sites > Edit Site > Domain:
+- Change the site URL to the custom domain
+
+Or via WP-CLI:
+```bash
+wp site list  # find the blog_id
+wp option update home 'https://shopA.com' --url=network.com/shopA/
+wp option update siteurl 'https://shopA.com' --url=network.com/shopA/
+```
+
+### 3. SSL Certificate
+
+Each mapped domain needs its own SSL certificate:
+- **Let's Encrypt**: Use Certbot with `--domains shopA.com,shopB.com`
+- **Wildcard**: Only covers `*.network.com`, NOT custom domains
+- **Multi-domain SAN cert**: Can cover all mapped domains in one cert
+
+### 4. Web Server Configuration
+
+The web server must accept requests for all mapped domains. In Nginx:
+
+```nginx
+server {
+    server_name shopA.com shopB.com network.com *.network.com;
+    # ... standard WordPress config
+}
+```
+
+## sunrise.php (Advanced)
+
+For complex domain mapping logic, WordPress supports a `sunrise.php` drop-in:
+
+- Location: `wp-content/sunrise.php`
+- Loaded very early in the WordPress bootstrap (before plugins)
+- Must be enabled: `define('SUNRISE', true);` in wp-config.php
+- Used by plugins like "WordPress MU Domain Mapping" (legacy) or "Mercator"
+
+## Tips and Gotchas
+
+- **Cookie domain**: After mapping, update `COOKIE_DOMAIN` if login issues occur.
+- **Mixed content**: Ensure all mapped domains use HTTPS to avoid mixed content warnings.
+- **Caching**: Flush caches after domain mapping changes — both server-side and CDN.
+- **Search Console**: Register each mapped domain separately in Google Search Console.
+- **Reverse proxy**: If using Cloudflare or similar, configure the DNS to point to the origin server's IP, not the CDN.

package/skills/wp-multisite/references/migration-multisite.md

@@ -0,0 +1,76 @@
+# Migration: Single-site to Multisite and Back
+
+Migrating between single-site and multisite WordPress installations requires careful planning due to database structure differences.
+
+## Single-site to Multisite
+
+### Prerequisites
+- WordPress installed at domain root (not a subdirectory)
+- All plugins deactivated
+- Permalink structure using "pretty permalinks" (not plain)
+- Full database and file backup
+
+### Procedure
+
+1. **Backup**: Full database dump + wp-content directory
+2. **Deactivate all plugins** via wp-admin or wp-cli
+3. **Enable multisite**: Add `define('WP_ALLOW_MULTISITE', true);` to wp-config.php
+4. **Network Setup**: Navigate to Tools > Network Setup, choose sub-directory or sub-domain
+5. **Apply configuration**: Copy generated code to wp-config.php and .htaccess
+6. **Re-login**: WordPress redirects to login — sign in as Super Admin
+7. **Re-activate plugins**: One by one, test each plugin for multisite compatibility
+8. **Verify**: Check permalink structure, media uploads, and user roles
+
+### What Changes in the Database
+
+| Component | Before | After |
+|-----------|--------|-------|
+| Tables | `wp_posts`, `wp_options`, ... | Same (become site 1) |
+| New tables | — | `wp_blogs`, `wp_site`, `wp_sitemeta`, `wp_registration_log`, `wp_signups` |
+| Options | `wp_options` | `wp_options` (site 1) + `wp_sitemeta` (network) |
+
+## Multisite to Single-site
+
+This migration is more complex because you need to extract one sub-site from the network.
+
+### Procedure (extract sub-site)
+
+1. **Backup**: Full database dump + wp-content directory
+2. **Export content**: Use WordPress Export (Tools > Export) on the target sub-site
+3. **Fresh WordPress install**: Install a clean single-site WordPress
+4. **Import content**: Use WordPress Importer plugin
+5. **Copy uploads**: Copy `wp-content/uploads/sites/{blog_id}/` to `wp-content/uploads/`
+6. **Activate theme and plugins**: Install and activate the same theme and plugins
+7. **Verify**: Check media URLs, internal links, shortcodes
+
+### Alternative: Direct Database Extraction
+
+For large sites where export/import is impractical:
+
+1. Export tables with prefix `wp_{blog_id}_` (e.g., `wp_2_posts`, `wp_2_options`)
+2. Rename tables to standard prefix (e.g., `wp_2_posts` → `wp_posts`)
+3. Update `siteurl` and `home` in `wp_options`
+4. Search-replace old URLs in content
+5. Remove multisite constants from wp-config.php
+6. Update .htaccess to standard WordPress rules
+
+## WP-CLI Migration Commands
+
+```bash
+# Export single site from multisite
+wp db export site-backup.sql --url=subsite.example.com
+
+# Search-replace URLs after migration
+wp search-replace 'subsite.example.com' 'newdomain.com' --all-tables
+
+# Export content as WXR
+wp export --url=subsite.example.com --dir=/tmp/exports/
+```
+
+## Tips and Gotchas
+
+- **Media paths**: Multisite stores uploads in `uploads/sites/{blog_id}/`. After migration to single-site, media URLs need search-replace.
+- **User roles**: Users may have different roles on different sub-sites. When extracting, only the target site's role assignments transfer.
+- **Plugins**: Some plugins store network-wide options in `wp_sitemeta`. These are lost when extracting to single-site.
+- **Test first**: Always perform migration on a staging environment before production.
+- **Backup twice**: Keep backups of both the source (multisite) and target (single-site) before starting.

package/skills/wp-multisite/references/network-plugins.md

@@ -0,0 +1,66 @@
+# Network Plugins and Themes
+
+In WordPress Multisite, plugins and themes can be managed at the network level (Super Admin) or at the individual site level (Site Admin). Understanding the activation modes prevents conflicts.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `ms_list_network_plugins` | List all plugins with network activation status |
+| `ms_network_activate_plugin` | Activate a plugin across the entire network |
+| `ms_network_deactivate_plugin` | Deactivate a plugin from the entire network |
+
+## Plugin Activation Modes
+
+| Mode | Who Controls | Scope | Use Case |
+|------|-------------|-------|----------|
+| Network-activated | Super Admin | All sites | Security plugins, caching, essential functionality |
+| Per-site activated | Site Admin | One site | Site-specific features |
+| Must-use (mu-plugins) | Developer | All sites, always on | Core business logic, cannot be deactivated |
+
+## Procedures
+
+### Network-Activate a Plugin
+
+1. `ms_network_activate_plugin` with the plugin slug
+2. The plugin immediately activates on ALL sub-sites
+3. Site Admins cannot deactivate a network-activated plugin
+
+### Network-Deactivate a Plugin
+
+1. `ms_network_deactivate_plugin` with the plugin slug
+2. The plugin deactivates on ALL sub-sites simultaneously
+3. Per-site activation state is lost
+
+### Check Plugin Status
+
+1. `ms_list_network_plugins` — returns all plugins with their status
+2. Look for `network_only: true` in the response for network-activated plugins
+
+## Theme Management
+
+Themes in multisite work differently from plugins:
+
+| Action | Level | Effect |
+|--------|-------|--------|
+| Network Enable | Super Admin | Theme becomes available for site admins to activate |
+| Network Disable | Super Admin | Theme removed from site admin's theme list |
+| Activate | Site Admin | Theme becomes active for that specific site |
+
+A theme must be **network-enabled** before any site admin can use it.
+
+## Must-Use Plugins
+
+- Location: `wp-content/mu-plugins/`
+- Always active on ALL sites — cannot be deactivated via UI
+- Loaded before regular plugins
+- No activation hooks (code runs immediately)
+- Useful for: custom login, security rules, performance optimizations
+
+## Tips and Gotchas
+
+- **Network activation is immediate**: No confirmation dialog. All sites are affected instantly.
+- **Plugin conflicts**: A network-activated plugin may conflict with per-site plugins. Test thoroughly.
+- **Updates**: Plugin updates on multisite affect all sites. Test in staging first.
+- **Memory**: Each network-activated plugin increases memory usage across all sites.
+- **Drop-in replacements**: `object-cache.php`, `advanced-cache.php`, `db.php` are shared across all sites.

package/skills/wp-multisite/references/network-setup.md

@@ -0,0 +1,69 @@
+# Network Setup
+
+WordPress Multisite allows a single WordPress installation to host multiple websites (sub-sites) sharing the same codebase and database. Understanding the setup options is critical for architecture decisions.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `ms_get_network_settings` | View current network configuration |
+
+## Sub-directory vs Sub-domain
+
+| Mode | URL Pattern | Example | Requirements |
+|------|------------|---------|-------------|
+| Sub-directory | `example.com/site1/` | `example.com/blog/` | Default, works everywhere |
+| Sub-domain | `site1.example.com` | `blog.example.com` | Wildcard DNS (`*.example.com`), wildcard SSL |
+
+Decision factors:
+- **Sub-directory**: simpler DNS, single SSL cert, better for related sites
+- **Sub-domain**: each site feels independent, better for unrelated brands
+
+## wp-config.php Constants
+
+Required constants for multisite (set during network installation):
+
+```php
+define('WP_ALLOW_MULTISITE', true);     // Step 1: enables Network Setup menu
+define('MULTISITE', true);               // Step 2: after network creation
+define('SUBDOMAIN_INSTALL', false);      // true for sub-domain, false for sub-directory
+define('DOMAIN_CURRENT_SITE', 'example.com');
+define('PATH_CURRENT_SITE', '/');
+define('SITE_ID_CURRENT_SITE', 1);
+define('BLOG_ID_CURRENT_SITE', 1);
+```
+
+## Installation Procedure
+
+1. Start with a fresh single-site WordPress installation
+2. Add `define('WP_ALLOW_MULTISITE', true);` to wp-config.php
+3. Navigate to Tools > Network Setup in wp-admin
+4. Choose sub-directory or sub-domain
+5. WordPress generates the remaining constants and .htaccess rules
+6. Add the generated code to wp-config.php and .htaccess
+7. Log in again — Network Admin menu appears
+
+## .htaccess Rules (sub-directory mode)
+
+```apache
+RewriteEngine On
+RewriteBase /
+RewriteRule ^index\.php$ - [L]
+
+# add a trailing slash to /wp-admin
+RewriteRule ^([_0-9a-zA-Z-]+/)?wp-admin$ $1wp-admin/ [R=301,L]
+
+RewriteCond %{REQUEST_FILENAME} -f [OR]
+RewriteCond %{REQUEST_FILENAME} -d
+RewriteRule ^ - [L]
+RewriteRule ^([_0-9a-zA-Z-]+/)?(wp-(content|admin|includes).*) $2 [L]
+RewriteRule ^([_0-9a-zA-Z-]+/)?(.*\.php)$ $2 [L]
+RewriteRule . index.php [L]
+```
+
+## Tips and Gotchas
+
+- **Cannot switch modes**: You cannot change from sub-directory to sub-domain (or vice versa) after network creation without a fresh install or complex migration.
+- **Existing content**: If the single site already has content, sub-directory mode may conflict with existing page slugs.
+- **SSL**: Sub-domain mode requires wildcard SSL (`*.example.com`). Let's Encrypt supports wildcard via DNS-01 challenge.
+- **WP_ALLOW_MULTISITE vs MULTISITE**: `WP_ALLOW_MULTISITE` enables the setup UI; `MULTISITE` activates the network. They are different constants.

package/skills/wp-multisite/references/site-management.md

@@ -0,0 +1,67 @@
+# Site Management
+
+Sub-site lifecycle in a WordPress Multisite network: creating, configuring, activating/deactivating, and deleting sites.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `ms_list_sites` | List all sub-sites with status |
+| `ms_get_site` | Get details of a specific sub-site |
+| `ms_create_site` | Create a new sub-site |
+| `ms_activate_site` | Activate or deactivate a sub-site |
+| `ms_delete_site` | Permanently delete a sub-site |
+
+## Sub-site Lifecycle
+
+```
+Create → Active → [Deactivate → Archived/Spam/Deleted]
+                 → [Delete permanently]
+```
+
+## Common Procedures
+
+### List All Sub-sites
+
+1. `ms_list_sites` — returns blog_id, url, registered date, status for all sites
+2. Review the `archived`, `spam`, `deleted` flags for each
+
+### Create a New Sub-site
+
+1. `ms_create_site` with slug, title, admin email
+2. WordPress creates the sub-site with default theme and plugins
+3. The specified email becomes the sub-site admin
+
+### Deactivate a Sub-site
+
+1. `ms_activate_site` with `active: false` and the target blog_id
+2. Deactivated sites return a "This site has been archived" message to visitors
+3. Content and settings are preserved
+
+### Delete a Sub-site
+
+1. `ms_delete_site` with blog_id and `confirm: true`
+2. **Permanent**: removes all content, settings, and uploads for that sub-site
+3. Database tables for the sub-site are dropped
+
+## Site Properties
+
+| Property | Description |
+|----------|-------------|
+| `blog_id` | Unique numeric identifier |
+| `domain` | Domain name of the sub-site |
+| `path` | URL path (e.g., `/blog/` in sub-directory mode) |
+| `registered` | Creation timestamp |
+| `last_updated` | Last modification timestamp |
+| `public` | Whether the site appears in search results |
+| `archived` | Manually archived by network admin |
+| `spam` | Marked as spam |
+| `deleted` | Soft-deleted (not permanently removed) |
+
+## Tips and Gotchas
+
+- **Blog ID 1**: The main site always has `blog_id: 1`. Do not delete it.
+- **Uploads**: Each sub-site has its own uploads directory under `wp-content/uploads/sites/{blog_id}/`.
+- **Database tables**: Each sub-site gets its own set of tables with prefix `wp_{blog_id}_` (e.g., `wp_2_posts`, `wp_2_options`).
+- **Default content**: New sub-sites get a "Hello World" post and sample page, similar to a fresh WordPress install.
+- **Themes**: Sub-sites can only use themes that are network-enabled or network-activated. See `network-plugins.md`.

package/skills/wp-multisite/references/user-roles.md

@@ -0,0 +1,73 @@
+# User Roles in Multisite
+
+WordPress Multisite adds a Super Admin role above the standard role hierarchy. Users can have different roles on different sub-sites within the same network.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `ms_list_super_admins` | List all Super Admin users in the network |
+
+## Role Hierarchy
+
+| Role | Scope | Key Capabilities |
+|------|-------|-----------------|
+| Super Admin | Entire network | All capabilities on all sites, network settings, site CRUD |
+| Administrator | Single site | Full control of one sub-site (cannot install plugins/themes) |
+| Editor | Single site | Manage and publish all posts on one site |
+| Author | Single site | Publish own posts |
+| Contributor | Single site | Write drafts, cannot publish |
+| Subscriber | Single site | Read-only access |
+
+## Super Admin vs Administrator (Multisite)
+
+| Capability | Super Admin | Site Administrator |
+|-----------|-------------|-------------------|
+| Install plugins | Yes | No |
+| Install themes | Yes | No |
+| Create/delete sub-sites | Yes | No |
+| Network activate plugins | Yes | No |
+| Edit wp-config.php | Yes | No |
+| Manage network settings | Yes | No |
+| Edit files (theme/plugin editor) | Yes | No (disabled by default) |
+| Manage site users | Yes | Yes (own site only) |
+| Manage site options | Yes | Yes (own site only) |
+
+## User Registration Modes
+
+Network-wide setting (Network Admin > Settings):
+
+| Mode | Description |
+|------|-------------|
+| Registration disabled | No one can register |
+| User accounts may be registered | Users can register but not create sites |
+| Logged-in users may register new sites | Existing users can create sub-sites |
+| Both user accounts and sites can be registered | Open registration for users and sites |
+
+## Common Operations
+
+### List Super Admins
+1. `ms_list_super_admins` — returns usernames with super admin status
+
+### Add Super Admin (via wp-cli)
+```bash
+wp super-admin add username
+```
+
+### Remove Super Admin (via wp-cli)
+```bash
+wp super-admin remove username
+```
+
+### Add User to Sub-site (via wp-cli)
+```bash
+wp user set-role username editor --url=site1.example.com
+```
+
+## Tips and Gotchas
+
+- **Super Admin bypass**: Super Admins bypass all capability checks. Use this role sparingly.
+- **User exists once**: A user account exists once in the network but can have different roles on different sub-sites.
+- **Cannot demote yourself**: The last Super Admin cannot remove their own super admin status.
+- **wp-admin vs network-admin**: Super Admins see both site-level wp-admin and network-level wp-admin/network/.
+- **Plugin capability checks**: Plugins using `current_user_can()` should work correctly with multisite, but some older plugins may not distinguish Super Admin from site Administrator.

package/skills/wp-multisite/scripts/multisite_inspect.mjs

@@ -0,0 +1,160 @@
+/**
+ * multisite_inspect.mjs — Detect WordPress Multisite configuration.
+ *
+ * Scans for multisite indicators: wp-config.php constants, WP_SITES_CONFIG flags,
+ * sunrise.php (domain mapping), .htaccess multisite rewrite rules.
+ *
+ * Usage:
+ *   node multisite_inspect.mjs [--cwd=/path/to/check]
+ *
+ * Exit codes:
+ *   0 — multisite indicators found
+ *   1 — no multisite indicators found
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, env, stdout, exit } from 'node:process';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readFileSafe(filePath) {
+  try { return readFileSync(filePath, 'utf-8'); } catch { return null; }
+}
+
+function existsSafe(filePath) {
+  try { return existsSync(filePath); } catch { return false; }
+}
+
+// ---------------------------------------------------------------------------
+// Detectors
+// ---------------------------------------------------------------------------
+
+function detectWpConfig(cwd) {
+  const paths = [
+    join(cwd, 'wp-config.php'),
+    join(cwd, '../wp-config.php'),  // wp-config one level up (common setup)
+  ];
+
+  for (const p of paths) {
+    const content = readFileSafe(p);
+    if (!content) continue;
+
+    const multisite = /define\s*\(\s*['"]MULTISITE['"]\s*,\s*true\s*\)/i.test(content);
+    const subdomain = content.match(/define\s*\(\s*['"]SUBDOMAIN_INSTALL['"]\s*,\s*(true|false)\s*\)/i);
+    const domain = content.match(/define\s*\(\s*['"]DOMAIN_CURRENT_SITE['"]\s*,\s*['"]([^'"]+)['"]\s*\)/i);
+    const pathMatch = content.match(/define\s*\(\s*['"]PATH_CURRENT_SITE['"]\s*,\s*['"]([^'"]+)['"]\s*\)/i);
+
+    if (multisite) {
+      return {
+        found: true,
+        path: p,
+        subdomain_install: subdomain ? subdomain[1] === 'true' : null,
+        domain_current_site: domain ? domain[1] : null,
+        path_current_site: pathMatch ? pathMatch[1] : null,
+      };
+    }
+  }
+  return null;
+}
+
+function detectSitesConfig() {
+  const sitesJson = env.WP_SITES_CONFIG;
+  if (!sitesJson) return null;
+  try {
+    const sites = JSON.parse(sitesJson);
+    const msSites = sites.filter(s => s.is_multisite === true);
+    const cliSites = sites.filter(s => s.wp_path);
+    return {
+      multisite_sites: msSites.map(s => ({
+        id: s.id,
+        wp_path: s.wp_path || null,
+        ssh_host: s.ssh_host || null,
+        has_wpcli: !!s.wp_path,
+      })),
+      cli_ready_sites: cliSites.map(s => s.id),
+      count: msSites.length,
+    };
+  } catch { return null; }
+}
+
+function detectSunrise(cwd) {
+  const paths = [
+    join(cwd, 'wp-content/sunrise.php'),
+    join(cwd, 'sunrise.php'),
+  ];
+  for (const p of paths) {
+    if (existsSafe(p)) {
+      return { found: true, path: p };
+    }
+  }
+  return null;
+}
+
+function detectHtaccessMultisite(cwd) {
+  const content = readFileSafe(join(cwd, '.htaccess'));
+  if (!content) return null;
+
+  // WordPress multisite .htaccess has specific rewrite rules
+  const hasMultisiteRules = /RewriteRule\s+\.\s+index\.php/i.test(content) &&
+    (/upload/.test(content) || /files/.test(content) || /blogs\.dir/.test(content));
+
+  return hasMultisiteRules ? { found: true } : null;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwdArg = argv.find(a => a.startsWith('--cwd='));
+  const cwd = cwdArg ? resolve(cwdArg.split('=')[1]) : process.cwd();
+
+  const wpConfig = detectWpConfig(cwd);
+  const sitesConfig = detectSitesConfig();
+  const sunrise = detectSunrise(cwd);
+  const htaccess = detectHtaccessMultisite(cwd);
+
+  const signals = [];
+  if (wpConfig) signals.push('wp_config_multisite');
+  if (sitesConfig?.count > 0) signals.push('sites_config_multisite');
+  if (sunrise) signals.push('sunrise_domain_mapping');
+  if (htaccess) signals.push('htaccess_multisite_rules');
+
+  const report = {
+    tool: 'multisite_inspect',
+    version: '1.0.0',
+    timestamp: new Date().toISOString(),
+    cwd,
+    found: signals.length > 0,
+    signals,
+    details: {
+      wp_config: wpConfig || undefined,
+      sites_config: sitesConfig || undefined,
+      sunrise: sunrise || undefined,
+      htaccess: htaccess || undefined,
+    },
+    recommendations: [],
+  };
+
+  if (wpConfig && !sitesConfig?.count) {
+    report.recommendations.push('Multisite detected in wp-config.php but no site in WP_SITES_CONFIG has is_multisite: true');
+  }
+  if (sitesConfig?.count > 0) {
+    const noCli = sitesConfig.multisite_sites.filter(s => !s.has_wpcli);
+    if (noCli.length > 0) {
+      report.recommendations.push(`Sites without wp_path (no wp-cli access): ${noCli.map(s => s.id).join(', ')}`);
+    }
+    report.recommendations.push(`${sitesConfig.count} multisite network(s) configured — 10 ms_* tools available`);
+  }
+  if (sunrise) {
+    report.recommendations.push('sunrise.php detected — domain mapping is active');
+  }
+
+  stdout.write(JSON.stringify(report, null, 2) + '\n');
+  exit(signals.length > 0 ? 0 : 1);
+}
+
+main();