@cerefox/memory 0.5.3 → 0.6.0

package/docs/guides/migration-v0.5.md

@@ -11,8 +11,9 @@ v0.5.3), and the Python `cerefox` → TS `cerefox` migration path.
 | Never used Cerefox before | [`quickstart.md`](quickstart.md) first, then come back here only if you hit a `.env` / config question |
 | Python `cerefox` (any version through v0.5.x) | "What changed" → "Install paths" → "v0.5.3 migrated `.env`" sections below |
 | `@cerefox/memory` v0.4.x (npm) | "Upgrading an existing MCP client config" → "v0.5.2 fixed the soft wrapper" → "v0.5.3 migrated `.env`" |
-| `@cerefox/memory` v0.5.0 or v0.5.1 (npm) | "v0.5.2 fixed the soft wrapper" + "v0.5.3 migrated `.env`" |
-| `@cerefox/memory` v0.5.2 (npm) | "v0.5.3 migrated `.env`" — the rest is unchanged |
+| `@cerefox/memory` v0.5.0 or v0.5.1 (npm) | "v0.5.2 fixed the soft wrapper" + "v0.5.3 migrated `.env`" + "v0.5.4 fixed configure-agent claude-code" |
+| `@cerefox/memory` v0.5.2 (npm) | "v0.5.3 migrated `.env`" + "v0.5.4 fixed configure-agent claude-code" |
+| `@cerefox/memory` v0.5.3 (npm) | **"v0.5.4 fixed configure-agent claude-code"** — re-run configure-agent |
 
 > Looking for `migration-v0.4.md`? It's been demoted to a historical
 > record (the bin names it documents no longer exist). Everything you
@@ -272,6 +273,135 @@ and skips the migration prompt.
 
 ---
 
