diff --git a/CLAUDE.md b/CLAUDE.md
index 4d6990f9..fb26720c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -147,6 +147,14 @@ hand-maintained per-file tree drifts out of sync with the code.
   unix socket the gateway's nginx proxies to — ⚠️ **the socket's
   directory is its access control**; the constraint that governs it is in
   the crate's README, and a unit test pins the path.
+- **`swarm-secret-client/`** — client for the swarm's secret store, over
+  `vaultrs`. Owns the *agreements* both ends of the store must share rather
+  than the HTTP: the path a credential lives at, the field its bytes are in,
+  and the translation from this deployment's environment into a logged-in
+  client. ⚠️ Reads the **`BAO_`** env spellings explicitly — `vaultrs`'s own
+  defaults look for `VAULT_ADDR`/`VAULT_CLIENT_CERT`/`VAULT_CLIENT_KEY`, which
+  no unit in this tree sets, so falling through to them yields a client with
+  **no identity** and a TLS handshake failure that names no cause.
 - **`swarmctl/`** — swarm-level operator CLI, installed by the
   swarm-controller module on the host that runs the daemon. Runs as
   **root and acts directly** — no socket, no HTTP route, no priv helper;