feat(ota): add authenticated firmware update workflow

- report firmware versions at startup and every six hours with a fresh device JWT
- support optional HMAC headers and retry once after authorization rejection
- handle forced and confirmed updates through managed OTA state
- stream images to the inactive partition and verify size, SHA-256, and format
- coordinate OTA HTTPS activity with voice teardown and restoration
- confirm pending images and expose configuration, status, and integration docs

docs/ota-firmware-integration.md

@@ -0,0 +1,31 @@
+# OTA Firmware Integration
+
+The control plane owns a managed OTA worker. After Wi-Fi is available, it
+obtains a device JWT with the `ota:report` scope and posts the running device
+identity and firmware version to `CONFIG_TQ_OTA_REPORT_URL`.
+
+The service returns `204` when the running image is current. A `200` response
+with `data.notUptodate=1` includes the target version, HTTPS download URL,
+exact byte size, SHA-256, and the `force`/`update` decision. Non-forced images
+wait for the mini-program confirmation (`update=1`); forced images proceed
+without that confirmation.
+
+Before an HTTPS exchange, the worker quiesces local wake and multimodal voice
+services, waits for transport teardown, and checks internal/DMA memory
+headroom. The platform layer streams the image into the inactive OTA
+partition, verifies the exact byte count and raw-file SHA-256, validates the
+ESP-IDF image, selects the new boot partition, and restarts. Any failure
+aborts the OTA handle and leaves the current partition active.
+
+The first normal runtime startup of a pending image confirms it with the
+ESP-IDF rollback API. A failed or unhealthy boot therefore rolls back to the
+previous image.
+
+The running version is embedded in the application descriptor at build time.
+Update the repository-root `version.txt` before publishing a release; the
+device reads it at runtime through `esp_app_get_description()->version`.
+
+The device report route should normally be exempted from service-to-service
+HMAC authentication while retaining device JWT authentication. The optional
+`CONFIG_TQ_OTA_INTERNAL_AUTH_SECRET` exists only for deployments that require
+the documented `X-Internal-*` headers.