build: make npm release tag configurable

docs/help/faq.md

@@ -301,9 +301,10 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
     - `latest` = stable
     - `beta` = early build for testing
 
-    We ship builds to **beta**, test them, and once a build is solid we **promote
-    that same version to `latest`**. That's why beta and stable can point at the
-    **same version**.
+    Usually, a stable release lands on **beta** first, then an explicit
+    promotion step moves that same version to `latest`. Maintainers can also
+    publish straight to `latest` when needed. That's why beta and stable can
+    point at the **same version** after promotion.
 
     See what changed:
     [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
@@ -313,7 +314,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   </Accordion>
 
   <Accordion title="How do I install the beta version and what is the difference between beta and dev?">
-    **Beta** is the npm dist-tag `beta` (may match `latest`).
+    **Beta** is the npm dist-tag `beta` (may match `latest` after promotion).
     **Dev** is the moving head of `main` (git); when published, it uses the npm dist-tag `dev`.
 
     One-liners (macOS/Linux):

docs/install/development-channels.md

@@ -18,8 +18,11 @@ OpenClaw ships three update channels:
   The `main` branch is for experimentation and active development. It may contain
   incomplete features or breaking changes. Do not use it for production gateways.
 
-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.
+We usually ship stable builds to **beta** first, test them there, then run an
+explicit promotion step that moves the vetted build to `latest` without
+changing the version number. Maintainers can also publish a stable release
+directly to `latest` when needed. Dist-tags are the source of truth for npm
+installs.
 
 ## Switching channels
 
@@ -109,7 +112,7 @@ source (config, git tag, git branch, or default).
 - 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
+  - `beta` -> candidate build or beta-first stable build
   - `dev` -> main snapshot (optional)
 
 ## macOS app availability

docs/reference/RELEASING.md

@@ -10,7 +10,7 @@ read_when:
 
 OpenClaw has three public release lanes:
 
-- stable: tagged releases that publish to npm `latest` and mirror the same version onto `beta` unless `beta` already points at a newer prerelease
+- stable: tagged releases that publish to npm `beta` by default, or to npm `latest` when explicitly requested
 - beta: prerelease tags that publish to npm `beta`
 - dev: the moving head of `main`
 
@@ -23,9 +23,9 @@ OpenClaw has three public release lanes:
 - Beta prerelease version: `YYYY.M.D-beta.N`
   - Git tag: `vYYYY.M.D-beta.N`
 - Do not zero-pad month or day
-- `latest` means the current stable npm release
-- `beta` means the current beta install target, which may point to either the active prerelease or the latest promoted stable build
-- Stable and stable correction releases publish to npm `latest` and also retag npm `beta` to that same non-beta version after promotion, unless `beta` already points at a newer prerelease
+- `latest` means the current promoted stable npm release
+- `beta` means the current beta install target
+- Stable and stable correction releases publish to npm `beta` by default; release operators can target `latest` explicitly, or promote a vetted beta build later
 - Every OpenClaw release ships the npm package and macOS app together
 
 ## Release cadence
@@ -49,6 +49,9 @@ OpenClaw has three public release lanes:
   install path in a fresh temp prefix
 - Maintainer release automation now uses preflight-then-promote:
   - real npm publish must pass a successful npm `preflight_run_id`
+  - stable npm releases default to `beta`
+  - stable npm publish can target `latest` explicitly via workflow input
+  - stable npm promotion from `beta` to `latest` is still available as a separate manual workflow step
   - public `macOS Release` is validation-only
   - real private mac publish must pass successful private mac
     `preflight_run_id` and `validate_run_id`
@@ -75,6 +78,7 @@ OpenClaw has three public release lanes:
 ## Public references
 
 - [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml)
+- [`.github/workflows/openclaw-npm-promote-beta.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-promote-beta.yml)
 - [`scripts/openclaw-npm-release-check.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/openclaw-npm-release-check.ts)
 - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
 - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)