From 2e370afe2ca4aa1ca867b3890d582fabc89c91b2 Mon Sep 17 00:00:00 2001
From: Jared Miller <jared@smell.flowers>
Date: Tue, 27 Jan 2026 16:18:48 -0500
Subject: [PATCH] Document Vim 9.0+ requirement for adapter

---
 CLAUDE.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3cb8050
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,66 @@
+# collabd - editor-agnostic collaborative editing daemon
+
+daemon + thin adapters architecture. daemon handles yjs crdt, adapters just
+hook buffer events and apply remote changes.
+
+## stack
+
+- bun runtime
+- yjs for crdt
+- websocket transport
+- vim9script adapter (with bun bridge since vim cant do websocket)
+
+## running
+
+```bash
+just dev          # daemon on :4040
+bun test          # unit tests
+just check        # biome lint
+```
+
+## vim adapter usage
+
+requires Vim 9.0+ (uses vim9script)
+
+```vim
+:source adapters/vim/collab.vim
+:CollabJoin roomname
+:CollabLeave
+:CollabStatus
+```
+
+the vim plugin spawns adapters/vim/bridge.ts which handles yjs and speaks
+json lines to vim via channels.
+
+## protocol
+
+daemon speaks json over websocket at /ws
+
+client -> server:
+  { type: "join", room: "name" }
+  { type: "leave" }
+  { type: "update", data: [...] }  // yjs update bytes
+
+server -> client:
+  { type: "sync", data: [...] }    // full yjs state on join
+  { type: "update", data: [...] }  // remote changes
+  { type: "peers", count: N }
+
+## key files
+
+- src/index.ts - websocket server, room routing
+- src/session.ts - yjs doc per room, peer management
+- src/protocol.ts - message types
+- adapters/vim/bridge.ts - bun process vim spawns
+- adapters/vim/collab.vim - vim9script plugin
+
+## adding new editor adapters
+
+each adapter needs:
+1. hook buffer change events
+2. send changes to daemon as yjs updates (or use a bridge like vim does)
+3. receive remote updates and apply to buffer
+4. optionally show peer cursors
+
+see NOTES.txt for cell-grid vs text-crdt mode discussion.
+see docs/ for full research and architecture breakdown.