@cachly-dev/mcp-server 0.10.4 → 0.10.6

package/src/index.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { jwtExpiryMs, checkJwt, handleApiError } from './auth.js';
 import { readFile } from 'node:fs/promises';
 import { execSync } from 'node:child_process';
 import { join } from 'node:path';
@@ -52,19 +53,22 @@ import { Redis } from 'ioredis';
 const API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
 let JWT = process.env.CACHLY_JWT ?? '';
 const EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.9.17';
+const CURRENT_VERSION = '0.10.0';
 
 // ── Default Instance Resolution (for Smithery & single-credential setups) ────
 // When CACHLY_BRAIN_INSTANCE_ID is set, tools can omit the instance_id parameter.
 // When neither is set, we auto-fetch the first running instance once per process.
 let _defaultInstanceId: string = process.env.CACHLY_BRAIN_INSTANCE_ID ?? '';
-let _defaultInstanceFetched = false;
+// Timestamp of last failed fetch — retries after 30 s (not permanently blocked).
+let _defaultInstanceLastAttempt = 0;
 
 async function resolveDefaultInstanceId(): Promise<string> {
   if (_defaultInstanceId) return _defaultInstanceId;
-  if (_defaultInstanceFetched) return '';
-  _defaultInstanceFetched = true;
   if (!JWT) return '';
+  // Cooldown: don't hammer the API on every tool call after a transient failure.
+  const now = Date.now();
+  if (_defaultInstanceLastAttempt > 0 && now - _defaultInstanceLastAttempt < 30_000) return '';
+  _defaultInstanceLastAttempt = now;
   try {
     const res = await fetch(`${API_URL}/api/v1/instances`, {
       headers: { Authorization: `Bearer ${JWT}`, Accept: 'application/json' },
@@ -72,9 +76,15 @@ async function resolveDefaultInstanceId(): Promise<string> {
     });
     if (!res.ok) return '';
     const data = await res.json() as { data?: Array<{ id: string; status: string }> };
-    const running = (data?.data ?? []).filter(i => i.status === 'running');
-    if (running.length > 0) { _defaultInstanceId = running[0].id; return _defaultInstanceId; }
-  } catch { /* non-fatal — caller will surface missing instance_id error */ }
+    const instances = (data?.data ?? []) as Array<{ id: string; status: string }>;
+    // Prefer running, fall back to provisioning so the ID is resolved even during startup.
+    const best = instances.find(i => i.status === 'running') ?? instances.find(i => i.status === 'provisioning');
+    if (best) {
+      _defaultInstanceId = best.id;
+      _defaultInstanceLastAttempt = 0;
+      return _defaultInstanceId;
+    }
+  } catch { /* transient error — will retry after cooldown */ }
   return '';
 }
 
@@ -149,24 +159,55 @@ async function pollDeviceFlow(flow: DeviceFlowState): Promise<'pending' | 'expir
       JWT = apiKey;
       setEmbedJwt(apiKey); // keep embeddings.ts in sync
       _deviceFlow = null;
-      // Auto-provision instance
-      _defaultInstanceFetched = false;
+      // Auto-provision: find or create the user's brain instance.
+      _defaultInstanceLastAttempt = 0;
       await resolveDefaultInstanceId();
       if (!_defaultInstanceId) {
-        // Try auto-provision
         try {
           const autoRes = await fetch(`${API_URL}/api/v1/instances/auto`, {
             method: 'POST',
             headers: { Authorization: `Bearer ${JWT}`, 'Content-Type': 'application/json' },
-            signal: AbortSignal.timeout(10000),
+            signal: AbortSignal.timeout(12000),
           });
           if (autoRes.ok) {
-            const body = await autoRes.json() as { instance?: { id: string }; instance_id?: string };
+            const body = await autoRes.json() as {
+              instance?: { id: string; status?: string };
+              instance_id?: string;
+              status?: string;
+            };
             const id = body.instance?.id ?? body.instance_id;
             if (id) _defaultInstanceId = id;
           }
         } catch { /* non-fatal */ }
       }
