@rolepod/wplab 1.2.2 → 1.2.3

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "rolepod-wplab",
   "displayName": "Rolepod WPLab",
-  "version": "0.1.0",
-  "description": "Multi-target WordPress automation for AI agents — scaffold, audit, verify, safe ops via wp-cli + REST + scoped fs. Optional companion plugin unlocks execute-php + runtime introspection. MIT, rolepod ecosystem.",
+  "version": "1.2.2",
+  "description": "WordPress operations toolkit for Claude Code / Cursor / Codex / Gemini — wp-cli + REST + scoped fs + 62 MCP tools, opt-in companion plugin unlocks execute-php + runtime introspection + one-click pair setup.",
   "author": {
     "name": "nuttaruj",
     "url": "https://github.com/nuttaruj"
@@ -16,6 +16,9 @@
     "wp-cli",
     "automation",
     "rolepod",
-    "ai-agents"
+    "ai-agents",
+    "claude-code",
+    "cursor",
+    "codex"
   ]
 }

package/.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "rolepod-wplab": {
+      "command": "npx",
+      "args": ["-y", "@rolepod/wplab@latest", "serve"]
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "rolepod-wplab": {
+      "command": "npx",
+      "args": ["-y", "@rolepod/wplab@latest", "serve"]
+    }
+  }
+}

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to `@rolepod/wplab` are documented here. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.3] — 2026-05-26 — Install path fixes + README rewrite
+
+### Fixed
+
+- `.mcp.json` previously pointed at `${CLAUDE_PLUGIN_ROOT}/dist/bin/rolepod-wplab.js`. `dist/` is gitignored, so users who installed via `claude plugin install nuttaruj/rolepod-wplab` got a server that wouldn't spawn. Now uses `npx -y @rolepod/wplab@latest serve` — pulls from npm, always works.
+- `.claude-plugin/plugin.json` version was stuck at `0.1.0`. Now `1.2.2` (will sync to package.json version on each release).
+- `package.json` `files` referenced `.cursor-plugin` + `.codex-plugin` directories that never existed. Replaced with the real `.mcp.json` + `.cursor/mcp.json` configs.
+
+### Added
+
+- `.cursor/mcp.json` — drop-in workspace MCP config for Cursor IDE (per-project or global via `~/.cursor/mcp.json`).
+- New README written in [`rolepod-uiproof`](https://github.com/nuttaruj/rolepod-uiproof) style — concise headline, "What it helps with" action list, skills table, per-CLI install (Claude Code / Cursor / Codex / Gemini / Direct npm), Path A (pair) + Path B (manual) quick start, doctor output, "What's inside" tech summary.
+
+### Numbers
+
+- MCP tools: 62 (unchanged).
+- Tests: 141 passing.
+
 ## [1.2.2] — 2026-05-26 — Slim dist
 
 ### Changed

package/README.md

@@ -1,101 +1,205 @@
 # rolepod-wplab
 
-**Status:** v0.1.0 — PoC complete (Path C foundation). Not yet published to npm; use locally via `npm link` or `claude --plugin-dir`.
+**rolepod-wplab gives Claude Code, Cursor, Codex CLI, and Gemini CLI a full WordPress operations toolkit — so the AI can actually wp-cli, edit page builders, audit security, migrate dev→staging, and (opt-in) run guarded `execute-php` against any WordPress site instead of guessing.**
 
-Novamira-class WordPress operations toolkit for AI coding agents — default-safe wp-cli + REST + scoped filesystem, opt-in companion plugin ([`rolepod-wplab-companion`](https://github.com/nuttaruj/rolepod-wplab-companion)) for `execute-php` + runtime introspection. MIT, sibling of [rolepod-uiproof](https://github.com/nuttaruj/rolepod-uiproof) in the rolepod ecosystem.
+One MCP server, 62 tools, 11 skills, 4 connection kinds (local path / REST + App Password / SSH / Docker). Default-safe — runs wp-cli + REST + scoped fs out of the box. Install the [`rolepod-wplab-companion`](https://github.com/nuttaruj/rolepod-wplab-companion) WP plugin to unlock `execute-php` + runtime introspection + the **one-click pair** setup wizard.
 
-## Two layers
+## What it helps with
 
-| Layer | Install | Capability |
+- **Connect any WP install in one command.** `connect_local`, `connect_rest`, `connect_ssh`, `connect_docker` — same tool surface, four ways to reach a site. App Passwords stored in the OS keychain, never echoed.
+- **One-click pair via companion.** Admin opens Tools → WPLab Setup → clicks "⚡ Generate setup prompt" → pastes the prompt into the AI → AI calls `rolepod_wp_pair { siteurl, pair_token }` and is connected with full power tools. Token single-use, 60-min TTL.
+- **Edit page builders without leaving chat.** `divi_{read,write}`, `oxygen_{read,write}`, `bricks_{read,write}`, `elementor_{read,write}` — all backed up before overwrite.
+- **Bulk SEO + WPML + ACF + Woo writes.** `yoast_write`, `rankmath_write`, `wpml_write` (link translations, duplicate for translation), `woo_write` (bulk price updates), `acf_write`.
+- **Scaffold blocks, plugins, themes, patterns.** `scaffold_block`, `scaffold_plugin`, `scaffold_theme`, `scaffold_pattern` — register-block-type-ready files into existing themes/plugins.
+- **Audit + migrate across many sites.** `audit_security`, `audit_many` (consolidated report for N sites), `migrate_dryrun` + `migrate_data` (plugin version sync dev→staging), `clone` (full db + wp-content + URL rewrite).
+- **Diagnose + back up before risky ops.** `diagnose` (plugin conflicts / slow queries / large autoloads / php errors), `backup_create` + `backup_restore`, `cache_tool`, `cron_tool`, `mail_test`.
+- **Safe `execute-php` (companion only).** AST screen on Node side AND PHP side, production-block unconditional, append-only audit log.
+
+## The 11 skills
+
+| Skill | Wraps | What it does |
 |---|---|---|
-| **Default** | `claude --plugin-dir ./rolepod-wplab` (or marketplace once v0.5) | wp-cli + REST + scoped fs + 19 MCP tools (3 adapters for Elementor / WooCommerce / ACF read) |
-| **Power** (opt-in) | + install [`rolepod-wplab-companion`](https://github.com/nuttaruj/rolepod-wplab-companion) WP plugin + `ROLEPOD_WPLAB_PROFILE=power` | adds `execute-php`, `introspect`, adapter writes (v0.2+) |
+| `/wp-pair-setup` | `rolepod_wp_pair` | Redeem a companion-issued pair token → mint App Password → store in vault → open Target. Single-use, 60-min TTL. |
+| `/wp-health-check` | `rolepod_wp_health_check` | Versions, db_ok, rest_ok, wp_cli_ok, companion_ok, warnings. |
+| `/wp-scaffold-block` | `rolepod_wp_scaffold_block` | Generate `block.json` + `index.js` + `render.php` (dynamic) into an existing plugin. |
+| `/wp-scaffold-plugin` | `rolepod_wp_scaffold_plugin` | Plugin skeleton (REST endpoint + admin page + Gutenberg + CLI command). |
+| `/wp-scaffold-theme` | `rolepod_wp_scaffold_theme` | Theme skeleton (theme.json + functions.php + style.css + templates). |
+| `/wp-audit-security` | `rolepod_wp_audit_security` | Core/plugin/theme updates + weak admin scan + WP_DEBUG check. Markdown or JSON. |
+| `/wp-audit-woo` | `rolepod_wp_woo_read` | WooCommerce products / orders / settings / shipping / payments. |
+| `/wp-edit-elementor` | `rolepod_wp_elementor_{read,write}` | Dump + replace `_elementor_data` widget tree. Backs up first. |
+| `/wp-introspect` | `rolepod_wp_introspect` | Hooks / transients / options / request-state. Requires companion. |
+| `/wp-execute-php` | `rolepod_wp_execute_php` | PHP eval against the live runtime. Companion + `power` profile + non-prod. AST-screened. |
+| `/wp-migrate-dryrun` | `rolepod_wp_migrate_dryrun` | Plan diff between source + dest target before `migrate_data`. |
+
+Every skill is **single-backend** — calls the rolepod-wplab server and only this server. If the server is unavailable, the skill fails with a clear diagnostic.
+
+## Install
+
+Pick your CLI. All install paths share the same MCP server (`@rolepod/wplab` on npm) and the same skill set.
 
-## Quick start (local dev)
+### Claude Code (recommended)
 
 ```bash
-git clone https://github.com/nuttaruj/rolepod-wplab.git
-cd rolepod-wplab
-npm install
-npm run build
+# Install
+claude plugin marketplace add nuttaruj/rolepod-wplab
+claude plugin install rolepod-wplab@rolepod-wplab
+
+# Update
+claude plugin marketplace update rolepod-wplab
+claude plugin install rolepod-wplab@rolepod-wplab
+
+# Uninstall
+claude plugin uninstall rolepod-wplab@rolepod-wplab
+claude plugin marketplace remove rolepod-wplab
+```
+
+The plugin auto-registers the 11 `/wp-*` skills AND spawns the MCP server (`npx -y @rolepod/wplab@latest serve`) on session start.
+
+### Cursor IDE
 
-# Test with Claude Code:
-claude --plugin-dir ./
+Cursor's plugin marketplace is enterprise-only (Free / Pro cannot install marketplace plugins). For everyone else, drop the workspace MCP config:
 
-# Or register globally:
-npm link
-claude mcp add wplab -- rolepod-wplab
+```bash
+# Per project
+mkdir -p .cursor
+curl -fsSL https://raw.githubusercontent.com/nuttaruj/rolepod-wplab/main/.cursor/mcp.json -o .cursor/mcp.json
 
-# Verify:
-rolepod-wplab doctor
+# Or global (across every project)
+mkdir -p ~/.cursor
+curl -fsSL https://raw.githubusercontent.com/nuttaruj/rolepod-wplab/main/.cursor/mcp.json -o ~/.cursor/mcp.json
 ```
 
-## Connecting to a WP target
+Then **fully restart Cursor** — MCP servers load only at startup. Verify under **Settings → MCP**.
+
+Skills are not auto-registered under Cursor (no unified plugin format yet). The 62 MCP tools are still available; invoke them by name in chat (`Use rolepod_wp_pair to …`).
+
+### Codex CLI
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.rolepod-wplab]
+command = "npx"
+args = ["-y", "@rolepod/wplab@latest", "serve"]
+```
 
-**Local install** (filesystem path):
+### Gemini CLI
+
+```json
+// ~/.gemini/settings.json
+{
+  "mcpServers": {
+    "rolepod-wplab": {
+      "command": "npx",
+      "args": ["-y", "@rolepod/wplab@latest", "serve"]
+    }
+  }
+}
 ```
-> "เชื่อม WP ที่ /Users/me/Sites/my-wp"
-Lead → rolepod_wp_connect_local { path: "/Users/me/Sites/my-wp" }
+
+### Direct npm (any MCP-aware tool)
+
+```json
+{
+  "mcpServers": {
+    "rolepod-wplab": {
+      "command": "npx",
+      "args": ["-y", "@rolepod/wplab@latest", "serve"]
+    }
+  }
+}
 ```
 
-**Remote site** (REST + App Password):
+62 MCP tools (`rolepod_wp_*`) will appear in your client. Skills are not surfaced via this path — call the tools by name.
+
+## Quick start
+
+### Path A — one-click pair (recommended)
+
 ```bash
-# 1. WP admin → Users → Profile → Application Passwords → name "rolepod-wplab" → copy
-# 2. Store locally (never echoed to chat):
+# 1. Install companion plugin on your WP site
+wp plugin install \
+  https://github.com/nuttaruj/rolepod-wplab-companion/releases/download/v1.2.0/rolepod-wplab-companion-1.2.0.zip \
+  --activate
+
+# 2. WP admin → Tools → WPLab Setup → ⚡ Generate setup prompt → copy
+
+# 3. Paste prompt into Claude Code / Cursor / Codex / Gemini → AI calls rolepod_wp_pair → done
+```
+
+The pair token is single-use, 60-min TTL. Companion mints a WP Application Password named `wplab-pair-<UTC-timestamp>` under your admin user — revocable from `profile.php` at any time.
+
+### Path B — manual (no companion required)
+
+```bash
+# 1. Create an App Password: WP admin → Users → Profile → Application Passwords
+# 2. Store locally (vault uses OS keychain when available)
 rolepod-wplab credentials add walnutztudio.com
-# Username: admin
-# Application Password: ****
-# ✓ stored in keychain
+
+# 3. In your AI CLI:
+#    "เชื่อม walnutztudio.com แล้ว run health_check"
+# Lead → rolepod_wp_connect_rest { url: "https://walnutztudio.com" }
 ```
+
+Path B works without the companion plugin — you get all 62 tools EXCEPT `execute_php`, `introspect`, `hook_state`, `mail_test` (those need the companion).
+
+## Verify your setup
+
+```bash
+npx rolepod-wplab doctor
+```
+
 ```
-> "เชื่อม walnutztudio.com"
-Lead → rolepod_wp_connect_rest { url: "https://walnutztudio.com" }
+✓ Node ≥20                       24.14.0
+✓ rolepod-wplab MCP binary       1.2.2
+✓ wp-cli on PATH                 wp-cli 2.12.0
+✓ Credential vault writable      ~/.config/rolepod-wplab/credentials.json (or keychain)
+✓ Memory dir writable            ~/.config/rolepod-wplab/memory/
+• Docker daemon (optional)       Not running — only needed for connect_docker
+• SSH agent (optional)           Not configured — only needed for connect_ssh
 ```
 
-## 19 MCP tools available
+`✓` = ready · `•` = optional · `✗` = blocker.
 
-**Connectivity:** `connect_local`, `connect_rest`, `disconnect`, `health_check`
-**wp-cli passthrough:** `cli_run` (allow-listed)
-**REST CRUD:** `post_{get,list,create,update}`, `user_list`, `rest_request`
-**Options:** `option_{get,set}`
-**Database:** `db_query` (SELECT-only by default)
-**Filesystem:** `file_{read,write}` (scoped to `wp-content/{themes,plugins,uploads}` + `wp-config.php`)
-**Adapters (read):** `elementor_read`, `woo_read`, `acf_read`
+## What's inside
 
-All prefixed `rolepod_wp_*`. Schemas in `src/schema/tools.ts`.
+- **62 MCP tools** — connectivity (4 kinds) + wp-cli passthrough + typed CRUD + page-builder adapters (Elementor / Divi / Oxygen / Bricks) + SEO/i18n (Yoast / RankMath / WPML) + WooCommerce + ACF + forms (Gravity / CF7 / WPForms) + cron + cache + mail + clone + backup + diagnose + scaffold (block / plugin / theme / pattern) + REST dump + user sessions + companion-gated (execute_php / introspect / hook_state) + pair (one-click setup). All prefixed `rolepod_wp_*`.
+- **4 connection kinds** — `LocalTarget` (filesystem + wp-cli), `RestTarget` (HTTPS + App Password, no shell needed), `SshTarget` (node-ssh), `DockerTarget` (dockerode). Same `Target` interface, same tools.
+- **3 profiles** — `strict` / `personal` / `power`. Profile-gated capability map (`power` required for execute_php; `strict` blocks all destructive ops).
+- **Safety floor that always applies** — wp-cli allow-list (3-token prefix match, hard-block on `db reset`/`db drop`/`core multisite-convert`), DB SELECT-only by default, scoped fs (resolves symlinks; refuses paths outside `wp-content/{themes,plugins,uploads}` + `wp-config.php`), AST screen on every `execute_php` payload (Node side + PHP side), production-host glob match with unconditional block on power tools, HTTPS-only RestTarget, OS-keychain credential vault.
+- **Per-site memory** — `memory_recall` / `memory_note` / `memory_list` keep context between sessions at `~/.config/rolepod-wplab/memory/<site>/`. Local files, $0, no SaaS.
+- **Audit trail** — every companion `execute_php` writes append-only `wplab_audit_<id>.log` (mode 0600) + a 1000-entry FIFO in `wp_options`.
 
-## Safety defaults
+## Companion
 
-- **Allow-list** wp-cli (W-005) — `db reset`, `db drop`, `core multisite-convert` never run from MCP.
-- **SELECT-only** DB queries (W-007) by default; `allow_write: true` + `confirm: true` on prod.
-- **Scoped filesystem writes** (W-006) — `wp-content/{themes,plugins,uploads}` + `wp-config.php` only.
-- **Production guard** (W-008) — siteurl glob match against `ROLEPOD_WPLAB_PROD_HOSTS`; all write tools require `confirm: true` on match.
-- **HTTPS-only** RestTarget (W-017) — App Password never travels plaintext.
-- **Credentials in OS keychain** (W-018) — never in chat history, never in audit log.
+The [`rolepod-wplab-companion`](https://github.com/nuttaruj/rolepod-wplab-companion) WP plugin is optional. Without it, wplab is a complete wp-cli + REST + scoped fs toolkit. With it, you get:
 
-Power tools (with companion + `power` profile) add:
-- **AST screen** for execute-php payloads (Node-side + companion-side, defence in depth).
-- **Production-block unconditional** for execute-php — no override exists.
-- **Append-only audit log** for every execute-php call (success + rejection).
+- **One-click pair** — `Tools → WPLab Setup → ⚡ Generate setup prompt` produces a ready-to-paste prompt for any AI CLI.
+- **execute-php** — runtime PHP eval, AST-screened, production-blocked.
+- **introspect** — hooks / transients / options / request-state read at runtime.
+- **mid-request observation + persistent PHP session**.
 
-## Skills (4 in v0.1)
+```bash
+wp plugin install \
+  https://github.com/nuttaruj/rolepod-wplab-companion/releases/latest/download/rolepod-wplab-companion-1.2.0.zip \
+  --activate
+```
 
-- `/rolepod-wplab:wp-health-check` — diagnostic snapshot
-- `/rolepod-wplab:wp-scaffold-block` — Gutenberg block scaffold (composite lands v0.2)
-- `/rolepod-wplab:wp-scaffold-plugin` — plugin skeleton (composite lands v0.2)
-- `/rolepod-wplab:wp-audit-security` — CVE + outdated + perms audit (composite lands v0.2)
+## Use with parent rolepod
 
-v0.2 adds: `/wp-execute-php`, `/wp-introspect`, `/wp-edit-elementor`, `/wp-audit-woo`, `/wp-scaffold-theme`, `/wp-migrate-dryrun`.
+If you also use [`rolepod`](https://github.com/nuttaruj/rolepod) (the markdown plugin), its phase skills auto-route WP work to rolepod-wplab when the server is present. The two are **independent**: install rolepod-wplab standalone and get a complete experience via slash commands, or install both together and let parent's phase router pick the right backend automatically.
 
-## Sibling repos
+## Docs
 
-- [`rolepod-wplab-companion`](https://github.com/nuttaruj/rolepod-wplab-companion) — optional WP plugin for runtime PHP context.
-- [`rolepod-uiproof`](https://github.com/nuttaruj/rolepod-uiproof) — UI / mobile automation sibling.
+- [docs/RECIPES.md](docs/RECIPES.md) — 23 end-to-end recipes (connect, scaffold, audit, migrate, edit page builders, pair, diagnose, clone, backup).
+- [docs/MIGRATION-FROM-NOVAMIRA.md](docs/MIGRATION-FROM-NOVAMIRA.md) — coexistence flow + feature parity matrix.
+- [CHANGELOG.md](CHANGELOG.md) — release history (v0.0 → v1.2.2).
+- [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
 
-## Design
+## Sibling repos
 
-Path C stance (W-026): same capability ceiling as Novamira, default-safe posture, opt-in companion for runtime PHP context. Differentiation matrix + decision log in the [internal design brief](./brief/) (gitignored, maintainer-only — reconstructable from conversation context if lost).
+- [`rolepod-wplab-companion`](https://github.com/nuttaruj/rolepod-wplab-companion) — optional WP plugin for runtime PHP context + one-click pair.
+- [`rolepod-uiproof`](https://github.com/nuttaruj/rolepod-uiproof) — UI / mobile automation sibling.
 
-## License
+---
 
-MIT — see [LICENSE](./LICENSE). Clean-room from [Novamira](https://github.com/use-novamira/novamira) (AGPL-3.0); no Novamira code was read or copied.
+MIT licensed — see [LICENSE](LICENSE). Clean-room from [Novamira](https://github.com/use-novamira/novamira) (AGPL-3.0); no Novamira code was read or copied. Feedback + runtime reports for Cursor / Codex / Gemini install paths especially welcome via [issues](https://github.com/nuttaruj/rolepod-wplab/issues).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rolepod/wplab",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Novamira-class WordPress operations toolkit for AI coding agents — default-safe wp-cli + REST + scoped fs, opt-in companion for execute-php + runtime introspection. MIT, rolepod ecosystem.",
   "keywords": [
     "mcp",
@@ -34,8 +34,8 @@
     "dist",
     "skills",
     ".claude-plugin",
-    ".cursor-plugin",
-    ".codex-plugin",
+    ".mcp.json",
+    ".cursor/mcp.json",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"