@cerefox/memory 0.11.1 → 1.0.0-beta.2

package/docs/guides/connect-agents.md

@@ -30,24 +30,27 @@ Three top-level paths plus a few special cases:
 | Client | Path | Search | Requirements / caveats |
 |--------|------|--------|-----------------------|
 | Claude Desktop (remote) | Path A-Remote — `cerefox-mcp` Edge Function | Hybrid | Node.js for `npx supergateway` or `npx mcp-remote`; no Python needed |
-| Claude Code (remote) | Path A-Remote — `cerefox-mcp` Edge Function | Hybrid | URL + anon key only; no local install |
-| Cursor (remote) | Path A-Remote — `cerefox-mcp` Edge Function | Hybrid | URL + anon key only; no local install |
-| OpenAI Codex CLI (remote) | Path A-Remote — `cerefox-mcp` Edge Function | Hybrid | URL + anon key env var; TOML config |
+| Claude Code (remote) | Path A-Remote — `cerefox-mcp` Edge Function | Hybrid | URL + Cerefox token only; no local install. Advanced/fallback — prefer Path A-Local |
+| Cursor (remote) | Path A-Remote — `cerefox-mcp` Edge Function | Hybrid | URL + Cerefox token only; no local install. Advanced/fallback — prefer Path A-Local |
+| OpenAI Codex CLI (remote) | Path A-Remote — `cerefox-mcp` Edge Function | Hybrid | URL + Cerefox token env var; TOML config. Advanced/fallback — prefer Path A-Local |
 | ChatGPT (chatgpt.com or desktop) | Path B — Custom GPT → Edge Functions | Hybrid | ChatGPT Plus required |
 | Claude Desktop (local) | Path A-Local — `@cerefox/memory` via `npx` | Hybrid | Local alternative; Node.js; zero Edge Function invocations |
 | Claude Code (local) | Path A-Local — `@cerefox/memory` via `npx` | Hybrid | Local alternative; zero Edge Function invocations |
 | Cursor (local) | Path A-Local — `@cerefox/memory` via `npx` | Hybrid | Local alternative; zero Edge Function invocations |
