@cerefox/memory 0.10.2 → 0.10.4

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

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

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

@@ -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-help-content.ts

@@ -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), `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 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. **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>\"` (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) |",
+  "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 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. **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```",
   "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>\" --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/metadata-search.ts

@@ -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,
@@ -78,12 +85,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
@@ -114,18 +121,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/set-document-projects.ts

@@ -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) {

package/dist/server-assets/supabase/functions/cerefox-metadata-search/index.ts

@@ -15,8 +15,11 @@ import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/inde
  * Note: cerefox-mcp calls the RPC directly (not this Edge Function).
  *
  * Request body (JSON):
- *   metadata_filter  object       required  Key-value pairs (AND semantics)
+ *   metadata_filter  object       optional  Key-value pairs (AND semantics)
  *   project_id       string       optional  Project UUID filter
+ *
+ * At least one of metadata_filter / project_id / updated_since / created_since
+ * must be supplied (an empty filter + project_id lists that project's docs).
  *   updated_since    string       optional  ISO-8601 lower bound for updated_at
  *   created_since    string       optional  ISO-8601 lower bound for created_at
  *   limit            number       optional  Max results (default: 10)
@@ -53,13 +56,12 @@ Deno.serve(async (req: Request): Promise<Response> => {
     const metadata_filter = body.metadata_filter;
 
     if (
-      !metadata_filter ||
-      typeof metadata_filter !== "object" ||
-      Array.isArray(metadata_filter) ||
-      Object.keys(metadata_filter).length === 0
+      metadata_filter !== undefined &&
+      metadata_filter !== null &&
+      (typeof metadata_filter !== "object" || Array.isArray(metadata_filter))
     ) {
       return new Response(
-        JSON.stringify({ error: "metadata_filter is required and must be a non-empty JSON object" }),
+        JSON.stringify({ error: "metadata_filter must be a JSON object when provided" }),
         { status: 400, headers: { ...CORS_HEADERS, "Content-Type": "application/json" } },
       );
     }
@@ -67,6 +69,22 @@ Deno.serve(async (req: Request): Promise<Response> => {
     const project_id = body.project_id ?? null;
     const updated_since = body.updated_since ?? null;
     const created_since = body.created_since ?? null;
+
+    // metadata_filter is optional, but at least one narrowing criterion is
+    // required so this never becomes an unbounded whole-KB dump. An empty
+    // filter + project_id lists a project's documents (the RPC's
+    // `metadata @> '{}'` matches every row; the project predicate narrows it).
+    const has_metadata =
+      metadata_filter && typeof metadata_filter === "object" &&
+      Object.keys(metadata_filter).length > 0;
+    if (!has_metadata && !project_id && !updated_since && !created_since) {
+      return new Response(
+        JSON.stringify({
+          error: "Provide at least one of: metadata_filter, project_id, updated_since, or created_since.",
+        }),
+        { status: 400, headers: { ...CORS_HEADERS, "Content-Type": "application/json" } },
+      );
+    }
     const limit = body.limit ?? 10;
     const include_content = body.include_content ?? false;
     const requested_max_bytes = body.max_bytes;
@@ -102,7 +120,7 @@ Deno.serve(async (req: Request): Promise<Response> => {
     }
 
     const params: Record<string, unknown> = {
-      p_metadata_filter: metadata_filter,
+      p_metadata_filter: has_metadata ? metadata_filter : {},
       p_project_id: project_id,
       p_updated_since: updated_since,
       p_created_since: created_since,

package/docs/guides/access-paths.md

@@ -209,7 +209,7 @@ paths.
 | Tier | Operations | Reversible? | Where exposed |
 |---|---|---|---|
 | 1. Reads + soft mutations | search, get, list-*, ingest (create/update), metadata-search, get-audit-log | n/a (reads) / yes (versioned) | All paths — MCP, Edge Functions, CLI, web UI |
-| 2. Soft-destructive | `delete_document` (soft delete to trash), `set_review_status` | yes — restorable via web UI | All paths (CLI: `cerefox document delete`; web UI; Python; **not** MCP or Edge Functions today) |
+| 2. Soft-destructive | `delete_document` (soft delete to trash), `set_review_status` | yes — restorable via web UI | All paths (CLI: `cerefox document delete`; web UI; **not** MCP or Edge Functions today) |
 | 3. **Hard-destructive** | `purge_document` (permanent), `restore_document` (un-trash), `set_version_archived` (toggle version retention) | no (purge) / yes (restore, but recovers from a destructive action) | **Web UI only** |
 
 ### Why purge / restore are web-UI-only

package/docs/guides/agent-coordination.md

@@ -53,7 +53,7 @@ A living document where agents record decisions, experiment outcomes, and lesson
 
 **Example**: A coding agent working on a project records "Chose PostgreSQL RPC approach over application-level logic because..." in a decision log document. Next week, a different agent working on a related feature searches Cerefox, finds the decision log, and understands the rationale without re-deriving it.
 
-**How it works**: Create a document with a structured format (date, context, decision, outcome). Use a consistent title or project tag so agents can find it. Use `update_if_exists: true` to append new entries.
+**How it works**: Create a document with a structured format (date, context, decision, outcome). Use a consistent title or project tag so agents can find it. To add entries over time, re-ingest with `update_if_exists: true` (or `document_id`) — this replaces the document in place, so build the new full content by appending to the prior content you fetched.
 
 **Best for**: Project-level institutional memory, avoiding repeated decisions, onboarding new agent sessions.
 

package/docs/guides/cli.md

@@ -207,7 +207,9 @@ cerefox document list [OPTIONS]
 | `--deleted` | flag | off | List soft-deleted (trashed) documents instead of active ones, newest-deleted first. Pair the ids with `cerefox document restore` / `cerefox document delete`. |
 | `--json` | flag | off | Machine-readable JSON output. |
 
-**Output**: tabular `id | title | source | status | updated_at` listing (or `deleted_at` with `--deleted`). CLI-only — there is no MCP equivalent.
+**Output**: tabular `id | title | source | status | updated_at` listing (or `deleted_at` with `--deleted`).
+
+**MCP equivalent**: scope-by-project / metadata / time listing maps to [`cerefox_metadata_search`](../../AGENT_GUIDE.md) — e.g. `cerefox_metadata_search(project_name="research")` lists that project's documents (the `metadata_filter` may be empty when another scope is supplied). The `--deleted` (trash) view and unscoped whole-KB listing remain CLI-only.
 
 ---
 
@@ -240,6 +242,43 @@ cerefox document edit <doc-id> --set-meta status=archived --unset-meta draft
 
 ---
 
+### `cerefox document set-projects`
+
+**Purpose**: replace a document's project memberships with **exactly** the given set (full-set replace — any project not listed is removed). This is the CLI equivalent of the `cerefox_set_document_projects` MCP tool; both share one membership-replace core, so they behave identically. Content is untouched; the change is logged as an `update-metadata` audit entry.
+
+**Synopsis**:
+```
+cerefox document set-projects [OPTIONS] DOCUMENT_ID [PROJECT_NAMES...]
+```
+
+**Options**:
+
+| Flag | Type | Default | Description |
+|---|---|---|---|
+| `[project-names...]` | variadic args | _none_ | One or more project names. Each is created if missing; order preserved; case-insensitively de-duplicated. |
+| `--clear` | flag | off | Remove the document from **all** projects. Mutually exclusive with passing names. |
+| `--author <name>` (`-a`) | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Identity recorded in the audit log. |
+| `--author-type <type>` | `user`\|`agent` | `user` | Caller type recorded in the audit log. |
+
+To set memberships **and** update content in one shot, use `cerefox document ingest --document-id <id> --project-name …` instead. Use this command when you only need to change membership.
+
+**Examples**:
+```bash
+# Set the document to belong to exactly these two projects (replaces any others)
+cerefox document set-projects <doc-id> research archive
+
+# Remove the document from all projects
+cerefox document set-projects <doc-id> --clear
+```
+
+**Output**: a confirmation line with the document title and the resulting project set (or a "cleared all memberships" line), plus a reminder that the previous set was replaced.
+
+**Exit codes**: `0` on success; `1` on validation error (no names and no `--clear`, or both) or if the document is missing / soft-deleted.
+
+**MCP equivalent**: [`cerefox_set_document_projects`](../../AGENT_GUIDE.md).
+
+---
+
 ### `cerefox document restore`
 
 **Purpose**: restore a soft-deleted (trashed) document back to active.
@@ -599,10 +638,59 @@ Every MCP parameter has an exact-name CLI flag (kebab-cased). Short forms exist
 | `cerefox_get_document(document_id, version_id, requestor)` | `cerefox document get <id> --version-id <vid> --requestor <name>` |
 | `cerefox_list_versions(document_id, requestor)` | `cerefox document version list <id> --requestor <name>` |
 | `cerefox_list_projects(requestor)` | `cerefox project list --requestor <name>` |
+| `cerefox_set_document_projects(document_id, project_names, author)` | `cerefox document set-projects <id> <name...> --author <a> --author-type <t>` (or `--clear` to remove all) |
 | `cerefox_list_metadata_keys()` | `cerefox metadata keys` |
 | `cerefox_metadata_search(metadata_filter, project_name, updated_since, created_since, limit, include_content, requestor)` | `cerefox metadata search --metadata-filter '<json>' --project-name <n> --updated-since <iso> --created-since <iso> --limit N --include-content --requestor <name>` |
 | `cerefox_get_audit_log(document_id, author, operation, since, until, limit, requestor)` | `cerefox audit list --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --requestor <name>` |
 
+## CLI ↔ MCP parity matrix
+
+The table above is MCP-first (it lists the tools that *have* a CLI form). This
+one is **CLI-first** — every `cerefox` command, with its MCP equivalent or an
+explicit reason it has none. It exists to make parity gaps visible. Legend:
+**✅ mapped** · **⚠️ gap** (a capability one surface has and the other lacks,
+arguably worth closing) · **🔒 intentional** (deliberately not on the MCP/agent
+surface).
+
+| CLI command | MCP equivalent | Status |
+|---|---|---|
+| `document ingest` | `cerefox_ingest` | ✅ |
+| `document ingest-dir` | — (agents loop `cerefox_ingest`) | 🔒 bulk filesystem walk; no server-side dir access from MCP |
+| `search` | `cerefox_search` | ✅ (CLI adds `--mode`/`--alpha`/`--min-score`/`--only-metadata`) |
+| `document get` | `cerefox_get_document` | ✅ |
+| `document list` | `cerefox_metadata_search` (scope by `project_name` / metadata / time) | ✅ as of this change. Unscoped whole-KB listing has no MCP path by design (scope it) |
+| `document edit` (title / metadata in place) | — | 🔒 intentional: a human/web-parity convenience. Agents update title+metadata deterministically via `cerefox_ingest` (with `document_id`); a metadata-only edit isn't a needed agent primitive |
+| `document delete` (soft-delete) | — | 🔒 destructive; trust model keeps delete/restore on CLI + web only |
+| `document restore` | — | 🔒 trust model (CLI + web only) |
+| `document version list` | `cerefox_list_versions` | ✅ |
+| `document version archive` / `unarchive` | — | 🔒 intentional: version-retention protection is exposed only to CLI + web (a maintenance concern, not an agent primitive) |
+| `document set-projects` | `cerefox_set_document_projects` | ✅ full-set replace of a document's project memberships (shared core; `--clear` to remove all) |
+| `project list` | `cerefox_list_projects` | ✅ |
+| `project create` / `edit` / `delete` | — | 🔒 project mutations CLI + web only |
+| `metadata keys` | `cerefox_list_metadata_keys` | ✅ |
+| `metadata search` | `cerefox_metadata_search` | ✅ |
+| `audit list` | `cerefox_get_audit_log` | ✅ |
+| `guides list` / `show` / `open` / `ingest` | `cerefox_get_help` (partial) | ✅~ `get_help` returns the bundled quick-reference; `guides` is the richer CLI form |
+| `server deploy` / `server reindex` | — | 🔒 operator/deploy surface |
+| `config list` / `get` / `set` | — | 🔒 runtime config; operator surface |
+| `web` / `mcp` | — | 🔒 lifecycle (`mcp` *is* the MCP server) |
+| `init` / `doctor` / `status` / `configure-agent` / `self-update` / `completion` / `backup *` | — | 🔒 install / health / ops |
+
+**Gap status** (the 🔒 rows are deliberate and out of scope):
+
+1. `document list` → **closed**: project/metadata/time-scoped listing now routes
+   through `cerefox_metadata_search` (it accepts an empty `metadata_filter` when
+   another scope is supplied).
+2. `cerefox_set_document_projects` → **closed**: added `cerefox document
+   set-projects` (full-set replace, `--clear` to remove all), sharing the
+   membership-replace core with the MCP tool.
+3. `document edit` (metadata/title-only edit) → **intentional non-gap**: a
+   human/web-parity convenience; agents use `cerefox_ingest` for content+metadata
+   updates. Revisit only if a concrete agent workflow needs metadata-only edits.
+4. `document version archive` / `unarchive` → **intentional non-gap**: version-retention
+   protection is exposed only to CLI + web (a maintenance concern, deliberately not on
+   the MCP/agent surface).
+
 ## Known issues
 
 None outstanding as of v0.1.17 (cerefox#27 — the `cerefox search` NameError — is resolved). When new bugs surface, they are tracked in the GitHub issues list; check there before relying on a behaviour the docs imply.

package/docs/guides/connect-agents.md

@@ -604,7 +604,7 @@ In the action editor, paste this schema (replace `<your-project-ref>`):
 openapi: 3.1.0
 info:
   title: Cerefox Knowledge Base
-  version: 1.8.0
+  version: 1.9.0
 servers:
   - url: https://<your-project-ref>.supabase.co/functions/v1
 paths:
@@ -895,15 +895,17 @@ paths:
     post:
       operationId: metadataSearch
       summary: >
-        Find documents by metadata key-value criteria without a text search term.
-        Use to discover documents tagged with specific attributes or browse by taxonomy.
+        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, or list a project's documents (pass project_id alone).
+        At least one of metadata_filter, project_id, updated_since, or
+        created_since must be supplied.
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
-              required: [metadata_filter]
               properties:
                 metadata_filter:
                   type: object
@@ -912,10 +914,14 @@ paths:
                   description: >
                     Key-value pairs; ALL must match (AND semantics).
                     Example: {"type": "decision", "status": "active"}.
+                    Optional — omit (or pass {}) to list by project_id / time
+                    range alone. At least one filter (metadata_filter, project_id,
+                    updated_since, or created_since) is required.
                 project_id:
                   type: string
                   description: >
-                    Filter by project UUID (optional). NOTE: this is the project
+                    Filter by project UUID (optional). Sufficient on its own to
+                    list that project's documents. NOTE: this is the project
                     UUID, not its name — unlike searchKnowledgeBase / ingestNote
                     which take project_name. Get UUIDs from listProjects.
                 updated_since:
@@ -1148,6 +1154,7 @@ The agent docs are written around MCP tool names. **CLI flag names match MCP par
 | `cerefox_get_document` | `cerefox document get <document-id> --version-id <vid> --requestor <name>` |
 | `cerefox_list_versions` | `cerefox document version list <document-id> --requestor <name>` |
 | `cerefox_list_projects` | `cerefox project list --requestor <name>` |
+| `cerefox_set_document_projects` | `cerefox document set-projects <document-id> <name...> --author <a> --author-type user\|agent` (or `--clear`) |
 | `cerefox_list_metadata_keys` | `cerefox metadata keys` |
 | `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --project-name <n> --requestor <name>` |
 | `cerefox_get_audit_log` | `cerefox audit list --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --json --requestor <name>` |