@cerefox/memory 1.7.1 → 1.9.0

package/dist/bin/cerefox.js

@@ -7438,7 +7438,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "1.7.1";
+var PKG_VERSION = "1.9.0";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -23427,6 +23427,44 @@ var init_client = __esm(() => {
   init_cli_core();
 });
 
+// ../../_shared/mcp-tools/audit-ops.ts
+function isStoreLevelAuditOp(operation) {
+  return STORE_LEVEL_AUDIT_OPS.includes(operation ?? "");
+}
+function auditDocLabel(docTitle, documentId, operation) {
+  if (docTitle)
+    return docTitle;
+  if (documentId)
+    return documentId.slice(0, 8) + "…";
+  return isStoreLevelAuditOp(operation) ? "(store)" : "(deleted)";
+}
+var STORE_LEVEL_AUDIT_OPS, AUDIT_OPERATIONS;
+var init_audit_ops = __esm(() => {
+  STORE_LEVEL_AUDIT_OPS = [
+    "config-change",
+    "project-create",
+    "project-edit",
+    "project-delete"
+  ];
+  AUDIT_OPERATIONS = [
+    "create",
+    "update-content",
+    "update-metadata",
+    "insert",
+    "replace-section",
+    "delete-section",
+    "rename-section",
+    "delete",
+    "restore",
+    "status-change",
+    "archive",
+    "unarchive",
+    "relation-set",
+    "relation-delete",
+    ...STORE_LEVEL_AUDIT_OPS
+  ];
+});
+
 // ../../_shared/mcp-tools/_utils.ts
 function getMaxResponseBytes() {
   const raw = globalThis.process?.env?.CEREFOX_MAX_RESPONSE_BYTES;
@@ -23486,6 +23524,21 @@ function extractConflictHashes(message) {
 function isDocumentNotFoundError(error) {
   return error.code === "22023" && /not found/i.test(error.message ?? "");
 }
+function isAuditCheckError(message) {
+  return /cerefox_audit_log_operation_check/.test(message);
+}
+function isDuplicateKeyError(message) {
+  return /duplicate key|unique constraint|23505/i.test(message);
+}
+function storeWriteRemediation(message, fnName) {
+  if (isMissingFunctionError(message, fnName)) {
+    return "The deployed server predates schema 0.14.0 — or PostgREST's schema cache " + "is stale right after a deploy. If you just deployed, retry in a few " + "seconds; otherwise run `cerefox server deploy`.";
+  }
+  if (isAuditCheckError(message)) {
+    return "The server's audit-log constraint predates migration 0028 (partial " + "deploy). Run `cerefox server deploy` to apply pending migrations, then retry.";
+  }
+  return null;
+}
 function isMissingFunctionError(message, fnName) {
   return message.includes("Could not find the function") && message.includes(fnName) || message.includes("does not exist") && message.includes(fnName);
 }
@@ -23502,6 +23555,9 @@ function logUsage(supabase, params) {
   })).catch(() => {});
 }
 var MAX_RESPONSE_BYTES = 200000, DEFAULT_MIN_SEARCH_SCORE = 0.5, DEFAULT_MIN_SEARCH_SCORE_LOCAL = 0.6, DEFAULT_SEARCH_ALPHA = 0.7;
+var init__utils = __esm(() => {
+  init_audit_ops();
+});
 
 // ../../_shared/server-assets/index.ts
 import { existsSync as existsSync5 } from "node:fs";
@@ -25543,15 +25599,27 @@ var init_src = __esm(() => {
 });
 
 // ../../_shared/mcp-tools/_projects.ts
