@refactco/refact-os 1.5.0

package/templates/overlays/wordpress/agent/skills/wp-env/SKILL.md

@@ -0,0 +1,478 @@
+---
+name: wp-env
+description: Manage the local WordPress stack via wp-env — setup, pull plugins/mu-plugins/db from staging, reset, custom local domain.
+pattern: procedure
+when_to_use: /refact wp-env setup | pull [plugins|mu-plugins|db] | reset | domain <host>.
+when_not_to_use: Non-WordPress projects.
+next_skills: []
+sub_agents: []
+---
+
+# wp-env Reference
+
+Use this reference when the user invokes any of:
+
+- `/refact wp-env setup` — bring up a fresh local WordPress stack with a sample DB.
+- `/refact wp-env pull` — alias for **pull plugins + mu-plugins + db** (staging → local).
+- `/refact wp-env pull plugins`
+- `/refact wp-env pull mu-plugins`
+- `/refact wp-env pull db`
+- `/refact wp-env reset` — destroy containers + volumes and rebuild from scratch.
+- `/refact wp-env domain set <hostname>` — front the local env with a `.local` hostname over HTTPS via Caddy.
+- `/refact wp-env domain clear` — remove the hostname mapping and revert to `http://localhost:8888`.
+
+## What this does
+
+Manages the local WordPress development stack for engagements scaffolded with `/refact add codebase wordpress`. Local code lives in `apps/wordpress/wp-content/`, which is the same tree the Kinsta deploy workflows push (see [`kinsta-auto-deploy.md`](./kinsta-auto-deploy.md)). The local env mirrors staging by pulling plugins, mu-plugins, and the DB over SSH using the credentials in `agent/AGENTS.md`.
+
+## Canonical layout
+
+```
+<project-root>/
+├── .wp-env.json                          ← wp-env config (created by setup)
+├── apps/wordpress/
+│   └── wp-content/
+│       ├── plugins/                      ← rsync target for `pull plugins`
+│       ├── themes/                       ← (not pulled by default — usually in-repo)
+│       └── mu-plugins/                   ← rsync target for `pull mu-plugins`
+└── package.json                          ← gets `wp:*` scripts on setup
+```
+
+`.wp-env.json` maps `wp-content/{plugins,themes,mu-plugins}` from inside `apps/wordpress/wp-content/` so the container sees the same files the deploy workflow ships. **Never** create a parallel `./wp-content/` at the repo root — it splits the source of truth and breaks the Kinsta deploy filter.
+
+## Optional local domain (`<project>.local`)
+
+wp-env binds to `127.0.0.1:8888` by default. To use a hostname like `https://website.local` instead, this flow can layer a [Caddy](https://caddyserver.com) reverse proxy on top: Caddy issues a trusted local cert via its own CA, fronts wp-env on `:443`, and you get clean URLs without ports.
+
+The hostname is stored at `.refact-os.json` › `wpEnv.localDomain` so every teammate gets the same URL after `/refact wp-env setup`. Per-project Caddy config lives outside the repo at `~/.refact/caddy/<project-slug>.caddyfile`, imported by a global `~/.refact/Caddyfile`. See **Step 4 — `domain set` / `domain clear`** below.
+
+---
+
+## Preflight (always)
+
+1. `.refact-os.json` › `stack` has a `wordpress` entry. If not, stop and ask the user to confirm — this flow is WordPress-specific.
+2. `apps/wordpress/` exists. If not, delegate to [`add-codebase.md`](./add-codebase.md) Flow B (`/refact add codebase wordpress`), then continue.
+3. Docker is reachable: `docker info` exits 0. If not, stop and tell the user to start Docker Desktop / Colima.
+4. Node is **18+**: `node --version`. wp-env requires it.
+
+For `pull` flows only — also verify the SSH fields in `agent/AGENTS.md` are filled (not the literal `<ssh-staging-…>` placeholders). If any placeholder remains, stop and tell the user to run `/refact init` first.
+
+---
+
+## Step 1 — `setup`
+
+Idempotent. Each sub-step is verified independently; skip silently if already met.
+
+### 1a. Ensure `apps/wordpress/wp-content/` subfolders
+
+```bash
+mkdir -p apps/wordpress/wp-content/plugins
+mkdir -p apps/wordpress/wp-content/themes
+mkdir -p apps/wordpress/wp-content/mu-plugins
+```
+
+### 1b. Write `.wp-env.json` (skip if present)
+
+If `.wp-env.json` already exists, **inspect it**:
+
+- If it maps `wp-content/*` from `./apps/wordpress/wp-content/*` — leave the mappings alone. If a Caddy domain is configured, make sure neither `.wp-env.json` nor `.wp-env.override.json` defines `config.WP_HOME` / `config.WP_SITEURL`; see Step 3.
+- If it maps from `./wp-content/*` (the legacy layout) — show the diff and ask the user before rewriting. Some older scaffolds had `wp-content/` at the root; the new convention is `apps/wordpress/wp-content/` so deploy and local share one tree.
+
+Resolve the local URL **before** writing the config block:
+
+- If `.refact-os.json` › `wpEnv.localDomain` is set → `LOCAL_URL="https://<that-host>"`.
+- Otherwise → `LOCAL_URL="http://localhost:8888"`.
+
+Template body when creating:
+
+```json
+{
+  "$schema": "https://schemas.wp.org/trunk/wp-env.json",
+  "core": null,
+  "phpVersion": "8.2",
+  "themes": [],
+  "plugins": [],
+  "mappings": {
+    "wp-content/plugins":    "./apps/wordpress/wp-content/plugins",
+    "wp-content/themes":     "./apps/wordpress/wp-content/themes",
+    "wp-content/mu-plugins": "./apps/wordpress/wp-content/mu-plugins"
+  },
+  "config": {
+    "WP_DEBUG": true,
+    "WP_DEBUG_LOG": true,
+    "WP_DEBUG_DISPLAY": false,
+    "SCRIPT_DEBUG": true,
+    "WP_ENVIRONMENT_TYPE": "local"
+  }
+}
+```
+
+Omit `WP_HOME` / `WP_SITEURL` from `.wp-env.json` and `.wp-env.override.json`. wp-env defines its own URL constants and may force its internal `:8888` port into WordPress URLs; when Caddy is in use, keep the public hostname in the DB plus the local-only mu-plugin from Step 3 instead.
+
+### 1c. Install `@wordpress/env`
+
+If `@wordpress/env` is missing from `package.json` › `devDependencies`:
+
+```bash
+npm install --save-dev @wordpress/env
+```
+
+### 1d. Add `wp:*` scripts to `package.json`
+
+Add only the ones missing — never overwrite existing entries:
+
+| Script | Command |
+|---|---|
+| `wp:start` | `wp-env start` |
+| `wp:stop` | `wp-env stop` |
+| `wp:destroy` | `wp-env destroy` |
+| `wp:clean` | `wp-env clean all` |
+| `wp:logs` | `wp-env logs all` |
+| `wp:cli` | `wp-env run cli wp` |
+| `wp:shell` | `wp-env run cli bash` |
+
+### 1e. Start the stack
+
+```bash
+npx wp-env start
+```
+
+First run downloads images and may take a few minutes. If it fails on `port already in use`, surface the exact error — don't guess at an alternate port without asking.
+
+### 1f. Report
+
+Print to the user:
+
+- Site URL: `<LOCAL_URL>` (the value resolved in 1b — either `https://<domain>` or `http://localhost:8888`).
+- Admin URL: `<LOCAL_URL>/wp-admin` — login `admin` / `password` (wp-env defaults).
+- Test connectivity: `npm run wp:cli -- --info`.
+
+If a domain is configured but Caddy isn't running yet, also remind the user to run `/refact wp-env domain set <hostname>` (or, if already set, `caddy start --config ~/.refact/Caddyfile` to bring the proxy up).
+
+---
+
+## Step 2 — `pull`
+
+`/refact wp-env pull` runs **2b → 2c → 2d** in order. The single-target variants (`pull plugins` / `pull mu-plugins` / `pull db`) run just that step. All variants share the preflight in 2a.
+
+### 2a. Resolve SSH target from `agent/AGENTS.md`
+
+Parse the **SSH access** section of `agent/AGENTS.md`. The init flow fills these placeholders:
+
+| agent/AGENTS.md field | Variable |
+|---|---|
+| `<ssh-staging-user>` | `SSH_USER` |
+| `<ssh-staging-host>` | `SSH_HOST` |
+| `<ssh-staging-port>` | `SSH_PORT` |
+| `<staging-document-root>` | `DOC_ROOT` |
+| `<staging-url>` (from the branch→env table) | `STAGING_URL` |
+
+Build the SSH connection string:
+
+```bash
+SSH_TARGET="${SSH_USER}@${SSH_HOST}"
+SSH_OPTS="-p ${SSH_PORT}"
+```
+
+Verify the connection before doing anything destructive:
+
+```bash
+ssh ${SSH_OPTS} "${SSH_TARGET}" "test -d '${DOC_ROOT}/wp-content' && echo ok"
+```
+
+If it doesn't print `ok`, stop. Common causes: wrong port, SSH key not registered with the host, doc root path wrong.
+
+> **Production guard.** This flow only ever pulls from **staging**. If the user explicitly asks to pull from production, refuse and explain the safer path: pull staging instead, or have the user export a sanitized DB from prod manually. Production WP-CLI requires owner approval per `agent/AGENTS.md`.
+
+### 2b. Pull `plugins`
+
+```bash
+rsync -avz --delete \
+  -e "ssh ${SSH_OPTS}" \
+  --exclude='index.php' \
+  "${SSH_TARGET}:${DOC_ROOT}/wp-content/plugins/" \
+  apps/wordpress/wp-content/plugins/
+```
+
+Notes:
+
+- `--delete` mirrors staging exactly. Warn the user once: "this removes any local-only plugins under `apps/wordpress/wp-content/plugins/`. Confirm?" If they decline, drop `--delete`.
+- Some hosts inject plugins that don't belong in the repo (e.g. `kinsta-mu-plugins` lives in `mu-plugins/`, not here, so it shouldn't appear; but check). Don't auto-exclude anything beyond `index.php` without asking.
+- After the rsync, remind the user to inspect `git status` for new tracked paths in `apps/wordpress/wp-content/plugins/`. If something new should reach Kinsta on deploy, the nested `apps/wordpress/.gitignore` needs an explicit `!` exception — see [`kinsta-auto-deploy.md`](./kinsta-auto-deploy.md) § "Adding new tracked files".
+
+### 2c. Pull `mu-plugins`
+
+```bash
+rsync -avz --delete \
+  -e "ssh ${SSH_OPTS}" \
+  --exclude='index.php' \
+  --exclude='00-wp-env-local-url.php' \
+  --exclude='kinsta-mu-plugins/' \
+  --exclude='kinsta-mu-plugins.php' \
+  "${SSH_TARGET}:${DOC_ROOT}/wp-content/mu-plugins/" \
+  apps/wordpress/wp-content/mu-plugins/
+```
+
+The Kinsta-injected mu-plugin is excluded because Kinsta manages it server-side; it isn't useful locally and shouldn't end up in git. For other hosts (WP Engine's `wpengine-common`, Pantheon's `pantheon.php`, etc.), apply the same logic — ask the user if you spot one you don't recognize before adding it to the exclude list permanently.
+
+`00-wp-env-local-url.php` is a local-only helper created by `domain set`; keep excluding it so `pull mu-plugins --delete` doesn't remove the local Caddy URL fix.
+
+### 2d. Pull `db`
+
+The local stack **must be running** for this step. If `npx wp-env run cli wp core is-installed` errors, run `npx wp-env start` first.
+
+Resolve `LOCAL_URL` the same way Step 1b does: `https://<wpEnv.localDomain>` if it's set in `.refact-os.json`, otherwise `http://localhost:8888`.
+
+```bash
+# 1. Dump staging DB and pipe straight into the wp-env container.
+ssh ${SSH_OPTS} "${SSH_TARGET}" \
+  "cd '${DOC_ROOT}' && wp db export --single-transaction -" \
+  | npx wp-env run cli wp db import -
+
+# 2. Rewrite URLs from staging → local.
+npx wp-env run cli wp search-replace "${STAGING_URL}" "${LOCAL_URL}" \
+  --skip-columns=guid --all-tables
+
+# If the staging URL in wp_options has no trailing slash, make sure home/siteurl land exactly.
+npx wp-env run cli wp db query "UPDATE wp_options SET option_value='${LOCAL_URL}' WHERE option_name IN ('home','siteurl')"
+
+# 3. Flush caches.
+npx wp-env run cli wp cache flush
+```
+
+Print `STAGING_URL → LOCAL_URL` before running `search-replace` and ask the user to confirm. A bad replace can rewrite half the DB to the wrong host and is painful to undo.
+
+After import:
+
+- Reset the admin password so the user can log in locally:
+
+  ```bash
+  npx wp-env run cli wp user update admin --user_pass=password --skip-email
+  ```
+
+  (Skip silently if `admin` doesn't exist — some sites use a different super-admin username; surface the existing admin list with `wp user list --role=administrator` and ask the user.)
+
+- Remind the user to run `npm run wp:cli -- option get siteurl` to verify the rewrite landed.
+- If a Caddy domain is enabled, also verify `curl -k -I -L --max-redirs 1 "https://<hostname>/wp-admin/"` ends on `https://<hostname>/wp-login.php...`, **not** `https://<hostname>:8888/...`.
+
+If the staging host has no `wp-cli` on `$PATH`, **stop** rather than silently falling back — surface the error and the user can decide whether to install wp-cli on the server or pull a manual `mysqldump`. Don't invent a fallback in this flow.
+
+---
+
+## Step 3 — `domain set <hostname>` / `domain clear`
+
+Front the wp-env stack with a Caddy reverse proxy so the local site answers on `https://<hostname>` instead of `http://localhost:8888`. The hostname is stored in `.refact-os.json` › `wpEnv.localDomain`, the proxy config lives in `~/.refact/`, and `/etc/hosts` maps the name to `127.0.0.1`.
+
+### 3a. Preflight
+
+- `caddy` is on `$PATH`. If missing, stop and tell the user to install it (macOS: `brew install caddy`; Linux: see [caddyserver.com/docs/install](https://caddyserver.com/docs/install)).
+- The hostname ends in `.local`, `.test`, or `.localhost`. Refuse public-looking suffixes (`.com`, `.io`, etc.) — Caddy would try to reach Let's Encrypt and fail, and the user almost certainly meant a local-only name. If they really want a registered TLD, surface the risk and ask again.
+- The hostname is lowercase, kebab-case ASCII (`^[a-z0-9][a-z0-9-]*\.(local|test|localhost)$`).
+- wp-env is running (`docker ps | grep -q wordpress`). If not, run `npx wp-env start` first — Caddy needs the upstream up.
+
+### 3b. `domain set <hostname>`
+
+1. Persist the value:
+
+   ```jsonc
+   // .refact-os.json
+   {
+     "stack": {
+       "wordpress": { "hosting": null, "runtime": null, "environments": {} }
+     },
+     "wpEnv": {
+       "localDomain": "<hostname>"
+     }
+   }
+   ```
+
+   Read, merge, write back via the same JSON the rest of `/refact` uses — don't hand-edit other keys.
+
+2. Ensure the global Caddy scaffold exists:
+
+   ```bash
+   mkdir -p ~/.refact/caddy
+   ```
+
+   Write `~/.refact/Caddyfile` (only if missing):
+
+   ```caddyfile
+   # Managed by /refact wp-env. Per-project site blocks live in ~/.refact/caddy/.
+   {
+     # global options
+   }
+   import caddy/*.caddyfile
+   ```
+
+3. Write the per-project site block at `~/.refact/caddy/<project-slug>.caddyfile`. `<project-slug>` is `basename` of the project root, lowercased, with non-alphanumerics replaced by `-`:
+
+   ```caddyfile
+   <hostname> {
+     reverse_proxy 127.0.0.1:8888 {
+       # wp-env may emit redirects to its internal port. Keep browser traffic on Caddy's HTTPS origin.
+       header_down Location "https://<hostname>:8888/" "https://<hostname>/"
+       header_down Location "https://localhost:8888/" "https://<hostname>/"
+       header_down Location "http://localhost:8888/" "https://<hostname>/"
+     }
+   }
+   ```
+
+   If the file already exists for this slug, overwrite it — this verb is the source of truth for the project's site block.
+
+4. Trust the Caddy local CA (idempotent — silently noops if already trusted):
+
+   ```bash
+   caddy trust
+   ```
+
+   On macOS this prompts for a sudo password the first time so it can add the root cert to the system keychain. Surface the prompt to the user; do not bypass.
+
+5. Add the `/etc/hosts` entry. This requires `sudo`. Don't run `sudo` directly from the flow — print the exact command and ask the user to run it themselves:
+
+   ```bash
+   # The user runs this:
+   echo "127.0.0.1 <hostname>" | sudo tee -a /etc/hosts
+   ```
+
+   Before printing, check whether the entry already exists (`grep -E "^127\.0\.0\.1[[:space:]]+<hostname>$" /etc/hosts`). If it's there, skip this step silently.
+
+6. Start or reload Caddy:
+
+   ```bash
+   # If not already running:
+   caddy start --config ~/.refact/Caddyfile --adapter caddyfile
+
+   # If already running:
+   caddy reload --config ~/.refact/Caddyfile --adapter caddyfile
+   ```
+
+   Detect "already running" with `pgrep -x caddy` or `caddy list-modules` exit status. Don't try both — pick one and stick with it.
+
+7. Do **not** set `.wp-env.json` or `.wp-env.override.json` › `config.WP_HOME` / `config.WP_SITEURL` for the Caddy hostname. wp-env rewrites URL constants to include its internal `:8888` port, which causes browsers to follow HTTPS redirects to the plain-HTTP wp-env port and fail with `SSL_ERROR_RX_RECORD_TOO_LONG`. Keep the public URL in the DB instead, and restart the stack after Caddy config changes:
+
+   ```bash
+   npx wp-env stop
+   npx wp-env start
+   ```
+
+   If the DB already has the old URL baked in (it usually does — WP stores `siteurl` and `home` in `wp_options`), run a one-shot search-replace:
+
+   ```bash
+   npx wp-env run cli wp search-replace "http://localhost:8888" "https://<hostname>" \
+     --skip-columns=guid --all-tables
+   npx wp-env run cli wp db query "UPDATE wp_options SET option_value='https://<hostname>' WHERE option_name IN ('home','siteurl')"
+   npx wp-env run cli wp cache flush
+   ```
+
+   Confirm the source/target URLs with the user before running.
+
+8. Write a local-only mu-plugin at `apps/wordpress/wp-content/mu-plugins/00-wp-env-local-url.php` (substitute `<hostname>`). This file is intentionally ignored by `apps/wordpress/.gitignore`; do not add a gitignore exception for it.
+
+   ```php
+   <?php
+   /**
+    * Local wp-env URL overrides.
+    *
+    * This file is ignored by git via apps/wordpress/.gitignore and should not be
+    * deployed. It keeps browser-facing URLs on the Caddy HTTPS origin instead of
+    * wp-env's internal :8888 port.
+    */
+
+   if ( defined( 'WP_ENVIRONMENT_TYPE' ) && 'local' === WP_ENVIRONMENT_TYPE ) {
+       $local_url = 'https://<hostname>';
+
+       $rewrite_local_url = static function ( $url ) use ( $local_url ) {
+           if ( ! is_string( $url ) ) {
+               return $url;
+           }
+
+           return str_replace(
+               array(
+                   'https://<hostname>:8888',
+                   'http://<hostname>:8888',
+                   'https://localhost:8888',
+                   'http://localhost:8888',
+               ),
+               $local_url,
+               $url
+           );
+       };
+
+       add_filter( 'option_home', static fn () => $local_url, PHP_INT_MAX );
+       add_filter( 'option_siteurl', static fn () => $local_url, PHP_INT_MAX );
+
+       foreach ( array( 'home_url', 'site_url', 'admin_url', 'includes_url', 'content_url', 'plugins_url', 'network_site_url' ) as $url_filter ) {
+           add_filter( $url_filter, $rewrite_local_url, PHP_INT_MAX );
+       }
+   }
+   ```
+
+9. Verify the browser-facing URLs:
+
+   ```bash
+   npx wp-env run cli wp cache flush
+   npm run wp:cli -- option get home
+   npm run wp:cli -- option get siteurl
+   curl -k -I -L --max-redirs 1 "https://<hostname>/wp-admin/"
+   if curl -k -sS "https://<hostname>/wp-login.php" | grep ':8888'; then
+     echo "unexpected :8888 URL"
+   fi
+   ```
+
+   Expected: `home` and `siteurl` print `https://<hostname>`, `/wp-admin/` redirects to `https://<hostname>/wp-login.php?...`, and the login page contains no `:8888` asset/form URLs. If the browser shows `SSL_ERROR_RX_RECORD_TOO_LONG`, it is almost certainly following an HTTPS URL on `:8888`; inspect the `Location` header and login markup.
+
+10. Report:
+
+   - Site URL: `https://<hostname>`
+   - Admin URL: `https://<hostname>/wp-admin`
+   - Caddyfile: `~/.refact/caddy/<project-slug>.caddyfile`
+   - Local URL helper: `apps/wordpress/wp-content/mu-plugins/00-wp-env-local-url.php` (gitignored)
+   - That the value is persisted in `.refact-os.json` so other teammates pick it up on their next `/refact wp-env setup`.
+
+### 3c. `domain clear`
+
+1. Remove `wpEnv.localDomain` from `.refact-os.json` (delete the key; if `wpEnv` becomes empty, remove that too).
+2. Delete `~/.refact/caddy/<project-slug>.caddyfile`. If the directory is now empty, leave the directory in place — another project may need it.
+3. Delete `apps/wordpress/wp-content/mu-plugins/00-wp-env-local-url.php` if it exists.
+4. Reload Caddy if it's running (`caddy reload …`). Don't stop the global Caddy process — other projects may rely on it.
+5. Tell the user the `/etc/hosts` entry was **not** removed automatically (it's harmless and removing it would need another sudo prompt). Print the exact `sudo sed -i ''` command they can run if they want it gone.
+6. Keep `.wp-env.json` and `.wp-env.override.json` free of `WP_HOME` / `WP_SITEURL`, restart wp-env, then run a search-replace from `https://<old-hostname>` back to `http://localhost:8888` so the DB matches.
+
+### 3d. Multi-project caveat
+
+Caddy binds `:80` and `:443`, so only one Caddy process can run per machine. The `~/.refact/Caddyfile` `import` pattern handles this: each project owns its own site block under `~/.refact/caddy/`, and the single running Caddy serves all of them. **Don't** scaffold a project-local Caddyfile inside the repo — it would either bind-collide or get accidentally committed.
+
+If two projects pick the same hostname, the second `domain set` overwrites the first project's site block. Detect this in 4b step 3 — if the existing file's contents reference a different `127.0.0.1:<port>` upstream than what we're about to write, ask the user to confirm before overwriting.
+
+## Step 4 — `reset`
+
+```bash
+npx wp-env destroy
+npx wp-env start
+```
+
+`destroy` removes the MySQL volume; the next `start` rebuilds with the wp-env default sample install. **Local DB changes are lost** — confirm with the user before running. Files under `apps/wordpress/wp-content/` are not touched (they live on the host, not in the volume).
+
+After reset, the user typically wants `/refact wp-env pull db` to restore staging state.
+
+---
+
+## Guardrails
+
+- **`apps/wordpress/wp-content/` is the source of truth.** Never write to `./wp-content/` at the repo root — that's the legacy layout. If you find both, ask the user which one is current before any pull.
+- **Never pull from production.** The flow is staging-only. If the user explicitly insists on prod, stop and require explicit owner approval (per `agent/AGENTS.md` § Deployment safety).
+- **Never run `search-replace` without confirming the URLs.** A bad replace can rewrite half the DB to the wrong host and is painful to undo. Always print the source and target URL once before executing.
+- **Never `wp-env destroy` without confirmation.** It nukes the local DB. `reset` confirms; ad-hoc destroy elsewhere should too.
+- **Never invent a fallback** when staging's wp-cli or rsync isn't available. Surface the error, let the user decide.
+- **Never edit `agent/AGENTS.md` to fill missing SSH fields from this flow.** Send the user to `/refact init` so the placeholders are filled in one place.
+- **Never commit pulled DB dumps.** If you write a `.sql` file at any point during this flow, place it in a gitignored path (e.g. `./.wp-env-dumps/`) and delete it after import.
+- **Never write Caddyfiles into the project tree.** Per-project site blocks live under `~/.refact/caddy/`. Project-local files would either bind-collide with another project's Caddy instance or end up committed by accident.
+- **Never accept a public-TLD hostname** for `domain set` (`.com`, `.io`, etc.) without explicit user confirmation — Caddy would try Let's Encrypt and either fail or, worse, attempt ACME against a domain the user doesn't control.
+- **Never run `sudo` from this flow.** `/etc/hosts` edits and `caddy trust` print the command for the user to run; they keep the credential prompt in their own hands.
+
+## When to stop and ask the user
+
+- `git status` shows large, unexpected diffs after `pull plugins` (e.g. an entire vendored plugin you didn't know was there) → surface before staging the changes.
+- The staging URL parsed from `agent/AGENTS.md` doesn't match the user's stated staging URL → resolve before running `search-replace`.
+- A pull would `--delete` a local-only plugin that looks like work-in-progress (no matching commit history) → ask first.
+- The user asks to point this flow at a different remote (e.g. "pull from dev instead") → that's an architectural change; confirm whether to extend `agent/AGENTS.md` with a `<dev-*>` block or treat it as a one-off prompt.

package/templates/overlays/wordpress/wp-cli.yml.example

@@ -0,0 +1,46 @@
+# wp-cli.yml — remote environment aliases for this engagement.
+#
+# Copy this file to `wp-cli.yml` and fill in the host-specific values for your
+# project. Keep `wp-cli.yml` committed; it is non-secret routing only. SSH keys,
+# tokens, and passwords stay out of this file (1Password, OS keychain, ~/.ssh/).
+#
+# Once configured, agents and engineers run remote WP-CLI like:
+#   wp @staging plugin list
+#   wp @development cache flush
+#
+# Host-specific setup (SSH config, key registration, dashboards) lives in
+# 1Password and the host's own docs. WP Engine uses an SSH gateway with a
+# /sites/<env>/ layout; Kinsta uses a custom port per site; Pantheon uses
+# Terminus instead of WP-CLI aliases (see the Pantheon block below).
+
+# --- WP Engine example ------------------------------------------------------
+# Requires `~/.ssh/config` entries `wpe-staging` and `wpe-development`.
+# @staging:
+#   ssh: wpe-staging:/sites/<staging-env>
+# @development:
+#   ssh: wpe-development:/sites/<dev-env>
+
+# --- Kinsta example ---------------------------------------------------------
+# Requires `~/.ssh/config` entries `kinsta-staging` and `kinsta-development`
+# (each with the custom port from MyKinsta).
+# @staging:
+#   ssh: kinsta-staging:~/public
+# @development:
+#   ssh: kinsta-development:~/public
+
+# --- Generic SSH host -------------------------------------------------------
+# @staging:
+#   ssh: deploy@staging.example.com:/var/www/staging/public_html
+# @development:
+#   ssh: deploy@dev.example.com:/var/www/dev/public_html
+
+# --- Pantheon ---------------------------------------------------------------
+# Pantheon uses Terminus rather than WP-CLI aliases. Do not add `@staging` /
+# `@development` here for Pantheon projects; use:
+#   terminus remote:wp <site>.<env> -- <command>
+
+# --- Production -------------------------------------------------------------
+# Intentionally NOT defined here. Production WP-CLI requires explicit owner
+# approval and a verified backup (per .cursor/rules/30-security.mdc). When
+# approved, run it manually in a one-off shell — do not commit a
+# `@production` alias.