Docs: clarify Matrix migration update flow

docs/cli/update.md

@@ -71,6 +71,8 @@ install method aligned:
 
 The Gateway core auto-updater (when enabled via config) reuses this same update path.
 
+By default, `openclaw update` also restarts the gateway after the core and plugin update finishes. That matters for migrations that complete on startup, including the Matrix in-place upgrade flow.
+
 ## Git checkout flow
 
 Channels:
@@ -88,9 +90,18 @@ High-level:
 5. Rebases onto the selected commit (dev only).
 6. Installs deps (pnpm preferred; npm fallback).
 7. Builds + builds the Control UI.
-8. Runs `openclaw doctor` as the final “safe update” check.
+8. Runs `openclaw doctor --fix` as the final “safe update” check.
 9. Syncs plugins to the active channel (dev uses bundled extensions; stable/beta uses npm) and updates npm-installed plugins.
 
+For package-manager installs, `openclaw update` updates the package, runs a non-interactive doctor pass when possible, syncs plugins, and restarts the gateway by default.
+
+If you use `--no-restart`, startup-backed migrations do not finish until you later restart the gateway yourself. For Matrix upgrades, the recommended follow-up is:
+
+```bash
+openclaw doctor --fix
+openclaw gateway restart
+```
+
 ## `--update` shorthand
 
 `openclaw --update` rewrites to `openclaw update` (useful for shells and launcher scripts).

docs/install/migrating-matrix.md

@@ -24,6 +24,12 @@ You do not need to rename config keys or reinstall the plugin under a new name.
 
 When the gateway starts, and when you run [`openclaw doctor --fix`](/gateway/doctor), OpenClaw tries to repair old Matrix state automatically.
 
+When you use `openclaw update`, the exact trigger depends on how OpenClaw is installed:
+
+- source installs run `openclaw doctor --fix` during the update flow, then restart the gateway by default
+- package-manager installs update the package, run a non-interactive doctor pass, then rely on the default gateway restart so startup can finish Matrix migration
+- if you use `openclaw update --no-restart`, startup-backed Matrix migration is deferred until you later run `openclaw doctor --fix` and restart the gateway
+
 Automatic migration covers:
 
 - reusing your cached Matrix credentials
@@ -33,6 +39,11 @@ Automatic migration covers:
 - extracting a previously saved Matrix room-key backup decryption key from the old rust crypto store, when that key exists locally
 - restoring backed-up room keys into the new crypto store on the next Matrix startup
 
+About multi-account upgrades:
+
+- the oldest flat Matrix store (`~/.openclaw/matrix/bot-storage.json` and `~/.openclaw/matrix/crypto/`) came from a single-store layout, so OpenClaw can only migrate it into one resolved Matrix account target
+- already account-scoped legacy Matrix stores are detected and prepared per configured Matrix account
+
 ## What the migration cannot do automatically
 
 The previous public Matrix plugin did **not** automatically create Matrix room-key backups. It persisted local crypto state and requested device verification, but it did not guarantee that your room keys were backed up to the homeserver.
@@ -46,11 +57,17 @@ OpenClaw cannot automatically recover:
 - custom plugin path installs that now point at a missing directory
 - a missing recovery key when the old store had backed-up keys but did not keep the decryption key locally
 
+Current warning scope:
+
+- stale custom Matrix plugin path installs are surfaced by `openclaw doctor` today
+- gateway startup does not currently emit a separate Matrix-specific custom-path warning
+
 If your old installation had local-only encrypted history that was never backed up, some older encrypted messages may remain unreadable after the upgrade.
 
 ## Recommended upgrade flow
 
 1. Update OpenClaw and the Matrix plugin normally.
+   Prefer plain `openclaw update` without `--no-restart` so startup can finish the Matrix migration immediately.
 2. Run:
 
    ```bash

docs/install/updating.md

@@ -141,10 +141,19 @@ It runs a safe-ish update flow:
 - Requires a clean worktree.
 - Switches to the selected channel (tag or branch).
 - Fetches + rebases against the configured upstream (dev channel).
-- Installs deps, builds, builds the Control UI, and runs `openclaw doctor`.
+- Installs deps, builds, builds the Control UI, and runs `openclaw doctor --fix`.
 - Restarts the gateway by default (use `--no-restart` to skip).
 
-If you installed via **npm/pnpm** (no git metadata), `openclaw update` will try to update via your package manager. If it can’t detect the install, use “Update (global install)” instead.
+That default restart matters for migrations that complete on startup. If you skip restart, run:
+
+```bash
+openclaw doctor --fix
+openclaw gateway restart
+```
+
+For Matrix upgrades specifically, startup is what finishes the in-place Matrix state migration and any pending backed-up room-key restore. See [Matrix migration](/install/migrating-matrix).
+
+If you installed via **npm/pnpm** (no git metadata), `openclaw update` will try to update via your package manager, run a non-interactive doctor pass when possible, and restart the gateway by default. If it can’t detect the install, use “Update (global install)” instead.
 
 ## Update (Control UI / RPC)