@cerefox/memory 0.10.0 → 0.10.1

package/dist/bin/cerefox.js

@@ -7184,7 +7184,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "0.10.0";
+var PKG_VERSION = "0.10.1";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js
@@ -24852,20 +24852,31 @@ var init_bundled_docs = __esm(() => {
 });
 
 // ../../_shared/embeddings/index.ts
+function openaiEmbeddingConfig() {
+  const env4 = globalThis.process?.env ?? {};
+  const base = env4.CEREFOX_OPENAI_BASE_URL?.replace(/\/+$/, "");
+  const dims = Number.parseInt(env4.CEREFOX_OPENAI_EMBEDDING_DIMENSIONS ?? "", 10);
+  return {
+    url: base ? `${base}/embeddings` : OPENAI_EMBEDDING_URL,
+    model: env4.CEREFOX_OPENAI_EMBEDDING_MODEL || OPENAI_MODEL,
+    dimensions: Number.isNaN(dims) || dims <= 0 ? EMBEDDING_DIMENSIONS : dims
+  };
+}
 async function getEmbedding(text, apiKey) {
   let lastError = null;
+  const cfg = openaiEmbeddingConfig();
   for (let attempt = 0;attempt < EMBEDDING_MAX_RETRIES; attempt++) {
     try {
-      const response = await fetch(OPENAI_EMBEDDING_URL, {
+      const response = await fetch(cfg.url, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${apiKey}`,
           "Content-Type": "application/json"
         },
         body: JSON.stringify({
-          model: OPENAI_MODEL,
+          model: cfg.model,
           input: text,
-          dimensions: EMBEDDING_DIMENSIONS
+          dimensions: cfg.dimensions
         })
       });
       if (!response.ok) {
@@ -24896,18 +24907,19 @@ async function getEmbedding(text, apiKey) {
 }
 async function embedBatchSingleCall(texts, apiKey) {
   let lastError = null;
+  const cfg = openaiEmbeddingConfig();
   for (let attempt = 0;attempt < EMBEDDING_MAX_RETRIES; attempt++) {
     try {
-      const response = await fetch(OPENAI_EMBEDDING_URL, {
+      const response = await fetch(cfg.url, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${apiKey}`,
           "Content-Type": "application/json"
         },
         body: JSON.stringify({
-          model: OPENAI_MODEL,
+          model: cfg.model,
           input: texts,
-          dimensions: EMBEDDING_DIMENSIONS
+          dimensions: cfg.dimensions
         })
       });
       if (!response.ok) {
@@ -53721,6 +53733,20 @@ var require_cli_progress = __commonJS((exports, module) => {
 });
 
 // ../../_shared/mcp-tools/_utils.ts
+function getMaxResponseBytes() {
+  const raw = globalThis.process?.env?.CEREFOX_MAX_RESPONSE_BYTES;
+  if (raw === undefined || raw === "")
+    return MAX_RESPONSE_BYTES;
+  const n = Number.parseInt(raw, 10);
+  return Number.isNaN(n) || n <= 0 ? MAX_RESPONSE_BYTES : n;
+}
+function getMinSearchScore() {
+  const raw = globalThis.process?.env?.CEREFOX_MIN_SEARCH_SCORE;
+  if (raw === undefined || raw === "")
+    return DEFAULT_MIN_SEARCH_SCORE;
+  const n = Number.parseFloat(raw);
+  return Number.isNaN(n) || n < 0 || n > 1 ? DEFAULT_MIN_SEARCH_SCORE : n;
+}
 function applyByteBudget(rows, maxBytes) {
   const accepted = [];
   let usedBytes = 0;
@@ -53748,7 +53774,7 @@ function logUsage(supabase, params) {
     p_extra: params.extra ?? {}
   })).catch(() => {});
 }
-var MAX_RESPONSE_BYTES = 200000;
+var MAX_RESPONSE_BYTES = 200000, DEFAULT_MIN_SEARCH_SCORE = 0.5;
 
 // ../../_shared/mcp-tools/audit-log.ts
 async function handler(supabase, args, ctx) {
@@ -54531,7 +54557,8 @@ async function handler8(supabase, args, ctx) {
     if (!projectId)
       throw new Error(`Project not found: ${project_name}`);
   }
-  const max_bytes = include_content ? Math.min(requested_max_bytes ?? MAX_RESPONSE_BYTES, MAX_RESPONSE_BYTES) : null;
+  const ceiling = getMaxResponseBytes();
+  const max_bytes = include_content ? Math.min(requested_max_bytes ?? ceiling, ceiling) : null;
   const params = {
     p_metadata_filter: metadata_filter,
     p_project_id: projectId,
@@ -54624,10 +54651,11 @@ async function handler9(supabase, args, ctx) {
   const match_count = args.match_count ?? 5;
   const mode = args.mode ?? "docs";
   const alpha = args.alpha ?? 0.7;
-  const min_score = args.min_score ?? 0.5;
+  const min_score = args.min_score ?? getMinSearchScore();
   const metadata_filter = args.metadata_filter ?? null;
   const requested_max_bytes = args.max_bytes;
-  const max_bytes = Math.min(requested_max_bytes ?? MAX_RESPONSE_BYTES, MAX_RESPONSE_BYTES);
+  const ceiling = getMaxResponseBytes();
+  const max_bytes = Math.min(requested_max_bytes ?? ceiling, ceiling);
   if (metadata_filter !== null && metadata_filter !== undefined && (typeof metadata_filter !== "object" || Array.isArray(metadata_filter))) {
     throw new McpInvalidParams("metadata_filter must be a JSON object or null");
   }
@@ -68087,7 +68115,7 @@ function utcStamp() {
   return d.getUTCFullYear().toString() + pad(d.getUTCMonth() + 1) + pad(d.getUTCDate()) + "T" + pad(d.getUTCHours()) + pad(d.getUTCMinutes()) + pad(d.getUTCSeconds()) + "Z";
 }
 async function action(options) {
-  const outDir = resolve(expandHome(options.outputDir ?? "~/.cerefox/backups"));
+  const outDir = resolve(expandHome(options.outputDir ?? process.env.CEREFOX_BACKUP_DIR ?? "~/.cerefox/backups"));
   if (!existsSync2(outDir))
     mkdirSync(outDir, { recursive: true });
   const stamp = utcStamp();
@@ -68133,7 +68161,7 @@ async function action(options) {
   }
 }
 function registerBackup(program2) {
-  program2.command("backup").description("Write a JSON snapshot of the knowledge base.").option("-o, --output-dir <dir>", "Snapshot output directory.", "~/.cerefox/backups").option("-l, --label <label>", "Optional suffix added to the filename.").option("--include-versions", "Include archived versions in the snapshot. (v0.5: ignored — current chunks only.)").option("--git", "Commit the snapshot to the output dir as a git checkpoint. (v0.5: ignored.)").action(action);
+  program2.command("backup").description("Write a JSON snapshot of the knowledge base.").option("-o, --output-dir <dir>", "Snapshot output directory (default: CEREFOX_BACKUP_DIR or ~/.cerefox/backups).").option("-l, --label <label>", "Optional suffix added to the filename.").option("--include-versions", "Include archived versions in the snapshot. (v0.5: ignored — current chunks only.)").option("--git", "Commit the snapshot to the output dir as a git checkpoint. (v0.5: ignored.)").action(action);
 }
 
 // src/cli/commands/completion.ts
@@ -73925,7 +73953,7 @@ import { homedir as homedir5 } from "node:os";
 import { join as join8 } from "node:path";
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "0.9.3";
+var EF_VERSION = "0.10.1";
 
 // src/cli/util/checks.ts
 init_config();
@@ -75049,6 +75077,22 @@ var DEFAULT_PIPELINE_SETTINGS = {
   versionRetentionHours: 48,
   versionCleanupEnabled: true
 };
+function loadPipelineSettings() {
+  const env4 = globalThis.process?.env ?? {};
+  const intMin = (raw, def, min) => {
+    if (raw === undefined || raw === "")
+      return def;
+    const n = Number.parseInt(raw, 10);
+    return Number.isNaN(n) || n < min ? def : n;
+  };
+  const bool = (raw, def) => raw === undefined || raw === "" ? def : !/^(false|0|no|off)$/i.test(raw.trim());
+  return {
+    maxChunkChars: intMin(env4.CEREFOX_MAX_CHUNK_CHARS, DEFAULT_PIPELINE_SETTINGS.maxChunkChars, 1),
+    minChunkChars: intMin(env4.CEREFOX_MIN_CHUNK_CHARS, DEFAULT_PIPELINE_SETTINGS.minChunkChars, 0),
+    versionRetentionHours: intMin(env4.CEREFOX_VERSION_RETENTION_HOURS, DEFAULT_PIPELINE_SETTINGS.versionRetentionHours, 0),
+    versionCleanupEnabled: bool(env4.CEREFOX_VERSION_CLEANUP_ENABLED, DEFAULT_PIPELINE_SETTINGS.versionCleanupEnabled)
+  };
+}
 
 // src/ingestion/pipeline.ts
 class IngestionPipeline {
@@ -75060,7 +75104,7 @@ class IngestionPipeline {
     this.db = new IngestionDbBridge(deps.supabase);
     this.apiKey = deps.openAiApiKey;
     this.embedderModel = deps.embedderModel ?? "text-embedding-3-small";
-    this.settings = { ...DEFAULT_PIPELINE_SETTINGS, ...deps.settings ?? {} };
+    this.settings = { ...loadPipelineSettings(), ...deps.settings ?? {} };
   }
   async ingestText(opts) {
     const {
@@ -76474,7 +76518,7 @@ async function action28(query, options) {
   }
   const matchCount = parsePositiveInt(options.matchCount, "--match-count", 5);
   const alpha = parseFloat01(options.alpha, "--alpha", 0.7);
-  const minScore = parseFloat01(options.minScore, "--min-score", 0.5);
+  const minScore = parseFloat01(options.minScore, "--min-score", getMinSearchScore());
   const maxBytes = parseNonNegativeInt(options.maxBytes, "--max-bytes", 200000);
   const mode = options.mode ?? "docs";
   if (!["docs", "hybrid", "fts"].includes(mode)) {
@@ -76620,7 +76664,7 @@ async function action28(query, options) {
   }
 }
 function registerSearch(program2) {
-  program2.command("search").description("Search the knowledge base (hybrid FTS + semantic).").argument("<query>", "Natural-language search query.").option("-c, --match-count <n>", "Maximum number of documents to return.", "5").option("-p, --project-name <name>", "Filter results to a specific project.").option("-f, --metadata-filter <json>", "JSON containment filter; only docs whose metadata contains ALL pairs are returned.").option("--mode <mode>", "Search mode: docs (default), hybrid, fts.", "docs").option("--alpha <float>", "Semantic weight 0..1 (default: 0.7).", "0.7").option("--min-score <float>", "Minimum cosine similarity threshold.", "0.5").option("--max-bytes <n>", "Response size budget in bytes.", "200000").option("-r, --requestor <name>", "Agent / user name (recorded in usage log).").option("--json", "Emit machine-readable JSON instead of the default text.").option("--only-metadata", "List matching docs (id, score, chunks, chars, partial/full) WITHOUT their content — like the web UI's collapsed result list. Grab a [id:…] then `cerefox document get <id>`.").action(action28);
+  program2.command("search").description("Search the knowledge base (hybrid FTS + semantic).").argument("<query>", "Natural-language search query.").option("-c, --match-count <n>", "Maximum number of documents to return.", "5").option("-p, --project-name <name>", "Filter results to a specific project.").option("-f, --metadata-filter <json>", "JSON containment filter; only docs whose metadata contains ALL pairs are returned.").option("--mode <mode>", "Search mode: docs (default), hybrid, fts.", "docs").option("--alpha <float>", "Semantic weight 0..1 (default: 0.7).", "0.7").option("--min-score <float>", "Minimum cosine similarity threshold (default: CEREFOX_MIN_SEARCH_SCORE or 0.5).").option("--max-bytes <n>", "Response size budget in bytes.", "200000").option("-r, --requestor <name>", "Agent / user name (recorded in usage log).").option("--json", "Emit machine-readable JSON instead of the default text.").option("--only-metadata", "List matching docs (id, score, chunks, chars, partial/full) WITHOUT their content — like the web UI's collapsed result list. Grab a [id:…] then `cerefox document get <id>`.").action(action28);
 }
 
 // src/cli/commands/self-update.ts
@@ -80241,7 +80285,7 @@ async function runSearch(ctx, opts) {
       p_alpha: 0.7,
       p_use_upgrade: false,
       p_project_id: projectId,
-      p_min_score: 0
+      p_min_score: getMinSearchScore()
     };
     if (metadataFilter)
       params2.p_metadata_filter = metadataFilter;

package/dist/server-assets/_shared/ef-meta/index.ts

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
 
-export const EF_VERSION = "0.9.3";
+export const EF_VERSION = "0.10.1";
 
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

package/dist/server-assets/_shared/embeddings/index.ts

@@ -17,25 +17,52 @@ export const OPENAI_EMBEDDING_URL = "https://api.openai.com/v1/embeddings";
 export const OPENAI_MODEL = "text-embedding-3-small";
 export const EMBEDDING_DIMENSIONS = 768;
 
+/**
+ * Resolve the OpenAI embedding endpoint/model/dimensions, applying `.env`
+ * overrides over the built-in defaults. These were configurable in the Python
+ * runtime; the TS migration hardcoded them.
+ *
+ * ⚠ Overriding the MODEL or DIMENSIONS is a BREAKING change: query vectors must
+ * match the stored vectors and the DB column is `vector(768)`. Changing either
+ * requires re-embedding the whole corpus (`cerefox server reindex`) and, for a
+ * non-768 model, a schema change. `CEREFOX_OPENAI_BASE_URL` (proxy/gateway) is
+ * the only safe one to flip on an existing KB.
+ *
+ * Runtime-agnostic env read; the Deno Edge Function (no host env) keeps the
+ * constants — matching the EF's "model config is a constant" design.
+ */
+export function openaiEmbeddingConfig(): { url: string; model: string; dimensions: number } {
+  const env =
+    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {};
+  const base = env.CEREFOX_OPENAI_BASE_URL?.replace(/\/+$/, "");
+  const dims = Number.parseInt(env.CEREFOX_OPENAI_EMBEDDING_DIMENSIONS ?? "", 10);
+  return {
+    url: base ? `${base}/embeddings` : OPENAI_EMBEDDING_URL,
+    model: env.CEREFOX_OPENAI_EMBEDDING_MODEL || OPENAI_MODEL,
+    dimensions: Number.isNaN(dims) || dims <= 0 ? EMBEDDING_DIMENSIONS : dims,
+  };
+}
+
 const EMBEDDING_MAX_RETRIES = 3;
 const EMBEDDING_INITIAL_BACKOFF_MS = 500; // 500ms → 1s → 2s
 
 /** Embed a single string. Used for the query vector in `cerefox_search`. */
 export async function getEmbedding(text: string, apiKey: string): Promise<number[]> {
   let lastError: Error | null = null;
+  const cfg = openaiEmbeddingConfig();
 
   for (let attempt = 0; attempt < EMBEDDING_MAX_RETRIES; attempt++) {
     try {
-      const response = await fetch(OPENAI_EMBEDDING_URL, {
+      const response = await fetch(cfg.url, {
         method: "POST",
         headers: {
           "Authorization": `Bearer ${apiKey}`,
           "Content-Type": "application/json",
         },
         body: JSON.stringify({
-          model: OPENAI_MODEL,
+          model: cfg.model,
           input: text,
-          dimensions: EMBEDDING_DIMENSIONS,
+          dimensions: cfg.dimensions,
         }),
       });
 
@@ -93,19 +120,20 @@ async function embedBatchSingleCall(
   apiKey: string,
 ): Promise<number[][]> {
   let lastError: Error | null = null;
+  const cfg = openaiEmbeddingConfig();
 
   for (let attempt = 0; attempt < EMBEDDING_MAX_RETRIES; attempt++) {
     try {
-      const response = await fetch(OPENAI_EMBEDDING_URL, {
+      const response = await fetch(cfg.url, {
         method: "POST",
         headers: {
           "Authorization": `Bearer ${apiKey}`,
           "Content-Type": "application/json",
         },
         body: JSON.stringify({
-          model: OPENAI_MODEL,
+          model: cfg.model,
           input: texts,
-          dimensions: EMBEDDING_DIMENSIONS,
+          dimensions: cfg.dimensions,
         }),
       });
 

package/dist/server-assets/_shared/mcp-tools/_utils.ts

@@ -14,10 +14,46 @@
 
 import type { MCPSupabaseClient } from "./types.ts";
 
-/** Server-enforced response-size ceiling for MCP results. Agents can request
- *  smaller budgets via `max_bytes`; values above this are capped. */
+/** Built-in default response-size ceiling for MCP/EF results. */
 export const MAX_RESPONSE_BYTES = 200_000;
 
+/**
+ * Server-enforced response-size ceiling for MCP/Edge-Function results (agents
+ * can request smaller via `max_bytes`; larger is capped). Overridable via
+ * `CEREFOX_MAX_RESPONSE_BYTES`. Read by the Python runtime; restored after the
+ * TS migration. The web UI + CLI are intentionally unlimited and do not use this.
+ * Runtime-agnostic env read (Deno EF safely falls back to the default).
+ */
+export function getMaxResponseBytes(): number {
+  const raw = (globalThis as { process?: { env?: Record<string, string | undefined> } })
+    .process?.env?.CEREFOX_MAX_RESPONSE_BYTES;
+  if (raw === undefined || raw === "") return MAX_RESPONSE_BYTES;
+  const n = Number.parseInt(raw, 10);
+  return Number.isNaN(n) || n <= 0 ? MAX_RESPONSE_BYTES : n;
+}
+
+/** Built-in default cosine-similarity floor for hybrid/semantic search. */
+export const DEFAULT_MIN_SEARCH_SCORE = 0.5;
+
+/**
+ * Resolve the minimum cosine-similarity floor for hybrid/semantic search
+ * (vector-only matches below this are dropped; FTS matches always pass).
+ * Overridable via the `CEREFOX_MIN_SEARCH_SCORE` env var (0.0–1.0). The Python
+ * runtime read this; the TS migration dropped it — restored here as the single
+ * default used by the CLI, local/remote MCP, and the web API.
+ *
+ * Runtime-agnostic env read: works in Node/Bun; in the Deno Edge Function
+ * `process` may be absent, so it falls back to the built-in default (the cloud
+ * EF path doesn't use the host `.env` anyway).
+ */
+export function getMinSearchScore(): number {
+  const raw = (globalThis as { process?: { env?: Record<string, string | undefined> } })
+    .process?.env?.CEREFOX_MIN_SEARCH_SCORE;
+  if (raw === undefined || raw === "") return DEFAULT_MIN_SEARCH_SCORE;
+  const n = Number.parseFloat(raw);
+  return Number.isNaN(n) || n < 0 || n > 1 ? DEFAULT_MIN_SEARCH_SCORE : n;
+}
+
 export function applyByteBudget(
   rows: unknown[],
   maxBytes: number,

package/dist/server-assets/_shared/mcp-tools/metadata-search.ts

@@ -7,7 +7,7 @@
 
 import type { MCPSupabaseClient } from "./types.ts";
 
-import { applyByteBudget, logUsage, MAX_RESPONSE_BYTES } from "./_utils.ts";
+import { applyByteBudget, getMaxResponseBytes, logUsage } from "./_utils.ts";
 import { lookupProjectId } from "./_projects.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
 
@@ -39,8 +39,9 @@ async function handler(
   }
 
   // Enforce byte ceiling for content mode
+  const ceiling = getMaxResponseBytes();
   const max_bytes = include_content
-    ? Math.min(requested_max_bytes ?? MAX_RESPONSE_BYTES, MAX_RESPONSE_BYTES)
+    ? Math.min(requested_max_bytes ?? ceiling, ceiling)
     : null;
 
   const params: Record<string, unknown> = {

package/dist/server-assets/_shared/mcp-tools/search.ts

@@ -18,7 +18,7 @@
 import type { MCPSupabaseClient } from "./types.ts";
 
 import { getEmbedding } from "../embeddings/index.ts";
-import { applyByteBudget, logUsage, MAX_RESPONSE_BYTES } from "./_utils.ts";
+import { applyByteBudget, getMaxResponseBytes, getMinSearchScore, logUsage } from "./_utils.ts";
 import { lookupProjectId } from "./_projects.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
 
@@ -32,12 +32,13 @@ async function handler(
   const match_count = (args.match_count as number | undefined) ?? 5;
   const mode = (args.mode as string | undefined) ?? "docs";
   const alpha = (args.alpha as number | undefined) ?? 0.7;
-  const min_score = (args.min_score as number | undefined) ?? 0.5;
+  const min_score = (args.min_score as number | undefined) ?? getMinSearchScore();
   const metadata_filter =
     (args.metadata_filter as Record<string, string> | null | undefined) ?? null;
   const requested_max_bytes = args.max_bytes as number | undefined;
 
-  const max_bytes = Math.min(requested_max_bytes ?? MAX_RESPONSE_BYTES, MAX_RESPONSE_BYTES);
+  const ceiling = getMaxResponseBytes();
+  const max_bytes = Math.min(requested_max_bytes ?? ceiling, ceiling);
 
   if (
     metadata_filter !== null &&

package/docs/guides/cli.md

@@ -14,7 +14,7 @@ Every command reads configuration from `.env` in the working directory (or envir
 
 The CLI is the TypeScript `@cerefox/memory` package. Invoke any command as plain `cerefox <subcommand>` (installed via the installer or `npm install -g @cerefox/memory` — see [`quickstart.md`](quickstart.md#1-install)).
 
-> **v0.9 verb rename**: commands now follow a `resource verb` shape (e.g. `cerefox document get`, `cerefox project list`). The old flat verbs (`get-doc`, `list-docs`, `ingest`, `list-versions`, `config-get`, `deploy-server`, `docs`, …) are husks and have been removed — use the new forms below.
+> **v0.9 verb rename**: commands now follow a `resource verb` shape (e.g. `cerefox document get`, `cerefox project list`). The old flat verbs (`get-doc`, `list-docs`, `ingest`, `list-versions`, `config-get`, `deploy-server`, `docs`, …) survive as hidden husks — they still run but print a pointer to the new form and exit non-zero (removed only at v1.0). Use the new forms below.
 
 ## Commands
 
@@ -141,7 +141,7 @@ cerefox search [OPTIONS] QUERY
 ```bash
 cerefox search "OAuth design"
 cerefox search "decisions" --metadata-filter '{"type":"decision-log"}' --match-count 5
-cerefox search "what we tried" --mode semantic --requestor "claude-code"
+cerefox search "what we tried" --mode hybrid --requestor "claude-code"
 cerefox search "design docs" --only-metadata
 ```
 

package/docs/guides/configuration.md

@@ -24,6 +24,13 @@ CEREFOX_CONFIG_DIR=~/.cerefox-personal cerefox search "…"
 
 Full rule documented in [`docs/specs/polish-and-distribution-design.md` §7](../specs/polish-and-distribution-design.md).
 
+> **Local / self-hosted (World B).** For the Docker backend (`cerefox-local`), do **not**
+> set the Supabase or `CEREFOX_DATABASE_URL` vars below — the container generates and owns
+> them. Put `OPENAI_API_KEY` plus any of the `CEREFOX_*` **tuning** options on this page
+> (search, chunking, retrieval, versioning, embedding base-url/model, caller identity) in
+> `~/.cerefox/local/.env`; the installer + `cerefox-local` forward them into the container.
+> Apply changes with `cerefox-local init`. See [`setup-local.md`](setup-local.md).
+
 ---
 
 ## Supabase / Database
@@ -45,34 +52,27 @@ Full rule documented in [`docs/specs/polish-and-distribution-design.md` §7](../
 
 Cerefox uses cloud-based embedding APIs. Local models (mpnet, Ollama) are not supported — they require large downloads, fail on some hardware, and add installation complexity.
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CEREFOX_EMBEDDER` | `openai` | Embedding provider. Valid values: `openai`, `fireworks` |
+> **TS runtime: OpenAI only (today).** The current TypeScript runtime implements the
+> OpenAI embedder. `CEREFOX_EMBEDDER` and the `CEREFOX_FIREWORKS_*` variables are
+> documented (they worked in the retired Python runtime) but are **not yet wired in TS** —
+> they're currently no-ops, tracked for a future release.
 
 ### OpenAI (default, recommended)
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `OPENAI_API_KEY` | `""` | OpenAI API key. Also accepted as `CEREFOX_OPENAI_API_KEY`. Get one at [platform.openai.com/api-keys](https://platform.openai.com/api-keys). |
-| `CEREFOX_OPENAI_BASE_URL` | `https://api.openai.com/v1` | API base URL. Override for proxies or OpenAI-compatible providers. |
-| `CEREFOX_OPENAI_EMBEDDING_MODEL` | `text-embedding-3-small` | OpenAI embedding model. |
-| `CEREFOX_OPENAI_EMBEDDING_DIMENSIONS` | `768` | Output dimensions. Must match the database schema (VECTOR(768)). |
-
-For cost estimates see `docs/guides/operational-cost.md`.
-
-### Fireworks AI (alternative, lower cost)
+| `CEREFOX_OPENAI_BASE_URL` | `https://api.openai.com/v1` | API base URL. Safe to override for proxies or OpenAI-compatible gateways. |
+| `CEREFOX_OPENAI_EMBEDDING_MODEL` | `text-embedding-3-small` | OpenAI embedding model. ⚠ see warning below. |
+| `CEREFOX_OPENAI_EMBEDDING_DIMENSIONS` | `768` | Output dimensions. Must match the DB schema (`VECTOR(768)`). ⚠ see warning below. |
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CEREFOX_FIREWORKS_API_KEY` | `""` | Fireworks AI API key. |
-| `CEREFOX_FIREWORKS_BASE_URL` | `https://api.fireworks.ai/inference/v1` | Fireworks API base URL. |
-| `CEREFOX_FIREWORKS_EMBEDDING_MODEL` | `nomic-ai/nomic-embed-text-v1.5` | Fireworks model. Must natively output 768-dim vectors. |
+> **⚠ Changing the model or dimensions is breaking.** Query vectors must match the stored
+> vectors. After changing `CEREFOX_OPENAI_EMBEDDING_MODEL` you MUST re-embed the whole
+> corpus (`cerefox server reindex`); changing `CEREFOX_OPENAI_EMBEDDING_DIMENSIONS` away
+> from 768 also requires a schema change. `CEREFOX_OPENAI_BASE_URL` is the only one safe to
+> flip on an existing knowledge base.
 
-To use Fireworks:
-```env
-CEREFOX_EMBEDDER=fireworks
-CEREFOX_FIREWORKS_API_KEY=fw_...
-```
+For cost estimates see `docs/guides/operational-cost.md`.
 
 ### Edge Functions (for agents)
 

package/docs/guides/ops-scripts.md

@@ -37,7 +37,7 @@ jobs / CI / make targets that invoke them.
 
 ### TS scripts and `.env` resolution
 
-`bun scripts/<name>.ts` reads the same `.env` the Python CLI does. Precedence:
+`bun scripts/<name>.ts` reads the same `.env` the `cerefox` CLI does. Precedence:
 
 1. `CEREFOX_CONFIG_DIR` env var (explicit override; supports `~`).
 2. `./.env` in the current working directory (dev mode).

package/docs/guides/quickstart.md

@@ -1,9 +1,9 @@
 # Quickstart -- Zero to First Document
 
-Get Cerefox running on your machine via the npm install path. **No source
-clone, no Python required.** Once you have a Supabase project (the one
-prerequisite — provisioning a free one takes a few minutes), the Cerefox
-install and setup below is about 5 minutes.
+Get Cerefox running on your machine via the npm install path (the **cloud /
+Supabase** backend). **No source clone required.** Once you have a Supabase
+project (the one prerequisite — provisioning a free one takes a few minutes),
+the Cerefox install and setup below takes ~15 minutes.
 
 > **Upgrading from an earlier version?** See [`upgrading.md`](upgrading.md)
 > for migration steps instead.
@@ -114,8 +114,9 @@ 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 [`setup-local.md`](setup-local.md) and
-`CONTRIBUTING.md`.
+for the legacy Python MCP fallback. See [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
+(Want a no-cloud install instead? That's the self-hosted Docker backend —
+[`setup-local.md`](setup-local.md).)
 
 ---
 
@@ -125,7 +126,7 @@ for the legacy Python MCP fallback. See [`setup-local.md`](setup-local.md) and
   `cerefox document ingest-dir ./notes/` (recurses into sub-directories automatically)
 - **Search from the CLI**: `cerefox search "your query"`
 - **Discover all commands**: `cerefox --help`
-- **Run the web UI**: `cerefox web` (TypeScript — Hono backend + React SPA); see [`setup-local.md`](setup-local.md)
+- **Run the web UI**: `cerefox web` (TypeScript — Hono backend + React SPA); see [`cli.md`](cli.md)
 - **Connect more AI clients** (Cursor, Codex, ChatGPT GPT Actions, etc.):
   [`connect-agents.md`](connect-agents.md)
 - **Configuration reference**: [`configuration.md`](configuration.md)

package/docs/guides/setup-supabase.md

@@ -47,7 +47,7 @@ You need three values from Supabase: a URL, an API key, and a direct Postgres co
 
 See the **[Supabase API keys (2026)](#supabase-api-keys-2026)** section near the end of this guide for the full picture. The short version:
 
-- For `CEREFOX_SUPABASE_KEY` (this guide, Python web app, CLI): use the new **secret key** (`sb_secret_…`) from **Project Settings → API Keys → Secret key**. The legacy `service_role` JWT also still works during the transition.
+- For `CEREFOX_SUPABASE_KEY` (this guide, the web UI, and the CLI): use the new **secret key** (`sb_secret_…`) from **Project Settings → API Keys → Secret key**. The legacy `service_role` JWT also still works during the transition.
 - For `CEREFOX_SUPABASE_ANON_KEY` (only if you'll use Edge Functions / MCP / GPT Actions; not needed for this guide's deployment step): you must use the **legacy anon JWT** (`eyJ…`). The new `sb_publishable_…` key fails at the Edge Function gateway. See the reference section for why.
 
 Either way: keep this key secret — it bypasses Row Level Security and grants full database access.

package/package.json

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