-| Cloud Claude (claude.ai web) | Remote Supabase MCP | FTS only | No install; search quality limited |
-| Gemini CLI (remote) | Path A-Remote — `cerefox-mcp` Edge Function | Hybrid | URL + anon key only; no local install |
+| Cloud Claude (claude.ai web + mobile) | Path A-Remote — `cerefox-mcp` over **OAuth** | Hybrid | No install; **optional** one-time OAuth setup + a free Cloudflare Worker consent page ([setup-supabase Step 7](setup-supabase.md#step-7--oauth-for-cloud-agents-claudeai--mobile-optional)) |
+| Gemini CLI (remote) | Path A-Remote — `cerefox-mcp` Edge Function | Hybrid | URL + Cerefox token only; no local install. Advanced/fallback — prefer Path A-Local |
 | Local coding agents (Claude Code, Codex CLI, opencode, OpenClaw, Hermes, …) | Path C — Shell CLI (Bash tool) | Hybrid | `npm install -g @cerefox/memory`; agent runs `cerefox …` as a shell command. Useful when MCP setup is friction. |
 | curl / scripts | Path B — Edge Functions directly | Hybrid | Direct HTTP; no client needed |
-| Custom Python agents | Python SDK directly (legacy) | Hybrid | Local Python + repo clone; the Python path is legacy/frozen |
 
 > **"Hybrid"** = FTS + semantic, document-level (complete reconstructed notes, not isolated chunks).
 > **"FTS only"** = keyword search only; no semantic/vector search.
 
-> **Cloud hybrid for all clients (future)**: deploying the MCP server to Cloud Run would give
-> cloud clients (claude.ai, chatgpt.com) full hybrid search. Tracked in `docs/TODO.md`.
+> **Cloud hybrid for claude.ai / mobile (iter-28A)**: `cerefox-mcp` is now an OAuth 2.1
+> protected resource, so claude.ai web and the Claude mobile app get **full hybrid search**
+> over the standard tool surface — no Cloud Run needed. Setup:
+> [setup-supabase Step 7](setup-supabase.md#step-7--oauth-for-cloud-agents-claudeai--mobile-optional)
+> + [Cloud Claude](#cloud-claude-claudeai-web--mobile-oauth) below. (An OAuth connector for
+> ChatGPT becomes possible on the same server but is not yet documented.)
 
 > **Perplexity** supports stdio-only MCP on macOS Desktop (via Helper App). Remote MCP is
 > "coming soon." Perplexity's CTO has signalled a strategic shift away from MCP (March 2026),
@@ -88,20 +91,24 @@ in the container.
   in the per-client configs below if your client can't see the file)
 - `.env` must define `CEREFOX_SUPABASE_URL`, `CEREFOX_SUPABASE_KEY`, and your
   embedding API key (`OPENAI_API_KEY`)
-- A frozen Python MCP server still exists as a standalone fallback (`uv run cerefox mcp` from a
-  repo clone), but the npm package is the maintained path.
-
-> **Important — which anon key to use (2026):** Path A-Remote and Path B both require an
-> "anon key" as a Bearer token. As of 2026, you **must** use the **legacy anon JWT**
-> (`eyJ…`) — the new `sb_publishable_…` key is rejected by the Supabase Edge Function
-> gateway with `UNAUTHORIZED_INVALID_JWT_FORMAT`. Find the legacy key in **Project
-> Settings → API Keys → Legacy → anon**. This is a Supabase platform constraint;
-> see [`setup-supabase.md` → Supabase API keys (2026)](setup-supabase.md#supabase-api-keys-2026)
-> for the full story.
-
-**For Path A-Remote (remote MCP Edge Function) — recommended:**
+
+> **Important — the Cerefox access token (iter-28E):** Path A-Remote and Path B both require a
+> **Bearer token** on every request. That credential is now the **Cerefox access token**
+> (`cfx_pat_…`), a random, Cerefox-managed secret validated in-function — **not** the legacy
+> Supabase anon JWT (which is retired for all Edge Function paths). Generate it with
+> `cerefox token generate`: it sets the accepted token set on Supabase (the
+> `CEREFOX_ACCESS_TOKENS` Function secret) and writes the value to your local `.env` as
+> `CEREFOX_ACCESS_TOKEN`, printing it once so you can paste it into client configs. Lose it →
+> `cerefox token rotate`. See [`setup-supabase.md` → Step 7](setup-supabase.md#step-7--oauth-for-cloud-agents-claudeai--mobile-optional)
+> for the server-side setup.
+
+**For Path A-Remote (remote MCP Edge Function) — advanced / fallback:**
+> For **local agents** (Claude Code, Cursor, Codex, Gemini, Claude Desktop) the **local MCP**
+> (Path A-Local, via `cerefox configure-agent`) is the preferred path — zero Edge Function
+> cost and no token to distribute. Use Path A-Remote when you specifically want a hosted URL
+> (multiple machines, cloud dev environments) or as a fallback.
 - `cerefox-mcp` Edge Function deployed (`npx supabase functions deploy cerefox-mcp`)
-- Your **legacy anon JWT** (see callout above): Supabase Dashboard → Project Settings → API Keys → Legacy → anon
+- Your **Cerefox access token** (see callout above): run `cerefox token generate`
 - For Claude Desktop: [Node.js](https://nodejs.org) installed (for `npx supergateway` or `npx mcp-remote`)
 - For Claude Code: [Node.js](https://nodejs.org) for `npx mcp-remote` (recommended), or no extra deps for native HTTP
 
@@ -111,7 +118,7 @@ in the container.
   `cerefox-get-audit-log`, `cerefox-metadata-search`, `cerefox-list-projects`, `cerefox-mcp`.
   End-user path: `cerefox server deploy`. Contributor/manual path: `npx supabase functions
   deploy` (see `setup-supabase.md`).
-- Your **legacy anon JWT** (see callout above): Supabase Dashboard → Project Settings → API Keys → Legacy → anon
+- Your **Cerefox access token** (see callout above): run `cerefox token generate`
 - Your **project ref**: visible in the Supabase Dashboard URL
   (`app.supabase.com/project/<project-ref>`)
 
@@ -130,12 +137,6 @@ Edge Function, communicating with clients over stdio.
 The local server ships as an npm package — **[`@cerefox/memory`](https://www.npmjs.com/package/@cerefox/memory)** — built with the official `@modelcontextprotocol/sdk`.
 The bin entry is `cerefox` (run as `cerefox mcp`). The recommended client config is `npx -y --package=@cerefox/memory cerefox mcp`, or if you've installed the package globally, just `cerefox mcp`.
 
-A separate, **frozen** Python MCP server still exists as a standalone fallback — invoke it
-explicitly with `uv run cerefox mcp` from a Cerefox repo clone. It is independent and
-unmaintained; the npm package is the maintained path. (A "soft wrapper" that auto-delegated
-the Python `cerefox mcp` to the npm package was removed in v0.5.2 — the two are now fully
-separate. Pick one explicitly in your MCP client config.)
-
 - Embeddings are computed locally using your `.env` key (no extra credentials)
 - Works offline except for the OpenAI embedding API call per query
 - One setup, all compatible local clients (Claude Desktop, Cursor, Claude Code, Codex CLI, …)
@@ -317,8 +318,8 @@ https://<your-project-ref>.supabase.co/functions/v1/cerefox-mcp
 
 | Scenario | Prefer |
 |----------|--------|
-| Default / new setup | Path A-Remote -- no Python, no local clone, one URL works everywhere |
-| Multiple machines / cloud dev environments | Path A-Remote |
+| Default local agent (Claude Code, Cursor, Codex, Gemini, Claude Desktop) | Path A-Local -- preferred; `cerefox configure-agent`, zero Edge Function cost, no token to distribute |
+| Multiple machines / cloud dev environments | Path A-Remote -- one hosted URL works everywhere (needs a Cerefox token) |
 | Minimise Supabase Edge Function usage (free tier limits) | Path A-Local -- zero Edge Function invocations |
 | Offline use or development on the cerefox codebase | Path A-Local -- no network dependency |
 | Lowest latency (same machine, no HTTPS round-trip) | Path A-Local -- slightly faster |
@@ -355,7 +356,7 @@ Add to your project's `.mcp.json` (or copy
         "mcp-remote",
         "https://<your-project-ref>.supabase.co/functions/v1/cerefox-mcp",
         "--header",
-        "Authorization: Bearer <your-anon-key>"
+        "Authorization: Bearer <your-cerefox-token>"
       ]
     }
   }
@@ -370,7 +371,7 @@ overhead (fixed in v0.1.12). However, `mcp-remote` is still preferred for the OA
 ```bash
 claude mcp add --transport http cerefox \
   https://<your-project-ref>.supabase.co/functions/v1/cerefox-mcp \
-  --header "Authorization: Bearer <your-anon-key>"
+  --header "Authorization: Bearer <your-cerefox-token>"
 ```
 
 Verify:
@@ -382,7 +383,7 @@ For a user-scoped server (available in all projects), add `--scope user`:
 ```bash
 claude mcp add --transport http --scope user cerefox \
   https://<your-project-ref>.supabase.co/functions/v1/cerefox-mcp \
-  --header "Authorization: Bearer <your-anon-key>"
+  --header "Authorization: Bearer <your-cerefox-token>"
 ```
 
 ---
@@ -400,7 +401,7 @@ Cursor supports remote MCP servers natively via `url` + `headers` in `mcp.json`.
     "cerefox": {
       "url": "https://<your-project-ref>.supabase.co/functions/v1/cerefox-mcp",
       "headers": {
-        "Authorization": "Bearer <your-anon-key>"
+        "Authorization": "Bearer <your-cerefox-token>"
       }
     }
   }
@@ -441,19 +442,19 @@ Add (or merge into) the file:
       "args": [
         "-y", "supergateway",
         "--streamableHttp", "https://<your-project-ref>.supabase.co/functions/v1/cerefox-mcp",
-        "--oauth2Bearer", "<your-anon-key>"
+        "--oauth2Bearer", "<your-cerefox-token>"
       ]
     }
   }
 }
 ```
 
-Replace `<your-project-ref>` and `<your-anon-key>` with your actual values.
+Replace `<your-project-ref>` and `<your-cerefox-token>` with your actual values.
 
 **Important:**
 - Restart Claude Desktop fully (Cmd+Q on macOS) after saving the config.
 - `-y` tells npx to auto-install `supergateway` without prompting.
-- No Python, no local repo clone, no `.env` file needed — just the URL and anon key.
+- No Python, no local repo clone, no `.env` file needed — just the URL and Cerefox token.
 
 ---
 
@@ -462,13 +463,13 @@ Replace `<your-project-ref>` and `<your-anon-key>` with your actual values.
 [Codex](https://github.com/openai/codex) supports remote MCP servers natively via Streamable
 HTTP. Configuration uses TOML (not JSON like most other MCP clients).
 
-**Step 1 — Set the anon key as an environment variable:**
+**Step 1 — Set the Cerefox token as an environment variable:**
 
 Codex references Bearer tokens by environment variable name, not by value. Add to your
 `~/.zshrc` (or `~/.bashrc`):
 
 ```bash
-export CEREFOX_ANON_KEY="<your-anon-key>"
+export CEREFOX_ACCESS_TOKEN="<your-cerefox-token>"
 ```
 
 Then reload: `source ~/.zshrc`
@@ -478,7 +479,7 @@ Then reload: `source ~/.zshrc`
 ```toml
 [mcp_servers.cerefox]
 url = "https://<your-project-ref>.supabase.co/functions/v1/cerefox-mcp"
-bearer_token_env_var = "CEREFOX_ANON_KEY"
+bearer_token_env_var = "CEREFOX_ACCESS_TOKEN"
 ```
 
 Replace `<your-project-ref>` with your Supabase project ref.
@@ -489,9 +490,9 @@ Launch Codex and use the `/mcp` slash command to confirm the `cerefox` server is
 and all 10 tools are listed.
 
 **Notes:**
-- `bearer_token_env_var` is the **name** of the env var (e.g. `"CEREFOX_ANON_KEY"`), not the
+- `bearer_token_env_var` is the **name** of the env var (e.g. `"CEREFOX_ACCESS_TOKEN"`), not the
   token itself. Codex reads the value at runtime.
-- No Python, no local repo clone needed — just the URL and anon key.
+- No Python, no local repo clone needed — just the URL and Cerefox token.
 - No idle SSE polling cost — the 405 GET fix in `cerefox-mcp` prevents it.
 
 ---
@@ -514,14 +515,14 @@ Add (or merge into) the file:
     "cerefox": {
       "httpUrl": "https://<your-project-ref>.supabase.co/functions/v1/cerefox-mcp",
       "headers": {
-        "Authorization": "Bearer <your-anon-key>"
+        "Authorization": "Bearer <your-cerefox-token>"
       }
     }
   }
 }
 ```
 
-Replace `<your-project-ref>` and `<your-anon-key>` with your actual values.
+Replace `<your-project-ref>` and `<your-cerefox-token>` with your actual values.
 
 **Verify:**
 
@@ -554,11 +555,11 @@ stored in Supabase.
 All Edge Function calls require:
 
 ```
-Authorization: Bearer <your-anon-key>
+Authorization: Bearer <your-cerefox-token>
 Content-Type: application/json
 ```
 
-Find your anon key: **Supabase Dashboard → Project Settings → API Keys → Legacy → anon** (use the legacy JWT, not the new `sb_publishable_…` — see the API keys callout in the Prerequisites section).
+Generate your token: run `cerefox token generate` (it prints the `cfx_pat_…` Cerefox access token once and sets it on Supabase). The legacy Supabase anon JWT is no longer accepted for Edge Function calls — see the token callout in the Prerequisites section.
 
 ### Path B system prompt
 
@@ -580,7 +581,7 @@ overwrite blindly.
 ```bash
 curl -s -X POST \
   "https://<your-project-ref>.supabase.co/functions/v1/cerefox-search" \
-  -H "Authorization: Bearer <your-anon-key>" \
+  -H "Authorization: Bearer <your-cerefox-token>" \
   -H "Content-Type: application/json" \
   -d '{"query": "second brain", "match_count": 3}'
 ```
@@ -609,7 +610,7 @@ In the action editor, paste this schema (replace `<your-project-ref>`):
 openapi: 3.1.0
 info:
   title: Cerefox Knowledge Base
-  version: 2.1.0
+  version: 3.0.0
 servers:
   - url: https://<your-project-ref>.supabase.co/functions/v1
 paths:
@@ -1001,11 +1002,15 @@ paths:
 In the action's **Authentication** settings:
 - Type: **API Key**
 - Auth type: **Bearer**
-- API key: your Supabase **anon key**
+- API key: your **Cerefox access token** (`cfx_pat_…`). Generate it with
+  `cerefox token generate` (it prints the token once and sets it on Supabase).
+  The legacy Supabase anon key is no longer accepted (iter-28E).
 
-> **Important:** ChatGPT may reset the API key when you update the action schema.
-> If you get a 403 error after changing the schema, re-enter the anon key in the
-> authentication settings — the functions themselves are fine.
+> **Important:** ChatGPT resets the stored API key when you update the action
+> schema. This release bumps the schema `info.version`, so on your next schema
+> paste ChatGPT will clear the key — re-enter your **Cerefox access token** in the
+> authentication settings. (That reset is expected here: it's what swaps you off
+> the old anon key.)
 
 **Step 4 — Save and test**
 
@@ -1025,7 +1030,7 @@ Direct HTTP access — useful for shell scripts, CI pipelines, or one-off querie
 ```bash
 curl -s -X POST \
   "https://<your-project-ref>.supabase.co/functions/v1/cerefox-search" \
-  -H "Authorization: Bearer <your-anon-key>" \
+  -H "Authorization: Bearer <your-cerefox-token>" \
   -H "Content-Type: application/json" \
   -d '{"query": "knowledge management", "match_count": 5}'
 ```
@@ -1034,7 +1039,7 @@ curl -s -X POST \
 ```bash
 curl -s -X POST \
   "https://<your-project-ref>.supabase.co/functions/v1/cerefox-ingest" \
-  -H "Authorization: Bearer <your-anon-key>" \
+  -H "Authorization: Bearer <your-cerefox-token>" \
   -H "Content-Type: application/json" \
   -d '{
     "title": "Meeting Notes 2026-03-11",
@@ -1101,20 +1106,50 @@ See `docs/guides/configuration.md` → "Response size limit" for full details.
 
 ---
 
-### Cloud Claude (claude.ai web)
+### Cloud Claude (claude.ai web + mobile — OAuth) <a id="cloud-claude-claudeai-web--mobile-oauth"></a>
+
+> **Optional feature.** This is the only path that needs the OAuth setup + a hosted
+> consent page. If you don't use claude.ai web / mobile, skip it — every other client
+> works without it. Design + rationale:
+> [`docs/specs/oauth-mcp-server-design.md`](../specs/oauth-mcp-server-design.md).
 
-Claude.ai web can connect to the Supabase-hosted remote MCP (no local install):
+Claude.ai web **and the Claude mobile app** connect to your own `cerefox-mcp` Edge
+Function over **OAuth**, with the **full hybrid-search tool surface** — no local install.
+This replaces the old FTS-only `mcp.supabase.com` approach (raw keyword search over the
+tables, no semantic search, no Cerefox tool ergonomics).
 
-1. In Claude.ai: **Settings → Integrations → Add integration**
-2. Enter the MCP URL:
+**Prerequisite:** complete the one-time Supabase OAuth setup in
+[`setup-supabase.md` → Step 7](setup-supabase.md#step-7--oauth-for-cloud-agents-claudeai--mobile-optional)
+— enable the OAuth 2.1 Server, deploy the Cloudflare Worker consent page, create the owner
+user + `CEREFOX_OAUTH_OWNER_ID` pin, and register the Claude OAuth App
+(**`client_secret_post`**) whose Client ID/Secret you paste below.
+
+1. In Claude.ai (web): **Settings → Connectors → Add custom connector**.
+2. **Name**: `CerefoxMCP` (distinct from the local `cerefox` server, so both can coexist).
+3. **URL** (must be the `*.supabase.co` host — custom domains break OAuth discovery):
    ```
-   https://mcp.supabase.com/sse?project_ref=<your-project-ref>
+   https://<your-project-ref>.supabase.co/functions/v1/cerefox-mcp
    ```
-3. Authenticate with your Personal Access Token when prompted.
-
-> **Limitation**: The cloud Supabase MCP only supports **FTS keyword search** — no hybrid or
-> semantic search. For full hybrid search from the web, deploy the MCP server to Cloud Run
-> (see `docs/TODO.md` → "Remote HTTP MCP server").
+4. **Advanced settings → OAuth Client ID / OAuth Client Secret**: paste the Client ID and
+   Client Secret from the pre-registered OAuth App (setup-supabase Step 7d).
+5. Save. Claude runs the OAuth flow → redirects you to the **Cerefox consent page** (sign
+   in with the owner email/password from Step 7c, then **Allow**) → returns to Claude. The
+   connector shows as connected with **10 tools**. (If you've approved before, Supabase
+   auto-consents and the page just flashes through — that's expected.)
+6. **Mobile**: connectors are account-level, so `CerefoxMCP` appears in the Claude mobile
+   app automatically — run one search from your phone to confirm.
+
+**Verify**: in a new chat with the connector enabled, ask *"Using CerefoxMCP, search the
+Cerefox Decision Log and give the title of the latest part."* A correct answer proves
+search + document reconstruction over the OAuth path.
+
+> **If the connect fails right after consent** with an `ofid_…` reference: the OAuth App's
+> token endpoint auth method is wrong. It must be **`request body` (`client_secret_post`)**,
+> not HTTP Basic — see setup-supabase Step 7d. This is the most common mistake.
+
+> **Cost note**: each cloud tool call is ~1 Edge Function invocation. Fine for interactive
+> use; for heavy/automated work prefer the local stdio server (zero EF cost). Your local
+> and static-Bearer clients (Claude Code, Cursor, Codex, Gemini, Desktop) are unchanged.
 
 ---
 
@@ -1237,39 +1272,6 @@ There is nothing Cerefox-specific to configure for the agent itself — just the
 
 ---
 
-## Custom agents (Python SDK — legacy)
-
-> **Legacy/frozen path.** The Python codebase is no longer the maintained runtime — the CLI,
-> local MCP server, and deploy tooling have all moved to TypeScript (`@cerefox/memory`). The
-> Python client below still works from a repo clone but is unmaintained. Prefer Path A (MCP),
-> Path B (Edge Functions HTTP), or Path C (the `cerefox` CLI) for new integrations.
-
-Use the Cerefox Python client directly for scripted or embedded agents (from a repo clone):
-
-```python
-from cerefox.config import Settings
-from cerefox.db.client import CerefoxClient
-from cerefox.embeddings.cloud import CloudEmbedder
-from cerefox.retrieval.search import SearchClient
-
-settings = Settings()            # reads from .env
-client = CerefoxClient(settings)
-embedder = CloudEmbedder(
-    api_key=settings.get_embedder_api_key(),
-    base_url=settings.get_embedder_base_url(),
-    model=settings.get_embedder_model(),
-    dimensions=settings.get_embedder_dimensions(),
-)
-sc = SearchClient(client, embedder, settings)
-
-resp = sc.search_docs("what did I write about Rust?", match_count=5)
-for hit in resp.results:
-    print(f"[{hit.best_score:.2f}] {hit.doc_title}")
-    print(hit.full_content[:400])
-```
-
----
-
 ## Keeping both paths in sync
 
 Both paths use the same Postgres RPCs and the same stored embeddings, but embed queries
@@ -1539,7 +1541,3 @@ claude mcp add --scope user cerefox \
 If `.env` isn't resolvable from your shell's CWD, edit the resulting JSON config to add an
 `env` block (see the Claude Desktop block above). The **Code** tab inside Claude Desktop uses
 this same config — run the `claude mcp add` above and it picks it up automatically.
-
-> The legacy Python MCP server can be wired manually as a standalone fallback by pointing the
-> `command` at `uv` with args `["--directory", "/path/to/cerefox", "run", "cerefox", "mcp"]`.
-> It is frozen and unmaintained — prefer the npm entry above.

package/docs/guides/content-format.md

@@ -0,0 +1,55 @@
+# Document content format (chunk reconstruction)
+
+Cerefox stores each document as a set of **chunks** (for search and small-to-big
+retrieval) and reassembles the full text from those chunks whenever you read a
+document. The **content format** records *how* a document's chunks reassemble.
+You normally never need to think about it: it exists so that a fix shipped in a
+later version can't change how your older documents read back.
+
+There are two formats:
+
+| Format | Meaning | When |
+|---|---|---|
+| **1 — legacy** | Chunk contents were trimmed sections; the full document is rebuilt by joining them with a blank line (`\n\n`) on read. | Every document written before the fix (Cerefox ≤ 0.11.x). |
+| **2 — blind-stitch** | Chunk contents are an exact, gapless slice-by-slice partition of the document; the full document is rebuilt by plain concatenation (nothing is inserted between chunks). | Documents written by the newer exact-partition chunker. |
+
+## Why it exists
+
+The older reconstruction always inserted a `\n\n` between chunks on read — a
+separator that was **never actually stored**. That is only correct if a chunk
+boundary falls exactly on a paragraph break. When a boundary fell elsewhere (for
+example, inside a large markdown table that has no blank lines), reconstruction
+injected a spurious blank line mid-content — splitting a table row, or turning
+`Source` into `Sour` + blank line + `ce`. A handful of large documents were
+corrupted this way.
+
+Format 2 fixes this at the root: because the stored chunks are an exact partition
+of the document, reconstruction just concatenates them and gets the original back
+byte-for-byte, so a chunk boundary can fall anywhere with zero corruption.
+
+The format is stored **per chunk** (on `cerefox_chunks`), not per document, so an
+archived version of a document always reconstructs with the format it was written
+in — even after the current version has moved to format 2.
+
+## Do I need to do anything?
+
+**No.** The migration is lazy and safe:
+
+- **Existing documents keep format 1** and reconstruct exactly as they always did.
+  Nothing is re-processed, nothing re-embeds.
+- A document **moves to format 2 automatically the next time it is edited/saved**
+  (it gets re-chunked by the new chunker).
+- If you want to convert everything now rather than on next edit, run
+  `cerefox server reindex` (re-chunks + re-embeds the whole knowledge base).
+
+`cerefox doctor` reports how many documents still use the legacy format — purely
+informational, never a failure. A fresh install shows zero.
+
+## For contributors
+
+- Column: `cerefox_chunks.content_format SMALLINT NOT NULL DEFAULT 1`.
+- The ingest RPC (`cerefox_ingest_document`) takes `p_content_format` and stamps it
+  on every chunk it writes; the exact-partition chunker path passes `2`.
+- The reconstruction RPCs branch on `MAX(content_format) >= 2` per aggregated group
+  (blind concat vs the legacy `\n\n`-join).
+- Design: `docs/specs/chunk-reconstruction-design.md`.

package/docs/guides/migration-1.0.md

@@ -0,0 +1,96 @@
+# Migrating to Cerefox 1.0.0
+
+Cerefox 1.0.0 is the first stable release. Two changes need attention when you
+upgrade an existing Supabase deployment; a third is automatic. **Nothing here
+affects the local/self-hosted (World B) backend.**
+
+Pre-releases are published on the `1.0.0-beta.N` line (breaking changes may still
+occur between betas) leading up to `1.0.0`.
+
+## 1. Edge Function auth: anon key → Cerefox access token (action required)
+
+The legacy Supabase **anon JWT** is no longer accepted for calling Cerefox Edge
+Functions. Every function now validates a rotatable, Cerefox-managed **access token**
+(`cfx_pat_…`) in-function. This is a **breaking change** for two client classes:
+
+- **ChatGPT Custom GPTs** using GPT Actions.
+- **Remote HTTP MCP** clients (any client pointed at `cerefox-mcp` with a static Bearer).
+
+**Local agents and cloud Claude are unaffected** (local MCP uses the Data API; cloud
+Claude uses OAuth).
+
+### `.env` / secrets changes
+
+| Variable | Change |
+|---|---|
+| `CEREFOX_ACCESS_TOKENS` | **New** — Supabase **Function secret**, the server-side accepted set (comma-separated; enables rotation). Set by `cerefox token generate`. |
+| `CEREFOX_ACCESS_TOKEN` | **New** — in your local `.env`, the token this machine presents (used by `cerefox doctor`, the live tests, and the optional remote-MCP client). Written by `cerefox token generate`. |
+| `CEREFOX_MCP_STATIC_BEARER` | **Remove** — the legacy anon static-Bearer for `cerefox-mcp` is gone. |
+| `CEREFOX_SUPABASE_ANON_KEY` | **No longer used** for Edge Function auth. Safe to delete from `.env`. |
+| `CEREFOX_SUPABASE_URL`, `CEREFOX_SUPABASE_KEY` | **Unchanged** — the Data API / local MCP path is not affected. |
+
+### Steps (in order — there is a brief cutover window)
+
+1. **Generate the token:** `cerefox token generate` — mints it, sets the
+   `CEREFOX_ACCESS_TOKENS` Function secret on Supabase, writes `CEREFOX_ACCESS_TOKEN`
+   into your `.env`, and prints it once.
+2. **Deploy the token-gated functions** (this also applies change #2 below):
+   `cerefox server deploy`. (If `CEREFOX_ACCESS_TOKENS` is unset, the functions reject
+   every caller, so keep step 1 first.)
+3. **Update your clients** (promptly after step 2):
+   - **Custom GPT (GPT Actions):** re-paste the OpenAPI schema (its `info.version` bumped,
+     so ChatGPT clears the stored key), then set **Authentication → API Key** to your
+     Cerefox access token (Bearer).
+   - **Remote HTTP MCP:** replace the anon key in the `Authorization: Bearer` header.
+4. **Verify:** `cerefox doctor` (the edge-functions check should pass).
+5. **Revoke the legacy anon key** in the Supabase dashboard (Project Settings → API Keys →
+   Legacy). Nothing at runtime uses it anymore.
+6. **Remove the retired consent Edge Function** (if you deployed it):
+   `npx supabase functions delete cerefox-oauth-consent`. The OAuth consent page is now
+   served solely by the Cloudflare Worker (`cloudflare/cerefox-consent/`).
+
+Rotating the token later: `cerefox token rotate` (accepts new + old for zero-downtime),
+then `cerefox token rotate --finalize` once every client is on the new token.
+
+## 2. New schema (0.7.0 → 0.8.0): document reconstruction fix (redeploy required, no data action)
+
+1.0.0 fixes a document-reconstruction bug that could corrupt documents containing large
+tables or blank-line-free paragraphs. It adds a `content_format` column on
+`cerefox_chunks`. **You just redeploy** — `cerefox server deploy` (step 2 above) applies
+the schema change.
+
+The migration is **lazy and safe**:
+
+- Existing documents keep the legacy format and reconstruct **exactly as before** — nothing
+  re-processes, nothing re-embeds.
+- A document moves to the new format automatically the next time it is edited/saved. To
+  convert everything now instead, run `cerefox server reindex`.
+- `cerefox doctor` shows how many documents still use the legacy format.
+
+Details: `cerefox guides show content-format` (or [`content-format.md`](content-format.md)).
+
+## 3. Python is fully removed at 1.0.0 (breaking)
+
+**The Python implementation is deleted in 1.0.0** — including the frozen MCP-server fallback
+(`uv run cerefox mcp`), the husked Python CLI / web / ingestion packages, and
+`pyproject.toml`. There is no Python code left to run.
+
+If you still invoke `uv run cerefox mcp`, switch to the maintained local server:
+
+```bash
+npx --package=@cerefox/memory cerefox mcp
+```
+
+(or stay on 0.11.x until you have migrated). The TypeScript CLI, local MCP, remote MCP, and
+web app are the only maintained paths. The SQL schema assets under `src/cerefox/db/` are
+unaffected — they are not Python and remain the source of truth for the schema + RPCs.
+
+## Upgrade order summary
+
+```bash
+cerefox self-update            # or: npm install -g @cerefox/memory@latest
+cerefox token generate         # change #1: mint + set the access token
+cerefox server deploy          # changes #1 + #2: token-gated EFs + schema 0.8.0
+cerefox doctor                 # verify (edge-functions green; content-format ℹ)
+# then: update GPT Actions / remote MCP clients to the token; revoke the anon key
+```

package/docs/guides/ops-scripts.md

@@ -30,10 +30,8 @@ The canonical scripts are **TypeScript**, run with [Bun](https://bun.sh) (instal
 | `backup_restore.ts` | `bun scripts/backup_restore.ts` |
 | `reindex_all.ts` | `bun scripts/reindex_all.ts` |
 
-The `.py` equivalents are **legacy** — they still exist as a migration aid but are no longer
-maintained; use the `.ts` scripts. The legacy `db_status.py` and `sync_docs.py` are
-deprecation shims that exit non-zero with a pointer to the TS replacement, so update any cron
-jobs / CI / make targets that invoke them.
+Use the `.ts` scripts. The former `.py` equivalents were **removed at v1.0.0** — update any
+cron jobs / CI / make targets that still invoke a `python scripts/*.py` path.
 
 ### TS scripts and `.env` resolution
 
@@ -75,7 +73,7 @@ CEREFOX_DATABASE_URL=postgresql://cerefox:cerefox@localhost:5432/cerefox \
 
 ## db_status.ts — Schema verification
 
-**TypeScript (v0.3.0+).** Checks that the schema is correctly deployed and reports table statistics. Replaces the legacy `db_status.py`, which now prints a deprecation notice and exits non-zero.
+**TypeScript (v0.3.0+).** Checks that the schema is correctly deployed and reports table statistics. Replaces the former `db_status.py` (removed at v1.0.0).
 
 ```bash
 bun scripts/db_status.ts          # human-readable report
@@ -223,7 +221,7 @@ The backup directory (`./backup-data/` by default) is gitignored. Back up the ba
 
 Ingests `README.md`, `AGENT_GUIDE.md`, `AGENT_QUICK_REFERENCE.md`, and every Markdown file under `docs/` into your Cerefox knowledge base, updating existing documents in-place. Run this any time after editing documentation so AI agents always have access to the current state of the project.
 
-Replaces the legacy `sync_docs.py`, which now prints a deprecation notice and exits non-zero.
+Replaces the former `sync_docs.py` (removed at v1.0.0).
 
 ```bash
 bun scripts/sync_docs.ts [OPTIONS]
@@ -234,7 +232,7 @@ bun scripts/sync_docs.ts [OPTIONS]
 | `--project NAME`, `-p NAME` | Project to assign documents to (default: `cerefox`) |
 | `--dry-run`, `-n` | List files that would be synced without ingesting anything |
 
-**Requires**: `CEREFOX_SUPABASE_URL` and `CEREFOX_SUPABASE_ANON_KEY` (the legacy anon JWT — `eyJ…` — used to invoke Edge Functions). Embedding happens server-side inside the `cerefox-ingest` Edge Function, so you don't need an OpenAI / Fireworks key in your local env for the TS script.
+**Requires**: `CEREFOX_SUPABASE_URL` and `CEREFOX_ACCESS_TOKEN` (the Cerefox access token — `cfx_pat_…`, from `cerefox token generate` — the Bearer used to invoke Edge Functions). Embedding happens server-side inside the `cerefox-ingest` Edge Function, so you don't need an OpenAI / Fireworks key in your local env for the TS script.
 
 The target project must already exist (create it with `cerefox project create cerefox` if needed).
 

package/docs/guides/quickstart.md

@@ -80,6 +80,26 @@ On an existing database this applies pending migrations and re-applies RPCs
 in place, so re-run it after upgrading. Detailed walkthrough:
 [`setup-supabase.md`](setup-supabase.md).
 
+## 3b. Generate the Edge Function access token
+
+The Edge Functions authenticate callers with a **Cerefox access token**. You need it
+if you'll connect a **Custom GPT** (GPT Actions) or a **remote HTTP MCP** client, and
+for a fully-green `cerefox doctor`. The **local MCP** (local agents), **cloud Claude**
+(OAuth), and the CLI/web reach Supabase over the Data API and don't use it — so this
+step is optional if that's your whole setup, but it's quick and harmless to run:
+
+```bash
+cerefox token generate
+```
+
+This creates a `cfx_pat_…` token, sets it as the `CEREFOX_ACCESS_TOKENS` secret on
+Supabase, and writes `CEREFOX_ACCESS_TOKEN` into your `.env` (so `cerefox doctor`,
+your tools, and any remote client can use it). It prints the token **once** — store
+it. You only need to paste it somewhere by hand if you connect a **Custom GPT**
+(into the Action's Authentication → API Key) or a **remote HTTP MCP** client; the
+local MCP and cloud Claude (OAuth) don't use it. Lose it → `cerefox token rotate`.
+Run `cerefox doctor` again — the "edge functions" check should now be green.
+
 ## 4. Wire up an AI agent
 
 ```bash
@@ -113,8 +133,8 @@ You should see results from the bundled self-docs.
 
 The path above is for **end users** (no clone). If you want to hack on Cerefox,
 clone the repo, run `bun install`, and use the contributor scripts
-(`bun scripts/db_deploy.ts`, `bun scripts/db_migrate.ts`). `uv` is only needed
-for the legacy Python MCP fallback. See [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
+(`bun scripts/db_deploy.ts`, `bun scripts/db_migrate.ts`). See
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md).
 (Want a no-cloud install instead? That's the self-hosted Docker backend —
 [`setup-local.md`](setup-local.md).)