refactor(skill): trim upgrade-wp-coding-agents to policy + procedure (#75)

The previous SKILL.md was ~157 lines and 70% of it restated what
`./upgrade.sh --help` and the script's own summary block already
print at runtime. The skill's actual job — what it does that
`upgrade.sh` cannot — is enforce policy:

  - never restart the chat bridge automatically (kills active
    sessions including the one the agent is talking in)
  - never skip the dry-run on a live install
  - never touch user state (auth, OAuth, memory files, etc.)
  - never hardcode workspace paths

That's the load-trigger value. A slash command can run the script,
but it can't enforce dry-run-first, can't gate restart on user
confirmation, and can't pivot mid-upgrade when the agent spots an
upstream bug worth fixing in the same session.

Trim to 56 lines:
  - keep the frontmatter description verbatim (load-trigger key)
  - keep "When to use" verbatim (recall trigger)
  - collapse Steps 1-6 into one 4-step procedure block
  - drop the chat-bridge-identification table (script auto-detects + summary prints)
  - drop the verify section (summary block already prints the right commands)
  - drop the persistent-skill-source explainer (implementation detail, not user-facing)
  - keep "Never do" verbatim (this IS the skill's job)
  - add a "Source of truth" table pointing at `--help` and the
    summary block for everything that was cut

Net: 157 → 56 lines (−64%). No behaviour change — the skill still
loads on the same triggers, still enforces the same policies, still
points at the same script.

Surfaced during a live upgrade session where I noticed the procedural
half of the skill was just narrating what the script's output already
said. The fix-bug-and-release pivot in that same session would have
been impossible behind a slash command — that conversational pivot is
exactly the value Option B (trim) preserves and Option A (replace
with slash command) would have lost.

## AI assistance

- **AI assistance:** Yes
- **Tool(s):** Claude Code (Sonnet 4.5)
- **Used for:** drafted the trimmed skill body and this commit message.
  Chris reviewed the cut against the actual session usage and
  approved the structure (policy + 4-step procedure + source-of-truth
  table) before commit.

Author: chubes4

skills/upgrade-wp-coding-agents/SKILL.md

@@ -6,9 +6,7 @@ compatibility: "Requires a wp-coding-agents repo clone and an existing setup. Wo
 
 # Upgrade wp-coding-agents
 
-**Purpose:** Pull the latest wp-coding-agents improvements onto a live install — new plugin versions, updated skills, regenerated AGENTS.md, systemd template fixes (VPS), and the opencode-claude-auth patch — without touching opencode config, WordPress, or agent memory.
-
-The same `upgrade.sh` script handles both environments. It auto-detects and branches internally; you do not need to memorise paths.
+`upgrade.sh` already auto-detects the environment, picks the chat bridge, prints a diff in dry-run, and emits the right verify + restart commands in its summary block. This skill exists for the **policy boundary** the script can't enforce on its own.
 
 ## When to use
 
@@ -18,140 +16,41 @@ The user says something like:
 - "My dm-context-filter.ts is out of date"
 - "Regenerate AGENTS.md from the latest template"
 
-## Step 1 — Detect the environment and chat bridge
-
-Before running anything, identify (a) which side you are on and (b) which chat bridge is installed. The script auto-detects both, but you should know too so you can give the user the right restart instructions.
-
-### Environment signals
-
-| Signal | VPS | Local |
-|---|---|---|
-| `/etc/systemd/system/<bridge>.service` exists | yes | no |
-| `command -v studio` succeeds | usually no | usually yes |
-| Platform | Linux | macOS or Linux |
-
-**On macOS the script auto-enables `--local`.** On Linux without `--local`, the script assumes VPS.
-
-### Supported chat bridges
-
-`upgrade.sh` auto-detects one of three chat bridges based on installed service files or binaries:
-
-| Bridge | VPS unit(s) | Local launchd plist(s) | Per-install artifacts |
-|---|---|---|---|
-| **kimaki** | `kimaki.service` | `com.wp.kimaki.plist` | `/opt/kimaki-config/` on VPS; `$(npm root -g)/kimaki/plugins` + `$KIMAKI_DATA_DIR/kimaki-config/` on local |
-| **cc-connect** | `cc-connect.service` | `com.wp.cc-connect.plist` | none (user owns `$HOME/.cc-connect/config.toml`) |
-| **telegram** | `opencode-serve.service` + `opencode-telegram.service` | `com.wp.opencode-serve.plist` + `com.wp.opencode-telegram.plist` | none (user owns `.env` files under `$HOME/.config/opencode-*/`) |
-
-Ordering matches install priority: kimaki > cc-connect > telegram if more than one is installed.
-
-### Restart commands
-
-Do not guess restart commands. The script's summary block prints the exact command for the detected bridge × environment combination at the end of every run — pass that through to the user verbatim. The source of truth for these commands is `lib/chat-bridges.sh::bridge_restart_cmd`; they are rendered once and reused by both `upgrade.sh` and setup-time summary output, so the skill never needs its own copy.
-
-## Step 2 — Resolve the repo path
-
-Never hardcode the workspace path. Use whichever clone the user has on disk:
-
-```bash
-# Inside the wp-coding-agents clone:
-cd "$(git rev-parse --show-toplevel)"
-
-# Or from a known checkout:
-cd /path/to/wp-coding-agents
-```
-
-Then pull latest:
-
-```bash
-git pull origin main
-```
-
-> If the user maintains a fork or a feature branch, ask before pulling. Default is `origin/main`.
-
-## Step 3 — Dry run
+## Procedure
 
-Always dry-run first on a live install. The dry-run never modifies anything.
+1. **Find the repo and pull main:**
+   ```bash
+   cd "$(git -C ~/Developer/wp-coding-agents rev-parse --show-toplevel)"
+   git pull origin main
+   ```
+   If the user maintains a fork or a feature branch, ask before pulling. Default is `origin/main`.
 
-**VPS:**
-```bash
-./upgrade.sh --dry-run
-```
+2. **Dry-run first.** Always.
+   ```bash
+   ./upgrade.sh --dry-run                      # VPS
+   ./upgrade.sh --dry-run --wp-path /path      # local (auto-set on macOS)
+   ```
+   Read the output. Stop and investigate if anything looks wrong (wrong runtime, unexpected unit rewrite, plugin paths point somewhere weird).
 
-**Local:**
-```bash
-./upgrade.sh --dry-run --wp-path "/path/to/site"
-# --local is auto on macOS; pass it explicitly on Linux local installs.
-```
+3. **Apply** by dropping `--dry-run`. The script prints a summary with the exact verify + restart commands for the detected bridge × environment. Pass them through to the user verbatim — do not paraphrase, do not guess.
 
-Review the diff output. If anything looks wrong (wrong runtime detected, unexpected unit rewrite, plugin paths point somewhere weird), stop and investigate before proceeding.
+4. **Tell the user to restart the chat bridge themselves.** Active chat sessions die on restart, so the user picks the moment.
 
-## Step 4 — Run the upgrade
+Run `./upgrade.sh --help` for scope flags (`--kimaki-only`, `--skills-only`, `--agents-md-only`, `--repair-opencode-json`, etc.) and the full list of what the script touches and never touches.
 
-Drop `--dry-run`:
-
-**VPS:**
-```bash
-./upgrade.sh
-```
-
-**Local:**
-```bash
-./upgrade.sh --wp-path "/path/to/site"
-```
-
-Backups are written next to each touched file with a timestamp suffix. On VPS that means `/opt/kimaki-config.backup.<ts>`, `AGENTS.md.backup.<ts>`, `kimaki.service.backup.<ts>`. On local, the kimaki-config backup lands under `$KIMAKI_DATA_DIR/backups/` (defaults to `~/.kimaki/backups/`).
-
-### Persistent skill source
-
-`--skills-only` (and a full run) also mirrors every installed skill into the persistent kimaki-config skill source dir. This is the durable copy that survives `npm update -g kimaki` wipes of `$(npm root -g)/kimaki/skills/`:
-
-- **Local:** `$KIMAKI_DATA_DIR/kimaki-config/skills/` (defaults to `~/.kimaki/kimaki-config/skills/`)
-- **VPS:** `/opt/kimaki-config/skills/`
-
-On local, `upgrade.sh` runs `post-upgrade.sh` inline. On VPS, `kimaki.service`'s `ExecStartPre` runs it on next service start. `post-upgrade.sh` performs two symmetric passes against `$(npm root -g)/kimaki/skills/`: (1) remove the unwanted bundled skills listed in `skills-kill-list.txt`, and (2) restore the wp-coding-agents skills from the persistent source dir. Both passes are idempotent and run on every kimaki restart.
-
-## Step 5 — Verify
-
-The script's summary block prints the right verify commands for the detected environment. Run them and sanity-check.
-
-**VPS verify:**
-```bash
-systemctl status kimaki
-diff -u /opt/kimaki-config/plugins/dm-context-filter.ts \
-        "$(git -C /path/to/wp-coding-agents rev-parse --show-toplevel)/kimaki/plugins/dm-context-filter.ts"
-head -20 /var/www/*/AGENTS.md
-```
-
-**Local verify:**
-```bash
-# launchd (auto-installed on macOS):
-launchctl print "gui/$(id -u)/com.wp.kimaki" | head -20
-# or, if running kimaki manually:
-pgrep -fl kimaki
-
-NPM_ROOT="$(npm root -g)"
-diff -u "$NPM_ROOT/kimaki/plugins/dm-context-filter.ts" \
-        "$(git -C /path/to/wp-coding-agents rev-parse --show-toplevel)/kimaki/plugins/dm-context-filter.ts"
-head -20 /path/to/site/AGENTS.md
-```
-
-## Step 6 — Tell the user to restart the chat bridge
-
-The upgrade script never restarts the chat bridge automatically — active chat sessions would die mid-turn. Hand the right command to the user based on what the summary block printed. See the restart-command table in Step 1.
-
-> Always say something like: *"Restart &lt;bridge&gt; when ready — active sessions will die."* Let the user pick the moment. For the telegram bridge there are two services (`opencode-serve` + `opencode-telegram`) — restart both, in that order.
-
-## Scope flags
-
-These work in both VPS and local mode:
+## Never do
 
-- `--kimaki-only` — only sync the chat-bridge config (name kept for backwards compatibility — also handles cc-connect and telegram when they are the detected bridge)
-- `--skills-only` — only refresh agent skills (WordPress/agent-skills + Extra-Chill/data-machine-skills)
-- `--agents-md-only` — only regenerate AGENTS.md via `datamachine memory compose`
+- **Never restart the chat bridge automatically.** It kills active sessions including the one you're talking in.
+- **Never skip the dry-run** on a live install.
+- **Never touch user state:** `opencode.json` (the script does additive-only repair), the WordPress DB, nginx, SSL certs, `~/.kimaki/` auth state and OAuth tokens, the DM workspace cloned repos, or agent memory files (`SOUL.md` / `MEMORY.md` / `USER.md`).
+- **Never hardcode workspace paths** (`/var/lib/...`, `/opt/...`, `/var/www/...`, `/root/...`) in commands you give the user. Use `git rev-parse --show-toplevel`, `$(npm root -g)`, `$KIMAKI_DATA_DIR`, and the script's auto-detection.
 
-## Never do
+## Source of truth
 
-- Never restart kimaki automatically. Always let the user decide.
-- Never touch `opencode.json`, the WordPress DB, nginx, SSL certs, `~/.kimaki/` auth state and OAuth tokens, the DM workspace cloned repos, or agent memory files (`SOUL.md` / `MEMORY.md` / `USER.md`).
-- Never run without a dry-run first on a live install.
-- Never hardcode `/var/lib/...`, `/opt/...`, `/var/www/...`, or `/root/...` paths in the steps you give the user. Use `git rev-parse --show-toplevel`, `$(npm root -g)`, `$KIMAKI_DATA_DIR`, and the script's auto-detection.
+| Question | Where to look |
+|---|---|
+| What flags exist? | `./upgrade.sh --help` |
+| What did the upgrade actually do? | The script's summary block (printed at the end of every run) |
+| What's the right restart command for this bridge × env? | The summary block — rendered from `lib/chat-bridges.sh::bridge_restart_cmd` |
+| What's the right verify command? | The summary block |
+| What chat bridges are supported? | `lib/chat-bridges.sh::bridge_names` (currently kimaki, cc-connect, telegram) |