@cerefox/memory 1.6.0 → 1.7.0

package/dist/bin/cerefox.js

@@ -7438,7 +7438,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "1.6.0";
+var PKG_VERSION = "1.7.0";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -23427,6 +23427,82 @@ var init_client = __esm(() => {
   init_cli_core();
 });
 
+// ../../_shared/mcp-tools/_utils.ts
+function getMaxResponseBytes() {
+  const raw = globalThis.process?.env?.CEREFOX_MAX_RESPONSE_BYTES;
+  if (raw === undefined || raw === "")
+    return MAX_RESPONSE_BYTES;
+  const n = Number.parseInt(raw, 10);
+  return Number.isNaN(n) || n <= 0 ? MAX_RESPONSE_BYTES : n;
+}
+function readEnv(name) {
+  const g = globalThis;
+  const fromProcess = g.process?.env?.[name];
+  if (fromProcess !== undefined && fromProcess !== "")
+    return fromProcess;
+  try {
+    const fromDeno = g.Deno?.env?.get(name);
+    return fromDeno === "" ? undefined : fromDeno;
+  } catch {
+    return;
+  }
+}
+function getSearchAlpha() {
+  return DEFAULT_SEARCH_ALPHA;
+}
+function getMinSearchScore() {
+  return readEnv("CEREFOX_EMBEDDER") === "local" ? DEFAULT_MIN_SEARCH_SCORE_LOCAL : DEFAULT_MIN_SEARCH_SCORE;
+}
+function getConfiguredMinSearchScore() {
+  return;
+}
+function getConfiguredSearchAlpha() {
+  return;
+}
+function getMinTermCoverage() {
+  return;
+}
+function applyByteBudget(rows, maxBytes) {
+  const accepted = [];
+  let usedBytes = 0;
+  let truncated = false;
+  for (const row of rows) {
+    const rowBytes = new TextEncoder().encode(JSON.stringify(row)).length;
+    if (usedBytes + rowBytes > maxBytes) {
+      truncated = true;
+      break;
+    }
+    accepted.push(row);
+    usedBytes += rowBytes;
+  }
+  return { accepted, truncated, usedBytes };
+}
+function extractConflictHashes(message) {
+  return {
+    expected: message.match(/expected hash ([0-9a-f]{64})/)?.[1] ?? "unknown",
+    current: message.match(/current hash ([0-9a-f]{64})/)?.[1] ?? "unknown"
+  };
+}
+function isDocumentNotFoundError(error) {
+  return error.code === "22023" && /not found/i.test(error.message ?? "");
+}
+function isMissingFunctionError(message, fnName) {
+  return message.includes("Could not find the function") && message.includes(fnName) || message.includes("does not exist") && message.includes(fnName);
+}
+function logUsage(supabase, params) {
+  Promise.resolve(supabase.rpc("cerefox_log_usage", {
+    p_operation: params.operation,
+    p_access_path: params.accessPath,
+    p_requestor: params.requestor ?? "mcp-agent",
+    p_document_id: params.document_id ?? null,
+    p_project_id: params.project_id ?? null,
+    p_query_text: params.query_text ?? null,
+    p_result_count: params.result_count ?? null,
+    p_extra: params.extra ?? {}
+  })).catch(() => {});
+}
+var MAX_RESPONSE_BYTES = 200000, DEFAULT_MIN_SEARCH_SCORE = 0.5, DEFAULT_MIN_SEARCH_SCORE_LOCAL = 0.6, DEFAULT_SEARCH_ALPHA = 0.7;
+
 // ../../_shared/server-assets/index.ts
 import { existsSync as existsSync5 } from "node:fs";
 import { dirname as dirname2, join as join5 } from "node:path";
@@ -25466,70 +25542,6 @@ var init_src = __esm(() => {
   src_default = Postgres;
 });
 
-// ../../_shared/mcp-tools/_utils.ts
-function getMaxResponseBytes() {
-  const raw = globalThis.process?.env?.CEREFOX_MAX_RESPONSE_BYTES;
-  if (raw === undefined || raw === "")
-    return MAX_RESPONSE_BYTES;
-  const n = Number.parseInt(raw, 10);
-  return Number.isNaN(n) || n <= 0 ? MAX_RESPONSE_BYTES : n;
-}
-function readEnv(name) {
-  const g = globalThis;
-  const fromProcess = g.process?.env?.[name];
-  if (fromProcess !== undefined && fromProcess !== "")
-    return fromProcess;
-  try {
-    const fromDeno = g.Deno?.env?.get(name);
-    return fromDeno === "" ? undefined : fromDeno;
-  } catch {
-    return;
-  }
-}
-function getSearchAlpha() {
-  return DEFAULT_SEARCH_ALPHA;
-}
-function getMinSearchScore() {
-  return readEnv("CEREFOX_EMBEDDER") === "local" ? DEFAULT_MIN_SEARCH_SCORE_LOCAL : DEFAULT_MIN_SEARCH_SCORE;
-}
-function getConfiguredMinSearchScore() {
-  return;
-}
-function getConfiguredSearchAlpha() {
-  return;
-}
-function getMinTermCoverage() {
-  return;
-}
-function applyByteBudget(rows, maxBytes) {
-  const accepted = [];
-  let usedBytes = 0;
-  let truncated = false;
-  for (const row of rows) {
-    const rowBytes = new TextEncoder().encode(JSON.stringify(row)).length;
-    if (usedBytes + rowBytes > maxBytes) {
-      truncated = true;
-      break;
-    }
-    accepted.push(row);
-    usedBytes += rowBytes;
-  }
-  return { accepted, truncated, usedBytes };
-}
-function logUsage(supabase, params) {
-  Promise.resolve(supabase.rpc("cerefox_log_usage", {
-    p_operation: params.operation,
-    p_access_path: params.accessPath,
-    p_requestor: params.requestor ?? "mcp-agent",
-    p_document_id: params.document_id ?? null,
-    p_project_id: params.project_id ?? null,
-    p_query_text: params.query_text ?? null,
-    p_result_count: params.result_count ?? null,
-    p_extra: params.extra ?? {}
-  })).catch(() => {});
-}
-var MAX_RESPONSE_BYTES = 200000, DEFAULT_MIN_SEARCH_SCORE = 0.5, DEFAULT_MIN_SEARCH_SCORE_LOCAL = 0.6, DEFAULT_SEARCH_ALPHA = 0.7;
-
 // ../../_shared/mcp-tools/_projects.ts
 async function ensureDocumentInProject(supabase, documentId, projectName) {
   let projectId = null;
@@ -25731,7 +25743,7 @@ var init_bundled_docs = __esm(() => {
 });
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "1.6.0", CEREFOX_VERSION = "1.6.0", EF_LAST_CHANGED = "1.6.0";
+var EF_VERSION = "1.7.0", CEREFOX_VERSION = "1.7.0", EF_LAST_CHANGED = "1.7.0";
 var init_ef_meta = () => {};
 
 // ../../_shared/compatibility/index.ts
@@ -54803,6 +54815,186 @@ var init_audit_log = __esm(() => {
   };
 });
 
