From f10c896a75f0a45e695d291b1cf76f592ddd2cf2 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Thu, 26 Feb 2026 19:00:46 -0800 Subject: [PATCH] docs(companion): add release bundle install and verification runbook --- README.md | 2 + docs/README.md | 1 + docs/operations/COMPANION_RELEASE_BUNDLE.md | 59 +++++++++++++++++++++ docs/plans/state.json | 17 +++++- 4 files changed, 77 insertions(+), 2 deletions(-) create mode 100644 docs/operations/COMPANION_RELEASE_BUNDLE.md diff --git a/README.md b/README.md index 2721064..e9d660e 100644 --- a/README.md +++ b/README.md @@ -1747,6 +1747,8 @@ Minimal companion CLI: - `flynn companion --once --latitude 37.3349 --longitude -122.009 --location-source gps` bootstraps node location metadata. - `flynn companion --once --platform android --push-token ` (or `--platform ios --push-token `) registers push routing metadata during bootstrap. +Companion release runbook: `docs/operations/COMPANION_RELEASE_BUNDLE.md` + ## WebChat PWA Push Subscriptions Enable installable WebChat PWA metadata and browser push-subscription storage on the gateway: diff --git a/docs/README.md b/docs/README.md index 879cf9e..e2b1289 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,7 @@ This documentation is written to be useful to both humans and AI agents. If you 6. Operations runbooks - `docs/operations/OPERATOR_PACK.md` - `docs/operations/GOOGLE_AUTH.md` + - `docs/operations/COMPANION_RELEASE_BUNDLE.md` ## Quick Map (One Diagram) diff --git a/docs/operations/COMPANION_RELEASE_BUNDLE.md b/docs/operations/COMPANION_RELEASE_BUNDLE.md new file mode 100644 index 0000000..7e83d08 --- /dev/null +++ b/docs/operations/COMPANION_RELEASE_BUNDLE.md @@ -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. diff --git a/docs/plans/state.json b/docs/plans/state.json index d18e5d0..5ddb9b9 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -7000,6 +7000,19 @@ "docs/plans/state.json" ], "test_status": "pnpm test:run src/cli/companion.test.ts src/companion/releaseBundle.test.ts + pnpm typecheck passing" + }, + "personal-assistant-productization-phase1-companion-install-runbook": { + "status": "completed", + "date": "2026-02-27", + "updated": "2026-02-27", + "summary": "Added companion release installation/verification runbook (`docs/operations/COMPANION_RELEASE_BUNDLE.md`) covering bundle generation, checksum verification, launch flows, platform push-provider defaults, and secret-handling guidance. Linked runbook from docs index and README companion section.", + "files_modified": [ + "docs/operations/COMPANION_RELEASE_BUNDLE.md", + "docs/README.md", + "README.md", + "docs/plans/state.json" + ], + "test_status": "docs-only runbook update; no runtime code changes" } }, "overall_progress": { @@ -7018,7 +7031,7 @@ "tier2_completion": "4/4 (100%) — inbound webhooks, vector memory search, Dockerfile, heartbeat monitor", "tier3_completion": "5/5 (100%) — lane queue, credential redaction, web UI token dashboard, xAI (Grok) provider, Voyage AI embeddings", "tier4_completion": "4/4 (100%) — gateway lock, shell completion, Tailscale Serve/Funnel, DM pairing codes", - "feature_gap_scorecard": "rebaselined 2026-02-26 and updated 2026-02-27 (phase 3 + phase 1 + phase 2 + phase 4 slices + companion packaging/bundle tooling + shell bootstrap controls) — channel breadth, setup wizard, baseline browser automation, subagent controls, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging primitives (bootstrap export + release-bundle artifacts + checksum manifests) and one-shot status/location/push shell bootstrap controls, voice reliability hardening (talk controls + TTS fallback/health + interruption-safe cancel semantics), and onboarding first-success funnel improvements are implemented; remaining high-impact personal-assistant gaps center on shipped desktop/mobile companion app binaries and signed distribution pipelines.", + "feature_gap_scorecard": "rebaselined 2026-02-26 and updated 2026-02-27 (phase 3 + phase 1 + phase 2 + phase 4 slices + companion packaging/bundle tooling + shell bootstrap controls + install runbook) — channel breadth, setup wizard, baseline browser automation, subagent controls, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging primitives (bootstrap export + release-bundle artifacts + checksum manifests), companion install/verification runbook, and one-shot status/location/push shell bootstrap controls, voice reliability hardening (talk controls + TTS fallback/health + interruption-safe cancel semantics), and onboarding first-success funnel improvements are implemented; remaining high-impact personal-assistant gaps center on shipped desktop/mobile companion app binaries and signed distribution pipelines.", "operator_dx_milestone": "Phase 3 (Live Ops Dashboard): 2/2 plans complete — milestone done", "dashboard_observability": "completed — service health graphs + core service log viewer added to web UI via observability RPCs and bounded backend sampling", "gmail_auth_cli": "flynn gmail-auth command implemented with OAuth2 flow, doctor check, config routed to Telegram", @@ -7051,7 +7064,7 @@ "deeper_surfaces_phase3_companion_canvas_voice": "completed — companion reconnect resilience (auto-reconnect with backoff, pending-wait cancellation on disconnect), canvas artifact persistence (SQLite-backed store, daemon-restart durability), voice TTS fallback coverage (text-only reply on TTS failure, no dropped responses)", "deeper_surfaces_phase4_rollout": "completed — phase 4 rollout and operator readiness plan documented: canary rollout plan by feature flag/surface, explicit rollback playbook, operator docs and architecture/protocol docs synchronized", "post_phase_test_fixes": "completed — fixed 4 test failures introduced by phases 1-3: iOS/Android push listNodes (missing publishHeartbeat before platform-filtered query), server.test agent.send (run_state events now precede done; added sendAndWaitForDone helper), httpBody 413 (req.destroy() closed socket before response could be sent; replaced with Connection: close header on 413 responses)", - "personal_assistant_productization_plan": "in_progress — 8-10 week phased roadmap active; Phase 3 browser workflow reliability shipped, Phase 1 companion runtime reliability includes reconnect state replay + typed handoff support, companion packaging primitives now include bootstrap manifest export, release-bundle artifact generation, and checksum manifests, companion shell bootstrap controls cover status/location/push metadata, Phase 2 voice reliability ships talk controls + TTS provider fallback/health + interruption-safe voice cancel mapping, and Phase 4 onboarding includes Personal Assistant Mode preset + live readiness checks + first-success guidance. Remaining phase focus: shipped companion app surfaces and signed release artifacts.", + "personal_assistant_productization_plan": "in_progress — 8-10 week phased roadmap active; Phase 3 browser workflow reliability shipped, Phase 1 companion runtime reliability includes reconnect state replay + typed handoff support, companion packaging primitives now include bootstrap manifest export, release-bundle artifact generation, checksum manifests, and an install/verification runbook, companion shell bootstrap controls cover status/location/push metadata, Phase 2 voice reliability ships talk controls + TTS provider fallback/health + interruption-safe voice cancel mapping, and Phase 4 onboarding includes Personal Assistant Mode preset + live readiness checks + first-success guidance. Remaining phase focus: shipped companion app surfaces and signed release artifacts.", "subagents_support": "completed — subagent phases 1-3 shipped with `subagent.spawn/send/list/cancel/delete/summary`, per-child queue mode (`followup|interrupt`), budgets (`max_turns`, `max_total_tokens`, `turn_timeout_ms`), tool-profile overrides, trace-linked audit events, `/subagents` inspection commands, and focused regression tests." }, "soul_md_and_cron_create": {