+      // Give a provisioning instance a head-start so getConnection's wait is shorter.
+      // The instance is almost always ready by the time the user's tool re-enters.
+      if (_defaultInstanceId) {
+        try {
+          const checkRes = await fetch(`${API_URL}/api/v1/instances/${_defaultInstanceId}`, {
+            headers: { Authorization: `Bearer ${JWT}`, Accept: 'application/json' },
+            signal: AbortSignal.timeout(4000),
+          });
+          if (checkRes.ok) {
+            const checkInst = await checkRes.json() as { status?: string };
+            if (checkInst.status === 'provisioning') {
+              // Wait up to 20s here so the re-entered tool call lands on a running instance.
+              const pDeadline = Date.now() + 20_000;
+              while (checkInst.status === 'provisioning' && Date.now() < pDeadline) {
+                await new Promise(r => setTimeout(r, 3000));
+                const rr = await fetch(`${API_URL}/api/v1/instances/${_defaultInstanceId}`, {
+                  headers: { Authorization: `Bearer ${JWT}`, Accept: 'application/json' },
+                  signal: AbortSignal.timeout(4000),
+                }).catch(() => null);
+                if (rr?.ok) {
+                  const ri = await rr.json() as { status?: string };
+                  (checkInst as { status?: string }).status = ri.status;
+                } else { break; }
+              }
+            }
+          }
+        } catch { /* non-fatal — getConnection will handle the wait if still provisioning */ }
+      }
       return 'done';
     }
     if (data.error === 'slow_down') flow.pollInterval = Math.min(flow.pollInterval + 2000, 15000);
@@ -216,18 +257,48 @@ interface SemanticSearchResponse {
 const pool = new Map<string, Redis>();
 
 async function getConnection(instance_id: string): Promise<Redis> {
-  if (pool.has(instance_id)) return pool.get(instance_id)!;
-
-  const inst = await apiFetch<Instance>(`/api/v1/instances/${instance_id}`);
-  if (inst.status !== 'running') {
+  if (!instance_id) {
     throw new McpError(
       ErrorCode.InvalidRequest,
-      `Instance "${inst.name}" is not running (status: ${inst.status}). ` +
-        `It may still be provisioning or awaiting payment.`
+      'No instance_id provided and no running instance could be resolved automatically.\n\n' +
+      '• Set CACHLY_BRAIN_INSTANCE_ID in your MCP config, or\n' +
+      '• Pass instance_id explicitly to the tool, or\n' +
+      '• Run `list_instances` to see your available instances.'
     );
   }
+
+  if (pool.has(instance_id)) return pool.get(instance_id)!;
+
+  // Fetch instance, waiting up to 25 s if it is still provisioning.
+  // This covers the zero-friction path: device-flow auth → auto-provision → first tool call
+  // all happen in quick succession and the instance isn't running yet.
+  let inst = await apiFetch<Instance>(`/api/v1/instances/${instance_id}`);
+  if (inst.status === 'provisioning') {
+    const deadline = Date.now() + 25_000;
+    while (inst.status === 'provisioning' && Date.now() < deadline) {
+      await new Promise(r => setTimeout(r, 3000));
+      inst = await apiFetch<Instance>(`/api/v1/instances/${instance_id}`);
+    }
+  }
+
+  if (inst.status !== 'running') {
+    // Telemetry: unreachable instance so the team can proactively investigate
+    void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...(JWT ? { Authorization: `Bearer ${JWT}` } : {}) },
+      body: JSON.stringify({ event: 'instance_not_reachable', instance_id, status: inst.status, version: CURRENT_VERSION }),
+      signal: AbortSignal.timeout(3000),
+    }).catch(() => {});
+    const hint = inst.status === 'provisioning'
+      ? `⏳ Brain instance "${inst.name}" is still starting up.\n\nThis usually finishes within 30 seconds. Please try again in a moment.`
+      : `Brain instance "${inst.name}" is not reachable (status: ${inst.status}).\n\n` +
+        `• View your instance at: https://cachly.dev/instances\n` +
+        `• Run \`get_api_status\` for a full diagnostic.`;
+    throw new McpError(ErrorCode.InvalidRequest, hint);
+  }
   if (!inst.host || !inst.port) {
-    throw new McpError(ErrorCode.InternalError, `Instance "${inst.name}" has no host/port yet.`);
+    throw new McpError(ErrorCode.InternalError,
+      `Instance "${inst.name}" is running but has no host/port — contact support@cachly.dev.`);
   }
 
   // Fetch connection details (includes password) from the dedicated endpoint.
