# 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`
- `RELEASE_MANIFEST.json`

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`

One-command automation:

```bash
pnpm companion:bundle -- \
  --output ./dist/companion-macos \
  --platform macos \
  --signing-key ./keys/release-private.pem \
  --signing-key-id team-k1
```

This script builds the bundle and immediately verifies checksums/signatures before returning success.

Reference app starters can be regenerated in-repo with:

```bash
pnpm companion:reference-apps -- --output ./apps/companion
```

This also regenerates `apps/companion/macos-app`, a runnable Swift Package menu-bar reference app scaffold.
By default it uses a reproducible `generatedAt` timestamp (`2026-02-27T00:00:00.000Z`); pass `--generated-at <iso>` if you need a different value.

CI automation:

- `.github/workflows/companion-release-bundle.yml` provides a manual-dispatch workflow that generates an ephemeral signing key, builds/verifies a bundle with `pnpm companion:bundle`, and uploads artifacts.
- `.github/workflows/companion-reference-apps-check.yml` runs `pnpm companion:reference-apps:check` on pull requests to ensure `apps/companion` stays in sync with generators.

## 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`
- `MenuBarCompanion.swift` (macOS)
- `CompanionBootstrap.swift` + `IOSCompanionRuntime.swift` (iOS)
- `CompanionBootstrap.kt` + `AndroidCompanionRuntime.kt` (Android)
- `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.