-async function ensureDocumentInProject(supabase, documentId, projectName) {
-  let projectId = null;
-  const { data: proj } = await supabase.from("cerefox_projects").select("id").ilike("name", projectName).limit(1);
-  if (proj?.length) {
-    projectId = proj[0].id;
-  } else {
-    const { data: newProj } = await supabase.from("cerefox_projects").insert({ name: projectName }).select("id");
-    projectId = newProj?.[0]?.id ?? null;
+async function resolveOrCreateProject(supabase, projectName, audit) {
+  const { data, error } = await supabase.rpc("cerefox_create_project", {
+    p_name: projectName,
+    p_description: "",
+    p_author: audit?.author ?? "unknown",
+    p_author_type: audit?.authorType ?? "agent",
+    p_if_exists: "return"
+  });
+  if (error) {
+    const remediation = storeWriteRemediation(error.message ?? "", "cerefox_create_project");
+    if (remediation)
+      throw new Error(`Project resolution failed for '${projectName}': ${remediation}`);
+    console.warn("resolveOrCreateProject: RPC failed", error);
+    return null;
   }
+  const row = data?.[0];
+  return row?.project_id ? { projectId: row.project_id, projectName: row.project_name ?? projectName } : null;
+}
+async function ensureDocumentInProject(supabase, documentId, projectName, audit) {
+  const resolved = await resolveOrCreateProject(supabase, projectName, audit);
+  const projectId = resolved?.projectId ?? null;
   if (!projectId)
     return null;
   const { data: existing } = await supabase.from("cerefox_document_projects").select("document_id").eq("document_id", documentId).eq("project_id", projectId).limit(1);
@@ -25563,20 +25631,14 @@ async function ensureDocumentInProject(supabase, documentId, projectName) {
   }
   return projectId;
 }
-async function setDocumentProjectsByName(supabase, documentId, projectNames) {
-  const projectIds = [];
-  for (const name of projectNames) {
-    if (!name)
-      continue;
-    const { data: proj } = await supabase.from("cerefox_projects").select("id").ilike("name", name).limit(1);
-    if (proj?.length) {
-      projectIds.push(proj[0].id);
-    } else {
-      const { data: newProj } = await supabase.from("cerefox_projects").insert({ name }).select("id");
-      if (newProj?.[0]?.id)
-        projectIds.push(newProj[0].id);
-    }
+async function setDocumentProjectsByName(supabase, documentId, projectNames, audit) {
+  const wanted = projectNames.filter((n) => !!n);
+  const resolved = await Promise.all(wanted.map((n) => resolveOrCreateProject(supabase, n, audit)));
+  const failed = wanted.filter((_, i) => !resolved[i]);
+  if (failed.length > 0) {
+    throw new Error(`Could not resolve project(s): ${failed.join(", ")} — memberships left unchanged.`);
   }
+  const projectIds = resolved.map((r) => r.projectId);
   await supabase.from("cerefox_document_projects").delete().eq("document_id", documentId);
   if (projectIds.length > 0) {
     const rows = projectIds.map((pid) => ({ document_id: documentId, project_id: pid }));
@@ -25602,17 +25664,12 @@ async function replaceDocumentProjects(supabase, opts) {
   if (!doc?.length) {
     throw new Error(`Document not found (or soft-deleted): ${documentId}`);
   }
-  const projectIds = [];
-  for (const name of cleanNames) {
-    const { data: proj } = await supabase.from("cerefox_projects").select("id").ilike("name", name).limit(1);
-    if (proj?.length) {
-      projectIds.push(proj[0].id);
-    } else {
-      const { data: newProj } = await supabase.from("cerefox_projects").insert({ name }).select("id");
-      if (newProj?.[0]?.id)
-        projectIds.push(newProj[0].id);
-    }
+  const resolved = await Promise.all(cleanNames.map((name) => resolveOrCreateProject(supabase, name, { author, authorType })));
+  const failed = cleanNames.filter((_, i) => !resolved[i]);
+  if (failed.length > 0) {
+    throw new Error(`Could not resolve project(s): ${failed.join(", ")} — memberships left unchanged.`);
   }
+  const projectIds = resolved.map((r) => r.projectId);
   await supabase.from("cerefox_document_projects").delete().eq("document_id", documentId);
   if (projectIds.length > 0) {
     const rows = projectIds.map((pid) => ({ document_id: documentId, project_id: pid }));
@@ -25647,7 +25704,9 @@ async function lookupProjectId(supabase, projectName) {
     return null;
   return data[0].id;
 }
-var init__projects = () => {};
+var init__projects = __esm(() => {
+  init__utils();
+});
 
 // src/cli/util/bundled-docs.ts
 import { existsSync as existsSync8, readdirSync as readdirSync3, readFileSync as readFileSync6, statSync } from "node:fs";
@@ -25743,7 +25802,7 @@ var init_bundled_docs = __esm(() => {
 });
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "1.7.1", CEREFOX_VERSION = "1.7.1", EF_LAST_CHANGED = "1.7.0";
+var EF_VERSION = "1.9.0", CEREFOX_VERSION = "1.9.0", EF_LAST_CHANGED = "1.9.0";
 var init_ef_meta = () => {};
 
 // ../../_shared/compatibility/index.ts
@@ -25874,7 +25933,7 @@ async function checkServerCompatibility(opts) {
 var COMPATIBILITY;
 var init_compatibility = __esm(() => {
   COMPATIBILITY = {
-    minSchema: "0.10.5",
+    minSchema: "0.14.0",
     minEdgeFunctions: "0.6.0"
   };
 });
@@ -54767,7 +54826,7 @@ async function handler(supabase, args, ctx) {
   if (!entries.length)
     return "No audit log entries found.";
   const lines = entries.map((e) => {
-    const docLabel = e.doc_title ?? (e.document_id ? e.document_id.slice(0, 8) + "..." : "(deleted)");
+    const docLabel = auditDocLabel(e.doc_title, e.document_id, e.operation);
     const sizeInfo = e.size_before != null && e.size_after != null ? ` | ${e.size_before} -> ${e.size_after} chars` : e.size_after != null ? ` | ${e.size_after} chars` : "";
     return `${utcStamp2(e.created_at)} | ${e.operation} | ${e.author} (${e.author_type}) | ${docLabel}${sizeInfo} | ${e.description}`;
   });
@@ -54778,6 +54837,7 @@ ${lines.join(`
 }
 var auditLogTool;
 var init_audit_log = __esm(() => {
+  init__utils();
   auditLogTool = {
     name: "cerefox_get_audit_log",
     description: "Retrieve audit log entries showing who changed what and when. Supports filtering by document, author, operation type, and time range. Returns entries with document titles, author attribution, size changes, and descriptions.",
@@ -54795,7 +54855,7 @@ var init_audit_log = __esm(() => {
         author: { type: "string", description: "Filter by author name (optional)" },
         operation: {
           type: "string",
-          description: "Filter by operation type: create, update-content, update-metadata, delete, status-change, archive, unarchive (optional)"
+          description: `Filter by operation type: ${AUDIT_OPERATIONS.join(", ")} (optional)`
         },
         since: {
           type: "string",
@@ -54881,6 +54941,7 @@ async function handler2(supabase, args, ctx) {
 }
 var deleteDocumentTool;
 var init_delete_document = __esm(() => {
+  init__utils();
   init_types3();
   deleteDocumentTool = {
     name: "cerefox_delete_document",
@@ -54961,6 +55022,7 @@ async function handler3(supabase, args, ctx) {
 }
 var restoreDocumentTool;
 var init_restore_document = __esm(() => {
+  init__utils();
   init_types3();
   restoreDocumentTool = {
     name: "cerefox_restore_document",
@@ -55150,6 +55212,7 @@ ${lines.join(`
 }
 var KNOWN_TYPES = "related_to, references, supersedes, contradicts, duplicates, part_of, follows, reply_to", setRelationTool, deleteRelationTool, getRelationsTool, getNeighborsTool;
 var init_relations = __esm(() => {
+  init__utils();
   init_types3();
   setRelationTool = {
     name: "cerefox_set_relation",
@@ -55325,6 +55388,7 @@ ${hashLine}${row.full_content ?? ""}`;
 var getDocumentTool;
 var init_get_document = __esm(() => {
   init_partial_edits();
+  init__utils();
   init_types3();
   getDocumentTool = {
     name: "cerefox_get_document",
@@ -55590,6 +55654,7 @@ var AUDIT_OP, insertTool, editTool;
 var init_partial_edits2 = __esm(() => {
   init_partial_edits();
   init__chunker();
+  init__utils();
   init_types3();
   AUDIT_OP = {
     insert: "insert",
@@ -55718,7 +55783,7 @@ 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 **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 HELP_FULL = '# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **15 core MCP tools** (14 with CLI equivalents — `cerefox_get_help` is MCP-only), plus 4 dormant relation tools that appear only when `relations_enabled` is on. 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_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.",
@@ -55903,6 +55968,7 @@ var getHelpTool;
 var init_get_help = __esm(() => {
   init_ef_meta();
   init_partial_edits2();
+  init__utils();
   init_get_help_content();
   getHelpTool = {
     name: "cerefox_get_help",
@@ -56038,9 +56104,9 @@ async function handler6(supabase, args, ctx) {
       result_count: chunks2.length
     });
     if (project_names !== null) {
-      await setDocumentProjectsByName(supabase, existingDoc.id, project_names);
+      await setDocumentProjectsByName(supabase, existingDoc.id, project_names, { author, authorType: author_type });
     } else if (project_name) {
-      await ensureDocumentInProject(supabase, existingDoc.id, project_name);
+      await ensureDocumentInProject(supabase, existingDoc.id, project_name, { author, authorType: author_type });
     }
     const note = update_if_exists ? "" : " Note: update_if_exists flag was overridden by document_id.";
     return `Document updated: "${title}" (id: ${existingDoc.id}), ${chunks2.length} chunk(s), ${totalChars2} chars. New content_hash: ${contentHash2}.${note}`;
@@ -56102,9 +56168,9 @@ async function handler6(supabase, args, ctx) {
         result_count: chunks2.length
       });
       if (project_names !== null) {
-        await setDocumentProjectsByName(supabase, existingDoc.id, project_names);
+        await setDocumentProjectsByName(supabase, existingDoc.id, project_names, { author, authorType: author_type });
       } else if (project_name) {
-        await ensureDocumentInProject(supabase, existingDoc.id, project_name);
+        await ensureDocumentInProject(supabase, existingDoc.id, project_name, { author, authorType: author_type });
       }
       return `Document updated: "${existingDoc.title}" (id: ${existingDoc.id}), ${chunks2.length} chunk(s), ${totalChars2} chars. New content_hash: ${contentHash2}.`;
     }
@@ -56149,9 +56215,9 @@ async function handler6(supabase, args, ctx) {
   }
   const documentId = ingestResult[0].document_id;
   if (project_names !== null && project_names.length > 0) {
-    await setDocumentProjectsByName(supabase, documentId, project_names);
+    await setDocumentProjectsByName(supabase, documentId, project_names, { author, authorType: author_type });
   } else if (project_name) {
-    await ensureDocumentInProject(supabase, documentId, project_name);
+    await ensureDocumentInProject(supabase, documentId, project_name, { author, authorType: author_type });
   }
   logUsage(supabase, {
     operation: "ingest",
@@ -56167,6 +56233,7 @@ var ingestTool;
 var init_ingest = __esm(() => {
   init__chunker();
   init__projects();
+  init__utils();
   init_types3();
   ingestTool = {
     name: "cerefox_ingest",
@@ -56239,6 +56306,7 @@ async function handler7(supabase, args, ctx) {
 }
 var listMetadataKeysTool;
 var init_list_metadata_keys = __esm(() => {
+  init__utils();
   listMetadataKeysTool = {
     name: "cerefox_list_metadata_keys",
     description: "List all metadata keys currently in use across documents in the Cerefox knowledge base. Returns each key with its document count and up to 5 example values.",
@@ -56286,6 +56354,7 @@ ${lines.join(`
 }
 var listProjectsTool;
 var init_list_projects = __esm(() => {
+  init__utils();
   listProjectsTool = {
     name: "cerefox_list_projects",
     description: "List all projects with their names and IDs. Use this to discover available projects before filtering by project_name in other tools.",
@@ -56340,6 +56409,7 @@ ${lines.join(`
 }
 var listVersionsTool;
 var init_list_versions = __esm(() => {
+  init__utils();
   init_types3();
   listVersionsTool = {
     name: "cerefox_list_versions",
@@ -56438,6 +56508,7 @@ ${row.content}`;
 }
 var metadataSearchTool;
 var init_metadata_search = __esm(() => {
+  init__utils();
   init__projects();
   init_types3();
   metadataSearchTool = {
@@ -56604,6 +56675,7 @@ ${row.full_content ?? ""}`;
 }
 var searchTool;
 var init_search = __esm(() => {
+  init__utils();
   init__projects();
   init_types3();
   searchTool = {
@@ -56710,6 +56782,7 @@ async function handler12(supabase, args, ctx) {
 }
 var setDocumentMetadataTool;
 var init_set_document_metadata = __esm(() => {
+  init__utils();
   init_types3();
   setDocumentMetadataTool = {
     name: "cerefox_set_document_metadata",
@@ -71370,19 +71443,32 @@ function registerConfigList(parent) {
 
 // src/cli/commands/config-set.ts
 init_cli_core();
+init__utils();
 init_client();
-async function action5(key, value) {
+async function action5(key, value, options) {
   const client = getClient();
-  try {
-    await client.rpc("cerefox_set_config", { p_key: key, p_value: value });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
+  const author = resolveAuthor(options.author);
+  const authorType = resolveAuthorType(options.authorType);
+  if (author === "unknown") {
+    warn("No --author / CEREFOX_AUTHOR_NAME set — audit log will record this change as 'unknown'.");
+  }
+  const { error } = await client.raw.rpc("cerefox_set_config", {
+    p_key: key,
+    p_value: value,
+    p_author: author,
+    p_author_type: authorType
+  });
+  if (error) {
+    const msg = error.message ?? String(error);
+    const remediation = storeWriteRemediation(msg, "cerefox_set_config");
+    if (remediation)
+      throw systemError(`Could not set ${key}.`, remediation);
     throw systemError(`Could not set ${key}: ${msg}`, "The RPC validates against an allowlist of known keys; check the key spelling.");
   }
   println(c.green("✓ ") + `${key} = ${value}`);
 }
 function registerConfigSet(program2) {
-  program2.command("config-set").description("Write a runtime config value into the cerefox_config table.").argument("<key>", "Config key.").argument("<value>", "Value to write.").action(action5);
+  program2.command("config-set").description("Write a runtime config value into the cerefox_config table.").argument("<key>", "Config key.").argument("<value>", "Value to write.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "user | agent (default: user).").action(action5);
 }
 
 // src/cli/commands/configure-agent.ts
@@ -72730,6 +72816,7 @@ function registerConfigureAgent(program2) {
 
 // src/cli/commands/delete-doc.ts
 init_cli_core();
+init__utils();
 init_client();
 async function action7(documentId, options) {
   const client = getClient();
@@ -72799,6 +72886,7 @@ function registerDeleteDoc(program2) {
 
 // src/cli/commands/document-dead-links.ts
 init_cli_core();
+init__utils();
 init_client();
 var SERVER_BEHIND = "The sweep did not run: this server has no cerefox_find_dead_links (needs schema 0.12.2). " + "Run `cerefox server deploy`, then retry.";
 async function action8(options) {
@@ -72840,6 +72928,8 @@ init_client();
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 async function action9(target, options) {
   const client = getClient();
+  const author = resolveAuthor(options.author);
+  const authorType = resolveAuthorType(options.authorType);
   const isUuid = UUID_RE.test(target);
   const lookup = isUuid ? client.raw.from("cerefox_projects").select("id, name, description").eq("id", target).maybeSingle() : client.raw.from("cerefox_projects").select("id, name, description").eq("name", target).maybeSingle();
   const { data: project, error } = await lookup;
@@ -72867,14 +72957,22 @@ async function action9(target, options) {
       return;
     }
   }
-  const { error: delErr } = await client.raw.from("cerefox_projects").delete().eq("id", project.id);
+  const { data: delData, error: delErr } = await client.raw.rpc("cerefox_delete_project", {
+    p_project_id: project.id,
+    p_author: author,
+    p_author_type: authorType
+  });
   if (delErr) {
     throw systemError(`Delete failed: ${delErr.message}`);
   }
+  const delRow = delData?.[0];
+  if (!delRow?.deleted) {
+    throw notFound(`Project "${project.name}" was already deleted (concurrently).`);
+  }
   println(c.green(`✓ Deleted project "${project.name}" (id: ${project.id}).`));
 }
 function registerDeleteProject(program2) {
-  program2.command("delete-project").description("Delete an empty project (use --force to remove a non-empty one).").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--yes", "Skip the confirmation prompt.").option("--force", "Allow deletion when documents are still linked to the project.").action(action9);
+  program2.command("delete-project").description("Delete an empty project (use --force to remove a non-empty one).").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--yes", "Skip the confirmation prompt.").option("--force", "Allow deletion when documents are still linked to the project.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "user | agent (default: user).").action(action9);
 }
 
 // src/cli/commands/deploy-server.ts
@@ -72918,7 +73016,7 @@ function buildDeploySteps(assets, opts = {}) {
   }
   steps.push({ label: "Enable extensions (uuid-ossp, vector/pgvector)", sql: EXTENSIONS_SQL }, { label: "Apply schema (tables, indexes, triggers)", sql: schemaSql }, { label: "Apply RPCs (search functions)", sql: rpcsSql });
   const migrationFiles = listMigrationFiles(assets.migrationsDir);
-  if (migrationFiles.length > 0) {
+  if ((opts.stampMigrations ?? true) && migrationFiles.length > 0) {
     const values2 = migrationFiles.map((n) => `('${n.replace(/'/g, "''")}')`).join(", ");
     steps.push({
       label: "Stamp migration files as already applied",
@@ -72929,14 +73027,20 @@ function buildDeploySteps(assets, opts = {}) {
 }
 async function runDbDeploy(opts) {
   const log = opts.log ?? (() => {});
-  const steps = buildDeploySteps(opts.assets, { reset: opts.reset });
   if (opts.dryRun) {
-    for (const step of steps) {
+    const steps2 = buildDeploySteps(opts.assets, { reset: opts.reset });
+    for (const step of steps2) {
       log(`▶  ${step.label}… (dry-run, not executed)`);
     }
-    return { ok: true, stepsRun: steps.length };
+    return { ok: true, stepsRun: steps2.length };
   }
   const sql = src_default(opts.dbUrl, { prepare: false, onnotice: () => {} });
+  const fresh = opts.reset ? true : !await detectExistingSchema(opts.dbUrl, sql);
+  const steps = buildDeploySteps(opts.assets, { reset: opts.reset, stampMigrations: fresh });
+  if (!fresh) {
+    log("⚠  Existing schema detected: pending migrations are NOT stamped by a re-apply.");
+    log("   Run `bun scripts/db_migrate.ts` (or `cerefox server deploy`) to apply them.");
+  }
   let stepsRun = 0;
   try {
     for (const step of steps) {
@@ -72949,11 +73053,17 @@ async function runDbDeploy(opts) {
         return { ok: false, stepsRun, failedStep: step.label, error: message };
       }
     }
+    await reloadPostgrestSchemaCache(sql);
     return { ok: true, stepsRun };
   } finally {
     await sql.end({ timeout: 5 }).catch(() => {});
   }
 }
+async function reloadPostgrestSchemaCache(sql) {
+  try {
+    await sql.unsafe("NOTIFY pgrst, 'reload schema'");
+  } catch {}
+}
 var BOOTSTRAP_MIGRATIONS_SQL = `
 CREATE TABLE IF NOT EXISTS cerefox_migrations (
     id         SERIAL      PRIMARY KEY,
@@ -72961,13 +73071,14 @@ CREATE TABLE IF NOT EXISTS cerefox_migrations (
     applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 `;
-async function detectExistingSchema(dbUrl) {
-  const sql = src_default(dbUrl, { prepare: false, onnotice: () => {} });
+async function detectExistingSchema(dbUrl, existing) {
+  const sql = existing ?? src_default(dbUrl, { prepare: false, onnotice: () => {} });
   try {
     const rows = await sql`SELECT to_regclass('public.cerefox_documents') AS t`;
     return rows[0]?.t != null;
   } finally {
-    await sql.end({ timeout: 5 }).catch(() => {});
+    if (!existing)
+      await sql.end({ timeout: 5 }).catch(() => {});
   }
 }
 async function migrationStatus(opts) {
@@ -72988,7 +73099,13 @@ async function migrationStatus(opts) {
 }
 async function runDbMigrate(opts) {
   const log = opts.log ?? (() => {});
-  const sql = src_default(opts.dbUrl, { prepare: false, onnotice: () => {} });
+  const sql = src_default(opts.dbUrl, {
+    prepare: false,
+    onnotice: (n) => {
+      if (n.message)
+        log(`   ↳ ${n.message}`);
+    }
+  });
   try {
     await sql.unsafe(BOOTSTRAP_MIGRATIONS_SQL);
     const allFiles = listMigrationFiles(opts.assets.migrationsDir);
@@ -73022,6 +73139,8 @@ async function runDbMigrate(opts) {
         };
       }
     }
+    if (applied.length > 0)
+      await reloadPostgrestSchemaCache(sql);
     return { ok: true, applied, pending };
   } finally {
     await sql.end({ timeout: 5 }).catch(() => {});
@@ -73036,6 +73155,7 @@ async function applyRpcs(opts) {
   const sql = src_default(opts.dbUrl, { prepare: false, onnotice: () => {} });
   try {
     await sql.unsafe(rpcsSql);
+    await reloadPostgrestSchemaCache(sql);
     return { ok: true };
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : String(err) };
@@ -73399,6 +73519,7 @@ function registerDocumentEdit(parent) {
 
 // src/cli/commands/document-restore.ts
 init_cli_core();
+init__utils();
 init_client();
 async function action12(documentId, options) {
   const client = getClient();
@@ -73618,20 +73739,38 @@ function registerGuides(parent) {
 
 // src/cli/commands/project-create.ts
 init_cli_core();
+init__utils();
 init_client();
 async function action15(name, options) {
   const trimmed = name.trim();
   if (!trimmed)
     throw userError("Project name is required.");
   const client = getClient();
-  const { data, error } = await client.raw.from("cerefox_projects").insert({ name: trimmed, description: (options.description ?? "").trim() }).select("id, name, description").maybeSingle();
-  if (error || !data) {
-    throw systemError(`Create failed: ${error?.message ?? "no row returned"}`);
+  const author = resolveAuthor(options.author);
+  const authorType = resolveAuthorType(options.authorType);
+  const { data, error } = await client.raw.rpc("cerefox_create_project", {
+    p_name: trimmed,
+    p_description: (options.description ?? "").trim(),
+    p_author: author,
+    p_author_type: authorType
+  });
+  if (error) {
+    const msg = error.message ?? "";
+    if (isDuplicateKeyError(msg)) {
+      throw userError(`Project "${trimmed}" already exists.`);
+    }
+    const remediation = storeWriteRemediation(msg, "cerefox_create_project");
+    if (remediation)
+      throw systemError("Create failed.", remediation);
+    throw systemError(`Create failed: ${msg}`);
   }
-  println(c.green(`✓ Created project "${data.name}" (id: ${data.id}).`));
+  const row = data?.[0];
+  if (!row)
+    throw systemError("Create failed: no row returned");
+  println(c.green(`✓ Created project "${row.project_name}" (id: ${row.project_id}).`));
 }
 function registerProjectCreate(parent) {
-  parent.command("create").description("Create a new (empty) project.").argument("<name>", "Project name (must be unique).").option("--description <text>", "Optional project description.").action(action15);
+  parent.command("create").description("Create a new (empty) project.").argument("<name>", "Project name (must be unique).").option("--description <text>", "Optional project description.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "user | agent (default: user).").action(action15);
 }
 
 // src/cli/commands/project-edit.ts
@@ -73652,20 +73791,30 @@ async function action16(target, options) {
     throw userError("Nothing to update — pass --name and/or --description.");
   }
   const client = getClient();
+  const author = resolveAuthor(options.author);
+  const authorType = resolveAuthorType(options.authorType);
   const isUuid = UUID_RE2.test(target);
   const { data: project, error: lookupErr } = await client.raw.from("cerefox_projects").select("id, name").eq(isUuid ? "id" : "name", target).maybeSingle();
   if (lookupErr)
     throw systemError(`Lookup failed: ${lookupErr.message}`);
   if (!project)
     throw notFound(`Project "${target}" not found.`);
-  const { data, error } = await client.raw.from("cerefox_projects").update(update).eq("id", project.id).select("id, name, description").maybeSingle();
-  if (error || !data) {
-    throw systemError(`Update failed: ${error?.message ?? "no row returned"}`);
-  }
-  println(c.green(`✓ Updated project "${data.name}" (id: ${data.id}).`));
+  const { data, error } = await client.raw.rpc("cerefox_update_project", {
+    p_project_id: project.id,
+    p_name: update.name ?? null,
+    p_description: update.description ?? null,
+    p_author: author,
+    p_author_type: authorType
+  });
+  if (error)
+    throw systemError(`Update failed: ${error.message}`);
+  const row = data?.[0];
+  if (!row)
+    throw systemError("Update failed: no row returned");
+  println(c.green(`✓ Updated project "${row.project_name}" (id: ${row.project_id}).`));
 }
 function registerProjectEdit(parent) {
-  parent.command("edit").description("Rename a project and/or change its description.").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--name <new-name>", "New project name.").option("--description <text>", "New project description.").action(action16);
+  parent.command("edit").description("Rename a project and/or change its description.").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--name <new-name>", "New project name.").option("--description <text>", "New project description.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "user | agent (default: user).").action(action16);
 }
 
 // src/cli/commands/version-archive.ts
@@ -77860,6 +78009,10 @@ async function action17(options) {
     }
     if (remediation) {
       println(cErr.yellow("→ " + remediation));
+      const configDir = (process.env.CEREFOX_CONFIG_DIR ?? "").trim();
+      if (configDir) {
+        println(cErr.dim(`  (this doctor ran against CEREFOX_CONFIG_DIR=${configDir} — ` + `prefix the command above the same way, or use your environment alias, ` + `or a bare \`cerefox\` will act on your DEFAULT environment instead)`));
+      }
       println("");
     }
   }
@@ -77886,6 +78039,7 @@ function registerDoctor(program2) {
 }
 
 // src/cli/commands/get-audit-log.ts
+init__utils();
 init_cli_core();
 init_client();
 async function action18(options) {
@@ -77920,13 +78074,13 @@ async function action18(options) {
   printTable(data.map((row) => ({
     when: `${(row.created_at ?? "").slice(0, 19).replace("T", " ")}Z`,
     operation: row.operation,
-    doc: (row.doc_title ?? (row.document_id ?? "?").slice(0, 8) + "…").slice(0, 40),
+    doc: auditDocLabel(row.doc_title, row.document_id, row.operation).slice(0, 40),
     author: (row.author ?? "") + (row.author_type ? `(${row.author_type})` : ""),
     size_delta: row.size_before !== null && row.size_after !== null ? `${row.size_before} → ${row.size_after}` : ""
   })));
 }
 function registerGetAuditLog(program2) {
-  program2.command("get-audit-log").description("Query the audit log with optional filters.").option("-d, --document-id <uuid>", "Filter by document.").option("-a, --author <name>", "Filter by author.").option("-o, --operation <type>", "Filter by operation: create, update-content, update-metadata, delete, restore.").option("--since <iso>", "Lower-bound ISO timestamp.").option("--until <iso>", "Upper-bound ISO timestamp.").option("-l, --limit <n>", "Maximum entries (max 200).", "50").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action18);
+  program2.command("get-audit-log").description("Query the audit log with optional filters.").option("-d, --document-id <uuid>", "Filter by document.").option("-a, --author <name>", "Filter by author.").option("-o, --operation <type>", `Filter by operation: ${AUDIT_OPERATIONS.join(", ")}.`).option("--since <iso>", "Lower-bound ISO timestamp.").option("--until <iso>", "Upper-bound ISO timestamp.").option("-l, --limit <n>", "Maximum entries (max 200).", "50").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action18);
 }
 
 // src/cli/commands/relation.ts
@@ -78215,6 +78369,10 @@ async function resolveProjectIds(input, getOrCreateProject) {
   }
   return [];
 }
+// src/ingestion/client-bridge.ts
+init__projects();
+init__utils();
+
 // src/ingestion/types.ts
 class ConcurrencyConflictError extends Error {
   documentId;
@@ -78384,19 +78542,15 @@ class IngestionDbBridge {
     if (error2)
       throw new Error(error2.message ?? JSON.stringify(error2));
   }
-  async getOrCreateProject(name) {
-    const { data: existing } = await this.supabase.from("cerefox_projects").select("*").eq("name", name).maybeSingle();
-    if (existing)
-      return existing;
-    const { data, error: error2 } = await this.supabase.from("cerefox_projects").insert({ name, description: "" }).select("*").maybeSingle();
-    if (error2 || !data) {
-      throw error2 ?? new Error(`getOrCreateProject(${name}) returned no data`);
-    }
-    return data;
+  async getOrCreateProject(name, audit) {
+    const resolved = await resolveOrCreateProject(this.supabase, name, audit);
+    if (!resolved)
+      throw new Error(`getOrCreateProject(${name}) returned no data`);
+    return { id: resolved.projectId, name: resolved.projectName, description: null };
   }
   async createAuditEntry(args) {
     try {
-      await this.supabase.rpc("cerefox_create_audit_entry", {
+      const { error: error2 } = await this.supabase.rpc("cerefox_create_audit_entry", {
         p_document_id: args.documentId ?? null,
         p_version_id: args.versionId ?? null,
         p_operation: args.operation,
@@ -78406,7 +78560,11 @@ class IngestionDbBridge {
         p_size_after: args.sizeAfter ?? null,
         p_description: args.description ?? ""
       });
-    } catch {}
+      if (error2)
+        console.warn("createAuditEntry failed:", error2.message ?? error2);
+    } catch (err) {
+      console.warn("createAuditEntry failed:", err);
+    }
   }
 }
 
@@ -78469,7 +78627,7 @@ class IngestionPipeline {
       forceRechunk = false
     } = opts;
     const listFormProvided = projectIds !== undefined && projectIds !== null || projectNames !== undefined && projectNames !== null;
-    const getOrCreate = (name) => this.db.getOrCreateProject(name);
+    const getOrCreate = (name) => this.db.getOrCreateProject(name, { author, authorType });
     if (documentId) {
       const existing = await this.db.getDocumentById(documentId);
       if (!existing) {
@@ -80226,6 +80384,7 @@ function registerRestore(program2) {
 
 // src/cli/commands/search.ts
 init_cli_core();
+init__utils();
 init_client();
 
 // src/cli/util/embed.ts
@@ -84289,6 +84448,7 @@ function validateConfigValue(key, value) {
 
 // src/web/routes/config.ts
 init_config();
+init__utils();
 function unwrapScalarRpc(data) {
   if (typeof data === "string")
     return data;
@@ -84361,13 +84521,22 @@ function registerConfigRoutes(app, ctx) {
       return c2.json({ detail: invalid }, 400);
     const { error: error3 } = await ctx.supabase.rpc("cerefox_set_config", {
       p_key: key,
-      p_value: value
+      p_value: value,
+      p_author: "web-ui",
+      p_author_type: "user"
     });
-    if (error3)
+    if (error3) {
+      const remediation = storeWriteRemediation(error3.message ?? "", "cerefox_set_config");
+      if (remediation)
+        return c2.json({ detail: remediation }, 503);
       return c2.json({ detail: error3.message }, 500);
+    }
     return c2.json({ key, value });
   });
 }
+// src/web/routes/discovery.ts
+init__utils();
+
 // src/web/usage.ts
 function logWebUsage(ctx, params) {
   Promise.resolve(ctx.supabase.rpc("cerefox_log_usage", {
@@ -85132,6 +85301,7 @@ function registerDocumentReadRoutes(app, ctx) {
   });
 }
 // src/web/routes/documents-write.ts
+init__utils();
 async function createAuditEntry(ctx, args) {
   try {
     await ctx.supabase.rpc("cerefox_create_audit_entry", {
@@ -85839,6 +86009,16 @@ function registerPreferencesRoutes(app) {
 }
 
 // src/web/routes/projects.ts
+init__utils();
+function rpcRowToResponse(row) {
+  return {
+    id: row.project_id,
+    name: row.project_name,
+    description: row.project_description ?? null,
+    created_at: row.created_at ?? "",
+    updated_at: row.updated_at ?? ""
+  };
+}
 function projectRowToResponse(row) {
   return {
     id: row.id,
@@ -85867,11 +86047,25 @@ function registerProjectsRoutes(app, ctx) {
     if (!name)
       return c2.json({ detail: "Project name is required" }, 400);
     const description = String(body.description ?? "").trim();
-    const { data, error: error3 } = await ctx.supabase.from("cerefox_projects").insert({ name, description }).select("*").maybeSingle();
-    if (error3 || !data) {
-      return c2.json({ detail: error3?.message ?? "create_project returned no data" }, 500);
-    }
-    return c2.json(projectRowToResponse(data));
+    const { data, error: error3 } = await ctx.supabase.rpc("cerefox_create_project", {
+      p_name: name,
+      p_description: description,
+      p_author: "web-ui",
+      p_author_type: "user"
+    });
+    if (error3) {
+      const msg = error3.message ?? "";
+      if (isDuplicateKeyError(msg))
+        return c2.json({ detail: msg }, 409);
+      const remediation = storeWriteRemediation(msg, "cerefox_create_project");
+      if (remediation)
+        return c2.json({ detail: remediation }, 503);
+      return c2.json({ detail: msg }, 500);
+    }
+    const row = data?.[0];
+    if (!row)
+      return c2.json({ detail: "create_project returned no data" }, 500);
+    return c2.json(rpcRowToResponse(row));
   });
   app.put("/api/v1/projects/:project_id", async (c2) => {
     const projectId = c2.req.param("project_id");
@@ -85881,19 +86075,51 @@ function registerProjectsRoutes(app, ctx) {
     } catch {
       return c2.json({ detail: "Invalid JSON body" }, 400);
     }
-    const name = String(body.name ?? "").trim();
-    const description = String(body.description ?? "").trim();
-    const { data, error: error3 } = await ctx.supabase.from("cerefox_projects").update({ name, description }).eq("id", projectId).select("*").maybeSingle();
-    if (error3 || !data) {
-      return c2.json({ detail: error3?.message ?? "update_project returned no data" }, 500);
+    const update = {};
+    if (body.name != null) {
+      const name = String(body.name).trim();
+      if (!name)
+        return c2.json({ detail: "Project name cannot be empty" }, 400);
+      update.name = name;
     }
-    return c2.json(projectRowToResponse(data));
+    if (body.description != null)
+      update.description = String(body.description).trim();
+    if (Object.keys(update).length === 0) {
+      return c2.json({ detail: "Nothing to update — pass name and/or description" }, 400);
+    }
+    const { data, error: error3 } = await ctx.supabase.rpc("cerefox_update_project", {
+      p_project_id: projectId,
+      p_name: update.name ?? null,
+      p_description: update.description ?? null,
+      p_author: "web-ui",
+      p_author_type: "user"
+    });
+    if (error3) {
+      const msg = error3.message ?? "";
+      if (/not found/i.test(msg))
+        return c2.json({ detail: msg }, 404);
+      const remediation = storeWriteRemediation(msg, "cerefox_update_project");
+      if (remediation)
+        return c2.json({ detail: remediation }, 503);
+      return c2.json({ detail: msg }, 500);
+    }
+    const row = data?.[0];
+    if (!row)
+      return c2.json({ detail: "update_project returned no data" }, 500);
+    return c2.json(rpcRowToResponse(row));
   });
   app.delete("/api/v1/projects/:project_id", async (c2) => {
     const projectId = c2.req.param("project_id");
-    const { error: error3 } = await ctx.supabase.from("cerefox_projects").delete().eq("id", projectId);
+    const { data, error: error3 } = await ctx.supabase.rpc("cerefox_delete_project", {
+      p_project_id: projectId,
+      p_author: "web-ui",
+      p_author_type: "user"
+    });
     if (error3)
       return c2.json({ detail: error3.message }, 500);
+    const row = data?.[0];
+    if (!row?.deleted)
+      return c2.json({ detail: "Project not found" }, 404);
     return c2.json({ success: true });
   });
 }