@cerefox/memory 0.8.3 → 0.9.0

package/dist/bin/cerefox.js

@@ -7184,7 +7184,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "0.8.3";
+var PKG_VERSION = "0.9.0";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js
@@ -26819,11 +26819,11 @@ async function runSyncSelfDocs(options = {}) {
     printTable(outcomes.filter((o) => o.status === "error").map((o) => ({ topic: o.topic, error: o.detail.slice(0, 100) })));
   }
 }
-async function action15(options) {
+async function action16(options) {
   await runSyncSelfDocs(options);
 }
 function registerSyncSelfDocs(program2) {
-  program2.command("sync-self-docs").description("Ingest bundled Cerefox docs under the _cerefox-self-docs project.").option("--dry-run", "List what would be ingested without writing.").option("--project <name>", "Override the target project name.", "_cerefox-self-docs").action(action15);
+  program2.command("sync-self-docs").description("Ingest bundled Cerefox docs under the _cerefox-self-docs project.").option("--dry-run", "List what would be ingested without writing.").option("--project <name>", "Override the target project name.", "_cerefox-self-docs").action(action16);
 }
 var init_sync_self_docs = __esm(() => {
   init_cli_core();
@@ -39930,6 +39930,7 @@ var {
 
 // src/cli/program.ts
 init_meta();
+init_cli_core();
 
 // src/cli/commands/backup.ts
 init_cli_core();
@@ -42001,6 +42002,64 @@ function registerDeployServer(program2) {
   program2.command("deploy-server").description("Deploy/update the Cerefox server side (schema + RPCs + Edge Functions) on Supabase.").option("--dry-run", "Print the plan + pre-flight without deploying.").option("--schema-only", "Deploy/update only the schema + RPCs (skip Edge Functions).").option("--functions-only", "Deploy only the Edge Functions (skip the schema/RPCs).").option("--project-ref <ref>", "Supabase project ref for Edge Function deploys (default: derived from CEREFOX_SUPABASE_URL).").action(action8);
 }
 
+// src/cli/commands/document-restore.ts
+init_cli_core();
+init_client();
+async function action9(documentId, options) {
+  const client = getClient();
+  const { data: doc, error } = await client.raw.from("cerefox_documents").select("id, title, deleted_at").eq("id", documentId).maybeSingle();
+  if (error)
+    throw systemError(`Lookup failed: ${error.message}`);
+  if (!doc)
+    throw notFound(`Document ${documentId} not found.`);
+  if (!doc.deleted_at) {
+    println(c.dim(`Document ${documentId} ("${doc.title}") is not soft-deleted — nothing to restore.`));
+    return;
+  }
+  const author = resolveAuthor(options.author);
+  const authorType = resolveAuthorType(options.authorType);
+  if (author === "unknown") {
+    warn("No --author / CEREFOX_AUTHOR_NAME set — audit log will record this restore as 'unknown'.");
+  }
+  await client.rpc("cerefox_restore_document", {
+    p_document_id: documentId,
+    p_author: author,
+    p_author_type: authorType
+  });
+  println(c.green(`✓ Restored "${doc.title}" (id: ${documentId}) from the trash.`));
+}
+function registerDocumentRestore(parent) {
+  parent.command("restore").description("Restore a soft-deleted document from the trash (inverse of `document delete`).").argument("<document-id>", "UUID of the soft-deleted document.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action9);
+}
+
+// src/cli/commands/version-archive.ts
+init_cli_core();
+init_client();
+async function setArchived(versionId, archived, options) {
+  const client = getClient();
+  const { data, error } = await client.raw.from("cerefox_document_versions").update({ archived }).eq("id", versionId).select("document_id, version_number").maybeSingle();
+  if (error)
+    throw systemError(`Update failed: ${error.message}`);
+  if (!data)
+    throw notFound(`Version ${versionId} not found.`);
+  const author = resolveAuthor(options.author);
+  const authorType = resolveAuthorType(options.authorType);
+  const op = archived ? "archive" : "unarchive";
+  await client.raw.rpc("cerefox_create_audit_entry", {
+    p_document_id: data.document_id,
+    p_version_id: versionId,
+    p_operation: op,
+    p_author: author,
+    p_author_type: authorType,
+    p_description: `Version ${data.version_number} ${op}d`
+  });
+  println(c.green(`✓ Version ${data.version_number} (${versionId}) ${op}d.`));
+}
+function registerVersionArchive(parent) {
+  parent.command("archive").description("Archive a document version (protect it from version cleanup).").argument("<version-id>", "UUID of the version (from `cerefox version list`).").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action((versionId, options) => setArchived(versionId, true, options));
+  parent.command("unarchive").description("Unarchive a document version (allow version cleanup again).").argument("<version-id>", "UUID of the version (from `cerefox version list`).").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action((versionId, options) => setArchived(versionId, false, options));
+}
+
 // src/cli/commands/docs.ts
 init_cli_core();
 init_bundled_docs();
@@ -42012,7 +42071,7 @@ function openInBrowser(path) {
     println(c.dim(`(could not auto-open; the file is at: ${path})`));
   }
 }
-function action9(topic, options) {
+function action10(topic, options) {
   const docs = listBundledDocs();
   if (options.list || !topic && !options.print) {
     if (docs.length === 0) {
@@ -42041,7 +42100,7 @@ function action9(topic, options) {
   openInBrowser(doc.path);
 }
 function registerDocs(program2) {
-  program2.command("docs").description("Open bundled Cerefox docs in your browser (or print to stdout).").argument("[topic]", "Doc topic (e.g. quickstart, connect-agents). Omit for the index.").option("--print", "Print to stdout instead of opening a browser.").option("--list", "List available topics.").action(action9);
+  program2.command("docs").description("Open bundled Cerefox docs in your browser (or print to stdout).").argument("[topic]", "Doc topic (e.g. quickstart, connect-agents). Omit for the index.").option("--print", "Print to stdout instead of opening a browser.").option("--list", "List available topics.").action(action10);
 }
 
 // ../../node_modules/.bun/ora@9.4.0/node_modules/ora/index.js
@@ -46001,7 +46060,7 @@ function symbol(status) {
       return cErr.dim("ℹ");
   }
 }
-async function action10(options) {
+async function action11(options) {
   const useSpinner = !options.json && process.stderr.isTTY;
   const spinner = useSpinner ? ora({ text: "Starting checks…", spinner: "dots", stream: process.stderr }).start() : null;
   const results = await runAllChecks({
@@ -46058,13 +46117,13 @@ async function action10(options) {
   }
 }
 function registerDoctor(program2) {
-  program2.command("doctor").description("Run diagnostic checks against the installed Cerefox.").option("--json", "Emit machine-readable JSON (no colours, structured output).").action(action10);
+  program2.command("doctor").description("Run diagnostic checks against the installed Cerefox.").option("--json", "Emit machine-readable JSON (no colours, structured output).").action(action11);
 }
 
 // src/cli/commands/get-audit-log.ts
 init_cli_core();
 init_client();
-async function action11(options) {
+async function action12(options) {
   const limit = parsePositiveInt(options.limit, "--limit", 50);
   const client = getClient();
   const data = await client.rpc("cerefox_list_audit_entries", {
@@ -46102,14 +46161,14 @@ async function action11(options) {
   })));
 }
 function registerGetAuditLog(program2) {
-  program2.command("get-audit-log").description("Query the audit log with optional filters.").option("-d, --document-id <uuid>", "Filter by document.").option("-a, --author <name>", "Filter by author.").option("-o, --operation <type>", "Filter by operation: create, update-content, update-metadata, delete, restore.").option("--since <iso>", "Lower-bound ISO timestamp.").option("--until <iso>", "Upper-bound ISO timestamp.").option("-l, --limit <n>", "Maximum entries (max 200).", "50").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action11);
+  program2.command("get-audit-log").description("Query the audit log with optional filters.").option("-d, --document-id <uuid>", "Filter by document.").option("-a, --author <name>", "Filter by author.").option("-o, --operation <type>", "Filter by operation: create, update-content, update-metadata, delete, restore.").option("--since <iso>", "Lower-bound ISO timestamp.").option("--until <iso>", "Upper-bound ISO timestamp.").option("-l, --limit <n>", "Maximum entries (max 200).", "50").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action12);
 }
 
 // src/cli/commands/get-doc.ts
 init_cli_core();
 init_cli_core();
 init_client();
-async function action12(documentId, options) {
+async function action13(documentId, options) {
   const client = getClient();
   const rows = await client.rpc("cerefox_get_document", {
     p_document_id: documentId,
@@ -46139,7 +46198,7 @@ async function action12(documentId, options) {
   println(doc.full_content);
 }
 function registerGetDoc(program2) {
-  program2.command("get-doc").description("Retrieve the full content of a document by ID.").argument("<document-id>", "UUID of the document.").option("--version-id <uuid>", "Specific archived version (default: current).").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action12);
+  program2.command("get-doc").description("Retrieve the full content of a document by ID.").argument("<document-id>", "UUID of the document.").option("--version-id <uuid>", "Specific archived version (default: current).").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action13);
 }
 
 // src/cli/commands/ingest.ts
@@ -46876,7 +46935,7 @@ async function readContent(path, paste) {
   const titleFromPath = basename2(path, extname2(path));
   return { content, titleFromPath };
 }
-async function action13(path, options) {
+async function action14(path, options) {
   const { content, titleFromPath } = await readContent(path, Boolean(options.paste));
   const title = options.title ?? titleFromPath;
   if (!title || title.trim() === "") {
@@ -46948,7 +47007,7 @@ async function action13(path, options) {
   }
 }
 function registerIngest(program2) {
-  program2.command("ingest").description("Ingest a file (or stdin paste) into the knowledge base.").argument("[path]", "Path to the file to ingest. Omit when using --paste.").option("--paste", "Read content from stdin instead of a file.").option("-t, --title <title>", "Document title (required with --paste; defaults to filename without extension).").option("-p, --project-name <name>", "Single project membership (non-destructive on update).").option("-P, --project-names <names>", "Comma-separated full project membership set (destructive replace on update).").option("-m, --metadata <json>", "JSON metadata object.").option("--source <label>", "Origin label (default: cli).", "cli").option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-i, --document-id <uuid>", "Update a specific document by UUID (overrides --update-if-exists).").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action13);
+  program2.command("ingest").description("Ingest a file (or stdin paste) into the knowledge base.").argument("[path]", "Path to the file to ingest. Omit when using --paste.").option("--paste", "Read content from stdin instead of a file.").option("-t, --title <title>", "Document title (required with --paste; defaults to filename without extension).").option("-p, --project-name <name>", "Single project membership (non-destructive on update).").option("-P, --project-names <names>", "Comma-separated full project membership set (destructive replace on update).").option("-m, --metadata <json>", "JSON metadata object.").option("--source <label>", "Origin label (default: cli).", "cli").option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-i, --document-id <uuid>", "Update a specific document by UUID (overrides --update-if-exists).").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action14);
 }
 
 // src/cli/commands/ingest-dir.ts
@@ -46984,7 +47043,7 @@ function walk(dir, extensions) {
   }
   return files;
 }
-async function action14(dir, options) {
+async function action15(dir, options) {
   const extensions = new Set((options.extensions ?? ".md,.txt").split(",").map((e) => e.trim().toLowerCase()).map((e) => e.startsWith(".") ? e : "." + e).filter((e) => e.length > 0));
   const files = walk(dir, extensions);
   if (files.length === 0) {
@@ -47057,7 +47116,7 @@ async function action14(dir, options) {
   }
 }
 function registerIngestDir(program2) {
-  program2.command("ingest-dir").description("Recursively ingest a directory of markdown / text files.").argument("<dir>", "Root directory to walk.").option("-p, --project-name <name>", "Project membership for all ingested docs.").option("-m, --metadata <json>", "JSON metadata applied to every doc.").option("--source <label>", "Origin label (default: cli).", "cli").option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("-e, --extensions <list>", "Comma-separated file extensions to ingest.", ".md,.txt").action(action14);
+  program2.command("ingest-dir").description("Recursively ingest a directory of markdown / text files.").argument("<dir>", "Root directory to walk.").option("-p, --project-name <name>", "Project membership for all ingested docs.").option("-m, --metadata <json>", "JSON metadata applied to every doc.").option("--source <label>", "Origin label (default: cli).", "cli").option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("-e, --extensions <list>", "Comma-separated file extensions to ingest.", ".md,.txt").action(action15);
 }
 
 // src/cli/commands/init.ts
@@ -47387,7 +47446,7 @@ function writeAnswersTo(target, answers) {
     }
   }
 }
-async function action16(options) {
+async function action17(options) {
   const homeEnv = join9(homedir5(), USER_STATE_DIR_NAME, ".env");
   const cwdEnv = join9(process.cwd(), ".env");
   const explicitDir = (process.env.CEREFOX_CONFIG_DIR ?? "").trim();
@@ -47496,13 +47555,13 @@ async function action16(options) {
   await postWriteLifecycle(target, options);
 }
 function registerInit(program2) {
-  program2.command("init").description("Interactive first-run setup (config, schema deploy stub, optional MCP wiring).").option("-c, --config <file>", "Non-interactive mode: read answers from a JSON file.").option("--force", "Overwrite existing configuration without prompting.").option("--skip-schema", "Skip the schema deploy step.").option("--skip-self-docs", "Skip the bundled self-doc ingest.").option("--skip-agent-config", "Skip the optional MCP agent wiring.").action(action16);
+  program2.command("init").description("Interactive first-run setup (config, schema deploy stub, optional MCP wiring).").option("-c, --config <file>", "Non-interactive mode: read answers from a JSON file.").option("--force", "Overwrite existing configuration without prompting.").option("--skip-schema", "Skip the schema deploy step.").option("--skip-self-docs", "Skip the bundled self-doc ingest.").option("--skip-agent-config", "Skip the optional MCP agent wiring.").action(action17);
 }
 
 // src/cli/commands/list-docs.ts
 init_cli_core();
 init_client();
-async function action17(options) {
+async function action18(options) {
   const limit = parsePositiveInt(options.limit, "--limit", 100);
   const client = getClient();
   let projectId;
@@ -47557,13 +47616,13 @@ async function action17(options) {
   })));
 }
 function registerListDocs(program2) {
-  program2.command("list-docs").description("List documents in the knowledge base.").option("-p, --project <name>", "Filter to a specific project.").option("-l, --limit <n>", "Maximum docs to return.", "100").option("--json", "Emit machine-readable JSON.").action(action17);
+  program2.command("list-docs").description("List documents in the knowledge base.").option("-p, --project <name>", "Filter to a specific project.").option("-l, --limit <n>", "Maximum docs to return.", "100").option("--json", "Emit machine-readable JSON.").action(action18);
 }
 
 // src/cli/commands/list-metadata-keys.ts
 init_cli_core();
 init_client();
-async function action18(options) {
+async function action19(options) {
   const client = getClient();
   const data = await client.rpc("cerefox_list_metadata_keys");
   if (data === null) {
@@ -47591,13 +47650,13 @@ async function action18(options) {
   })));
 }
 function registerListMetadataKeys(program2) {
-  program2.command("list-metadata-keys").description("List all metadata keys with document counts and example values.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action18);
+  program2.command("list-metadata-keys").description("List all metadata keys with document counts and example values.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action19);
 }
 
 // src/cli/commands/list-projects.ts
 init_cli_core();
 init_client();
-async function action19(options) {
+async function action20(options) {
   const client = getClient();
   const { data, error: error2 } = await client.raw.from("cerefox_projects").select("id, name, description, created_at").order("name", { ascending: true });
   if (error2) {
@@ -47626,13 +47685,13 @@ async function action19(options) {
   })), "(no projects)");
 }
 function registerListProjects(program2) {
-  program2.command("list-projects").description("List all projects in the knowledge base.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action19);
+  program2.command("list-projects").description("List all projects in the knowledge base.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action20);
 }
 
 // src/cli/commands/list-versions.ts
 init_cli_core();
 init_client();
-async function action20(documentId, options) {
+async function action21(documentId, options) {
   const client = getClient();
   const data = await client.rpc("cerefox_list_document_versions", {
     p_document_id: documentId
@@ -47673,7 +47732,7 @@ async function action20(documentId, options) {
   })));
 }
 function registerListVersions(program2) {
-  program2.command("list-versions").description("List archived versions of a document.").argument("<document-id>", "UUID of the document.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action20);
+  program2.command("list-versions").description("List archived versions of a document.").argument("<document-id>", "UUID of the document.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action21);
 }
 
 // src/cli/commands/mcp.ts
@@ -47688,7 +47747,7 @@ function registerMcp(program2) {
 // src/cli/commands/metadata-search.ts
 init_cli_core();
 init_client();
-async function action21(options) {
+async function action22(options) {
   const metadataFilter = parseJsonObjectArg(options.metadataFilter, "--metadata-filter");
   if (!metadataFilter || Object.keys(metadataFilter).length === 0) {
     throw userError("--metadata-filter is required and must be a non-empty JSON object.", `Example: --metadata-filter '{"type":"decision-log"}'.`);
@@ -47751,7 +47810,7 @@ async function action21(options) {
   }
 }
 function registerMetadataSearch(program2) {
-  program2.command("metadata-search").description("Find documents by metadata criteria (no text query).").requiredOption("-f, --metadata-filter <json>", "JSON object; only docs whose metadata contains ALL pairs are returned.").option("-p, --project-name <name>", "Filter to a specific project.").option("--updated-since <iso>", "Only docs updated on/after this ISO timestamp.").option("--created-since <iso>", "Only docs created on/after this ISO timestamp.").option("--include-content", "Include full document text in results.").option("-l, --limit <n>", "Maximum docs to return.", "10").option("--max-bytes <n>", "Response size budget in bytes (with --include-content).", "200000").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action21);
+  program2.command("metadata-search").description("Find documents by metadata criteria (no text query).").requiredOption("-f, --metadata-filter <json>", "JSON object; only docs whose metadata contains ALL pairs are returned.").option("-p, --project-name <name>", "Filter to a specific project.").option("--updated-since <iso>", "Only docs updated on/after this ISO timestamp.").option("--created-since <iso>", "Only docs created on/after this ISO timestamp.").option("--include-content", "Include full document text in results.").option("-l, --limit <n>", "Maximum docs to return.", "10").option("--max-bytes <n>", "Response size budget in bytes (with --include-content).", "200000").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action22);
 }
 
 // src/cli/commands/reindex.ts
@@ -47759,7 +47818,7 @@ init_dist4();
 init_cli_core();
 init_config();
 var DEFAULT_MODEL = "text-embedding-3-small";
-async function action22(options) {
+async function action23(options) {
   const settings = loadSettings();
   if (!settings.supabaseUrl || !settings.supabaseKey) {
     throw userError("Supabase credentials not configured — run `cerefox init` first.");
@@ -47838,7 +47897,7 @@ ${c2.content}`;
   }
 }
 function registerReindex(program2) {
-  program2.command("reindex").description("Re-embed existing document chunks (v0.7+).").option("--all", "Reindex every chunk regardless of embedder.").option("--batch <n>", "Chunks per OpenAI batch call. Capped at 96 internally.", "32").option("--dry-run", "Show counts without re-embedding.").option("-i, --document-id <uuid>", "Limit reindex to a single document.").action(action22);
+  program2.command("reindex").description("Re-embed existing document chunks (v0.7+).").option("--all", "Reindex every chunk regardless of embedder.").option("--batch <n>", "Chunks per OpenAI batch call. Capped at 96 internally.", "32").option("--dry-run", "Show counts without re-embedding.").option("-i, --document-id <uuid>", "Limit reindex to a single document.").action(action23);
 }
 
 // src/cli/commands/restore.ts
@@ -47868,7 +47927,7 @@ function resolveBackupFile(target) {
   }
   return join10(path, candidates[0].name);
 }
-async function action23(target, options) {
+async function action24(target, options) {
   const file = resolveBackupFile(target);
   let payload;
   try {
@@ -47924,7 +47983,7 @@ async function action23(target, options) {
   }
 }
 function registerRestore(program2) {
-  program2.command("restore").description("Restore a JSON-snapshot backup into the knowledge base.").argument("<snapshot>", "Backup file (or directory; most recent is picked) produced by `cerefox backup`.").option("--dry-run", "Print what would be restored without writing.").option("-p, --project-name <name>", "Reserved for future use; currently ignored (project memberships ride along with each doc's metadata).").action(action23);
+  program2.command("restore").description("Restore a JSON-snapshot backup into the knowledge base.").argument("<snapshot>", "Backup file (or directory; most recent is picked) produced by `cerefox backup`.").option("--dry-run", "Print what would be restored without writing.").option("-p, --project-name <name>", "Reserved for future use; currently ignored (project memberships ride along with each doc's metadata).").action(action24);
 }
 
 // src/cli/commands/search.ts
@@ -47949,7 +48008,7 @@ async function embedQuery(query) {
 }
 
 // src/cli/commands/search.ts
-async function action24(query, options) {
+async function action25(query, options) {
   if (!query || query.trim() === "") {
     throw userError("Empty query.");
   }
@@ -48083,7 +48142,7 @@ async function action24(query, options) {
   }
 }
 function registerSearch(program2) {
-  program2.command("search").description("Search the knowledge base (hybrid FTS + semantic).").argument("<query>", "Natural-language search query.").option("-c, --match-count <n>", "Maximum number of documents to return.", "5").option("-p, --project-name <name>", "Filter results to a specific project.").option("-f, --metadata-filter <json>", "JSON containment filter; only docs whose metadata contains ALL pairs are returned.").option("--mode <mode>", "Search mode: docs (default), hybrid, fts.", "docs").option("--alpha <float>", "Semantic weight 0..1 (default: 0.7).", "0.7").option("--min-score <float>", "Minimum cosine similarity threshold.", "0.5").option("--max-bytes <n>", "Response size budget in bytes.", "200000").option("-r, --requestor <name>", "Agent / user name (recorded in usage log).").option("--json", "Emit machine-readable JSON instead of the default text.").action(action24);
+  program2.command("search").description("Search the knowledge base (hybrid FTS + semantic).").argument("<query>", "Natural-language search query.").option("-c, --match-count <n>", "Maximum number of documents to return.", "5").option("-p, --project-name <name>", "Filter results to a specific project.").option("-f, --metadata-filter <json>", "JSON containment filter; only docs whose metadata contains ALL pairs are returned.").option("--mode <mode>", "Search mode: docs (default), hybrid, fts.", "docs").option("--alpha <float>", "Semantic weight 0..1 (default: 0.7).", "0.7").option("--min-score <float>", "Minimum cosine similarity threshold.", "0.5").option("--max-bytes <n>", "Response size budget in bytes.", "200000").option("-r, --requestor <name>", "Agent / user name (recorded in usage log).").option("--json", "Emit machine-readable JSON instead of the default text.").action(action25);
 }
 
 // src/cli/commands/self-update.ts
@@ -48130,7 +48189,7 @@ async function fetchLatestVersion() {
   }
   return body.version;
 }
-async function action25(options) {
+async function action26(options) {
   let target;
   try {
     target = options.version ?? await fetchLatestVersion();
@@ -48182,7 +48241,7 @@ async function action25(options) {
 }
 function registerSelfUpdate(program2) {
   const desc = "Upgrade Cerefox in place. Alias: `cerefox upgrade`.";
-  const declaration = (cmd) => cmd.description(desc).option("--check", "Print current vs latest; do nothing.").option("--yes", "Non-interactive (skip confirmation).").option("--version <version>", "Pin a specific version (e.g. 0.5.1 or 0.6.0-rc.1).").action(action25);
+  const declaration = (cmd) => cmd.description(desc).option("--check", "Print current vs latest; do nothing.").option("--yes", "Non-interactive (skip confirmation).").option("--version <version>", "Pin a specific version (e.g. 0.5.1 or 0.6.0-rc.1).").action(action26);
   declaration(program2.command("self-update"));
   declaration(program2.command("upgrade"));
 }
@@ -48201,7 +48260,7 @@ function symbol2(status) {
       return cErr.dim("ℹ");
   }
 }
-async function action26(options) {
+async function action27(options) {
   const useSpinner = !options.json && process.stderr.isTTY;
   const spinner = useSpinner ? ora({ text: "Starting checks…", spinner: "dots", stream: process.stderr }).start() : null;
   const results = await runFastChecks({
@@ -48222,7 +48281,7 @@ async function action26(options) {
   }
 }
 function registerStatus(program2) {
-  program2.command("status").description("Quick sanity check (fast subset of `cerefox doctor`).").option("--json", "Emit machine-readable JSON.").action(action26);
+  program2.command("status").description("Quick sanity check (fast subset of `cerefox doctor`).").option("--json", "Emit machine-readable JSON.").action(action27);
 }
 
 // src/cli/commands/sync-docs.ts
@@ -48258,7 +48317,7 @@ function walkMarkdown(dir) {
   }
   return out;
 }
-async function action27(options) {
+async function action28(options) {
   const cwd = process.cwd();
   const project = options.project ?? "cerefox";
   const targets = [];
@@ -48320,7 +48379,7 @@ async function action27(options) {
   }
 }
 function registerSyncDocs(program2) {
-  program2.command("sync-docs").description("Sync repo docs (README, AGENT_*, docs/) into a Cerefox project.").option("--dry-run", "Print what would be synced without writing.").option("-p, --project <name>", "Target project for the sync.", "cerefox").action(action27);
+  program2.command("sync-docs").description("Sync repo docs (README, AGENT_*, docs/) into a Cerefox project.").option("--dry-run", "Print what would be synced without writing.").option("-p, --project <name>", "Target project for the sync.", "cerefox").action(action28);
 }
 
 // src/cli/program.ts
@@ -53313,15 +53372,56 @@ function registerWeb(program2) {
 }
 
 // src/cli/program.ts
+function moveInto(parent, register, newName) {
+  register(parent);
+  const cmd = parent.commands[parent.commands.length - 1];
+  cmd.name(newName);
+  return cmd;
+}
+var RENAMED_VERBS = [
+  ["get-doc", "document get"],
+  ["list-docs", "document list"],
+  ["delete-doc", "document delete"],
+  ["ingest", "document ingest"],
+  ["ingest-dir", "document ingest-dir"],
+  ["list-projects", "project list"],
+  ["delete-project", "project delete"],
+  ["list-versions", "version list"],
+  ["get-audit-log", "audit list"],
+  ["list-metadata-keys", "metadata keys"],
+  ["metadata-search", "metadata search"],
+  ["config-get", "config get"],
+  ["config-set", "config set"],
+  ["restore", "backup restore"],
+  ["deploy-server", "server deploy"],
+  ["reindex", "server reindex"]
+];
+function registerRenameHusks(program2) {
+  for (const [oldName, newForm] of RENAMED_VERBS) {
+    program2.command(oldName, { hidden: true }).allowUnknownOption(true).allowExcessArguments(true).argument("[args...]", "(renamed)").action(() => {
+      eprintln(c.yellow(`✗ \`cerefox ${oldName}\` was renamed in v0.9.0.`));
+      eprintln(`  Use \`cerefox ${newForm}\` instead (run \`cerefox ${newForm.split(" ")[0]} --help\`).`);
+      process.exit(1);
+    });
+  }
+}
 function buildProgram() {
-  const program2 = new Command("cerefox").description("Cerefox — user-owned shared memory for AI agents.").version(PKG_VERSION, "-v, --version", "Print the cerefox version and exit.").addOption(new Option("--json", "Emit machine-readable JSON on stdout instead of the default human text. " + "Available on read commands; ignored on commands without a JSON shape.").hideHelp()).showHelpAfterError("(run `cerefox --help` for usage)").enablePositionalOptions().addHelpText("after", `
-Command groups (each row in the list above falls into one):
-` + `  READS      search · get-doc · list-docs · list-versions · list-projects
-` + `             · list-metadata-keys · metadata-search · get-audit-log
-` + `  WRITES     ingest · ingest-dir · delete-doc · delete-project
-` + `  SERVERS    mcp · web
-` + `  LIFECYCLE  init · doctor · status · configure-agent · self-update · upgrade · sync-self-docs · deploy-server
-` + `  OPS        backup · restore · sync-docs · docs · reindex · config-get · config-set · completion
+  const program2 = new Command("cerefox").description("Cerefox — user-owned shared memory for AI agents.").version(PKG_VERSION, "-v, --version", "Print the cerefox version and exit.").addOption(new Option("--json", "Emit machine-readable JSON on stdout instead of the default human text. " + "Available on read commands; ignored on commands without a JSON shape.").hideHelp()).showHelpAfterError("(run `cerefox --help` for usage)").enablePositionalOptions().addHelpText("after", "\nResource groups (run `cerefox <group> --help`):\n" + `  document   get · list · delete · ingest · ingest-dir
+` + `  project    list · delete
+` + `  version    list
+` + `  metadata   keys · search
+` + `  audit      list
+` + `  config     get · set
+` + `  backup     create · restore
+` + `  server     deploy · reindex
+` + `
+Top-level commands:
+` + `  search · init · doctor · status · configure-agent · self-update
+` + `  mcp · web · docs · completion · sync-docs · sync-self-docs
+` + `
+Renamed in v0.9.0: the old flat verbs (get-doc, list-docs, ingest, …)
+` + `  now live under the groups above. The old names still run but exit with
+` + `  a pointer to the new form. They are removed in v1.0.
 ` + `
 Exit codes:
 ` + `  0  success            2  system error (unreachable Supabase, RPC failure, …)
@@ -53333,34 +53433,49 @@ Learn more:
 ` + `  https://github.com/fstamatelopoulos/cerefox
 `);
   registerSearch(program2);
-  registerGetDoc(program2);
-  registerListDocs(program2);
-  registerListVersions(program2);
-  registerListProjects(program2);
-  registerListMetadataKeys(program2);
-  registerMetadataSearch(program2);
-  registerGetAuditLog(program2);
-  registerIngest(program2);
-  registerIngestDir(program2);
-  registerDeleteDoc(program2);
-  registerDeleteProject(program2);
-  registerMcp(program2);
-  registerWeb(program2);
   registerInit(program2);
   registerDoctor(program2);
   registerStatus(program2);
   registerConfigureAgent(program2);
   registerSelfUpdate(program2);
-  registerSyncSelfDocs(program2);
-  registerDeployServer(program2);
-  registerBackup(program2);
-  registerRestore(program2);
-  registerSyncDocs(program2);
+  registerMcp(program2);
+  registerWeb(program2);
   registerDocs(program2);
-  registerReindex(program2);
-  registerConfigGet(program2);
-  registerConfigSet(program2);
   registerCompletion(program2);
+  registerSyncDocs(program2);
+  registerSyncSelfDocs(program2);
+  const document2 = program2.command("document").description("Documents: get, list, delete, ingest.");
+  moveInto(document2, registerGetDoc, "get");
+  moveInto(document2, registerListDocs, "list");
+  moveInto(document2, registerDeleteDoc, "delete");
+  registerDocumentRestore(document2);
+  moveInto(document2, registerIngest, "ingest");
+  moveInto(document2, registerIngestDir, "ingest-dir");
+  const project = program2.command("project").description("Projects: list, delete.");
+  moveInto(project, registerListProjects, "list");
+  moveInto(project, registerDeleteProject, "delete");
+  const version4 = program2.command("version").description("Document version history: list, archive, unarchive.");
+  moveInto(version4, registerListVersions, "list");
+  registerVersionArchive(version4);
+  const metadata = program2.command("metadata").description("Metadata: keys, search.");
+  moveInto(metadata, registerListMetadataKeys, "keys");
+  moveInto(metadata, registerMetadataSearch, "search");
+  const audit = program2.command("audit").description("Audit log: list.");
+  moveInto(audit, registerGetAuditLog, "list");
+  const config2 = program2.command("config").description("Runtime config: get, set.");
+  moveInto(config2, registerConfigGet, "get");
+  moveInto(config2, registerConfigSet, "set");
+  const backup = program2.command("backup").description("Backup + restore the knowledge base: create, restore.").action(() => {
+    eprintln(c.yellow("`cerefox backup` needs a subcommand."));
+    eprintln("  Use `cerefox backup create` or `cerefox backup restore`.");
+    process.exit(1);
+  });
+  moveInto(backup, registerBackup, "create");
+  moveInto(backup, registerRestore, "restore");
+  const server = program2.command("server").description("Server side: deploy, reindex.");
+  moveInto(server, registerDeployServer, "deploy");
+  moveInto(server, registerReindex, "reindex");
+  registerRenameHusks(program2);
   return program2;
 }
 

package/docs/guides/access-paths.md

@@ -177,7 +177,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 delete-doc`; 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; Python; **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
@@ -210,7 +210,7 @@ clear before the operation actually runs).
 
 If you're building tooling that uses the CLI (Path C) or any MCP/Edge Function path:
 
-- **Use `cerefox delete-doc` freely** to soft-delete agent-authored content. Pair it
+- **Use `cerefox document delete` freely** to soft-delete agent-authored content. Pair it
   with `--author <name> --author-type agent` so the audit trail is correct.
 - **Surface the soft-delete to the user.** When your agent decides to delete something,
   tell the user explicitly: "I soft-deleted X (recoverable from the Cerefox trash in
@@ -221,13 +221,13 @@ If you're building tooling that uses the CLI (Path C) or any MCP/Edge Function p
 
 ### CLI delete-doc — interactive vs scripted
 
-`cerefox delete-doc` prompts for confirmation by default (since `click.confirm` requires
+`cerefox document delete` prompts for confirmation by default (since `click.confirm` requires
 a TTY, an agent's Bash tool will get an abort instead of accidentally deleting). Agents
 that legitimately need to soft-delete must pass `--yes` *and* set `--author` /
 `--author-type` so the audit log captures who acted:
 
 ```bash
-cerefox delete-doc <doc-id> --yes \
+cerefox document delete <doc-id> --yes \
   --author "claude-code" --author-type "agent"
 ```
 

package/docs/guides/cli.md

@@ -16,14 +16,14 @@ Invoke any command with `uv run cerefox <subcommand>`. Inside an activated venv,
 
 ## Commands
 
-### `cerefox ingest`
+### `cerefox document ingest`
 
 **Purpose**: ingest a markdown / PDF / DOCX file (or stdin) into the knowledge base.
 
 **Synopsis**:
 ```
-cerefox ingest [OPTIONS] [PATH]
-cerefox ingest --paste --title "<title>" [OPTIONS]   # stdin
+cerefox document ingest [OPTIONS] [PATH]
+cerefox document ingest --paste --title "<title>" [OPTIONS]   # stdin
 ```
 
 **Options**:
@@ -45,18 +45,18 @@ cerefox ingest --paste --title "<title>" [OPTIONS]   # stdin
 **Examples**:
 ```bash
 # Minimal: ingest a file
-cerefox ingest notes.md
+cerefox document ingest notes.md
 
 # Paste from stdin
-printf '# Title\n\nbody' | cerefox ingest --paste --title "Title"
+printf '# Title\n\nbody' | cerefox document ingest --paste --title "Title"
 
 # Agent ingestion with full attribution
-cerefox ingest notes.md \
+cerefox document ingest notes.md \
   --author "claude-code" --author-type "agent" \
   --project-name "research" --metadata '{"type":"design-doc"}'
 
 # Deterministic update (preferred — agents should search → grab ID → ingest)
-cerefox ingest --paste --title "Same Title" \
+cerefox document ingest --paste --title "Same Title" \
   --document-id "abc12345-..." \
   --author "claude-code" --author-type "agent"
 ```
@@ -69,13 +69,13 @@ cerefox ingest --paste --title "Same Title" \
 
 ---
 
-### `cerefox ingest-dir`
+### `cerefox document ingest-dir`
 
 **Purpose**: bulk-ingest every matching file in a directory.
 
 **Synopsis**:
 ```
-cerefox ingest-dir [OPTIONS] DIRECTORY
+cerefox document ingest-dir [OPTIONS] DIRECTORY
 ```
 
 **Options**:
@@ -94,11 +94,11 @@ cerefox ingest-dir [OPTIONS] DIRECTORY
 **Examples**:
 ```bash
 # Bulk import research notes with shared metadata
-cerefox ingest-dir ./research-notes --recursive \
+cerefox document ingest-dir ./research-notes --recursive \
   --project-name "research" --metadata '{"type":"research","status":"active"}'
 
 # Re-ingest after editing files
-cerefox ingest-dir ./notes --update-if-exists
+cerefox document ingest-dir ./notes --update-if-exists
 ```
 
 **Output**: one line per file showing `✓` (ingested), `↑` (updated), `⏭` (skipped: hash match), or `❌` (error); summary at the end.
@@ -143,27 +143,27 @@ cerefox search "what we tried" --mode semantic --requestor "claude-code"
 
 ---
 
-### `cerefox get-doc`
+### `cerefox document get`
 
 **Purpose**: print the full markdown content of a document to stdout.
 
 **Synopsis**:
 ```
-cerefox get-doc [OPTIONS] DOCUMENT_ID
+cerefox document get [OPTIONS] DOCUMENT_ID
 ```
 
 **Options**:
 
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `--version-id TEXT` (alias: `--version`) | UUID | _none_ (current) | Archived version UUID — get from `cerefox list-versions`. |
+| `--version-id TEXT` (alias: `--version`) | UUID | _none_ (current) | Archived version UUID — get from `cerefox version list`. |
 | `--requestor TEXT` | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
 
 **Examples**:
 ```bash
-cerefox get-doc abc12345-...
-cerefox get-doc abc12345-... --version-id <version-uuid>     # archived
-cerefox get-doc abc12345-... | bat -l md                  # pipe to viewer
+cerefox document get abc12345-...
+cerefox document get abc12345-... --version-id <version-uuid>     # archived
+cerefox document get abc12345-... | bat -l md                  # pipe to viewer
 ```
 
 **Output**: title + metadata line, blank line, then raw markdown.
@@ -172,13 +172,13 @@ cerefox get-doc abc12345-... | bat -l md                  # pipe to viewer
 
 ---
 
-### `cerefox list-docs`
+### `cerefox document list`
 
 **Purpose**: list documents in the knowledge base.
 
 **Synopsis**:
 ```
-cerefox list-docs [OPTIONS]
+cerefox document list [OPTIONS]
 ```
 
 **Options**:
@@ -192,13 +192,13 @@ cerefox list-docs [OPTIONS]
 
 ---
 
-### `cerefox list-versions`
+### `cerefox version list`
 
 **Purpose**: list all archived versions of a document.
 
 **Synopsis**:
 ```
-cerefox list-versions [OPTIONS] DOCUMENT_ID
+cerefox version list [OPTIONS] DOCUMENT_ID
 ```
 
 **Options**:
@@ -207,19 +207,19 @@ cerefox list-versions [OPTIONS] DOCUMENT_ID
 |---|---|---|---|
 | `--requestor TEXT` | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
 
-**Output**: table with version number, created timestamp, source, chunk/char counts, and version UUID. Pass the UUID to `cerefox get-doc --version-id <uuid>` to retrieve the archived content.
+**Output**: table with version number, created timestamp, source, chunk/char counts, and version UUID. Pass the UUID to `cerefox document get --version-id <uuid>` to retrieve the archived content.
 
 **MCP equivalent**: [`cerefox_list_versions`](../../AGENT_GUIDE.md).
 
 ---
 
-### `cerefox list-projects`
+### `cerefox project list`
 
 **Purpose**: list all projects.
 
 **Synopsis**:
 ```
-cerefox list-projects [OPTIONS]
+cerefox project list [OPTIONS]
 ```
 
 **Options**:
@@ -232,23 +232,23 @@ cerefox list-projects [OPTIONS]
 
 ---
 
-### `cerefox list-metadata-keys`
+### `cerefox metadata keys`
 
 **Purpose**: discover metadata keys used across all documents (with example values and document counts).
 
-**Synopsis**: `cerefox list-metadata-keys`
+**Synopsis**: `cerefox metadata keys`
 
 **MCP equivalent**: [`cerefox_list_metadata_keys`](../../AGENT_GUIDE.md).
 
 ---
 
-### `cerefox metadata-search`
+### `cerefox metadata search`
 
 **Purpose**: find documents by metadata key-value criteria (no text query needed).
 
 **Synopsis**:
 ```
-cerefox metadata-search --metadata-filter '<json>' [OPTIONS]
+cerefox metadata search --metadata-filter '<json>' [OPTIONS]
 ```
 
 **Options**:
@@ -265,21 +265,21 @@ cerefox metadata-search --metadata-filter '<json>' [OPTIONS]
 
 **Examples**:
 ```bash
-cerefox metadata-search --metadata-filter '{"type":"decision-log"}' --updated-since 2026-05-01
-cerefox metadata-search --metadata-filter '{"status":"active"}' --project-name "research" --include-content
+cerefox metadata search --metadata-filter '{"type":"decision-log"}' --updated-since 2026-05-01
+cerefox metadata search --metadata-filter '{"status":"active"}' --project-name "research" --include-content
 ```
 
 **MCP equivalent**: [`cerefox_metadata_search`](../../AGENT_GUIDE.md).
 
 ---
 
-### `cerefox get-audit-log`
+### `cerefox audit list`
 
 **Purpose**: query the immutable audit log (who changed what, when).
 
 **Synopsis**:
 ```
-cerefox get-audit-log [OPTIONS]
+cerefox audit list [OPTIONS]
 ```
 
 **Options**:
@@ -298,24 +298,24 @@ cerefox get-audit-log [OPTIONS]
 **Examples**:
 ```bash
 # All audit entries in the last week
-cerefox get-audit-log --since 2026-05-11
+cerefox audit list --since 2026-05-11
 
 # All edits by a specific agent
-cerefox get-audit-log --author "claude-code" --operation update-content
+cerefox audit list --author "claude-code" --operation update-content
 
 # JSON output, piped to jq
-cerefox get-audit-log --json --limit 1000 | jq 'select(.author_type == "agent")'
+cerefox audit list --json --limit 1000 | jq 'select(.author_type == "agent")'
 ```
 
 **MCP equivalent**: [`cerefox_get_audit_log`](../../AGENT_GUIDE.md).
 
 ---
 
-### `cerefox delete-doc`
+### `cerefox document delete`
 
 **Purpose**: **soft-delete** a document — moves it to trash, recoverable. The CLI cannot permanently delete or restore; see [Destructive operations and the trust model](access-paths.md#destructive-operations-and-the-trust-model) for the rationale.
 
-**Synopsis**: `cerefox delete-doc [OPTIONS] DOCUMENT_ID`
+**Synopsis**: `cerefox document delete [OPTIONS] DOCUMENT_ID`
 
 **Options**:
 
@@ -327,7 +327,7 @@ cerefox get-audit-log --json --limit 1000 | jq 'select(.author_type == "agent")'
 
 **What this command does:**
 - Sets `deleted_at` on the document row. The document stays in the database.
-- Excludes the document from search and from `cerefox list-docs`.
+- Excludes the document from search and from `cerefox document list`.
 - Writes an immutable `delete` audit-log entry with the resolved author / author_type and timestamp.
 
 **What this command does NOT do:**
@@ -340,7 +340,7 @@ cerefox get-audit-log --json --limit 1000 | jq 'select(.author_type == "agent")'
 **Agent usage**:
 ```bash
 # Required: --yes (no TTY for confirmation) + identity flags
-cerefox delete-doc <doc-id> --yes \
+cerefox document delete <doc-id> --yes \
   --author "claude-code" --author-type "agent"
 ```
 The success message echoes the resolved author / author_type back so you can surface it to the user in your response.
@@ -349,11 +349,11 @@ The success message echoes the resolved author / author_type back so you can sur
 
 ---
 
-### `cerefox reindex`
+### `cerefox server reindex`
 
 **Purpose**: re-embed chunks (e.g. after switching embedding models or pulling a schema change like title-boosting).
 
-**Synopsis**: `cerefox reindex [OPTIONS]`
+**Synopsis**: `cerefox server reindex [OPTIONS]`
 
 **Options**:
 
@@ -365,14 +365,14 @@ The success message echoes the resolved author / author_type back so you can sur
 
 ---
 
-### `cerefox config-get` / `cerefox config-set`
+### `cerefox config get` / `cerefox config set`
 
 **Purpose**: read/write runtime config in `cerefox_config` (e.g. `usage_tracking_enabled`).
 
 **Synopsis**:
 ```
-cerefox config-get KEY
-cerefox config-set KEY VALUE
+cerefox config get KEY
+cerefox config set KEY VALUE
 ```
 
 Used for toggling features at runtime without a redeploy — see [Decision Log Q1 Part 2 — usage tracking opt-in](https://github.com/fstamatelopoulos/cerefox) entry.
@@ -436,14 +436,14 @@ Every MCP parameter has an exact-name CLI flag (kebab-cased). Short forms exist
 | MCP tool | CLI command |
 |---|---|
 | `cerefox_search(query, match_count, project_name, metadata_filter, requestor)` | `cerefox search "<q>" --match-count N --project-name <name> --metadata-filter '<json>' --requestor <name>` |
-| `cerefox_ingest(title, content, project_name, metadata, update_if_exists, document_id, source, author, author_type)` (file) | `cerefox ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --source <s> --author <a> --author-type <t>` |
-| `cerefox_ingest(...)` (paste) | `printf '...' \| cerefox ingest --paste --title "<t>"` (same flags) |
-| `cerefox_get_document(document_id, version_id, requestor)` | `cerefox get-doc <id> --version-id <vid> --requestor <name>` |
-| `cerefox_list_versions(document_id, requestor)` | `cerefox list-versions <id> --requestor <name>` |
-| `cerefox_list_projects(requestor)` | `cerefox list-projects --requestor <name>` |
-| `cerefox_list_metadata_keys()` | `cerefox list-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 get-audit-log --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --requestor <name>` |
+| `cerefox_ingest(title, content, project_name, metadata, update_if_exists, document_id, source, author, author_type)` (file) | `cerefox document ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --source <s> --author <a> --author-type <t>` |
+| `cerefox_ingest(...)` (paste) | `printf '...' \| cerefox document ingest --paste --title "<t>"` (same flags) |
+| `cerefox_get_document(document_id, version_id, requestor)` | `cerefox document get <id> --version-id <vid> --requestor <name>` |
+| `cerefox_list_versions(document_id, requestor)` | `cerefox version list <id> --requestor <name>` |
+| `cerefox_list_projects(requestor)` | `cerefox project list --requestor <name>` |
+| `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>` |
 
 ## Known issues
 
@@ -453,7 +453,7 @@ None outstanding as of v0.1.17 (cerefox#27 — the `cerefox search` NameError
 
 ### Bulk-import a directory with shared metadata
 ```bash
-cerefox ingest-dir ./papers --recursive --pattern '*.pdf' \
+cerefox document ingest-dir ./papers --recursive --pattern '*.pdf' \
   --project-name "literature" \
   --metadata '{"type":"paper","status":"reviewed"}'
 ```
@@ -465,7 +465,7 @@ cerefox search "the OAuth design doc" --match-count 1
 
 # Step 2: copy the id from `Doc: ... (id: <uuid>)` line
 # Step 3: update in place
-printf '%s' "$NEW_CONTENT" | cerefox ingest --paste \
+printf '%s' "$NEW_CONTENT" | cerefox document ingest --paste \
   --title "OAuth 2.1 Design Document" \
   --document-id "<uuid>" \
   --author "claude-code" --author-type "agent"
@@ -474,7 +474,7 @@ printf '%s' "$NEW_CONTENT" | cerefox ingest --paste \
 ### Unattended sync job
 ```bash
 # In a cron job / launchd plist. Set CEREFOX_AUTHOR_NAME=sync-script in env.
-cd /path/to/cerefox && uv run cerefox ingest-dir ~/notes --recursive --update-if-exists
+cd /path/to/cerefox && uv run cerefox document ingest-dir ~/notes --recursive --update-if-exists
 ```
 
 ### Use the CLI from an agent's Bash tool

package/docs/guides/configuration.md

@@ -121,7 +121,7 @@ The `metadata_filter` search parameter (available in all search modes, all acces
 - All key-value pairs must match (AND semantics via PostgreSQL `@>` operator)
 - Uses the existing GIN index on `cerefox_documents.metadata` — no additional schema changes needed
 - `NULL` filter = no restriction (backwards-compatible default)
-- Discover available keys via `cerefox_list_metadata_keys` MCP tool or `cerefox list-metadata-keys` CLI
+- Discover available keys via `cerefox_list_metadata_keys` MCP tool or `cerefox metadata keys` CLI
 
 Access paths:
 - **MCP tool**: `metadata_filter` argument on `cerefox_search`
@@ -209,8 +209,8 @@ Metadata-only updates (same content, different title or project) do **not** crea
 
 To view and retrieve previous versions:
 ```bash
-uv run cerefox list-versions <document-id>
-uv run cerefox get-doc <document-id> --version <version-id>
+uv run cerefox version list <document-id>
+uv run cerefox document get <document-id> --version <version-id>
 ```
 
 ---
@@ -281,7 +281,7 @@ Change `CEREFOX_OPENAI_EMBEDDING_MODEL` and `CEREFOX_OPENAI_EMBEDDING_DIMENSIONS
 ### Step 2 — Re-embed all stored chunks
 
 ```bash
-uv run cerefox reindex
+uv run cerefox server reindex
 ```
 
 This re-embeds every chunk in the database using the model now configured in `.env`.
@@ -351,13 +351,13 @@ This means:
 **Via CLI:**
 ```bash
 # Enable
-cerefox config-set usage_tracking_enabled true
+cerefox config set usage_tracking_enabled true
 
 # Disable
-cerefox config-set usage_tracking_enabled false
+cerefox config set usage_tracking_enabled false
 
 # Check current state
-cerefox config-get usage_tracking_enabled
+cerefox config get usage_tracking_enabled
 ```
 
 **Via REST API:**
@@ -401,7 +401,7 @@ The `access_path` is set by the caller layer (not the end user):
 
 **CLI:**
 ```bash
-cerefox config-get usage_tracking_enabled
+cerefox config get usage_tracking_enabled
 ```
 
 ---
@@ -421,11 +421,11 @@ with a helpful message telling the agent what to provide.
 
 ```bash
 # Require all MCP tool calls to include requestor/author
-cerefox config-set require_requestor_identity true
+cerefox config set require_requestor_identity true
 
 # Optionally override the default naming format (regex)
 # Default: ^[a-zA-Z0-9_:.\- ]+$ (letters, numbers, underscores, colons, dots, hyphens, spaces)
-cerefox config-set requestor_identity_format "^[a-z]+:[a-z]+$"
+cerefox config set requestor_identity_format "^[a-z]+:[a-z]+$"
 ```
 
 ### Format examples
@@ -441,7 +441,7 @@ The format is applied to both `requestor` (read tools) and `author` (ingest).
 ### Disabling enforcement
 
 ```bash
-cerefox config-set require_requestor_identity false
+cerefox config set require_requestor_identity false
 ```
 
 When disabled, the requestor parameter remains optional with the `"mcp-agent"` default.

package/docs/guides/connect-agents.md

@@ -65,7 +65,7 @@ Three top-level paths plus a few special cases:
 
 **For all paths:**
 - Supabase project set up and schema deployed (see `setup-supabase.md`)
-- Some content ingested (`cerefox ingest my-notes.md`)
+- Some content ingested (`cerefox document ingest my-notes.md`)
 
 **For Path A-Local only:**
 - **Recommended (v0.4.0+):** [Node.js ≥20](https://nodejs.org) (for `npx --package=@cerefox/memory cerefox mcp`)
@@ -1177,7 +1177,7 @@ Quick sanity check before pointing an agent at it:
 ```bash
 cd /path/to/cerefox
 uv run cerefox search "any query"
-uv run cerefox list-projects
+uv run cerefox project list
 ```
 
 If both work for you, they'll work for the agent.
@@ -1218,14 +1218,14 @@ The agent docs are written around MCP tool names. **CLI flag names match MCP par
 | MCP tool | CLI command |
 |---|---|
 | `cerefox_search` | `uv run cerefox search "<query>" --match-count N --project-name <n> --metadata-filter '<json>' --requestor <name>` (CLI-only: `--mode`, `--alpha`, `--min-score`) |
-| `cerefox_ingest` (file) | `uv run cerefox ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --source <s> --author <a> --author-type user\|agent` |
-| `cerefox_ingest` (paste) | `printf '...' \| uv run cerefox ingest --paste --title "<title>"` (same flags) |
-| `cerefox_get_document` | `uv run cerefox get-doc <document-id> --version-id <vid> --requestor <name>` |
-| `cerefox_list_versions` | `uv run cerefox list-versions <document-id> --requestor <name>` |
-| `cerefox_list_projects` | `uv run cerefox list-projects --requestor <name>` |
-| `cerefox_list_metadata_keys` | `uv run cerefox list-metadata-keys` |
-| `cerefox_metadata_search` | `uv run cerefox metadata-search --metadata-filter '<json>' --project-name <n> --requestor <name>` |
-| `cerefox_get_audit_log` | `uv run cerefox get-audit-log --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --json --requestor <name>` |
+| `cerefox_ingest` (file) | `uv run cerefox document ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --source <s> --author <a> --author-type user\|agent` |
+| `cerefox_ingest` (paste) | `printf '...' \| uv run cerefox document ingest --paste --title "<title>"` (same flags) |
+| `cerefox_get_document` | `uv run cerefox document get <document-id> --version-id <vid> --requestor <name>` |
+| `cerefox_list_versions` | `uv run cerefox version list <document-id> --requestor <name>` |
+| `cerefox_list_projects` | `uv run cerefox project list --requestor <name>` |
+| `cerefox_list_metadata_keys` | `uv run cerefox metadata keys` |
+| `cerefox_metadata_search` | `uv run cerefox metadata search --metadata-filter '<json>' --project-name <n> --requestor <name>` |
+| `cerefox_get_audit_log` | `uv run cerefox audit list --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --json --requestor <name>` |
 
 ### Path C verification prompts
 
@@ -1235,16 +1235,16 @@ After pointing your agent at the repo, ask it:
 > Expected: agent runs `uv run cerefox search "second brain"` via its Bash tool and reports results.
 
 > "Save a note titled 'Test Note' to Cerefox with the content '# Test\nThis is a Path C test.'"
-> Expected: agent runs `cerefox ingest --paste --title "Test Note"` (or equivalent) and reports the new document ID.
+> Expected: agent runs `cerefox document ingest --paste --title "Test Note"` (or equivalent) and reports the new document ID.
 
 > "List my Cerefox projects."
-> Expected: agent runs `uv run cerefox list-projects`.
+> Expected: agent runs `uv run cerefox project list`.
 
 ### Caveats
 
 - **Privilege level**: the CLI uses the **service-role key** (`CEREFOX_SUPABASE_KEY`), which bypasses Row Level Security. An agent with Bash access has the same full read/write power you do. Only enable Path C for agents you trust to act on your behalf — the same trust level you'd grant Cursor/Claude Code for editing your source code.
 - **Audit attribution**: Path C records `access_path = "cli"` in usage logs, distinct from `"local-mcp"` / `"remote-mcp"`. **Agents must set `--author <name> --author-type agent` on writes and `--requestor <name>` on reads** (or rely on `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` env vars). Without these flags, writes attribute to `"unknown"` / `"user"`, which under-reports agent activity. See the 2026-05-18 Decision Log Q2 entry for the design rationale (`author_type` is caller-declared on ambiguous channels — CLI and Edge Functions — but `access_path` is always derived from the code layer).
-- **Soft-delete is reachable; purge and restore are not** — by design. `cerefox delete-doc` is exposed on the CLI and sends documents to trash with an audit entry. **Permanent purge** (irreversible) and **restore from trash** (un-doing a destructive action) are intentionally web-UI-only and require human-in-the-loop confirmation. If an agent on Path C decides to delete content, it should surface that to the user explicitly so they can review and either restore or commit. See [`access-paths.md` → Destructive operations and the trust model](access-paths.md#destructive-operations-and-the-trust-model) for the full rationale and contributor guidance.
+- **Soft-delete is reachable; purge and restore are not** — by design. `cerefox document delete` is exposed on the CLI and sends documents to trash with an audit entry. **Permanent purge** (irreversible) and **restore from trash** (un-doing a destructive action) are intentionally web-UI-only and require human-in-the-loop confirmation. If an agent on Path C decides to delete content, it should surface that to the user explicitly so they can review and either restore or commit. See [`access-paths.md` → Destructive operations and the trust model](access-paths.md#destructive-operations-and-the-trust-model) for the full rationale and contributor guidance.
 - **Cross-doc links in content you ingest** become clickable when the user views them in the Cerefox web UI. Author them as `[Text](uuid)` (most stable), `[Text](docs/path.md)` (repo files), or `[Text](<Title With Spaces>)` (angle-bracket form — bare spaces break markdown). See [`AGENT_GUIDE.md` → "Writing linkable content"](../../AGENT_GUIDE.md#writing-linkable-content) for the full set of rules.
 - **One repo per machine**: the agent needs your checkout — there's no "Path C without a local clone". If you skip the local install entirely, Path A-Remote or Path B is the only option.
 - **No sandboxing beyond the agent's existing Bash sandbox**: the CLI is just shell. If your agent's tool framework restricts which commands run, allowlist `uv run cerefox …` explicitly.
@@ -1295,7 +1295,7 @@ for hit in resp.results:
 Both paths use the same Postgres RPCs and the same stored embeddings, but embed queries
 independently. If you change the embedding model, **update both paths** before searching:
 
-1. Update `.env` + run `cerefox reindex` (re-embeds stored chunks via Python)
+1. Update `.env` + run `cerefox server reindex` (re-embeds stored chunks via Python)
 2. Update the TypeScript constants in `supabase/functions/*/index.ts` + redeploy Edge Functions
 
 See `docs/guides/configuration.md` → "Changing the embedding model" for the full procedure.

package/docs/guides/operational-cost.md

@@ -100,7 +100,7 @@ If you want to keep costs as low as possible:
   See `docs/guides/configuration.md` for how to switch.
 - **Batch ingest, don't re-ingest**: Cerefox deduplicates by content hash — re-ingesting the
   same file twice costs nothing. Only new or changed content triggers embedding calls.
-- **`cerefox reindex`**: Re-embeds all existing chunks if you switch embedders. Run this once
+- **`cerefox server reindex`**: Re-embeds all existing chunks if you switch embedders. Run this once
   after switching, not repeatedly.
 
 ---

package/docs/guides/ops-scripts.md

@@ -200,7 +200,7 @@ Backups are JSON files with the following structure:
 }
 ```
 
-**Embeddings are included** in backups. This means a restored database is immediately searchable — no `cerefox reindex` required after restore.
+**Embeddings are included** in backups. This means a restored database is immediately searchable — no `cerefox server reindex` required after restore.
 
 The backup directory (`./backup-data/` by default) is gitignored. Back up the backup files separately if you want off-site copies (e.g. copy to cloud storage).
 
@@ -257,15 +257,15 @@ The `cerefox` CLI also provides data management commands:
 
 | Command | Description |
 |---------|-------------|
-| `uv run cerefox ingest FILE` | Ingest a markdown file |
-| `uv run cerefox ingest --paste --title TITLE` | Ingest text from stdin |
+| `uv run cerefox document ingest FILE` | Ingest a markdown file |
+| `uv run cerefox document ingest --paste --title TITLE` | Ingest text from stdin |
 | `uv run cerefox search QUERY` | Search the knowledge base |
-| `uv run cerefox list-docs` | List all documents |
-| `uv run cerefox delete-doc ID` | Delete a document by ID |
-| `uv run cerefox list-projects` | List all projects |
-| `uv run cerefox list-versions ID` | List all archived versions of a document |
-| `uv run cerefox get-doc ID` | Retrieve current content of a document |
-| `uv run cerefox get-doc ID --version VERSION_ID` | Retrieve a specific archived version |
+| `uv run cerefox document list` | List all documents |
+| `uv run cerefox document delete ID` | Delete a document by ID |
+| `uv run cerefox project list` | List all projects |
+| `uv run cerefox version list ID` | List all archived versions of a document |
+| `uv run cerefox document get ID` | Retrieve current content of a document |
+| `uv run cerefox document get ID --version VERSION_ID` | Retrieve a specific archived version |
 | `uv run cerefox web` | Start the web UI |
 
 Run `uv run cerefox --help` or `uv run cerefox COMMAND --help` for details.

package/docs/guides/quickstart.md

@@ -93,8 +93,8 @@ After v0.6.0, `cerefox init` will offer to do this for you.
 
 ## What's next
 
-- **Ingest your notes**: `cerefox ingest my-notes.md`, or
-  `cerefox ingest-dir ./notes/ --recursive`
+- **Ingest your notes**: `cerefox document ingest my-notes.md`, or
+  `cerefox document ingest-dir ./notes/ --recursive`
 - **Search from the CLI**: `cerefox search "your query"`
 - **Discover all commands**: `cerefox --help`
 - **Run the web UI** (Python-only until v0.6): [`setup-local.md`](setup-local.md)

package/docs/guides/setup-local.md

@@ -95,10 +95,10 @@ You should see all tables (cerefox_documents, cerefox_chunks, cerefox_projects)
 
 ```bash
 # Ingest a markdown file
-cerefox ingest my-notes.md --project-name "personal"
+cerefox document ingest my-notes.md --project-name "personal"
 
 # Or paste content from stdin
-echo "# Quick Note\n\nThis is a quick note." | cerefox ingest --paste --title "Quick Note"
+echo "# Quick Note\n\nThis is a quick note." | cerefox document ingest --paste --title "Quick Note"
 ```
 
 Each ingest calls the OpenAI embedding API once per batch of chunks (fast, typically under a second).

package/docs/guides/setup-supabase.md

@@ -227,10 +227,10 @@ appear with a green "Active" status.
 > Supabase compiles them in the cloud. **Docker is not a prerequisite for deploying Cerefox's
 > Edge Functions.** A deploy succeeded as long as each function ends with
 > `Deployed Functions on project …`. This applies to both the manual commands here and
-> `cerefox deploy-server --functions-only`.
+> `cerefox server deploy --functions-only`.
 
 > **Re-deploying after updates**: run the same `npx supabase functions deploy` commands
-> again from the project root, or just `cerefox deploy-server --functions-only` (it deploys
+> again from the project root, or just `cerefox server deploy --functions-only` (it deploys
 > all 9 from the bundled assets). `npx supabase login` only needs to be run once per machine.
 
 ---

package/docs/guides/upgrading.md

@@ -213,7 +213,7 @@ uv run python scripts/reindex_all.py --dry-run
 uv run python scripts/reindex_all.py
 
 # Or run directly via the CLI (same effect)
-uv run cerefox reindex --all
+uv run cerefox server reindex --all
 ```
 
 The reindex is **resumable**: if interrupted, re-running it skips chunks already embedded with the current model. Archived chunks (historical versions) are not reindexed -- they are not searched.
@@ -238,7 +238,7 @@ redeploy RPCs via `db_deploy.py` (step 4) to update the canonical function defin
 
 **Usage tracking is opt-in**: disabled by default. Enable via CLI:
 ```bash
-cerefox config-set usage_tracking_enabled true
+cerefox config set usage_tracking_enabled true
 ```
 Or via the toggle on the Analytics page. When enabled, **all operations** (both reads
 and writes) are logged with operation type, access path, requestor identity, query text,
@@ -290,7 +290,7 @@ MCP clients pick up new tools automatically on the next connection.
 
 ### Upgrading to v0.1.1+ (from v0.1.0)
 
-**Cloud-only embeddings**: Local embedders (mpnet, Ollama) were removed. If you were using a local embedder, switch to OpenAI or Fireworks AI and run `uv run cerefox reindex` to re-embed all chunks.
+**Cloud-only embeddings**: Local embedders (mpnet, Ollama) were removed. If you were using a local embedder, switch to OpenAI or Fireworks AI and run `uv run cerefox server reindex` to re-embed all chunks.
 
 ## AI Agent Integration After Upgrade
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Cerefox — user-owned shared memory for AI agents. The local TypeScript runtime: stdio MCP server in v0.4; CLI binary added in v0.5; in-process web server in v0.6; ingestion pipeline in v0.7.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",