+## v0.5.4 fixed `cerefox configure-agent --tool claude-code`
+
+**If you ran `cerefox configure-agent --tool claude-code` on any version
+from v0.5.0 through v0.5.3, Claude Code did not actually pick up the
+config.** The writer wrote to `~/.claude/mcp.json` — a path Claude Code
+doesn't read. Claude Code's user-scope MCP servers live in
+**`~/.claude.json`** (a dot-file in `$HOME`) under the `.mcpServers` key.
+
+The bug went unnoticed because `cerefox doctor` was scanning the same
+wrong path — both surfaces were consistently lying.
+
+### What v0.5.4 changed
+
+- **`configure-agent --tool claude-code`** now shells out to Claude Code's
+  own `claude mcp add --scope user` CLI. Claude Code manages its own
+  config schema; delegating is future-proof. Requires the `claude` CLI
+  on PATH (fair assumption — you're configuring it).
+- Before invoking the delegated CLI, the writer takes a defensive backup
+  of `~/.claude.json` to `~/.claude.json.pre-cerefox.bak`.
+- **`cerefox doctor`** now scans `~/.claude.json` for a `mcpServers.cerefox`
+  entry (not the orphaned `~/.claude/mcp.json` from the bug window).
+- **`--tool claude-desktop` is unchanged** — Claude Desktop has no CLI
+  helper, so its writer remains direct-file-write.
+
+### What you need to do
+
+Anyone who ran `configure-agent --tool claude-code` on v0.5.0–v0.5.3:
+
+```bash
+# 1. Upgrade
+bun update -g @cerefox/memory      # or: npm update -g @cerefox/memory
+
+# 2. (Optional) Remove the orphaned file the buggy versions wrote.
+#    It does nothing — Claude Code never read it. Safe to delete.
+rm -f ~/.claude/mcp.json
+
+# 3. Re-run configure-agent to write the config at the correct path.
+cerefox configure-agent --tool claude-code
+
+# 4. Verify
+claude mcp list                    # should now show 'cerefox'
+cerefox doctor                     # 'mcp clients' should list 'Claude Code (user)'
+
+# 5. Start a fresh Claude Code session — the cerefox tools appear.
+```
+
+Running sessions cache the MCP server list at startup, so an
+**already-open Claude Code session won't pick up the new server**.
+Open a new session.
+
+### `--config-path FILE` override (advanced)
+
+If you pass `--config-path FILE` explicitly, configure-agent does a
+direct-write to FILE instead of shelling out — preserves the v0.5.0–v0.5.3
+test path and works for power users who want a specific file location.
+
+---
+
+## v0.6.0 moved the web server to TypeScript
+
+**TL;DR**: `cerefox web` from the npm package now boots an in-process
+Hono server (TypeScript on Bun) instead of pointing you at
+`uv run cerefox web`. Three ingestion endpoints temporarily return
+503; the web UI shows a friendly toast pointing at the working CLI
+fallback. Full ingestion support lands in v0.7.
+
+### What's new
+
+- **`cerefox web` works from npm.** No clone, no `uv`. `npm install
+  -g @cerefox/memory` followed by `cerefox web` boots the local web
+  UI + JSON API on `http://127.0.0.1:8000/`.
+- **React SPA bundled** into `@cerefox/memory`. The web UI is part
+  of the npm tarball; you get the same UI Python's `uv run cerefox
+  web` serves, no extra install.
+- **Configure-agent grew Phase 2 writers**: `cerefox configure-agent
+  --tool cursor` / `--tool codex` / `--tool gemini` join the existing
+  `--tool claude-code` / `--tool claude-desktop`. Codex's config is
+  TOML (`~/.codex/config.toml`); the rest are JSON.
+
+### The 503-ingestion-stubs window
+
+Three endpoints return 503 with `{error: "Ingestion lands in v0.7",
+see: <url>, note: …}`:
+
+- `POST /api/v1/ingest` (paste)
+- `POST /api/v1/ingest/file` (file upload)
+- `POST /api/v1/documents/{id}/upload` (replace)
+
+The web UI detects this and shows a yellow Mantine toast — no scary
+error banner. `/documents/{id}/edit` also returns 503 if you try to
+change content (it compares SHA-256 hashes against the stored
+`content_hash` — title / metadata / project changes work fine).
+
+### Working fallbacks during the v0.6 window
+
+Both fully functional, no behaviour change:
+
+```bash
+# Option A — npm-installed CLI hits the deployed Edge Function.
+cerefox ingest my-notes.md
+cerefox ingest-dir docs/
+
+# Option B — keep using the Python web for ingestion until v0.7.
+uv run cerefox web
+```
+
+v0.7 swaps the 503 stubs for in-process pipeline calls. The toast
+just stops firing — no frontend changes, no config changes, no
+re-install.
+
+### Should I upgrade from v0.5.4 to v0.6.0?
+
+| Workflow | Recommendation |
+|---|---|
+| MCP client only (Claude Code, Cursor, etc.) | Yes — Phase 2 writers + faster install matter. No risk. |
+| `cerefox` CLI for ingest / search | Yes — same CLI, no API changes. Ingest still works via the Edge Function. |
+| Web UI to ingest documents | Optional — wait a few days for v0.7 if ingestion-via-web is your main flow. Or upgrade and use the CLI for ingest until v0.7. |
+| `uv run cerefox web` | Keep using it through v0.7; the Python web is unchanged. The deprecation banner lands in v0.7 once the TS web is feature-complete. |
+
+### Python web kept through v0.7.x
+
+`src/cerefox/api/app.py` and `routes_api.py` ship unchanged in v0.6.
+The Python web-specific deprecation banner is **deferred to v0.7's
+Part 25L** — we won't nudge users away from a fully-working Python
+web while the TS web's 3 ingest endpoints are still 503. v0.8 makes
+the banner prominent; v0.9 deletes the Python web code.
+
+---
+
 ## Known gotchas
 
 ### `npx` from inside an npm workspace

package/docs/guides/quickstart.md

@@ -1,165 +1,104 @@
-# Quickstart -- Zero to First Document in 15 Minutes
+# Quickstart -- Zero to First Document in 5 Minutes
 
-Get Cerefox running locally and ingest your first document.
+Get Cerefox running on your machine via the npm install path. **No source
+clone, no Python required.**
 
-> **Upgrading from a previous version?** See the [Upgrading Guide](upgrading.md) for migration steps instead.
+> **Upgrading from an earlier version?** See [`upgrading.md`](upgrading.md)
+> for migration steps instead.
 
 ---
 
-## 1. Prerequisites (2 min)
+## Prerequisites
 
-- Python 3.11+ (`python3 --version`)
-- Node.js 18+ and npm (`node --version`)
-- `uv` package manager (`pip install uv`)
-- A Supabase account -- [supabase.com](https://supabase.com) (free tier works)
-- An OpenAI API key -- [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
+- **Node.js 20+** (`node --version`) or **Bun 1.0+** (`bun --version`)
+- A **Supabase account** -- [supabase.com](https://supabase.com) (free tier works) -- with the Cerefox schema deployed (see [Note on schema deploy](#note-on-schema-deploy) below)
+- An **OpenAI API key** -- [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
 
 ---
 
-## 2. Install Cerefox (2 min)
+## 1. Install
 
 ```bash
-git clone https://github.com/fstamatelopoulos/cerefox.git
-cd cerefox
-uv sync
-```
-
-> No heavy ML model downloads needed -- embeddings are handled by the OpenAI API.
-
----
-
-## 3. Set up Supabase (5 min)
-
-1. Create a new Supabase project at [app.supabase.com](https://app.supabase.com).
-2. Go to **Project Settings → API → Project URL** and copy it. Also note your project ref (the slug in the URL, e.g. `abcd1234`).
-3. Go to **Project Settings → API Keys** and copy the **Secret key** (`sb_secret_…`). The legacy `service_role` JWT also works if you prefer; either goes into `CEREFOX_SUPABASE_KEY`. See [`setup-supabase.md` → Supabase API keys (2026)](setup-supabase.md#supabase-api-keys-2026) for the full key story (including why the anon key, if you ever need it, must currently stay as the legacy JWT — `sb_publishable_…` does not work for Edge Functions).
-4. Go to **Project Settings → Database → Connection pooling** and copy the **Session Pooler** URI (host ends `.pooler.supabase.com`, port `5432`). If you only see the Transaction Pooler in the dashboard, take that URI and change `:6543` → `:5432`. **Do not use port 6543** — Transaction Pooler does not support DDL. See [`setup-supabase.md` → Connection pooling (2026)](setup-supabase.md#connection-pooling-2026) for context.
-
-Create a `.env` file:
-
-```env
-CEREFOX_SUPABASE_URL=https://your-project-ref.supabase.co
-CEREFOX_SUPABASE_KEY=sb_secret_...your-supabase-secret-key...
-CEREFOX_DATABASE_URL=postgresql://postgres.your-project-ref:your-db-password@aws-N-region.pooler.supabase.com:5432/postgres?sslmode=require
-OPENAI_API_KEY=sk-...your-openai-key...
+curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install.sh | sh
 ```
 
-The username must include the `.<project-ref>` suffix (e.g. `postgres.abcd1234`) — without it, Supabase returns "Tenant or user not found".
-
----
-
-## 4. Deploy the schema (1 min)
+Detects Bun (or installs it) and falls back to npm. After install,
+`cerefox` is on your PATH.
 
+Direct alternatives:
 ```bash
-uv run python scripts/db_deploy.py
+bun add -g @cerefox/memory       # preferred (faster cold start)
+npm install -g @cerefox/memory   # equivalent
 ```
 
-You should see all steps complete with a final `Done` message.
+## 2. First-run setup
 
-Verify:
 ```bash
-uv run python scripts/db_status.py
+cerefox init        # 5-step interactive setup — prompts for the credentials above
+cerefox doctor      # green across the board if everything's wired correctly
 ```
 
-This should show all checks passed.
-
----
-
-## 5. Ingest your first document (2 min)
+`cerefox init` validates each entry against the live service before saving,
+writes `~/.cerefox/.env` (mode 0600), and optionally ingests the bundled
+self-docs into the `_cerefox-self-docs` project so agents can search for
+Cerefox usage guidance.
 
-Have a markdown file? Ingest it:
+## 3. Wire up an AI agent
 
 ```bash
-uv run cerefox ingest my-notes.md
+# Run the commands that apply to your setup:
+cerefox configure-agent --tool claude-code      # Claude Code (~/.claude.json)
+cerefox configure-agent --tool claude-desktop   # Claude Desktop config
 ```
 
-Or paste directly from the terminal:
+Then restart your client:
+- **Claude Code**: start a fresh session — running sessions cache the MCP tool list.
+- **Claude Desktop**: Cmd+Q to fully quit, then relaunch.
 
-```bash
-echo "# My First Note
+Cursor, OpenAI Codex CLI, and Gemini CLI ship in a follow-up (v0.6+).
+For manual setup of those today, see [`connect-agents.md`](connect-agents.md).
 
-This is the beginning of my personal knowledge base." | uv run cerefox ingest --paste --title "First Note"
-```
+## 4. Try it
 
----
+From your AI agent, ask:
 
-## 6. Build and start the web app (1 min)
+> "Use cerefox_search to look for 'cerefox conventions' and tell me what you find."
 
-Build the React frontend:
-
-```bash
-cd frontend && npm install && npm run build && cd ..
-```
-
-Start the web app:
-
-```bash
-uv run cerefox web
-```
-
-Open [http://localhost:8000/app/](http://localhost:8000/app/) -- your dashboard is live.
-
-> The root URL (`http://localhost:8000/`) redirects to `/app/` automatically.
+You should see results from the bundled self-docs.
 
 ---
 
-## 7. Search your knowledge (30 sec)
+## Note on schema deploy
 
-From the CLI:
+If your Supabase project is **brand new**, the Cerefox schema needs to be
+deployed once before the CLI works. Until v0.6 ports the schema deploy to
+TypeScript, this is the one step that still requires the source-checkout
+path:
 
 ```bash
-uv run cerefox search "my first note"
-```
-
-Or use the web UI search page at [http://localhost:8000/app/search](http://localhost:8000/app/search).
-
----
-
-## 8. Connect an AI agent (optional, 5 min)
-
-Cerefox ships a built-in MCP server. Add it to Claude Desktop's config file
-(`~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "cerefox": {
-      "command": "uv",
-      "args": ["--directory", "/path/to/cerefox", "run", "cerefox", "mcp"]
-    }
-  }
-}
+git clone https://github.com/fstamatelopoulos/cerefox.git && cd cerefox
+uv sync
+# Add CEREFOX_DATABASE_URL to your .env, then:
+uv run python scripts/db_deploy.py
 ```
 
-Replace `/path/to/cerefox` with the absolute path to this checkout. Restart Claude Desktop.
-
-> **Recommended: remote MCP** -- if you deployed the Edge Functions (see the main
-> README), use the remote MCP path instead -- no Python install needed on the client machine.
-> See `docs/guides/connect-agents.md` for Path A-Remote.
->
-> **ChatGPT** does not support MCP -- use a Custom GPT with
-> Edge Functions instead (see `docs/guides/connect-agents.md`, Path B).
-
-For full setup details (remote MCP, Cursor, cloud clients, GPT Actions), see `docs/guides/connect-agents.md`.
+Detailed walkthrough: [`setup-supabase.md`](setup-supabase.md).
+After v0.6.0, `cerefox init` will offer to do this for you.
 
 ---
 
-## You're done!
-
-**What's next:**
-- Ingest a directory of notes: `cerefox ingest-dir ./notes/ --recursive`
-- Re-embed existing content: `cerefox reindex`
-- Create a backup: `python scripts/backup_create.py`
-- Sync project docs into your knowledge base: `python scripts/sync_docs.py`
-  (this also ingests the agent reference guides -- `AGENT_GUIDE.md` and `AGENT_QUICK_REFERENCE.md` --
-  so your AI agents can search for "How AI Agents Use Cerefox" and learn how to use the tools)
-- See all commands: `cerefox --help`
-
-**More guides:**
-- `AGENT_GUIDE.md` -- comprehensive reference for AI agents using Cerefox tools
-- `AGENT_QUICK_REFERENCE.md` -- minimal quick reference card for AI agents
-- `docs/guides/setup-supabase.md` -- detailed Supabase setup
-- `docs/guides/configuration.md` -- all configuration options
-- `docs/guides/connect-agents.md` -- connecting AI agents via MCP and Edge Functions
-- `docs/guides/setup-local.md` -- local Docker setup (no Supabase account needed)
-- `docs/guides/upgrading.md` -- upgrading from a previous version
+## What's next
+
+- **Ingest your notes**: `cerefox ingest my-notes.md`, or
+  `cerefox ingest-dir ./notes/ --recursive`
+- **Search from the CLI**: `cerefox search "your query"`
+- **Discover all commands**: `cerefox --help`
+- **Run the web UI** (Python-only until v0.6): [`setup-local.md`](setup-local.md)
+- **Connect more AI clients** (Cursor, Codex, ChatGPT GPT Actions, etc.):
+  [`connect-agents.md`](connect-agents.md)
+- **Configuration reference**: [`configuration.md`](configuration.md)
+- **Backup + restore**: [`ops-scripts.md`](ops-scripts.md)
+
+For the agent-facing reference (what tools agents have, how to use them well),
+read `AGENT_QUICK_REFERENCE.md` in the repo root — or have your agent run
+`cerefox_get_help` from any MCP-connected client.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Cerefox — user-owned shared memory for AI agents. The local TypeScript runtime: stdio MCP server in v0.4; CLI binary added in v0.5; in-process web server in v0.6; ingestion pipeline in v0.7.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",
@@ -39,12 +39,15 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
+    "@hono/node-server": "^2.0.4",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@supabase/supabase-js": "^2.45.0",
     "cli-progress": "^3.12.0",
     "commander": "^12.1.0",
+    "hono": "^4.12.23",
     "picocolors": "^1.0.0",
     "prompts": "^2.4.2",
+    "smol-toml": "^1.6.1",
     "zod": "^3.23.0"
   },
   "devDependencies": {
@@ -58,7 +61,9 @@
     "build": "bun build src/bin/cerefox.ts --outdir dist/bin --target node --format esm",
     "clean": "rm -rf dist docs AGENT_GUIDE.md AGENT_QUICK_REFERENCE.md",
     "bundle-docs": "bun run ../../scripts/bundle_package_docs.ts",
-    "prepublishOnly": "bun run clean && bun run bundle-docs && bun run build",
+    "build-frontend": "cd ../../frontend && bun install && bun run build",
+    "bundle-frontend": "rm -rf dist/frontend && mkdir -p dist/frontend && cp -R ../../frontend/dist/. dist/frontend/",
+    "prepublishOnly": "bun run clean && bun run bundle-docs && bun run build-frontend && bun run bundle-frontend && bun run build",
     "smoke": "node dist/bin/cerefox.js --help && node dist/bin/cerefox.js mcp --help"
   },
   "publishConfig": {

package/docs/guides/migration-v0.4.md

@@ -1,260 +0,0 @@
-# Migrating to Cerefox v0.4.0 (historical)
-
-> ## ⚠ Historical document — do not use the snippets in this file
->
-> This guide documents the **v0.4.0 → v0.4.3 migration window** (May 2026).
-> The `cerefox-mcp` bin name referenced throughout was dropped in **v0.5.1**;
-> the soft-wrapper described in some sections was removed in **v0.5.2**.
-> The per-client config snippets below **will not work on @cerefox/memory v0.5+**.
->
-> **If you're upgrading today, use the current guide instead:**
-> → [`migration-v0.5.md`](migration-v0.5.md) — covers Python `cerefox` → v0.5.x
->   AND v0.4.x → v0.5.x in a single document, with the v0.5.0/v0.5.1/v0.5.2/v0.5.3
->   transitions all explained.
->
-> This file is preserved so historical CHANGELOG entries that reference it
-> still resolve. It's not maintained.
-
----
-
-**Original TL;DR (preserved verbatim)**: nothing urgent. Your existing `cerefox mcp` configs keep
-working unchanged. The Python `cerefox mcp` command is now a soft
-wrapper that transparently uses the new TypeScript MCP server if it's
-installed, falling back to the legacy Python implementation otherwise.
-Switch to the npm-installed TS server at your convenience for faster
-boot times and fewer Python dependencies.
-
-This guide is for **existing users** of `cerefox mcp` who want to
-optionally upgrade. **New users** should follow
-[`docs/guides/connect-agents.md`](connect-agents.md) instead — that's
-the canonical configuration recipe per MCP client.
-
-## What changed in v0.4.0
-
-- **`@cerefox/memory`** is a new npm package containing the Cerefox
-  local stdio MCP server. Same 10 MCP tools, same protocol, faster
-  boot.
-- **The Edge Function (`cerefox-mcp`) shares tool handlers** with the
-  new local server via `_shared/mcp-tools/`. One source of truth; no
-  drift.
-- **`cerefox_get_help`** is a new MCP tool (10 total now, was 9). Layer
-  3 of MCP discoverability — agents can now retrieve
-  `AGENT_QUICK_REFERENCE.md` content over MCP without filesystem
-  access.
-- **`cerefox mcp` (Python CLI)** starts the in-tree Python MCP server.
-  (v0.4–v0.5.1 advertised a "soft wrapper" that tried to delegate to the
-  npm package's TS MCP server via npx, but the probe was unreliable
-  under `uv run`-launched MCP-client contexts and caused infinite
-  recursion. v0.5.2 stripped the wrapper; the Python path is now
-  always the Python server, and the npm/TS path is configured
-  explicitly. See `docs/guides/migration-v0.5.md` § "v0.5.2 fixed the
-  soft wrapper" for the migration story.)
-
-## The optional one-time upgrade
-
-If you have Node 20+ installed, install `@cerefox/memory` globally:
-
-```bash
-npm install -g @cerefox/memory
-# or, if you have Bun:
-bun install -g @cerefox/memory
-```
-
-After this, the npm `cerefox` is on your PATH. To actually have your
-MCP client use the TS server, you need to **update your MCP client
-config explicitly** — v0.5.2 removed the auto-delegation. The
-canonical config invokes the npm bin directly; see the next section.
-
-(v0.4–v0.5.1 *thought* it had auto-delegation, but the soft wrapper
-was unreliable under `uv run`-launched contexts and caused infinite
-recursion when the MCP client launched it. v0.5.2 took the simpler
-"each path is explicit" stance.)
-
-You can also point your MCP client directly at `cerefox mcp` (the
-TS-CLI subcommand) and bypass the Python path entirely:
-
-### Claude Code
-
-**Old:**
-
-```bash
-claude mcp add cerefox -- uv run --directory /path/to/cerefox cerefox mcp
-```
-
-**New (optional):**
-
-```bash
-claude mcp add cerefox -- npx -y --package=@cerefox/memory cerefox-mcp
-```
-
-### Cursor
-
-**Old** (`mcp.json` in your project or `~/.cursor/mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "cerefox": {
-      "command": "uv",
-      "args": ["run", "--directory", "/path/to/cerefox", "cerefox", "mcp"]
-    }
-  }
-}
-```
-
-**New (optional):**
-
-```json
-{
-  "mcpServers": {
-    "cerefox": {
-      "command": "npx",
-      "args": ["-y", "--package=@cerefox/memory", "cerefox-mcp"]
-    }
-  }
-}
-```
-
-### Claude Desktop
-
-**Old** (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "cerefox": {
-      "command": "uv",
-      "args": ["--directory", "/path/to/cerefox", "run", "cerefox", "mcp"]
-    }
-  }
-}
-```
-
-**New (optional):**
-
-```json
-{
-  "mcpServers": {
-    "cerefox": {
-      "command": "npx",
-      "args": ["-y", "--package=@cerefox/memory", "cerefox-mcp"]
-    }
-  }
-}
-```
-
-### Codex CLI
-
-**Old** (`~/.codex/config.toml`):
-
-```toml
-[mcp_servers.cerefox]
-command = "uv"
-args = ["--directory", "/path/to/cerefox", "run", "cerefox", "mcp"]
-```
-
-**New (optional):**
-
-```toml
-[mcp_servers.cerefox]
-command = "npx"
-args = ["-y", "--package=@cerefox/memory", "cerefox-mcp"]
-```
-
-## Environment
-
-The new TS server reads `.env` the same way the Python CLI does (per
-v0.3.0's `_resolve_config_dir()`):
-
-1. `CEREFOX_CONFIG_DIR` env var override.
-2. `./.env` in the current working directory.
-3. `~/.cerefox/.env`.
-
-For most users with an existing Cerefox install, your `.env` is already
-where it needs to be. If you want to verify:
-
-```bash
-npx --package=@cerefox/memory cerefox-mcp --help
-```
-
-(That's the help text, not a server start — safe to run anywhere.)
-
-## Schema-version-mismatch banner
-
-The new server prints a one-line warning to stderr at boot if the
-bundled `@cerefox/memory` schema version doesn't match what's deployed
-to your Supabase. Run `uv run python scripts/db_deploy.py` from the
-repo to update.
-
-## Falling back
-
-If the npm path doesn't work for any reason (npx missing, package not
-installed, network issue during `npx` resolution), `cerefox mcp` falls
-back to the legacy Python server with a one-line stderr nudge. Your
-MCP client never notices — same stdio interface, same tools.
-
-To force the legacy path even when `@cerefox/memory` is installed:
-uninstall it (`npm uninstall -g @cerefox/memory`) or invoke the Python
-CLI from a shell without `npx` in `$PATH`.
-
-## `cerefox_get_help` — the new tool
-
-If you use Cerefox through an MCP client and ever wonder "wait, what's
-the right way to do X in Cerefox?", you can now ask the server
-directly:
-
-- `cerefox_get_help()` — returns the full `AGENT_QUICK_REFERENCE.md`
-  plus a section index.
-- `cerefox_get_help(topic: "links")` — returns just the cross-document
-  linking section.
-- `cerefox_get_help(topic: "update")` — returns the update workflow
-  sections.
-
-The topic match is a case-insensitive substring against H2 headings.
-Both the new TS server AND the legacy Python fallback expose this tool
-— consistent surface regardless of which path serves your session.
-
-## When v0.5.0 ships
-
-The TypeScript CLI lands in v0.5.0. At that point `@cerefox/memory`
-will gain a second binary (`cerefox`) for the full CLI surface
-(`cerefox search`, `cerefox ingest`, etc.) plus a `cerefox
-configure-agent` command that writes the right MCP config for each
-client automatically. For now, the manual recipes above are the way.
-
-## Known gotchas
-
-- **`npx` from inside an npm workspace can fail with "command not
-  found"** even when the package is correctly published. Running
-  `npx -y --package=@cerefox/memory cerefox-mcp` from the root of a
-  surrounding npm-workspace monorepo (your own project) confuses npx's
-  bin-resolution path. Symptoms: `sh: cerefox-mcp: command not found`
-  even though the published package has the bin entry. Workarounds —
-  any one of these works:
-  - Use `bunx` instead: `bunx --package @cerefox/memory cerefox-mcp` —
-    cleanly handles workspace contexts.
-  - Run from a non-workspace directory (e.g. `cd /tmp` first).
-  - Install globally and invoke from PATH:
-    `npm install -g @cerefox/memory` then `cerefox-mcp`.
-  - When configuring an MCP client (Claude Code, Cursor, Claude
-    Desktop, Codex CLI), the launched process inherits the client's
-    own working directory rather than your shell's, so this gotcha
-    usually doesn't bite real MCP usage — only manual `npx` smoke
-    tests run from a project root.
-
-- **The minimum npm version for OIDC publish is 11.5.1.** The shipped
-  `release.yml` workflow already pins this; only relevant if you're
-  forking the project for your own publish target.
-
-## What didn't change
-
-- The Edge Function (remote MCP) URL and auth: unchanged. Same
-  Bearer-with-anon-JWT pattern; the EF just shares its tool handlers
-  with the local TS server now.
-- The Postgres RPC contracts: unchanged. v0.4.0 ships zero schema
-  changes — the `cerefox_schema_version()` RPC introduced in v0.3.0
-  still returns `0.3.1`. (The mismatch warning at TS server startup
-  fires until you redeploy from `main`, which is what you'd do
-  whenever the schema version actually bumps.)
-- Web UI, ingestion pipeline, CLI subcommands: all unchanged in v0.4.
-  Those migrate in v0.6 and v0.7.