Merge develop into main

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Python control plane for DotBots. Serial / cloud / edge adapters talk to a DotBot gateway (often via Mari → marilib); a FastAPI REST + WebSocket server exposes state; a React web UI provides joystick/map/lighthouse-position visualization. Also ships CLI tools (`dotbot-controller`, `dotbot-edge-gateway`, `dotbot-keyboard`, `dotbot-joystick`, `dotbot-qrkey`) and DotBot/SailBot simulators.
+Python control plane for DotBots. Serial / cloud / edge adapters talk to a DotBot gateway (often via Mari → marilib); a FastAPI REST + WebSocket server exposes state; a React web UI provides joystick/map/lighthouse-position visualization. Ships a unified `dotbot` CLI whose top level is four object-namespaces: `fw` (firmware artifacts: build/fetch/list/make), `device` (one cabled device: flash/info), `swarm` (the fleet over the air), and `run` (host-side processes you launch — `dotbot run controller`, `run gateway`, `run simulator`, `run lh2-calibration`, `run demo`, `run keyboard`, `run joystick`), plus DotBot/SailBot simulators. The `dotbot` dispatcher is the only console script — there are no per-command `dotbot-*` binaries.
 
 This is the most active repo in the ecosystem (187 commits in last 90 days as of 2026-05-05).
 
