@cerefox/memory 0.8.3 → 0.9.1

package/docs/guides/setup-supabase.md

@@ -8,9 +8,11 @@ This guide walks you from a blank Supabase project to a fully deployed Cerefox s
 
 ## Prerequisites
 
-- [uv](https://docs.astral.sh/uv/getting-started/installation/) installed
+- The Cerefox CLI installed (`cerefox --version`) — see [`quickstart.md`](quickstart.md#1-install). End users do **not** need a source clone or Python.
+- **Node.js 20+** or **Bun 1.0+** (the CLI runtime; also used for `npx supabase`).
 - A Supabase account (free tier is enough): [supabase.com](https://supabase.com)
-- Python 3.11 or higher
+
+> The `python scripts/db_*.py` paths shown in the contributor footnotes below are **legacy**. The Python implementation is legacy and slated for removal in a future release; only the Python MCP server remains as a fallback. Contributors with a repo clone should use `bun scripts/db_deploy.ts` / `bun scripts/db_migrate.ts`.
 
 ---
 
@@ -52,14 +54,14 @@ Either way: keep this key secret — it bypasses Row Level Security and grants f
 
 ### 3c. Direct database URL — `CEREFOX_DATABASE_URL`
 
-This is used by `db_deploy.py`, `db_migrate.py`, and `db_status.py`. See the **[Connection pooling in 2026](#connection-pooling-2026)** reference section near the end of this guide for context. The short version:
+This is used by `cerefox server deploy` (and the contributor scripts `bun scripts/db_deploy.ts` / `bun scripts/db_migrate.ts`). See the **[Connection pooling in 2026](#connection-pooling-2026)** reference section near the end of this guide for context. The short version:
 
 1. Open **Project Settings → Database → Connection pooling** (not the "Connect" dialog — that one usually omits the Session Pooler in the new UI).
 2. Copy the **Session Pooler** URI (host ends in `.pooler.supabase.com`, port `5432`).
 3. Confirm the username has the form `postgres.<project-ref>` — without that suffix you'll get "Tenant or user not found".
 4. Append `?sslmode=require` to enforce TLS explicitly.
 
-If you only see Direct Connection and Transaction Pooler in your dashboard, take the Transaction Pooler URI and change `:6543` → `:5432`. That gives you the Session Pooler. **Do not use port 6543** — Transaction Pooler does not support DDL and `db_deploy.py` will fail mid-schema.
+If you only see Direct Connection and Transaction Pooler in your dashboard, take the Transaction Pooler URI and change `:6543` → `:5432`. That gives you the Session Pooler. **Do not use port 6543** — Transaction Pooler does not support DDL and the schema deploy will fail mid-schema.
 
 The Direct Connection (`db.<project-ref>.supabase.co:5432`) is IPv6-only on the free tier and unusable on most home/office networks. The dashboard now warns about this directly.
 
@@ -67,133 +69,56 @@ The Direct Connection (`db.<project-ref>.supabase.co:5432`) is IPv6-only on the
 
 ## Step 4 — Configure Your Environment
 
+Run the interactive setup — it validates each credential against the live
+service and writes `~/.cerefox/.env` (mode 0600):
+
 ```bash
-# In the cerefox project root:
-cp .env.example .env
+cerefox init
 ```
 
-Edit `.env` and fill in your values. A minimal working configuration looks like:
+When prompted, supply the three values from Step 3 (URL, secret key, database
+URL) plus your `OPENAI_API_KEY`. If you plan to connect AI agents via the
+remote MCP / GPT Actions path, also set `CEREFOX_SUPABASE_ANON_KEY` to the
+**legacy anon JWT** (`eyJ…`, not `sb_publishable_…` — see "Supabase API keys
+(2026)" below).
+
+A minimal `~/.cerefox/.env` looks like:
 
 ```bash
 CEREFOX_SUPABASE_URL=https://your-project-ref.supabase.co
 CEREFOX_SUPABASE_KEY=sb_secret_...your-secret-key...
 CEREFOX_DATABASE_URL=postgresql://postgres.yourref:yourpassword@aws-N-region.pooler.supabase.com:5432/postgres?sslmode=require
-# CEREFOX_SUPABASE_ANON_KEY only needed if you'll deploy Edge Functions (Step 8)
-# Must be the legacy anon JWT, NOT sb_publishable_... — see "Supabase API keys (2026)" below
+OPENAI_API_KEY=sk-...
+# Only needed for Edge Functions / MCP / GPT Actions — must be the legacy anon JWT:
 # CEREFOX_SUPABASE_ANON_KEY=eyJ...your-legacy-anon-jwt...
 ```
 
-Leave all other settings at their defaults for now.
+> **Contributors** (repo clone): copy `cp .env.example .env` in the project root
+> and edit it directly; the repo-local `.env` takes precedence (see
+> [`configuration.md`](configuration.md#where-cerefox-looks-for-env-v030)).
 
 ---
 
-## Step 5 — Install Dependencies
+## Step 5 — Deploy the Schema and Edge Functions
 
-```bash
-uv sync
-```
-
-This installs all Python dependencies defined in `pyproject.toml`, including `supabase`, `psycopg2-binary`, and `pydantic-settings`.
-
----
-
-## Step 6 — Deploy the Schema
+`cerefox server deploy` is the catch-all end-user deploy path. It deploys the
+schema + RPCs (using `CEREFOX_DATABASE_URL`) and all 9 Edge Functions — straight
+from the npm-bundled assets, no source clone. It detects fresh vs. existing
+databases: a fresh DB gets schema + RPCs + migration stamps; an existing DB gets
+pending migrations applied and `rpcs.sql` re-applied in place.
 
 ```bash
 # Preview what will happen (no changes made):
-python scripts/db_deploy.py --dry-run
-
-# Apply the schema:
-python scripts/db_deploy.py
-```
-
-Expected output:
-```
-╔══════════════════════════════════════╗
-║  Cerefox DB Deploy                   ║
-╚══════════════════════════════════════╝
-
-Connecting to database...
-
-▶  Enable extensions (uuid-ossp, vector/pgvector)...
-   ✓  Done
-
-▶  Apply schema (tables, indexes, triggers)...
-   ✓  Done
-
-▶  Apply RPCs (search functions)...
-   ✓  Done
-
-──────────────────────────────────────────
-✓  Deployment complete. 3 steps applied.
-
-Next step: verify the schema with:
-    python scripts/db_status.py
-```
-
----
-
-## Step 7 — Verify the Schema
-
-```bash
-python scripts/db_status.py
-```
+cerefox server deploy --dry-run
 
-Expected output:
-```
-╔══════════════════════════════════════╗
-║  Cerefox DB Status                   ║
-╚══════════════════════════════════════╝
-
-Extensions:
-  ✓  uuid-ossp
-  ✓  vector
-
-Tables:
-  ✓  cerefox_projects
-  ✓  cerefox_documents
-  ✓  cerefox_chunks
-  ✓  cerefox_migrations
-
-Functions / RPCs:
-  ✓  cerefox_set_updated_at()
-  ✓  cerefox_hybrid_search()
-  ✓  cerefox_fts_search()
-  ✓  cerefox_semantic_search()
-  ✓  cerefox_reconstruct_doc()
-  ✓  cerefox_save_note()
-  ✓  cerefox_search_docs()
-  ✓  cerefox_context_expand()
-
-Indexes:
-  ✓  idx_cerefox_chunks_fts
-  ✓  idx_cerefox_chunks_emb_primary
-  ✓  idx_cerefox_chunks_emb_upgrade
-  ✓  idx_cerefox_chunks_document
-  ✓  idx_cerefox_docs_metadata
-  ✓  idx_cerefox_docs_project
-
-Row counts:
-  ℹ  cerefox_projects: 0 rows
-  ℹ  cerefox_documents: 0 rows
-  ℹ  cerefox_chunks: 0 rows
-
-──────────────────────────────────────────
-✓  All checks passed. Schema looks healthy.
+# Deploy everything (schema + RPCs + Edge Functions):
+cerefox server deploy
 ```
 
-All checks should show ✓. If any show ✗, re-run `python scripts/db_deploy.py`.
-
----
+Useful flags: `--schema-only`, `--functions-only`, `--dry-run`.
 
-## Step 8 — Deploy Edge Functions
-
-The Edge Functions run server-side on Supabase. `cerefox-search` and `cerefox-ingest` handle
-embedding for agents; `cerefox-mcp` wraps them as a remote MCP endpoint (recommended for
-Claude Code, Cursor, and Claude Desktop). Deploy using the Supabase CLI via `npx` — no
-separate install needed, just Node.js.
-
-**First time only — authenticate and link your project:**
+**First time only — the Edge Function step authenticates and links your project**
+(it shells out to `npx supabase`). If prompted, run:
 
 ```bash
 npx supabase login        # opens a browser tab; click "Confirm" to generate an access token
@@ -203,72 +128,42 @@ npx supabase link         # prompts for your project ref (the ID in your Supabas
 Your project ref is in the Supabase dashboard URL:
 `https://supabase.com/dashboard/project/<project-ref>`
 
-**Deploy all three functions** (from the cerefox project root):
-
-```bash
-npx supabase functions deploy cerefox-ingest
-npx supabase functions deploy cerefox-search
-npx supabase functions deploy cerefox-mcp
-```
-
-Expected output for each:
-```
-Bundling Function: cerefox-ingest
-Deploying Function: cerefox-ingest (script size: ~880kB)
-Deployed Functions on project <your-project-ref>: cerefox-ingest
-```
-
-You can verify in the Supabase Dashboard → **Edge Functions** — all three functions should
-appear with a green "Active" status.
+After it finishes, verify in the Supabase Dashboard → **Edge Functions** — all 9
+functions should appear with a green "Active" status.
 
 > **`WARNING: Docker is not running` is expected and harmless.** The Supabase CLI checks for
 > Docker (its older local bundler ran in a container) but falls back to bundling the functions
 > server-side — it uploads the source assets (you'll see `Uploading asset (…)` lines) and
 > Supabase compiles them in the cloud. **Docker is not a prerequisite for deploying Cerefox's
 > Edge Functions.** A deploy succeeded as long as each function ends with
-> `Deployed Functions on project …`. This applies to both the manual commands here and
-> `cerefox deploy-server --functions-only`.
+> `Deployed Functions on project …`.
 
-> **Re-deploying after updates**: run the same `npx supabase functions deploy` commands
-> again from the project root, or just `cerefox deploy-server --functions-only` (it deploys
-> all 9 from the bundled assets). `npx supabase login` only needs to be run once per machine.
+> **Re-deploying after upgrades**: just re-run `cerefox server deploy` (or
+> `cerefox server deploy --functions-only` for EFs only). It applies pending
+> migrations and re-applies RPCs in place. `npx supabase login` only needs to be
+> run once per machine.
 
----
-
-## Step 9 — Run the Tests
-
-Confirm everything is wired up correctly:
-
-```bash
-uv run pytest
-```
-
-These are unit tests only (no real database connection needed). You should see all tests pass.
-
-To also run the integration tests against your live Supabase instance:
-```bash
-uv run pytest -m integration
-```
+> **Contributors** (repo clone): the low-level path is `bun scripts/db_deploy.ts`
+> / `bun scripts/db_migrate.ts` for schema, and `npx supabase functions deploy
+> <name>` per Edge Function. The `python scripts/db_deploy.py` path is legacy.
 
 ---
 
-## Step 11 — Connect an AI agent (optional)
+## Step 6 — Connect an AI agent (optional)
 
 Cerefox ships a built-in MCP server that gives desktop agents named tools
 (`cerefox_search`, `cerefox_ingest`) with full hybrid search.
 
-**For Claude Desktop / ChatGPT Desktop / Cursor** — add to the client's MCP config:
-```json
-{
-  "mcpServers": {
-    "cerefox": {
-      "command": "uv",
-      "args": ["--directory", "/path/to/cerefox", "run", "cerefox", "mcp"]
-    }
-  }
-}
+**For Claude Code / Claude Desktop / Cursor / Codex / Gemini** — let the CLI
+write the config:
+```bash
+cerefox configure-agent --tool claude-code      # or claude-desktop, cursor, codex, gemini
 ```
 
+This points the client at the local stdio server (`cerefox mcp`). To edit
+configs by hand or use the remote (Edge Function) HTTP transport, see
+[`connect-agents.md`](connect-agents.md).
+
 **For cloud Claude.ai** — connect to the Supabase remote MCP (FTS keyword search only):
 1. In Supabase Dashboard → Project Settings → Integrations → MCP, get your project ref
 2. In Claude.ai Settings → Integrations, add `https://mcp.supabase.com/sse?project_ref=<ref>`
@@ -288,14 +183,14 @@ architecture explanation, and ChatGPT GPT Actions setup.
 
 ### "extension 'vector' does not exist"
 - Go to Supabase Dashboard → Database → Extensions → enable `vector`
-- Then re-run `python scripts/db_deploy.py`
+- Then re-run `cerefox server deploy`
 
 ### "permission denied for table"
 - Make sure `CEREFOX_SUPABASE_KEY` is your secret key (`sb_secret_…`) or legacy `service_role` JWT — not the publishable / anon key. See [Supabase API keys (2026)](#supabase-api-keys-2026) below.
 
 ### Schema already exists (re-deploying)
-- All schema objects use `CREATE ... IF NOT EXISTS` / `CREATE OR REPLACE`, so re-running is safe
-- To start completely fresh: `python scripts/db_deploy.py --reset` (⚠️ deletes all data)
+- All schema objects use `CREATE ... IF NOT EXISTS` / `CREATE OR REPLACE`, so re-running `cerefox server deploy` is safe
+- To start completely fresh, contributors with a repo clone can run `bun scripts/db_deploy.ts --reset` (⚠️ deletes all data; typed-`yes` guard). There is deliberately no `--reset` on `cerefox server deploy`.
 
 ---
 
@@ -342,7 +237,7 @@ Supabase's "Connect" dialog was redesigned in 2026 and the **Session Pooler** is
 | Type | Host / port | DDL support | IPv4 compatible? | Use for Cerefox? |
 |---|---|---|---|---|
 | **Direct Connection** | `db.<project-ref>.supabase.co:5432` | ✓ | **IPv6 only on free tier.** Dashboard warns about this directly. | No — most networks can't reach it. |
-| **Transaction Pooler** | `aws-N-region.pooler.supabase.com:6543` (note port) | **✗ no DDL** | ✓ | No — `db_deploy.py` fails mid-schema. |
+| **Transaction Pooler** | `aws-N-region.pooler.supabase.com:6543` (note port) | **✗ no DDL** | ✓ | No — the schema deploy fails mid-schema. |
 | **Session Pooler** | `aws-N-region.pooler.supabase.com:5432` | ✓ | ✓ | **Yes — use this.** |
 
 The Transaction Pooler runs PgBouncer in transaction mode and does not maintain a session between statements, breaking DDL, prepared statements, `SET LOCAL`, and advisory locks. The Session Pooler is the same hostname on a different port and keeps a full session per connection.

package/docs/guides/upgrading.md

@@ -4,24 +4,35 @@ This guide covers upgrading an existing Cerefox installation. All steps are idem
 
 ## Pick your path
 
-Cerefox has two install paths since v0.4.0 (npm) and v0.5.0 (TS CLI). The right
-upgrade procedure depends on how you installed Cerefox:
+The right upgrade procedure depends on how you installed Cerefox:
 
 | You installed via | Upgrade with |
 |---|---|
-| **npm / Bun** (`@cerefox/memory` global) | `bun update -g @cerefox/memory` (or `npm update -g @cerefox/memory`), then read [`migration-v0.5.md`](migration-v0.5.md) for any breaking-change notes per version. **`cerefox doctor`** verifies the install. |
-| **Source checkout** (`git clone` + `uv sync`) | The "Standard Upgrade Checklist" below — Python deps, schema migrations, Edge Functions, frontend build, the works. |
-| **Both** (you contribute AND have the npm bin globally) | Both flows. The two paths share the same Supabase + `.env`; just keep them updated in lockstep. |
+| **Installer / npm** (end user, no repo clone) | Re-run the installer (`curl …/install.sh \| sh`) or `cerefox self-update` (or `bun update -g @cerefox/memory` / `npm update -g @cerefox/memory`). Then run `cerefox server deploy` **if the server side changed** (new migration or RPC change — release notes will say). **`cerefox doctor`** verifies the install. |
+| **Source checkout** (`git clone`, contributor) | The "Contributor Upgrade Checklist" below — `git pull`, schema migrations, Edge Functions, frontend build. |
+| **Both** (you contribute AND have the bin globally) | Both flows. The two paths share the same Supabase + `.env`; just keep them updated in lockstep. |
 
-> If you're upgrading from Python `cerefox` to the npm-installed TS CLI for the first
-> time, [`migration-v0.5.md`](migration-v0.5.md) is the canonical guide — it covers
-> `cerefox init`'s coexistence flow (`[c]opy` your existing `.env` to `~/.cerefox/.env`),
-> the v0.5.2 soft-wrapper removal, and the v0.5.3 paths precedence change.
+> If you're upgrading across a major boundary for the first time,
+> [`migration-v0.9.md`](migration-v0.9.md) is the canonical migration guide.
 
-The rest of this document covers the **source checkout** path (Python + frontend + Edge
-Functions). If you're an npm-installed user, you've already got everything you need.
+## End-User Upgrade
 
-## Standard Upgrade Checklist (source-checkout users)
+```bash
+# 1. Update the CLI
+cerefox self-update          # or: re-run the installer, or bun/npm update -g @cerefox/memory
+
+# 2. If the release notes flag a server-side change (new migration / RPC change):
+cerefox server deploy        # applies pending migrations, re-applies RPCs, redeploys the 9 Edge Functions
+
+# 3. Verify
+cerefox doctor
+```
+
+`cerefox server deploy` is the catch-all for the server side: on an existing DB it applies
+pending migrations and re-applies `rpcs.sql` in place, then redeploys all nine Edge Functions
+from npm-bundled assets. No repo clone required.
+
+## Contributor Upgrade Checklist (source checkout)
 
 Run these steps every time you pull a new version:
 
@@ -29,19 +40,16 @@ Run these steps every time you pull a new version:
 # 1. Pull the latest code
 git pull origin main
 
-# 2. Install/update Python dependencies
-uv sync
-
-# 3. Apply database migrations (skips already-applied ones)
-uv run python scripts/db_migrate.py
+# 2. Apply database migrations (skips already-applied ones)
+bun scripts/db_migrate.ts
 
-# 4. Redeploy RPC functions (safe to re-run)
-uv run python scripts/db_deploy.py
+# 3. Redeploy RPC functions (safe to re-run)
+bun scripts/db_deploy.ts
 
-# 5. Build the web UI
+# 4. Build the web UI
 cd frontend && npm install && npm run build && cd ..
 
-# 6. Deploy Edge Functions (if using Supabase-hosted)
+# 5. Deploy Edge Functions (if using Supabase-hosted)
 #    Run from the project root (where supabase/ directory is)
 npx supabase functions deploy cerefox-search
 npx supabase functions deploy cerefox-ingest
@@ -50,16 +58,21 @@ npx supabase functions deploy cerefox-get-document
 npx supabase functions deploy cerefox-list-versions
 npx supabase functions deploy cerefox-get-audit-log
 npx supabase functions deploy cerefox-metadata-search
+npx supabase functions deploy cerefox-list-projects
 npx supabase functions deploy cerefox-mcp
 
-# 7. Restart the application
-uv run uvicorn cerefox.api.app:create_app --factory --reload
+# 6. Restart the web UI
+cerefox web
 
-# 8. (Optional) Sync project docs to Cerefox knowledge base
-uv run python scripts/sync_docs.py
+# 7. (Optional) Sync project docs to Cerefox knowledge base
+bun scripts/sync_docs.ts
 ```
 
-Steps 3-4 require `CEREFOX_DATABASE_URL` in your `.env` file (direct Postgres connection). Steps 6 require the Supabase CLI and a linked project.
+Steps 2-3 require `CEREFOX_DATABASE_URL` in your `.env` file (direct Postgres connection). Step 5 requires the Supabase CLI and a linked project. (`cerefox server deploy` does steps 2, 3, and 5 in one command.)
+
+> Python is legacy and slated for removal: the Python CLI and FastAPI web app are husks; only
+> `uv run cerefox mcp` survives as a frozen, unmaintained fallback. Tests run via `bun test`
+> (pytest is retired).
 
 ## Verifying the Upgrade
 
@@ -67,10 +80,10 @@ After upgrading, verify the key components:
 
 ```bash
 # Check migration status
-uv run python scripts/db_migrate.py --status
+bun scripts/db_migrate.ts --status
 
 # Run unit tests (optional but recommended)
-uv run pytest -q
+bun test
 
 # Visit the web UI
 open http://localhost:8000/app/
@@ -213,7 +226,7 @@ uv run python scripts/reindex_all.py --dry-run
 uv run python scripts/reindex_all.py
 
 # Or run directly via the CLI (same effect)
-uv run cerefox reindex --all
+cerefox server reindex --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.
@@ -238,7 +251,7 @@ redeploy RPCs via `db_deploy.py` (step 4) to update the canonical function defin
 
 **Usage tracking is opt-in**: disabled by default. Enable via CLI:
 ```bash
-cerefox config-set usage_tracking_enabled true
+cerefox config set usage_tracking_enabled true
 ```
 Or via the toggle on the Analytics page. When enabled, **all operations** (both reads
 and writes) are logged with operation type, access path, requestor identity, query text,
@@ -290,7 +303,7 @@ MCP clients pick up new tools automatically on the next connection.
 
 ### Upgrading to v0.1.1+ (from v0.1.0)
 
-**Cloud-only embeddings**: Local embedders (mpnet, Ollama) were removed. If you were using a local embedder, switch to OpenAI or Fireworks AI and run `uv run cerefox reindex` to re-embed all chunks.
+**Cloud-only embeddings**: Local embedders (mpnet, Ollama) were removed. If you were using a local embedder, switch to OpenAI or Fireworks AI and run `cerefox server reindex` to re-embed all chunks.
 
 ## AI Agent Integration After Upgrade
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "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",