From 0e4be1e3d33fe153aa9feecca024e9a2a2deb518 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Mon, 27 Apr 2026 03:12:27 -0700 Subject: [PATCH] docs(matrix): move migration guide from install/ to channels/ The Matrix migration guide is plugin-upgrade content (encrypted-state recovery, device verification, room-key restore) rather than a cross-system import or machine move, so it belongs alongside the Matrix channel docs rather than under Install > Maintenance > Migrating. - Move docs/install/migrating-matrix.md to docs/channels/matrix-migration.md - Update inbound link in docs/channels/matrix.md - Update the migrating.md hub: replace the Matrix Card with a one-line link in 'Upgrade a plugin in place' - Refresh Related list on the moved page (link Matrix push rules and Migration guide hub) - docs.json: remove install/migrating-matrix from Maintenance > Migrating, slot channels/matrix-migration between channels/matrix and channels/matrix-push-rules in the Mainstream channels group, and add a /install/migrating-matrix -> /channels/matrix-migration redirect --- .../matrix-migration.md} | 11 ++++++----- docs/channels/matrix.md | 2 +- docs/docs.json | 8 ++++++-- docs/install/migrating.md | 8 ++------ 4 files changed, 15 insertions(+), 14 deletions(-) rename docs/{install/migrating-matrix.md => channels/matrix-migration.md} (98%) 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 `, 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. 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: - - - Encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands for the Matrix plugin. - - +- [Matrix migration](/channels/matrix-migration): encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands. ## Related