@cerefox/memory 0.5.4 → 0.6.0

package/docs/guides/quickstart.md

@@ -1,224 +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.
 
-## Two install paths
+---
 
-| You want | Read this section | Why |
-|---|---|---|
-| **Use Cerefox as an MCP server / CLI** | "Path A — npm install" below (fastest) | One install, callable from any directory. No Python needed. Recommended for end users since v0.5. |
-| **Contribute to Cerefox, run the web UI, deploy schema** | "Path B — source checkout" below | Full source: schema deploy, web UI, ingestion pipeline. Required for contributors and for the web UI (until v0.6). |
+## Prerequisites
 
-You'll need a Supabase project (free tier works) and an OpenAI API key for either
-path — those go into `.env`. The npm install asks for them interactively via
-`cerefox init`; the source checkout has you write them into a `.env` file
-yourself.
+- **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)
 
 ---
 
-## Path A — npm install (fastest, 5 min total)
-
-For end users who just want the Cerefox CLI + MCP server on their machine.
+## 1. Install
 
-### A.1 Prerequisites
-- Node.js 20+ (`node --version`) or Bun 1.0+ (`bun --version`)
-- 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)
-- **Schema must be deployed** to your Supabase. Until v0.6 ports the schema
-  deploy to TypeScript, this still requires the source checkout (Path B) once,
-  or someone else who has the source checkout to deploy it for you.
-
-### A.2 Install
 ```bash
-# One-line install (detects Bun or installs it, falls back to npm):
 curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install.sh | sh
-
-# Or direct:
-bun add -g @cerefox/memory       # preferred
-# npm install -g @cerefox/memory # alternative
 ```
 
-### A.3 First-run setup
-```bash
-cerefox init        # 5-step interactive setup
-cerefox doctor      # verify the install
-```
+Detects Bun (or installs it) and falls back to npm. After install,
+`cerefox` is on your PATH.
 
-### A.4 Wire up your MCP client
+Direct alternatives:
 ```bash
-# Run the ones that apply:
-cerefox configure-agent --tool claude-code
-cerefox configure-agent --tool claude-desktop
+bun add -g @cerefox/memory       # preferred (faster cold start)
+npm install -g @cerefox/memory   # equivalent
 ```
 
-`--tool claude-code` shells out to Claude Code's own `claude mcp add --scope user`
-to register the server (Claude Code knows where to store the config).
-`--tool claude-desktop` writes the JSON config file directly.
-
-Then restart your MCP client. **Path A users skip ahead to "[Connect an AI agent](#8-connect-an-ai-agent-optional-5-min)" (step 8) for the verification prompt.** Steps 3–7
-below are Path B-only (setting up `.env` by hand, deploying the schema, the web UI).
-
----
-
-## Path B — source checkout (contributors, schema deploy, web UI)
-
-For anyone hacking on Cerefox itself, deploying the schema for the first time,
-or running the web UI.
-
-### B.1 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)
-
-### B.2 Install Cerefox (2 min)
+## 2. First-run setup
 
 ```bash
-git clone https://github.com/fstamatelopoulos/cerefox.git
-cd cerefox
-uv sync
+cerefox init        # 5-step interactive setup — prompts for the credentials above
+cerefox doctor      # green across the board if everything's wired correctly
 ```
 
-> No heavy ML model downloads needed -- embeddings are handled by the OpenAI API.
+`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.
 
----
-
-## 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...
-```
-
-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)
+## 3. Wire up an AI agent
 
 ```bash
-uv run python scripts/db_deploy.py
+# 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
 ```
 
-You should see all steps complete with a final `Done` message.
+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.
 
-Verify:
-```bash
-uv run python scripts/db_status.py
-```
+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 should show all checks passed.
+## 4. Try it
 
----
+From your AI agent, ask:
 
-## 5. Ingest your first document (2 min)
+> "Use cerefox_search to look for 'cerefox conventions' and tell me what you find."
 
-Have a markdown file? Ingest it:
-
-```bash
-uv run cerefox ingest my-notes.md
-```
-
-Or paste directly from the terminal:
-
-```bash
-echo "# My First Note
-
-This is the beginning of my personal knowledge base." | uv run cerefox ingest --paste --title "First Note"
-```
-
----
-
-## 6. Build and start the web app (1 min)
-
-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.4",
+  "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.