feat(#815): add /gsd-update --next to install the @next RC channel (#839)

Adds an opt-in --next (alias --rc) flag to /gsd-update targeting the @next RC dist-tag (ADR #660), with a {latest,next} allowlist enforced at three layers, channel-aware version check + banner, and byte-for-byte unchanged default @latest behavior.

Closes #815

docs/COMMANDS.md

@@ -1148,11 +1148,13 @@ Update GSD with changelog preview, and optionally sync skills or reapply local p
 |------|-------------|
 | `--sync` | Sync skills from the GSD registry after updating |
 | `--reapply` | Restore local modifications (patches) after updating |
+| `--next` / `--rc` | Target the `@next` RC dist-tag instead of `@latest` (installs or refreshes a release candidate, e.g. `1.4.0-rc.1`; see ADR #660) |
 
 ```bash
 /gsd-update                         # Check for updates and install
 /gsd-update --sync                  # Update and sync skills
 /gsd-update --reapply               # Update and reapply local patches
+/gsd-update --next                  # Install from the @next RC dist-tag
 ```
 
 ---

docs/FEATURES.md

@@ -904,6 +904,7 @@ continues. Drift detection cannot fail verification.
 - REQ-UPDATE-03: System MUST be runtime-aware and target the correct directory
 - REQ-UPDATE-04: System MUST back up locally modified files to `gsd-local-patches/`
 - REQ-UPDATE-05: `/gsd-update --reapply` MUST restore local modifications after update
+- REQ-UPDATE-06: `/gsd-update --next` (alias `--rc`) MUST target the `@next` RC dist-tag for version check and install; omitting the flag MUST keep `@latest` behavior unchanged (ADR #660)
 
 ---
 

docs/USER-GUIDE.md

@@ -830,6 +830,18 @@ Set `commit_docs: false` during `/gsd-new-project` or via `/gsd-settings`. Add `
 
 Since v1.17, the installer backs up locally modified files to `gsd-local-patches/`. Run `/gsd-update --reapply` to merge your changes back.
 
+### Install or Refresh a Release Candidate
+
+To install or refresh GSD from the `@next` RC dist-tag (the pre-release channel established by ADR #660), run:
+
+```bash
+/gsd-update --next
+# or equivalently:
+/gsd-update --rc
+```
+
+The same scope/runtime detection, changelog preview, custom-file backup, and cache clearing apply. Omitting `--next`/`--rc` keeps targeting `@latest` (stable channel, no change). Only the `@latest` and `@next` channels are supported — no arbitrary dist-tag can be passed.
+
 ### Cannot Update via npm
 
 See [docs/manual-update.md](manual-update.md) for a step-by-step manual update procedure.

docs/how-to/update-gsd.md

@@ -35,14 +35,34 @@ Restart your runtime after the update to pick up new commands and agents.
 |------|--------------|
 | `--sync` | After updating, sync skills from the GSD registry |
 | `--reapply` | After updating, merge locally modified GSD files back in from `gsd-local-patches/` |
+| `--next` / `--rc` | Target the `@next` RC dist-tag instead of `@latest` (installs or refreshes a release candidate; see ADR #660) |
 
 ```bash
 /gsd-update --sync        # Update and sync skills
 /gsd-update --reapply     # Update and reapply local patches
+/gsd-update --next        # Install from the @next RC dist-tag
 ```
 
 ---
 
+## Install or refresh a release candidate
+
+GSD publishes release candidates on the `@next` npm dist-tag (established by ADR #660). To install or refresh from that channel:
+
+```bash
+/gsd-update --next
+# or equivalently:
+/gsd-update --rc
+```
+
+The full update flow applies — scope/runtime detection, changelog preview, custom-file backup, and cache clearing all run normally. The only difference is that `check-latest-version.cjs` resolves the `@next` tag and npx installs from `@opengsd/gsd-core@next`.
+
+Only `latest` and `next` are supported channels; no arbitrary dist-tag can be passed (the script enforces an allowlist and exits with code 2 on an invalid tag).
+
+Omitting `--next`/`--rc` keeps targeting `@latest` (stable channel, no change in behavior).
+
+---
+
 ## Reviewing the changelog before updating
 
 `/gsd-update` always shows the changelog diff between your installed version and the latest *before* it asks for confirmation. You do not need to visit GitHub separately. The output looks like: