Migrate server to CAS only

sync-server/README.md

@@ -1,5 +1,38 @@
 # Sync server
 
+## Document pushes (API v3)
+
+The server stores immutable document versions. One compare-and-swap endpoint,
+`PUT /vaults/:vault_id/documents/:document_id`, handles every mutation. The client
+generates the document UUID; the JSON body contains:
+
+- `requestId`: a UUID identifying this exact push.
+- `parentVersionId`: `null` to create an absent document, otherwise its base version.
+- `relativePath`: the desired filename.
+- `content`: `{ "type": "Snapshot", "value": "<base64>" }`,
+  `{ "type": "Diff", "value": [3, "inserted text", -2] }`, or `{ "type": "Delete" }`.
+
+All pushes return one of:
+
+- `Accepted`: version metadata for the exact snapshot committed. A retry with the
+  same request ID returns the original acknowledgement, even after a restart or
+  subsequent updates. Clients must persist the ID with the unchanged request.
+  A payload fingerprint rejects reusing that ID for a different mutation.
+- `StaleBase`: the current version, including `contentBase64`. Nothing was written;
+  the client merges locally and submits a new push with a new request ID.
+
+The base check, path allocation, new version, and durable acknowledgement share
+one SQLite write transaction. A deleted document stays deleted; recreating a file
+uses a new document ID. Occupied paths receive an available numbered filename.
+Text updates accept reconcile-text transport diffs against the base version;
+the server only reconstructs snapshots and never merges concurrent edits.
+
+Snapshot requests use base64, adding roughly one third to the raw file size.
+Server and reverse-proxy request limits apply to the encoded JSON body.
+
+API v3 uses a fresh schema. Update clients together with the server and initialise
+new vault databases; compatibility with previous releases is not supported.
+
 ## Creating/resetting the Database for development
 
 ```sh