npm - @cerefox/memory - Versions diffs - 0.10.3 → 0.11.0 - Mend

@cerefox/memory 0.10.3 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/AGENT_GUIDE.md +47 -20
package/AGENT_QUICK_REFERENCE.md +16 -11
package/dist/bin/cerefox.js +525 -331
package/dist/frontend/assets/{index-DVXDQ7__.js → index-ojNhWSxm.js} +3 -3
package/dist/frontend/assets/index-ojNhWSxm.js.map +1 -0
package/dist/frontend/index.html +1 -1
package/dist/server-assets/_shared/ef-meta/index.ts +1 -1
package/dist/server-assets/_shared/mcp-tools/_projects.ts +117 -1
package/dist/server-assets/_shared/mcp-tools/get-document.ts +6 -2
package/dist/server-assets/_shared/mcp-tools/get-help-content.ts +6 -6
package/dist/server-assets/_shared/mcp-tools/ingest.ts +71 -6
package/dist/server-assets/_shared/mcp-tools/metadata-search.ts +20 -12
package/dist/server-assets/_shared/mcp-tools/search.ts +4 -1
package/dist/server-assets/_shared/mcp-tools/set-document-projects.ts +9 -74
package/dist/server-assets/db/rpcs.sql +77 -11
package/dist/server-assets/db/schema.sql +1 -1
package/dist/server-assets/supabase/functions/cerefox-get-document/index.ts +5 -1
package/dist/server-assets/supabase/functions/cerefox-ingest/index.ts +65 -1
package/dist/server-assets/supabase/functions/cerefox-metadata-search/index.ts +25 -7
package/docs/guides/access-paths.md +1 -1
package/docs/guides/agent-coordination.md +14 -1
package/docs/guides/cli.md +109 -6
package/docs/guides/connect-agents.md +51 -7
package/package.json +1 -1
package/dist/frontend/assets/index-DVXDQ7__.js.map +0 -1

package/dist/frontend/index.html CHANGED Viewed

@@ -15,7 +15,7 @@
       href="https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&display=swap"
     />
     <title>Cerefox</title>
-    <script type="module" crossorigin src="/app/assets/index-DVXDQ7__.js"></script>
+    <script type="module" crossorigin src="/app/assets/index-ojNhWSxm.js"></script>
     <link rel="stylesheet" crossorigin href="/app/assets/index-Asx5wD7g.css">
   </head>
   <body>

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

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
-export const EF_VERSION = "0.10.1";
+export const EF_VERSION = "0.11.0";
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

package/dist/server-assets/_shared/mcp-tools/_projects.ts CHANGED Viewed

@@ -21,7 +21,9 @@
  * prevents drift.
  */
