@cerefox/memory 1.3.0-beta.1 → 1.3.0-beta.3

package/AGENT_GUIDE.md

@@ -140,7 +140,7 @@ Add text to a document **without resending it**. Purely additive: this tool cann
 | `text` | Yes | Markdown to insert. Blank-line separation from surrounding content is handled for you. |
 | `position` | Yes | `end_of_document` (plain append) · `end_of_section` (add to a section's body — the most common mid-document add) · `after_heading` (lead-in text) · `before_heading` (a new block above a section). |
 | `anchor_heading` | Unless `end_of_document` | The exact heading line (`## Intake`) or a ` > ` parent path (`## Intake > ### Notes`) when a heading appears more than once. |
-| `section_part` | Sometimes | Only when the target section has BOTH its own content and child sections: `own_body` (before the first child) or `subtree` (after everything nested under it). If it is needed, the error tells you and lists both options. |
+| `section_part` | Sometimes | Required when the target section **has child sections** (whether or not it also has its own body): `own_body` (before the first child) or `subtree` (after everything nested under it). These can be far apart, so the tool refuses rather than choosing; the error lists both options. |
 | `expected_content_hash` | **Yes** | The hash of the version you are basing this on. There is **no `last_write_wins` on this tool**. |
 | `requestor` | No | Your agent name. |
 
@@ -163,6 +163,15 @@ Change parts of a document: **one to many operations applied atomically in a sin
 
 **Put changes that belong together in ONE call.** Operations apply in order against the evolving document (op 2 sees op 1's result), and a half-applied state is impossible — so a table row and the running total it feeds cannot end up disagreeing. If any operation fails (bad anchor, ambiguity), nothing at all is written and the error names the failing operation.
 
+**One sharp edge worth knowing.** A section runs to the next heading of the same
+or higher level — **or to the end of the document**. So the last section owns
+everything appended after it: an `end_of_document` insert becomes part of that
+section's body, and a later `replace_section` or `delete_section` on that heading
+removes it along with the rest. This is correct addressing, not a bug, but it is
+silent. If a write reports a large shrink, that is the warning; the previous
+content is in `cerefox_list_versions`. To append somewhere a later section edit
+cannot swallow, give the appended material its own heading.
+
 **To change a single line**, `replace_section` on its smallest enclosing heading and resend just that section. That is the intended granularity — line-level anchors were deliberately excluded because they silently edit the wrong place.
 
 The audit trail records each operation distinctly (`insert` / `replace-section` / `delete-section`), so *added to*, *rewrote* and *removed* stay distinguishable from a full rewrite.

package/AGENT_QUICK_REFERENCE.md

@@ -50,6 +50,11 @@ diff. Use the partial-edit tools instead:
    conflict means someone else changed the document; re-read and decide, do not
    force it.
 
+**A section runs to the next same-or-higher heading, or to the end of the
+document.** So `end_of_document` inserts land inside the *last* section, and
+replacing or deleting that section removes them too. A large shrink in the
+response is your warning; `cerefox_list_versions` has the previous content.
+
 **When an anchor is ambiguous the tool refuses and hands you the options** — a
 repeated heading returns the qualifying paths, and a section with both its own
 content and sub-sections returns both `section_part` choices. That is a

package/dist/bin/cerefox.js

@@ -7438,7 +7438,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "1.3.0-beta.1";
+var PKG_VERSION = "1.3.0-beta.3";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -26304,9 +26304,6 @@ function resolveAnchor(outline, anchorHeading) {
   }
   throw new AnchorNotFoundError(anchor, outline);
 }
-function hasOwnBody(content, node) {
-  return content.slice(node.bodyStart, node.ownBodyEnd).trim().length > 0;
-}
 function firstChild(outline, node) {
   for (const n of outline) {
     if (n.start >= node.bodyStart && n.start < node.subtreeEnd)
@@ -26314,7 +26311,7 @@ function firstChild(outline, node) {
   }
   return null;
 }
-function resolveSectionEnd(content, outline, node, sectionPart, opName, destructive) {
+function resolveSectionEnd(content, outline, node, sectionPart, opName) {
   const child = firstChild(outline, node);
   if (!child)
     return node.subtreeEnd;
@@ -26322,11 +26319,6 @@ function resolveSectionEnd(content, outline, node, sectionPart, opName, destruct
     return node.ownBodyEnd;
   if (sectionPart === "subtree")
     return node.subtreeEnd;
-  if (!hasOwnBody(content, node)) {
-    if (!destructive)
-      return node.subtreeEnd;
-    throw new AmbiguousPositionError(node, child.heading, opName);
-  }
   throw new AmbiguousPositionError(node, child.heading, opName);
 }
 function spliceBlock(content, from, to, text) {
@@ -26370,7 +26362,7 @@ function applyOne(content, operation) {
       at = node2.bodyStart;
       detail = "insert after_heading";
     } else {
-      at = resolveSectionEnd(content, outline, node2, operation.section_part, "end_of_section insert", false);
+      at = resolveSectionEnd(content, outline, node2, operation.section_part, "end_of_section insert");
       detail = `insert at end_of_section` + (operation.section_part ? ` (${operation.section_part})` : "");
     }
     return {
@@ -26380,7 +26372,7 @@ function applyOne(content, operation) {
   }
   if (operation.op === "replace_section") {
     const node2 = resolveAnchor(outline, operation.anchor_heading);
-    const to2 = resolveSectionEnd(content, outline, node2, operation.section_part, "replace_section", true);
+    const to2 = resolveSectionEnd(content, outline, node2, operation.section_part, "replace_section");
     return {
       content: spliceBlock(content, node2.bodyStart, to2, operation.text),
       applied: {
@@ -26392,7 +26384,7 @@ function applyOne(content, operation) {
   }
   const node = resolveAnchor(outline, operation.anchor_heading);
   const scope = operation.scope ?? "body_only";
-  const to = resolveSectionEnd(content, outline, node, operation.section_part, "delete_section", true);
+  const to = resolveSectionEnd(content, outline, node, operation.section_part, "delete_section");
   const from = scope === "heading_and_body" ? node.start : node.bodyStart;
   return {
     content: spliceBlock(content, from, to, ""),
@@ -26497,14 +26489,14 @@ ${outline.map((n) => `  ${n.path}`).join(`
       const candidates = [
         {
           section_part: "own_body",
-          description: `the section's own content, before its first child (${firstChildHeading})`
+          description: `just this section's own content, stopping before its first child ` + `(${firstChildHeading}) — often only a line or two below the heading`
         },
         {
           section_part: "subtree",
-          description: `the whole subtree, including everything nested under ${node.heading}`
+          description: `the whole subtree, past everything nested under ${node.heading} — ` + `which can be a long way down`
         }
       ];
-      super(`Ambiguous position: "${node.path}" has both its own content and child sections, ` + `so ${opName} could target two different ranges. No write was performed. ` + `Pass section_part to choose:
+      super(`Ambiguous position: "${node.path}" has child sections, so "the end of ` + `the section" could mean two different places and ${opName} will not guess. ` + `No write was performed. Pass section_part to choose:
 ` + candidates.map((c2) => `  section_part: "${c2.section_part}" — ${c2.description}`).join(`
 `));
       this.name = "AmbiguousPositionError";
@@ -55069,11 +55061,11 @@ var init_get_document = __esm(() => {
 });
 
 // ../../_shared/mcp-tools/get-help-content.ts
-var HELP_FULL = '# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **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`), `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 | `document_id` (required), `outline` |\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. **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.\n4. Both 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**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', HELP_SECTIONS, HELP_SECTION_HEADINGS;
+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`), `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 | `document_id` (required), `outline` |\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. **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.\n4. Both 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', 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`), `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 | `document_id` (required), `outline` |\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.",
-    "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. **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.\n4. Both 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**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.',
+    "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. **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.\n4. Both 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)
 
@@ -55454,6 +55446,16 @@ function resolveAuthorType2(ctx, args) {
 function defaultRequestor(ctx) {
   return ctx.accessPath === "cli" ? "cli-user" : "mcp-agent";
 }
+function shrinkNote(before, after) {
+  const lost = before - after;
+  if (lost <= 0)
+    return "";
+  const pct = Math.round(lost / Math.max(before, 1) * 100);
+  if (pct < 25)
+    return "";
+  return `⚠ This edit removed ${lost} characters (${pct}% smaller). If you did not ` + `intend that, note that a section runs to the next heading of the same or ` + `higher level — or to the end of the document — so replacing or deleting ` + `the LAST section also removes anything appended after it. ` + `cerefox_list_versions has the previous content.
+`;
+}
 function conflictError2(documentId, expectedHash, currentHash) {
   return new Error(`Conflict: document ${documentId} changed since you read it ` + `(your base hash: ${expectedHash}, current hash: ${currentHash}). No write was performed. ` + `To resolve: (1) cerefox_get_document("${documentId}", outline=true) to see the current ` + `structure and hash cheaply, or a full read if you need the text, (2) decide whether your ` + `edit still applies — another writer may have already made it, or made something it ` + `contradicts, (3) retry with expected_content_hash set to the current hash. ` + `These tools have no last-write-wins: the other writer's work is not yours to discard.`);
 }
@@ -55560,8 +55562,8 @@ async function applyAndWrite(supabase, ctx, args) {
 ${summary}
 
 ` + `New content_hash: ${row?.content_hash ?? newHash}
-` + `Size: ${row?.total_chars ?? totalChars} chars, ${chunks.length} chunk(s).
-` + `Pass the new content_hash as expected_content_hash on your next edit.${warning2}`;
+` + `Size: ${row?.total_chars ?? totalChars} chars (was ${doc.content.length}), ${chunks.length} chunk(s).
+` + shrinkNote(doc.content.length, row?.total_chars ?? totalChars) + `Pass the new content_hash as expected_content_hash on your next edit.${warning2}`;
 }
 async function insertHandler(supabase, args, ctx) {
   const documentId = args.document_id?.trim();
@@ -55654,7 +55656,7 @@ var init_partial_edits2 = __esm(() => {
         section_part: {
           type: "string",
           enum: ["own_body", "subtree"],
-          description: "Only for end_of_section when the section has BOTH its own content and child sections: own_body = before the first child, subtree = after everything nested under it. Omit otherwise; you will be told (with both options) if it is needed."
+          description: "Only for end_of_section when the target section HAS CHILD SECTIONS: own_body = before the first child, subtree = after everything nested under it. These can be far apart, so the tool refuses rather than choosing. Omit it otherwise; you will be told (with both options) whenever it is needed."
         },
         expected_content_hash: {
           type: "string",
@@ -55710,7 +55712,7 @@ var init_partial_edits2 = __esm(() => {
               section_part: {
                 type: "string",
                 enum: ["own_body", "subtree"],
-                description: "Only when the target section has BOTH its own content and child sections. You will be told (with both options) if it is needed."
+                description: "Only when the target section has child sections. You will be told (with both options) whenever it is needed."
               },
               scope: {
                 type: "string",
@@ -76319,8 +76321,8 @@ import { homedir as homedir6 } from "node:os";
 import { join as join9 } from "node:path";
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "1.3.0-beta.1";
-var EF_LAST_CHANGED = "1.3.0-beta.1";
+var EF_VERSION = "1.3.0-beta.3";
+var EF_LAST_CHANGED = "1.3.0-beta.3";
 
 // src/cli/util/checks.ts
 init_config();
@@ -78038,7 +78040,7 @@ async function runTool(toolName, args) {
   }
 }
 function registerDocumentInsert(program2) {
-  program2.command("insert <document-id>").description("Add text to a document without resending it (purely additive)").requiredOption("-t, --text <text>", "Markdown to insert. Use '-' for stdin or '@path' for a file.").option("-p, --position <position>", "end_of_document | end_of_section | after_heading | before_heading", "end_of_document").option("-a, --anchor-heading <heading>", "Heading line, or a ' > ' path. Required unless end_of_document.").option("--section-part <part>", "own_body | subtree — only when a section has both content and children").requiredOption("-e, --expected-content-hash <hash>", "content_hash you are basing this on (cerefox document get --outline shows it)").option("--requestor <name>", "Recorded in the usage log", "cli-user").option("--author-type <type>", "user (default for the CLI) or agent, when scripting on an agent's behalf", "user").action(async (documentId, options) => {
+  program2.command("insert <document-id>").description("Add text to a document without resending it (purely additive)").requiredOption("-t, --text <text>", "Markdown to insert. Use '-' for stdin or '@path' for a file.").option("-p, --position <position>", "end_of_document | end_of_section | after_heading | before_heading", "end_of_document").option("-a, --anchor-heading <heading>", "Heading line, or a ' > ' path. Required unless end_of_document.").option("--section-part <part>", "own_body | subtree — required when the target section has child sections").requiredOption("-e, --expected-content-hash <hash>", "content_hash you are basing this on (cerefox document get --outline shows it)").option("--requestor <name>", "Recorded in the usage log", "cli-user").option("--author-type <type>", "user (default for the CLI) or agent, when scripting on an agent's behalf", "user").action(async (documentId, options) => {
     await runTool("cerefox_insert", {
       document_id: documentId,
       text: resolveText(options.text, "--text"),

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

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
 
-export const EF_VERSION = "1.3.0-beta.1";
+export const EF_VERSION = "1.3.0-beta.3";
 
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).
@@ -28,7 +28,7 @@ export const EF_VERSION = "1.3.0-beta.1";
  * `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.3.0-beta.1";
+export const EF_LAST_CHANGED = "1.3.0-beta.3";
 
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

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

@@ -11,12 +11,12 @@
  * 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`), `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 | `document_id` (required), `outline` |\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. **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.\n4. Both 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**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";
+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`), `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 | `document_id` (required), `outline` |\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. **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.\n4. Both 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";
 
 /** 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`), `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 | `document_id` (required), `outline` |\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.",
-  "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. **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.\n4. Both 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**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.",
+  "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. **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.\n4. Both 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```",

package/dist/server-assets/_shared/mcp-tools/partial-edits.ts

@@ -53,6 +53,35 @@ function defaultRequestor(ctx: ToolContext): string {
   return ctx.accessPath === "cli" ? "cli-user" : "mcp-agent";
 }
 
+
+/**
+ * Surface a large shrink in the response the agent already reads.
+ *
+ * A section extends to the next heading of equal-or-higher level **or to the
+ * end of the document**, so the last section owns everything appended after it.
+ * That means an `end_of_document` insert becomes part of the last section's
+ * body, and a later `replace_section` on that heading removes it — correctly by
+ * the addressing rules, and invisibly, because the response otherwise just says
+ * the operation applied. Observed on a real store during the v1.3.0 beta: an
+ * appended entry vanished under a routine-looking section replace.
+ *
+ * The full-document diff is deliberately not returned (§3.8), so the size delta
+ * is the cheapest honest signal available.
+ */
+function shrinkNote(before: number, after: number): string {
+  const lost = before - after;
+  if (lost <= 0) return "";
+  const pct = Math.round((lost / Math.max(before, 1)) * 100);
+  if (pct < 25) return "";
+  return (
+    `⚠ This edit removed ${lost} characters (${pct}% smaller). If you did not ` +
+    `intend that, note that a section runs to the next heading of the same or ` +
+    `higher level — or to the end of the document — so replacing or deleting ` +
+    `the LAST section also removes anything appended after it. ` +
+    `cerefox_list_versions has the previous content.\n`
+  );
+}
+
 /** Audit `operation` values, matching the CHECK constraint widened by migration 0019. */
 const AUDIT_OP: Record<AppliedOperation["op"], string> = {
   insert: "insert",
@@ -263,7 +292,8 @@ async function applyAndWrite(
   return (
     `Applied ${applied.length} operation(s) to "${doc.title}" (id: ${documentId}):\n${summary}\n\n` +
     `New content_hash: ${row?.content_hash ?? newHash}\n` +
-    `Size: ${row?.total_chars ?? totalChars} chars, ${chunks.length} chunk(s).\n` +
+    `Size: ${row?.total_chars ?? totalChars} chars (was ${doc.content.length}), ${chunks.length} chunk(s).\n` +
+    shrinkNote(doc.content.length, row?.total_chars ?? totalChars) +
     `Pass the new content_hash as expected_content_hash on your next edit.${warning}`
   );
 }
@@ -351,7 +381,7 @@ export const insertTool: ToolDefinition = {
         type: "string",
         enum: ["own_body", "subtree"],
         description:
-          "Only for end_of_section when the section has BOTH its own content and child sections: own_body = before the first child, subtree = after everything nested under it. Omit otherwise; you will be told (with both options) if it is needed.",
+          "Only for end_of_section when the target section HAS CHILD SECTIONS: own_body = before the first child, subtree = after everything nested under it. These can be far apart, so the tool refuses rather than choosing. Omit it otherwise; you will be told (with both options) whenever it is needed.",
       },
       expected_content_hash: {
         type: "string",
@@ -458,7 +488,7 @@ export const editTool: ToolDefinition = {
               type: "string",
               enum: ["own_body", "subtree"],
               description:
-                "Only when the target section has BOTH its own content and child sections. You will be told (with both options) if it is needed.",
+                "Only when the target section has child sections. You will be told (with both options) whenever it is needed.",
             },
             scope: {
               type: "string",

package/dist/server-assets/_shared/partial-edits/index.ts

@@ -0,0 +1,497 @@
+/**
+ * Partial document edits — pure string layer (iteration 34).
+ *
+ * Implements the position/anchor semantics of
+ * `docs/specs/partial-document-edits-design.md` §3 exactly. No I/O, no client,
+ * no runtime dependencies: everything here is testable against strings alone
+ * and runs identically under Deno (Edge Function) and Node/Bun (local MCP,
+ * CLI). The handlers in `_shared/mcp-tools/{insert,edit}.ts` compose this with
+ * read → chunk → embed → `cerefox_ingest_document`.
+ *
+ * The one rule that governs every function: **never guess**. An absent anchor
+ * is an error, an ambiguous anchor is an error carrying the candidates that
+ * resolve it, and an ambiguous position (a section with both its own body and
+ * child headings) is an error carrying both concrete insertion points. A
+ * silent wrong-location write is strictly worse than a refusal (spec §3.7).
+ */
+
+/** One section in document order. Offsets are into the parsed string. */
+export interface OutlineNode {
+  /** Full heading line, trimmed — e.g. `### Notes`. */
+  heading: string;
+  /** 1–6. */
+  level: number;
+  /** ` > `-joined ancestor headings + own — the §3.7 anchor path form. */
+  path: string;
+  /** Offset of the heading line's first character. */
+  start: number;
+  /** Offset just past the heading line (start of the section's own body). */
+  bodyStart: number;
+  /** End of the section's own body: before its first child heading (== subtreeEnd for leaves). */
+  ownBodyEnd: number;
+  /** Before the next heading of equal-or-higher level (end of the whole subtree). */
+  subtreeEnd: number;
+  /** subtreeEnd - start: the per-section size reported by outline mode. */
+  chars: number;
+}
+
+export type InsertPosition =
+  | "end_of_document"
+  | "end_of_section"
+  | "after_heading"
+  | "before_heading";
+
+export type SectionPart = "own_body" | "subtree";
+
+export type EditOperation =
+  | {
+      op: "insert";
+      text: string;
+      position: InsertPosition;
+      anchor_heading?: string;
+      section_part?: SectionPart;
+    }
+  | {
+      op: "replace_section";
+      text: string;
+      anchor_heading: string;
+      section_part?: SectionPart;
+    }
+  | {
+      op: "delete_section";
+      anchor_heading: string;
+      scope?: "body_only" | "heading_and_body";
+      section_part?: SectionPart;
+    };
+
+/** Echo of one applied operation, for audit labels and response text. */
+export interface AppliedOperation {
+  op: "insert" | "replace_section" | "delete_section";
+  /** Resolved anchor path (or "(document)" for end_of_document). */
+  path: string;
+  /** Human summary: position / scope / section_part actually used. */
+  detail: string;
+}
+
+/** Anchor matched nothing. The write must never fall back to appending. */
+export class AnchorNotFoundError extends Error {
+  constructor(anchor: string, outline: OutlineNode[]) {
+    const known = outline.length
+      ? ` Known headings:\n${outline.map((n) => `  ${n.path}`).join("\n")}`
+      : " The document has no headings.";
+    super(
+      `Anchor not found: "${anchor}". No write was performed.${known}\n` +
+        `Anchors match a heading line exactly ("## Title") or a parent path ` +
+        `("## Parent > ### Child").`,
+    );
+    this.name = "AnchorNotFoundError";
+  }
+}
+
+/** Anchor matched more than one section. Candidates resolve the retry. */
+export class AmbiguousAnchorError extends Error {
+  readonly candidates: string[];
+  constructor(anchor: string, candidates: string[]) {
+    super(
+      `Ambiguous anchor: "${anchor}" matches ${candidates.length} sections. ` +
+        `No write was performed. Disambiguate by passing one of these paths as anchor_heading:\n` +
+        candidates.map((c) => `  ${c}`).join("\n"),
+    );
+    this.name = "AmbiguousAnchorError";
+    this.candidates = candidates;
+  }
+}
+
+/**
+ * The anchored section has both its own body and child headings, so "the
+ * section" has two defensible readings (spec §3.3). Never guessed.
+ */
+export class AmbiguousPositionError extends Error {
+  readonly candidates: { section_part: SectionPart; description: string }[];
+  constructor(node: OutlineNode, firstChildHeading: string, opName: string) {
+    const candidates = [
+      {
+        section_part: "own_body" as const,
+        description:
+          `just this section's own content, stopping before its first child ` +
+          `(${firstChildHeading}) — often only a line or two below the heading`,
+      },
+      {
+        section_part: "subtree" as const,
+        description:
+          `the whole subtree, past everything nested under ${node.heading} — ` +
+          `which can be a long way down`,
+      },
+    ];
+    super(
+      `Ambiguous position: "${node.path}" has child sections, so "the end of ` +
+        `the section" could mean two different places and ${opName} will not guess. ` +
+        `No write was performed. Pass section_part to choose:\n` +
+        candidates.map((c) => `  section_part: "${c.section_part}" — ${c.description}`).join("\n"),
+    );
+    this.name = "AmbiguousPositionError";
+    this.candidates = candidates;
+  }
+}
+
+/** Structural validation failure of an operations array (before any parsing). */
+export class InvalidOperationError extends Error {
+  constructor(index: number, message: string) {
+    super(`Invalid operation at index ${index}: ${message}. No write was performed.`);
+    this.name = "InvalidOperationError";
+  }
+}
+
+const ATX_HEADING = /^(#{1,6})[ \t]+(.*[^ \t#]|)[ \t]*#*[ \t]*$/;
+const FENCE_OPEN = /^([ \t]{0,3})(`{3,}|~{3,})(.*)$/;
+
+/**
+ * Parse the outline of a markdown document in one pass.
+ *
+ * ATX headings only (the chunker's convention). Headings inside fenced code
+ * blocks are content, not structure: the scanner tracks the open fence's
+ * marker character and length, and only a closing fence at least as long, of
+ * the same character, closes it (CommonMark). A decision log quoting markdown
+ * WILL contain `#` lines inside fences; treating those as headings would
+ * corrupt every anchor computed after them.
+ */
+export function parseOutline(content: string): OutlineNode[] {
+  const nodes: OutlineNode[] = [];
+  const stack: OutlineNode[] = []; // open ancestors, strictly increasing level
+  let fence: { char: string; len: number } | null = null;
+
+  let offset = 0;
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineStart = offset;
+    offset += line.length + (i < lines.length - 1 ? 1 : 0);
+
+    const fenceMatch = line.match(FENCE_OPEN);
+    if (fence) {
+      if (
+        fenceMatch &&
+        fenceMatch[2][0] === fence.char &&
+        fenceMatch[2].length >= fence.len &&
+        fenceMatch[3].trim() === ""
+      ) {
+        fence = null; // closing fence
+      }
+      continue;
+    }
+    if (fenceMatch) {
+      fence = { char: fenceMatch[2][0], len: fenceMatch[2].length };
+      continue;
+    }
+
+    const m = line.match(ATX_HEADING);
+    if (!m) continue;
+
+    const level = m[1].length;
+    const bodyStart = lineStart + line.length + (i < lines.length - 1 ? 1 : 0);
+
+    // Close every open section at >= this level.
+    while (stack.length && stack[stack.length - 1].level >= level) {
+      const closed = stack.pop()!;
+      closed.subtreeEnd = lineStart;
+      if (closed.ownBodyEnd === -1) closed.ownBodyEnd = lineStart;
+    }
+    // This heading is the first child of the innermost still-open ancestor.
+    if (stack.length && stack[stack.length - 1].ownBodyEnd === -1) {
+      stack[stack.length - 1].ownBodyEnd = lineStart;
+    }
+
+    // CommonMark treats a trailing run of #s as decoration, so `## Title ##`
+    // and `## Title` name the same section. Store the canonical form: an agent
+    // that read the rendered document addresses it as `## Title`, and one that
+    // pasted an outline path gets the same string back (resolveAnchor
+    // canonicalises the incoming anchor too).
+    const heading = `${m[1]} ${m[2].trim()}`.trim();
+    const node: OutlineNode = {
+      heading,
+      level,
+      path: [...stack.map((a) => a.heading), heading].join(" > "),
+      start: lineStart,
+      bodyStart,
+      ownBodyEnd: -1, // resolved when the first child or the subtree end is seen
+      subtreeEnd: -1,
+      chars: 0,
+    };
+    nodes.push(node);
+    stack.push(node);
+  }
+
+  const end = content.length;
+  for (const open of stack) {
+    open.subtreeEnd = end;
+    if (open.ownBodyEnd === -1) open.ownBodyEnd = end;
+  }
+  for (const n of nodes) n.chars = n.subtreeEnd - n.start;
+  return nodes;
+}
+
+/**
+ * Resolve an anchor per spec §3.7: exact heading text, or a ` > ` parent path.
+ * 0 matches → AnchorNotFoundError; 2+ → AmbiguousAnchorError with the paths.
+ */
+/** `## Title ##` and `## Title` name the same section (CommonMark decoration). */
+function canonicalHeading(text: string): string {
+  const m = text.trim().match(/^(#{1,6})[ \t]+(.*?)[ \t]*#*[ \t]*$/);
+  return m ? `${m[1]} ${m[2].trim()}`.trim() : text.trim();
+}
+
+export function resolveAnchor(outline: OutlineNode[], anchorHeading: string): OutlineNode {
+  const anchor = canonicalHeading(anchorHeading);
+
+  // Try the LITERAL heading first, always — including when the anchor contains
+  // the path separator. Headings really do contain " > " (`## Draft > Review`,
+  // `## A > B`), and treating any such anchor as a path made those sections
+  // unaddressable by their own text: the agent would read `## A > B` from the
+  // outline, pass it back verbatim, and be told the anchor does not exist while
+  // the error listed it. Literal-first also keeps the outline's promise that
+  // what it prints can be pasted straight back.
+  const byHeading = outline.filter((n) => n.heading === anchor);
+  if (byHeading.length === 1) return byHeading[0];
+  if (byHeading.length > 1) {
+    throw new AmbiguousAnchorError(anchor, byHeading.map((n) => n.path));
+  }
+
+  // No heading matched literally: interpret it as a parent path.
+  if (anchor.includes(" > ")) {
+    const normalizedPath = anchor.split(" > ").map((seg) => canonicalHeading(seg)).join(" > ");
+    const byPath = outline.filter((n) => n.path === normalizedPath);
+    if (byPath.length === 1) return byPath[0];
+    if (byPath.length > 1) {
+      throw new AmbiguousAnchorError(anchor, byPath.map((n) => n.path));
+    }
+  }
+
+  throw new AnchorNotFoundError(anchor, outline);
+}
+
+function firstChild(outline: OutlineNode[], node: OutlineNode): OutlineNode | null {
+  for (const n of outline) {
+    if (n.start >= node.bodyStart && n.start < node.subtreeEnd) return n;
+  }
+  return null;
+}
+
+/**
+ * Resolve the [from, to) range a replace/delete targets, and the end offset an
+ * end_of_section insert lands at. Spec §3.3 + the freeze-pass rule: leaf →
+ * unambiguous; body+children → require section_part; children-without-body →
+ * subtree (the two readings coincide in intent: "everything under it").
+ */
+function resolveSectionEnd(
+  content: string,
+  outline: OutlineNode[],
+  node: OutlineNode,
+  sectionPart: SectionPart | undefined,
+  opName: string,
+): number {
+  const child = firstChild(outline, node);
+  if (!child) return node.subtreeEnd; // leaf: unambiguous
+  if (sectionPart === "own_body") return node.ownBodyEnd;
+  if (sectionPart === "subtree") return node.subtreeEnd;
+
+  // A section with children is ambiguous, full stop — whether or not it has
+  // any body of its own, and whichever operation is asking.
+  //
+  // Two earlier versions of this function were wrong here, in opposite ways.
+  // The first returned subtreeEnd for every children-only section, so
+  // `delete_section` on a grouping heading silently removed every sub-section
+  // under it — with `scope: "body_only"`, whose whole promise is to keep the
+  // structure. A review caught that and the destructive path started refusing.
+  //
+  // The insert path kept the exemption, on the reasoning that "for an insert
+  // the two readings coincide, both landing at the section's terminus". That
+  // reasoning was simply false, and an agent editing a real document found it:
+  // for `## Parent` with children and no body of its own, `own_body` lands
+  // BEFORE the first child and `subtree` lands AFTER the last one. Those are
+  // different places — potentially pages apart — and the code was choosing
+  // silently. The agent's text went to the end of a long section, and it only
+  // discovered that by re-reading the document, which is the cost this feature
+  // exists to remove.
+  //
+  // So: no exemption. `hasOwnBody` no longer gates anything, because the
+  // presence of children is what makes "the end of this section" ambiguous.
+  throw new AmbiguousPositionError(node, child.heading, opName);
+}
+
+/**
+ * Splice `text` into `content` as a markdown block: exactly one blank line
+ * separates it from any non-empty neighbour, existing surrounding blank runs
+ * collapse rather than stack. Agents send content; the join owns whitespace.
+ */
+function spliceBlock(content: string, from: number, to: number, text: string): string {
+  const before = content.slice(0, from).replace(/\n+$/, "");
+  const after = content.slice(to).replace(/^\n+/, "").replace(/\n+$/, "");
+  const block = text.replace(/^\n+/, "").replace(/\n+$/, "");
+
+  const parts: string[] = [];
+  if (before.length) parts.push(before);
+  if (block.length) parts.push(block);
+  if (after.length) parts.push(after);
+  const joined = parts.join("\n\n");
+  // Preserve a single trailing newline if the original ended with one.
+  return content.endsWith("\n") && joined.length ? joined + "\n" : joined;
+}
+
+function applyOne(
+  content: string,
+  operation: EditOperation,
+): { content: string; applied: AppliedOperation } {
+  const outline = parseOutline(content);
+
+  if (operation.op === "insert") {
+    const { position, text } = operation;
+    if (position === "end_of_document") {
+      return {
+        content: spliceBlock(content, content.length, content.length, text),
+        applied: { op: "insert", path: "(document)", detail: "insert at end_of_document" },
+      };
+    }
+    if (!operation.anchor_heading) {
+      // Validated earlier for real callers; guarded here for direct users.
+      throw new InvalidOperationError(0, `insert with position "${position}" requires anchor_heading`);
+    }
+    const node = resolveAnchor(outline, operation.anchor_heading);
+    let at: number;
+    let detail: string;
+    if (position === "before_heading") {
+      at = node.start;
+      detail = "insert before_heading";
+    } else if (position === "after_heading") {
+      at = node.bodyStart;
+      detail = "insert after_heading";
+    } else {
+      at = resolveSectionEnd(content, outline, node, operation.section_part, "end_of_section insert");
+      detail =
+        `insert at end_of_section` +
+        (operation.section_part ? ` (${operation.section_part})` : "");
+    }
+    return {
+      content: spliceBlock(content, at, at, text),
+      applied: { op: "insert", path: node.path, detail },
+    };
+  }
+
+  if (operation.op === "replace_section") {
+    const node = resolveAnchor(outline, operation.anchor_heading);
+    const to = resolveSectionEnd(content, outline, node, operation.section_part, "replace_section");
+    return {
+      content: spliceBlock(content, node.bodyStart, to, operation.text),
+      applied: {
+        op: "replace_section",
+        path: node.path,
+        detail:
+          "replace_section body" + (operation.section_part ? ` (${operation.section_part})` : ""),
+      },
+    };
+  }
+
+  // delete_section
+  const node = resolveAnchor(outline, operation.anchor_heading);
+  const scope = operation.scope ?? "body_only";
+  const to = resolveSectionEnd(content, outline, node, operation.section_part, "delete_section");
+  const from = scope === "heading_and_body" ? node.start : node.bodyStart;
+  return {
+    content: spliceBlock(content, from, to, ""),
+    applied: {
+      op: "delete_section",
+      path: node.path,
+      detail:
+        `delete_section (${scope})` + (operation.section_part ? ` (${operation.section_part})` : ""),
+    },
+  };
+}
+
+/** Structural validation of an operations array — index-precise, before any work. */
+export function validateOperations(operations: unknown): EditOperation[] {
+  if (!Array.isArray(operations) || operations.length === 0) {
+    throw new InvalidOperationError(0, "operations must be a non-empty array");
+  }
+  return operations.map((raw, i) => {
+    if (typeof raw !== "object" || raw === null) {
+      throw new InvalidOperationError(i, "each operation must be an object");
+    }
+    const o = raw as Record<string, unknown>;
+    const op = o.op;
+    if (op === "insert") {
+      const position = o.position;
+      if (
+        position !== "end_of_document" &&
+        position !== "end_of_section" &&
+        position !== "after_heading" &&
+        position !== "before_heading"
+      ) {
+        throw new InvalidOperationError(
+          i,
+          "insert requires position: end_of_document | end_of_section | after_heading | before_heading",
+        );
+      }
+      if (typeof o.text !== "string" || o.text.trim() === "") {
+        throw new InvalidOperationError(i, "insert requires non-empty text");
+      }
+      if (position !== "end_of_document" && typeof o.anchor_heading !== "string") {
+        throw new InvalidOperationError(i, `insert at ${position} requires anchor_heading`);
+      }
+      if (position === "end_of_document" && o.anchor_heading !== undefined) {
+        throw new InvalidOperationError(i, "end_of_document takes no anchor_heading");
+      }
+    } else if (op === "replace_section") {
+      if (typeof o.anchor_heading !== "string" || o.anchor_heading.trim() === "") {
+        throw new InvalidOperationError(i, "replace_section requires anchor_heading");
+      }
+      if (typeof o.text !== "string" || o.text.trim() === "") {
+        throw new InvalidOperationError(i, "replace_section requires non-empty text");
+      }
+    } else if (op === "delete_section") {
+      if (typeof o.anchor_heading !== "string" || o.anchor_heading.trim() === "") {
+        throw new InvalidOperationError(i, "delete_section requires anchor_heading");
+      }
+      if (o.scope !== undefined && o.scope !== "body_only" && o.scope !== "heading_and_body") {
+        throw new InvalidOperationError(i, "scope must be body_only or heading_and_body");
+      }
+    } else {
+      throw new InvalidOperationError(i, "op must be insert | replace_section | delete_section");
+    }
+    if (
+      o.section_part !== undefined &&
+      o.section_part !== "own_body" &&
+      o.section_part !== "subtree"
+    ) {
+      throw new InvalidOperationError(i, "section_part must be own_body or subtree");
+    }
+    return raw as EditOperation;
+  });
+}
+
+/**
+ * Apply operations in order against the evolving text (spec §3.4). All or
+ * nothing is upheld by construction: this function either returns the fully
+ * assembled result or throws before the caller writes anything — the write
+ * itself is a single ingest call downstream. Errors are re-thrown with the
+ * failing index prefixed so a batch caller can report it.
+ */
+export function applyOperations(
+  content: string,
+  operations: EditOperation[],
+): { content: string; applied: AppliedOperation[] } {
+  let current = content;
+  const applied: AppliedOperation[] = [];
+  for (let i = 0; i < operations.length; i++) {
+    try {
+      const result = applyOne(current, operations[i]);
+      current = result.content;
+      applied.push(result.applied);
+    } catch (err) {
+      if (err instanceof InvalidOperationError) throw err;
+      const msg = err instanceof Error ? err.message : String(err);
+      const wrapped = new Error(`Operation ${i + 1} of ${operations.length} failed: ${msg}`);
+      wrapped.name = err instanceof Error ? err.name : "Error";
+      throw wrapped;
+    }
+  }
+  return { content: current, applied };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.3.0-beta.1",
+  "version": "1.3.0-beta.3",
   "description": "Cerefox — user-owned shared memory for AI agents. CLI + stdio MCP server + web UI + ingestion for a knowledge base on your own Supabase project (or fully self-hosted with Cerefox Local).",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",