# 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`

Optional signed export:

```bash
flynn companion \
  --platform macos \
  --node-id companion-macbook \
  --export-release-bundle ./dist/companion-macos \
  --signing-key ./keys/release-private.pem \
  --signing-key-id team-k1
```

Additional file:

- `CHECKSUMS.sha256.sig`

## Generate Platform Starter Shell Template

For native app bootstrapping (without launcher/checksum artifacts), export a platform template:

```bash
flynn companion \
  --platform ios \
  --node-id companion-ios \
  --export-shell-template ./dist/companion-ios-template
```

Generated files:

- `companion.bootstrap.json`
- platform starter file (`CompanionBootstrap.swift`, `CompanionBootstrap.kt`, or `MenuBarCompanion.swift`)
- `README.md`

## 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`

If signature is present, verify `CHECKSUMS.sha256.sig` with your org signing key policy before launch.

Automated CLI verification mode:

```bash
flynn companion \
  --verify-release-bundle ./dist/companion-macos \
  --verify-signing-key ./keys/release-public.pem \
  --verify-signing-key-id team-k1 \
  --require-signature
```

## Launch

```bash
./run-companion.sh
```

Launcher behavior:

- verifies `CHECKSUMS.sha256` before invoking `flynn companion`
- aborts launch on checksum mismatch or missing checksum tooling

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.