@cerefox/memory 0.9.1 → 0.9.3

package/AGENT_GUIDE.md

@@ -359,7 +359,7 @@ If you're using Cerefox via the local CLI (Path C from `connect-agents.md`), the
 ## Governance
 
 - **Review status**: agent writes set `pending_review`; human edits set `approved`. Both are searchable.
-- **Soft delete**: deleted documents go to trash (recoverable). They are excluded from search. You can soft-delete via MCP (`cerefox_delete_document` if your client exposes it) or CLI (`cerefox document delete --yes --author <you> --author-type agent`).
+- **Soft delete**: deleted documents go to trash (recoverable). They are excluded from search. There is no delete MCP tool — soft-delete is done via the CLI (`cerefox document delete --yes --author <you> --author-type agent`) or the web UI.
 - **Permanent purge and restore-from-trash are web-UI-only**, by design. If you decide to delete something, **tell the user explicitly** that you soft-deleted it and that they can review or restore it via the Cerefox web UI. You cannot un-do your own soft-delete from agent code; only the human can. See [`docs/guides/access-paths.md` → Destructive operations and the trust model](docs/guides/access-paths.md#destructive-operations-and-the-trust-model).
 - **Versioning**: every update via `update_if_exists` creates an archived version. Old content is always recoverable.
 - **Audit log**: all write operations are recorded with author, timestamp, and size changes.
@@ -378,7 +378,7 @@ The Cerefox CLI is the TypeScript binary from `@cerefox/memory` (`npm install -g
 
 The legacy Python `uv run cerefox` is a frozen husk as of v0.9 — only `uv run cerefox mcp` (the standalone Python MCP fallback) still works; every other verb has moved to the TypeScript `cerefox` binary.
 
-> Full per-flag reference lives in [`docs/guides/cli.md`](docs/guides/cli.md). The mapping table below is the agent-facing summary. **CLI flag names match MCP parameter names exactly** (kebab-case); short forms like `--project`, `--filter`, `--count`, `--update`, `--version` are accepted as aliases.
+> Full per-flag reference lives in [`docs/guides/cli.md`](docs/guides/cli.md). The mapping table below is the agent-facing summary. **CLI flag names match MCP parameter names exactly** (kebab-case), each with a single-letter short form (`-p`, `-f`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name or its short form — there are no long-form aliases like `--project` or `--count`.
 
 ### MCP tool ↔ CLI command mapping
 
@@ -407,7 +407,7 @@ Alternative: have your user set `CEREFOX_AUTHOR_NAME`, `CEREFOX_AUTHOR_TYPE`, `C
 
 ### Behavioural differences worth knowing
 
-1. **CLI output is human-formatted by default.** `cerefox search` returns a numbered, indented text block with title, score, and a 300-char preview per result. To extract document IDs reliably, parse the `Doc: <title>  (<source>)` lines or fall back to `cerefox document list` for a clean tabular listing. `cerefox document get <id>` prints raw Markdown to stdout. **For scripted access to audit data**, use `cerefox audit list --json` — one JSON object per line, ideal for piping to `jq`.
+1. **CLI output is human-formatted by default.** In the default `docs` mode, `cerefox search` prints, per match, a header line `## <title> [id: <uuid>] · score · N chunks · M chars · partial|full` followed by the document body. Grab the document ID from the `[id: <uuid>]` tag, or use `cerefox document list` for a clean tabular listing. For structured output, `cerefox search --json` and `cerefox audit list --json` emit machine-readable JSON (the latter one object per line, ideal for `jq`). `cerefox document get <id>` prints raw Markdown to stdout.
 
 2. **Every invocation is independent.** With MCP, your tool framework can pass `requestor` once per session. With the CLI, every command is a separate process — pass `--requestor` / `--author` / `--author-type` on every relevant invocation, or set the env-var defaults once at the start.
 

package/AGENT_QUICK_REFERENCE.md

@@ -53,7 +53,7 @@ metadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03
 
 If `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.
 
-Same 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.
+Same operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.
 
 | MCP tool | CLI |
 |---|---|

package/README.md

@@ -9,7 +9,7 @@ curated knowledge layer that multiple AI tools can read and write.
 > Supabase project** (Postgres + pgvector; free tier works). Installing this
 > npm package does **not** give you a working KB on its own; you also need a
 > Supabase project + an embedding API key, and a one-time server-side deploy
-> from the source repo. **See "Before you install" below.**
+> (`cerefox server deploy` — no repo clone needed). **See "Before you install" below.**
 
 **Why cloud-backed?** Cerefox is designed as a *cloud-backed* memory layer so
 the same knowledge is reachable from every agent you run — Claude Code on
@@ -45,7 +45,7 @@ Cerefox is a self-hosted memory layer with two halves you set up independently:
 **Client side** (this npm package, runs on your machine):
 - `cerefox` CLI + `cerefox mcp` (local stdio MCP) + `cerefox web` (local UI at `http://localhost:8000`)
 
-The server side ships with the source repo, not this npm package. Both halves are required for a working install.
+You deploy the server side with this package's CLI — `cerefox server deploy` stands up the schema, RPCs, and all 9 Edge Functions from bundled assets (no repo clone). Both halves are required for a working install.
 
 ### What you need
 
@@ -55,23 +55,20 @@ The server side ships with the source repo, not this npm package. Both halves ar
 | An **embedding API key** | OpenAI `text-embedding-3-small` (default) or Fireworks AI. Pennies/month for typical personal use (see [operational-cost.md](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/operational-cost.md)). | Get an [OpenAI API key](https://platform.openai.com/api-keys). |
 | **Node ≥ 20** or **Bun ≥ 1.0** | Runtime for the `cerefox` bin (and the bundled `cerefox mcp` server). | [nodejs.org](https://nodejs.org) · [bun.sh](https://bun.sh). The one-line installer below bootstraps Bun if neither is present. |
 
-### One-time server-side setup (~10 min — clone required)
+### One-time server-side setup (~10 min — no clone needed)
 
-The schema, RPCs, and Edge Functions ship with the source repo, not this npm package. Clone once, configure, deploy:
+The CLI stands up the whole server side — schema, RPCs, and all 9 Edge
+Functions — from bundled assets:
 
 ```bash
-git clone https://github.com/fstamatelopoulos/cerefox.git
-cd cerefox && cp .env.example .env       # fill in CEREFOX_SUPABASE_* + OPENAI_API_KEY + CEREFOX_DATABASE_URL
-bun install                              # workspace deps for the deploy scripts
-bun scripts/db_deploy.ts                 # creates tables, indexes, RPCs in your Supabase
-npx supabase functions deploy cerefox-mcp cerefox-search cerefox-ingest \
-                              cerefox-metadata cerefox-get-document \
-                              cerefox-list-versions cerefox-get-audit-log \
-                              cerefox-metadata-search cerefox-list-projects
-npx supabase secrets set OPENAI_API_KEY=sk-...
+cerefox init             # enter your Supabase URL/keys + embedding key
+cerefox server deploy    # schema + RPCs + Edge Functions
 ```
 
-Full walkthrough (connection-pooling quirks, Supabase API-key flavors, troubleshooting): [setup-supabase.md](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/setup-supabase.md).
+Details (Supabase login/linking, connection-pooling quirks, API-key flavors,
+troubleshooting, and the contributor clone-and-deploy path) live in the
+[quickstart](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/quickstart.md)
+and [setup-supabase.md](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/setup-supabase.md).
 
 If you don't yet have Supabase + an OpenAI key, the [Cerefox
 quickstart](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/quickstart.md)
@@ -113,7 +110,7 @@ already provisioned (see "Before you install").
 > **Already ran the server-side setup above?** Then your schema is in place and
 > `cerefox init` only needs the URL + keys. If you skipped that step,
 > `cerefox doctor` will flag it and point you back to
-> `bun scripts/db_deploy.ts` from a repo clone.
+> `cerefox server deploy`.
 
 > **Upgrading from the Python `cerefox` CLI?** If you have a working
 > `.env` in your repo clone, init detects it and offers to **copy** it to
@@ -160,17 +157,18 @@ the 10 MCP tools (`cerefox_search`, `cerefox_ingest`, `cerefox_get_document`,
 ## Common commands
 
 ```bash
-cerefox search "second brain"                       # hybrid (FTS + semantic)
-cerefox ingest notes.md --project "Personal"        # add a doc
-cerefox list-projects                               # discover projects
-cerefox metadata-search --metadata-filter '{"type":"decision-log"}'
-cerefox get-audit-log --since 2026-05-01            # immutable history
-cerefox doctor                                      # diagnose your install
-cerefox upgrade                                     # alias for self-update
+cerefox search "second brain"                          # hybrid (FTS + semantic)
+cerefox document ingest notes.md --project "Personal"  # add a doc
+cerefox project list                                   # discover projects
+cerefox metadata search --metadata-filter '{"type":"decision-log"}'
+cerefox audit list --since 2026-05-01                  # immutable history
+cerefox doctor                                         # diagnose your install
+cerefox upgrade                                        # alias for self-update
 ```
 
-Run `cerefox --help` for the full command surface (28 subcommands grouped
-by category).
+Run `cerefox --help` for the full command surface — a resource-verb shape
+(`document …`, `project …`, `metadata …`, `server …`) plus flat commands
+like `search` and the lifecycle verbs.
 
 ---
 
@@ -181,8 +179,8 @@ MCP client) gives your AI agent full access to the knowledge base on
 its own. The rest of the `cerefox` CLI is useful for:
 
 - **One-off shell operations**: search, ingest, list, audit-log.
-- **Power-user workflows**: `cerefox ingest-dir ./meeting-notes`,
-  `cerefox metadata-search --metadata-filter …`, `cerefox backup`.
+- **Power-user workflows**: `cerefox document ingest-dir ./meeting-notes`,
+  `cerefox metadata search --metadata-filter …`, `cerefox backup create`.
 - **Setup + diagnostics**: `cerefox init`, `cerefox doctor`,
   `cerefox configure-agent`, `cerefox self-update`.
 - **Agents via local Bash tool**: some coding agents prefer running
@@ -196,7 +194,7 @@ its own. The rest of the `cerefox` CLI is useful for:
 - **Architecture overview**: [`CLAUDE.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/CLAUDE.md)
 - **Setup guides**: [`docs/guides/`](https://github.com/fstamatelopoulos/cerefox/tree/main/docs/guides)
 - **Migration from v0.4.x**: [`docs/guides/migration-v0.5.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/migration-v0.5.md)
-- **For AI agents using Cerefox**: [`AGENT_GUIDE.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/AGENT_GUIDE.md), [`AGENT_QUICK_REFERENCE.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/AGENT_QUICK_REFERENCE.md), or run `cerefox docs --list`.
+- **For AI agents using Cerefox**: [`AGENT_GUIDE.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/AGENT_GUIDE.md), [`AGENT_QUICK_REFERENCE.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/AGENT_QUICK_REFERENCE.md), or run `cerefox guides list`.
 - **Changelog**: [`CHANGELOG.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/CHANGELOG.md)
 
 ---

package/dist/bin/cerefox.js

@@ -7184,7 +7184,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "0.9.1";
+var PKG_VERSION = "0.9.3";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js
@@ -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. 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 HELP_FULL = '# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for "How AI Agents Use Cerefox" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |\n| `cerefox_get_document` | Get full document by ID | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find docs by metadata (no text query) | `metadata_filter` (required), `include_content`, `updated_since` |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc\'s project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., "Claude Code", "archiver"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch("topic") -> find doc [id: abc123] -> get_document(abc123) -> modify ->\ningest(title="Same Title", content="...", document_id="abc123", author="my-agent")\n```\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch("topic") -> find doc -> modify ->\ningest(title="Same Title", content="...", update_if_exists=true, author="my-agent")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03-28T00:00:00Z")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` |\n| `cerefox_set_document_projects` | _MCP-only; a CLI command will be added in a future release. Until then, run via MCP if available._ |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n', 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. 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.'
+    "CLI fallback (when MCP is unavailable)": '## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` |\n| `cerefox_set_document_projects` | _MCP-only; a CLI command will be added in a future release. Until then, run via MCP if available._ |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.'
   };
   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)"];
 });
