diff --git a/docs/install/migrating-matrix.md b/docs/channels/matrix-migration.md
similarity index 98%
rename from docs/install/migrating-matrix.md
rename to docs/channels/matrix-migration.md
index fb79f75f8ca..0ca607c1f16 100644
--- a/docs/install/migrating-matrix.md
+++ b/docs/channels/matrix-migration.md
@@ -361,9 +361,10 @@ openclaw matrix verify status
 
 If the device is still unverified after that, finish verification from your Matrix client by comparing the SAS emoji or decimal codes and confirming that they match.
 
-## Related pages
+## Related
 
-- [Matrix](/channels/matrix)
-- [Doctor](/gateway/doctor)
-- [Migrating](/install/migrating)
-- [Plugins](/tools/plugin)
+- [Matrix](/channels/matrix): channel setup and config.
+- [Matrix push rules](/channels/matrix-push-rules): notification routing.
+- [Doctor](/gateway/doctor): health check and automatic migration trigger.
+- [Migration guide](/install/migrating): all migration paths (machine moves, cross-system imports).
+- [Plugins](/tools/plugin): plugin install and registration.
diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md
index 3c0240ab278..2c0e64cdcc8 100644
--- a/docs/channels/matrix.md
+++ b/docs/channels/matrix.md
@@ -401,7 +401,7 @@ Without `--account <id>`, Matrix CLI commands use the implicit default account.
 
     Startup also runs a conservative crypto bootstrap pass that reuses the current secret storage and cross-signing identity. If bootstrap state is broken, OpenClaw attempts a guarded repair even without `channels.matrix.password`; if the homeserver requires password UIA, startup logs a warning and stays non-fatal. Already-owner-signed devices are preserved.
 
-    See [Matrix migration](/install/migrating-matrix) for the full upgrade flow.
+    See [Matrix migration](/channels/matrix-migration) for the full upgrade flow.
 
   </Accordion>
 
diff --git a/docs/docs.json b/docs/docs.json
index 3cb57853e7d..1e56d770cdd 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -52,6 +52,10 @@
     ]
   },
   "redirects": [
+    {
+      "source": "/install/migrating-matrix",
+      "destination": "/channels/matrix-migration"
+    },
     {
       "source": "/help/gpt54-codex-agentic-parity",
       "destination": "/help/gpt55-codex-agentic-parity"
@@ -984,8 +988,7 @@
                     "pages": [
                       "install/migrating",
                       "install/migrating-claude",
-                      "install/migrating-hermes",
-                      "install/migrating-matrix"
+                      "install/migrating-hermes"
                     ]
                   },
                   "install/uninstall",
@@ -1050,6 +1053,7 @@
                   "channels/imessage",
                   "channels/bluebubbles",
                   "channels/matrix",
+                  "channels/matrix-migration",
                   "channels/matrix-push-rules"
                 ]
               },
diff --git a/docs/install/migrating.md b/docs/install/migrating.md
index b71d7d9e10d..64a8418f29f 100644
--- a/docs/install/migrating.md
+++ b/docs/install/migrating.md
@@ -117,13 +117,9 @@ On the new machine, confirm:
 
 ## Upgrade a plugin in place
 
-In-place plugin upgrades preserve the same plugin id and config keys but may move on-disk state into the current layout. The Matrix plugin is the largest example because of its encrypted-state recovery requirements.
+In-place plugin upgrades preserve the same plugin id and config keys but may move on-disk state into the current layout. Plugin-specific upgrade guides live alongside their channels:
 
-<CardGroup cols={1}>
-  <Card title="Matrix plugin migration" href="/install/migrating-matrix" icon="key">
-    Encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands for the Matrix plugin.
-  </Card>
-</CardGroup>
+- [Matrix migration](/channels/matrix-migration): encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands.
 
 ## Related