@linchpinagency/skills 0.1.0

package/skills/wp-local-setup/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: wp-local-setup
+description: Stand up the Linchpin baseline WordPress local environment — scaffold a new wp-content-shaped project repo (Composer-managed plugins from wpackagist.org + packagist.linchpin.com, a theme started from base-wp-theme-2026, release-please deploys) and/or wire a project repo into a WordPress Studio site by symlinking the repo in as the site's wp-content while preserving Studio's SQLite runtime pieces. Use when starting a new Linchpin WordPress project or setting up local development for an existing one.
+version: 1.0.0
+---
+
+# WordPress local setup (Linchpin baseline)
+
+Every Linchpin WordPress project follows the same baseline, driven by three facts:
+
+1. **The project repo IS `wp-content`.** The repo root contains `themes/`, `plugins/`
+   (and sometimes `mu-plugins/`) plus tooling — not a full WordPress install. WordPress
+   core is never committed.
+2. **Local dev runs on [WordPress Studio](https://developer.wordpress.com/studio/).**
+   The Studio site's `wp-content` directory is replaced with a **symlink to the repo
+   checkout**, so edits in the repo are live on the local site instantly.
+3. **Plugins and themes are Composer dependencies**, resolved from
+   [wpackagist.org](https://wpackagist.org) (wordpress.org mirrors) and
+   `https://packagist.linchpin.com` (private/premium packages, `linchpin/<slug>`).
+   Only project-specific code — the project theme and a client-functionality plugin —
+   is committed; everything else is gitignored and installed.
+
+## When to use
+
+**Use this when** you're starting a new WordPress project (scaffold the repo) or
+setting up local development for an existing one (wire it into Studio).
+
+**Not this for:**
+
+- **Operating a running Studio site** (WP-CLI, credentials, `eval`) → `wp-studio-cli`.
+- **Live servers** (Pressable prod/staging, deploy pipeline detail) → `wp-pressable`.
+- **Seeding local content/database** → out of scope; follow that project's own docs.
+- **One site's specific blocks/conventions** → that project's `AGENTS.md`/`CLAUDE.md`.
+
+## Part 1 — Scaffold a new project repo
+
+Target shape (the repo root doubles as `wp-content`):
+
+```
+<project>/
+  themes/<project>/            # committed — the project theme (from base-wp-theme-2026)
+  plugins/<project>-functionality/  # committed — client-functionality plugin (if needed)
+  composer.json                # plugin/theme dependencies + PHP QA tooling
+  package.json                 # JS tooling (theme builds via @wordpress/scripts)
+  index.php                    # "Silence is golden."
+  phpcs.xml.dist               # WordPress coding standards config
+  release-please-config.json   # automated releases (see wp-pressable for the pipeline)
+  renovate.json                # dependency automation
+  .gitignore                   # allowlist pattern — see below
+```
+
+### composer.json baseline
+
+```json
+{
+  "name": "linchpin/<project>",
+  "repositories": [
+    { "type": "composer", "url": "https://wpackagist.org" },
+    { "type": "composer", "url": "https://packagist.linchpin.com" }
+  ],
+  "require": {
+    "php": ">=8.2"
+  },
+  "require-dev": {
+    "composer/installers": "^2"
+  },
+  "extra": {
+    "installer-paths": {
+      "plugins/{$name}/": ["type:wordpress-plugin"],
+      "themes/{$name}/": ["type:wordpress-theme"]
+    }
+  }
+}
+```
+
+- wordpress.org plugins/themes → `wpackagist-plugin/<slug>` / `wpackagist-theme/<slug>`.
+- Premium or shared-private packages → `linchpin/<slug>` from packagist.linchpin.com.
+- A plugin built **only for this client** is committed to `plugins/` instead (and
+  allowlisted in `.gitignore`).
+- Which plugins a project needs is project-specific — don't copy another site's list.
+- Mature projects add the PHP QA stack to `require-dev` (`wp-coding-standards/wpcs`,
+  `phpstan/phpstan` + `szepeviktor/phpstan-wordpress`, `php-parallel-lint/php-parallel-lint`,
+  `friendsofphp/php-cs-fixer`) — mirror `linchpin/linchpin.com` when setting that up.
+
+### .gitignore baseline (allowlist pattern)
+
+Ignore everything Composer or the runtime writes; explicitly re-include what's ours:
+
+```gitignore
+# Plugins/themes are Composer-installed — commit only project code
+/plugins/*
+!plugins/<project>-functionality/
+!plugins/<project>-functionality/**
+/themes/*
+!themes/<project>/
+!themes/<project>/**
+/vendor
+node_modules
+
+# WordPress runtime
+debug.log
+/uploads/
+/upgrade/
+
+# WordPress Studio runtime (SQLite) — never commit these
+db.php
+/database
+/mu-plugins/sqlite-database-integration
+mu-plugins/99-studio-loader.php
+```
+
+Adding a new **committed** plugin later requires a new `!plugins/<name>/` pair —
+otherwise the `/plugins/*` rule silently keeps it out of git.
+
+### The project theme
+
+Start from the baseline theme, don't build from scratch:
+
+```bash
+git clone https://github.com/linchpin/base-wp-theme-2026.git themes/<project>
+rm -rf themes/<project>/.git
+```
+
+Then rebrand: update `style.css` (`Theme Name`, `Theme URI`, `Description`,
+`Text Domain`) and `package.json` (`name`), and search-replace the text domain in PHP
+files. It's a block theme (`theme.json`, `templates/`, `parts/`, `patterns/`) built
+with `@wordpress/scripts`:
+
+```bash
+cd themes/<project> && npm install && npm run build   # npm start = watch mode
+```
+
+## Part 2 — Wire the repo into a Studio site
+
+Prereq: the `studio` CLI on `PATH` (Studio app → **Settings → General → Studio CLI**),
+and the repo cloned somewhere like `~/GitHub/<project>` — **not** inside `~/Studio`.
+
+1. **Create a Studio site** for the project. Convention: site path `~/Studio/<project>`.
+   ```bash
+   studio create --path ~/Studio/<project> --name "<Project>"
+   ```
+   (The Studio app's **Add site** or the Studio MCP `site_create` work too.)
+2. **Stop the site** before touching its filesystem:
+   ```bash
+   studio stop --path ~/Studio/<project>
+   ```
+3. **Rescue Studio's SQLite runtime pieces** from the freshly provisioned
+   `wp-content` into the repo checkout (they're gitignored, so this is safe):
+   ```bash
+   SITE=~/Studio/<project>; REPO=~/GitHub/<project>
+   mkdir -p "$REPO/mu-plugins"
+   cp    "$SITE/wp-content/db.php"         "$REPO/"
+   cp -R "$SITE/wp-content/mu-plugins/."   "$REPO/mu-plugins/"   # sqlite-database-integration
+   cp -R "$SITE/wp-content/database"       "$REPO/"              # .ht.sqlite lives here
+   ```
+   (The trailing `/.` merges into an existing committed `mu-plugins/` dir instead of
+   nesting a second one inside it.)
+   Without these three the site cannot boot — Studio has no MySQL; the `db.php`
+   drop-in + SQLite mu-plugin **are** the database layer.
+4. **Symlink the repo in as `wp-content`:**
+   ```bash
+   mv "$SITE/wp-content" "$SITE/wp-content-studio-default"   # keep as fallback
+   ln -s "$REPO" "$SITE/wp-content"
+   ```
+5. **Install dependencies and build:**
+   ```bash
+   cd "$REPO" && composer install
+   cd themes/<project> && npm install && npm run build
+   ```
+6. **Start and activate:**
+   ```bash
+   studio start --skip-browser --path ~/Studio/<project>
+   studio wp theme activate <project> --path ~/Studio/<project>
+   studio config set --debug-log --path ~/Studio/<project>   # baseline: log to wp-content/debug.log
+   ```
+
+   If the started site can't read the symlinked files (blank page, file-not-found
+   errors), allow PHP to follow the symlink out of the site directory:
+   `studio config set --file-access all-files --path ~/Studio/<project>`. The default
+   `site-directory` mode normally follows the symlink fine — this is a fallback only.
+
+### Verify
+
+```bash
+studio site status --path ~/Studio/<project> --format json   # URL + admin credentials
+studio wp theme list --status=active --path ~/Studio/<project>
+studio wp plugin list --path ~/Studio/<project>               # Composer-installed plugins visible
+studio wp eval 'echo ABSPATH;' --path ~/Studio/<project>      # runtime answers
+```
+
+Then load the site URL — a booted front page on the project theme means the wiring is
+correct. From here, day-to-day operation is `wp-studio-cli`.
+
+## Gotchas
+
+- **`--path` targets the SITE, not the repo.** `studio` commands take
+  `~/Studio/<project>` (or run from that directory). The repo path only appears in the
+  symlink.
+- **`wp-config.php` lives in the site root**, above `wp-content` — never in the repo.
+  Studio strips the MySQL `DB_*` constants; don't add them back, and don't reference
+  them in code (SQLite handles the connection via `db.php`).
+- **Never commit the Studio runtime pieces** (`db.php`, `/database`,
+  `mu-plugins/sqlite-database-integration`). They're local-only; on a Pressable deploy
+  they would shadow the host's real MySQL setup.
+- **Never delete them locally either** — the site dies without its database layer.
+- **Composer writes into `plugins/` and `themes/`** (via `installer-paths`) and those
+  paths are gitignored — that's by design. CI runs `composer install` at deploy time;
+  a plugin "missing from git" is usually just Composer-managed.
+- **The symlink cuts both ways:** edits in the repo are live immediately, but
+  `wp plugin update`/`wp plugin install` run against the live site also **write into
+  your repo checkout**. Manage plugin versions through `composer.json`, not the admin
+  or WP-CLI, or the next `composer install` reverts them.
+- **Media isn't in git** (`/uploads/` is ignored). Getting real content/uploads locally
+  is per-project — check that project's docs.
+
+## Quick reference
+
+| Task | Command |
+| --- | --- |
+| Clone base theme | `git clone https://github.com/linchpin/base-wp-theme-2026.git themes/<project>` (then `rm -rf .git`, rebrand) |
+| Install plugins | `composer install` (repo root) |
+| Add a wordpress.org plugin | `composer require wpackagist-plugin/<slug>` |
+| Add a premium/shared plugin | `composer require linchpin/<slug>` (packagist.linchpin.com) |
+| Build the theme | `npm run build` in `themes/<project>` (`npm start` to watch) |
+| Symlink repo into Studio | `mv <site>/wp-content <site>/wp-content-studio-default && ln -s <repo> <site>/wp-content` |
+| Start the site | `studio start --skip-browser --path ~/Studio/<project>` |
+| Activate the theme | `studio wp theme activate <project> --path ~/Studio/<project>` |
+| Site URL + credentials | `studio site status --path ~/Studio/<project> --format json` |
+
+## Guardrails
+
+- **Never commit WordPress core, `wp-config.php`, or Studio's SQLite runtime**
+  (`db.php`, `/database`, `mu-plugins/sqlite-database-integration`) — on a real host they
+  shadow the live MySQL setup.
+- **Never delete the Studio runtime pieces locally** either; the site dies without them.
+- **Never move `wp-content` without preserving the original.** Rename it
+  (`wp-content-studio-default`) before symlinking, so the site can be restored.
+- **Never manage plugin versions through the admin or `wp plugin update`** when the repo is
+  symlinked in — those writes land in your checkout and get reverted by the next
+  `composer install`. Versions change in `composer.json`.
+- **Never commit Composer-installed plugins/themes** — `installer-paths` writes into
+  gitignored directories by design.
+- Don't hand-edit versions or `CHANGELOG.md` in a scaffolded repo — release-please owns
+  them ([`commit-and-release`](../commit-and-release/SKILL.md)).
+
+## Done
+
+- [ ] Repo root is `wp-content`-shaped (`themes/`, `plugins/`, tooling) with no core files.
+- [ ] `composer install` resolves all plugins from wpackagist / packagist.linchpin.com.
+- [ ] The Studio site's `wp-content` is a symlink to the repo, with the original preserved
+      and the SQLite runtime pieces intact.
+- [ ] The site loads, the project theme is active, and the admin URL/credentials are known.
+- [ ] `.gitignore` allowlists only project code; `git status` is clean of vendored plugins.
+
+## Related skills
+
+- [`wp-studio-cli`](../wp-studio-cli/SKILL.md) — operating the running Studio site (WP-CLI
+  passthrough, `eval`, the PHP-WASM `ABSPATH` rule).
+- [`wp-pressable`](../wp-pressable/SKILL.md) — the hosted environments this baseline deploys
+  to, and the release-please → `linchpin/actions` pipeline.
+- [`task-tracking`](../task-tracking/SKILL.md) — tie the setup work to a ClickUp task before
+  committing.

package/skills/wp-pressable/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: wp-pressable
+description: Operate a Pressable-hosted WordPress site (production or staging) from an agent — connect via the Pressable MCP or SSH+WP-CLI, run read-first diagnostics, and safely fix the classic "renders locally but not on production" Full-Site-Editing bug where database template/part overrides shadow the deployed theme files. Use for any WordPress project hosted on Pressable when you need to inspect or change the live server (not just the repo).
+version: 1.0.0
+---
+
+# WordPress on Pressable (agent operations)
+
+[Pressable](https://pressable.com/) is Automattic's managed WordPress host. Code reaches it
+through a deploy pipeline (Linchpin convention: `release-please` → a published GitHub
+Release → `linchpin/actions` deploy workflow), while the **database lives only on the
+server**. Two facts drive everything in this skill:
+
+1. **Change code by deploying, never by editing files on the server.** The next deploy
+   overwrites server files.
+2. **Change content/templates by operating on the server database** (MCP or SSH+WP-CLI),
+   because **deploys never touch the database**.
+
+Most "I shipped it but it's not on prod" tickets are a collision of those two facts. See
+[The signature bug](#the-signature-bug-it-shows-locally-but-not-on-production).
+
+## When to use
+
+**Use this when** you need to inspect or change a **live Pressable environment**
+(production or staging) — its database, templates/parts, caches, users, or runtime state —
+via the Pressable MCP or SSH+WP-CLI.
+
+**Not this for:**
+
+- **Local development** → use `wp-studio-cli` (Studio / PHP-WASM).
+- **Shipping code** → code reaches Pressable only through the deploy pipeline; never edit
+  theme/plugin files on the server (the next deploy overwrites them).
+- **Task tracking / commits** → that's `task-tracking`.
+
+This skill operates the **server and its database** — nothing else.
+
+## Two ways in
+
+### A) Pressable MCP (preferred when connected)
+
+A remote MCP server at `https://mcp.pressable.com/mcp`, authenticated with a bearer token.
+
+```bash
+# Native HTTP transport — cleaner than the mcp-remote wrapper.
+claude mcp add --transport http pressable https://mcp.pressable.com/mcp \
+  --header "Authorization: Bearer <TOKEN>"
+```
+
+- **Quote the whole header as one argument.** A common footgun is
+  `--header Authorization:Bearer <TOKEN>` (no space / unquoted) — the shell splits it into
+  separate argv tokens and the server gets a malformed header, then fails to connect.
+- **Restart to connect.** MCP servers connect at agent **startup**. After adding/rotating,
+  restart the session, then confirm with `claude mcp list` → `pressable … ✔ Connected`.
+- **`401 Invalid Authorization token` = dead token.** Regenerate it from your Pressable
+  account and re-add the server. Verify a token fast without restarting:
+  ```bash
+  curl -s -o /dev/null -w '%{http_code}\n' -X POST https://mcp.pressable.com/mcp \
+    -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
+    -H "Accept: application/json, text/event-stream" \
+    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"diag","version":"1"}}}'
+  # 200 = good, 401 = regenerate the token
+  ```
+- **Don't leave the raw token in `~/.claude.json`.** Pull it from a secret manager
+  (1Password, etc.). The token grants control of the host.
+
+### B) SSH + WP-CLI (always available; the fallback and the scripting route)
+
+When the MCP is down (or you want deterministic, scriptable fixes), use SSH.
+
+- Get SSH/SFTP credentials from the Pressable dashboard (**Sites → <site> → SSH/SFTP**).
+- Connect; you land in the site root with `wp` on `PATH`. Confirm: `wp --info`.
+- Everything below is plain WP-CLI, so it works identically whether you reach `wp` over SSH
+  or through the MCP's WP-CLI tool.
+
+## Guardrails
+
+- **It's production.** Confirm with the user before any mutating action on a live prod
+  site; lead with read-only diagnostics and back up first.
+- **Read before write.** List and inspect first; mutate only after you've confirmed the
+  cause.
+- **Back up before any DB change:** `wp db export ~/backup-$(date +%F-%H%M).sql`.
+- **Never edit theme/plugin files on the server** — deploys overwrite them. File changes go
+  through the repo + deploy pipeline.
+- **Flush caches after content/DB changes.** Pressable runs object + edge (page) cache:
+  `wp cache flush`, then clear the page cache from the Pressable dashboard (or
+  `wp pressable-cache clear` if the helper plugin is present). Stale cache makes a correct
+  fix look like it didn't work.
+
+## The signature bug: "it shows locally but not on production"
+
+**Symptom.** A block / pattern / section lives in the theme's template **files** and renders
+on your local site, but is missing on the Pressable site — even though the theme and plugin
+are deployed.
+
+**Cause.** In block (Full-Site-Editing) themes, the moment a template or template part is
+edited in the Site Editor, WordPress writes a copy to the database (a `wp_template` or
+`wp_template_part` post) and **that DB copy permanently shadows the theme file**. Deploys
+ship files, not the DB — so a block you added to the file never appears, because the server
+keeps serving the older DB copy.
+
+**Diagnose (read-only):**
+
+```bash
+# 1. Is the code actually deployed? (rules out a stale release)
+wp plugin get <plugin-slug> --field=version
+wp eval 'var_export( WP_Block_Type_Registry::get_instance()->is_registered("<namespace/block>") );'
+#   -> false or an old version => deploy problem, not a DB problem. Ship/redeploy.
+
+# 2. Which templates/parts are DB overrides that shadow the files?
+wp post list --post_type=wp_template      --post_status=any --fields=ID,post_name,post_title
+wp post list --post_type=wp_template_part --post_status=any --fields=ID,post_name,post_title
+#   -> a row for the template that should show the block (e.g. front-page, page, home) is an override.
+
+# 3. Confirm the override is what's hiding it
+wp eval 'echo has_block("<namespace/block>", get_post(<ID>)->post_content) ? "HAS" : "MISSING";'
+#   -> "MISSING" confirms the stale DB copy is the culprit.
+```
+
+**Fix (pick one):**
+
+- **Clean revert to the deployed file** (recommended when templates are version-controlled
+  in the repo): delete the DB override so WordPress falls back to the theme file, which
+  already has the block in the right place.
+  ```bash
+  wp post delete <ID> --force      # repeat per template
+  ```
+  ⚠️ This discards **all** Site-Editor edits to that template, reverting it entirely to the
+  repo's file. Admin equivalent: **Appearance → Editor → Templates → ⋯ → Clear
+  customizations**.
+- **Surgical** (when production has intentional Site-Editor-only edits you must keep): add
+  the block in the Site Editor, or `wp post update <ID>` the override's `post_content`,
+  instead of deleting.
+
+Then `wp cache flush` and clear the Pressable page cache.
+
+## Deploy & rollback awareness (Linchpin convention)
+
+- `main` → `release-please` opens a release PR → merging it **publishes a GitHub Release** →
+  `linchpin/actions` deploy workflow builds and deploys to Pressable (`environment:
+  production`), attaching a `release.zip`.
+- **Staging** deploys on push to the `staging` branch.
+- **Rollback** re-deploys a previous `release.zip` (no rebuild) via the repo's
+  `rollback.yml` workflow.
+- **Implication:** a **code** fix is not live until a release is published and deployed — a
+  merge to `main` alone is not on prod. A **content/template** fix is applied directly on
+  the server (MCP/SSH), as above, and is independent of deploys.
+
+## Quick reference
+
+| Task | Command |
+| --- | --- |
+| Add the MCP | `claude mcp add --transport http pressable https://mcp.pressable.com/mcp --header "Authorization: Bearer <TOKEN>"` |
+| Verify MCP connects | `claude mcp list` → `pressable … ✔ Connected` (restart session after adding) |
+| SSH in | dashboard **Sites → <site> → SSH/SFTP**, then `wp --info` |
+| Back up DB | `wp db export ~/backup-$(date +%F-%H%M).sql` |
+| Deployed plugin version | `wp plugin get <plugin> --field=version` |
+| Is a block registered | `wp eval 'var_export( WP_Block_Type_Registry::get_instance()->is_registered("<ns/block>") );'` |
+| List template overrides | `wp post list --post_type=wp_template --post_status=any --fields=ID,post_name,post_title` |
+| List part overrides | `wp post list --post_type=wp_template_part --post_status=any --fields=ID,post_name,post_title` |
+| Override has block? | `wp eval 'echo has_block("<ns/block>", get_post(<ID>)->post_content) ? "HAS" : "MISSING";'` |
+| Revert template to file | `wp post delete <ID> --force` (wipes that template's Site-Editor edits) |
+| Flush caches | `wp cache flush` + clear page cache in the Pressable dashboard |
+
+## Done
+
+- [ ] The environment you touched (production vs staging) is stated explicitly.
+- [ ] Diagnosis ran read-only first, and the cause is named — deploy gap vs DB override.
+- [ ] Any DB change was preceded by `wp db export` and confirmed with the user.
+- [ ] No theme or plugin file was edited on the server.
+- [ ] Object and page caches flushed, and the fix verified on the live URL.
+- [ ] If the fix belongs in code, it's tracked back to the repo and the deploy pipeline —
+      the server change is not the permanent fix.

package/skills/wp-studio-cli/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: wp-studio-cli
+description: Operate a local WordPress Studio site — preferring the wordpress-studio MCP (site_list, site_start, wp_cli, validate_blocks, take_screenshot, inspect_design) and falling back to the `studio` CLI when MCP isn't connected. Use whenever working against a Linchpin local dev install, running WP-CLI locally, reading admin credentials, validating block markup, or screenshotting a local site. Studio runs PHP-WASM, so file paths inside `wp eval` must use ABSPATH (resolves to /wordpress/), never host filesystem paths.
+version: 1.1.0
+---
+
+# WordPress Studio
+
+[WordPress Studio](https://developer.wordpress.com/studio/) is **Linchpin's default local
+environment**, running each site in a **PHP-WASM** runtime. Older projects still on wp-env
+or LocalWP predate that switch — new work is Studio.
+
+Two interfaces reach the same site: the **wordpress-studio MCP** (structured tools, richer
+capabilities) and the **`studio` CLI** (always present with the app). Prefer MCP; the CLI is
+the fallback and the scripting route.
+
+## When to use
+
+- Running WP-CLI, inspecting options/posts, or evaluating PHP against a local Studio site.
+- Needing the site's admin URL or credentials.
+- Validating serialized block markup, or screenshotting a local page.
+- Reproducing a bug locally before touching a server.
+
+**Not this skill:** creating the site or symlinking a repo into it —
+[`wp-local-setup`](../wp-local-setup/SKILL.md). Live servers —
+[`wp-pressable`](../wp-pressable/SKILL.md). Performance/accessibility audits —
+[`wp-audit`](../wp-audit/SKILL.md). A legacy project on wp-env or LocalWP — use that
+project's tooling ([`quality-gates`](../quality-gates/SKILL.md) detects which).
+
+## Preflight — pick the interface
+
+1. **Try MCP first.** A cheap call like `site_list` confirms it's connected.
+2. **Fall back to the CLI** when MCP is absent, erroring, or you need something scriptable
+   in a shell pipeline: `studio site list`.
+3. **If neither works**, say so — Studio isn't installed or the CLI isn't enabled. Don't
+   guess at site paths.
+
+Whichever you use, **resolve the target site explicitly**. Never assume the current
+directory is the site.
+
+## MCP tools (preferred)
+
+| Need | Tool |
+| --- | --- |
+| List sites, find paths/URLs | `site_list` |
+| Site detail, admin credentials | `site_info` |
+| Start / stop a site | `site_start`, `site_stop` |
+| Run any WP-CLI command | `wp_cli` |
+| Validate serialized block markup | `validate_blocks` |
+| Screenshot a page | `take_screenshot` |
+| Inspect rendered DOM / computed styles | `inspect_design` |
+| Push/pull against a connected remote | `site_push`, `site_pull` |
+
+`wp_cli` is the general-purpose escape hatch — anything the CLI can do, it can do. Reach for
+a shell only when you need to pipe output into other commands.
+
+**`site_push` / `site_pull` move real data.** Treat them like a deploy: confirm the direction
+and the target with the user first, and never push to a production-connected site from here.
+
+## CLI fallback
+
+Every `studio` command takes a global `--path` pointing at the site's WordPress files. It
+**defaults to the current directory**, so `cd` in or pass `--path`. Running outside a
+registered site path fails with "The specified directory is not added to Studio."
+
+```bash
+studio site list                                   # names, paths, URLs, online status
+studio site start --path ~/Studio/<site>           # a site must be Online for `wp`
+studio site status --path ~/Studio/<site> --format json   # adminUsername/adminPassword/URL
+studio wp <args> --path ~/Studio/<site>            # full WP-CLI passthrough
+```
+
+## Eval PHP — and the ABSPATH rule
+
+This applies to **both** interfaces — MCP `wp_cli` and `studio wp` run in the same runtime.
+
+> **The PHP-WASM runtime cannot see your host filesystem.** Inside `eval`, file paths must
+> be WASM paths. Use the `ABSPATH` constant, which resolves to `/wordpress/` — not
+> `/Users/...` host paths.
+
+```bash
+# ✅ correct — ABSPATH-relative path inside the WASM FS
+studio wp eval 'echo ABSPATH;' --path ~/Studio/<site>
+# -> /wordpress/
+
+# ✅ read/render a theme file from inside the site
+studio wp eval 'echo file_get_contents(ABSPATH . "wp-content/themes/<theme>/style.css");' \
+  --path ~/Studio/<site>
+
+# ❌ wrong — a host path is invisible to PHP-WASM and returns nothing/false
+studio wp eval 'echo file_get_contents("/Users/me/Documents/GitHub/<repo>/themes/<theme>/style.css");' \
+  --path ~/Studio/<site>
+```
+
+Even when Studio **hardlinks** `wp-content/themes/<x>` and `wp-content/plugins/<x>` from a
+host repo (so editor changes show up live), the PHP runtime still resolves them only via
+WASM/`ABSPATH` paths.
+
+To operate on host files (grep, list, edit), use ordinary shell tools against the **repo
+path**; switch to `eval` + `ABSPATH` only when the running site must read or execute them.
+
+## Common recipes
+
+```bash
+# Render a block pattern's PHP to inspect its output
+studio wp eval 'ob_start(); include ABSPATH . "wp-content/themes/<theme>/patterns/<name>.php"; echo ob_get_clean();' \
+  --path ~/Studio/<site>
+
+# Flush rewrite rules / caches after changes
+studio wp rewrite flush --path ~/Studio/<site>
+studio wp cache flush --path ~/Studio/<site>
+
+# Search-replace a URL across the DB (dry run first!)
+studio wp search-replace 'http://old.test' 'https://new.test' --dry-run --path ~/Studio/<site>
+```
+
+## Gotchas
+
+- **Deprecation noise:** Studio's WP-CLI may print `Deprecated: Case statements followed
+  by a semicolon …` lines (from a bundled dependency). They're benign — the real result is
+  still on stdout. When scripting, parse stdout and ignore stderr (`2>/dev/null`), and be
+  ready to strip a stray leading/trailing deprecation line.
+- **`--path` is required** on the CLI unless you `cd` into the site directory first.
+- **Site must be Online** before `wp` — `site_start` or `studio site start`.
+- **Block markup gets validated, not eyeballed.** When you write serialized block markup
+  into templates or content, run `validate_blocks` and repair until clean — see
+  [`wordpress-blocks`](../wordpress-blocks/SKILL.md).
+
+## Quick reference
+
+| Task | MCP | CLI fallback |
+| --- | --- | --- |
+| List sites + paths | `site_list` | `studio site list` |
+| Start a site | `site_start` | `studio site start --path ~/Studio/<site>` |
+| Admin user/pass | `site_info` | `studio site status --path … --format json` |
+| Run WP-CLI | `wp_cli` | `studio wp <args> --path ~/Studio/<site>` |
+| Eval PHP | `wp_cli` (`eval`, use `ABSPATH`) | `studio wp eval '<php>' --path …` |
+| Validate blocks | `validate_blocks` | — |
+| Screenshot | `take_screenshot` | — |
+
+## Guardrails
+
+- **Never use host paths inside `eval`** — PHP-WASM can't see them and returns `false`
+  rather than an error, which reads as "the file is empty" and sends you debugging the wrong
+  thing. Always build paths from `ABSPATH`.
+- **`--dry-run` first** on anything that rewrites the database (`search-replace`, bulk
+  `wp post` operations). A local site is cheap to break but expensive to re-seed.
+- **Never `site_push`** without explicit confirmation of direction and target — it writes to
+  a remote site.
+- **Don't edit files through the site directory** when `wp-content` is a symlink to a repo
+  checkout — edit the repo, which is the same files with git history attached.
+- **Don't treat a green local result as a production result.** Studio runs SQLite and
+  PHP-WASM; MySQL-specific behavior and server caches differ. Verify on the server via
+  [`wp-pressable`](../wp-pressable/SKILL.md) when it matters.
+- Don't fabricate output when a command prints deprecation noise — parse stdout, and say so
+  if a command produced nothing.
+
+## Done
+
+- [ ] Interface chosen deliberately — MCP tried first, CLI fallback only if needed.
+- [ ] The target site was resolved explicitly, not assumed from the working directory.
+- [ ] The site was Online before running `wp`.
+- [ ] Any `eval` path is `ABSPATH`-relative.
+- [ ] Destructive DB commands were dry-run first; no unconfirmed `site_push`.
+- [ ] Reported output is what the command actually returned, deprecation noise excluded.