docs: public-facing README + MIT LICENSE; genericize CI workflow comment

README.md

@@ -1,46 +1,121 @@
-# varroa
+# Varroa
 
-Android companion for the Hivemapper Bee dashcam. Pulls detection
-landmarks off the on-Bee `adacam-api`, queues them in a local Room
-DB, forwards to AdaMaps when the phone has real internet.
+Varroa is an Android companion app for the **Hivemapper Bee** dashcam. It
+pulls detection landmarks off the camera's on-device API, queues them in a
+local database, and forwards them to an **AdaMaps** ingest endpoint once the
+phone has a validated internet connection. The Bee exposes its API only over
+its own Wi‑Fi access point, so Varroa exists to bridge that gap: collect while
+you're connected to the camera, upload when you're back on the internet.
 
-Sister piece: `blackbox/` — Python aggregator that runs on a truck
-Pi (BME680 + PMS5003) and ships air-quality readings into the same
-AdaMaps stream.
+The repository also ships `blackbox/`, a small Python companion that reads an
+air‑quality sensor on a Linux single‑board computer (e.g. a Raspberry Pi),
+fuses the readings with GPS from the Bee, and posts them to the same AdaMaps
+stream.
+
+## Features
+
+- **Store‑and‑forward collection** — `BeeCollectorService` polls the Bee for
+  detection landmarks and writes them to a local Room database. Nothing is lost
+  if the phone is offline.
+- **Validated‑internet uploads** — `AdaMapsUploadWorker` (WorkManager) drains
+  the queue to the AdaMaps API only when real connectivity is available, not
+  when you're merely attached to the camera's captive AP.
+- **Image capture** — `ImageCollectorService` pulls detection JPEGs from the
+  Bee for landmarks that have associated crops.
+- **Device pairing & status** — pair with the camera, view Wi‑Fi/storage/GNSS
+  status, and toggle device options from the in‑app settings screens.
+- **Optional Cardano wallet linking** — attach a wallet address to detection
+  uploads so contribution rewards can be routed to you. Entirely optional.
+
+## How it works
+
+```
+Hivemapper Bee  ──HTTP (AP only)──►  Varroa (Android)
+   detections                          ├─ Room queue (local DB)
+   landmark crops                      └─ AdaMapsUploadWorker
+                                              │  (only on validated internet)
+                                              ▼
+                                        AdaMaps ingest API
+```
+
+The Bee's API is reachable only over the camera's own access point, which
+serves plain HTTP on a fixed device‑AP address. Varroa scopes an Android
+cleartext exception to just that one host (see
+`app/src/main/res/xml/network_security_config.xml`); everything else is
+HTTPS‑only.
 
 ## Build
 
-```
-JDK 17, Android SDK 34
+Requirements: **JDK 17**, **Android SDK 34**. Minimum supported device is
+Android 8.0 (API 26).
+
+```bash
 ./gradlew :app:assembleDebug
 ```
 
-Release signing needs:
+The debug APK lands in `app/build/outputs/apk/debug/`.
 
-```
-VARROA_KEYSTORE_PATH=/path/to/varroa-release.keystore
-VARROA_KEYSTORE_PASSWORD=<see vault>
-VARROA_KEY_PASSWORD=<see vault>
+### Release signing
+
+Release builds are signed from a keystore supplied through environment
+variables (no secrets are stored in the repo):
+
+```bash
+export VARROA_KEYSTORE_PATH=/path/to/your-release.keystore
+export VARROA_KEYSTORE_PASSWORD=…
+export VARROA_KEY_PASSWORD=…        # defaults to the keystore password
 ./gradlew :app:assembleRelease
 ```
 
-## Config (set in-app)
+If the keystore variables are unset, Gradle falls back to an unsigned release
+build.
 
-- **Bee URL** — defaults to `http://192.168.0.10:5000` (Bee AP).
-- **AdaMaps URL + ingest key** — required before uploads run.
-- **Cardano wallet** — optional. Attaches to detection ingest for
-  rewards routing.
+## Configuration (set in‑app)
 
-## Architecture
+- **Bee URL** — the camera's API base URL. Defaults to
+  `http://192.168.0.10:5000`, the factory access‑point address; change it if
+  your camera uses a different AP IP.
+- **AdaMaps URL + ingest key** — required before uploads will run. Both are
+  entered in the app and stored locally; there are no baked‑in defaults.
+- **Cardano wallet** — optional. When set, the address is attached to detection
+  uploads for reward routing.
 
-- `BeeCollectorService` — polls the Bee, writes landmarks to Room.
-- `AdaMapsUploadWorker` — drains Room to `api.adamaps.org` once
-  validated internet is available.
-- `ImageCollectorService` — pulls detection JPEGs from the Bee.
+## blackbox (air‑quality companion)
 
-## blackbox
+`blackbox/air_aggregator.py` reads a BME680 (I²C) and a PMS5003 particulate
+sensor (UART), fuses the readings with GPS pulled from the Bee, and posts them
+to the AdaMaps ingest endpoint on a fixed interval, buffering to disk while
+offline.
 
-The air-quality side. `air_aggregator.py` reads BME680 +
-PMS5003 over USB, posts to AdaMaps every 60s. Systemd unit at
-`blackbox/air-aggregator.service` — set `ADAMAPS_KEY` and
-`AGGREGATOR_BEE_URL` in the unit before enabling.
+```bash
+pip install bme680 requests smbus2 pyserial
+BEE_URL=http://192.168.197.1:5000 \
+ADAMAPS_URL=https://api.adamaps.org \
+ADAMAPS_KEY=your-ingest-key \
+python3 blackbox/air_aggregator.py
+```
+
+A sample `systemd` unit is provided at `blackbox/air-aggregator.service`.
+
+## Documentation
+
+- `docs/BEE-CAMERA.md` — reverse‑engineering notes on the Hivemapper Bee's
+  internal camera pipeline (Intel Keem Bay / Myriad X VPU, DepthAI, the
+  on‑device REST API). Useful background for anyone building against the camera.
+- `docs/AIR-QUALITY-INTEGRATION.md` — design notes for adding an air‑quality
+  sensor to the Bee and ingesting the readings.
+
+## Tech stack
+
+Kotlin · Jetpack Compose · Room · DataStore · WorkManager · OkHttp/Gson ·
+osmdroid (map preview) · Coil (images).
+
+## Contributing
+
+Contributions are welcome. Please open an issue to discuss substantial changes
+before sending a pull request, keep commits focused, and make sure
+`./gradlew :app:assembleDebug` passes before submitting.
+
+## License
+
+Released under the MIT License. See [`LICENSE`](LICENSE).