1 files changed, 55 insertions, 0 deletions

diff --git a/docs/adr/0002-version-lockstep.md b/docs/adr/0002-version-lockstep.md
new file mode 100644
index 0000000..1e7f8ba
--- /dev/null
+++ b/docs/adr/0002-version-lockstep.md
@@ -0,0 +1,55 @@
+# 0002 — Client and server must share MAJOR.MINOR
+
+Status: accepted, 2026-11-01
+
+## Context
+
+`AGENTS.md` previously described MINOR as backwards compatible: an old client
+should work with a newer server and vice versa. In practice the wire format,
+game messages, and client flows have changed in every MINOR so far
+(`PLAY_START` payloads, `CRASH_*`, `HISTORY`, cursor and bet semantics). Silent
+half-compatibility produces confusing failures: a new client sends a command
+the old server echoes back as text, or an old client misparses a new field.
+
+The project now ships multiple frontends (TUI and GUI) and a server, all
+released together from one repository.
+
+## Decision
+
+1. **Version compatibility is MAJOR.MINOR lockstep.** A client and server may
+   differ only in PATCH. Any difference in MAJOR or MINOR refuses the
+   connection.
+2. **The first line after the TLS handshake is `HELLO <version>`.** The server
+   replies with its own version, the latest release version, and the download
+   URL. Any other message before `HELLO` is rejected. No credentials are sent
+   before the versions agree.
+3. **The server is authoritative about the latest release.** It advertises
+   `latest` and the download URL in the handshake; the client compares its own
+   `CARGO_PKG_VERSION` and offers a link when it is behind. The download site
+   is not queried by clients: that would add a second TLS stack and a web PKI
+   trust domain for one string.
+4. **A MAJOR bump covers a wire change; a MINOR bump covers a feature that
+   changes the protocol or the shared semantics.** Both require releasing
+   clients and server together.
+
+## Consequences
+
+- Every MINOR release must update the server and all clients simultaneously;
+  a stale server is a hard failure, not a degraded experience. Deployment order
+  matters.
+- `AGENTS.md`'s MINOR rule is rewritten; the old "old clients work with new
+  servers" promise is withdrawn.
+- The handshake is itself a breaking wire change: this lands as v4.0.0.
+- The update check needs no extra dependency and works for both frontends, at
+  the cost of only being as fresh as the server you connect to.
+
+## Alternatives considered
+
+- **Keep MINOR backwards compatible** and negotiate per-feature: more work,
+  and every feature so far would have needed a capability flag. Rejected.
+- **Fetch `version.json` from the download site**: site-authoritative updates,
+  but adds an HTTP client and a CA trust store with different rules from the
+  pinned game server. Rejected.
+- **Semver-range matching**: allows broader compatibility but makes the
+  failure modes depend on which optional features each side implemented.
+  Rejected for a small, tightly released product.