docs: document release publish orchestration

docs/ci.md

@@ -141,6 +141,14 @@ dispatches `Plugin NPM Release` for all publishable plugin packages, dispatches
 `Plugin ClawHub Release` for the same release SHA, and only then dispatches
 `OpenClaw NPM Release` with the saved `preflight_run_id`.
 
+```bash
+gh workflow run openclaw-release-publish.yml \
+  --ref release/YYYY.M.D \
+  -f tag=vYYYY.M.D-beta.N \
+  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
+  -f npm_dist_tag=beta
+```
+
 For pinned commit proof on a fast-moving branch, use the helper instead of
 `gh workflow run ... --ref main -f ref=<sha>`:
 

docs/reference/RELEASING.md

@@ -103,6 +103,12 @@ the maintainer-only release runbook.
 - Run `pnpm build && pnpm ui:build` before `pnpm release:check` so the expected
   `dist/*` release artifacts and Control UI bundle exist for the pack
   validation step
+- Run `pnpm plugins:sync` after the root version bump and before tagging. It
+  updates publishable plugin package versions, OpenClaw peer/API compatibility
+  metadata, build metadata, and plugin changelog stubs to match the core
+  release version. `pnpm plugins:sync:check` is the non-mutating release guard;
+  the publish workflow fails before any registry mutation if this step was
+  forgotten.
 - Run the manual `Full Release Validation` workflow before release approval to
   kick off all pre-release test boxes from one entrypoint. It accepts a branch,
   tag, or full commit SHA, dispatches manual `CI`, and dispatches
@@ -518,6 +524,56 @@ For package-candidate Telegram proof, enable `telegram_mode=mock-openai` or
 resolved `package-under-test` tarball into the Telegram lane; the standalone
 Telegram workflow still accepts a published npm spec for post-publish checks.
 
+## Release publish automation
+
+`OpenClaw Release Publish` is the normal mutating publish entrypoint. It
+orchestrates the trusted-publisher workflows in the order the release needs:
+
+1. Check out the release tag and resolve its commit SHA.
+2. Verify the tag is reachable from `main` or `release/*`.
+3. Run `pnpm plugins:sync:check`.
+4. Dispatch `Plugin NPM Release` with `publish_scope=all-publishable` and
+   `ref=<release-sha>`.
+5. Dispatch `Plugin ClawHub Release` with the same scope and SHA.
+6. Dispatch `OpenClaw NPM Release` with the release tag, npm dist-tag, and
+   saved `preflight_run_id`.
+
+Beta publish example:
+
+```bash
+gh workflow run openclaw-release-publish.yml \
+  --ref release/YYYY.M.D \
+  -f tag=vYYYY.M.D-beta.N \
+  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
+  -f npm_dist_tag=beta
+```
+
+Stable publish to the default beta dist-tag:
+
+```bash
+gh workflow run openclaw-release-publish.yml \
+  --ref release/YYYY.M.D \
+  -f tag=vYYYY.M.D \
+  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
+  -f npm_dist_tag=beta
+```
+
+Stable promotion directly to `latest` is explicit:
+
+```bash
+gh workflow run openclaw-release-publish.yml \
+  --ref release/YYYY.M.D \
+  -f tag=vYYYY.M.D \
+  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
+  -f npm_dist_tag=latest
+```
+
+Use the lower-level `Plugin NPM Release` and `Plugin ClawHub Release` workflows
+only for focused repair or republish work. For a selected plugin repair, pass
+`plugin_publish_scope=selected` and `plugins=@openclaw/name` to
+`OpenClaw Release Publish`, or dispatch the child workflow directly when the
+OpenClaw package must not be published.
+
 ## NPM workflow inputs
 
 `OpenClaw NPM Release` accepts these operator-controlled inputs:
@@ -531,6 +587,19 @@ Telegram workflow still accepts a published npm spec for post-publish checks.
   the prepared tarball from the successful preflight run
 - `npm_dist_tag`: npm target tag for the publish path; defaults to `beta`
 
+`OpenClaw Release Publish` accepts these operator-controlled inputs:
+
+- `tag`: required release tag; must already exist
+- `preflight_run_id`: successful `OpenClaw NPM Release` preflight run id;
+  required when `publish_openclaw_npm=true`
+- `npm_dist_tag`: npm target tag for the OpenClaw package
+- `plugin_publish_scope`: defaults to `all-publishable`; use `selected` only
+  for focused repair work
+- `plugins`: comma-separated `@openclaw/*` package names when
+  `plugin_publish_scope=selected`
+- `publish_openclaw_npm`: defaults to `true`; set `false` only when using the
+  workflow as a plugin-only repair orchestrator
+
 `OpenClaw Release Checks` accepts these operator-controlled inputs:
 
 - `ref`: branch, tag, or full commit SHA to validate. Secret-bearing checks
@@ -563,8 +632,9 @@ When cutting a stable npm release:
 4. If you intentionally only need the deterministic normal test graph, run the
    manual `CI` workflow on the release ref instead
 5. Save the successful `preflight_run_id`
-6. Run `OpenClaw NPM Release` again with `preflight_only=false`, the same
-   `tag`, the same `npm_dist_tag`, and the saved `preflight_run_id`
+6. Run `OpenClaw Release Publish` with the same `tag`, the same `npm_dist_tag`,
+   and the saved `preflight_run_id`; it publishes externalized plugins to npm
+   and ClawHub before promoting the OpenClaw npm package
 7. If the release landed on `beta`, use the private
    `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
    workflow to promote that stable version from `beta` to `latest`