docs: explain snapshots and rollback (#108159)

docs/docs_map.md

@@ -4710,8 +4710,12 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
   - H3: Restart the gateway
   - H3: Verify
   - H2: Rollback
-  - H3: Pin a version (npm)
-  - H3: Pin a commit (source)
+  - H3: Before updating: create a verified backup
+  - H3: Roll back a package install
+  - H3: Roll back a source checkout
+  - H3: Downgrading across the session SQLite migration
+  - H3: Restore state only when necessary
+  - H3: Verify the rollback
   - H2: If you are stuck
   - H2: Related
 

docs/install/updating.md

@@ -293,29 +293,130 @@ openclaw health
 
 ## Rollback
 
-### Pin a version (npm)
+Rollback has two layers:
+
+1. Reinstall older OpenClaw code while keeping the current state.
+2. Restore pre-update state only when the older code cannot use a migrated
+   config or database.
+
+Start with a code-only rollback. Restoring state discards changes made after
+the backup.
+
+### Before updating: create a verified backup
+
+`openclaw update` preserves an automatic pre-update config copy, but it does not
+create a full state recovery point. Before a significant update, create one
+explicitly:
 
 ```bash
-npm i -g openclaw@<version>
-openclaw doctor
+mkdir -p ~/Backups/openclaw
+openclaw backup create --output ~/Backups/openclaw --verify
+```
+
+The archive manifest records the OpenClaw version and the source paths included
+in the backup. The archive can contain credentials, auth profiles, and channel
+state, so store it with owner-only permissions and the same protection as the
+live state directory. See [Backup](/cli/backup) for included and intentionally
+omitted files.
+
+For a byte-for-byte recovery point that includes volatile artifacts omitted by
+the portable archive, stop the Gateway and use a filesystem, volume, or VM
+snapshot provided by your platform.
+
+### Roll back a package install
+
+List published versions, then preview and install the known-good version:
+
+```bash
+npm view openclaw versions --json
+openclaw update --tag <known-good-version> --dry-run
+openclaw update --tag <known-good-version>
+```
+
+`openclaw update --tag` is preferred over a direct package-manager install. It
+detects the downgrade, asks for confirmation, runs managed plugin convergence
+and compatibility checks against the installed target, refreshes service
+metadata, restarts the Gateway, and verifies the running version. If the stored
+channel is `extended-stable`, use
+`--channel stable --tag <known-good-version>` because exact one-off tags cannot
+be combined with the `extended-stable` selector.
+
+Package updates stage and verify the candidate before activation. If the
+filesystem swap or command-shim replacement fails, OpenClaw restores the old
+package automatically. After a successful swap, a later Gateway health failure
+reports the previous version and manual rollback instructions instead of
+automatically replacing the package again.
+
+If the CLI update path is unavailable, use the same package manager and install
+scope that own the current Gateway:
+
+```bash
+openclaw gateway stop
+npm i -g openclaw@<known-good-version>
+openclaw gateway install --force
 openclaw gateway restart
 ```
 
-<Tip>
-`npm view openclaw version` shows the current published version.
-</Tip>
+Replace `npm` with `pnpm` or `bun` when that manager owns the install. During
+incident recovery, prevent an enabled auto-updater from immediately applying a
+newer release by setting `OPENCLAW_NO_AUTO_UPDATE=1` in the Gateway environment.
 
-### Pin a commit (source)
+### Roll back a source checkout
+
+Use a clean checkout and select a known-good tag or commit:
 
 ```bash
-git fetch origin
-git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
+git fetch --all --tags
+git checkout --detach <known-good-tag-or-commit>
 pnpm install && pnpm build
 openclaw gateway restart
 ```
 
 To return to latest: `git checkout main && git pull`.
 
+The updater automatically returns a git checkout to its previous branch and
+SHA when dependency installation, build, UI build, or doctor fails after a git
+update starts. Manual checkout is still required when you intentionally choose
+an older commit.
+
+### Downgrading across the session SQLite migration
+
+Before starting an older file-backed OpenClaw release, use the current CLI to
+restore archived legacy transcript artifacts:
+
+```bash
+openclaw gateway stop
+openclaw doctor --session-sqlite restore --session-sqlite-all-agents
+```
+
+This does not delete SQLite data. Sessions created after the SQLite migration
+exist only in SQLite and will not appear to the older runtime. See
+[Downgrading after session SQLite migration](/cli/doctor#downgrading-after-session-sqlite-migration).
+
+### Restore state only when necessary
+
+If the older code cannot read a newer config or database schema, stop the
+Gateway and restore the verified pre-update filesystem, volume, or VM snapshot.
+Preserve the current state separately before restoring because this removes
+changes made after the snapshot.
+
+Broad `openclaw backup create` archives support creation and verification, but
+not in-place whole-archive activation. Extract a broad archive into a staging
+directory and use its `manifest.json` source-to-archive mapping for an offline
+restore. `openclaw backup sqlite restore` likewise writes a verified database
+to a fresh target; activating that target remains an explicit offline operator
+step.
+
+### Verify the rollback
+
+```bash
+openclaw --version
+openclaw health
+openclaw plugins list --json
+openclaw gateway status --deep --json
+openclaw doctor --lint --json
+```
+
 ## If you are stuck
 
 - Run `openclaw doctor` again and read the output carefully.