@cerefox/memory 1.17.4 → 1.19.0

package/dist/server-assets/db/schema.sql

@@ -5,7 +5,7 @@
 -- Requires extensions: vector (pgvector), uuid-ossp
 -- These are enabled at the top of db_deploy.py before this file is applied.
 --
--- @version: 0.18.2
+-- @version: 0.21.1
 -- The `@version` marker above is read by the schema-version-mismatch banner
 -- (see /api/v1/schema-version). Bump it whenever schema.sql OR rpcs.sql
 -- changes in a way that requires `cerefox server deploy` to be re-run —
@@ -40,7 +40,9 @@ CREATE TABLE IF NOT EXISTS cerefox_documents (
     source          TEXT        NOT NULL DEFAULT 'manual',
     -- source values: 'file' | 'paste' | 'agent' | 'url' | 'manual'
     source_path     TEXT,
-    -- SHA-256 of raw markdown content; used for deduplication
+    -- SHA-256 of raw markdown content: the optimistic-concurrency token, and
+    -- the create-time duplicate check (live documents only, in
+    -- cerefox_ingest_document). Deliberately NOT unique (0.20.0, #332).
     content_hash    TEXT        NOT NULL,
     -- #212 (0.12.2): must be a JSON OBJECT — jsonb accepts any JSON value,
     -- but every reader assumes an object, and non-object values were silently
@@ -51,6 +53,12 @@ CREATE TABLE IF NOT EXISTS cerefox_documents (
     metadata        JSONB       NOT NULL DEFAULT '{}'::jsonb
                     CONSTRAINT cerefox_documents_metadata_object
                     CHECK (jsonb_typeof(metadata) = 'object'),
+    -- #333 (0.21.0): the metadata's optimistic-concurrency token, independent
+    -- of content_hash (which covers the body only). Starts at 1 and goes up by
+    -- one whenever `metadata` actually changes; maintained by the
+    -- trig_cerefox_documents_metadata_revision trigger below, so every writer
+    -- is covered and no caller can set it.
+    metadata_revision INT       NOT NULL DEFAULT 1,
     chunk_count     INT         NOT NULL DEFAULT 0,
     total_chars     INT         NOT NULL DEFAULT 0,
     -- review_status: human governance flag. 'approved' = validated by human,
@@ -71,7 +79,6 @@ CREATE TABLE IF NOT EXISTS cerefox_documents (
     -- Search indexes exclude soft-deleted docs. Purge does the real CASCADE DELETE.
     deleted_at      TIMESTAMPTZ DEFAULT NULL,
 
-    CONSTRAINT cerefox_documents_hash_unique UNIQUE (content_hash),
     CONSTRAINT cerefox_documents_review_status_check CHECK (review_status IN ('approved', 'pending_review'))
 );
 
@@ -127,6 +134,11 @@ CREATE TABLE IF NOT EXISTS cerefox_audit_log (
     -- author_type: 'user' (human via web UI/CLI) or 'agent' (AI via MCP/Edge Function)
     size_before     INT,
     size_after      INT,
+    -- #333 (0.21.0): on 'update-metadata' entries, the document's metadata
+    -- before and after the change, so every metadata change is recoverable
+    -- (content versions never captured metadata). NULL on other operations.
+    metadata_before JSONB,
+    metadata_after  JSONB,
     description     TEXT        NOT NULL DEFAULT '',
     -- description: free-text explaining what changed and why.
     -- Auto-generated for system actions (approval, archival, retention cleanup).
@@ -166,7 +178,7 @@ CREATE TABLE IF NOT EXISTS cerefox_document_projects (
 -- ── Document relations (iteration 29) ─────────────────────────────────────────
 -- Typed, directed edges between documents. rel_type is free text by design so
 -- agents can define new types without a migration; the type dictionary lives in
--- the RPCs and gives KNOWN types behaviour (symmetry, lifecycle side effects).
+-- the RPCs and gives KNOWN types behavior (symmetry, lifecycle side effects).
 -- Design: docs/research/document-relations-and-semantic-graph.md §2.2.
 
 CREATE TABLE IF NOT EXISTS cerefox_document_relations (
@@ -267,17 +279,11 @@ CREATE INDEX IF NOT EXISTS idx_cerefox_chunks_fts
     ON cerefox_chunks USING GIN(fts)
     WHERE version_id IS NULL;
 
--- Vector similarity — primary embedding, current chunks only
-CREATE INDEX IF NOT EXISTS idx_cerefox_chunks_emb_primary
-    ON cerefox_chunks USING hnsw (embedding_primary vector_cosine_ops)
-    WITH (m = 16, ef_construction = 64)
-    WHERE version_id IS NULL;
-
--- Vector similarity — upgrade embedding, current chunks only
-CREATE INDEX IF NOT EXISTS idx_cerefox_chunks_emb_upgrade
-    ON cerefox_chunks USING hnsw (embedding_upgrade vector_cosine_ops)
-    WITH (m = 16, ef_construction = 64)
-    WHERE version_id IS NULL;
+-- Vector similarity: deliberately NO index (0.19.0, migration 0034). Search
+-- ranks vector candidates by an exact scan, which is both correct and fast at
+-- knowledge-base scale; the HNSW indexes it replaced returned too few, mostly
+-- wrong candidates on stores with version churn. Do not add one back without
+-- the measurements in docs/specs/search-calibration.md (scale section).
 
 -- Partial unique index: enforces (document_id, chunk_index) uniqueness for
 -- current chunks. Archived chunks are excluded and may share chunk_index values
@@ -295,7 +301,7 @@ CREATE INDEX IF NOT EXISTS idx_cerefox_chunks_version
 CREATE INDEX IF NOT EXISTS idx_cerefox_docs_metadata
     ON cerefox_documents USING GIN(metadata);
 
--- Documents by content_hash (unique constraint covers equality; this covers range/prefix)
+-- Documents by content_hash (the create-time duplicate check and hash lookups)
 CREATE INDEX IF NOT EXISTS idx_cerefox_docs_hash
     ON cerefox_documents(content_hash);
 
@@ -350,6 +356,31 @@ CREATE OR REPLACE TRIGGER trig_cerefox_chunks_updated
     BEFORE UPDATE ON cerefox_chunks
     FOR EACH ROW EXECUTE FUNCTION cerefox_set_updated_at();
 
+-- ── metadata_revision trigger (#333, 0.21.0) ─────────────────────────────────
+-- Bumps metadata_revision when, and only when, metadata actually changes. A
+-- trigger rather than per-RPC code because metadata has several writers (the
+-- metadata RPC, the ingest RPC, direct table updates from older clients), and
+-- a counter that one of them forgets to bump is a token that lies. It also
+-- pins the column on every other UPDATE, so no caller can set it directly.
+CREATE OR REPLACE FUNCTION cerefox_bump_metadata_revision()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+BEGIN
+    IF NEW.metadata IS DISTINCT FROM OLD.metadata THEN
+        NEW.metadata_revision := OLD.metadata_revision + 1;
+    ELSE
+        NEW.metadata_revision := OLD.metadata_revision;
+    END IF;
+    RETURN NEW;
+END;
+$$;
+
+CREATE OR REPLACE TRIGGER trig_cerefox_documents_metadata_revision
+    BEFORE UPDATE ON cerefox_documents
+    FOR EACH ROW EXECUTE FUNCTION cerefox_bump_metadata_revision();
+
 
 -- ── Live-database migration ───────────────────────────────────────────────────
 -- When applying this schema to an existing database that still has the old
@@ -408,7 +439,7 @@ ON CONFLICT (key) DO NOTHING;
 -- The review workflow (agent writes land pending_review, a person approves)
 -- is OFF on a fresh install (#241): most stores have no reviewer, and a queue
 -- nobody drains is noise. Migration 0031 seeds TRUE on stores that predate the
--- flag, so an upgrade never changes behaviour. Only this seed and that
+-- flag, so an upgrade never changes behavior. Only this seed and that
 -- migration ever write the value; the toggle itself is `cerefox config set`.
 INSERT INTO cerefox_config (key, value)
 VALUES ('review_workflow_enabled', 'false')
@@ -491,7 +522,7 @@ ALTER TABLE cerefox_document_relations    ENABLE ROW LEVEL SECURITY;
 -- Guarded: on the local (World B) stack this file deploys BEFORE roles.sql
 -- creates service_role, so missing-role must be a no-op (roles.sql re-runs the
 -- grants implicitly via its own PostgREST wiring; the next deploy picks them up).
--- DERIVED from the catalogue, never listed. The list used to be a hand-written
+-- DERIVED from the catalog, never listed. The list used to be a hand-written
 -- ARRAY and it drifted: cerefox_document_relations was added above and never
 -- added to the array, so a FRESH cloud deploy left that table with no Data API
 -- grant. Upgrades hid it (migration 0014 grants it inline) and the self-hosted

package/dist/server-assets/supabase/functions/cerefox-get-document/index.ts

@@ -19,7 +19,8 @@ import { callerIdentity } from "../../../_shared/mcp-tools/identity.ts";
  *   { document_id: string, version_id?: string | null }
  *
  * Response (200):
- *   { document_id, doc_title, full_content, chunk_count, total_chars, is_archived, version_id, content_hash }
+ *   { document_id, doc_title, full_content, chunk_count, total_chars, is_archived, version_id, content_hash,
+ *     metadata, metadata_revision }
  * Response (404):
  *   { error: "Document not found" }
  * Response (400):
@@ -108,6 +109,8 @@ Deno.serve(async (req: Request): Promise<Response> => {
       chunk_count?: number;
       total_chars?: number;
       content_hash?: string;
+      doc_metadata?: Record<string, unknown> | null;
+      metadata_revision?: number | null;
     } | undefined;
 
     if (!row) {
@@ -138,6 +141,10 @@ Deno.serve(async (req: Request): Promise<Response> => {
         // Optimistic-concurrency token (iter-32): always the CURRENT hash —
         // pass back as expected_content_hash when updating via ingest.
         content_hash: row.content_hash ?? null,
+        // #333: the metadata and its own token — pass metadata_revision back as
+        // expected_metadata_revision when changing metadata via ingest.
+        metadata: row.doc_metadata ?? {},
+        metadata_revision: version_id === null ? (row.metadata_revision ?? null) : null,
       }),
       { status: 200, headers: { ...CORS_HEADERS, "Content-Type": "application/json" } },
     );

package/dist/server-assets/supabase/functions/cerefox-ingest/index.ts

@@ -3,6 +3,7 @@ import { createClient } from "jsr:@supabase/supabase-js@2";
 import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/index.ts";
 import { efAuthGate } from "../../../_shared/ef-auth/index.ts";
 import { callerIdentity } from "../../../_shared/mcp-tools/identity.ts";
+import { duplicateContentDocumentId, legacyContentUniqueError } from "../../../_shared/mcp-tools/_utils.ts";
 import { capEmbeddingInput } from "../../../_shared/embeddings/index.ts";
 import {
   ensureDocumentInProject,
@@ -61,24 +62,26 @@ interface IngestRequest {
   expected_content_hash?: string;
   // Explicitly skip the concurrency check (external source of truth).
   last_write_wins?: boolean;
+  // #333: the metadata's token, checked when `metadata` is passed on an update
+  // (metadata merges; a null value removes a key).
+  expected_metadata_revision?: number;
 }
 
 // Map the RPC's expected/validation errors to proper HTTP responses:
 //   CEREFOX_CONFLICT                → 409 (stale optimistic-concurrency token)
 //   CEREFOX_TOKEN_REQUIRED          → 400 (missing expected_content_hash)
-//   cerefox_documents_hash_unique   → 409 (content de-dup: another doc already
-//                                          holds identical content)
+//   CEREFOX_METADATA_CONFLICT       → 409 (stale expected_metadata_revision, #333)
 // Returns null for genuinely unexpected errors (→ 500 at the call site).
 function concurrencyErrorResponse(
   message: string,
   headers: Record<string, string>,
 ): Response | null {
-  if (message.includes("cerefox_documents_hash_unique")) {
+  if (message.includes("CEREFOX_METADATA_CONFLICT")) {
     return new Response(
       JSON.stringify({
-        error: "duplicate_content",
+        error: "metadata_conflict",
         message:
-          "Another document already has identical content. Cerefox de-duplicates by content hash — update that document instead of creating or editing a second copy to match it.",
+          "The document's metadata changed since it was read. Re-read it (getDocument), reapply your change, and retry with the new expected_metadata_revision.",
         detail: message,
       }),
       { status: 409, headers },
@@ -278,7 +281,7 @@ Deno.serve(async (req: Request) => {
   // metadata: null = "not provided" — the RPC keeps existing metadata on
   // update and uses {} on create (v0.11.1; a `= {}` default here used to wipe
   // a document's tags on every content update that didn't re-pass them).
-  const { title, content, document_id = null, project_name, source = "agent", metadata = null, update_if_exists = false, author_type = "agent", expected_content_hash = null, last_write_wins = false } = body;
+  const { title, content, document_id = null, project_name, source = "agent", metadata = null, update_if_exists = false, author_type = "agent", expected_content_hash = null, last_write_wins = false, expected_metadata_revision = null } = body;
   const callerName = callerIdentity(body as unknown as Record<string, unknown>);
   const author = callerName ?? "agent";
 
@@ -436,6 +439,9 @@ Deno.serve(async (req: Request) => {
       p_source_label: source,
       p_expected_content_hash: expected_content_hash,
       p_last_write_wins: last_write_wins,
+      // Only when set (#333 review): a null would name a signature a pre-0.21.0
+      // schema lacks, failing the whole update.
+      ...(expected_metadata_revision != null ? { p_expected_metadata_revision: expected_metadata_revision } : {}),
       p_content_format: CONTENT_FORMAT_BLIND_STITCH,
     });
 
@@ -554,6 +560,9 @@ Deno.serve(async (req: Request) => {
         p_source_label: source,
         p_expected_content_hash: expected_content_hash,
         p_last_write_wins: last_write_wins,
+        // Only when set (#333 review): a null would name a signature a pre-0.21.0
+      // schema lacks, failing the whole update.
+      ...(expected_metadata_revision != null ? { p_expected_metadata_revision: expected_metadata_revision } : {}),
       p_content_format: CONTENT_FORMAT_BLIND_STITCH,
       });
 
@@ -600,10 +609,14 @@ Deno.serve(async (req: Request) => {
   }
 
   // ── Hash deduplication (normal create path) ────────────────────────────────
+  // Creates only, against LIVE documents (#332). Saves the embedding spend;
+  // the RPC repeats the check authoritatively.
   const { data: hashMatch } = await supabase
     .from("cerefox_documents")
     .select("id, title")
     .eq("content_hash", contentHash)
+    .is("deleted_at", null)
+    .order("created_at", { ascending: true })
     .limit(1);
 
   if (hashMatch?.length) {
@@ -665,7 +678,30 @@ Deno.serve(async (req: Request) => {
     p_content_format: CONTENT_FORMAT_BLIND_STITCH,
   });
 
+  // The RPC's duplicate check caught an identical create that landed after
+  // the pre-check above. Nothing was written; answer as the pre-check does.
+  const duplicateId = duplicateContentDocumentId(ingestErr?.message ?? "");
+  if (duplicateId) {
+    const { data: existing } = await supabase
+      .from("cerefox_documents")
+      .select("title")
+      .eq("id", duplicateId)
+      .maybeSingle();
+    return new Response(
+      JSON.stringify({
+        document_id: duplicateId,
+        title: existing?.title ?? title.trim(),
+        skipped: true,
+        message: "Document already exists (content hash match)",
+      }),
+      { headers },
+    );
+  }
   if (ingestErr || !ingestResult?.length) {
+    // Functions deployed ahead of the schema still meet the pre-0.20.0
+    // store-wide content constraint.
+    const legacy = legacyContentUniqueError(ingestErr?.message ?? "");
+    if (legacy) return new Response(JSON.stringify({ error: legacy.message }), { status: 409, headers });
     return new Response(
       JSON.stringify({ error: `Ingest RPC failed: ${ingestErr?.message ?? "no data returned"}` }),
       { status: 500, headers },

package/docs/api/openapi.json

@@ -206,6 +206,34 @@
                       "created_at": {
                         "default": "",
                         "type": "string"
+                      },
+                      "metadata_before": {
+                        "anyOf": [
+                          {
+                            "type": "object",
+                            "propertyNames": {
+                              "type": "string"
+                            },
+                            "additionalProperties": {}
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
+                      },
+                      "metadata_after": {
+                        "anyOf": [
+                          {
+                            "type": "object",
+                            "propertyNames": {
+                              "type": "string"
+                            },
+                            "additionalProperties": {}
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
                       }
                     },
                     "required": [
@@ -1498,6 +1526,18 @@
                         "null"
                       ]
                     },
+                    "metadata_revision": {
+                      "anyOf": [
+                        {
+                          "type": "integer",
+                          "minimum": -9007199254740991,
+                          "maximum": 9007199254740991
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
                     "versions": {
                       "default": [],
                       "type": "array",
@@ -2007,7 +2047,7 @@
                     }
                   },
                   "metadata": {
-                    "description": "Replaces the metadata. `{}` clears every key; omit to leave it unchanged.",
+                    "description": "Replaces the metadata (this route edits it as a whole form). `{}` clears every key; omit to leave it unchanged. Send expected_metadata_revision with it.",
                     "type": "object",
                     "propertyNames": {
                       "type": "string"
@@ -2021,6 +2061,19 @@
                       "null"
                     ]
                   },
+                  "expected_metadata_revision": {
+                    "description": "The metadata_revision you read (GET /documents/{id}). Required with `metadata` for an identified caller; a stale one is a 409.",
+                    "anyOf": [
+                      {
+                        "type": "integer",
+                        "minimum": -9007199254740991,
+                        "maximum": 9007199254740991
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
                   "last_write_wins": {
                     "description": "Skip the concurrency check. Only when an external source of truth makes a conflict meaningless.",
                     "type": "boolean"
@@ -3471,12 +3524,19 @@
                     "type": "string"
                   },
                   "metadata": {
+                    "description": "On an update it MERGES into the stored metadata: a null value removes a key, omitted keys are kept.",
                     "type": "object",
                     "propertyNames": {
                       "type": "string"
                     },
                     "additionalProperties": {}
                   },
+                  "expected_metadata_revision": {
+                    "description": "Optional, with metadata on an update: the metadata_revision you read. A stale one is a 409.",
+                    "type": "integer",
+                    "minimum": -9007199254740991,
+                    "maximum": 9007199254740991
+                  },
                   "source": {
                     "description": "Origin label. Defaults to \"paste\".",
                     "type": "string"
@@ -5731,7 +5791,7 @@
     },
     "/api/v1/version": {
       "get": {
-        "summary": "Server version and environment label.",
+        "summary": "Server version, environment label, and the newest release on npm as the server last checked it (`latest`, plus `update_command` when it is newer).",
         "operationId": "get_version",
         "responses": {
           "200": {
@@ -5761,13 +5821,27 @@
                         "string",
                         "null"
                       ]
+                    },
+                    "latest": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "update_command": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
                     }
                   },
                   "required": [
                     "version",
                     "git_commit_short",
                     "build_date",
-                    "env_label"
+                    "env_label",
+                    "latest",
+                    "update_command"
                   ],
                   "additionalProperties": false
                 }

package/docs/guides/access-paths.md

@@ -60,8 +60,12 @@ Postgres RPCs
 ```
 
 **ChatGPT Custom GPT Actions** call the eight primitive Edge Functions directly over HTTPS
-using an OpenAPI schema. `cerefox-mcp` is not involved (ChatGPT does not support the
-Streamable HTTP MCP protocol).
+using an OpenAPI schema. `cerefox-mcp` is not involved. OpenAI retires Custom GPTs on **December 11, 2026**, and custom actions do not carry over to its plugins, so this path ends
+then. ChatGPT now supports remote MCP connectors (OAuth or no auth, no static bearer
+token), so its replacement is expected to be a connector to `cerefox-mcp` over OAuth,
+like cloud Claude; see
+[`chatgpt-after-custom-gpts.md`](../research/chatgpt-after-custom-gpts.md) and
+[#326](https://github.com/fstamatelopoulos/cerefox/issues/326).
 
 **curl / scripts / custom HTTP clients** can also call the primitives directly using the
 same Cerefox token as a Bearer token.
@@ -213,7 +217,7 @@ single container with an internally-held token.
 | Claude Code / Cursor | HTTPS → `cerefox-mcp` | Cerefox access token (`cfx_pat_…`) | Advanced/fallback; prefer local MCP for daily use |
 | Claude Desktop | HTTPS → `cerefox-mcp` (via `supergateway`) | Cerefox access token (`cfx_pat_…`) | Advanced/fallback; prefer local MCP for daily use |
 | **Cloud Claude (claude.ai web + mobile)** | HTTPS → `cerefox-mcp` over **OAuth 2.1** | Owner-pinned OAuth access token (JWKS-verified) | Optional; memory in the browser + on the phone |
-| ChatGPT Custom GPT | HTTPS → primitive Edge Functions | Cerefox access token (`cfx_pat_…`) | AI assistant via GPT Actions |
+| ChatGPT Custom GPT | HTTPS → primitive Edge Functions | Cerefox access token (`cfx_pat_…`) | AI assistant via GPT Actions; **ends 2026-12-11** (Custom GPTs retire) |
 | curl / HTTP scripts | HTTPS → primitive Edge Functions | Cerefox access token (`cfx_pat_…`) | Ad-hoc queries, automation |
 | Web UI (`cerefox web`) | Supabase REST API | Secret key (or legacy service_role) | Web UI backend (TS Hono) |
 | **HTTP client → `/api/v1`** | Plain HTTP to `cerefox web` / Cerefox Local | **None from loopback; API key otherwise** (v1.12.0) — `cerefox api-key generate` / `cerefox-local api-key` | A local program or bot harness that wants HTTP rather than MCP. Names itself with `X-Cerefox-Author` / `X-Cerefox-Requestor` (v1.11.0): a declared label for attribution, not a verified identity. See [`api.md`](api.md) |

package/docs/guides/api.md

@@ -179,7 +179,7 @@ default; Cerefox Local picks its own port and `cerefox-local status` prints it).
 
 | Method + path | Purpose |
 |---|---|
-| `GET /version` | Server version and environment label. |
+| `GET /version` | Server version, environment label, and the newest release on npm as the server last checked it (`latest`, plus `update_command` when it is newer). |
 | `GET /schema-version` | Deployed schema version. |
 | `GET /openapi.json` | This API's OpenAPI 3.1 description, served by the version you are talking to. Every `/api/v1` response points at it with `Link: </api/v1/openapi.json>; rel="service-desc"` (RFC 8631). |
 | `GET /search?q=…` | Hybrid search (FTS + semantic). `&review_status=approved\|pending_review` filters server-side; `400` while the review workflow is off. The response's `embedder` (`openai` or `local`) says which scale the scores are on. |

package/docs/guides/cli.md

@@ -278,7 +278,9 @@ cerefox document set-metadata [OPTIONS] DOCUMENT_ID
 | `-s, --set <key=value...>` | Set a key. Repeatable. |
 | `-r, --remove <key...>` | Remove a key. Repeatable. |
 | `--json <object>` | A JSON object of keys to set; a `null` value removes that key. |
-| `--replace` | Set the metadata to **exactly** what was given, discarding every key not listed. |
+| `--replace` | Set the metadata to **exactly** what was given, discarding every key not listed. Needs `--expected-metadata-revision` or `--last-write-wins` (v1.19.0). |
+| `--expected-metadata-revision <n>` | The `metadata_revision` you read (`document get` shows it). The write fails if the metadata changed since. Optional on a merge, required with `--replace`. |
+| `--last-write-wins` | Replace without a revision, regardless of concurrent changes (recorded in the audit log). |
 | `-a, --author <name>` | Caller identity (audit log). |
 | `--author-type <type>` | `user` (default) or `agent`. |
 | `--json-out` | Emit the result as JSON. |
@@ -773,11 +775,11 @@ These flat commands handle install, configuration, and health. Run any with `--h
 | Command | Purpose |
 |---|---|
 | `cerefox init` | Interactive first-run setup; writes `~/.cerefox/.env`, offers `server deploy` + self-docs ingest. |
-| `cerefox doctor` | Diagnose the install (credentials, DB reachability, schema version, whether the review workflow is on). |
+| `cerefox doctor` | Diagnose the install (credentials, DB reachability, schema version, whether the review workflow is on, whether a newer release is out). |
 | `cerefox status` | Show connection + schema status. |
 | `cerefox configure-agent --tool <client>` | Write MCP client config (`claude-code`, `claude-desktop`, `cursor`, `codex`, `gemini`). |
 | `cerefox token generate` / `rotate` / `list` | Manage the Cerefox access token (`cfx_pat_…`) — the Edge Function Bearer credential (remote MCP, GPT Actions, curl). See the [`cerefox token`](#cerefox-token-generate--cerefox-token-rotate--cerefox-token-list) section above. |
-| `cerefox self-update` | Update the installed `@cerefox/memory` package. |
+| `cerefox self-update` | Update the installed `@cerefox/memory` package. Other commands print a one-line notice when a newer release is out; see [configuration.md → Update check](configuration.md#update-check) to turn it off. |
 | `cerefox completion` | Emit a shell completion script. |
 | `cerefox backup create` / `cerefox backup restore` | File-system backup / restore of the knowledge base (see [`ops-scripts.md`](ops-scripts.md)). |
 

package/docs/guides/configuration.md

@@ -183,7 +183,7 @@ This handles intermittent OpenAI API errors (500s) that would otherwise cause se
 | `CEREFOX_MIN_TERM_COVERAGE` | **Retired in v1.1.0 — no longer read.** | Now a store setting: `cerefox config set min_term_coverage <value>`, or the **Settings** page. A per-call override still works (`cerefox search --min-term-coverage`, the MCP `min_term_coverage` param). `cerefox doctor` and the Settings page report the variable if it is still set. |
 | `CEREFOX_EMBED_MAX_INPUT_CHARS` | `20000` | Safety cap on the characters sent to the embedding model per input. The full chunk content is always stored and reconstructed untouched; only the embedding uses the (rare) truncated prefix, so an oversized chunk can never fail an ingest. |
 | `CEREFOX_MODELS_DIR` | `~/.cerefox/models` (in-container: inside the data volume) | Where the local embedder caches downloaded model weights (Cerefox Local; `CEREFOX_EMBEDDER=local`). |
-| `CEREFOX_ONNX_BATCH` | `4` | Texts per local-embedder inference call. Peak memory scales with this; the small default keeps ingest/reindex safe on small Docker VMs. |
+| `CEREFOX_ONNX_BATCH` | `1` | Texts per local-embedder inference call. Peak memory grows with this (each batch is padded to its longest chunk), and on CPU a larger batch is not faster, so leave it at 1. Was 4 before v1.19.0 (#335). Cerefox Local forwards it from its `.env` (from v1.19.0; after upgrading, run `cerefox-local init` once for a value set there to apply). |
 
 ### Metadata filter
 
@@ -344,6 +344,27 @@ there matters.
 
 ---
 
+## Update check
+
+Cerefox tells you when a newer release is on npm (v1.18.0, #323): one line after
+a CLI command (at most once a day, only at a terminal), an `updates` row in
+`cerefox doctor`, and a note in the web UI footer. Inside the Cerefox Local
+container it points at `cerefox-local upgrade` instead of `cerefox self-update`.
+
+The only network call is a GET of the `latest` release from the npm registry
+(`registry.npmjs.org`), the same request `cerefox self-update` makes. It is made
+by `cerefox web` (at startup, then daily), `cerefox mcp` (at startup, when the
+last answer is over a day old), `cerefox doctor` and `cerefox self-update`.
+Every other command only reads the saved answer, `update-check.json` in
+`~/.cerefox` (or in `CEREFOX_CONFIG_DIR`, when set), so it never adds latency.
+Offline, the check stays quiet.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CEREFOX_NO_UPDATE_CHECK` | _(unset)_ | Set to `1` to turn the check off entirely: no request to npm, and no notice anywhere. `NO_UPDATE_NOTIFIER` (the convention other CLIs use) and `CI` do the same. |
+
+---
+
 ## Logging
 
 | Variable | Default | Description |
@@ -422,7 +443,7 @@ cerefox server deploy --functions-only
 
 Contributors with a repo clone can instead redeploy individual functions with `npx supabase functions deploy cerefox-search` (and `cerefox-ingest`), or through the Supabase Dashboard → Edge Functions → Deploy.
 
-> **If you only use the local MCP server** (Claude Desktop, ChatGPT Desktop, Cursor), Step 3 is
+> **If you only use the local MCP server** (Claude Code, Claude Desktop, Codex, Cursor), Step 3 is
 > optional — the Edge Functions are only used for GPT Actions and direct HTTP access.
 
 > **Future improvement**: the Edge Functions will be updated to read model config from Supabase