npm - @cerefox/memory - Versions diffs - 0.10.4 → 0.11.1 - Mend

@cerefox/memory 0.10.4 → 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/AGENT_GUIDE.md +38 -15
package/AGENT_QUICK_REFERENCE.md +13 -8
package/dist/bin/cerefox.js +189 -69
package/dist/frontend/assets/{index-DVXDQ7__.js → index-ojNhWSxm.js} +3 -3
package/dist/frontend/assets/index-ojNhWSxm.js.map +1 -0
package/dist/frontend/index.html +1 -1
package/dist/server-assets/_shared/ef-meta/index.ts +1 -1
package/dist/server-assets/_shared/mcp-tools/get-document.ts +6 -2
package/dist/server-assets/_shared/mcp-tools/get-help-content.ts +6 -6
package/dist/server-assets/_shared/mcp-tools/ingest.ts +75 -7
package/dist/server-assets/_shared/mcp-tools/metadata-search.ts +3 -1
package/dist/server-assets/_shared/mcp-tools/search.ts +4 -1
package/dist/server-assets/db/rpcs.sql +89 -16
package/dist/server-assets/db/schema.sql +1 -1
package/dist/server-assets/supabase/functions/cerefox-get-document/index.ts +5 -1
package/dist/server-assets/supabase/functions/cerefox-ingest/index.ts +71 -2
package/docs/guides/agent-coordination.md +14 -1
package/docs/guides/cli.md +23 -8
package/docs/guides/connect-agents.md +44 -3
package/package.json +1 -1
package/dist/frontend/assets/index-DVXDQ7__.js.map +0 -1

package/dist/frontend/index.html CHANGED Viewed

@@ -15,7 +15,7 @@
       href="https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&display=swap"
     />
     <title>Cerefox</title>
-    <script type="module" crossorigin src="/app/assets/index-DVXDQ7__.js"></script>
+    <script type="module" crossorigin src="/app/assets/index-ojNhWSxm.js"></script>
     <link rel="stylesheet" crossorigin href="/app/assets/index-Asx5wD7g.css">
   </head>
   <body>

package/dist/server-assets/_shared/ef-meta/index.ts CHANGED Viewed

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
-export const EF_VERSION = "0.10.4";
+export const EF_VERSION = "0.11.1";
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

package/dist/server-assets/_shared/mcp-tools/get-document.ts CHANGED Viewed

@@ -32,6 +32,7 @@ async function handler(
         full_content?: string;
         chunk_count?: number;
         total_chars?: number;
+        content_hash?: string;
       }
     | undefined;
@@ -46,13 +47,16 @@ async function handler(
   });
   const label = version_id !== null ? " (archived version)" : " (current)";
