Battery tentacle created.

battery-status/README.md

@@ -0,0 +1,64 @@
+# Battery Status
+
+Press **Cthulhu+Shift+B** in either keyboard layout to report battery status.
+With one battery, hear and read a short message such as
+“Laptop battery, discharging, 90 percent.” With several batteries, an internal
+**Battery Menu** lists each device with its status and charge. Use Up and Down
+to browse; Enter and Escape both close without additional output. The shortcut
+is a suggestion and can be remapped in Cthulhu.
+
+Battery Status reads the UPower service over the system D-Bus. It does not run
+the `upower` command, require root, or change power settings. Install and enable
+your distribution's UPower service if it is missing. An unavailable service
+produces “Battery information unavailable.” A successful read with no batteries
+produces “No batteries detected.” If some devices cannot be read, readable
+results are accompanied by “Some battery information is unavailable.”
+
+The kernel, drivers, and hardware determine which laptop, controller, headset,
+mouse, UPS, and other batteries UPower can expose. Device model names may be
+generic. Unknown charge is reported explicitly; unknown charging state is
+omitted. Devices with only coarse levels use words such as “low” or “normal”
+rather than an artificial percentage. Precise percentages are rounded to whole
+numbers. System batteries appear first; duplicate names have numbered suffixes.
+UPower's combined DisplayDevice and AC adapters are excluded.
+
+Each invocation reads UPower's latest reported values, with a one-second read
+limit to fit Cthulhu's two-second command deadline. An open menu is a snapshot:
+close and invoke again to refresh. There are
+no background notifications, time estimates, hardware-statistics views, or
+sysfs fallbacks. UPower may itself cache values between device updates.
+See the [UPower device API](https://upower.freedesktop.org/docs/Device.html).
+
+## Build and verify
+
+From the repository root, run `make check`. Build release artifacts with
+`python3 -B tools/package.py --tentacle battery-status`. This prepares amd64 and
+arm64 packages and a proposed catalog under `dist/`; it publishes nothing.
+The source catalog intentionally advertises no release downloads yet.
+
+For an actual-host diagnostic without speech or changes to the running reader,
+run from the adjacent `cthulhu` checkout:
+
+```sh
+GOCACHE=/tmp/cthulhu-cache go run ./cmd/tentacle-host -presentation -interaction -command battery-status "$PWD/../cthulhu-tentacles/battery-status/bin/battery-status"
+```
+
+Use the development launch procedure in Hello World's README for live testing,
+with launch ID `battery-status`, the matching executable, and both Presentation
+and Interaction grants. Review and test before submission, as required by
+CONTRIBUTING.md. Verify:
+
+- The shortcut, learn-mode description, and remapping in both layouts.
+- A single battery speaks and brailles its status without a menu.
+- With another battery-bearing device connected, the Battery Menu opens,
+  Up/Down reads each row, and Enter and Escape dismiss it silently.
+- Reopening reflects updated devices and charge; no combined duplicate appears.
+- Speech preferences and interruption, connected Braille, screen lock/handoff,
+  disable/re-enable, and normal reading after closing the menu still work.
+
+Automated tests use injected device sources for absent/unavailable services,
+partial failures, and battery combinations, without altering the system service.
+Cross-building arm64 does not establish execution on arm64; test that package
+on matching hardware before publication.
+
+Licensed GPL-3.0-or-later; see LICENSE.