npm - @cerefox/memory - Versions diffs - 0.9.2 → 0.9.4 - Mend

@cerefox/memory 0.9.2 → 0.9.4

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 (21) hide show

package/AGENT_GUIDE.md +33 -3
package/AGENT_QUICK_REFERENCE.md +1 -1
package/README.md +25 -27
package/dist/bin/cerefox.js +4 -4
package/dist/frontend/assets/{index-CAp2_lFX.js → index-D0zn7Zv2.js} +29 -29
package/dist/frontend/assets/index-D0zn7Zv2.js.map +1 -0
package/dist/frontend/index.html +1 -1
package/dist/server-assets/_shared/ef-meta/index.ts +1 -1
package/dist/server-assets/_shared/mcp-tools/get-help-content.ts +2 -2
package/docs/guides/access-paths.md +2 -2
package/docs/guides/cli.md +43 -34
package/docs/guides/configuration.md +2 -2
package/docs/guides/connect-agents.md +3 -3
package/docs/guides/operational-cost.md +33 -9
package/docs/guides/ops-scripts.md +1 -1
package/docs/guides/quickstart.md +1 -1
package/docs/guides/response-limits.md +1 -1
package/docs/guides/setup-cloud-run.md +7 -0
package/docs/guides/upgrading.md +11 -11
package/package.json +1 -1
package/dist/frontend/assets/index-CAp2_lFX.js.map +0 -1

package/dist/frontend/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/png" href="/app/cerefox_icon.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Cerefox</title>
-    <script type="module" crossorigin src="/app/assets/index-CAp2_lFX.js"></script>
+    <script type="module" crossorigin src="/app/assets/index-D0zn7Zv2.js"></script>
     <link rel="stylesheet" crossorigin href="/app/assets/index-DoDJGRih.css">
   </head>
   <body>

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

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

package/dist/server-assets/_shared/mcp-tools/get-help-content.ts CHANGED Viewed

@@ -11,7 +11,7 @@
  * docs/specs/polish-and-distribution-design.md §10d.
  */
