Commit c0c5f61

export function assertWpEnvPrecision(repoRoot) {

requireIncludes(repoRoot, "skills/wp-env/SKILL.md", [

"verified against @wordpress/env 11.16.0",

"npm exec --no -- wp-env",

"wp-env run cli wp rewrite structure /%postname%/",

"wp-env run mysql mariadb --",

"`tests-cli`",

'"testsEnvironment": false',

"wp-env destroy --force",

"`lifecycleScripts` are **merged**",

"Invalid or unrecognized source",

]);

requireExcludes(repoRoot, "skills/wp-env/SKILL.md", [

"`cli`, `composer`",

'wp-env run cli "wp rewrite structure',

"wp-env run mysql mysql",

"# Then use: npx wp-env",

"run via `npx wp-env`",

"Could not find a valid source",

]);

requireIncludes(repoRoot, "skills/wordpress-router/references/decision-tree.md", [

"Route → `wp-env`",

]);

assertWpEnvPrecision(repoRoot);

- **playground.wordpress.net / Blueprint Editor / share links / browser-only Playground / WebMCP site tools / Playground MCP / `window.playgroundSites`**

- **wp-env / @wordpress/env / .wp-env.json / Docker-based local WordPress / `wp-env run`**

- Route → `wp-env`. For a quick, disposable local site without Docker, route → `wp-playground` instead.

- **Testing / PHPUnit / Playwright**

- Route → `wp-testing` (planned). To run PHPUnit inside a wp-env environment, route → `wp-env`.

description: "Use when setting up, configuring, or troubleshooting local WordPress development environments with @wordpress/env (wp-env). Triggers on mentions of wp-env, local WordPress development, Docker-based WordPress, or requests to start/stop/configure a local WordPress instance. For a quick, disposable local site without Docker, use wp-playground instead."

compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires Docker (default runtime) and Node.js 18.12+; verified against @wordpress/env 11.16.0."

license: GPL-2.0-or-later

Verified against `@wordpress/env` 11.16.0. When exact flags matter, check `wp-env --version` and `wp-env <command> --help`.

Run a project-local install with `npm exec --no -- wp-env` (or a `package.json` script), not `npx wp-env`. If the local install is missing, `npx wp-env` fetches the unscoped `wp-env` package from the registry, which is not `@wordpress/env`, and a non-interactive shell installs it without asking. `--no` makes npm fail instead.

- `wp-env start --auto-port` -- find available ports when defaults are busy (ignored when `CI` is set)

By default `start` also creates a separate tests environment (port 8889, `tests-*` containers) and prints a deprecation warning. Add `"testsEnvironment": false` to `.wp-env.json` to start only the development environment; for an isolated test site, run a second environment from its own config file with `wp-env start --config=<file>`.

**GOTCHA:** WordPress.org plugin/theme slugs (bare names like `"akismet"`) do NOT work. Use the full ZIP URL. Relative local paths must start with `.` (`"."`, `"./path"`, `"../path"`): `"plugins/my-plugin"` is parsed as the GitHub repository `plugins/my-plugin`.

Create `.wp-env.override.json` next to `.wp-env.json` for personal settings (gitignored). `config`, `mappings`, and `lifecycleScripts` are **merged** key by key -- all other fields (including `plugins` and `themes` arrays) **fully replace** the base.

wp-env run cli wp rewrite structure /%postname%/

wp-env run mysql mariadb -- --user=root --password=password wordpress

`wp-env run` hands each argument straight to `docker compose exec` without a shell. Never wrap the whole command in one quoted string: `wp-env run cli "wp user list"` fails with `executable file not found in $PATH`. Quote only individual arguments that contain spaces. The database image is `mariadb:lts`, which ships a `mariadb` client but no `mysql` binary.

Available containers: `mysql`, `wordpress`, `cli`, and `phpmyadmin` (only when enabled), plus `tests-mysql`, `tests-wordpress`, and `tests-cli` while the tests environment is on. The `composer` and `phpunit` containers were removed; run those tools in `cli`.

wp-env cleanup --force # Remove containers/volumes (keep images)

wp-env destroy --force # Remove everything including images

`cleanup` and `destroy` delete the site's database and content. Without `--force` they wait for an interactive confirmation that a non-interactive agent shell cannot answer, so get the user's go-ahead first and then pass `--force`.

| `Invalid or unrecognized source: "<value>"` | Bare wp.org slug, or a relative path without a leading `.` | Use the full ZIP URL for wp.org plugins; prefix local paths with `./` |

| Stale environment after source changes | Cached Docker volumes | `wp-env start --update`; if that fails and the user accepts losing local data, `wp-env destroy --force` then `wp-env start` |

| White screen / PHP errors | PHP fatal in the code under development, or a corrupted database | Check `wp-env logs --no-watch` first; if the database is the cause, `wp-env reset all && wp-env start` (deletes all site content) |

| Override not taking effect | Wrong merge behavior | `plugins`/`themes` in override **replace** base arrays; only `config`/`mappings`/`lifecycleScripts` merge |

| Tests environment not accessible | Wrong port, or `"testsEnvironment": false` | It runs on port 8889 unless disabled; the separate tests environment is deprecated, so prefer a second config started with `--config` |

| npm global install permission error | Node installed to a system path | Use `nvm`, or install locally: `npm i -D @wordpress/env` and run via `npm exec --no -- wp-env` |

- If the task needs native PHP extensions, external database access, persistence, or production-like infrastructure that Playground cannot provide, use a full WordPress stack such as wp-env (see the `wp-env` skill), Docker, or the project-provided environment.