feat: add minimal companion client CLI command

README.md

@@ -77,6 +77,7 @@ Flynn provides a full CLI via the `flynn` binary (or `npx tsx src/cli/index.ts`
 | `flynn gmail-auth` | Authenticate with Gmail via OAuth2 |
 | `flynn gcal-auth` | Authenticate with Google Calendar via OAuth2 |
 | `flynn skills` | List/install/manage skills |
+| `flynn companion` | Run a minimal companion node client against the gateway |
 
 `flynn setup` / `flynn onboard` now print a post-save channel verification checklist (start command, WebChat URL, `/status` smoke test, and channel-specific validation hints).
 
@@ -1330,6 +1331,10 @@ Companion runtime helper:
   - runtime observability/control passthroughs (`pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, `lastDisconnectCode`, `lastDisconnectReason`, `getPendingWorkSnapshot()`, `getEventSurfaceSnapshot()`, `getConnectionSnapshot()`, `connected`, `waitForIdle()`)
 - `src/companion/heartbeatLoop.ts` provides `CompanionHeartbeatLoop` for periodic heartbeat scheduling (`publishHeartbeat`) with start/stop safety, optional interval jitter (`jitterRatio`) to spread load (with safe normalization for invalid random samples), `tickNow()` for manual sends, success/error hooks, loop observability (`successCount`, `lastSuccessAt`, `failureCount`, `lastFailure`, `getState()`), and optional auto-stop after repeated failures.
 
+Minimal companion CLI:
+- `flynn companion --once` connects to the gateway, registers a node, publishes one heartbeat, then exits.
+- `flynn companion --platform macos --heartbeat 30` runs a long-lived node with periodic heartbeats and logs `agent.stream`/`agent.typing` events.
+
 ## WebChat PWA Push Subscriptions
 
 Enable installable WebChat PWA metadata and browser push-subscription storage on the gateway: