@cerefox/memory 0.10.1 → 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.1";
+var PKG_VERSION = "0.10.2";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js
@@ -68198,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]}"
@@ -68227,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
@@ -68267,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
@@ -68282,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
@@ -68306,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
@@ -68321,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() {
@@ -68350,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) {
@@ -68361,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;
@@ -69604,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");
 }
@@ -69617,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]
@@ -69684,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 });
@@ -69725,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 {
@@ -69771,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);
@@ -69815,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
@@ -76519,7 +76540,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", getMinSearchScore());
-  const maxBytes = parseNonNegativeInt(options.maxBytes, "--max-bytes", 200000);
+  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".`);
@@ -76664,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 (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);
+  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
@@ -80300,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;
@@ -81983,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
@@ -82008,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/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,12 +4,18 @@ 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)).
@@ -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. |

package/docs/guides/configuration.md

@@ -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/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/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.1",
+  "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",