docs: correct upgrade spec channel + CLI commands after container verification

- GPM channel is system.yaml gpm.releases (testing->stable), not GRAV_CHANNEL
- core upgrade is 'bin/gpm self-upgrade -y'; existing remote-upgrade-grav
  target ('bin/grav upgrade') is broken and must be fixed
- add server content-pull + cache-clear + preflight steps to Phase 2

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/working/specs/2026-07-04-grav-2.0.4-upgrade-design.md

@@ -108,9 +108,10 @@ The plan therefore has distinct local and remote steps.
 |---|---|
 | `Dockerfile` | grav-admin zip URL `2.0.0-rc.10/grav-admin-v2.0.0-rc.10.zip` → `2.0.4/grav-admin-v2.0.4.zip`. Verified: the 2.0.4 zip still extracts to a `grav-admin/` folder, so the existing `cp` block is unchanged. |
 | `plugins.txt` | add `api`, `admin2`, `flex-objects` (`form`, `login` already present as their deps) |
-| `docker-compose.yml` | `GRAV_CHANNEL=beta` → `production` so GPM serves stable releases, not RCs |
+| `user/config/system.yaml` | **`gpm.releases: testing → stable`** — this is the authoritative GPM channel. `testing` is what has been serving RC/pre-release versions. Tracked in the `user` repo, so it applies to both local and server once pushed. |
+| `docker-compose.yml` | `GRAV_CHANNEL=beta` → `production` for consistency only. This env drives the base image's `docker-entrypoint.sh`, **not** `bin/gpm`'s channel — `gpm.releases` above is what governs updates. |
 | `scripts/server-install.sh` | remove the admin2/api stash+restore special-casing (lines 25–26 and 43–45); they now install via `gpm install` from `PLUGINS` |
-| `Makefile` | add remote targets (below) to `REMOTE_TARGETS` so each gets `-test`/`-prod` variants |
+| `Makefile` | **fix broken `remote-upgrade-grav`:** `php bin/grav upgrade` is not a real command — change to `php bin/gpm self-upgrade -y`. Add the new remote targets (below) to `REMOTE_TARGETS` so each gets `-test`/`-prod` variants. |
 | `CLAUDE.md`, `docs/reference/architecture.md`, memory | update stack versions; document the three-category plugin model and the channel change |
 
 ### New Makefile targets
@@ -124,7 +125,13 @@ Added to the `REMOTE_TARGETS` list (Makefile:22–24) so the env-suffix macro
   never rewrite `folders`)
 - `remote-git-sync-enable` → set `enabled: true` in the same file
 
-`remote-upgrade-grav` (`bin/grav upgrade`) already exists.
+`remote-upgrade-grav` exists but its command is **broken** (`php bin/grav
+upgrade` is not a Grav CLI command) — it is fixed to `php bin/gpm self-upgrade
+-y` as part of Phase 0. Core self-upgrade respects the `gpm.releases` channel.
+
+**Verified CLI command names** (against the running rc.10 container):
+`php bin/gpm self-upgrade -y` (core), `php bin/gpm update -y` (all plugins),
+`php bin/grav cache` (clear cache; aliases `clearcache`/`cache-clear`).
 
 > The exact idempotent shell used to toggle the `enabled` key is finalized in the
 > implementation plan; it must not disturb the `folders` array or the encrypted
@@ -150,15 +157,22 @@ New branch off `main`. Apply all file changes above.
    trip's dailies; `/gpx-manager` list + upload + delete; a trip page and a
    story render; maps load.
 
-### Phase 2 — test
+Prerequisite: the Phase 0 config changes (esp. `system.yaml`
+`gpm.releases: stable`) are committed and pushed to Gitea, or GPM on the server
+will still resolve the `testing` channel and pull RCs.
+
 1. `make remote-git-sync-disable-test`
-2. `make remote-upgrade-grav-test` (core → 2.0.4)
+2. `make remote-fetch-content-test` — pull latest `user/` content to the test
-3. `make remote-update-plugins-test` (`gpm update -y` — all plugins incl.
+   server so `system.yaml` `gpm.releases: stable` is in place before any GPM
+   operation.
+3. `make remote-upgrade-grav-test` (core self-upgrade → 2.0.4)
+4. `make remote-update-plugins-test` (`gpm update -y` — all plugins incl.
    admin2/api/flex/git-sync/login/form)
-4. Review `git status` in the server's `user/` for unexpected config diffs;
+5. Clear cache on the server (`php bin/grav cache`).
+6. Review `git status` in the server's `user/` for unexpected config diffs;
    handle any deliberately (do not blind-commit).
-5. Smoke test on the test URL (same checklist as Phase 1).
+7. Smoke test on the test URL (same checklist as Phase 1).
-6. **Leave git-sync disabled and notify the user.** After the user validates,
+8. **Leave git-sync disabled and notify the user.** After the user validates,
    re-enable as a separate deliberate step: `make remote-git-sync-enable-test`,
    then a `content-push` round-trip to confirm sync still works.
 
@@ -186,5 +200,10 @@ accounts are already in git, so no data restore is needed.
 - **admin2/api behavioral changes across RC→stable** — these back the `/post`
   form and `/gpx-manager`; covered by the smoke tests, which are the
   highest-weight validation in this effort.
-- **GPM channel** — the server must resolve stable releases; verify the channel
+- **GPM channel** — `gpm.releases` must be `stable` on the server *before* any
-  (`gpm.releases` / `GRAV_CHANNEL`) yields 2.0.x stable, not RCs.
+  `gpm update`/`self-upgrade`, or GPM pulls RCs. Enforced by pushing the
+  `system.yaml` change and running `remote-fetch-content` first (Phase 2 step 2).
+- **`bin/gpm self-upgrade` on shared hosting** — Grav 2.0.3 fixed self-upgrade
+  failures on shared-folder setups. On the native server this can still be
+  fragile; run `php bin/gpm preflight` first and use `-o/--overwrite` if a retry
+  is needed.