diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 153dd23c6..f28a611c9 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "b6af40f1f11e08d3c73d79c678351306bef4acbe",
-  "syncedAt": "2026-04-25T19:40:08.535Z"
+  "sha": "1d49b8cdaa4a9c57d44a42505984aa7104fa6953",
+  "syncedAt": "2026-04-25T19:46:45.168Z"
 }
diff --git a/docs/plugins/architecture-internals.md b/docs/plugins/architecture-internals.md
index 203e8a9d9..98215dc32 100644
--- a/docs/plugins/architecture-internals.md
+++ b/docs/plugins/architecture-internals.md
@@ -920,6 +920,9 @@ source-plane diagnostics without adding a second raw filesystem-path disclosure
 surface. Legacy `plugins.installs` config entries are still read as a
 compatibility fallback while the state-managed `plugins/installs.json` ledger
 becomes the install source of truth.
+`openclaw doctor --fix` migrates those legacy config entries into the managed
+ledger and refreshes the cold registry index without loading plugin runtime
+modules.
 
 ## Context engine plugins
 
diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md
index 1d4175e5d..ca336e630 100644
--- a/docs/tools/plugin.md
+++ b/docs/tools/plugin.md
@@ -266,6 +266,7 @@ openclaw plugins info <id>                 # inspect alias
 openclaw plugins doctor                    # diagnostics
 openclaw plugins registry                  # inspect persisted registry state
 openclaw plugins registry --refresh        # rebuild persisted registry
+openclaw doctor --fix                      # repair registry/ledger migration state
 
 openclaw plugins install <package>         # install (ClawHub first, then npm)
 openclaw plugins install clawhub:<pkg>     # install from ClawHub only
@@ -279,7 +280,7 @@ openclaw plugins install <spec> --dangerously-force-unsafe-install
 openclaw plugins update <id-or-npm-spec> # update one plugin
 openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
 openclaw plugins update --all            # update all
-openclaw plugins uninstall <id>          # remove config/install records
+openclaw plugins uninstall <id>          # remove config and install ledger records
 openclaw plugins uninstall <id> --keep-files
 openclaw plugins marketplace list <source>
 openclaw plugins marketplace list <source> --json
@@ -307,6 +308,9 @@ uninstall, enable, and disable flows refresh that registry after changing plugin
 state. If the registry is missing, stale, or invalid, `openclaw plugins registry
 --refresh` rebuilds it from the durable install ledger, config policy, and
 manifest/package metadata without loading plugin runtime modules.
+If a machine still has legacy `plugins.installs` records in config, run
+`openclaw doctor --fix` to move them into the managed
+`plugins/installs.json` ledger and remove the config copy.
 
 `openclaw plugins update <id-or-npm-spec>` applies to tracked installs. Passing
 an npm package spec with a dist-tag or exact version resolves the package name