docs(companion): add release bundle install and verification runbook

2026-02-26 19:00:46 -08:00
parent bbec292434
commit f10c896a75
4 changed files with 77 additions and 2 deletions
@@ -0,0 +1,59 @@
+# Companion Release Bundle Runbook
+
+This runbook covers generating, verifying, and launching Flynn companion shell bundles.
+
+## Generate Bundle
+
+From a Flynn host:
+
+```bash
+flynn companion \
+  --platform macos \
+  --node-id companion-macbook \
+  --app-version 1.0.0 \
+  --export-release-bundle ./dist/companion-macos
+```
+
+Generated files:
+
+- `companion.bootstrap.json`
+- `run-companion.sh`
+- `README.md`
+- `CHECKSUMS.sha256`
+
+## Verify Bundle Integrity
+
+On the target host (before launch), verify checksums:
+
+```bash
+cd ./dist/companion-macos
+sha256sum --check CHECKSUMS.sha256
+```
+
+Expected result:
+
+- all bundle files report `OK`
+
+## Launch
+
+```bash
+./run-companion.sh
+```
+
+Optional handoff smoke test:
+
+```bash
+./run-companion.sh --handoff "status check"
+```
+
+## Platform Notes
+
+- `ios` and `macos` default push provider to `apns` when `--push-token` is set.
+- `android` defaults push provider to `fcm` when `--push-token` is set.
+- For `linux`, `windows`, or `unknown` platforms, specify `--push-provider` explicitly when using `--push-token`.
+
+## Distribution Guidance
+
+- Treat `companion.bootstrap.json` as sensitive if it includes gateway tokens or push tokens.
+- Remove or rotate secrets before sharing bundles externally.
+- For signed releases, sign the bundle directory or tarball with your standard org release-signing process after checksum verification.