Add account migration guide

content/docs/advanced/_index.md

@@ -0,0 +1,9 @@
++++
+title = "Advanced"
+weight = 150
+template = "docs/with_menu.html"
+render = false
+[extra]
+tile = "Take the next steps with some advanced use cases."
+updated = "2026-02-11T17:55:00Z"
++++

content/docs/advanced/account_migration/_index.md

@@ -0,0 +1,125 @@
++++
+title = "Account Migration"
+template = "docs/with_menu.html"
+weight = 100
+
+[extra]
+updated = "2026-04-06T13:55:00Z"
+authors = ["HarHarLinks", "Website & Content WG", "Matrix Stammtisch Aachen"]
++++
+
+It is possible that it becomes necessary to migrate from one account to another.
+For example you might be looking into [switching providers](@/docs/communities/switching-providers/_index.md) because you tried Matrix out by joining matrix.org and
+have decided to start your own homeserver, or perhaps the homeserver currently
+hosting your account is shutting down.
+Maybe you are just looking to change your Matrix user ID but staying on the
+same server.
+
+Unfortunately there is no first class support for this in the Matrix protocol yet.
+The following guide hopes to support you to make the transition as smooth as possible.
+
+## What to expect
+
+The goal of migrating to a new account is create a new account and then transfer
+all the conversations you are participating in to it, optionally removing the old account.
+It is useful to know that despite often different presentation in clients,
+direct messages and group conversations both use the technical concept of a
+"room" in the background.
+The process for both is hence largely the same.
+
+There are generally two major types each room you are migrating can fall into:
+
+1. The room can be joined autonomously
+   (e.g. [Public Rooms](@/docs/chat_basics/public-rooms/_index.md))
+   or your old account has a sufficient
+   [Power Level](@/docs/communities/moderation/_index.md#power-levels)
+   to invite your new account to it.
+   This will for example include rooms you created as well as your direct messages.
+2. You have no means to join your new account without help from someone else.
+   This is rare, but in this case you will have to reach out to the room's moderators
+   individually to let them know to invite your new account.
+
+Additionally, each room can configure a [history visibility](@/docs/communities/getting-started/_index.md#history-visibility).
+
+- If the room's existing history is visible to new joiners, your new account
+  will be able to access old messages that your old account can already see.
+- If the room's existing history is *not* visible to new joiners prior to joining,
+  then your new account will not be able to show you old messages despite having
+  an old account that can.
+  If that history is relevant to you, consider exporting the room history from
+  your old account.
+
+Finally, there are also rare exceptions:
+
+- Rooms can be configured not to federate, so if the new account is on another server
+  it will never be able to join that room.
+- Some homeservers might also implement other measures to block other servers,
+  e.g. [ACL-bans](https://spec.matrix.org/v1.18/client-server-api/#server-access-control-lists-acls-for-rooms)
+  or via [custom policies](https://spec.matrix.org/v1.18/client-server-api/#policy-servers).
+
+Of course you can always decide to only migrate a subset of rooms from your old
+account for a little spring cleaning.
+
+If you are the admin of some communities,
+make sure to also read our [transferring ownership](@/docs/communities/switching-providers/_index.md#transferring-ownership) guide.
+
+## Speeding things up
+
+You will be sending a lot of invites with the old account and join a lot of
+rooms with the new account.
+Matrix by default limits how often an account can run different types of actions
+to prevent abuse, including inviting and joining.
+
+We suggest asking the admins of both your old and new homeserver to disable or
+raise your rate limits temporarily to speed up the process significantly, if
+possible.
+Otherwise you might be looking at hours of waiting, depending on the amount of
+conversations you participate in.
+
+## Tools
+
+The process of inviting and joining can be very tedious if you are migrating more
+than just a handful of rooms.
+Resourceful community members have created multiple tools over the years to
+meet each of their individual requirements.
+We recommend evaluating any tool against your individual needs so you can take
+additional steps or precautions as needed.
+
+One of the most comprehensive tools at the time of writing is Dominik's fork of
+[matrix-migrate](https://gitlab.com/domrim/matrix-migrate),
+which merges the features from multiple earlier forks of the same tool.
+You will need to use a command line to run it.
+It is built on the state of the art matrix-rust-sdk and has features including dry run
+(simulation without executing), rate limit handling, SSO, key backup migration, and more.
+
+TODO: can it produce a log of rooms it is unable to migrate?
+
+You can find more tools (and guides) about account migration 
+via community maintained lists.
+For example, check out the "migration" tag filter of
+[Tune Your Chat](https://tune-your-chat.github.io/ecosystem/tune/)
+
+## Finishing up
+
+Exploring your new account with the freshly migrated rooms, you might notice
+that in End-to-End Encrypted rooms, our new account does not yet have the keys
+to decrypt the historical messages.
+Clients with support for End-to-End Encryption usually also allow to export and
+import encryption keys, and some migration tools may also support doing this automatically.
+Simply export your old account's keys and import them to your new account, and
+messages should become readable once more!
+
+Depending on the approach you took to migrate, the direct messages might not
+appear as such in your new account.
+Some clients offer a command to fix this.
+For example, simply send `/converttodm` via the regular message input box of
+Element Web to a room you know is supposed to be a direct message to convert
+it.
+
+You should now have migrated your account! 🎉
+
+This process should be largely invisible for the conversations you migrated.
+However, don't forget to let everyone else know to reach you under your new ID
+as needed!
+A common way to do this is to change your old account's display name to include
+a hint at your new Matrix ID.

content/docs/communities/switching-providers/_index.md

@@ -13,7 +13,7 @@ conversations, and to connect them to their own systems.
 """
 +++
 
-## Why switching providers?
+## Why switch providers?
 
 Many users start by creating a Matrix account on Matrix.org, operated by the 
 Matrix.org Foundation. It is a reliable and free provider, but as they grow
@@ -76,7 +76,7 @@ rooms section of the technical documentation.
 
 The Matrix.org Foundation and [t2bot.io](https://t2bot.io/) are hosting some
 public bridges for the convenience of users. They are of course bridging public
-services with the matrix.org homeserver.
+services with [the matrix.org homeserver](@/homeserver/about.md).
 
 If you want to bridge a private service such as your company's Slack Workspace,
 you will need to deploy a bridge by yourself since the matrix.org homeserver
@@ -85,12 +85,12 @@ doesn't accept bridges to new private systems.
 Finally, relying on bridges hosted by The Matrix.org Foundation creates
 unnecessary centralisation around it: if either the matrix.org homeserver or the
 bridge hosted by The Matrix.org Foundation are down, you temporarily lose access
-to this system. To understand why, please read the [app services](/docs/matrix-concepts/elements-of-matrix/#appservice-bridges-and-some-bots)
-and [room](/docs/matrix-concepts/rooms_and_events/) sections of the Matrix
+to this system. To understand why, please read the [app services](@/docs/matrix-concepts/elements-of-matrix/_index.md#appservice-bridges-and-some-bots)
+and [room](@/docs/matrix-concepts/rooms_and_events/_index.md) sections of the Matrix
 Concepts documentation.
 
 You can find a list of the systems that can be bridged to Matrix on the
-[bridges section](/ecosystem/bridges) of this website.
+[bridges section](@/ecosystem/bridges/_index.md) of this website.
 
 {{ page_card(
     title="Bridges",
@@ -120,9 +120,9 @@ providers The Matrix.org Foundation is aware of](/ecosystem/hosting).
 ### Rolling your own
 
 People who either want or need to have on-premises can either pick a [server
-implementation](/ecosystem/servers) they are comfortable with and install it
+implementation](@/ecosystem/servers/index.md) they are comfortable with and install it
 themselves, or get an on-premises support plan from [one of the providers the
-Foundation knows](/ecosystem/hosting).
+Foundation knows](@/ecosystem/hosting/index.md).
 
 {{ page_card(
     title="Servers",
@@ -135,10 +135,10 @@ Foundation knows](/ecosystem/hosting).
 
 Transferring ownership is one of the great strengths of Matrix. You can start
 your community with an account you have created on the matrix.org homeserver and
-then decide to move to another server.
+then [decide to move to another server](@/docs/advanced/account_migration/_index.md).
 
-Matrix doesn't have (yet?) a concept of ownership: it only relies on
-[Power Levels](/docs/communities/moderation/#power-levels) to define whether
+Matrix before [room version 12](#) has not had a concept of ownership: it relies on
+[Power Levels](@/docs/communities/moderation/_index.md#power-levels) to define whether
 someone is authorised to do something or not. This means that the person who has
 the highest Power Level in a room or a Space is a (co-)owner of that room and
 Space.
@@ -148,12 +148,31 @@ Whenever you give the Power Level 100 (sometimes seen as the role
 your room or Space with them. As co-owners you can't unilaterally take back what
 was given to the other.
 
+Introduction of room version 12 adjusted this slightly by introducing room creators.
+The account creating a room has an implicit infinite power level.
+Additional accounts can be named as co-creators during room creation and will share
+the infinite power level.
+Creators' Power Level cannot be removed by others nor themselves.
+The only way to remove room creators from a room is by
+[upgrading](@/docs/communities/administration/_index.md#room-upgrades)
+the room and setting different (co-)creators.
+From room version 12 on, the required Power Level to upgrade a room is 150.
+This way the room can effectively be handed over to new accounts after already
+aving been created.
+
+You can check what version a room uses by checking the room settings in your client.
+Read the [Room Upgrades](@/docs/communities/administration/_index.md#room-upgrades)
+guide to learn more about room versions and room upgrades.
+
 Imagine Alice had created a few rooms in a Space on matrix.org for her Warm
 Drinks community. She then decides that Warm Drinks is serious business and she
 wants to have a Matrix instance dedicated to it. She relies on a
-[hosting provider](/ecosystem/hosting/) to create a `warm-drinks.com`
-homeserver. Then she creates the user `@alice:warm-drinks.com`.
-
-She can promote `@alice:warm-drinks.com` to the Power Level 100 in all the rooms
-and Spaces about warm drinks she had created on matrix.org, and demote her
-matrix.org user. Now her new user is the only owner of the community.
+[hosting provider](@/ecosystem/hosting/index.md) to create a `warm-drinks.com`
+homeserver. Then she creates the account `@alice:warm-drinks.com`.
+
+For all rooms using a version below 12, she can promote `@alice:warm-drinks.com`
+to the Power Level 100 in all the rooms and Spaces about warm drinks she had
+created on matrix.org, and demote her matrix.org user.
+For rooms using version 12 or newer, she can promote her new account to
+Power Level 150 and then upgrade the room as `@alice:warm-drinks.com`.
+Now her new account is the only owner of the community.