@@ -240,7 +311,7 @@ async function getConnection(instance_id: string): Promise<Redis> {
     password = conn.password ?? undefined;
     tlsEnabled = conn.tls_enabled !== false;
   } catch {
-    // Fallback: no password, use TLS default from instance
+    // Fallback: use TLS flag from instance metadata
   }
 
   const client = new Redis({
@@ -248,26 +319,33 @@ async function getConnection(instance_id: string): Promise<Redis> {
     port: inst.port,
     password: password || undefined,
     ...(tlsEnabled ? { tls: {} } : {}),
-    lazyConnect: true,          // don't auto-connect — we connect explicitly below
+    lazyConnect: true,
     enableReadyCheck: true,
-    connectTimeout: 5000,
+    connectTimeout: 8000,
     retryStrategy: () => null,  // fail fast, no reconnect loops in MCP context
   });
 
-  client.on('error', () => {
-    pool.delete(instance_id); // remove stale connection on error
-  });
+  const evict = () => pool.delete(instance_id);
+  client.on('error', evict);
+  client.on('end', evict);
 
-  // Connect explicitly so we can catch connection errors as a proper rejected
-  // Promise instead of an unhandled 'error' event that would kill the process.
   try {
     await client.connect();
   } catch (err: unknown) {
     client.disconnect();
     const msg = err instanceof Error ? err.message : String(err);
+    void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...(JWT ? { Authorization: `Bearer ${JWT}` } : {}) },
+      body: JSON.stringify({ event: 'redis_connect_failed', instance_id, host: inst.host, port: inst.port, error: msg, version: CURRENT_VERSION }),
+      signal: AbortSignal.timeout(3000),
+    }).catch(() => {});
     throw new McpError(
       ErrorCode.InternalError,
-      `Could not connect to instance "${inst.name}" (${inst.host}:${inst.port}): ${msg}`
+      `Could not reach Brain instance "${inst.name}" (${inst.host}:${inst.port}).\n\n` +
+      `• Check your network connection\n` +
+      `• Run \`get_api_status\` to verify instance status\n` +
+      `• Technical detail: ${msg}`
     );
   }
 
