npm - @cerefox/memory - Versions diffs - 1.5.0 → 1.6.1 - Mend

@cerefox/memory 1.5.0 → 1.6.1

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

Files changed (21) hide show

package/AGENT_GUIDE.md +13 -4
package/AGENT_QUICK_REFERENCE.md +14 -3
package/README.md +3 -2
package/dist/bin/cerefox.js +318 -136
package/dist/frontend/assets/{index-C1JXZA9m.css → index-Dm_zCch4.css} +1 -1
package/dist/frontend/assets/{index-D9z5yV9u.js → index-OqloGFwv.js} +2 -2
package/dist/frontend/assets/index-OqloGFwv.js.map +1 -0
package/dist/frontend/index.html +2 -2
package/dist/server-assets/_shared/ef-meta/index.ts +3 -3
package/dist/server-assets/_shared/mcp-tools/get-help-content.ts +4 -4
package/dist/server-assets/_shared/mcp-tools/get-help.ts +15 -1
package/dist/server-assets/_shared/mcp-tools/index.ts +3 -0
package/dist/server-assets/_shared/mcp-tools/set-document-metadata.ts +133 -0
package/dist/server-assets/db/migrations/0023_set_document_metadata.sql +16 -0
package/dist/server-assets/db/rpcs.sql +116 -1
package/dist/server-assets/db/schema.sql +1 -1
package/docs/guides/cli.md +54 -1
package/docs/guides/connect-agents.md +11 -8
package/docs/guides/operational-cost.md +1 -1
package/package.json +1 -1
package/dist/frontend/assets/index-D9z5yV9u.js.map +0 -1

package/dist/frontend/index.html CHANGED Viewed

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

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

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
-export const EF_VERSION = "1.5.0";
+export const EF_VERSION = "1.6.1";
 /**
  * The Cerefox RELEASE version — what `cerefox --version` reports and what npm
@@ -36,7 +36,7 @@ export const EF_VERSION = "1.5.0";
  * is imported by the Deno Edge Functions, which cannot reach into the npm
  * package.
  */
-export const CEREFOX_VERSION = "1.5.0";
+export const CEREFOX_VERSION = "1.6.1";
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).
@@ -46,7 +46,7 @@ export const CEREFOX_VERSION = "1.5.0";
  * `cut_release.ts` ONLY when EF source changed since the last tag; doctor
  * uses it to stay silent on label-only drift.
  */
-export const EF_LAST_CHANGED = "1.5.0";
+export const EF_LAST_CHANGED = "1.6.0";
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

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

@@ -11,19 +11,19 @@
  * docs/specs/polish-and-distribution-design.md §10d.
  */
-export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **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";
+export const 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";
 /** Sections keyed by their H2 heading text (lower-cased for matching). */
 export const HELP_SECTIONS: Record<string, string> = {
-  "Tools": "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `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)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\",\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.",
   "Update Workflow (title-based -- fallback)": "## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc (note its hash) -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true,\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```",
   "Catch-Up Workflow": "## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```",
-  "CLI fallback (when MCP is unavailable)": "## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\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\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.",
-  "Mistakes that have actually happened": "## 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.",
+  "Mistakes that have actually happened": "## 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.",
 };
 export const HELP_SECTION_HEADINGS: string[] = ["Tools", "Editing part of a document (prefer this over re-sending)", "Essential Rules", "Update Workflow (ID-based -- preferred)", "Update Workflow (title-based -- fallback)", "Catch-Up Workflow", "CLI fallback (when MCP is unavailable)", "Timestamps are UTC", "Mistakes that have actually happened"];

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

@@ -90,6 +90,18 @@ async function handler(
     result_count: 1,
   });
