docs(CLAUDE): document how to decrypt diagnostic reports

Use the repo's own scripts/decrypt-diagnostic.go (not the generic age
CLI), unpack per-file next to the .age, and note the archive layout.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tobias Gesellchen
2026-06-27 19:34:09 +02:00
co-authored by Claude Opus 4.8
parent 9d8e8f4858
commit 96cdc050d1
+28
View File
@@ -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
```