+// ../../_shared/mcp-tools/types.ts
+var McpInvalidParams;
+var init_types3 = __esm(() => {
+  McpInvalidParams = class McpInvalidParams extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "McpInvalidParams";
+    }
+  };
+});
+
+// ../../_shared/mcp-tools/delete-document.ts
+function conflictError(documentId, expectedHash, currentHash) {
+  return new Error(`Conflict: document ${documentId} changed since you read it ` + `(your base hash: ${expectedHash}, current hash: ${currentHash}). ` + `Someone wrote to this document after you decided to delete it. ` + `To resolve: (1) cerefox_get_document("${documentId}") to see the current ` + `content, (2) check the deletion is still warranted — the new content may ` + `change your mind, (3) if it is, retry with expected_content_hash set to ` + `the new hash. Do not delete blindly — the change may be another writer's work.`);
+}
+async function handler2(supabase, args, ctx) {
+  const document_id = args.document_id;
+  const expected_content_hash = args.expected_content_hash?.trim();
+  const reason = args.reason;
+  if (!document_id)
+    throw new McpInvalidParams("document_id is required");
+  if (!expected_content_hash) {
+    throw new McpInvalidParams("expected_content_hash is required: the content_hash of the document as you read it " + "(returned by cerefox_get_document, cerefox_search, and cerefox_metadata_search). " + "If you have not read the document, read it first — deletion requires knowing what " + "you are deleting.");
+  }
+  const author = args.author ?? args.requestor;
+  const authorType = ctx.accessPath === "cli" ? "user" : "agent";
+  const { data, error: error2 } = await supabase.rpc("cerefox_delete_document", {
+    p_document_id: document_id,
+    p_author: author ?? "unknown",
+    p_author_type: authorType,
+    p_expected_content_hash: expected_content_hash,
+    p_reason: reason ?? null
+  });
+  if (error2) {
+    const message = error2.message ?? String(error2);
+    if (message.includes("CEREFOX_CONFLICT")) {
+      const { expected, current } = extractConflictHashes(message);
+      throw conflictError(document_id, expected === "unknown" ? expected_content_hash : expected, current);
+    }
+    if (isMissingFunctionError(message, "cerefox_delete_document")) {
+      throw new Error(`This server is behind: cerefox_delete_document needs schema 0.12.0 or newer. ` + `Run \`cerefox server deploy\`, then retry. (${message})`);
+    }
+    if (isDocumentNotFoundError(error2)) {
+      throw new McpInvalidParams(`Document ${document_id} not found.`);
+    }
+    throw new Error(`RPC error: ${message}`);
+  }
+  const row = data;
+  if (!row)
+    throw new Error("cerefox_delete_document returned no data");
+  if (row.already_deleted) {
+    return `Document ${document_id} ("${row.title ?? "untitled"}") was ALREADY soft-deleted ` + `at ${row.deleted_at}. No change was made and no audit entry was written.`;
+  }
+  logUsage(supabase, {
+    operation: "delete",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor,
+    document_id,
+    result_count: 1
+  });
+  return `Soft-deleted "${row.title ?? "untitled"}" (id: ${document_id}, ` + `${row.total_chars ?? "?"} chars) at ${row.deleted_at}.
+` + `The document is excluded from search but fully recoverable: it sits in the ` + `trash until restored or purged. cerefox_restore_document undoes this if it ` + `was a mistake; permanent purge is human-only (web UI).
+` + `Tell your user what you deleted and why, so they can review it.`;
+}
+var deleteDocumentTool;
+var init_delete_document = __esm(() => {
+  init_types3();
+  deleteDocumentTool = {
+    name: "cerefox_delete_document",
+    description: "SOFT-delete a document: it leaves search results and lands in the trash, recoverable until a human purges it. Requires expected_content_hash — the content_hash of the document AS YOU READ IT — so a delete always follows a read; if the document changed in between, the call fails with a conflict and you should re-read before deciding again. A mistaken delete can be undone with cerefox_restore_document; permanent purge is human-only (web UI). ALWAYS tell your user what you deleted and why. Pass a short reason — it is recorded in the audit log for the human reviewing the trash. Prefer this over ingesting empty/placeholder content when a document should go away.",
+    annotations: {
+      title: "Delete document (soft, recoverable)",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    inputSchema: {
+      type: "object",
+      required: ["document_id", "expected_content_hash"],
+      properties: {
+        document_id: { type: "string", description: "UUID of the document to soft-delete." },
+        expected_content_hash: {
+          type: "string",
+          description: "The content_hash of the document as you read it (returned by cerefox_get_document, cerefox_search, and cerefox_metadata_search). Required: a delete must follow a read. A stale hash fails with a conflict — re-read, reconsider, retry with the new hash."
+        },
+        reason: {
+          type: "string",
+          description: "Why this document is being deleted. Recorded in the audit log entry, where it is the main thing the human reviewing the trash has to go on. Short and specific beats long."
+        },
+        author: {
+          type: "string",
+          description: "Who is making this change. Recorded in the audit log."
+        },
+        requestor: {
+          type: "string",
+          description: "Name of the agent or user making this request. Recorded in the usage log."
+        }
+      }
+    },
+    handler: handler2
+  };
+});
+
+// ../../_shared/mcp-tools/restore-document.ts
+async function handler3(supabase, args, ctx) {
+  const document_id = args.document_id;
+  const reason = args.reason;
+  if (!document_id)
+    throw new McpInvalidParams("document_id is required");
+  const author = args.author ?? args.requestor;
+  const authorType = ctx.accessPath === "cli" ? "user" : "agent";
+  const { data, error: error2 } = await supabase.rpc("cerefox_restore_document", {
+    p_document_id: document_id,
+    p_author: author ?? "unknown",
+    p_author_type: authorType,
+    p_reason: reason ?? null
+  });
+  if (error2) {
+    const message = error2.message ?? String(error2);
+    if (isMissingFunctionError(message, "cerefox_restore_document")) {
+      throw new Error(`This server is behind: cerefox_restore_document needs schema 0.12.0 or newer. ` + `Run \`cerefox server deploy\`, then retry. (${message})`);
+    }
+    if (isDocumentNotFoundError(error2)) {
+      throw new McpInvalidParams(`Document ${document_id} not found.`);
+    }
+    throw new Error(`RPC error: ${message}`);
+  }
+  const row = data;
+  if (!row)
+    throw new Error("cerefox_restore_document returned no data");
+  if (!row.restored) {
+    return `Document ${document_id} ("${row.title ?? "untitled"}") is NOT deleted — ` + `there is nothing to restore. No change was made.`;
+  }
+  logUsage(supabase, {
+    operation: "restore",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor,
+    document_id,
+    result_count: 1
+  });
+  return `Restored "${row.title ?? "untitled"}" (id: ${document_id}, ` + `${row.total_chars ?? "?"} chars) from the trash. It is searchable again ` + `and the restore is recorded in the audit log.
+` + `Tell your user what you restored and why.`;
+}
+var restoreDocumentTool;
+var init_restore_document = __esm(() => {
+  init_types3();
+  restoreDocumentTool = {
+    name: "cerefox_restore_document",
+    description: "Restore a soft-deleted document from the trash — the inverse of cerefox_delete_document. The document becomes searchable again; the restore is recorded in the audit log with your identity. Restoring a document that is not deleted is a reported no-op. Pass a short reason — like a delete's reason, it is what the human reviewing the audit trail goes on. Permanent purge has no agent surface: once a human purges a document from the web UI, it is gone and cannot be restored.",
+    annotations: {
+      title: "Restore document from trash",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    inputSchema: {
+      type: "object",
+      required: ["document_id"],
+      properties: {
+        document_id: { type: "string", description: "UUID of the soft-deleted document to restore." },
+        reason: {
+          type: "string",
+          description: "Why this document is being restored. Recorded in the audit-log entry. Short and specific beats long."
+        },
+        author: {
+          type: "string",
+          description: "Who is making this change. Recorded in the audit log."
+        },
+        requestor: {
+          type: "string",
+          description: "Name of the agent or user making this request. Recorded in the usage log."
+        }
+      }
+    },
+    handler: handler3
+  };
+});
+
 // ../../_shared/mcp-tools/feature-flags.ts
 async function relationsEnabled(supabase) {
   if (cached && Date.now() - cached.at < CACHE_TTL_MS)
@@ -54833,17 +55025,6 @@ var init_feature_flags = __esm(() => {
   ]);
 });
 
-// ../../_shared/mcp-tools/types.ts
-var McpInvalidParams;
-var init_types3 = __esm(() => {
-  McpInvalidParams = class McpInvalidParams extends Error {
-    constructor(message) {
-      super(message);
-      this.name = "McpInvalidParams";
-    }
-  };
-});
-
 // ../../_shared/mcp-tools/relations.ts
 function requireUuid2(value, field) {
   const s = typeof value === "string" ? value.trim() : "";
@@ -55069,7 +55250,7 @@ var init_relations = __esm(() => {
 });
 
 // ../../_shared/mcp-tools/get-document.ts
-async function handler2(supabase, args, ctx) {
+async function handler4(supabase, args, ctx) {
   const document_id = args.document_id;
   const version_id = args.version_id ?? null;
   const outline = args.outline ?? false;
@@ -55182,7 +55363,7 @@ var init_get_document = __esm(() => {
         }
       }
     },
-    handler: handler2
+    handler: handler4
   };
 });
 
@@ -55228,10 +55409,19 @@ function shrinkNote(before, afterChars, applied) {
   return `⚠ This edit removed ${lost} characters (${pct}% smaller). ${why}cerefox_list_versions has the previous content.
 `;
 }
