diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index fc84d0e00..2110dce7b 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "9090457da742159d95306e0b4f5eb686abe103ba",
-  "syncedAt": "2026-04-27T14:15:13.478Z"
+  "sha": "ca444af891e6e039a253bfab8565160028491be7",
+  "syncedAt": "2026-04-27T14:29:07.421Z"
 }
diff --git a/docs/cli/update.md b/docs/cli/update.md
index 4eeef6822..2ea75e736 100644
--- a/docs/cli/update.md
+++ b/docs/cli/update.md
@@ -85,7 +85,11 @@ install method aligned:
 The Gateway core auto-updater (when enabled via config) reuses this same update path.
 
 For package-manager installs, `openclaw update` resolves the target package
-version before invoking the package manager. Even when the installed version
+version before invoking the package manager. npm global installs use a staged
+install: OpenClaw installs the new package into a temporary npm prefix, verifies
+the packaged `dist` inventory there, then swaps that clean package tree into the
+real global prefix. If verification fails, post-update doctor, plugin sync, and
+restart work do not run from the suspect tree. Even when the installed version
 already matches the target, the command refreshes the global package install,
 then runs plugin sync, a core-command completion refresh, and restart work. This
 keeps packaged sidecars and channel-owned plugin records aligned with the
diff --git a/docs/install/updating.md b/docs/install/updating.md
index 92c036d7e..e967c5e62 100644
--- a/docs/install/updating.md
+++ b/docs/install/updating.md
@@ -87,11 +87,13 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --ve
 npm i -g openclaw@latest
 ```
 
-When `openclaw update` manages a global npm install, it first runs the normal
-global install command. If that command fails, OpenClaw retries once with
-`--omit=optional`. That retry helps hosts where native optional dependencies
-cannot compile, while keeping the original failure visible if the fallback also
-fails.
+When `openclaw update` manages a global npm install, it installs the target into
+a temporary npm prefix first, verifies the packaged `dist` inventory, then swaps
+the clean package tree into the real global prefix. That avoids npm overlaying a
+new package onto stale files from the old package. If the install command fails,
+OpenClaw retries once with `--omit=optional`. That retry helps hosts where native
+optional dependencies cannot compile, while keeping the original failure visible
+if the fallback also fails.
 
 ```bash
 pnpm add -g openclaw@latest