-import type { MCPSupabaseClient } from "./types.ts";
+import type { AccessPath, MCPSupabaseClient } from "./types.ts";
+import { logUsage } from "./_utils.ts";
 /** Ensure `(documentId, project)` exists. Resolves project by name
  *  (case-insensitive); creates the project if missing. Idempotent.
@@ -104,6 +106,120 @@ export async function setDocumentProjectsByName(
   return projectIds;
 }
+export interface ReplaceDocumentProjectsResult {
+  documentTitle: string;
+  /** Names after stripping blanks + case-insensitive dedup, in input order. */
+  cleanNames: string[];
+  projectIds: string[];
+}
+/**
+ * Full-set replace of a document's project memberships, with audit + usage
+ * logging. The shared core behind both the `cerefox_set_document_projects`
+ * MCP tool and the `cerefox document set-projects` CLI command, so the two
+ * behave identically.
+ *
+ * Cleans the incoming names (strip blanks, preserve order, case-insensitive
+ * dedup), verifies the document exists and isn't soft-deleted, resolves each
+ * name → project_id (creating the project if absent), then DELETE-then-INSERT
+ * replaces the membership set. An empty (or all-blank) list clears all
+ * memberships. Writes an `update-metadata` audit entry (content is untouched)
+ * and a usage-log entry.
+ *
+ * Throws if the document is missing or soft-deleted. Callers validate
+ * argument *shape* (e.g. that `projectNames` is an array of strings).
+ */
+export async function replaceDocumentProjects(
+  supabase: MCPSupabaseClient,
+  opts: {
+    documentId: string;
+    projectNames: string[];
+    author: string;
+    authorType: string;
+    accessPath: AccessPath;
+  },
+): Promise<ReplaceDocumentProjectsResult> {
+  const { documentId, projectNames, author, authorType, accessPath } = opts;
+  // Strip empties; preserve order; dedup case-insensitively.
+  const seenLower = new Set<string>();
+  const cleanNames: string[] = [];
+  for (const n of projectNames) {
+    const stripped = (n ?? "").trim();
+    if (!stripped) continue;
+    const key = stripped.toLowerCase();
+    if (seenLower.has(key)) continue;
+    seenLower.add(key);
+    cleanNames.push(stripped);
+  }
+  // Verify the document exists and isn't soft-deleted.
+  const { data: doc } = await supabase
+    .from("cerefox_documents")
+    .select("id, title")
+    .eq("id", documentId)
+    .is("deleted_at", null)
+    .limit(1);
+  if (!doc?.length) {
+    throw new Error(`Document not found (or soft-deleted): ${documentId}`);
+  }
+  // Resolve each name → project_id (create if absent). Preserve order.
+  const projectIds: string[] = [];
+  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);
+    }
+  }
+  // DELETE-then-INSERT replace (matches Python assign_document_projects).
+  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 }));
+    await supabase.from("cerefox_document_projects").insert(rows);
+  }
+  // Audit entry — project membership is metadata, not content.
+  try {
+    await supabase.rpc("cerefox_create_audit_entry", {
+      p_document_id: documentId,
+      p_version_id: null,
+      p_operation: "update-metadata",
+      p_author: author,
+      p_author_type: authorType,
+      p_size_before: null,
+      p_size_after: null,
+      p_description:
+        cleanNames.length > 0
+          ? `Set document projects to [${cleanNames.join(", ")}]`
+          : "Cleared all project memberships",
+    });
+  } catch (err) {
+    console.warn("replaceDocumentProjects: audit entry failed", err);
+  }
+  logUsage(supabase, {
+    operation: "set-document-projects",
+    accessPath,
+    requestor: author,
+    document_id: documentId,
+    result_count: projectIds.length,
+  });
+  return { documentTitle: doc[0].title as string, cleanNames, projectIds };
+}
 /** Resolve a project name → project_id (case-insensitive), or `null` if
  *  not found. Does NOT create. Used by search / metadata-search to translate
  *  `project_name` parameters to UUIDs. */

package/dist/server-assets/_shared/mcp-tools/get-document.ts CHANGED Viewed

@@ -32,6 +32,7 @@ async function handler(
         full_content?: string;
         chunk_count?: number;
         total_chars?: number;
+        content_hash?: string;
       }
     | undefined;
@@ -46,13 +47,16 @@ async function handler(
   });
   const label = version_id !== null ? " (archived version)" : " (current)";
