@cachly-dev/mcp-server 0.10.27 → 0.10.40

package/src/index.ts

@@ -3,6 +3,13 @@ import { jwtExpiryMs, checkJwt, handleApiError } from './auth.js';
 import { readFile } from 'node:fs/promises';
 import { execSync } from 'node:child_process';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// True only when this file is the entry point (not imported by tests or other modules).
+const _isMain = process.argv[1] != null &&
+  (process.argv[1] === fileURLToPath(import.meta.url) ||
+   process.argv[1].endsWith('/dist/index.js') ||
+   process.argv[1].endsWith('/src/index.ts'));
 /**
  * cachly MCP Server v0.4.0
  *
@@ -53,7 +60,7 @@ 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.10.10';
+const CURRENT_VERSION = '0.10.40';
 
 // ── Default Instance Resolution (for Smithery & single-credential setups) ────
 // When CACHLY_BRAIN_INSTANCE_ID is set, tools can omit the instance_id parameter.
@@ -159,6 +166,7 @@ async function pollDeviceFlow(flow: DeviceFlowState): Promise<'pending' | 'expir
       JWT = apiKey;
       setEmbedJwt(apiKey); // keep embeddings.ts in sync
       _deviceFlow = null;
+      sendFunnelEvent('device_flow_completed');
       // Auto-provision: find or create the user's brain instance.
       _defaultInstanceLastAttempt = 0;
       await resolveDefaultInstanceId();
@@ -177,8 +185,16 @@ async function pollDeviceFlow(flow: DeviceFlowState): Promise<'pending' | 'expir
             };
             const id = body.instance?.id ?? body.instance_id;
             if (id) _defaultInstanceId = id;
+          } else {
+            // Log so telemetry can detect free-tier auto-provision failures
+            void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${JWT}` },
+              body: JSON.stringify({ event: 'auto_provision_failed', status: autoRes.status, version: CURRENT_VERSION }),
+              signal: AbortSignal.timeout(3000),
+            }).catch(() => {});
           }
-        } catch { /* non-fatal */ }
+        } catch { /* non-fatal — server unreachable, getConnection will surface the error */ }
       }
       // 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.
@@ -289,11 +305,24 @@ async function getConnection(instance_id: string): Promise<Redis> {
       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` +
+    let hint: string;
+    if (inst.status === 'provisioning') {
+      hint = `⏳ Brain instance "${inst.name}" is still starting up.\n\nFirst-time provisioning typically takes 1–3 minutes. Please retry in a moment — the instance will be ready soon.`;
+    } else if (inst.status === 'failed') {
+      hint = `❌ Brain instance "${inst.name}" failed to start.\n\n` +
+        `Our system will retry automatically. Check status at: https://cachly.dev/instances\n` +
+        `If this persists, contact support@cachly.dev.`;
+    } else if (inst.status === 'suspended') {
+      hint = `⏸ Brain instance "${inst.name}" is suspended (billing issue).\n\n` +
+        `Update your payment method at: https://cachly.dev/billing`;
+    } else if (inst.status === 'pending_payment') {
+      hint = `💳 Brain instance "${inst.name}" is waiting for payment.\n\n` +
+        `Complete your checkout at: https://cachly.dev/instances`;
+    } else {
+      hint = `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) {
@@ -310,8 +339,15 @@ async function getConnection(instance_id: string): Promise<Redis> {
     );
     password = conn.password ?? undefined;
     tlsEnabled = conn.tls_enabled !== false;
-  } catch {
-    // Fallback: use TLS flag from instance metadata
+  } catch (connErr) {
+    // If the connection endpoint fails and the instance has a password, we cannot connect.
+    // Surface the error so the user knows why Redis auth will fail rather than getting a cryptic NOAUTH.
+    const msg = connErr instanceof Error ? connErr.message : String(connErr);
+    if (msg.includes('401') || msg.includes('403') || msg.includes('Unauthorized')) {
+      throw new McpError(ErrorCode.InvalidRequest,
+        `API key rejected — run \`cachly setup\` to refresh your credentials.`);
+    }
+    // Other failures (timeout, 500): proceed without password, Redis will surface NOAUTH if needed
   }
 
   const client = new Redis({
@@ -400,21 +436,40 @@ import { TOOLS } from './tools.js';
 
 // 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> {
-  if (_telemetryPingSent) return;
-  if (process.env.CACHLY_NO_TELEMETRY === '1') return;
-  _telemetryPingSent = true;
-  // Detect editor from common env vars injected by IDE extensions
-  const editor = process.env.CURSOR_TRACE_ID ? 'cursor'
+// Fires once per process on the first successful Brain tool call — key activation metric
+let _firstCallSuccessSent = false;
+
+function detectEditor(): string {
+  return process.env.CURSOR_TRACE_ID ? 'cursor'
     : process.env.WINDSURF_SESSION_ID ? 'windsurf'
     : process.env.GITHUB_COPILOT_WORKSPACE ? 'copilot'
     : process.env.CLAUDE_CODE_ENTRYPOINT ? 'claude'
     : 'unknown';
+}
+
+function sendFunnelEvent(event: string, extra?: Record<string, unknown>): void {
+  if (process.env.CACHLY_NO_TELEMETRY === '1') return;
+  void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      event, version: CURRENT_VERSION, editor: detectEditor(),
+      ...(JWT ? { jwt: JWT } : {}),
+      ...extra,
+    }),
+    signal: AbortSignal.timeout(3000),
+  }).catch(() => {/* fire-and-forget */});
+}
+
+async function sendAnonymousTelemetry(toolName: string): Promise<void> {
+  if (_telemetryPingSent) return;
+  if (process.env.CACHLY_NO_TELEMETRY === '1') return;
+  _telemetryPingSent = true;
   try {
     await fetch(`${API_URL}/api/v1/telemetry/mcp`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ event: 'first_call_no_jwt', version: CURRENT_VERSION, editor, tool: toolName }),
+      body: JSON.stringify({ event: 'first_call_no_jwt', version: CURRENT_VERSION, editor: detectEditor(), tool: toolName }),
       signal: AbortSignal.timeout(3000),
     });
   } catch { /* fire-and-forget, never block the user */ }
@@ -453,18 +508,28 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
     const flow = await startDeviceFlow();
     if (flow) {
       _deviceFlow = flow;
+      sendFunnelEvent('device_flow_started', { tool: name });
+      // Try to open the browser automatically — fire-and-forget, never block
+      void (async () => {
+        try {
+          const { exec } = await import('node:child_process');
+          const url = flow.verifyUrl;
+          const cmd = process.platform === 'win32' ? `start "" "${url}"`
+            : process.platform === 'darwin' ? `open "${url}"`
+            : `xdg-open "${url}"`;
+          exec(cmd);
+        } catch { /* non-critical */ }
+      })();
       return [
-        '🧠 **cachly AI Brain — One-click sign in**',
+        '🧠 **cachly AI Brain — sign in to activate** (browser opening...)',
         '',
-        '1. Open this URL in your browser (it may open automatically):',
-        `   **${flow.verifyUrl}**`,
+        `👉 **${flow.verifyUrl}**`,
         '',
-        `2. Enter this code if prompted: **${flow.userCode}**`,
+        `Code: **${flow.userCode}** (pre-filled if browser opened automatically)`,
         '',
-        '3. After sign-in, call this tool again — it will proceed automatically.',
+        'After sign-in: call **any tool again** — your Brain activates instantly.',
         '',
-        '✨ Free tier includes: 1 Brain instance, persistent memory, 63 MCP tools.',
-        '   No credit card required.',
+        '✨ Free forever · No credit card · 89 MCP tools · GDPR · EU servers',
       ].join('\n');
     }
 
@@ -491,11 +556,81 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
 
   // Delegate brain tools (learn, recall, session, etc.)
   const brainResult = await handleBrainTool(name, args, getConnection, apiFetch);
-  if (brainResult !== null) return brainResult;
+  if (brainResult !== null) {
+    if (!_firstCallSuccessSent && JWT) {
+      _firstCallSuccessSent = true;
+      sendFunnelEvent('first_call_success', { tool: name, instance_id: args.instance_id ?? _defaultInstanceId ?? '' });
+    }
+    // Per-tool telemetry — fires after every successful brain tool call.
+    // api_key carries the cky_live_... token so the backend can resolve tenant + increment counters.
+    const instanceId = (args.instance_id as string | undefined) ?? _defaultInstanceId ?? '';
+    const telemetryExtra = JWT ? { api_key: JWT, instance_id: instanceId } : { instance_id: instanceId };
+    if (name === 'recall_best_solution') {
+      // recall_best_solution → increments BrainRecallCount + triggers level-up logic
+      sendFunnelEvent('recall_best_solution', telemetryExtra);
+    } else if (name === 'learn_from_attempts') {
+      sendFunnelEvent('learn_from_attempts', telemetryExtra);
+    } else if (name === 'session_start') {
+      sendFunnelEvent('session_start', telemetryExtra);
+      const resultText = typeof brainResult === 'object' && brainResult !== null && 'content' in brainResult
+        ? JSON.stringify(brainResult)
+        : String(brainResult ?? '');
+      const isFirstSession = resultText.includes('Welcome! Your AI Brain is live.');
+
+      if (!isFirstSession && resultText.length > 100) {
+        // Existing brain — session_start acts as implicit recall → increment counter.
+        sendFunnelEvent('recall_best_solution', telemetryExtra);
+      } else if (isFirstSession && args.workspace_path) {
+        // First session with a known workspace: auto-bootstrap from git history.
+        // Runs synchronously so the user sees the result in the same response.
+        try {
+          const gitBootstrap = await handleFedbrainTool('brain_from_git', {
+            instance_id: instanceId,
+            repo_path: args.workspace_path as string,
+            limit: 50,
+          }, getConnection, apiFetch);
+          if (gitBootstrap !== null) {
+            sendFunnelEvent('brain_from_git', telemetryExtra);
+            sendFunnelEvent('recall_best_solution', telemetryExtra);
+            // Append bootstrap summary to the session_start briefing.
+            const bootstrapText = typeof gitBootstrap === 'object' && gitBootstrap !== null && 'content' in gitBootstrap
+              ? (gitBootstrap as { content: { text?: string }[] }).content.map((c) => c.text ?? '').join('\n')
+              : String(gitBootstrap);
+            if (typeof brainResult === 'object' && brainResult !== null && 'content' in brainResult) {
+              (brainResult as { content: { type: string; text: string }[] }).content.push({
+                type: 'text',
+                text: '\n---\n' + bootstrapText,
+              });
+            }
+          }
+        } catch { /* git bootstrap errors must never break session_start */ }
+      }
+    } else if (name === 'session_end') {
+      sendFunnelEvent('session_end', telemetryExtra);
+    } else if (name === 'smart_recall') {
+      sendFunnelEvent('smart_recall', telemetryExtra);
+      // smart_recall is the primary recall tool in CLAUDE.md — it retrieves brain lessons
+      // just like recall_best_solution. Count it toward BrainRecallCount so the dashboard
+      // nudge clears and the first-recall email fires for users following CLAUDE.md.
+      const srText = typeof brainResult === 'object' && brainResult !== null && 'content' in brainResult
+        ? JSON.stringify(brainResult)
+        : String(brainResult ?? '');
+      if (srText.length > 50 && !srText.includes('No lessons found') && !srText.includes('no lessons')) {
+        sendFunnelEvent('recall_best_solution', telemetryExtra);
+      }
+    }
+    return brainResult;
+  }
 
   // Delegate context tools (remember/recall/list/forget)
   const contextResult = await handleContextTool(name, args, getConnection, apiFetch);
