openclaw
diff --git a/‎.agents/skills/release-openclaw-maintainer/SKILL.md‎
Lines changed: 13 additions & 0 deletions b/‎.agents/skills/release-openclaw-maintainer/SKILL.md‎
Lines changed: 13 additions & 0 deletions
diff --git a/‎package.json‎
Lines changed: 1 addition & 0 deletions b/‎package.json‎
Lines changed: 1 addition & 0 deletions
@@ -237,6 +237,19 @@ Stable publication is not complete until `main` carries the actual shipped relea
 
 ## Handle versions and release files consistently
 
+Use the release preparation controller before manual version edits:
+
+```bash
+pnpm release:prepare -- --version YYYY.M.PATCH-beta.N --shadow
+pnpm release:prepare -- --version YYYY.M.PATCH-beta.N --write
+pnpm release:prepare -- --version YYYY.M.PATCH-beta.N --check
+```
+
+Shadow mode is the default and never runs mutating commands. Write mode aligns
+the root and macOS versions, optionally Android with `--android`, then runs only
+the version-owned generated metadata DAG. Every mode writes an exact
+HEAD/worktree-bound manifest under git metadata for cutover review.
+
 - Version locations include:
   - `package.json`
   - `apps/android/app/build.gradle.kts`
 
@@ -1761,6 +1761,7 @@
     "release:generated:check": "node scripts/release-preflight.mjs --check",
     "release:openclaw:npm:check": "node --import tsx scripts/openclaw-npm-release-check.ts",
     "release:openclaw:npm:verify-published": "node --import tsx scripts/openclaw-npm-postpublish-verify.ts",
+    "release:prepare": "node --import tsx scripts/release-prepare.ts",
     "release:plugins:clawhub:check": "node --import tsx scripts/plugin-clawhub-release-check.ts",
     "release:plugins:clawhub:plan": "node --import tsx scripts/plugin-clawhub-release-plan.ts",
     "release:plugins:npm:check": "node --import tsx scripts/plugin-npm-release-check.ts",