docs: add initial RVBox design and protocol contracts

2026-08-21 09:02:57 +00:00
commit 97c2d5cf45
10 changed files with 1138 additions and 0 deletions
@@ -0,0 +1,18 @@
+# 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.
+
+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.