@cerefox/memory 0.9.0 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. package/AGENT_GUIDE.md +28 -26
  2. package/AGENT_QUICK_REFERENCE.md +12 -12
  3. package/dist/bin/cerefox.js +507 -355
  4. package/dist/frontend/assets/{index-CAp2_lFX.js → index-De3R6K8J.js} +29 -29
  5. package/dist/frontend/assets/{index-CAp2_lFX.js.map → index-De3R6K8J.js.map} +1 -1
  6. package/dist/frontend/index.html +1 -1
  7. package/dist/server-assets/_shared/ef-meta/index.ts +1 -1
  8. package/dist/server-assets/_shared/mcp-tools/get-help-content.ts +2 -2
  9. package/docs/guides/access-paths.md +40 -34
  10. package/docs/guides/cli.md +158 -16
  11. package/docs/guides/configuration.md +20 -29
  12. package/docs/guides/connect-agents.md +154 -177
  13. package/docs/guides/ops-scripts.md +73 -53
  14. package/docs/guides/quickstart.md +26 -20
  15. package/docs/guides/setup-cloud-run.md +12 -2
  16. package/docs/guides/setup-local.md +14 -8
  17. package/docs/guides/setup-supabase.md +57 -162
  18. package/docs/guides/upgrading.md +43 -30
  19. package/package.json +1 -1
package/dist/frontend/index.html CHANGED
@@ -5,7 +5,7 @@
5
5
  <link rel="icon" type="image/png" href="/app/cerefox_icon.png" />
6
6
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7
7
  <title>Cerefox</title>
8
- <script type="module" crossorigin src="/app/assets/index-CAp2_lFX.js"></script>
8
+ <script type="module" crossorigin src="/app/assets/index-De3R6K8J.js"></script>
9
9
  <link rel="stylesheet" crossorigin href="/app/assets/index-DoDJGRih.css">
10
10
  </head>
11
11
  <body>
package/dist/server-assets/_shared/ef-meta/index.ts CHANGED
@@ -18,7 +18,7 @@
18
18
  * doesn't touch `supabase/functions/` leaves it alone).
19
19
  */
20
20
 
21
- export const EF_VERSION = "0.8.0";
21
+ export const EF_VERSION = "0.9.1";
22
22
 
23
23
  /**
24
24
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp
package/dist/server-assets/_shared/mcp-tools/get-help-content.ts CHANGED
@@ -11,7 +11,7 @@
11
11
  * docs/specs/polish-and-distribution-design.md §10d.
12
12
  */
13
13
 
14
- export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for \"How AI Agents Use Cerefox\" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |\n| `cerefox_get_document` | Get full document by ID | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find docs by metadata (no text query) | `metadata_filter` (required), `include_content`, `updated_since` |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\", author=\"my-agent\")\n```\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true, author=\"my-agent\")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. 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";
14
+ export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for \"How AI Agents Use Cerefox\" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |\n| `cerefox_get_document` | Get full document by ID | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find docs by metadata (no text query) | `metadata_filter` (required), `include_content`, `updated_since` |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\", author=\"my-agent\")\n```\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true, author=\"my-agent\")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); 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";
15
15
 
16
16
  /** Sections keyed by their H2 heading text (lower-cased for matching). */
