wordpress-agent-kit 0.3.2 → 0.5.1

package/.agents/skills/wp-phpstan/references/wordpress-annotations.md

@@ -0,0 +1,124 @@
+# WordPress-specific type annotations
+
+These patterns help PHPStan understand WordPress code where runtime behavior and dynamic typing make inference difficult.
+
+## REST API request typing
+
+PHPStan cannot infer valid request parameters from REST API schemas. Provide explicit type hints for request params.
+
+```php
+/**
+ * Handle REST API request.
+ *
+ * @param WP_REST_Request $request Full details about the request.
+ * @return WP_REST_Response|WP_Error Response object on success, error on failure.
+ *
+ * @phpstan-param WP_REST_Request<array{
+ *     post?: int,
+ *     orderby?: string,
+ *     meta_key?: string,
+ *     per_page?: int,
+ *     status?: array<string>
+ * }> $request
+ */
+public function get_items( $request ) {
+    $post_id = $request->get_param( 'post' );
+    // PHPStan now knows $post_id is int|null.
+}
+```
+
+For complex schemas, define reusable types.
+
+```php
+/**
+ * @phpstan-type PostRequestParams array{
+ *     title?: string,
+ *     content?: string,
+ *     status?: 'publish'|'draft'|'private',
+ *     meta?: array<string, mixed>
+ * }
+ *
+ * @phpstan-param WP_REST_Request<PostRequestParams> $request
+ */
+```
+
+## Hook callbacks
+
+```php
+/**
+ * Handle status transitions.
+ *
+ * @param string $new_status
+ * @param string $old_status
+ * @param WP_Post $post
+ */
+function handle_transition( string $new_status, string $old_status, WP_Post $post ): void {
+    // ...
+}
+
+add_action( 'transition_post_status', 'handle_transition', 10, 3 );
+```
+
+## Database and iterables
+
+```php
+/**
+ * @return array<WP_Post> WP_Post objects.
+ */
+function get_custom_posts(): array {
+    $posts = get_posts( [ 'post_type' => 'custom_type', 'numberposts' => -1 ] );
+    return $posts;
+}
+
+/**
+ * @return array<object{id: int, name: string}> Database results.
+ */
+function get_user_data(): array {
+    global $wpdb;
+
+    $results = $wpdb->get_results( "SELECT id, name FROM users", OBJECT );
+    return $results ?: [];
+}
+```
+
+## Hooks (`apply_filters()` and `do_action()`)
+
+Docblocks for `apply_filters()` and `do_action()` are validated. The type of the first `@param` is definitive.
+
+If a third party returns the wrong type for a filter, a PHPStan error is expected and does not require defensive code.
+
+```php
+/**
+ * Allows hooking into formatting of the price.
+ *
+ * @param string $formatted The formatted price.
+ * @param float  $price     The raw price.
+ * @param string $locale    Locale to localize pricing display.
+ * @param string $currency  Currency symbol.
+ */
+return apply_filters( 'autoscout_vehicle_price_formatted', $formatted, $price, $locale, $currency );
+```
+
+## Action Scheduler argument shapes
+
+```php
+/**
+ * Process a scheduled email.
+ *
+ * @param array{user_id: int, email: string, data: array<string, mixed>} $args
+ */
+function process_scheduled_email( array $args ): void {
+    $user_id = $args['user_id'];
+    // ...
+}
+
+as_schedule_single_action(
+    time() + 3600,
+    'process_scheduled_email',
+    [
+        'user_id' => 123,
+        'email' => 'user@example.com',
+        'data' => [ 'key' => 'value' ],
+    ]
+);
+```

package/.agents/skills/wp-phpstan/scripts/phpstan_inspect.mjs

