diff --git a/docs/swarm.md b/docs/swarm.md
index 1fa69f17..4e0d6fb8 100644
--- a/docs/swarm.md
+++ b/docs/swarm.md
@@ -53,6 +53,13 @@ optional:
   for peers whose self-signed TLS cert doesn't chain to a CA your
   host trusts.
 
+`certFingerprint` scopes **only** to hive-c0re's own peer HTTPS checks
+(the P33RS dashboard links and agent peer discovery below). It is
+**not** consulted by matrix federation — tuwunel validates a peer's
+federation certificate against the system CA bundle independently (see
+*Matrix federation* below), so pinning a fingerprint here does nothing
+for a self-signed matrix gateway cert.
+
 ### Fingerprint format
 
 The value is the string `sha256:` followed by exactly 64 hexadecimal
@@ -105,10 +112,15 @@ environment and forwarded to agent containers.
    qualified names (`agent@domain`).
 
 3. **Matrix federation** — when `matrix.enable` is on, tuwunel
-   federates with the peer's matrix server at
-   `matrix.{peer-domain}:8448`. No extra config needed; federation
-   works as soon as the domains are reachable and TLS validates.
-   See `docs/matrix.md` for federation firewall requirements.
+   federates with the peer's matrix server (discovered via the peer's
+   `.well-known/matrix/server` delegation, which the gateway serves).
+   Federation validates the peer's TLS certificate against the
+   **system CA bundle** — independently of `certFingerprint`, which it
+   never consults. A self-signed gateway certificate therefore won't
+   federate even with a fingerprint pinned above: the peers need
+   CA-issued certs (ACME) or a shared private CA trusted on both
+   gateway hosts. See `docs/matrix.md` for federation firewall + TLS
+   requirements.
 
 ## Bilateral setup