-  if (contextResult !== null) return contextResult;
+  if (contextResult !== null) {
+    if (!_firstCallSuccessSent && JWT) {
+      _firstCallSuccessSent = true;
+      sendFunnelEvent('first_call_success', { tool: name, instance_id: args.instance_id ?? _defaultInstanceId ?? '' });
+    }
+    return contextResult;
+  }
 
   // Delegate instance + cache tools
   const instanceResult = await handleInstanceTool(name, args, getConnection, apiFetch);
@@ -515,10 +650,28 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
   if (advancedResult !== null) return advancedResult;
 
   const syndicateResult = await handleSyndicateTool(name, args, getConnection, apiFetch);
-  if (syndicateResult !== null) return syndicateResult;
+  if (syndicateResult !== null) {
+    // brain_predict is in syndicate handler — track telemetry here.
+    if (name === 'brain_predict') {
+      const instanceId = (args.instance_id as string | undefined) ?? _defaultInstanceId ?? '';
+      const telemetryExtra = JWT ? { api_key: JWT, instance_id: instanceId } : { instance_id: instanceId };
+      sendFunnelEvent('brain_predict', telemetryExtra);
+    }
+    return syndicateResult;
+  }
 
   const fedbrainResult = await handleFedbrainTool(name, args, getConnection, apiFetch);
