@cerefox/memory 0.5.2 → 0.5.3

package/README.md

@@ -79,11 +79,19 @@ already provisioned (see "Before you install").
 > the deploy logic is ported to the TS CLI. For now, the setup-supabase
 > guide walks through it.
 
+> **Upgrading from the Python `cerefox` CLI?** If you have a working
+> `.env` in your repo clone, init detects it and offers to **copy** it to
+> `~/.cerefox/.env` so the TS CLI uses the new home while Python keeps
+> reading the repo file unchanged. See the migration-v0.5 guide for the
+> three-choice prompt. Existing users with no `~/.cerefox/.env` see zero
+> behavior change until they opt in.
+
 ---
 
 ## Connect an AI agent
 
 ```bash
+# Run the configure-agent commands that apply to your setup:
 cerefox configure-agent --tool claude-code          # writes ~/.claude/mcp.json
 cerefox configure-agent --tool claude-desktop       # writes Claude Desktop config
 ```

package/dist/bin/cerefox.js

@@ -7179,7 +7179,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "0.5.2";
+var PKG_VERSION = "0.5.3";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js
@@ -22494,26 +22494,35 @@ function expandTilde(p) {
   }
   return p;
 }
+function userStateDirAbs(opts) {
+  return resolvePath(join(opts.home ?? homedir(), USER_STATE_DIR_NAME));
+}
 function resolveConfigDir(opts = {}) {
   const override = (env.CEREFOX_CONFIG_DIR ?? "").trim();
   if (override) {
     return resolvePath(expandTilde(override));
   }
+  const userState = userStateDirAbs(opts);
+  if (existsSync(join(userState, ".env"))) {
+    return userState;
+  }
   const here = opts.cwd ?? processCwd();
   if (existsSync(join(here, ".env"))) {
     return resolvePath(here);
   }
-  return resolvePath(join(homedir(), USER_STATE_DIR_NAME));
+  return userState;
 }
 function resolveEnvFile(opts = {}) {
   return join(resolveConfigDir(opts), ".env");
 }