-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}). 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) {
+  try {
+    const { data: lifecycle } = await supabase.from("cerefox_documents").select("deleted_at").eq("id", documentId).maybeSingle();
+    if (lifecycle?.deleted_at) {
+      throw new McpInvalidParams(`Document ${documentId} is soft-deleted (in the trash). A trashed document ` + `cannot be edited — restore it first with cerefox_restore_document, then retry.`);
+    }
+  } catch (e) {
+    if (e instanceof McpInvalidParams)
+      throw e;
+  }
   const { data, error: error2 } = await supabase.rpc("cerefox_get_document", {
     p_document_id: documentId,
     p_version_id: null
@@ -55255,7 +55445,7 @@ async function applyAndWrite(supabase, ctx, args) {
   }
   const doc = await readDocument(supabase, documentId);
   if (doc.hash && expectedHash !== doc.hash) {
-    throw conflictError(documentId, expectedHash, doc.hash);
+    throw conflictError2(documentId, expectedHash, doc.hash);
   }
   let assembled;
   let applied;
@@ -55306,13 +55496,19 @@ async function applyAndWrite(supabase, ctx, args) {
   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);
+      throw conflictError2(documentId, expectedHash, extractConflictHashes(message).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")) {
+    if (message.includes("CEREFOX_UNRESOLVED_LINKS")) {
+      const ids = message.match(/do not exist: ([^.]+)\./)?.[1] ?? "(unparsed)";
+      throw new Error(`Edit rejected — this edit introduces link(s) to document id(s) that do not ` + `exist: ${ids}. The UUIDs are almost certainly mangled — re-read the source ` + `you copied each link from, correct the id(s), and retry. Do not retry ` + `unchanged. Deliberate examples belong in code formatting (backticks).`);
+    }
+    if (message.includes("CEREFOX_DELETED")) {
+      throw new Error(`Document ${documentId} was soft-deleted while this edit was in flight. ` + `Restore it first with cerefox_restore_document, then retry.`);
+    }
+    if (isMissingFunctionError(message, "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}`);
@@ -55522,12 +55718,12 @@ var init_partial_edits2 = __esm(() => {
 });
 
 // ../../_shared/mcp-tools/get-help-content.ts
-var HELP_FULL = '# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **17 MCP tools** (16 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for "How AI Agents Use Cerefox" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part` |\n| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required) |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: "## Heading"` one section\'s text | `document_id` (required), `outline`, `section`, `section_part` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project\'s docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_metadata` | Change tags WITHOUT resending content. **Merges** by default; a `null` value removes a key | `document_id`, `metadata` (required), `replace` (rare: set exactly this object), `author` |\n| `cerefox_set_document_projects` | Set doc\'s project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.\n\n## Editing part of a document (prefer this over re-sending)\n\n**Re-sending a whole document to change part of it is the main way agents lose\ndata.** You have to reproduce the untouched remainder verbatim, and any drift\nsilently rewrites content nobody asked you to touch — which the caller cannot\ndiff. Use the partial-edit tools instead:\n\n1. **Learn the anchors** — `cerefox_get_document(document_id, outline: true)`.\n   Returns heading paths, per-section sizes and the `content_hash`, without the\n   body. The paths it returns are exactly what `anchor_heading` accepts.\n2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;\n   `end_of_section` adds inside a named section. It is structurally incapable of\n   removing anything, so "I meant to append" cannot become "I replaced the file".\n3. **Look before you overwrite** — `cerefox_get_document(document_id,\n   section: "## Heading")` returns exactly the text a `replace_section` on that\n   anchor would destroy. The outline gives you a section\'s *size*, never its\n   *text*, so on a document you did not write yourself this is the difference\n   between a replace and a blind overwrite.\n4. **Change or remove** → `cerefox_edit`. Put changes that belong together in\n   ONE call: they apply atomically, so a table row and the total it feeds cannot\n   end up disagreeing. To change a single line, `replace_section` on its\n   smallest enclosing heading — that is the intended granularity, not a\n   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use\n   `rename_section`: it changes the heading text and leaves the body and\n   position alone.\n5. All of them require `expected_content_hash` and **have no last-write-wins**. A\n   conflict means someone else changed the document; re-read and decide, do not\n   force it.\n\n**A section runs to the next same-or-higher heading, or to the end of the\ndocument.** So `end_of_document` inserts land inside the *last* section, and\nreplacing or deleting that section removes them too. A large shrink in the\nresponse is your warning; `cerefox_list_versions` has the previous content.\n\n**When an anchor is ambiguous the tool refuses and hands you the options** — a\nrepeated heading returns the qualifying paths, and a section with both its own\ncontent and sub-sections returns both `section_part` choices. That is a\nrecoverable answer, not a failure: retry with what it gave you.\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., "Claude Code", "archiver"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch("topic") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title="Same Title", content="...", document_id="abc123",\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch("topic") -> find doc (note its hash) -> modify ->\ningest(title="Same Title", content="...", update_if_exists=true,\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03-28T00:00:00Z")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --expected-content-hash "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_metadata` | `cerefox document set-metadata <id> --set key=value` (also `--remove key`, `--json \'{...}\'`, `--replace`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n\n## Timestamps are UTC\n\nEvery timestamp Cerefox returns — `created_at` on audit entries, version\nhistory, document metadata — is **UTC**, and now carries its `Z` marker so it\ncannot be mistaken for local time.\n\n**When you write a date into a document\'s CONTENT, use your own clock, not a\nCerefox timestamp.** These are different things: a timestamp records when the\nserver stored something; a date in a log entry or a heading is authored content\nand belongs to your timezone. An agent working a Pacific afternoon read\n`2026-08-11` from version history, wrote "8/11" into its entries, and put a\nday\'s work in the future — the timestamp was correct, and copying it into\ncontent was not.\n\nCerefox deliberately does not convert to local time on the API or MCP paths.\n"Local" has no server-side meaning: the remote MCP server runs in a cloud\nfunction whose local time *is* UTC, while a local MCP server runs in yours, so\nthe same document would report two different times depending on transport. The\nweb UI converts because a browser knows the viewer\'s timezone; nothing\nserver-side does.\n\n## Mistakes that have actually happened\n\nEach of these comes from a real agent session, and each is easy to make.\n\n- **`cerefox_ingest` always replaces the ENTIRE document.** Never a section.\n  Before sending, check that the tool name matches the intent: if the intent is\n  "change one section", the call is `cerefox_edit` with `replace_section`. A\n  section-sized edit sent as a full ingest truncated a 13,000-character index to\n  a single word. It was recovered from version history within the minute, but\n  only because it was noticed immediately.\n\n- **Do not include the anchor\'s own heading in your text.** `replace_section`\n  keeps the heading and `insert` places your text inside the section, so\n  including it produces two. This is now refused rather than silently applied,\n  but the shape is worth knowing: it happened twice in one session, the second\n  time while trying to repair the first. A *deeper* sub-heading inside your text\n  is fine.\n\n- **Content between sections belongs to the section ABOVE it.** A section runs\n  to the next heading of the same or higher level, so a `---` rule, a note, or\n  any trailing text sitting just above the next heading is part of the section\n  before it — even when it visually reads as belonging below. Replacing that\n  section takes it too. An agent hit exactly this: a `---` that separated two\n  major sections disappeared when the section above it was replaced. The write\n  was correct by the addressing rules; the surprise is that "the end of this\n  section" is further down the page than it looks. Note the loss warning will\n  not catch it if your replacement text is longer than what it replaced, since\n  there is then no net loss to report.\n\n- **To change only tags, use `cerefox_set_document_metadata`, never `cerefox_ingest`.**\n  Ingest replaces the whole document, so re-sending it to set one tag carries the\n  full transcription risk for no reason. The metadata tool merges: the keys you\n  pass are set, everything else is left alone, so you do not need to read the\n  document first and cannot drop a tag another agent set. Pass `null` as a value\n  to remove a key.\n\n- **Never partial-edit to fix a partial edit.** If a write leaves unexpected\n  structure, stop. Use `cerefox_list_versions`, retrieve the last good version,\n  and re-ingest cleanly. Repairing edits with more edits compounds the damage.\n\n- **A rejected batch is safe.** Operations in one `cerefox_edit` are\n  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a\n  retry, not data — so prefer one call for changes that belong together, and do\n  not split a batch to "make it more likely to succeed".\n\n- **Read before replacing.** `cerefox_get_document(section: "## Heading")`\n  returns exactly what a `replace_section` on that anchor would overwrite. Use it\n  for any section you did not write in this session. The outline gives a\n  section\'s *size*, never its *text*.\n\n- **Verify after writing** — read the result back before reporting success, and\n  report what the read actually shows.\n\n- **Partial edits cannot change a document\'s stored TITLE.** `rename_section`\n  changes a heading inside the content; the title is a separate field and still\n  needs `cerefox_ingest`.\n\n- **If a capability seems missing from one server, suspect your client first.**\n  Local and remote run the same code. **Every `cerefox_get_help()` response\n  begins with the server\'s version and the operations it registers** — you do\n  not need a special topic, and the *absence* of that block is itself an answer:\n  a server that does not print it predates v1.5.0. If that\n  disagrees with your tool list, the client is holding a list it fetched before\n  an upgrade — clients cache it at connect time. Ask the user to restart the\n  client. Do not record a capability difference between servers as a fact; every\n  such report so far has been a stale client.\n', HELP_SECTIONS, HELP_SECTION_HEADINGS;
+var HELP_FULL = '# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **19 MCP tools** (18 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_delete_document` | **Soft**-delete a document (to trash; excluded from search; permanent purge is human-only) | `document_id`, `expected_content_hash` (**required** — a delete must follow a read), `reason` (recorded in the audit log — give one), `author` |\n| `cerefox_restore_document` | Restore a soft-deleted document from the trash (audited inverse of delete; no-op if not deleted) | `document_id` (required), `reason` (recorded in the audit log), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: "## Heading"` one section\'s text | `document_id` (required), `outline`, `section`, `section_part` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project\'s docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_metadata` | Change tags WITHOUT resending content. **Merges** by default; a `null` value removes a key | `document_id`, `metadata` (required), `replace` (rare: set exactly this object), `author` |\n| `cerefox_set_document_projects` | Set doc\'s project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.\n\n## Editing part of a document (prefer this over re-sending)\n\n**Re-sending a whole document to change part of it is the main way agents lose\ndata.** You have to reproduce the untouched remainder verbatim, and any drift\nsilently rewrites content nobody asked you to touch — which the caller cannot\ndiff. Use the partial-edit tools instead:\n\n1. **Learn the anchors** — `cerefox_get_document(document_id, outline: true)`.\n   Returns heading paths, per-section sizes and the `content_hash`, without the\n   body. The paths it returns are exactly what `anchor_heading` accepts.\n2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;\n   `end_of_section` adds inside a named section. It is structurally incapable of\n   removing anything, so "I meant to append" cannot become "I replaced the file".\n3. **Look before you overwrite** — `cerefox_get_document(document_id,\n   section: "## Heading")` returns exactly the text a `replace_section` on that\n   anchor would destroy. The outline gives you a section\'s *size*, never its\n   *text*, so on a document you did not write yourself this is the difference\n   between a replace and a blind overwrite.\n4. **Change or remove** → `cerefox_edit`. Put changes that belong together in\n   ONE call: they apply atomically, so a table row and the total it feeds cannot\n   end up disagreeing. To change a single line, `replace_section` on its\n   smallest enclosing heading — that is the intended granularity, not a\n   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use\n   `rename_section`: it changes the heading text and leaves the body and\n   position alone.\n5. All of them require `expected_content_hash` and **have no last-write-wins**. A\n   conflict means someone else changed the document; re-read and decide, do not\n   force it.\n\n**A section runs to the next same-or-higher heading, or to the end of the\ndocument.** So `end_of_document` inserts land inside the *last* section, and\nreplacing or deleting that section removes them too. A large shrink in the\nresponse is your warning; `cerefox_list_versions` has the previous content.\n\n**When an anchor is ambiguous the tool refuses and hands you the options** — a\nrepeated heading returns the qualifying paths, and a section with both its own\ncontent and sub-sections returns both `section_part` choices. That is a\nrecoverable answer, not a failure: retry with what it gave you.\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., "Claude Code", "archiver"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); permanent purge is web-UI-only.** `cerefox_delete_document` requires the document\'s `content_hash` as you read it (read before you delete) and takes a `reason` — give one; it is what the human reviewing the trash sees. `cerefox_restore_document` undoes a mistaken delete (also audited, also takes a `reason`). Always surface deletes AND restores to the user. Once a human purges from the web UI, the document is gone for good.\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. **The server validates `](uuid)` links on every write** (v1.7.0): a link to a nonexistent id rejects the write, naming the offender — that means you mangled the UUID; re-read the source and correct it, do not retry unchanged. Example ids go in backticks (code is not validated). `[[Wikilinks]]` may dangle. 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_insert` | `cerefox document insert <id> -t "<text>" -p <position> -a "<anchor-heading>" -e "<hash>" --requestor "<your-name>" --author-type agent` |\n| `cerefox_edit` | `cerefox document edit-parts <id> --operations \'<json>\' -e "<hash>" --requestor "<your-name>" --author-type agent` |\n| `cerefox_delete_document` | `cerefox document delete <id> --reason "<why>" --author "<your-name>" --author-type agent --yes` (confirms interactively instead of requiring the hash) |\n| `cerefox_restore_document` | `cerefox document restore <id> --reason "<why>" --author "<your-name>" --author-type agent` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_metadata` | `cerefox document set-metadata <id> --set key=value` (also `--remove key`, `--json \'{...}\'`, `--replace`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n\n## Timestamps are UTC\n\nEvery timestamp Cerefox returns — `created_at` on audit entries, version\nhistory, document metadata — is **UTC**, and now carries its `Z` marker so it\ncannot be mistaken for local time.\n\n**When you write a date into a document\'s CONTENT, use your own clock, not a\nCerefox timestamp.** These are different things: a timestamp records when the\nserver stored something; a date in a log entry or a heading is authored content\nand belongs to your timezone. An agent working a Pacific afternoon read\n`2026-08-11` from version history, wrote "8/11" into its entries, and put a\nday\'s work in the future — the timestamp was correct, and copying it into\ncontent was not.\n\nCerefox deliberately does not convert to local time on the API or MCP paths.\n"Local" has no server-side meaning: the remote MCP server runs in a cloud\nfunction whose local time *is* UTC, while a local MCP server runs in yours, so\nthe same document would report two different times depending on transport. The\nweb UI converts because a browser knows the viewer\'s timezone; nothing\nserver-side does.\n\n## Mistakes that have actually happened\n\nEach of these comes from a real agent session, and each is easy to make.\n\n- **`cerefox_ingest` always replaces the ENTIRE document.** Never a section.\n  Before sending, check that the tool name matches the intent: if the intent is\n  "change one section", the call is `cerefox_edit` with `replace_section`. A\n  section-sized edit sent as a full ingest truncated a 13,000-character index to\n  a single word. It was recovered from version history within the minute, but\n  only because it was noticed immediately.\n\n- **Do not include the anchor\'s own heading in your text.** `replace_section`\n  keeps the heading and `insert` places your text inside the section, so\n  including it produces two. This is now refused rather than silently applied,\n  but the shape is worth knowing: it happened twice in one session, the second\n  time while trying to repair the first. A *deeper* sub-heading inside your text\n  is fine.\n\n- **Content between sections belongs to the section ABOVE it.** A section runs\n  to the next heading of the same or higher level, so a `---` rule, a note, or\n  any trailing text sitting just above the next heading is part of the section\n  before it — even when it visually reads as belonging below. Replacing that\n  section takes it too. An agent hit exactly this: a `---` that separated two\n  major sections disappeared when the section above it was replaced. The write\n  was correct by the addressing rules; the surprise is that "the end of this\n  section" is further down the page than it looks. Note the loss warning will\n  not catch it if your replacement text is longer than what it replaced, since\n  there is then no net loss to report.\n\n- **To change only tags, use `cerefox_set_document_metadata`, never `cerefox_ingest`.**\n  Ingest replaces the whole document, so re-sending it to set one tag carries the\n  full transcription risk for no reason. The metadata tool merges: the keys you\n  pass are set, everything else is left alone, so you do not need to read the\n  document first and cannot drop a tag another agent set. Pass `null` as a value\n  to remove a key.\n\n- **Never partial-edit to fix a partial edit.** If a write leaves unexpected\n  structure, stop. Use `cerefox_list_versions`, retrieve the last good version,\n  and re-ingest cleanly. Repairing edits with more edits compounds the damage.\n\n- **A rejected batch is safe.** Operations in one `cerefox_edit` are\n  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a\n  retry, not data — so prefer one call for changes that belong together, and do\n  not split a batch to "make it more likely to succeed".\n\n- **Read before replacing.** `cerefox_get_document(section: "## Heading")`\n  returns exactly what a `replace_section` on that anchor would overwrite. Use it\n  for any section you did not write in this session. The outline gives a\n  section\'s *size*, never its *text*.\n\n- **Verify after writing** — read the result back before reporting success, and\n  report what the read actually shows.\n\n- **Partial edits cannot change a document\'s stored TITLE.** `rename_section`\n  changes a heading inside the content; the title is a separate field and still\n  needs `cerefox_ingest`.\n\n- **If a capability seems missing from one server, suspect your client first.**\n  Local and remote run the same code. **Every `cerefox_get_help()` response\n  begins with the server\'s version and the operations it registers** — you do\n  not need a special topic, and the *absence* of that block is itself an answer:\n  a server that does not print it predates v1.5.0. If that\n  disagrees with your tool list, the client is holding a list it fetched before\n  an upgrade — clients cache it at connect time. Ask the user to restart the\n  client. Do not record a capability difference between servers as a fact; every\n  such report so far has been a stale client.\n', HELP_SECTIONS, HELP_SECTION_HEADINGS;
 var init_get_help_content = __esm(() => {
   HELP_SECTIONS = {
-    Tools: "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part` |\n| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required) |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: \"## Heading\"` one section's text | `document_id` (required), `outline`, `section`, `section_part` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_metadata` | Change tags WITHOUT resending content. **Merges** by default; a `null` value removes a key | `document_id`, `metadata` (required), `replace` (rare: set exactly this object), `author` |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.",
+    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_delete_document` | **Soft**-delete a document (to trash; excluded from search; permanent purge is human-only) | `document_id`, `expected_content_hash` (**required** — a delete must follow a read), `reason` (recorded in the audit log — give one), `author` |\n| `cerefox_restore_document` | Restore a soft-deleted document from the trash (audited inverse of delete; no-op if not deleted) | `document_id` (required), `reason` (recorded in the audit log), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: \"## Heading\"` one section's text | `document_id` (required), `outline`, `section`, `section_part` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_metadata` | Change tags WITHOUT resending content. **Merges** by default; a `null` value removes a key | `document_id`, `metadata` (required), `replace` (rare: set exactly this object), `author` |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.",
     "Editing part of a document (prefer this over re-sending)": '## Editing part of a document (prefer this over re-sending)\n\n**Re-sending a whole document to change part of it is the main way agents lose\ndata.** You have to reproduce the untouched remainder verbatim, and any drift\nsilently rewrites content nobody asked you to touch — which the caller cannot\ndiff. Use the partial-edit tools instead:\n\n1. **Learn the anchors** — `cerefox_get_document(document_id, outline: true)`.\n   Returns heading paths, per-section sizes and the `content_hash`, without the\n   body. The paths it returns are exactly what `anchor_heading` accepts.\n2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;\n   `end_of_section` adds inside a named section. It is structurally incapable of\n   removing anything, so "I meant to append" cannot become "I replaced the file".\n3. **Look before you overwrite** — `cerefox_get_document(document_id,\n   section: "## Heading")` returns exactly the text a `replace_section` on that\n   anchor would destroy. The outline gives you a section\'s *size*, never its\n   *text*, so on a document you did not write yourself this is the difference\n   between a replace and a blind overwrite.\n4. **Change or remove** → `cerefox_edit`. Put changes that belong together in\n   ONE call: they apply atomically, so a table row and the total it feeds cannot\n   end up disagreeing. To change a single line, `replace_section` on its\n   smallest enclosing heading — that is the intended granularity, not a\n   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use\n   `rename_section`: it changes the heading text and leaves the body and\n   position alone.\n5. All of them require `expected_content_hash` and **have no last-write-wins**. A\n   conflict means someone else changed the document; re-read and decide, do not\n   force it.\n\n**A section runs to the next same-or-higher heading, or to the end of the\ndocument.** So `end_of_document` inserts land inside the *last* section, and\nreplacing or deleting that section removes them too. A large shrink in the\nresponse is your warning; `cerefox_list_versions` has the previous content.\n\n**When an anchor is ambiguous the tool refuses and hands you the options** — a\nrepeated heading returns the qualifying paths, and a section with both its own\ncontent and sub-sections returns both `section_part` choices. That is a\nrecoverable answer, not a failure: retry with what it gave you.',
-    "Essential Rules": '## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., "Claude Code", "archiver"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.',
+    "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); permanent purge is web-UI-only.** `cerefox_delete_document` requires the document\'s `content_hash` as you read it (read before you delete) and takes a `reason` — give one; it is what the human reviewing the trash sees. `cerefox_restore_document` undoes a mistaken delete (also audited, also takes a `reason`). Always surface deletes AND restores to the user. Once a human purges from the web UI, the document is gone for good.\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. **The server validates `](uuid)` links on every write** (v1.7.0): a link to a nonexistent id rejects the write, naming the offender — that means you mangled the UUID; re-read the source and correct it, do not retry unchanged. Example ids go in backticks (code is not validated). `[[Wikilinks]]` may dangle. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.',
     "Update Workflow (ID-based -- preferred)": `## Update Workflow (ID-based -- preferred)
 
 \`\`\`
@@ -55539,7 +55735,7 @@ ingest(title="Same Title", content="...", document_id="abc123",
 On a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.`,
     "Update Workflow (title-based -- fallback)": '## Update Workflow (title-based -- fallback)\n\n```\nsearch("topic") -> find doc (note its hash) -> modify ->\ningest(title="Same Title", content="...", update_if_exists=true,\n       expected_content_hash="<the hash you read>", author="my-agent")\n```',
     "Catch-Up Workflow": '## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03-28T00:00:00Z")\n```',
-    "CLI fallback (when MCP is unavailable)": '## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --expected-content-hash "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_metadata` | `cerefox document set-metadata <id> --set key=value` (also `--remove key`, `--json \'{...}\'`, `--replace`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.',
+    "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_insert` | `cerefox document insert <id> -t "<text>" -p <position> -a "<anchor-heading>" -e "<hash>" --requestor "<your-name>" --author-type agent` |\n| `cerefox_edit` | `cerefox document edit-parts <id> --operations \'<json>\' -e "<hash>" --requestor "<your-name>" --author-type agent` |\n| `cerefox_delete_document` | `cerefox document delete <id> --reason "<why>" --author "<your-name>" --author-type agent --yes` (confirms interactively instead of requiring the hash) |\n| `cerefox_restore_document` | `cerefox document restore <id> --reason "<why>" --author "<your-name>" --author-type agent` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_metadata` | `cerefox document set-metadata <id> --set key=value` (also `--remove key`, `--json \'{...}\'`, `--replace`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.',
     "Timestamps are UTC": `## Timestamps are UTC
 
 Every timestamp Cerefox returns — \`created_at\` on audit entries, version
@@ -55652,7 +55848,7 @@ function serverIdentity() {
   ].join(`
 `);
 }
-async function handler3(supabase, args, ctx) {
+async function handler5(supabase, args, ctx) {
   const topic = args.topic?.trim();
   logUsage(supabase, {
     operation: "get_help",
@@ -55730,19 +55926,26 @@ var init_get_help = __esm(() => {
         }
       }
     },
-    handler: handler3
+    handler: handler5
   };
 });
 
 // ../../_shared/mcp-tools/ingest.ts
-function conflictError2(documentId, expectedHash, currentHash) {
+function conflictError3(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 conflictError2(documentId, expected, current);
+    const { expected, current } = extractConflictHashes(message);
+    return conflictError3(documentId, expected, current);
+  }
+  if (message.includes("CEREFOX_UNRESOLVED_LINKS")) {
+    const ids = message.match(/do not exist: ([^.]+)\./)?.[1] ?? "(unparsed)";
+    return new Error(`Write rejected — the content links document id(s) that do not exist: ${ids}. ` + `These are almost certainly mangled UUIDs (long random ids corrupt easily when ` + `regenerated). Do NOT retry unchanged: re-read the SOURCE you copied each link ` + `from, correct the id(s), and resend. If an id is a deliberate example rather ` + `than a real link, put it in code formatting (backticks or a fence).`);
+  }
+  if (message.includes("CEREFOX_DELETED")) {
+    const id = message.match(/document ([0-9a-f-]{36})/)?.[1] ?? documentId;
+    return new Error(`Document ${id} is soft-deleted (in the trash). A trashed document cannot be ` + `updated — restore it first with cerefox_restore_document, then retry, or ` + `create a new document instead.`);
   }
   if (message.includes("CEREFOX_TOKEN_REQUIRED")) {
     const current = message.match(/Current hash: ([0-9a-f]{64})/)?.[1];
@@ -55750,7 +55953,7 @@ function mapIngestRpcError(message, documentId) {
   }
   return new Error(`Ingest RPC failed: ${message}`);
 }
-async function handler4(supabase, args, ctx) {
+async function handler6(supabase, args, ctx) {
   const title = args.title?.trim();
   const content = args.content;
   const document_id = args.document_id ?? null;
@@ -55779,17 +55982,20 @@ async function handler4(supabase, args, ctx) {
   const contentHash2 = await sha256hex(normalizeContent(content));
   const reviewStatus = author_type === "agent" ? "pending_review" : "approved";
   if (document_id) {
-    const { data: existing } = await supabase.from("cerefox_documents").select("id, title, content_hash").eq("id", document_id).is("deleted_at", null).limit(1);
+    const { data: existing } = await supabase.from("cerefox_documents").select("id, title, content_hash, deleted_at").eq("id", document_id).limit(1);
     if (!existing?.length) {
       throw new Error(`Document not found: ${document_id}`);
     }
     const existingDoc = existing[0];
+    if (existingDoc.deleted_at) {
+      throw new McpInvalidParams(`Document ${document_id} ("${existingDoc.title}") is soft-deleted (in the trash). ` + `A trashed document cannot be updated — restore it first with ` + `cerefox_restore_document, then retry, or create a new document instead.`);
+    }
     if (existingDoc.content_hash === contentHash2) {
       const note2 = update_if_exists ? "" : " Note: update_if_exists flag was overridden by document_id.";
       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 conflictError2(existingDoc.id, expected_content_hash, existingDoc.content_hash);
+      throw conflictError3(existingDoc.id, expected_content_hash, existingDoc.content_hash);
     }
     const chunks2 = chunkMarkdown(content);
     if (chunks2.length === 0)
@@ -55840,14 +56046,20 @@ async function handler4(supabase, args, ctx) {
     return `Document updated: "${title}" (id: ${existingDoc.id}), ${chunks2.length} chunk(s), ${totalChars2} chars. New content_hash: ${contentHash2}.${note}`;
   }
   if (update_if_exists) {
-    const { data: existing } = await supabase.from("cerefox_documents").select("id, title, content_hash").eq("title", title).order("updated_at", { ascending: false }).limit(1);
+    let { data: existing } = await supabase.from("cerefox_documents").select("id, title, content_hash, deleted_at").eq("title", title).is("deleted_at", null).order("updated_at", { ascending: false }).limit(1);
+    if (!existing?.length) {
+      ({ data: existing } = await supabase.from("cerefox_documents").select("id, title, content_hash, deleted_at").eq("title", title).order("updated_at", { ascending: false }).limit(1));
+    }
     if (existing?.length) {
       const existingDoc = existing[0];
+      if (existingDoc.deleted_at) {
+        throw new McpInvalidParams(`A document titled "${existingDoc.title}" is in the trash (soft-deleted, ` + `id: ${existingDoc.id}). Restore it first with cerefox_restore_document ` + `and re-ingest to update it — or have your user purge it from the web UI ` + `Trash to start fresh.`);
+      }
       if (existingDoc.content_hash === contentHash2) {
         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 conflictError2(existingDoc.id, expected_content_hash, existingDoc.content_hash);
+        throw conflictError3(existingDoc.id, expected_content_hash, existingDoc.content_hash);
       }
       const chunks2 = chunkMarkdown(content);
       if (chunks2.length === 0)
@@ -55897,8 +56109,11 @@ async function handler4(supabase, args, ctx) {
       return `Document updated: "${existingDoc.title}" (id: ${existingDoc.id}), ${chunks2.length} chunk(s), ${totalChars2} chars. New content_hash: ${contentHash2}.`;
     }
   }
-  const { data: hashMatch } = await supabase.from("cerefox_documents").select("id, title").eq("content_hash", contentHash2).limit(1);
+  const { data: hashMatch } = await supabase.from("cerefox_documents").select("id, title, deleted_at").eq("content_hash", contentHash2).limit(1);
   if (hashMatch?.length) {
+    if (hashMatch[0].deleted_at) {
+      return `This exact content is already in the TRASH as "${hashMatch[0].title}" ` + `(soft-deleted, id: ${hashMatch[0].id}). Restore it with ` + `cerefox_restore_document instead of re-ingesting — or have your user ` + `purge it from the web UI Trash to start fresh.`;
+    }
     return `Document already up-to-date: "${hashMatch[0].title}" (id: ${hashMatch[0].id}). Content hash unchanged (${contentHash2}) — pass it as expected_content_hash to edit it.`;
   }
   const chunks = chunkMarkdown(content);
@@ -56002,12 +56217,12 @@ var init_ingest = __esm(() => {
         }
       }
     },
-    handler: handler4
+    handler: handler6
   };
 });
 
 // ../../_shared/mcp-tools/list-metadata-keys.ts
-async function handler5(supabase, args, ctx) {
+async function handler7(supabase, args, ctx) {
   const { data, error: error2 } = await supabase.rpc("cerefox_list_metadata_keys");
   if (error2)
     throw new Error(`RPC error: ${error2.message}`);
@@ -56042,12 +56257,12 @@ var init_list_metadata_keys = __esm(() => {
         }
       }
     },
-    handler: handler5
+    handler: handler7
   };
 });
 
 // ../../_shared/mcp-tools/list-projects.ts
-async function handler6(supabase, args, ctx) {
+async function handler8(supabase, args, ctx) {
   const { data, error: error2 } = await supabase.rpc("cerefox_list_projects");
   if (error2)
     throw new Error(`RPC error: ${error2.message}`);
@@ -56089,7 +56304,7 @@ var init_list_projects = __esm(() => {
         }
       }
     },
-    handler: handler6
+    handler: handler8
   };
 });
 
@@ -56098,7 +56313,7 @@ function utcStamp3(iso) {
   const trimmed = iso.slice(0, 19);
   return trimmed.includes("T") ? `${trimmed}Z` : `${trimmed} UTC`;
 }
-async function handler7(supabase, args, ctx) {
+async function handler9(supabase, args, ctx) {
   const document_id = args.document_id;
   if (!document_id)
     throw new McpInvalidParams("document_id is required");
@@ -56149,12 +56364,12 @@ var init_list_versions = __esm(() => {
         }
       }
     },
-    handler: handler7
+    handler: handler9
   };
 });
 
 // ../../_shared/mcp-tools/metadata-search.ts
-async function handler8(supabase, args, ctx) {
+async function handler10(supabase, args, ctx) {
   const metadata_filter = args.metadata_filter;
   const project_name = args.project_name;
   const updated_since = args.updated_since;
@@ -56266,12 +56481,12 @@ var init_metadata_search = __esm(() => {
         }
       }
     },
-    handler: handler8
+    handler: handler10
   };
 });
 
 // ../../_shared/mcp-tools/search.ts
-async function handler9(supabase, args, ctx) {
+async function handler11(supabase, args, ctx) {
   const query = args.query;
   const project_name = args.project_name;
   const match_count = args.match_count ?? 5;
@@ -56445,12 +56660,12 @@ var init_search = __esm(() => {
         }
       }
     },
-    handler: handler9
+    handler: handler11
   };
 });
 
 // ../../_shared/mcp-tools/set-document-metadata.ts
-async function handler10(supabase, args, ctx) {
+async function handler12(supabase, args, ctx) {
   const document_id = args.document_id;
   const metadata = args.metadata;
   const replace = args.replace ?? false;
@@ -56529,12 +56744,12 @@ var init_set_document_metadata = __esm(() => {
         }
       }
     },
-    handler: handler10
+    handler: handler12
   };
 });
 
 // ../../_shared/mcp-tools/set-document-projects.ts
-async function handler11(supabase, args, ctx) {
+async function handler13(supabase, args, ctx) {
   const document_id = args.document_id?.trim();
   const project_names_raw = args.project_names;
   const author = args.author ?? "mcp-agent";
@@ -56595,7 +56810,7 @@ var init_set_document_projects = __esm(() => {
         }
       }
     },
-    handler: handler11
+    handler: handler13
   };
 });
 
@@ -56614,6 +56829,8 @@ async function assertToolEnabled(supabase, name) {
 var ALL_TOOLS, TOOLS_BY_NAME;
 var init_mcp_tools = __esm(() => {
   init_audit_log();
+  init_delete_document();
+  init_restore_document();
   init_feature_flags();
   init_relations();
   init_get_document();
@@ -56634,6 +56851,8 @@ var init_mcp_tools = __esm(() => {
     ingestTool,
     insertTool,
     editTool,
+    deleteDocumentTool,
+    restoreDocumentTool,
     getDocumentTool,
     listVersionsTool,
     metadataSearchTool,
@@ -62713,25 +62932,25 @@ class Protocol {
     const error3 = McpError.fromError(ErrorCode.ConnectionClosed, "Connection closed");
     this._transport = undefined;
     this.onclose?.();
-    for (const handler12 of responseHandlers.values()) {
-      handler12(error3);
+    for (const handler14 of responseHandlers.values()) {
+      handler14(error3);
     }
   }
   _onerror(error3) {
     this.onerror?.(error3);
   }
   _onnotification(notification) {
-    const handler12 = this._notificationHandlers.get(notification.method) ?? this.fallbackNotificationHandler;
-    if (handler12 === undefined) {
+    const handler14 = this._notificationHandlers.get(notification.method) ?? this.fallbackNotificationHandler;
+    if (handler14 === undefined) {
       return;
     }
-    Promise.resolve().then(() => handler12(notification)).catch((error3) => this._onerror(new Error(`Uncaught error in notification handler: ${error3}`)));
+    Promise.resolve().then(() => handler14(notification)).catch((error3) => this._onerror(new Error(`Uncaught error in notification handler: ${error3}`)));
   }
   _onrequest(request, extra) {
-    const handler12 = this._requestHandlers.get(request.method) ?? this.fallbackRequestHandler;
+    const handler14 = this._requestHandlers.get(request.method) ?? this.fallbackRequestHandler;
     const capturedTransport = this._transport;
     const relatedTaskId = request.params?._meta?.[RELATED_TASK_META_KEY]?.taskId;
-    if (handler12 === undefined) {
+    if (handler14 === undefined) {
       const errorResponse = {
         jsonrpc: "2.0",
         id: request.id,
@@ -62795,7 +63014,7 @@ class Protocol {
       if (taskCreationParams) {
         this.assertTaskHandlerCapability(request.method);
       }
-    }).then(() => handler12(request, fullExtra)).then(async (result) => {
+    }).then(() => handler14(request, fullExtra)).then(async (result) => {
       if (abortController.signal.aborted) {
         return;
       }
@@ -62844,8 +63063,8 @@ class Protocol {
   _onprogress(notification) {
     const { progressToken, ...params } = notification.params;
     const messageId = Number(progressToken);
-    const handler12 = this._progressHandlers.get(messageId);
-    if (!handler12) {
+    const handler14 = this._progressHandlers.get(messageId);
+    if (!handler14) {
       this._onerror(new Error(`Received a progress notification for an unknown token: ${JSON.stringify(notification)}`));
       return;
     }
@@ -62862,7 +63081,7 @@ class Protocol {
         return;
       }
     }
-    handler12(params);
+    handler14(params);
   }
   _onresponse(response) {
     const messageId = Number(response.id);
@@ -62877,8 +63096,8 @@ class Protocol {
       }
       return;
     }
-    const handler12 = this._responseHandlers.get(messageId);
-    if (handler12 === undefined) {
+    const handler14 = this._responseHandlers.get(messageId);
+    if (handler14 === undefined) {
       this._onerror(new Error(`Received a response for an unknown message ID: ${JSON.stringify(response)}`));
       return;
     }
@@ -62899,10 +63118,10 @@ class Protocol {
       this._progressHandlers.delete(messageId);
     }
     if (isJSONRPCResultResponse(response)) {
-      handler12(response);
+      handler14(response);
     } else {
       const error3 = McpError.fromError(response.error.code, response.error.message, response.error.data);
-      handler12(error3);
+      handler14(error3);
     }
   }
   get transport() {
@@ -63065,9 +63284,9 @@ class Protocol {
       const relatedTaskId = relatedTask?.taskId;
       if (relatedTaskId) {
         const responseResolver = (response) => {
-          const handler12 = this._responseHandlers.get(messageId);
-          if (handler12) {
-            handler12(response);
+          const handler14 = this._responseHandlers.get(messageId);
+          if (handler14) {
+            handler14(response);
           } else {
             this._onerror(new Error(`Response handler missing for side-channeled request ${messageId}`));
           }
@@ -63176,12 +63395,12 @@ class Protocol {
     }
     await this._transport.send(jsonrpcNotification, options);
   }
-  setRequestHandler(requestSchema, handler12) {
+  setRequestHandler(requestSchema, handler14) {
     const method = getMethodLiteral(requestSchema);
     this.assertRequestHandlerCapability(method);
     this._requestHandlers.set(method, (request, extra) => {
       const parsed = parseWithCompat(requestSchema, request);
-      return Promise.resolve(handler12(parsed, extra));
+      return Promise.resolve(handler14(parsed, extra));
     });
   }
   removeRequestHandler(method) {
@@ -63192,11 +63411,11 @@ class Protocol {
       throw new Error(`A request handler for ${method} already exists, which would be overridden`);
     }
   }
-  setNotificationHandler(notificationSchema, handler12) {
+  setNotificationHandler(notificationSchema, handler14) {
     const method = getMethodLiteral(notificationSchema);
     this._notificationHandlers.set(method, (notification) => {
       const parsed = parseWithCompat(notificationSchema, notification);
-      return Promise.resolve(handler12(parsed));
+      return Promise.resolve(handler14(parsed));
     });
   }
   removeNotificationHandler(method) {
@@ -70138,7 +70357,7 @@ var init_server2 = __esm(() => {
       }
       this._capabilities = mergeCapabilities(this._capabilities, capabilities);
     }
-    setRequestHandler(requestSchema, handler12) {
+    setRequestHandler(requestSchema, handler14) {
       const shape = getObjectShape(requestSchema);
       const methodSchema = shape?.method;
       if (!methodSchema) {
@@ -70157,7 +70376,7 @@ var init_server2 = __esm(() => {
             throw new McpError(ErrorCode.InvalidParams, `Invalid tools/call request: ${errorMessage}`);
           }
           const { params } = validatedRequest.data;
-          const result = await Promise.resolve(handler12(request, extra));
+          const result = await Promise.resolve(handler14(request, extra));
           if (params.task) {
             const taskValidationResult = safeParse2(CreateTaskResultSchema, result);
             if (!taskValidationResult.success) {
@@ -70175,7 +70394,7 @@ var init_server2 = __esm(() => {
         };
         return super.setRequestHandler(requestSchema, wrappedHandler);
       }
-      return super.setRequestHandler(requestSchema, handler12);
+      return super.setRequestHandler(requestSchema, handler14);
     }
     assertCapabilityForMethod(method) {
       switch (method) {
@@ -72540,14 +72759,38 @@ async function action7(documentId, options) {
       return;
     }
   }
-  await client.rpc("cerefox_delete_document", {
-    p_document_id: documentId,
-    p_author: author,
-    p_author_type: authorType
-  });
+  let result;
+  try {
+    result = await client.rpc("cerefox_delete_document", {
+      p_document_id: documentId,
+      p_author: author,
+      p_author_type: authorType,
+      ...options.reason ? { p_reason: options.reason } : {}
+    });
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    if (isMissingFunctionError(message, "cerefox_delete_document")) {
+      throw systemError(options.reason ? `This server is behind: \`--reason\` needs schema 0.12.0 or newer. ` + `Run \`cerefox server deploy\` and retry, or retry without --reason.` : `The delete did not run: the server has no matching cerefox_delete_document ` + `(mid-deploy window, or an old schema). Run \`cerefox server deploy\` and retry.`);
+    }
+    throw e;
+  }
+  if (result === null) {
+    const { data: check, error: checkError } = await client.raw.from("cerefox_documents").select("deleted_at").eq("id", documentId).maybeSingle();
+    if (checkError) {
+      warn(`Delete submitted, but the follow-up verification read failed (${checkError.message}). ` + `Confirm with: cerefox document get ${documentId}`);
+      return;
+    }
+    if (!check?.deleted_at) {
+      throw systemError(`The delete did not take effect — the server has no matching ` + `cerefox_delete_document (mid-deploy window, or an old schema). ` + `Run \`cerefox server deploy\` and retry.`);
+    }
+  }
+  if (result?.already_deleted) {
+    println(c.dim(`Document ${documentId} ("${doc.title}") was already soft-deleted at ${result.deleted_at} ` + `by the time the delete ran. No change was made and no reason was recorded.`));
+    return;
+  }
   println(c.green(`✓ Soft-deleted "${doc.title}" (id: ${documentId}). Recoverable from the Cerefox web UI trash.`));
   if (options.reason) {
-    println(c.dim(`  Reason (informational only): ${options.reason}`));
+    println(c.dim(`  Reason (recorded in the audit log): ${options.reason}`));
   }
 }
 function registerDeleteDoc(program2) {
@@ -73116,15 +73359,45 @@ async function action11(documentId, options) {
   if (author === "unknown") {
     warn("No --author / CEREFOX_AUTHOR_NAME set — audit log will record this restore as 'unknown'.");
   }
-  await client.rpc("cerefox_restore_document", {
-    p_document_id: documentId,
-    p_author: author,
-    p_author_type: authorType
-  });
+  let result;
+  try {
+    result = await client.rpc("cerefox_restore_document", {
+      p_document_id: documentId,
+      p_author: author,
+      p_author_type: authorType,
+      ...options.reason ? { p_reason: options.reason } : {}
+    });
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    if (isMissingFunctionError(message, "cerefox_restore_document")) {
+      throw systemError(options.reason ? `This server is behind: \`--reason\` needs schema 0.12.0 or newer. ` + `Run \`cerefox server deploy\` and retry, or retry without --reason.` : `The restore did not run: the server has no matching cerefox_restore_document ` + `(mid-deploy window, or an old schema). Run \`cerefox server deploy\` and retry.`);
+    }
+    throw e;
+  }
+  if (result === null) {
+    const { data: check, error: checkError } = await client.raw.from("cerefox_documents").select("deleted_at").eq("id", documentId).maybeSingle();
+    if (checkError) {
+      warn(`Restore submitted, but the follow-up verification read failed (${checkError.message}). ` + `Confirm with: cerefox document get ${documentId}`);
+      return;
+    }
+    if (!check) {
+      throw systemError(`Document ${documentId} no longer exists — it may have been purged concurrently. Nothing was restored.`);
+    }
+    if (check.deleted_at) {
+      throw systemError(`The restore did not take effect — the server has no matching ` + `cerefox_restore_document (mid-deploy window, or an old schema). ` + `Run \`cerefox server deploy\` and retry.`);
+    }
+  }
+  if (result && result.restored === false) {
+    println(c.dim(`Document ${documentId} ("${doc.title}") was already restored by the time this ran. No change was made.`));
+    return;
+  }
   println(c.green(`✓ Restored "${doc.title}" (id: ${documentId}) from the trash.`));
+  if (options.reason) {
+    println(c.dim(`  Reason (recorded in the audit log): ${options.reason}`));
+  }
 }
 function registerDocumentRestore(parent) {
-  parent.command("restore").description("Restore a soft-deleted document from the trash (inverse of `document delete`).").argument("<document-id>", "UUID of the soft-deleted document.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action11);
+  parent.command("restore").description("Restore a soft-deleted document from the trash (inverse of `document delete`).").argument("<document-id>", "UUID of the soft-deleted document.").option("--reason <text>", "Optional reason recorded in the audit log.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action11);
 }
 
 // src/cli/commands/document-set-metadata.ts
@@ -77895,15 +78168,20 @@ class IngestionDbBridge {
     const rows = data ?? [];
     return rows.length > 0 ? rows[0] : null;
   }
+  async findPreferLive(column, value) {
+    const live = await this.supabase.from("cerefox_documents").select("*").eq(column, value).is("deleted_at", null).order("updated_at", { ascending: false }).limit(1);
+    const liveRows = live.data ?? [];
+    if (liveRows.length > 0)
+      return liveRows[0];
+    const any = await this.supabase.from("cerefox_documents").select("*").eq(column, value).order("updated_at", { ascending: false }).limit(1);
+    const anyRows = any.data ?? [];
+    return anyRows.length > 0 ? anyRows[0] : null;
+  }
   async findDocumentByTitle(title) {
-    const { data } = await this.supabase.from("cerefox_documents").select("*").eq("title", title).order("updated_at", { ascending: false }).limit(1);
-    const rows = data ?? [];
-    return rows.length > 0 ? rows[0] : null;
+    return this.findPreferLive("title", title);
   }
   async findDocumentBySourcePath(sourcePath) {
-    const { data } = await this.supabase.from("cerefox_documents").select("*").eq("source_path", sourcePath).order("updated_at", { ascending: false }).limit(1);
-    const rows = data ?? [];
-    return rows.length > 0 ? rows[0] : null;
+    return this.findPreferLive("source_path", sourcePath);
   }
   async listChunksForDocument(documentId) {
     const data = await fetchAllPages((from, to) => this.supabase.from("cerefox_chunks").select("id, document_id, chunk_index, heading_path, heading_level, title, content, char_count").eq("document_id", documentId).is("version_id", null).order("chunk_index").range(from, to));
@@ -77942,8 +78220,8 @@ class IngestionDbBridge {
     if (error2) {
       const msg = error2.message ?? JSON.stringify(error2);
       if (msg.includes("CEREFOX_CONFLICT")) {
-        const current = msg.match(/current hash ([0-9a-f]{64})/)?.[1] ?? null;
-        throw new ConcurrencyConflictError(args.documentId ?? "", current, msg);
+        const { current } = extractConflictHashes(msg);
+        throw new ConcurrencyConflictError(args.documentId ?? "", current === "unknown" ? null : current, msg);
       }
       if (msg.includes("CEREFOX_TOKEN_REQUIRED")) {
         throw new ConcurrencyTokenRequiredError(msg);
@@ -78126,12 +78404,33 @@ class IngestionPipeline {
     }
     if (updateExisting) {
       let existingDoc = null;
+      let matchedBySourcePath = false;
       if (sourcePathOpt) {
         existingDoc = await this.db.findDocumentBySourcePath(sourcePathOpt);
+        matchedBySourcePath = existingDoc !== null;
       }
       if (!existingDoc) {
         existingDoc = await this.db.findDocumentByTitle(title);
       }
+      if (existingDoc?.deleted_at) {
+        if (matchedBySourcePath && lastWriteWins) {
+          const projIds = await this.db.getDocumentProjectIds(existingDoc.id);
+          return {
+            documentId: existingDoc.id,
+            title: existingDoc.title ?? title,
+            chunkCount: existingDoc.chunk_count ?? 0,
+            totalChars: existingDoc.total_chars ?? 0,
+            action: "skipped",
+            reindexed: false,
+            projectIds: projIds,
+            note: `"${existingDoc.title}" is in the trash (soft-deleted ` + `${existingDoc.deleted_at.slice(0, 10)}) — skipped, deletion respected. ` + `To resume syncing this file, restore the document ` + `(\`cerefox document restore ${existingDoc.id}\`) or purge it from the web UI Trash.`,
+            contentHash: existingDoc.content_hash ?? ""
+          };
+        }
+        if (!matchedBySourcePath) {
+          existingDoc = null;
+        }
+      }
       if (existingDoc) {
         let fullSetResolved = null;
         if (listFormProvided) {
@@ -78174,7 +78473,7 @@ class IngestionPipeline {
         action: "skipped",
         reindexed: false,
         projectIds: existingProjectIds,
-        note: "",
+        note: existingByHash.deleted_at ? `Identical content is in the TRASH as "${existingByHash.title}" ` + `(soft-deleted ${existingByHash.deleted_at.slice(0, 10)}). Restore it ` + `(\`cerefox document restore ${existingByHash.id}\` or the web UI Trash page) ` + `instead of re-ingesting, or purge it first to start fresh.` : "",
         contentHash: existingByHash.content_hash ?? hash
       };
     }
@@ -78246,11 +78545,15 @@ class IngestionPipeline {
     if (!existing) {
       throw new Error(`Document ${JSON.stringify(documentId)} not found`);
     }
+    if (existing.deleted_at) {
+      throw new Error(`Document ${documentId} ("${existing.title}") is soft-deleted (in the trash). ` + `A trashed document cannot be updated — restore it first ` + `(\`cerefox document restore ${documentId}\`, the web UI Trash page, or ` + `cerefox_restore_document over MCP), then re-ingest.`);
+    }
     const newHash = contentHash(text);
     const contentUnchanged = newHash === existing.content_hash;
+    const expectedHashTrimmed = expectedContentHash?.trim() || null;
     if (!contentUnchanged) {
-      if (!lastWriteWins && expectedContentHash && expectedContentHash !== existing.content_hash) {
-        throw new ConcurrencyConflictError(documentId, existing.content_hash, `CEREFOX_CONFLICT: document ${documentId} changed since it was read ` + `(expected hash ${expectedContentHash}, current hash ${existing.content_hash}). ` + `Re-read the document, merge your changes, and retry with the new hash.`);
+      if (!lastWriteWins && expectedHashTrimmed && expectedHashTrimmed !== existing.content_hash) {
+        throw new ConcurrencyConflictError(documentId, existing.content_hash, `CEREFOX_CONFLICT: document ${documentId} changed since it was read ` + `(expected hash ${expectedHashTrimmed}, current hash ${existing.content_hash}). ` + `Re-read the document, merge your changes, and retry with the new hash.`);
       }
       const collision = await this.db.getDocumentByHash(newHash);
       if (collision && collision.id !== documentId) {
@@ -78351,7 +78654,7 @@ class IngestionPipeline {
       author,
       authorType,
       sourceLabel: sourceLabel ?? source ?? "manual",
-      expectedContentHash: expectedContentHash ?? (forceRechunk && contentUnchanged ? existing.content_hash : null),
+      expectedContentHash: expectedHashTrimmed ?? (forceRechunk && contentUnchanged ? existing.content_hash : null),
       lastWriteWins
     });
     let finalProjectIds;
@@ -78664,7 +78967,7 @@ async function action20(dir, options) {
       outcomes.push({
         file,
         status: "ok",
-        detail: `${result.action}: ${result.chunkCount} chunks`
+        detail: `${result.action}: ${result.chunkCount} chunks${result.note ? ` (${result.note})` : ""}`
       });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -80371,13 +80674,13 @@ var WSContext = class {
     this.#init.close(code, reason);
   }
 };
-var defineWebSocketHelper = (handler12) => {
+var defineWebSocketHelper = (handler14) => {
   return (...args) => {
     if (typeof args[0] === "function") {
       const [createEvents, options] = args;
       return async function upgradeWebSocket(c2, next) {
         const events = await createEvents(c2);
-        const result = await handler12(c2, events, options);
+        const result = await handler14(c2, events, options);
         if (result) {
           return result;
         }
@@ -80386,7 +80689,7 @@ var defineWebSocketHelper = (handler12) => {
     } else {
       const [c2, events, options] = args;
       return (async () => {
-        const upgraded = await handler12(c2, events, options);
+        const upgraded = await handler14(c2, events, options);
         if (!upgraded) {
           throw new Error("Failed to upgrade WebSocket");
         }
@@ -81979,16 +82282,16 @@ var compose = (middleware, onError, onNotFound) => {
       index = i;
       let res;
       let isError = false;
-      let handler12;
+      let handler14;
       if (middleware[i]) {
-        handler12 = middleware[i][0][0];
+        handler14 = middleware[i][0][0];
         context2.req.routeIndex = i;
       } else {
-        handler12 = i === middleware.length && next || undefined;
+        handler14 = i === middleware.length && next || undefined;
       }
-      if (handler12) {
+      if (handler14) {
         try {
-          res = await handler12(context2, () => dispatch(i + 1));
+          res = await handler14(context2, () => dispatch(i + 1));
         } catch (err) {
           if (err instanceof Error && onError) {
             context2.error = err;
@@ -82672,8 +82975,8 @@ var Hono = class _Hono {
         } else {
           this.#addRoute(method, this.#path, args1);
         }
-        args.forEach((handler12) => {
-          this.#addRoute(method, this.#path, handler12);
+        args.forEach((handler14) => {
+          this.#addRoute(method, this.#path, handler14);
         });
         return this;
       };
@@ -82682,8 +82985,8 @@ var Hono = class _Hono {
       for (const p of [path].flat()) {
         this.#path = p;
         for (const m of [method].flat()) {
-          handlers.map((handler12) => {
-            this.#addRoute(m.toUpperCase(), this.#path, handler12);
+          handlers.map((handler14) => {
+            this.#addRoute(m.toUpperCase(), this.#path, handler14);
           });
         }
       }
@@ -82696,8 +82999,8 @@ var Hono = class _Hono {
         this.#path = "*";
         handlers.unshift(arg1);
       }
-      handlers.forEach((handler12) => {
-        this.#addRoute(METHOD_NAME_ALL, this.#path, handler12);
+      handlers.forEach((handler14) => {
+        this.#addRoute(METHOD_NAME_ALL, this.#path, handler14);
       });
       return this;
     };
@@ -82720,14 +83023,14 @@ var Hono = class _Hono {
   route(path, app) {
     const subApp = this.basePath(path);
     app.routes.map((r) => {
-      let handler12;
+      let handler14;
       if (app.errorHandler === errorHandler) {
-        handler12 = r.handler;
+        handler14 = r.handler;
       } else {
-        handler12 = async (c2, next) => (await compose([], app.errorHandler)(c2, () => r.handler(c2, next))).res;
-        handler12[COMPOSED_HANDLER] = r.handler;
+        handler14 = async (c2, next) => (await compose([], app.errorHandler)(c2, () => r.handler(c2, next))).res;
+        handler14[COMPOSED_HANDLER] = r.handler;
       }
-      subApp.#addRoute(r.method, r.path, handler12, r.basePath);
+      subApp.#addRoute(r.method, r.path, handler14, r.basePath);
     });
     return this;
   }
@@ -82736,12 +83039,12 @@ var Hono = class _Hono {
     subApp._basePath = mergePath(this._basePath, path);
     return subApp;
   }
-  onError = (handler12) => {
-    this.errorHandler = handler12;
+  onError = (handler14) => {
+    this.errorHandler = handler14;
     return this;
   };
-  notFound = (handler12) => {
-    this.#notFoundHandler = handler12;
+  notFound = (handler14) => {
+    this.#notFoundHandler = handler14;
     return this;
   };
   mount(path, applicationHandler, options) {
@@ -82778,26 +83081,26 @@ var Hono = class _Hono {
         return new Request(url, request);
       };
     })();
-    const handler12 = async (c2, next) => {
+    const handler14 = async (c2, next) => {
       const res = await applicationHandler(replaceRequest(c2.req.raw), ...getOptions(c2));
       if (res) {
         return res;
       }
       await next();
     };
-    this.#addRoute(METHOD_NAME_ALL, mergePath(path, "*"), handler12);
+    this.#addRoute(METHOD_NAME_ALL, mergePath(path, "*"), handler14);
     return this;
   }
-  #addRoute(method, path, handler12, baseRoutePath) {
+  #addRoute(method, path, handler14, baseRoutePath) {
     method = method.toUpperCase();
     path = mergePath(this._basePath, path);
     const r = {
       basePath: baseRoutePath !== undefined ? mergePath(this._basePath, baseRoutePath) : this._basePath,
       path,
       method,
-      handler: handler12
+      handler: handler14
     };
-    this.router.add(method, path, [handler12, r]);
+    this.router.add(method, path, [handler14, r]);
     this.routes.push(r);
   }
   #handleError(err, c2) {
@@ -83122,7 +83425,7 @@ var RegExpRouter = class {
     this.#middleware = { [METHOD_NAME_ALL]: /* @__PURE__ */ Object.create(null) };
     this.#routes = { [METHOD_NAME_ALL]: /* @__PURE__ */ Object.create(null) };
   }
-  add(method, path, handler12) {
+  add(method, path, handler14) {
     const middleware = this.#middleware;
     const routes = this.#routes;
     if (!middleware || !routes) {
@@ -83152,13 +83455,13 @@ var RegExpRouter = class {
       Object.keys(middleware).forEach((m) => {
         if (method === METHOD_NAME_ALL || method === m) {
           Object.keys(middleware[m]).forEach((p) => {
-            re.test(p) && middleware[m][p].push([handler12, paramCount]);
+            re.test(p) && middleware[m][p].push([handler14, paramCount]);
           });
         }
       });
       Object.keys(routes).forEach((m) => {
         if (method === METHOD_NAME_ALL || method === m) {
-          Object.keys(routes[m]).forEach((p) => re.test(p) && routes[m][p].push([handler12, paramCount]));
+          Object.keys(routes[m]).forEach((p) => re.test(p) && routes[m][p].push([handler14, paramCount]));
         }
       });
       return;
@@ -83171,7 +83474,7 @@ var RegExpRouter = class {
           routes[m][path2] ||= [
             ...findMiddleware(middleware[m], path2) || findMiddleware(middleware[METHOD_NAME_ALL], path2) || []
           ];
-          routes[m][path2].push([handler12, paramCount - len + i + 1]);
+          routes[m][path2].push([handler14, paramCount - len + i + 1]);
         }
       });
     }
@@ -83220,21 +83523,21 @@ var PreparedRegExpRouter = class {
     matcher[1].forEach((list) => list && list.push(handlerData));
     Object.values(matcher[2]).forEach((list) => list[0].push(handlerData));
   }
-  #addPath(method, path, handler12, indexes, map2) {
+  #addPath(method, path, handler14, indexes, map2) {
     const matcher = this.#matchers[method];
     if (!map2) {
-      matcher[2][path][0].push([handler12, {}]);
+      matcher[2][path][0].push([handler14, {}]);
     } else {
       indexes.forEach((index) => {
         if (typeof index === "number") {
-          matcher[1][index].push([handler12, map2]);
+          matcher[1][index].push([handler14, map2]);
         } else {
-          matcher[2][index || path][0].push([handler12, map2]);
+          matcher[2][index || path][0].push([handler14, map2]);
         }
       });
     }
   }
-  add(method, path, handler12) {
+  add(method, path, handler14) {
     if (!this.#matchers[method]) {
       const all = this.#matchers[METHOD_NAME_ALL];
       const staticMap = {};
@@ -83248,7 +83551,7 @@ var PreparedRegExpRouter = class {
       ];
     }
     if (path === "/*" || path === "*") {
-      const handlerData = [handler12, {}];
+      const handlerData = [handler14, {}];
       if (method === METHOD_NAME_ALL) {
         for (const m in this.#matchers) {
           this.#addWildcard(m, handlerData);
@@ -83265,10 +83568,10 @@ var PreparedRegExpRouter = class {
     for (const [indexes, map2] of data) {
       if (method === METHOD_NAME_ALL) {
         for (const m in this.#matchers) {
-          this.#addPath(m, path, handler12, indexes, map2);
+          this.#addPath(m, path, handler14, indexes, map2);
         }
       } else {
-        this.#addPath(method, path, handler12, indexes, map2);
+        this.#addPath(method, path, handler14, indexes, map2);
       }
     }
   }
@@ -83286,11 +83589,11 @@ var SmartRouter = class {
   constructor(init) {
     this.#routers = init.routers;
   }
-  add(method, path, handler12) {
+  add(method, path, handler14) {
     if (!this.#routes) {
       throw new Error(MESSAGE_MATCHER_IS_ALREADY_BUILT);
     }
-    this.#routes.push([method, path, handler12]);
+    this.#routes.push([method, path, handler14]);
   }
   match(method, path) {
     if (!this.#routes) {
@@ -83347,17 +83650,17 @@ var Node2 = class _Node2 {
   #patterns;
   #order = 0;
   #params = emptyParams;
-  constructor(method, handler12, children) {
+  constructor(method, handler14, children) {
     this.#children = children || /* @__PURE__ */ Object.create(null);
     this.#methods = [];
-    if (method && handler12) {
+    if (method && handler14) {
       const m = /* @__PURE__ */ Object.create(null);
-      m[method] = { handler: handler12, possibleKeys: [], score: 0 };
+      m[method] = { handler: handler14, possibleKeys: [], score: 0 };
       this.#methods = [m];
     }
     this.#patterns = [];
   }
-  insert(method, path, handler12) {
+  insert(method, path, handler14) {
     this.#order = ++this.#order;
     let curNode = this;
     const parts = splitRoutingPath(path);
@@ -83383,7 +83686,7 @@ var Node2 = class _Node2 {
     }
     curNode.#methods.push({
       [method]: {
-        handler: handler12,
+        handler: handler14,
         possibleKeys: possibleKeys.filter((v, i, a) => a.indexOf(v) === i),
         score: this.#order
       }
@@ -83501,7 +83804,7 @@ var Node2 = class _Node2 {
         return a.score - b2.score;
       });
     }
-    return [handlerSets.map(({ handler: handler12, params }) => [handler12, params])];
+    return [handlerSets.map(({ handler: handler14, params }) => [handler14, params])];
   }
 };
 
@@ -83512,15 +83815,15 @@ var TrieRouter = class {
   constructor() {
     this.#node = new Node2;
   }
-  add(method, path, handler12) {
+  add(method, path, handler14) {
     const results = checkOptionalParameter(path);
     if (results) {
       for (let i = 0, len = results.length;i < len; i++) {
-        this.#node.insert(method, results[i], handler12);
+        this.#node.insert(method, results[i], handler14);
       }
       return;
     }
-    this.#node.insert(method, path, handler12);
+    this.#node.insert(method, path, handler14);
   }
   match(method, path) {
     return this.#node.search(method, path);
@@ -84353,6 +84656,33 @@ function registerDiscoveryRoutes(app, ctx) {
       content: row.content ?? null
     })));
   });
+  app.get("/api/v1/dashboard/recent-docs", async (c2) => {
+    const projectId = c2.req.query("project_id") || null;
+    if (projectId && !UUID_RE4.test(projectId)) {
+      return c2.json({ detail: "project_id must be a UUID" }, 400);
+    }
+    const [recentDocs, projects] = await Promise.all([
+      listDocuments(ctx, { projectId, limit: 10 }),
+      listAllProjects(ctx)
+    ]);
+    const docIds = recentDocs.map((d) => String(d.id));
+    const [docProjectsMap, authors] = await Promise.all([
+      getProjectsForDocuments(ctx, docIds, projects),
+      getRecentDocAuthors(ctx, docIds)
+    ]);
+    return c2.json({
+      recent_docs: recentDocs.map((d) => {
+        const id = String(d.id);
+        const pids = (docProjectsMap[id] ?? []).map((p) => String(p.id));
+        const a = authors[id];
+        return {
+          ...dashboardDocFromRow(d, pids),
+          author: a?.author ?? null,
+          author_type: a?.author_type ?? null
+        };
+      })
+    });
+  });
   app.get("/api/v1/dashboard", async (c2) => {
     const [recentDocs, projects, docCount, totals] = await Promise.all([
       listDocuments(ctx, { limit: 10 }),
@@ -84744,6 +85074,13 @@ function registerDocumentWriteRoutes(app, ctx) {
     if (!doc2) {
       return c2.json({ success: false, error: "Document not found" }, 404);
     }
+    if (doc2.deleted_at) {
+      return c2.json({
+        success: false,
+        error: "document is in the trash",
+        message: "This document was moved to the trash while you were editing. " + "Restore it from the Trash page first, then save again."
+      }, 409);
+    }
     const currentHash = doc2.content_hash;
     const proposedHash = content.trim() ? contentHash(content) : null;
     const contentChanged = proposedHash !== null && currentHash !== null && proposedHash !== currentHash;
@@ -84787,10 +85124,23 @@ function registerDocumentWriteRoutes(app, ctx) {
             message: err.message
           }, 400);
         }
-        return c2.json({
-          success: false,
-          error: err instanceof Error ? err.message : String(err)
-        }, 500);
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("CEREFOX_UNRESOLVED_LINKS")) {
+          const ids = msg.match(/do not exist: ([^.]+)\./)?.[1] ?? "";
+          return c2.json({
+            success: false,
+            error: "unresolved document links",
+            message: `This content links document id(s) that don't exist${ids ? `: ${ids}` : ""}. ` + `Fix or remove the broken link(s), or wrap example ids in backticks.`
+          }, 422);
+        }
+        if (msg.includes("soft-deleted")) {
+          return c2.json({
+            success: false,
+            error: "document is in the trash",
+            message: "This document was moved to the trash while you were editing. " + "Restore it from the Trash page first, then save again."
+          }, 409);
+        }
+        return c2.json({ success: false, error: msg }, 500);
       }
     }
     const updates = {};
@@ -84823,25 +85173,35 @@ function registerDocumentWriteRoutes(app, ctx) {
   });
   app.delete("/api/v1/documents/:document_id", async (c2) => {
     const documentId = c2.req.param("document_id");
-    const { error: error3 } = await ctx.supabase.rpc("cerefox_delete_document", {
+    const { data, error: error3 } = await ctx.supabase.rpc("cerefox_delete_document", {
       p_document_id: documentId,
       p_author: "web-ui",
       p_author_type: "user"
     });
-    if (error3)
+    if (error3) {
+      if (isDocumentNotFoundError(error3)) {
+        return c2.json({ detail: `Document ${documentId} not found` }, 404);
+      }
       return c2.json({ detail: error3.message }, 500);
-    return c2.json({ success: true });
+    }
+    const row = data;
+    return c2.json({ success: true, ...row ? { already_deleted: row.already_deleted ?? false } : {} });
   });
   app.post("/api/v1/documents/:document_id/restore", async (c2) => {
     const documentId = c2.req.param("document_id");
-    const { error: error3 } = await ctx.supabase.rpc("cerefox_restore_document", {
+    const { data, error: error3 } = await ctx.supabase.rpc("cerefox_restore_document", {
       p_document_id: documentId,
       p_author: "web-ui",
       p_author_type: "user"
     });
-    if (error3)
+    if (error3) {
+      if (isDocumentNotFoundError(error3)) {
+        return c2.json({ detail: `Document ${documentId} not found` }, 404);
+      }
       return c2.json({ detail: error3.message }, 500);
-    return c2.json({ success: true });
+    }
+    const row = data;
+    return c2.json({ success: true, ...row ? { restored: row.restored ?? false } : {} });
   });
   app.delete("/api/v1/documents/:document_id/purge", async (c2) => {
     const documentId = c2.req.param("document_id");
@@ -84867,6 +85227,9 @@ function registerDocumentWriteRoutes(app, ctx) {
       return c2.json({ detail: `Invalid status: ${JSON.stringify(status)}` }, 400);
     }
     const old = await getCurrentDoc(ctx, documentId);
+    if (old?.deleted_at) {
+      return c2.json({ detail: "This document is in the trash — restore it before changing its review status." }, 409);
+    }
     const oldStatus = old?.review_status ?? "unknown";
     const { error: error3 } = await ctx.supabase.from("cerefox_documents").update({ review_status: status, updated_at: new Date().toISOString() }).eq("id", documentId);
     if (error3)
@@ -85013,7 +85376,8 @@ function registerIngestRoutes(app, ctx) {
         document_id: result.documentId,
         title: result.title,
         skipped,
-        updated: result.reindexed
+        updated: result.reindexed,
+        ...result.note ? { note: result.note } : {}
       }, 200);
     } catch (err) {
       return c2.json(notReady(err instanceof Error ? err.message : String(err)), 200);