diff --git a/docs/matrix.md b/docs/matrix.md
index 9d16aeac..023862ea 100644
--- a/docs/matrix.md
+++ b/docs/matrix.md
@@ -141,6 +141,29 @@ purges and is reused on re-provision.
 considered already created. Delete the file to force re-creation (e.g.
 after a homeserver wipe).
 
+## Configuration tuning
+
+```nix
+services.hyperhive.matrix = {
+  trustedServers  = [ "matrix.org" "example.com" ];   # default: []
+  maxRequestSize  = 20000000;                          # default: 20 MB
+};
+```
+
+**`trustedServers`** (default `[]`) — list of peer homeserver names
+whose signing keys tuwunel will fetch and trust. Federation is enabled
+at the protocol level from first boot (`allow_federation = true`) but
+no remote homeserver is trusted until listed here. For a closed
+single-hive deployment the default empty list is correct — add peer
+hive domains here when connecting hives into a swarm (see
+[`docs/swarm.md`](swarm.md)).
+
+**`maxRequestSize`** (default `20_000_000` bytes = 20 MB) — maximum
+size of a single matrix client request body. Matches the matrix-spec
+recommendation for media uploads and the upstream tuwunel default.
+Raise for deployments that need large file transfers; lower for
+resource-constrained hosts where a 20 MB request is unexpectedly large.
+
 ## Assertion rationale
 
 Two `config.assertions` entries fail eval early rather than ship