@cerefox/memory 0.10.3 → 0.11.0

package/dist/server-assets/db/rpcs.sql

@@ -38,6 +38,13 @@ DROP FUNCTION IF EXISTS cerefox_hybrid_search(TEXT, VECTOR(768), INT, FLOAT, BOO
 DROP FUNCTION IF EXISTS cerefox_fts_search(TEXT, INT, UUID);
 DROP FUNCTION IF EXISTS cerefox_semantic_search(VECTOR(768), INT, BOOLEAN, UUID, FLOAT);
 DROP FUNCTION IF EXISTS cerefox_reconstruct_doc(UUID);
+
+-- Iteration 32 (v0.11, optimistic concurrency): content_hash added to the return
+-- types of all document-shaped reads — the writer's concurrency token must be
+-- obtainable from every read surface. Drop the pre-change signatures first.
+DROP FUNCTION IF EXISTS cerefox_get_document(UUID, UUID);
+DROP FUNCTION IF EXISTS cerefox_search_docs(TEXT, VECTOR(768), INT, FLOAT, UUID, FLOAT, INT, INT, JSONB);
+DROP FUNCTION IF EXISTS cerefox_metadata_search(JSONB, UUID, TIMESTAMPTZ, TIMESTAMPTZ, INT, BOOLEAN, INT);
 DROP FUNCTION IF EXISTS cerefox_search_docs(TEXT, VECTOR(768), INT, FLOAT, UUID, FLOAT);
 
 -- Iteration 13: Drop pre-metadata-filter signatures so we can add p_metadata_filter JSONB.
@@ -592,7 +599,10 @@ RETURNS TABLE (
     total_chars              INT,
     doc_updated_at           TIMESTAMPTZ,
     version_count            INT,
-    is_partial               BOOL
+    is_partial               BOOL,
+    -- Optimistic-concurrency token (iter-32): the document's current
+    -- content_hash, to pass back as expected_content_hash on update.
+    content_hash             TEXT
 )
 LANGUAGE sql
 SECURITY DEFINER
@@ -625,7 +635,8 @@ AS $$
             cr.doc_project_ids,
             cr.doc_project_names,
             cr.version_count,
-            d.updated_at       AS doc_updated_at
+            d.updated_at       AS doc_updated_at,
+            d.content_hash
         FROM chunk_results cr
         JOIN cerefox_documents d ON d.id = cr.document_id
         ORDER BY cr.document_id, cr.score DESC
@@ -707,7 +718,8 @@ AS $$
         ds.total_chars,    -- always full document size, even for partial results
         td.doc_updated_at,
         td.version_count,
-        ac.is_partial
+        ac.is_partial,
+        td.content_hash
     FROM top_docs td
     JOIN doc_sizes ds ON ds.document_id = td.document_id
     JOIN all_content ac ON ac.document_id = td.document_id
@@ -832,7 +844,11 @@ RETURNS TABLE (
     full_content    TEXT,
     chunk_count     INT,
     total_chars     INT,
-    created_at      TIMESTAMPTZ
+    created_at      TIMESTAMPTZ,
+    -- Current content_hash of the document — the optimistic-concurrency token
+    -- to pass back as expected_content_hash on update (iter-32). Note: always
+    -- the CURRENT hash, even when an archived version is being retrieved.
+    content_hash    TEXT
 )
 LANGUAGE sql
 SECURITY DEFINER
@@ -853,7 +869,8 @@ AS $$
         STRING_AGG(c.content, E'\n\n' ORDER BY c.chunk_index) AS full_content,
         COUNT(*)::INT   AS chunk_count,
         SUM(c.char_count)::INT AS total_chars,
-        d.created_at
+        d.created_at,
+        d.content_hash
     FROM cerefox_documents d
     JOIN cerefox_chunks c ON c.document_id = d.id
     WHERE d.id = p_document_id
@@ -861,7 +878,7 @@ AS $$
           (p_version_id IS NULL     AND c.version_id IS NULL) OR
           (p_version_id IS NOT NULL AND c.version_id = p_version_id)
       )
-    GROUP BY d.id, d.title, d.source, d.metadata, d.created_at;
+    GROUP BY d.id, d.title, d.source, d.metadata, d.created_at, d.content_hash;
 $$;
 
 -- ── cerefox_list_document_versions ────────────────────────────────────────────
@@ -1037,11 +1054,21 @@ $$;
 --   p_source_label    : version source label for snapshot ('file','paste','agent','manual')
 --   p_retention_hours : for version cleanup (default 48)
 --   p_cleanup_enabled : whether version cleanup runs (default true)