-function userStateDir() {
-  return resolvePath(join(homedir(), USER_STATE_DIR_NAME));
+function userStateDir(opts = {}) {
+  return userStateDirAbs(opts);
 }
 function isDevMode(opts = {}) {
   if ((env.CEREFOX_CONFIG_DIR ?? "").trim())
     return false;
+  if (existsSync(join(userStateDirAbs(opts), ".env")))
+    return false;
   const here = opts.cwd ?? processCwd();
   return existsSync(join(here, ".env"));
 }
@@ -38333,7 +38342,7 @@ init_cli_core();
 init_meta();
 init_config();
 init_config();
-import { existsSync as existsSync5, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync5, realpathSync, statSync as statSync2 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { join as join5 } from "node:path";
 function checkBinary() {
@@ -38577,6 +38586,23 @@ function checkMcpConfigs() {
     detail: found.map((f) => f.label).join(", ")
   };
 }
+function checkLegacyShadowEnv() {
+  const home = homedir4();
+  const homeEnv = join5(home, USER_STATE_DIR_NAME, ".env");
+  const cwdEnv = join5(process.cwd(), ".env");
+  if (!existsSync5(homeEnv) || !existsSync5(cwdEnv))
+    return null;
+  try {
+    if (realpathSync(homeEnv) === realpathSync(cwdEnv))
+      return null;
+  } catch {}
+  return {
+    name: "legacy env",
+    status: "skipped",
+    detail: `${cwdEnv} (shadowed by ~/.cerefox/.env)`,
+    hint: "Python `uv run cerefox …` still reads this file during the v0.5–v0.7 migration window. " + "Safe to delete once Python support is removed (v0.9+)."
+  };
+}
 function checkPostgres() {
   if (process.env.CEREFOX_DATABASE_URL) {
     return {
@@ -38593,11 +38619,13 @@ function checkPostgres() {
   };
 }
 async function runAllChecks() {
+  const legacy = checkLegacyShadowEnv();
   return [
     checkBinary(),
     checkRuntime(),
     checkVersion(),
     checkConfig(),
+    ...legacy ? [legacy] : [],
     await checkSupabase(),
     await checkOpenAI(),
     await checkSchemaVersion(),
@@ -38938,12 +38966,14 @@ init_cli_core();
 init_config();
 import {
   chmodSync,
+  copyFileSync as copyFileSync2,
   existsSync as existsSync6,
   mkdirSync as mkdirSync3,
   readFileSync as readFileSync7,
   writeFileSync as writeFileSync3
 } from "node:fs";
-import { dirname as dirname3 } from "node:path";
+import { homedir as homedir5 } from "node:os";
+import { dirname as dirname3, join as join7 } from "node:path";
 async function readConfigFile(path) {
   if (!existsSync6(path)) {
     throw userError(`--config file not found: ${path}`);
@@ -38973,6 +39003,41 @@ async function readConfigFile(path) {
     CEREFOX_AUTHOR_TYPE: typeof obj.CEREFOX_AUTHOR_TYPE === "string" ? obj.CEREFOX_AUTHOR_TYPE : undefined
   };
 }
+function parseDotEnvFile(content) {
+  const map = {};
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#"))
+      continue;
+    const eqIdx = line.indexOf("=");
+    if (eqIdx === -1)
+      continue;
+    const key = line.slice(0, eqIdx).trim();
+    let value = line.slice(eqIdx + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    map[key] = value;
+  }
+  return map;
+}
+function answersFromEnvFile(path) {
+  const parsed = parseDotEnvFile(readFileSync7(path, "utf8"));
+  const required = ["CEREFOX_SUPABASE_URL", "CEREFOX_SUPABASE_KEY", "OPENAI_API_KEY"];
+  for (const key of required) {
+    if (!parsed[key] || parsed[key].trim() === "") {
+      throw userError(`Existing .env at ${path} is missing required key "${key}".`, `Fix it manually or run \`cerefox init --force\` to start fresh.`);
+    }
+  }
+  return {
+    CEREFOX_SUPABASE_URL: parsed.CEREFOX_SUPABASE_URL,
+    CEREFOX_SUPABASE_KEY: parsed.CEREFOX_SUPABASE_KEY,
+    OPENAI_API_KEY: parsed.OPENAI_API_KEY,
+    CEREFOX_DATABASE_URL: parsed.CEREFOX_DATABASE_URL,
+    CEREFOX_AUTHOR_NAME: parsed.CEREFOX_AUTHOR_NAME,
+    CEREFOX_AUTHOR_TYPE: parsed.CEREFOX_AUTHOR_TYPE
+  };
+}
 async function promptForAnswers() {
   println(c.bold("Cerefox first-run setup."));
   println(c.dim(`This will write configuration to ~/.cerefox/.env (or CEREFOX_CONFIG_DIR if set).
@@ -39087,35 +39152,38 @@ async function validateOpenAI(key) {
     throw userError(`OpenAI key validation failed: ${resp.status} ${body.slice(0, 100)}`, "Verify the key on https://platform.openai.com/api-keys.");
   }
 }
-async function action14(options) {
-  const envPath = resolveEnvFile();
-  if (existsSync6(envPath) && !options.force) {
-    println(c.yellow(`⚠ Config already exists at ${envPath}.`));
-    const ok2 = await confirm("Overwrite?", true);
-    if (!ok2) {
-      println(c.dim("Aborted. Use `--force` to skip this prompt next time."));
-      return;
-    }
-  }
-  const answers = options.config ? await readConfigFile(options.config) : await promptForAnswers();
+function printMigrationMenu(cwdEnv, homeEnv) {
   println("");
-  println(c.bold("Validating credentials…"));
-  await validateSupabase(answers.CEREFOX_SUPABASE_URL, answers.CEREFOX_SUPABASE_KEY);
-  println(c.green("  ✓ Supabase reachable"));
-  await validateOpenAI(answers.OPENAI_API_KEY);
-  println(c.green("  ✓ OpenAI key valid (test embedding succeeded)"));
-  mkdirSync3(dirname3(envPath), { recursive: true });
-  writeFileSync3(envPath, buildEnvFile(answers), "utf8");
-  if (process.platform !== "win32") {
-    try {
-      chmodSync(envPath, 384);
-    } catch {
-      warn(`Could not chmod 0600 ${envPath}.`);
-    }
-  }
+  println(c.yellow(`⚠ Found existing config at ${cwdEnv}.`));
+  println("");
+  println("This may be from a previous Python install. The TS CLI can use the");
+  println("same .env — env-var names are identical, no rewrite needed.");
   println("");
-  println(c.green(`✓ Wrote ${envPath}`));
+  println("  " + c.bold("[c]") + " Copy to " + homeEnv + "  " + c.green("(recommended)"));
+  println(c.dim("      • TS reads the new home from now on"));
+  println(c.dim("      • Python keeps reading " + cwdEnv + " (backward compat)"));
+  println(c.dim("      • Edit ~/.cerefox/.env going forward; the repo .env is legacy"));
   println("");
+  println("  " + c.bold("[u]") + " Use " + cwdEnv + " as-is, skip writing anything");
+  println(c.dim("      • Both TS and Python keep reading the existing file"));
+  println(c.dim("      • Defer the migration"));
+  println("");
+  println("  " + c.bold("[f]") + " Fresh start — interactive prompts, write to " + homeEnv);
+  println(c.dim("      • Use if the existing file is stale or wrong"));
+  println("");
+}
+async function promptMigrationChoice() {
+  const choice = await ask({
+    type: "text",
+    name: "choice",
+    message: "Choice (c/u/f) [c]",
+    initial: "c",
+    validate: (v) => /^[cuf]?$/i.test(v.trim()) || "Expected c, u, or f."
+  });
+  const ch = choice.trim().toLowerCase() || "c";
+  return ch;
+}
+async function postWriteLifecycle(envPath, options) {
   if (!options.skipSchema) {
     println(c.bold("Schema deploy"));
     println(c.dim(`  v0.5 doesn't yet bundle the schema-deploy path (it needs the direct
@@ -39159,6 +39227,127 @@ async function action14(options) {
   println(c.dim("  cerefox doctor              # verify everything"));
   println(c.dim('  cerefox search "…"          # search the KB'));
   println(c.dim("  cerefox ingest <file>       # add a doc"));
+  println("");
+  println(c.dim(`  Config in effect: ${envPath}`));
+}
+function writeAnswersTo(target, answers) {
+  mkdirSync3(dirname3(target), { recursive: true });
+  writeFileSync3(target, buildEnvFile(answers), "utf8");
+  if (process.platform !== "win32") {
+    try {
+      chmodSync(target, 384);
+    } catch {
+      warn(`Could not chmod 0600 ${target}.`);
+    }
+  }
+}
+async function action14(options) {
+  const homeEnv = join7(homedir5(), USER_STATE_DIR_NAME, ".env");
+  const cwdEnv = join7(process.cwd(), ".env");
+  const explicitDir = (process.env.CEREFOX_CONFIG_DIR ?? "").trim();
+  if (explicitDir) {
+    const target2 = resolveEnvFile();
+    if (existsSync6(target2) && !options.force) {
+      println(c.yellow(`⚠ Config already exists at ${target2}.`));
+      const ok2 = await confirm("Overwrite?", true);
+      if (!ok2) {
+        println(c.dim("Aborted. Use `--force` to skip this prompt next time."));
+        return;
+      }
+    }
+    const answers2 = options.config ? await readConfigFile(options.config) : await promptForAnswers();
+    println("");
+    println(c.bold("Validating credentials…"));
+    await validateSupabase(answers2.CEREFOX_SUPABASE_URL, answers2.CEREFOX_SUPABASE_KEY);
+    println(c.green("  ✓ Supabase reachable"));
+    await validateOpenAI(answers2.OPENAI_API_KEY);
+    println(c.green("  ✓ OpenAI key valid (test embedding succeeded)"));
+    writeAnswersTo(target2, answers2);
+    println("");
+    println(c.green(`✓ Wrote ${target2}`));
+    println("");
+    await postWriteLifecycle(target2, options);
+    return;
+  }
+  if (existsSync6(homeEnv) && !options.force) {
+    println(c.yellow(`⚠ Config already exists at ${homeEnv}.`));
+    const ok2 = await confirm("Overwrite?", true);
+    if (!ok2) {
+      println(c.dim("Aborted. Use `--force` to skip this prompt next time."));
+      return;
+    }
+    const answers2 = options.config ? await readConfigFile(options.config) : await promptForAnswers();
+    println("");
+    println(c.bold("Validating credentials…"));
+    await validateSupabase(answers2.CEREFOX_SUPABASE_URL, answers2.CEREFOX_SUPABASE_KEY);
+    println(c.green("  ✓ Supabase reachable"));
+    await validateOpenAI(answers2.OPENAI_API_KEY);
+    println(c.green("  ✓ OpenAI key valid (test embedding succeeded)"));
+    writeAnswersTo(homeEnv, answers2);
+    println("");
+    println(c.green(`✓ Wrote ${homeEnv}`));
+    println("");
+    await postWriteLifecycle(homeEnv, options);
+    return;
+  }
+  if (existsSync6(cwdEnv) && !options.force && !options.config) {
+    printMigrationMenu(cwdEnv, homeEnv);
+    const ch = await promptMigrationChoice();
+    println("");
+    if (ch === "c") {
+      mkdirSync3(dirname3(homeEnv), { recursive: true });
+      copyFileSync2(cwdEnv, homeEnv);
+      if (process.platform !== "win32") {
+        try {
+          chmodSync(homeEnv, 384);
+        } catch {
+          warn(`Could not chmod 0600 ${homeEnv}.`);
+        }
+      }
+      println(c.green(`✓ Copied ${cwdEnv} → ${homeEnv}`));
+      println(c.dim(`  Repo file unchanged — Python still reads it during migration.`));
+      println("");
+      const answers2 = answersFromEnvFile(homeEnv);
+      println(c.bold("Validating credentials…"));
+      await validateSupabase(answers2.CEREFOX_SUPABASE_URL, answers2.CEREFOX_SUPABASE_KEY);
+      println(c.green("  ✓ Supabase reachable"));
+      await validateOpenAI(answers2.OPENAI_API_KEY);
+      println(c.green("  ✓ OpenAI key valid (test embedding succeeded)"));
+      println("");
+      await postWriteLifecycle(homeEnv, options);
+      return;
+    }
+    if (ch === "u") {
+      const answers2 = answersFromEnvFile(cwdEnv);
+      println(c.bold("Validating existing config…"));
+      await validateSupabase(answers2.CEREFOX_SUPABASE_URL, answers2.CEREFOX_SUPABASE_KEY);
+      println(c.green("  ✓ Supabase reachable"));
+      await validateOpenAI(answers2.OPENAI_API_KEY);
+      println(c.green("  ✓ OpenAI key valid (test embedding succeeded)"));
+      println("");
+      println(c.green(`✓ Using existing config at ${cwdEnv}`));
+      println(c.dim(`  TS reads it via the legacy dev-mode fallback (~/.cerefox/.env not present).`));
+      println(c.dim(`  Run \`cerefox init\` again later to migrate to the new home.`));
+      println("");
+      await postWriteLifecycle(cwdEnv, options);
+      return;
+    }
+    println(c.dim(`Fresh start. Ignoring ${cwdEnv}; writing a new config to ${homeEnv}.`));
+    println("");
+  }
+  const target = homeEnv;
+  const answers = options.config ? await readConfigFile(options.config) : await promptForAnswers();
+  println("");
+  println(c.bold("Validating credentials…"));
+  await validateSupabase(answers.CEREFOX_SUPABASE_URL, answers.CEREFOX_SUPABASE_KEY);
+  println(c.green("  ✓ Supabase reachable"));
+  await validateOpenAI(answers.OPENAI_API_KEY);
+  println(c.green("  ✓ OpenAI key valid (test embedding succeeded)"));
+  writeAnswersTo(target, answers);
+  println("");
+  println(c.green(`✓ Wrote ${target}`));
+  println("");
+  await postWriteLifecycle(target, options);
 }
 function registerInit(program2) {
   program2.command("init").description("Interactive first-run setup (config, schema deploy stub, optional MCP wiring).").option("-c, --config <file>", "Non-interactive mode: read answers from a JSON file.").option("--force", "Overwrite existing configuration without prompting.").option("--skip-schema", "Skip the schema deploy step.").option("--skip-self-docs", "Skip the bundled self-doc ingest.").option("--skip-agent-config", "Skip the optional MCP agent wiring.").action(action14);
@@ -39436,13 +39625,13 @@ function registerReindex(program2) {
 init_cli_core();
 init_client();
 import { existsSync as existsSync7, readFileSync as readFileSync8, readdirSync as readdirSync3, statSync as statSync4 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
-import { join as join7, resolve as resolve3 } from "node:path";
+import { homedir as homedir6 } from "node:os";
+import { join as join8, resolve as resolve3 } from "node:path";
 function expandHome2(path) {
   if (path === "~")
-    return homedir5();
+    return homedir6();
   if (path.startsWith("~/"))
-    return join7(homedir5(), path.slice(2));
+    return join8(homedir6(), path.slice(2));
   return path;
 }
 function resolveBackupFile(target) {
@@ -39453,11 +39642,11 @@ function resolveBackupFile(target) {
   const stat = statSync4(path);
   if (stat.isFile())
     return path;
-  const candidates = readdirSync3(path).filter((n) => n.endsWith(".json") && n.startsWith("cerefox-")).map((n) => ({ name: n, mtime: statSync4(join7(path, n)).mtimeMs })).sort((a, b) => b.mtime - a.mtime);
+  const candidates = readdirSync3(path).filter((n) => n.endsWith(".json") && n.startsWith("cerefox-")).map((n) => ({ name: n, mtime: statSync4(join8(path, n)).mtimeMs })).sort((a, b) => b.mtime - a.mtime);
   if (candidates.length === 0) {
     throw userError(`No cerefox-*.json files in ${path}`);
   }
-  return join7(path, candidates[0].name);
+  return join8(path, candidates[0].name);
 }
 async function action20(target, options) {
   const file = resolveBackupFile(target);
@@ -39824,14 +40013,14 @@ import {
   readdirSync as readdirSync4,
   statSync as statSync5
 } from "node:fs";
-import { basename as basename4, extname as extname4, join as join8, relative } from "node:path";
+import { basename as basename4, extname as extname4, join as join9, relative } from "node:path";
 var ROOT_LEVEL_DOCS = ["README.md", "AGENT_GUIDE.md", "AGENT_QUICK_REFERENCE.md"];
 function walkMarkdown(dir) {
   const out = [];
   if (!existsSync8(dir))
     return out;
   for (const name of readdirSync4(dir)) {
-    const full = join8(dir, name);
+    const full = join9(dir, name);
     let stat;
     try {
       stat = statSync5(full);
@@ -39851,11 +40040,11 @@ async function action24(options) {
   const project = options.project ?? "cerefox";
   const targets = [];
   for (const rel of ROOT_LEVEL_DOCS) {
-    const abs = join8(cwd, rel);
+    const abs = join9(cwd, rel);
     if (existsSync8(abs))
       targets.push({ abs, rel });
   }
-  for (const abs of walkMarkdown(join8(cwd, "docs"))) {
+  for (const abs of walkMarkdown(join9(cwd, "docs"))) {
     targets.push({ abs, rel: relative(cwd, abs) });
   }
   if (targets.length === 0) {

package/docs/guides/connect-agents.md

@@ -112,19 +112,22 @@ The local Cerefox MCP server runs on your machine and exposes the same 10 tools
 Edge Function, communicating with clients over stdio.
 
 As of **v0.4.0** the local server ships as an npm package — **[`@cerefox/memory`](https://www.npmjs.com/package/@cerefox/memory)** — built with the official `@modelcontextprotocol/sdk`.
-The bin entry is `cerefox` (run as `cerefox mcp`). The recommended client config is `npx -y --package=@cerefox/memory cerefox mcp`.
+The bin entry is `cerefox` (run as `cerefox mcp`). The recommended client config is `npx -y --package=@cerefox/memory cerefox mcp`, or if you've installed the package globally, just `cerefox mcp`.
 
-The legacy `uv run cerefox mcp` invocation **still works** and is preserved as a soft
-wrapper: it tries `npx --no-install @cerefox/memory cerefox mcp` first and falls back to the
-Python MCP server if npm is unavailable or `@cerefox/memory` isn't installed. New users
-should prefer the npm-native config; existing users don't have to change anything.
+The Python `uv run cerefox mcp` invocation **still works** and remains the right choice if
+you've installed Cerefox from a source checkout. v0.4 through v0.5.1 advertised a
+"soft wrapper" that tried to auto-delegate to the npm package, but the probe was unreliable
+under MCP-client launch environments — v0.5.2 removed it. The two paths (Python via
+`uv run`, TS via `cerefox mcp` on PATH or via `npx`) are now **fully independent**.
+Pick one explicitly in your MCP client config.
 
 - Embeddings are computed locally using your `.env` key (no extra credentials)
 - Works offline except for the OpenAI embedding API call per query
 - One setup, all compatible local clients (Claude Desktop, Cursor, Claude Code, Codex CLI, …)
 
-See [`docs/guides/migration-v0.4.md`](migration-v0.4.md) for before/after config snippets
-per client.
+See [`docs/guides/migration-v0.5.md`](migration-v0.5.md) for the per-client config
+snippets, the v0.5.2 soft-wrapper removal explainer, and the v0.5.3 `.env` location
+change.
 
 > **Why not `mcp-server-fetch`?** The generic fetch MCP only supports GET requests and cannot
 > make authenticated POST calls to the Edge Functions. The built-in local server is

package/docs/guides/migration-v0.4.md

@@ -1,6 +1,23 @@
-# Migrating to Cerefox v0.4.0
-
-**TL;DR**: nothing urgent. Your existing `cerefox mcp` configs keep
+# Migrating to Cerefox v0.4.0 (historical)
+
+> ## ⚠ Historical document — do not use the snippets in this file
+>
+> This guide documents the **v0.4.0 → v0.4.3 migration window** (May 2026).
+> The `cerefox-mcp` bin name referenced throughout was dropped in **v0.5.1**;
+> the soft-wrapper described in some sections was removed in **v0.5.2**.
+> The per-client config snippets below **will not work on @cerefox/memory v0.5+**.
+>
+> **If you're upgrading today, use the current guide instead:**
+> → [`migration-v0.5.md`](migration-v0.5.md) — covers Python `cerefox` → v0.5.x
+>   AND v0.4.x → v0.5.x in a single document, with the v0.5.0/v0.5.1/v0.5.2/v0.5.3
+>   transitions all explained.
+>
+> This file is preserved so historical CHANGELOG entries that reference it
+> still resolve. It's not maintained.
+
+---
+
+**Original TL;DR (preserved verbatim)**: nothing urgent. Your existing `cerefox mcp` configs keep
 working unchanged. The Python `cerefox mcp` command is now a soft
 wrapper that transparently uses the new TypeScript MCP server if it's
 installed, falling back to the legacy Python implementation otherwise.

package/docs/guides/migration-v0.5.md

@@ -1,4 +1,22 @@
-# Migrating to Cerefox v0.5.0
+# Migrating to Cerefox v0.5.x
+
+**This is the canonical upgrade guide for any user landing on Cerefox v0.5+.**
+It covers the v0.4 → v0.5 transition, the v0.5.x patch trail (v0.5.1, v0.5.2,
+v0.5.3), and the Python `cerefox` → TS `cerefox` migration path.
+
+## Where to start
+
+| Coming from | Read |
+|---|---|
+| Never used Cerefox before | [`quickstart.md`](quickstart.md) first, then come back here only if you hit a `.env` / config question |
+| Python `cerefox` (any version through v0.5.x) | "What changed" → "Install paths" → "v0.5.3 migrated `.env`" sections below |
+| `@cerefox/memory` v0.4.x (npm) | "Upgrading an existing MCP client config" → "v0.5.2 fixed the soft wrapper" → "v0.5.3 migrated `.env`" |
+| `@cerefox/memory` v0.5.0 or v0.5.1 (npm) | "v0.5.2 fixed the soft wrapper" + "v0.5.3 migrated `.env`" |
+| `@cerefox/memory` v0.5.2 (npm) | "v0.5.3 migrated `.env`" — the rest is unchanged |
+
+> Looking for `migration-v0.4.md`? It's been demoted to a historical
+> record (the bin names it documents no longer exist). Everything you
+> need to know about the v0.4 → v0.5 transition lives in this file.
 
 **TL;DR:** the Cerefox CLI is now a TypeScript binary published to npm.
 You can keep using the Python CLI through v0.7.x (it just prints a
@@ -196,6 +214,64 @@ explicit instead of "magic delegation".
 
 ---
 
+## v0.5.3 migrated `.env` from `<repo>/.env` to `~/.cerefox/.env`
+
+If you've been using the Python `cerefox` CLI, your `.env` lives in your
+repo root (`/path/to/cerefox/.env`). The TS CLI v0.5.2 also read that
+file, via a "CWD `.env` wins" precedence inherited from Python. v0.5.3
+flips that precedence: **once `~/.cerefox/.env` exists, the TS CLI reads
+from there**; the repo file becomes a legacy fallback for Python's
+`uv run cerefox …` workflows.
+
+**You see zero behavior change until you run `cerefox init`.** If your
+home dir doesn't have `~/.cerefox/.env`, the TS CLI keeps reading your
+existing repo `.env` (legacy dev-mode precedence). No action required.
+
+When you do run `cerefox init` with a repo `.env` already in place, the
+TS CLI offers a three-choice menu:
+
+```
+⚠ Found existing config at /path/to/cerefox/.env.
+
+  [c] Copy to /Users/you/.cerefox/.env  (recommended)
+      • TS reads the new home from now on
+      • Python keeps reading /path/to/cerefox/.env (backward compat)
+      • Edit ~/.cerefox/.env going forward; the repo .env is legacy
+
+  [u] Use /path/to/cerefox/.env as-is, skip writing anything
+      • Both TS and Python keep reading the existing file
+      • Defer the migration
+
+  [f] Fresh start — interactive prompts, write to /Users/you/.cerefox/.env
+      • Use if the existing file is stale or wrong
+```
+
+Pick **[c]** for the typical Python → TS upgrade. The TS CLI starts
+reading `~/.cerefox/.env`; your remaining Python `uv run cerefox …`
+commands keep reading the unchanged repo file. The two files diverge
+only if you start editing one of them — keep them in sync (or just edit
+`~/.cerefox/.env` and accept that Python uses a frozen snapshot until
+v0.9).
+
+After v0.9 (Python CLI removed), `cerefox doctor` will say "ok" if you
+delete the repo file. Until then, `doctor` reports it as
+`legacy env … (shadowed by ~/.cerefox/.env)` so you know it's harmless.
+
+### Python paths.py precedence (unchanged)
+
+`src/cerefox/paths.py` keeps the v0.5.2 precedence (CWD `.env` wins).
+Your existing `uv run cerefox …` invocations from inside the repo
+continue to read the repo file regardless of what's in `~/.cerefox/`.
+When this module goes away in v0.9+, the divergence resolves naturally.
+
+### `CEREFOX_CONFIG_DIR` is unchanged
+
+If you have `CEREFOX_CONFIG_DIR` set (e.g. for a non-standard install),
+it still wins over both home and repo `.env` files. Init writes there
+and skips the migration prompt.
+
+---
+
 ## Known gotchas
 
 ### `npx` from inside an npm workspace

package/docs/guides/upgrading.md

@@ -1,8 +1,27 @@
 # Upgrading Cerefox
 
-This guide covers upgrading an existing Cerefox installation to the latest version. All steps are idempotent and safe to re-run.
+This guide covers upgrading an existing Cerefox installation. All steps are idempotent and safe to re-run.
 
-## Standard Upgrade Checklist
+## Pick your path
+
+Cerefox has two install paths since v0.4.0 (npm) and v0.5.0 (TS CLI). The right
+upgrade procedure depends on how you installed Cerefox:
+
+| You installed via | Upgrade with |
+|---|---|
+| **npm / Bun** (`@cerefox/memory` global) | `bun update -g @cerefox/memory` (or `npm update -g @cerefox/memory`), then read [`migration-v0.5.md`](migration-v0.5.md) for any breaking-change notes per version. **`cerefox doctor`** verifies the install. |
+| **Source checkout** (`git clone` + `uv sync`) | The "Standard Upgrade Checklist" below — Python deps, schema migrations, Edge Functions, frontend build, the works. |
+| **Both** (you contribute AND have the npm bin globally) | Both flows. The two paths share the same Supabase + `.env`; just keep them updated in lockstep. |
+
+> If you're upgrading from Python `cerefox` to the npm-installed TS CLI for the first
+> time, [`migration-v0.5.md`](migration-v0.5.md) is the canonical guide — it covers
+> `cerefox init`'s coexistence flow (`[c]opy` your existing `.env` to `~/.cerefox/.env`),
+> the v0.5.2 soft-wrapper removal, and the v0.5.3 paths precedence change.
+
+The rest of this document covers the **source checkout** path (Python + frontend + Edge
+Functions). If you're an npm-installed user, you've already got everything you need.
+
+## Standard Upgrade Checklist (source-checkout users)
 
 Run these steps every time you pull a new version:
 
@@ -61,6 +80,30 @@ open http://localhost:8000/app/
 
 Most upgrades require no special steps beyond the standard checklist above. Notes below only apply when upgrading across specific version boundaries.
 
+### Upgrading to v0.5.x (from any v0.4.x or earlier)
+
+The v0.4 → v0.5 transition is a milestone — the CLI itself moved from Python
+to TypeScript. The full migration guide is [`migration-v0.5.md`](migration-v0.5.md);
+the short version for source-checkout users is:
+
+- The Python `cerefox` CLI **still works** through v0.7.x — `uv sync` is enough
+  to pull it. It prints a one-line ⚠ deprecation banner on every invocation.
+- The new npm CLI lives alongside: `bun install -g @cerefox/memory` (or
+  `npm install -g @cerefox/memory`). `cerefox doctor` from any directory will
+  verify it.
+- **v0.5.2** stripped the Python `cerefox mcp` soft-wrapper. If your MCP
+  client config uses `uv run --directory /path/to/cerefox cerefox mcp`,
+  nothing changes — that path runs the Python MCP server directly. If you
+  want the TS server instead, point your client at `cerefox mcp`
+  (npm-installed) or `npx -y --package=@cerefox/memory cerefox mcp`.
+- **v0.5.3** changed the TS CLI's `.env` precedence: `~/.cerefox/.env` now
+  wins over `<repo>/.env` when both exist. Your existing `<repo>/.env` keeps
+  working until you run `cerefox init` and pick the `[c]opy` migration
+  option. Python `paths.py` is unchanged.
+
+No schema migration, no Edge Function redeploy, no chunk reindex required
+for the v0.4 → v0.5.3 arc.
+
 ### Upgrading to v0.1.20 (from v0.1.19) -- Multi-Project Preservation Fix
 
 **Edge Function redeploy is required.** v0.1.20 fixes

package/package.json

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