# Companion Runtime Client Foundation Checklist (2026-02-16)

## Scope

- Add a reusable Node/WebSocket runtime client for companion apps to call gateway node/system RPC methods without manually handling request IDs, pending maps, or error-code parsing.
- Keep API focused on current companion milestones:
  - `node.register`
  - `node.capabilities.get`
  - `node.location.set/get`
  - `node.status.set`
  - `node.push_token.set`
  - `system.capabilities`
  - `system.nodes`

## Implementation

- Added `src/companion/runtimeClient.ts`:
  - `CompanionRuntimeClient` typed wrapper around gateway JSON-RPC over `ws`.
  - `GatewayRpcError` carrying gateway error code + message.
  - Connection lifecycle (`connect`, `disconnect`, `connected`) and typed `call<T>()`.
  - Method-specific wrappers for node/system companion RPCs.
  - Token query-param support for gateway bearer auth.
- Added `src/companion/index.ts` exports for companion runtime integration.
- Added `src/companion/runtimeClient.test.ts` integration coverage against live `GatewayServer` fixture.

## Validation

- Companion runtime tests:
  - registration + capability flow
  - status/location/push updates and `system.nodes` visibility
  - RPC error mapping into `GatewayRpcError`

## Docs Updated

- `README.md` (Gateway Node Capability Negotiation section): references `src/companion/runtimeClient.ts` helper.
- `docs/api/PROTOCOL.md`: implementation reference updated with runtime client helper.
- `docs/architecture/CONTRIBUTOR_MAP.md`: repo tour now includes `src/companion/`.