@cachly-dev/mcp-server 0.10.14 → 0.10.15

package/src/index.ts

@@ -53,7 +53,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.15';
 
 // ── Default Instance Resolution (for Smithery & single-credential setups) ────
 // When CACHLY_BRAIN_INSTANCE_ID is set, tools can omit the instance_id parameter.
@@ -635,33 +635,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 +644,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)' });
     } 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 +706,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 +724,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;
@@ -945,6 +875,415 @@ 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('│  \x1b[32m📋 Share this digest:\x1b[0m                                        │');
+    console.log('│  \x1b[90m   npx @cachly-dev/mcp-server@latest share\x1b[0m                   │');
+    console.log('│  \x1b[90m   Add more: npx @cachly-dev/mcp-server@latest invite\x1b[0m         │');
+    console.log('└─────────────────────────────────────────────────────────────┘');
+    console.log('');
+
+    // Pro tip for cron
+    console.log('  \x1b[2m💡 Automate: add to crontab for a weekly team email\x1b[0m');
+    console.log('  \x1b[2m   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') {
+  const { createInterface } = await import('node:readline');
+  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);
+  }
+
+  let email = process.argv[3] ?? '';
+
+  if (!email) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    email = await new Promise<string>((resolve) => {
+      rl.question('\n  📬 Teammate email to invite: ', (ans) => { rl.close(); resolve(ans.trim()); });
+    });
+  }
+
+  if (!email || !email.includes('@')) {
+    console.log('\n❌ Invalid email address.\n');
+    process.exit(1);
+  }
+
+  console.log(`\n  ⏳ Inviting ${email}...`);
+
+  try {
+    const res = await fetch(`${API_URL}/api/v1/team/invite`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, role: 'member', source: 'cli-invite' }),
+      signal: AbortSignal.timeout(8000),
+    });
+
+    if (res.ok) {
+      console.log(`\n  ✅ Invite sent to \x1b[32m${email}\x1b[0m`);
+      console.log(`     They'll get a link to join your Brain — one click, 30 seconds.\n`);
+      console.log(`  💡 Once they join, your AI assistants share lessons automatically.\n`);
+    } else if (res.status === 409) {
+      console.log(`\n  ✓  ${email} is already a team member.\n`);
+    } else {
+      const body = await res.json().catch(() => ({})) as { error?: string };
+      console.log(`\n  ❌ Invite failed: ${body.error ?? `HTTP ${res.status}`}\n`);
+      process.exit(1);
+    }
+  } catch (e) {
+    console.log(`\n  ❌ Network error: ${(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 } = await import('node:fs');
+  const { resolve } = 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);
+  }
+
+  // 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 ?? '?'}`;
+
+  // Display the demo
+  process.stdout.write('\x1b[2K\r');
+  console.log('┌─────────────────────────────────────────────────────────────┐');
+  console.log('│  \x1b[1m🧠 Brain Preview — What your AI would know\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('├─────────────────────────────────────────────────────────────┤');
+
+  // 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 remember:\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('');
+  console.log('  \x1b[1mMake this permanent (free, 30 seconds):\x1b[0m');
+  console.log('  \x1b[32m$ npx @cachly-dev/mcp-server@latest setup\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 30 seconds)\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 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\nnpx @cachly-dev/mcp-server@latest setup\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 30 seconds)\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('  Your AI forgets everything when a session ends.');
+  console.log('  cachly gives it a brain that survives forever.');
+  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('');
+  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]
 
@@ -1018,6 +1357,158 @@ if (process.argv[2] === 'init') {
   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.
+
+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 };
+        if (inst.status === 'running') {
+          ok(`Instance "${inst.name}" (${instanceId.slice(0, 8)}…) is running`);
+        } 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);
+}
+
 // ── CLI: cachly setup (interactive — no flags required) ───────────────────────
 // Usage: npx @cachly-dev/mcp-server setup
 
@@ -1478,7 +1969,9 @@ if (process.argv[2] === 'index') {
 
 // 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) {
+// Skip for CLI commands that intentionally run without credentials.
+const _cliNoAuthCommands = ['demo', 'share', 'health', 'setup', 'init', 'digest', 'invite', 'badge'];
+if (!JWT && !_cliNoAuthCommands.includes(process.argv[2] ?? '') && !(!process.argv[2] && process.stdout.isTTY)) {
   process.stderr.write(
     '\n' +
     '╔══════════════════════════════════════════════════════════════════╗\n' +