@@ -40005,106 +40005,173 @@ 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() {
+function isHidden(cmd) {
+  return Boolean(cmd._hidden);
+}
+function visibleSubs(cmd) {
+  return cmd.commands.filter((c2) => c2.name() !== "help" && !isHidden(c2));
+}
+function longFlags(cmd) {
+  const flags = [];
+  for (const opt of cmd.options) {
+    if (opt.long)
+      flags.push(opt.long);
+  }
+  return flags;
+}
+function collectNodes() {
   const program2 = buildProgram();
-  const subcommands = [];
-  for (const cmd of program2.commands) {
-    if (cmd.name() === "help")
-      continue;
-    const flags = [];
-    for (const opt of cmd.options) {
-      const long = opt.long;
-      if (long)
-        flags.push(long);
-    }
-    flags.push("--help");
-    subcommands.push({ name: cmd.name(), flags });
-  }
-  subcommands.sort((a, b) => a.name.localeCompare(b.name));
-  return { subcommands };
-}
-function bashScript(info2) {
-  const cmdNames = info2.subcommands.map((s) => s.name).join(" ");
-  const cases = info2.subcommands.map((s) => `        ${s.name})
-            opts="${s.flags.join(" ")}"
-            ;;`).join(`
+  const nodes = [];
+  const walk = (cmd, path) => {
+    const subs = visibleSubs(cmd);
+    const candidates = [...subs.map((s) => s.name()), ...longFlags(cmd), "--help"];
+    nodes.push({ path, candidates });
+    for (const s of subs) {
+      walk(s, path === "" ? s.name() : `${path} ${s.name()}`);
+    }
+  };
+  walk(program2, "");
+  nodes.sort((a, b) => a.path.localeCompare(b.path));
+  return nodes;
+}
+function bashScript(nodes) {
+  const candCases = nodes.map((n) => `        "${n.path}") echo "${n.candidates.join(" ")}" ;;`).join(`
 `);
+  const pathPatterns = nodes.filter((n) => n.path !== "").map((n) => `"${n.path}"`).join("|");
   return `# Cerefox bash completion. Source from ~/.bashrc:
 #   source <(cerefox completion bash)
 #
+_cerefox_candidates() {
+    case "$1" in
+${candCases}
+        *) echo "--help" ;;
+    esac
+}
+_cerefox_is_path() {
+    case "$1" in
+        ${pathPatterns}) return 0 ;;
+        *) return 1 ;;
+    esac
+}
 _cerefox_completion() {
-    local cur prev cmd opts
+    local cur path trial w i
     COMPREPLY=()
     cur="\${COMP_WORDS[COMP_CWORD]}"
-    cmd="\${COMP_WORDS[1]}"
-    if [ "\${COMP_CWORD}" -eq 1 ]; then
-        opts="${cmdNames}"
-        COMPREPLY=( $(compgen -W "\${opts}" -- "\${cur}") )
-        return 0
-    fi
-    case "\${cmd}" in
-${cases}
-        *)
-            opts="--help"
-            ;;
-    esac
-    COMPREPLY=( $(compgen -W "\${opts}" -- "\${cur}") )
+    path=""
+    i=1
+    while [ "$i" -lt "\${COMP_CWORD}" ]; do
+        w="\${COMP_WORDS[$i]}"
+        case "$w" in -*) break ;; esac
+        if [ -z "$path" ]; then trial="$w"; else trial="$path $w"; fi
+        if _cerefox_is_path "$trial"; then
+            path="$trial"; i=$((i + 1))
+        else
+            break
+        fi
+    done
+    COMPREPLY=( $(compgen -W "$(_cerefox_candidates "$path")" -- "$cur") )
     return 0
 }
 complete -F _cerefox_completion cerefox
 `;
 }
-function zshScript(info2) {
-  const cmdNames = info2.subcommands.map((s) => `'${s.name}'`).join(" ");
-  const cases = info2.subcommands.map((s) => {
-    const flagList = s.flags.map((f) => `'${f}'`).join(" ");
-    return `        ${s.name}) flags=(${flagList}) ;;`;
-  }).join(`
+function zshScript(nodes) {
+  const candCases = nodes.map((n) => `        "${n.path}") REPLY="${n.candidates.join(" ")}" ;;`).join(`
 `);
+  const pathPatterns = nodes.filter((n) => n.path !== "").map((n) => `"${n.path}"`).join("|");
   return `#compdef cerefox
 # Cerefox zsh completion. Save and source from ~/.zshrc:
 #   source <(cerefox completion zsh)
 #
-_cerefox() {
-    local -a cmds flags
-    cmds=(${cmdNames})
-    if (( CURRENT == 2 )); then
-        _values 'cerefox subcommand' $cmds
-        return
-    fi
-    case "$words[2]" in
-${cases}
-        *) flags=() ;;
+_cerefox_candidates() {
+    case "$1" in
+${candCases}
+        *) REPLY="--help" ;;
+    esac
+}
+_cerefox_is_path() {
+    case "$1" in
+        ${pathPatterns}) return 0 ;;
+        *) return 1 ;;
     esac
-    _values 'flag' $flags
+}
+_cerefox() {
+    local path trial w i REPLY
+    path=""
+    i=2
+    while (( i < CURRENT )); do
+        w="\${words[i]}"
+        case "$w" in -*) break ;; esac
+        if [[ -z "$path" ]]; then trial="$w"; else trial="$path $w"; fi
+        if _cerefox_is_path "$trial"; then
+            path="$trial"; (( i++ ))
+        else
+            break
+        fi
+    done
+    _cerefox_candidates "$path"
+    compadd -- \${=REPLY}
 }
 compdef _cerefox cerefox
 `;
 }