@@ -15,16 +15,23 @@ This is the most active repo in the ecosystem (187 commits in last 90 days as of
 
 ## Entry points
 
-- `dotbot/controller_app.py` — main CLI (`dotbot-controller`); wires adapters and settings
+- `dotbot/cli/main.py` — unified `dotbot` Click group (lazy subcommand loader)
+- `dotbot/controller_app.py` — `dotbot run controller` subcommand backend; wires adapters and settings
 - `dotbot/controller.py:1` — 737-line `Controller` class; central object
 - `dotbot/frontend/src/App.tsx` — React UI root
 
 ## Build / run / test
 
 ```bash
 pip install pydotbot                         # or `pip install -e .`
-dotbot-controller --help
-# Other entry points: dotbot-edge-gateway, dotbot-keyboard, dotbot-joystick, dotbot-qrkey
+dotbot --help                    # unified dispatcher: fw / device / swarm / run
+dotbot fw --help                 # firmware artifacts: build / fetch / list / make
+dotbot device --help             # one cabled device: flash an app/role, read info
+dotbot swarm --help              # the fleet over the air (swarmit; in the base install)
+dotbot run --help                # host-side processes (controller, gateway, simulator, ...)
+dotbot run controller --help     # start the controller
+dotbot run lh2-calibration --help  # LH2 calibration (optional: pip install pydotbot[calibrate])
+dotbot run demo --list           # built-in research demos
 
 # Tests / lint / build
 tox                                          # envs: tests, check, cli, web=npm run lint, doc
@@ -45,7 +52,14 @@ CI: `.github/workflows/continuous-integration.yml` — `tox` on Linux/macOS/Wind
 - **`PyDotBot-utils`** — `pyproject.toml:49`; used by `utils/hooks/sdist.py:build_frontend`
 - **`DotBot-libs`** — checked out in CI to build `utils/control_loop` C library
 - **`DotBot-firmware`** — referenced only in README (flashing instructions); no code dep
-- No references to: `swarmit`, `dotbot-lh2-calibration`, `dotbot-provision`
+- **`swarmit`** — sibling package, a core dependency (`pyproject.toml`);
+  imported lazily inside `dotbot/cli/swarm.py`, which bridges the unified
+  config's `conn`/`swarm_id` into swarmit's flags at the mount boundary.
+- **`dotbot-provision`** — vendored into `dotbot/provision/` (Phase 2,
+  2026-05). Standalone PyPI package scheduled for deprecation.
+- **`dotbot-lh2-calibration` (Python)** — vendored into
+  `dotbot/calibration/` (Phase 2, 2026-05). The C firmware stays in
+  its own repo.
 
 ## State of repo (snapshot 2026-05-05)
 

CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to PyDotBot are recorded here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Unified `dotbot` CLI dispatcher that mounts every workflow (controller,
+  simulator, testbed ops, calibration, demos, keyboard/joystick) under one
+  command. Subcommand modules are loaded lazily so `dotbot --help` stays
+  cheap.
+- `dotbot run demo` discoverable launcher; `dotbot run demo qr` runs the
+  qrkey phone-bridge demo.
+- `dotbot fw` mock surface (scaffold/build/flash subcommands; placeholder
+  for the firmware-developer workflow).
+- **Vendored `dotbot-provision`** into `dotbot/provision/`. All five
+  subcommands available as `dotbot testbed provision <fetch|flash|
+  flash-hex|read-config|flash-bringup>`.
+- **Vendored `dotbot-lh2-calibration` (Python side)** into
+  `dotbot/calibration/`. Surfaced as `dotbot run lh2-calibration` with
+  two subcommands:
+  - `collect` — runs the Textual TUI (default — bare
+    `dotbot run lh2-calibration` invokes this for muscle memory)
+  - `apply <path>` — write the saved calibration as a C header to
+    `<path>` (replaces the previous `dotbot-calibration-exporter`;
+    today the only consumer is the swarmit secure bootloader which
+    `#include`s the file at compile time)
+  The C firmware in the `dotbot-lh2-calibration` repo is unchanged.
+  Future OTA / swarm-wide counterparts (`collect` over MQTT,
+  `apply` as OTA push) will live under `dotbot swarm
+  calibrate-lh2`.
+- Calibration records are now saved as timestamped, schema-versioned
+  TOML files (`~/.dotbot/calibration-<UTC timestamp>.toml`) carrying
+  metadata (number of LH stations, calibration distance, creation
+  time) alongside the homography bytes (hex-encoded under
+  `[calibration].data_hex`). The legacy `~/.dotbot/calibration.out`
+  binary is still written as a back-compat byproduct so external
+  consumers (swarmit OTA, `dotbot testbed provision flash`) keep
+  working unchanged; once they learn to read TOML the legacy write
+  will be dropped. `load_calibration()` prefers the newest TOML and
+  falls back to `calibration.out` if no TOML files exist.
+- `dotbot testbed provision flash --calibration <path>` accepts a
+  `.toml` calibration file in addition to the legacy binary format
+  (the file extension drives the parsing path).
+- Optional dependency groups (revised):
+  - `pip install dotbot[testbed]` adds `swarmit` (still external)
+  - `pip install dotbot[provision]` adds `intelhex` (provision runtime)
+  - `pip install dotbot[calibrate]` adds `opencv-python` + `textual`
+  - `pip install dotbot[all]` pulls all three
+
+### Changed
+
+- **Breaking — CLI reorganized into four object-namespaces.** The top
+  level is now exactly `fw` (firmware artifacts), `device` (one cabled
+  device), `swarm` (the fleet), and `run` (host-side processes). The flat
+  process verbs moved under `run`: `dotbot controller` → `dotbot run
+  controller`, and likewise `gateway` / `simulator` / `demo` / `keyboard` /
+  `joystick`; `dotbot calibrate-lh2` → `dotbot run lh2-calibration`. The
+  Makefile escape hatch moved from `dotbot make` to `dotbot fw make`.
+  `run` subcommands are still loaded lazily, so `dotbot run --help` stays
+  cheap.
+- The qrkey integration moved from `dotbot/qrkey.py` to
+  `dotbot/examples/qrkey_demo/`. The demo is now a separate process that
+  consumes the controller's REST API — the controller stays agnostic to
+  qrkey.
+- `dotbot/examples/qrkey_demo/` is a thin client of the upstream `qrkey`
+  package (now pinned `>= 0.12.2`); none of its code is vendored.
+- Frontend polls qrkey count every 1 s for faster Show QR button
+  feedback.
+
+### Removed
+
+- `dotbot-qrkey` console script — use `python -m dotbot.examples.qrkey_demo`
+  or `dotbot run demo qr` instead.
+- `dotbot-edge-gateway` console script — the referenced module
+  `dotbot.edge_gateway_app` never existed; the entry was silently broken.
+- `pin_code` tox env — referenced `dotbot/pin_code_ui/` which never
+  existed.
+- `dotbot-provision` and `dotbot-lh2-calibration` PyPI dependencies
+  (folded into the `dotbot` package). The standalone PyPI packages are
+  scheduled for deprecation releases that point users at `pip install
+  dotbot[provision]` / `pip install dotbot[calibrate]`.
+- `dotbot-controller`, `dotbot-keyboard`, and `dotbot-joystick` console
+  scripts — removed outright (no longer aliased). Use `dotbot run
+  controller` / `dotbot run keyboard` / `dotbot run joystick`.
+
+### Deprecated
+
+- The standalone `dotbot-provision` and `dotbot-lh2-calibration` PyPI
+  packages will issue `DeprecationWarning` on their next release and
+  point users at `pip install dotbot[provision]` /
+  `pip install dotbot[calibrate]`. Their console scripts
+  (`dotbot-provision`, `dotbot-calibration`,
+  `dotbot-calibration-exporter`) are not re-exported by `dotbot`
+  because they never shipped from this package; use the unified
+  subcommands instead.