-  return `# ${row.doc_title ?? "Untitled"}${label}\n\n${row.full_content ?? ""}`;
+  // content_hash is the optimistic-concurrency token: pass it back as
+  // expected_content_hash when updating this document via cerefox_ingest.
+  const hashLine = row.content_hash ? `content_hash: ${row.content_hash}\n\n` : "";
+  return `# ${row.doc_title ?? "Untitled"}${label}\n${hashLine}${row.full_content ?? ""}`;
 }
 export const getDocumentTool: ToolDefinition = {
   name: "cerefox_get_document",
   description:
-    "Retrieve the full reconstructed content of a document. Pass version_id to retrieve an archived version; omit it (or pass null) for the current version. Version UUIDs are returned by cerefox_list_versions.",
+    "Retrieve the full reconstructed content of a document. Pass version_id to retrieve an archived version; omit it (or pass null) for the current version. Version UUIDs are returned by cerefox_list_versions. The response header includes the document's current content_hash — pass it back as expected_content_hash when updating via cerefox_ingest (optimistic concurrency).",
   inputSchema: {
     type: "object",
     required: ["document_id"],

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

@@ -11,16 +11,16 @@
  * docs/specs/polish-and-distribution-design.md §10d.
  */
-export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 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), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |\n| `cerefox_get_document` | Get full document by ID | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find docs by metadata (no text query) | `metadata_filter` (required), `include_content`, `updated_since` |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## 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. **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) -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\", author=\"my-agent\")\n```\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true, 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`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\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>\" --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_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor \"<your-name>\"` |\n| `cerefox_set_document_projects` | _MCP-only; a CLI command will be added in a future release. Until then, run via MCP if available._ |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n";
+export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 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`, `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token) | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## 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 read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. 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. **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`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\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_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor \"<your-name>\"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author \"<your-name>\" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n";
 /** Sections keyed by their H2 heading text (lower-cased for matching). */
 export const HELP_SECTIONS: Record<string, string> = {
-  "Tools": "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |\n| `cerefox_get_document` | Get full document by ID | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find docs by metadata (no text query) | `metadata_filter` (required), `include_content`, `updated_since` |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |",
-  "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. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.",
-  "Update Workflow (ID-based -- preferred)": "## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\", author=\"my-agent\")\n```",
-  "Update Workflow (title-based -- fallback)": "## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true, author=\"my-agent\")\n```",
+  "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`, `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token) | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |",
+  "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 read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. 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. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.",
+  "Update Workflow (ID-based -- preferred)": "## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\",\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.",
+  "Update Workflow (title-based -- fallback)": "## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc (note its hash) -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true,\n       expected_content_hash=\"<the hash you read>\", author=\"my-agent\")\n```",
   "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`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\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>\" --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_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor \"<your-name>\"` |\n| `cerefox_set_document_projects` | _MCP-only; a CLI command will be added in a future release. Until then, run via MCP if available._ |\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`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\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_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor \"<your-name>\"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author \"<your-name>\" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.",
 };
 export const HELP_SECTION_HEADINGS: string[] = ["Tools", "Essential Rules", "Update Workflow (ID-based -- preferred)", "Update Workflow (title-based -- fallback)", "Catch-Up Workflow", "CLI fallback (when MCP is unavailable)"];

package/dist/server-assets/_shared/mcp-tools/ingest.ts CHANGED Viewed

@@ -23,6 +23,43 @@ import { ensureDocumentInProject, setDocumentProjectsByName } from "./_projects.
 import { logUsage } from "./_utils.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+/**