@@ -277,33 +355,8 @@ async function getConnection(instance_id: string): Promise<Redis> {
 
 // ── API helper ────────────────────────────────────────────────────────────────
 
-function jwtExpiryMs(token: string): number | null {
-  try {
-    const parts = token.split('.');
-    if (parts.length !== 3) return null;
-    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8')) as { exp?: number };
-    return payload.exp ? payload.exp * 1000 : null;
-  } catch { return null; }
-}
-
 async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T> {
-  if (!JWT) {
-    throw new McpError(
-      ErrorCode.InvalidRequest,
-      'CACHLY_JWT env var not set.\n\nGet your token at https://cachly.dev/setup-ai and add it to your MCP config:\n  CACHLY_JWT=<your-token>'
-    );
-  }
-
-  // Detect token expiry before making the network call — gives a clearer error
-  const expMs = jwtExpiryMs(JWT);
-  if (expMs !== null && expMs < Date.now()) {
-    const expiredAt = new Date(expMs).toISOString();
-    throw new McpError(
-      ErrorCode.InvalidRequest,
-      `CACHLY_JWT expired at ${expiredAt}.\n\nGet a fresh token at https://cachly.dev/setup-ai and update CACHLY_JWT in your MCP config.`
-    );
-  }
-
+  checkJwt(JWT);
   const timeoutMs = Number(process.env.CACHLY_API_TIMEOUT_MS ?? 15_000);
   const res = await fetch(`${API_URL}${path}`, {
     ...options,
@@ -317,22 +370,7 @@ async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T>
   if (!res.ok) {
     const body = await res.json().catch(() => ({ error: res.statusText }));
     const detail = (body as { error?: string }).error ?? res.statusText;
-    if (res.status === 401) {
-      throw new McpError(
-        ErrorCode.InvalidRequest,
-        `Authentication failed (401): ${detail}\n\nYour CACHLY_JWT may be expired or invalid. Get a fresh token at https://cachly.dev/setup-ai`
-      );
-    }
-    if (res.status === 403) {
-      throw new McpError(
-        ErrorCode.InvalidRequest,
-        `Access denied (403): ${detail}\n\nCheck that your CACHLY_JWT belongs to an account with access to this resource.`
-      );
-    }
-    throw new McpError(
-      ErrorCode.InternalError,
-      `cachly API error ${res.status}: ${detail}`
-    );
+    handleApiError(res.status, detail);
   }
   if (res.status === 204) return undefined as T;
   return res.json() as Promise<T>;
@@ -360,47 +398,6 @@ import { TOOLS } from './tools.js';
 
 // ── Handlers ──────────────────────────────────────────────────────────────────
 
-// ── Tool-call analytics (opt-out: CACHLY_NO_TELEMETRY=1) ────────────────────
-// In-memory counters — exposed via /stats on HTTP mode
-const _toolCallCounts: Record<string, number> = {};
-let _toolCallTotal = 0;
-let _toolCallAuthedTotal = 0;
-
-async function trackToolCall(toolName: string, authed: boolean, durationMs: number): Promise<void> {
-  if (process.env.CACHLY_NO_TELEMETRY === '1') return;
-  // Increment in-memory counters
-  _toolCallTotal++;
-  if (authed) _toolCallAuthedTotal++;
-  _toolCallCounts[toolName] = (_toolCallCounts[toolName] ?? 0) + 1;
-  // Structured JSON to stdout — searchable via: docker logs cachly-mcp-http-1 | jq
-  process.stdout.write(JSON.stringify({
-    ts: new Date().toISOString(),
-    event: 'tool_call',
-    tool: toolName,
-    authed,
-    ms: durationMs,
-    v: CURRENT_VERSION,
-  }) + '\n');
-  // Plausible custom event (fire-and-forget, never blocks user)
-  try {
-    await fetch('https://analytics.cachly.dev/api/event', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'User-Agent': `cachly-mcp/${CURRENT_VERSION}`,
-        'X-Forwarded-For': '127.0.0.1',
-      },
-      body: JSON.stringify({
-        domain: 'mcp.cachly.dev',
-        name: 'tool_call',
-        url: `https://mcp.cachly.dev/mcp/${toolName}`,
-        props: { tool: toolName, authed: String(authed) },
-      }),
-      signal: AbortSignal.timeout(3000),
-    });
-  } catch { /* fire-and-forget */ }
-}
-
 // Fires once per process when no JWT is set (anonymous, opt-out via CACHLY_NO_TELEMETRY=1)
 let _telemetryPingSent = false;
 async function sendAnonymousTelemetry(toolName: string): Promise<void> {
@@ -424,61 +421,6 @@ async function sendAnonymousTelemetry(toolName: string): Promise<void> {
 }
 
 async function handleTool(name: string, args: Record<string, unknown>): Promise<string> {
-  // ── sign_in: explicit device-flow trigger — works even without JWT ────────
-  if (name === 'sign_in') {
-    if (JWT) {
-      return '✅ **Already signed in.** Your cachly AI Brain is ready — all 63 tools available.';
-    }
-    // Poll if flow already in progress
-    if (_deviceFlow) {
-      const result = await pollDeviceFlow(_deviceFlow);
-      if (result === 'done') {
-        return [
-          '✅ **Sign-in complete!** Your cachly AI Brain is ready.',
-          '',
-          'All 63 brain tools are now available. Start with `session_start` to load context from your last session.',
-        ].join('\n');
-      }
-      if (result === 'expired') {
-        _deviceFlow = null;
-        // fall through to start a new flow
-      } else {
-        return [
-          '⏳ **Waiting for you to approve in the browser...**',
-          '',
-          `Sign in at: **${_deviceFlow.verifyUrl}**`,
-          `Code: **${_deviceFlow.userCode}**`,
-          '',
-          'After approving, call `sign_in` again — it will complete automatically.',
-        ].join('\n');
-      }
-    }
-    const flow = await startDeviceFlow();
-    if (flow) {
-      _deviceFlow = flow;
-      return [
-        '🧠 **cachly AI Brain — One-click sign in**',
-        '',
-        '1. Open this URL (it may open automatically):',
-        `   **${flow.verifyUrl}**`,
-        '',
-        `2. If prompted for a code, enter: **${flow.userCode}**`,
-        '',
-        '3. After approving in your browser, call `sign_in` again — it will complete automatically.',
-        '',
-        '✨ Free tier: 1 Brain instance · persistent memory · 63 MCP tools · no credit card required.',
-      ].join('\n');
-    }
-    return [
-      '🧠 **cachly AI Brain — Setup required**',
-      '',
-      'Run once in your terminal:',
-      '   `npx @cachly-dev/mcp-server@latest setup`',
-      '',
-      'Or sign up at: https://cachly.dev/setup-ai',
-    ].join('\n');
-  }
-
   // Guard: if no JWT, return actionable onboarding message instead of HTTP 401
   if (!JWT) {
     void sendAnonymousTelemetry(name);
@@ -541,10 +483,6 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
     ].join('\n');
   }
 
-  // Track authenticated tool call (fire-and-forget)
-  const _trackStart = Date.now();
-  void (async () => { await trackToolCall(name, true, Date.now() - _trackStart); })();
-
   // Auto-resolve instance_id from env / API when not provided in args
   if (!args.instance_id) {
     const defaultId = await resolveDefaultInstanceId();
@@ -637,6 +575,44 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         authInfo = '❌ JWT decode failed – check CACHLY_JWT format';
       }
 
+      // List instances + connectivity
+      let instanceInfo = '';
+      try {
+        const listRes = await apiFetch<{ data: Instance[] }>('/api/v1/instances');
+        const instances = listRes.data ?? [];
+        if (instances.length === 0) {
+          instanceInfo = '\n\n🧠 **Brain Instances:** none — create one at https://cachly.dev/instances';
+        } else {
+          const lines: string[] = ['\n\n🧠 **Brain Instances:**'];
+          for (const inst of instances) {
+            const badge = inst.status === 'running' ? '🟢' : inst.status === 'provisioning' ? '🟡' : '🔴';
+            const defaultMark = inst.id === _defaultInstanceId ? ' ← active' : '';
+            lines.push(`  ${badge} **${inst.name}** (\`${inst.id}\`) · ${inst.status}${defaultMark}`);
+            if (inst.status === 'running' && inst.host) {
+              // Try a quick ping on the cached connection
+              const pooled = pool.get(inst.id);
+              if (pooled) {
+                try {
+                  await pooled.ping();
+                  lines.push(`     💓 Redis: connected`);
+                } catch {
+                  lines.push(`     ⚠️  Redis: pooled but ping failed — will reconnect on next use`);
+                }
+              } else {
+                lines.push(`     💤 Redis: not connected yet (connects on first tool use)`);
+              }
+            } else if (inst.status === 'provisioning') {
+              lines.push(`     ⏳ Still provisioning — check back in ~30 s`);
+            } else if (inst.status !== 'running') {
+              lines.push(`     ❌ Not reachable (status: ${inst.status})`);
+            }
+          }
+          instanceInfo = lines.join('\n');
+        }
+      } catch (e) {
+        instanceInfo = `\n\n🧠 **Brain Instances:** could not fetch — ${(e as Error).message}`;
+      }
+
       return [
         `📡 **cachly API Status**`,
         ``,
@@ -645,6 +621,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         ``,
         `🔑 **Auth:**`,
         authInfo,
+        instanceInfo,
       ].join('\n');
     }
 
@@ -658,15 +635,7 @@ const server = new Server(
   { capabilities: { tools: {} } }
 );
 
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  if (!JWT) {
-    // Surface sign_in as the only prominent tool when not authenticated,
-    // so AI assistants proactively call it before attempting any brain tool.
-    const signInTool = TOOLS.find(t => t.name === 'sign_in');
-    return { tools: signInTool ? [signInTool] : TOOLS };
-  }
-  return { tools: TOOLS };
-});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 
 // ── Auto-session management ───────────────────────────────────────────────────
 // Transparently starts a Brain session on the first tool call of a process
