@cerefox/memory 0.5.2 → 0.5.4

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.4";
 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"));
 }
@@ -24728,7 +24737,7 @@ __export(exports_sync_self_docs, {
   runSyncSelfDocs: () => runSyncSelfDocs,
   registerSyncSelfDocs: () => registerSyncSelfDocs
 });
-import { readFileSync as readFileSync6 } from "node:fs";
+import { readFileSync as readFileSync7 } from "node:fs";
 import { basename as basename3, extname as extname3 } from "node:path";
 async function runSyncSelfDocs(options = {}) {
   const project = options.project ?? "_cerefox-self-docs";
@@ -24755,7 +24764,7 @@ async function runSyncSelfDocs(options = {}) {
   const authorType = resolveAuthorType("agent");
   const outcomes = [];
   for (const doc of docs) {
-    const content = readFileSync6(doc.path, "utf8");
+    const content = readFileSync7(doc.path, "utf8");
     const m = content.match(/^#\s+(.+)$/m);
     const title = m ? m[1].trim() : basename3(doc.path, extname3(doc.path));
     try {
@@ -38135,17 +38144,24 @@ function registerConfigSet(program2) {
 init_cli_core();
 
 // src/cli/util/mcp-config-writers.ts
-import { copyFileSync, existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import {
+  copyFileSync,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  writeFileSync as writeFileSync2
+} from "node:fs";
 import { homedir as homedir3, platform } from "node:os";
 import { dirname, join as join3 } from "node:path";
+import { spawnSync } from "node:child_process";
 function defaultCerefoxEntry() {
   return {
     command: "npx",
     args: ["-y", "--package=@cerefox/memory", "cerefox", "mcp"]
   };
 }
-function claudeCodeConfigPath() {
-  return join3(homedir3(), ".claude", "mcp.json");
+function claudeCodeUserConfigPath() {
+  return join3(homedir3(), ".claude.json");
 }
 function claudeDesktopConfigPath() {
   const home = homedir3();
@@ -38157,22 +38173,40 @@ function claudeDesktopConfigPath() {
   }
   return join3(home, ".config", "Claude", "claude_desktop_config.json");
 }
+function claudeCodeDelegated() {
+  const entry = defaultCerefoxEntry();
+  return {
+    cmd: "claude",
+    args: ["mcp", "add", "cerefox", "--scope", "user", "--", entry.command, ...entry.args]
+  };
+}
 var WRITERS = {
   "claude-code": {
     id: "claude-code",
     label: "Claude Code",
-    configPath: claudeCodeConfigPath(),
-    buildServerEntry: defaultCerefoxEntry
+    kind: "delegated",
+    configPath: claudeCodeUserConfigPath(),
+    buildServerEntry: defaultCerefoxEntry,
+    delegated: claudeCodeDelegated
   },
   "claude-desktop": {
     id: "claude-desktop",
     label: "Claude Desktop",
+    kind: "direct-write",
     configPath: claudeDesktopConfigPath(),
     buildServerEntry: defaultCerefoxEntry
   }
 };
 function writeMcpConfig(writer, opts = {}) {
-  const configPath = opts.customPath ?? writer.configPath;
+  if (opts.customPath) {
+    return directWrite({ ...writer, kind: "direct-write" }, opts.customPath, opts);
+  }
+  if (writer.kind === "delegated") {
+    return delegatedWrite(writer, opts);
+  }
+  return directWrite(writer, writer.configPath, opts);
+}
+function directWrite(writer, configPath, opts) {
   const entry = writer.buildServerEntry();
   if (!opts.dryRun)
     mkdirSync2(dirname(configPath), { recursive: true });
@@ -38200,6 +38234,46 @@ function writeMcpConfig(writer, opts = {}) {
   }
   return { configPath, backupPath, action: action5, serverEntry: entry };
 }
+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 delegatedCommand = `${cmd} ${args.join(" ")}`;
+  if (opts.dryRun) {
+    return {
+      configPath: writer.configPath,
+      backupPath: null,
+      action: "delegated",
+      serverEntry: entry,
+      delegatedCommand
+    };
+  }
+  let backupPath = null;
+  if (!opts.noBackup && existsSync3(writer.configPath)) {
+    backupPath = writer.configPath + ".pre-cerefox.bak";
+    copyFileSync(writer.configPath, backupPath);
+  }
+  const result = spawnSync(cmd, args, { stdio: "inherit" });
+  if (result.error) {
+    const err = result.error;
+    if (err.code === "ENOENT") {
+      throw new Error(`${writer.label}: \`${cmd}\` not found on PATH. ` + `Install ${writer.label} (https://docs.claude.com/en/docs/claude-code) ` + `and re-run \`cerefox configure-agent --tool ${writer.id}\`.`);
+    }
+    throw new Error(`${writer.label}: failed to spawn \`${cmd}\`: ${err.message}`);
+  }
+  if (result.status !== 0) {
+    throw new Error(`${writer.label}: \`${delegatedCommand}\` exited with status ${result.status ?? "unknown"}. ` + `Check the output above; you may need to update or re-authenticate ${writer.label}.`);
+  }
+  return {
+    configPath: writer.configPath,
+    backupPath,
+    action: "delegated",
+    serverEntry: entry,
+    delegatedCommand
+  };
+}
 
 // src/cli/commands/configure-agent.ts
 function action5(options) {
@@ -38226,12 +38300,15 @@ function action5(options) {
     println(c.dim(`  backup: ${result.backupPath}`));
   }
   println(c.dim(`  action: ${result.action}`));
+  if (result.delegatedCommand) {
+    println(c.dim(`  invoked: ${result.delegatedCommand}`));
+  }
   println("");
   println(c.bold("Server entry written:"));
   println(JSON.stringify(result.serverEntry, null, 2));
   if (!options.dryRun) {
     println("");
-    println(c.dim(writer.id === "claude-desktop" ? "Restart Claude Desktop fully (Cmd+Q on macOS) to pick up the new server." : "Reload your Claude Code session to pick up the new server."));
+    println(c.dim(writer.id === "claude-desktop" ? "Restart Claude Desktop fully (Cmd+Q on macOS) to pick up the new server." : "Start a new Claude Code session to pick up the new server " + "(running sessions cache MCP server lists at startup)."));
   }
 }
 function registerConfigureAgent(program2) {
@@ -38286,10 +38363,10 @@ function registerDeleteDoc(program2) {
 // src/cli/commands/docs.ts
 init_cli_core();
 init_bundled_docs();
-import { spawnSync } from "node:child_process";
+import { spawnSync as spawnSync2 } from "node:child_process";
 function openInBrowser(path) {
   const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  const result = spawnSync(cmd, [path], { stdio: "ignore" });
+  const result = spawnSync2(cmd, [path], { stdio: "ignore" });
   if (result.status !== 0) {
     println(c.dim(`(could not auto-open; the file is at: ${path})`));
   }
@@ -38333,7 +38410,7 @@ init_cli_core();
 init_meta();
 init_config();
 init_config();
-import { existsSync as existsSync5, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync4, realpathSync, statSync as statSync2 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { join as join5 } from "node:path";
 function checkBinary() {
@@ -38552,29 +38629,58 @@ async function checkSchemaVersion() {
     };
   }
 }
+function hasCerefoxInJsonFile(path) {
+  if (!existsSync5(path))
+    return false;
+  try {
+    const parsed = JSON.parse(readFileSync4(path, "utf8"));
+    const mcpServers = parsed.mcpServers;
+    return Boolean(mcpServers && typeof mcpServers === "object" && "cerefox" in mcpServers);
+  } catch {
+    return false;
+  }
+}
 function checkMcpConfigs() {
   const home = homedir4();
-  const candidates = [
-    { label: "Claude Code (user)", path: join5(home, ".claude", "mcp.json") },
-    { label: "Claude Code (proj)", path: join5(process.cwd(), ".mcp.json") },
-    {
-      label: "Claude Desktop",
-      path: process.platform === "darwin" ? join5(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : process.platform === "win32" ? join5(process.env.APPDATA ?? "", "Claude", "claude_desktop_config.json") : join5(home, ".config", "Claude", "claude_desktop_config.json")
-    }
-  ];
-  const found = candidates.filter((c2) => existsSync5(c2.path));
+  const claudeCodeUser = join5(home, ".claude.json");
+  const claudeCodeProj = join5(process.cwd(), ".mcp.json");
+  const claudeDesktop = process.platform === "darwin" ? join5(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : process.platform === "win32" ? join5(process.env.APPDATA ?? "", "Claude", "claude_desktop_config.json") : join5(home, ".config", "Claude", "claude_desktop_config.json");
+  const found = [];
+  if (hasCerefoxInJsonFile(claudeCodeUser))
+    found.push("Claude Code (user)");
+  if (hasCerefoxInJsonFile(claudeCodeProj))
+    found.push("Claude Code (proj)");
+  if (hasCerefoxInJsonFile(claudeDesktop))
+    found.push("Claude Desktop");
   if (found.length === 0) {
     return {
       name: "mcp clients",
       status: "warn",
-      detail: "No MCP client configs detected.",
-      hint: "Run `cerefox configure-agent --tool claude-code` to wire up Claude Code."
+      detail: "No MCP client configs reference Cerefox.",
+      hint: "Run `cerefox configure-agent --tool claude-code` (or `--tool claude-desktop`) to wire up a client."
     };
   }
   return {
     name: "mcp clients",
     status: "ok",
-    detail: found.map((f) => f.label).join(", ")
+    detail: found.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() {
@@ -38593,11 +38699,13 @@ function checkPostgres() {
   };
 }
 async function runAllChecks() {
+  const legacy = checkLegacyShadowEnv();
   return [
     checkBinary(),
     checkRuntime(),
     checkVersion(),
     checkConfig(),
+    ...legacy ? [legacy] : [],
     await checkSupabase(),
     await checkOpenAI(),
     await checkSchemaVersion(),
@@ -38738,7 +38846,7 @@ init_cli_core();
 init_mcp_tools();
 init_config();
 init_client();
-import { readFileSync as readFileSync4 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 import { basename, extname } from "node:path";
 async function readContent(path, paste) {
   if (paste) {
@@ -38760,7 +38868,7 @@ async function readContent(path, paste) {
   }
   let content;
   try {
-    content = readFileSync4(path, "utf8");
+    content = readFileSync5(path, "utf8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw userError(`Cannot read ${path}: ${msg}`);
@@ -38825,7 +38933,7 @@ init_mcp_tools();
 init_config();
 init_client();
 var import_cli_progress = __toESM(require_cli_progress(), 1);
-import { readFileSync as readFileSync5, readdirSync as readdirSync2, statSync as statSync3 } from "node:fs";
+import { readFileSync as readFileSync6, readdirSync as readdirSync2, statSync as statSync3 } from "node:fs";
 import { basename as basename2, extname as extname2, join as join6 } from "node:path";
 function walk(dir, extensions) {
   let entries;
@@ -38881,7 +38989,7 @@ async function action12(dir, options) {
     bar?.update({ file: basename2(file) });
     let content;
     try {
-      content = readFileSync5(file, "utf8");
+      content = readFileSync6(file, "utf8");
     } catch (err) {
       outcomes.push({ file, status: "error", detail: `read failed: ${err instanceof Error ? err.message : String(err)}` });
       bar?.increment();
@@ -38938,19 +39046,21 @@ init_cli_core();
 init_config();
 import {
   chmodSync,
+  copyFileSync as copyFileSync2,
   existsSync as existsSync6,
   mkdirSync as mkdirSync3,
-  readFileSync as readFileSync7,
+  readFileSync as readFileSync8,
   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}`);
   }
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync7(path, "utf8"));
+    parsed = JSON.parse(readFileSync8(path, "utf8"));
   } catch (err) {
     throw userError(`--config: invalid JSON in ${path}: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -38973,6 +39083,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(readFileSync8(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 +39232,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.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.green(`✓ Wrote ${envPath}`));
+  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 +39307,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);
@@ -39435,14 +39704,14 @@ function registerReindex(program2) {
 // src/cli/commands/restore.ts
 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 { existsSync as existsSync7, readFileSync as readFileSync9, readdirSync as readdirSync3, statSync as statSync4 } from "node:fs";
+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,17 +39722,17 @@ 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);
   let payload;
   try {
-    payload = JSON.parse(readFileSync8(file, "utf8"));
+    payload = JSON.parse(readFileSync9(file, "utf8"));
   } catch (err) {
     throw userError(`Could not parse backup file ${file}: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -39680,7 +39949,7 @@ function registerSearch(program2) {
 // src/cli/commands/self-update.ts
 init_cli_core();
 init_meta();
-import { spawnSync as spawnSync2 } from "node:child_process";
+import { spawnSync as spawnSync3 } from "node:child_process";
 function detectRuntime() {
   const bin = (process.argv[1] ?? "").toLowerCase();
   if (bin.includes(".bun") || bin.includes("/bun/")) {
@@ -39753,7 +40022,7 @@ async function action22(options) {
       return;
     }
   }
-  const result = spawnSync2(runtime.command, runtime.args(target), {
+  const result = spawnSync3(runtime.command, runtime.args(target), {
     stdio: "inherit"
   });
   if (result.status !== 0) {
@@ -39820,18 +40089,18 @@ init_config();
 init_client();
 import {
   existsSync as existsSync8,
-  readFileSync as readFileSync9,
+  readFileSync as readFileSync10,
   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 +40120,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) {
@@ -39879,7 +40148,7 @@ async function action24(options) {
   const authorType = resolveAuthorType("agent");
   const outcomes = [];
   for (const t of targets) {
-    const content = readFileSync9(t.abs, "utf8");
+    const content = readFileSync10(t.abs, "utf8");
     const title = basename4(t.abs, extname4(t.abs));
     try {
       const message = await ingestTool.handler(client.raw, {

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,23 @@
-# 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`" + "v0.5.4 fixed configure-agent claude-code" |
+| `@cerefox/memory` v0.5.2 (npm) | "v0.5.3 migrated `.env`" + "v0.5.4 fixed configure-agent claude-code" |
+| `@cerefox/memory` v0.5.3 (npm) | **"v0.5.4 fixed configure-agent claude-code"** — re-run configure-agent |
+
+> 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 +215,122 @@ 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.
+
+---
+
+## v0.5.4 fixed `cerefox configure-agent --tool claude-code`
+
+**If you ran `cerefox configure-agent --tool claude-code` on any version
+from v0.5.0 through v0.5.3, Claude Code did not actually pick up the
+config.** The writer wrote to `~/.claude/mcp.json` — a path Claude Code
+doesn't read. Claude Code's user-scope MCP servers live in
+**`~/.claude.json`** (a dot-file in `$HOME`) under the `.mcpServers` key.
+
+The bug went unnoticed because `cerefox doctor` was scanning the same
+wrong path — both surfaces were consistently lying.
+
+### What v0.5.4 changed
+
+- **`configure-agent --tool claude-code`** now shells out to Claude Code's
+  own `claude mcp add --scope user` CLI. Claude Code manages its own
+  config schema; delegating is future-proof. Requires the `claude` CLI
+  on PATH (fair assumption — you're configuring it).
+- Before invoking the delegated CLI, the writer takes a defensive backup
+  of `~/.claude.json` to `~/.claude.json.pre-cerefox.bak`.
+- **`cerefox doctor`** now scans `~/.claude.json` for a `mcpServers.cerefox`
+  entry (not the orphaned `~/.claude/mcp.json` from the bug window).
+- **`--tool claude-desktop` is unchanged** — Claude Desktop has no CLI
+  helper, so its writer remains direct-file-write.
+
+### What you need to do
+
+Anyone who ran `configure-agent --tool claude-code` on v0.5.0–v0.5.3:
+
+```bash
+# 1. Upgrade
+bun update -g @cerefox/memory      # or: npm update -g @cerefox/memory
+
+# 2. (Optional) Remove the orphaned file the buggy versions wrote.
+#    It does nothing — Claude Code never read it. Safe to delete.
+rm -f ~/.claude/mcp.json
+
+# 3. Re-run configure-agent to write the config at the correct path.
+cerefox configure-agent --tool claude-code
+
+# 4. Verify
+claude mcp list                    # should now show 'cerefox'
+cerefox doctor                     # 'mcp clients' should list 'Claude Code (user)'
+
+# 5. Start a fresh Claude Code session — the cerefox tools appear.
+```
+
+Running sessions cache the MCP server list at startup, so an
+**already-open Claude Code session won't pick up the new server**.
+Open a new session.
+
+### `--config-path FILE` override (advanced)
+
+If you pass `--config-path FILE` explicitly, configure-agent does a
+direct-write to FILE instead of shelling out — preserves the v0.5.0–v0.5.3
+test path and works for power users who want a specific file location.
+
+---
+
 ## Known gotchas
 
 ### `npx` from inside an npm workspace

package/docs/guides/quickstart.md

@@ -4,9 +4,70 @@ Get Cerefox running locally and ingest your first document.
 
 > **Upgrading from a previous version?** See the [Upgrading Guide](upgrading.md) for migration steps instead.
 
+## Two install paths
+
+| You want | Read this section | Why |
+|---|---|---|
+| **Use Cerefox as an MCP server / CLI** | "Path A — npm install" below (fastest) | One install, callable from any directory. No Python needed. Recommended for end users since v0.5. |
+| **Contribute to Cerefox, run the web UI, deploy schema** | "Path B — source checkout" below | Full source: schema deploy, web UI, ingestion pipeline. Required for contributors and for the web UI (until v0.6). |
+
+You'll need a Supabase project (free tier works) and an OpenAI API key for either
+path — those go into `.env`. The npm install asks for them interactively via
+`cerefox init`; the source checkout has you write them into a `.env` file
+yourself.
+
+---
+
+## Path A — npm install (fastest, 5 min total)
+
+For end users who just want the Cerefox CLI + MCP server on their machine.
+
+### A.1 Prerequisites
+- Node.js 20+ (`node --version`) or Bun 1.0+ (`bun --version`)
+- A Supabase account -- [supabase.com](https://supabase.com) (free tier works)
+- An OpenAI API key -- [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
+- **Schema must be deployed** to your Supabase. Until v0.6 ports the schema
+  deploy to TypeScript, this still requires the source checkout (Path B) once,
+  or someone else who has the source checkout to deploy it for you.
+
+### A.2 Install
+```bash
+# One-line install (detects Bun or installs it, falls back to npm):
+curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install.sh | sh
+
+# Or direct:
+bun add -g @cerefox/memory       # preferred
+# npm install -g @cerefox/memory # alternative
+```
+
+### A.3 First-run setup
+```bash
+cerefox init        # 5-step interactive setup
+cerefox doctor      # verify the install
+```
+
+### A.4 Wire up your MCP client
+```bash
+# Run the ones that apply:
+cerefox configure-agent --tool claude-code
+cerefox configure-agent --tool claude-desktop
+```
+
+`--tool claude-code` shells out to Claude Code's own `claude mcp add --scope user`
+to register the server (Claude Code knows where to store the config).
+`--tool claude-desktop` writes the JSON config file directly.
+
+Then restart your MCP client. **Path A users skip ahead to "[Connect an AI agent](#8-connect-an-ai-agent-optional-5-min)" (step 8) for the verification prompt.** Steps 3–7
+below are Path B-only (setting up `.env` by hand, deploying the schema, the web UI).
+
 ---
 
-## 1. Prerequisites (2 min)
+## Path B — source checkout (contributors, schema deploy, web UI)
+
+For anyone hacking on Cerefox itself, deploying the schema for the first time,
+or running the web UI.
+
+### B.1 Prerequisites
 
 - Python 3.11+ (`python3 --version`)
 - Node.js 18+ and npm (`node --version`)
@@ -14,9 +75,7 @@ Get Cerefox running locally and ingest your first document.
 - A Supabase account -- [supabase.com](https://supabase.com) (free tier works)
 - An OpenAI API key -- [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
 
----
-
-## 2. Install Cerefox (2 min)
+### B.2 Install Cerefox (2 min)
 
 ```bash
 git clone https://github.com/fstamatelopoulos/cerefox.git

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.4",
   "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",