-export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for \"How AI Agents Use Cerefox\" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |\n| `cerefox_get_document` | Get full document by ID | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find docs by metadata (no text query) | `metadata_filter` (required), `include_content`, `updated_since` |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\", author=\"my-agent\")\n```\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true, author=\"my-agent\")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); 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";
+export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for \"How AI Agents Use Cerefox\" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |\n| `cerefox_get_document` | Get full document by ID | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find docs by metadata (no text query) | `metadata_filter` (required), `include_content`, `updated_since` |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\", author=\"my-agent\")\n```\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true, author=\"my-agent\")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search \"<q>\" --requestor \"<your-name>\"` |\n| `cerefox_ingest` (paste) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf '...' \\| cerefox document ingest --paste --title \"<t>\" --document-id \"<uuid>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor \"<your-name>\"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor \"<your-name>\"` |\n| `cerefox_list_projects` | `cerefox project list --requestor \"<your-name>\"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor \"<your-name>\"` |\n| `cerefox_set_document_projects` | _MCP-only; a CLI command will be added in a future release. Until then, run via MCP if available._ |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n";
 /** Sections keyed by their H2 heading text (lower-cased for matching). */
 export const HELP_SECTIONS: Record<string, string> = {
@@ -20,7 +20,7 @@ export const HELP_SECTIONS: Record<string, string> = {
   "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.",
 };
 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 Viewed

@@ -227,8 +227,8 @@ If you're building tooling that uses the CLI (Path C) or any MCP/Edge Function p
 ### CLI delete-doc — interactive vs scripted
-`cerefox document delete` prompts for confirmation by default (since `click.confirm` requires
-a TTY, an agent's Bash tool will get an abort instead of accidentally deleting). Agents
+`cerefox document delete` prompts for confirmation by default (the prompt requires a TTY, so
+an agent's Bash tool gets an abort instead of accidentally deleting). Agents
 that legitimately need to soft-delete must pass `--yes` *and* set `--author` /
 `--author-type` so the audit log captures who acted:

package/docs/guides/cli.md CHANGED Viewed

@@ -30,7 +30,7 @@ cerefox document ingest --paste --title "<title>" [OPTIONS]   # stdin
 **Options**:
-> **Flag naming**: every flag below matches its MCP-tool parameter name (e.g. `project_name` → `--project-name`). Short forms (`--project`, `-p`) remain as aliases — the long form is the canonical name shown in `--help`.
+> **Flag naming**: every flag below matches its MCP-tool parameter name (e.g. `project_name` → `--project-name`). Common flags also have a single-letter short form (`-p`, `-c`, `-f`, `-m`, `-u`, `-a`, `-r`, `-l`, `-t`, `-i`); the long form is canonical. There are **no** long-form aliases such as `--project`, `--count`, `--filter`, `--update`, or `--version` — use the canonical long name or its single-letter short form.
 | Flag (canonical) | Aliases | Type | Default | Description |
 |---|---|---|---|---|
@@ -38,8 +38,8 @@ cerefox document ingest --paste --title "<title>" [OPTIONS]   # stdin
 | `--project-name` | `--project`, `-p` | str | _none_ | Project name to assign the document to (created if missing). |
 | `--paste` | — | flag | off | Read markdown from stdin. Requires `--title`. |
 | `--metadata` | `-m` | JSON | `{}` | Extra metadata as a JSON object, e.g. `'{"tags":["work"]}'`. |
-| `--update-if-exists` | `--update` | flag | off | Title/source-path-based fallback update. Mutually exclusive with `--document-id`. |
-| `--document-id` | — | UUID | _none_ | Deterministic ID-based update. Errors if the document doesn't exist. |
+| `--update-if-exists` | `-u` | flag | off | Title/source-path-based fallback update. Mutually exclusive with `--document-id`. |
+| `--document-id` | `-i` | UUID | _none_ | Deterministic ID-based update. Errors if the document doesn't exist. |
 | `--source` | — | str | `paste` / `file` | Source label recorded on the document. |
 | `--author` | — | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Audit-log author identity. |
 | `--author-type` | — | `user`\|`agent` | `CEREFOX_AUTHOR_TYPE` or `user` | Caller type. Agent writes auto-routed to `pending_review`. |
@@ -82,23 +82,27 @@ cerefox document ingest-dir [OPTIONS] DIRECTORY
 **Options**:
+Walks `DIRECTORY` **recursively** (always — there is no recurse toggle) and ingests every file whose extension is in `--extensions`.
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `--pattern TEXT` | glob | `*.md` | Glob pattern. Examples: `**/*.md`, `*.txt`. |
-| `--project-name TEXT` (alias: `--project`, `-p`) | str | _none_ | Project to assign every document to. |
-| `--recursive / --no-recursive` | flag | `--no-recursive` | Recurse into sub-directories. |
-| `--dry-run` | flag | off | Print files that would be ingested; do nothing. |
-| `--update-if-exists` (alias: `--update`) | flag | off | Update existing documents by source path. |
-| `-m, --metadata TEXT` | JSON | `{}` | JSON metadata applied to every file in the run. |
-| `--author TEXT` | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Audit-log author identity (applies to every write). |
-| `--author-type [user\|agent]` | choice | `CEREFOX_AUTHOR_TYPE` or `user` | Caller type. |
+| `--extensions <list>` (`-e`) | comma list | `.md,.txt` | File extensions to ingest, e.g. `--extensions .md`. |
+| `--project-name <name>` (`-p`) | str | _none_ | Project to assign every document to. |
+| `--update-if-exists` (`-u`) | flag | off | Update existing documents by source path / title. |
+| `--metadata <json>` (`-m`) | JSON | `{}` | JSON metadata applied to every file in the run. |
+| `--source <label>` | str | `cli` | Source label recorded on each document. |
+| `--author <name>` (`-a`) | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Audit-log author identity (applies to every write). |
+| `--author-type <type>` | `user`\|`agent` | `CEREFOX_AUTHOR_TYPE` or `user` | Caller type. |
 **Examples**:
 ```bash
-# Bulk import research notes with shared metadata
-cerefox document ingest-dir ./research-notes --recursive \
+# Bulk import research notes with shared metadata (recurses automatically)
+cerefox document ingest-dir ./research-notes \
   --project-name "research" --metadata '{"type":"research","status":"active"}'
+# Only .md files
+cerefox document ingest-dir ./notes --extensions .md
 # Re-ingest after editing files
 cerefox document ingest-dir ./notes --update-if-exists
 ```
@@ -122,14 +126,16 @@ cerefox search [OPTIONS] QUERY
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `-m, --mode [hybrid\|fts\|semantic]` | choice | `hybrid` | Search mode. |
-| `--match-count INTEGER` (alias: `--count`, `-n`) | int | `10` | Number of results. |
-| `--project-name TEXT` (alias: `--project`, `-p`) | str | _none_ | Limit to a project by name. |
-| `--alpha FLOAT` | float | `0.7` | FTS/semantic weight (hybrid only). |
-| `--min-score FLOAT` | float | `CEREFOX_MIN_SEARCH_SCORE` or `0.50` | Minimum cosine similarity (hybrid/semantic only). |
-| `--metadata-filter TEXT` (alias: `--filter`, `-f`) | JSON | _none_ | JSONB metadata containment filter, e.g. `'{"type":"decision"}'`. |
-| `--only-metadata` | flag | off | Return only document titles + metadata (no chunk content / previews) — a compact listing. |
-| `--requestor TEXT` | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
+| `--mode <mode>` | `docs`\|`hybrid`\|`fts` | `docs` | `docs` = reconstructed documents (recommended); `hybrid` = ranked chunks; `fts` = keyword-only (no embedding / API key needed). |
+| `--match-count <n>` (`-c`) | int | `5` | Number of results. |
+| `--project-name <name>` (`-p`) | str | _none_ | Limit to a project by name. |
+| `--alpha <float>` | float | `0.7` | Semantic weight 0..1 (`docs`/`hybrid`). |
+| `--min-score <float>` | float | `0.5` | Minimum cosine similarity (`docs`/`hybrid`; not applied to `fts`). |
+| `--metadata-filter <json>` (`-f`) | JSON | _none_ | JSONB metadata containment filter, e.g. `'{"type":"decision"}'`. |
+| `--max-bytes <n>` | int | `200000` | Response size budget in bytes. |
+| `--only-metadata` | flag | off | List matching docs (id, score, chunks, chars) without content — a compact listing. |
+| `--requestor <name>` (`-r`) | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
+| `--json` | flag | off | Machine-readable JSON output. |
 **Examples**:
 ```bash
@@ -139,7 +145,7 @@ cerefox search "what we tried" --mode semantic --requestor "claude-code"
 cerefox search "design docs" --only-metadata
 ```
-**Output**: numbered result list with title, score, and 300-char preview per hit. Final line shows total results + bytes.
+**Output**: in `docs` mode (default), each match prints `## Title [id: …] · score · N chunks · M chars · partial|full` followed by the (re)constructed document body; `hybrid`/`fts` print ranked chunks. A truncation note appears if the byte budget is hit.
 **Exit codes**: `0` on success. Note: as of v0.1.17, the CLI logs usage in a try/except so a usage-logging error does not affect the user-visible output (closes the failure mode that produced cerefox#27).
@@ -160,8 +166,9 @@ cerefox document get [OPTIONS] DOCUMENT_ID
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `--version-id TEXT` (alias: `--version`) | UUID | _none_ (current) | Archived version UUID — get from `cerefox document version list`. |
-| `--requestor TEXT` | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
+| `--version-id <uuid>` | UUID | _none_ (current) | Archived version UUID — get from `cerefox document version list`. |
+| `--requestor <name>` (`-r`) | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
+| `--json` | flag | off | Machine-readable JSON output. |
 **Examples**:
 ```bash
@@ -189,8 +196,9 @@ cerefox document list [OPTIONS]
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `--project-name TEXT` (alias: `--project`, `-p`) | str | _none_ | Filter by project ID or name. |
-| `-n, --limit INTEGER` | int | `20` | Max rows. |
+| `--project <name>` (`-p`) | str | _none_ | Filter by project name. |
+| `--limit <n>` (`-l`) | int | `100` | Max rows. |
+| `--json` | flag | off | Machine-readable JSON output. |
 **Output**: tabular `id | chunk_count | total_chars | title` listing. CLI-only — there is no MCP equivalent.
@@ -347,8 +355,8 @@ cerefox metadata search --metadata-filter '<json>' [OPTIONS]
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `--metadata-filter TEXT` (alias: `--filter`) | JSON | **required** | Metadata filter, e.g. `'{"type":"decision-log"}'`. |
-| `--project-name TEXT` (alias: `--project`) | str | _none_ | Filter by project name. |
+| `--metadata-filter <json>` (`-f`) | JSON | **required** | Metadata filter, e.g. `'{"type":"decision-log"}'`. |
+| `--project-name <name>` (`-p`) | str | _none_ | Filter by project name. |
 | `--updated-since TEXT` | ISO-8601 | _none_ | Documents updated after this timestamp. |
 | `--created-since TEXT` | ISO-8601 | _none_ | Documents created after this timestamp. |
 | `--limit INTEGER` | int | `10` | Max results. |
@@ -413,9 +421,10 @@ cerefox audit list --json --limit 1000 | jq 'select(.author_type == "agent")'
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `-y, --yes` | flag | off | Skip confirmation prompt. Required for non-interactive use (agents, scripts). |
-| `--author` | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Identity recorded in the audit log. |
-| `--author-type` | `user`\|`agent` | `CEREFOX_AUTHOR_TYPE` or `user` | Caller type, recorded in the audit log. |
+| `--yes` | flag | off | Skip confirmation prompt. Required for non-interactive use (agents, scripts). |
+| `--reason <text>` | str | _none_ | Optional reason recorded on the delete audit entry. |
+| `--author <name>` (`-a`) | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Identity recorded in the audit log. |
+| `--author-type <type>` | `user`\|`agent` | `CEREFOX_AUTHOR_TYPE` or `user` | Caller type, recorded in the audit log. |
 **What this command does:**
 - Sets `deleted_at` on the document row. The document stays in the database.
@@ -486,7 +495,7 @@ cerefox config get KEY
 cerefox config set KEY VALUE
 ```
-Used for toggling features at runtime without a redeploy — see [Decision Log Q1 Part 2 — usage tracking opt-in](https://github.com/fstamatelopoulos/cerefox) entry.
+Used for toggling features at runtime without a redeploy — see the "Decision Log Q1 Part 2 — usage tracking opt-in" entry (stored in the Cerefox knowledge base).
 ---
@@ -595,7 +604,7 @@ None outstanding as of v0.1.17 (cerefox#27 — the `cerefox search` NameError
 ### Bulk-import a directory with shared metadata
 ```bash
-cerefox document ingest-dir ./papers --recursive --pattern '*.md' \
+cerefox document ingest-dir ./papers --extensions .md \
   --project-name "literature" \
   --metadata '{"type":"paper","status":"reviewed"}'
 ```
@@ -616,7 +625,7 @@ printf '%s' "$NEW_CONTENT" | cerefox document ingest --paste \
 ### Unattended sync job
 ```bash
 # In a cron job / launchd plist. Set CEREFOX_AUTHOR_NAME=sync-script in env.
-cerefox document ingest-dir ~/notes --recursive --update-if-exists
+cerefox document ingest-dir ~/notes --update-if-exists
 ```
 ### Use the CLI from an agent's Bash tool

package/docs/guides/configuration.md CHANGED Viewed

@@ -80,7 +80,7 @@ The `cerefox-search` and `cerefox-ingest` Supabase Edge Functions handle embeddi
 ### Embedding API retry
-All embedding API calls (Python `CloudEmbedder` and Edge Functions) include automatic retry with exponential backoff for transient failures:
+All embedding API calls (TS embedder and Edge Functions) include automatic retry with exponential backoff for transient failures:
 - **3 attempts** with backoff: 500ms, 1s, 2s
 - **Retried**: HTTP 5xx server errors, network timeouts, connection failures
@@ -125,7 +125,7 @@ The `metadata_filter` search parameter (available in all search modes, all acces
 Access paths:
 - **MCP tool**: `metadata_filter` argument on `cerefox_search`
-- **CLI**: `cerefox search "query" --metadata-filter '{"type": "decision"}'` (alias: `--filter`, `-f`)
+- **CLI**: `cerefox search "query" --metadata-filter '{"type": "decision"}'` (short form: `-f`)
 - **Web UI**: Metadata Filter section (collapsible) in the Knowledge Browser
 - **GPT Actions**: `metadata_filter` field in `searchKnowledgeBase` request body (schema v1.4.0)
 - **HTTP API**: `metadata_filter` JSON key in the `cerefox-search` Edge Function POST body

package/docs/guides/connect-agents.md CHANGED Viewed

@@ -1022,7 +1022,7 @@ If the same content was already ingested (SHA-256 hash match), returns `"skipped
 | `full_content` | string | Reconstructed document content (may be partial — see `is_partial`) |
 | `chunk_count` | integer | Number of chunks in `full_content` |
 | `total_chars` | integer | Full document size in characters (always the whole doc, even when `is_partial` is true) |
-| `is_partial` | boolean | `true` when `full_content` contains only matched chunks + neighbours instead of the complete document. Triggered when the document exceeds the small-to-big threshold (default 40 000 chars). Use `getDocument` to retrieve the full text. |
+| `is_partial` | boolean | `true` when `full_content` contains only matched chunks + neighbours instead of the complete document. Triggered when the document exceeds the small-to-big threshold (default 20 000 chars). Use `getDocument` to retrieve the full text. |
 | `doc_updated_at` | string | ISO 8601 timestamp of the last document update |
 | `version_count` | integer | Number of archived versions (0 if never updated) |
 | `doc_project_ids` | string[] | Project UUIDs the document belongs to |
@@ -1124,7 +1124,7 @@ from the knowledge base.
 ### MCP tool ↔ CLI command mapping
-The agent docs are written around MCP tool names. **CLI flag names match MCP parameter names exactly** (kebab-cased) — short forms like `--project`, `--filter`, `--count`, `--update`, `--version` are accepted as aliases. Full per-flag reference: [`docs/guides/cli.md`](cli.md).
+The agent docs are written around MCP tool names. **CLI flag names match MCP parameter names exactly** (kebab-cased), each with a single-letter short form (`-p`, `-f`, `-c`, `-m`, `-u`, `-a`, `-r`). There are no long-form aliases like `--project` or `--count` — use the canonical long name or its short form. Full per-flag reference: [`docs/guides/cli.md`](cli.md).
 | MCP tool | CLI command |
 |---|---|
@@ -1344,7 +1344,7 @@ recommended RPC for agent use** — agents receive complete notes, not isolated
 | `p_alpha` | FLOAT | 0.7 | Semantic weight |
 | `p_project_id` | UUID | null | Filter by project |
 | `p_min_score` | FLOAT | 0.0 | Minimum cosine similarity |
-| `p_small_to_big_threshold` | INT | 40000 | Documents larger than this return matched chunks + neighbours instead of the full document. Set to `0` to always return full content. Change the DEFAULT in `rpcs.sql` to apply server-wide. |
+| `p_small_to_big_threshold` | INT | 20000 | Documents larger than this return matched chunks + neighbours instead of the full document. Set to `0` to always return full content. Change the DEFAULT in `rpcs.sql` to apply server-wide. |
 | `p_context_window` | INT | 1 | Neighbour chunks on each side of each matched chunk. `1` → up to 3 contiguous chunks per hit. `0` → matched chunks only. |
 Returns: `document_id`, `doc_title`, `doc_source`, `doc_metadata`, `doc_project_ids`,

package/docs/guides/operational-cost.md CHANGED Viewed

@@ -14,7 +14,7 @@ and gives rough estimates for two common deployment scenarios.
 | Component | Cost driver |
 |-----------|-------------|
-| **Supabase** | Database storage and API calls. The free tier is generous and covers a typical personal knowledge base indefinitely. |
+| **Supabase** | Database storage and **Edge Function invocations** — the latter is the binding free-tier limit for cloud / remote-MCP usage (see below). Direct Data API requests are unlimited. The free tier covers typical personal use indefinitely. |
 | **OpenAI embeddings** | Charged per token when ingesting content or running searches. The default model (`text-embedding-3-small`) is among the cheapest available. |
 | **Cloud Run** (optional) | Compute for the web UI if you deploy it to GCP rather than running it locally. |
 | **Artifact Registry** (optional) | Docker image storage on GCP, if you deploy to Cloud Run. |
@@ -46,14 +46,38 @@ The web UI's built-in search bar and document browser make no embedding calls.
 ### Supabase free tier limits
-Supabase's free tier is sufficient for a personal knowledge base. Key limits as of early 2026:
-- 500 MB database storage (text + vectors; a typical knowledge base is well under this)
-- 50,000 API calls/month (for queries via supabase-py)
-- 2 active projects
-If you exceed these limits, Supabase's Pro plan is the next step — check
-[supabase.com/pricing](https://supabase.com/pricing) for current rates.
+Supabase's free tier is sufficient for a personal knowledge base. Current limits
+(verify at [supabase.com/pricing](https://supabase.com/pricing)):
+- **500 MB database storage** — text + 768-dim vectors; a typical personal KB is well under this.
+- **500,000 Edge Function invocations / month** — *the limit that matters most for Cerefox* (see below).
+- **5 GB egress / month**.
+- **2 active projects**, paused after ~1 week of inactivity (a single request unpauses).
+- **Unlimited Data API (REST/PostgREST) requests** on all plans — direct database reads/writes are not metered.
+(Supabase's "50,000 monthly active users" figure is an **Auth** limit; Cerefox
+doesn't use Supabase Auth, so it never applies.)
+#### Edge Function invocations are the real free-tier limiter
+Most of Cerefox runs against the **Data API** (unlimited), but the **remote** agent
+paths go through **Edge Functions**, which the free tier caps at 500,000/month:
+| Access path | Uses Edge Functions? | Cost per call |
+|---|---|---|
+| Remote MCP (`cerefox-mcp`) — Claude/Cursor/etc. over HTTP | **Yes** | ~1 invocation per agent tool call (calls the RPC directly — no fan-out) |
+| GPT Actions (Custom GPT) → primitive Edge Functions | **Yes** | 1 invocation per action call |
+| `cerefox doctor` | **Yes** | several (it calls the `/version?peers=true` aggregator) |
+| **Local stdio MCP (`cerefox mcp`)** | **No** | 0 — talks to the Data API directly |
+| `cerefox` CLI and `cerefox web` (web UI) | **No** | 0 — Data API directly |
+500K/month is generous for a single human-driven agent. But **automated or
+high-frequency agents on the remote path** can approach it. The lever: point those
+agents at the **local stdio MCP server** (`cerefox mcp`) instead of the remote Edge
+Function — it exposes the identical 10 tools, talks to the Data API directly, and
+costs **zero** Edge Function invocations (bonus: lower latency, and it works offline
+against a reachable database). If you do exceed the free EF quota, Supabase's Pro
+plan ($25/mo, 2M invocations included) is the next step.
 ---

package/docs/guides/ops-scripts.md CHANGED Viewed

@@ -2,7 +2,7 @@
 Reference guide for the operational scripts in `scripts/`. Run these from the project root.
-> Looking for `cerefox <subcommand>` reference (ingest, search, get-doc, etc.)? See [`docs/guides/cli.md`](cli.md). This guide covers the `scripts/` directory only.
+> Looking for `cerefox <subcommand>` reference (`document ingest`, `search`, `document get`, etc.)? See [`docs/guides/cli.md`](cli.md). This guide covers the `scripts/` directory only.
 ## Who this guide is for

package/docs/guides/quickstart.md CHANGED Viewed

@@ -100,7 +100,7 @@ for the legacy Python MCP fallback. See [`setup-local.md`](setup-local.md) and
 ## What's next
 - **Ingest your notes**: `cerefox document ingest my-notes.md`, or
-  `cerefox document ingest-dir ./notes/ --recursive`
+  `cerefox document ingest-dir ./notes/` (recurses into sub-directories automatically)
 - **Search from the CLI**: `cerefox search "your query"`
 - **Discover all commands**: `cerefox --help`
 - **Run the web UI**: `cerefox web` (TypeScript — Hono backend + React SPA); see [`setup-local.md`](setup-local.md)

package/docs/guides/response-limits.md CHANGED Viewed

@@ -133,7 +133,7 @@ contributions compact. The response size limit then governs the total across all
 documents.
 See `docs/guides/configuration.md` → "RPC-level retrieval parameters" to change the
-threshold (it is a SQL DEFAULT in `rpcs.sql`, changed via `db_deploy.py`).
+threshold (it is a SQL DEFAULT in `rpcs.sql`, changed via `cerefox server deploy`).
 ---

package/docs/guides/setup-cloud-run.md CHANGED Viewed

@@ -1,5 +1,12 @@
 # Google Cloud Run Deployment
+> **⚠ Aspirational guidance — not yet tested end-to-end.** This deployment path
+> has not been validated against a live Cloud Run deploy. Treat it as a starting
+> point / design sketch rather than a verified runbook; expect to adapt the
+> `Dockerfile`, ports, and env wiring, and please report back what worked. For
+> paths we actively test, see `setup-supabase.md` (server side) and
+> `setup-local.md`.
 Deploy the Cerefox web UI to Google Cloud Run for a lightweight, serverless hosting option. This guide uses Supabase (free tier) for the database.
 > **Note (v0.9):** The Cerefox web UI is now the TypeScript server (`cerefox web` — Hono

package/docs/guides/upgrading.md CHANGED Viewed

@@ -47,7 +47,7 @@ bun scripts/db_migrate.ts
 bun scripts/db_deploy.ts
 # 4. Build the web UI
-cd frontend && npm install && npm run build && cd ..
+cd frontend && bun install && bun run build && cd ..
 # 5. Deploy Edge Functions (if using Supabase-hosted)
 #    Run from the project root (where supabase/ directory is)
@@ -172,10 +172,10 @@ the new code does **not** apply it. After `git pull`, step 4 of the standard
 checklist (redeploy RPCs) is mandatory, not optional:
 ```bash
-uv run python scripts/db_deploy.py
+bun scripts/db_deploy.ts   # or: cerefox server deploy
 ```
-`db_deploy.py` is idempotent (`CREATE OR REPLACE FUNCTION`) and safe to
+`db_deploy.ts` is idempotent (`CREATE OR REPLACE FUNCTION`) and safe to
 re-run. **If you skip this step, searches for any title containing `-`
 (e.g. "Job Hunting - Opportunity Index", `setup-supabase`) will continue
 to return zero results until the RPCs are redeployed.** This is the
@@ -202,7 +202,7 @@ rationale lives in [`docs/solution-design.md` §5.2](../solution-design.md#52-ti
 - Drops the `GENERATED ALWAYS AS` expression on `cerefox_chunks.fts` (it can't cross-reference `cerefox_documents.title`)
 - Adds `cerefox_update_chunk_fts(p_document_id, p_new_title)` RPC for title-change FTS refresh
-Both are applied automatically by `db_migrate.py` (step 3). After the migration, also run `db_deploy.py` (step 4) to update the RPC definitions.
+Both are applied automatically by `bun scripts/db_migrate.ts` (step 3). After the migration, also run `bun scripts/db_deploy.ts` (step 4) to update the RPC definitions.
 **Redeploy Edge Functions**: `cerefox-ingest` and `cerefox-mcp` now prepend the document title to chunk embedding inputs. Redeploy both:
@@ -219,14 +219,14 @@ To upgrade existing chunks:
 ```bash
 # Preview what would be reindexed (no changes made)
-uv run python scripts/reindex_all.py --dry-run
+cerefox server reindex --all --dry-run
 # Reindex all chunks (re-embeds with title prefix, updates FTS)
 # Uses 50 chunks per API call by default; lower --batch if you hit rate limits
-uv run python scripts/reindex_all.py
-# Or run directly via the CLI (same effect)
 cerefox server reindex --all
+# Or run the contributor script directly (same effect)
+bun scripts/reindex_all.ts --all
 ```
 The reindex is **resumable**: if interrupted, re-running it skips chunks already embedded with the current model. Archived chunks (historical versions) are not reindexed -- they are not searched.
@@ -240,8 +240,8 @@ Cost estimate: ~$0.01-0.05 for a typical personal knowledge base (a few thousand
 - `0007_usage_log_requestor.sql` -- renames `reader` column to `requestor` in `cerefox_usage_log`
   and updates all 3 usage RPCs. Non-destructive (existing data preserved).
-Both are applied automatically by `db_migrate.py` (step 3 above). After migrations, also
-redeploy RPCs via `db_deploy.py` (step 4) to update the canonical function definitions.
+Both are applied automatically by `bun scripts/db_migrate.ts` (step 3 above). After migrations, also
+redeploy RPCs via `bun scripts/db_deploy.ts` (step 4) to update the canonical function definitions.
 **New REST API endpoints**: `/api/v1/usage-log`, `/api/v1/usage-log/export.csv`,
 `/api/v1/usage-log/summary`, `/api/v1/config/{key}`.
@@ -299,7 +299,7 @@ MCP clients pick up new tools automatically on the next connection.
 ### Upgrading to v0.1.4+ (from v0.1.0-v0.1.3)
-**Versioning schema**: Migration `0003_add_document_versions.sql` adds the `cerefox_document_versions` table and `version_id` column on `cerefox_chunks`. This is applied automatically by `db_migrate.py`.
+**Versioning schema**: Migration `0003_add_document_versions.sql` adds the `cerefox_document_versions` table and `version_id` column on `cerefox_chunks`. This is applied automatically by `bun scripts/db_migrate.ts`.
 ### Upgrading to v0.1.1+ (from v0.1.0)

package/package.json CHANGED Viewed

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