From 461ed7d8885108a5b75b1b97afdb8a656780de83 Mon Sep 17 00:00:00 2001
From: Peter Woolery <peter@research.bike>
Date: Mon, 27 Apr 2026 14:45:08 -0700
Subject: [PATCH] docs(readme): add HMAC secret generation command to operator
 setup

Step 2 now shows openssl rand -hex 32 (with python and /dev/urandom
fallbacks) and writes to .agent/dc-<id>-secret with chmod 600, so the
flash_device.py example can read $(cat ...) the same way the known-good
dc-0002 command does.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3391e6f..cfb2d51 100644
--- a/README.md
+++ b/README.md
@@ -193,12 +193,29 @@ pio run -t upload --upload-port /dev/ttyUSB0
 
 ### 2. Provision device identity
 
+Generate a fresh 32-byte HMAC secret (64 hex chars) and stash it where you
+won't lose it — the server must store the same value or counts will be
+rejected:
+
+```bash
+# Generate and save (one device per file; never commit these)
+mkdir -p .agent
+openssl rand -hex 32 > .agent/dc-0042-secret
+chmod 600 .agent/dc-0042-secret
+```
+
+> No `openssl`? Equivalents:
+> - `python3 -c 'import secrets; print(secrets.token_hex(32))'`
+> - `head -c 32 /dev/urandom | xxd -p -c 64`
+
+Then provision:
+
 ```bash
 python tools/flash_device.py \
   --port /dev/ttyUSB0 \
   --device-id dc-0042 \
   --location-id retailer-123 \
-  --hmac-secret <32-byte-hex> \
+  --hmac-secret "$(cat .agent/dc-0042-secret)" \
   --wifi-ssid "StoreWiFi" \
   --wifi-password "secret"
 ```