@cerefox/memory 1.3.0 → 1.4.0

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";
+var PKG_VERSION = "1.4.0";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -26285,13 +26285,13 @@ function canonicalHeading(text) {
   const m = text.trim().match(/^(#{1,6})[ \t]+(.*?)[ \t]*#*[ \t]*$/);
   return m ? `${m[1]} ${m[2].trim()}`.trim() : text.trim();
 }
-function resolveAnchor(outline, anchorHeading) {
+function resolveAnchor(outline, anchorHeading, reads = false) {
   const anchor = canonicalHeading(anchorHeading);
   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));
+    throw new AmbiguousAnchorError(anchor, byHeading.map((n) => n.path), reads);
   }
   if (anchor.includes(" > ")) {
     const normalizedPath = anchor.split(" > ").map((seg) => canonicalHeading(seg)).join(" > ");
@@ -26299,10 +26299,24 @@ function resolveAnchor(outline, anchorHeading) {
     if (byPath.length === 1)
       return byPath[0];
     if (byPath.length > 1) {
-      throw new AmbiguousAnchorError(anchor, byPath.map((n) => n.path));
+      throw new AmbiguousAnchorError(anchor, byPath.map((n) => n.path), reads);
     }
   }
-  throw new AnchorNotFoundError(anchor, outline);
+  throw new AnchorNotFoundError(anchor, outline, reads);
+}
+function extractSection(content, anchorHeading, sectionPart) {
+  const outline = parseOutline(content);
+  const node = resolveAnchor(outline, anchorHeading, true);
+  const to = resolveSectionEnd(content, outline, node, sectionPart, "the section read", true);
+  const text = content.slice(node.bodyStart, to);
+  return {
+    heading: node.heading,
+    path: node.path,
+    level: node.level,
+    text,
+    chars: text.length,
+    section_part: sectionPart ?? null
+  };
 }
 function firstChild(outline, node) {
   for (const n of outline) {
@@ -26311,7 +26325,7 @@ function firstChild(outline, node) {
   }
   return null;
 }
-function resolveSectionEnd(content, outline, node, sectionPart, opName) {
+function resolveSectionEnd(content, outline, node, sectionPart, opName, reads = false) {
   const child = firstChild(outline, node);
   if (!child)
     return node.subtreeEnd;
@@ -26319,7 +26333,7 @@ function resolveSectionEnd(content, outline, node, sectionPart, opName) {
     return node.ownBodyEnd;
   if (sectionPart === "subtree")
     return node.subtreeEnd;
-  throw new AmbiguousPositionError(node, child.heading, opName);
+  throw new AmbiguousPositionError(node, child.heading, opName, reads);
 }
 function spliceBlock(content, from, to, text) {
   const before = content.slice(0, from).replace(/\n+$/, "");
@@ -26378,7 +26392,30 @@ function applyOne(content, operation) {
       applied: {
         op: "replace_section",
         path: node2.path,
-        detail: "replace_section body" + (operation.section_part ? ` (${operation.section_part})` : "")
+        detail: "replace_section body" + (operation.section_part ? ` (${operation.section_part})` : ""),
+        reachedEnd: to2 >= content.trimEnd().length
+      }
+    };
+  }
+  if (operation.op === "rename_section") {
+    const node2 = resolveAnchor(outline, operation.anchor_heading);
+    const next = canonicalHeading(operation.new_heading);
+    const m = next.match(ATX_HEADING);
+    if (!m) {
+      throw new InvalidOperationError(0, `new_heading must be a markdown heading line like "## Title", got ${JSON.stringify(operation.new_heading)}`);
+    }
+    if (m[1].length !== node2.level)
+      throw new HeadingLevelChangeError(node2.heading, next);
+    const hadNewline = content[node2.bodyStart - 1] === `
+`;
+    const replacement = next + (hadNewline ? `
+` : "");
+    return {
+      content: content.slice(0, node2.start) + replacement + content.slice(node2.bodyStart),
+      applied: {
+        op: "rename_section",
+        path: node2.path,
+        detail: `rename_section to ${next}`
       }
     };
   }
@@ -26391,7 +26428,8 @@ function applyOne(content, operation) {
     applied: {
       op: "delete_section",
       path: node.path,
-      detail: `delete_section (${scope})` + (operation.section_part ? ` (${operation.section_part})` : "")
+      detail: `delete_section (${scope})` + (operation.section_part ? ` (${operation.section_part})` : ""),
+      reachedEnd: to >= content.trimEnd().length
     }
   };
 }
@@ -26433,8 +26471,21 @@ function validateOperations(operations) {
       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 if (op === "rename_section") {
+      if (typeof o.anchor_heading !== "string" || o.anchor_heading.trim() === "") {
+        throw new InvalidOperationError(i, "rename_section requires anchor_heading");
+      }
+      if (typeof o.new_heading !== "string" || o.new_heading.trim() === "") {
+        throw new InvalidOperationError(i, "rename_section requires non-empty new_heading");
+      }
+      if (o.text !== undefined) {
+        throw new InvalidOperationError(i, "rename_section changes only the heading and takes no text — use replace_section for the body, or both operations in one call");
+      }
+      if (o.section_part !== undefined) {
+        throw new InvalidOperationError(i, "rename_section takes no section_part: it replaces the heading line, so no extent is involved");
+      }
     } else {
-      throw new InvalidOperationError(i, "op must be insert | replace_section | delete_section");
+      throw new InvalidOperationError(i, "op must be insert | replace_section | delete_section | rename_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");
@@ -26461,22 +26512,22 @@ function applyOperations(content, operations) {
   }
   return { content: current, applied };
 }
-var AnchorNotFoundError, AmbiguousAnchorError, AmbiguousPositionError, InvalidOperationError, ATX_HEADING, FENCE_OPEN;
+var AnchorNotFoundError, AmbiguousAnchorError, AmbiguousPositionError, HeadingLevelChangeError, InvalidOperationError, ATX_HEADING, FENCE_OPEN;
 var init_partial_edits = __esm(() => {
   AnchorNotFoundError = class AnchorNotFoundError extends Error {
-    constructor(anchor, outline) {
+    constructor(anchor, outline, reads = false) {
       const known = outline.length ? ` Known headings:
 ${outline.map((n) => `  ${n.path}`).join(`
 `)}` : " The document has no headings.";
-      super(`Anchor not found: "${anchor}". No write was performed.${known}
+      super(`Anchor not found: "${anchor}".${reads ? "" : " No write was performed."}${known}
 ` + `Anchors match a heading line exactly ("## Title") or a parent path ` + `("## Parent > ### Child").`);
       this.name = "AnchorNotFoundError";
     }
   };
   AmbiguousAnchorError = class AmbiguousAnchorError extends Error {
     candidates;
-    constructor(anchor, candidates) {
-      super(`Ambiguous anchor: "${anchor}" matches ${candidates.length} sections. ` + `No write was performed. Disambiguate by passing one of these paths as anchor_heading:
+    constructor(anchor, candidates, reads = false) {
+      super(`Ambiguous anchor: "${anchor}" matches ${candidates.length} sections. ` + `${reads ? "" : "No write was performed. "}Disambiguate by passing one of these paths as anchor_heading:
 ` + candidates.map((c2) => `  ${c2}`).join(`
 `));
       this.name = "AmbiguousAnchorError";
@@ -26485,7 +26536,7 @@ ${outline.map((n) => `  ${n.path}`).join(`
   };
   AmbiguousPositionError = class AmbiguousPositionError extends Error {
     candidates;
-    constructor(node, firstChildHeading, opName) {
+    constructor(node, firstChildHeading, opName, reads = false) {
       const candidates = [
         {
           section_part: "own_body",
@@ -26496,13 +26547,21 @@ ${outline.map((n) => `  ${n.path}`).join(`
           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:
+      super(`Ambiguous position: "${node.path}" has child sections, so "the end of ` + `the section" could mean two different places and ${opName} will not guess. ` + `${reads ? "" : "No write was performed. "}Pass section_part to choose:
 ` + candidates.map((c2) => `  section_part: "${c2.section_part}" — ${c2.description}`).join(`
 `));
       this.name = "AmbiguousPositionError";
       this.candidates = candidates;
     }
   };
+  HeadingLevelChangeError = class HeadingLevelChangeError extends Error {
+    constructor(fromHeading, toHeading) {
+      const from = (fromHeading.match(/^#+/) ?? [""])[0].length;
+      const to = (toHeading.match(/^#+/) ?? [""])[0].length;
+      super(`rename_section changes heading TEXT, not depth: "${fromHeading}" is level ` + `${from} and "${toHeading}" is level ${to}. No write was performed. ` + `Changing the level would re-parent every section nested under it. ` + `Pass a level-${from} heading (${"#".repeat(from)} ...), or restructure ` + `explicitly with delete_section + insert if that is what you meant.`);
+      this.name = "HeadingLevelChangeError";
+    }
+  };
   InvalidOperationError = class InvalidOperationError extends Error {
     constructor(index, message) {
       super(`Invalid operation at index ${index}: ${message}. No write was performed.`);
@@ -54984,8 +55043,16 @@ async function handler2(supabase, args, ctx) {
   const document_id = args.document_id;
   const version_id = args.version_id ?? null;
   const outline = args.outline ?? false;
+  const section = (args.section ?? "").trim() || null;
+  const section_part = args.section_part ?? undefined;
   if (!document_id)
     throw new McpInvalidParams("document_id is required");
+  if (section && outline) {
+    throw new McpInvalidParams("Pass either outline (the whole structure) or section (one section's text), not both.");
+  }
+  if (section_part && !section) {
+    throw new McpInvalidParams("section_part only applies together with section.");
+  }
   const { data, error: error2 } = await supabase.rpc("cerefox_get_document", {
     p_document_id: document_id,
     p_version_id: version_id
@@ -55017,6 +55084,26 @@ async function handler2(supabase, args, ctx) {
       note: archived ? "This is an ARCHIVED version's structure, so no content_hash is returned: these anchors describe the old version and must not be used to edit the current one. Re-read without version_id to edit." : nodes.length === 0 ? "This document has no headings, so it has no anchors: only end_of_document inserts apply." : "Use a path as anchor_heading in cerefox_insert / cerefox_edit; content_hash is your expected_content_hash."
     }, null, 2);
   }
+  if (section) {
+    let extracted;
+    try {
+      extracted = extractSection(row.full_content ?? "", section, section_part);
+    } catch (err) {
+      throw new McpInvalidParams(err instanceof Error ? err.message : String(err));
+    }
+    const archived = version_id !== null;
+    return JSON.stringify({
+      title: row.doc_title ?? "Untitled",
+      heading: extracted.heading,
+      path: extracted.path,
+      level: extracted.level,
+      section_part: extracted.section_part,
+      chars: extracted.chars,
+      content_hash: archived ? null : row.content_hash ?? null,
+      text: extracted.text,
+      note: archived ? "This is an ARCHIVED version's section, so no content_hash is returned: it must not be used to edit the current document." : "This is exactly the text a replace_section on this anchor would overwrite (the heading itself is kept). content_hash is your expected_content_hash."
+    }, null, 2);
+  }
   const label = version_id !== null ? " (archived version)" : " (current)";
   const hashLine = row.content_hash ? `content_hash: ${row.content_hash}
 
@@ -55030,7 +55117,7 @@ var init_get_document = __esm(() => {
   init_types3();
   getDocumentTool = {
     name: "cerefox_get_document",
-    description: "Retrieve the full reconstructed content of a document — or, with outline=true, just its heading structure, sizes and content_hash (much cheaper, and the paths are the anchors the edit tools take). Pass version_id to retrieve an archived version; omit it (or pass null) for the current version. Version UUIDs are returned by cerefox_list_versions. The response header includes the document's current content_hash — pass it back as expected_content_hash when updating via cerefox_ingest (optimistic concurrency).",
+    description: `Retrieve a document at one of three zoom levels: the whole reconstructed content (default), its heading structure with outline=true (much cheaper, and the headings are the anchors the edit tools take), or one section's text with section="## Heading" (what a replace_section on that anchor would overwrite — read it before replacing a section you did not write). Pass version_id to retrieve an archived version; omit it (or pass null) for the current version. Version UUIDs are returned by cerefox_list_versions. Every non-archived response carries the document's current content_hash — pass it back as expected_content_hash when updating (optimistic concurrency).`,
     annotations: {
       title: "Read document",
       readOnlyHint: true,
@@ -55048,7 +55135,16 @@ var init_get_document = __esm(() => {
         },
         outline: {
           type: "boolean",
-          description: "Return the document's STRUCTURE instead of its content: heading paths, levels and per-section sizes, plus content_hash and total size. Far cheaper than a full read, and the paths are exactly what cerefox_insert / cerefox_edit take as anchor_heading. Use this before editing a document you have not read."
+          description: "Return the document's STRUCTURE instead of its content: heading paths, levels and per-section sizes, plus content_hash and total size. Far cheaper than a full read. Every heading listed is addressable by cerefox_insert / cerefox_edit: pass the bare heading line (e.g. '## Daily Logs') when it occurs once in the document, and only the full ' > ' path shown here when the same heading text repeats. Use this before editing a document you have not read."
+        },
+        section: {
+          type: "string",
+          description: "Return ONE section's text instead of the whole document: the anchor heading, exactly as cerefox_insert / cerefox_edit take it (bare heading line when unique, ' > ' path when it repeats). What comes back is precisely the text a replace_section on this anchor would overwrite, so read it before replacing a section you did not write. The heading itself is returned separately, because replace_section keeps it. Cannot be combined with outline."
+        },
+        section_part: {
+          type: "string",
+          enum: ["own_body", "subtree"],
+          description: "Only when the target section HAS CHILD SECTIONS, and it means the same here as on the edit tools: own_body = up to the first child, subtree = everything nested underneath. The read refuses without it for exactly the cases the write refuses, so that what you read is what you would replace. Omit it otherwise; you will be told (with both options) whenever it is needed."
         },
         requestor: {
           type: "string",
@@ -55061,11 +55157,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**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 HELP_FULL = '# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **16 MCP tools** (15 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for "How AI Agents Use Cerefox" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part` |\n| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required) |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: "## Heading"` one section\'s text | `document_id` (required), `outline`, `section`, `section_part` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project\'s docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc\'s project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.\n\n## Editing part of a document (prefer this over re-sending)\n\n**Re-sending a whole document to change part of it is the main way agents lose\ndata.** You have to reproduce the untouched remainder verbatim, and any drift\nsilently rewrites content nobody asked you to touch — which the caller cannot\ndiff. Use the partial-edit tools instead:\n\n1. **Learn the anchors** — `cerefox_get_document(document_id, outline: true)`.\n   Returns heading paths, per-section sizes and the `content_hash`, without the\n   body. The paths it returns are exactly what `anchor_heading` accepts.\n2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;\n   `end_of_section` adds inside a named section. It is structurally incapable of\n   removing anything, so "I meant to append" cannot become "I replaced the file".\n3. **Look before you overwrite** — `cerefox_get_document(document_id,\n   section: "## Heading")` returns exactly the text a `replace_section` on that\n   anchor would destroy. The outline gives you a section\'s *size*, never its\n   *text*, so on a document you did not write yourself this is the difference\n   between a replace and a blind overwrite.\n4. **Change or remove** → `cerefox_edit`. Put changes that belong together in\n   ONE call: they apply atomically, so a table row and the total it feeds cannot\n   end up disagreeing. To change a single line, `replace_section` on its\n   smallest enclosing heading — that is the intended granularity, not a\n   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use\n   `rename_section`: it changes the heading text and leaves the body and\n   position alone.\n5. All of them require `expected_content_hash` and **have no last-write-wins**. A\n   conflict means someone else changed the document; re-read and decide, do not\n   force it.\n\n**A section runs to the next same-or-higher heading, or to the end of the\ndocument.** So `end_of_document` inserts land inside the *last* section, and\nreplacing or deleting that section removes them too. A large shrink in the\nresponse is your warning; `cerefox_list_versions` has the previous content.\n\n**When an anchor is ambiguous the tool refuses and hands you the options** — a\nrepeated heading returns the qualifying paths, and a section with both its own\ncontent and sub-sections returns both `section_part` choices. That is a\nrecoverable answer, not a failure: retry with what it gave you.\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., "Claude Code", "archiver"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch("topic") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title="Same Title", content="...", document_id="abc123",\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch("topic") -> find doc (note its hash) -> modify ->\ningest(title="Same Title", content="...", update_if_exists=true,\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03-28T00:00:00Z")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --expected-content-hash "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n', 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**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.',
+    Tools: "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part` |\n| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required) |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: \"## Heading\"` one section's text | `document_id` (required), `outline`, `section`, `section_part` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.",
+    "Editing part of a document (prefer this over re-sending)": '## Editing part of a document (prefer this over re-sending)\n\n**Re-sending a whole document to change part of it is the main way agents lose\ndata.** You have to reproduce the untouched remainder verbatim, and any drift\nsilently rewrites content nobody asked you to touch — which the caller cannot\ndiff. Use the partial-edit tools instead:\n\n1. **Learn the anchors** — `cerefox_get_document(document_id, outline: true)`.\n   Returns heading paths, per-section sizes and the `content_hash`, without the\n   body. The paths it returns are exactly what `anchor_heading` accepts.\n2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;\n   `end_of_section` adds inside a named section. It is structurally incapable of\n   removing anything, so "I meant to append" cannot become "I replaced the file".\n3. **Look before you overwrite** — `cerefox_get_document(document_id,\n   section: "## Heading")` returns exactly the text a `replace_section` on that\n   anchor would destroy. The outline gives you a section\'s *size*, never its\n   *text*, so on a document you did not write yourself this is the difference\n   between a replace and a blind overwrite.\n4. **Change or remove** → `cerefox_edit`. Put changes that belong together in\n   ONE call: they apply atomically, so a table row and the total it feeds cannot\n   end up disagreeing. To change a single line, `replace_section` on its\n   smallest enclosing heading — that is the intended granularity, not a\n   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use\n   `rename_section`: it changes the heading text and leaves the body and\n   position alone.\n5. All of them require `expected_content_hash` and **have no last-write-wins**. A\n   conflict means someone else changed the document; re-read and decide, do not\n   force it.\n\n**A section runs to the next same-or-higher heading, or to the end of the\ndocument.** So `end_of_document` inserts land inside the *last* section, and\nreplacing or deleting that section removes them too. A large shrink in the\nresponse is your warning; `cerefox_list_versions` has the previous content.\n\n**When an anchor is ambiguous the tool refuses and hands you the options** — a\nrepeated heading returns the qualifying paths, and a section with both its own\ncontent and sub-sections returns both `section_part` choices. That is a\nrecoverable answer, not a failure: retry with what it gave you.',
     "Essential Rules": '## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., "Claude Code", "archiver"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.',
     "Update Workflow (ID-based -- preferred)": `## Update Workflow (ID-based -- preferred)
 
@@ -55386,7 +55482,7 @@ var init_ingest = __esm(() => {
   init_types3();
   ingestTool = {
     name: "cerefox_ingest",
-    description: "Save a note or document to the Cerefox knowledge base.",
+    description: "Save a note or document to the Cerefox knowledge base. Updating an existing document REPLACES its whole content, so every unchanged character has to be reproduced exactly. Prefer cerefox_insert / cerefox_edit for any change to part of a document, and especially where the untouched content cannot be checked by reading it — document IDs, hashes, numeric tables, indexes and registries. Drifting prose is obvious on review; one wrong character in a UUID is not, and it silently breaks the reference.",
     annotations: {
       title: "Save or update a document",
       readOnlyHint: false,
@@ -55446,14 +55542,22 @@ function resolveAuthorType2(ctx, args) {
 function defaultRequestor(ctx) {
   return ctx.accessPath === "cli" ? "cli-user" : "mcp-agent";
 }
-function shrinkNote(before, after) {
-  const lost = before - after;
+function touchedTrailingSection(applied) {
+  return applied.some((a) => a.reachedEnd === true);
+}
+function shrinkNote(before, afterChars, applied) {
+  const beforeChars = [...before].length;
+  const lost = beforeChars - afterChars;
   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.
+  const pct = Math.round(lost / Math.max(beforeChars, 1) * 100);
+  const trailing = touchedTrailingSection(applied);
+  if (pct < 25 && !trailing) {
+    return `This edit removed ${lost} characters. cerefox_list_versions has the previous content.
+`;
+  }
+  const why = trailing ? `You replaced or deleted the LAST section, and a section runs to the next ` + `heading of the same or higher level — or to the end of the document — so ` + `anything appended after it was inside it. ` : `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. `;
+  return `⚠ This edit removed ${lost} characters (${pct}% smaller). ${why}cerefox_list_versions has the previous content.
 `;
 }
 function conflictError2(documentId, expectedHash, currentHash) {
@@ -55563,7 +55667,7 @@ ${summary}
 
 ` + `New content_hash: ${row?.content_hash ?? newHash}
 ` + `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}`;
+` + shrinkNote(doc.content, row?.total_chars ?? totalChars, applied) + `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();
@@ -55626,7 +55730,8 @@ var init_partial_edits2 = __esm(() => {
   AUDIT_OP = {
     insert: "insert",
     replace_section: "replace-section",
-    delete_section: "delete-section"
+    delete_section: "delete-section",
+    rename_section: "rename-section"
   };
   insertTool = {
     name: "cerefox_insert",
@@ -55677,7 +55782,7 @@ var init_partial_edits2 = __esm(() => {
   };
   editTool = {
     name: "cerefox_edit",
-    description: "Change parts of a document without resending the whole thing: one or many operations " + "applied ATOMICALLY in one write. Operations: insert (same positions as cerefox_insert), " + "replace_section (swap a section's body, heading kept), delete_section (remove a section, " + "scope body_only or heading_and_body). Use one call for changes that belong together — a " + "half-applied edit is impossible, so a row and the total it feeds cannot disagree. " + "Operations apply in order and each sees the previous one's result. To change a single " + "line, replace_section on its smallest enclosing heading. Requires expected_content_hash; " + "returns the new hash, not the document.",
+    description: "Change parts of a document without resending the whole thing: one or many operations " + "applied ATOMICALLY in one write. Operations: insert (same positions as cerefox_insert), " + "replace_section (swap a section's body, heading kept), delete_section (remove a section, " + "scope body_only or heading_and_body), rename_section (change a heading's text, leaving " + "its body and position untouched — for headings that go stale, like a dated one). " + "Use one call for changes that belong together — a " + "half-applied edit is impossible, so a row and the total it feeds cannot disagree. " + "Operations apply in order and each sees the previous one's result. To change a single " + "line, replace_section on its smallest enclosing heading. Requires expected_content_hash; " + "returns the new hash, not the document.",
     annotations: {
       title: "Edit document sections",
       readOnlyHint: false,
@@ -55698,7 +55803,10 @@ var init_partial_edits2 = __esm(() => {
             type: "object",
             required: ["op"],
             properties: {
-              op: { type: "string", enum: ["insert", "replace_section", "delete_section"] },
+              op: {
+                type: "string",
+                enum: ["insert", "replace_section", "delete_section", "rename_section"]
+              },
               text: { type: "string", description: "Markdown. Required for insert and replace_section." },
               position: {
                 type: "string",
@@ -55718,6 +55826,10 @@ var init_partial_edits2 = __esm(() => {
                 type: "string",
                 enum: ["body_only", "heading_and_body"],
                 description: "delete_section only. Defaults to body_only, which keeps the heading."
+              },
+              new_heading: {
+                type: "string",
+                description: "rename_section only: the replacement heading LINE, at the same level (## stays ##). Changes the heading text and nothing else — the body and the section's position are untouched, which is the point: renaming via delete + insert would risk both. Use it for headings that go stale, like '## OPEN TODOs (as of 2026-08-08)'. A rename changes the anchor, so a later operation in the same call must target the NEW heading."
               }
             }
           }
@@ -71898,16 +72010,27 @@ function stringify(obj2, { maxDepth = 1000, numbersAsFloat = false } = {}) {
  */
 
 // src/cli/util/mcp-config-writers.ts
+init_config();
+function envForEntry() {
+  const label = (process.env.CEREFOX_ENV_LABEL ?? "").trim();
+  if (!label || mcpServerName() === "cerefox")
+    return;
+  return { CEREFOX_CONFIG_DIR: resolveConfigDir(), CEREFOX_ENV_LABEL: label };
+}
 function defaultCerefoxEntry() {
+  const env3 = envForEntry();
   return {
     command: "npx",
-    args: ["-y", "--package=@cerefox/memory", "cerefox", "mcp"]
+    args: ["-y", "--package=@cerefox/memory", "cerefox", "mcp"],
+    ...env3 ? { env: env3 } : {}
   };
 }
 function localCerefoxEntry() {
+  const env3 = envForEntry();
   return {
     command: process.env.CEREFOX_LOCAL_CMD || "cerefox-local",
-    args: ["mcp"]
+    args: ["mcp"],
+    ...env3 ? { env: env3 } : {}
   };
 }
 function claudeCodeUserConfigPath() {
@@ -71924,9 +72047,20 @@ function claudeDesktopConfigPath() {
   return join4(home, ".config", "Claude", "claude_desktop_config.json");
 }
 function claudeCodeDelegated(entry) {
+  const envFlags = Object.entries(entry.env ?? {}).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
   return {
     cmd: "claude",
-    args: ["mcp", "add", "cerefox", "--scope", "user", "--", entry.command, ...entry.args]
+    args: [
+      "mcp",
+      "add",
+      mcpServerName(),
+      "--scope",
+      "user",
+      ...envFlags,
+      "--",
+      entry.command,
+      ...entry.args
+    ]
   };
 }
 function cursorConfigPath() {
@@ -72011,7 +72145,7 @@ function directWrite(writer, configPath, opts) {
   }
   const serversKey = format === "toml" ? "mcp_servers" : "mcpServers";
   const servers = (existing[serversKey] && typeof existing[serversKey] === "object" ? existing[serversKey] : {}) ?? {};
-  servers.cerefox = entry;
+  servers[mcpServerName()] = entry;
   existing[serversKey] = servers;
   if (!opts.dryRun) {
     const body = format === "toml" ? stringify(existing) + `
@@ -72021,10 +72155,17 @@ function directWrite(writer, configPath, opts) {
   }
   return { configPath, backupPath, action: action6, serverEntry: entry };
 }
+function mcpServerName() {
+  const label = (process.env.CEREFOX_ENV_LABEL ?? "").trim();
+  if (!label)
+    return "cerefox";
+  const slug = label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug ? `cerefox-${slug}` : "cerefox";
+}
 function hasCerefoxEntry(existing, format) {
   const key = format === "toml" ? "mcp_servers" : "mcpServers";
   const servers = existing[key];
-  return typeof servers === "object" && servers !== null && servers.cerefox !== undefined;
+  return typeof servers === "object" && servers !== null && servers[mcpServerName()] !== undefined;
 }
 function delegatedWrite(writer, opts) {
   if (!writer.delegated) {
@@ -72093,6 +72234,7 @@ function action6(options) {
     println(c.dim(`  backup: ${result.backupPath}`));
   }
   println(c.dim(`  action: ${result.action}`));
+  println(c.dim(`  server name: ${mcpServerName()}`));
   if (result.delegatedCommand) {
     println(c.dim(`  invoked: ${result.delegatedCommand}`));
   }
@@ -76319,8 +76461,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";
-var EF_LAST_CHANGED = "1.3.0-beta.4";
+var EF_VERSION = "1.4.0";
+var EF_LAST_CHANGED = "1.4.0";
 
 // src/cli/util/checks.ts
 init_config();
@@ -76812,7 +76954,8 @@ async function checkPostgres() {
   }
   let postgres2;
   try {
-    postgres2 = (await Promise.resolve().then(() => (init_src(), exports_src))).default;
+    const mod = await Promise.resolve().then(() => (init_src(), exports_src));
+    postgres2 = mod.default;
   } catch (err) {
     return {
       name: "postgres",
@@ -77576,6 +77719,7 @@ class IngestionPipeline {
       text,
       title,
       source = "paste",
+      sourceOnCreate,
       sourceLabel,
       sourcePath: sourcePathOpt,
       projectName,
@@ -77678,7 +77822,8 @@ class IngestionPipeline {
         action: "skipped",
         reindexed: false,
         projectIds: existingProjectIds,
-        note: ""
+        note: "",
+        contentHash: existingByHash.content_hash ?? hash
       };
     }
     const chunks = chunkMarkdown(text, this.settings.maxChunkChars, this.settings.minChunkChars);
@@ -77703,7 +77848,7 @@ class IngestionPipeline {
     const rpcResult = await this.db.ingestDocumentRpc({
       documentId: null,
       title,
-      source,
+      source: source ?? sourceOnCreate ?? null,
       sourcePath,
       contentHash: hash,
       metadata: validatedMeta,
@@ -77725,7 +77870,8 @@ class IngestionPipeline {
       action: "created",
       reindexed: false,
       projectIds: resolvedIds,
-      note: ""
+      note: "",
+      contentHash: hash
     };
   }
   async updateDocument(opts) {
@@ -77817,7 +77963,8 @@ class IngestionPipeline {
         action: "updated",
         reindexed: false,
         projectIds: finalProjectIds2,
-        note: ""
+        note: "",
+        contentHash: existing.content_hash ?? newHash
       };
     }
     const chunks = chunkMarkdown(text, this.settings.maxChunkChars, this.settings.minChunkChars);
@@ -77851,7 +77998,7 @@ class IngestionPipeline {
       contentFormat: CONTENT_FORMAT_BLIND_STITCH,
       author,
       authorType,
-      sourceLabel: sourceLabel ?? source,
+      sourceLabel: sourceLabel ?? source ?? "manual",
       expectedContentHash: expectedContentHash ?? (forceRechunk && contentUnchanged ? existing.content_hash : null),
       lastWriteWins
     });
@@ -77870,7 +78017,8 @@ class IngestionPipeline {
       action: "updated",
       reindexed: true,
       projectIds: finalProjectIds,
-      note: ""
+      note: "",
+      contentHash: newHash
     };
   }
   async ingestFile(path, opts = {}) {
@@ -77881,7 +78029,8 @@ class IngestionPipeline {
       ...opts,
       text,
       title: opts.title ?? stem,
-      source: opts.source ?? "file",
+      source: opts.source === undefined ? "file" : opts.source,
+      sourceOnCreate: opts.sourceOnCreate ?? "file",
       sourcePath: absPath
     });
   }
@@ -77953,6 +78102,7 @@ async function action18(path, options) {
     title = data.title;
     println(c.dim(`  (keeping existing title: ${JSON.stringify(title)})`));
   }
+  const resolvedSource = options.source ?? null;
   const pipeline = new IngestionPipeline({
     supabase,
     openAiApiKey: settings.openaiApiKey
@@ -77960,7 +78110,8 @@ async function action18(path, options) {
   try {
     const result = path && !options.paste ? await pipeline.ingestFile(path, {
       title,
-      source: options.source ?? "cli",
+      source: resolvedSource,
+      sourceOnCreate: "cli",
       projectName: options.projectName ?? null,
       projectNames: projectNames ?? null,
       metadata: metadata ?? null,
@@ -77973,7 +78124,8 @@ async function action18(path, options) {
     }) : await pipeline.ingestText({
       text: content,
       title,
-      source: options.source ?? "cli",
+      source: resolvedSource,
+      sourceOnCreate: "cli",
       projectName: options.projectName ?? null,
       projectNames: projectNames ?? null,
       metadata: metadata ?? null,
@@ -77995,13 +78147,16 @@ async function action18(path, options) {
     const projects = result.projectIds.length > 0 ? ` [projects: ${result.projectIds.length}]` : "";
     const note = result.note ? ` (${result.note})` : "";
     println(c.green("✓ ") + `${verb}: ${JSON.stringify(result.title)} (id: ${result.documentId}), ` + `${result.chunkCount} chunk(s), ${result.totalChars} chars.${projects}${note}`);
+    if (result.contentHash) {
+      println(c.dim(`  content_hash: ${result.contentHash}`));
+    }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw systemError(`Ingest failed: ${msg}`);
   }
 }
 function registerIngest(program2) {
-  program2.command("ingest").description("Ingest a file (or stdin paste) into the knowledge base.").argument("[path]", "Path to the file to ingest. Omit when using --paste.").option("--paste", "Read content from stdin instead of a file.").option("-t, --title <title>", "Document title (required with --paste; defaults to filename without extension).").option("-p, --project-name <name>", "Single project membership (non-destructive on update).").option("-P, --project-names <names>", "Comma-separated full project membership set (destructive replace on update).").option("-m, --metadata <json>", "JSON metadata object.").option("--source <label>", "Origin label (default: cli).", "cli").option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-i, --document-id <uuid>", "Update a specific document by UUID (overrides --update-if-exists).").option("--expected-content-hash <sha256>", "Optimistic-concurrency token: the content_hash of the version this edit is based on (shown by `document get` / `search`). Required on content updates unless --last-write-wins.").option("--last-write-wins", "Skip the concurrency check and overwrite regardless of concurrent changes (recorded in the audit log).").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action18);
+  program2.command("ingest").description("Ingest a file (or stdin paste) into the knowledge base.").argument("[path]", "Path to the file to ingest. Omit when using --paste.").option("--paste", "Read content from stdin instead of a file.").option("-t, --title <title>", "Document title (required with --paste; defaults to filename without extension).").option("-p, --project-name <name>", "Single project membership (non-destructive on update).").option("-P, --project-names <names>", "Comma-separated full project membership set (destructive replace on update).").option("-m, --metadata <json>", "JSON metadata object.").option("--source <label>", 'Origin label. Omit it on an update and the document keeps the source it already has (#193); omit it on a create and it is recorded as "cli".').option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-i, --document-id <uuid>", "Update a specific document by UUID (overrides --update-if-exists).").option("--expected-content-hash <sha256>", "Optimistic-concurrency token: the content_hash of the version this edit is based on (shown by `document get` / `search`). Required on content updates unless --last-write-wins.").option("--last-write-wins", "Skip the concurrency check and overwrite regardless of concurrent changes (recorded in the audit log).").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action18);
 }
 
 // src/cli/commands/document-partial-edit.ts
@@ -78145,7 +78300,8 @@ async function action19(dir, options) {
     try {
       const result = await pipeline.ingestFile(file, {
         title: basename3(file, extname4(file)),
-        source: options.source ?? "cli",
+        source: options.source ?? null,
+        sourceOnCreate: "cli",
         projectName: options.projectName ?? null,
         metadata: metadata ?? null,
         updateExisting: Boolean(options.updateIfExists),
@@ -78178,7 +78334,7 @@ async function action19(dir, options) {
   }
 }
 function registerIngestDir(program2) {
-  program2.command("ingest-dir").description("Recursively ingest a directory of markdown / text files.").argument("<dir>", "Root directory to walk.").option("-p, --project-name <name>", "Project membership for all ingested docs.").option("-m, --metadata <json>", "JSON metadata applied to every doc.").option("--source <label>", "Origin label (default: cli).", "cli").option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("-e, --extensions <list>", "Comma-separated file extensions to ingest.", ".md,.txt").action(action19);
+  program2.command("ingest-dir").description("Recursively ingest a directory of markdown / text files.").argument("<dir>", "Root directory to walk.").option("-p, --project-name <name>", "Project membership for all ingested docs.").option("-m, --metadata <json>", "JSON metadata applied to every doc.").option("--source <label>", 'Origin label. Omit it and each matched document keeps the source it already has (#193); newly created ones are recorded as "cli".').option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("-e, --extensions <list>", "Comma-separated file extensions to ingest.", ".md,.txt").action(action19);
 }
 
 // src/cli/commands/init.ts
@@ -83652,7 +83808,7 @@ async function runSearch(ctx, opts) {
   if (!ctx.openAiApiKey && resolveEmbedderKind() !== "local") {
     throw new HttpError(503, "Embedder not available");
   }
-  const embedding = await getEmbedding(query, ctx.openAiApiKey);
+  const embedding = await getEmbedding(query, ctx.openAiApiKey ?? "");
   if (mode === "semantic") {
     const params2 = {
       p_query_embedding: embedding,
@@ -84249,7 +84405,7 @@ function registerDocumentWriteRoutes(app, ctx) {
       try {
         const pipeline2 = new IngestionPipeline({
           supabase: ctx.supabase,
-          openAiApiKey: ctx.openAiApiKey
+          openAiApiKey: ctx.openAiApiKey ?? ""
         });
         const result = await pipeline2.updateDocument({
           documentId,
@@ -84420,7 +84576,7 @@ function registerIngestRoutes(app, ctx) {
     try {
       const pipeline2 = new IngestionPipeline({
         supabase: ctx.supabase,
-        openAiApiKey: ctx.openAiApiKey
+        openAiApiKey: ctx.openAiApiKey ?? ""
       });
       const result = await pipeline2.ingestText({
         text: content.trim(),
@@ -84485,7 +84641,7 @@ function registerIngestRoutes(app, ctx) {
     try {
       const pipeline2 = new IngestionPipeline({
         supabase: ctx.supabase,
-        openAiApiKey: ctx.openAiApiKey
+        openAiApiKey: ctx.openAiApiKey ?? ""
       });
       const result = await pipeline2.ingestText({
         text,
@@ -84538,7 +84694,7 @@ function registerIngestRoutes(app, ctx) {
     try {
       const pipeline2 = new IngestionPipeline({
         supabase: ctx.supabase,
-        openAiApiKey: ctx.openAiApiKey
+        openAiApiKey: ctx.openAiApiKey ?? ""
       });
       const result = await pipeline2.updateDocument({
         documentId,