-  return `# ${row.doc_title ?? "Untitled"}${label}\n\n${row.full_content ?? ""}`;
+  // content_hash is the optimistic-concurrency token: pass it back as
+  // expected_content_hash when updating this document via cerefox_ingest.
+  const hashLine = row.content_hash ? `content_hash: ${row.content_hash}\n\n` : "";
+  return `# ${row.doc_title ?? "Untitled"}${label}\n${hashLine}${row.full_content ?? ""}`;
 }
 export const getDocumentTool: ToolDefinition = {
   name: "cerefox_get_document",
   description:
-    "Retrieve the full reconstructed content of a document. Pass version_id to retrieve an archived version; omit it (or pass null) for the current version. Version UUIDs are returned by cerefox_list_versions.",
+    "Retrieve the full reconstructed content of a document. Pass version_id to retrieve an archived version; omit it (or pass null) for the current version. Version UUIDs are returned by cerefox_list_versions. The response header includes the document's current content_hash — pass it back as expected_content_hash when updating via cerefox_ingest (optimistic concurrency).",
   inputSchema: {
     type: "object",
     required: ["document_id"],

package/dist/server-assets/_shared/mcp-tools/get-help-content.ts CHANGED Viewed

@@ -11,16 +11,16 @@
  * docs/specs/polish-and-distribution-design.md §10d.
  */
-export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for \"How AI Agents Use Cerefox\" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |\n| `cerefox_get_document` | Get full document by ID | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\", author=\"my-agent\")\n```\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true, author=\"my-agent\")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search \"<q>\" --requestor \"<your-name>\"` |\n| `cerefox_ingest` (paste) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --document-id \"<uuid>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor \"<your-name>\"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor \"<your-name>\"` |\n| `cerefox_list_projects` | `cerefox project list --requestor \"<your-name>\"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor \"<your-name>\"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author \"<your-name>\" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n";
+export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for \"How AI Agents Use Cerefox\" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token) | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. If it's stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer's work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\",\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc (note its hash) -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true,\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search \"<q>\" --requestor \"<your-name>\"` |\n| `cerefox_ingest` (paste) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --document-id \"<uuid>\" --expected-content-hash \"<hash>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor \"<your-name>\"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor \"<your-name>\"` |\n| `cerefox_list_projects` | `cerefox project list --requestor \"<your-name>\"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor \"<your-name>\"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author \"<your-name>\" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n";
 /** Sections keyed by their H2 heading text (lower-cased for matching). */
 export const HELP_SECTIONS: Record<string, string> = {
-  "Tools": "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |\n| `cerefox_get_document` | Get full document by ID | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |",
-  "Essential Rules": "## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.",
-  "Update Workflow (ID-based -- preferred)": "## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\", author=\"my-agent\")\n```",
-  "Update Workflow (title-based -- fallback)": "## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true, author=\"my-agent\")\n```",
+  "Tools": "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token) | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |",
+  "Essential Rules": "## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. If it's stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer's work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.",
+  "Update Workflow (ID-based -- preferred)": "## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\",\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.",
+  "Update Workflow (title-based -- fallback)": "## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc (note its hash) -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true,\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```",
   "Catch-Up Workflow": "## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```",
-  "CLI fallback (when MCP is unavailable)": "## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search \"<q>\" --requestor \"<your-name>\"` |\n| `cerefox_ingest` (paste) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --document-id \"<uuid>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor \"<your-name>\"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor \"<your-name>\"` |\n| `cerefox_list_projects` | `cerefox project list --requestor \"<your-name>\"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor \"<your-name>\"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author \"<your-name>\" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.",
+  "CLI fallback (when MCP is unavailable)": "## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search \"<q>\" --requestor \"<your-name>\"` |\n| `cerefox_ingest` (paste) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --document-id \"<uuid>\" --expected-content-hash \"<hash>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor \"<your-name>\"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor \"<your-name>\"` |\n| `cerefox_list_projects` | `cerefox project list --requestor \"<your-name>\"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor \"<your-name>\"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author \"<your-name>\" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.",
 };
 export const HELP_SECTION_HEADINGS: string[] = ["Tools", "Essential Rules", "Update Workflow (ID-based -- preferred)", "Update Workflow (title-based -- fallback)", "Catch-Up Workflow", "CLI fallback (when MCP is unavailable)"];

package/dist/server-assets/_shared/mcp-tools/ingest.ts CHANGED Viewed

@@ -23,6 +23,43 @@ import { ensureDocumentInProject, setDocumentProjectsByName } from "./_projects.
 import { logUsage } from "./_utils.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+/**
+ * Agent-first instructions for an optimistic-concurrency conflict (iter-32).
+ * Raised either by the local fast-fail (before the embedding spend) or by the
+ * authoritative check inside the cerefox_ingest_document RPC.
+ */
+function conflictError(documentId: string, expectedHash: string, currentHash: string): Error {
+  return new Error(
+    `Conflict: document ${documentId} changed since you read it ` +
+      `(your base hash: ${expectedHash}, current hash: ${currentHash}). ` +
+      `To resolve: (1) cerefox_get_document("${documentId}") to fetch the latest content ` +
+      `and its content_hash, (2) merge your changes into it, (3) retry cerefox_ingest ` +
+      `with expected_content_hash set to the new hash. Do not overwrite blindly — ` +
+      `the current content may include another writer's work.`,
+  );
+}
+/** Map RPC-side CEREFOX_CONFLICT / CEREFOX_TOKEN_REQUIRED errors to agent-first text. */
+function mapIngestRpcError(message: string, documentId: string): Error {
+  if (message.includes("CEREFOX_CONFLICT")) {
+    const current = message.match(/current hash ([0-9a-f]{64})/)?.[1] ?? "unknown";
+    const expected = message.match(/expected hash ([0-9a-f]{64})/)?.[1] ?? "unknown";
+    return conflictError(documentId, expected, current);
+  }
+  if (message.includes("CEREFOX_TOKEN_REQUIRED")) {
+    const current = message.match(/Current hash: ([0-9a-f]{64})/)?.[1];
+    return new Error(
+      `Concurrency token required: content updates need expected_content_hash — ` +
+        `the content_hash of the version you based your edit on (returned by ` +
+        `cerefox_get_document, cerefox_search, and cerefox_metadata_search).` +
+        (current ? ` The document's current hash is ${current}; pass it ONLY if your edit was based on the current content.` : "") +
+        ` If you have not read the document, read it first. To deliberately overwrite ` +
+        `regardless of concurrent changes, pass last_write_wins=true.`,
+    );
+  }
+  return new Error(`Ingest RPC failed: ${message}`);
+}
 async function handler(
   supabase: MCPSupabaseClient,
   args: Record<string, unknown>,
@@ -34,10 +71,15 @@ async function handler(
   const project_name = args.project_name as string | undefined;
   const project_names_raw = args.project_names;
   const source = (args.source as string | undefined) ?? "agent";
-  const metadata = (args.metadata as Record<string, unknown> | undefined) ?? {};
+  // null = "not provided": the RPC keeps existing metadata on update and uses
+  // {} on create (v0.11.1 — defaulting to {} here used to wipe a document's
+  // tags on every content update that didn't re-pass them).
+  const metadata = (args.metadata as Record<string, unknown> | undefined) ?? null;
   const update_if_exists = (args.update_if_exists as boolean | undefined) ?? false;
   const author = (args.author as string | undefined) ?? "mcp-agent";
   const author_type = "agent"; // MCP path is always agent
+  const expected_content_hash = (args.expected_content_hash as string | undefined)?.trim() || null;
+  const last_write_wins = (args.last_write_wins as boolean | undefined) ?? false;
   if (!title || !content?.trim()) {
     throw new McpInvalidParams("title and content are required");
@@ -83,7 +125,13 @@ async function handler(
       const note = update_if_exists
         ? ""
         : " Note: update_if_exists flag was overridden by document_id.";
-      return `Document already up-to-date: "${existingDoc.title}" (id: ${existingDoc.id}). Content hash unchanged.${note}`;
+      return `Document already up-to-date: "${existingDoc.title}" (id: ${existingDoc.id}). Content hash unchanged (${contentHash}).${note}`;
+    }
+    // Fast-fail on a stale token BEFORE paying the embedding cost. Advisory
+    // only — the authoritative, race-free check is inside the RPC (FOR UPDATE).
+    if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
+      throw conflictError(existingDoc.id, expected_content_hash, existingDoc.content_hash);
     }
     const chunks = chunkMarkdown(content);
@@ -115,9 +163,11 @@ async function handler(
       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) throw new Error(`Ingest RPC failed: ${ingestErr.message}`);
+    if (ingestErr) throw mapIngestRpcError(ingestErr.message, existingDoc.id);
     logUsage(supabase, {
       operation: "ingest",
@@ -136,7 +186,7 @@ async function handler(
     const note = update_if_exists
       ? ""
       : " Note: update_if_exists flag was overridden by document_id.";
-    return `Document updated: "${title}" (id: ${existingDoc.id}), ${chunks.length} chunk(s), ${totalChars} chars.${note}`;
+    return `Document updated: "${title}" (id: ${existingDoc.id}), ${chunks.length} chunk(s), ${totalChars} chars. New content_hash: ${contentHash}.${note}`;
   }
   // ── Update-existing path ─────────────────────────────────────────────────
@@ -152,7 +202,13 @@ async function handler(
       const existingDoc = existing[0];
       if (existingDoc.content_hash === contentHash) {
-        return `Document already up-to-date: "${existingDoc.title}" (id: ${existingDoc.id}). Content hash unchanged.`;
+        return `Document already up-to-date: "${existingDoc.title}" (id: ${existingDoc.id}). Content hash unchanged (${contentHash}).`;
+      }
+      // Fast-fail on a stale token BEFORE the embedding cost (advisory; the
+      // authoritative check is in the RPC).
+      if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
+        throw conflictError(existingDoc.id, expected_content_hash, existingDoc.content_hash);
       }
       const chunks = chunkMarkdown(content);
@@ -184,9 +240,11 @@ async function handler(
         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) throw new Error(`Ingest RPC failed: ${ingestErr.message}`);
+      if (ingestErr) throw mapIngestRpcError(ingestErr.message, existingDoc.id);
       logUsage(supabase, {
         operation: "ingest",
@@ -202,7 +260,7 @@ async function handler(
         await ensureDocumentInProject(supabase, existingDoc.id, project_name);
       }
-      return `Document updated: "${existingDoc.title}" (id: ${existingDoc.id}), ${chunks.length} chunk(s), ${totalChars} chars.`;
+      return `Document updated: "${existingDoc.title}" (id: ${existingDoc.id}), ${chunks.length} chunk(s), ${totalChars} chars. New content_hash: ${contentHash}.`;
     }
     // Fall through to create path
   }
@@ -303,6 +361,16 @@ export const ingestTool: ToolDefinition = {
         description:
           "When true, update an existing document with the same title instead of creating a new one (default: false). Ignored when document_id is provided.",
       },
+      expected_content_hash: {
+        type: "string",
+        description:
+          "REQUIRED on content updates (optimistic concurrency): the content_hash of the document version you based your edit on, as returned by cerefox_get_document / cerefox_search / cerefox_metadata_search. If the document changed since you read it, the update fails with a conflict — re-read, merge, retry with the new hash. Not needed when creating a new document.",
+      },
+      last_write_wins: {
+        type: "boolean",
+        description:
+          "Explicitly skip the concurrency check and overwrite regardless of concurrent changes (default: false). Use ONLY when an external source of truth makes conflicts meaningless (e.g. re-syncing from files). Recorded in the audit log.",
+      },
       metadata: { type: "object", description: "Arbitrary JSON metadata (optional)" },
       author: {
         type: "string",

package/dist/server-assets/_shared/mcp-tools/metadata-search.ts CHANGED Viewed

@@ -78,6 +78,7 @@ async function handler(
     project_ids: string[];
     project_names: string[];
     version_count: number;
+    content_hash: string | null;
     content: string | null;
   }>;
@@ -105,9 +106,10 @@ async function handler(
     const meta = Object.entries(row.doc_metadata ?? {})
       .map(([k, v]) => `${k}=${v}`)
       .join(", ");
+    const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
     const header =
       `## ${row.title} [id: ${row.document_id}]\n` +
-      `${meta}${projects} | ${row.total_chars} chars | ${row.review_status} | updated ${row.updated_at?.slice(0, 10) ?? "?"}`;
+      `${meta}${projects} | ${row.total_chars} chars | ${row.review_status} | updated ${row.updated_at?.slice(0, 10) ?? "?"}${hash}`;
     if (include_content && row.content) {
       return `${header}\n\n${row.content}`;

package/dist/server-assets/_shared/mcp-tools/search.ts CHANGED Viewed

@@ -135,6 +135,7 @@ async function handler(
     is_partial?: boolean;
     chunk_count?: number;
     total_chars?: number;
+    content_hash?: string;
   }>;
   const parts: string[] = rows.map((row) => {
@@ -144,7 +145,9 @@ async function handler(
     const partial = row.is_partial
       ? ` -- partial (${row.chunk_count} of ${(row.total_chars ?? 0).toLocaleString()} chars)`
       : "";
-    return `## ${title}${docId}${score}${partial}\n\n${row.full_content ?? ""}`;
+    // content_hash = the concurrency token for cerefox_ingest updates (iter-32).
+    const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
+    return `## ${title}${docId}${score}${partial}${hash}\n\n${row.full_content ?? ""}`;
   });
   let output = parts.join("\n\n---\n\n");

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

@@ -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 ────────────────────────────────────────────
@@ -1028,7 +1045,10 @@ $$;
 --
 -- Parameters:
 --   p_document_id     : NULL for create, UUID for update
---   p_title, p_source, p_source_path, p_content_hash, p_metadata : document fields
+--   p_title, p_source, p_source_path, p_content_hash : document fields
+--   p_metadata        : JSONB metadata. NULL = "not provided" → create uses '{}',
+--                       update keeps the existing metadata (v0.11.1). Pass '{}'
+--                       explicitly to clear all metadata.
 --   p_review_status   : 'approved' or 'pending_review' (based on author_type)
 --   p_chunks          : JSONB array of chunk objects, each with:
 --                        chunk_index, heading_path, heading_level, title,
@@ -1037,25 +1057,40 @@ $$;
 --   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',
     p_source            TEXT        DEFAULT 'agent',
     p_source_path       TEXT        DEFAULT NULL,
     p_content_hash      TEXT        DEFAULT '',
-    p_metadata          JSONB       DEFAULT '{}',
+    -- NULL = "not provided": create uses '{}', update KEEPS existing metadata
+    -- (v0.11.1 fix — content updates without metadata used to wipe tags).
+    -- Pass '{}' explicitly to deliberately clear all metadata.
+    p_metadata          JSONB       DEFAULT NULL,
     p_review_status     TEXT        DEFAULT 'approved',
     p_chunks            JSONB       DEFAULT '[]',
     p_author            TEXT        DEFAULT 'unknown',
     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 +1110,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,21 +1150,51 @@ 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
         FROM cerefox_snapshot_version(v_doc_id, p_source_label, p_retention_hours, p_cleanup_enabled) sv;
-        -- Update document record
+        -- Update document record. metadata: NULL = keep existing (v0.11.1 —
+        -- a content update without metadata must not wipe the document's tags).
         UPDATE cerefox_documents SET
             title = p_title,
             source = p_source,
             source_path = COALESCE(p_source_path, source_path),
             content_hash = p_content_hash,
-            metadata = p_metadata,
+            metadata = COALESCE(p_metadata, metadata),
             chunk_count = v_chunk_count,
             total_chars = v_total_chars,
             review_status = v_status,
@@ -1143,7 +1209,7 @@ BEGIN
             title, source, source_path, content_hash, metadata,
             chunk_count, total_chars, review_status
         ) VALUES (
-            p_title, p_source, p_source_path, p_content_hash, p_metadata,
+            p_title, p_source, p_source_path, p_content_hash, COALESCE(p_metadata, '{}'::JSONB),
             v_chunk_count, v_total_chars, v_status
         )
         RETURNING id INTO v_doc_id;
@@ -1183,6 +1249,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 +1475,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 +1507,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 +1546,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 +1767,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.6.0'::TEXT;
 $$;

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

@@ -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.6.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 CHANGED Viewed

@@ -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" } },
     );