@cerefox/memory 0.8.3 → 0.9.1

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.1";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js
@@ -24628,16 +24628,16 @@ var init_src = __esm(() => {
 });
 
 // src/cli/util/bundled-docs.ts
-import { existsSync as existsSync7, readdirSync as readdirSync3, readFileSync as readFileSync5, statSync } from "node:fs";
-import { dirname as dirname3, join as join6, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync8, readdirSync as readdirSync3, readFileSync as readFileSync6, statSync } from "node:fs";
+import { dirname as dirname3, join as join7, resolve as resolve2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function findPackageRoot() {
   let dir = dirname3(fileURLToPath2(import.meta.url));
   for (let i = 0;i < 10; i++) {
-    const pkgJson = join6(dir, "package.json");
-    if (existsSync7(pkgJson)) {
+    const pkgJson = join7(dir, "package.json");
+    if (existsSync8(pkgJson)) {
       try {
-        const parsed = JSON.parse(readFileSync5(pkgJson, "utf8"));
+        const parsed = JSON.parse(readFileSync6(pkgJson, "utf8"));
         if (parsed.name === "@cerefox/memory")
           return dir;
       } catch {}
@@ -24650,40 +24650,40 @@ function findPackageRoot() {
   return resolve2(dirname3(fileURLToPath2(import.meta.url)), "..", "..", "..");
 }
 function bundledDocsDir() {
-  const inPackage = join6(PACKAGE_ROOT, "docs");
-  if (existsSync7(inPackage))
+  const inPackage = join7(PACKAGE_ROOT, "docs");
+  if (existsSync8(inPackage))
     return inPackage;
   return resolve2(PACKAGE_ROOT, "..", "..", "docs");
 }
 function agentGuidePath() {
   const candidates = [
-    join6(PACKAGE_ROOT, "AGENT_GUIDE.md"),
+    join7(PACKAGE_ROOT, "AGENT_GUIDE.md"),
     resolve2(PACKAGE_ROOT, "..", "..", "AGENT_GUIDE.md")
   ];
   for (const c2 of candidates)
-    if (existsSync7(c2))
+    if (existsSync8(c2))
       return c2;
   return null;
 }
 function agentQuickReferencePath() {
   const candidates = [
-    join6(PACKAGE_ROOT, "AGENT_QUICK_REFERENCE.md"),
+    join7(PACKAGE_ROOT, "AGENT_QUICK_REFERENCE.md"),
     resolve2(PACKAGE_ROOT, "..", "..", "AGENT_QUICK_REFERENCE.md")
   ];
   for (const c2 of candidates)
-    if (existsSync7(c2))
+    if (existsSync8(c2))
       return c2;
   return null;
 }
 function listBundledDocs() {
   const entries = [];
   const docsDir = bundledDocsDir();
-  const guidesDir = join6(docsDir, "guides");
-  if (existsSync7(guidesDir) && statSync(guidesDir).isDirectory()) {
+  const guidesDir = join7(docsDir, "guides");
+  if (existsSync8(guidesDir) && statSync(guidesDir).isDirectory()) {
     for (const name of readdirSync3(guidesDir)) {
       if (!name.endsWith(".md"))
         continue;
-      const full = join6(guidesDir, name);
+      const full = join7(guidesDir, name);
       entries.push({
         topic: name.replace(/\.md$/, ""),
         path: full,
@@ -24712,7 +24712,7 @@ function readBundledDoc(topic) {
   return {
     topic: entry.topic,
     path: entry.path,
-    content: readFileSync5(entry.path, "utf8")
+    content: readFileSync6(entry.path, "utf8")
   };
 }
 var PACKAGE_ROOT;
@@ -25748,7 +25748,7 @@ var init_get_document = __esm(() => {
 });
 
 // ../../_shared/mcp-tools/get-help-content.ts
-var HELP_FULL = '# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **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. From v0.5+ the canonical invocation is plain **`cerefox <subcommand>`** (installed via `npm install -g @cerefox/memory`). The legacy `uv run cerefox <subcommand>` (Python CLI in a Cerefox checkout) still works through v0.7 but emits a deprecation banner.\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`); short forms (`--filter`, `--project`, `--count`, `--update`, `--version`) work as aliases.\n\n| MCP tool | CLI (v0.5+ canonical) |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox ingest --paste --title "<t>" --document-id "<uuid>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox get-doc <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox list-versions <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox list-projects --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox list-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 get-audit-log --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox docs agent-quick-reference --print` (or `cerefox docs --list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`ingest`, `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', HELP_SECTIONS, HELP_SECTION_HEADINGS;
+var 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`); short forms (`--filter`, `--project`, `--count`, `--update`, `--version`) work as aliases.\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', HELP_SECTIONS, HELP_SECTION_HEADINGS;
 var init_get_help_content = __esm(() => {
   HELP_SECTIONS = {
     Tools: "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `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) |",
@@ -25756,7 +25756,7 @@ var init_get_help_content = __esm(() => {
     "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. From v0.5+ the canonical invocation is plain **`cerefox <subcommand>`** (installed via `npm install -g @cerefox/memory`). The legacy `uv run cerefox <subcommand>` (Python CLI in a Cerefox checkout) still works through v0.7 but emits a deprecation banner.\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`); short forms (`--filter`, `--project`, `--count`, `--update`, `--version`) work as aliases.\n\n| MCP tool | CLI (v0.5+ canonical) |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox ingest --paste --title "<t>" --document-id "<uuid>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox get-doc <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox list-versions <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox list-projects --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox list-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 get-audit-log --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox docs agent-quick-reference --print` (or `cerefox docs --list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`ingest`, `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`); short forms (`--filter`, `--project`, `--count`, `--update`, `--version`) work as aliases.\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.'
   };
   HELP_SECTION_HEADINGS = ["Tools", "Essential Rules", "Update Workflow (ID-based -- preferred)", "Update Workflow (title-based -- fallback)", "Catch-Up Workflow", "CLI fallback (when MCP is unavailable)"];
 });
@@ -26758,7 +26758,7 @@ __export(exports_sync_self_docs, {
   runSyncSelfDocs: () => runSyncSelfDocs,
   registerSyncSelfDocs: () => registerSyncSelfDocs
 });
-import { readFileSync as readFileSync9 } from "node:fs";
+import { readFileSync as readFileSync10 } from "node:fs";
 import { basename as basename4, extname as extname4 } from "node:path";
 async function runSyncSelfDocs(options = {}) {
   const project = options.project ?? "_cerefox-self-docs";
@@ -26785,7 +26785,7 @@ async function runSyncSelfDocs(options = {}) {
   const authorType = resolveAuthorType("agent");
   const outcomes = [];
   for (const doc of docs) {
-    const content = readFileSync9(doc.path, "utf8");
+    const content = readFileSync10(doc.path, "utf8");
     const m = content.match(/^#\s+(.+)$/m);
     const title = m ? m[1].trim() : basename4(doc.path, extname4(doc.path));
     try {
@@ -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 action19(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(action19);
 }
 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();
@@ -40001,6 +40002,9 @@ function registerBackup(program2) {
 
 // src/cli/commands/completion.ts
 init_cli_core();
+import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join3 } from "node:path";
 function collectCompletionInfo() {
   const program2 = buildProgram();
   const subcommands = [];
@@ -40092,26 +40096,84 @@ function fishScript(info2) {
 `) + `
 `;
 }
-function action2(shell) {
+function scriptFor(shell) {
   const info2 = collectCompletionInfo();
-  let script;
   switch (shell) {
     case "bash":
-      script = bashScript(info2);
-      break;
+      return bashScript(info2);
     case "zsh":
-      script = zshScript(info2);
-      break;
+      return zshScript(info2);
     case "fish":
-      script = fishScript(info2);
-      break;
-    default:
-      throw userError(`Unknown shell "${shell}". Supported: bash, zsh, fish.`);
+      return fishScript(info2);
+  }
+}
+function detectShell() {
+  const sh = (process.env.SHELL ?? "").split("/").pop() ?? "";
+  if (sh === "bash" || sh === "zsh" || sh === "fish")
+    return sh;
+  return null;
+}
+var RC_BEGIN = "# >>> cerefox shell completion (managed by `cerefox completion install`) >>>";
+var RC_END = "# <<< cerefox shell completion <<<";
+async function installMode(options) {
+  const shell = options.shell ?? detectShell();
+  if (!shell) {
+    throw userError("Could not detect your shell from $SHELL. Pass --shell bash|zsh|fish.");
+  }
+  if (shell !== "bash" && shell !== "zsh" && shell !== "fish") {
+    throw userError(`Unsupported --shell "${shell}". Use bash, zsh, or fish.`);
+  }
+  const home = homedir3();
+  const scriptPath = join3(home, `.cerefox-completion.${shell}`);
+  writeFileSync2(scriptPath, scriptFor(shell), "utf8");
+  println(c.green(`✓ Wrote completion script: ${scriptPath}`));
+  if (shell === "fish") {
+    println(c.dim("  For fish, also copy it into ~/.config/fish/completions/cerefox.fish (or `source` it)."));
+    return;
+  }
+  const rcPath = join3(home, shell === "zsh" ? ".zshrc" : ".bashrc");
+  const sourceLine = `[ -s "${scriptPath}" ] && source "${scriptPath}"`;
+  const block = `${RC_BEGIN}
+${sourceLine}
+${RC_END}
+`;
+  const existing = existsSync3(rcPath) ? readFileSync3(rcPath, "utf8") : "";
+  if (existing.includes(RC_BEGIN)) {
+    println(c.dim(`  ${rcPath} already sources the completion (left as-is).`));
+  } else {
+    const interactive = process.stdout.isTTY && !options.yes;
+    if (interactive) {
+      const ok2 = await confirm(`Add a completion source line to ${rcPath}?`, false);
+      if (!ok2) {
+        println(c.dim(`Skipped the rc edit. Add this line to ${rcPath} yourself:`));
+        println(`  ${sourceLine}`);
+        return;
+      }
+    }
+    writeFileSync2(rcPath, (existing.endsWith(`
+`) || existing === "" ? existing : existing + `
+`) + `
+` + block, "utf8");
+    println(c.green(`✓ Added completion to ${rcPath}.`));
+  }
+  println(c.dim(`  Activate now: exec ${shell}   (or open a new terminal).`));
+}
+async function action2(target, options) {
+  if (target === "install") {
+    await installMode(options);
+    return;
+  }
+  if (target !== "bash" && target !== "zsh" && target !== "fish") {
+    throw userError(`Unknown shell "${target}". Supported: bash, zsh, fish (or 'install').`);
+  }
+  println(scriptFor(target));
+  if (process.stdout.isTTY) {
+    eprintln(c.dim(`
+# Tip: \`cerefox completion install\` writes this + wires your shell rc automatically.`));
   }
-  println(script);
 }
 function registerCompletion(program2) {
-  program2.command("completion").description("Emit a tab-completion script for your shell.").argument("<shell>", "Target shell: bash, zsh, or fish.").action(action2);
+  program2.command("completion").description("Shell tab-completion. `install` to auto-wire your shell, or a shell name to print the script.").argument("<shell>", "bash | zsh | fish (print the script), or 'install' (auto-wire).").option("--shell <shell>", "For 'install': override the auto-detected shell.").option("--yes", "For 'install': skip the rc-edit confirmation (used by install.sh).").action(action2);
 }
 
 // src/cli/commands/config-get.ts
@@ -40144,10 +40206,41 @@ function registerConfigGet(program2) {
   program2.command("config-get").description("Read a runtime config value from the cerefox_config table.").argument("<key>", "Config key (e.g. usage_tracking_enabled).").option("--json", "Emit JSON.").action(action3);
 }
 
+// src/cli/commands/config-list.ts
+init_cli_core();
+var CONFIG_KEYS = [
+  {
+    key: "usage_tracking_enabled",
+    description: "'true'/'false' — log reads + writes to cerefox_usage_log. Default off."
+  },
+  {
+    key: "require_requestor_identity",
+    description: "'true'/'false' — require requestor/author on MCP tool calls. Default off."
+  },
+  {
+    key: "requestor_identity_format",
+    description: "Regex the requestor/author must match (only enforced when the above is on)."
+  }
+];
+function action4(options) {
+  if (options.json) {
+    printJson({ keys: CONFIG_KEYS.map((k) => k.key) });
+    return;
+  }
+  println(c.bold("Runtime config keys (stored in cerefox_config; read with `cerefox config get <key>`):"));
+  for (const { key, description } of CONFIG_KEYS) {
+    println(`  ${c.bold(key)}`);
+    println(c.dim(`    ${description}`));
+  }
+}
+function registerConfigList(parent) {
+  parent.command("list").description("List the runtime config keys (the cerefox_config allow-list; not values).").option("--json", "Emit the key list as JSON.").action(action4);
+}
+
 // src/cli/commands/config-set.ts
 init_cli_core();
 init_client();
-async function action4(key, value) {
+async function action5(key, value) {
   const client = getClient();
   try {
     await client.rpc("cerefox_set_config", { p_key: key, p_value: value });
@@ -40158,7 +40251,7 @@ async function action4(key, value) {
   println(c.green("✓ ") + `${key} = ${value}`);
 }
 function registerConfigSet(program2) {
-  program2.command("config-set").description("Write a runtime config value into the cerefox_config table.").argument("<key>", "Config key.").argument("<value>", "Value to write.").action(action4);
+  program2.command("config-set").description("Write a runtime config value into the cerefox_config table.").argument("<key>", "Config key.").argument("<value>", "Value to write.").action(action5);
 }
 
 // src/cli/commands/configure-agent.ts
@@ -40167,13 +40260,13 @@ init_cli_core();
 // src/cli/util/mcp-config-writers.ts
 import {
   copyFileSync,
-  existsSync as existsSync3,
+  existsSync as existsSync4,
   mkdirSync as mkdirSync2,
-  readFileSync as readFileSync3,
-  writeFileSync as writeFileSync2
+  readFileSync as readFileSync4,
+  writeFileSync as writeFileSync3
 } from "node:fs";
-import { homedir as homedir3, platform } from "node:os";
-import { dirname, join as join3 } from "node:path";
+import { homedir as homedir4, platform } from "node:os";
+import { dirname, join as join4 } from "node:path";
 import { spawnSync } from "node:child_process";
 
 // ../../node_modules/.bun/smol-toml@1.6.1/node_modules/smol-toml/dist/error.js
@@ -41275,17 +41368,17 @@ function defaultCerefoxEntry() {
   };
 }
 function claudeCodeUserConfigPath() {
-  return join3(homedir3(), ".claude.json");
+  return join4(homedir4(), ".claude.json");
 }
 function claudeDesktopConfigPath() {
-  const home = homedir3();
+  const home = homedir4();
   if (platform() === "darwin") {
-    return join3(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    return join4(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
   }
   if (platform() === "win32") {
-    return join3(process.env.APPDATA ?? home, "Claude", "claude_desktop_config.json");
+    return join4(process.env.APPDATA ?? home, "Claude", "claude_desktop_config.json");
   }
-  return join3(home, ".config", "Claude", "claude_desktop_config.json");
+  return join4(home, ".config", "Claude", "claude_desktop_config.json");
 }
 function claudeCodeDelegated() {
   const entry = defaultCerefoxEntry();
@@ -41295,13 +41388,13 @@ function claudeCodeDelegated() {
   };
 }
 function cursorConfigPath() {
-  return join3(homedir3(), ".cursor", "mcp.json");
+  return join4(homedir4(), ".cursor", "mcp.json");
 }
 function codexConfigPath() {
-  return join3(homedir3(), ".codex", "config.toml");
+  return join4(homedir4(), ".codex", "config.toml");
 }
 function geminiConfigPath() {
-  return join3(homedir3(), ".gemini", "settings.json");
+  return join4(homedir4(), ".gemini", "settings.json");
 }
 var WRITERS = {
   "claude-code": {
@@ -41359,15 +41452,15 @@ function directWrite(writer, configPath, opts) {
   if (!opts.dryRun)
     mkdirSync2(dirname(configPath), { recursive: true });
   let existing = {};
-  let action5 = "created";
+  let action6 = "created";
   let backupPath = null;
-  if (existsSync3(configPath)) {
+  if (existsSync4(configPath)) {
     try {
-      const raw = readFileSync3(configPath, "utf8");
+      const raw = readFileSync4(configPath, "utf8");
       existing = format === "toml" ? parse(raw) : JSON.parse(raw);
-      action5 = hasCerefoxEntry(existing, format) ? "replaced" : "merged";
+      action6 = hasCerefoxEntry(existing, format) ? "replaced" : "merged";
     } catch {
-      action5 = "replaced";
+      action6 = "replaced";
     }
     if (!opts.noBackup && !opts.dryRun) {
       backupPath = configPath + ".pre-cerefox.bak";
@@ -41382,9 +41475,9 @@ function directWrite(writer, configPath, opts) {
     const body = format === "toml" ? stringify(existing) + `
 ` : JSON.stringify(existing, null, 2) + `
 `;
-    writeFileSync2(configPath, body, "utf8");
+    writeFileSync3(configPath, body, "utf8");
   }
-  return { configPath, backupPath, action: action5, serverEntry: entry };
+  return { configPath, backupPath, action: action6, serverEntry: entry };
 }
 function hasCerefoxEntry(existing, format) {
   const key = format === "toml" ? "mcp_servers" : "mcpServers";
@@ -41408,7 +41501,7 @@ function delegatedWrite(writer, opts) {
     };
   }
   let backupPath = null;
-  if (!opts.noBackup && existsSync3(writer.configPath)) {
+  if (!opts.noBackup && existsSync4(writer.configPath)) {
     backupPath = writer.configPath + ".pre-cerefox.bak";
     copyFileSync(writer.configPath, backupPath);
   }
@@ -41433,7 +41526,7 @@ function delegatedWrite(writer, opts) {
 }
 
 // src/cli/commands/configure-agent.ts
-function action5(options) {
+function action6(options) {
   const writer = WRITERS[options.tool];
   if (!writer) {
     throw userError(`Unknown --tool "${options.tool}".`, `Supported clients: ${Object.keys(WRITERS).join(", ")}.`);
@@ -41485,13 +41578,13 @@ function restartHint(id) {
   }
 }
 function registerConfigureAgent(program2) {
-  program2.command("configure-agent").description("Write the MCP server config for a supported client.").requiredOption("-t, --tool <client>", "Target client: claude-code, claude-desktop, cursor, codex, gemini.").option("--config-path <path>", "Override the default config-file path.").option("--no-backup", "Skip the .pre-cerefox.bak backup of any existing config.").option("--dry-run", "Print the planned write without modifying any file.").option("--json", "Emit JSON describing the result.").action(action5);
+  program2.command("configure-agent").description("Write the MCP server config for a supported client.").requiredOption("-t, --tool <client>", "Target client: claude-code, claude-desktop, cursor, codex, gemini.").option("--config-path <path>", "Override the default config-file path.").option("--no-backup", "Skip the .pre-cerefox.bak backup of any existing config.").option("--dry-run", "Print the planned write without modifying any file.").option("--json", "Emit JSON describing the result.").action(action6);
 }
 
 // src/cli/commands/delete-doc.ts
 init_cli_core();
 init_client();
-async function action6(documentId, options) {
+async function action7(documentId, options) {
   const client = getClient();
   const { data: doc, error } = await client.raw.from("cerefox_documents").select("id, title, total_chars, chunk_count, deleted_at").eq("id", documentId).maybeSingle();
   if (error) {
@@ -41530,14 +41623,14 @@ async function action6(documentId, options) {
   }
 }
 function registerDeleteDoc(program2) {
-  program2.command("delete-doc").description("Soft-delete a document (recoverable via the web UI trash).").argument("<document-id>", "UUID of the document to delete.").option("--reason <text>", "Optional reason recorded in the audit log.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("--yes", "Skip the confirmation prompt.").action(action6);
+  program2.command("delete-doc").description("Soft-delete a document (recoverable via the web UI trash).").argument("<document-id>", "UUID of the document to delete.").option("--reason <text>", "Optional reason recorded in the audit log.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("--yes", "Skip the confirmation prompt.").action(action7);
 }
 
 // src/cli/commands/delete-project.ts
 init_cli_core();
 init_client();
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-async function action7(target, options) {
+async function action8(target, options) {
   const client = getClient();
   const isUuid = UUID_RE.test(target);
   const lookup = isUuid ? client.raw.from("cerefox_projects").select("id, name, description").eq("id", target).maybeSingle() : client.raw.from("cerefox_projects").select("id, name, description").eq("name", target).maybeSingle();
@@ -41573,19 +41666,19 @@ async function action7(target, options) {
   println(c.green(`✓ Deleted project "${project.name}" (id: ${project.id}).`));
 }
 function registerDeleteProject(program2) {
-  program2.command("delete-project").description("Delete an empty project (use --force to remove a non-empty one).").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--yes", "Skip the confirmation prompt.").option("--force", "Allow deletion when documents are still linked to the project.").action(action7);
+  program2.command("delete-project").description("Delete an empty project (use --force to remove a non-empty one).").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--yes", "Skip the confirmation prompt.").option("--force", "Allow deletion when documents are still linked to the project.").action(action8);
 }
 
 // src/cli/commands/deploy-server.ts
 init_cli_core();
 init_config();
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync6 } from "node:fs";
+import { existsSync as existsSync7 } from "node:fs";
 import { readdirSync as readdirSync2 } from "node:fs";
 
 // ../../_shared/server-assets/index.ts
-import { existsSync as existsSync4 } from "node:fs";
-import { dirname as dirname2, join as join4 } from "node:path";
+import { existsSync as existsSync5 } from "node:fs";
+import { dirname as dirname2, join as join5 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { cwd as processCwd2 } from "node:process";
 function moduleDir() {
@@ -41593,25 +41686,25 @@ function moduleDir() {
 }
 function bundledServerAssets(serverAssetsRoot) {
   return {
-    schemaFile: join4(serverAssetsRoot, "db", "schema.sql"),
-    rpcsFile: join4(serverAssetsRoot, "db", "rpcs.sql"),
-    migrationsDir: join4(serverAssetsRoot, "db", "migrations"),
-    functionsDir: join4(serverAssetsRoot, "supabase", "functions"),
+    schemaFile: join5(serverAssetsRoot, "db", "schema.sql"),
+    rpcsFile: join5(serverAssetsRoot, "db", "rpcs.sql"),
+    migrationsDir: join5(serverAssetsRoot, "db", "migrations"),
+    functionsDir: join5(serverAssetsRoot, "supabase", "functions"),
     layout: "bundled"
   };
 }
 function sourceServerAssets(repoRoot) {
-  const dbDir = join4(repoRoot, "src", "cerefox", "db");
+  const dbDir = join5(repoRoot, "src", "cerefox", "db");
   return {
-    schemaFile: join4(dbDir, "schema.sql"),
-    rpcsFile: join4(dbDir, "rpcs.sql"),
-    migrationsDir: join4(dbDir, "migrations"),
-    functionsDir: join4(repoRoot, "supabase", "functions"),
+    schemaFile: join5(dbDir, "schema.sql"),
+    rpcsFile: join5(dbDir, "rpcs.sql"),
+    migrationsDir: join5(dbDir, "migrations"),
+    functionsDir: join5(repoRoot, "supabase", "functions"),
     layout: "source"
   };
 }
 function serverAssetsUsable(p) {
-  return existsSync4(p.schemaFile) && existsSync4(p.rpcsFile);
+  return existsSync5(p.schemaFile) && existsSync5(p.rpcsFile);
 }
 function resolveServerAssets(opts = {}) {
   if (opts.assetsDir) {
@@ -41620,21 +41713,21 @@ function resolveServerAssets(opts = {}) {
   const here = opts.moduleDirOverride ?? moduleDir();
   const cwd = opts.cwd ?? processCwd2();
   const candidates = [
-    bundledServerAssets(join4(here, "..", "server-assets")),
-    sourceServerAssets(join4(here, "..", "..")),
+    bundledServerAssets(join5(here, "..", "server-assets")),
+    sourceServerAssets(join5(here, "..", "..")),
     sourceServerAssets(cwd)
   ];
   for (const candidate of candidates) {
     if (serverAssetsUsable(candidate))
       return candidate;
   }
-  return sourceServerAssets(join4(here, "..", ".."));
+  return sourceServerAssets(join5(here, "..", ".."));
 }
 
 // ../../_shared/db-deploy/index.ts
 init_src();
-import { existsSync as existsSync5, readFileSync as readFileSync4, readdirSync } from "node:fs";
-import { join as join5 } from "node:path";
+import { existsSync as existsSync6, readFileSync as readFileSync5, readdirSync } from "node:fs";
+import { join as join6 } from "node:path";
 var RESET_SQL = `
 DROP TABLE IF EXISTS cerefox_chunks      CASCADE;
 DROP TABLE IF EXISTS cerefox_documents   CASCADE;
@@ -41651,13 +41744,13 @@ CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
 CREATE EXTENSION IF NOT EXISTS "vector";
 `;
 function listMigrationFiles(migrationsDir) {
-  if (!existsSync5(migrationsDir))
+  if (!existsSync6(migrationsDir))
     return [];
   return readdirSync(migrationsDir).filter((n) => n.endsWith(".sql")).sort();
 }
 function buildDeploySteps(assets, opts = {}) {
-  const schemaSql = readFileSync4(assets.schemaFile, "utf8");
-  const rpcsSql = readFileSync4(assets.rpcsFile, "utf8");
+  const schemaSql = readFileSync5(assets.schemaFile, "utf8");
+  const rpcsSql = readFileSync5(assets.rpcsFile, "utf8");
   const steps = [];
   if (opts.reset) {
     steps.push({ label: "Reset: drop existing Cerefox objects", sql: RESET_SQL });
@@ -41750,7 +41843,7 @@ async function runDbMigrate(opts) {
     }
     const applied = [];
     for (const f of pending) {
-      const body = readFileSync4(join5(opts.assets.migrationsDir, f), "utf8");
+      const body = readFileSync5(join6(opts.assets.migrationsDir, f), "utf8");
       log(`Applying ${f}…`);
       try {
         await sql.begin(async (tx) => {
@@ -41778,7 +41871,7 @@ async function applyRpcs(opts) {
   log("Refresh RPCs (rpcs.sql)…");
   if (opts.dryRun)
     return { ok: true };
-  const rpcsSql = readFileSync4(opts.assets.rpcsFile, "utf8");
+  const rpcsSql = readFileSync5(opts.assets.rpcsFile, "utf8");
   const sql = src_default(opts.dbUrl, { prepare: false, onnotice: () => {} });
   try {
     await sql.unsafe(rpcsSql);
@@ -41811,11 +41904,11 @@ function parseProjectRef(supabaseUrl) {
   }
 }
 function listEdgeFunctions(functionsDir) {
-  if (!existsSync6(functionsDir))
+  if (!existsSync7(functionsDir))
     return [];
   return readdirSync2(functionsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name.startsWith("cerefox-")).map((e) => e.name).sort();
 }
-async function action8(options) {
+async function action9(options) {
   const settings = loadSettings();
   const assets = resolveServerAssets();
   const doSchema = !options.functionsOnly;
@@ -41830,7 +41923,7 @@ async function action8(options) {
     });
     checks.push({
       label: "Bundled schema assets present",
-      ok: existsSync6(assets.schemaFile) && existsSync6(assets.rpcsFile),
+      ok: existsSync7(assets.schemaFile) && existsSync7(assets.rpcsFile),
       remediation: "Schema files not found. Reinstall the package, or run from a repo " + "clone (src/cerefox/db/)."
     });
   }
@@ -41998,10 +42091,116 @@ Proceed with deployment to Supabase?`, true);
   println(c.dim("Verify with: cerefox doctor"));
 }
 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);
+  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(action9);
 }
 
-// src/cli/commands/docs.ts
+// src/cli/commands/document-edit.ts
+init_cli_core();
+init_client();
+function parseMetaPair(pair) {
+  const eq = pair.indexOf("=");
+  if (eq <= 0)
+    throw userError(`--set-meta expects key=value, got "${pair}".`);
+  const key = pair.slice(0, eq).trim();
+  const raw = pair.slice(eq + 1);
+  let value = raw;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    value = raw;
+  }
+  return [key, value];
+}
+async function action10(documentId, options) {
+  const hasTitle = options.title !== undefined;
+  const sets = options.setMeta ?? [];
+  const unsets = options.unsetMeta ?? [];
+  if (!hasTitle && sets.length === 0 && unsets.length === 0) {
+    throw userError("Nothing to edit — pass --title and/or --set-meta / --unset-meta.");
+  }
+  if (hasTitle && !options.title.trim())
+    throw userError("--title cannot be empty.");
+  const client = getClient();
+  const { data: doc, error } = await client.raw.from("cerefox_documents").select("id, title, metadata, 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) {
+    throw userError(`Document ${documentId} is soft-deleted — restore it first (cerefox document restore).`);
+  }
+  const metadata = { ...doc.metadata ?? {} };
+  for (const pair of sets) {
+    const [k, v] = parseMetaPair(pair);
+    metadata[k] = v;
+  }
+  for (const k of unsets)
+    delete metadata[k.trim()];
+  const newTitle = hasTitle ? options.title.trim() : doc.title;
+  const titleChanged = newTitle !== doc.title;
+  const { error: updErr } = await client.raw.from("cerefox_documents").update({ title: newTitle, metadata, updated_at: new Date().toISOString() }).eq("id", documentId);
+  if (updErr)
+    throw systemError(`Update failed: ${updErr.message}`);
+  if (titleChanged) {
+    const { error: ftsErr } = await client.raw.rpc("cerefox_update_chunk_fts", {
+      p_document_id: documentId,
+      p_new_title: newTitle
+    });
+    if (ftsErr)
+      throw systemError(`Title updated but FTS refresh failed: ${ftsErr.message}`);
+  }
+  const author = resolveAuthor(options.author);
+  const authorType = resolveAuthorType(options.authorType);
+  await client.raw.rpc("cerefox_create_audit_entry", {
+    p_document_id: documentId,
+    p_operation: "update-metadata",
+    p_author: author,
+    p_author_type: authorType,
+    p_description: `Edited${titleChanged ? " title" : ""}` + (sets.length ? ` · set ${sets.length} meta key(s)` : "") + (unsets.length ? ` · unset ${unsets.length} meta key(s)` : "")
+  });
+  println(c.green(`✓ Edited "${newTitle}" (id: ${documentId}).`));
+  if (titleChanged) {
+    println(c.dim("  Title changed: FTS refreshed; semantic embeddings update on next `cerefox server reindex`."));
+  }
+}
+function collect(value, prev) {
+  return [...prev, value];
+}
+function registerDocumentEdit(parent) {
+  parent.command("edit").description("Edit a document's title and/or metadata (non-destructive patch). Content edits: `document ingest --document-id <id> --update`.").argument("<document-id>", "UUID of the document.").option("--title <title>", "New title (refreshes FTS; re-embed on next reindex).").option("--set-meta <key=value>", "Set/overwrite a metadata key (repeatable). Value is JSON-parsed when possible.", collect, []).option("--unset-meta <key>", "Remove a metadata key (repeatable).", collect, []).option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action10);
+}
+
+// src/cli/commands/document-restore.ts
+init_cli_core();
+init_client();
+async function action11(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(action11);
+}
+
+// src/cli/commands/guides.ts
 init_cli_core();
 init_bundled_docs();
 import { spawnSync as spawnSync3 } from "node:child_process";
@@ -42012,36 +42211,117 @@ function openInBrowser(path) {
     println(c.dim(`(could not auto-open; the file is at: ${path})`));
   }
 }
-function action9(topic, options) {
-  const docs = listBundledDocs();
-  if (options.list || !topic && !options.print) {
-    if (docs.length === 0) {
-      println("(no bundled docs found)");
-      return;
-    }
-    println(c.bold("Available docs:"));
-    println("");
-    printTable(docs.map((d) => ({
-      topic: d.topic,
-      size_kb: Math.round(d.size / 1024) + " KB"
-    })));
-    println("");
-    println(c.dim("Run `cerefox docs <topic>` to open in browser, or `--print` for stdout."));
-    return;
-  }
-  const doc = topic ? readBundledDoc(topic) : null;
+function resolveDoc(topic) {
+  const doc = readBundledDoc(topic);
   if (!doc) {
-    throw notFound(`No bundled doc named "${topic}".`, `Run \`cerefox docs --list\` to see available topics.`);
+    throw notFound(`No bundled guide named "${topic}".`, "Run `cerefox guides list` to see available topics.");
   }
-  if (options.print) {
-    println(doc.content);
+  return doc;
+}
+function listAction() {
+  const docs = listBundledDocs();
+  if (docs.length === 0) {
+    println("(no bundled guides found)");
     return;
   }
+  println(c.bold("Available guides:"));
+  println("");
+  printTable(docs.map((d) => ({ topic: d.topic, size_kb: Math.round(d.size / 1024) + " KB" })));
+  println("");
+  println(c.dim("Open with `cerefox guides open <topic>` (browser) or `cerefox guides show <topic>` (stdout)."));
+}
+function openAction(topic) {
+  const doc = resolveDoc(topic);
   println(c.dim(`Opening ${doc.path} …`));
   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);
+function showAction(topic) {
+  println(resolveDoc(topic).content);
+}
+function registerGuides(parent) {
+  parent.command("list").description("List the bundled documentation topics.").action(listAction);
+  parent.command("open").description("Open a bundled guide in your browser.").argument("<topic>", "Topic (e.g. quickstart, connect-agents).").action(openAction);
+  parent.command("show").description("Print a bundled guide to stdout.").argument("<topic>", "Topic (e.g. quickstart, connect-agents).").action(showAction);
+}
+
+// src/cli/commands/project-create.ts
+init_cli_core();
+init_client();
+async function action12(name, options) {
+  const trimmed = name.trim();
+  if (!trimmed)
+    throw userError("Project name is required.");
+  const client = getClient();
+  const { data, error } = await client.raw.from("cerefox_projects").insert({ name: trimmed, description: (options.description ?? "").trim() }).select("id, name, description").maybeSingle();
+  if (error || !data) {
+    throw systemError(`Create failed: ${error?.message ?? "no row returned"}`);
+  }
+  println(c.green(`✓ Created project "${data.name}" (id: ${data.id}).`));
+}
+function registerProjectCreate(parent) {
+  parent.command("create").description("Create a new (empty) project.").argument("<name>", "Project name (must be unique).").option("--description <text>", "Optional project description.").action(action12);
+}
+
+// src/cli/commands/project-edit.ts
+init_cli_core();
+init_client();
+var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function action13(target, options) {
+  const update = {};
+  if (options.name !== undefined) {
+    const n = options.name.trim();
+    if (!n)
+      throw userError("--name cannot be empty.");
+    update.name = n;
+  }
+  if (options.description !== undefined)
+    update.description = options.description.trim();
+  if (Object.keys(update).length === 0) {
+    throw userError("Nothing to update — pass --name and/or --description.");
+  }
+  const client = getClient();
+  const isUuid = UUID_RE2.test(target);
+  const { data: project, error: lookupErr } = await client.raw.from("cerefox_projects").select("id, name").eq(isUuid ? "id" : "name", target).maybeSingle();
+  if (lookupErr)
+    throw systemError(`Lookup failed: ${lookupErr.message}`);
+  if (!project)
+    throw notFound(`Project "${target}" not found.`);
+  const { data, error } = await client.raw.from("cerefox_projects").update(update).eq("id", project.id).select("id, name, description").maybeSingle();
+  if (error || !data) {
+    throw systemError(`Update failed: ${error?.message ?? "no row returned"}`);
+  }
+  println(c.green(`✓ Updated project "${data.name}" (id: ${data.id}).`));
+}
+function registerProjectEdit(parent) {
+  parent.command("edit").description("Rename a project and/or change its description.").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--name <new-name>", "New project name.").option("--description <text>", "New project description.").action(action13);
+}
+
+// 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));
 }
 
 // ../../node_modules/.bun/ora@9.4.0/node_modules/ora/index.js
@@ -45431,12 +45711,12 @@ init_cli_core();
 
 // src/cli/util/checks.ts
 init_meta();
-import { existsSync as existsSync8, readFileSync as readFileSync6, realpathSync, statSync as statSync2 } from "node:fs";
-import { homedir as homedir4 } from "node:os";
-import { join as join7 } from "node:path";
+import { existsSync as existsSync9, readFileSync as readFileSync7, realpathSync, statSync as statSync2 } from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { join as join8 } from "node:path";
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "0.8.0";
+var EF_VERSION = "0.9.1";
 
 // src/cli/util/checks.ts
 init_config();
@@ -45587,7 +45867,7 @@ function checkConfig() {
       hint: "Run `cerefox init` to bootstrap."
     };
   }
-  if (!existsSync8(envPath)) {
+  if (!existsSync9(envPath)) {
     return {
       name: "config",
       status: "error",
@@ -45715,9 +45995,9 @@ var SCHEMA_VERSION_RE = /^--\s*@version:\s*(\S+)/m;
 function readBundledSchemaVersion() {
   try {
     const assets = resolveServerAssets();
-    if (!existsSync8(assets.schemaFile))
+    if (!existsSync9(assets.schemaFile))
       return null;
-    const m = readFileSync6(assets.schemaFile, "utf8").match(SCHEMA_VERSION_RE);
+    const m = readFileSync7(assets.schemaFile, "utf8").match(SCHEMA_VERSION_RE);
     return m ? m[1] : null;
   } catch {
     return null;
@@ -45786,10 +46066,10 @@ async function checkSchemaVersion() {
   }
 }
 function hasCerefoxInJsonFile(path) {
-  if (!existsSync8(path))
+  if (!existsSync9(path))
     return false;
   try {
-    const parsed = JSON.parse(readFileSync6(path, "utf8"));
+    const parsed = JSON.parse(readFileSync7(path, "utf8"));
     const mcpServers = parsed.mcpServers;
     return Boolean(mcpServers && typeof mcpServers === "object" && "cerefox" in mcpServers);
   } catch {
@@ -45797,10 +46077,10 @@ function hasCerefoxInJsonFile(path) {
   }
 }
 function checkMcpConfigs() {
-  const home = homedir4();
-  const claudeCodeUser = join7(home, ".claude.json");
-  const claudeCodeProj = join7(process.cwd(), ".mcp.json");
-  const claudeDesktop = process.platform === "darwin" ? join7(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : process.platform === "win32" ? join7(process.env.APPDATA ?? "", "Claude", "claude_desktop_config.json") : join7(home, ".config", "Claude", "claude_desktop_config.json");
+  const home = homedir5();
+  const claudeCodeUser = join8(home, ".claude.json");
+  const claudeCodeProj = join8(process.cwd(), ".mcp.json");
+  const claudeDesktop = process.platform === "darwin" ? join8(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : process.platform === "win32" ? join8(process.env.APPDATA ?? "", "Claude", "claude_desktop_config.json") : join8(home, ".config", "Claude", "claude_desktop_config.json");
   const found = [];
   if (hasCerefoxInJsonFile(claudeCodeUser))
     found.push("Claude Code (user)");
@@ -45823,10 +46103,10 @@ function checkMcpConfigs() {
   };
 }
 function checkLegacyShadowEnv() {
-  const home = homedir4();
-  const homeEnv = join7(home, USER_STATE_DIR_NAME, ".env");
-  const cwdEnv = join7(process.cwd(), ".env");
-  if (!existsSync8(homeEnv) || !existsSync8(cwdEnv))
+  const home = homedir5();
+  const homeEnv = join8(home, USER_STATE_DIR_NAME, ".env");
+  const cwdEnv = join8(process.cwd(), ".env");
+  if (!existsSync9(homeEnv) || !existsSync9(cwdEnv))
     return null;
   try {
     if (realpathSync(homeEnv) === realpathSync(cwdEnv))
@@ -46001,7 +46281,7 @@ function symbol(status) {
       return cErr.dim("ℹ");
   }
 }
-async function action10(options) {
+async function action14(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 +46338,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(action14);
 }
 
 // src/cli/commands/get-audit-log.ts
 init_cli_core();
 init_client();
-async function action11(options) {
+async function action15(options) {
   const limit = parsePositiveInt(options.limit, "--limit", 50);
   const client = getClient();
   const data = await client.rpc("cerefox_list_audit_entries", {
@@ -46102,14 +46382,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(action15);
 }
 
 // src/cli/commands/get-doc.ts
 init_cli_core();
 init_cli_core();
 init_client();
-async function action12(documentId, options) {
+async function action16(documentId, options) {
   const client = getClient();
   const rows = await client.rpc("cerefox_get_document", {
     p_document_id: documentId,
@@ -46139,18 +46419,18 @@ 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(action16);
 }
 
 // src/cli/commands/ingest.ts
 init_dist4();
 init_cli_core();
 init_config();
-import { readFileSync as readFileSync8 } from "node:fs";
+import { readFileSync as readFileSync9 } from "node:fs";
 import { basename as basename2, extname as extname2 } from "node:path";
 
 // src/ingestion/pipeline.ts
-import { readFileSync as readFileSync7 } from "node:fs";
+import { readFileSync as readFileSync8 } from "node:fs";
 import { basename, extname, resolve as resolve3 } from "node:path";
 
 // ../../_shared/ingest/chunker.ts
@@ -46834,7 +47114,7 @@ ${c2.content}`);
     };
   }
   async ingestFile(path, opts = {}) {
-    const text = readFileSync7(path, "utf8");
+    const text = readFileSync8(path, "utf8");
     const absPath = resolve3(path);
     const stem = basename(absPath, extname(absPath));
     return this.ingestText({
@@ -46868,7 +47148,7 @@ async function readContent(path, paste) {
   }
   let content;
   try {
-    content = readFileSync8(path, "utf8");
+    content = readFileSync9(path, "utf8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw userError(`Cannot read ${path}: ${msg}`);
@@ -46876,7 +47156,7 @@ async function readContent(path, paste) {
   const titleFromPath = basename2(path, extname2(path));
   return { content, titleFromPath };
 }
-async function action13(path, options) {
+async function action17(path, options) {
   const { content, titleFromPath } = await readContent(path, Boolean(options.paste));
   const title = options.title ?? titleFromPath;
   if (!title || title.trim() === "") {
@@ -46948,7 +47228,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(action17);
 }
 
 // src/cli/commands/ingest-dir.ts
@@ -46957,7 +47237,7 @@ init_cli_core();
 init_config();
 var import_cli_progress = __toESM(require_cli_progress(), 1);
 import { readdirSync as readdirSync4, statSync as statSync3 } from "node:fs";
-import { basename as basename3, extname as extname3, join as join8 } from "node:path";
+import { basename as basename3, extname as extname3, join as join9 } from "node:path";
 function walk(dir, extensions) {
   let entries;
   try {
@@ -46967,7 +47247,7 @@ function walk(dir, extensions) {
   }
   const files = [];
   for (const name of entries) {
-    const full = join8(dir, name);
+    const full = join9(dir, name);
     let stat;
     try {
       stat = statSync3(full);
@@ -46984,7 +47264,7 @@ function walk(dir, extensions) {
   }
   return files;
 }
-async function action14(dir, options) {
+async function action18(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 +47337,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(action18);
 }
 
 // src/cli/commands/init.ts
@@ -47067,20 +47347,20 @@ import { spawnSync as spawnSync4 } from "node:child_process";
 import {
   chmodSync,
   copyFileSync as copyFileSync2,
-  existsSync as existsSync9,
+  existsSync as existsSync10,
   mkdirSync as mkdirSync3,
-  readFileSync as readFileSync10,
-  writeFileSync as writeFileSync3
+  readFileSync as readFileSync11,
+  writeFileSync as writeFileSync4
 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
-import { dirname as dirname4, join as join9 } from "node:path";
+import { homedir as homedir6 } from "node:os";
+import { dirname as dirname4, join as join10 } from "node:path";
 async function readConfigFile(path) {
-  if (!existsSync9(path)) {
+  if (!existsSync10(path)) {
     throw userError(`--config file not found: ${path}`);
   }
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync10(path, "utf8"));
+    parsed = JSON.parse(readFileSync11(path, "utf8"));
   } catch (err) {
     throw userError(`--config: invalid JSON in ${path}: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -47122,7 +47402,7 @@ function parseDotEnvFile(content) {
   return map;
 }
 function answersFromEnvFile(path) {
-  const parsed = parseDotEnvFile(readFileSync10(path, "utf8"));
+  const parsed = parseDotEnvFile(readFileSync11(path, "utf8"));
   const required = ["CEREFOX_SUPABASE_URL", "CEREFOX_SUPABASE_KEY", "OPENAI_API_KEY"];
   for (const key of required) {
     if (!parsed[key] || parsed[key].trim() === "") {
@@ -47378,7 +47658,7 @@ async function postWriteLifecycle(envPath, options) {
 }
 function writeAnswersTo(target, answers) {
   mkdirSync3(dirname4(target), { recursive: true });
-  writeFileSync3(target, buildEnvFile(answers), "utf8");
+  writeFileSync4(target, buildEnvFile(answers), "utf8");
   if (process.platform !== "win32") {
     try {
       chmodSync(target, 384);
@@ -47387,13 +47667,13 @@ function writeAnswersTo(target, answers) {
     }
   }
 }
-async function action16(options) {
-  const homeEnv = join9(homedir5(), USER_STATE_DIR_NAME, ".env");
-  const cwdEnv = join9(process.cwd(), ".env");
+async function action20(options) {
+  const homeEnv = join10(homedir6(), USER_STATE_DIR_NAME, ".env");
+  const cwdEnv = join10(process.cwd(), ".env");
   const explicitDir = (process.env.CEREFOX_CONFIG_DIR ?? "").trim();
   if (explicitDir) {
     const target2 = resolveEnvFile();
-    if (existsSync9(target2) && !options.force) {
+    if (existsSync10(target2) && !options.force) {
       println(c.yellow(`⚠ Config already exists at ${target2}.`));
       const ok2 = await confirm("Overwrite?", true);
       if (!ok2) {
@@ -47415,7 +47695,7 @@ async function action16(options) {
     await postWriteLifecycle(target2, options);
     return;
   }
-  if (existsSync9(homeEnv) && !options.force) {
+  if (existsSync10(homeEnv) && !options.force) {
     println(c.yellow(`⚠ Config already exists at ${homeEnv}.`));
     const ok2 = await confirm("Overwrite?", true);
     if (!ok2) {
@@ -47436,7 +47716,7 @@ async function action16(options) {
     await postWriteLifecycle(homeEnv, options);
     return;
   }
-  if (existsSync9(cwdEnv) && !options.force && !options.config) {
+  if (existsSync10(cwdEnv) && !options.force && !options.config) {
     printMigrationMenu(cwdEnv, homeEnv);
     const ch = await promptMigrationChoice();
     println("");
@@ -47496,13 +47776,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(action20);
 }
 
 // src/cli/commands/list-docs.ts
 init_cli_core();
 init_client();
-async function action17(options) {
+async function action21(options) {
   const limit = parsePositiveInt(options.limit, "--limit", 100);
   const client = getClient();
   let projectId;
@@ -47557,13 +47837,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(action21);
 }
 
 // src/cli/commands/list-metadata-keys.ts
 init_cli_core();
 init_client();
-async function action18(options) {
+async function action22(options) {
   const client = getClient();
   const data = await client.rpc("cerefox_list_metadata_keys");
   if (data === null) {
@@ -47591,13 +47871,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(action22);
 }
 
 // src/cli/commands/list-projects.ts
 init_cli_core();
 init_client();
-async function action19(options) {
+async function action23(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 +47906,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(action23);
 }
 
 // src/cli/commands/list-versions.ts
 init_cli_core();
 init_client();
-async function action20(documentId, options) {
+async function action24(documentId, options) {
   const client = getClient();
   const data = await client.rpc("cerefox_list_document_versions", {
     p_document_id: documentId
@@ -47673,7 +47953,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(action24);
 }
 
 // src/cli/commands/mcp.ts
@@ -47688,7 +47968,7 @@ function registerMcp(program2) {
 // src/cli/commands/metadata-search.ts
 init_cli_core();
 init_client();
-async function action21(options) {
+async function action25(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 +48031,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(action25);
 }
 
 // src/cli/commands/reindex.ts
@@ -47759,7 +48039,7 @@ init_dist4();
 init_cli_core();
 init_config();
 var DEFAULT_MODEL = "text-embedding-3-small";
-async function action22(options) {
+async function action26(options) {
   const settings = loadSettings();
   if (!settings.supabaseUrl || !settings.supabaseKey) {
     throw userError("Supabase credentials not configured — run `cerefox init` first.");
@@ -47838,41 +48118,41 @@ ${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(action26);
 }
 
 // src/cli/commands/restore.ts
 init_cli_core();
 init_client();
-import { existsSync as existsSync10, readFileSync as readFileSync11, readdirSync as readdirSync5, statSync as statSync4 } from "node:fs";
-import { homedir as homedir6 } from "node:os";
-import { join as join10, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync11, readFileSync as readFileSync12, readdirSync as readdirSync5, statSync as statSync4 } from "node:fs";
+import { homedir as homedir7 } from "node:os";
+import { join as join11, resolve as resolve4 } from "node:path";
 function expandHome2(path) {
   if (path === "~")
-    return homedir6();
+    return homedir7();
   if (path.startsWith("~/"))
-    return join10(homedir6(), path.slice(2));
+    return join11(homedir7(), path.slice(2));
   return path;
 }
 function resolveBackupFile(target) {
   const path = resolve4(expandHome2(target));
-  if (!existsSync10(path)) {
+  if (!existsSync11(path)) {
     throw userError(`Backup path not found: ${target}`);
   }
   const stat = statSync4(path);
   if (stat.isFile())
     return path;
-  const candidates = readdirSync5(path).filter((n) => n.endsWith(".json") && n.startsWith("cerefox-")).map((n) => ({ name: n, mtime: statSync4(join10(path, n)).mtimeMs })).sort((a, b2) => b2.mtime - a.mtime);
+  const candidates = readdirSync5(path).filter((n) => n.endsWith(".json") && n.startsWith("cerefox-")).map((n) => ({ name: n, mtime: statSync4(join11(path, n)).mtimeMs })).sort((a, b2) => b2.mtime - a.mtime);
   if (candidates.length === 0) {
     throw userError(`No cerefox-*.json files in ${path}`);
   }
-  return join10(path, candidates[0].name);
+  return join11(path, candidates[0].name);
 }
-async function action23(target, options) {
+async function action27(target, options) {
   const file = resolveBackupFile(target);
   let payload;
   try {
-    payload = JSON.parse(readFileSync11(file, "utf8"));
+    payload = JSON.parse(readFileSync12(file, "utf8"));
   } catch (err) {
     throw userError(`Could not parse backup file ${file}: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -47924,7 +48204,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(action27);
 }
 
 // src/cli/commands/search.ts
@@ -47949,7 +48229,7 @@ async function embedQuery(query) {
 }
 
 // src/cli/commands/search.ts
-async function action24(query, options) {
+async function action28(query, options) {
   if (!query || query.trim() === "") {
     throw userError("Empty query.");
   }
@@ -48038,8 +48318,14 @@ async function action24(query, options) {
     p_result_count: accepted.length
   }).then(() => {}, () => {});
   if (options.json) {
+    const jsonResults = options.onlyMetadata ? accepted.map((r) => {
+      const copy = { ...r };
+      delete copy.full_content;
+      delete copy.content;
+      return copy;
+    }) : accepted;
     printJson({
-      results: accepted,
+      results: jsonResults,
       query,
       mode,
       match_count: matchCount,
@@ -48059,13 +48345,25 @@ async function action24(query, options) {
       const doc2 = row;
       const title = doc2.doc_title ?? "Untitled";
       const docId = doc2.document_id ? ` [id: ${doc2.document_id}]` : "";
-      const score = doc2.best_score != null ? ` (score: ${doc2.best_score.toFixed(3)})` : "";
-      const partial2 = doc2.is_partial ? ` -- partial (${doc2.chunk_count} of ${doc2.total_chars.toLocaleString()} chars)` : "";
-      println(c.bold(`## ${title}${docId}${score}${partial2}`));
+      const score = doc2.best_score != null ? ` · score ${doc2.best_score.toFixed(3)}` : "";
+      const counts = ` · ${doc2.chunk_count} chunk${doc2.chunk_count === 1 ? "" : "s"} · ${doc2.total_chars.toLocaleString()} chars`;
+      const kind = doc2.is_partial ? " · partial" : " · full";
+      println(c.bold(`## ${title}${docId}${score}${counts}${kind}`));
+      const bestMatch = doc2.best_chunk_heading_path?.length ? doc2.best_chunk_heading_path.join(" › ") : null;
+      const updated = doc2.doc_updated_at ? doc2.doc_updated_at.slice(0, 10) : null;
+      if (bestMatch || updated) {
+        const bits = [
+          bestMatch ? `best match: ${bestMatch}` : null,
+          updated ? `updated ${updated}` : null
+        ].filter(Boolean);
+        println(c.dim(`   ${bits.join(" · ")}`));
+      }
+      if (options.onlyMetadata)
+        continue;
       println("");
       println(doc2.full_content ?? "");
       println("");
-      println(c.dim("---"));
+      println(c.dim("════════════════════════════════════════"));
       println("");
     } else {
       const chunk = row;
@@ -48083,7 +48381,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.").option("--only-metadata", "List matching docs (id, score, chunks, chars, partial/full) WITHOUT their content — like the web UI's collapsed result list. Grab a [id:…] then `cerefox document get <id>`.").action(action28);
 }
 
 // src/cli/commands/self-update.ts
@@ -48130,7 +48428,7 @@ async function fetchLatestVersion() {
   }
   return body.version;
 }
-async function action25(options) {
+async function action29(options) {
   let target;
   try {
     target = options.version ?? await fetchLatestVersion();
@@ -48182,7 +48480,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(action29);
   declaration(program2.command("self-update"));
   declaration(program2.command("upgrade"));
 }
@@ -48201,7 +48499,7 @@ function symbol2(status) {
       return cErr.dim("ℹ");
   }
 }
-async function action26(options) {
+async function action30(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,105 +48520,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);
-}
-
-// src/cli/commands/sync-docs.ts
-init_cli_core();
-init_mcp_tools();
-init_config();
-init_client();
-import {
-  existsSync as existsSync11,
-  readFileSync as readFileSync12,
-  readdirSync as readdirSync6,
-  statSync as statSync5
-} from "node:fs";
-import { basename as basename5, extname as extname5, join as join11, relative } from "node:path";
-var ROOT_LEVEL_DOCS = ["README.md", "AGENT_GUIDE.md", "AGENT_QUICK_REFERENCE.md"];
-function walkMarkdown(dir) {
-  const out = [];
-  if (!existsSync11(dir))
-    return out;
-  for (const name of readdirSync6(dir)) {
-    const full = join11(dir, name);
-    let stat;
-    try {
-      stat = statSync5(full);
-    } catch {
-      continue;
-    }
-    if (stat.isDirectory()) {
-      out.push(...walkMarkdown(full));
-    } else if (stat.isFile() && name.toLowerCase().endsWith(".md")) {
-      out.push(full);
-    }
-  }
-  return out;
-}
-async function action27(options) {
-  const cwd = process.cwd();
-  const project = options.project ?? "cerefox";
-  const targets = [];
-  for (const rel of ROOT_LEVEL_DOCS) {
-    const abs = join11(cwd, rel);
-    if (existsSync11(abs))
-      targets.push({ abs, rel });
-  }
-  for (const abs of walkMarkdown(join11(cwd, "docs"))) {
-    targets.push({ abs, rel: relative(cwd, abs) });
-  }
-  if (targets.length === 0) {
-    println(c.dim(`(no markdown files found in ${cwd})`));
-    return;
-  }
-  println(c.bold(`Syncing ${targets.length} markdown file(s) to project "${project}"`));
-  if (options.dryRun)
-    println(c.yellow("(dry run — no writes)"));
-  println("");
-  if (options.dryRun) {
-    printTable(targets.map((t) => ({
-      file: t.rel,
-      title: basename5(t.abs, extname5(t.abs))
-    })));
-    return;
-  }
-  const client = getClient();
-  const settings = loadSettings();
-  const author = resolveAuthor(undefined);
-  const authorType = resolveAuthorType("agent");
-  const outcomes = [];
-  for (const t of targets) {
-    const content = readFileSync12(t.abs, "utf8");
-    const title = basename5(t.abs, extname5(t.abs));
-    try {
-      const message = await ingestTool.handler(client.raw, {
-        title,
-        content,
-        source: "sync-docs",
-        metadata: { source_path: t.rel },
-        update_if_exists: true,
-        project_name: project,
-        author,
-        author_type: authorType
-      }, { openaiApiKey: settings.openaiApiKey, accessPath: "cli" });
-      outcomes.push({ file: t.rel, status: "ok", detail: message });
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      outcomes.push({ file: t.rel, status: "error", detail: msg });
-    }
-  }
-  const ok2 = outcomes.filter((o) => o.status === "ok");
-  const errs = outcomes.filter((o) => o.status === "error");
-  println("");
-  println(c.bold(`Summary: ${ok2.length} ok · ${errs.length} error${errs.length === 1 ? "" : "s"}`));
-  if (errs.length > 0) {
-    println("");
-    printTable(errs.map((e) => ({ file: e.file, error: e.detail.slice(0, 100) })));
-  }
-}
-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("status").description("Quick sanity check (fast subset of `cerefox doctor`).").option("--json", "Emit machine-readable JSON.").action(action30);
 }
 
 // src/cli/program.ts
@@ -49655,7 +49855,7 @@ var _baseMimes = {
 var baseMimes = _baseMimes;
 
 // ../../node_modules/.bun/@hono+node-server@2.0.4+1bbe96acb4c5ebf1/node_modules/@hono/node-server/dist/serve-static.mjs
-import { createReadStream, existsSync as existsSync12, statSync as statSync6 } from "node:fs";
+import { createReadStream, existsSync as existsSync12, statSync as statSync5 } from "node:fs";
 import { join as join12 } from "node:path";
 var COMPRESSIBLE_CONTENT_TYPE_REGEX = /^\s*(?:text\/[^;\s]+|application\/(?:javascript|json|xml|xml-dtd|ecmascript|dart|postscript|rtf|tar|toml|vnd\.dart|vnd\.ms-fontobject|vnd\.ms-opentype|wasm|x-httpd-php|x-javascript|x-ns-proxy-autoconfig|x-sh|x-tar|x-virtualbox-hdd|x-virtualbox-ova|x-virtualbox-ovf|x-virtualbox-vbox|x-virtualbox-vdi|x-virtualbox-vhd|x-virtualbox-vmdk|x-www-form-urlencoded)|font\/(?:otf|ttf)|image\/(?:bmp|vnd\.adobe\.photoshop|vnd\.microsoft\.icon|vnd\.ms-dds|x-icon|x-ms-bmp)|message\/rfc822|model\/gltf-binary|x-shader\/x-fragment|x-shader\/x-vertex|[^;\s]+?\+(?:json|text|xml|yaml))(?:[;\s]|$)/i;
 var ENCODINGS = {
@@ -49667,7 +49867,7 @@ var ENCODINGS_ORDERED_KEYS = Object.keys(ENCODINGS);
 var getStats = (path) => {
   let stats;
   try {
-    stats = statSync6(path);
+    stats = statSync5(path);
   } catch {}
   return stats;
 };
@@ -51575,7 +51775,7 @@ function registerConfigRoutes(app, ctx) {
 }
 
 // src/web/routes/discovery.ts
-var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var UUID_RE3 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var DOC_COLS = "id, title, source, source_path, content_hash, metadata, chunk_count, total_chars, review_status, created_at, updated_at, deleted_at";
 function jsonByteLength(value) {
   return Buffer.byteLength(JSON.stringify(value), "utf8");
@@ -52021,7 +52221,7 @@ function registerDiscoveryRoutes(app, ctx) {
     if (!path) {
       return c2.json({ tried_path: "", anchor, matches: [] });
     }
-    if (UUID_RE2.test(path)) {
+    if (UUID_RE3.test(path)) {
       if (path === fromDocId) {
         return c2.json({ tried_path: path, anchor, matches: [] });
       }
@@ -52047,7 +52247,7 @@ function registerDiscoveryRoutes(app, ctx) {
     if (!normalised) {
       return c2.json({ tried_path: "", anchor, matches: [] });
     }
-    const basename6 = normalised.split("/").pop() ?? normalised;
+    const basename5 = normalised.split("/").pop() ?? normalised;
     const project = (rows, method) => rows.filter((r) => r.id !== fromDocId).map((r) => ({
       document_id: r.id,
       title: r.title ?? "",
@@ -52062,8 +52262,8 @@ function registerDiscoveryRoutes(app, ctx) {
         return c2.json({ tried_path: normalised, anchor, matches });
       }
     }
-    if (basename6 !== normalised) {
-      const { data } = await ctx.supabase.from("cerefox_documents").select("id, title, source_path").is("deleted_at", null).like("source_path", `%/${basename6}`).order("updated_at", { ascending: false }).limit(limit);
+    if (basename5 !== normalised) {
+      const { data } = await ctx.supabase.from("cerefox_documents").select("id, title, source_path").is("deleted_at", null).like("source_path", `%/${basename5}`).order("updated_at", { ascending: false }).limit(limit);
       const rows = data ?? [];
       const matches = project(rows, "basename");
       if (matches.length > 0) {
@@ -52071,7 +52271,7 @@ function registerDiscoveryRoutes(app, ctx) {
       }
     }
     {
-      const stem = basename6.replace(/\.md$/i, "").replace(/[-_]+/g, " ").trim();
+      const stem = basename5.replace(/\.md$/i, "").replace(/[-_]+/g, " ").trim();
       if (stem) {
         const { data } = await ctx.supabase.from("cerefox_documents").select("id, title, source_path").is("deleted_at", null).ilike("title", `%${stem}%`).order("updated_at", { ascending: false }).limit(limit);
         const rows = data ?? [];
@@ -52619,10 +52819,10 @@ import { execFileSync } from "node:child_process";
 import {
   existsSync as existsSync13,
   readFileSync as readFileSync13,
-  readdirSync as readdirSync7,
-  statSync as statSync7
+  readdirSync as readdirSync6,
+  statSync as statSync6
 } from "node:fs";
-import { basename as basename6, dirname as dirname5, join as join13, resolve as resolve5 } from "node:path";
+import { basename as basename5, dirname as dirname5, join as join13, resolve as resolve5 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 var TOP_LEVEL_DOCS = [
   { filename: "README.md", path: "README.md", category: "readme" },
@@ -52650,7 +52850,7 @@ function resolveDocsRoots() {
   let pkgTopLevel = null;
   for (const pkg of pkgRootCandidates) {
     const guides = join13(pkg, "docs", "guides");
-    if (existsSync13(guides) && statSync7(guides).isDirectory()) {
+    if (existsSync13(guides) && statSync6(guides).isDirectory()) {
       pkgGuides = guides;
       pkgTopLevel = pkg;
       break;
@@ -52679,7 +52879,7 @@ function slugifiedTitle(filename) {
   return filename.replace(/\.md$/i, "").replace(/[-_]+/g, " ").replace(/\b\w/g, (m) => m.toUpperCase());
 }
 function entryForFile(absPath, relPath, category) {
-  const title = readH1(absPath) ?? slugifiedTitle(basename6(relPath));
+  const title = readH1(absPath) ?? slugifiedTitle(basename5(relPath));
   return { path: relPath, title, category };
 }
 function listBundledDocs2() {
@@ -52696,7 +52896,7 @@ function listBundledDocs2() {
   }
   const guidesRoot = pkgGuides ?? repoGuides;
   if (guidesRoot) {
-    const names = readdirSync7(guidesRoot).filter((n) => n.endsWith(".md")).sort();
+    const names = readdirSync6(guidesRoot).filter((n) => n.endsWith(".md")).sort();
     for (const name of names) {
       const abs = join13(guidesRoot, name);
       entries.push(entryForFile(abs, `guides/${name}`, "guide"));
@@ -52712,7 +52912,7 @@ function readDoc(docPath) {
     if (!candidate.startsWith(resolve5(root) + "/") && candidate !== resolve5(root)) {
       continue;
     }
-    if (existsSync13(candidate) && statSync7(candidate).isFile()) {
+    if (existsSync13(candidate) && statSync6(candidate).isFile()) {
       try {
         return readFileSync13(candidate, "utf8");
       } catch {
@@ -52880,14 +53080,14 @@ function registerProjectsRoutes(app, ctx) {
 }
 
 // src/web/static.ts
-import { existsSync as existsSync14, statSync as statSync8 } from "node:fs";
+import { existsSync as existsSync14, statSync as statSync7 } from "node:fs";
 import { dirname as dirname6, join as join14 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 function moduleDir3() {
   return dirname6(fileURLToPath4(import.meta.url));
 }
 function isUsableSpaDir(dir) {
-  return existsSync14(dir) && statSync8(dir).isDirectory() && existsSync14(join14(dir, "index.html"));
+  return existsSync14(dir) && statSync7(dir).isDirectory() && existsSync14(join14(dir, "index.html"));
 }
 function resolveSpaDist() {
   const here = moduleDir3();
@@ -52909,7 +53109,7 @@ function resolveStaticDir() {
     join14(here, "..", "..", "..", "..", "web", "static")
   ];
   for (const c2 of candidates) {
-    if (existsSync14(c2) && statSync8(c2).isDirectory())
+    if (existsSync14(c2) && statSync7(c2).isDirectory())
       return c2;
   }
   return null;
@@ -53058,11 +53258,11 @@ import {
   openSync,
   readFileSync as readFileSync15,
   rmSync,
-  writeFileSync as writeFileSync4
+  writeFileSync as writeFileSync5
 } from "node:fs";
-import { homedir as homedir7 } from "node:os";
+import { homedir as homedir8 } from "node:os";
 import { join as join16 } from "node:path";
-var STATE_DIR = join16(homedir7(), ".cerefox");
+var STATE_DIR = join16(homedir8(), ".cerefox");
 var PID_FILE = join16(STATE_DIR, "web.pid");
 var LOG_FILE = join16(STATE_DIR, "web.log");
 var daemonPaths = { stateDir: STATE_DIR, pidFile: PID_FILE, logFile: LOG_FILE };
@@ -53089,7 +53289,7 @@ function readPidFile() {
 }
 function writePidFile(info3) {
   ensureStateDir();
-  writeFileSync4(PID_FILE, JSON.stringify(info3, null, 2) + `
+  writeFileSync5(PID_FILE, JSON.stringify(info3, null, 2) + `
 `, "utf8");
 }
 function removePidFile() {
@@ -53313,15 +53513,58 @@ 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", "document 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"],
+  ["docs", "guides"],
+  ["sync-self-docs", "guides ingest"]
+];
+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.`));
+      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 · edit · delete · restore · ingest · ingest-dir · version {list·archive·unarchive}
+` + `  project    list · create · edit · delete
+` + `  metadata   keys · search
+` + `  audit      list
+` + `  config     list · get · set
+` + `  backup     create · restore
+` + `  server     deploy · reindex
+` + `  guides     list · open · show · ingest   (bundled documentation)
+` + `
+Top-level commands:
+` + `  search · init · doctor · status · configure-agent · self-update
+` + `  mcp · web · completion
+` + `
+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 +53576,58 @@ 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);
-  registerDocs(program2);
-  registerReindex(program2);
-  registerConfigGet(program2);
-  registerConfigSet(program2);
+  registerMcp(program2);
+  registerWeb(program2);
   registerCompletion(program2);
+  const document2 = program2.command("document").description("Documents: get, list, edit, delete, restore, ingest, ingest-dir, version.");
+  moveInto(document2, registerGetDoc, "get");
+  moveInto(document2, registerListDocs, "list");
+  moveInto(document2, registerDeleteDoc, "delete");
+  registerDocumentRestore(document2);
+  registerDocumentEdit(document2);
+  moveInto(document2, registerIngest, "ingest");
+  moveInto(document2, registerIngestDir, "ingest-dir");
+  const documentVersion = document2.command("version").description("Document versions: list, archive, unarchive.");
+  moveInto(documentVersion, registerListVersions, "list");
+  registerVersionArchive(documentVersion);
+  const project = program2.command("project").description("Projects: list, create, edit, delete.");
+  moveInto(project, registerListProjects, "list");
+  registerProjectCreate(project);
+  registerProjectEdit(project);
+  moveInto(project, registerDeleteProject, "delete");
+  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: list, get, set.");
+  registerConfigList(config2);
+  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");
+  const guides = program2.command("guides").description("Bundled docs: list, open, show, ingest (into the KB).");
+  registerGuides(guides);
+  moveInto(guides, registerSyncSelfDocs, "ingest");
+  registerRenameHusks(program2);
+  program2.command("sync-docs", { hidden: true }).allowUnknownOption(true).allowExcessArguments(true).argument("[args...]", "(removed)").action(() => {
+    eprintln(c.yellow("✗ `cerefox sync-docs` was removed from the CLI in v0.9.1."));
+    eprintln("  It synced a local repo clone (contributor op). From a repo clone: `bun scripts/sync_docs.ts`.");
+    process.exit(1);
+  });
   return program2;
 }