diff --git a/CLAUDE.md b/CLAUDE.md
index 34fcf29..305e5b3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -99,6 +99,34 @@ The rotate target is non-destructive (it moves, never deletes) and
 opt-in (no other target invokes it). Old archives stay around for
 retrospective diffing whenever something goes sideways.
 
+## Decrypting diagnostic reports
+
+Reporters attach an encrypted diagnostic archive
+(`aftertouch-diagnostic-*.age`), usually saved under `_/i_<reporter>/`.
+Decrypt it with **this repo's own tool**, not the generic `age` CLI:
+
+```bash
+go run scripts/decrypt-diagnostic.go <file.age> | tar xz -C <dir containing the .age>
+```
+
+- The tool is `scripts/decrypt-diagnostic.go`; the private key lives at
+  `keys/private/diagnostic` (provisioned by `scripts/setup-diagnostic-key.sh`,
+  and never committed). It writes the decrypted `.tar.gz` to stdout.
+- Always decrypt/unpack next to the `.age` (not a scratch/tmp dir), into a
+  **per-file subfolder** so nothing collides: e.g.
+  `mkdir -p <dir>/extracted-<timestamp> && go run scripts/decrypt-diagnostic.go <dir>/<file>.age | tar xz -C <dir>/extracted-<timestamp>`.
+  This matters when a reporter folder holds multiple `.age` snapshots or
+  already has other files: every archive uses the same inner names
+  (`diagnostic.json`, `datastore/`, `http/`, ...), so extracting two into the
+  same dir overwrites and mixes them.
+- The archive contains `diagnostic.json` (health/device summary), `datastore/`
+  (raw speaker XML: DeviceInfo/Presets/Recents/Sources), `http/` (service
+  `full.xml`, `sourceproviders.xml`, captured speaker responses), `logs/`,
+  `settings.json`, `env.txt`, `system/`, `ssh/`. See
+  `docs/content/docs/appendix/DIAGNOSTIC-EXPORT.md`.
+- Reporter data stays under `_/` and is never committed (see "What never goes
+  into this repo").
+
 ## Project structure
 
 ```