diff --git a/docs/reference/RELEASING.md b/docs/reference/RELEASING.md
index f929d16e5f7..7b284ac3cfe 100644
--- a/docs/reference/RELEASING.md
+++ b/docs/reference/RELEASING.md
@@ -72,6 +72,7 @@ Historical note:
 - [ ] `pnpm check`
 - [ ] `pnpm test` (or `pnpm test:coverage` if you need coverage output)
 - [ ] `pnpm release:check` (verifies npm pack contents)
+- [ ] If `pnpm config:docs:check` fails as part of release validation and the config-surface change is intentional, run `pnpm config:docs:gen`, review `docs/.generated/config-baseline.json` and `docs/.generated/config-baseline.jsonl`, commit the updated baselines, then rerun `pnpm release:check`.
 - [ ] `OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke` (Docker install smoke test, fast path; required before release)
   - If the immediate previous npm release is known broken, set `OPENCLAW_INSTALL_SMOKE_PREVIOUS=<last-good-version>` or `OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS=1` for the preinstall step.
 - [ ] (Optional) Full installer smoke (adds non-root + CLI coverage): `pnpm test:install:smoke`
diff --git a/package.json b/package.json
index e9292d4cf79..497bd9be4ab 100644
--- a/package.json
+++ b/package.json
@@ -299,7 +299,7 @@
     "protocol:check": "pnpm protocol:gen && pnpm protocol:gen:swift && git diff --exit-code -- dist/protocol.schema.json apps/macos/Sources/OpenClawProtocol/GatewayModels.swift apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift",
     "protocol:gen": "node --import tsx scripts/protocol-gen.ts",
     "protocol:gen:swift": "node --import tsx scripts/protocol-gen-swift.ts",
-    "release:check": "node --import tsx scripts/release-check.ts",
+    "release:check": "pnpm config:docs:check && node --import tsx scripts/release-check.ts",
     "release:openclaw:npm:check": "node --import tsx scripts/openclaw-npm-release-check.ts",
     "start": "node scripts/run-node.mjs",
     "test": "node scripts/test-parallel.mjs",
diff --git a/scripts/generate-config-doc-baseline.ts b/scripts/generate-config-doc-baseline.ts
index 4563d3328ef..48fcb4c5d6f 100644
--- a/scripts/generate-config-doc-baseline.ts
+++ b/scripts/generate-config-doc-baseline.ts
@@ -26,10 +26,11 @@ if (checkOnly) {
   }
   console.error(
     [
-      "Config doc baseline artifacts are out of date.",
+      "Config baseline drift detected.",
       `Expected current: ${path.relative(repoRoot, result.jsonPath)}`,
       `Expected current: ${path.relative(repoRoot, result.statefilePath)}`,
-      "Run: node --import tsx scripts/generate-config-doc-baseline.ts --write",
+      "If this config-surface change is intentional, run `pnpm config:docs:gen` and commit the updated baseline files.",
+      "If not intentional, treat this as docs drift or a possible breaking config change and fix the schema/help changes first.",
     ].join("\n"),
   );
   process.exit(1);