+  // The identity block leads EVERY response, not just `topic: "server"`.
+  //
+  // Behind a topic name it had a bootstrap problem an agent caught immediately:
+  // the remedy for a stale server requires a server new enough to contain the
+  // remedy. Asked for "server" on a pre-1.5.0 deployment, they got "no such
+  // topic" and reasonably concluded the documented check did not exist — inside
+  // the very section warning against unverified infrastructure claims.
+  //
+  // Nothing can retrofit old servers. What this fixes is the need to know a
+  // magic word: any `cerefox_get_help()` call now shows the version, and the
+  // ABSENCE of this block is itself diagnostic — a server that does not print
+  // it predates 1.5.0.
   if (!topic) {
     const idx = HELP_SECTION_HEADINGS.map((h) => `  - ${h}`).join("\n");
     return (
@@ -113,6 +125,8 @@ async function handler(
   if (matched.length === 0) {
     return (
+      serverIdentity() +
+      "\n\n---\n\n" +
       `No help topic matched "${topic}".\n\n` +
       `Available topics:\n` +
       HELP_SECTION_HEADINGS.map((h) => `  - ${h}`).join("\n") +
@@ -120,7 +134,7 @@ async function handler(
     );
   }
-  return matched.map((h) => HELP_SECTIONS[h]).join("\n\n---\n\n");
+  return serverIdentity() + "\n\n---\n\n" + matched.map((h) => HELP_SECTIONS[h]).join("\n\n---\n\n");
 }
 export const getHelpTool: ToolDefinition = {

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

@@ -32,6 +32,7 @@ import { listProjectsTool } from "./list-projects.ts";
 import { listVersionsTool } from "./list-versions.ts";
 import { metadataSearchTool } from "./metadata-search.ts";
 import { searchTool } from "./search.ts";
+import { setDocumentMetadataTool } from "./set-document-metadata.ts";
 import { setDocumentProjectsTool } from "./set-document-projects.ts";
 import { McpInvalidParams, type MCPSupabaseClient, type ToolDefinition } from "./types.ts";
@@ -49,6 +50,7 @@ export const ALL_TOOLS: ToolDefinition[] = [
   metadataSearchTool,
   listMetadataKeysTool,
   listProjectsTool,
+  setDocumentMetadataTool,
   setDocumentProjectsTool,
   auditLogTool,
   // Document relations (iteration 29): the graph surface.
@@ -110,5 +112,6 @@ export {
   listVersionsTool,
   metadataSearchTool,
   searchTool,
+  setDocumentMetadataTool,
   setDocumentProjectsTool,
 };

package/dist/server-assets/_shared/mcp-tools/set-document-metadata.ts ADDED Viewed

@@ -0,0 +1,133 @@
+/**
+ * `cerefox_set_document_metadata` — change a document's tags without touching
+ * its content (#204).
+ *
+ * Until this existed, `cerefox_ingest` was the only way to set a tag and it
+ * requires title + content, so changing one key meant resending the whole
+ * document — reproducing every untouched character, including IDs and tables.
+ * That is precisely the transcription risk the partial-edit tools were built to
+ * remove, still fully present for metadata. Project membership had a
+ * metadata-only writer (`cerefox_set_document_projects`) all along; tags never
+ * got one.
+ *
+ * The composition lives in the RPC rather than here, because the merge has to
+ * be atomic: several agent roles write to the same documents, and a read →
+ * merge → write done client-side would let two agents setting different keys
+ * clobber each other. `cerefox_set_document_metadata` merges inside one UPDATE
+ * against a locked row.
+ */
+import type { MCPSupabaseClient } from "./types.ts";
+import { logUsage } from "./_utils.ts";
+import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+async function handler(
+  supabase: MCPSupabaseClient,
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+): Promise<string> {
+  const document_id = args.document_id as string | undefined;
+  const metadata = args.metadata as Record<string, unknown> | undefined;
+  const replace = (args.replace as boolean | undefined) ?? 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) {
+    // An empty merge is a no-op, and a caller who wanted "clear everything"
+    // meant `replace: true`. Refusing beats silently doing nothing.
+    throw new McpInvalidParams(
+      "metadata is empty, which would change nothing. To clear all metadata pass replace: true with {}.",
+    );
+  }
+  const author = (args.author as string | undefined) ?? (args.requestor as string | undefined);
+  // Derived from the transport, never taken from the caller: an agent must not
+  // be able to record itself as a user. Matches the partial-edit handlers.
+  const authorType = ctx.accessPath === "cli" ? "user" : "agent";
+  const { data, error } = 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 (error) throw new Error(`RPC error: ${error.message}`);
+  const row = data?.[0] as
+    | { document_id?: string; metadata?: Record<string, unknown>; keys_set?: number; keys_removed?: number }
+    | undefined;
+  if (!row) throw new Error("cerefox_set_document_metadata returned no data");
+  logUsage(supabase, {
+    operation: "update_metadata",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor as string | undefined,
+    document_id,
+    result_count: 1,
+  });
+  const set = row.keys_set ?? 0;
+  const removed = row.keys_removed ?? 0;
+  // Report what CHANGED, not what was asked for. Setting a key to the value it
+  // already held is a no-op, and saying so beats implying work happened.
+  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}\n` +
+    `Now: ${JSON.stringify(row.metadata ?? {})}\n` +
+    `Content untouched — no new version, no re-embedding.`
+  );
+}
+export const setDocumentMetadataTool: ToolDefinition = {
+  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,
+    // Merge cannot lose a key you did not name; `replace: true` can.
+    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,
+};

package/dist/server-assets/db/migrations/0023_set_document_metadata.sql ADDED Viewed

@@ -0,0 +1,16 @@
+-- 0023_set_document_metadata.sql — metadata-only writes (#204).
+--
+-- Adds cerefox_set_document_metadata. No table DDL: the function itself ships
+-- in rpcs.sql, which `cerefox server deploy` re-applies wholesale. This
+-- migration exists so the schema version advances in step, which is what tells
+-- an existing deployment it needs that redeploy.
+--
+-- Schema version 0.11.2 → 0.11.3. Purely additive.
+DO $$
+BEGIN
+    RAISE NOTICE
+        'Migration 0023: cerefox_set_document_metadata arrives with rpcs.sql on '
+        'this deploy — metadata-only writes, merge by default, JSON null removes '
+        'a key (RFC 7386). Schema version 0.11.3.';
+END $$;

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

@@ -2416,6 +2416,120 @@ $$;
 -- redeploy. The web UI's /api/v1/schema-version endpoint compares the bundled
 -- and deployed values and surfaces a 'redeploy needed' banner on mismatch.
+-- ── cerefox_set_document_metadata ────────────────────────────────────────────
+-- Change a document's metadata WITHOUT touching its content (#204).
+--
+-- Until this existed, `cerefox_ingest` was the only way to set a tag, and it
+-- requires title + content — so changing one key meant resending the whole
+-- document, reproducing every untouched character. That is the transcription
+-- risk the partial-edit tools were built to remove, and it was still fully
+-- present for metadata. Project membership had a metadata-only writer
+-- (`cerefox_set_document_projects`) all along; tags simply never got one.
+--
+-- MERGE is the default, not replace. Several agent roles write to the same
+-- documents, so a destructive default would let a caller setting `status`
+-- silently drop `type`, `seq` and `agent_role` written by someone else — a
+-- default shadowing stored state, which is the defect class behind #183 and
+-- #191. It would also force a read-modify-write, which is the cost this
+-- function exists to remove.
+--
+-- REMOVAL uses a JSON null, following RFC 7386 (JSON Merge Patch):
+--     {"status": "active", "stale_key": null}  -- sets status, deletes stale_key
+-- Unambiguous because Cerefox metadata values are JSON strings by convention,
+-- so a null can never be a legitimate value. Same spirit as `cerefox_ingest`,
+-- where NULL means "not provided, keep existing" and '{}' means "clear all".
+--
+-- The merge happens inside one UPDATE against a locked row, so two agents
+-- setting different keys concurrently cannot clobber each other. Doing this
+-- client-side would reintroduce exactly that race.
+--
+-- Metadata-only: no re-chunk, no re-embed, no content version snapshot. The
+-- audit trail records it as 'update-metadata', which the CHECK already allows.
+DROP FUNCTION IF EXISTS cerefox_set_document_metadata(UUID, JSONB, BOOLEAN, TEXT, TEXT);
+CREATE FUNCTION cerefox_set_document_metadata(
+    p_document_id   UUID,
+    p_metadata      JSONB,
+    p_replace       BOOLEAN DEFAULT FALSE,
+    p_author        TEXT    DEFAULT 'unknown',
+    p_author_type   TEXT    DEFAULT 'user'
+)
+RETURNS TABLE (
+    document_id     UUID,
+    metadata        JSONB,
+    keys_set        INT,
+    keys_removed    INT
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_before      JSONB;
+    v_after       JSONB;
+    v_null_keys   TEXT[];
+    v_title       TEXT;
+    v_removed     INT;
+    v_set         INT;
+BEGIN
+    IF p_metadata IS NULL OR jsonb_typeof(p_metadata) <> 'object' THEN
+        RAISE EXCEPTION 'metadata must be a JSON object'
+            USING ERRCODE = '22023';
+    END IF;
+    -- Lock the row so a concurrent metadata write cannot interleave between
+    -- the read and the merge.
+    SELECT d.metadata, d.title INTO v_before, v_title
+    FROM cerefox_documents d
+    WHERE d.id = p_document_id AND d.deleted_at IS NULL
+    FOR UPDATE;
+    IF v_title IS NULL THEN
+        RAISE EXCEPTION 'Document % not found (or is deleted)', p_document_id
+            USING ERRCODE = 'P0002';
+    END IF;
+    -- Keys explicitly set to null are removals, never stored values.
+    SELECT COALESCE(array_agg(key), ARRAY[]::TEXT[]) INTO v_null_keys
+    FROM jsonb_each(p_metadata)
+    WHERE value = 'null'::jsonb;
+    IF p_replace THEN
+        v_after := p_metadata - v_null_keys;
+    ELSE
+        v_after := (COALESCE(v_before, '{}'::jsonb) || p_metadata) - v_null_keys;
+    END IF;
+    UPDATE cerefox_documents
+    SET metadata = v_after, updated_at = NOW()
+    WHERE id = p_document_id;
+    -- Report what actually changed, not what was asked for: a caller that sets
+    -- a key to the value it already had should see 0, so "nothing happened" is
+    -- distinguishable from "it worked".
+    SELECT count(*)::INT INTO v_removed
+    FROM jsonb_object_keys(COALESCE(v_before, '{}'::jsonb)) k
+    WHERE NOT v_after ? k;
+    SELECT count(*)::INT INTO v_set
+    FROM jsonb_each(v_after) e
+    WHERE COALESCE(v_before, '{}'::jsonb) -> e.key IS DISTINCT FROM e.value;
+    PERFORM cerefox_create_audit_entry(
+        p_document_id := p_document_id,
+        p_operation   := 'update-metadata',
+        p_author      := p_author,
+        p_author_type := p_author_type,
+        p_description := format(
+            'Metadata %s on "%s": %s key(s) set, %s removed',
+            CASE WHEN p_replace THEN 'replaced' ELSE 'merged' END,
+            v_title, v_set, v_removed
+        )
+    );
+    RETURN QUERY SELECT p_document_id, v_after, v_set, v_removed;
+END;
+$$;
 CREATE OR REPLACE FUNCTION cerefox_schema_version()
 RETURNS TEXT
 LANGUAGE sql
@@ -2425,13 +2539,14 @@ SET search_path = public, pg_catalog
 AS $$
     -- Keep in lockstep with the `@version:` marker in schema.sql (cut_release.ts
     -- enforces it). Bump whenever schema.sql OR rpcs.sql changes.
+    -- 0.11.3 (#204): cerefox_set_document_metadata — metadata-only writes.
     -- 0.11.2 (iteration 36): RLS enabled on cerefox_document_relations,
     -- which iteration 29 left off the list (Supabase rls_disabled_in_public).
     -- 0.11.1 (iteration 35, #197): audit CHECK accepts 'rename-section'.
     -- 0.11.0 supersedes 0.10.6 (v1.2.1, #191): this branch carries that fix plus
     -- the partial-edit surface, and both migrations (0019, 0020) are in the
     -- sequence, so a store deploying this gets everything from both lines.
-    SELECT '0.11.2'::TEXT;
+    SELECT '0.11.3'::TEXT;
 $$;
 -- ── cerefox_content_format_stats ─────────────────────────────────────────────

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

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