diff --git a/.env.sample b/.env.sample
index 921bc3f..e6bea9f 100644
--- a/.env.sample
+++ b/.env.sample
@@ -71,7 +71,7 @@ ENABLE_REGISTRATION=false
 ### Matrix Authentication Service (MAS) — Element X / OIDC-native auth
 
 #COMPOSE_FILE="$COMPOSE_FILE:compose.mas.yml"
-#MAS_ENABLED=1
+#MAS_ENABLED=1 # !!! Leave commented if you plan to migrate an existing homeserver
 #PASSWORD_LOGIN_ENABLED=false
 #SECRET_MAS_ENCRYPTION_VERSION=v1 # length=64 # charset=hex
 #SECRET_MAS_SYNAPSE_SHARED_VERSION=v1 # length=64 # charset=hex
diff --git a/README.md b/README.md
index 86e04a0..4ac257d 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,9 @@ You'll need to deploy something like [this](https://git.autonomic.zone/ruangrupa
 
 [MAS](https://element-hq.github.io/matrix-authentication-service/) is Element’s OAuth/OIDC-native auth service for Matrix: it handles login, tokens, and upstream IdPs while Synapse delegates authentication via `matrix_authentication_service`.
 
+> [!IMPORTANT]
+> **If you plan to migrate an existing homeserver with `syn2mas`:** deploy and configure MAS as below, but **leave `MAS_ENABLED=1` commented** until migration and cutover are done, so Synapse keeps using your current login path until you intentionally switch. You cannot use Synapse legacy OIDC/Keycloak SSO alongside MAS; plan IdP apps and envs accordingly.
+
 **Enable the stack:**
 
 - In `.env`, uncomment `compose.mas.yml` (and `compose.mas-upstream.yml` plus upstream envs if you use an external IdP), and uncomment the `SECRET_MAS_*` version lines.
@@ -57,8 +60,6 @@ You'll need to deploy something like [this](https://git.autonomic.zone/ruangrupa
 - `abra app cmd YOURAPPDOMAIN db ensure_mas_database` (once, creates the `mas` database in Postgres)
 - `abra app deploy YOURAPPDOMAIN`
 
-**If you plan to migrate an existing homeserver with `syn2mas`:** deploy and configure MAS as above, but **leave `MAS_ENABLED=1` commented** until migration and cutover are done, so Synapse keeps using your current login path until you intentionally switch. You cannot use Synapse legacy OIDC/Keycloak SSO alongside MAS; plan IdP apps and envs accordingly.
-
 <details>
 <summary><strong>Migrating an existing server (<code>syn2mas</code>)</strong></summary>