@refactco/refact-os 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ Notable changes to the refact-os standard and scaffolder.
 
 **Staying current:** a consumer repo updates with `npm run refact:update` (or `npx @refactco/refact-os init`). That refreshes the package-managed `agent/` payload, **prunes** skills this package has removed or renamed (safe — only skills the package previously shipped, never your own), regenerates `.cursor/` + `.claude/`, and flags `agent/AGENTS.md` drift for a manual merge. The version it last applied is recorded in `.refact-os.json` under `_scaffold.version`, and `init` prints the `old → new` transition so you can scan the entries below for anything needing manual action. Run `npm run refact:validate` afterward.
 
+## 1.6.0
+
+### Added
+- **`wp-env pull wp-config`** — new sub-command reads the staging `wp-config.php` via SSH and classifies each `define()` into the right local destination: scalar non-secrets → `.wp-env.json` `config`, secrets → `.wp-env.override.json` (gitignored), PHP arrays → a guarded local mu-plugin. Restart + verify included.
+- **Host-aware rsync excludes for `pull mu-plugins`.** The `pull mu-plugins` flow now reads `stack.wordpress.hosting` from `.refact-os.json` and automatically excludes host-injected system mu-plugins (Kinsta: `kinsta-mu-plugins/`; WP Engine: `wpengine-common/`, `mu-plugin.php`, etc.) so they don't end up in git.
+- **SSH access migration to `.refact-os.json`.** `init` now migrates SSH connection details from legacy `agent/AGENTS.md` blocks into the structured `stack.wordpress.environments.<env>.ssh` config, making `.refact-os.json` the single source of truth for all deploy/pull flows.
+
+### Changed
+- **Split `.gitignore` strategy for `apps/wordpress/`.** The wp-env skill now maintains a separate `apps/wordpress/.gitignore` for wp-content paths (local-only mu-plugins, override files) instead of appending to the root `.gitignore`.
+- **Large DB fallback.** `pull db` now uses a two-step dump-to-file approach (SSH export → `docker cp` → `wp db import`) instead of piping directly, preventing stalls on databases larger than ~500 MB.
+- **Release flow is now local-only.** Removed dependency on CI `NPM_TOKEN`; publishing uses the maintainer's interactive `npm login` session with 2FA OTP (see `agent/skills/release/SKILL.md`).
+
 ## 1.5.2
 
 ### Added

package/bin/refact-os.js

