Upload

docs/box-lifecycle.md

@@ -0,0 +1,42 @@
+# Box Lifecycle
+
+## Purpose
+Defines the virtual box lifecycle: identity, WiFi states, and restart behavior.
+
+## Prerequisites
+- Box started with `python3 box/main.py run`
+
+## Step-by-step
+### Box identity
+- Generated on first start if `box/data/box.json` has no `box_id`.
+- Format: `klangkiste-<10 chars a-z0-9>`
+- Stored in `box/data/box.json`
+
+### WiFi states (logical)
+- `WIFI_UNCONFIGURED`: no profiles stored
+- `WIFI_CONNECTING`: reserved for future; not emitted in mock
+- `WIFI_ONLINE`: profile exists and mock is "connected"
+- `WIFI_OFFLINE`: profile exists but not connected
+
+### IP model (informational)
+- Setup/AP mode: `192.168.4.1`
+- Normal mode: `127.0.0.1`
+
+### Restart behavior
+- Box reloads `box_id`, resume state, and WiFi profiles from `box/data/`
+- Playback resume and WiFi status are preserved
+
+### Resets
+- WiFi reset: clears WiFi profiles only (`wifi_reset` command)
+- Factory reset: delete `box/data/box.json`, `box/data/state.json`, `box/data/secrets.enc`
+
+## Checklist
+- ✅ After first boot, `box/data/box.json` contains `box_id`
+- ✅ `GET /status` returns `wifi_state` and `ip_address`
+- ✅ WiFi reset clears profiles, `wifi_state=WIFI_UNCONFIGURED`
+
+## Troubleshooting
+- `wifi_state` not changing:
+  - Add a WiFi profile via setup UI or API.
+- Missing `box_id`:
+  - Ensure `box/data/box.json` is writable.