@cerefox/memory 1.5.0 → 1.6.0

package/dist/bin/cerefox.js

@@ -7438,7 +7438,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "1.5.0";
+var PKG_VERSION = "1.6.0";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -25731,7 +25731,7 @@ var init_bundled_docs = __esm(() => {
 });
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "1.5.0", CEREFOX_VERSION = "1.5.0", EF_LAST_CHANGED = "1.5.0";
+var EF_VERSION = "1.6.0", CEREFOX_VERSION = "1.6.0", EF_LAST_CHANGED = "1.6.0";
 var init_ef_meta = () => {};
 
 // ../../_shared/compatibility/index.ts
@@ -41580,10 +41580,10 @@ var require_flate = __commonJS((exports) => {
   var GenericWorker = require_GenericWorker();
   var ARRAY_TYPE = USE_TYPEDARRAY ? "uint8array" : "array";
   exports.magic = "\b\x00";
-  function FlateWorker(action18, options) {
-    GenericWorker.call(this, "FlateWorker/" + action18);
+  function FlateWorker(action19, options) {
+    GenericWorker.call(this, "FlateWorker/" + action19);
     this._pako = null;
-    this._pakoAction = action18;
+    this._pakoAction = action19;
     this._pakoOptions = options;
     this.meta = {};
   }
@@ -55522,10 +55522,10 @@ var init_partial_edits2 = __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 **16 MCP tools** (15 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_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part` |\n| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required) |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: "## Heading"` one section\'s text | `document_id` (required), `outline`, `section`, `section_part` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\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⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.\n\n## Editing part of a document (prefer this over re-sending)\n\n**Re-sending a whole document to change part of it is the main way agents lose\ndata.** You have to reproduce the untouched remainder verbatim, and any drift\nsilently rewrites content nobody asked you to touch — which the caller cannot\ndiff. Use the partial-edit tools instead:\n\n1. **Learn the anchors** — `cerefox_get_document(document_id, outline: true)`.\n   Returns heading paths, per-section sizes and the `content_hash`, without the\n   body. The paths it returns are exactly what `anchor_heading` accepts.\n2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;\n   `end_of_section` adds inside a named section. It is structurally incapable of\n   removing anything, so "I meant to append" cannot become "I replaced the file".\n3. **Look before you overwrite** — `cerefox_get_document(document_id,\n   section: "## Heading")` returns exactly the text a `replace_section` on that\n   anchor would destroy. The outline gives you a section\'s *size*, never its\n   *text*, so on a document you did not write yourself this is the difference\n   between a replace and a blind overwrite.\n4. **Change or remove** → `cerefox_edit`. Put changes that belong together in\n   ONE call: they apply atomically, so a table row and the total it feeds cannot\n   end up disagreeing. To change a single line, `replace_section` on its\n   smallest enclosing heading — that is the intended granularity, not a\n   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use\n   `rename_section`: it changes the heading text and leaves the body and\n   position alone.\n5. All of them require `expected_content_hash` and **have no last-write-wins**. A\n   conflict means someone else changed the document; re-read and decide, do not\n   force it.\n\n**A section runs to the next same-or-higher heading, or to the end of the\ndocument.** So `end_of_document` inserts land inside the *last* section, and\nreplacing or deleting that section removes them too. A large shrink in the\nresponse is your warning; `cerefox_list_versions` has the previous content.\n\n**When an anchor is ambiguous the tool refuses and hands you the options** — a\nrepeated heading returns the qualifying paths, and a section with both its own\ncontent and sub-sections returns both `section_part` choices. That is a\nrecoverable answer, not a failure: retry with what it gave you.\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 last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. 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. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **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`, …).\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_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\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\n## Timestamps are UTC\n\nEvery timestamp Cerefox returns — `created_at` on audit entries, version\nhistory, document metadata — is **UTC**, and now carries its `Z` marker so it\ncannot be mistaken for local time.\n\n**When you write a date into a document\'s CONTENT, use your own clock, not a\nCerefox timestamp.** These are different things: a timestamp records when the\nserver stored something; a date in a log entry or a heading is authored content\nand belongs to your timezone. An agent working a Pacific afternoon read\n`2026-08-11` from version history, wrote "8/11" into its entries, and put a\nday\'s work in the future — the timestamp was correct, and copying it into\ncontent was not.\n\nCerefox deliberately does not convert to local time on the API or MCP paths.\n"Local" has no server-side meaning: the remote MCP server runs in a cloud\nfunction whose local time *is* UTC, while a local MCP server runs in yours, so\nthe same document would report two different times depending on transport. The\nweb UI converts because a browser knows the viewer\'s timezone; nothing\nserver-side does.\n\n## Mistakes that have actually happened\n\nEach of these comes from a real agent session, and each is easy to make.\n\n- **`cerefox_ingest` always replaces the ENTIRE document.** Never a section.\n  Before sending, check that the tool name matches the intent: if the intent is\n  "change one section", the call is `cerefox_edit` with `replace_section`. A\n  section-sized edit sent as a full ingest truncated a 13,000-character index to\n  a single word. It was recovered from version history within the minute, but\n  only because it was noticed immediately.\n\n- **Do not include the anchor\'s own heading in your text.** `replace_section`\n  keeps the heading and `insert` places your text inside the section, so\n  including it produces two. This is now refused rather than silently applied,\n  but the shape is worth knowing: it happened twice in one session, the second\n  time while trying to repair the first. A *deeper* sub-heading inside your text\n  is fine.\n\n- **Content between sections belongs to the section ABOVE it.** A section runs\n  to the next heading of the same or higher level, so a `---` rule, a note, or\n  any trailing text sitting just above the next heading is part of the section\n  before it — even when it visually reads as belonging below. Replacing that\n  section takes it too. An agent hit exactly this: a `---` that separated two\n  major sections disappeared when the section above it was replaced. The write\n  was correct by the addressing rules; the surprise is that "the end of this\n  section" is further down the page than it looks. Note the loss warning will\n  not catch it if your replacement text is longer than what it replaced, since\n  there is then no net loss to report.\n\n- **Never partial-edit to fix a partial edit.** If a write leaves unexpected\n  structure, stop. Use `cerefox_list_versions`, retrieve the last good version,\n  and re-ingest cleanly. Repairing edits with more edits compounds the damage.\n\n- **A rejected batch is safe.** Operations in one `cerefox_edit` are\n  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a\n  retry, not data — so prefer one call for changes that belong together, and do\n  not split a batch to "make it more likely to succeed".\n\n- **Read before replacing.** `cerefox_get_document(section: "## Heading")`\n  returns exactly what a `replace_section` on that anchor would overwrite. Use it\n  for any section you did not write in this session. The outline gives a\n  section\'s *size*, never its *text*.\n\n- **Verify after writing** — read the result back before reporting success, and\n  report what the read actually shows.\n\n- **Partial edits cannot change a document\'s stored TITLE.** `rename_section`\n  changes a heading inside the content; the title is a separate field and still\n  needs `cerefox_ingest`.\n\n- **If a capability seems missing from one server, suspect your client first.**\n  Local and remote run the same code. Call `cerefox_get_help(topic: "server")`:\n  it reports the server\'s own version and the operations it registers. If that\n  disagrees with your tool list, the client is holding a list it fetched before\n  an upgrade — clients cache it at connect time. Ask the user to restart the\n  client. Do not record a capability difference between servers as a fact; every\n  such report so far has been a stale client.\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 **17 MCP tools** (16 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_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part` |\n| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required) |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: "## Heading"` one section\'s text | `document_id` (required), `outline`, `section`, `section_part` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\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_metadata` | Change tags WITHOUT resending content. **Merges** by default; a `null` value removes a key | `document_id`, `metadata` (required), `replace` (rare: set exactly this object), `author` |\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⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.\n\n## Editing part of a document (prefer this over re-sending)\n\n**Re-sending a whole document to change part of it is the main way agents lose\ndata.** You have to reproduce the untouched remainder verbatim, and any drift\nsilently rewrites content nobody asked you to touch — which the caller cannot\ndiff. Use the partial-edit tools instead:\n\n1. **Learn the anchors** — `cerefox_get_document(document_id, outline: true)`.\n   Returns heading paths, per-section sizes and the `content_hash`, without the\n   body. The paths it returns are exactly what `anchor_heading` accepts.\n2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;\n   `end_of_section` adds inside a named section. It is structurally incapable of\n   removing anything, so "I meant to append" cannot become "I replaced the file".\n3. **Look before you overwrite** — `cerefox_get_document(document_id,\n   section: "## Heading")` returns exactly the text a `replace_section` on that\n   anchor would destroy. The outline gives you a section\'s *size*, never its\n   *text*, so on a document you did not write yourself this is the difference\n   between a replace and a blind overwrite.\n4. **Change or remove** → `cerefox_edit`. Put changes that belong together in\n   ONE call: they apply atomically, so a table row and the total it feeds cannot\n   end up disagreeing. To change a single line, `replace_section` on its\n   smallest enclosing heading — that is the intended granularity, not a\n   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use\n   `rename_section`: it changes the heading text and leaves the body and\n   position alone.\n5. All of them require `expected_content_hash` and **have no last-write-wins**. A\n   conflict means someone else changed the document; re-read and decide, do not\n   force it.\n\n**A section runs to the next same-or-higher heading, or to the end of the\ndocument.** So `end_of_document` inserts land inside the *last* section, and\nreplacing or deleting that section removes them too. A large shrink in the\nresponse is your warning; `cerefox_list_versions` has the previous content.\n\n**When an anchor is ambiguous the tool refuses and hands you the options** — a\nrepeated heading returns the qualifying paths, and a section with both its own\ncontent and sub-sections returns both `section_part` choices. That is a\nrecoverable answer, not a failure: retry with what it gave you.\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 last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. 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. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **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`, …).\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_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\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_metadata` | `cerefox document set-metadata <id> --set key=value` (also `--remove key`, `--json \'{...}\'`, `--replace`) |\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\n## Timestamps are UTC\n\nEvery timestamp Cerefox returns — `created_at` on audit entries, version\nhistory, document metadata — is **UTC**, and now carries its `Z` marker so it\ncannot be mistaken for local time.\n\n**When you write a date into a document\'s CONTENT, use your own clock, not a\nCerefox timestamp.** These are different things: a timestamp records when the\nserver stored something; a date in a log entry or a heading is authored content\nand belongs to your timezone. An agent working a Pacific afternoon read\n`2026-08-11` from version history, wrote "8/11" into its entries, and put a\nday\'s work in the future — the timestamp was correct, and copying it into\ncontent was not.\n\nCerefox deliberately does not convert to local time on the API or MCP paths.\n"Local" has no server-side meaning: the remote MCP server runs in a cloud\nfunction whose local time *is* UTC, while a local MCP server runs in yours, so\nthe same document would report two different times depending on transport. The\nweb UI converts because a browser knows the viewer\'s timezone; nothing\nserver-side does.\n\n## Mistakes that have actually happened\n\nEach of these comes from a real agent session, and each is easy to make.\n\n- **`cerefox_ingest` always replaces the ENTIRE document.** Never a section.\n  Before sending, check that the tool name matches the intent: if the intent is\n  "change one section", the call is `cerefox_edit` with `replace_section`. A\n  section-sized edit sent as a full ingest truncated a 13,000-character index to\n  a single word. It was recovered from version history within the minute, but\n  only because it was noticed immediately.\n\n- **Do not include the anchor\'s own heading in your text.** `replace_section`\n  keeps the heading and `insert` places your text inside the section, so\n  including it produces two. This is now refused rather than silently applied,\n  but the shape is worth knowing: it happened twice in one session, the second\n  time while trying to repair the first. A *deeper* sub-heading inside your text\n  is fine.\n\n- **Content between sections belongs to the section ABOVE it.** A section runs\n  to the next heading of the same or higher level, so a `---` rule, a note, or\n  any trailing text sitting just above the next heading is part of the section\n  before it — even when it visually reads as belonging below. Replacing that\n  section takes it too. An agent hit exactly this: a `---` that separated two\n  major sections disappeared when the section above it was replaced. The write\n  was correct by the addressing rules; the surprise is that "the end of this\n  section" is further down the page than it looks. Note the loss warning will\n  not catch it if your replacement text is longer than what it replaced, since\n  there is then no net loss to report.\n\n- **To change only tags, use `cerefox_set_document_metadata`, never `cerefox_ingest`.**\n  Ingest replaces the whole document, so re-sending it to set one tag carries the\n  full transcription risk for no reason. The metadata tool merges: the keys you\n  pass are set, everything else is left alone, so you do not need to read the\n  document first and cannot drop a tag another agent set. Pass `null` as a value\n  to remove a key.\n\n- **Never partial-edit to fix a partial edit.** If a write leaves unexpected\n  structure, stop. Use `cerefox_list_versions`, retrieve the last good version,\n  and re-ingest cleanly. Repairing edits with more edits compounds the damage.\n\n- **A rejected batch is safe.** Operations in one `cerefox_edit` are\n  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a\n  retry, not data — so prefer one call for changes that belong together, and do\n  not split a batch to "make it more likely to succeed".\n\n- **Read before replacing.** `cerefox_get_document(section: "## Heading")`\n  returns exactly what a `replace_section` on that anchor would overwrite. Use it\n  for any section you did not write in this session. The outline gives a\n  section\'s *size*, never its *text*.\n\n- **Verify after writing** — read the result back before reporting success, and\n  report what the read actually shows.\n\n- **Partial edits cannot change a document\'s stored TITLE.** `rename_section`\n  changes a heading inside the content; the title is a separate field and still\n  needs `cerefox_ingest`.\n\n- **If a capability seems missing from one server, suspect your client first.**\n  Local and remote run the same code. **Every `cerefox_get_help()` response\n  begins with the server\'s version and the operations it registers** — you do\n  not need a special topic, and the *absence* of that block is itself an answer:\n  a server that does not print it predates v1.5.0. If that\n  disagrees with your tool list, the client is holding a list it fetched before\n  an upgrade — clients cache it at connect time. Ask the user to restart the\n  client. Do not record a capability difference between servers as a fact; every\n  such report so far has been a stale client.\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), `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_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part` |\n| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required) |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: \"## Heading\"` one section's text | `document_id` (required), `outline`, `section`, `section_part` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\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⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.",
+    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_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part` |\n| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required) |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: \"## Heading\"` one section's text | `document_id` (required), `outline`, `section`, `section_part` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\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_metadata` | Change tags WITHOUT resending content. **Merges** by default; a `null` value removes a key | `document_id`, `metadata` (required), `replace` (rare: set exactly this object), `author` |\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⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.",
     "Editing part of a document (prefer this over re-sending)": '## Editing part of a document (prefer this over re-sending)\n\n**Re-sending a whole document to change part of it is the main way agents lose\ndata.** You have to reproduce the untouched remainder verbatim, and any drift\nsilently rewrites content nobody asked you to touch — which the caller cannot\ndiff. Use the partial-edit tools instead:\n\n1. **Learn the anchors** — `cerefox_get_document(document_id, outline: true)`.\n   Returns heading paths, per-section sizes and the `content_hash`, without the\n   body. The paths it returns are exactly what `anchor_heading` accepts.\n2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;\n   `end_of_section` adds inside a named section. It is structurally incapable of\n   removing anything, so "I meant to append" cannot become "I replaced the file".\n3. **Look before you overwrite** — `cerefox_get_document(document_id,\n   section: "## Heading")` returns exactly the text a `replace_section` on that\n   anchor would destroy. The outline gives you a section\'s *size*, never its\n   *text*, so on a document you did not write yourself this is the difference\n   between a replace and a blind overwrite.\n4. **Change or remove** → `cerefox_edit`. Put changes that belong together in\n   ONE call: they apply atomically, so a table row and the total it feeds cannot\n   end up disagreeing. To change a single line, `replace_section` on its\n   smallest enclosing heading — that is the intended granularity, not a\n   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use\n   `rename_section`: it changes the heading text and leaves the body and\n   position alone.\n5. All of them require `expected_content_hash` and **have no last-write-wins**. A\n   conflict means someone else changed the document; re-read and decide, do not\n   force it.\n\n**A section runs to the next same-or-higher heading, or to the end of the\ndocument.** So `end_of_document` inserts land inside the *last* section, and\nreplacing or deleting that section removes them too. A large shrink in the\nresponse is your warning; `cerefox_list_versions` has the previous content.\n\n**When an anchor is ambiguous the tool refuses and hands you the options** — a\nrepeated heading returns the qualifying paths, and a section with both its own\ncontent and sub-sections returns both `section_part` choices. That is a\nrecoverable answer, not a failure: retry with what it gave you.',
     "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 last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. 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. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **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)
@@ -55539,7 +55539,7 @@ ingest(title="Same Title", content="...", document_id="abc123",
 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`, …).\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_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\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`, …).\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_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\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_metadata` | `cerefox document set-metadata <id> --set key=value` (also `--remove key`, `--json \'{...}\'`, `--replace`) |\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.',
     "Timestamps are UTC": `## Timestamps are UTC
 
 Every timestamp Cerefox returns — \`created_at\` on audit entries, version
@@ -55589,6 +55589,13 @@ Each of these comes from a real agent session, and each is easy to make.
   not catch it if your replacement text is longer than what it replaced, since
   there is then no net loss to report.
 
+- **To change only tags, use \`cerefox_set_document_metadata\`, never \`cerefox_ingest\`.**
+  Ingest replaces the whole document, so re-sending it to set one tag carries the
+  full transcription risk for no reason. The metadata tool merges: the keys you
+  pass are set, everything else is left alone, so you do not need to read the
+  document first and cannot drop a tag another agent set. Pass \`null\` as a value
+  to remove a key.
+
 - **Never partial-edit to fix a partial edit.** If a write leaves unexpected
   structure, stop. Use \`cerefox_list_versions\`, retrieve the last good version,
   and re-ingest cleanly. Repairing edits with more edits compounds the damage.
@@ -55611,8 +55618,10 @@ Each of these comes from a real agent session, and each is easy to make.
   needs \`cerefox_ingest\`.
 
 - **If a capability seems missing from one server, suspect your client first.**
-  Local and remote run the same code. Call \`cerefox_get_help(topic: "server")\`:
-  it reports the server's own version and the operations it registers. If that
+  Local and remote run the same code. **Every \`cerefox_get_help()\` response
+  begins with the server's version and the operations it registers** — you do
+  not need a special topic, and the *absence* of that block is itself an answer:
+  a server that does not print it predates v1.5.0. If that
   disagrees with your tool list, the client is holding a list it fetched before
   an upgrade — clients cache it at connect time. Ask the user to restart the
   client. Do not record a capability difference between servers as a fact; every
@@ -55674,13 +55683,21 @@ async function handler3(supabase, args, ctx) {
   const t = topic.toLowerCase();
   const matched = HELP_SECTION_HEADINGS.filter((h) => h.toLowerCase().includes(t));
   if (matched.length === 0) {
-    return `No help topic matched "${topic}".
+    return serverIdentity() + `
+
+---
+
+` + `No help topic matched "${topic}".
 
 ` + `Available topics:
 ` + HELP_SECTION_HEADINGS.map((h) => `  - ${h}`).join(`
 `) + "\n\nCall `cerefox_get_help()` with no topic for the full document.";
   }
-  return matched.map((h) => HELP_SECTIONS[h]).join(`
+  return serverIdentity() + `
+
+---
+
+` + matched.map((h) => HELP_SECTIONS[h]).join(`
 
 ---
 
@@ -56432,8 +56449,92 @@ var init_search = __esm(() => {
   };
 });
 
-// ../../_shared/mcp-tools/set-document-projects.ts
+// ../../_shared/mcp-tools/set-document-metadata.ts
 async function handler10(supabase, args, ctx) {
+  const document_id = args.document_id;
+  const metadata = args.metadata;
+  const replace = args.replace ?? false;
+  if (!document_id)
+    throw new McpInvalidParams("document_id is required");
+  if (metadata === undefined || metadata === null) {
+    throw new McpInvalidParams("metadata is required: an object of keys to set. Use null as a value to REMOVE a key.");
+  }
+  if (typeof metadata !== "object" || Array.isArray(metadata)) {
+    throw new McpInvalidParams("metadata must be an object, not an array or scalar");
+  }
+  if (Object.keys(metadata).length === 0 && !replace) {
+    throw new McpInvalidParams("metadata is empty, which would change nothing. To clear all metadata pass replace: true with {}.");
+  }
+  const author = args.author ?? args.requestor;
+  const authorType = ctx.accessPath === "cli" ? "user" : "agent";
+  const { data, error: error2 } = await supabase.rpc("cerefox_set_document_metadata", {
+    p_document_id: document_id,
+    p_metadata: metadata,
+    p_replace: replace,
+    p_author: author ?? "unknown",
+    p_author_type: authorType
+  });
+  if (error2)
+    throw new Error(`RPC error: ${error2.message}`);
+  const row = data?.[0];
+  if (!row)
+    throw new Error("cerefox_set_document_metadata returned no data");
+  logUsage(supabase, {
+    operation: "update_metadata",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor,
+    document_id,
+    result_count: 1
+  });
+  const set = row.keys_set ?? 0;
+  const removed = row.keys_removed ?? 0;
+  const summary = set === 0 && removed === 0 ? "No change: every key already held that value." : `${set} key(s) set, ${removed} removed.`;
+  return `Metadata ${replace ? "replaced" : "merged"} on ${document_id}. ${summary}
+` + `Now: ${JSON.stringify(row.metadata ?? {})}
+` + `Content untouched — no new version, no re-embedding.`;
+}
+var setDocumentMetadataTool;
+var init_set_document_metadata = __esm(() => {
+  init_types3();
+  setDocumentMetadataTool = {
+    name: "cerefox_set_document_metadata",
+    description: `Change a document's metadata WITHOUT resending its content. MERGES by default: the keys you pass are set, every other key is left alone — so you do not need to read the document first, and you cannot accidentally drop tags another agent set. To REMOVE a key, pass it with a null value ({"stale_key": null}). Pass replace: true to set the metadata to exactly the object given, discarding everything else (rare; the same destructive contract as cerefox_set_document_projects). Content, chunks and embeddings are untouched and no new version is created. Use this instead of cerefox_ingest whenever only the tags are changing.`,
+    annotations: {
+      title: "Set document metadata",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    inputSchema: {
+      type: "object",
+      required: ["document_id", "metadata"],
+      properties: {
+        document_id: { type: "string", description: "UUID of the document to tag." },
+        metadata: {
+          type: "object",
+          description: 'Keys to set. Values are JSON strings by convention (a metadata_filter matches JSONB as strings, so a boolean true will not match "true"). A null value REMOVES that key. Keys you do not mention are left alone unless replace is true.'
+        },
+        replace: {
+          type: "boolean",
+          description: "Set the metadata to EXACTLY this object, discarding any key not listed. Defaults to false (merge). Use only when you mean to reset a document's tags wholesale."
+        },
+        author: {
+          type: "string",
+          description: "Who is making this change. Recorded in the audit log."
+        },
+        requestor: {
+          type: "string",
+          description: "Name of the agent or user making this request. Recorded in the usage log."
+        }
+      }
+    },
+    handler: handler10
+  };
+});
+
+// ../../_shared/mcp-tools/set-document-projects.ts
+async function handler11(supabase, args, ctx) {
   const document_id = args.document_id?.trim();
   const project_names_raw = args.project_names;
   const author = args.author ?? "mcp-agent";
@@ -56494,7 +56595,7 @@ var init_set_document_projects = __esm(() => {
         }
       }
     },
-    handler: handler10
+    handler: handler11
   };
 });
 
@@ -56524,6 +56625,7 @@ var init_mcp_tools = __esm(() => {
   init_list_versions();
   init_metadata_search();
   init_search();
+  init_set_document_metadata();
   init_set_document_projects();
   init_types3();
   init_types3();
@@ -56537,6 +56639,7 @@ var init_mcp_tools = __esm(() => {
     metadataSearchTool,
     listMetadataKeysTool,
     listProjectsTool,
+    setDocumentMetadataTool,
     setDocumentProjectsTool,
     auditLogTool,
     setRelationTool,
@@ -57377,11 +57480,11 @@ async function runSyncSelfDocs(options = {}) {
     printTable(outcomes.filter((o) => o.status === "error").map((o) => ({ topic: o.topic, error: o.detail.slice(0, 100) })));
   }
 }
-async function action20(options) {
+async function action21(options) {
   await runSyncSelfDocs(options);
 }
 function registerSyncSelfDocs(program2) {
-  program2.command("sync-self-docs").description("Ingest bundled Cerefox docs under the _cerefox-self-docs project.").option("--dry-run", "List what would be ingested without writing.").option("--project <name>", "Override the target project name.", "_cerefox-self-docs").action(action20);
+  program2.command("sync-self-docs").description("Ingest bundled Cerefox docs under the _cerefox-self-docs project.").option("--dry-run", "List what would be ingested without writing.").option("--project <name>", "Override the target project name.", "_cerefox-self-docs").action(action21);
 }
 var init_sync_self_docs = __esm(() => {
   init_cli_core();
@@ -62610,25 +62713,25 @@ class Protocol {
     const error3 = McpError.fromError(ErrorCode.ConnectionClosed, "Connection closed");
     this._transport = undefined;
     this.onclose?.();
-    for (const handler11 of responseHandlers.values()) {
-      handler11(error3);
+    for (const handler12 of responseHandlers.values()) {
+      handler12(error3);
     }
   }
   _onerror(error3) {
     this.onerror?.(error3);
   }
   _onnotification(notification) {
-    const handler11 = this._notificationHandlers.get(notification.method) ?? this.fallbackNotificationHandler;
-    if (handler11 === undefined) {
+    const handler12 = this._notificationHandlers.get(notification.method) ?? this.fallbackNotificationHandler;
+    if (handler12 === undefined) {
       return;
     }
-    Promise.resolve().then(() => handler11(notification)).catch((error3) => this._onerror(new Error(`Uncaught error in notification handler: ${error3}`)));
+    Promise.resolve().then(() => handler12(notification)).catch((error3) => this._onerror(new Error(`Uncaught error in notification handler: ${error3}`)));
   }
   _onrequest(request, extra) {
-    const handler11 = this._requestHandlers.get(request.method) ?? this.fallbackRequestHandler;
+    const handler12 = this._requestHandlers.get(request.method) ?? this.fallbackRequestHandler;
     const capturedTransport = this._transport;
     const relatedTaskId = request.params?._meta?.[RELATED_TASK_META_KEY]?.taskId;
-    if (handler11 === undefined) {
+    if (handler12 === undefined) {
       const errorResponse = {
         jsonrpc: "2.0",
         id: request.id,
@@ -62692,7 +62795,7 @@ class Protocol {
       if (taskCreationParams) {
         this.assertTaskHandlerCapability(request.method);
       }
-    }).then(() => handler11(request, fullExtra)).then(async (result) => {
+    }).then(() => handler12(request, fullExtra)).then(async (result) => {
       if (abortController.signal.aborted) {
         return;
       }
@@ -62741,8 +62844,8 @@ class Protocol {
   _onprogress(notification) {
     const { progressToken, ...params } = notification.params;
     const messageId = Number(progressToken);
-    const handler11 = this._progressHandlers.get(messageId);
-    if (!handler11) {
+    const handler12 = this._progressHandlers.get(messageId);
+    if (!handler12) {
       this._onerror(new Error(`Received a progress notification for an unknown token: ${JSON.stringify(notification)}`));
       return;
     }
@@ -62759,7 +62862,7 @@ class Protocol {
         return;
       }
     }
-    handler11(params);
+    handler12(params);
   }
   _onresponse(response) {
     const messageId = Number(response.id);
@@ -62774,8 +62877,8 @@ class Protocol {
       }
       return;
     }
-    const handler11 = this._responseHandlers.get(messageId);
-    if (handler11 === undefined) {
+    const handler12 = this._responseHandlers.get(messageId);
+    if (handler12 === undefined) {
       this._onerror(new Error(`Received a response for an unknown message ID: ${JSON.stringify(response)}`));
       return;
     }
@@ -62796,10 +62899,10 @@ class Protocol {
       this._progressHandlers.delete(messageId);
     }
     if (isJSONRPCResultResponse(response)) {
-      handler11(response);
+      handler12(response);
     } else {
       const error3 = McpError.fromError(response.error.code, response.error.message, response.error.data);
-      handler11(error3);
+      handler12(error3);
     }
   }
   get transport() {
@@ -62962,9 +63065,9 @@ class Protocol {
       const relatedTaskId = relatedTask?.taskId;
       if (relatedTaskId) {
         const responseResolver = (response) => {
-          const handler11 = this._responseHandlers.get(messageId);
-          if (handler11) {
-            handler11(response);
+          const handler12 = this._responseHandlers.get(messageId);
+          if (handler12) {
+            handler12(response);
           } else {
             this._onerror(new Error(`Response handler missing for side-channeled request ${messageId}`));
           }
@@ -63073,12 +63176,12 @@ class Protocol {
     }
     await this._transport.send(jsonrpcNotification, options);
   }
-  setRequestHandler(requestSchema, handler11) {
+  setRequestHandler(requestSchema, handler12) {
     const method = getMethodLiteral(requestSchema);
     this.assertRequestHandlerCapability(method);
     this._requestHandlers.set(method, (request, extra) => {
       const parsed = parseWithCompat(requestSchema, request);
-      return Promise.resolve(handler11(parsed, extra));
+      return Promise.resolve(handler12(parsed, extra));
     });
   }
   removeRequestHandler(method) {
@@ -63089,11 +63192,11 @@ class Protocol {
       throw new Error(`A request handler for ${method} already exists, which would be overridden`);
     }
   }
-  setNotificationHandler(notificationSchema, handler11) {
+  setNotificationHandler(notificationSchema, handler12) {
     const method = getMethodLiteral(notificationSchema);
     this._notificationHandlers.set(method, (notification) => {
       const parsed = parseWithCompat(notificationSchema, notification);
-      return Promise.resolve(handler11(parsed));
+      return Promise.resolve(handler12(parsed));
     });
   }
   removeNotificationHandler(method) {
@@ -70035,7 +70138,7 @@ var init_server2 = __esm(() => {
       }
       this._capabilities = mergeCapabilities(this._capabilities, capabilities);
     }
-    setRequestHandler(requestSchema, handler11) {
+    setRequestHandler(requestSchema, handler12) {
       const shape = getObjectShape(requestSchema);
       const methodSchema = shape?.method;
       if (!methodSchema) {
@@ -70054,7 +70157,7 @@ var init_server2 = __esm(() => {
             throw new McpError(ErrorCode.InvalidParams, `Invalid tools/call request: ${errorMessage}`);
           }
           const { params } = validatedRequest.data;
-          const result = await Promise.resolve(handler11(request, extra));
+          const result = await Promise.resolve(handler12(request, extra));
           if (params.task) {
             const taskValidationResult = safeParse2(CreateTaskResultSchema, result);
             if (!taskValidationResult.success) {
@@ -70072,7 +70175,7 @@ var init_server2 = __esm(() => {
         };
         return super.setRequestHandler(requestSchema, wrappedHandler);
       }
-      return super.setRequestHandler(requestSchema, handler11);
+      return super.setRequestHandler(requestSchema, handler12);
     }
     assertCapabilityForMethod(method) {
       switch (method) {
@@ -73024,11 +73127,89 @@ function registerDocumentRestore(parent) {
   parent.command("restore").description("Restore a soft-deleted document from the trash (inverse of `document delete`).").argument("<document-id>", "UUID of the soft-deleted document.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action11);
 }
 
+// src/cli/commands/document-set-metadata.ts
+init_cli_core();
+init_client();
+async function action12(documentId, options) {
+  const patch = {};
+  if (options.json) {
+    let parsed;
+    try {
+      parsed = JSON.parse(options.json);
+    } catch (err) {
+      throw userError(`--json is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw userError(`--json must be a JSON object, e.g. '{"type":"note","stale":null}'`);
+    }
+    Object.assign(patch, parsed);
+  }
+  for (const pair of options.set ?? []) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) {
+      throw userError(`--set expects key=value, got ${JSON.stringify(pair)}`);
+    }
+    const key = pair.slice(0, eq);
+    const raw = pair.slice(eq + 1);
+    if (raw === "null") {
+      throw userError(`--set ${key}=null is ambiguous: over MCP a null REMOVES the key, but on the ` + `command line it could mean the literal text "null". ` + `Use --remove ${key} to delete it, or --json '{"${key}":"null"}' to store the word.`);
+    }
+    let value = raw;
+    if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) {
+      try {
+        value = JSON.parse(raw);
+      } catch {}
+    }
+    patch[key] = value;
+  }
+  for (const key of options.remove ?? []) {
+    patch[key] = null;
+  }
+  if (Object.keys(patch).length === 0 && !options.replace) {
+    throw userError("Nothing to change. Pass --set key=value, --remove key, or --json '{...}'. " + "To clear all metadata use --replace --json '{}'.");
+  }
+  const client = getClient();
+  let rows;
+  try {
+    rows = await client.rpc("cerefox_set_document_metadata", {
+      p_document_id: documentId,
+      p_metadata: patch,
+      p_replace: Boolean(options.replace),
+      p_author: options.author ?? "cli-user",
+      p_author_type: options.authorType === "agent" ? "agent" : "user"
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/not found/i.test(msg))
+      throw notFound(`Document ${documentId} not found (or is deleted).`);
+    throw systemError(`Could not set metadata: ${msg}`);
+  }
+  if (!rows || rows.length === 0) {
+    throw systemError("cerefox_set_document_metadata returned no data.", "Verify the RPC is deployed: `cerefox server deploy`.");
+  }
+  const row = rows[0];
+  if (options.jsonOut) {
+    printJson(row);
+    return;
+  }
+  const verb = options.replace ? "Replaced" : "Merged";
+  if (row.keys_set === 0 && row.keys_removed === 0) {
+    println(c.green(`✓ ${verb} metadata on ${documentId} — no change (every key already held that value).`));
+  } else {
+    println(c.green(`✓ ${verb} metadata on ${documentId}: ${row.keys_set} key(s) set, ${row.keys_removed} removed.`));
+  }
+  println(c.dim(`  Now: ${JSON.stringify(row.metadata ?? {})}`));
+  println(c.dim("  Content untouched — no new version, no re-embedding."));
+}
+function registerDocumentSetMetadata(parent) {
+  parent.command("set-metadata").description("Change a document's metadata without resending its content (merges by default).").argument("<document-id>", "UUID of the document.").option("-s, --set <key=value...>", "Set a key. Repeatable. Values are stored as JSON strings; quote to force JSON parsing.").option("-r, --remove <key...>", "Remove a key. Repeatable. (Sends a JSON null.)").option("--json <object>", "A JSON object of keys to set; a null value removes that key.").option("--replace", "Set the metadata to EXACTLY what was given, discarding every key not listed. Default is merge.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("--json-out", "Emit the result as JSON.").action(action12);
+}
+
 // src/cli/commands/document-set-projects.ts
 init_cli_core();
 init__projects();
 init_client();
-async function action12(documentId, projectNames, options) {
+async function action13(documentId, projectNames, options) {
   const names = projectNames ?? [];
   if (options.clear && names.length > 0) {
     throw userError("Pass either project names or --clear, not both.", "Use --clear on its own to remove the document from all projects.");
@@ -73058,7 +73239,7 @@ async function action12(documentId, projectNames, options) {
   println(c.dim("  This REPLACED the previous set — any project not listed is no longer associated."));
 }
 function registerDocumentSetProjects(parent) {
-  parent.command("set-projects").description("Replace a document's project memberships with exactly the given set (or --clear to remove all).").argument("<document-id>", "UUID of the document.").argument("[project-names...]", "Project names to set (created if missing). Omit and pass --clear to remove all.").option("--clear", "Remove the document from all projects.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action12);
+  parent.command("set-projects").description("Replace a document's project memberships with exactly the given set (or --clear to remove all).").argument("<document-id>", "UUID of the document.").argument("[project-names...]", "Project names to set (created if missing). Omit and pass --clear to remove all.").option("--clear", "Remove the document from all projects.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action13);
 }
 
 // src/cli/commands/guides.ts
@@ -73108,7 +73289,7 @@ function registerGuides(parent) {
 // src/cli/commands/project-create.ts
 init_cli_core();
 init_client();
-async function action13(name, options) {
+async function action14(name, options) {
   const trimmed = name.trim();
   if (!trimmed)
     throw userError("Project name is required.");
@@ -73120,14 +73301,14 @@ async function action13(name, options) {
   println(c.green(`✓ Created project "${data.name}" (id: ${data.id}).`));
 }
 function registerProjectCreate(parent) {
-  parent.command("create").description("Create a new (empty) project.").argument("<name>", "Project name (must be unique).").option("--description <text>", "Optional project description.").action(action13);
+  parent.command("create").description("Create a new (empty) project.").argument("<name>", "Project name (must be unique).").option("--description <text>", "Optional project description.").action(action14);
 }
 
 // src/cli/commands/project-edit.ts
 init_cli_core();
 init_client();
 var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-async function action14(target, options) {
+async function action15(target, options) {
   const update = {};
   if (options.name !== undefined) {
     const n = options.name.trim();
@@ -73154,7 +73335,7 @@ async function action14(target, options) {
   println(c.green(`✓ Updated project "${data.name}" (id: ${data.id}).`));
 }
 function registerProjectEdit(parent) {
-  parent.command("edit").description("Rename a project and/or change its description.").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--name <new-name>", "New project name.").option("--description <text>", "New project description.").action(action14);
+  parent.command("edit").description("Rename a project and/or change its description.").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--name <new-name>", "New project name.").option("--description <text>", "New project description.").action(action15);
 }
 
 // src/cli/commands/version-archive.ts
@@ -77261,7 +77442,7 @@ function symbol(status) {
       return cErr.dim("ℹ");
   }
 }
-async function action15(options) {
+async function action16(options) {
   const useSpinner = !options.json && process.stderr.isTTY;
   const spinner = useSpinner ? ora({ text: "Starting checks…", spinner: "dots", stream: process.stderr }).start() : null;
   const results = await runAllChecks({
@@ -77325,13 +77506,13 @@ async function action15(options) {
     process.exit(1);
 }
 function registerDoctor(program2) {
-  program2.command("doctor").description("Run diagnostic checks against the installed Cerefox.").option("--json", "Emit machine-readable JSON (no colours, structured output).").option("--strict", "Exit non-zero when any check warns (default: only errors fail).").action(action15);
+  program2.command("doctor").description("Run diagnostic checks against the installed Cerefox.").option("--json", "Emit machine-readable JSON (no colours, structured output).").option("--strict", "Exit non-zero when any check warns (default: only errors fail).").action(action16);
 }
 
 // src/cli/commands/get-audit-log.ts
 init_cli_core();
 init_client();
-async function action16(options) {
+async function action17(options) {
   const limit = parsePositiveInt(options.limit, "--limit", 50);
   const client = getClient();
   const data = await client.rpc("cerefox_list_audit_entries", {
@@ -77369,7 +77550,7 @@ async function action16(options) {
   })));
 }
 function registerGetAuditLog(program2) {
-  program2.command("get-audit-log").description("Query the audit log with optional filters.").option("-d, --document-id <uuid>", "Filter by document.").option("-a, --author <name>", "Filter by author.").option("-o, --operation <type>", "Filter by operation: create, update-content, update-metadata, delete, restore.").option("--since <iso>", "Lower-bound ISO timestamp.").option("--until <iso>", "Upper-bound ISO timestamp.").option("-l, --limit <n>", "Maximum entries (max 200).", "50").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action16);
+  program2.command("get-audit-log").description("Query the audit log with optional filters.").option("-d, --document-id <uuid>", "Filter by document.").option("-a, --author <name>", "Filter by author.").option("-o, --operation <type>", "Filter by operation: create, update-content, update-metadata, delete, restore.").option("--since <iso>", "Lower-bound ISO timestamp.").option("--until <iso>", "Upper-bound ISO timestamp.").option("-l, --limit <n>", "Maximum entries (max 200).", "50").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action17);
 }
 
 // src/cli/commands/relation.ts
@@ -77505,7 +77686,7 @@ init_cli_core();
 init_cli_core();
 init_partial_edits();
 init_client();
-async function action17(documentId, options) {
+async function action18(documentId, options) {
   const section = (options.section ?? "").trim() || null;
   if (section && options.outline) {
     throw userError("Pass either --outline (the whole structure) or --section (one section's text), not both.");
@@ -77602,7 +77783,7 @@ async function action17(documentId, options) {
   println(doc.full_content);
 }
 function registerGetDoc(program2) {
-  program2.command("get-doc").description("Retrieve the full content of a document by ID.").argument("<document-id>", "UUID of the document.").option("--version-id <uuid>", "Specific archived version (default: current).").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").option("--outline", "Show the heading structure, per-section sizes and content_hash instead of the content. Cheap, and the paths are the anchors the edit commands take.").option("--section <anchor>", "Show ONE section's text instead of the whole document: exactly what a replace_section on this anchor would overwrite. Pass the bare heading line when it is unique, or the full ' > ' path from --outline when it repeats.").option("--section-part <part>", "own_body | subtree — only when the target section has child sections, where 'the end' means two different places. You are told (with both options) whenever it is needed.").action(action17);
+  program2.command("get-doc").description("Retrieve the full content of a document by ID.").argument("<document-id>", "UUID of the document.").option("--version-id <uuid>", "Specific archived version (default: current).").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").option("--outline", "Show the heading structure, per-section sizes and content_hash instead of the content. Cheap, and the paths are the anchors the edit commands take.").option("--section <anchor>", "Show ONE section's text instead of the whole document: exactly what a replace_section on this anchor would overwrite. Pass the bare heading line when it is unique, or the full ' > ' path from --outline when it repeats.").option("--section-part <part>", "own_body | subtree — only when the target section has child sections, where 'the end' means two different places. You are told (with both options) whenever it is needed.").action(action18);
 }
 
 // src/cli/commands/ingest.ts
@@ -78236,7 +78417,7 @@ async function readContent(path, paste) {
   const titleFromPath = basename2(path, extname3(path));
   return { content, titleFromPath };
 }
-async function action18(path, options) {
+async function action19(path, options) {
   const { content, titleFromPath } = await readContent(path, Boolean(options.paste));
   const updatingById = Boolean(options.documentId);
   let title = options.title ?? (updatingById ? null : titleFromPath);
@@ -78327,7 +78508,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. Omit it on an update and the document keeps the source it already has (#193); omit it on a create and it is recorded as "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);
+  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. Omit it on an update and the document keeps the source it already has (#193); omit it on a create and it is recorded as "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(action19);
 }
 
 // src/cli/commands/document-partial-edit.ts
@@ -78430,7 +78611,7 @@ function walk(dir, extensions) {
   }
   return files;
 }
-async function action19(dir, options) {
+async function action20(dir, options) {
   const extensions = new Set((options.extensions ?? ".md,.txt").split(",").map((e) => e.trim().toLowerCase()).map((e) => e.startsWith(".") ? e : "." + e).filter((e) => e.length > 0));
   const files = walk(dir, extensions);
   if (files.length === 0) {
@@ -78505,7 +78686,7 @@ async function action19(dir, options) {
   }
 }
 function registerIngestDir(program2) {
-  program2.command("ingest-dir").description("Recursively ingest a directory of markdown / text files.").argument("<dir>", "Root directory to walk.").option("-p, --project-name <name>", "Project membership for all ingested docs.").option("-m, --metadata <json>", "JSON metadata applied to every doc.").option("--source <label>", 'Origin label. Omit it and each matched document keeps the source it already has (#193); newly created ones are recorded as "cli".').option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("-e, --extensions <list>", "Comma-separated file extensions to ingest.", ".md,.txt").action(action19);
+  program2.command("ingest-dir").description("Recursively ingest a directory of markdown / text files.").argument("<dir>", "Root directory to walk.").option("-p, --project-name <name>", "Project membership for all ingested docs.").option("-m, --metadata <json>", "JSON metadata applied to every doc.").option("--source <label>", 'Origin label. Omit it and each matched document keeps the source it already has (#193); newly created ones are recorded as "cli".').option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("-e, --extensions <list>", "Comma-separated file extensions to ingest.", ".md,.txt").action(action20);
 }
 
 // src/cli/commands/init.ts
@@ -78836,7 +79017,7 @@ function writeAnswersTo(target, answers) {
     }
   }
 }
-async function action21(options) {
+async function action22(options) {
   const homeEnv = join11(homedir7(), USER_STATE_DIR_NAME, ".env");
   const cwdEnv = join11(process.cwd(), ".env");
   const explicitDir = (process.env.CEREFOX_CONFIG_DIR ?? "").trim();
@@ -78945,13 +79126,13 @@ async function action21(options) {
   await postWriteLifecycle(target, options);
 }
 function registerInit(program2) {
-  program2.command("init").description("Interactive first-run setup (config, schema deploy stub, optional MCP wiring).").option("-c, --config <file>", "Non-interactive mode: read answers from a JSON file.").option("--force", "Overwrite existing configuration without prompting.").option("--skip-schema", "Skip the schema deploy step.").option("--skip-self-docs", "Skip the bundled self-doc ingest.").option("--skip-agent-config", "Skip the optional MCP agent wiring.").action(action21);
+  program2.command("init").description("Interactive first-run setup (config, schema deploy stub, optional MCP wiring).").option("-c, --config <file>", "Non-interactive mode: read answers from a JSON file.").option("--force", "Overwrite existing configuration without prompting.").option("--skip-schema", "Skip the schema deploy step.").option("--skip-self-docs", "Skip the bundled self-doc ingest.").option("--skip-agent-config", "Skip the optional MCP agent wiring.").action(action22);
 }
 
 // src/cli/commands/list-docs.ts
 init_cli_core();
 init_client();
-async function action22(options) {
+async function action23(options) {
   const deleted = !!options.deleted;
   const limit = parsePositiveInt(options.limit, "--limit", 100);
   const client = getClient();
@@ -79007,13 +79188,13 @@ async function action22(options) {
   }));
 }
 function registerListDocs(program2) {
-  program2.command("list-docs").description("List documents in the knowledge base.").option("-p, --project <name>", "Filter to a specific project.").option("-l, --limit <n>", "Maximum docs to return.", "100").option("--deleted", "List soft-deleted (trashed) documents instead of active ones.").option("--json", "Emit machine-readable JSON.").action(action22);
+  program2.command("list-docs").description("List documents in the knowledge base.").option("-p, --project <name>", "Filter to a specific project.").option("-l, --limit <n>", "Maximum docs to return.", "100").option("--deleted", "List soft-deleted (trashed) documents instead of active ones.").option("--json", "Emit machine-readable JSON.").action(action23);
 }
 
 // src/cli/commands/list-metadata-keys.ts
 init_cli_core();
 init_client();
-async function action23(options) {
+async function action24(options) {
   const client = getClient();
   const data = await client.rpc("cerefox_list_metadata_keys");
   if (data === null) {
@@ -79041,13 +79222,13 @@ async function action23(options) {
   })));
 }
 function registerListMetadataKeys(program2) {
-  program2.command("list-metadata-keys").description("List all metadata keys with document counts and example values.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action23);
+  program2.command("list-metadata-keys").description("List all metadata keys with document counts and example values.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action24);
 }
 
 // src/cli/commands/list-projects.ts
 init_cli_core();
 init_client();
-async function action24(options) {
+async function action25(options) {
   const client = getClient();
   const { data, error: error2 } = await client.raw.from("cerefox_projects").select("id, name, description, created_at").order("name", { ascending: true });
   if (error2) {
@@ -79076,13 +79257,13 @@ async function action24(options) {
   })), "(no projects)");
 }
 function registerListProjects(program2) {
-  program2.command("list-projects").description("List all projects in the knowledge base.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action24);
+  program2.command("list-projects").description("List all projects in the knowledge base.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action25);
 }
 
 // src/cli/commands/list-versions.ts
 init_cli_core();
 init_client();
-async function action25(documentId, options) {
+async function action26(documentId, options) {
   const client = getClient();
   const data = await client.rpc("cerefox_list_document_versions", {
     p_document_id: documentId
@@ -79123,7 +79304,7 @@ async function action25(documentId, options) {
   })));
 }
 function registerListVersions(program2) {
-  program2.command("list-versions").description("List archived versions of a document.").argument("<document-id>", "UUID of the document.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action25);
+  program2.command("list-versions").description("List archived versions of a document.").argument("<document-id>", "UUID of the document.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action26);
 }
 
 // src/cli/commands/mcp.ts
@@ -79155,7 +79336,7 @@ function registerEmbedderWarmup(program2) {
 // src/cli/commands/metadata-search.ts
 init_cli_core();
 init_client();
-async function action26(options) {
+async function action27(options) {
   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).`);
@@ -79218,7 +79399,7 @@ async function action26(options) {
   }
 }
 function registerMetadataSearch(program2) {
-  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);
+  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(action27);
 }
 
 // src/cli/commands/reindex.ts
@@ -79244,7 +79425,7 @@ function warnLargeBulkWrite(opts) {
 }
 
 // src/cli/commands/reindex.ts
-async function action27(options) {
+async function action28(options) {
   const settings = loadSettings();
   if (!settings.supabaseUrl || !settings.supabaseKey) {
     throw userError("Supabase credentials not configured — run `cerefox init` first.");
@@ -79334,7 +79515,7 @@ ${c2.content}`;
   }
 }
 function registerReindex(program2) {
-  program2.command("reindex").description("Re-embed existing document chunks (v0.7+).").option("--all", "Reindex every chunk regardless of embedder.").option("--batch <n>", "Chunks per OpenAI batch call. Capped at 96 internally.", "32").option("--dry-run", "Show counts without re-embedding.").option("-i, --document-id <uuid>", "Limit reindex to a single document.").action(action27);
+  program2.command("reindex").description("Re-embed existing document chunks (v0.7+).").option("--all", "Reindex every chunk regardless of embedder.").option("--batch <n>", "Chunks per OpenAI batch call. Capped at 96 internally.", "32").option("--dry-run", "Show counts without re-embedding.").option("-i, --document-id <uuid>", "Limit reindex to a single document.").action(action28);
 }
 
 // src/cli/commands/migrate-format.ts
@@ -79342,7 +79523,7 @@ init_cli_core();
 init_config();
 init_client();
 var CURRENT_FORMAT = 2;
-async function action28(options) {
+async function action29(options) {
   const settings = loadSettings();
   const client = getClient();
   const supabase = client.raw;
@@ -79469,7 +79650,7 @@ async function action28(options) {
   }
 }
 function registerMigrateFormat(program2) {
-  program2.command("migrate-format").description("Convert legacy-format documents to the current chunk format (re-chunks + re-embeds).").option("--dry-run", "Report how many documents would be converted; write nothing.").option("-l, --limit <n>", "Convert at most N documents (re-run to continue).").option("--document-id <uuid>", "Convert a single document.").option("--author <name>", "Recorded in the audit log for each conversion.").action(action28);
+  program2.command("migrate-format").description("Convert legacy-format documents to the current chunk format (re-chunks + re-embeds).").option("--dry-run", "Report how many documents would be converted; write nothing.").option("-l, --limit <n>", "Convert at most N documents (re-run to continue).").option("--document-id <uuid>", "Convert a single document.").option("--author <name>", "Recorded in the audit log for each conversion.").action(action29);
 }
 
 // src/cli/commands/restore.ts
@@ -79499,7 +79680,7 @@ function resolveBackupFile(target) {
   }
   return join12(path, candidates[0].name);
 }
-async function action29(target, options) {
+async function action30(target, options) {
   const file = resolveBackupFile(target);
   let payload;
   try {
@@ -79634,7 +79815,7 @@ async function action29(target, options) {
   }
 }
 function registerRestore(program2) {
-  program2.command("restore").description("Restore a JSON-snapshot backup into the knowledge base.").argument("<snapshot>", "Backup file (or directory; most recent is picked) produced by `cerefox backup`.").option("--dry-run", "Print what would be restored without writing.").option("-p, --project-name <name>", "Reserved for future use; currently ignored. Project memberships are restored from the backup itself (format 2+).").action(action29);
+  program2.command("restore").description("Restore a JSON-snapshot backup into the knowledge base.").argument("<snapshot>", "Backup file (or directory; most recent is picked) produced by `cerefox backup`.").option("--dry-run", "Print what would be restored without writing.").option("-p, --project-name <name>", "Reserved for future use; currently ignored. Project memberships are restored from the backup itself (format 2+).").action(action30);
 }
 
 // src/cli/commands/search.ts
@@ -79659,7 +79840,7 @@ async function embedQuery(query) {
 }
 
 // src/cli/commands/search.ts
-async function action30(query, options) {
+async function action31(query, options) {
   if (!query || query.trim() === "") {
     throw userError("Empty query.");
   }
@@ -79825,7 +80006,7 @@ async function action30(query, options) {
   }
 }
 function registerSearch(program2) {
-  program2.command("search").description("Search the knowledge base (hybrid FTS + semantic).").argument("<query>", "Natural-language search query.").option("-c, --match-count <n>", "Maximum number of documents to return.", "5").option("-p, --project-name <name>", "Filter results to a specific project.").option("-f, --metadata-filter <json>", "JSON containment filter; only docs whose metadata contains ALL pairs are returned.").option("--mode <mode>", "Search mode: docs (default), hybrid, fts.", "docs").option("--alpha <float>", "Semantic weight 0..1 (default: CEREFOX_SEARCH_ALPHA; else 0.7).").option("--min-score <float>", "Minimum cosine similarity threshold (default: CEREFOX_MIN_SEARCH_SCORE; else 0.5, or 0.6 with the local embedder).").option("--min-term-coverage <float>", "OR-fallback keyword matches must cover at least this fraction of the query's meaningful terms to count as confident hits (default: CEREFOX_MIN_TERM_COVERAGE; else the server default 0.5; needs schema ≥ 0.9.1).").option("--max-bytes <n>", "Response size budget in bytes (default: CEREFOX_MAX_RESPONSE_BYTES or 200000).").option("-r, --requestor <name>", "Agent / user name (recorded in usage log).").option("--json", "Emit machine-readable JSON instead of the default text.").option("--only-metadata", "List matching docs (id, score, chunks, chars, partial/full) WITHOUT their content — like the web UI's collapsed result list. Grab a [id:…] then `cerefox document get <id>`.").action(action30);
+  program2.command("search").description("Search the knowledge base (hybrid FTS + semantic).").argument("<query>", "Natural-language search query.").option("-c, --match-count <n>", "Maximum number of documents to return.", "5").option("-p, --project-name <name>", "Filter results to a specific project.").option("-f, --metadata-filter <json>", "JSON containment filter; only docs whose metadata contains ALL pairs are returned.").option("--mode <mode>", "Search mode: docs (default), hybrid, fts.", "docs").option("--alpha <float>", "Semantic weight 0..1 (default: CEREFOX_SEARCH_ALPHA; else 0.7).").option("--min-score <float>", "Minimum cosine similarity threshold (default: CEREFOX_MIN_SEARCH_SCORE; else 0.5, or 0.6 with the local embedder).").option("--min-term-coverage <float>", "OR-fallback keyword matches must cover at least this fraction of the query's meaningful terms to count as confident hits (default: CEREFOX_MIN_TERM_COVERAGE; else the server default 0.5; needs schema ≥ 0.9.1).").option("--max-bytes <n>", "Response size budget in bytes (default: CEREFOX_MAX_RESPONSE_BYTES or 200000).").option("-r, --requestor <name>", "Agent / user name (recorded in usage log).").option("--json", "Emit machine-readable JSON instead of the default text.").option("--only-metadata", "List matching docs (id, score, chunks, chars, partial/full) WITHOUT their content — like the web UI's collapsed result list. Grab a [id:…] then `cerefox document get <id>`.").action(action31);
 }
 
 // src/cli/commands/self-update.ts
@@ -79872,7 +80053,7 @@ async function fetchLatestVersion() {
   }
   return body.version;
 }
-async function action31(options) {
+async function action32(options) {
   let target;
   try {
     target = options.version ?? await fetchLatestVersion();
@@ -79925,7 +80106,7 @@ async function action31(options) {
 }
 function registerSelfUpdate(program2) {
   const desc = "Upgrade Cerefox in place. Alias: `cerefox upgrade`.";
-  const declaration = (cmd) => cmd.description(desc).option("--check", "Print current vs latest; do nothing.").option("--yes", "Non-interactive (skip confirmation).").option("--version <version>", "Pin a specific version (e.g. 0.5.1 or 0.6.0-rc.1).").action(action31);
+  const declaration = (cmd) => cmd.description(desc).option("--check", "Print current vs latest; do nothing.").option("--yes", "Non-interactive (skip confirmation).").option("--version <version>", "Pin a specific version (e.g. 0.5.1 or 0.6.0-rc.1).").action(action32);
   declaration(program2.command("self-update"));
   declaration(program2.command("upgrade"));
 }
@@ -79944,7 +80125,7 @@ function symbol2(status) {
       return cErr.dim("ℹ");
   }
 }
-async function action32(options) {
+async function action33(options) {
   const useSpinner = !options.json && process.stderr.isTTY;
   const spinner = useSpinner ? ora({ text: "Starting checks…", spinner: "dots", stream: process.stderr }).start() : null;
   const results = await runFastChecks({
@@ -79965,7 +80146,7 @@ async function action32(options) {
   }
 }
 function registerStatus(program2) {
-  program2.command("status").description("Quick sanity check (fast subset of `cerefox doctor`).").option("--json", "Emit machine-readable JSON.").action(action32);
+  program2.command("status").description("Quick sanity check (fast subset of `cerefox doctor`).").option("--json", "Emit machine-readable JSON.").action(action33);
 }
 
 // src/cli/commands/token.ts
@@ -79998,10 +80179,10 @@ function upsertEnvVar(path, key, value, opts = {}) {
   }
   const re = new RegExp(`^(\\s*)${escapeRegExp(key)}=.*$`, "m");
   let next;
-  let action33;
+  let action34;
   if (re.test(original)) {
     next = original.replace(re, `$1${line}`);
-    action33 = "updated";
+    action34 = "updated";
   } else {
     const base = original.endsWith(`
 `) ? original : `${original}
@@ -80009,10 +80190,10 @@ function upsertEnvVar(path, key, value, opts = {}) {
     next = `${base}
 ${header}${line}
 `;
-    action33 = "added";
+    action34 = "added";
   }
   writeFileSync5(path, next);
-  return { path, action: action33, backupPath };
+  return { path, action: action34, backupPath };
 }
 function readEnvVar(path, key) {
   if (!existsSync14(path))
@@ -80190,13 +80371,13 @@ var WSContext = class {
     this.#init.close(code, reason);
   }
 };
-var defineWebSocketHelper = (handler11) => {
+var defineWebSocketHelper = (handler12) => {
   return (...args) => {
     if (typeof args[0] === "function") {
       const [createEvents, options] = args;
       return async function upgradeWebSocket(c2, next) {
         const events = await createEvents(c2);
-        const result = await handler11(c2, events, options);
+        const result = await handler12(c2, events, options);
         if (result) {
           return result;
         }
@@ -80205,7 +80386,7 @@ var defineWebSocketHelper = (handler11) => {
     } else {
       const [c2, events, options] = args;
       return (async () => {
-        const upgraded = await handler11(c2, events, options);
+        const upgraded = await handler12(c2, events, options);
         if (!upgraded) {
           throw new Error("Failed to upgrade WebSocket");
         }
@@ -81798,16 +81979,16 @@ var compose = (middleware, onError, onNotFound) => {
       index = i;
       let res;
       let isError = false;
-      let handler11;
+      let handler12;
       if (middleware[i]) {
-        handler11 = middleware[i][0][0];
+        handler12 = middleware[i][0][0];
         context2.req.routeIndex = i;
       } else {
-        handler11 = i === middleware.length && next || undefined;
+        handler12 = i === middleware.length && next || undefined;
       }
-      if (handler11) {
+      if (handler12) {
         try {
-          res = await handler11(context2, () => dispatch(i + 1));
+          res = await handler12(context2, () => dispatch(i + 1));
         } catch (err) {
           if (err instanceof Error && onError) {
             context2.error = err;
@@ -82491,8 +82672,8 @@ var Hono = class _Hono {
         } else {
           this.#addRoute(method, this.#path, args1);
         }
-        args.forEach((handler11) => {
-          this.#addRoute(method, this.#path, handler11);
+        args.forEach((handler12) => {
+          this.#addRoute(method, this.#path, handler12);
         });
         return this;
       };
@@ -82501,8 +82682,8 @@ var Hono = class _Hono {
       for (const p of [path].flat()) {
         this.#path = p;
         for (const m of [method].flat()) {
-          handlers.map((handler11) => {
-            this.#addRoute(m.toUpperCase(), this.#path, handler11);
+          handlers.map((handler12) => {
+            this.#addRoute(m.toUpperCase(), this.#path, handler12);
           });
         }
       }
@@ -82515,8 +82696,8 @@ var Hono = class _Hono {
         this.#path = "*";
         handlers.unshift(arg1);
       }
-      handlers.forEach((handler11) => {
-        this.#addRoute(METHOD_NAME_ALL, this.#path, handler11);
+      handlers.forEach((handler12) => {
+        this.#addRoute(METHOD_NAME_ALL, this.#path, handler12);
       });
       return this;
     };
@@ -82539,14 +82720,14 @@ var Hono = class _Hono {
   route(path, app) {
     const subApp = this.basePath(path);
     app.routes.map((r) => {
-      let handler11;
+      let handler12;
       if (app.errorHandler === errorHandler) {
-        handler11 = r.handler;
+        handler12 = r.handler;
       } else {
-        handler11 = async (c2, next) => (await compose([], app.errorHandler)(c2, () => r.handler(c2, next))).res;
-        handler11[COMPOSED_HANDLER] = r.handler;
+        handler12 = async (c2, next) => (await compose([], app.errorHandler)(c2, () => r.handler(c2, next))).res;
+        handler12[COMPOSED_HANDLER] = r.handler;
       }
-      subApp.#addRoute(r.method, r.path, handler11, r.basePath);
+      subApp.#addRoute(r.method, r.path, handler12, r.basePath);
     });
     return this;
   }
@@ -82555,12 +82736,12 @@ var Hono = class _Hono {
     subApp._basePath = mergePath(this._basePath, path);
     return subApp;
   }
-  onError = (handler11) => {
-    this.errorHandler = handler11;
+  onError = (handler12) => {
+    this.errorHandler = handler12;
     return this;
   };
-  notFound = (handler11) => {
-    this.#notFoundHandler = handler11;
+  notFound = (handler12) => {
+    this.#notFoundHandler = handler12;
     return this;
   };
   mount(path, applicationHandler, options) {
@@ -82597,26 +82778,26 @@ var Hono = class _Hono {
         return new Request(url, request);
       };
     })();
-    const handler11 = async (c2, next) => {
+    const handler12 = async (c2, next) => {
       const res = await applicationHandler(replaceRequest(c2.req.raw), ...getOptions(c2));
       if (res) {
         return res;
       }
       await next();
     };
-    this.#addRoute(METHOD_NAME_ALL, mergePath(path, "*"), handler11);
+    this.#addRoute(METHOD_NAME_ALL, mergePath(path, "*"), handler12);
     return this;
   }
-  #addRoute(method, path, handler11, baseRoutePath) {
+  #addRoute(method, path, handler12, baseRoutePath) {
     method = method.toUpperCase();
     path = mergePath(this._basePath, path);
     const r = {
       basePath: baseRoutePath !== undefined ? mergePath(this._basePath, baseRoutePath) : this._basePath,
       path,
       method,
-      handler: handler11
+      handler: handler12
     };
-    this.router.add(method, path, [handler11, r]);
+    this.router.add(method, path, [handler12, r]);
     this.routes.push(r);
   }
   #handleError(err, c2) {
@@ -82941,7 +83122,7 @@ var RegExpRouter = class {
     this.#middleware = { [METHOD_NAME_ALL]: /* @__PURE__ */ Object.create(null) };
     this.#routes = { [METHOD_NAME_ALL]: /* @__PURE__ */ Object.create(null) };
   }
-  add(method, path, handler11) {
+  add(method, path, handler12) {
     const middleware = this.#middleware;
     const routes = this.#routes;
     if (!middleware || !routes) {
@@ -82971,13 +83152,13 @@ var RegExpRouter = class {
       Object.keys(middleware).forEach((m) => {
         if (method === METHOD_NAME_ALL || method === m) {
           Object.keys(middleware[m]).forEach((p) => {
-            re.test(p) && middleware[m][p].push([handler11, paramCount]);
+            re.test(p) && middleware[m][p].push([handler12, paramCount]);
           });
         }
       });
       Object.keys(routes).forEach((m) => {
         if (method === METHOD_NAME_ALL || method === m) {
-          Object.keys(routes[m]).forEach((p) => re.test(p) && routes[m][p].push([handler11, paramCount]));
+          Object.keys(routes[m]).forEach((p) => re.test(p) && routes[m][p].push([handler12, paramCount]));
         }
       });
       return;
@@ -82990,7 +83171,7 @@ var RegExpRouter = class {
           routes[m][path2] ||= [
             ...findMiddleware(middleware[m], path2) || findMiddleware(middleware[METHOD_NAME_ALL], path2) || []
           ];
-          routes[m][path2].push([handler11, paramCount - len + i + 1]);
+          routes[m][path2].push([handler12, paramCount - len + i + 1]);
         }
       });
     }
@@ -83039,21 +83220,21 @@ var PreparedRegExpRouter = class {
     matcher[1].forEach((list) => list && list.push(handlerData));
     Object.values(matcher[2]).forEach((list) => list[0].push(handlerData));
   }
-  #addPath(method, path, handler11, indexes, map2) {
+  #addPath(method, path, handler12, indexes, map2) {
     const matcher = this.#matchers[method];
     if (!map2) {
-      matcher[2][path][0].push([handler11, {}]);
+      matcher[2][path][0].push([handler12, {}]);
     } else {
       indexes.forEach((index) => {
         if (typeof index === "number") {
-          matcher[1][index].push([handler11, map2]);
+          matcher[1][index].push([handler12, map2]);
         } else {
-          matcher[2][index || path][0].push([handler11, map2]);
+          matcher[2][index || path][0].push([handler12, map2]);
         }
       });
     }
   }
-  add(method, path, handler11) {
+  add(method, path, handler12) {
     if (!this.#matchers[method]) {
       const all = this.#matchers[METHOD_NAME_ALL];
       const staticMap = {};
@@ -83067,7 +83248,7 @@ var PreparedRegExpRouter = class {
       ];
     }
     if (path === "/*" || path === "*") {
-      const handlerData = [handler11, {}];
+      const handlerData = [handler12, {}];
       if (method === METHOD_NAME_ALL) {
         for (const m in this.#matchers) {
           this.#addWildcard(m, handlerData);
@@ -83084,10 +83265,10 @@ var PreparedRegExpRouter = class {
     for (const [indexes, map2] of data) {
       if (method === METHOD_NAME_ALL) {
         for (const m in this.#matchers) {
-          this.#addPath(m, path, handler11, indexes, map2);
+          this.#addPath(m, path, handler12, indexes, map2);
         }
       } else {
-        this.#addPath(method, path, handler11, indexes, map2);
+        this.#addPath(method, path, handler12, indexes, map2);
       }
     }
   }
@@ -83105,11 +83286,11 @@ var SmartRouter = class {
   constructor(init) {
     this.#routers = init.routers;
   }
-  add(method, path, handler11) {
+  add(method, path, handler12) {
     if (!this.#routes) {
       throw new Error(MESSAGE_MATCHER_IS_ALREADY_BUILT);
     }
-    this.#routes.push([method, path, handler11]);
+    this.#routes.push([method, path, handler12]);
   }
   match(method, path) {
     if (!this.#routes) {
@@ -83166,17 +83347,17 @@ var Node2 = class _Node2 {
   #patterns;
   #order = 0;
   #params = emptyParams;
-  constructor(method, handler11, children) {
+  constructor(method, handler12, children) {
     this.#children = children || /* @__PURE__ */ Object.create(null);
     this.#methods = [];
-    if (method && handler11) {
+    if (method && handler12) {
       const m = /* @__PURE__ */ Object.create(null);
-      m[method] = { handler: handler11, possibleKeys: [], score: 0 };
+      m[method] = { handler: handler12, possibleKeys: [], score: 0 };
       this.#methods = [m];
     }
     this.#patterns = [];
   }
-  insert(method, path, handler11) {
+  insert(method, path, handler12) {
     this.#order = ++this.#order;
     let curNode = this;
     const parts = splitRoutingPath(path);
@@ -83202,7 +83383,7 @@ var Node2 = class _Node2 {
     }
     curNode.#methods.push({
       [method]: {
-        handler: handler11,
+        handler: handler12,
         possibleKeys: possibleKeys.filter((v, i, a) => a.indexOf(v) === i),
         score: this.#order
       }
@@ -83320,7 +83501,7 @@ var Node2 = class _Node2 {
         return a.score - b2.score;
       });
     }
-    return [handlerSets.map(({ handler: handler11, params }) => [handler11, params])];
+    return [handlerSets.map(({ handler: handler12, params }) => [handler12, params])];
   }
 };
 
@@ -83331,15 +83512,15 @@ var TrieRouter = class {
   constructor() {
     this.#node = new Node2;
   }
-  add(method, path, handler11) {
+  add(method, path, handler12) {
     const results = checkOptionalParameter(path);
     if (results) {
       for (let i = 0, len = results.length;i < len; i++) {
-        this.#node.insert(method, results[i], handler11);
+        this.#node.insert(method, results[i], handler12);
       }
       return;
     }
-    this.#node.insert(method, path, handler11);
+    this.#node.insert(method, path, handler12);
   }
   match(method, path) {
     return this.#node.search(method, path);
@@ -85792,6 +85973,7 @@ Learn more:
   registerDocumentRestore(document2);
   registerDocumentEdit(document2);
   registerDocumentSetProjects(document2);
+  registerDocumentSetMetadata(document2);
   moveInto(document2, registerIngest, "ingest");
   registerDocumentInsert(document2);
   registerDocumentEditParts(document2);