17
17
  export const HELP_SECTIONS: Record<string, string> = {
@@ -20,7 +20,7 @@ export const HELP_SECTIONS: Record<string, string> = {
20
20
  "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```",
21
21
  "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```",
22
22
  "Catch-Up Workflow": "## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```",
23
- "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.",
23
+ "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.",
24
24
  };
25
25
 
26
26
  export const HELP_SECTION_HEADINGS: string[] = ["Tools", "Essential Rules", "Update Workflow (ID-based -- preferred)", "Update Workflow (title-based -- fallback)", "Catch-Up Workflow", "CLI fallback (when MCP is unavailable)"];
package/docs/guides/access-paths.md CHANGED
@@ -5,7 +5,7 @@ configure, what can reach the database, and which path is right for your integra
5
5
 
6
6
  > **A note on Supabase keys (2026):** Cerefox needs two API keys for two different transport
7
7
  > layers. Layer 1 (Edge Functions) uses the **legacy anon JWT** as a Bearer token — the new
8
- > `sb_publishable_…` key is rejected by the Edge Function gateway. Layer 2 (Python REST)
8
+ > `sb_publishable_…` key is rejected by the Edge Function gateway. Layer 2 (web + CLI REST)
9
9
  > uses the new **secret key** (`sb_secret_…`) or the legacy `service_role` JWT — either
10
10
  > works. See [`setup-supabase.md` → Supabase API keys (2026)](setup-supabase.md#supabase-api-keys-2026)
11
11
  > for the full picture and why this asymmetry exists.
@@ -14,7 +14,7 @@ configure, what can reach the database, and which path is right for your integra
14
14
 
15
15
  ## Layer 1 — AI Agents via Edge Functions (HTTPS)
16
16
 
17
- This is the primary integration layer for AI clients. Six Supabase Edge Functions are
17
+ This is the primary integration layer for AI clients. Nine Supabase Edge Functions are
18
18
  deployed on the Supabase platform and are reachable over HTTPS with nothing more than the
19
19
  **legacy anon JWT** (a public-facing JWT, `eyJ…`). The Supabase gateway validates the key
20
20
  before any request reaches a function; individual functions then use the service-role key
@@ -25,7 +25,7 @@ internally to call Postgres RPCs. Your anon key is never elevated to database-le
25
25
  > [`setup-supabase.md` → Supabase API keys (2026)](setup-supabase.md#supabase-api-keys-2026)
26
26
  > for why.
27
27
 
28
- ### The six Edge Functions
28
+ ### The nine Edge Functions
29
29
 
30
30
  | Edge Function | Role |
31
31
  |---|---|
@@ -34,29 +34,28 @@ internally to call Postgres RPCs. Your anon key is never elevated to database-le
34
34
  | `cerefox-metadata` | List metadata keys with document counts and example values |
35
35
  | `cerefox-get-document` | Retrieve full document content (current or archived version) |
36
36
  | `cerefox-list-versions` | List the archived version history for a document |
37
- | `cerefox-mcp` | Streamable HTTP MCP adapter — delegates to all five above |
37
+ | `cerefox-get-audit-log` | Query audit log entries with filters |
38
+ | `cerefox-metadata-search` | Query documents by metadata key-value criteria without text search |
39
+ | `cerefox-list-projects` | List all projects with names, IDs, and descriptions |
40
+ | `cerefox-mcp` | Streamable HTTP MCP adapter — calls Postgres RPCs directly |
38
41
 
39
42
  ### How clients connect
40
43
 
41
44
  **MCP clients** (Claude Code, Cursor, Claude Desktop) connect to `cerefox-mcp`. It speaks
42
- the MCP Streamable HTTP protocol and fans out each tool call to the appropriate primitive
43
- Edge Function via an internal `fetch()`. The client only ever talks to one URL.
45
+ the MCP Streamable HTTP protocol and calls the Postgres RPCs directly (no internal fan-out
46
+ to the primitive Edge Functions). The client only ever talks to one URL.
44
47
 
45
48
  ```
46
49
  MCP client (anon key)
47
50
  │
48
51
  ▼
49
- cerefox-mcp ──▶ cerefox-search
50
- ──▶ cerefox-ingest
51
- ──▶ cerefox-metadata
52
- ──▶ cerefox-get-document
53
- ──▶ cerefox-list-versions
54
- │
55
- ▼ (service-role key, internal)
56
- Postgres RPCs
52
+ cerefox-mcp
53
+ │
54
+ ▼ (service-role key, internal)
55
+ Postgres RPCs
57
56
  ```
58
57
 
59
- **ChatGPT Custom GPT Actions** call the five primitive Edge Functions directly over HTTPS
58
+ **ChatGPT Custom GPT Actions** call the eight primitive Edge Functions directly over HTTPS
60
59
  using an OpenAPI schema. `cerefox-mcp` is not involved (ChatGPT does not support the
61
60
  Streamable HTTP MCP protocol).
62
61
 
@@ -72,14 +71,17 @@ See `docs/guides/connect-agents.md` for step-by-step setup per client.
72
71
 
73
72
  ---
74
73
 
75
- ## Layer 2 — Python Web App and CLI via Supabase REST
74
+ ## Layer 2 — Web UI and CLI via Supabase REST
75
+
76
+ The web UI (TypeScript Hono backend + React/Mantine SPA, served by `cerefox web`) and all
77
+ `cerefox` CLI commands (`document ingest`, `search`, `server reindex`, `backup`, etc.) talk
78
+ to Supabase over its REST API (PostgREST), authenticating with a **service-role-equivalent
79
+ key** rather than the anon key — either the new **secret key** (`sb_secret_…`) or the legacy
80
+ `service_role` JWT. Both are accepted by the Data API gateway.
76
81
 
77
- The FastAPI web app and all `cerefox` CLI commands (`ingest`, `search`, `reindex`,
78
- `backup`, etc.) use `CerefoxClient` (`src/cerefox/db/client.py`), a thin wrapper around
79
- `supabase-py`. This library talks to Supabase over its REST API (PostgREST), but
80
- authenticates with a **service-role-equivalent key** rather than the anon key — either
81
- the new **secret key** (`sb_secret_…`) or the legacy `service_role` JWT. Both are
82
- accepted by the Data API gateway.
82
+ > The legacy Python FastAPI web app and Python CLI are husks slated for removal; only
83
+ > `uv run cerefox mcp` survives as a frozen, unmaintained fallback. The TS `cerefox` CLI
84
+ > and `cerefox web` are the current implementations.
83
85
 
84
86
  The service-role key bypasses Supabase Row Level Security (RLS) policies and grants
85
87
  unrestricted read and write access. This is intentional — the CLI and web app are trusted,
@@ -87,14 +89,14 @@ local tools that need to insert, update, and delete freely. Keep this key out of
87
89
  public-facing configuration.
88
90
 
89
91
  > **Local coding agents (Claude Code, Codex CLI, opencode, OpenClaw, Hermes, …) also reach
90
- > Cerefox through this layer**, when the user authorises the agent to invoke `uv run cerefox …`
92
+ > Cerefox through this layer**, when the user authorises the agent to invoke `cerefox …`
91
93
  > via its Bash tool. This is "Path C" in `connect-agents.md`. The agent runs with the same
92
94
  > service-role privileges as the user — same trust assumption as letting the agent edit
93
95
  > source code in your repo. See `docs/guides/connect-agents.md` → "Path C — Shell CLI for
94
96
  > local coding agents" for the setup and caveats.
95
97
 
96
98
  ```
97
- Python web app / CLI (service-role key)
99
+ Web UI / CLI (service-role key)
98
100
  │
99
101
  ▼
100
102
  Supabase REST API (PostgREST)
@@ -103,7 +105,7 @@ Supabase REST API (PostgREST)
103
105
  Postgres RPCs (same cerefox_* functions called by Edge Functions)
104
106
  ```
105
107
 
106
- The Python layer calls the same Postgres RPCs as the Edge Functions — the business logic
108
+ This layer calls the same Postgres RPCs as the Edge Functions — the business logic
107
109
  lives in one place (Postgres) and is shared across all callers.
108
110
 
109
111
  ### Credentials needed
@@ -115,20 +117,24 @@ lives in one place (Postgres) and is shared across all callers.
115
117
 
116
118
  ## Layer 3 — Direct Postgres (Deployment Scripts Only)
117
119
 
118
- The deployment and migration scripts (`scripts/db_deploy.py`, `scripts/db_migrate.py`,
119
- `scripts/backup_restore.py`) connect directly to Postgres over TCP using **psycopg2** and
120
- the database connection string. This is the only path that can run DDL statements (`CREATE
121
- TABLE`, `CREATE FUNCTION`) — the REST API does not support them.
120
+ For end users, `cerefox server deploy` (which bundles schema + RPCs + the nine Edge
121
+ Functions from the npm package) handles schema deployment directly. For contributors, the
122
+ canonical deployment and migration scripts (`bun scripts/db_deploy.ts`,
123
+ `bun scripts/db_migrate.ts`, `bun scripts/backup_restore.ts`) connect directly to Postgres
124
+ over TCP using the database connection string. (The legacy `.py` equivalents still exist
125
+ but are deprecated.) This is the only path that can run DDL statements (`CREATE TABLE`,
126
+ `CREATE FUNCTION`) — the REST API does not support them.
122
127
 
123
128
  ```
124
- scripts/db_deploy.py (DB password via DATABASE_URL)
129
+ cerefox server deploy / bun scripts/db_deploy.ts (DB password via DATABASE_URL)
125
130
  │
126
131
  ▼
127
132
  Postgres (direct TCP connection)
128
133
  ```
129
134
 
130
- No application code — not the web app, not the CLI — uses this path at runtime. It is
131
- exclusively for schema deployment and data restore operations.
135
+ No application code — not the web app, not the CLI's runtime read/write commands — uses
136
+ this path at request time. It is exclusively for schema deployment and data restore
137
+ operations.
132
138
 
133
139
  ### Credentials needed
134
140
 
@@ -149,10 +155,10 @@ exclusively for schema deployment and data restore operations.
149
155
  | Claude Desktop | HTTPS → `cerefox-mcp` (via `supergateway`) | Legacy anon JWT | Daily AI assistant access |
150
156
  | ChatGPT Custom GPT | HTTPS → primitive Edge Functions | Legacy anon JWT | AI assistant via GPT Actions |
151
157
  | curl / HTTP scripts | HTTPS → primitive Edge Functions | Legacy anon JWT | Ad-hoc queries, automation |
152
- | Python web app | Supabase REST API | Secret key (or legacy service_role) | Web UI backend |
158
+ | Web UI (`cerefox web`) | Supabase REST API | Secret key (or legacy service_role) | Web UI backend (TS Hono) |
153
159
  | `cerefox` CLI (human) | Supabase REST API | Secret key (or legacy service_role) | Ingestion, search, reindex, backup |
154
160
  | Local coding agent via `cerefox` CLI | Supabase REST API | Secret key (or legacy service_role) | User-authorised agent (Claude Code, Codex CLI, opencode, OpenClaw, Hermes, …) acting on user's behalf via Bash tool |
155
- | Deployment scripts | Direct TCP (psycopg2) | DB password | Schema deploy, data restore |
161
+ | `cerefox server deploy` / deployment scripts | Direct TCP | DB password | Schema deploy, data restore |
156
162
 
157
163
  ### Key security principle
158
164
 
package/docs/guides/cli.md CHANGED
@@ -10,15 +10,17 @@ Every command reads configuration from `.env` in the working directory (or envir
10
10
 
11
11
  - `CEREFOX_SUPABASE_URL` and `CEREFOX_SUPABASE_KEY` for any command that talks to Supabase
12
12
  - `OPENAI_API_KEY` (or `CEREFOX_FIREWORKS_API_KEY`) for any command that embeds (ingest, search)
13
- - `CEREFOX_DATABASE_URL` only for the `scripts/db_*.py` deployment scripts (not the `cerefox` CLI itself)
13
+ - `CEREFOX_DATABASE_URL` for `cerefox server deploy` and the contributor scripts (`bun scripts/db_*.ts`)
14
14
 
15
- Invoke any command with `uv run cerefox <subcommand>`. Inside an activated venv, `cerefox <subcommand>` works too — but `uv run` is preferred (no venv activation needed; see Decision Log Q2 lesson on `uv` installation).
15
+ The CLI is the TypeScript `@cerefox/memory` package. Invoke any command as plain `cerefox <subcommand>` (installed via the installer or `npm install -g @cerefox/memory` — see [`quickstart.md`](quickstart.md#1-install)).
16
+
17
+ > **v0.9 verb rename**: commands now follow a `resource verb` shape (e.g. `cerefox document get`, `cerefox project list`). The old flat verbs (`get-doc`, `list-docs`, `ingest`, `list-versions`, `config-get`, `deploy-server`, `docs`, …) are husks and have been removed — use the new forms below.
16
18
 
17
19
  ## Commands
18
20
 
19
21
  ### `cerefox document ingest`
20
22
 
21
- **Purpose**: ingest a markdown / PDF / DOCX file (or stdin) into the knowledge base.
23
+ **Purpose**: ingest a markdown / plain-text file (or stdin) into the knowledge base. (PDF/DOCX conversion was dropped in v0.7 — markdown/text only.)
22
24
 
23
25
  **Synopsis**:
24
26
  ```
@@ -82,7 +84,7 @@ cerefox document ingest-dir [OPTIONS] DIRECTORY
82
84
 
83
85
  | Flag | Type | Default | Description |
84
86
  |---|---|---|---|
85
- | `--pattern TEXT` | glob | `*.md` | Glob pattern. Examples: `**/*.md`, `*.pdf`. |
87
+ | `--pattern TEXT` | glob | `*.md` | Glob pattern. Examples: `**/*.md`, `*.txt`. |
86
88
  | `--project-name TEXT` (alias: `--project`, `-p`) | str | _none_ | Project to assign every document to. |
87
89
  | `--recursive / --no-recursive` | flag | `--no-recursive` | Recurse into sub-directories. |
88
90
  | `--dry-run` | flag | off | Print files that would be ingested; do nothing. |
@@ -126,6 +128,7 @@ cerefox search [OPTIONS] QUERY
126
128
  | `--alpha FLOAT` | float | `0.7` | FTS/semantic weight (hybrid only). |
127
129
  | `--min-score FLOAT` | float | `CEREFOX_MIN_SEARCH_SCORE` or `0.50` | Minimum cosine similarity (hybrid/semantic only). |
128
130
  | `--metadata-filter TEXT` (alias: `--filter`, `-f`) | JSON | _none_ | JSONB metadata containment filter, e.g. `'{"type":"decision"}'`. |
131
+ | `--only-metadata` | flag | off | Return only document titles + metadata (no chunk content / previews) — a compact listing. |
129
132
  | `--requestor TEXT` | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
130
133
 
131
134
  **Examples**:
@@ -133,6 +136,7 @@ cerefox search [OPTIONS] QUERY
133
136
  cerefox search "OAuth design"
134
137
  cerefox search "decisions" --metadata-filter '{"type":"decision-log"}' --match-count 5
135
138
  cerefox search "what we tried" --mode semantic --requestor "claude-code"
139
+ cerefox search "design docs" --only-metadata
136
140
  ```
137
141
 
138
142
  **Output**: numbered result list with title, score, and 300-char preview per hit. Final line shows total results + bytes.
@@ -156,7 +160,7 @@ cerefox document get [OPTIONS] DOCUMENT_ID
156
160
 
157
161
  | Flag | Type | Default | Description |
158
162
  |---|---|---|---|
159
- | `--version-id TEXT` (alias: `--version`) | UUID | _none_ (current) | Archived version UUID — get from `cerefox version list`. |
163
+ | `--version-id TEXT` (alias: `--version`) | UUID | _none_ (current) | Archived version UUID — get from `cerefox document version list`. |
160
164
  | `--requestor TEXT` | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
161
165
 
162
166
  **Examples**:
@@ -192,13 +196,59 @@ cerefox document list [OPTIONS]
192
196
 
193
197
  ---
194
198
 
195
- ### `cerefox version list`
199
+ ### `cerefox document edit`
200
+
201
+ **Purpose**: update a document's title and/or metadata in place, without re-ingesting content.
202
+
203
+ **Synopsis**:
204
+ ```
205
+ cerefox document edit [OPTIONS] DOCUMENT_ID
206
+ ```
207
+
208
+ **Options**:
209
+
210
+ | Flag | Type | Default | Description |
211
+ |---|---|---|---|
212
+ | `--title TEXT` | str | _unchanged_ | New document title. |
213
+ | `--set-meta TEXT` | `key=value` (repeatable) | _none_ | Set/overwrite a metadata key, e.g. `--set-meta type=decision --set-meta status=active`. |
214
+ | `--unset-meta TEXT` | key (repeatable) | _none_ | Remove a metadata key, e.g. `--unset-meta status`. |
215
+ | `--author TEXT` | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Identity recorded in the audit log. |
216
+ | `--author-type [user\|agent]` | choice | `CEREFOX_AUTHOR_TYPE` or `user` | Caller type. |
217
+
218
+ Metadata-only edits do **not** create a new version. A title change re-derives the FTS vector and re-embeds current chunks.
219
+
220
+ **Examples**:
221
+ ```bash
222
+ cerefox document edit <doc-id> --title "Renamed Doc"
223
+ cerefox document edit <doc-id> --set-meta status=archived --unset-meta draft
224
+ ```
225
+
226
+ ---
227
+
228
+ ### `cerefox document restore`
229
+
230
+ **Purpose**: restore a soft-deleted (trashed) document back to active.
231
+
232
+ **Synopsis**: `cerefox document restore [OPTIONS] DOCUMENT_ID`
233
+
234
+ **Options**:
235
+
236
+ | Flag | Type | Default | Description |
237
+ |---|---|---|---|
238
+ | `--author TEXT` | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Identity recorded in the audit log. |
239
+ | `--author-type [user\|agent]` | choice | `CEREFOX_AUTHOR_TYPE` or `user` | Caller type. |
240
+
241
+ Clears `deleted_at`, returning the document to search and `cerefox document list`, and writes a `restore` audit entry.
242
+
243
+ ---
244
+
245
+ ### `cerefox document version list`
196
246
 
197
247
  **Purpose**: list all archived versions of a document.
198
248
 
199
249
  **Synopsis**:
200
250
  ```
201
- cerefox version list [OPTIONS] DOCUMENT_ID
251
+ cerefox document version list [OPTIONS] DOCUMENT_ID
202
252
  ```
203
253
 
204
254
  **Options**:
@@ -213,6 +263,20 @@ cerefox version list [OPTIONS] DOCUMENT_ID
213
263
 
214
264
  ---
215
265
 
266
+ ### `cerefox document version archive` / `cerefox document version unarchive`
267
+
268
+ **Purpose**: mark a specific version as `archived` (protecting it from automatic version-retention cleanup), or remove that protection.
269
+
270
+ **Synopsis**:
271
+ ```
272
+ cerefox document version archive [OPTIONS] DOCUMENT_ID VERSION_ID
273
+ cerefox document version unarchive [OPTIONS] DOCUMENT_ID VERSION_ID
274
+ ```
275
+
276
+ An archived version is never deleted by the lazy version-retention sweep (see [`configuration.md` → Versioning](configuration.md#versioning)). `unarchive` makes it eligible for cleanup again. Both write an `archive` / `unarchive` audit entry.
277
+
278
+ ---
279
+
216
280
  ### `cerefox project list`
217
281
 
218
282
  **Purpose**: list all projects.
@@ -232,6 +296,34 @@ cerefox project list [OPTIONS]
232
296
 
233
297
  ---
234
298
 
299
+ ### `cerefox project create` / `cerefox project edit` / `cerefox project delete`
300
+
301
+ **Purpose**: manage projects (the grouping documents are assigned to). CLI/web-only — there is no MCP equivalent for mutations.
302
+
303
+ **Synopsis**:
304
+ ```
305
+ cerefox project create [OPTIONS] NAME
306
+ cerefox project edit [OPTIONS] PROJECT # by id or name
307
+ cerefox project delete [OPTIONS] PROJECT
308
+ ```
309
+
310
+ **Options** (common):
311
+
312
+ | Flag | Type | Default | Description |
313
+ |---|---|---|---|
314
+ | `--description TEXT` | str | _none_ | Project description (`create` / `edit`). |
315
+ | `--name TEXT` | str | _unchanged_ | New name (`edit`). |
316
+ | `-y, --yes` | flag | off | Skip confirmation (`delete`; required for non-interactive use). |
317
+
318
+ **Examples**:
319
+ ```bash
320
+ cerefox project create research --description "Literature and design notes"
321
+ cerefox project edit research --name research-archive
322
+ cerefox project delete research-archive --yes
323
+ ```
324
+
325
+ ---
326
+
235
327
  ### `cerefox metadata keys`
236
328
 
237
329
  **Purpose**: discover metadata keys used across all documents (with example values and document counts).
@@ -349,6 +441,24 @@ The success message echoes the resolved author / author_type back so you can sur
349
441
 
350
442
  ---
351
443
 
444
+ ### `cerefox server deploy`
445
+
446
+ **Purpose**: stand up *or update* the server side — schema + RPCs and all 9 Edge Functions — from the npm-bundled assets (no source clone). This is the end-user deploy path.
447
+
448
+ **Synopsis**: `cerefox server deploy [OPTIONS]`
449
+
450
+ **Options**:
451
+
452
+ | Flag | Type | Default | Description |
453
+ |---|---|---|---|
454
+ | `--schema-only` | flag | off | Deploy only schema + RPCs (skip Edge Functions). |
455
+ | `--functions-only` | flag | off | Deploy only the 9 Edge Functions (skip schema). |
456
+ | `--dry-run` | flag | off | Preview what would happen; make no changes. |
457
+
458
+ Detects fresh vs. existing databases: a fresh DB gets schema + RPCs + migration stamps; an existing DB gets pending migrations applied and `rpcs.sql` re-applied in place. There is deliberately **no `--reset`** here — the destructive wipe lives only in the contributor script `bun scripts/db_deploy.ts --reset`. See [`setup-supabase.md`](setup-supabase.md).
459
+
460
+ ---
461
+
352
462
  ### `cerefox server reindex`
353
463
 
354
464
  **Purpose**: re-embed chunks (e.g. after switching embedding models or pulling a schema change like title-boosting).
@@ -365,12 +475,13 @@ The success message echoes the resolved author / author_type back so you can sur
365
475
 
366
476
  ---
367
477
 
368
- ### `cerefox config get` / `cerefox config set`
478
+ ### `cerefox config list` / `cerefox config get` / `cerefox config set`
369
479
 
370
- **Purpose**: read/write runtime config in `cerefox_config` (e.g. `usage_tracking_enabled`).
480
+ **Purpose**: read/write runtime config in `cerefox_config` (e.g. `usage_tracking_enabled`, `require_requestor_identity`).
371
481
 
372
482
  **Synopsis**:
373
483
  ```
484
+ cerefox config list # all current key/value pairs
374
485
  cerefox config get KEY
375
486
  cerefox config set KEY VALUE
376
487
  ```
@@ -381,7 +492,7 @@ Used for toggling features at runtime without a redeploy — see [Decision Log Q
381
492
 
382
493
  ### `cerefox web`
383
494
 
384
- **Purpose**: start the FastAPI web UI (React SPA + JSON API).
495
+ **Purpose**: start the web UI — a TypeScript Hono backend serving the React/Mantine SPA + JSON API.
385
496
 
386
497
  **Synopsis**: `cerefox web [OPTIONS]`
387
498
 
@@ -391,9 +502,8 @@ Used for toggling features at runtime without a redeploy — see [Decision Log Q
391
502
  |---|---|---|---|
392
503
  | `--host TEXT` | str | `127.0.0.1` | Bind address. |
393
504
  | `--port INTEGER` | int | `8000` | Listen port. |
394
- | `--reload` | flag | off | Auto-reload on source changes (dev). |
395
505
 
396
- Requires the frontend to be built: `cd frontend && npm install && npm run build`.
506
+ The SPA assets are bundled in the npm package; no separate build step is needed for installed users. Contributors building from source can rebuild the frontend with `cd frontend && bun install && bun run build`.
397
507
 
398
508
  ---
399
509
 
@@ -407,6 +517,38 @@ No options. See [`connect-agents.md` → Path A-Local](connect-agents.md#path-a-
407
517
 
408
518
  ---
409
519
 
520
+ ### `cerefox guides`
521
+
522
+ **Purpose**: work with the bundled Cerefox self-docs that ship inside the npm package.
523
+
524
+ **Synopsis**:
525
+ ```
526
+ cerefox guides list # list the bundled guide names
527
+ cerefox guides show <name> # print a guide to stdout
528
+ cerefox guides open <name> # open a guide in your pager / browser
529
+ cerefox guides ingest # ingest the bundled self-docs into the knowledge base
530
+ ```
531
+
532
+ `cerefox guides ingest` loads the bundled guides into the `_cerefox-self-docs` project so agents can search Cerefox usage guidance (the same step `cerefox init` offers). It replaces the old `cerefox docs` / `sync-self-docs` / `sync-docs` commands.
533
+
534
+ ---
535
+
536
+ ### Setup & maintenance commands
537
+
538
+ These flat commands handle install, configuration, and health. Run any with `--help` for details:
539
+
540
+ | Command | Purpose |
541
+ |---|---|
542
+ | `cerefox init` | Interactive first-run setup; writes `~/.cerefox/.env`, offers `server deploy` + self-docs ingest. |
543
+ | `cerefox doctor` | Diagnose the install (credentials, DB reachability, schema version). |
544
+ | `cerefox status` | Show connection + schema status. |
545
+ | `cerefox configure-agent --tool <client>` | Write MCP client config (`claude-code`, `claude-desktop`, `cursor`, `codex`, `gemini`). |
546
+ | `cerefox self-update` | Update the installed `@cerefox/memory` package. |
547
+ | `cerefox completion` | Emit a shell completion script. |
548
+ | `cerefox backup create` / `cerefox backup restore` | File-system backup / restore of the knowledge base (see [`ops-scripts.md`](ops-scripts.md)). |
549
+
550
+ ---
551
+
410
552
  ## Environment variables
411
553
 
412
554
  The CLI reads its own runtime config from environment (or `.env`). See [`configuration.md`](configuration.md) for the full list. Most relevant to CLI behaviour:
@@ -425,7 +567,7 @@ Precedence: **CLI flag > env var > built-in default**.
425
567
  |---|---|
426
568
  | `0` | Success |
427
569
  | `1` | Validation error, missing config, document-not-found, etc. — see error message |
428
- | `2` | Click argument-parsing error (invalid Choice value, missing required arg) |
570
+ | `2` | Argument-parsing error (invalid choice value, missing required arg) |
429
571
 
430
572
  ## MCP tool ↔ CLI command mapping
431
573
 
@@ -439,7 +581,7 @@ Every MCP parameter has an exact-name CLI flag (kebab-cased). Short forms exist
439
581
  | `cerefox_ingest(title, content, project_name, metadata, update_if_exists, document_id, source, author, author_type)` (file) | `cerefox document ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --source <s> --author <a> --author-type <t>` |
440
582
  | `cerefox_ingest(...)` (paste) | `printf '...' \| cerefox document ingest --paste --title "<t>"` (same flags) |
441
583
  | `cerefox_get_document(document_id, version_id, requestor)` | `cerefox document get <id> --version-id <vid> --requestor <name>` |
442
- | `cerefox_list_versions(document_id, requestor)` | `cerefox version list <id> --requestor <name>` |
584
+ | `cerefox_list_versions(document_id, requestor)` | `cerefox document version list <id> --requestor <name>` |
443
585
  | `cerefox_list_projects(requestor)` | `cerefox project list --requestor <name>` |
444
586
  | `cerefox_list_metadata_keys()` | `cerefox metadata keys` |
445
587
  | `cerefox_metadata_search(metadata_filter, project_name, updated_since, created_since, limit, include_content, requestor)` | `cerefox metadata search --metadata-filter '<json>' --project-name <n> --updated-since <iso> --created-since <iso> --limit N --include-content --requestor <name>` |
@@ -453,7 +595,7 @@ None outstanding as of v0.1.17 (cerefox#27 — the `cerefox search` NameError
453
595
 
454
596
  ### Bulk-import a directory with shared metadata
455
597
  ```bash
456
- cerefox document ingest-dir ./papers --recursive --pattern '*.pdf' \
598
+ cerefox document ingest-dir ./papers --recursive --pattern '*.md' \
457
599
  --project-name "literature" \
458
600
  --metadata '{"type":"paper","status":"reviewed"}'
459
601
  ```
@@ -474,7 +616,7 @@ printf '%s' "$NEW_CONTENT" | cerefox document ingest --paste \
474
616
  ### Unattended sync job
475
617
  ```bash
476
618
  # In a cron job / launchd plist. Set CEREFOX_AUTHOR_NAME=sync-script in env.
477
- cd /path/to/cerefox && uv run cerefox document ingest-dir ~/notes --recursive --update-if-exists
619
+ cerefox document ingest-dir ~/notes --recursive --update-if-exists
478
620
  ```
479
621
 
480
622
  ### Use the CLI from an agent's Bash tool