feat(power): add controlled low-battery shutdown

docs/battery-management.md

@@ -50,15 +50,33 @@ The direct LCD renderer composites the transparent `charging.png` asset in the
 top-right corner whenever GPIO10 reports active-low charging. It composites
 `lowbat.png` at the bottom center after the domain level enters low or critical
 state. Both overlays may be visible together, and QR-code presentations omit
-them to preserve scan reliability. Overlay state changes do not trigger any
-shutdown, sleep, prompt, or actuator policy.
+them to preserve scan reliability.
 
-## Deferred Policy
+## Controlled Critical-Battery Shutdown
 
-Critical status currently produces a state-transition log only. The reserved
-shutdown hook returns `ESP_ERR_NOT_SUPPORTED`; it does not stop audio or the
-stepper, enter deep sleep, or release board power. Implement wake sources and
-the product shutdown sequence before enabling any automatic critical action.
+When controlled shutdown is enabled, an unplugged battery at or below both the
+configured critical percentage and 3450 mV must produce three valid samples.
+An emergency raw voltage at or below 3350 mV requires two samples and is not
+blocked by the high-load suppression window. Either path latches a single
+shutdown sequence.
+
+The sequence stops interaction sources, OTA, multimodal transport, active
+playback, and the stepper before synchronously playing
+`shutdown_power_empty.opus`. The prompt is mandatory: a failed or incomplete
+playback is retried and deep sleep is entered only after playback completion.
+The codec/PA, LCD backlight, Wi-Fi, and stepper outputs are then disabled. PA,
+backlight, and stepper GPIOs are held low through deep sleep. A small NVS record
+stores the shutdown reason, voltage, and percentage on a best-effort basis.
+
+GPIO10 is configured as the default active-low wake source. The optional
+active-low button wake GPIO defaults to `-1` (disabled). After deep-sleep wake,
+normal boot continues only while charging or when battery voltage is at least
+3550 mV. Otherwise the device immediately returns to deep sleep before audio,
+LCD, Wi-Fi, or server startup.
+
+This is a low-power software shutdown, not physical board power removal,
+because the board power-hold GPIO is disabled. The fixed battery divider and
+any board-level always-on loads continue to draw current.
 
 ## Bench Calibration