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 fb79f75f8ca2..0ca607c1f164 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 3c0240ab278b..2c0e64cdcc81 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 3cb57853e7d3..1e56d770cdd1 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 b71d7d9e10df..64a8418f29f5 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