contrib header changes

docs/OTA.md

@@ -1,8 +1,8 @@
 # Over-the-air (OTA) updates — deployment schema **v0**
 
-The app checks a **stable channel URL**, follows it to a per-build manifest, then downloads the APK. Version comparison uses **`major.minor.build`** (packed into Android `versionCode` at build time). Deploy never computes `versionCode` by hand.
+The app checks a **stable channel URL**, follows it to a per-build manifest, then downloads the update. Version comparison uses **`major.minor.build`** (packed into Android `versionCode` at build time). Deploy never computes `versionCode` by hand.
 
-The client runs checks and downloads in **`OtaUpdateService`** (a standalone `Service`, not embedded in cast/receiver services). Launch checks enqueue work there; APK download uses a **foreground service** (`dataSync`) with a progress notification.
+The client runs checks and downloads in **`OtaUpdateService`** (a standalone `Service`, not embedded in cast/receiver services). Launch checks enqueue work there; download uses a **foreground service** (`dataSync`) with a progress notification.
 
 MQTT is fully supported for OTA sources using retained topic payloads (`mqtt://...` / `mqtts://...`). The URI path is treated as the exact topic to subscribe.
 
@@ -13,6 +13,7 @@ https://host/v0/ota/channel/stable.json
 https://host/v0/ota/00/00.{major}/00.{major}.{minor}/android_cast_00.{major}.{minor}.{build}.otapkg
 https://host/v0/ota/00/00.{major}/00.{major}.{minor}/android_cast_00.{major}.{minor}.{build}_sign.json
 https://host/v0/ota/00/00.{major}/00.{major}.{minor}/android_cast_00.{major}.{minor}.{build}_manifest.json
+https://host/v0/ota/00/00.{major}/00.{major}.{minor}/android_cast_00.{major}.{minor}.{build}.otabundle.zip
 ```
 
 - **`v0`** — deployment schema version (default channel).
@@ -59,6 +60,10 @@ Example: `0.1.5` → `versionCode` **105**.
   "versionName": "0.1.5",
   "apkUrl": "https://host/v0/ota/00/00.01/00.01.05/android_cast_00.01.05.otapkg",
   "signUrl": "https://host/v0/ota/00/00.01/00.01.05/android_cast_00.01.05_sign.json",
+  "sizeBytes": 42100000,
+  "bundleUrl": "https://host/v0/ota/00/00.01/00.01.05/android_cast_00.01.05.00.otabundle.zip",
+  "bundleSha256": "…",
+  "bundleSizeBytes": 42150000,
   "mandatory": false,
   "releaseNotes": ""
 }
@@ -73,7 +78,23 @@ Example: `0.1.5` → `versionCode` **105**.
 }
 ```
 
-The app loads `sha256` from `sign.json` when the manifest omits it.
+The app loads `sha256` from `sign.json` when the manifest omits it (APK hash inside the bundle or standalone `.otapkg`).
+
+## Optional HTTP bundle (`.otabundle.zip`)
+
+`generate-ota-v0.sh` emits a **STORE** (uncompressed) zip so the APK is not re-deflated:
+
+| Entry inside zip | Content |
+|------------------|---------|
+| `manifest.json` | Same as `*_manifest.json` |
+| `sign.json` | Same as `*_sign.json` |
+| `package.apk` | Release APK bytes |
+
+**Check path (lightweight):** channel → small `*_manifest.json` (+ optional `*_sign.json`) — no bundle download until the user installs.
+
+**Download path (HTTP):** if `bundleUrl` is `http`/`https`, the app downloads one zip, verifies `bundleSha256`, unpacks, verifies `package.apk` against `sha256`, then runs the installer. If `bundleUrl` is absent, it falls back to separate `apkUrl` / `signUrl` fetches (required for MQTT).
+
+**MQTT:** keep **per-artifact** retained topics (`manifest.json`, `sign.json`, `.otapkg`). Do not publish full bundles on MQTT (message size limits). The app ignores `bundleUrl` when the scheme is not HTTP(S).
 
 ## MQTT transport
 
@@ -114,5 +135,5 @@ Legacy `ota.manifest.url` still works as a direct manifest URL fallback.
 
 1. Bump `ota.major` / `ota.minor` / `ota.build` (or Gradle defaults).
 2. Build signed release APK (`versionCode` is derived automatically).
-3. Run `generate-ota-v0.sh` and upload `v0/ota/**`.
+3. Run `generate-ota-v0.sh` and upload `v0/ota/**` (including `.otabundle.zip`).
 4. Confirm `stable.json` points at the new `*_manifest.json`.