@cerefox/memory 0.5.3 → 0.5.4

package/dist/bin/cerefox.js

@@ -7179,7 +7179,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "0.5.3";
+var PKG_VERSION = "0.5.4";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js
@@ -24737,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";
@@ -24764,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 {
@@ -38144,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();
@@ -38166,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 });
@@ -38209,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) {
@@ -38235,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) {
@@ -38295,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})`));
   }
@@ -38342,7 +38410,7 @@ init_cli_core();
 init_meta();
 init_config();
 init_config();
-import { existsSync as existsSync5, realpathSync, 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() {
@@ -38561,29 +38629,41 @@ 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() {
@@ -38766,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) {
@@ -38788,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}`);
@@ -38853,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;
@@ -38909,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();
@@ -38969,7 +39049,7 @@ import {
   copyFileSync as copyFileSync2,
   existsSync as existsSync6,
   mkdirSync as mkdirSync3,
-  readFileSync as readFileSync7,
+  readFileSync as readFileSync8,
   writeFileSync as writeFileSync3
 } from "node:fs";
 import { homedir as homedir5 } from "node:os";
@@ -38980,7 +39060,7 @@ async function readConfigFile(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)}`);
   }
@@ -39022,7 +39102,7 @@ function parseDotEnvFile(content) {
   return map;
 }
 function answersFromEnvFile(path) {
-  const parsed = parseDotEnvFile(readFileSync7(path, "utf8"));
+  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() === "") {
@@ -39624,7 +39704,7 @@ 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 { 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) {
@@ -39652,7 +39732,7 @@ 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)}`);
   }
@@ -39869,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/")) {
@@ -39942,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) {
@@ -40009,7 +40089,7 @@ init_config();
 init_client();
 import {
   existsSync as existsSync8,
-  readFileSync as readFileSync9,
+  readFileSync as readFileSync10,
   readdirSync as readdirSync4,
   statSync as statSync5
 } from "node:fs";
@@ -40068,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/migration-v0.5.md

@@ -11,8 +11,9 @@ v0.5.3), and the Python `cerefox` → TS `cerefox` migration path.
 | 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 |
+| `@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
@@ -272,6 +273,64 @@ 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/package.json

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