docs(worker-sync): add guide and protocol

AGENTS.md

@@ -32,4 +32,5 @@
 
 ## Agent-Specific Notes
 - Review notes live in `@prompts/review.md`; check them when preparing changes.
-- Worker-sync feature guide for AI agents: `docs/agent-guide/worker-sync.md`.
+- Worker-sync feature guide for AI agents: `docs/agent-guide/worker-sync/worker-sync-guide.md`.
+- Worker-sync protocol reference: `docs/agent-guide/worker-sync/protocol.md`.

docs/agent-guide/worker-sync/protocol.md

@@ -0,0 +1,37 @@
+# Worker-Sync Client-Server Protocol
+
+## Transport
+- WebSocket `ws(s)` to `/sync/:graph-id`.
+- Client builds URL from config and appends `?token=...` when available.
+- Encoding: JSON objects; `tx` payloads are Transit strings.
+- Note: keep this document in sync with the current implementation.
+
+## Client -> Server
+- `{"type":"hello","client":"<repo-id>"}`
+  - Initial handshake from client.
+- `{"type":"pull","since":<t>}`
+  - Request txs after `since` (defaults to 0).
+- `{"type":"tx/batch","t_before":<t>,"txs":["<tx-transit>", ...]}`
+  - Upload a batch of txs based on `t_before`.
+- `{"type":"ping"}`
+  - Optional keepalive; server replies `pong`.
+
+## Server -> Client
+- `{"type":"hello","t":<t>}`
+  - Server hello with current t.
+- `{"type":"pull/ok","t":<t>,"txs":[{"t":<t>,"tx":"<tx-transit>"}...]}`
+  - Pull response with txs.
+- `{"type":"tx/batch/ok","t":<t>}`
+  - Batch accepted; server advanced to t.
+- `{"type":"changed","t":<t>}`
+  - Broadcast that server state advanced; client should pull.
+- `{"type":"tx/reject","reason":"stale","t":<t>}`
+  - Client tx is based on stale t.
+- `{"type":"tx/reject","reason":"cycle","data":"<transit {:attr <kw> :server_values ...}>"}`
+  - Cycle detected with server values.
+- `{"type":"tx/reject","reason":"empty tx data"|"invalid tx"}`
+  - Invalid batch.
+- `{"type":"pong"}`
+  - Keepalive response.
+- `{"type":"error","message":"..."}`
+  - Invalid/unknown message.

docs/agent-guide/worker-sync.md → docs/agent-guide/worker-sync/worker-sync-guide.md

@@ -22,6 +22,25 @@ This guide helps AI agents implement and review worker-sync features consistentl
 - Use existing `:worker-sync/*` keywords; add new keywords via `logseq.common.defkeywords/defkeyword`.
 - When adding persisted fields, ensure any migration or index logic is updated on both client and worker.
 
+## Client-Server Message Protocol (WebSocket)
+- Transport: WebSocket `ws(s)` to `/sync/:graph-id` (client builds URL from config and appends `?token=...` when available).
+- Encoding: JSON objects; `tx` payloads are Transit strings.
+- Client -> Server:
+  - `{"type":"hello","client":"<repo-id>"}`: initial hello; server responds with `t`.
+  - `{"type":"pull","since":<t>}`: request txs after `since` (defaults to 0).
+  - `{"type":"tx/batch","t_before":<t>,"txs":["<tx-transit>", ...]}`: upload batch.
+  - `{"type":"ping"}`: optional keepalive; server replies `pong`.
+- Server -> Client:
+  - `{"type":"hello","t":<t>}`: server hello with current t.
+  - `{"type":"pull/ok","t":<t>,"txs":[{"t":<t>,"tx":"<tx-transit>"}...]}`: pull response.
+  - `{"type":"tx/batch/ok","t":<t>}`: batch accepted.
+  - `{"type":"changed","t":<t>}`: broadcast that server state advanced; client should `pull`.
+  - `{"type":"tx/reject","reason":"stale","t":<t>}`: client tx based on stale t.
+  - `{"type":"tx/reject","reason":"cycle","data":"<transit {:attr <kw> :server_values ...}>"}`: cycle detected with server values.
+  - `{"type":"tx/reject","reason":"empty tx data"|"invalid tx"}`: invalid batch.
+  - `{"type":"pong"}`: keepalive response.
+  - `{"type":"error","message":"..."}`: invalid/unknown message.
+
 ## Testing & Verification
 - Local dev(client+server): `bb dev:worker-sync-start` runs the worker-sync watcher, `wrangler dev`, and `yarn watch` with `ENABLE_WORKER_SYNC_LOCAL=true`
 - Unit tests: `bb dev:lint-and-test`