# RVBox v1 design set

This design set turns the initial proposal into an implementation contract.
Read the documents in this order:

1. [Architecture](architecture.md) — scope, trust model, state machine,
   execution, storage, and retention decisions.
2. [Agent protocol](protocol.md) — WSS framing, sessions, replay, ordering,
   script transfer, heartbeat, and failure containment.
3. [Control plane](control-plane.md) — `rvc`, Unix-socket gRPC, JSON-RPC, and
   query/foreground semantics.
4. [Platform and operations](platform-and-operations.md) — Unix/Windows
   contracts, recovery, storage safety, telemetry, and defaults.
5. [Configuration contract](configuration.md) — strict TOML loading, shell
   resolution, cross-field validation, and annotated server/client examples.
6. [Go implementation plan](implementation-plan.v1.md) — phased build order,
   package boundaries, storage/session/client details, tests, and release gates.
7. [Implementation testing](testing.md) — container entry points, run
   lifecycle, exact cleanup, and coverage inventory.

The wire authority is in [`../protos/rvbox/v1`](../protos/rvbox/v1):
`common.proto` contains shared data types, `agent.proto` contains the
client/server WebSocket envelopes, and `control.proto` defines the local gRPC
service that the HTTP JSON-RPC adapter mirrors.