@cerefox/memory 1.3.0 → 1.5.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.5.0";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -25730,6 +25730,10 @@ var init_bundled_docs = __esm(() => {
   PACKAGE_ROOT = findPackageRoot();
 });
 
+// ../../_shared/ef-meta/index.ts
+var EF_VERSION = "1.5.0", CEREFOX_VERSION = "1.5.0", EF_LAST_CHANGED = "1.5.0";
+var init_ef_meta = () => {};
+
 // ../../_shared/compatibility/index.ts
 function compareSemver(a, b2) {
   const split = (v) => {
@@ -26285,13 +26289,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 +26303,37 @@ 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 firstMeaningfulLine(text) {
+  for (const line of text.split(`
+`)) {
+    if (line.trim() !== "")
+      return canonicalHeading(line);
+  }
+  return "";
+}
+function assertNoDuplicateHeading(text, node, opName) {
+  if (firstMeaningfulLine(text) === node.heading) {
+    throw new DuplicateHeadingError(node.heading, opName);
+  }
 }
 function firstChild(outline, node) {
   for (const n of outline) {
@@ -26311,7 +26342,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 +26350,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+$/, "");
@@ -26359,9 +26390,11 @@ function applyOne(content, operation) {
       at = node2.start;
       detail = "insert before_heading";
     } else if (position === "after_heading") {
+      assertNoDuplicateHeading(text, node2, "insert");
       at = node2.bodyStart;
       detail = "insert after_heading";
     } else {
+      assertNoDuplicateHeading(text, node2, "insert");
       at = resolveSectionEnd(content, outline, node2, operation.section_part, "end_of_section insert");
       detail = `insert at end_of_section` + (operation.section_part ? ` (${operation.section_part})` : "");
     }
@@ -26372,13 +26405,37 @@ function applyOne(content, operation) {
   }
   if (operation.op === "replace_section") {
     const node2 = resolveAnchor(outline, operation.anchor_heading);
+    assertNoDuplicateHeading(operation.text, node2, "replace_section");
     const to2 = resolveSectionEnd(content, outline, node2, operation.section_part, "replace_section");
     return {
       content: spliceBlock(content, node2.bodyStart, to2, operation.text),
       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 +26448,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 +26491,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 +26532,22 @@ function applyOperations(content, operations) {
   }
   return { content: current, applied };
 }
-var AnchorNotFoundError, AmbiguousAnchorError, AmbiguousPositionError, InvalidOperationError, ATX_HEADING, FENCE_OPEN;
+var AnchorNotFoundError, AmbiguousAnchorError, AmbiguousPositionError, HeadingLevelChangeError, DuplicateHeadingError, 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 +26556,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 +26567,27 @@ ${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";
+    }
+  };
+  DuplicateHeadingError = class DuplicateHeadingError extends Error {
+    constructor(heading, opName) {
+      super(`The text you passed to ${opName} starts with the anchor heading itself ` + `(${JSON.stringify(heading)}). No write was performed. The heading is kept ` + `automatically — ${opName === "replace_section" ? "replace_section preserves it" : "insert places your text inside the section"}, ` + `so including it would produce two. Send only the new content, without that ` + `heading line. A DEEPER sub-heading inside your text is fine.`);
+      this.name = "DuplicateHeadingError";
+    }
+  };
   InvalidOperationError = class InvalidOperationError extends Error {
     constructor(index, message) {
       super(`Invalid operation at index ${index}: ${message}. No write was performed.`);
@@ -54639,6 +54724,10 @@ var require_lib7 = __commonJS((exports) => {
 });
 
 // ../../_shared/mcp-tools/audit-log.ts
+function utcStamp2(iso) {
+  const trimmed = iso.slice(0, 19);
+  return trimmed.includes("T") ? `${trimmed}Z` : `${trimmed} UTC`;
+}
 async function handler(supabase, args, ctx) {
   const params = {};
   if (args.document_id)
@@ -54668,7 +54757,7 @@ async function handler(supabase, args, ctx) {
   const lines = entries.map((e) => {
     const docLabel = e.doc_title ?? (e.document_id ? e.document_id.slice(0, 8) + "..." : "(deleted)");
     const sizeInfo = e.size_before != null && e.size_after != null ? ` | ${e.size_before} -> ${e.size_after} chars` : e.size_after != null ? ` | ${e.size_after} chars` : "";
-    return `${e.created_at.slice(0, 19)} | ${e.operation} | ${e.author} (${e.author_type}) | ${docLabel}${sizeInfo} | ${e.description}`;
+    return `${utcStamp2(e.created_at)} | ${e.operation} | ${e.author} (${e.author_type}) | ${docLabel}${sizeInfo} | ${e.description}`;
   });
   return `Audit log (${entries.length} entries, newest first):
 
@@ -54984,8 +55073,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 +55114,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 +55147,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 +55165,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",
@@ -55060,12 +55186,347 @@ var init_get_document = __esm(() => {
   };
 });
 
+// ../../_shared/mcp-tools/_chunker.ts
+function normalizeContent(text) {
+  return text.trim().replace(/\r\n/g, `
+`).replace(/\r/g, `
+`).replace(/\n{3,}/g, `
+
+`);
+}
+async function sha256hex(text) {
+  const bytes = new TextEncoder().encode(text);
+  const hash = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(hash)).map((b2) => b2.toString(16).padStart(2, "0")).join("");
+}
+var init__chunker = () => {};
+
+// ../../_shared/mcp-tools/partial-edits.ts
+function resolveAuthorType2(ctx, args) {
+  if (ctx.accessPath !== "cli")
+    return "agent";
+  return args.author_type === "agent" ? "agent" : "user";
+}
+function defaultRequestor(ctx) {
+  return ctx.accessPath === "cli" ? "cli-user" : "mcp-agent";
+}
+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(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 conflictError(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.`);
+}
+async function readDocument(supabase, documentId) {
+  const { data, error: error2 } = await supabase.rpc("cerefox_get_document", {
+    p_document_id: documentId,
+    p_version_id: null
+  });
+  if (error2)
+    throw new Error(`Could not read document: ${error2.message}`);
+  const row = data?.[0] ?? undefined;
+  if (!row || row.full_content === undefined) {
+    throw new McpInvalidParams(`Document not found: ${documentId}. Partial edits apply to an existing document; ` + `use cerefox_ingest to create one.`);
+  }
+  return {
+    title: row.doc_title ?? "Untitled",
+    content: row.full_content,
+    hash: row.content_hash ?? ""
+  };
+}
+async function applyAndWrite(supabase, ctx, args) {
+  const { documentId, operations, expectedHash, requestor, toolLabel, authorType } = args;
+  if (!ctx.openaiApiKey && resolveEmbedderKind() !== "local") {
+    throw new Error("OpenAI API key not configured. Set OPENAI_API_KEY (Edge Function) or CEREFOX_OPENAI_API_KEY (.env, local).");
+  }
+  const doc = await readDocument(supabase, documentId);
+  if (doc.hash && expectedHash !== doc.hash) {
+    throw conflictError(documentId, expectedHash, doc.hash);
+  }
+  let assembled;
+  let applied;
+  try {
+    const result = applyOperations(doc.content, operations);
+    assembled = result.content;
+    applied = result.applied;
+  } catch (err) {
+    throw new McpInvalidParams(err instanceof Error ? err.message : String(err));
+  }
+  if (assembled === doc.content) {
+    return `No change: the ${toolLabel} produced content identical to the current document ` + `"${doc.title}" (id: ${documentId}). content_hash: ${doc.hash} (unchanged).`;
+  }
+  const newHash = await sha256hex(normalizeContent(assembled));
+  const chunks = chunkMarkdown(assembled);
+  if (chunks.length === 0) {
+    throw new McpInvalidParams("The result of this edit produced no chunks (the document would be empty). " + "To remove a document use cerefox_ingest or the delete path, not a partial edit.");
+  }
+  const texts = chunks.map((c2) => embeddingInputFor(doc.title, c2));
+  const embeddings = await embedBatch(texts, ctx.openaiApiKey ?? "");
+  const totalChars = chunks.reduce((s, c2) => s + c2.char_count, 0);
+  const chunkData = chunks.map((chunk, i) => ({
+    chunk_index: i,
+    heading_path: chunk.heading_path,
+    heading_level: chunk.heading_level,
+    title: chunk.title,
+    content: chunk.content,
+    char_count: chunk.char_count,
+    embedding: embeddings[i],
+    embedder: activeEmbedderName()
+  }));
+  const { data, error: error2 } = await supabase.rpc("cerefox_ingest_document", {
+    p_document_id: documentId,
+    p_title: doc.title,
+    p_source: null,
+    p_content_hash: newHash,
+    p_metadata: null,
+    p_review_status: authorType === "agent" ? "pending_review" : "approved",
+    p_chunks: chunkData,
+    p_author: requestor,
+    p_author_type: authorType,
+    p_source_label: authorType === "user" ? "manual" : "agent",
+    p_expected_content_hash: expectedHash,
+    p_last_write_wins: false,
+    p_content_format: CONTENT_FORMAT_BLIND_STITCH,
+    p_operations: applied.map((a) => ({ op: AUDIT_OP[a.op], detail: a.detail }))
+  });
+  if (error2) {
+    const message = error2.message ?? "";
+    if (message.includes("CEREFOX_CONFLICT")) {
+      const current = message.match(/current hash ([0-9a-f]{64})/)?.[1] ?? "unknown";
+      throw conflictError(documentId, expectedHash, current);
+    }
+    if (message.includes("cerefox_documents_hash_unique")) {
+      throw new Error(`This edit would make "${doc.title}" (id: ${documentId}) byte-identical to another ` + `document in the store, and content must be unique. No write was performed. ` + `Usually this means the two documents have converged and one should be removed or ` + `merged, or that this edit was already applied to the other one — ` + `cerefox_search for the resulting content to find it.`);
+    }
+    if (message.includes("does not exist") && message.includes("cerefox_ingest_document")) {
+      throw new Error(`This server is behind: partial edits need schema 0.11.0 or newer. ` + `Run \`cerefox server deploy\`, then retry. (${message})`);
+    }
+    throw new Error(`Edit failed: ${message}`);
+  }
+  const row = data?.[0] ?? undefined;
+  logUsage(supabase, {
+    operation: toolLabel,
+    accessPath: ctx.accessPath,
+    requestor,
+    document_id: documentId,
+    result_count: applied.length
+  });
+  const summary = applied.map((a, i) => `  ${i + 1}. ${a.detail} → ${a.path}`).join(`
+`);
+  const warning2 = row?.size_warning ? `
+
+⚠ This document has passed the configured size threshold ` + `(document_size_warning_chars). Consider splitting it.` : "";
+  return `Applied ${applied.length} operation(s) to "${doc.title}" (id: ${documentId}):
+${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, 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();
+  const text = args.text;
+  const position = args.position;
+  const expectedHash = args.expected_content_hash?.trim();
+  if (!documentId)
+    throw new McpInvalidParams("document_id is required");
+  if (!text?.trim())
+    throw new McpInvalidParams("text is required and cannot be empty");
+  if (!expectedHash) {
+    throw new McpInvalidParams("expected_content_hash is required. It is the content_hash of the version you are " + "basing this insert on — returned by cerefox_get_document (including outline mode), " + "cerefox_search, cerefox_metadata_search, and by every write. There is no " + "last-write-wins here: knowing the document changed under you is the point.");
+  }
+  const operations = validateOperations([
+    {
+      op: "insert",
+      text,
+      position,
+      ...args.anchor_heading !== undefined ? { anchor_heading: args.anchor_heading } : {},
+      ...args.section_part !== undefined ? { section_part: args.section_part } : {}
+    }
+  ]);
+  return applyAndWrite(supabase, ctx, {
+    documentId,
+    operations,
+    expectedHash,
+    requestor: args.requestor ?? defaultRequestor(ctx),
+    toolLabel: "insert",
+    authorType: resolveAuthorType2(ctx, args)
+  });
+}
+async function editHandler(supabase, args, ctx) {
+  const documentId = args.document_id?.trim();
+  const expectedHash = args.expected_content_hash?.trim();
+  if (!documentId)
+    throw new McpInvalidParams("document_id is required");
+  if (!expectedHash) {
+    throw new McpInvalidParams("expected_content_hash is required. It is the content_hash of the version you are " + "basing these edits on — returned by cerefox_get_document (including outline mode), " + "cerefox_search, cerefox_metadata_search, and by every write.");
+  }
+  let operations;
+  try {
+    operations = validateOperations(args.operations);
+  } catch (err) {
+    throw new McpInvalidParams(err instanceof Error ? err.message : String(err));
+  }
+  return applyAndWrite(supabase, ctx, {
+    documentId,
+    operations,
+    expectedHash,
+    requestor: args.requestor ?? defaultRequestor(ctx),
+    toolLabel: "edit",
+    authorType: resolveAuthorType2(ctx, args)
+  });
+}
+var AUDIT_OP, insertTool, editTool;
+var init_partial_edits2 = __esm(() => {
+  init_partial_edits();
+  init__chunker();
+  init_types3();
+  AUDIT_OP = {
+    insert: "insert",
+    replace_section: "replace-section",
+    delete_section: "delete-section",
+    rename_section: "rename-section"
+  };
+  insertTool = {
+    name: "cerefox_insert",
+    description: "Add text to a document without resending the whole thing. Purely additive: it cannot " + "remove or overwrite existing content, so it is the safe way to append. Positions: " + "end_of_document (a plain append), end_of_section (add to the end of a section's body — " + "the most common mid-document add), after_heading (lead-in text), before_heading (a new " + "block above a section). Anchors are the exact heading line ('## Intake') or a parent path " + "('## Intake > ### Notes') when a heading appears more than once. Requires " + "expected_content_hash; returns the new hash, not the document.",
+    annotations: {
+      title: "Insert into document",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    },
+    inputSchema: {
+      type: "object",
+      required: ["document_id", "text", "position", "expected_content_hash"],
+      properties: {
+        document_id: { type: "string", description: "UUID of the document to add to" },
+        text: { type: "string", description: "Markdown to insert. Sent as-is; blank-line separation is handled for you." },
+        position: {
+          type: "string",
+          enum: ["end_of_document", "end_of_section", "after_heading", "before_heading"],
+          description: "Where to insert. end_of_document needs no anchor; the other three require anchor_heading."
+        },
+        anchor_heading: {
+          type: "string",
+          description: "Exact heading line, or a ' > ' path for a heading that appears more than once. Required unless position is end_of_document."
+        },
+        section_part: {
+          type: "string",
+          enum: ["own_body", "subtree"],
+          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",
+          description: "content_hash of the version you are basing this on. Required — no last-write-wins."
+        },
+        requestor: {
+          type: "string",
+          description: 'Agent or user making this request. Recorded in the usage log. Defaults to "mcp-agent".'
+        },
+        author_type: {
+          type: "string",
+          enum: ["user", "agent"],
+          description: "Honoured on the CLI only, where a human ran the command; over MCP the write is always recorded as an agent write regardless of what is passed."
+        }
+      }
+    },
+    handler: insertHandler
+  };
+  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), 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,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: false
+    },
+    inputSchema: {
+      type: "object",
+      required: ["document_id", "operations", "expected_content_hash"],
+      properties: {
+        document_id: { type: "string", description: "UUID of the document to edit" },
+        operations: {
+          type: "array",
+          minItems: 1,
+          description: "Operations applied in order, all-or-nothing. If any fails (bad anchor, ambiguity), nothing is written.",
+          items: {
+            type: "object",
+            required: ["op"],
+            properties: {
+              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",
+                enum: ["end_of_document", "end_of_section", "after_heading", "before_heading"],
+                description: "Required for insert."
+              },
+              anchor_heading: {
+                type: "string",
+                description: "Exact heading line, or a ' > ' path when the heading is not unique. Required for replace_section, delete_section, and any insert other than end_of_document."
+              },
+              section_part: {
+                type: "string",
+                enum: ["own_body", "subtree"],
+                description: "Only when the target section has child sections. You will be told (with both options) whenever it is needed."
+              },
+              scope: {
+                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."
+              }
+            }
+          }
+        },
+        expected_content_hash: {
+          type: "string",
+          description: "content_hash of the version you are basing these edits on. Required — no last-write-wins."
+        },
+        requestor: {
+          type: "string",
+          description: 'Agent or user making this request. Recorded in the usage log. Defaults to "mcp-agent".'
+        },
+        author_type: {
+          type: "string",
+          enum: ["user", "agent"],
+          description: "Honoured on the CLI only, where a human ran the command; over MCP the write is always recorded as an agent write regardless of what is passed."
+        }
+      }
+    },
+    handler: editHandler
+  };
+});
+
 // ../../_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\n## Timestamps are UTC\n\nEvery timestamp Cerefox returns — `created_at` on audit entries, version\nhistory, document metadata — is **UTC**, and now carries its `Z` marker so it\ncannot be mistaken for local time.\n\n**When you write a date into a document\'s CONTENT, use your own clock, not a\nCerefox timestamp.** These are different things: a timestamp records when the\nserver stored something; a date in a log entry or a heading is authored content\nand belongs to your timezone. An agent working a Pacific afternoon read\n`2026-08-11` from version history, wrote "8/11" into its entries, and put a\nday\'s work in the future — the timestamp was correct, and copying it into\ncontent was not.\n\nCerefox deliberately does not convert to local time on the API or MCP paths.\n"Local" has no server-side meaning: the remote MCP server runs in a cloud\nfunction whose local time *is* UTC, while a local MCP server runs in yours, so\nthe same document would report two different times depending on transport. The\nweb UI converts because a browser knows the viewer\'s timezone; nothing\nserver-side does.\n\n## Mistakes that have actually happened\n\nEach of these comes from a real agent session, and each is easy to make.\n\n- **`cerefox_ingest` always replaces the ENTIRE document.** Never a section.\n  Before sending, check that the tool name matches the intent: if the intent is\n  "change one section", the call is `cerefox_edit` with `replace_section`. A\n  section-sized edit sent as a full ingest truncated a 13,000-character index to\n  a single word. It was recovered from version history within the minute, but\n  only because it was noticed immediately.\n\n- **Do not include the anchor\'s own heading in your text.** `replace_section`\n  keeps the heading and `insert` places your text inside the section, so\n  including it produces two. This is now refused rather than silently applied,\n  but the shape is worth knowing: it happened twice in one session, the second\n  time while trying to repair the first. A *deeper* sub-heading inside your text\n  is fine.\n\n- **Content between sections belongs to the section ABOVE it.** A section runs\n  to the next heading of the same or higher level, so a `---` rule, a note, or\n  any trailing text sitting just above the next heading is part of the section\n  before it — even when it visually reads as belonging below. Replacing that\n  section takes it too. An agent hit exactly this: a `---` that separated two\n  major sections disappeared when the section above it was replaced. The write\n  was correct by the addressing rules; the surprise is that "the end of this\n  section" is further down the page than it looks. Note the loss warning will\n  not catch it if your replacement text is longer than what it replaced, since\n  there is then no net loss to report.\n\n- **Never partial-edit to fix a partial edit.** If a write leaves unexpected\n  structure, stop. Use `cerefox_list_versions`, retrieve the last good version,\n  and re-ingest cleanly. Repairing edits with more edits compounds the damage.\n\n- **A rejected batch is safe.** Operations in one `cerefox_edit` are\n  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a\n  retry, not data — so prefer one call for changes that belong together, and do\n  not split a batch to "make it more likely to succeed".\n\n- **Read before replacing.** `cerefox_get_document(section: "## Heading")`\n  returns exactly what a `replace_section` on that anchor would overwrite. Use it\n  for any section you did not write in this session. The outline gives a\n  section\'s *size*, never its *text*.\n\n- **Verify after writing** — read the result back before reporting success, and\n  report what the read actually shows.\n\n- **Partial edits cannot change a document\'s stored TITLE.** `rename_section`\n  changes a heading inside the content; the title is a separate field and still\n  needs `cerefox_ingest`.\n\n- **If a capability seems missing from one server, suspect your client first.**\n  Local and remote run the same code. Call `cerefox_get_help(topic: "server")`:\n  it reports the server\'s own version and the operations it registers. If that\n  disagrees with your tool list, the client is holding a list it fetched before\n  an upgrade — clients cache it at connect time. Ask the user to restart the\n  client. Do not record a capability difference between servers as a fact; every\n  such report so far has been a stale client.\n', HELP_SECTIONS, HELP_SECTION_HEADINGS;
 var 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)
 
@@ -55078,12 +55539,110 @@ ingest(title="Same Title", content="...", document_id="abc123",
 On a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.`,
     "Update Workflow (title-based -- fallback)": '## Update Workflow (title-based -- fallback)\n\n```\nsearch("topic") -> find doc (note its hash) -> modify ->\ningest(title="Same Title", content="...", update_if_exists=true,\n       expected_content_hash="<the hash you read>", author="my-agent")\n```',
     "Catch-Up Workflow": '## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03-28T00:00:00Z")\n```',
-    "CLI fallback (when MCP is unavailable)": '## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --expected-content-hash "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.'
-  };
-  HELP_SECTION_HEADINGS = ["Tools", "Editing part of a document (prefer this over re-sending)", "Essential Rules", "Update Workflow (ID-based -- preferred)", "Update Workflow (title-based -- fallback)", "Catch-Up Workflow", "CLI fallback (when MCP is unavailable)"];
+    "CLI fallback (when MCP is unavailable)": '## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --expected-content-hash "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.',
+    "Timestamps are UTC": `## Timestamps are UTC
+
+Every timestamp Cerefox returns — \`created_at\` on audit entries, version
+history, document metadata — is **UTC**, and now carries its \`Z\` marker so it
+cannot be mistaken for local time.
+
+**When you write a date into a document's CONTENT, use your own clock, not a
+Cerefox timestamp.** These are different things: a timestamp records when the
+server stored something; a date in a log entry or a heading is authored content
+and belongs to your timezone. An agent working a Pacific afternoon read
+\`2026-08-11\` from version history, wrote "8/11" into its entries, and put a
+day's work in the future — the timestamp was correct, and copying it into
+content was not.
+
+Cerefox deliberately does not convert to local time on the API or MCP paths.
+"Local" has no server-side meaning: the remote MCP server runs in a cloud
+function whose local time *is* UTC, while a local MCP server runs in yours, so
+the same document would report two different times depending on transport. The
+web UI converts because a browser knows the viewer's timezone; nothing
+server-side does.`,
+    "Mistakes that have actually happened": `## Mistakes that have actually happened
+
+Each of these comes from a real agent session, and each is easy to make.
+
+- **\`cerefox_ingest\` always replaces the ENTIRE document.** Never a section.
+  Before sending, check that the tool name matches the intent: if the intent is
+  "change one section", the call is \`cerefox_edit\` with \`replace_section\`. A
+  section-sized edit sent as a full ingest truncated a 13,000-character index to
+  a single word. It was recovered from version history within the minute, but
+  only because it was noticed immediately.
+
+- **Do not include the anchor's own heading in your text.** \`replace_section\`
+  keeps the heading and \`insert\` places your text inside the section, so
+  including it produces two. This is now refused rather than silently applied,
+  but the shape is worth knowing: it happened twice in one session, the second
+  time while trying to repair the first. A *deeper* sub-heading inside your text
+  is fine.
+
+- **Content between sections belongs to the section ABOVE it.** A section runs
+  to the next heading of the same or higher level, so a \`---\` rule, a note, or
+  any trailing text sitting just above the next heading is part of the section
+  before it — even when it visually reads as belonging below. Replacing that
+  section takes it too. An agent hit exactly this: a \`---\` that separated two
+  major sections disappeared when the section above it was replaced. The write
+  was correct by the addressing rules; the surprise is that "the end of this
+  section" is further down the page than it looks. Note the loss warning will
+  not catch it if your replacement text is longer than what it replaced, since
+  there is then no net loss to report.
+
+- **Never partial-edit to fix a partial edit.** If a write leaves unexpected
+  structure, stop. Use \`cerefox_list_versions\`, retrieve the last good version,
+  and re-ingest cleanly. Repairing edits with more edits compounds the damage.
+
+- **A rejected batch is safe.** Operations in one \`cerefox_edit\` are
+  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a
+  retry, not data — so prefer one call for changes that belong together, and do
+  not split a batch to "make it more likely to succeed".
+
+- **Read before replacing.** \`cerefox_get_document(section: "## Heading")\`
+  returns exactly what a \`replace_section\` on that anchor would overwrite. Use it
+  for any section you did not write in this session. The outline gives a
+  section's *size*, never its *text*.
+
+- **Verify after writing** — read the result back before reporting success, and
+  report what the read actually shows.
+
+- **Partial edits cannot change a document's stored TITLE.** \`rename_section\`
+  changes a heading inside the content; the title is a separate field and still
+  needs \`cerefox_ingest\`.
+
+- **If a capability seems missing from one server, suspect your client first.**
+  Local and remote run the same code. Call \`cerefox_get_help(topic: "server")\`:
+  it reports the server's own version and the operations it registers. If that
+  disagrees with your tool list, the client is holding a list it fetched before
+  an upgrade — clients cache it at connect time. Ask the user to restart the
+  client. Do not record a capability difference between servers as a fact; every
+  such report so far has been a stale client.`
+  };
+  HELP_SECTION_HEADINGS = ["Tools", "Editing part of a document (prefer this over re-sending)", "Essential Rules", "Update Workflow (ID-based -- preferred)", "Update Workflow (title-based -- fallback)", "Catch-Up Workflow", "CLI fallback (when MCP is unavailable)", "Timestamps are UTC", "Mistakes that have actually happened"];
 });
 
 // ../../_shared/mcp-tools/get-help.ts
+function editOperations() {
+  const schema = editTool.inputSchema;
+  return schema.properties?.operations?.items?.properties?.op?.enum ?? [];
+}
+function serverIdentity() {
+  return [
+    "## This server",
+    "",
+    `- **Version**: ${CEREFOX_VERSION}`,
+    `- **cerefox_edit operations**: ${editOperations().join(", ")}`,
+    "",
+    "**If your tool list disagrees with this block, your CLIENT is out of date, not the server.**",
+    "MCP clients fetch the tool list once when they connect and cache it, so a server",
+    "upgraded mid-session is invisible until the client reconnects. Ask the user to restart",
+    "the client — and if it stays missing after a restart, the client config may pin an old",
+    "version of the package. Do not record a capability difference between the local and",
+    "remote servers: they run the same code, and every such report so far has been a stale",
+    "client."
+  ].join(`
+`);
+}
 async function handler3(supabase, args, ctx) {
   const topic = args.topic?.trim();
   logUsage(supabase, {
@@ -55096,7 +55655,11 @@ async function handler3(supabase, args, ctx) {
   if (!topic) {
     const idx = HELP_SECTION_HEADINGS.map((h) => `  - ${h}`).join(`
 `);
-    return HELP_FULL + `
+    return serverIdentity() + `
+
+---
+
+` + HELP_FULL + `
 
 ---
 
@@ -55106,6 +55669,8 @@ async function handler3(supabase, args, ctx) {
 
 (Topic match is case-insensitive substring on the headings above.)`;
   }
+  if (/^(server|version|stale|client)$/i.test(topic))
+    return serverIdentity();
   const t = topic.toLowerCase();
   const matched = HELP_SECTION_HEADINGS.filter((h) => h.toLowerCase().includes(t));
   if (matched.length === 0) {
@@ -55123,6 +55688,8 @@ async function handler3(supabase, args, ctx) {
 }
 var getHelpTool;
 var init_get_help = __esm(() => {
+  init_ef_meta();
+  init_partial_edits2();
   init_get_help_content();
   getHelpTool = {
     name: "cerefox_get_help",
@@ -55150,30 +55717,15 @@ var init_get_help = __esm(() => {
   };
 });
 
-// ../../_shared/mcp-tools/_chunker.ts
-function normalizeContent(text) {
-  return text.trim().replace(/\r\n/g, `
-`).replace(/\r/g, `
-`).replace(/\n{3,}/g, `
-
-`);
-}
-async function sha256hex(text) {
-  const bytes = new TextEncoder().encode(text);
-  const hash = await crypto.subtle.digest("SHA-256", bytes);
-  return Array.from(new Uint8Array(hash)).map((b2) => b2.toString(16).padStart(2, "0")).join("");
-}
-var init__chunker = () => {};
-
 // ../../_shared/mcp-tools/ingest.ts
-function conflictError(documentId, expectedHash, currentHash) {
+function conflictError2(documentId, expectedHash, currentHash) {
   return new Error(`Conflict: document ${documentId} changed since you read it ` + `(your base hash: ${expectedHash}, current hash: ${currentHash}). ` + `To resolve: (1) cerefox_get_document("${documentId}") to fetch the latest content ` + `and its content_hash, (2) merge your changes into it, (3) retry cerefox_ingest ` + `with expected_content_hash set to the new hash. Do not overwrite blindly — ` + `the current content may include another writer's work.`);
 }
 function mapIngestRpcError(message, documentId) {
   if (message.includes("CEREFOX_CONFLICT")) {
     const current = message.match(/current hash ([0-9a-f]{64})/)?.[1] ?? "unknown";
     const expected = message.match(/expected hash ([0-9a-f]{64})/)?.[1] ?? "unknown";
-    return conflictError(documentId, expected, current);
+    return conflictError2(documentId, expected, current);
   }
   if (message.includes("CEREFOX_TOKEN_REQUIRED")) {
     const current = message.match(/Current hash: ([0-9a-f]{64})/)?.[1];
@@ -55220,7 +55772,7 @@ async function handler4(supabase, args, ctx) {
       return `Document already up-to-date: "${existingDoc.title}" (id: ${existingDoc.id}). Content hash unchanged (${contentHash2}).${note2}`;
     }
     if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
-      throw conflictError(existingDoc.id, expected_content_hash, existingDoc.content_hash);
+      throw conflictError2(existingDoc.id, expected_content_hash, existingDoc.content_hash);
     }
     const chunks2 = chunkMarkdown(content);
     if (chunks2.length === 0)
@@ -55278,7 +55830,7 @@ async function handler4(supabase, args, ctx) {
         return `Document already up-to-date: "${existingDoc.title}" (id: ${existingDoc.id}). Content hash unchanged (${contentHash2}).`;
       }
       if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
-        throw conflictError(existingDoc.id, expected_content_hash, existingDoc.content_hash);
+        throw conflictError2(existingDoc.id, expected_content_hash, existingDoc.content_hash);
       }
       const chunks2 = chunkMarkdown(content);
       if (chunks2.length === 0)
@@ -55386,7 +55938,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,
@@ -55437,310 +55989,6 @@ var init_ingest = __esm(() => {
   };
 });
 
-// ../../_shared/mcp-tools/partial-edits.ts
-function resolveAuthorType2(ctx, args) {
-  if (ctx.accessPath !== "cli")
-    return "agent";
-  return args.author_type === "agent" ? "agent" : "user";
-}
-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.`);
-}
-async function readDocument(supabase, documentId) {
-  const { data, error: error2 } = await supabase.rpc("cerefox_get_document", {
-    p_document_id: documentId,
-    p_version_id: null
-  });
-  if (error2)
-    throw new Error(`Could not read document: ${error2.message}`);
-  const row = data?.[0] ?? undefined;
-  if (!row || row.full_content === undefined) {
-    throw new McpInvalidParams(`Document not found: ${documentId}. Partial edits apply to an existing document; ` + `use cerefox_ingest to create one.`);
-  }
-  return {
-    title: row.doc_title ?? "Untitled",
-    content: row.full_content,
-    hash: row.content_hash ?? ""
-  };
-}
-async function applyAndWrite(supabase, ctx, args) {
-  const { documentId, operations, expectedHash, requestor, toolLabel, authorType } = args;
-  if (!ctx.openaiApiKey && resolveEmbedderKind() !== "local") {
-    throw new Error("OpenAI API key not configured. Set OPENAI_API_KEY (Edge Function) or CEREFOX_OPENAI_API_KEY (.env, local).");
-  }
-  const doc = await readDocument(supabase, documentId);
-  if (doc.hash && expectedHash !== doc.hash) {
-    throw conflictError2(documentId, expectedHash, doc.hash);
-  }
-  let assembled;
-  let applied;
-  try {
-    const result = applyOperations(doc.content, operations);
-    assembled = result.content;
-    applied = result.applied;
-  } catch (err) {
-    throw new McpInvalidParams(err instanceof Error ? err.message : String(err));
-  }
-  if (assembled === doc.content) {
-    return `No change: the ${toolLabel} produced content identical to the current document ` + `"${doc.title}" (id: ${documentId}). content_hash: ${doc.hash} (unchanged).`;
-  }
-  const newHash = await sha256hex(normalizeContent(assembled));
-  const chunks = chunkMarkdown(assembled);
-  if (chunks.length === 0) {
-    throw new McpInvalidParams("The result of this edit produced no chunks (the document would be empty). " + "To remove a document use cerefox_ingest or the delete path, not a partial edit.");
-  }
-  const texts = chunks.map((c2) => embeddingInputFor(doc.title, c2));
-  const embeddings = await embedBatch(texts, ctx.openaiApiKey ?? "");
-  const totalChars = chunks.reduce((s, c2) => s + c2.char_count, 0);
-  const chunkData = chunks.map((chunk, i) => ({
-    chunk_index: i,
-    heading_path: chunk.heading_path,
-    heading_level: chunk.heading_level,
-    title: chunk.title,
-    content: chunk.content,
-    char_count: chunk.char_count,
-    embedding: embeddings[i],
-    embedder: activeEmbedderName()
-  }));
-  const { data, error: error2 } = await supabase.rpc("cerefox_ingest_document", {
-    p_document_id: documentId,
-    p_title: doc.title,
-    p_source: null,
-    p_content_hash: newHash,
-    p_metadata: null,
-    p_review_status: authorType === "agent" ? "pending_review" : "approved",
-    p_chunks: chunkData,
-    p_author: requestor,
-    p_author_type: authorType,
-    p_source_label: authorType === "user" ? "manual" : "agent",
-    p_expected_content_hash: expectedHash,
-    p_last_write_wins: false,
-    p_content_format: CONTENT_FORMAT_BLIND_STITCH,
-    p_operations: applied.map((a) => ({ op: AUDIT_OP[a.op], detail: a.detail }))
-  });
-  if (error2) {
-    const message = error2.message ?? "";
-    if (message.includes("CEREFOX_CONFLICT")) {
-      const current = message.match(/current hash ([0-9a-f]{64})/)?.[1] ?? "unknown";
-      throw conflictError2(documentId, expectedHash, current);
-    }
-    if (message.includes("cerefox_documents_hash_unique")) {
-      throw new Error(`This edit would make "${doc.title}" (id: ${documentId}) byte-identical to another ` + `document in the store, and content must be unique. No write was performed. ` + `Usually this means the two documents have converged and one should be removed or ` + `merged, or that this edit was already applied to the other one — ` + `cerefox_search for the resulting content to find it.`);
-    }
-    if (message.includes("does not exist") && message.includes("cerefox_ingest_document")) {
-      throw new Error(`This server is behind: partial edits need schema 0.11.0 or newer. ` + `Run \`cerefox server deploy\`, then retry. (${message})`);
-    }
-    throw new Error(`Edit failed: ${message}`);
-  }
-  const row = data?.[0] ?? undefined;
-  logUsage(supabase, {
-    operation: toolLabel,
-    accessPath: ctx.accessPath,
-    requestor,
-    document_id: documentId,
-    result_count: applied.length
-  });
-  const summary = applied.map((a, i) => `  ${i + 1}. ${a.detail} → ${a.path}`).join(`
-`);
-  const warning2 = row?.size_warning ? `
-
-⚠ This document has passed the configured size threshold ` + `(document_size_warning_chars). Consider splitting it.` : "";
-  return `Applied ${applied.length} operation(s) to "${doc.title}" (id: ${documentId}):
-${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}`;
-}
-async function insertHandler(supabase, args, ctx) {
-  const documentId = args.document_id?.trim();
-  const text = args.text;
-  const position = args.position;
-  const expectedHash = args.expected_content_hash?.trim();
-  if (!documentId)
-    throw new McpInvalidParams("document_id is required");
-  if (!text?.trim())
-    throw new McpInvalidParams("text is required and cannot be empty");
-  if (!expectedHash) {
-    throw new McpInvalidParams("expected_content_hash is required. It is the content_hash of the version you are " + "basing this insert on — returned by cerefox_get_document (including outline mode), " + "cerefox_search, cerefox_metadata_search, and by every write. There is no " + "last-write-wins here: knowing the document changed under you is the point.");
-  }
-  const operations = validateOperations([
-    {
-      op: "insert",
-      text,
-      position,
-      ...args.anchor_heading !== undefined ? { anchor_heading: args.anchor_heading } : {},
-      ...args.section_part !== undefined ? { section_part: args.section_part } : {}
-    }
-  ]);
-  return applyAndWrite(supabase, ctx, {
-    documentId,
-    operations,
-    expectedHash,
-    requestor: args.requestor ?? defaultRequestor(ctx),
-    toolLabel: "insert",
-    authorType: resolveAuthorType2(ctx, args)
-  });
-}
-async function editHandler(supabase, args, ctx) {
-  const documentId = args.document_id?.trim();
-  const expectedHash = args.expected_content_hash?.trim();
-  if (!documentId)
-    throw new McpInvalidParams("document_id is required");
-  if (!expectedHash) {
-    throw new McpInvalidParams("expected_content_hash is required. It is the content_hash of the version you are " + "basing these edits on — returned by cerefox_get_document (including outline mode), " + "cerefox_search, cerefox_metadata_search, and by every write.");
-  }
-  let operations;
-  try {
-    operations = validateOperations(args.operations);
-  } catch (err) {
-    throw new McpInvalidParams(err instanceof Error ? err.message : String(err));
-  }
-  return applyAndWrite(supabase, ctx, {
-    documentId,
-    operations,
-    expectedHash,
-    requestor: args.requestor ?? defaultRequestor(ctx),
-    toolLabel: "edit",
-    authorType: resolveAuthorType2(ctx, args)
-  });
-}
-var AUDIT_OP, insertTool, editTool;
-var init_partial_edits2 = __esm(() => {
-  init_partial_edits();
-  init__chunker();
-  init_types3();
-  AUDIT_OP = {
-    insert: "insert",
-    replace_section: "replace-section",
-    delete_section: "delete-section"
-  };
-  insertTool = {
-    name: "cerefox_insert",
-    description: "Add text to a document without resending the whole thing. Purely additive: it cannot " + "remove or overwrite existing content, so it is the safe way to append. Positions: " + "end_of_document (a plain append), end_of_section (add to the end of a section's body — " + "the most common mid-document add), after_heading (lead-in text), before_heading (a new " + "block above a section). Anchors are the exact heading line ('## Intake') or a parent path " + "('## Intake > ### Notes') when a heading appears more than once. Requires " + "expected_content_hash; returns the new hash, not the document.",
-    annotations: {
-      title: "Insert into document",
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: false,
-      openWorldHint: false
-    },
-    inputSchema: {
-      type: "object",
-      required: ["document_id", "text", "position", "expected_content_hash"],
-      properties: {
-        document_id: { type: "string", description: "UUID of the document to add to" },
-        text: { type: "string", description: "Markdown to insert. Sent as-is; blank-line separation is handled for you." },
-        position: {
-          type: "string",
-          enum: ["end_of_document", "end_of_section", "after_heading", "before_heading"],
-          description: "Where to insert. end_of_document needs no anchor; the other three require anchor_heading."
-        },
-        anchor_heading: {
-          type: "string",
-          description: "Exact heading line, or a ' > ' path for a heading that appears more than once. Required unless position is end_of_document."
-        },
-        section_part: {
-          type: "string",
-          enum: ["own_body", "subtree"],
-          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",
-          description: "content_hash of the version you are basing this on. Required — no last-write-wins."
-        },
-        requestor: {
-          type: "string",
-          description: 'Agent or user making this request. Recorded in the usage log. Defaults to "mcp-agent".'
-        },
-        author_type: {
-          type: "string",
-          enum: ["user", "agent"],
-          description: "Honoured on the CLI only, where a human ran the command; over MCP the write is always recorded as an agent write regardless of what is passed."
-        }
-      }
-    },
-    handler: insertHandler
-  };
-  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.",
-    annotations: {
-      title: "Edit document sections",
-      readOnlyHint: false,
-      destructiveHint: true,
-      idempotentHint: false,
-      openWorldHint: false
-    },
-    inputSchema: {
-      type: "object",
-      required: ["document_id", "operations", "expected_content_hash"],
-      properties: {
-        document_id: { type: "string", description: "UUID of the document to edit" },
-        operations: {
-          type: "array",
-          minItems: 1,
-          description: "Operations applied in order, all-or-nothing. If any fails (bad anchor, ambiguity), nothing is written.",
-          items: {
-            type: "object",
-            required: ["op"],
-            properties: {
-              op: { type: "string", enum: ["insert", "replace_section", "delete_section"] },
-              text: { type: "string", description: "Markdown. Required for insert and replace_section." },
-              position: {
-                type: "string",
-                enum: ["end_of_document", "end_of_section", "after_heading", "before_heading"],
-                description: "Required for insert."
-              },
-              anchor_heading: {
-                type: "string",
-                description: "Exact heading line, or a ' > ' path when the heading is not unique. Required for replace_section, delete_section, and any insert other than end_of_document."
-              },
-              section_part: {
-                type: "string",
-                enum: ["own_body", "subtree"],
-                description: "Only when the target section has child sections. You will be told (with both options) whenever it is needed."
-              },
-              scope: {
-                type: "string",
-                enum: ["body_only", "heading_and_body"],
-                description: "delete_section only. Defaults to body_only, which keeps the heading."
-              }
-            }
-          }
-        },
-        expected_content_hash: {
-          type: "string",
-          description: "content_hash of the version you are basing these edits on. Required — no last-write-wins."
-        },
-        requestor: {
-          type: "string",
-          description: 'Agent or user making this request. Recorded in the usage log. Defaults to "mcp-agent".'
-        },
-        author_type: {
-          type: "string",
-          enum: ["user", "agent"],
-          description: "Honoured on the CLI only, where a human ran the command; over MCP the write is always recorded as an agent write regardless of what is passed."
-        }
-      }
-    },
-    handler: editHandler
-  };
-});
-
 // ../../_shared/mcp-tools/list-metadata-keys.ts
 async function handler5(supabase, args, ctx) {
   const { data, error: error2 } = await supabase.rpc("cerefox_list_metadata_keys");
@@ -55829,6 +56077,10 @@ var init_list_projects = __esm(() => {
 });
 
 // ../../_shared/mcp-tools/list-versions.ts
+function utcStamp3(iso) {
+  const trimmed = iso.slice(0, 19);
+  return trimmed.includes("T") ? `${trimmed}Z` : `${trimmed} UTC`;
+}
 async function handler7(supabase, args, ctx) {
   const document_id = args.document_id;
   if (!document_id)
@@ -55848,7 +56100,7 @@ async function handler7(supabase, args, ctx) {
   });
   if (!versions.length)
     return "No archived versions found for this document.";
-  const lines = versions.map((v) => `v${v.version_number} | ${v.created_at.slice(0, 10)} | ${v.source} | ${v.chunk_count} chunks / ${v.total_chars.toLocaleString()} chars | id: ${v.version_id}`);
+  const lines = versions.map((v) => `v${v.version_number} | ${utcStamp3(v.created_at)} | ${v.source} | ${v.chunk_count} chunks / ${v.total_chars.toLocaleString()} chars | id: ${v.version_id}`);
   return `Archived versions (newest first):
 
 ${lines.join(`
@@ -71898,16 +72150,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 +72187,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 +72285,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 +72295,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) {
@@ -72080,7 +72361,7 @@ function action6(options) {
     entry: options.local ? localCerefoxEntry() : undefined
   });
   if (options.json) {
-    printJson(result);
+    printJson({ ...result, serverName: mcpServerName() });
     return;
   }
   if (options.dryRun) {
@@ -72093,6 +72374,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}`));
   }
@@ -76314,19 +76596,14 @@ init_cli_core();
 
 // src/cli/util/checks.ts
 init_meta();
-import { existsSync as existsSync10, readFileSync as readFileSync7, realpathSync, statSync as statSync2 } from "node:fs";
-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";
-
-// src/cli/util/checks.ts
+init_ef_meta();
 init_config();
 init_config();
 init_compatibility();
 init_server_assets();
+import { existsSync as existsSync10, readFileSync as readFileSync7, realpathSync, statSync as statSync2 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import { join as join9 } from "node:path";
 function checkBinary() {
   return {
     name: "binary",
@@ -76812,7 +77089,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",
@@ -77083,7 +77361,7 @@ async function action16(options) {
     return;
   }
   printTable(data.map((row) => ({
-    when: (row.created_at ?? "").slice(0, 19).replace("T", " "),
+    when: `${(row.created_at ?? "").slice(0, 19).replace("T", " ")}Z`,
     operation: row.operation,
     doc: (row.doc_title ?? (row.document_id ?? "?").slice(0, 8) + "…").slice(0, 40),
     author: (row.author ?? "") + (row.author_type ? `(${row.author_type})` : ""),
@@ -77228,6 +77506,13 @@ init_cli_core();
 init_partial_edits();
 init_client();
 async function action17(documentId, options) {
+  const section = (options.section ?? "").trim() || null;
+  if (section && options.outline) {
+    throw userError("Pass either --outline (the whole structure) or --section (one section's text), not both.");
+  }
+  if (options.sectionPart && !section) {
+    throw userError("--section-part only applies together with --section.");
+  }
   const client = getClient();
   const rows = await client.rpc("cerefox_get_document", {
     p_document_id: documentId,
@@ -77275,6 +77560,35 @@ async function action17(documentId, options) {
     println(c.dim(`  --anchor ${JSON.stringify(nodes[nodes.length - 1].path)}`));
     return;
   }
+  if (section) {
+    let extracted;
+    try {
+      extracted = extractSection(doc.full_content ?? "", section, options.sectionPart);
+    } catch (err) {
+      throw userError(err instanceof Error ? err.message : String(err));
+    }
+    const archived = Boolean(options.versionId);
+    if (options.json) {
+      printJson({
+        title: doc.doc_title,
+        heading: extracted.heading,
+        path: extracted.path,
+        level: extracted.level,
+        section_part: extracted.section_part,
+        chars: extracted.chars,
+        content_hash: archived ? null : doc.content_hash ?? null,
+        text: extracted.text
+      });
+      return;
+    }
+    println(c.bold(extracted.heading));
+    println(c.dim(`[${doc.document_id}] · ${extracted.path} · ${extracted.chars} chars` + (extracted.section_part ? ` · ${extracted.section_part}` : "") + (archived ? " · archived" : "")));
+    if (!archived && doc.content_hash)
+      println(c.dim(`content_hash: ${doc.content_hash}`));
+    println("");
+    println(extracted.text);
+    return;
+  }
   if (options.json) {
     printJson(doc);
     return;
@@ -77288,7 +77602,7 @@ async function action17(documentId, options) {
   println(doc.full_content);
 }
 function registerGetDoc(program2) {
-  program2.command("get-doc").description("Retrieve the full content of a document by ID.").argument("<document-id>", "UUID of the document.").option("--version-id <uuid>", "Specific archived version (default: current).").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").option("--outline", "Show the heading structure, per-section sizes and content_hash instead of the content. Cheap, and the paths are the anchors the edit commands take.").action(action17);
+  program2.command("get-doc").description("Retrieve the full content of a document by ID.").argument("<document-id>", "UUID of the document.").option("--version-id <uuid>", "Specific archived version (default: current).").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").option("--outline", "Show the heading structure, per-section sizes and content_hash instead of the content. Cheap, and the paths are the anchors the edit commands take.").option("--section <anchor>", "Show ONE section's text instead of the whole document: exactly what a replace_section on this anchor would overwrite. Pass the bare heading line when it is unique, or the full ' > ' path from --outline when it repeats.").option("--section-part <part>", "own_body | subtree — only when the target section has child sections, where 'the end' means two different places. You are told (with both options) whenever it is needed.").action(action17);
 }
 
 // src/cli/commands/ingest.ts
@@ -77576,6 +77890,7 @@ class IngestionPipeline {
       text,
       title,
       source = "paste",
+      sourceOnCreate,
       sourceLabel,
       sourcePath: sourcePathOpt,
       projectName,
@@ -77678,7 +77993,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 +78019,7 @@ class IngestionPipeline {
     const rpcResult = await this.db.ingestDocumentRpc({
       documentId: null,
       title,
-      source,
+      source: source ?? sourceOnCreate ?? null,
       sourcePath,
       contentHash: hash,
       metadata: validatedMeta,
@@ -77725,7 +78041,8 @@ class IngestionPipeline {
       action: "created",
       reindexed: false,
       projectIds: resolvedIds,
-      note: ""
+      note: "",
+      contentHash: hash
     };
   }
   async updateDocument(opts) {
@@ -77817,7 +78134,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 +78169,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 +78188,8 @@ class IngestionPipeline {
       action: "updated",
       reindexed: true,
       projectIds: finalProjectIds,
-      note: ""
+      note: "",
+      contentHash: newHash
     };
   }
   async ingestFile(path, opts = {}) {
@@ -77881,7 +78200,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 +78273,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 +78281,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 +78295,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 +78318,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 +78471,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 +78505,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 +83979,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 +84576,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 +84747,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 +84812,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 +84865,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,
@@ -84993,6 +85320,7 @@ var ROOT_REDIRECT_HTML = `<!DOCTYPE html>
 
 // src/web/server.ts
 init_meta();
+init_ef_meta();
 init_cli_core();
 init_config();
 init_compatibility();