@@ -0,0 +1,263 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const TOOL_VERSION = "0.1.0";
+
+/**
+ * Reads and parses JSON from a file path.
+ *
+ * Returns null when parsing fails so the caller can provide user-facing
+ * guidance without crashing.
+ *
+ * @param {string} filePath Absolute path to a JSON file.
+ * @returns {any|null} Parsed JSON object.
+ */
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reads a UTF-8 text file.
+ *
+ * Returns null when reading fails so callers can surface missing configs
+ * without crashing.
+ *
+ * @param {string} filePath Absolute path to a text file.
+ * @returns {string|null} File contents.
+ */
+function readTextSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Checks whether a path exists and is a regular file.
+ *
+ * @param {string} filePath Absolute or relative file path.
+ * @returns {boolean} True when the path exists and is a file.
+ */
+function isFile(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Normalizes Composer script entries into a flat list of commands.
+ *
+ * Composer allows scripts to be strings or arrays. This helper provides a
+ * consistent format for analysis.
+ *
+ * @param {unknown} value Composer script value.
+ * @returns {string[]} Command list.
+ */
+function normalizeComposerScript(value) {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.filter((x) => typeof x === "string");
+  return [];
+}
+
+/**
+ * Detects which Composer scripts invoke PHPStan.
+ *
+ * This helps the agent prefer the repo's own invocation (memory limits,
+ * config, bootstrap files) instead of guessing.
+ *
+ * @param {Record<string, unknown>} scripts Composer scripts block.
+ * @returns {Array<{name: string, commands: string[]}>} Matching script entries.
+ */
+function findPhpstanScripts(scripts) {
+  if (!scripts || typeof scripts !== "object") return [];
+
+  const matches = [];
+
+  for (const [name, raw] of Object.entries(scripts)) {
+    const commands = normalizeComposerScript(raw);
+
+    const invokesPhpstan = commands.some((cmd) => {
+      if (typeof cmd !== "string") return false;
+      return cmd.includes("phpstan") || cmd.includes("vendor/bin/phpstan");
+    });
+
+    if (!invokesPhpstan) continue;
+
+    matches.push({ name, commands });
+  }
+
+  return matches;
+}
+
+/**
+ * Chooses a recommended command for running PHPStan in the current repo.
+ *
+ * The intent is to prefer an existing Composer script (often has correct
+ * config, bootstrap, and memory limits), falling back to vendor binaries.
+ *
+ * @param {Array<{name: string, commands: string[]}>} phpstanScripts Matching Composer scripts.
+ * @param {{binaryRelPath: string|null, configRelPath: string|null}} fallbackInfo Fallback discovery.
+ * @returns {{command: string|null, rationale: string}} Suggested command and why.
+ */
+function suggestCommand(phpstanScripts, fallbackInfo) {
+  const preferred = phpstanScripts.find((s) => s.name === "phpstan");
+  if (preferred) {
+    return {
+      command: `composer run ${preferred.name}`,
+      rationale: "Uses the repo's Composer script (preferred for consistent config).",
+    };
+  }
+
+  if (phpstanScripts.length > 0) {
+    return {
+      command: `composer run ${phpstanScripts[0].name}`,
+      rationale: "Uses the repo's Composer script that invokes PHPStan.",
+    };
+  }
+
+  if (!fallbackInfo.binaryRelPath) {
+    return {
+      command: null,
+      rationale: "No PHPStan binary detected under vendor/bin and no Composer script found.",
+    };
+  }
+
+  const configArg = fallbackInfo.configRelPath ? ` -c ${fallbackInfo.configRelPath}` : "";
+
+  return {
+    command: `${fallbackInfo.binaryRelPath} analyse${configArg}`,
+    rationale: "Falls back to vendor/bin/phpstan with an explicit config when needed.",
+  };
+}
+
+/**
+ * Extracts lightweight hints from a phpstan.neon config.
+ *
+ * This does not parse NEON. It only checks for common directive tokens so the
+ * agent can quickly see whether scan directives are in use.
+ *
+ * @param {string} configText Raw phpstan config contents.
+ * @returns {{mentionsScanDirectories: boolean, mentionsScanFiles: boolean}} Hints.
+ */
+function buildConfigHints(configText) {
+  const t = configText.toLowerCase();
+
+  return {
+    mentionsScanDirectories: t.includes("scandirectories"),
+    mentionsScanFiles: t.includes("scanfiles"),
+  };
+}
+
+/**
+ * Extracts stub-like package references from a PHPStan config.
+ *
+ * The PHPStan config usually references stubs via vendor paths (for example,
+ * "vendor/php-stubs/wordpress-stubs"), so this helper focuses on composer-style
+ * "vendor/package" tokens containing "stubs".
+ *
+ * @param {string} configText Raw phpstan config contents.
+ * @returns {string[]} Unique, lowercased composer-style package references.
+ */
+function extractStubPackageReferences(configText) {
+  const matches = configText
+    .toLowerCase()
+    .match(/\b[a-z0-9_.-]+\/[a-z0-9_.-]*stubs[a-z0-9_.-]*\b/g);
+
+  if (!matches) return [];
+
+  return [...new Set(matches)].sort();
+}
+
+/**
+ * Builds a JSON report describing the current repository's PHPStan setup.
+ *
+ * @returns {object} A stable, machine-readable inspection report.
+ */
+function buildReport() {
+  const repoRoot = process.cwd();
+
+  const composerPath = path.join(repoRoot, "composer.json");
+  const composer = isFile(composerPath) ? readJsonSafe(composerPath) : null;
+
+  const phpstanConfigFiles = ["phpstan.neon", "phpstan.neon.dist"].filter((f) =>
+    isFile(path.join(repoRoot, f))
+  );
+  const phpstanBaselineFiles = ["phpstan-baseline.neon", "phpstan-baseline.neon.dist"].filter((f) =>
+    isFile(path.join(repoRoot, f))
+  );
+
+  let configRelPath = null;
+  if (phpstanConfigFiles.includes("phpstan.neon")) configRelPath = "phpstan.neon";
+  else if (phpstanConfigFiles.includes("phpstan.neon.dist")) configRelPath = "phpstan.neon.dist";
+
+  const configAbsPath = configRelPath ? path.join(repoRoot, configRelPath) : null;
+  const configText = configAbsPath ? readTextSafe(configAbsPath) : null;
+
+  const binaryRelPath = isFile(path.join(repoRoot, "vendor", "bin", "phpstan")) ? "vendor/bin/phpstan" : null;
+
+  const composerScripts = composer?.scripts && typeof composer.scripts === "object" ? composer.scripts : null;
+  const phpstanScripts = composerScripts ? findPhpstanScripts(composerScripts) : [];
+
+  const composerDependencies = [
+    ...Object.keys(composer?.require ?? {}),
+    ...Object.keys(composer?.["require-dev"] ?? {}),
+  ].sort();
+  const referencedDependencies = configText ? extractStubPackageReferences(configText) : [];
+
+  const configHints = configText ? buildConfigHints(configText) : null;
+
+  const suggested = suggestCommand(phpstanScripts, {
+    binaryRelPath,
+    configRelPath: configRelPath === "phpstan.neon" ? null : configRelPath,
+  });
+
+  const notes = [];
+
+  if (!composer) notes.push("No composer.json found; PHPStan is usually installed via Composer.");
+  if (phpstanConfigFiles.length === 0) notes.push("No phpstan.neon or phpstan.neon.dist found at repo root.");
+  if (!binaryRelPath && phpstanScripts.length === 0) notes.push("No PHPStan entrypoint detected (Composer script or vendor/bin/phpstan).");
+
+
+
+  return {
+    tool: { name: "phpstan_inspect", version: TOOL_VERSION },
+    repoRoot,
+    composer: {
+      exists: Boolean(composer),
+      path: isFile(composerPath) ? "composer.json" : null,
+      phpstanScripts,
+      dependencies: composerDependencies,
+    },
+    phpstan: {
+      configFiles: phpstanConfigFiles,
+      baselineFiles: phpstanBaselineFiles,
+      config: {
+        primary: configRelPath,
+        hints: configHints,
+        referencedDependencies,
+      },
+      binary: {
+        vendorBin: binaryRelPath,
+      },
+    },
+    suggested,
+    notes,
+  };
+}
+
+/**
+ * CLI entrypoint for printing the inspection report.
+ */
+function main() {
+  const report = buildReport();
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+main();

package/.agents/skills/wp-playground/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: wp-playground
+description: "Use for WordPress Playground workflows: fast disposable WP instances in the browser or locally via @wp-playground/cli (server, run-blueprint, build-snapshot), auto-mounting plugins/themes, switching WP/PHP versions, blueprints, PHPUnit testing, E2E Playwright testing, programmatic runCLI API, and debugging (Xdebug)."
+license: GPL-2.0-or-later
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Playground CLI requires Node.js 20.18+; runs WP in WebAssembly with SQLite."
+---
+
+# WordPress Playground
+
+## When to use
+
+- Spin up a disposable WordPress to test a plugin/theme without full stack setup.
+- Run or iterate on Playground Blueprints (JSON) locally.
+- Build a reproducible snapshot of a site for sharing or CI.
+- Switch WP/PHP versions quickly to reproduce issues.
+- Debug plugin/theme code with Xdebug in an isolated Playground.
+- Run PHPUnit tests without a local database (no Docker, no MySQL).
+- Write E2E Playwright tests against a real WordPress instance.
+- Automate Playground in CI/CD pipelines via the programmatic `runCLI` API.
+
+## Inputs required
+
+- Host machine readiness: Node.js ≥ 20.18, `npm`/`npx` available.
+- Project path to mount (`--auto-mount` or explicit mount mapping).
+- Desired WP version/PHP version (optional; defaults to latest WP, PHP 8.3).
+- Blueprint location/URL if running a blueprint.
+- Port preference if 9400 conflicts.
+- Whether Xdebug is needed.
+
+## Procedure
+
+### 0) Guardrails
+
+- Playground instances are ephemeral and SQLite-backed; **never** point at production data.
+- Confirm Node ≥ 20.18 (`node -v`) before running CLI.
+- If mounting local code, ensure it is clean of secrets; Playground copies files into an in-memory FS.
+
+### 1) Quick local spin-up (auto-mount)
+
+```bash
+cd <plugin-or-theme-root>
+npx @wp-playground/cli@latest server --auto-mount
+```
+- Opens on http://localhost:9400 by default. Auto-detects plugin/theme and installs it.
+- Add `--wp=<version>` / `--php=<version>` as needed.
+- For classic full installs already present, add `--skip-wordpress-setup` and mount the whole tree.
+
+### 2) Manual mounts or multiple mounts
+
+- Use `--mount=/host/path:/vfs/path` (repeatable) when auto-mount is insufficient (multi-plugin, mu-plugins, custom content).
+- Mount before install with `--mount-before-install` for bootstrapping installer flows.
+- Reference: `references/cli-commands.md`
+
+### 3) Run a Blueprint (no server needed)
+
+```bash
+npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>
+```
+- Use for scripted setup/CI validation. Supports remote URLs and local files.
+- Allow bundled assets in local blueprints with `--blueprint-may-read-adjacent-files` when required.
+- See `references/blueprints.md` for structure and common flags.
+
+### 4) Build a snapshot for sharing
+
+```bash
+npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site.zip
+```
+- Produces a ZIP you can load in Playground or attach to bug reports.
+
+### 5) Debugging with Xdebug
+
+- Start with `--xdebug` (or `--enable-xdebug` depending on CLI release) to expose an IDE key, then connect VS Code/PhpStorm to the host/port shown in CLI output.
+- Combine with `--auto-mount` for plugin/theme debugging.
+- Checklist: `references/debugging.md`
+
+### 6) Version switching
+
+- Use `--wp=` to pin WP (e.g., 6.9.0) and `--php=` to test compatibility.
+- If feature depends on Gutenberg trunk, prefer the latest WP release plus plugin if available; Playground images track stable WP plus bundled Gutenberg.
+
+### 7) Browser-only workflows (no CLI)
+
+- Launch quick previews with URL fragments or query params:
+  - Fragment: `https://playground.wordpress.net/#<base64-or-json-blueprint>`
+  - Query: `https://playground.wordpress.net/?blueprint-url=<public-url-or-zip>`
+- Use the live Blueprint Editor (playground.wordpress.net) to author blueprints with schema help; paste JSON and copy a shareable link.
+
+### 8) PHPUnit testing (no database required)
+
+Run PHPUnit inside Playground — every run starts with a clean WordPress install, fully isolated.
+
+Plugin:
+```bash
+npx @wp-playground/cli@latest php \
+  --auto-mount \
+  -- \
+  /wordpress/wp-content/plugins/MY_PLUGIN/vendor/bin/phpunit \
+  -c /wordpress/wp-content/plugins/MY_PLUGIN/phpunit.xml.dist
+```
+
+Theme (replace `plugins/` with `themes/`):
+```bash
+npx @wp-playground/cli@latest php \
+  --auto-mount \
+  -- \
+  /wordpress/wp-content/themes/MY_THEME/vendor/bin/phpunit \
+  -c /wordpress/wp-content/themes/MY_THEME/phpunit.xml.dist
+```
+
+- Requires PHPUnit installed via Composer in the project (`composer require --dev phpunit/phpunit`).
+- `--auto-mount` maps the current directory to the correct WP content path automatically.
+- Use `--php=8.1 --wp=6.5` flags to test against specific versions (PHP 7.4–8.5 supported).
+- Explicit mount: `--mount=.:/wordpress/wp-content/plugins/MY_PLUGIN`.
+
+### 9) E2E testing with Playwright
+
+Use `runCLI` from `@wp-playground/cli` to start a Playground server programmatically in Playwright tests. No Docker, no database.
+
+Install:
+```bash
+npm install --save-dev @playwright/test @wp-playground/cli
+npx playwright install chromium
+```
+
+Minimal `playwright.config.ts`:
+```ts
+import { defineConfig } from '@playwright/test';
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: false,
+  workers: 1,           // prevent port conflicts
+  timeout: 120_000,     // WP boot takes time
+  expect: { timeout: 30_000 },
+  use: { screenshot: 'only-on-failure', trace: 'on-first-retry' },
+});
+```
+
+First test (`tests/e2e/plugin.spec.ts`):
+```ts
+import { test, expect } from '@playwright/test';
+import { runCLI } from '@wp-playground/cli';
+
+let cli: Awaited<ReturnType<typeof runCLI>>;
+
+test.beforeAll(async () => {
+  cli = await runCLI({
+    command: 'server',
+    blueprint: {
+      preferredVersions: { php: '8.3', wp: 'latest' },
+      login: true,
+    },
+  });
+});
+
+test.afterAll(async () => { await cli?.server?.close(); });
+
+test('dashboard loads', async ({ page }) => {
+  await page.goto(`${cli.serverUrl}/wp-admin/`);
+  await expect(page.locator('#wpbody-content')).toBeVisible();
+});
+```
+
+Mount a local plugin:
+```ts
+cli = await runCLI({
+  command: 'server',
+  mount: { './': '/wordpress/wp-content/plugins/my-plugin' },
+  blueprint: {
+    preferredVersions: { php: '8.3', wp: 'latest' },
+    login: true,
+    steps: [{ step: 'activatePlugin', pluginPath: 'my-plugin/my-plugin.php' }],
+  },
+});
+```
+
+Locator priority (most to least preferred):
+1. `page.getByRole()` — buttons, headings, links, inputs
+2. `page.getByLabel()` — labeled form fields
+3. `page.getByText()` — visible text
+4. `page.getByTestId()` — your own `data-testid` attributes
+5. `page.locator()` — CSS/XPath last resort (WP core layout elements like `#wpadminbar`)
+
+Version matrix pattern:
+```ts
+const matrix = [{ php: '8.1', wp: '6.5' }, { php: '8.3', wp: 'latest' }];
+for (const { php, wp } of matrix) {
+  test.describe(`PHP ${php} + WP ${wp}`, () => {
+    // ... beforeAll/afterAll with those versions
+  });
+}
+```
+
+CI (GitHub Actions): see `references/e2e-playwright.md`.
+
+### 10) Programmatic `runCLI` API (scripts / Vitest integration)
+
+```ts
+import { runCLI } from '@wp-playground/cli';
+
+const server = await runCLI({
+  command: 'server',
+  php: '8.3',
+  wp: 'latest',
+  login: true,
+  mount: [{ hostPath: './my-plugin', vfsPath: '/wordpress/wp-content/plugins/my-plugin' }],
+  blueprint: { steps: [{ step: 'activatePlugin', pluginPath: 'my-plugin/plugin.php' }] },
+});
+
+// server.serverUrl — the base URL
+// server.server — the HTTP server instance (call .close() in afterEach)
+// server[Symbol.asyncDispose]() — cleanup in Vitest afterEach
+```
+
+Use `wordpressInstallMode: 'do-not-attempt-installing'` + `skipSqliteSetup: true` when testing pure PHP with no WordPress overhead.
+
+## Verification
+
+- Verify mounted code is active (plugin listed/active; theme selected).
+- For blueprints/snapshots, re-run with `--verbosity=debug` to confirm steps executed.
+- Run targeted smoke (e.g., `wp plugin list` inside Playground shell via browser terminal if exposed) or UI click-path.
+
+## Failure modes / debugging
+
+- **CLI exits complaining about Node**: upgrade to ≥ 20.18.
+- **Mount not applied**: check path, use absolute path, add `--verbosity=debug`.
+- **Blueprint cannot read local assets**: add `--blueprint-may-read-adjacent-files`.
+- **Port already used**: `--port=<free-port>`.
+- **Slow/locked UI**: disable `--experimental-multi-worker` if enabled; or enable it to improve throughput on CPU-bound runs.
+
+## Escalation
+
+- If PHP extensions or native DB access are required, Playground may be unsuitable; fall back to full WP stack or wp-env/Docker.
+- For browser-only embedding or VS Code extension specifics, consult the upstream docs: https://wordpress.github.io/wordpress-playground/

package/.agents/skills/wp-playground/references/blueprints.md

@@ -0,0 +1,36 @@
+## Blueprint quick reference
+
+Blueprints are JSON recipes that describe how Playground should set up WordPress.
+
+### Minimal example
+
+```json
+{
+  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
+  "steps": [
+    { "step": "installTheme", "themeZipUrl": "https://downloads.wordpress.org/theme/twentytwentythree.zip" },
+    { "step": "installPlugin", "pluginZipUrl": "https://downloads.wordpress.org/plugin/classic-editor.zip" }
+  ]
+}
+```
+
+### Common steps (non-exhaustive)
+
+- `setSiteUrl`, `setHomeUrl`
+- `installTheme`, `installPlugin` (ZIP URLs or local paths when allowed)
+- `activateTheme`, `activatePlugin`
+- `runPHP` (inline PHP)
+- `applyPatches` (filesystem patch)
+- `writeFile` (create/update files)
+- `importFile` (XML/WXR)
+- `wpConfigConstants` (define constants)
+- `preferredVersions` (pick WP/PHP; matches CLI `--wp` / `--php`)
+- `blueprintSteps` that include `extraLibraries` (e.g., Jetpack) and `features.networking` when browser networking is required
+
+### Tips
+
+- Use `--blueprint-may-read-adjacent-files` when the blueprint needs local files (e.g., custom plugin ZIP) during `run-blueprint` or `build-snapshot`.
+- For iterative authoring, keep blueprints small and compose via separate files.
+- Validate against the published schema URL above to catch typos.
+- For Gutenberg/nightly testing, set `--wp=<version>` to align with target WP.
+- To share quickly, encode the blueprint as base64 in the Playground URL fragment or host the JSON/ZIP and pass `?blueprint-url=…`.

package/.agents/skills/wp-playground/references/cli-commands.md

@@ -0,0 +1,39 @@
+## Playground CLI command cheatsheet
+
+> Requires Node.js 20.18+ and npm/npx.
+> Latest version: 3.0.20 (November 2025)
+
+### What's new in 2025
+
+- **PHP 8.3 is now the default** (since July 2025).
+- **New PHP extensions**: ImageMagick, SOAP, and AVIF GD support.
+- **OpCache enabled**: 42% faster response times (185ms → 108ms average).
+- **Multi-worker default**: `--experimental-multi-worker` now defaults to CPU count minus one.
+
+### Install / run server
+
+- `npx @wp-playground/cli@latest server [--port=9400] [--auto-mount] [--wp=<ver>] [--php=<ver>] [--verbosity=debug] [--blueprint=<url-or-path>]`
+- Mounts:
+  - `--auto-mount` (detect plugin/theme in CWD)
+  - `--mount=/abs/host:/vfs/path` (repeatable)
+  - `--mount-before-install` (apply mounts before WP install)
+
+### Run a blueprint
+
+- `npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url> [--blueprint-may-read-adjacent-files] [--wp=<ver>] [--php=<ver>] [--verbosity=debug]`
+- Use for scripted setup; no persistent server.
+
+### Build a snapshot
+
+- `npx @wp-playground/cli@latest build-snapshot --blueprint=<file-or-url> --outfile=./site.zip [--verbosity=debug]`
+- Produces a sharable ZIP usable by Playground UI or other CLI commands.
+
+### Debugging flags
+
+- `--xdebug` / `--enable-xdebug` (depends on release) to start Xdebug listener.
+- `--experimental-multi-worker` to speed multi-step blueprints; disable if unstable.
+
+### Version control
+
+- `--wp=<version>` to pick WordPress version (defaults to latest).
+- `--php=<version>` to pick PHP version (defaults to 8.3 since July 2025).