+--   p_expected_content_hash : optimistic-concurrency token (iter-32). On the UPDATE
+--                       path this must equal the document's current content_hash —
+--                       the caller proves they based their edit on the live version.
+--                       Mismatch → CEREFOX_CONFLICT (SQLSTATE 40001). Absent (NULL)
+--                       without p_last_write_wins → CEREFOX_TOKEN_REQUIRED (22023).
+--                       Ignored on the CREATE path.
+--   p_last_write_wins : explicit opt-out of the concurrency check (filesystem-sync
+--                       flows where an external source of truth makes conflicts
+--                       meaningless). Recorded in the audit description when used.
 --
 -- Returns: document_id, chunk_count, total_chars, operation ('create' or 'update-content'),
 --          version_id (UUID of snapshot, null on create)
 
 DROP FUNCTION IF EXISTS cerefox_ingest_document(UUID, TEXT, TEXT, TEXT, TEXT, JSONB, TEXT, JSONB, TEXT, TEXT, TEXT, INT, BOOLEAN);
+DROP FUNCTION IF EXISTS cerefox_ingest_document(UUID, TEXT, TEXT, TEXT, TEXT, JSONB, TEXT, JSONB, TEXT, TEXT, TEXT, INT, BOOLEAN, TEXT, BOOLEAN);
 CREATE FUNCTION cerefox_ingest_document(
     p_document_id       UUID        DEFAULT NULL,
     p_title             TEXT        DEFAULT 'Untitled',
@@ -1055,7 +1082,9 @@ CREATE FUNCTION cerefox_ingest_document(
     p_author_type       TEXT        DEFAULT 'user',
     p_source_label      TEXT        DEFAULT 'manual',
     p_retention_hours   INT         DEFAULT 48,
-    p_cleanup_enabled   BOOLEAN     DEFAULT TRUE
+    p_cleanup_enabled   BOOLEAN     DEFAULT TRUE,
+    p_expected_content_hash TEXT    DEFAULT NULL,
+    p_last_write_wins   BOOLEAN     DEFAULT FALSE
 )
 RETURNS TABLE (
     document_id     UUID,
@@ -1075,6 +1104,7 @@ DECLARE
     v_operation     TEXT;
     v_version_id    UUID    := NULL;
     v_old_chars     INT     := 0;
+    v_current_hash  TEXT;
     v_chunk         JSONB;
     v_snap          RECORD;
     v_status        TEXT;
@@ -1114,9 +1144,38 @@ BEGIN
         v_doc_id := p_document_id;
         v_operation := 'update-content';
 
-        -- Get old size for audit
-        SELECT COALESCE(d.total_chars, 0) INTO v_old_chars
-        FROM cerefox_documents d WHERE d.id = v_doc_id;
+        -- Lock the row and read its current state. FOR UPDATE makes the
+        -- concurrency check below atomic with the write: two simultaneous
+        -- updaters serialize here, and the second one sees the first one's
+        -- hash — the race window (chunk + embed latency) is closed at the
+        -- only place all transports share (iter-32).
+        SELECT COALESCE(d.total_chars, 0), d.content_hash
+        INTO v_old_chars, v_current_hash
+        FROM cerefox_documents d WHERE d.id = v_doc_id
+        FOR UPDATE;
+
+        IF NOT FOUND THEN
+            RAISE EXCEPTION 'cerefox_ingest_document: document not found: %', v_doc_id
+                USING ERRCODE = '22023';  -- invalid_parameter_value
+        END IF;
+
+        -- ── Optimistic concurrency check (iter-32) ───────────────────
+        -- Content updates must prove freshness (expected hash) or explicitly
+        -- choose last-write-wins. Message prefixes are machine-detectable:
+        -- transport handlers map them to agent-first retry instructions.
+        IF NOT p_last_write_wins THEN
+            IF p_expected_content_hash IS NULL THEN
+                RAISE EXCEPTION
+                    'CEREFOX_TOKEN_REQUIRED: content updates require expected_content_hash (the content_hash you read) or last_write_wins=true. Current hash: %',
+                    v_current_hash
+                    USING ERRCODE = '22023';  -- invalid_parameter_value
+            ELSIF p_expected_content_hash <> v_current_hash THEN
+                RAISE EXCEPTION
+                    'CEREFOX_CONFLICT: document % changed since it was read (expected hash %, current hash %). Re-read the document, merge your changes, and retry with the new hash.',
+                    v_doc_id, p_expected_content_hash, v_current_hash
+                    USING ERRCODE = '40001';  -- serialization_failure
+            END IF;
+        END IF;
 
         -- Snapshot old version (archives current chunks, runs retention cleanup)
         SELECT sv.version_id INTO v_version_id
@@ -1183,6 +1242,8 @@ BEGIN
         p_size_before := CASE WHEN v_operation = 'create' THEN NULL ELSE v_old_chars END,
         p_size_after := v_total_chars,
         p_description := v_operation || ': ' || p_title || ' (' || v_chunk_count || ' chunks, ' || v_total_chars || ' chars)'
+            || CASE WHEN p_last_write_wins AND v_operation = 'update-content'
+                    THEN ' [last-write-wins]' ELSE '' END
     );
 
     RETURN QUERY SELECT v_doc_id, v_chunk_count, v_total_chars, v_operation, v_version_id;
@@ -1407,6 +1468,9 @@ RETURNS TABLE (
     project_ids     UUID[],
     project_names   TEXT[],
     version_count   INT,
+    -- Optimistic-concurrency token (iter-32): pass back as
+    -- expected_content_hash on update.
+    content_hash    TEXT,
     content         TEXT
 )
 LANGUAGE plpgsql
@@ -1436,6 +1500,7 @@ BEGIN
                   WHERE dp.document_id = d.id) AS project_names,
             (SELECT COUNT(*)::INT FROM cerefox_document_versions dv
              WHERE dv.document_id = d.id) AS version_count,