@@ -72,6 +72,11 @@ async function runScaffold(args, { force }) {
   if (result.missingFields && result.missingFields.length > 0) {
     console.log(`Missing metadata (re-asked on next /refact run): ${result.missingFields.join(", ")}`);
   }
+  if (result.agentsMigration && result.agentsMigration.sshLifted) {
+    const { env, fields } = result.agentsMigration.sshLifted;
+    console.log(`Lifted SSH routing from agent/AGENTS.md → .refact-os.json (stack.wordpress.environments.${env}: ${fields.join(", ")}).`);
+    console.log("  You can now delete the '## SSH access' section from agent/AGENTS.md — .refact-os.json is the single source of truth.");
+  }
   if (result.contractChanged) {
     console.log("");
     console.log("⚠  agent/AGENTS.md template changed upstream. Your copy was preserved (skipIfExists).");

package/lib/refact-config.js

@@ -140,6 +140,63 @@ function _readIfExists(p) {
   }
 }
 
+// Parse a legacy "## SSH access (staging)" block out of an AGENTS.md. Older
+// scaffolds (pre-2026-05) wrote the staging SSH routing as a Markdown table:
+//
+//   ## SSH access (staging)
+//   | Field | Value |
+//   |---|---|
+//   | Host | `stlmagstg.ssh.wpengine.net` |
+//   | User | `stlmagstg` |
+//   | Port | `22` |
+//   | Document root | `sites/stlmagstg/` |
+//   | Staging URL | `https://stlmagstg.wpenginepowered.com` |
+//
+// `.refact-os.json` is now the single source of truth (see the wp-env skill).
+// This parser is the one-way migration lift: it pulls a filled block out of
+// AGENTS.md so a consumer that hasn't touched the schema gets its `staging.ssh`
+// populated automatically on the next `init`. Returns null if the block is
+// absent, any required row is missing, or any value is still a `<placeholder>`.
+function _parseAgentsSshBlock(agentsContent) {
+  if (typeof agentsContent !== "string" || agentsContent.length === 0) return null;
+  const headingMatch = agentsContent.match(/^##\s+SSH\s+access[^\n]*$/im);
+  if (!headingMatch) return null;
+  const startIdx = headingMatch.index + headingMatch[0].length;
+  const remainder = agentsContent.slice(startIdx);
+  const nextHeading = remainder.match(/^##\s+/m);
+  const block = nextHeading ? remainder.slice(0, nextHeading.index) : remainder;
+
+  const rowRe = /^\|\s*([^|]+?)\s*\|\s*`?([^`|\n]+?)`?\s*\|\s*$/gm;
+  const rows = {};
+  let m;
+  while ((m = rowRe.exec(block)) !== null) {
+    const label = m[1].toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+    const value = m[2].trim();
+    if (!value) continue;
+    if (/^<.*>$/.test(value)) continue; // skip unfilled placeholders
+    if (/^[-:|\s]+$/.test(value)) continue; // skip the header separator row
+    rows[label] = value;
+  }
+
+  const host = rows.host;
+  const user = rows.user;
+  const portRaw = rows.port;
+  const docRoot = rows["document root"] || rows["doc root"];
+  const stagingUrl = rows["staging url"] || rows["url"];
+  if (!host || !user || !portRaw || !docRoot) return null;
+  const port = Number(portRaw);
+  if (!Number.isFinite(port) || port <= 0) return null;
+
+  const result = {
+    user,
+    host,
+    port,
+    path: docRoot.replace(/\/+$/, ""), // strip trailing slash to match new schema
+  };
+  if (stagingUrl) result.url = stagingUrl;
+  return result;
+}
+
 function _stripScaffoldMetadataSection(agentsContent) {
   const lines = agentsContent.split("\n");
   const startIdx = lines.findIndex((line) => /^##\s+Scaffold Metadata\s*$/.test(line));
@@ -271,15 +328,60 @@ function migrateFromAgents(targetDir, config) {
     }
   }
 
+  // Lift a filled "## SSH access (staging)" block from AGENTS.md into
+  // .refact-os.json › stack.wordpress.environments.<staging-like>.ssh. One-way
+  // and idempotent: if the JSON already has the ssh routing for the staging-like
+  // env, do nothing. (The new wp-env skill reads SSH only from .refact-os.json.)
+  let sshLifted = null;
+  const wpEntry = config.stack && config.stack.wordpress;
+  if (wpEntry && proseSource) {
+    if (!wpEntry.environments || typeof wpEntry.environments !== "object" || Array.isArray(wpEntry.environments)) {
+      wpEntry.environments = {};
+    }
+    // Prefer an existing staging-like env to avoid creating a duplicate next to
+    // a project's `stage` (or similar) key. Fall back to creating `staging` only
+    // if nothing staging-shaped exists yet.
+    let stagingKey = null;
+    for (const candidate of ["staging", "stage"]) {
+      if (wpEntry.environments[candidate]) {
+        stagingKey = candidate;
+        break;
+      }
+    }
+    const existingEnv = stagingKey ? wpEntry.environments[stagingKey] : null;
+    const sshAbsent =
+      !existingEnv ||
+      !existingEnv.ssh ||
+      typeof existingEnv.ssh !== "object" ||
+      !existingEnv.ssh.host ||
+      !existingEnv.ssh.user ||
+      !existingEnv.ssh.port ||
+      !existingEnv.ssh.path;
+    if (sshAbsent) {
+      const parsed = _parseAgentsSshBlock(proseSource);
+      if (parsed) {
+        const targetKey = stagingKey || "staging";
+        const env =
+          wpEntry.environments[targetKey] ||
+          (wpEntry.environments[targetKey] = { branch: null, url: null });
+        env.ssh = { user: parsed.user, host: parsed.host, port: parsed.port, path: parsed.path };
+        if (parsed.url && !env.url) env.url = parsed.url;
+        sshLifted = { env: targetKey, fields: ["user", "host", "port", "path", ...(parsed.url && !existingEnv?.url ? ["url"] : [])] };
+        migrated = true;
+      }
+    }
+  }
+
   // Strip the legacy "## Scaffold Metadata" section from the root AGENTS.md.
+  let stripped = false;
   if (rootText != null) {
-    const stripped = _stripScaffoldMetadataSection(rootText);
-    if (stripped !== rootText) {
-      fs.writeFileSync(rootPath, stripped, "utf8");
-      return { migrated, stripped: true };
+    const strippedText = _stripScaffoldMetadataSection(rootText);
+    if (strippedText !== rootText) {
+      fs.writeFileSync(rootPath, strippedText, "utf8");
+      stripped = true;
     }
   }
-  return { migrated, stripped: false };
+  return { migrated, stripped, sshLifted };
 }
 
 function setAsanaProjectId(config, raw) {
@@ -320,5 +422,5 @@ module.exports = {
   ensureStack,
   setAsanaProjectId,
   askAsanaProjectId,
-  _internal: { _get, _set, _has, _parseProjectTypeFromAgents, _parseAgentsField, _stripScaffoldMetadataSection },
+  _internal: { _get, _set, _has, _parseProjectTypeFromAgents, _parseAgentsField, _parseAgentsSshBlock, _stripScaffoldMetadataSection },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@refactco/refact-os",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Installable scaffolder for the agent-first repo standard: minimum-seed substrate + canonical agent/ skill catalog with generated tool adapters",
   "keywords": [
     "agent",

package/templates/base/README.md

@@ -7,10 +7,24 @@ A Refact engagement scaffolded by [`refact-os`](https://github.com/refactco/refa
 ## Quickstart
 
 ```bash
-npm install
-cp .env.example .env       # fill in per-user tokens
+npm install                 # installs the @refactco/refact-os devDependency + others
+cp .env.example .env        # fill in per-user tokens
 ```
 
+## WordPress quickstart
+
+If this is a WordPress engagement (`.refact-os.json` › `stack.wordpress` present), open the repo in Cursor / Claude Code and run, in order:
+
+```
+/refact init                # idempotent checklist: stack, hosting, per-env (url/branch/install/ssh), .env, git
+/refact wp-env setup        # one-shot: containers up + plugins/mu-plugins/DB from staging + local domain
+/refact setup wpengine deploy   # or: /refact setup kinsta deploy — generates .github/workflows/wordpress-deploy-*.yml
+```
+
+Each command is **idempotent**: re-running on a fully-configured project is a no-op, so a teammate joining later just runs the same sequence and gets prompted for nothing the owner already filled in. Stack/hosting/SSH routing lives in `.refact-os.json`; per-user secrets (tokens, etc.) stay in `.env`. SSH **private keys** for auto-deploy live in GitHub Actions secrets, never in the repo.
+
+Delete this section if this isn't a WordPress project.
+
 ## Where things live
 
 | Path | What's in it |

package/templates/base/agent/skills/adopt/SKILL.md

@@ -35,6 +35,7 @@ Produce a **plan** for bringing an existing repo to the agent-first standard. Th
    - Duplicate canonical map (`INDEX.md` vs `docs/index.md`) → which is canonical; merge the other.
    - Duplicate contract (root `AGENTS.md` vs `agent/AGENTS.md`) → consolidate into `agent/AGENTS.md`, leave a thin root pointer.
    - Variant dirs (`docs/tasks` vs `docs/task`) → consolidate onto the standard name.
+   - **Existing root `.gitignore` (when a codebase is moving into `apps/<slot>/`)** → propose moving the existing file wholesale to `apps/<slot>/.gitignore` (merge if one already exists there), and refresh the root `.gitignore` from the refact-os shipped template. The existing rules were written for code at the repo root; once the code lives at `apps/<slot>/`, the rules belong with the code. The refreshed root `.gitignore` is project-level only (refact-os hygiene: `.env`, OS junk, the generated `.claude/settings.local.json`, etc.). The user can pluck specific rules back to root afterward if they realize one is project-scoped (e.g. an org-wide editor pattern). Surface this as a single phase, not three — the move is one paired operation.
    - Forbidden `agent/workflows/` / `agent/evals/` → fold each into `agent/skills/<verb-object>/SKILL.md` (orchestrator/review pattern); propose names.
    - **Folders to delete** where a folder is genuinely unneeded (e.g. an empty `docs/deliverables/` on a repo that ships nothing) — list them explicitly so the user can approve.
    - Content not in a clear role → propose a role + destination.

package/templates/base/agent/skills/setup-project/SKILL.md

@@ -57,7 +57,8 @@ Run each check in order. After handling any unmet item, re-check it before movin
 |---|---|---|
 | `url` | `"https://www.example.com/"` | Full URL including `https://`. |
 | `branch` | `"main"`, `"stage"`, `"develop"` | Git branch that auto-deploys to this environment. |
-| `ssh` | `{ "user": "example", "host": "1.2.3.4", "port": 12345, "path": "/www/<env>/public" }` | **SSH-push hosts only** (Kinsta, WP Engine). Omit entirely for git-integration hosts (Vercel, Netlify). Never store the private **key** here — that's a CI secret. |
+| `install` | `"stlmagdev"` | **WP Engine only.** The WP Engine install name used in the deploy URL `git@git.wpengine.com:<install>.git`. Required when `hosting === "wpengine"`; omit otherwise. |
+| `ssh` | `{ "user": "example", "host": "1.2.3.4", "port": 12345, "path": "/www/<env>/public" }` | **SSH hosts only** (Kinsta, WP Engine). Used by the `wp-env` skill to pull plugins/mu-plugins/DB from staging. Omit entirely for git-integration hosts (Vercel, Netlify). Never store the private **key** here — that's a CI secret. |
 
 **Handle (if unmet):** Ask the user, one focused question at a time, for each type's `hosting` + `runtime` and at least its `production` (usually also `staging`) environment. Accept "skip" — leave the field `null` (or omit `ssh`) so it stays visibly outstanding without blocking init. Write directly into `.refact-os.json` and show the proposed change first. Collect **non-secret routing only** — SSH keys, tokens, and passwords belong in `.env` or the CI secret store, never here.
 
@@ -93,13 +94,18 @@ Run each check in order. After handling any unmet item, re-check it before movin
 
 **Handle (if unmet):** Ask the user whether they want to install the curated WP skills now — it's optional and they may prefer to defer. If yes, delegate to `agent/skills/install-wp-skills/SKILL.md`. If no, mark the checkbox as user-deferred and move on; do not re-prompt on the next init run unless the user re-asks.
 
-### 7. Kinsta auto-deploy workflows (WordPress + Kinsta only)
+### 7. Auto-deploy workflows (WordPress + SSH host only)
 
-**Skip this check** if `.refact-os.json` › `stack` has no `wordpress` entry, **or** if `stack.wordpress.hosting` is not `kinsta`.
+**Skip this check** if `.refact-os.json` › `stack` has no `wordpress` entry, **or** if `stack.wordpress.hosting` is neither `kinsta` nor `wpengine`.
 
-**Check:** Both `.github/workflows/wordpress-deploy-stage.yml` and `.github/workflows/wordpress-deploy-main.yml` exist at the repo root.
+**Check:** A `.github/workflows/wordpress-deploy-*.yml` file exists for each `stack.wordpress.environments.<env>` whose `branch` is set. (Concretely: a `kinsta` project usually has `wordpress-deploy-stage.yml` + `wordpress-deploy-main.yml`; a `wpengine` project usually adds `wordpress-deploy-develop.yml` as well.)
 
-**Handle (if unmet):** Ask the user whether they want to create the Kinsta workflows now — it requires Kinsta-side SSH keys and GitHub Actions secrets, so they may want to defer. If yes, delegate to `agent/skills/setup-kinsta-deploy/SKILL.md`. If no, mark as user-deferred and move on.
+**Handle (if unmet):** Ask the user whether they want to create the auto-deploy workflows now — it requires host-side SSH keys and GitHub Actions secrets, so they may want to defer. If yes:
+
+- `stack.wordpress.hosting === "kinsta"` → delegate to `agent/skills/setup-kinsta-deploy/SKILL.md`.
+- `stack.wordpress.hosting === "wpengine"` → delegate to `agent/skills/setup-wpengine-deploy/SKILL.md`.
+
+If no, mark as user-deferred and move on.
 
 ### 8. agent/AGENTS.md drift warning (post-update only)
 
@@ -119,7 +125,7 @@ init checklist:
   [x] git + GitHub remote
   [x] apps/wordpress/                (wordpress only)
   [-] WordPress agent skills          (deferred by user)
-  [x] Kinsta auto-deploy workflows    (wordpress + kinsta only)
+  [x] Auto-deploy workflows           (wordpress + kinsta/wpengine only)
   [x] agent/AGENTS.md drift                 (no pending warning)
 ```
 

package/templates/overlays/code/agent/skills/add-codebase/SKILL.md

@@ -181,7 +181,34 @@ touch apps/wordpress/wp-content/themes/.gitkeep
 touch apps/wordpress/wp-content/mu-plugins/.gitkeep
 ```
 
-### B3. Write a stub README
+### B3. Write `apps/wordpress/.gitignore`
+
+This file is load-bearing: it is the deploy filter for WP Engine and Kinsta workflows (only git-tracked files under `apps/wordpress/wp-content/` reach the server). WordPress-scoped ignore rules live here using relative paths; repo-level ignores (`.env`, `node_modules`, `.wp-env.override.json`) stay in the root `.gitignore`.
+
+```gitignore
+# Ignore everything in the WordPress root except wp-content.
+/*
+!.gitignore
+!wp-content/
+
+# Inside wp-content, only track themes, plugins, and mu-plugins.
+wp-content/*
+!wp-content/themes/
+!wp-content/plugins/
+!wp-content/mu-plugins/
+
+# Inside each, ignore everything by default — add explicit ! exceptions
+# for tracked themes/plugins/mu-plugins as they are added to the project.
+wp-content/themes/*
+wp-content/plugins/*
+wp-content/mu-plugins/*
+
+# Local-only wp-env mu-plugins (never deploy)
+wp-content/mu-plugins/00-wp-env-local-url.php
+wp-content/mu-plugins/01-wp-env-local-config.php
+```
+
+### B4. Write a stub README
 
 Write `apps/wordpress/REFACT-SOURCE.md`:
 
@@ -193,9 +220,9 @@ Created fresh via `/refact add codebase wordpress` on <DATE>.
 This slot is an empty WordPress codebase shell. Drop the client's WordPress source here — plugins under `wp-content/plugins/`, themes under `wp-content/themes/`, mu-plugins under `wp-content/mu-plugins/`.
 ```
 
-### B4. Report
+### B5. Report
 
-Tell the user the slot exists with empty `wp-content/{plugins,themes,mu-plugins}/` ready for content.
+Tell the user the slot exists with empty `wp-content/{plugins,themes,mu-plugins}/` ready for content, and that `apps/wordpress/.gitignore` was created as the deploy filter (they should add `!` exceptions as they add tracked themes/plugins/mu-plugins).
 
 ---
 

package/templates/overlays/wordpress/agent/skills/setup-kinsta-deploy/SKILL.md

@@ -184,6 +184,25 @@ Round-trip test that doesn't touch theme/plugin code:
 5. Visit the staging URL — bottom-right badge means the tree reached Kinsta and was checked out.
 6. Revert via a **new commit** (don't amend) — delete the file, remove the gitignore line, push.
 
+## Vendor policy
+
+**The default for refact-os WordPress projects is: `vendor/` directories are tracked in git.** Each plugin (or mu-plugin) commits its `composer install` output alongside the source.
+
+Consequences for this deploy flow:
+
+- The deploy workflow **must not** run `composer install`. It commits exactly what's tracked under `apps/wordpress/` and force-pushes that tree to Kinsta.
+- The bytes deployed to Kinsta equal the bytes in the merge commit — deploys are deterministic and there's no build step that can drift between environments.
+- New plugin dependencies require a commit that includes the updated `vendor/` tree alongside the `composer.json` change.
+
+Override path: a project that wants a build-in-CI flow must (a) add a `composer install --no-dev --optimize-autoloader` step in each plugin dir before the `git add .`, (b) add the matching `vendor/` ignore rules to the repo's `.gitignore`, and (c) document the deviation in `docs/decisions.md` with a responsible person.
+
+## `.gitignore` hard rules
+
+Kinsta receives **only** what reaches the workflow's fresh-init tree, which is **only** what's tracked by git under `apps/wordpress/`. That means the `.gitignore` files in the repo are the deploy filter, not just a local hygiene tool.
+
+- **Never use a root-whitelist `.gitignore` pattern (`/*` followed by `!apps/`, `!docs/`, …)** at the repo root. Whitelists are fragile across branch switches: a branch that doesn't carve out one of the allowed paths can quietly drop tracking on files the deploy depends on. Use blocklist semantics (ignore specific things; track everything else).
+- **Scoped allow-lists belong in `apps/wordpress/.gitignore`**, not at the repo root.
+
 ## Hard rules
 
 1. **Force-push (`--force`) is required for the Kinsta endpoint and only the Kinsta endpoint.** Kinsta's bare repo can't fast-forward against a fresh-init tree. Never `--force` to GitHub's `main` or `stage`.
@@ -191,6 +210,7 @@ Round-trip test that doesn't touch theme/plugin code:
 3. **Never place workflows under `apps/wordpress/.github/`.** GitHub doesn't run nested workflows. If any exist there, delete them.
 4. **Never push to `main` directly.** Stage gets validated first, then `stage → main` via PR.
 5. **Don't bypass the path filter** (e.g. removing `paths: 'apps/wordpress/**'`). Doing so means every README edit redeploys to Kinsta.
+6. **Never run `composer install` (or any other build step) in the deploy workflow** without first changing the vendor policy as described above.
 
 ## When to stop and ask the user
 

package/templates/overlays/wordpress/agent/skills/setup-wpengine-deploy/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: setup-wpengine-deploy
+description: Create the WP Engine auto-deploy GitHub workflows for apps/wordpress. WordPress-on-WP-Engine only.
+pattern: procedure
+requires_approval: true
+when_to_use: /refact setup wpengine auto-deploy | add wpengine deploy | create wpengine workflows.
+when_not_to_use: Non-WP-Engine hosting.
+next_skills: []
+sub_agents: []
+---
+
+# WP Engine Auto-Deploy Reference
+
+Use this reference when the user invokes any of:
+
+- `/refact setup wpengine auto-deploy`
+- `/refact add wpengine deploy`
+- `/refact enable wpengine auto-deploy`
+- `/refact create wpengine workflows`
+
+This reference both **documents** how the WP Engine auto-deploy works for projects scaffolded by this package, and **drives the agent** to create the GitHub Actions workflow files on demand. The workflow YAMLs are *not* pre-vendored into the project — they are generated by following Step 2 below, because not every engagement deploys to WP Engine.
+
+## TL;DR
+
+```
+push to <env.branch> ──▶ .github/workflows/wordpress-deploy-<env>.yml ──▶ WP Engine <install>
+
+(path-filtered on apps/wordpress/**; each workflow copies apps/wordpress/wp-content
+ into a fresh /tmp/deploy repo and force-pushes it to git@git.wpengine.com:<install>.git)
+```
+
+Each workflow:
+
+1. Checks out the monorepo.
+2. Loads the env's SSH private key and trusts `git.wpengine.com`.
+3. `cp -r apps/wordpress/wp-content /tmp/deploy/wp-content` — only the wp-content tree leaves the monorepo.
+4. Inside `/tmp/deploy`: `git init -b master`, single commit, force-push to `git@git.wpengine.com:<install>.git HEAD:master`.
+5. WP Engine's git endpoint deploys the pushed tree to the install.
+
+## Step 1 — Preflight
+
+### 1a. Confirm this is a WordPress-on-WP-Engine project
+
+Check `.refact-os.json`:
+
+- `stack.wordpress` exists.
+- `stack.wordpress.hosting === "wpengine"`.
+- `apps/wordpress/wp-content/` exists.
+
+If `stack.wordpress` is missing → stop, this flow is WordPress-specific. If `apps/wordpress/` is missing → delegate to `/refact add codebase wordpress` first. If `hosting` is `kinsta` → use `setup-kinsta-deploy.md` instead.
+
+### 1b. Confirm each environment has the fields we need
+
+For every `stack.wordpress.environments.<env>` entry, the workflow needs:
+
+| Field | Purpose | Source |
+|---|---|---|
+| `branch` | Which git branch's pushes trigger this env's workflow. | `.refact-os.json` |
+| `install` | WP Engine install name; used in `git@git.wpengine.com:<install>.git`. | `.refact-os.json` |
+| `url` | Public URL (informational; used in the report at Step 3). | `.refact-os.json` |
+| `ssh.user` / `ssh.host` / `ssh.port` / `ssh.path` | Used by the `wp-env` SKILL for staging pulls, not by deploy. Not required here. | `.refact-os.json` |
+
+If `branch` or `install` is missing for any env you're about to generate, stop and ask the user to run `/refact init` to fill them in — do not invent defaults.
+
+The **non-secret** deploy routing lives in `.refact-os.json`. The SSH **private keys** are GitHub Actions secrets and live only there — never in `.refact-os.json` and never in `agent/AGENTS.md`.
+
+### 1c. Confirm with the user
+
+Tell the user which workflow files are about to be created — one per env in the stack, e.g.:
+
+- `.github/workflows/wordpress-deploy-develop.yml`
+- `.github/workflows/wordpress-deploy-stage.yml`
+- `.github/workflows/wordpress-deploy-main.yml`
+
+And list the GitHub Actions secrets they will need to add **before** the workflows can succeed. One private key per env:
+
+| Env | Secret name |
+|---|---|
+| `develop` (or whatever maps to the develop install) | `SSH_PRIV_KEY_DEV` |
+| `stage` | `SSH_PRIV_KEY_STG` |
+| `production` (the `main` branch env) | `SSH_PRIV_KEY_PROD` |
+
+The matching public keys go in WP Engine's SSH allow-list for each install (User Portal → Sites → `<install>` → SSH gateway).
+
+Confirm before writing files.
+
+## Step 2 — Create the workflow files
+
+GitHub Actions only reads workflows from the **repo root** `/.github/workflows/`. Never place these under `apps/wordpress/.github/` — GitHub will not run them, and they would pollute WP Engine's checkout.
+
+Generate one file per env present in `stack.wordpress.environments`. Substitute `<env-key>`, `<env.branch>`, `<env.install>`, and `<SECRET_NAME>` for each.
+
+### Template (one file per env)
+
+```yaml
+name: <Env-Title> auto-deploy
+on:
+  push:
+    branches: [<env.branch>]
+    paths:
+      - 'apps/wordpress/**'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Push wp-content to WP Engine (<env-key>)
+        run: |
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          eval $(ssh-agent -s)
+          echo "${{ secrets.<SECRET_NAME> }}" | tr -d '\r' | ssh-add -
+          ssh-keyscan git.wpengine.com >> ~/.ssh/known_hosts
+          chmod 644 ~/.ssh/known_hosts
+
+          mkdir -p /tmp/deploy
+          cp -r apps/wordpress/wp-content /tmp/deploy/wp-content
+          cd /tmp/deploy
+          git init -b master
+          git config user.email "deploy@github.actions"
+          git config user.name "GitHub Actions"
+          git add .
+          git commit -m "Deploy ${{ github.sha }}"
+          git push git@git.wpengine.com:<env.install>.git HEAD:master --force
+```
+
+Concrete example, for an env keyed `production` with `branch: "main"` and `install: "stlouismagazin"`:
+
+```yaml
+name: Production auto-deploy
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'apps/wordpress/**'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Push wp-content to WP Engine (production)
+        run: |
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          eval $(ssh-agent -s)
+          echo "${{ secrets.SSH_PRIV_KEY_PROD }}" | tr -d '\r' | ssh-add -
+          ssh-keyscan git.wpengine.com >> ~/.ssh/known_hosts
+          chmod 644 ~/.ssh/known_hosts
+
+          mkdir -p /tmp/deploy
+          cp -r apps/wordpress/wp-content /tmp/deploy/wp-content
+          cd /tmp/deploy
+          git init -b master
+          git config user.email "deploy@github.actions"
+          git config user.name "GitHub Actions"
+          git add .
+          git commit -m "Deploy ${{ github.sha }}"
+          git push git@git.wpengine.com:stlouismagazin.git HEAD:master --force
+```
+
+### Secret name mapping
+
+Use the env key (not the branch) to pick the secret:
+
+| Env key | Secret name |
+|---|---|
+| `production` | `SSH_PRIV_KEY_PROD` |
+| `stage` / `staging` | `SSH_PRIV_KEY_STG` |
+| `develop` / `development` / `dev` | `SSH_PRIV_KEY_DEV` |
+| Anything else | `SSH_PRIV_KEY_<UPPER_ENV>` (e.g. `preview` → `SSH_PRIV_KEY_PREVIEW`) |
+
+WP Engine accepts the same public key across installs, but a separate secret per env is the safer default — rotating one install's key doesn't disturb the others.
+
+## Step 3 — Report and hand off
+
+Tell the user:
+
+1. Which files were created (one per env).
+2. The list of GitHub Actions secrets they must add at **Settings → Secrets and variables → Actions** before the first push. If a secret is missing, the workflow fails at the `ssh-add` step.
+3. The corresponding public keys need to be added to each WP Engine install's SSH gateway (User Portal → site → SSH keys).
+4. The next step: push to the `develop` branch first, watch the run in the Actions tab, then promote `develop → stage → main` via PRs.
+5. That the workflows are **path-filtered** on `apps/wordpress/**`, so edits elsewhere in the monorepo will not trigger a deploy or burn Actions minutes.
+
+## Vendor policy
+
+**The default for refact-os WordPress projects is: `vendor/` directories are tracked in git.** Each plugin (or mu-plugin) commits its `composer install` output alongside the source.
+
+Consequences for this deploy flow:
+
+- The deploy workflow **must not** run `composer install`. It `cp -r`s exactly what was committed.
+- The bytes deployed to WP Engine equal the bytes in the merge commit — deploys are deterministic and there's no build step that can drift between environments.
+- New plugin dependencies require a commit that includes the updated `vendor/` tree alongside the `composer.json` change.
+
+Override path: a project that wants a build-in-CI flow must (a) add a `composer install --no-dev --optimize-autoloader` step before the `cp -r` here, (b) add the matching `vendor/` ignore rules to the repo's `.gitignore`, and (c) document the deviation in `docs/decisions.md` with a responsible person.
+
+## `.gitignore` hard rules
+
+WP Engine receives **only** what reaches `/tmp/deploy/wp-content`, which is **only** what's tracked by git under `apps/wordpress/wp-content/`. That means the `.gitignore` files in the repo are the deploy filter, not just a local hygiene tool.
+
+- **Never use a root-whitelist `.gitignore` pattern (`/*` followed by `!apps/`, `!docs/`, …)** at the repo root. Whitelists are fragile across branch switches: a branch that doesn't carve out one of the allowed paths can quietly drop tracking on files the deploy depends on. Use blocklist semantics (ignore specific things; track everything else).
+- **Scoped allow-lists belong in `apps/wordpress/.gitignore`**, not at the repo root. That's where the classic "ignore WP core; allow `wp-content/`; inside `wp-content/`, only track our theme + mu-plugin" pattern lives.
+- **Never delete or aggressively rewrite `apps/wordpress/.gitignore`** — it's load-bearing. Without it, the `cp -r` could pick up untracked WordPress core, dump files, or local dev artifacts.
+
+## Adding new tracked files under `apps/wordpress/`
+
+The nested `apps/wordpress/.gitignore` is the allow-list. New files in `wp-content/mu-plugins/`, `wp-content/plugins/`, or `wp-content/themes/` need an explicit `!` exception or git won't see them — and if git doesn't see them, neither does WP Engine.
+
+Verify it works before committing:
+
+```bash
+git check-ignore -v apps/wordpress/wp-content/mu-plugins/your-new-plugin.php
+# Should print the `!...` rule line, NOT the wildcard rule.
+```
+
+`git status` showing the file as untracked-but-eligible is the green-light.
+
+## Smoke-testing the auto-deploy
+
+Round-trip test that doesn't touch theme/plugin code:
+
+1. On `develop`, create `apps/wordpress/wp-content/mu-plugins/deploy-test.php`:
+
+   ```php
+   <?php
+   /** Plugin Name: Deploy Test */
+   defined('ABSPATH') || exit;
+   add_action('wp_footer', function () {
+       echo '<div style="position:fixed;bottom:8px;right:8px;background:#222;color:#fff;padding:6px 10px;font:12px monospace;z-index:99999;">deploy ok &middot; ' . esc_html(gmdate('c')) . '</div>';
+   });
+   ```
+
+2. Add `!wp-content/mu-plugins/deploy-test.php` to `apps/wordpress/.gitignore`.
+3. Commit and `git push origin develop`.
+4. Watch `https://github.com/<org>/<repo>/actions` → "Development auto-deploy" run.
+5. Visit the dev install URL — bottom-right badge means the tree reached WP Engine.
+6. Revert via a **new commit** (don't amend) — delete the file, remove the gitignore line, push.
+
+## Hard rules
+
+1. **Force-push (`--force`) is required for the WP Engine endpoint and only the WP Engine endpoint.** WP Engine's git endpoint expects a fresh-init tree and cannot fast-forward against one. Never `--force` to GitHub's `main` (or any other GitHub branch).
+2. **Never delete or aggressively rewrite `apps/wordpress/.gitignore`.** It is the deploy filter (see above).
+3. **Never place workflows under `apps/wordpress/.github/`.** GitHub doesn't run nested workflows. If any exist there, delete them.
+4. **Never push to `main` directly.** Develop and stage get validated first, then `stage → main` via PR.
+5. **Don't bypass the path filter** (e.g. removing `paths: 'apps/wordpress/**'`). Doing so means every README edit redeploys.
+6. **Never run `composer install` (or any other build step) in the deploy workflow** without first changing the vendor policy as described above.
+
+## When to stop and ask the user
+
+- About to add a path under `apps/wordpress/` and unsure if the nested allow-list covers it → run `git check-ignore -v` first; if it points at the wildcard rule, you need a new `!` line.
+- A workflow run fails → diagnose, don't retry blindly. Common causes: missing secret, public key not in WP Engine's SSH allow-list for that install, wrong `install` name (`.git` path mismatch).
+- Stage deploy works but production doesn't pick up → confirm `branch:` matches the actual production branch, and `<install>` matches the production install name in WP Engine.
+- About to change a workflow to push something other than `apps/wordpress/wp-content/` → that's an architecture change; surface and confirm scope.

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

@@ -12,18 +12,19 @@ sub_agents: []
 
 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 setup` — bring up a fresh local WordPress stack and, in the same flow, optionally pull plugins/mu-plugins + DB from staging and set a local domain. Idempotent: each sub-step is verified independently and skipped silently if already met, so re-running on a fully-configured project is a no-op.
 - `/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 pull wp-config` — read staging `wp-config.php` and extract application constants into local config files.
 - `/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`.
+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 and WP Engine deploy workflows push (see [`setup-kinsta-deploy.md`](../setup-kinsta-deploy/SKILL.md) / [`setup-wpengine-deploy.md`](../setup-wpengine-deploy/SKILL.md)). The local env mirrors staging by pulling plugins, mu-plugins, and the DB over SSH using the routing in `.refact-os.json` › `stack.wordpress.environments.staging`.
 
 ## Canonical layout
 
@@ -55,7 +56,7 @@ The hostname is stored at `.refact-os.json` › `wpEnv.localDomain` so every tea
 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.
+For `pull` flows only — also verify `.refact-os.json` › `stack.wordpress.environments.staging` has its `ssh` block (user/host/port/path) and `url` filled. If the `ssh` block is missing or any of its fields are absent, stop and tell the user to run `/refact init` first — the deploy/SSH source of truth is `.refact-os.json`, not `agent/AGENTS.md`.
 
 ---
 
@@ -149,23 +150,60 @@ Print to the user:
 
 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).
 
+### 1g. One-shot post-start checklist
+
+The container is up. Walk this **idempotent checklist** so the user gets to a usable, populated local site in one command. Each item is independent: verify the condition, skip silently if already met, otherwise ask the user a single yes/no and delegate to the documented sub-flow. Re-running `/refact wp-env setup` on a fully-configured project does nothing.
+
+The values prompted for here persist into `.refact-os.json`, so the next teammate who clones the repo and runs `/refact wp-env setup` is asked **none** of them.
+
+#### Checklist
+
+1. **Pull plugins + mu-plugins from staging.**
+   - Skip silently if `apps/wordpress/wp-content/plugins/` contains any directory other than `.gitkeep` (i.e. there's already at least one plugin checked in or pulled).
+   - Otherwise ask: *"Pull plugins and mu-plugins from staging now? [Y/n]"*. On yes, run Step 2b (`pull plugins`) followed by Step 2c (`pull mu-plugins`). On no, mark as user-deferred and continue.
+   - Preflight is shared: if Step 2a's SSH check fails, surface and stop the checklist here.
+
+2. **Pull staging DB.**
+   - Skip silently if `npm run wp:cli -- option get siteurl` returns anything other than wp-env's default (`http://localhost:8888` or `https://localhost:8888`). Any non-default value means the DB has already been imported.
+   - Otherwise ask: *"Pull the staging database now? This rewrites local URLs from `<STAGING_URL>` → `<LOCAL_URL>` and resets the admin password. [Y/n]"*. On yes, run Step 2d (`pull db`). On no, mark as user-deferred.
+
+3. **Set a local domain.**
+   - Skip silently if `.refact-os.json` › `wpEnv.localDomain` is already set. (If it is set but Caddy isn't running, the message printed in 1f covers that.)
+   - Otherwise ask: *"Front the local stack with a `.local` hostname over HTTPS (recommended)? Leave blank to keep `http://localhost:8888`."*. If the user provides a hostname, run Step 3b (`domain set <hostname>`). If they leave it blank or decline, persist nothing (so the next teammate gets the same prompt — they may want a domain even if this user doesn't).
+
+#### Output
+
+After the checklist, print a single summary, in the same shape `setup-project` uses:
+
+```
+wp-env setup checklist:
+  [x] containers up                       (wp-env start)
+  [x] plugins + mu-plugins pulled         (or [-] deferred / [-] already populated)
+  [x] staging DB imported                 (or [-] deferred / [-] already populated)
+  [x] local domain set                    (or [-] deferred / [-] not requested)
+```
+
+Use `[x]` for met, `[-]` for user-deferred or already-populated (don't re-prompt next run unless the user re-asks), and `[ ]` only for items that failed mid-step (with the suggested next action).
+
 ---
 
 ## 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`
+### 2a. Resolve SSH target from `.refact-os.json`
 
-Parse the **SSH access** section of `agent/AGENTS.md`. The init flow fills these placeholders:
+Read `.refact-os.json` › `stack.wordpress.environments.staging`. (For projects whose staging env is keyed differently — e.g. `stage` — fall back to that key; never default to `production`.) Map the fields:
 
-| agent/AGENTS.md field | Variable |
+| `.refact-os.json` path | 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` |
+| `…environments.staging.ssh.user` | `SSH_USER` |
+| `…environments.staging.ssh.host` | `SSH_HOST` |
+| `…environments.staging.ssh.port` | `SSH_PORT` |
+| `…environments.staging.ssh.path` | `DOC_ROOT` (the WordPress install root, relative to the SSH user's home; e.g. `sites/<install>` on WP Engine, `/www/<dir>/public` on Kinsta) |
+| `…environments.staging.url` | `STAGING_URL` |
+
+If `stack.wordpress.environments.staging.ssh` is absent (or any of `user`/`host`/`port`/`path` is missing), stop and tell the user to run `/refact init` to fill it. Do **not** fall back to parsing `agent/AGENTS.md` — `.refact-os.json` is the single source of truth.
 
 Build the SSH connection string:
 
@@ -198,24 +236,49 @@ 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".
+- 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 the host on deploy, the nested `apps/wordpress/.gitignore` needs an explicit `!` exception — see the project's deploy skill (`setup-kinsta-deploy` or `setup-wpengine-deploy`) § "Adding new tracked files under `apps/wordpress/`".
 
 ### 2c. Pull `mu-plugins`
 
+Build the rsync exclude list from two sources: local-only files that must never be deleted by `--delete`, and host-injected system mu-plugins that aren't useful locally. Read `hosting` from `.refact-os.json` › `stack.wordpress.hosting` to select the right set.
+
+**Always exclude (local-only wp-env helpers):**
+
+```
+--exclude='index.php'
+--exclude='00-wp-env-local-url.php'
+--exclude='01-wp-env-local-config.php'
+```
+
+**Host-specific excludes:**
+
+| Hosting | Exclude patterns |
+|---|---|
+| `kinsta` | `kinsta-mu-plugins/`, `kinsta-mu-plugins.php` |
+| `wpengine` | `mu-plugin.php`, `force-strong-passwords/`, `slt-force-strong-passwords.php`, `wpe-cache-plugin*`, `wpe-update-source-selector*`, `wpe-wp-sign-on-plugin*`, `wpengine-common/`, `wpengine-security-auditor.php` |
+| Other | Ask the user if unrecognized system mu-plugins are detected |
+
+Example for a WP Engine project:
+
 ```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' \
+  --exclude='01-wp-env-local-config.php' \
+  --exclude='mu-plugin.php' \
+  --exclude='force-strong-passwords/' \
+  --exclude='slt-force-strong-passwords.php' \
+  --exclude='wpe-cache-plugin*' \
+  --exclude='wpe-update-source-selector*' \
+  --exclude='wpe-wp-sign-on-plugin*' \
+  --exclude='wpengine-common/' \
+  --exclude='wpengine-security-auditor.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.
+These host-injected mu-plugins are managed server-side; they aren't useful locally and shouldn't end up in git. If you spot an unrecognized system mu-plugin (owned by `root` or `nobody`, or matching a known hosting vendor pattern), ask the user before adding it to the exclude list.
 
 ### 2d. Pull `db`
 
@@ -223,21 +286,32 @@ The local stack **must be running** for this step. If `npx wp-env run cli wp cor
 
 Resolve `LOCAL_URL` the same way Step 1b does: `https://<wpEnv.localDomain>` if it's set in `.refact-os.json`, otherwise `http://localhost:8888`.
 
+Use a two-step dump-to-file approach. Piping SSH export directly into `wp-env run cli wp db import -` can stall on databases larger than ~500 MB because Docker's stdin buffering saturates before the import catches up.
+
 ```bash
-# 1. Dump staging DB and pipe straight into the wp-env container.
+# 1. Dump staging DB to a local file.
+mkdir -p .wp-env-dumps
 ssh ${SSH_OPTS} "${SSH_TARGET}" \
   "cd '${DOC_ROOT}' && wp db export --single-transaction -" \
-  | npx wp-env run cli wp db import -
+  > .wp-env-dumps/staging.sql
+
+# 2. Copy the dump into the wp-env container and import.
+CONTAINER=$(docker ps --filter "name=cli" --format '{{.Names}}' | grep wp-env | head -1)
+docker cp .wp-env-dumps/staging.sql "${CONTAINER}:/tmp/staging.sql"
+npx wp-env run cli wp db import /tmp/staging.sql
 
-# 2. Rewrite URLs from staging → local.
+# 3. 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.
+# 4. Flush caches.
 npx wp-env run cli wp cache flush
+
+# 5. Clean up the dump (gitignored path, but no reason to keep ~1 GB on disk).
+rm -f .wp-env-dumps/staging.sql
 ```
 
 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.
@@ -257,6 +331,64 @@ After import:
 
 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.
 
+### 2e. Pull `wp-config`
+
+Reads the staging `wp-config.php` via SSH and extracts application-level constants into the local environment. Run this after `pull db` so the local stack has the same constants the staging code expects.
+
+```bash
+ssh ${SSH_OPTS} "${SSH_TARGET}" "cat '${DOC_ROOT}/wp-config.php'"
+```
+
+Classify each `define()` in the file into one of four buckets:
+
+**Skip (infrastructure — handled by wp-env or the host):**
+
+- Database: `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_HOST_SLAVE`, `DB_CHARSET`, `DB_COLLATE`, `$table_prefix`
+- Salts/keys: `AUTH_KEY`, `SECURE_AUTH_KEY`, `LOGGED_IN_KEY`, `NONCE_KEY`, `AUTH_SALT`, `SECURE_AUTH_SALT`, `LOGGED_IN_SALT`, `NONCE_SALT`
+- WordPress core paths: `ABSPATH`, `WP_CACHE`, `WPLANG`, `WP_AUTO_UPDATE_CORE`
+- Host-injected (read `hosting` from `.refact-os.json` › `stack.wordpress.hosting`):
+  - **WP Engine**: `WPE_*`, `PWP_NAME`, `FS_METHOD`, `FS_CHMOD_*`, `WPE_SFTP_*`, `WPE_CDN_*`, `DISALLOW_FILE_*`, `DISABLE_WP_CRON`, `FORCE_SSL_LOGIN`, `WPE_FORCE_SSL_LOGIN`, `WP_POST_REVISIONS`, `WP_TURN_OFF_ADMIN_BAR`, `WPE_BETA_TESTER`, `WPE_WHITELABEL`, `WPE_EXTERNAL_URL`, `$wpe_*`, `$memcached_servers`
+  - **Kinsta**: `KINSTA_*`, `WP_CACHE_KEY_SALT`
+- Debug flags: `WP_DEBUG`, `WP_DEBUG_LOG`, `WP_DEBUG_DISPLAY` (already set in `.wp-env.json`)
+
+**Scalar, non-secret → `.wp-env.json` `config` (committed):**
+
+Application constants with no secret value: version strings, import/feature IDs, memory limits, email addresses. Examples: `SLM_CORE_VERSION`, `CONTENT_IMPORT_ID`, `WP_MEMORY_LIMIT`, `WP_MAX_MEMORY_LIMIT`.
+
+Add these to the existing `config` object in `.wp-env.json`. Don't overwrite values already present.
+
+**Scalar, secret → `.wp-env.override.json` `config` (gitignored):**
+
+API keys, encryption keys, tokens. Examples: `SLM_AKISMET_API_KEY`, `WP2FA_ENCRYPT_KEY`.
+
+Create `.wp-env.override.json` if it doesn't exist (`{ "config": { … } }`). This file must be in the root `.gitignore`.
+
+**Complex (PHP arrays) → local mu-plugin (gitignored):**
+
+wp-env `config` only supports scalar values. PHP arrays (e.g. service-account credential blobs) go into `apps/wordpress/wp-content/mu-plugins/01-wp-env-local-config.php`, guarded by:
+
+```php
+if ( defined( 'WP_ENVIRONMENT_TYPE' ) && 'local' === WP_ENVIRONMENT_TYPE ) {
+    if ( ! defined( 'SOME_CONSTANT' ) ) {
+        define( 'SOME_CONSTANT', array( … ) );
+    }
+}
+```
+
+This file must be in `apps/wordpress/.gitignore`.
+
+**After writing all files:**
+
+1. Restart wp-env: `npx wp-env start` (picks up `.wp-env.json` and override changes).
+2. Verify: `npx wp-env run cli wp eval "echo defined('CONSTANT_NAME') ? 'yes' : 'no';"` for a sample of the extracted constants.
+3. If a previously-crashed plugin depended on a missing constant (common: GA4/analytics credentials), re-activate it: `npx wp-env run cli wp plugin activate <plugin-slug>`.
+
+**Guardrails:**
+
+- Never commit secrets. `.wp-env.override.json` and `01-wp-env-local-config.php` must always be gitignored.
+- Never copy the staging DB credentials, salts, or host-specific constants into local files — they're meaningless locally and risk leaking if committed.
+- Show the user the proposed classification (which constants go where) before writing, so they can override the bucket for edge cases.
+
 ---
 
 ## Step 3 — `domain set <hostname>` / `domain clear`
@@ -464,7 +596,7 @@ After reset, the user typically wants `/refact wp-env pull db` to restore stagin
 - **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 edit `agent/AGENTS.md` (or any other file) to fill missing SSH fields from this flow.** Send the user to `/refact init` so `.refact-os.json` › `stack.wordpress.environments.<env>.ssh` is filled — that's the single source of truth.
 - **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.