@cerefox/memory 0.10.0 → 0.10.2

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.2";
 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
@@ -68170,26 +68198,26 @@ function collectNodes() {
   nodes.sort((a, b) => a.path.localeCompare(b.path));
   return nodes;
 }
-function bashScript(nodes) {
+function bashScript(nodes, prog, fn) {
   const candCases = nodes.map((n) => `        "${n.path}") echo "${n.candidates.join(" ")}" ;;`).join(`
 `);
   const pathPatterns = nodes.filter((n) => n.path !== "").map((n) => `"${n.path}"`).join("|");
   return `# Cerefox bash completion. Source from ~/.bashrc:
-#   source <(cerefox completion bash)
+#   source <(${prog} completion bash)
 #
-_cerefox_candidates() {
+_${fn}_candidates() {
     case "$1" in
 ${candCases}
         *) echo "--help" ;;
     esac
 }
-_cerefox_is_path() {
+_${fn}_is_path() {
     case "$1" in
         ${pathPatterns}) return 0 ;;
         *) return 1 ;;
     esac
 }
-_cerefox_completion() {
+_${fn}_completion() {
     local cur path trial w i
     COMPREPLY=()
     cur="\${COMP_WORDS[COMP_CWORD]}"
@@ -68199,39 +68227,39 @@ _cerefox_completion() {
         w="\${COMP_WORDS[$i]}"
         case "$w" in -*) break ;; esac
         if [ -z "$path" ]; then trial="$w"; else trial="$path $w"; fi
-        if _cerefox_is_path "$trial"; then
+        if _${fn}_is_path "$trial"; then
             path="$trial"; i=$((i + 1))
         else
             break
         fi
     done
-    COMPREPLY=( $(compgen -W "$(_cerefox_candidates "$path")" -- "$cur") )
+    COMPREPLY=( $(compgen -W "$(_${fn}_candidates "$path")" -- "$cur") )
     return 0
 }
-complete -F _cerefox_completion cerefox
+complete -F _${fn}_completion ${prog}
 `;
 }
-function zshScript(nodes) {
+function zshScript(nodes, prog, fn) {
   const candCases = nodes.map((n) => `        "${n.path}") REPLY="${n.candidates.join(" ")}" ;;`).join(`
 `);
   const pathPatterns = nodes.filter((n) => n.path !== "").map((n) => `"${n.path}"`).join("|");
-  return `#compdef cerefox
+  return `#compdef ${prog}
 # Cerefox zsh completion. Save and source from ~/.zshrc:
-#   source <(cerefox completion zsh)
+#   source <(${prog} completion zsh)
 #
-_cerefox_candidates() {
+_${fn}_candidates() {
     case "$1" in
 ${candCases}
         *) REPLY="--help" ;;
     esac
 }
-_cerefox_is_path() {
+_${fn}_is_path() {
     case "$1" in
         ${pathPatterns}) return 0 ;;
         *) return 1 ;;
     esac
 }
-_cerefox() {
+_${fn}() {
     local path trial w i REPLY
     path=""
     i=2
@@ -68239,13 +68267,13 @@ _cerefox() {
         w="\${words[i]}"
         case "$w" in -*) break ;; esac
         if [[ -z "$path" ]]; then trial="$w"; else trial="$path $w"; fi
-        if _cerefox_is_path "$trial"; then
+        if _${fn}_is_path "$trial"; then
             path="$trial"; (( i++ ))
         else
             break
         fi
     done
-    _cerefox_candidates "$path"
+    _${fn}_candidates "$path"
     compadd -- \${=REPLY}
 }
 # Self-bootstrap the completion system if no \`compinit\` has run yet (e.g. this
@@ -68254,23 +68282,23 @@ _cerefox() {
 if ! whence compdef >/dev/null 2>&1; then
     autoload -Uz compinit && compinit
 fi
-compdef _cerefox cerefox
+compdef _${fn} ${prog}
 `;
 }
-function fishScript(nodes) {
+function fishScript(nodes, prog, fn) {
   const candCases = nodes.map((n) => `        case "${n.path}"
             echo "${n.candidates.join(" ")}"`).join(`
 `);
   const pathList = nodes.filter((n) => n.path !== "").map((n) => `"${n.path}"`).join(" ");
-  return `# Cerefox fish completion. Save to ~/.config/fish/completions/cerefox.fish
-function __cerefox_candidates
+  return `# Cerefox fish completion. Save to ~/.config/fish/completions/${prog}.fish
+function __${fn}_candidates
     switch "$argv[1]"
 ${candCases}
         case '*'
             echo "--help"
     end
 end
-function __cerefox_is_path
+function __${fn}_is_path
     for p in ${pathList}
         if test "$argv[1]" = "$p"
             return 0
@@ -68278,7 +68306,7 @@ function __cerefox_is_path
     end
     return 1
 end
-function __cerefox_complete
+function __${fn}_complete
     set -l tokens (commandline -opc)
     set -l path ""
     set -l i 2
@@ -68293,27 +68321,35 @@ function __cerefox_complete
         else
             set trial "$path $w"
         end
-        if __cerefox_is_path "$trial"
+        if __${fn}_is_path "$trial"
             set path "$trial"
             set i (math $i + 1)
         else
             break
         end
     end
-    string split ' ' -- (__cerefox_candidates "$path")
+    string split ' ' -- (__${fn}_candidates "$path")
 end
-complete -c cerefox -f -a '(__cerefox_complete)'
+complete -c ${prog} -f -a '(__${fn}_complete)'
 `;
 }
+function progName() {
+  return buildProgram().name();
+}
+function fnId(prog) {
+  return prog.replace(/[^a-zA-Z0-9]/g, "_");
+}
 function scriptFor(shell) {
   const nodes = collectNodes();
+  const prog = progName();
+  const fn = fnId(prog);
   switch (shell) {
     case "bash":
-      return bashScript(nodes);
+      return bashScript(nodes, prog, fn);
     case "zsh":
-      return zshScript(nodes);
+      return zshScript(nodes, prog, fn);
     case "fish":
-      return fishScript(nodes);
+      return fishScript(nodes, prog, fn);
   }
 }
 function detectShell() {
@@ -68322,8 +68358,12 @@ function detectShell() {
     return sh;
   return null;
 }
-var RC_BEGIN = "# >>> cerefox shell completion (managed by `cerefox completion install`) >>>";
-var RC_END = "# <<< cerefox shell completion <<<";
+function rcBeginFor(prog) {
+  return `# >>> ${prog} shell completion (managed by \`${prog} completion install\`) >>>`;
+}
+function rcEndFor(prog) {
+  return `# <<< ${prog} shell completion <<<`;
+}
 async function installMode(options) {
   const shell = options.shell ?? detectShell();
   if (!shell) {
@@ -68333,21 +68373,24 @@ async function installMode(options) {
     throw userError(`Unsupported --shell "${shell}". Use bash, zsh, or fish.`);
   }
   const home = homedir3();
-  const scriptPath = join3(home, `.cerefox-completion.${shell}`);
+  const prog = progName();
+  const rcBegin = rcBeginFor(prog);
+  const rcEnd = rcEndFor(prog);
+  const scriptPath = join3(home, `.${prog}-completion.${shell}`);
   writeFileSync2(scriptPath, scriptFor(shell), "utf8");
   println(c.green(`✓ Wrote completion script: ${scriptPath}`));
   if (shell === "fish") {
-    println(c.dim("  For fish, also copy it into ~/.config/fish/completions/cerefox.fish (or `source` it)."));
+    println(c.dim(`  For fish, also copy it into ~/.config/fish/completions/${prog}.fish (or \`source\` it).`));
     return;
   }
   const rcPath = join3(home, shell === "zsh" ? ".zshrc" : ".bashrc");
   const sourceLine = `[ -s "${scriptPath}" ] && source "${scriptPath}"`;
-  const block = `${RC_BEGIN}
+  const block = `${rcBegin}
 ${sourceLine}
-${RC_END}
+${rcEnd}
 `;
   const existing = existsSync3(rcPath) ? readFileSync3(rcPath, "utf8") : "";
-  if (existing.includes(RC_BEGIN)) {
+  if (existing.includes(rcBegin)) {
     println(c.dim(`  ${rcPath} already sources the completion (left as-is).`));
   } else {
     const interactive = process.stdout.isTTY && !options.yes;
@@ -69576,6 +69619,12 @@ function defaultCerefoxEntry() {
     args: ["-y", "--package=@cerefox/memory", "cerefox", "mcp"]
   };
 }
+function localCerefoxEntry() {
+  return {
+    command: process.env.CEREFOX_LOCAL_CMD || "cerefox-local",
+    args: ["mcp"]
+  };
+}
 function claudeCodeUserConfigPath() {
   return join4(homedir4(), ".claude.json");
 }
@@ -69589,8 +69638,7 @@ function claudeDesktopConfigPath() {
   }
   return join4(home, ".config", "Claude", "claude_desktop_config.json");
 }
-function claudeCodeDelegated() {
-  const entry = defaultCerefoxEntry();
+function claudeCodeDelegated(entry) {
   return {
     cmd: "claude",
     args: ["mcp", "add", "cerefox", "--scope", "user", "--", entry.command, ...entry.args]
@@ -69656,7 +69704,7 @@ function writeMcpConfig(writer, opts = {}) {
   return directWrite(writer, writer.configPath, opts);
 }
 function directWrite(writer, configPath, opts) {
-  const entry = writer.buildServerEntry();
+  const entry = opts.entry ?? writer.buildServerEntry();
   const format = writer.format ?? "json";
   if (!opts.dryRun)
     mkdirSync2(dirname(configPath), { recursive: true });
@@ -69697,8 +69745,8 @@ function delegatedWrite(writer, opts) {
   if (!writer.delegated) {
     throw new Error(`${writer.label}: kind=delegated but no delegated() factory`);
   }
-  const { cmd, args } = writer.delegated();
-  const entry = writer.buildServerEntry();
+  const entry = opts.entry ?? writer.buildServerEntry();
+  const { cmd, args } = writer.delegated(entry);
   const delegatedCommand = `${cmd} ${args.join(" ")}`;
   if (opts.dryRun) {
     return {
@@ -69743,7 +69791,8 @@ function action6(options) {
   const result = writeMcpConfig(writer, {
     customPath: options.configPath,
     noBackup: !options.backup,
-    dryRun: options.dryRun
+    dryRun: options.dryRun,
+    entry: options.local ? localCerefoxEntry() : undefined
   });
   if (options.json) {
     printJson(result);
@@ -69787,7 +69836,7 @@ function restartHint(id) {
   }
 }
 function registerConfigureAgent(program2) {
-  program2.command("configure-agent").description("Write the MCP server config for a supported client.").requiredOption("-t, --tool <client>", "Target client: claude-code, claude-desktop, cursor, codex, gemini.").option("--config-path <path>", "Override the default config-file path.").option("--no-backup", "Skip the .pre-cerefox.bak backup of any existing config.").option("--dry-run", "Print the planned write without modifying any file.").option("--json", "Emit JSON describing the result.").action(action6);
+  program2.command("configure-agent").description("Write the MCP server config for a supported client.").requiredOption("-t, --tool <client>", "Target client: claude-code, claude-desktop, cursor, codex, gemini.").option("--config-path <path>", "Override the default config-file path.").option("--no-backup", "Skip the .pre-cerefox.bak backup of any existing config.").option("--dry-run", "Print the planned write without modifying any file.").option("--json", "Emit JSON describing the result.").option("--local", "Wire the local/self-hosted backend (`cerefox-local mcp`) instead of npx. Used by `cerefox-local configure-agent`.").action(action6);
 }
 
 // src/cli/commands/delete-doc.ts
@@ -73925,7 +73974,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 +75098,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 +75125,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,8 +76539,8 @@ 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 maxBytes = parseNonNegativeInt(options.maxBytes, "--max-bytes", 200000);
+  const minScore = parseFloat01(options.minScore, "--min-score", getMinSearchScore());
+  const maxBytes = parseNonNegativeInt(options.maxBytes, "--max-bytes", getMaxResponseBytes());
   const mode = options.mode ?? "docs";
   if (!["docs", "hybrid", "fts"].includes(mode)) {
     throw userError(`--mode "${mode}": expected "docs", "hybrid", or "fts".`);
@@ -76620,7 +76685,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 (default: CEREFOX_MAX_RESPONSE_BYTES or 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 +80306,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;
@@ -80256,7 +80321,7 @@ async function runSearch(ctx, opts) {
     p_match_count: Math.min(count, 5),
     p_alpha: 0.7,
     p_project_id: projectId,
-    p_min_score: 0
+    p_min_score: getMinSearchScore()
   };
   if (metadataFilter)
     params.p_metadata_filter = metadataFilter;
@@ -81939,9 +82004,9 @@ function registerRenameHusks(program2) {
   }
 }
 function buildProgram() {
-  const progName = process.env.CEREFOX_PROG_NAME || "cerefox";
-  const program2 = new Command(progName).description("Cerefox — user-owned shared memory for AI agents.").version(PKG_VERSION, "-v, --version", `Print the ${progName} version and exit.`).addOption(new Option("--json", "Emit machine-readable JSON on stdout instead of the default human text. " + "Available on read commands; ignored on commands without a JSON shape.").hideHelp()).showHelpAfterError(`(run \`${progName} --help\` for usage)`).enablePositionalOptions().addHelpText("after", `
-Resource groups (run \`${progName} <group> --help\`):
+  const progName2 = process.env.CEREFOX_PROG_NAME || "cerefox";
+  const program2 = new Command(progName2).description("Cerefox — user-owned shared memory for AI agents.").version(PKG_VERSION, "-v, --version", `Print the ${progName2} version and exit.`).addOption(new Option("--json", "Emit machine-readable JSON on stdout instead of the default human text. " + "Available on read commands; ignored on commands without a JSON shape.").hideHelp()).showHelpAfterError(`(run \`${progName2} --help\` for usage)`).enablePositionalOptions().addHelpText("after", `
+Resource groups (run \`${progName2} <group> --help\`):
 ` + `  document   get · list · edit · delete · restore · ingest · ingest-dir · version {list·archive·unarchive}
 ` + `  project    list · create · edit · delete
 ` + `  metadata   keys · search
@@ -81964,8 +82029,8 @@ Exit codes:
 ` + `  1  user error         3  not found (document / version / project)
 ` + `
 Learn more:
-` + `  ${progName} guides list                  # bundled docs (offline)
-` + `  ${progName} doctor                       # diagnose your install
+` + `  ${progName2} guides list                  # bundled docs (offline)
+` + `  ${progName2} doctor                       # diagnose your install
 ` + `  https://github.com/fstamatelopoulos/cerefox
 `);
   registerSearch(program2);

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/access-paths.md

@@ -147,6 +147,32 @@ operations.
 
 ---
 
+## Local / self-hosted (World B) — a different access model
+
+Everything above describes the **cloud / Supabase** deployment. The **local / self-hosted**
+backend ([`setup-local.md`](setup-local.md)) runs Postgres + PostgREST + the Cerefox server
+in one Docker container, and its access model is deliberately simpler:
+
+- **No Layer 1 (Edge Functions) and no anon-JWT.** There are no Edge Functions; the
+  `cerefox-server` inside the container exposes `/rest/v1` (a reverse-proxy to the in-container
+  PostgREST) plus `/app` + `/api/v1`. Remote agents over HTTP are not a goal of World B.
+- **The access token never leaves the container.** db-init self-generates the PostgREST JWT
+  secret on boot and mints a `service_role` token into the container's runtime env. The web
+  UI (served by the container) and the in-container CLI/MCP read it internally — nothing on
+  the host holds it.
+- **Agents use stdio over `docker exec`, not a network credential.** `cerefox-local mcp`
+  runs `cerefox mcp` inside the container via `docker exec -i`; the MCP client launches that
+  as a local subprocess. No URL, no bearer token in the client config.
+- **The only host-side secret is `OPENAI_API_KEY`** (in `~/.cerefox/local/.env`), used for
+  embeddings — the same as every deployment.
+- By default the container publishes on **`127.0.0.1`** (loopback only); set
+  `CEREFOX_LOCAL_BIND=0.0.0.0` to expose it on the LAN.
+
+So Layers 1–3 below apply to the cloud deployment; the local backend collapses them into a
+single container with an internally-held token.
+
+---
+
 ## Summary
 
 | Caller | Transport | Auth credential | Typical use |

package/docs/guides/agent-coordination.md

@@ -23,6 +23,8 @@ Within a single runtime (e.g., Claude Code's agent teams feature, or a LangGraph
 
 Cerefox sits in a unique position: it is vendor-neutral, protocol-native (MCP + REST), and designed for persistent storage. Any agent that can make an HTTP call can read and write to Cerefox.
 
+> **Cross-machine coordination assumes the cloud / Supabase backend** (a shared network endpoint). The default **local / self-hosted (Docker) backend is single-machine** — it binds `127.0.0.1` and agents reach it via `cerefox-local mcp` (stdio). To coordinate agents across machines with a local backend, expose it on your LAN (`CEREFOX_LOCAL_BIND=0.0.0.0`) or use the cloud backend.
+
 The coordination model is **asynchronous and knowledge-based**:
 
 1. **Agent A writes** a finding, decision, or task breakdown to Cerefox. It does not need to know which agent will consume it.

package/docs/guides/cli.md

@@ -4,17 +4,23 @@ Comprehensive reference for every `cerefox` subcommand. For tutorials and walkth
 
 > `--help` is canonical. If anything in this document disagrees with `cerefox <subcommand> --help`, trust `--help` and file an issue against this guide.
 
+> **Local / self-hosted (Docker) backend?** Every KB verb below is identical, but you run it
+> as **`cerefox-local <verb>`** (it proxies into the container via `docker exec`); lifecycle
+> is different (`cerefox-local init/start/stop/upgrade/uninstall/status/logs/configure-agent`).
+> A local user sets **only `OPENAI_API_KEY`** — the Supabase/database vars below do **not**
+> apply (the container owns them). See [`setup-local.md`](setup-local.md).
+
 ## Setup
 
-Every command reads configuration from `.env` in the working directory (or environment variables — see [`configuration.md`](configuration.md)). Required at minimum:
+This section is for the **cloud / Supabase** backend. Every command reads configuration from `.env` in the working directory (or environment variables — see [`configuration.md`](configuration.md)). Required at minimum:
 
 - `CEREFOX_SUPABASE_URL` and `CEREFOX_SUPABASE_KEY` for any command that talks to Supabase
-- `OPENAI_API_KEY` (or `CEREFOX_FIREWORKS_API_KEY`) for any command that embeds (ingest, search)
+- `OPENAI_API_KEY` for any command that embeds (ingest, search)
 - `CEREFOX_DATABASE_URL` for `cerefox server deploy` and the contributor scripts (`bun scripts/db_*.ts`)
 
 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
 
@@ -86,7 +92,7 @@ Walks `DIRECTORY` **recursively** (always — there is no recurse toggle) and in
 
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `--extensions <list>` (`-e`) | comma list | `.md,.txt` | File extensions to ingest, e.g. `--extensions .md`. |
+| `--extensions <list>` (`-e`) | comma list | `.md,.txt` | File extensions to ingest, e.g. `--extensions .md`. `.docx` is **not** in the default set — opt in with `--extensions .md,.txt,.docx` (converted via mammoth, same as single-file ingest). |
 | `--project-name <name>` (`-p`) | str | _none_ | Project to assign every document to. |
 | `--update-if-exists` (`-u`) | flag | off | Update existing documents by source path / title. |
 | `--metadata <json>` (`-m`) | JSON | `{}` | JSON metadata applied to every file in the run. |
@@ -141,7 +147,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`.
+| `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. |
 
-### Fireworks AI (alternative, lower cost)
+> **⚠ 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.
 
-| 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. |
-
-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)
 
@@ -250,16 +250,9 @@ OPENAI_API_KEY=sk-...
 # All other settings use defaults
 ```
 
-## Example: Fireworks Embedder `.env`
-
-```bash
-CEREFOX_SUPABASE_URL=https://abcdefghijkl.supabase.co
-CEREFOX_SUPABASE_KEY=eyJhbGciOiJIUzI1NiIs...
-CEREFOX_DATABASE_URL=postgresql://...
-
-CEREFOX_EMBEDDER=fireworks
-CEREFOX_FIREWORKS_API_KEY=fw_...
-```
+> **Fireworks is not wired in the TS runtime yet** — `CEREFOX_EMBEDDER=fireworks` /
+> `CEREFOX_FIREWORKS_*` are documented for the retired Python runtime but are currently
+> no-ops (OpenAI is the only embedder implemented today). Tracked for a future release.
 
 ---
 

package/docs/guides/connect-agents.md

@@ -59,6 +59,20 @@ Three top-level paths plus a few special cases:
 > available in [`examples/mcp-configs/`](../examples/mcp-configs/). Pick the one for your
 > client, replace the placeholders, and you're connected.
 
+### Local / self-hosted (World B)
+
+If you run the **Docker backend** ([`setup-local.md`](setup-local.md)) instead of cloud, the
+MCP path is different: the server runs **inside the container**, launched per session over
+`docker exec`. There's no URL or bearer token in the client config — the access token stays
+in the container.
+
+- **Easiest:** `cerefox-local configure-agent` wires it up (registers an MCP server named
+  `cerefox-local` with Claude Code if the `claude` CLI is present, else prints the snippet).
+- **Manual:** point the client at `command: cerefox-local, args: ["mcp"]` (stdio). That proxies
+  to `cerefox mcp` in the container; the same 10 tools, identical behavior to every other path.
+- The cloud paths above (remote Edge Function, GPT Actions) **do not apply** to a local-only
+  install — there are no Edge Functions.
+
 ---
 
 ## Prerequisites

package/docs/guides/operational-cost.md

@@ -116,12 +116,34 @@ These limits comfortably cover personal-use traffic. Check
 
 ---
 
+## Scenario C — Fully local / self-hosted (Docker)
+
+The whole backend runs in one Docker container on your machine — Postgres + pgvector +
+the Cerefox server — with **no Supabase and no Edge Functions** ([`setup-local.md`](setup-local.md)).
+
+```
+Your machine
+└── Docker container       (free)
+    └── Postgres + pgvector + cerefox web/MCP
+        Embeddings via OpenAI API  (pay-per-use)
+```
+
+**Typical cost for personal use**: just the **OpenAI embedding spend** (the same pay-per-use
+as every scenario — fractions of a cent per document) plus local compute/electricity. There
+is **no Supabase tier and no Edge-Function invocation limit** to worry about — the binding
+free-tier constraint from Scenarios A/B (500K EF calls/month) simply doesn't exist here, and
+agents using the local MCP server make zero billable cloud calls. The only ongoing cost is
+embeddings (and only when you ingest or run semantic/hybrid search) — see "Controlling
+embedding costs" below.
+
+---
+
 ## Controlling embedding costs
 
 If you want to keep costs as low as possible:
 
-- **Fireworks AI** is an OpenAI-compatible alternative that offers competitive embedding prices.
-  See `docs/guides/configuration.md` for how to switch.
+- **Cheaper embedding models**: a lower-cost OpenAI-compatible provider (e.g. Fireworks AI)
+  is on the roadmap — **not yet wired in the TS runtime** (OpenAI only today).
 - **Batch ingest, don't re-ingest**: Cerefox deduplicates by content hash — re-ingesting the
   same file twice costs nothing. Only new or changed content triggers embedding calls.
 - **`cerefox server reindex`**: Re-embeds all existing chunks if you switch embedders. Run this once

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-local.md

@@ -36,11 +36,13 @@ That's it. No Node, Bun, Postgres, or repo clone needed.
 ## Step 1 — Install
 
 ```bash
-OPENAI_API_KEY=sk-... sh -c "$(curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install-local.sh)"
+curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install-local.sh | sh
 ```
 
 This pulls the published multi-arch image (`amd64` + `arm64`), starts the container, and
-installs a `cerefox-local` command (symlinked into `~/.local/bin`). Pick a different port
+installs a `cerefox-local` command (symlinked into `~/.local/bin`). To set your OpenAI key
+inline at install instead of via `cerefox-local init` (Step 2), use the command-substitution
+form: `OPENAI_API_KEY=sk-... sh -c "$(curl -fsSL …/install-local.sh)"`. Pick a specific port
 with `PORT=8017 …`.
 
 > If the installer warns that `~/.local/bin` isn't on your `PATH`, add it:
@@ -48,7 +50,12 @@ with `PORT=8017 …`.
 > echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
 > ```
 
-The web UI is now at **http://localhost:8000/app/** (or your chosen port).
+The web UI is now at **http://localhost:8000/app/** — **or the port the installer chose**
+(it auto-steps to 8010/8020/… if 8000 is busy or you also run the cloud `cerefox web`, which
+defaults to 8000). The installer prints the actual URL; `cerefox-local status` shows it too.
+
+The installer also wires **shell tab-completion** for `cerefox-local` (best-effort) — run
+`exec $SHELL` or open a new terminal to activate it.
 
 **How the credential works:** the container generates its own JWT secret on first boot and
 mints the access token internally — the token never leaves the container. The only secret

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/docs/guides/upgrading.md

@@ -10,6 +10,7 @@ to re-run.
 |---|---|
 | **Installer / npm** (end user, no repo clone) | `cerefox self-update` (or re-run the [installer](quickstart.md#1-install), or `bun/npm update -g @cerefox/memory`). Then `cerefox server deploy` **if the release notes flag a server-side change**. `cerefox doctor` verifies. |
 | **Source checkout** (`git clone`, contributor) | `git pull`, then `cerefox server deploy` (or the lower-level `bun scripts/db_*.ts` + `npx supabase functions deploy`). Rebuild the SPA if you run `cerefox web` from source. |
+| **Local / self-hosted (Docker, World B)** | `cerefox-local upgrade` — pulls the new image and recreates the container (data persists in the volume; OpenAI key + tuning overrides preserved). **No separate `server deploy`/`reindex`**: the CLI, web, PostgREST, and schema all ship together in one versioned image, so they can't drift. See [`setup-local.md`](setup-local.md). |
 
 > **On an old pre-installer clone (0.1.x)?** The cleanest upgrade is to stop
 > running from the repo and install the package: follow the

package/package.json

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