-  if (fedbrainResult !== null) return fedbrainResult;
+  if (fedbrainResult !== null) {
+    // brain_from_git and brain_predict_failures are in fedbrain handler.
+    const instanceId = (args.instance_id as string | undefined) ?? _defaultInstanceId ?? '';
+    const telemetryExtra = JWT ? { api_key: JWT, instance_id: instanceId } : { instance_id: instanceId };
+    if (name === 'brain_from_git') {
+      sendFunnelEvent('brain_from_git', telemetryExtra);
+    } else if (name === 'brain_predict_failures') {
+      sendFunnelEvent('brain_predict_failures', telemetryExtra);
+    }
+    return fedbrainResult;
+  }
 
   switch (name) {
     // ── Instance management ──────────────────────────────────────────────
@@ -635,33 +788,7 @@ const server = new Server(
   { capabilities: { tools: {} } }
 );
 
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  if (!JWT) {
-    // No credentials — inject sign-up CTA into session_start description
-    const tools = TOOLS.map(t => {
-      if (t.name !== 'session_start') return t;
-      return {
-        ...t,
-        description:
-          `⚡ FREE AI BRAIN — sign up once at https://cachly.dev/sign-up (no credit card) ` +
-          `then run: npx @cachly-dev/mcp-server@latest setup\n\n` + t.description,
-      };
-    });
-    return { tools };
-  }
-
-  // ── Auto-start session on connection (fire and forget) ────────────────────
-  // When the AI reads the tools list, it has just connected. Proactively start
-  // the Brain session in the background so by the time the first tool call
-  // arrives, session context is already loaded and ready to inject.
-  if (!_autoSessionStarted && !_autoSessionStarting) {
-    void resolveDefaultInstanceId().then(instanceId => {
-      if (instanceId) void autoStartSession(instanceId).catch(() => undefined);
-    }).catch(() => undefined);
-  }
-
-  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
@@ -670,91 +797,59 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 
 let _autoSessionInstanceId: string | null = null;
 let _autoSessionStarted = false;
-let _autoSessionStarting: Promise<string | null> | null = null; // guard against double-start race
+let _autoSessionStarting: Promise<void> | null = null; // guard against double-start race
 let _autoSessionToolCount = 0;
-let _autoSessionContext: string | null = null; // result of session_start, injected into first tool response
-let _autoSessionContextInjected = false; // only inject once
 
 // ── brain_from_git concurrency limiter ────────────────────────────────────────
 // Spawning many `git log` subprocesses in parallel can fork-bomb the host.
 // This simple semaphore caps concurrent brain_from_git calls to 10 per process.
-async function autoStartSession(instanceId: string): Promise<string | null> {
-  if (_autoSessionStarted) return null;
+async function autoStartSession(instanceId: string): Promise<void> {
+  if (_autoSessionStarted) return;
   // If another call already started the session, await it instead of double-starting.
-  if (_autoSessionStarting) { return _autoSessionStarting; }
-  _autoSessionStarting = (async (): Promise<string | null> => {
+  if (_autoSessionStarting) { await _autoSessionStarting; return; }
+  _autoSessionStarting = (async () => {
     _autoSessionStarted = true;
     _autoSessionInstanceId = instanceId;
-    let sessionResult: string | null = null;
     try {
-      // Auto-detect git context for a meaningful session focus
-      let focus = 'auto (MCP session)';
-      try {
-        const { execSync } = await import('node:child_process');
-        const branch = execSync('git rev-parse --abbrev-ref HEAD',
-          { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }
-        ).trim();
-        const lastMsg = execSync('git log -1 --pretty=%s',
-          { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }
-        ).trim();
-        if (branch && branch !== 'HEAD') {
-          focus = lastMsg ? `${branch}: ${lastMsg.slice(0, 80)}` : `branch: ${branch}`;
-        }
-      } catch { /* git not available in this workspace */ }
-      sessionResult = await handleTool('session_start', { instance_id: instanceId, focus });
-      _autoSessionContext = sessionResult;
+      await handleTool('session_start', { instance_id: instanceId, focus: 'auto (MCP session)', workspace_path: process.cwd() });
     } catch { /* non-fatal — session tracking is a best-effort feature */ } finally {
       _autoSessionStarting = null;
     }
-
-    // Auto-index the project if it hasn't been indexed in the last 24h.
-    // This is the main lever for growing token savings: more indexed code →
-    // more semantic cache hits → fewer LLM calls for repeated questions.
-    if (process.env.CACHLY_AUTO_INDEX !== 'false') {
-      try {
-        const redis = await getConnection(instanceId);
-        const lastIndexed = await redis.get(`cachly:index:last_indexed:${instanceId}`);
-        const staleMs = 24 * 60 * 60 * 1000;
-        const isStale = !lastIndexed || (Date.now() - parseInt(lastIndexed, 10)) > staleMs;
-        if (isStale) {
-          // Mark as indexing now to prevent concurrent re-runs.
-          await redis.set(`cachly:index:last_indexed:${instanceId}`, String(Date.now()), 'EX', 90000);
-          // Run in background — don't block the first tool call.
-          handleTool('index_project', {
-            instance_id: instanceId,
-            dir: process.cwd(),
-            max_files: 150,
-            ttl: 86400 * 7, // cache for 7 days
-            namespace: 'cachly:sem:code',
-          }).catch(() => undefined);
-        }
-      } catch { /* never block the session on indexing errors */ }
-    }
-
-    return sessionResult;
   })();
-  return _autoSessionStarting;
+  await _autoSessionStarting;
+
+  // Auto-index the project if it hasn't been indexed in the last 24h.
+  // This is the main lever for growing token savings: more indexed code →
+  // more semantic cache hits → fewer LLM calls for repeated questions.
+  if (process.env.CACHLY_AUTO_INDEX !== 'false') {
+    try {
+      const redis = await getConnection(instanceId);
+      const lastIndexed = await redis.get(`cachly:index:last_indexed:${instanceId}`);
+      const staleMs = 24 * 60 * 60 * 1000;
+      const isStale = !lastIndexed || (Date.now() - parseInt(lastIndexed, 10)) > staleMs;
+      if (isStale) {
+        // Mark as indexing now to prevent concurrent re-runs.
+        await redis.set(`cachly:index:last_indexed:${instanceId}`, String(Date.now()), 'EX', 90000);
+        // Run in background — don't block the first tool call.
+        handleTool('index_project', {
+          instance_id: instanceId,
+          dir: process.cwd(),
+          max_files: 150,
+          ttl: 86400 * 7, // cache for 7 days
+          namespace: 'cachly:sem:code',
+        }).catch(() => undefined);
+      }
+    } catch { /* never block the session on indexing errors */ }
+  }
 }
 
 async function autoEndSession(): Promise<void> {
   if (!_autoSessionStarted || !_autoSessionInstanceId) return;
   _autoSessionStarted = false;
   try {
-    // Try to derive a meaningful summary from git
-    let summary = `Auto-ended after ${_autoSessionToolCount} tool call(s).`;
-    try {
-      const { execSync } = await import('node:child_process');
-      const branch = execSync('git rev-parse --abbrev-ref HEAD',
-        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }
-      ).trim();
-      const lastMsg = execSync('git log -1 --pretty=%s',
-        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }
-      ).trim();
-      if (lastMsg) summary = `${branch ? `[${branch}] ` : ''}${lastMsg} · ${_autoSessionToolCount} tool calls`;
-    } catch { /* git unavailable */ }
     await handleTool('session_end', {
       instance_id: _autoSessionInstanceId,
-      summary,
+      summary: `Auto-ended after ${_autoSessionToolCount} tool call(s). Session was started automatically.`,
       files_changed: [],
       lessons_learned: 0,
     });
@@ -764,7 +859,7 @@ async function autoEndSession(): Promise<void> {
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
 
-  // Auto-start brain session if not yet started (fallback: ListTools already fired this).
+  // Auto-start brain session on first tool call that has an instance_id.
   // Skip session management tools to avoid recursion.
   const sessionTools = new Set(['session_start', 'session_end', 'auto_learn_session']);
   if (!sessionTools.has(name) && !_autoSessionStarted && !_autoSessionStarting) {
@@ -782,18 +877,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
   try {
     const text = await handleTool(name, (args ?? {}) as Record<string, unknown>);
-
-    // ── Inject session context into the FIRST tool response ─────────────────
-    // This is the key: the AI sees the previous session summary, handoff tasks,
-    // and recent lessons automatically — without needing to call session_start.
-    // Only injected once per process (on the very first tool call).
-    if (!_autoSessionContextInjected && _autoSessionContext && !sessionTools.has(name)) {
-      _autoSessionContextInjected = true;
-      const ctx = _autoSessionContext;
-      _autoSessionContext = null; // free memory
-      return { content: [{ type: 'text', text: `${ctx}\n\n---\n\n${text}` }] };
-    }
-
     return { content: [{ type: 'text', text }] };
   } catch (err) {
     if (err instanceof McpError) throw err;
@@ -873,122 +956,61 @@ function buildMcpConfig(apiKey: string, instanceId: string, editor: string): str
   }, null, 2);
 }
 
-/**
- * Build only the per-server entry that gets merged into an existing config.
- * Returned shape varies by editor — see writeMergedMcpConfig for the merge
- * locations.
- */
-function buildCachlyServerEntry(apiKey: string, instanceId: string, editor: string): unknown {
-  if (editor === 'continue') {
-    return {
-      transport: { type: 'stdio', command: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'] },
-      env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
-    };
-  }
-  if (editor === 'zed') {
-    return {
-      command: {
-        path: 'npx',
-        args: ['-y', '@cachly-dev/mcp-server@latest'],
-        env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
-      },
-      settings: {},
-    };
-  }
-  return {
-    command: 'npx',
-    args: ['-y', '@cachly-dev/mcp-server@latest'],
-    env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
-  };
-}
-
-/**
- * Merge the cachly server into an existing editor MCP config file — preserving
- * every other MCP server the user has configured. Creates the file if missing.
- * Writes a one-time .cachly-backup-<timestamp> next to the file before any
- * mutation so the user can recover from corrupt/unexpected merges.
- *
- * Returns 'created' if the file did not exist, 'updated' if cachly was already
- * present (re-pointed to a possibly new instance), or 'merged' if cachly was
- * added alongside other servers.
- */
-async function writeMergedMcpConfig(
+// mergeMcpConfig reads an existing config file (if any), merges the cachly entry,
+// and returns the updated JSON string — preserving all other MCP servers and settings.
+async function mergeMcpConfig(
   configPath: string,
   apiKey: string,
   instanceId: string,
   editor: string,
-): Promise<'created' | 'updated' | 'merged'> {
-  const { writeFile, readFile, mkdir, copyFile } = await import('node:fs/promises');
-  const { existsSync } = await import('node:fs');
-  const { dirname } = await import('node:path');
-
-  await mkdir(dirname(configPath), { recursive: true });
+  fsOps: { readFile: (p: string, enc: BufferEncoding) => Promise<string>; existsSync: (p: string) => boolean },
+): Promise<string> {
+  const cachlyEntry = {
+    command: 'npx',
+    args: ['-y', '@cachly-dev/mcp-server@latest'],
+    env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
+  };
 
-  // No existing file → write fresh full config.
-  if (!existsSync(configPath)) {
-    await writeFile(configPath, buildMcpConfig(apiKey, instanceId, editor), 'utf-8');
-    return 'created';
-  }
+  if (!fsOps.existsSync(configPath)) return buildMcpConfig(apiKey, instanceId, editor);
 
-  // Parse existing config. On parse failure, back it up and start fresh
-  // (never silently destroy user data — the .cachly-backup gives them a
-  // recovery path).
-  const raw = await readFile(configPath, 'utf-8');
-  let existing: Record<string, unknown>;
+  let existing: Record<string, unknown> = {};
   try {
-    existing = JSON.parse(raw) as Record<string, unknown>;
-    if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
-      throw new Error('config root is not an object');
-    }
+    existing = JSON.parse(await fsOps.readFile(configPath, 'utf-8')) as Record<string, unknown>;
   } catch {
-    const backupPath = `${configPath}.cachly-backup-${Date.now()}`;
-    await copyFile(configPath, backupPath);
-    await writeFile(configPath, buildMcpConfig(apiKey, instanceId, editor), 'utf-8');
-    return 'created';
+    // Corrupt or unreadable JSON — back it up by appending .bak, then start fresh
+    try {
+      const { rename } = await import('node:fs/promises');
+      await rename(configPath, configPath + '.bak');
+      process.stderr.write(`⚠️  ${configPath} was not valid JSON — backed up to ${configPath}.bak\n`);
+    } catch { /* backup failed — still safe to overwrite with valid config */ }
   }
 
-  // Defensive backup of the valid config before mutation — first time only.
-  // The cachly-backup file is overwritten on each re-init so we don't pollute
-  // the project, but it gives the user one undo level.
-  const backupPath = `${configPath}.cachly-backup`;
-  try {
-    await copyFile(configPath, backupPath);
-  } catch { /* non-critical — backup is best-effort */ }
-
-  const entry = buildCachlyServerEntry(apiKey, instanceId, editor);
-  let hadCachly = false;
-
   if (editor === 'continue') {
-    // experimental.modelContextProtocolServers is an Array — replace existing
-    // cachly entry (matched by command/args containing @cachly-dev/mcp-server)
-    // or append.
-    type ContinueServer = { transport?: { args?: string[] }; env?: Record<string, string> };
-    const exp = (existing.experimental as Record<string, unknown> | undefined) ?? {};
-    const servers = Array.isArray(exp.modelContextProtocolServers)
-      ? (exp.modelContextProtocolServers as ContinueServer[])
-      : [];
-    const isCachly = (s: ContinueServer) =>
-      s?.transport?.args?.some((a) => typeof a === 'string' && a.includes('@cachly-dev/mcp-server')) ?? false;
+    // Merge into experimental.modelContextProtocolServers array — replace cachly entry if present
+    const exp = (existing['experimental'] ?? {}) as Record<string, unknown>;
+    const servers = (exp['modelContextProtocolServers'] ?? []) as Array<Record<string, unknown>>;
     const filtered = servers.filter((s) => {
-      if (isCachly(s)) { hadCachly = true; return false; }
-      return true;
+      const env = (s['env'] ?? {}) as Record<string, string>;
+      return !env['CACHLY_JWT'] && !env['CACHLY_BRAIN_INSTANCE_ID'];
     });
-    filtered.push(entry as ContinueServer);
-    existing.experimental = { ...exp, modelContextProtocolServers: filtered };
-  } else if (editor === 'zed') {
-    // context_servers is a Record — set cachly key.
-    const cs = (existing.context_servers as Record<string, unknown> | undefined) ?? {};
-    hadCachly = 'cachly' in cs;
-    existing.context_servers = { ...cs, cachly: entry };
-  } else {
-    // Standard mcpServers map — Claude / Cursor / Windsurf / VS Code / Cline.
-    const mcp = (existing.mcpServers as Record<string, unknown> | undefined) ?? {};
-    hadCachly = 'cachly' in mcp;
-    existing.mcpServers = { ...mcp, cachly: entry };
+    filtered.push({ transport: { type: 'stdio', command: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'] }, env: cachlyEntry.env });
+    existing['experimental'] = { ...exp, modelContextProtocolServers: filtered };
+    return JSON.stringify(existing, null, 2);
   }
 
-  await writeFile(configPath, JSON.stringify(existing, null, 2), 'utf-8');
-  return hadCachly ? 'updated' : 'merged';
+  if (editor === 'zed') {
+    // Merge only context_servers.cachly — preserve all other Zed settings
+    const cs = (existing['context_servers'] ?? {}) as Record<string, unknown>;
+    cs['cachly'] = { command: { path: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'], env: cachlyEntry.env }, settings: {} };
+    existing['context_servers'] = cs;
+    return JSON.stringify(existing, null, 2);
+  }
+
+  // Standard mcpServers format (Claude Code, Cursor, Windsurf, Copilot, Cline)
+  const servers = (existing['mcpServers'] ?? {}) as Record<string, unknown>;
+  servers['cachly'] = cachlyEntry;
+  existing['mcpServers'] = servers;
+  return JSON.stringify(existing, null, 2);
 }
 
 function buildClaudeMdBlock(instanceId: string): string {
@@ -997,15 +1019,23 @@ function buildClaudeMdBlock(instanceId: string): string {
 
 The Brain MCP server runs automatically. Instance: \`${instanceId}\`
 
-Sessions start and end automatically — never call \`session_start\` or \`session_end\`.
-
 ---
 
+### AT THE START of every new conversation (mandatory — first thing, before anything else):
+\`\`\`
+session_start(instance_id="${instanceId}", workspace_path="<absolute path to this project>", focus="<first topic the user mentioned>")
+\`\`\`
+Show the full briefing output to the user. If the response says the brain is empty or has 0 lessons, immediately seed it:
+\`\`\`
+brain_from_git(instance_id="${instanceId}", repo_path="<workspace_path>", limit=100)
+\`\`\`
+Then tell the user: "Your brain just learned from your git history. You're now pre-briefed."
+
 ### 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.
+If relevant lessons are found, say: "Your brain knows this pattern — [lesson]." Then proceed.
 
 ### BEFORE editing any file (mandatory):
 \`\`\`
@@ -1020,6 +1050,11 @@ learn_from_attempts(instance_id="${instanceId}", topic="<category:keyword>", out
   file_paths=["..."], commands=["..."], tags=["..."])
 \`\`\`
 
+### AT THE END of every conversation (mandatory):
+\`\`\`
+session_end(instance_id="${instanceId}", summary="<one sentence: what was done>", files_changed=["..."])
+\`\`\`
+
 ### WHEN debugging any error (mandatory before grepping/reading files):
 \`\`\`
 causal_trace(instance_id="${instanceId}", problem="<exact error or symptom>")
@@ -1063,6 +1098,682 @@ async function writeClaudeMd(projectDir: string, instanceId: string): Promise<'w
   return 'written';
 }
 
+
+
+// ── CLI: cachly digest ────────────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest digest
+// Weekly brain summary — what your AI learned this week. Shareable output.
+
+if (process.argv[2] === 'digest') {
+  const apiKey = process.env.CACHLY_JWT ?? '';
+  const instanceId = process.env.CACHLY_BRAIN_INSTANCE_ID ?? '';
+
+  if (!apiKey || !instanceId) {
+    console.log('\n⚠️  CACHLY_JWT and CACHLY_BRAIN_INSTANCE_ID must be set.');
+    console.log('   Run: npx @cachly-dev/mcp-server@latest setup\n');
+    process.exit(1);
+  }
+
+  process.stdout.write('\n🧠 Fetching your weekly Brain digest...\n\n');
+
+  try {
+    // Fetch current stats
+    const statsRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/brain/stats`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!statsRes.ok) throw new Error(`stats HTTP ${statsRes.status}`);
+    const stats = await statsRes.json() as {
+      lesson_count?: number; context_count?: number; quality_score?: number;
+      total_recall_count?: number; top_lessons?: Array<{ topic: string; recall_count: number; what_worked: string }>;
+      team_authors?: string[];
+    };
+
+    const lessons      = stats.lesson_count ?? 0;
+    const recalls      = stats.total_recall_count ?? 0;
+    const score        = Math.round((stats.quality_score ?? 0) * 100);
+    const topLessons   = (stats.top_lessons ?? []).slice(0, 5);
+    const teamAuthors  = stats.team_authors ?? [];
+    const tokensSaved  = recalls * 1200;
+    const costSaved    = (tokensSaved * 0.000003).toFixed(2);
+
+    const level = lessons < 10 ? 'Junior Dev 🔧' : lessons < 30 ? 'Mid Dev ⚡' :
+      lessons < 60 ? 'Senior Dev 🧠' : lessons < 100 ? 'Staff Eng 🚀' : 'Principal Eng 🏆';
+
+    const now = new Date();
+    const weekStart = new Date(now); weekStart.setDate(now.getDate() - 7);
+    const fmt = (d: Date) => d.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+
+    console.log('┌─────────────────────────────────────────────────────────────┐');
+    console.log(`│  \x1b[1m🧠 Brain Weekly Digest\x1b[0m  \x1b[90m${fmt(weekStart)} – ${fmt(now)}\x1b[0m                 │`);
+    console.log('├─────────────────────────────────────────────────────────────┤');
+    console.log(`│  Total lessons  : \x1b[33m${String(lessons).padEnd(8)}\x1b[0m  Brain level : \x1b[32m${level.padEnd(18)}\x1b[0m│`);
+    console.log(`│  Total recalls  : \x1b[36m${String(recalls).padEnd(8)}\x1b[0m  Quality score: \x1b[32m${String(score).padEnd(3)}%\x1b[0m              │`);
+    console.log(`│  Tokens saved   : \x1b[32m${String(Math.round(tokensSaved / 1000) + 'K').padEnd(8)}\x1b[0m  Cost saved   : \x1b[32m$${costSaved.padEnd(20)}\x1b[0m│`);
+
+    if (teamAuthors.length > 0) {
+      console.log('├─────────────────────────────────────────────────────────────┤');
+      console.log(`│  \x1b[36m👥 Team contributors:\x1b[0m ${teamAuthors.slice(0, 5).join(', ').slice(0, 42).padEnd(42)} │`);
+    }
+
+    if (topLessons.length > 0) {
+      console.log('├─────────────────────────────────────────────────────────────┤');
+      console.log('│  \x1b[33m🔥 Most recalled lessons this week:\x1b[0m                         │');
+      for (const l of topLessons) {
+        const line = `${l.topic}: ${l.what_worked}`.slice(0, 57);
+        console.log(`│  \x1b[90m• ${line.padEnd(58)}\x1b[0m│`);
+      }
+    }
+
+    console.log('└─────────────────────────────────────────────────────────────┘');
+    console.log('');
+
+    // ── Shareable tweet card ────────────────────────────────────────────────
+    const topLesson = topLessons[0];
+    const tweetLines = [
+      `🧠 My AI Brain weekly digest (${fmt(weekStart)} – ${fmt(now)}):`,
+      ``,
+      `  📚 ${lessons} lessons learned`,
+      `  🔁 ${recalls} recalls · ~${Math.round(tokensSaved / 1000)}K tokens saved`,
+      `  🎯 Brain Level: ${level}`,
+      topLesson ? `  🔥 Top lesson: "${topLesson.topic}: ${topLesson.what_worked.slice(0, 60)}${topLesson.what_worked.length > 60 ? '…' : ''}"` : '',
+      ``,
+      `Built with @cachly_dev — AI that actually remembers 🚀`,
+      `cachly.dev`,
+    ].filter(Boolean).join('\n');
+
+    const tweetUrl = 'https://twitter.com/intent/tweet?text=' + encodeURIComponent(tweetLines);
+
+    console.log('\x1b[1m📣 Share your digest:\x1b[0m');
+    console.log('');
+    console.log('\x1b[90m' + '─'.repeat(63) + '\x1b[0m');
+    for (const line of tweetLines.split('\n')) {
+      console.log(`  ${line}`);
+    }
+    console.log('\x1b[90m' + '─'.repeat(63) + '\x1b[0m');
+    console.log('');
+    console.log('  \x1b[36m🐦 Tweet this:\x1b[0m');
+    console.log(`  \x1b[4m${tweetUrl.slice(0, 90)}...\x1b[0m`);
+    console.log('');
+    console.log('  \x1b[2m💡 Invite your team: npx @cachly-dev/mcp-server@latest invite\x1b[0m');
+    console.log('  \x1b[2m   Cron: 0 9 * * 1 npx @cachly-dev/mcp-server@latest digest\x1b[0m');
+    console.log('');
+  } catch (e) {
+    console.log(`\n❌ Could not fetch digest: ${(e as Error).message}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── CLI: cachly invite ────────────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest invite [email]
+// Invites a teammate to share your Brain. Fastest referral loop.
+
+if (process.argv[2] === 'invite') {
+  // ── invite: fetch the user's unique referral link and show shareable messages ──
+  const apiKey = process.env.CACHLY_JWT ?? '';
+
+  if (!apiKey) {
+    console.log('\n⚠️  CACHLY_JWT must be set.');
+    console.log('   Run: npx @cachly-dev/mcp-server@latest setup\n');
+    process.exit(1);
+  }
+
+  try {
+    const res = await fetch(`${API_URL}/api/v1/referral/me`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(8000),
+    });
+
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data = await res.json() as { code?: string; url?: string; referral_count?: number };
+    const referralUrl = data.url ?? `https://cachly.dev/r/${data.code}`;
+    const count = data.referral_count ?? 0;
+
+    const slackMsg = `Hey, I've been using cachly to give my AI persistent memory across sessions — no more re-explaining my stack every morning.\n\nYou get a free Brain: ${referralUrl}`;
+    const tweetText = encodeURIComponent(`I gave my AI persistent memory. It remembers fixes, patterns, and context across every session — no more re-explaining.\n\nTry it free: ${referralUrl}\n\n@cachlydev`);
+
+    console.log('');
+    console.log('┌─────────────────────────────────────────────────────────────┐');
+    console.log('│  🧠 Your cachly Brain invite link                            │');
+    console.log('├─────────────────────────────────────────────────────────────┤');
+    console.log(`│  ${referralUrl.padEnd(61)}│`);
+    console.log('├─────────────────────────────────────────────────────────────┤');
+    if (count > 0) {
+      console.log(`│  \x1b[32m✓  ${count} developer${count === 1 ? '' : 's'} joined via your link so far\x1b[0m`.padEnd(72) + '│');
+      console.log('├─────────────────────────────────────────────────────────────┤');
+    }
+    console.log('│  \x1b[33mSlack / DM message:\x1b[0m                                         │');
+    console.log('│                                                              │');
+    for (const line of slackMsg.split('\n')) {
+      console.log(`│  \x1b[90m${line.slice(0, 58).padEnd(58)}\x1b[0m  │`);
+    }
+    console.log('│                                                              │');
+    console.log('├─────────────────────────────────────────────────────────────┤');
+    console.log(`│  \x1b[36m𝕏 Tweet:\x1b[0m https://twitter.com/intent/tweet?text=${tweetText.slice(0, 10)}...  │`);
+    console.log('└─────────────────────────────────────────────────────────────┘');
+    console.log('');
+    console.log('\x1b[2m  Each developer who signs up via your link earns you 1 month Pro.\x1b[0m');
+    console.log('');
+  } catch (e) {
+    console.log(`\n❌ Could not fetch invite link: ${(e as Error).message}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── CLI: cachly join <token> ──────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest join <token>
+// Accepts a Brain invite link — writes the shared instance ID into all
+// detected editor MCP configs and the global ~/.claude/mcp.json.
+// No account needed if CACHLY_JWT is already set; otherwise prompts for auth.
+
+if (process.argv[2] === 'join') {
+  const { writeFile: wfJ, readFile: rfJ, mkdir: mkJ } = await import('node:fs/promises');
+  const { existsSync: exJ } = await import('node:fs');
+  const { resolve: resJ, dirname: dirJ } = await import('node:path');
+  const { homedir } = await import('node:os');
+  const { createInterface: ciJ } = await import('node:readline');
+
+  const token = process.argv[3] ?? '';
+  if (!token) {
+    console.log('\n❌ Usage: npx @cachly-dev/mcp-server@latest join <token>\n');
+    console.log('   Get a token from a teammate: npx @cachly-dev/mcp-server@latest invite\n');
+    process.exit(1);
+  }
+
+  console.log('\n⏳ Looking up invite...');
+
+  // ── Step 1: Fetch invite info (public, no auth) ───────────────────────────
+  let inviteInfo: { instance_id: string; instance_name: string; tier: string; expires_at: string; label?: string };
+  try {
+    const res = await fetch(`${API_URL}/api/invite/${token}`, { signal: AbortSignal.timeout(8000) });
+    if (res.status === 404) { console.log('\n❌ Invite not found — the link may be invalid.\n'); process.exit(1); }
+    if (res.status === 410) { console.log('\n❌ This invite link has expired (7-day limit).\n'); process.exit(1); }
+    if (!res.ok) { console.log(`\n❌ Could not fetch invite: HTTP ${res.status}\n`); process.exit(1); }
+    inviteInfo = await res.json() as typeof inviteInfo;
+  } catch (e) {
+    console.log(`\n❌ Network error: ${(e as Error).message}\n`);
+    process.exit(1);
+  }
+
+  const { instance_id, instance_name, tier, label } = inviteInfo;
+  const expires = new Date(inviteInfo.expires_at).toLocaleDateString();
+
+  console.log('');
+  console.log('  \x1b[35m╔══════════════════════════════════════════════════════╗\x1b[0m');
+  console.log('  \x1b[35m║\x1b[0m  \x1b[1m🧠 Brain Invite\x1b[0m                                  \x1b[35m║\x1b[0m');
+  console.log('  \x1b[35m╚══════════════════════════════════════════════════════╝\x1b[0m');
+  console.log('');
+  console.log(`  Brain   : \x1b[1m${instance_name}\x1b[0m`);
+  console.log(`  Tier    : ${tier}`);
+  if (label) console.log(`  Note    : ${label}`);
+  console.log(`  Expires : ${expires}`);
+  console.log('');
+
+  // ── Step 2: Confirm ───────────────────────────────────────────────────────
+  const rlJ = ciJ({ input: process.stdin, output: process.stdout });
+  const confirmJ = await new Promise<string>((resolve) => {
+    rlJ.question('  Join this Brain? [Y/n] ', (a) => { rlJ.close(); resolve(a.trim().toLowerCase() || 'y'); });
+  });
+  if (confirmJ !== 'y' && confirmJ !== 'yes') {
+    console.log('\n  Cancelled.\n');
+    process.exit(0);
+  }
+
+  // ── Step 3: Ensure JWT ────────────────────────────────────────────────────
+  let joinJwt = JWT;
+  if (!joinJwt) {
+    console.log('\n  No API key found — starting sign-in (10 seconds)...\n');
+    try {
+      const dcRes = await fetch(`${API_URL}/api/v1/auth/device/code`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ client_id: 'cachly-mcp-cli' }),
+        signal: AbortSignal.timeout(10000),
+      });
+      if (dcRes.ok) {
+        const dc = await dcRes.json() as { verification_uri: string; user_code: string; device_code: string; interval: number };
+        console.log(`  👉 Open: \x1b[36m${dc.verification_uri}\x1b[0m`);
+        console.log(`     Code: \x1b[1m${dc.user_code}\x1b[0m\n`);
+        // Poll for token
+        const pollInterval = (dc.interval ?? 5) * 1000;
+        for (let i = 0; i < 24; i++) {
+          await new Promise(r => setTimeout(r, pollInterval));
+          try {
+            const tokRes = await fetch(`${API_URL}/api/v1/auth/device/token`, {
+              method: 'POST', headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ device_code: dc.device_code, client_id: 'cachly-mcp-cli' }),
+              signal: AbortSignal.timeout(8000),
+            });
+            if (tokRes.ok) {
+              const tok = await tokRes.json() as { access_token?: string };
+              if (tok.access_token) { joinJwt = tok.access_token; break; }
+            }
+          } catch { /* polling — keep going */ }
+        }
+        if (!joinJwt) { console.log('\n❌ Sign-in timed out. Run the command again.\n'); process.exit(1); }
+        console.log('  ✅ Signed in!\n');
+      }
+    } catch (e) {
+      console.log(`\n  ⚠️  Could not start sign-in: ${(e as Error).message}`);
+      console.log(`   Set CACHLY_JWT manually from https://cachly.dev/setup-ai\n`);
+      process.exit(1);
+    }
+  }
+
+  // ── Step 4: Write instance ID into all editor MCP configs ────────────────
+  const cwd  = process.cwd();
+  const home = homedir();
+
+  const editorFiles: Array<{ label: string; path: string; global?: boolean }> = [
+    { label: '.mcp.json (Claude Code project)',    path: resJ(cwd, '.mcp.json') },
+    { label: '.cursor/mcp.json',                   path: resJ(cwd, '.cursor', 'mcp.json') },
+    { label: '.windsurf/mcp.json',                 path: resJ(cwd, '.windsurf', 'mcp.json') },
+    { label: '.vscode/mcp.json (Copilot/Cline)',   path: resJ(cwd, '.vscode', 'mcp.json') },
+    { label: '~/.claude/mcp.json (global)',         path: resJ(home, '.claude', 'mcp.json'), global: true },
+  ];
+
+  let written = 0;
+  for (const { label: eLabel, path: ePath, global: isGlobal } of editorFiles) {
+    // Only write project configs if the directory exists (or global)
+    const dir = dirJ(ePath);
+    if (!isGlobal && !exJ(dir) && !exJ(ePath)) continue;
+    try {
+      await mkJ(dir, { recursive: true });
+      let cfg: Record<string, unknown> = {};
+      if (exJ(ePath)) {
+        try {
+          cfg = JSON.parse(await rfJ(ePath, 'utf-8')) as Record<string, unknown>;
+        } catch {
+          try { await (await import('node:fs/promises')).rename(ePath, ePath + '.bak'); } catch { /* backup failed */ }
+        }
+      }
+      // Update or create the cachly entry with the shared instance ID
+      const servers = (cfg['mcpServers'] ?? {}) as Record<string, unknown>;
+      const existing = (servers['cachly'] ?? {}) as Record<string, unknown>;
+      const env = (existing['env'] ?? {}) as Record<string, string>;
+      env['CACHLY_BRAIN_INSTANCE_ID'] = instance_id;
+      if (joinJwt && !env['CACHLY_JWT']) env['CACHLY_JWT'] = joinJwt;
+      env['CACHLY_API_URL'] ??= 'https://api.cachly.dev';
+      servers['cachly'] = { ...existing, command: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'], env };
+      cfg['mcpServers'] = servers;
+      await wfJ(ePath, JSON.stringify(cfg, null, 2), 'utf-8');
+      console.log(`  ✅ ${eLabel}`);
+      written++;
+    } catch (joinWriteErr) {
+      // Only surface unexpected errors — missing editor dirs are expected and silently skipped above
+      if ((joinWriteErr as NodeJS.ErrnoException).code !== 'ENOENT') {
+        console.log(`  ⚠️  ${eLabel}: ${(joinWriteErr as Error).message}`);
+      }
+    }
+  }
+
+  console.log('');
+  if (written === 0) {
+    console.log('  ⚠️  No editor configs found — run `cachly setup` first.\n');
+  } else {
+    console.log(`  🧠 You're now sharing Brain: \x1b[1m${instance_name}\x1b[0m`);
+    console.log('     Restart your editor — your AI arrives pre-briefed from the team Brain.\n');
+    console.log('  📛 Add the badge to your README:');
+    console.log(`     npx @cachly-dev/mcp-server@latest badge\n`);
+  }
+  process.exit(0);
+}
+
+// ── CLI: cachly upgrade ───────────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest upgrade
+// Checks npm for the latest version and prints upgrade instructions if outdated.
+
+if (process.argv[2] === 'upgrade') {
+  process.stdout.write('\n⏳ Checking for updates...\n');
+  try {
+    const res = await fetch('https://registry.npmjs.org/@cachly-dev/mcp-server/latest', {
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!res.ok) throw new Error(`registry HTTP ${res.status}`);
+    const pkg = await res.json() as { version?: string };
+    const latest = pkg.version;
+    if (!latest || !/^\d+\.\d+\.\d+/.test(latest)) throw new Error('npm registry returned unexpected response');
+
+    if (latest === CURRENT_VERSION) {
+      console.log(`\n✅ Already on the latest version: \x1b[32mv${CURRENT_VERSION}\x1b[0m\n`);
+    } else {
+      console.log('');
+      console.log('\x1b[35m  ╔══════════════════════════════════════════════════════╗\x1b[0m');
+      console.log('\x1b[35m  ║\x1b[0m  \x1b[1m🧠 cachly update available\x1b[0m                       \x1b[35m║\x1b[0m');
+      console.log('\x1b[35m  ╚══════════════════════════════════════════════════════╝\x1b[0m');
+      console.log('');
+      console.log(`  Current : \x1b[31mv${CURRENT_VERSION}\x1b[0m`);
+      console.log(`  Latest  : \x1b[32mv${latest}\x1b[0m`);
+      console.log('');
+      console.log('  Update your editor configs to pick up the new version:');
+      console.log('');
+      console.log('  \x1b[32m  npx @cachly-dev/mcp-server@latest setup\x1b[0m');
+      console.log('');
+      console.log('  \x1b[2m(npx always fetches the latest when @latest is specified)\x1b[0m');
+      console.log('');
+    }
+  } catch (e) {
+    console.log(`\n❌ Could not check for updates: ${(e as Error).message}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── CLI: cachly demo ──────────────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest demo
+// Zero-signup. Reads local git history and shows what the AI Brain would know.
+// The fastest path from "what is this?" to "I need this".
+
+if (process.argv[2] === 'demo') {
+  const { execSync } = await import('node:child_process');
+  const { existsSync, readFileSync } = await import('node:fs');
+  const { resolve, basename } = await import('node:path');
+  const cwd = process.cwd();
+
+  console.log('\n\x1b[35m🧠 cachly Brain — Live Demo\x1b[0m');
+  console.log('\x1b[90mNo account needed. Reading your git history...\x1b[0m\n');
+
+  // Verify git repo
+  if (!existsSync(resolve(cwd, '.git'))) {
+    console.log('⚠️  No git repository found here.');
+    console.log('   Run this command inside a project directory with git history.\n');
+    console.log('   Example: cd ~/my-project && npx @cachly-dev/mcp-server@latest demo\n');
+    process.exit(0);
+  }
+
+  // Get developer name from git config
+  let devName = '';
+  try {
+    devName = execSync('git config user.name', { cwd, encoding: 'utf-8', stdio: 'pipe' }).trim().split(' ')[0] ?? '';
+  } catch { /* ignore */ }
+
+  // Get project name from package.json or directory name
+  let projectName = basename(cwd);
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(cwd, 'package.json'), 'utf-8')) as { name?: string };
+    if (pkg.name) projectName = pkg.name.replace(/^@[^/]+\//, '');
+  } catch { /* ignore */ }
+
+  // Read git log
+  let logOutput = '';
+  try {
+    logOutput = execSync(
+      'git log HEAD --pretty=format:"%H|||%s|||%ad|||%an" --date=short --no-merges -n 200',
+      { cwd, encoding: 'utf-8', stdio: 'pipe' }
+    );
+  } catch {
+    console.log('⚠️  Could not read git log. Make sure you have commits.\n');
+    process.exit(0);
+  }
+
+  const commits = logOutput.trim().split('\n').filter(Boolean).map(line => {
+    const [sha, subject, date, author] = line.split('|||');
+    return { sha: (sha ?? '').trim().slice(0, 8), subject: (subject ?? '').trim(), date: (date ?? '').trim(), author: (author ?? '').trim() };
+  });
+
+  if (commits.length === 0) {
+    console.log('⚠️  No commits found.\n');
+    process.exit(0);
+  }
+
+  // Classify commits (same logic as brain_from_git)
+  const classify = (s: string) => {
+    const t = s.toLowerCase();
+    if (/\b(fix|fixed|bug|hotfix|patch|revert|resolve)\b/.test(t)) return 'fix';
+    if (/\b(feat|feature|add|implement|new|introduce)\b/.test(t)) return 'feat';
+    if (/\b(perf|optim|speed|cache|latency)\b/.test(t)) return 'perf';
+    if (/\b(security|cve|auth|csrf|xss|inject|sanitize)\b/.test(t)) return 'security';
+    if (/\b(deploy|ci|cd|docker|k8s|infra)\b/.test(t)) return 'deploy';
+    if (/\b(refactor|clean|simplify|extract)\b/.test(t)) return 'refactor';
+    return 'chore';
+  };
+
+  // Count categories
+  const cats = new Map<string, number>();
+  const fixes: string[] = [];
+  const feats: string[] = [];
+  const security: string[] = [];
+  const authors = new Set<string>();
+
+  for (const c of commits) {
+    const cat = classify(c.subject);
+    cats.set(cat, (cats.get(cat) ?? 0) + 1);
+    if (cat === 'fix' && fixes.length < 5) fixes.push(c.subject.slice(0, 72));
+    if (cat === 'feat' && feats.length < 5) feats.push(c.subject.slice(0, 72));
+    if (cat === 'security' && security.length < 3) security.push(c.subject.slice(0, 72));
+    if (c.author) authors.add(c.author.split(' ')[0]!);
+  }
+
+  const totalLessons = commits.length - (cats.get('chore') ?? 0);
+  const dateRange = `${commits[commits.length - 1]?.date ?? '?'} → ${commits[0]?.date ?? '?'}`;
+
+  // Estimate time wasted re-explaining (45 min/day * workdays since first commit)
+  const firstDate = commits[commits.length - 1]?.date;
+  let daysActive = 0;
+  if (firstDate) {
+    const ms = Date.now() - new Date(firstDate).getTime();
+    daysActive = Math.max(1, Math.round(ms / (1000 * 60 * 60 * 24) * 5 / 7)); // workdays
+  }
+  const hoursWasted = Math.round(daysActive * 0.75); // 45 min/day
+
+  // Brain Level based on total lessons (matches Go ComputeBrainLevel thresholds)
+  const brainLevelName = totalLessons >= 501 ? 'Oracle' : totalLessons >= 201 ? 'Architect' : totalLessons >= 51 ? 'Expert' : totalLessons >= 11 ? 'Explorer' : 'Apprentice';
+
+  // Personalized header
+  const greeting = devName ? `Hey ${devName} — ` : '';
+  const headerTitle = `${greeting}here's what your AI would know about ${projectName}`;
+
+  // Display the demo
+  process.stdout.write('\x1b[2K\r');
+  console.log('┌─────────────────────────────────────────────────────────────┐');
+  console.log(`│  \x1b[1m🧠 ${headerTitle.slice(0, 58).padEnd(58)}\x1b[0m│`);
+  console.log('├─────────────────────────────────────────────────────────────┤');
+  console.log(`│  Commits analysed : \x1b[33m${String(commits.length).padEnd(6)}\x1b[0m  Date range: \x1b[90m${dateRange.slice(0, 23).padEnd(23)}\x1b[0m  │`);
+  console.log(`│  Lessons extracted: \x1b[32m${String(totalLessons).padEnd(6)}\x1b[0m  Contributors: \x1b[36m${String(authors.size).padEnd(20)}\x1b[0m│`);
+  console.log(`│  Brain Level      : \x1b[35m${brainLevelName.padEnd(14)}\x1b[0m  Time wasted re-explaining: \x1b[31m${String(hoursWasted + 'h').padEnd(5)}\x1b[0m│`);
+  console.log('├─────────────────────────────────────────────────────────────┤');
+
+  // Category breakdown
+  const sorted = [...cats.entries()].filter(([k]) => k !== 'chore').sort((a, b) => b[1] - a[1]);
+  const bar = (n: number, max: number) => '█'.repeat(Math.round((n / max) * 20)).padEnd(20);
+  const maxVal = Math.max(...sorted.map(([, v]) => v), 1);
+  console.log('│  \x1b[90mCategory breakdown:\x1b[0m                                         │');
+  for (const [cat, count] of sorted) {
+    const emoji = { fix: '🔧', feat: '✨', perf: '⚡', security: '🔒', deploy: '🚀', refactor: '🔄' }[cat] ?? '•';
+    console.log(`│  ${emoji} \x1b[36m${cat.padEnd(10)}\x1b[0m \x1b[35m${bar(count, maxVal)}\x1b[0m \x1b[33m${String(count).padStart(3)}\x1b[0m  │`);
+  }
+
+  if (security.length > 0) {
+    console.log('├─────────────────────────────────────────────────────────────┤');
+    console.log('│  \x1b[31m🔒 Security fixes your AI would know:\x1b[0m                       │');
+    for (const s of security) console.log(`│  \x1b[90m• ${s.slice(0, 58).padEnd(58)}\x1b[0m │`);
+  }
+
+  if (fixes.length > 0) {
+    console.log('├─────────────────────────────────────────────────────────────┤');
+    console.log('│  \x1b[33m🔧 Bug fixes your AI would never repeat:\x1b[0m                    │');
+    for (const f of fixes.slice(0, 4)) console.log(`│  \x1b[90m• ${f.slice(0, 58).padEnd(58)}\x1b[0m │`);
+  }
+
+  if (feats.length > 0) {
+    console.log('├─────────────────────────────────────────────────────────────┤');
+    console.log('│  \x1b[32m✨ Features & decisions it would recall:\x1b[0m                    │');
+    for (const f of feats.slice(0, 3)) console.log(`│  \x1b[90m• ${f.slice(0, 58).padEnd(58)}\x1b[0m │`);
+  }
+
+  console.log('├─────────────────────────────────────────────────────────────┤');
+  console.log('│  \x1b[32m💡 With cachly, your AI arrives pre-briefed every session.\x1b[0m  │');
+  console.log('│  \x1b[32m   No more re-explaining. No more repeated mistakes.\x1b[0m         │');
+  console.log('└─────────────────────────────────────────────────────────────┘');
+  console.log('');
+  // Generate shareable preview URL with encoded stats
+  const previewParams = new URLSearchParams({
+    repo: projectName,
+    commits: String(commits.length),
+    lessons: String(totalLessons),
+    level: brainLevelName,
+    authors: String(authors.size),
+    hours: String(hoursWasted),
+  });
+  const previewURL = `https://cachly.dev/preview?${previewParams.toString()}`;
+
+  console.log('  \x1b[1mMake this permanent (free, 1–5 minutes):\x1b[0m');
+  console.log('  \x1b[32m$ npx @cachly-dev/mcp-server@latest setup\x1b[0m');
+  console.log('');
+  console.log(`  \x1b[90m🔗 Shareable preview:\x1b[0m \x1b[36m${previewURL}\x1b[0m`);
+  console.log('');
+  console.log('  Works with: Claude Code · Cursor · Windsurf · Copilot · Cline · Zed');
+  console.log('  Free forever · GDPR · German servers · No credit card');
+  console.log('');
+  process.exit(0);
+}
+
+// ── CLI: cachly share ─────────────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest share
+// Generates a shareable ASCII card + tweet text with your Brain stats.
+
+if (process.argv[2] === 'share') {
+  const apiKey = process.env.CACHLY_JWT ?? '';
+  const instanceId = process.env.CACHLY_BRAIN_INSTANCE_ID ?? '';
+
+  if (!apiKey || !instanceId) {
+    console.log('\n⚠️  CACHLY_JWT and CACHLY_BRAIN_INSTANCE_ID must be set.');
+    console.log('   Run: npx @cachly-dev/mcp-server@latest setup  (takes 1–5 minutes)\n');
+    process.exit(1);
+  }
+
+  process.stdout.write('\n🧠 Fetching your Brain stats...\n');
+
+  try {
+    const statsRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/brain/stats`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(8000),
+    });
+
+    if (!statsRes.ok) throw new Error(`HTTP ${statsRes.status}`);
+    const stats = await statsRes.json() as {
+      lesson_count?: number; context_count?: number;
+      quality_score?: number; total_recall_count?: number;
+    };
+
+    const lessons  = stats.lesson_count ?? 0;
+    const recalls  = stats.total_recall_count ?? 0;
+    const score    = Math.round((stats.quality_score ?? 0) * 100);
+    const tokensSaved = recalls * 1200;
+    const costSaved = (tokensSaved * 0.000003).toFixed(2);
+
+    const level = lessons === 0 ? 'Intern 🌱' :
+      lessons < 10  ? 'Junior Dev 🔧' :
+      lessons < 30  ? 'Mid Dev ⚡' :
+      lessons < 60  ? 'Senior Dev 🧠' :
+      lessons < 100 ? 'Staff Eng 🚀' : 'Principal Eng 🏆';
+
+    console.log('');
+    console.log('┌─────────────────────────────────────────────────────────────┐');
+    console.log('│  🧠 My AI Brain  ·  powered by \x1b[35mcachly.dev\x1b[0m                   │');
+    console.log('├─────────────────────────────────────────────────────────────┤');
+    console.log(`│  Lessons stored : \x1b[33m${String(lessons).padEnd(8)}\x1b[0m  Brain level: \x1b[32m${level.padEnd(18)}\x1b[0m│`);
+    console.log(`│  Total recalls  : \x1b[36m${String(recalls).padEnd(8)}\x1b[0m  Quality score: \x1b[32m${String(score).padEnd(3)}%\x1b[0m              │`);
+    console.log(`│  Tokens saved   : \x1b[32m${String((tokensSaved / 1000).toFixed(0) + 'K').padEnd(8)}\x1b[0m  Cost saved: \x1b[32m$${costSaved.padEnd(20)}\x1b[0m│`);
+    console.log('├─────────────────────────────────────────────────────────────┤');
+    console.log('│  Works with: Claude Code · Cursor · Windsurf · Copilot      │');
+    console.log('│  Free · GDPR · German servers                                │');
+    console.log('│  \x1b[35mnpx @cachly-dev/mcp-server@latest setup\x1b[0m                     │');
+    console.log('└─────────────────────────────────────────────────────────────┘');
+    console.log('');
+
+    // Tweet text
+    const shareUrl = 'https://cachly.dev?ref=share&utm_source=x&utm_medium=social&utm_campaign=cli-share';
+    const tweet = `🧠 My AI coding assistant now has persistent memory.\n\n${lessons} lessons stored · ${recalls} recalls · ${level}\n\nFix a bug once → AI remembers forever. Across Claude Code, Cursor, Windsurf, Copilot.\n\n${shareUrl}\n\n#AIMemory #ClaudeCode #Cursor #DeveloperTools`;
+
+    console.log('  \x1b[1m📋 Share on Twitter/X (copy this):\x1b[0m');
+    console.log('  ─────────────────────────────────────');
+    console.log(tweet.split('\n').map(l => `  ${l}`).join('\n'));
+    console.log('  ─────────────────────────────────────');
+    console.log('');
+    console.log('  \x1b[2mPro tip: add a screenshot of your Brain panel for 3x more engagement\x1b[0m');
+    console.log('  \x1b[2mAlso add a live badge to your README:\x1b[0m');
+    console.log(`  \x1b[90m  npx @cachly-dev/mcp-server@latest badge\x1b[0m`);
+    console.log('');
+  } catch (e) {
+    console.log(`\n❌ Could not fetch stats: ${(e as Error).message}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── CLI: cachly badge ─────────────────────────────────────────────────────────
+// Outputs the Markdown + HTML snippet for embedding a live Brain lesson-count
+// badge in any README or website. Badge SVG served by cachly API (public, no auth).
+
+if (process.argv[2] === 'badge') {
+  const instanceId = process.env.CACHLY_BRAIN_INSTANCE_ID ?? '';
+
+  if (!instanceId) {
+    console.log('\n⚠️  CACHLY_BRAIN_INSTANCE_ID must be set.');
+    console.log('   Run: npx @cachly-dev/mcp-server@latest setup  (takes 1–5 minutes)\n');
+    process.exit(1);
+  }
+
+  const badgeUrl   = `${API_URL}/api/v1/badge/${instanceId}`;
+  const targetUrl  = 'https://cachly.dev';
+  const markdown   = `[![cachly Brain](${badgeUrl})](${targetUrl})`;
+  const htmlBadge  = `<a href="${targetUrl}"><img src="${badgeUrl}" alt="cachly Brain" /></a>`;
+
+  console.log('');
+  console.log('\x1b[35m  ╔═══════════════════════════════════════════════════════╗\x1b[0m');
+  console.log('\x1b[35m  ║\x1b[0m  \x1b[1m🧠 cachly Brain Badge\x1b[0m                              \x1b[35m║\x1b[0m');
+  console.log('\x1b[35m  ╚═══════════════════════════════════════════════════════╝\x1b[0m');
+  console.log('');
+  console.log('  Paste into your README.md:');
+  console.log('');
+  console.log(`  \x1b[32m${markdown}\x1b[0m`);
+  console.log('');
+  console.log('  ─────────────────────────────────────────────────────');
+  console.log('  Or paste into HTML:');
+  console.log('');
+  console.log(`  \x1b[36m${htmlBadge}\x1b[0m`);
+  console.log('');
+  console.log('  ─────────────────────────────────────────────────────');
+  console.log('  Badge URL (live, updates every hour):');
+  console.log(`  \x1b[90m${badgeUrl}\x1b[0m`);
+  console.log('');
+  console.log('  \x1b[2mThe badge shows your current lesson count — no auth required,');
+  console.log('  safe to embed in public repos. Updates hourly.\x1b[0m');
+  console.log('');
+  process.exit(0);
+}
+
+// ── CLI: no-args splash screen ────────────────────────────────────────────────
+// When run with no recognized subcommand, show a compelling pitch + help.
+
+if (!process.argv[2] && process.stdout.isTTY) {
+  console.log('');
+  console.log('\x1b[35m  ╔═══════════════════════════════════════════════════════╗\x1b[0m');
+  console.log('\x1b[35m  ║\x1b[0m  \x1b[1m🧠 cachly — Persistent AI Memory for Developers\x1b[0m   \x1b[35m║\x1b[0m');
+  console.log('\x1b[35m  ╚═══════════════════════════════════════════════════════╝\x1b[0m');
+  console.log('');
+  console.log('  Stop re-teaching your AI every morning.');
+  console.log('  cachly gives it a permanent brain — pre-briefed every session.');
+  console.log('');
+  console.log('  \x1b[1mCommands:\x1b[0m');
+  console.log('  \x1b[32m  npx @cachly-dev/mcp-server@latest demo\x1b[0m     ← Start here (no account)');
+  console.log('  \x1b[32m  npx @cachly-dev/mcp-server@latest setup\x1b[0m    ← Wire up your AI editors');
+  console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest health\x1b[0m   ← Check everything works');
+  console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest digest\x1b[0m   ← Weekly Brain summary');
+  console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest share\x1b[0m    ← Share your Brain stats');
+  console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest badge\x1b[0m    ← README badge for your Brain');
+  console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest invite\x1b[0m   ← Invite a teammate');
+  console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest join <token>\x1b[0m ← Accept a Brain invite');
+  console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest upgrade\x1b[0m  ← Check for updates');
+  console.log('');
+  console.log('  \x1b[90mWorks with: Claude Code · Cursor · Windsurf · GitHub Copilot · Cline · Zed\x1b[0m');
+  console.log('  \x1b[90mFree forever · GDPR · German servers · 89 MCP tools\x1b[0m');
+  console.log('');
+  process.exit(0);
+}
+
 // ── CLI: cachly init ──────────────────────────────────────────────────────────
 // Usage: npx @cachly-dev/mcp-server init --instance-id <id> --api-key <key> [--editor claude|cursor|windsurf|copilot|continue] [--project-dir /path]
 
@@ -1087,11 +1798,11 @@ if (process.argv[2] === 'init') {
 
   const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
   const configPath = resolve(projectDir, configFile);
-  const mergeResult = await writeMergedMcpConfig(configPath, apiKey, instanceId, editor);
-  const verb = mergeResult === 'created' ? '✅ Written'
-             : mergeResult === 'updated' ? '✅ Updated (kept existing servers)'
-             : '✅ Merged into existing config (other servers untouched)';
-  console.log(`\n${verb}: ${configFile}`);
+  await mkdir(dirname(configPath), { recursive: true });
+  const { existsSync: exInit } = await import('node:fs');
+  const merged = await mergeMcpConfig(configPath, apiKey, instanceId, editor, { readFile, existsSync: exInit });
+  await writeFile(configPath, merged, 'utf-8');
+  console.log(`\n✅ ${exInit(configPath) ? 'Updated' : 'Written'}: ${configFile}`);
 
   // Always write CLAUDE.md (idempotent — safe to run multiple times)
   const result = await writeClaudeMd(projectDir, instanceId);
@@ -1134,7 +1845,282 @@ if (process.argv[2] === 'init') {
   } catch { /* non-critical — git hook is a best-effort feature */ }
 
   console.log(`\n🧠 Cachly AI Brain configured for ${editor === 'claude' ? 'Claude Code' : editor}!`);
-  console.log(`   Restart your editor — the \`cachly\` MCP tools will appear.\n`);
+  console.log(`   Restart your editor — the \`cachly\` MCP tools will appear.`);
+  console.log(`\n   📛 Add a live badge to your README:`);
+  console.log(`      npx @cachly-dev/mcp-server@latest badge\n`);
+  process.exit(0);
+}
+
+// ── CLI: cachly health ────────────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest health
+// Checks: JWT valid, Brain API reachable, editor configs found, git hook present.
+
+// ── CLI: cachly status ────────────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest status
+// Shows Brain health, team size, and quick stats at a glance.
+
+if (process.argv[2] === 'status') {
+  const apiKey = process.env.CACHLY_JWT ?? '';
+  const instanceId = process.env.CACHLY_BRAIN_INSTANCE_ID ?? '';
+
+  if (!apiKey || !instanceId) {
+    console.log('\n⚠️  CACHLY_JWT and CACHLY_BRAIN_INSTANCE_ID must be set.');
+    console.log('   Run: npx @cachly-dev/mcp-server@latest setup\n');
+    process.exit(1);
+  }
+
+  try {
+    const [statsRes, referralRes] = await Promise.all([
+      fetch(`${API_URL}/api/v1/instances/${instanceId}/brain/stats`, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+        signal: AbortSignal.timeout(8000),
+      }),
+      fetch(`${API_URL}/api/v1/referral/me`, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+        signal: AbortSignal.timeout(8000),
+      }),
+    ]);
+
+    if (!statsRes.ok) throw new Error(`stats HTTP ${statsRes.status}`);
+    const stats = await statsRes.json() as {
+      lesson_count?: number; total_recall_count?: number;
+      quality_score?: number; team_authors?: string[];
+    };
+    const referral = referralRes.ok
+      ? await referralRes.json() as { url?: string; referral_count?: number }
+      : null;
+
+    const lessons = stats.lesson_count ?? 0;
+    const recalls = stats.total_recall_count ?? 0;
+    const score   = Math.round((stats.quality_score ?? 0) * 100);
+    const team    = stats.team_authors ?? [];
+    const refCount = referral?.referral_count ?? 0;
+    const refUrl   = referral?.url ?? '';
+
+    const level = lessons === 0 ? 'Intern 🌱' :
+      lessons < 10  ? 'Junior Dev 🔧' :
+      lessons < 30  ? 'Mid Dev ⚡' :
+      lessons < 60  ? 'Senior Dev 🧠' :
+      lessons < 100 ? 'Staff Eng 🚀' : 'Principal Eng 🏆';
+
+    const statusIcon = lessons > 0 ? '\x1b[32m●\x1b[0m' : '\x1b[33m●\x1b[0m';
+
+    console.log('');
+    console.log('┌─────────────────────────────────────────────────────────────┐');
+    console.log(`│  ${statusIcon} \x1b[1mBrain status\x1b[0m · instance ${instanceId.slice(0, 8)}...              │`);
+    console.log('├─────────────────────────────────────────────────────────────┤');
+    console.log(`│  Lessons       : \x1b[33m${String(lessons).padEnd(8)}\x1b[0m  Level        : \x1b[32m${level.padEnd(18)}\x1b[0m│`);
+    console.log(`│  Recalls       : \x1b[36m${String(recalls).padEnd(8)}\x1b[0m  Quality score: \x1b[32m${String(score).padEnd(3)}%\x1b[0m              │`);
+
+    if (team.length > 0) {
+      console.log('├─────────────────────────────────────────────────────────────┤');
+      const teamStr = team.slice(0, 4).join(', ');
+      console.log(`│  \x1b[36m👥 Team Brain\x1b[0m · ${String(team.length).padEnd(2)} developer${team.length === 1 ? ' ' : 's'} sharing lessons${' '.repeat(Math.max(0, 19 - teamStr.length))} │`);
+      console.log(`│     ${teamStr.slice(0, 56).padEnd(56)} │`);
+    }
+
+    if (refUrl) {
+      console.log('├─────────────────────────────────────────────────────────────┤');
+      const refLine = `${refUrl.slice(0, 44)}${refUrl.length > 44 ? '…' : ''}`;
+      console.log(`│  \x1b[35m🔗 Invite link\x1b[0m · ${refCount > 0 ? `\x1b[32m${refCount} joined\x1b[0m` : 'share to grow your team'}${' '.repeat(Math.max(0, 35 - String(refCount).length))} │`);
+      console.log(`│     \x1b[2m${refLine.padEnd(56)}\x1b[0m │`);
+    }
+
+    console.log('└─────────────────────────────────────────────────────────────┘');
+    console.log('');
+    if (lessons === 0) {
+      console.log('  \x1b[33m💡 No lessons yet.\x1b[0m Run a session with cachly connected to start learning.');
+      console.log('');
+    }
+  } catch (e) {
+    console.log(`\n❌ Could not fetch status: ${(e as Error).message}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (process.argv[2] === 'health') {
+  const { existsSync } = await import('node:fs');
+  const { readFile } = await import('node:fs/promises');
+  const { resolve, join: pJoin } = await import('node:path');
+
+  const cwd = process.cwd();
+  let passed = 0;
+  let failed = 0;
+
+  const ok  = (msg: string) => { console.log(`  ✅ ${msg}`); passed++; };
+  const warn = (msg: string) => { console.log(`  ⚠️  ${msg}`); };
+  const fail = (msg: string) => { console.log(`  ❌ ${msg}`); failed++; };
+
+  console.log('\n🧠 cachly health check\n');
+
+  // ── 1. JWT token ────────────────────────────────────────────────────────────
+  console.log('🔑 Auth token');
+  const jwt = process.env.CACHLY_JWT ?? '';
+  if (!jwt) {
+    fail('CACHLY_JWT not set — run: npx @cachly-dev/mcp-server@latest setup');
+  } else {
+    try {
+      const parts = jwt.split('.');
+      if (parts.length !== 3) throw new Error('not a JWT');
+      const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8')) as {
+        sub?: string; exp?: number;
+      };
+      const expMs = payload.exp ? payload.exp * 1000 : null;
+      const minsLeft = expMs ? Math.floor((expMs - Date.now()) / 60_000) : null;
+      if (expMs && expMs < Date.now()) {
+        fail(`JWT expired ${Math.abs(minsLeft!)} minute(s) ago — get a new one: https://cachly.dev/setup-ai`);
+      } else if (minsLeft !== null && minsLeft < 30) {
+        warn(`JWT expires in ${minsLeft} minute(s) — refresh soon at https://cachly.dev/setup-ai`);
+      } else {
+        ok(`JWT valid${minsLeft !== null ? ` (expires in ${Math.floor(minsLeft / 60)}h ${minsLeft % 60}m)` : ''}`);
+      }
+    } catch {
+      fail('CACHLY_JWT format invalid (expected JWT with 3 parts)');
+    }
+  }
+
+  // ── 2. Brain API reachability ───────────────────────────────────────────────
+  console.log('\n🌐 Brain API');
+  const apiUrl = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
+  try {
+    const res = await fetch(`${apiUrl}/health`, { signal: AbortSignal.timeout(5000) });
+    if (res.ok) {
+      const body = await res.json() as { status?: string };
+      ok(`${apiUrl} reachable (status: ${body.status ?? 'ok'})`);
+    } else if (res.status === 401 || res.status === 403) {
+      ok(`${apiUrl} reachable (auth required — expected)`);
+    } else {
+      fail(`${apiUrl}/health returned HTTP ${res.status}`);
+    }
+  } catch (e) {
+    fail(`${apiUrl} unreachable — ${(e as Error).message}`);
+  }
+
+  // ── 3. Brain instance ───────────────────────────────────────────────────────
+  console.log('\n🧠 Brain instance');
+  const instanceId = process.env.CACHLY_BRAIN_INSTANCE_ID ?? '';
+  if (!instanceId) {
+    warn('CACHLY_BRAIN_INSTANCE_ID not set — will auto-resolve on first tool call');
+  } else if (jwt) {
+    try {
+      const instRes = await fetch(`${apiUrl}/api/v1/instances/${instanceId}`, {
+        headers: { Authorization: `Bearer ${jwt}`, Accept: 'application/json' },
+        signal: AbortSignal.timeout(5000),
+      });
+      if (instRes.ok) {
+        const inst = await instRes.json() as { name?: string; status?: string; host?: string; port?: number; tls_enabled?: boolean };
+        if (inst.status === 'running') {
+          ok(`Instance "${inst.name}" (${instanceId.slice(0, 8)}…) is running`);
+          // Attempt actual Redis PING to verify connectivity end-to-end
+          console.log('\n🔌 Redis connectivity');
+          if (inst.host && inst.port) {
+            try {
+              let pingPassword: string | undefined;
+              let pingTls = inst.tls_enabled !== false;
+              try {
+                const connRes = await fetch(`${apiUrl}/api/v1/instances/${instanceId}/connection`, {
+                  headers: { Authorization: `Bearer ${jwt}`, Accept: 'application/json' },
+                  signal: AbortSignal.timeout(5000),
+                });
+                if (connRes.ok) {
+                  const conn = await connRes.json() as { password?: string; tls_enabled?: boolean };
+                  pingPassword = conn.password;
+                  pingTls = conn.tls_enabled !== false;
+                }
+              } catch { /* proceed without password */ }
+              const pingClient = new Redis({
+                host: inst.host, port: inst.port,
+                password: pingPassword,
+                ...(pingTls ? { tls: {} } : {}),
+                lazyConnect: true, connectTimeout: 5000, retryStrategy: () => null,
+              });
+              await pingClient.connect();
+              const pong = await pingClient.ping();
+              pingClient.disconnect();
+              if (pong === 'PONG') {
+                ok(`Redis PING → PONG (${inst.host}:${inst.port})`);
+              } else {
+                warn(`Redis responded but not PONG: ${pong}`);
+              }
+            } catch (pingErr) {
+              fail(`Redis unreachable — ${(pingErr as Error).message}`);
+            }
+          } else {
+            warn('Instance has no host/port yet');
+          }
+        } else {
+          warn(`Instance "${inst.name}" status: ${inst.status}`);
+        }
+      } else {
+        fail(`Instance ${instanceId.slice(0, 8)}… not found (HTTP ${instRes.status})`);
+      }
+    } catch (e) {
+      fail(`Could not check instance — ${(e as Error).message}`);
+    }
+  }
+
+  // ── 4. Editor configs ───────────────────────────────────────────────────────
+  console.log('\n🛠  Editor configs (project dir)');
+  const editorConfigs: Array<{ editor: string; path: string }> = [
+    { editor: 'Claude Code',     path: '.mcp.json' },
+    { editor: 'Cursor',          path: '.cursor/mcp.json' },
+    { editor: 'Windsurf',        path: '.windsurf/mcp.json' },
+    { editor: 'Copilot / Cline', path: '.vscode/mcp.json' },
+    { editor: 'Zed',             path: '.zed/settings.json' },
+    { editor: 'Continue.dev',    path: '.continue/config.json' },
+  ];
+  let configsFound = 0;
+  for (const { editor, path } of editorConfigs) {
+    const fullPath = resolve(cwd, path);
+    if (existsSync(fullPath)) {
+      try {
+        const content = await readFile(fullPath, 'utf-8');
+        const hasCachly = content.includes('@cachly-dev/mcp-server') || content.includes('cachly');
+        if (hasCachly) {
+          ok(`${editor}: ${path}`);
+          configsFound++;
+        } else {
+          warn(`${editor}: ${path} exists but cachly not found inside`);
+        }
+      } catch {
+        warn(`${editor}: ${path} exists but could not read`);
+      }
+    }
+  }
+  if (configsFound === 0) {
+    fail('No editor MCP configs found — run: npx @cachly-dev/mcp-server@latest setup');
+  }
+
+  // ── 5. Git hook ─────────────────────────────────────────────────────────────
+  console.log('\n🪝 Git hook (ambient learning)');
+  const hookPath = resolve(cwd, '.git', 'hooks', 'post-commit');
+  if (!existsSync(resolve(cwd, '.git'))) {
+    warn('Not in a git repository — skip');
+  } else if (existsSync(hookPath)) {
+    try {
+      const hook = await readFile(hookPath, 'utf-8');
+      if (hook.includes('cachly')) {
+        ok('.git/hooks/post-commit (cachly CLS hook present)');
+      } else {
+        warn('.git/hooks/post-commit exists but cachly hook not found — run setup to add it');
+      }
+    } catch {
+      warn('.git/hooks/post-commit exists but could not read');
+    }
+  } else {
+    warn('.git/hooks/post-commit not found — run: npx @cachly-dev/mcp-server@latest setup');
+  }
+
+  // ── Summary ─────────────────────────────────────────────────────────────────
+  console.log(`\n${'─'.repeat(40)}`);
+  if (failed === 0) {
+    console.log(`✅ All checks passed (${passed} ok)\n`);
+  } else {
+    console.log(`❌ ${failed} check(s) failed, ${passed} passed\n`);
+    console.log(`💡 Fix issues with: npx @cachly-dev/mcp-server@latest setup\n`);
+    process.exit(1);
+  }
   process.exit(0);
 }
 
@@ -1147,6 +2133,8 @@ if (process.argv[2] === 'setup') {
   const { resolve, dirname } = await import('node:path');
   const { createInterface } = await import('node:readline');
 
+  sendFunnelEvent('setup_started');
+
   // --yes / -y → non-interactive mode (skips all prompts, picks defaults)
   const nonInteractive = process.argv.includes('--yes') || process.argv.includes('-y');
 
@@ -1372,18 +2360,22 @@ if (process.argv[2] === 'setup') {
   console.log(`Step 3: Configuring for: ${editorsToSetup.map(editorLabel).join(', ')}\n`);
 
   // ── Step 4: Write editor configs (project-level) ─────────────────────────
-  // Critical: NEVER overwrite existing configs blindly — merge cachly into the
-  // existing mcpServers map so the user's other MCP servers (filesystem,
-  // github, postgres, …) are preserved. writeMergedMcpConfig also drops a
-  // .cachly-backup file next to the original for one-step recovery.
+  // Uses mergeMcpConfig to preserve all existing MCP servers — only adds/updates
+  // the cachly entry without touching filesystem, github, or other servers.
+  const { existsSync: exSetup } = await import('node:fs');
   for (const editor of editorsToSetup) {
     const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
     const configPath = resolve(cwd, configFile);
-    const result = await writeMergedMcpConfig(configPath, token, instance.id, editor);
-    const verb = result === 'created' ? '✅ Written'
-               : result === 'updated' ? '✅ Updated (kept existing servers)'
-               : '✅ Merged (other servers untouched)';
-    console.log(`${verb}: ${configFile}`);
+    try {
+      await mkdir(dirname(configPath), { recursive: true });
+      const wasExisting = exSetup(configPath);
+      const merged = await mergeMcpConfig(configPath, token, instance.id, editor, { readFile, existsSync: exSetup });
+      await writeFile(configPath, merged, 'utf-8');
+      console.log(`✅ ${wasExisting ? 'Updated' : 'Written'}: ${configFile}`);
+    } catch (writeErr) {
+      console.log(`⚠️  Could not write ${configFile}: ${(writeErr as Error).message}`);
+      console.log(`   Fix permissions or run with sudo, then re-run setup.`);
+    }
   }
 
   // ── Step 4b: Write global Claude Code config (~/.claude/mcp.json) ─────────
@@ -1424,8 +2416,8 @@ if (process.argv[2] === 'setup') {
       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,
+        repo_path: cwd,
+        limit: 100,
       });
       const match = gitResult.match(/(\d+) lesson/);
       console.log(` ✓  ${match ? match[1] + ' lessons' : 'done'} extracted from git history`);
@@ -1502,9 +2494,12 @@ if (process.argv[2] === 'setup') {
     }
   } catch { console.log(' (skipped)'); }
 
-  console.log(`\n🧠  Done! Restart your editor — the \`cachly\` MCP tools will appear.`);
-  console.log(`   Your AI now has persistent memory across every session.\n`);
-  console.log(`   Dashboard: https://cachly.dev/instances/${instance.id}\n`);
+  console.log(`\n🎉  Your AI just got a permanent brain.`);
+  console.log(`   Restart your editor — from this session on, it arrives pre-briefed.\n`);
+  console.log(`   No more re-explaining your stack. No repeated mistakes.\n`);
+  console.log(`   Dashboard: https://cachly.dev/instances/${instance.id}`);
+  console.log(`\n   📛 Add a live badge to your README:`);
+  console.log(`      npx @cachly-dev/mcp-server@latest badge\n`);
 
   // ── Step 7: Email opt-in (non-blocking — at the very end) ────────────────
   if (!nonInteractive) {
@@ -1554,7 +2549,13 @@ if (process.argv[2] === 'setup') {
     }
   } catch { /* non-critical */ }
 
+  // Setup reached the end successfully — close the funnel.
+  JWT = token;
+  sendFunnelEvent('setup_completed', { instance_id: instance.id });
+
   rl.close();
+  // Give the fire-and-forget telemetry a moment to flush before exit.
+  await new Promise(r => setTimeout(r, 300));
   process.exit(0);
 }
 
@@ -1600,12 +2601,59 @@ if (process.argv[2] === 'index') {
   process.exit(0);
 }
 
+// ── CLI: cachly learn-git ─────────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest learn-git [./repo] [--max-commits 50]
+// Auto-learns brain lessons from recent git commits — ideal for CI on PR merge.
+// Each meaningful commit becomes a lesson, so the Brain grows with zero manual work.
+
+if (process.argv[2] === 'learn-git') {
+  const { resolve } = await import('node:path');
+  const argv = process.argv.slice(3);
+  const flag = (name: string) => { const i = argv.indexOf(`--${name}`); return i !== -1 ? argv[i + 1] : undefined; };
+
+  const repoDir    = resolve(flag('dir') ?? argv.find(a => !a.startsWith('--')) ?? '.');
+  const instanceId = flag('instance-id') ?? process.env.CACHLY_BRAIN_INSTANCE_ID;
+  const maxCommits = parseInt(flag('max-commits') ?? '50', 10);
+
+  if (!instanceId || !JWT) {
+    console.error('\n❌  CACHLY_BRAIN_INSTANCE_ID and CACHLY_JWT must be set\n');
+    console.error('   export CACHLY_BRAIN_INSTANCE_ID=<uuid>');
+    console.error('   export CACHLY_JWT=<cky_live_...>');
+    console.error('   npx @cachly-dev/mcp-server@latest learn-git .\n');
+    process.exit(1);
+  }
+
+  console.log(`\n🧠  Learning from git history: ${repoDir}`);
+  console.log(`    Instance: ${instanceId.slice(0, 8)}…  Max commits: ${maxCommits}\n`);
+
+  try {
+    const result = await handleTool('brain_from_git', {
+      instance_id: instanceId,
+      repo_path: repoDir,
+      limit: maxCommits,
+    });
+    console.log(result);
+    sendFunnelEvent('brain_from_git', { api_key: JWT, instance_id: instanceId });
+    console.log('\n✅  Brain learned from your commits.\n');
+    // Let fire-and-forget telemetry flush before exit.
+    await new Promise(r => setTimeout(r, 300));
+  } catch (err) {
+    console.error(`\n❌  learn-git failed: ${(err as Error).message}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 // ── Start ─────────────────────────────────────────────────────────────────────
 
 // Warn on stderr when credentials are missing so the user sees a clear
 // actionable message in their editor's MCP log instead of silent failures.
-if (!JWT) {
-  process.stderr.write(
+// Skip for CLI commands that intentionally run without credentials.
+const _cliNoAuthCommands = ['demo', 'share', 'health', 'setup', 'init', 'digest', 'invite', 'badge', 'join', 'upgrade'];
+if (!JWT && !_cliNoAuthCommands.includes(process.argv[2] ?? '') && !(!process.argv[2] && process.stdout.isTTY)) {
+  // No args + no JWT in a non-TTY context = running as MCP server without credentials.
+  // Print actionable setup banner to stdout so it's captured by callers/tests.
+  const banner =
     '\n' +
     '╔══════════════════════════════════════════════════════════════════╗\n' +
     '║  🧠  cachly AI Brain — Setup required                           ║\n' +
@@ -1621,8 +2669,15 @@ if (!JWT) {
     '║                                                                  ║\n' +
     '║  Free tier — no credit card required.                           ║\n' +
     '╚══════════════════════════════════════════════════════════════════╝\n' +
-    '\n',
-  );
+    '\n';
+  // When invoked with no args as the main entry point, write to stdout + exit cleanly.
+  // When used as MCP server (args present), write to stderr so editors see it.
+  if (!process.argv[2] && _isMain) {
+    process.stdout.write(banner);
+    process.exit(0);
+  } else {
+    process.stderr.write(banner);
+  }
 } else {
   // Warn if the JWT is already expired or expiring within the hour.
   const expMs = jwtExpiryMs(JWT);