@@ -690,8 +659,9 @@ async function autoStartSession(instanceId: string): Promise<void> {
     _autoSessionInstanceId = instanceId;
     try {
       await handleTool('session_start', { instance_id: instanceId, focus: 'auto (MCP session)' });
-    } catch { /* non-fatal — session tracking is a best-effort feature */ }
-    _autoSessionStarting = null;
+    } catch { /* non-fatal — session tracking is a best-effort feature */ } finally {
+      _autoSessionStarting = null;
+    }
   })();
   await _autoSessionStarting;
 
@@ -740,7 +710,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   // Skip session management tools to avoid recursion.
   const sessionTools = new Set(['session_start', 'session_end', 'auto_learn_session']);
   if (!sessionTools.has(name) && !_autoSessionStarted && !_autoSessionStarting) {
-    const instanceId = (args as Record<string, unknown>)?.instance_id as string | undefined;
+    const instanceId = ((args as Record<string, unknown>)?.instance_id as string | undefined)
+      || _defaultInstanceId
+      || process.env.CACHLY_BRAIN_INSTANCE_ID;
     if (instanceId) {
       await autoStartSession(instanceId).catch(() => undefined);
     }
@@ -833,54 +805,47 @@ function buildMcpConfig(apiKey: string, instanceId: string, editor: string): str
 
 function buildClaudeMdBlock(instanceId: string): string {
   return `${CLAUDE_MD_MARKER_START}
-## Cachly AI Brain
+## Cachly AI Brain — Always Active
 
-The Cachly MCP server is available as tool \`cachly\`.
-Your instance ID: \`${instanceId}\`
+The Brain MCP server runs automatically. Instance: \`${instanceId}\`
 
-> **Sessions are fully automatic** (MCP ≥ 0.5.3).
-> The Brain starts tracking when you call any tool for the first time and saves a summary when your editor closes. You never need to call \`session_start\` or \`session_end\` manually.
+Sessions start and end automatically — never call \`session_start\` or \`session_end\`.
 
 ---
 
-### Before editing any file — WIP-registry (prevents half-finished code across sessions):
+### BEFORE every task (mandatory — no exceptions):
+\`\`\`
+smart_recall(instance_id="${instanceId}", query="<what you are about to do>")
+\`\`\`
+Report any relevant lessons found to the user before proceeding.
+
+### BEFORE editing any file (mandatory):
 \`\`\`
-remember_context(
-  instance_id = "${instanceId}",
-  key         = "wip-registry",
-  content     = "EDITING: <file:line> — goal: <what you are implementing>",
-  category    = "bug",
-  ttl         = 86400,
-)
+remember_context(instance_id="${instanceId}", key="wip:<filename>", content="EDITING: <file:line> — <goal>", ttl=86400)
 \`\`\`
-After the edit is complete, update \`content\` to \`"DONE: <file> — <what was completed>"\`.
+When done: update content to \`"DONE: <file> — <summary>"\`.
 
-### After fixing any bug or solving a tricky problem:
+### AFTER every fix, deploy, or discovery (mandatory):
 \`\`\`
-learn_from_attempts(
-  instance_id = "${instanceId}",
-  topic       = "category:keyword",
-  outcome     = "success",
-  what_worked = "...",
-  what_failed = "...",
-  severity    = "critical" | "major" | "minor",
-  file_paths  = ["path/to/file"],
-  commands    = ["the command that worked"],
-  tags        = ["tag1"],
-)
+learn_from_attempts(instance_id="${instanceId}", topic="<category:keyword>", outcome="success"|"failure",
+  what_worked="...", what_failed="...", severity="critical"|"major"|"minor",
+  file_paths=["..."], commands=["..."], tags=["..."])
 \`\`\`
 
-### Before starting any task — recall relevant lessons first:
+### WHEN debugging any error (mandatory before grepping/reading files):
 \`\`\`
-smart_recall(
-  instance_id = "${instanceId}",
-  query       = "<describe what you are about to do>",
-)
+causal_trace(instance_id="${instanceId}", problem="<exact error or symptom>")
 \`\`\`
+If a known fix exists in the Brain, use it directly. Skip research if Brain has the answer.
+
+### BEFORE any risky operation (deploy, migration, dependency upgrade):
+\`\`\`
+brain_predict(instance_id="${instanceId}", context="<what you are about to do>")
+\`\`\`
+Report predicted failure risks to the user before proceeding.
 
 ### Half-finished code rule:
 Never commit code that does not compile. Run \`tsc --noEmit\` / \`go build ./...\` before every commit.
-If a session ends mid-task, save the WIP-registry entry so the next session picks up exactly where you left off.
 ${CLAUDE_MD_MARKER_END}`;
 }
 
@@ -987,7 +952,7 @@ if (process.argv[2] === 'init') {
 // Usage: npx @cachly-dev/mcp-server setup
 
 if (process.argv[2] === 'setup') {
-  const { writeFile, mkdir } = await import('node:fs/promises');
+  const { writeFile, mkdir, readFile } = await import('node:fs/promises');
   const { existsSync } = await import('node:fs');
   const { resolve, dirname } = await import('node:path');
   const { createInterface } = await import('node:readline');
@@ -1216,7 +1181,7 @@ if (process.argv[2] === 'setup') {
   const editorsToSetup = detected;
   console.log(`Step 3: Configuring for: ${editorsToSetup.map(editorLabel).join(', ')}\n`);
 
-  // ── Step 4: Write editor configs ──────────────────────────────────────────
+  // ── Step 4: Write editor configs (project-level) ─────────────────────────
   for (const editor of editorsToSetup) {
     const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
     const configPath = resolve(cwd, configFile);
@@ -1225,11 +1190,54 @@ if (process.argv[2] === 'setup') {
     console.log(`✅ Written: ${configFile}`);
   }
 
+  // ── Step 4b: Write global Claude Code config (~/.claude/mcp.json) ─────────
+  // Merges cachly into the existing global config so it works in every project,
+  // without removing other MCP servers the user may have configured.
+  const globalClaudePath = resolve(home, '.claude', 'mcp.json');
+  try {
+    await mkdir(dirname(globalClaudePath), { recursive: true });
+    let globalConfig: { mcpServers?: Record<string, unknown> } = {};
+    if (existsSync(globalClaudePath)) {
+      try {
+        globalConfig = JSON.parse(await readFile(globalClaudePath, 'utf-8')) as typeof globalConfig;
+      } catch { /* corrupt — start fresh */ }
+    }
+    globalConfig.mcpServers ??= {};
+    globalConfig.mcpServers['cachly'] = {
+      command: 'npx',
+      args: ['-y', '@cachly-dev/mcp-server@latest'],
+      env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: token, CACHLY_BRAIN_INSTANCE_ID: instance.id },
+    };
+    await writeFile(globalClaudePath, JSON.stringify(globalConfig, null, 2), 'utf-8');
+    console.log(`✅ Written: ~/.claude/mcp.json  (global — works in every project)`);
+  } catch (e) {
+    console.log(`⚠️  Could not write ~/.claude/mcp.json: ${(e as Error).message}`);
+  }
+
   // ── Step 5: CLAUDE.md (always — idempotent) ───────────────────────────────
   const mdResult = await writeClaudeMd(cwd, instance.id);
   const mdLabel = mdResult === 'updated' ? '✅ Updated' : mdResult === 'appended' ? '✅ Appended to' : '✅ Written';
   console.log(`${mdLabel}: CLAUDE.md\n`);
 
+  // ── Step 5b: Bootstrap Brain from git history ─────────────────────────────
+  // Pre-populates the Brain with real lessons so the first session_start shows
+  // actual project knowledge instead of an empty brain.
+  if (existsSync(resolve(cwd, '.git'))) {
+    process.stdout.write('⏳ Bootstrapping Brain from git history (~10s)...');
+    try {
+      JWT = token; // set global JWT so handleTool can authenticate
+      const gitResult = await handleTool('brain_from_git', {
+        instance_id: instance.id,
+        dir: cwd,
+        max_commits: 100,
+      });
+      const match = gitResult.match(/(\d+) lesson/);
+      console.log(` ✓  ${match ? match[1] + ' lessons' : 'done'} extracted from git history`);
+    } catch (e) {
+      console.log(` (skipped: ${(e as Error).message.slice(0, 80)})`);
+    }
+  }
+
   // ── Step 6: Show Brain health (Aha moment) ────────────────────────────────
   // Fetch brain health from the API to show the user what their agent will see.
   process.stdout.write('\n⏳ Fetching your Brain health preview...');
@@ -1450,7 +1458,6 @@ if (httpPort) {
       res.end(JSON.stringify({
         status: 'ok',
         version: CURRENT_VERSION,
-        toolCalls: { total: _toolCallTotal, authed: _toolCallAuthedTotal },
         zeroResults: {
           total: zeroResultsTotal,
           last10: ZERO_RESULTS_LOG.slice(-10).map(e => ({ query: e.query, ts: new Date(e.ts).toISOString() })),
@@ -1458,23 +1465,6 @@ if (httpPort) {
       }));
       return;
     }
-    if (url.pathname === '/stats') {
-      // Top tools sorted by call count
-      const top = Object.entries(_toolCallCounts)
-        .sort(([, a], [, b]) => b - a)
-        .slice(0, 20)
-        .map(([tool, count]) => ({ tool, count }));
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({
-        version: CURRENT_VERSION,
-        total: _toolCallTotal,
-        authed: _toolCallAuthedTotal,
-        unauthenticated: _toolCallTotal - _toolCallAuthedTotal,
-        topTools: top,
-        uptimeSec: Math.floor(process.uptime()),
-      }));
-      return;
-    }
     if (url.pathname === '/mcp' || url.pathname === '/') {
       transport.handleRequest(req, res);
       return;