diff --git a/CLAUDE.md b/CLAUDE.md
index c235369d..03bb7eb6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -255,10 +255,10 @@ nix/
                                  local-dev DNS; v0 HTTP-only (#609)
   modules/hive-matrix.nix       optional in-container matrix-tuwunel
                                  homeserver (`services.hyperhive.matrix.enable`,
-                                 default off); server_name derives from
-                                 `services.hyperhive.domain` (subdomain by default);
-                                 federation on (empty trusted_servers),
-                                 registration off, e2ee deferred (#551)
+                                 default off); server_name defaults to bare
+                                 `services.hyperhive.domain` (#660); gateway serves
+                                 `.well-known/matrix/{client,server}` for
+                                 auto-discovery; federation on, e2ee deferred (#551)
   templates/harness-base.nix    shared scaffolding for sub-agents + manager;
                                  `hyperhive.model` option (HIVE_DEFAULT_MODEL)
   templates/agent-base.nix      sub-agent nixosConfiguration
diff --git a/README.md b/README.md
index 017b7bf3..3bcf3955 100644
--- a/README.md
+++ b/README.md
@@ -110,8 +110,13 @@ homeserver in a nixos-container. Requires either
 `services.hyperhive.domain` or `services.hyperhive.matrix.serverName`
 to be set (eval fails with a clear error if both are absent). The
 `server_name` (embedded irrevocably in every user and room ID)
-defaults to `matrix.<domain>`; override with
-`services.hyperhive.matrix.serverName = "chat.example.com";` if needed. State
+defaults to `<domain>` (bare hive domain, since #660); the hive-gateway serves
+`.well-known/matrix/{client,server}` endpoints so clients auto-discover the
+homeserver without a subdomain. **Existing homeservers** must set
+`services.hyperhive.matrix.serverName = "matrix.<domain>";` explicitly to
+preserve pre-#660 user/room IDs. Override with
+`services.hyperhive.matrix.serverName = "chat.example.com";` for a custom
+server name. State
 lives at `/var/lib/nixos-containers/hive-matrix/`. Federation is
 enabled with an empty `trusted_servers` list; e2ee is deferred to
 a follow-up (#551).