diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index 208b859..16f9b6b 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -119,6 +119,29 @@ litestream restore -config /etc/litestream.yml /data/landing/.state.sqlite
 source /opt/padelnomics/.env && bash infra/restore_landing.sh
 ```
 
+## Secrets management (SOPS + age)
+
+Secrets are stored encrypted in the repo using SOPS with age encryption:
+
+| File | Purpose |
+|------|---------|
+| `.env.dev.sops` | Dev defaults (safe/blank values) |
+| `.env.prod.sops` | Production secrets |
+| `.sops.yaml` | Maps file patterns to age public keys |
+
+```bash
+# Decrypt dev secrets to .env (one-time, or after changes)
+make secrets-decrypt-dev
+
+# Edit prod secrets (opens in $EDITOR, re-encrypts on save)
+make secrets-edit-prod
+
+# deploy.sh auto-decrypts .env.prod.sops → .env on the server
+```
+
+All env vars are defined in the sops files. See `.env.dev.sops` for the full list
+(decrypt with `make secrets-decrypt-dev` to read).
+
 ## Environment variables
 
 | Variable | Default | Description |