-function fishScript(info2) {
-  const lines = [
-    "# Cerefox fish completion. Save to ~/.config/fish/completions/cerefox.fish",
-    ""
-  ];
-  for (const sub of info2.subcommands) {
-    lines.push(`complete -c cerefox -n '__fish_use_subcommand' -a '${sub.name}'`);
-    for (const flag of sub.flags) {
-      lines.push(`complete -c cerefox -n '__fish_seen_subcommand_from ${sub.name}' -l '${flag.replace(/^--/, "")}'`);
-    }
-  }
-  return lines.join(`
-`) + `
+function fishScript(nodes) {
+  const candCases = nodes.map((n) => `        case "${n.path}"
+            echo "${n.candidates.join(" ")}"`).join(`
+`);
+  const pathList = nodes.filter((n) => n.path !== "").map((n) => `"${n.path}"`).join(" ");
+  return `# Cerefox fish completion. Save to ~/.config/fish/completions/cerefox.fish
+function __cerefox_candidates
+    switch "$argv[1]"
+${candCases}
+        case '*'
+            echo "--help"
+    end
+end
+function __cerefox_is_path
+    for p in ${pathList}
+        if test "$argv[1]" = "$p"
+            return 0
+        end
+    end
+    return 1
+end
+function __cerefox_complete
+    set -l tokens (commandline -opc)
+    set -l path ""
+    set -l i 2
+    while test $i -le (count $tokens)
+        set -l w $tokens[$i]
+        if string match -q -- '-*' $w
+            break
+        end
+        set -l trial
+        if test -z "$path"
+            set trial $w
+        else
+            set trial "$path $w"
+        end
+        if __cerefox_is_path "$trial"
+            set path "$trial"
+            set i (math $i + 1)
+        else
+            break
+        end
+    end
+    string split ' ' -- (__cerefox_candidates "$path")
+end
+complete -c cerefox -f -a '(__cerefox_complete)'
 `;
 }
 function scriptFor(shell) {
-  const info2 = collectCompletionInfo();
+  const nodes = collectNodes();
   switch (shell) {
     case "bash":
-      return bashScript(info2);
+      return bashScript(nodes);
     case "zsh":
-      return zshScript(info2);
+      return zshScript(nodes);
     case "fish":
-      return fishScript(info2);
+      return fishScript(nodes);
   }
 }
 function detectShell() {
@@ -43118,13 +43185,13 @@ var restoreCursor = terminal ? onetime_default(() => {
 var restore_cursor_default = restoreCursor;
 
 // ../../node_modules/.bun/cli-cursor@5.0.0/node_modules/cli-cursor/index.js
-var isHidden = false;
+var isHidden2 = false;
 var cliCursor = {};
 cliCursor.show = (writableStream = process5.stderr) => {
   if (!writableStream.isTTY) {
     return;
   }
-  isHidden = false;
+  isHidden2 = false;
   writableStream.write("\x1B[?25h");
 };
 cliCursor.hide = (writableStream = process5.stderr) => {
@@ -43132,14 +43199,14 @@ cliCursor.hide = (writableStream = process5.stderr) => {
     return;
   }
   restore_cursor_default();
-  isHidden = true;
+  isHidden2 = true;
   writableStream.write("\x1B[?25l");
 };
 cliCursor.toggle = (force, writableStream) => {
   if (force !== undefined) {
-    isHidden = force;
+    isHidden2 = force;
   }
-  if (isHidden) {
+  if (isHidden2) {
     cliCursor.show(writableStream);
   } else {
     cliCursor.hide(writableStream);
@@ -45716,7 +45783,7 @@ import { homedir as homedir5 } from "node:os";
 import { join as join8 } from "node:path";
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "0.9.1";
+var EF_VERSION = "0.9.3";
 
 // src/cli/util/checks.ts
 init_config();