docs: update development-channels with --tag, --dry-run, and status sections

docs/install/development-channels.md

@@ -1,15 +1,14 @@
 ---
-summary: "Stable, beta, and dev channels: semantics, switching, and tagging"
+summary: "Stable, beta, and dev channels: semantics, switching, pinning, and tagging"
 read_when:
   - You want to switch between stable/beta/dev
+  - You want to pin a specific version, tag, or SHA
   - You are tagging or publishing prereleases
 title: "Development Channels"
 ---
 
 # Development channels
 
-Last updated: 2026-01-21
-
 OpenClaw ships three update channels:
 
 - **stable**: npm dist-tag `latest`.
@@ -17,61 +16,102 @@ OpenClaw ships three update channels:
 - **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).
 
 We ship builds to **beta**, test them, then **promote a vetted build to `latest`**
-without changing the version number — dist-tags are the source of truth for npm installs.
+without changing the version number -- dist-tags are the source of truth for npm installs.
 
 ## Switching channels
 
-Git checkout:
-
 ```bash
 openclaw update --channel stable
 openclaw update --channel beta
 openclaw update --channel dev
 ```
 
-- `stable`/`beta` check out the latest matching tag (often the same tag).
-- `dev` switches to `main` and rebases on the upstream.
+`--channel` persists your choice in config (`update.channel`) and aligns the
+install method:
 
-npm/pnpm global install:
+- **`stable`/`beta`** (package installs): updates via the matching npm dist-tag.
+- **`stable`/`beta`** (git installs): checks out the latest matching git tag.
+- **`dev`**: ensures a git checkout (default `~/openclaw`, override with
+  `OPENCLAW_GIT_DIR`), switches to `main`, rebases on upstream, builds, and
+  installs the global CLI from that checkout.
+
+Tip: if you want stable + dev in parallel, keep two clones and point your
+gateway at the stable one.
+
+## One-off version or tag targeting
+
+Use `--tag` to target a specific dist-tag, version, or package spec for a single
+update **without** changing your persisted channel:
 
 ```bash
-openclaw update --channel stable
-openclaw update --channel beta
-openclaw update --channel dev
+# Install a specific version
+openclaw update --tag 2026.3.14
+
+# Install from the beta dist-tag (one-off, does not persist)
+openclaw update --tag beta
+
+# Install from GitHub main branch (npm tarball)
+openclaw update --tag main
+
+# Install a specific npm package spec
+openclaw update --tag openclaw@2026.3.12
 ```
 
-This updates via the corresponding npm dist-tag (`latest`, `beta`, `dev`).
+Notes:
 
-When you **explicitly** switch channels with `--channel`, OpenClaw also aligns
-the install method:
+- `--tag` applies to **package (npm) installs only**. Git installs ignore it.
+- The tag is not persisted. Your next `openclaw update` uses your configured
+  channel as usual.
+- Downgrade protection: if the target version is older than your current version,
+  OpenClaw prompts for confirmation (skip with `--yes`).
 
-- `dev` ensures a git checkout (default `~/openclaw`, override with `OPENCLAW_GIT_DIR`),
-  updates it, and installs the global CLI from that checkout.
-- `stable`/`beta` installs from npm using the matching dist-tag.
+## Dry run
 
-Tip: if you want stable + dev in parallel, keep two clones and point your gateway at the stable one.
+Preview what `openclaw update` would do without making changes:
+
+```bash
+openclaw update --dry-run
+openclaw update --channel beta --dry-run
+openclaw update --tag 2026.3.14 --dry-run
+openclaw update --dry-run --json
+```
+
+The dry run shows the effective channel, target version, planned actions, and
+whether a downgrade confirmation would be required.
 
 ## Plugins and channels
 
-When you switch channels with `openclaw update`, OpenClaw also syncs plugin sources:
+When you switch channels with `openclaw update`, OpenClaw also syncs plugin
+sources:
 
 - `dev` prefers bundled plugins from the git checkout.
 - `stable` and `beta` restore npm-installed plugin packages.
+- npm-installed plugins are updated after the core update completes.
+
+## Checking current status
+
+```bash
+openclaw update status
+```
+
+Shows the active channel, install kind (git or package), current version, and
+source (config, git tag, git branch, or default).
 
 ## Tagging best practices
 
-- Tag releases you want git checkouts to land on (`vYYYY.M.D` for stable, `vYYYY.M.D-beta.N` for beta).
+- Tag releases you want git checkouts to land on (`vYYYY.M.D` for stable,
+  `vYYYY.M.D-beta.N` for beta).
 - `vYYYY.M.D.beta.N` is also recognized for compatibility, but prefer `-beta.N`.
 - Legacy `vYYYY.M.D-<patch>` tags are still recognized as stable (non-beta).
 - Keep tags immutable: never move or reuse a tag.
 - npm dist-tags remain the source of truth for npm installs:
-  - `latest` → stable
-  - `beta` → candidate build
-  - `dev` → main snapshot (optional)
+  - `latest` -> stable
+  - `beta` -> candidate build
+  - `dev` -> main snapshot (optional)
 
 ## macOS app availability
 
-Beta and dev builds may **not** include a macOS app release. That’s OK:
+Beta and dev builds may **not** include a macOS app release. That is OK:
 
 - The git tag and npm dist-tag can still be published.
-- Call out “no macOS build for this beta” in release notes or changelog.
+- Call out "no macOS build for this beta" in release notes or changelog.