diff --git a/crdt-demo/runner.zig b/crdt-demo/runner.zig
index b975d24..6baacb9 100644
--- a/crdt-demo/runner.zig
+++ b/crdt-demo/runner.zig
@@ -1,3 +1,6 @@
+//! Demo runner. Spawns a Python HTTP server for static files and the
+//! CRDT server binary, then waits for the server to exit.
+
 const std = @import("std");
 
 pub fn main(init: std.process.Init) !void {
diff --git a/crdt-demo/src/demo.zig b/crdt-demo/src/demo.zig
index bea9a7f..347a6cd 100644
--- a/crdt-demo/src/demo.zig
+++ b/crdt-demo/src/demo.zig
@@ -1,9 +1,9 @@
-/// WASM module for collaborative text editing via RGA CRDT.
-///
-/// Exports functions callable from JavaScript for insert, remove, text
-/// readout, JSON state snapshot/merge, and memory management. Each
-/// replica gets a Handle with its own RGA and monotonic sequence
-/// counter. JS glue in www/demo.js drives a contenteditable editor.
+//! WASM module for collaborative text editing via RGA CRDT.
+//!
+//! Exports functions callable from JavaScript for insert, remove, text
+//! readout, JSON state snapshot/merge, and memory management. Each
+//! replica gets a Handle with its own RGA and monotonic sequence
+//! counter. JS glue in www/demo.js drives a contenteditable editor.
 const std = @import("std");
 const crdt = @import("crdt");
 
diff --git a/crdt-lib/src/mv_register.zig b/crdt-lib/src/mv_register.zig
index 54ab937..ab081ef 100644
--- a/crdt-lib/src/mv_register.zig
+++ b/crdt-lib/src/mv_register.zig
@@ -1,6 +1,7 @@
 //! MV-Register (multi-value register) CRDT.
-//! Retains all concurrent writes; a value is dominated if its tag
-//! is less than another in both replica and seq.
+//! Retains all concurrent writes; within the same replica only the
+//! highest seq survives, so concurrent writes from different replicas
+//! are preserved.
 
 const std = @import("std");
 const Allocator = std.mem.Allocator;
diff --git a/crdt-server/src/main.zig b/crdt-server/src/main.zig
index a6444a1..4cb769c 100644
--- a/crdt-server/src/main.zig
+++ b/crdt-server/src/main.zig
@@ -1,3 +1,6 @@
+//! CRDT server entry point. Parses CLI args, sets up the TCP listener,
+//! actor task, and I/O selector loop.
+
 const std = @import("std");
 const builtin = @import("builtin");
 const crdt_server = @import("crdt-server");
diff --git a/crdt-server/src/operation.zig b/crdt-server/src/operation.zig
index ac39afe..2651aa1 100644
--- a/crdt-server/src/operation.zig
+++ b/crdt-server/src/operation.zig
@@ -49,7 +49,8 @@ pub const SubChannel = struct {
 /// actor via the operation queue.
 pub const Operation = union(enum) {
     /// Create a new CRDT at `key` with initial `value`. The actor sets
-    /// `result_ptr` to `true` on success and fires `event` to wake the caller.
+    /// `result_ptr` to `CreateState.success` on success and fires
+    /// `event` to wake the caller.
     create: struct { key: RcStr, value: *crdt.Crdt, result_ptr: *Allocator.Error!CreateState, event: *Event },
     /// Merge `replica` into the CRDT at `key`. Idempotent — safe to replay.
     /// When `result_ptr` and `event` are provided, the actor signals `event`
diff --git a/crdt-server/src/state.zig b/crdt-server/src/state.zig
index 62d015b..942eb5e 100644
--- a/crdt-server/src/state.zig
+++ b/crdt-server/src/state.zig
@@ -1,5 +1,5 @@
 //! Shared state between HTTP handlers and the actor task.
-//! Contains the lock-free operation queue and allocator.
+//! Contains the operation queue (bounded, mutex-guarded) and allocator.
 
 const std = @import("std");
 const Operation = @import("operation.zig").Operation;