@cerefox/memory 0.10.4 → 0.11.1

package/dist/bin/cerefox.js

@@ -7184,7 +7184,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "0.10.4";
+var PKG_VERSION = "0.11.1";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js
@@ -54007,16 +54007,18 @@ async function handler2(supabase, args, ctx) {
     result_count: 1
   });
   const label = version_id !== null ? " (archived version)" : " (current)";
-  return `# ${row.doc_title ?? "Untitled"}${label}
+  const hashLine = row.content_hash ? `content_hash: ${row.content_hash}
 
-${row.full_content ?? ""}`;
+` : "";
+  return `# ${row.doc_title ?? "Untitled"}${label}
+${hashLine}${row.full_content ?? ""}`;
 }
 var getDocumentTool;
 var init_get_document = __esm(() => {
   init_types3();
   getDocumentTool = {
     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.",
+    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. 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"],
@@ -54037,15 +54039,23 @@ var init_get_document = __esm(() => {
 });
 
 // ../../_shared/mcp-tools/get-help-content.ts
-var 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', HELP_SECTIONS, HELP_SECTION_HEADINGS;
+var 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', HELP_SECTIONS, HELP_SECTION_HEADINGS;
 var init_get_help_content = __esm(() => {
   HELP_SECTIONS = {
-    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)
+
+\`\`\`
+search("topic") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->
+ingest(title="Same Title", content="...", document_id="abc123",
+       expected_content_hash="<the hash you read>", author="my-agent")
+\`\`\`
+
+On 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.'
   };
   HELP_SECTION_HEADINGS = ["Tools", "Essential Rules", "Update Workflow (ID-based -- preferred)", "Update Workflow (title-based -- fallback)", "Catch-Up Workflow", "CLI fallback (when MCP is unavailable)"];
 });
@@ -54265,6 +54275,21 @@ async function sha256hex(text) {
 var MAX_CHUNK_CHARS = 4000;
 
 // ../../_shared/mcp-tools/ingest.ts
+function conflictError(documentId, expectedHash, currentHash) {
+  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.`);
+}
+function mapIngestRpcError(message, documentId) {
+  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 handler4(supabase, args, ctx) {
   const title = args.title?.trim();
   const content = args.content;
@@ -54272,10 +54297,12 @@ async function handler4(supabase, args, ctx) {
   const project_name = args.project_name;
   const project_names_raw = args.project_names;
   const source = args.source ?? "agent";
-  const metadata = args.metadata ?? {};
+  const metadata = args.metadata ?? null;
   const update_if_exists = args.update_if_exists ?? false;
   const author = args.author ?? "mcp-agent";
   const author_type = "agent";
+  const expected_content_hash = args.expected_content_hash?.trim() || null;
+  const last_write_wins = args.last_write_wins ?? false;
   if (!title || !content?.trim()) {
     throw new McpInvalidParams("title and content are required");
   }
@@ -54296,7 +54323,10 @@ async function handler4(supabase, args, ctx) {
     const existingDoc = existing[0];
     if (existingDoc.content_hash === contentHash2) {
       const note2 = 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.${note2}`;
+      return `Document already up-to-date: "${existingDoc.title}" (id: ${existingDoc.id}). Content hash unchanged (${contentHash2}).${note2}`;
+    }
+    if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
+      throw conflictError(existingDoc.id, expected_content_hash, existingDoc.content_hash);
     }
     const chunks2 = chunkMarkdown2(content);
     if (chunks2.length === 0)
@@ -54325,10 +54355,12 @@ ${c2.content}`);
       p_chunks: chunkData2,
       p_author: author,
       p_author_type: author_type,
-      p_source_label: source
+      p_source_label: source,
+      p_expected_content_hash: expected_content_hash,
+      p_last_write_wins: last_write_wins
     });
     if (ingestErr2)
-      throw new Error(`Ingest RPC failed: ${ingestErr2.message}`);
+      throw mapIngestRpcError(ingestErr2.message, existingDoc.id);
     logUsage(supabase, {
       operation: "ingest",
       accessPath: ctx.accessPath,
@@ -54342,14 +54374,17 @@ ${c2.content}`);
       await ensureDocumentInProject(supabase, existingDoc.id, project_name);
     }
     const note = update_if_exists ? "" : " Note: update_if_exists flag was overridden by document_id.";
-    return `Document updated: "${title}" (id: ${existingDoc.id}), ${chunks2.length} chunk(s), ${totalChars2} chars.${note}`;
+    return `Document updated: "${title}" (id: ${existingDoc.id}), ${chunks2.length} chunk(s), ${totalChars2} chars. New content_hash: ${contentHash2}.${note}`;
   }
   if (update_if_exists) {
     const { data: existing } = await supabase.from("cerefox_documents").select("id, title, content_hash").eq("title", title).order("updated_at", { ascending: false }).limit(1);
     if (existing?.length) {
       const existingDoc = existing[0];
       if (existingDoc.content_hash === contentHash2) {
-        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 (${contentHash2}).`;
+      }
+      if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
+        throw conflictError(existingDoc.id, expected_content_hash, existingDoc.content_hash);
       }
       const chunks2 = chunkMarkdown2(content);
       if (chunks2.length === 0)
@@ -54378,10 +54413,12 @@ ${c2.content}`);
         p_chunks: chunkData2,
         p_author: author,
         p_author_type: author_type,
-        p_source_label: source
+        p_source_label: source,
+        p_expected_content_hash: expected_content_hash,
+        p_last_write_wins: last_write_wins
       });
       if (ingestErr2)
-        throw new Error(`Ingest RPC failed: ${ingestErr2.message}`);
+        throw mapIngestRpcError(ingestErr2.message, existingDoc.id);
       logUsage(supabase, {
         operation: "ingest",
         accessPath: ctx.accessPath,
@@ -54394,7 +54431,7 @@ ${c2.content}`);
       } else if (project_name) {
         await ensureDocumentInProject(supabase, existingDoc.id, project_name);
       }
-      return `Document updated: "${existingDoc.title}" (id: ${existingDoc.id}), ${chunks2.length} chunk(s), ${totalChars2} chars.`;
+      return `Document updated: "${existingDoc.title}" (id: ${existingDoc.id}), ${chunks2.length} chunk(s), ${totalChars2} chars. New content_hash: ${contentHash2}.`;
     }
   }
   const { data: hashMatch } = await supabase.from("cerefox_documents").select("id, title").eq("content_hash", contentHash2).limit(1);
@@ -54479,6 +54516,14 @@ var init_ingest = __esm(() => {
           type: "boolean",
           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",
@@ -54666,8 +54711,10 @@ async function handler8(supabase, args, ctx) {
   const parts = rows.map((row) => {
     const projects = row.project_names?.length ? ` | projects: ${row.project_names.join(", ")}` : "";
     const meta = Object.entries(row.doc_metadata ?? {}).map(([k, v]) => `${k}=${v}`).join(", ");
+    const hash = row.content_hash ? `
+hash: ${row.content_hash}` : "";
     const header = `## ${row.title} [id: ${row.document_id}]
-` + `${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}
 
@@ -54809,7 +54856,9 @@ async function handler9(supabase, args, ctx) {
     const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
     const score = row.best_score != null ? ` (score: ${row.best_score.toFixed(3)})` : "";
     const partial = row.is_partial ? ` -- partial (${row.chunk_count} of ${(row.total_chars ?? 0).toLocaleString()} chars)` : "";
-    return `## ${title}${docId}${score}${partial}
+    const hash = row.content_hash ? `
+hash: ${row.content_hash}` : "";
+    return `## ${title}${docId}${score}${partial}${hash}
 
 ${row.full_content ?? ""}`;
   });
@@ -55001,6 +55050,7 @@ async function runSyncSelfDocs(options = {}) {
           topic: doc.topic
         },
         update_if_exists: true,
+        last_write_wins: true,
         project_name: project,
         author,
         author_type: authorType
@@ -74047,7 +74097,7 @@ import { homedir as homedir5 } from "node:os";
 import { join as join8 } from "node:path";
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "0.10.4";
+var EF_VERSION = "0.11.1";
 
 // src/cli/util/checks.ts
 init_config();
@@ -74746,6 +74796,9 @@ async function action17(documentId, options) {
   }
   println(c.bold(`# ${doc.doc_title}`));
   println(c.dim(`[${doc.document_id}] · chunks: ${doc.chunk_count} · chars: ${doc.total_chars}` + (doc.is_archived ? " · archived" : "") + (doc.version_id ? ` · version: ${doc.version_id}` : "")));
+  if (doc.content_hash) {
+    println(c.dim(`content_hash: ${doc.content_hash}`));
+  }
   println("");
   println(doc.full_content);
 }
@@ -75005,6 +75058,47 @@ async function resolveProjectIds(input, getOrCreateProject) {
   }
   return [];
 }
+// src/ingestion/types.ts
+class ConcurrencyConflictError extends Error {
+  documentId;
+  currentHash;
+  constructor(documentId, currentHash, message) {
+    super(message);
+    this.name = "ConcurrencyConflictError";
+    this.documentId = documentId;
+    this.currentHash = currentHash;
+  }
+}
+
+class ConcurrencyTokenRequiredError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConcurrencyTokenRequiredError";
+  }
+}
+var DEFAULT_PIPELINE_SETTINGS = {
+  maxChunkChars: 4000,
+  minChunkChars: 100,
+  versionRetentionHours: 48,
+  versionCleanupEnabled: true
+};
+function loadPipelineSettings() {
+  const env4 = globalThis.process?.env ?? {};
+  const intMin = (raw, def, min) => {
+    if (raw === undefined || raw === "")
+      return def;
+    const n = Number.parseInt(raw, 10);
+    return Number.isNaN(n) || n < min ? def : n;
+  };
+  const bool = (raw, def) => raw === undefined || raw === "" ? def : !/^(false|0|no|off)$/i.test(raw.trim());
+  return {
+    maxChunkChars: intMin(env4.CEREFOX_MAX_CHUNK_CHARS, DEFAULT_PIPELINE_SETTINGS.maxChunkChars, 1),
+    minChunkChars: intMin(env4.CEREFOX_MIN_CHUNK_CHARS, DEFAULT_PIPELINE_SETTINGS.minChunkChars, 0),
+    versionRetentionHours: intMin(env4.CEREFOX_VERSION_RETENTION_HOURS, DEFAULT_PIPELINE_SETTINGS.versionRetentionHours, 0),
+    versionCleanupEnabled: bool(env4.CEREFOX_VERSION_CLEANUP_ENABLED, DEFAULT_PIPELINE_SETTINGS.versionCleanupEnabled)
+  };
+}
+
 // src/ingestion/client-bridge.ts
 class IngestionDbBridge {
   supabase;
@@ -75057,9 +75151,22 @@ class IngestionDbBridge {
       params.p_retention_hours = args.retentionHours;
     if (args.cleanupEnabled !== undefined)
       params.p_cleanup_enabled = args.cleanupEnabled;
+    if (args.documentId !== null) {
+      params.p_expected_content_hash = args.expectedContentHash ?? null;
+      params.p_last_write_wins = args.lastWriteWins ?? false;
+    }
     const { data, error: error2 } = await this.supabase.rpc("cerefox_ingest_document", params);
-    if (error2)
-      throw new Error(error2.message ?? JSON.stringify(error2));
+    if (error2) {
+      const msg = error2.message ?? JSON.stringify(error2);
+      if (msg.includes("CEREFOX_CONFLICT")) {
+        const current = msg.match(/current hash ([0-9a-f]{64})/)?.[1] ?? null;
+        throw new ConcurrencyConflictError(args.documentId ?? "", current, msg);
+      }
+      if (msg.includes("CEREFOX_TOKEN_REQUIRED")) {
+        throw new ConcurrencyTokenRequiredError(msg);
+      }
+      throw new Error(msg);
+    }
     if (Array.isArray(data) && data.length > 0) {
       return data[0];
     }
@@ -75164,30 +75271,6 @@ async function fileToMarkdown(filename, data) {
   return data.toString("utf8");
 }
 
-// src/ingestion/types.ts
-var DEFAULT_PIPELINE_SETTINGS = {
-  maxChunkChars: 4000,
-  minChunkChars: 100,
-  versionRetentionHours: 48,
-  versionCleanupEnabled: true
-};
-function loadPipelineSettings() {
-  const env4 = globalThis.process?.env ?? {};
-  const intMin = (raw, def, min) => {
-    if (raw === undefined || raw === "")
-      return def;
-    const n = Number.parseInt(raw, 10);
-    return Number.isNaN(n) || n < min ? def : n;
-  };
-  const bool = (raw, def) => raw === undefined || raw === "" ? def : !/^(false|0|no|off)$/i.test(raw.trim());
-  return {
-    maxChunkChars: intMin(env4.CEREFOX_MAX_CHUNK_CHARS, DEFAULT_PIPELINE_SETTINGS.maxChunkChars, 1),
-    minChunkChars: intMin(env4.CEREFOX_MIN_CHUNK_CHARS, DEFAULT_PIPELINE_SETTINGS.minChunkChars, 0),
-    versionRetentionHours: intMin(env4.CEREFOX_VERSION_RETENTION_HOURS, DEFAULT_PIPELINE_SETTINGS.versionRetentionHours, 0),
-    versionCleanupEnabled: bool(env4.CEREFOX_VERSION_CLEANUP_ENABLED, DEFAULT_PIPELINE_SETTINGS.versionCleanupEnabled)
-  };
-}
-
 // src/ingestion/pipeline.ts
 class IngestionPipeline {
   db;
@@ -75214,7 +75297,9 @@ class IngestionPipeline {
       updateExisting = false,
       documentId,
       author = "unknown",
-      authorType = "user"
+      authorType = "user",
+      expectedContentHash,
+      lastWriteWins = false
     } = opts;
     const listFormProvided = projectIds !== undefined && projectIds !== null || projectNames !== undefined && projectNames !== null;
     const getOrCreate = (name) => this.db.getOrCreateProject(name);
@@ -75235,7 +75320,9 @@ class IngestionPipeline {
         projectIds: fullSetResolved,
         metadata,
         author,
-        authorType
+        authorType,
+        expectedContentHash,
+        lastWriteWins
       });
       if (!listFormProvided && (projectId || projectName)) {
         const singular = await resolveProjectIds({ projectId, projectName }, getOrCreate);
@@ -75270,7 +75357,9 @@ class IngestionPipeline {
           projectIds: fullSetResolved,
           metadata,
           author,
-          authorType
+          authorType,
+          expectedContentHash,
+          lastWriteWins
         });
         if (!listFormProvided && (projectId || projectName)) {
           const singular = await resolveProjectIds({ projectId, projectName }, getOrCreate);
@@ -75356,7 +75445,9 @@ ${c2.content}`);
       projectIds,
       metadata,
       author = "unknown",
-      authorType = "user"
+      authorType = "user",
+      expectedContentHash,
+      lastWriteWins = false
     } = opts;
     const existing = await this.db.getDocumentById(documentId);
     if (!existing) {
@@ -75365,6 +75456,9 @@ ${c2.content}`);
     const newHash = contentHash(text);
     const contentUnchanged = newHash === existing.content_hash;
     if (!contentUnchanged) {
+      if (!lastWriteWins && expectedContentHash && expectedContentHash !== existing.content_hash) {
+        throw new ConcurrencyConflictError(documentId, existing.content_hash, `CEREFOX_CONFLICT: document ${documentId} changed since it was read ` + `(expected hash ${expectedContentHash}, current hash ${existing.content_hash}). ` + `Re-read the document, merge your changes, and retry with the new hash.`);
+      }
       const collision = await this.db.getDocumentByHash(newHash);
       if (collision && collision.id !== documentId) {
         throw new Error(`Identical content already exists as document ${JSON.stringify(collision.title)}. ` + "Edit that document or change the content before saving.");
@@ -75465,7 +75559,9 @@ ${c2.content}`);
       authorType,
       sourceLabel: source,
       retentionHours: this.settings.versionRetentionHours,
-      cleanupEnabled: this.settings.versionCleanupEnabled
+      cleanupEnabled: this.settings.versionCleanupEnabled,
+      expectedContentHash: expectedContentHash ?? null,
+      lastWriteWins
     });
     let finalProjectIds;
     if (newProjectIds !== null) {
@@ -75539,7 +75635,7 @@ async function action18(path, options) {
   if (author === "unknown") {
     warn("No --author / CEREFOX_AUTHOR_NAME set — audit log will record this write as 'unknown'.");
   }
-  const metadata = parseJsonObjectArg(options.metadata, "--metadata") ?? {};
+  const metadata = parseJsonObjectArg(options.metadata, "--metadata");
   let projectNames;
   if (options.projectNames) {
     projectNames = options.projectNames.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
@@ -75566,22 +75662,26 @@ async function action18(path, options) {
       source: options.source ?? "cli",
       projectName: options.projectName ?? null,
       projectNames: projectNames ?? null,
-      metadata,
+      metadata: metadata ?? null,
       updateExisting: Boolean(options.updateIfExists),
       documentId: options.documentId ?? null,
       author,
-      authorType
+      authorType,
+      expectedContentHash: options.expectedContentHash ?? null,
+      lastWriteWins: Boolean(options.lastWriteWins)
     }) : await pipeline.ingestText({
       text: content,
       title,
       source: options.source ?? "cli",
       projectName: options.projectName ?? null,
       projectNames: projectNames ?? null,
-      metadata,
+      metadata: metadata ?? null,
       updateExisting: Boolean(options.updateIfExists),
       documentId: options.documentId ?? null,
       author,
-      authorType
+      authorType,
+      expectedContentHash: options.expectedContentHash ?? null,
+      lastWriteWins: Boolean(options.lastWriteWins)
     });
     let verb;
     if (result.action === "created") {
@@ -75600,7 +75700,7 @@ async function action18(path, options) {
   }
 }
 function registerIngest(program2) {
-  program2.command("ingest").description("Ingest a file (or stdin paste) into the knowledge base.").argument("[path]", "Path to the file to ingest. Omit when using --paste.").option("--paste", "Read content from stdin instead of a file.").option("-t, --title <title>", "Document title (required with --paste; defaults to filename without extension).").option("-p, --project-name <name>", "Single project membership (non-destructive on update).").option("-P, --project-names <names>", "Comma-separated full project membership set (destructive replace on update).").option("-m, --metadata <json>", "JSON metadata object.").option("--source <label>", "Origin label (default: cli).", "cli").option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-i, --document-id <uuid>", "Update a specific document by UUID (overrides --update-if-exists).").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action18);
+  program2.command("ingest").description("Ingest a file (or stdin paste) into the knowledge base.").argument("[path]", "Path to the file to ingest. Omit when using --paste.").option("--paste", "Read content from stdin instead of a file.").option("-t, --title <title>", "Document title (required with --paste; defaults to filename without extension).").option("-p, --project-name <name>", "Single project membership (non-destructive on update).").option("-P, --project-names <names>", "Comma-separated full project membership set (destructive replace on update).").option("-m, --metadata <json>", "JSON metadata object.").option("--source <label>", "Origin label (default: cli).", "cli").option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-i, --document-id <uuid>", "Update a specific document by UUID (overrides --update-if-exists).").option("--expected-content-hash <sha256>", "Optimistic-concurrency token: the content_hash of the version this edit is based on (shown by `document get` / `search`). Required on content updates unless --last-write-wins.").option("--last-write-wins", "Skip the concurrency check and overwrite regardless of concurrent changes (recorded in the audit log).").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action18);
 }
 
 // src/cli/commands/ingest-dir.ts
@@ -75648,7 +75748,7 @@ async function action19(dir, options) {
   if (author === "unknown") {
     warn("No --author / CEREFOX_AUTHOR_NAME set — audit log will record these writes as 'unknown'.");
   }
-  const metadata = parseJsonObjectArg(options.metadata, "--metadata") ?? {};
+  const metadata = parseJsonObjectArg(options.metadata, "--metadata");
   const settings = loadSettings();
   if (!settings.supabaseUrl || !settings.supabaseKey) {
     throw userError("Supabase credentials not configured — run `cerefox init` first.");
@@ -75679,10 +75779,11 @@ async function action19(dir, options) {
         title: basename3(file, extname4(file)),
         source: options.source ?? "cli",
         projectName: options.projectName ?? null,
-        metadata,
+        metadata: metadata ?? null,
         updateExisting: Boolean(options.updateIfExists),
         author,
-        authorType
+        authorType,
+        lastWriteWins: true
       });
       outcomes.push({
         file,
@@ -76346,9 +76447,9 @@ function registerMcp(program2) {
 init_cli_core();
 init_client();
 async function action26(options) {
-  const metadataFilter = parseJsonObjectArg(options.metadataFilter, "--metadata-filter");
-  if (!metadataFilter || Object.keys(metadataFilter).length === 0) {
-    throw userError("--metadata-filter is required and must be a non-empty JSON object.", `Example: --metadata-filter '{"type":"decision-log"}'.`);
+  const metadataFilter = parseJsonObjectArg(options.metadataFilter, "--metadata-filter") ?? {};
+  if (Object.keys(metadataFilter).length === 0 && !options.projectName && !options.updatedSince && !options.createdSince) {
+    throw userError("Provide at least one of: --metadata-filter, --project-name, --updated-since, or --created-since.", `Examples: --metadata-filter '{"type":"decision-log"}' · --project-name "research" (lists that project's docs).`);
   }
   const limit = parsePositiveInt(options.limit, "--limit", 10);
   const maxBytes = parseNonNegativeInt(options.maxBytes, "--max-bytes", 200000);
@@ -76408,7 +76509,7 @@ async function action26(options) {
   }
 }
 function registerMetadataSearch(program2) {
-  program2.command("metadata-search").description("Find documents by metadata criteria (no text query).").requiredOption("-f, --metadata-filter <json>", "JSON object; only docs whose metadata contains ALL pairs are returned.").option("-p, --project-name <name>", "Filter to a specific project.").option("--updated-since <iso>", "Only docs updated on/after this ISO timestamp.").option("--created-since <iso>", "Only docs created on/after this ISO timestamp.").option("--include-content", "Include full document text in results.").option("-l, --limit <n>", "Maximum docs to return.", "10").option("--max-bytes <n>", "Response size budget in bytes (with --include-content).", "200000").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action26);
+  program2.command("metadata-search").description("Find or list documents by metadata, project, or time criteria (no text query).").option("-f, --metadata-filter <json>", "JSON object; only docs whose metadata contains ALL pairs are returned. Optional — omit to list by --project-name / time range alone (at least one criterion is required).").option("-p, --project-name <name>", "Filter to a specific project.").option("--updated-since <iso>", "Only docs updated on/after this ISO timestamp.").option("--created-since <iso>", "Only docs created on/after this ISO timestamp.").option("--include-content", "Include full document text in results.").option("-l, --limit <n>", "Maximum docs to return.", "10").option("--max-bytes <n>", "Response size budget in bytes (with --include-content).", "200000").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action26);
 }
 
 // src/cli/commands/reindex.ts
@@ -76728,10 +76829,12 @@ async function action29(query, options) {
       println(c.bold(`## ${title}${docId}${score}${counts}${kind}`));
       const bestMatch = doc2.best_chunk_heading_path?.length ? doc2.best_chunk_heading_path.join(" › ") : null;
       const updated = doc2.doc_updated_at ? doc2.doc_updated_at.slice(0, 10) : null;
-      if (bestMatch || updated) {
+      const hash = doc2.content_hash ? `hash: ${doc2.content_hash}` : null;
+      if (bestMatch || updated || hash) {
         const bits = [
           bestMatch ? `best match: ${bestMatch}` : null,
-          updated ? `updated ${updated}` : null
+          updated ? `updated ${updated}` : null,
+          hash
         ].filter(Boolean);
         println(c.dim(`   ${bits.join(" · ")}`));
       }
@@ -80801,6 +80904,7 @@ function registerDocumentReadRoutes(app, ctx) {
       created_at: meta ? meta.created_at ?? null : null,
       updated_at: meta ? meta.updated_at ?? null : null,
       deleted_at: meta ? meta.deleted_at ?? null : null,
+      content_hash: meta ? meta.content_hash ?? null : null,
       versions: versions3.map((v) => ({
         version_id: v.version_id,
         version_number: v.version_number,
@@ -80963,10 +81067,26 @@ function registerDocumentWriteRoutes(app, ctx) {
           projectIds: Array.isArray(body.project_ids) ? body.project_ids : undefined,
           metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
           author: "web-ui",
-          authorType: "user"
+          authorType: "user",
+          expectedContentHash: typeof body.expected_content_hash === "string" ? body.expected_content_hash : null
         });
         return c2.json({ success: true, reindexed: result.reindexed });
       } catch (err) {
+        if (err instanceof ConcurrencyConflictError) {
+          return c2.json({
+            success: false,
+            error: "conflict",
+            message: "This document changed while you were editing it (another writer saved a newer version). Open it again in a new tab, merge your changes, and save from there.",
+            current_hash: err.currentHash
+          }, 409);
+        }
+        if (err instanceof ConcurrencyTokenRequiredError) {
+          return c2.json({
+            success: false,
+            error: "expected_content_hash required",
+            message: err.message
+          }, 400);
+        }
         return c2.json({
           success: false,
           error: err instanceof Error ? err.message : String(err)