diff --git a/CLAUDE.md b/CLAUDE.md
index 54aa3453..ed4e52ab 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -297,6 +297,8 @@ docs/
   damocles-migration.md  future migration plan for damocles → hyperhive
   gateway.md           nginx vhost map, matrix discovery flow, firewall posture,
                        HIVE_FORGE_URL loopback rationale (#764, #772, #793)
+  matrix.md            matrix container shape, serverName/gatewayHost split,
+                       firewall + federation, provisioning flow, fluffychat-web build
 ```
 
 ## Reading paths
@@ -320,6 +322,9 @@ read them à la carte.
   [`docs/gotchas.md`](docs/gotchas.md).
 - **"What nginx vhosts does the gateway serve? How does matrix
   discovery work?"** → [`docs/gateway.md`](docs/gateway.md).
+- **"How does the matrix-tuwunel container work? What about
+  fluffychat-web and per-agent matrix accounts?"** →
+  [`docs/matrix.md`](docs/matrix.md).
 
 ## Conventions & process