+            d.content_hash,
             CASE WHEN p_include_content THEN
                 (SELECT STRING_AGG(c.content, E'\n\n' ORDER BY c.chunk_index)
                  FROM cerefox_chunks c
@@ -1474,6 +1539,7 @@ BEGIN
         project_ids   := v_row.project_ids;
         project_names := v_row.project_names;
         version_count := v_row.version_count;
+        content_hash  := v_row.content_hash;
         content       := v_row.content;
         RETURN NEXT;
     END LOOP;
@@ -1694,7 +1760,7 @@ SET search_path = public, pg_catalog
 AS $$
     -- Keep in lockstep with the `@version:` marker in schema.sql (cut_release.ts
     -- enforces it). Bump whenever schema.sql OR rpcs.sql changes.
-    SELECT '0.4.0'::TEXT;
+    SELECT '0.5.0'::TEXT;
 $$;
 
 

package/dist/server-assets/db/schema.sql

@@ -5,7 +5,7 @@
 -- Requires extensions: vector (pgvector), uuid-ossp
 -- These are enabled at the top of db_deploy.py before this file is applied.
 --
--- @version: 0.4.0
+-- @version: 0.5.0
 -- The `@version` marker above is read by the schema-version-mismatch banner
 -- (see /api/v1/schema-version). Bump it whenever schema.sql OR rpcs.sql
 -- changes in a way that requires `cerefox server deploy` to be re-run —

package/dist/server-assets/supabase/functions/cerefox-get-document/index.ts

@@ -17,7 +17,7 @@ import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/inde
  *   { document_id: string, version_id?: string | null }
  *
  * Response (200):
- *   { document_id, doc_title, full_content, chunk_count, total_chars, is_archived, version_id }
+ *   { document_id, doc_title, full_content, chunk_count, total_chars, is_archived, version_id, content_hash }
  * Response (404):
  *   { error: "Document not found" }
  * Response (400):
@@ -98,6 +98,7 @@ Deno.serve(async (req: Request): Promise<Response> => {
       full_content?: string;
       chunk_count?: number;
       total_chars?: number;
+      content_hash?: string;
     } | undefined;
 
     if (!row) {
@@ -125,6 +126,9 @@ Deno.serve(async (req: Request): Promise<Response> => {
         total_chars: row.total_chars ?? 0,
         is_archived: version_id !== null,
         version_id,
+        // Optimistic-concurrency token (iter-32): always the CURRENT hash —
+        // pass back as expected_content_hash when updating via ingest.
+        content_hash: row.content_hash ?? null,
       }),
       { status: 200, headers: { ...CORS_HEADERS, "Content-Type": "application/json" } },
     );

package/dist/server-assets/supabase/functions/cerefox-ingest/index.ts

@@ -40,6 +40,42 @@ interface IngestRequest {
   update_if_exists?: boolean;
   author?: string;
   author_type?: string; // 'user' | 'agent'
+  // Optimistic concurrency (iter-32): REQUIRED on content updates — the
+  // content_hash of the version this edit was based on. Conflict → HTTP 409.
+  expected_content_hash?: string;
+  // Explicitly skip the concurrency check (external source of truth).
+  last_write_wins?: boolean;
+}
+
+// Map the RPC's CEREFOX_CONFLICT / CEREFOX_TOKEN_REQUIRED errors to HTTP
+// responses (409 conflict / 400 missing token). Returns null for other errors.
+function concurrencyErrorResponse(
+  message: string,
+  headers: Record<string, string>,
+): Response | null {
+  if (message.includes("CEREFOX_CONFLICT")) {
+    return new Response(
+      JSON.stringify({
+        error: "conflict",
+        message:
+          "Document changed since it was read. Re-read it (getDocument), merge your changes, and retry with the new expected_content_hash.",
+        detail: message,
+      }),
+      { status: 409, headers },
+    );
+  }
+  if (message.includes("CEREFOX_TOKEN_REQUIRED")) {
+    return new Response(
+      JSON.stringify({
+        error: "expected_content_hash required",
+        message:
+          "Content updates require expected_content_hash (the content_hash returned by getDocument / searchKnowledgeBase / metadataSearch) or last_write_wins=true.",
+        detail: message,
+      }),
+      { status: 400, headers },
+    );
+  }
+  return null;
 }
 
 interface Chunk {
@@ -428,7 +464,7 @@ Deno.serve(async (req: Request) => {
     });
   }
 
-  const { title, content, document_id = null, project_name, source = "agent", metadata = {}, update_if_exists = false, author = "agent", author_type = "agent" } = body;
+  const { title, content, document_id = null, project_name, source = "agent", metadata = {}, update_if_exists = false, author = "agent", author_type = "agent", expected_content_hash = null, last_write_wins = false } = body;
 
   // Validate + normalize project_names if provided (full-set destructive form)
   let project_names: string[] | null = null;
@@ -525,6 +561,16 @@ Deno.serve(async (req: Request) => {
       );
     }
 
+    // Optimistic-concurrency fast-fail (iter-32): stale token fails BEFORE
+    // the embedding spend. Advisory only — the authoritative race-free check
+    // is inside the RPC (SELECT … FOR UPDATE).
+    if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
+      return concurrencyErrorResponse(
+        `CEREFOX_CONFLICT: document ${existingDoc.id} changed since it was read (expected hash ${expected_content_hash}, current hash ${existingDoc.content_hash}).`,
+        headers,
+      )!;
+    }
+
     // Content changed -- re-chunk, re-embed, ingest via RPC
     const chunks = chunkMarkdown(content);
     if (chunks.length === 0) {
@@ -562,9 +608,13 @@ Deno.serve(async (req: Request) => {
       p_author: author,
       p_author_type: author_type,
       p_source_label: source,
+      p_expected_content_hash: expected_content_hash,
+      p_last_write_wins: last_write_wins,
     });
 
     if (ingestErr) {
+      const mapped = concurrencyErrorResponse(ingestErr.message ?? "", headers);
+      if (mapped) return mapped;
       return new Response(JSON.stringify({ error: `Ingest RPC failed: ${ingestErr.message}` }), { status: 500, headers });
     }
 
@@ -593,6 +643,7 @@ Deno.serve(async (req: Request) => {
         chunk_count: chunks.length,
         total_chars: totalChars,
         updated: true,
+        content_hash: contentHash,
         ...(note && { note }),
       }),
       { headers },
@@ -625,6 +676,14 @@ Deno.serve(async (req: Request) => {
         );
       }
 
+      // Optimistic-concurrency fast-fail (iter-32) — see ID-based path.
+      if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
+        return concurrencyErrorResponse(
+          `CEREFOX_CONFLICT: document ${existingDoc.id} changed since it was read (expected hash ${expected_content_hash}, current hash ${existingDoc.content_hash}).`,
+          headers,
+        )!;
+      }
+
       // Content changed — re-chunk, re-embed, ingest via RPC
       const chunks = chunkMarkdown(content);
       if (chunks.length === 0) {
@@ -667,9 +726,13 @@ Deno.serve(async (req: Request) => {
         p_author: author,
         p_author_type: author_type,
         p_source_label: source,
+        p_expected_content_hash: expected_content_hash,
+        p_last_write_wins: last_write_wins,
       });
 
       if (ingestErr) {
+        const mapped = concurrencyErrorResponse(ingestErr.message ?? "", headers);
+        if (mapped) return mapped;
         return new Response(
           JSON.stringify({ error: `Ingest RPC failed: ${ingestErr.message}` }),
           { status: 500, headers },
@@ -701,6 +764,7 @@ Deno.serve(async (req: Request) => {
           chunk_count: chunks.length,
           total_chars: totalChars,
           updated: true,
+          content_hash: contentHash,
         }),
         { headers },
       );

package/dist/server-assets/supabase/functions/cerefox-metadata-search/index.ts

@@ -15,8 +15,11 @@ import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/inde
  * Note: cerefox-mcp calls the RPC directly (not this Edge Function).
  *
  * Request body (JSON):
- *   metadata_filter  object       required  Key-value pairs (AND semantics)
+ *   metadata_filter  object       optional  Key-value pairs (AND semantics)
  *   project_id       string       optional  Project UUID filter
+ *
+ * At least one of metadata_filter / project_id / updated_since / created_since
+ * must be supplied (an empty filter + project_id lists that project's docs).
  *   updated_since    string       optional  ISO-8601 lower bound for updated_at
  *   created_since    string       optional  ISO-8601 lower bound for created_at
  *   limit            number       optional  Max results (default: 10)
@@ -53,13 +56,12 @@ Deno.serve(async (req: Request): Promise<Response> => {
     const metadata_filter = body.metadata_filter;
 
     if (
-      !metadata_filter ||
-      typeof metadata_filter !== "object" ||
-      Array.isArray(metadata_filter) ||
-      Object.keys(metadata_filter).length === 0
+      metadata_filter !== undefined &&
+      metadata_filter !== null &&
+      (typeof metadata_filter !== "object" || Array.isArray(metadata_filter))
     ) {
       return new Response(
-        JSON.stringify({ error: "metadata_filter is required and must be a non-empty JSON object" }),
+        JSON.stringify({ error: "metadata_filter must be a JSON object when provided" }),
         { status: 400, headers: { ...CORS_HEADERS, "Content-Type": "application/json" } },
       );
     }
@@ -67,6 +69,22 @@ Deno.serve(async (req: Request): Promise<Response> => {
     const project_id = body.project_id ?? null;
     const updated_since = body.updated_since ?? null;
     const created_since = body.created_since ?? null;
+
+    // metadata_filter is optional, but at least one narrowing criterion is
+    // required so this never becomes an unbounded whole-KB dump. An empty
+    // filter + project_id lists a project's documents (the RPC's
+    // `metadata @> '{}'` matches every row; the project predicate narrows it).
+    const has_metadata =
+      metadata_filter && typeof metadata_filter === "object" &&
+      Object.keys(metadata_filter).length > 0;
+    if (!has_metadata && !project_id && !updated_since && !created_since) {
+      return new Response(
+        JSON.stringify({
+          error: "Provide at least one of: metadata_filter, project_id, updated_since, or created_since.",
+        }),
+        { status: 400, headers: { ...CORS_HEADERS, "Content-Type": "application/json" } },
+      );
+    }
     const limit = body.limit ?? 10;
     const include_content = body.include_content ?? false;
     const requested_max_bytes = body.max_bytes;
@@ -102,7 +120,7 @@ Deno.serve(async (req: Request): Promise<Response> => {
     }
 
     const params: Record<string, unknown> = {
-      p_metadata_filter: metadata_filter,
+      p_metadata_filter: has_metadata ? metadata_filter : {},
       p_project_id: project_id,
       p_updated_since: updated_since,
       p_created_since: created_since,

package/docs/guides/access-paths.md

@@ -209,7 +209,7 @@ paths.
 | Tier | Operations | Reversible? | Where exposed |
 |---|---|---|---|
 | 1. Reads + soft mutations | search, get, list-*, ingest (create/update), metadata-search, get-audit-log | n/a (reads) / yes (versioned) | All paths — MCP, Edge Functions, CLI, web UI |
-| 2. Soft-destructive | `delete_document` (soft delete to trash), `set_review_status` | yes — restorable via web UI | All paths (CLI: `cerefox document delete`; web UI; Python; **not** MCP or Edge Functions today) |
+| 2. Soft-destructive | `delete_document` (soft delete to trash), `set_review_status` | yes — restorable via web UI | All paths (CLI: `cerefox document delete`; web UI; **not** MCP or Edge Functions today) |
 | 3. **Hard-destructive** | `purge_document` (permanent), `restore_document` (un-trash), `set_version_archived` (toggle version retention) | no (purge) / yes (restore, but recovers from a destructive action) | **Web UI only** |
 
 ### Why purge / restore are web-UI-only

package/docs/guides/agent-coordination.md

@@ -33,6 +33,19 @@ The coordination model is **asynchronous and knowledge-based**:
 
 This is not real-time orchestration. It is persistent, searchable shared memory.
 
+### Concurrent writers are conflict-guarded (v0.11+)
+
+Shared memory means two agents can hold the same document at once. Cerefox
+protects content updates with **optimistic concurrency control**: every read
+surface returns the document's `content_hash`, and a content update must pass
+it back as `expected_content_hash`. If the document changed in between, the
+write fails with a **conflict** instead of silently overwriting the other
+writer's work — the losing agent re-reads, merges, and retries with the fresh
+hash. (Versioning remains the recovery net; the conflict guard is the
+prevention layer.) An explicit `last_write_wins: true` exists for re-sync flows
+where an external source of truth makes conflicts meaningless — agents should
+never use it to silence a conflict. See `AGENT_GUIDE.md → Concurrent writers`.
+
 ---
 
 ## Coordination Patterns
@@ -53,7 +66,7 @@ A living document where agents record decisions, experiment outcomes, and lesson
 
 **Example**: A coding agent working on a project records "Chose PostgreSQL RPC approach over application-level logic because..." in a decision log document. Next week, a different agent working on a related feature searches Cerefox, finds the decision log, and understands the rationale without re-deriving it.
 
-**How it works**: Create a document with a structured format (date, context, decision, outcome). Use a consistent title or project tag so agents can find it. Use `update_if_exists: true` to append new entries.
+**How it works**: Create a document with a structured format (date, context, decision, outcome). Use a consistent title or project tag so agents can find it. To add entries over time, re-ingest with `update_if_exists: true` (or `document_id`) — this replaces the document in place, so build the new full content by appending to the prior content you fetched, and pass the `content_hash` you fetched as `expected_content_hash` (two agents appending entries concurrently is exactly the conflict the guard catches).
 
 **Best for**: Project-level institutional memory, avoiding repeated decisions, onboarding new agent sessions.
 

package/docs/guides/cli.md

@@ -46,6 +46,8 @@ cerefox document ingest --paste --title "<title>" [OPTIONS]   # stdin
 | `--metadata` | `-m` | JSON | `{}` | Extra metadata as a JSON object, e.g. `'{"tags":["work"]}'`. |
 | `--update-if-exists` | `-u` | flag | off | Title/source-path-based fallback update. Mutually exclusive with `--document-id`. |
 | `--document-id` | `-i` | UUID | _none_ | Deterministic ID-based update. Errors if the document doesn't exist. |
+| `--expected-content-hash` | — | sha256 | _none_ | **Required on content updates** (v0.11 optimistic concurrency): the `content_hash` of the version this edit is based on, shown by `cerefox document get` / `cerefox search`. Stale → conflict error (re-read, merge, retry). |
+| `--last-write-wins` | — | flag | off | Skip the concurrency check and overwrite regardless of concurrent changes. For re-sync flows where an external source of truth makes conflicts meaningless. Recorded in the audit log. |
 | `--source` | — | str | `paste` / `file` | Source label recorded on the document. |
 | `--author` | — | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Audit-log author identity. |
 | `--author-type` | — | `user`\|`agent` | `CEREFOX_AUTHOR_TYPE` or `user` | Caller type. Agent writes auto-routed to `pending_review`. |
@@ -63,12 +65,19 @@ cerefox document ingest notes.md \
   --author "claude-code" --author-type "agent" \
   --project-name "research" --metadata '{"type":"design-doc"}'
 
-# Deterministic update (preferred — agents should search → grab ID → ingest)
+# Deterministic update (preferred — agents should search → grab ID + hash → ingest)
 cerefox document ingest --paste --title "Same Title" \
   --document-id "abc12345-..." \
+  --expected-content-hash "<hash from `document get`>" \
   --author "claude-code" --author-type "agent"
 ```
 
+> **Concurrency (v0.11+)**: content updates require `--expected-content-hash`
+> (or an explicit `--last-write-wins`). On a conflict, re-run
+> `cerefox document get <id>`, merge your changes into the latest content, and
+> retry with the new hash. `document ingest-dir` and `guides ingest` bypass the
+> check internally (the filesystem / npm package is their source of truth).
+
 **Output**: human-readable summary line(s) — "Ingested" or "Updated" with the document ID, chunk count, character count.
 
 **Exit codes**: `0` success, `1` on validation error (missing `--title`, invalid JSON, document-not-found, mutually-exclusive flags, etc.).
@@ -183,7 +192,7 @@ cerefox document get abc12345-... --version-id <version-uuid>     # archived
 cerefox document get abc12345-... | bat -l md                  # pipe to viewer
 ```
 
-**Output**: title + metadata line, blank line, then raw markdown.
+**Output**: title + metadata line + `content_hash` line (the optimistic-concurrency token — pass back via `document ingest --expected-content-hash` when updating), blank line, then raw markdown.
 
 **MCP equivalent**: [`cerefox_get_document`](../../AGENT_GUIDE.md).
 
@@ -207,7 +216,9 @@ cerefox document list [OPTIONS]
 | `--deleted` | flag | off | List soft-deleted (trashed) documents instead of active ones, newest-deleted first. Pair the ids with `cerefox document restore` / `cerefox document delete`. |
 | `--json` | flag | off | Machine-readable JSON output. |
 
-**Output**: tabular `id | title | source | status | updated_at` listing (or `deleted_at` with `--deleted`). CLI-only — there is no MCP equivalent.
+**Output**: tabular `id | title | source | status | updated_at` listing (or `deleted_at` with `--deleted`).
+
+**MCP equivalent**: scope-by-project / metadata / time listing maps to [`cerefox_metadata_search`](../../AGENT_GUIDE.md) — e.g. `cerefox_metadata_search(project_name="research")` lists that project's documents (the `metadata_filter` may be empty when another scope is supplied). The `--deleted` (trash) view and unscoped whole-KB listing remain CLI-only.
 
 ---
 
@@ -240,6 +251,43 @@ cerefox document edit <doc-id> --set-meta status=archived --unset-meta draft
 
 ---
 
+### `cerefox document set-projects`
+
+**Purpose**: replace a document's project memberships with **exactly** the given set (full-set replace — any project not listed is removed). This is the CLI equivalent of the `cerefox_set_document_projects` MCP tool; both share one membership-replace core, so they behave identically. Content is untouched; the change is logged as an `update-metadata` audit entry.
+
+**Synopsis**:
+```
+cerefox document set-projects [OPTIONS] DOCUMENT_ID [PROJECT_NAMES...]
+```
+
+**Options**:
+
+| Flag | Type | Default | Description |
+|---|---|---|---|
+| `[project-names...]` | variadic args | _none_ | One or more project names. Each is created if missing; order preserved; case-insensitively de-duplicated. |
+| `--clear` | flag | off | Remove the document from **all** projects. Mutually exclusive with passing names. |
+| `--author <name>` (`-a`) | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Identity recorded in the audit log. |
+| `--author-type <type>` | `user`\|`agent` | `user` | Caller type recorded in the audit log. |
+
+To set memberships **and** update content in one shot, use `cerefox document ingest --document-id <id> --project-name …` instead. Use this command when you only need to change membership.
+
+**Examples**:
+```bash
+# Set the document to belong to exactly these two projects (replaces any others)
+cerefox document set-projects <doc-id> research archive
+
+# Remove the document from all projects
+cerefox document set-projects <doc-id> --clear
+```
+
+**Output**: a confirmation line with the document title and the resulting project set (or a "cleared all memberships" line), plus a reminder that the previous set was replaced.
+
+**Exit codes**: `0` on success; `1` on validation error (no names and no `--clear`, or both) or if the document is missing / soft-deleted.
+
+**MCP equivalent**: [`cerefox_set_document_projects`](../../AGENT_GUIDE.md).
+
+---
+
 ### `cerefox document restore`
 
 **Purpose**: restore a soft-deleted (trashed) document back to active.
@@ -594,15 +642,64 @@ Every MCP parameter has an exact-name CLI flag (kebab-cased). Short forms exist
 | MCP tool | CLI command |
 |---|---|
 | `cerefox_search(query, match_count, project_name, metadata_filter, requestor)` | `cerefox search "<q>" --match-count N --project-name <name> --metadata-filter '<json>' --requestor <name>` |
-| `cerefox_ingest(title, content, project_name, metadata, update_if_exists, document_id, source, author, author_type)` (file) | `cerefox document ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --source <s> --author <a> --author-type <t>` |
+| `cerefox_ingest(title, content, project_name, metadata, update_if_exists, document_id, expected_content_hash, last_write_wins, source, author, author_type)` (file) | `cerefox document ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --expected-content-hash <hash>\|--last-write-wins --source <s> --author <a> --author-type <t>` |
 | `cerefox_ingest(...)` (paste) | `printf '...' \| cerefox document ingest --paste --title "<t>"` (same flags) |
 | `cerefox_get_document(document_id, version_id, requestor)` | `cerefox document get <id> --version-id <vid> --requestor <name>` |
 | `cerefox_list_versions(document_id, requestor)` | `cerefox document version list <id> --requestor <name>` |
 | `cerefox_list_projects(requestor)` | `cerefox project list --requestor <name>` |
+| `cerefox_set_document_projects(document_id, project_names, author)` | `cerefox document set-projects <id> <name...> --author <a> --author-type <t>` (or `--clear` to remove all) |
 | `cerefox_list_metadata_keys()` | `cerefox metadata keys` |
 | `cerefox_metadata_search(metadata_filter, project_name, updated_since, created_since, limit, include_content, requestor)` | `cerefox metadata search --metadata-filter '<json>' --project-name <n> --updated-since <iso> --created-since <iso> --limit N --include-content --requestor <name>` |
 | `cerefox_get_audit_log(document_id, author, operation, since, until, limit, requestor)` | `cerefox audit list --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --requestor <name>` |
 
+## CLI ↔ MCP parity matrix
+
+The table above is MCP-first (it lists the tools that *have* a CLI form). This
+one is **CLI-first** — every `cerefox` command, with its MCP equivalent or an
+explicit reason it has none. It exists to make parity gaps visible. Legend:
+**✅ mapped** · **⚠️ gap** (a capability one surface has and the other lacks,
+arguably worth closing) · **🔒 intentional** (deliberately not on the MCP/agent
+surface).
+
+| CLI command | MCP equivalent | Status |
+|---|---|---|
+| `document ingest` | `cerefox_ingest` | ✅ |
+| `document ingest-dir` | — (agents loop `cerefox_ingest`) | 🔒 bulk filesystem walk; no server-side dir access from MCP |
+| `search` | `cerefox_search` | ✅ (CLI adds `--mode`/`--alpha`/`--min-score`/`--only-metadata`) |
+| `document get` | `cerefox_get_document` | ✅ |
+| `document list` | `cerefox_metadata_search` (scope by `project_name` / metadata / time) | ✅ as of this change. Unscoped whole-KB listing has no MCP path by design (scope it) |
+| `document edit` (title / metadata in place) | — | 🔒 intentional: a human/web-parity convenience. Agents update title+metadata deterministically via `cerefox_ingest` (with `document_id`); a metadata-only edit isn't a needed agent primitive |
+| `document delete` (soft-delete) | — | 🔒 destructive; trust model keeps delete/restore on CLI + web only |
+| `document restore` | — | 🔒 trust model (CLI + web only) |
+| `document version list` | `cerefox_list_versions` | ✅ |
+| `document version archive` / `unarchive` | — | 🔒 intentional: version-retention protection is exposed only to CLI + web (a maintenance concern, not an agent primitive) |
+| `document set-projects` | `cerefox_set_document_projects` | ✅ full-set replace of a document's project memberships (shared core; `--clear` to remove all) |
+| `project list` | `cerefox_list_projects` | ✅ |
+| `project create` / `edit` / `delete` | — | 🔒 project mutations CLI + web only |
+| `metadata keys` | `cerefox_list_metadata_keys` | ✅ |
+| `metadata search` | `cerefox_metadata_search` | ✅ |
+| `audit list` | `cerefox_get_audit_log` | ✅ |
+| `guides list` / `show` / `open` / `ingest` | `cerefox_get_help` (partial) | ✅~ `get_help` returns the bundled quick-reference; `guides` is the richer CLI form |
+| `server deploy` / `server reindex` | — | 🔒 operator/deploy surface |
+| `config list` / `get` / `set` | — | 🔒 runtime config; operator surface |
+| `web` / `mcp` | — | 🔒 lifecycle (`mcp` *is* the MCP server) |
+| `init` / `doctor` / `status` / `configure-agent` / `self-update` / `completion` / `backup *` | — | 🔒 install / health / ops |
+
+**Gap status** (the 🔒 rows are deliberate and out of scope):
+
+1. `document list` → **closed**: project/metadata/time-scoped listing now routes
+   through `cerefox_metadata_search` (it accepts an empty `metadata_filter` when
+   another scope is supplied).
+2. `cerefox_set_document_projects` → **closed**: added `cerefox document
+   set-projects` (full-set replace, `--clear` to remove all), sharing the
+   membership-replace core with the MCP tool.
+3. `document edit` (metadata/title-only edit) → **intentional non-gap**: a
+   human/web-parity convenience; agents use `cerefox_ingest` for content+metadata
+   updates. Revisit only if a concrete agent workflow needs metadata-only edits.
+4. `document version archive` / `unarchive` → **intentional non-gap**: version-retention
+   protection is exposed only to CLI + web (a maintenance concern, deliberately not on
+   the MCP/agent surface).
+
 ## Known issues
 
 None outstanding as of v0.1.17 (cerefox#27 — the `cerefox search` NameError — is resolved). When new bugs surface, they are tracked in the GitHub issues list; check there before relying on a behaviour the docs imply.
@@ -621,12 +718,18 @@ cerefox document ingest-dir ./papers --extensions .md \
 # Step 1: find it
 cerefox search "the OAuth design doc" --match-count 1
 
-# Step 2: copy the id from `Doc: ... (id: <uuid>)` line
-# Step 3: update in place
+# Step 2: read it — note the id AND the `content_hash:` line (the concurrency token)
+cerefox document get "<uuid>"
+
+# Step 3: update in place, proving freshness with the hash from step 2
 printf '%s' "$NEW_CONTENT" | cerefox document ingest --paste \
   --title "OAuth 2.1 Design Document" \
   --document-id "<uuid>" \
+  --expected-content-hash "<hash>" \
   --author "claude-code" --author-type "agent"
+
+# On a conflict error: repeat from step 2 (fresh content + fresh hash),
+# merge your changes into the latest content, then retry.
 ```
 
 ### Unattended sync job