+ * Agent-first instructions for an optimistic-concurrency conflict (iter-32).
+ * Raised either by the local fast-fail (before the embedding spend) or by the
+ * authoritative check inside the cerefox_ingest_document RPC.
+ */
+function conflictError(documentId: string, expectedHash: string, currentHash: string): Error {
+  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.`,
+  );
+}
+/** Map RPC-side CEREFOX_CONFLICT / CEREFOX_TOKEN_REQUIRED errors to agent-first text. */
+function mapIngestRpcError(message: string, documentId: string): Error {
+  if (message.includes("CEREFOX_CONFLICT")) {
+    const current = message.match(/current hash ([0-9a-f]{64})/)?.[1] ?? "unknown";
+    const expected = message.match(/expected hash ([0-9a-f]{64})/)?.[1] ?? "unknown";
+    return conflictError(documentId, expected, current);
+  }
+  if (message.includes("CEREFOX_TOKEN_REQUIRED")) {
+    const current = message.match(/Current hash: ([0-9a-f]{64})/)?.[1];
+    return new Error(
+      `Concurrency token required: content updates need expected_content_hash — ` +
+        `the content_hash of the version you based your edit on (returned by ` +
+        `cerefox_get_document, cerefox_search, and cerefox_metadata_search).` +
+        (current ? ` The document's current hash is ${current}; pass it ONLY if your edit was based on the current content.` : "") +
+        ` If you have not read the document, read it first. To deliberately overwrite ` +
+        `regardless of concurrent changes, pass last_write_wins=true.`,
+    );
+  }
+  return new Error(`Ingest RPC failed: ${message}`);
+}
 async function handler(
   supabase: MCPSupabaseClient,
   args: Record<string, unknown>,
@@ -38,6 +75,8 @@ async function handler(
   const update_if_exists = (args.update_if_exists as boolean | undefined) ?? false;
   const author = (args.author as string | undefined) ?? "mcp-agent";
   const author_type = "agent"; // MCP path is always agent
+  const expected_content_hash = (args.expected_content_hash as string | undefined)?.trim() || null;
+  const last_write_wins = (args.last_write_wins as boolean | undefined) ?? false;
   if (!title || !content?.trim()) {
     throw new McpInvalidParams("title and content are required");
@@ -83,7 +122,13 @@ async function handler(
       const note = 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.${note}`;
+      return `Document already up-to-date: "${existingDoc.title}" (id: ${existingDoc.id}). Content hash unchanged (${contentHash}).${note}`;
+    }
+    // Fast-fail on a stale token BEFORE paying the embedding cost. Advisory
+    // only — the authoritative, race-free check is inside the RPC (FOR UPDATE).
+    if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
+      throw conflictError(existingDoc.id, expected_content_hash, existingDoc.content_hash);
     }
     const chunks = chunkMarkdown(content);
@@ -115,9 +160,11 @@ async function handler(
       p_author: author,
       p_author_type: author_type,
       p_source_label: source,
+      p_expected_content_hash: expected_content_hash,
+      p_last_write_wins: last_write_wins,
     });
-    if (ingestErr) throw new Error(`Ingest RPC failed: ${ingestErr.message}`);
+    if (ingestErr) throw mapIngestRpcError(ingestErr.message, existingDoc.id);
     logUsage(supabase, {
       operation: "ingest",
@@ -136,7 +183,7 @@ async function handler(
     const note = update_if_exists
       ? ""
       : " Note: update_if_exists flag was overridden by document_id.";
-    return `Document updated: "${title}" (id: ${existingDoc.id}), ${chunks.length} chunk(s), ${totalChars} chars.${note}`;
+    return `Document updated: "${title}" (id: ${existingDoc.id}), ${chunks.length} chunk(s), ${totalChars} chars. New content_hash: ${contentHash}.${note}`;
   }
   // ── Update-existing path ─────────────────────────────────────────────────
@@ -152,7 +199,13 @@ async function handler(
       const existingDoc = existing[0];
       if (existingDoc.content_hash === contentHash) {
-        return `Document already up-to-date: "${existingDoc.title}" (id: ${existingDoc.id}). Content hash unchanged.`;
+        return `Document already up-to-date: "${existingDoc.title}" (id: ${existingDoc.id}). Content hash unchanged (${contentHash}).`;
+      }
+      // Fast-fail on a stale token BEFORE the embedding cost (advisory; the
+      // authoritative check is in the RPC).
+      if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
+        throw conflictError(existingDoc.id, expected_content_hash, existingDoc.content_hash);
       }
       const chunks = chunkMarkdown(content);
@@ -184,9 +237,11 @@ async function handler(
         p_author: author,
         p_author_type: author_type,
         p_source_label: source,
+        p_expected_content_hash: expected_content_hash,
+        p_last_write_wins: last_write_wins,
       });
-      if (ingestErr) throw new Error(`Ingest RPC failed: ${ingestErr.message}`);
+      if (ingestErr) throw mapIngestRpcError(ingestErr.message, existingDoc.id);
       logUsage(supabase, {
         operation: "ingest",
@@ -202,7 +257,7 @@ async function handler(
         await ensureDocumentInProject(supabase, existingDoc.id, project_name);
       }
-      return `Document updated: "${existingDoc.title}" (id: ${existingDoc.id}), ${chunks.length} chunk(s), ${totalChars} chars.`;
+      return `Document updated: "${existingDoc.title}" (id: ${existingDoc.id}), ${chunks.length} chunk(s), ${totalChars} chars. New content_hash: ${contentHash}.`;
     }
     // Fall through to create path
   }
@@ -303,6 +358,16 @@ export const ingestTool: ToolDefinition = {
         description:
           "When true, update an existing document with the same title instead of creating a new one (default: false). Ignored when document_id is provided.",
       },
+      expected_content_hash: {
+        type: "string",
+        description:
+          "REQUIRED on content updates (optimistic concurrency): the content_hash of the document version you based your edit on, as returned by cerefox_get_document / cerefox_search / cerefox_metadata_search. If the document changed since you read it, the update fails with a conflict — re-read, merge, retry with the new hash. Not needed when creating a new document.",
+      },
+      last_write_wins: {
+        type: "boolean",
+        description:
+          "Explicitly skip the concurrency check and overwrite regardless of concurrent changes (default: false). Use ONLY when an external source of truth makes conflicts meaningless (e.g. re-syncing from files). Recorded in the audit log.",
+      },
       metadata: { type: "object", description: "Arbitrary JSON metadata (optional)" },
       author: {
         type: "string",

package/dist/server-assets/_shared/mcp-tools/metadata-search.ts CHANGED Viewed

@@ -24,11 +24,18 @@ async function handler(
   const include_content = (args.include_content as boolean | undefined) ?? false;
   const requested_max_bytes = args.max_bytes as number | undefined;
-  if (!metadata_filter || typeof metadata_filter !== "object" || Array.isArray(metadata_filter)) {
-    throw new McpInvalidParams("metadata_filter is required and must be a JSON object");
+  if (metadata_filter !== undefined && (typeof metadata_filter !== "object" || Array.isArray(metadata_filter))) {
+    throw new McpInvalidParams("metadata_filter must be a JSON object when provided");
   }
-  if (Object.keys(metadata_filter).length === 0) {
-    throw new McpInvalidParams("metadata_filter must contain at least one key-value pair");
+  const has_metadata = !!metadata_filter && Object.keys(metadata_filter).length > 0;
+  // metadata_filter is optional, but at least one narrowing criterion is
+  // required so this can never become an unbounded whole-KB dump. An empty
+  // filter + project_name lists a project's documents: the RPC's
+  // `metadata @> '{}'` matches every row and the project predicate narrows it.
+  if (!has_metadata && !project_name && !updated_since && !created_since) {
+    throw new McpInvalidParams(
+      "Provide at least one of: metadata_filter, project_name, updated_since, or created_since.",
+    );
   }
   // Resolve project name to UUID if provided
@@ -45,7 +52,7 @@ async function handler(
     : null;
   const params: Record<string, unknown> = {
-    p_metadata_filter: metadata_filter,
+    p_metadata_filter: metadata_filter ?? {},
     p_project_id: projectId,
     p_updated_since: updated_since ?? null,
     p_created_since: created_since ?? null,
@@ -71,6 +78,7 @@ async function handler(
     project_ids: string[];
     project_names: string[];
     version_count: number;
+    content_hash: string | null;
     content: string | null;
   }>;
@@ -78,12 +86,12 @@ async function handler(
     operation: "metadata_search",
     accessPath: ctx.accessPath,
     requestor: args.requestor as string | undefined,
-    query_text: JSON.stringify(metadata_filter),
+    query_text: JSON.stringify(metadata_filter ?? {}),
     project_id: projectId,
     result_count: rows.length,
   });
-  if (rows.length === 0) return "No documents match the metadata filter.";
+  if (rows.length === 0) return "No documents match the given criteria.";
   // Note: when include_content is true the RPC already respects p_max_bytes
   // server-side. The applyByteBudget helper is retained here only for
@@ -98,9 +106,10 @@ async function handler(
     const meta = Object.entries(row.doc_metadata ?? {})
       .map(([k, v]) => `${k}=${v}`)
       .join(", ");
+    const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
     const header =
       `## ${row.title} [id: ${row.document_id}]\n` +
-      `${meta}${projects} | ${row.total_chars} chars | ${row.review_status} | updated ${row.updated_at?.slice(0, 10) ?? "?"}`;
+      `${meta}${projects} | ${row.total_chars} chars | ${row.review_status} | updated ${row.updated_at?.slice(0, 10) ?? "?"}${hash}`;
     if (include_content && row.content) {
       return `${header}\n\n${row.content}`;
@@ -114,18 +123,17 @@ async function handler(
 export const metadataSearchTool: ToolDefinition = {
   name: "cerefox_metadata_search",
   description:
-    "Find documents by metadata key-value criteria without a text search term. Use to discover documents tagged with specific attributes, browse by taxonomy, or retrieve messages/tasks by type and status.",
+    "Find or list documents by metadata key-value criteria without a text search term. Use to discover documents tagged with specific attributes, browse by taxonomy, retrieve messages/tasks by type and status, or list all documents in a project (pass project_name alone). At least one of metadata_filter, project_name, updated_since, or created_since must be supplied; results are ordered newest-updated first.",
   inputSchema: {
     type: "object",
-    required: ["metadata_filter"],
     properties: {
       metadata_filter: {
         type: "object",
         description:
-          'Key-value pairs; ALL must match (AND semantics). Example: {"type": "decision", "status": "active"}. Call cerefox_list_metadata_keys first to discover available keys.',
+          'Key-value pairs; ALL must match (AND semantics). Example: {"type": "decision", "status": "active"}. Call cerefox_list_metadata_keys first to discover available keys. Optional — omit (or pass {}) to list by project_name / time range alone.',
         additionalProperties: { type: "string" },
       },
-      project_name: { type: "string", description: "Restrict to a project by name (optional)" },
+      project_name: { type: "string", description: "Restrict to a project by name. Sufficient on its own to list that project's documents (optional)." },
       updated_since: {
         type: "string",
         description: "ISO-8601 timestamp; only docs updated on/after (optional)",

package/dist/server-assets/_shared/mcp-tools/search.ts CHANGED Viewed

@@ -135,6 +135,7 @@ async function handler(
     is_partial?: boolean;
     chunk_count?: number;
     total_chars?: number;
+    content_hash?: string;
   }>;
   const parts: string[] = rows.map((row) => {
@@ -144,7 +145,9 @@ async function handler(
     const partial = row.is_partial
       ? ` -- partial (${row.chunk_count} of ${(row.total_chars ?? 0).toLocaleString()} chars)`
       : "";
-    return `## ${title}${docId}${score}${partial}\n\n${row.full_content ?? ""}`;
+    // content_hash = the concurrency token for cerefox_ingest updates (iter-32).
+    const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
+    return `## ${title}${docId}${score}${partial}${hash}\n\n${row.full_content ?? ""}`;
   });
   let output = parts.join("\n\n---\n\n");

package/dist/server-assets/_shared/mcp-tools/set-document-projects.ts CHANGED Viewed

@@ -11,7 +11,7 @@
 import type { MCPSupabaseClient } from "./types.ts";
-import { logUsage } from "./_utils.ts";
+import { replaceDocumentProjects } from "./_projects.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
 async function handler(
@@ -42,80 +42,15 @@ async function handler(
     throw new McpInvalidParams("project_names must contain only strings.");
   }
-  // Strip empties; preserve order; dedup case-insensitively.
-  const seenLower = new Set<string>();
-  const cleanNames: string[] = [];
-  for (const n of project_names_raw as string[]) {
-    const stripped = n.trim();
-    if (!stripped) continue;
-    const key = stripped.toLowerCase();
-    if (seenLower.has(key)) continue;
-    seenLower.add(key);
-    cleanNames.push(stripped);
-  }
-  // Verify the document exists and isn't soft-deleted.
-  const { data: doc } = await supabase
-    .from("cerefox_documents")
-    .select("id, title")
-    .eq("id", document_id)
-    .is("deleted_at", null)
-    .limit(1);
-  if (!doc?.length) {
-    throw new Error(`Document not found (or soft-deleted): ${document_id}`);
-  }
-  // Resolve each name → project_id (create if absent). Preserve order.
-  const projectIds: string[] = [];
-  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);
-    }
-  }
-  // DELETE-then-INSERT replace (matches Python assign_document_projects).
-  await supabase.from("cerefox_document_projects").delete().eq("document_id", document_id);
-  if (projectIds.length > 0) {
-    const rows = projectIds.map((pid) => ({ document_id, project_id: pid }));
-    await supabase.from("cerefox_document_projects").insert(rows);
-  }
-  // Audit entry — project membership is metadata, not content.
-  try {
-    await supabase.rpc("cerefox_create_audit_entry", {
-      p_document_id: document_id,
-      p_version_id: null,
-      p_operation: "update-metadata",
-      p_author: author,
-      p_author_type: "agent",
-      p_size_before: null,
-      p_size_after: null,
-      p_description:
-        cleanNames.length > 0
-          ? `Set document projects to [${cleanNames.join(", ")}]`
-          : "Cleared all project memberships",
-    });
-  } catch (err) {
-    console.warn("set-document-projects: audit entry failed", err);
-  }
-  logUsage(supabase, {
-    operation: "set-document-projects",
+  // The clean/dedup, existence check, name→id resolution, DELETE-then-INSERT
+  // replace, audit entry, and usage log all live in the shared core so the
+  // `cerefox document set-projects` CLI command behaves identically.
+  const { cleanNames, projectIds } = await replaceDocumentProjects(supabase, {
+    documentId: document_id,
+    projectNames: project_names_raw as string[],
+    author,
+    authorType: "agent",
     accessPath: ctx.accessPath,
-    requestor: author,
-    document_id,
-    result_count: projectIds.length,
   });
   if (cleanNames.length === 0) {