diff --git a/README.md b/README.md
index 6c618412..9c46ee0f 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,22 @@ system closure. Off by default (the toplevels are pinned to
 Alternatively warm the store manually:
 `nix build git+https://forge.darkest.space/hyperhive/hyperhive#agent-base-toplevel`.
 
+Optional: set `hyperhive.domain = "example.com";` to define the
+canonical hostname for hyperhive subsystems that need a stable public
+name. No default — subsystems that require it (currently:
+`hyperhive.matrix`) assert non-null at eval time with a clear error
+message if it is missing.
+
+Optional: set `hyperhive.matrix.enable = true;` to spin up a private
+[matrix-tuwunel](https://github.com/girlbossceo/conduwuit) homeserver
+in a nixos-container. Requires `hyperhive.domain` to be set first.
+The `server_name` (embedded irrevocably in every user and room ID)
+defaults to `matrix.<domain>`; override with
+`hyperhive.matrix.serverName = "chat.example.com";` if needed. 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).
+
 ## Agent configuration
 
 Per-agent settings live in each agent's `agent.nix` and are synced to