@cachly-dev/mcp-server 0.5.43 → 0.5.45

package/src/index.ts

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 import { randomUUID } from 'node:crypto';
+import { createHash } from 'node:crypto';
 import { readdir, readFile, stat } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
 import { join, relative, extname } from 'node:path';
 /**
- * cachly MCP Server v0.5.43
+ * cachly MCP Server v0.4.0
  *
  * Exposes cachly.dev as MCP tools so any AI assistant
  * (GitHub Copilot, Claude, Cursor, Windsurf, Continue.dev …) can:
@@ -31,7 +34,6 @@ import { join, relative, extname } from 'node:path';
  *
  * Configuration (env vars):
  *   CACHLY_API_URL      – default https://api.cachly.dev
- *   CACHLY_AUTH_URL     – default https://auth.cachly.dev (Keycloak base URL for health checks)
  *   CACHLY_JWT          – your JWT (Keycloak access token)
  *   CACHLY_EMBED_PROVIDER – embedding backend: openai (default), gemini, mistral, cohere, ollama, cachly (server fallback)
  *   CACHLY_EMBED_MODEL  – override embedding model (optional)
@@ -39,6 +41,7 @@ import { join, relative, extname } from 'node:path';
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import {
   CallToolRequestSchema,
   ErrorCode,
@@ -50,9 +53,9 @@ import { Redis } from 'ioredis';
 // ── Config ────────────────────────────────────────────────────────────────────
 
 const API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
-const AUTH_URL = process.env.CACHLY_AUTH_URL ?? 'https://auth.cachly.dev';
 const JWT = process.env.CACHLY_JWT ?? '';
 const EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
+const CURRENT_VERSION = '0.5.26';
 /**
  * ┌──────────────────────────────────────────────────────────────────────┐
  * │  EMBEDDING PROVIDER — pluggable, client-side first                  │
@@ -72,6 +75,44 @@ const EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
  */
 const EMBED_PROVIDER = (process.env.CACHLY_EMBED_PROVIDER ?? detectEmbedProvider()).toLowerCase();
 
+// ── Confidence Decay Config (all values configurable via env) ─────────────────
+const CONFIDENCE_WARN_DAYS  = Number(process.env.CACHLY_CONFIDENCE_WARN_DAYS  ?? 5);   // → 0.7
+const CONFIDENCE_STALE_DAYS = Number(process.env.CACHLY_CONFIDENCE_STALE_DAYS ?? 10);  // → 0.5
+const CONFIDENCE_WARN_VALUE  = 0.7;
+const CONFIDENCE_STALE_VALUE = 0.5;
+
+/** Calculate current confidence for a lesson based on how long since last verified. */
+function calculateConfidence(lesson: { verified_at?: string; ts: string; recall_count?: number }): number {
+  const ref = lesson.verified_at ?? lesson.ts;
+  const ageMs = Date.now() - new Date(ref).getTime();
+  const ageDays = ageMs / 86400000;
+  if (ageDays >= CONFIDENCE_STALE_DAYS) return CONFIDENCE_STALE_VALUE;
+  if (ageDays >= CONFIDENCE_WARN_DAYS)  return CONFIDENCE_WARN_VALUE;
+  // Linear interpolation between fresh (1.0) and warn threshold
+  return 1.0 - (ageDays / CONFIDENCE_WARN_DAYS) * (1.0 - CONFIDENCE_WARN_VALUE);
+}
+
+/** Render a confidence badge string. */
+function confidenceBadge(confidence: number, ageDays: number): string {
+  if (confidence >= 0.9) return '✅';
+  if (confidence >= 0.7) return `⚠️ (${Math.round(ageDays)}d old, confidence ${(confidence * 100).toFixed(0)}% — verify before applying)`;
+  return `🔴 STALE (${Math.round(ageDays)}d old, confidence ${(confidence * 100).toFixed(0)}% — likely outdated!)`;
+}
+
+/** Category-specific required fields for structured lessons. */
+const STRUCTURED_TEMPLATES: Record<string, { required: string[]; hint: string }> = {
+  'deploy':  { required: ['commands'],                hint: 'deploy:* needs commands[]' },
+  'bash':    { required: ['commands'],                hint: 'bash:* needs commands[]' },
+  'infra':   { required: ['commands'],                hint: 'infra:* needs commands[] + verified on real system' },
+  'pricing': { required: [],                          hint: 'pricing:* — add context with source (e.g. "Stripe Dashboard Apr 2026")' },
+  'stripe':  { required: [],                          hint: 'stripe:* — add context with Stripe API version' },
+};
+
+/** Fast content hash for index invalidation (not cryptographic, just change detection) */
+function simpleHash(text: string): string {
+  return createHash('md5').update(text).digest('hex').slice(0, 12);
+}
+
 function detectEmbedProvider(): string {
   // Client-side keys first (direct, fast, no server roundtrip)
   if (process.env.OPENAI_API_KEY) return 'openai';
@@ -260,13 +301,18 @@ function embedProviderHint(): string {
 //   • Recency boost — newer entries rank higher (exponential decay, 7-day half-life)
 //   • Multi-query splitting — numbered lists, semicolons, conjunctions
 //   • Fuzzy matching with Levenshtein distance ≤ 2
-//   • Multilingual stopwords (EN, DE, FR, ES, IT, PT)
+//   • Multilingual stopwords (EN, DE, FR, ES, IT, PT, ZH, JA, KO, AR, HE)
+//   • CJK character bigram extraction — handles Chinese, Japanese, Korean
+//   • RTL language support (Arabic, Hebrew) — word tokenization + light stemming
+//   • Romanization matching — katakana → romaji tokens for romaji queries
+//   • Cross-language retrieval — tech term synonyms EN↔JA↔ZH↔KO↔AR↔HE
 //   • Pipeline Redis reads for performance
 //
 
 /**
  * Stopwords — filtered out during tokenization.
- * Covers: English, German, French, Spanish, Italian, Portuguese.
+ * Covers: English, German, French, Spanish, Italian, Portuguese,
+ *         Chinese (Simplified + Traditional), Japanese, Korean.
  * Keeps the index small and scores meaningful.
  */
 const STOPWORDS = new Set([
@@ -340,15 +386,436 @@ const STOPWORDS = new Set([
   'eu', 'tu', 'ele', 'ela', 'nós', 'eles', 'elas', 'você', 'vocês',
   'não', 'já', 'sim', 'bem', 'muito', 'também', 'ainda', 'sempre',
   'todo', 'toda', 'todos', 'cada', 'outro', 'outra', 'quando', 'porque',
+  // ── Chinese (Simplified + Traditional) — high-frequency function characters ──
+  '的', '了', '是', '在', '不', '和', '我', '他', '这', '中', '大', '为',
+  '上', '个', '国', '以', '要', '就', '出', '说', '们', '有', '来', '到',
+  '时', '地', '年', '得', '着', '那', '过', '后', '还', '与', '也', '可',
+  '于', '从', '但', '而', '被', '把', '让', '使', '对', '很', '都', '一',
+  '会', '没', '人', '它', '这个', '那个', '什么', '如果', '因为', '所以',
+  '已经', '可以', '这些', '那些', '我们', '他们', '她们', '它们',
+  // ── Japanese — common hiragana particles and auxiliary verbs ──
+  'の', 'は', 'が', 'を', 'に', 'で', 'と', 'も', 'や', 'か', 'な', 'ね',
+  'よ', 'わ', 'て', 'い', 'う', 'え', 'お', 'き', 'く', 'け', 'こ', 'さ',
+  'し', 'す', 'せ', 'そ', 'た', 'ち', 'つ', 'ぬ', 'ん', 'から', 'まで',
+  'より', 'へ', 'です', 'ます', 'ない', 'ある', 'いる', 'する', 'こと',
+  'もの', 'ので', 'では', 'には', 'との', 'への', 'から', 'まで',
+  // ── Korean — common particles and auxiliary forms ──
+  '이', '가', '은', '는', '을', '를', '의', '에', '와', '과', '도',
+  '로', '에서', '한', '하', '있', '없', '것', '수', '않', '들',
+  '이다', '하다', '이고', '이며', '라고', '에게', '에서', '으로',
+  // ── Arabic — high-frequency function words & particles ──
+  'في', 'من', 'إلى', 'على', 'عن', 'مع', 'هذا', 'هذه', 'ذلك', 'تلك',
+  'الذي', 'التي', 'الذين', 'اللواتي', 'هو', 'هي', 'هم', 'هن', 'نحن',
+  'أنت', 'أنتم', 'أنا', 'كان', 'كانت', 'كانوا', 'يكون', 'تكون',
+  'أن', 'إن', 'لأن', 'لكن', 'أو', 'بل', 'ثم', 'حتى', 'إذا', 'كي',
+  'قد', 'لقد', 'لم', 'لن', 'ما', 'لا', 'ليس', 'غير', 'بعض', 'كل',
+  'جميع', 'أي', 'كيف', 'متى', 'أين', 'لماذا', 'ماذا', 'هل', 'ال',
+  'و', 'ف', 'ب', 'ل', 'ك', 'يا', 'أم', 'إلا', 'عند', 'بين',
+  // ── Hebrew — common particles, pronouns, conjunctions ──
+  'של', 'את', 'אל', 'על', 'עם', 'לא', 'הוא', 'היא', 'הם', 'הן',
+  'אני', 'אתה', 'אנחנו', 'אתם', 'כי', 'אם', 'אבל', 'גם', 'כבר',
+  'רק', 'עוד', 'יש', 'אין', 'מה', 'זה', 'זאת', 'אלה', 'כל', 'כן',
+  'לו', 'לה', 'להם', 'בו', 'בה', 'בהם', 'שם', 'כך', 'כן', 'מי',
+  'אשר', 'אחרי', 'לפני', 'תחת', 'בין', 'מאז', 'עד', 'כמו', 'אז',
+]);
+
+// CJK Unicode ranges used for bigram extraction
+const CJK_RE = /[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uac00-\ud7af]/;
+const SEGMENT_RE = /([\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uac00-\ud7af]+|[^\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uac00-\ud7af]+)/g;
+
+// RTL Unicode ranges: Arabic (U+0600–U+06FF + extended), Hebrew (U+0590–U+05FF)
+const RTL_RE = /[\u0590-\u05ff\u0600-\u06ff\u0750-\u077f\u08a0-\u08ff\ufb1d-\ufb4f\ufb50-\ufdff\ufe70-\ufeff]/;
+
+// ── Katakana → Romaji conversion table (Hepburn system) ──────────────────────
+// Digraphs must be listed before single chars so they match first.
+const KATA_ROMAJI_TABLE: [string, string][] = [
+  // Special combinations for loanwords
+  ['ファ', 'fa'], ['フィ', 'fi'], ['フェ', 'fe'], ['フォ', 'fo'],
+  ['ティ', 'ti'], ['ディ', 'di'], ['トゥ', 'tu'], ['ドゥ', 'du'],
+  ['ウィ', 'wi'], ['ウェ', 'we'], ['ウォ', 'wo'],
+  ['チェ', 'che'], ['ジェ', 'je'], ['シェ', 'she'],
+  ['イェ', 'ye'], ['ヴァ', 'va'], ['ヴィ', 'vi'], ['ヴェ', 've'], ['ヴォ', 'vo'],
+  // Digraphs (2-char → romaji)
+  ['キャ', 'kya'], ['キュ', 'kyu'], ['キョ', 'kyo'],
+  ['シャ', 'sha'], ['シュ', 'shu'], ['ショ', 'sho'],
+  ['チャ', 'cha'], ['チュ', 'chu'], ['チョ', 'cho'],
+  ['ニャ', 'nya'], ['ニュ', 'nyu'], ['ニョ', 'nyo'],
+  ['ヒャ', 'hya'], ['ヒュ', 'hyu'], ['ヒョ', 'hyo'],
+  ['ミャ', 'mya'], ['ミュ', 'myu'], ['ミョ', 'myo'],
+  ['リャ', 'rya'], ['リュ', 'ryu'], ['リョ', 'ryo'],
+  ['ギャ', 'gya'], ['ギュ', 'gyu'], ['ギョ', 'gyo'],
+  ['ジャ', 'ja'], ['ジュ', 'ju'], ['ジョ', 'jo'],
+  ['ビャ', 'bya'], ['ビュ', 'byu'], ['ビョ', 'byo'],
+  ['ピャ', 'pya'], ['ピュ', 'pyu'], ['ピョ', 'pyo'],
+  // Single chars
+  ['ア', 'a'], ['イ', 'i'], ['ウ', 'u'], ['エ', 'e'], ['オ', 'o'],
+  ['カ', 'ka'], ['キ', 'ki'], ['ク', 'ku'], ['ケ', 'ke'], ['コ', 'ko'],
+  ['サ', 'sa'], ['シ', 'shi'], ['ス', 'su'], ['セ', 'se'], ['ソ', 'so'],
+  ['タ', 'ta'], ['チ', 'chi'], ['ツ', 'tsu'], ['テ', 'te'], ['ト', 'to'],
+  ['ナ', 'na'], ['ニ', 'ni'], ['ヌ', 'nu'], ['ネ', 'ne'], ['ノ', 'no'],
+  ['ハ', 'ha'], ['ヒ', 'hi'], ['フ', 'fu'], ['ヘ', 'he'], ['ホ', 'ho'],
+  ['マ', 'ma'], ['ミ', 'mi'], ['ム', 'mu'], ['メ', 'me'], ['モ', 'mo'],
+  ['ヤ', 'ya'], ['ユ', 'yu'], ['ヨ', 'yo'],
+  ['ラ', 'ra'], ['リ', 'ri'], ['ル', 'ru'], ['レ', 're'], ['ロ', 'ro'],
+  ['ワ', 'wa'], ['ヲ', 'wo'], ['ン', 'n'],
+  // Voiced
+  ['ガ', 'ga'], ['ギ', 'gi'], ['グ', 'gu'], ['ゲ', 'ge'], ['ゴ', 'go'],
+  ['ザ', 'za'], ['ジ', 'ji'], ['ズ', 'zu'], ['ゼ', 'ze'], ['ゾ', 'zo'],
+  ['ダ', 'da'], ['ヂ', 'ji'], ['ヅ', 'zu'], ['デ', 'de'], ['ド', 'do'],
+  ['バ', 'ba'], ['ビ', 'bi'], ['ブ', 'bu'], ['ベ', 'be'], ['ボ', 'bo'],
+  ['パ', 'pa'], ['ピ', 'pi'], ['プ', 'pu'], ['ペ', 'pe'], ['ポ', 'po'],
+  ['ヴ', 'v'],
+  // Long vowel / small chars
+  ['ー', ''], ['ァ', 'a'], ['ィ', 'i'], ['ゥ', 'u'], ['ェ', 'e'], ['ォ', 'o'],
+  ['ッ', ''],  // handled separately (doubles next consonant)
+];
+
+const KATA_MAP = new Map<string, string>(KATA_ROMAJI_TABLE);
+
+/**
+ * Convert a katakana string to Hepburn romaji.
+ * Handles digraphs, geminate consonants (ッ), and long vowel marks (ー).
+ */
+function katakanaToRomaji(kata: string): string {
+  let result = '';
+  let i = 0;
+  while (i < kata.length) {
+    // Geminate consonant: ッ doubles the following consonant
+    if (kata[i] === 'ッ' && i + 1 < kata.length) {
+      const next = KATA_MAP.get(kata[i + 1]) ?? KATA_MAP.get(kata[i + 1] + kata[i + 2]) ?? '';
+      if (next.length > 0) result += next[0]; // double first consonant
+      i++;
+      continue;
+    }
+    // Try 2-char digraph first
+    if (i + 1 < kata.length) {
+      const two = kata[i] + kata[i + 1];
+      const r2 = KATA_MAP.get(two);
+      if (r2 !== undefined) { result += r2; i += 2; continue; }
+    }
+    // Single char
+    const r1 = KATA_MAP.get(kata[i]);
+    if (r1 !== undefined) result += r1;
+    i++;
+  }
+  return result;
+}
+
+/**
+ * Arabic light stemmer — strips definite article and common prefix particles.
+ * Handles: ال (al-), و (wa-), ب (bi-), ل (li-), ف (fa-), ك (ka-).
+ * Only strips when the result is still ≥ 3 chars to avoid over-stemming.
+ */
+function arabicLightStem(word: string): string {
+  if (word.startsWith('ال') && word.length > 4) return word.slice(2);
+  if (word.length > 3 && 'وبلفك'.includes(word[0]) && RTL_RE.test(word[1])) return word.slice(1);
+  return word;
+}
+
+// ── Cross-lingual tech term dictionary ────────────────────────────────────────
+// Maps tokens (English, Japanese katakana, Chinese, Korean, Arabic, Hebrew)
+// to their equivalents in other languages. Used to expand tokens at search time
+// so "deploy" finds documents containing "デプロイ" / "部署" / "배포", and vice versa.
+//
+// Keys must be lowercase. CJK values will be bigram-expanded at use time.
+const CROSS_LINGUAL_MAP = new Map<string, string[]>([
+  // English → all
+  ['deploy',      ['デプロイ', '部署', '배포', 'deployment', 'deploying']],
+  ['deployment',  ['デプロイ', '部署', '배포', 'deploy']],
+  ['container',   ['コンテナ', '容器', '컨테이너', 'docker']],
+  ['server',      ['サーバー', 'サーバ', '服务器', '서버', 'سيرفر', 'שרת']],
+  ['database',    ['データベース', '数据库', '데이터베이스', 'db', 'قاعدة البيانات']],
+  ['cache',       ['キャッシュ', '缓存', '캐시', 'كاش', 'מטמון']],
+  ['error',       ['エラー', '错误', '오류', 'خطأ', 'שגיאה', 'exception', 'err']],
+  ['bug',         ['バグ', '缺陷', '버그', 'issue', 'defect', 'خلل']],
+  ['fix',         ['修正', '修复', '수정', 'bugfix', 'patch', 'hotfix', 'إصلاح', 'תיקון']],
+  ['build',       ['ビルド', '构建', '빌드', 'بناء', 'בנייה']],
+  ['test',        ['テスト', '测试', '테스트', 'اختبار', 'בדיקה']],
+  ['auth',        ['認証', '认证', '인증', 'authentication', 'login', 'oauth', 'مصادقة', 'אימות']],
+  ['kubernetes',  ['クベルネテス', 'k8s', 'kube']],
+  ['network',     ['ネットワーク', '网络', '네트워크', 'شبكة', 'רשת']],
+  ['timeout',     ['タイムアウト', '超时', '타임아웃', 'مهلة']],
+  ['memory',      ['メモリ', '内存', '메모리', 'ram', 'ذاكرة', 'זיכרון']],
+  ['config',      ['設定', '配置', '설정', 'configuration', 'settings', 'conf', 'إعدادات', 'הגדרות']],
+  ['install',     ['インストール', '安装', '설치', 'تثبيت', 'התקנה']],
+  ['update',      ['アップデート', '更新', '업데이트', 'upgrade', 'تحديث', 'עדכון']],
+  ['log',         ['ログ', '日志', '로그', 'logging', 'سجل', 'יומן']],
+  ['port',        ['ポート', '端口', '포트', 'منفذ', 'פורט']],
+  ['file',        ['ファイル', '文件', '파일', 'ملف', 'קובץ']],
+  ['image',       ['イメージ', '镜像', '이미지', 'صورة', 'תמונה']],
+  ['volume',      ['ボリューム', '卷', '볼륨']],
+  ['cluster',     ['クラスター', '集群', '클러스터']],
+  ['node',        ['ノード', '节点', '노드']],
+  ['service',     ['サービス', '服务', '서비스', 'svc', 'خدمة', 'שירות']],
+  ['certificate', ['証明書', '证书', '인증서', 'cert', 'ssl', 'tls', 'شهادة', 'תעודה']],
+  ['password',    ['パスワード', '密码', '비밀번호', 'passwd', 'pwd', 'كلمة المرور', 'סיסמה']],
+  ['token',       ['トークン', '令牌', '토큰', 'jwt', 'secret', 'رمز', 'אסימון']],
+  ['health',      ['ヘルス', '健康', '헬스', 'healthcheck', 'probe', 'صحة']],
+  ['migration',   ['マイグレーション', '迁移', '마이그레이션', 'migrate', 'هجرة']],
+  ['backup',      ['バックアップ', '备份', '백업', 'نسخ احتياطي', 'גיבוי']],
+  ['monitor',     ['モニター', '监控', '모니터링', 'monitoring', 'metrics', 'alert', 'مراقبة', 'ניטור']],
+  ['performance', ['パフォーマンス', '性能', '성능', 'latency', 'throughput']],
+  ['connection',  ['接続', '连接', '연결', 'conn', 'socket', 'اتصال', 'חיבור']],
+  ['queue',       ['キュー', '队列', '큐', 'طابور']],
+  ['redis',       ['レディス', '레디스']],
+  ['nginx',       ['エンジンエックス']],
+  ['linux',       ['リナックス', 'لينكس']],
+  ['api',         ['エーピーアイ', '接口', 'endpoint', 'واجهة برمجية', 'ממשק']],
+  ['healthcheck', ['ヘルスチェック', 'health', 'probe', 'فحص الصحة']],
+  ['loadbalancer',['ロードバランサー', '负载均衡', '로드밸런서', 'lb']],
+  ['ssl',         ['tls', 'https', 'certificate', 'cert']],
+  ['tls',         ['ssl', 'https', 'certificate', 'cert']],
+  ['docker',      ['container', 'コンテナ', '容器', '컨테이너', 'دوكر']],
+  ['git',         ['version control', 'repo', 'repository', 'commit', 'push', 'pull']],
+  ['ci',          ['pipeline', 'github actions', 'gitlab', 'jenkins', 'build']],
+  ['cd',          ['deploy', 'deployment', 'release']],
+  ['debug',       ['デバッグ', '调试', '디버그', 'debugging', 'breakpoint', 'تصحيح', 'איתור באגים']],
+  ['crash',       ['クラッシュ', '崩溃', '크래시', 'panic', 'segfault', 'انهيار']],
+  ['restart',     ['再起動', '重启', '재시작', 'reboot', 'إعادة تشغيل', 'הפעלה מחדש']],
+  ['permission',  ['権限', '权限', '권한', 'access', 'acl', 'chmod', 'صلاحية', 'הרשאה']],
+  // Japanese katakana → English
+  ['デプロイ',    ['deploy', 'deployment']],
+  ['コンテナ',    ['container', 'docker']],
+  ['サーバー',    ['server']],
+  ['サーバ',      ['server']],
+  ['データベース',['database', 'db']],
+  ['キャッシュ',  ['cache']],
+  ['エラー',      ['error', 'err']],
+  ['バグ',        ['bug', 'issue']],
+  ['ビルド',      ['build']],
+  ['テスト',      ['test']],
+  ['認証',        ['auth', 'authentication']],
+  ['設定',        ['config', 'configuration']],
+  ['インストール',['install']],
+  ['アップデート',['update', 'upgrade']],
+  ['ログ',        ['log', 'logs']],
+  ['ポート',      ['port']],
+  ['ファイル',    ['file']],
+  ['イメージ',    ['image']],
+  ['クラスター',  ['cluster']],
+  ['ノード',      ['node']],
+  ['サービス',    ['service']],
+  ['パスワード',  ['password']],
+  ['トークン',    ['token']],
+  ['バックアップ',['backup']],
+  ['モニター',    ['monitor', 'monitoring']],
+  ['接続',        ['connection']],
+  ['キュー',      ['queue']],
+  ['ヘルスチェック',['healthcheck', 'health check', 'health']],
+  ['ロードバランサー',['loadbalancer', 'load balancer']],
+  ['デバッグ',    ['debug']],
+  ['クラッシュ',  ['crash', 'panic']],
+  ['再起動',      ['restart', 'reboot']],
+  ['権限',        ['permission', 'access']],
+  // Chinese → English
+  ['部署',        ['deploy', 'deployment']],
+  ['容器',        ['container', 'docker']],
+  ['服务器',      ['server']],
+  ['数据库',      ['database']],
+  ['缓存',        ['cache']],
+  ['错误',        ['error']],
+  ['修复',        ['fix', 'bugfix']],
+  ['构建',        ['build']],
+  ['测试',        ['test']],
+  ['认证',        ['auth']],
+  ['配置',        ['config']],
+  ['安装',        ['install']],
+  ['更新',        ['update']],
+  ['日志',        ['log']],
+  ['端口',        ['port']],
+  ['镜像',        ['image']],
+  ['集群',        ['cluster']],
+  ['节点',        ['node']],
+  ['服务',        ['service']],
+  ['密码',        ['password']],
+  ['令牌',        ['token']],
+  ['备份',        ['backup']],
+  ['监控',        ['monitor']],
+  ['连接',        ['connection']],
+  ['队列',        ['queue']],
+  ['性能',        ['performance']],
+  ['内存',        ['memory']],
+  ['调试',        ['debug']],
+  ['崩溃',        ['crash']],
+  ['重启',        ['restart']],
+  ['权限',        ['permission']],
+  // Korean → English
+  ['배포',        ['deploy', 'deployment']],
+  ['컨테이너',    ['container']],
+  ['서버',        ['server']],
+  ['데이터베이스',['database']],
+  ['캐시',        ['cache']],
+  ['오류',        ['error']],
+  ['수정',        ['fix']],
+  ['빌드',        ['build']],
+  ['테스트',      ['test']],
+  ['인증',        ['auth']],
+  ['설정',        ['config']],
+  ['설치',        ['install']],
+  ['업데이트',    ['update']],
+  ['로그',        ['log']],
+  ['포트',        ['port']],
+  ['이미지',      ['image']],
+  ['클러스터',    ['cluster']],
+  ['노드',        ['node']],
+  ['서비스',      ['service']],
+  ['토큰',        ['token']],
+  ['백업',        ['backup']],
+  ['모니터링',    ['monitor']],
+  ['연결',        ['connection']],
+  ['큐',          ['queue']],
+  ['성능',        ['performance']],
+  ['메모리',      ['memory']],
+  ['디버그',      ['debug']],
+  ['크래시',      ['crash']],
+  ['재시작',      ['restart']],
+  ['권한',        ['permission']],
+  // Arabic → English
+  ['خطأ',         ['error']],
+  ['إصلاح',       ['fix']],
+  ['بناء',        ['build']],
+  ['اختبار',      ['test']],
+  ['مصادقة',      ['auth']],
+  ['إعدادات',     ['config']],
+  ['تثبيت',       ['install']],
+  ['تحديث',       ['update']],
+  ['سجل',         ['log']],
+  ['صورة',        ['image']],
+  ['خدمة',        ['service']],
+  ['نسخ احتياطي', ['backup']],
+  ['مراقبة',      ['monitor']],
+  ['اتصال',       ['connection']],
+  ['ذاكرة',       ['memory']],
+  ['تصحيح',       ['debug']],
+  ['شبكة',        ['network']],
+  // Hebrew → English
+  ['שגיאה',       ['error']],
+  ['תיקון',       ['fix']],
+  ['בנייה',       ['build']],
+  ['בדיקה',       ['test']],
+  ['אימות',       ['auth']],
+  ['הגדרות',      ['config']],
+  ['התקנה',       ['install']],
+  ['עדכון',       ['update']],
+  ['יומן',        ['log']],
+  ['שרת',         ['server']],
+  ['שירות',       ['service']],
+  ['גיבוי',       ['backup']],
+  ['ניטור',       ['monitor']],
+  ['חיבור',       ['connection']],
+  ['זיכרון',      ['memory']],
+  ['רשת',         ['network']],
+  ['תמונה',       ['image']],
+  ['סיסמה',       ['password']],
+  ['הרשאה',       ['permission']],
 ]);
 
-/** Tokenize text into meaningful keywords. Handles unicode (accented chars). */
+/**
+ * Expand a token to its cross-lingual synonyms.
+ * Returns synonyms to be added to the token stream (pre-tokenized).
+ * CJK synonyms are NOT pre-bigram'd here — caller handles that.
+ */
+function expandCrossLingual(token: string): string[] {
+  return CROSS_LINGUAL_MAP.get(token) ?? [];
+}
+
+/**
+ * Tokenize text into meaningful keywords.
+ * Handles accented Latin, RTL (Arabic, Hebrew), and CJK (Chinese, Japanese, Korean).
+ *
+ * Features:
+ *  • CJK → character bigrams
+ *  • Katakana → additionally emits Hepburn romaji tokens (enables romaji queries)
+ *  • Arabic/Hebrew → word tokenization with light Arabic stemming
+ *  • All scripts → cross-lingual synonym expansion (EN↔JA↔ZH↔KO↔AR↔HE)
+ */
 function tokenize(text: string): string[] {
-  return text
-    .toLowerCase()
-    .replace(/[^a-záàâãäåæçéèêëíìîïñóòôõöúùûüýÿßœ0-9:_\-./]/g, ' ')
-    .split(/\s+/)
-    .filter(w => w.length > 1 && !STOPWORDS.has(w));
+  const tokens: string[] = [];
+  const lower = text.toLowerCase();
+
+  for (const [seg] of lower.matchAll(SEGMENT_RE)) {
+    if (CJK_RE.test(seg)) {
+      // CJK segment — extract overlapping character bigrams
+      for (let i = 0; i < seg.length - 1; i++) {
+        const bigram = seg[i] + seg[i + 1];
+        if (!STOPWORDS.has(seg[i]) && !STOPWORDS.has(bigram)) {
+          tokens.push(bigram);
+        }
+      }
+      // Trailing single character (for 1-char CJK terms)
+      if (seg.length >= 1) {
+        const last = seg[seg.length - 1];
+        if (!STOPWORDS.has(last)) tokens.push(last);
+      }
+      // Whole-segment cross-lingual lookup (for known tech terms like デプロイ, 部署, 배포)
+      // This ensures CJK full-words map to their English equivalents
+      const segSyns = expandCrossLingual(seg);
+      for (const syn of segSyns) {
+        if (!CJK_RE.test(syn)) {
+          syn.split(/\s+/).filter(w => w.length > 1 && !STOPWORDS.has(w)).forEach(w => tokens.push(w));
+        }
+      }
+      // Romanization: extract katakana-only portion and emit romaji tokens.
+      // This allows users to search "kontena" or "depuroi" to find katakana docs.
+      const kataOnly = seg.replace(/[^\u30a0-\u30ff]/g, '');
+      if (kataOnly.length >= 2) {
+        const romaji = katakanaToRomaji(kataOnly);
+        if (romaji.length >= 2 && romaji.length <= 40 && !STOPWORDS.has(romaji)) {
+          tokens.push(romaji);
+        }
+      }
+    } else if (RTL_RE.test(seg)) {
+      // RTL segment (Arabic / Hebrew) — space-separated words with light stemming
+      const words = seg.trim().split(/\s+/);
+      for (const w of words) {
+        if (w.length <= 1 || STOPWORDS.has(w)) continue;
+        const stemmed = arabicLightStem(w);
+        if (stemmed.length > 1 && !STOPWORDS.has(stemmed)) tokens.push(stemmed);
+      }
+    } else {
+      // Latin / other — existing logic preserved exactly
+      const words = seg
+        .replace(/[^a-záàâãäåæçéèêëíìîïñóòôõöúùûüýÿßœ0-9:_\-./]/g, ' ')
+        .split(/\s+/)
+        .filter(w => w.length > 1 && !STOPWORDS.has(w));
+      tokens.push(...words);
+    }
+  }
+
+  // ── Cross-lingual expansion ──────────────────────────────────────────────
+  // For each token, look up synonyms in other languages and add them.
+  // CJK synonyms are bigram-expanded inline; Latin/RTL synonyms added as-is.
+  const expansions: string[] = [];
+  const seen = new Set(tokens);
+  for (const tok of tokens) {
+    const syns = expandCrossLingual(tok);
+    for (const syn of syns) {
+      if (seen.has(syn)) continue;
+      seen.add(syn);
+      if (CJK_RE.test(syn)) {
+        // CJK synonym → expand to character bigrams
+        for (let i = 0; i < syn.length - 1; i++) {
+          const bg = syn[i] + syn[i + 1];
+          if (!STOPWORDS.has(syn[i]) && !STOPWORDS.has(bg)) expansions.push(bg);
+        }
+        if (syn.length >= 1) {
+          const last = syn[syn.length - 1];
+          if (!STOPWORDS.has(last)) expansions.push(last);
+        }
+      } else if (RTL_RE.test(syn)) {
+        // RTL synonym
+        const stemmed = arabicLightStem(syn);
+        if (stemmed.length > 1 && !STOPWORDS.has(stemmed)) expansions.push(stemmed);
+      } else {
+        // Latin synonym — split in case of multi-word (e.g. "load balancer")
+        const parts = syn.split(/\s+/).filter(w => w.length > 1 && !STOPWORDS.has(w));
+        expansions.push(...parts);
+      }
+    }
+  }
+  tokens.push(...expansions);
+
+  return tokens;
 }
 
 /**
@@ -661,7 +1128,8 @@ async function keywordSearch(
 }
 
 // ── Exported for testing ──────────────────────────────────────────────────────
-export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp, STOPWORDS };
+export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp, STOPWORDS,
+         katakanaToRomaji, arabicLightStem, expandCrossLingual, CROSS_LINGUAL_MAP };
 
 // ── Types ─────────────────────────────────────────────────────────────────────
 
@@ -696,26 +1164,11 @@ interface SemanticSearchResponse {
 
 // ── Connection pool ───────────────────────────────────────────────────────────
 
-/** Reuse Redis connections across tool calls (keyed by instance_id). Max 20 entries, LRU eviction. */
+/** Reuse Redis connections across tool calls (keyed by instance_id). */
 const pool = new Map<string, Redis>();
-const POOL_MAX = 20;
 
 async function getConnection(instance_id: string): Promise<Redis> {
-  if (pool.has(instance_id)) {
-    // Move to end (most-recently-used)
-    const conn = pool.get(instance_id)!;
-    pool.delete(instance_id);
-    pool.set(instance_id, conn);
-    return conn;
-  }
-  // Evict oldest entry when pool is full
-  if (pool.size >= POOL_MAX) {
-    const oldest = pool.keys().next().value;
-    if (oldest) {
-      pool.get(oldest)?.quit().catch(() => undefined);
-      pool.delete(oldest);
-    }
-  }
+  if (pool.has(instance_id)) return pool.get(instance_id)!;
 
   const inst = await apiFetch<Instance>(`/api/v1/instances/${instance_id}`);
   if (inst.status !== 'running') {
@@ -785,34 +1238,13 @@ async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T>
   }
   const res = await fetch(`${API_URL}${path}`, {
     ...options,
-    signal: AbortSignal.timeout(15000),
     headers: {
       'Content-Type': 'application/json',
       Authorization: `Bearer ${JWT}`,
       ...options.headers,
     },
-  }).catch((err: Error) => {
-    if (err.name === 'TimeoutError' || err.name === 'AbortError') {
-      throw new McpError(ErrorCode.InternalError,
-        `cachly API timed out after 15s — check your connection or try again.`);
-    }
-    throw new McpError(ErrorCode.InternalError, `cachly API unreachable: ${err.message}`);
   });
   if (!res.ok) {
-    if (res.status === 401 || res.status === 403) {
-      throw new McpError(
-        ErrorCode.InvalidRequest,
-        `cachly API: authentication failed (${res.status}) — your JWT may be expired or invalid.\n` +
-        `Get a new API token at https://cachly.dev/settings or run \`get_api_status\` to check token expiry.`
-      );
-    }
-    if (res.status === 503 || res.status === 502) {
-      throw new McpError(
-        ErrorCode.InternalError,
-        `cachly API: auth service unavailable (${res.status}) — the authentication service may be temporarily down.\n` +
-        `Please try again in a moment or contact support@cachly.dev`
-      );
-    }
     const body = await res.json().catch(() => ({ error: res.statusText }));
     throw new McpError(
       ErrorCode.InternalError,
@@ -839,8 +1271,8 @@ const TOOLS = [
     description:
       'Create a new managed Valkey/Redis cache instance on cachly.dev. ' +
       'Free tier provisions in ~30 seconds. Paid tiers return a Stripe checkout URL. ' +
-      'Available tiers: free (30 MB), dev (256 MB, €8/mo), pro (1 GB, €25/mo), ' +
-      'speed (1 GB Dragonfly + Semantic Cache, €39/mo), business (8 GB, €99/mo).',
+      'Available tiers: free (25 MB), dev (200 MB, €19/mo), pro (900 MB, €49/mo), ' +
+      'speed (900 MB Dragonfly + Semantic Cache, €79/mo), business (7 GB, €199/mo).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1215,10 +1647,10 @@ const TOOLS = [
   {
     name: 'get_api_status',
     description:
-      'Check the cachly API health, auth service reachability, and your authentication status. ' +
-      'Returns API health, whether the Keycloak auth service is reachable, JWT validity, ' +
-      'user ID (sub claim), token expiry, and the auth provider. ' +
-      'Use this to debug connection issues, verify your CACHLY_JWT, or diagnose "Auth Service Unavailable" errors.',
+      'Check the cachly API health and your authentication status. ' +
+      'Returns whether the JWT is valid, your user ID (sub claim), ' +
+      'token expiry, and the auth provider (keycloak). ' +
+      'Use this to debug connection issues or verify your CACHLY_JWT is correct.',
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
   // ── Thinking/Context Cache (for AI assistants) ────────────────────────────
@@ -1309,7 +1741,9 @@ const TOOLS = [
       'Fields: topic (short slug like "deploy:web"), outcome ("success"|"failure"), ' +
       'what_worked (what solved it), what_failed (what did NOT work), context (extra details). ' +
       'Supports structured metadata: severity, file_paths (files involved), commands (working commands), tags. ' +
-      'Deduplication: if a lesson for this topic already exists, it is updated instead of duplicated. ' +
+      'Deduplication: if a lesson for this topic already exists, it is updated with full audit trail. ' +
+      'Contradiction detection: warns if new outcome conflicts with existing lesson outcome. ' +
+      'Confidence: lesson starts at 1.0, decays after 5d (→0.7) and 10d (→0.5) without recall. ' +
       'Example: learn_from_attempts(topic="deploy:api", outcome="success", what_worked="nohup docker compose up -d --build", what_failed="docker compose up hangs on SSH timeout", severity="critical", commands=["nohup docker compose up -d --build"])',
     inputSchema: {
       type: 'object',
@@ -1340,6 +1774,15 @@ const TOOLS = [
           items: { type: 'string' },
           description: 'Topic tags for filtering (e.g. ["bash", "deploy", "env"])',
         },
+        depends_on: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Prerequisites this lesson depends on (e.g. ["node:>=20", "docker:running", "wireguard:active"]). When a dependency is marked stale, all dependent lessons get needs_review.',
+        },
+        author: {
+          type: 'string',
+          description: 'Name or handle of the person storing this lesson (e.g. "alice", "bob"). Used for Team Telepathy — teammates see each other\'s lessons in session_start.',
+        },
       },
       required: ['instance_id', 'topic', 'outcome', 'what_worked'],
     },
@@ -1349,7 +1792,9 @@ const TOOLS = [
     description:
       'Recall the best known solution for a topic from past lessons. ' +
       'Call this BEFORE attempting any task that might have been done before. ' +
-      'Returns the most recent successful lesson for the topic, or a summary of attempts. ' +
+      'Returns the most recent successful lesson for the topic, with confidence indicator. ' +
+      '⚠️ badge = lesson is >5d old (verify before applying). 🔴 = >10d old (likely stale!). ' +
+      'Recalling a lesson resets its confidence clock to 1.0 (marks as recently verified). ' +
       'Example: recall_best_solution(topic="deploy:web") → returns the working deploy command.',
     inputSchema: {
       type: 'object',
@@ -1360,35 +1805,6 @@ const TOOLS = [
       required: ['instance_id', 'topic'],
     },
   },
-  {
-    name: 'list_lessons',
-    description:
-      'List all topics stored in the Brain. Use this to see what the AI has learned, find topics to recall, or identify outdated lessons to delete with forget_lesson. ' +
-      'Returns topics sorted by most recently stored, with severity and recall count.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        instance_id: { type: 'string', description: 'UUID of the cache instance' },
-        filter:      { type: 'string', description: 'Optional substring filter, e.g. "deploy" returns only deploy-related topics' },
-      },
-      required: ['instance_id'],
-    },
-  },
-  {
-    name: 'forget_lesson',
-    description:
-      'Delete a stored lesson from the Brain. Use this when a lesson is wrong, outdated, or was learned incorrectly. ' +
-      'Removes both the best-solution entry and the attempt history for the topic. ' +
-      'Example: forget_lesson(topic="deploy:web") → deletes the wrong deployment lesson so a correct one can be stored.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        instance_id: { type: 'string', description: 'UUID of the cache instance' },
-        topic:       { type: 'string', description: 'Exact topic slug to delete, e.g. "deploy:web"' },
-      },
-      required: ['instance_id', 'topic'],
-    },
-  },
   {
     name: 'smart_recall',
     description:
@@ -1411,7 +1827,8 @@ const TOOLS = [
     description:
       'Single-call session briefing. Call this at the START of every session INSTEAD of multiple separate smart_recall/recall_best_solution calls. ' +
       'Returns: last session summary, recent lessons sorted by recency, relevant lessons for your focus area, ' +
-      'open failures (topics with only failure outcomes), and brain health stats (lesson count, context count). ' +
+      'open failures (topics with only failure outcomes), brain health stats, team telepathy (what teammates learned this week), ' +
+      'predictive pre-warnings (if your focus area has known failure patterns), and memory crystals (compressed wisdom from old sessions). ' +
       'Also saves a session start marker so session_end can compute duration.',
     inputSchema: {
       type: 'object',
@@ -1421,6 +1838,18 @@ const TOOLS = [
           type: 'string',
           description: 'Keywords for what you plan to work on today (e.g. "deploy infra api"). Used to surface relevant lessons at the top.',
         },
+        author: {
+          type: 'string',
+          description: 'Your name or handle (e.g. "alice"). Enables Team Telepathy — filters YOUR lessons vs TEAM lessons from past 7 days.',
+        },
+        provider: {
+          type: 'string',
+          description: 'Current AI provider (e.g. "claude-code", "copilot", "cursor", "windsurf"). Shown in the briefing header and saved so the next provider can see who was last active.',
+        },
+        workspace_path: {
+          type: 'string',
+          description: 'Absolute path to the project root. If no session_end was found (e.g. context limit hit), reads git log to reconstruct what happened since last session.',
+        },
       },
       required: ['instance_id'],
     },
@@ -1431,7 +1860,8 @@ const TOOLS = [
       'Save a session summary when you finish working. ' +
       'Records what was accomplished, files changed, and lesson count. ' +
       'The next session_start will show this summary as "Last session". ' +
-      'Call this when ending a work session, before going idle, or before summarizing.',
+      'Call this when ending a work session, before going idle, or before summarizing. ' +
+      'Ambient Learning: if workspace_path is provided, reads git log since session start and auto-learns from commits.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1449,10 +1879,101 @@ const TOOLS = [
           type: 'number',
           description: 'Number of new lessons stored this session (optional)',
         },
+        workspace_path: {
+          type: 'string',
+          description: 'Absolute path to the project root (e.g. "/Users/you/myproject"). Enables Ambient Learning — reads git log since session start and auto-learns from commit messages.',
+        },
       },
       required: ['instance_id', 'summary'],
     },
   },
+  // ── Session Handoff — cross-window continuity ─────────────────────────────
+  {
+    name: 'session_handoff',
+    description:
+      'Save a detailed handoff for the NEXT chat window / session. ' +
+      'Stores: current progress, TODO list (done + remaining), changed files with descriptions, ' +
+      'instructions for the next assistant, and any incomplete work. ' +
+      'The next session_start automatically includes this handoff so the new window knows EXACTLY what happened and what remains. ' +
+      'Call this BEFORE closing a chat window, especially if work is incomplete. ' +
+      'This prevents the "continue" problem where new windows lose context, skip tasks, or produce broken code.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        completed_tasks: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tasks that were fully completed (e.g. "Implemented brainSearch() in JS SDK")',
+        },
+        remaining_tasks: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tasks NOT yet done — the next window MUST pick these up',
+        },
+        files_changed: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              path: { type: 'string', description: 'File path relative to project root' },
+              status: { type: 'string', enum: ['complete', 'partial', 'broken'], description: 'State of this file' },
+              description: { type: 'string', description: 'What was changed and what still needs work' },
+            },
+            required: ['path', 'status'],
+          },
+          description: 'Changed files with their current state — marks partial/broken files so next window knows to fix them',
+        },
+        instructions: {
+          type: 'string',
+          description: 'Free-form instructions for the next assistant. Be specific: what to do next, what to avoid, what broke.',
+        },
+        context_summary: {
+          type: 'string',
+          description: 'Brief summary of what happened this session (architecture decisions, key findings, blockers)',
+        },
+        blocked_on: {
+          type: 'string',
+          description: 'If work is blocked, describe what is needed to unblock (e.g. "waiting for API deploy", "needs user input on design")',
+        },
+      },
+      required: ['instance_id', 'completed_tasks', 'remaining_tasks'],
+    },
+  },
+  // ── session_ping — lightweight in-session checkpoint ─────────────────────
+  {
+    name: 'session_ping',
+    description:
+      'Lightweight checkpoint — call this every ~5 tool calls or whenever you complete a significant step. ' +
+      'Stores the current task + files touched so session_start on the NEXT provider can reconstruct what happened ' +
+      'even if session_end was never called (e.g. Claude context limit hit, window crashed). ' +
+      'This solves the provider-switching problem: Claude → Copilot → Cursor all see the same last checkpoint. ' +
+      'Extremely fast — one Redis SET, no blocking operations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        task: {
+          type: 'string',
+          description: 'What you are currently working on (e.g. "Implementing invite handler in handler/invite.go")',
+        },
+        files_touched: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Files modified so far this session',
+        },
+        next_step: {
+          type: 'string',
+          description: 'What the NEXT step is after this checkpoint (helps next provider resume immediately)',
+        },
+        provider: {
+          type: 'string',
+          description: 'Current AI provider (e.g. "claude-code", "copilot", "cursor", "windsurf")',
+        },
+      },
+      required: ['instance_id', 'task'],
+    },
+  },
   // ── AI Brain — Extended features ─────────────────────────────────────────
   {
     name: 'auto_learn_session',
@@ -1544,50 +2065,135 @@ const TOOLS = [
     },
   },
   {
-    name: 'brain_stats',
+    name: 'team_synthesize',
+    description:
+      'Team Brain Synthesis — merge multiple contributors\' lessons on the same topic into one canonical version. ' +
+      'When 2+ developers store lessons for the same topic with different details, this proposes the best merged version. ' +
+      'Shows: all contributions by author, what worked (consensus), what failed (union), canonical lesson to store. ' +
+      'Use this when onboarding new team members or before documenting a process.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the shared team brain instance' },
+        topic:       { type: 'string', description: 'Topic slug to synthesize (e.g. "deploy:api")' },
+      },
+      required: ['instance_id', 'topic'],
+    },
+  },
+  {
+    name: 'memory_crystalize',
     description:
-      'Complete statistics dashboard for your AI Brain — lessons, recalls, time saved, top topics, team authors, memory usage. ' +
-      'Returns a formatted report designed for sharing (screenshot-worthy). ' +
-      'Use this when you want a full overview or want to share your brain health with others.',
+      'Compress the last 30-50 sessions and auto-learned lessons into a dense Memory Crystal. ' +
+      'A crystal is a compact, structured summary of everything the brain learned — grouped by category (deploy, fix, debug, …). ' +
+      'Crystals survive session cleanup and appear in session_start once enough sessions have accumulated. ' +
+      'Run this monthly or after a big milestone to preserve institutional knowledge. ' +
+      'Returns a digest of what was crystallized.',
     inputSchema: {
       type: 'object',
       properties: {
         instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        label: {
+          type: 'string',
+          description: 'Optional label for this crystal (e.g. "Q1 2026", "v2 launch"). Auto-generated from date if omitted.',
+        },
       },
       required: ['instance_id'],
     },
   },
+  // ── Roadmap — Persistent project plan tracker ───────────────────────────
+  {
+    name: 'roadmap_add',
+    description:
+      'Add a new item to the persistent project roadmap stored in the Brain. ' +
+      'Items survive across sessions and editors — the roadmap is always up to date. ' +
+      'Use for features, bugs, refactors, or any planned work. ' +
+      'Call roadmap_list to see all open items, roadmap_next to get the next actionable item.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        title: { type: 'string', description: 'Short title of the task/feature (3–10 words)' },
+        description: { type: 'string', description: 'What needs to be done, acceptance criteria, context' },
+        priority: {
+          type: 'string',
+          enum: ['critical', 'high', 'medium', 'low'],
+          description: 'Priority level (default: medium)',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tags for filtering (e.g. ["api", "web", "sdk", "infra"])',
+        },
+        milestone: { type: 'string', description: 'Milestone/epic this belongs to (optional)' },
+      },
+      required: ['instance_id', 'title'],
+    },
+  },
+  {
+    name: 'roadmap_update',
+    description:
+      'Update the status, priority, or details of a roadmap item. ' +
+      'Use to move items through the lifecycle: planned → in-progress → done (or blocked/cancelled). ' +
+      'Also use to add notes/findings while working on an item.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        id: { type: 'string', description: 'Item ID returned by roadmap_add or roadmap_list' },
+        status: {
+          type: 'string',
+          enum: ['planned', 'in-progress', 'done', 'blocked', 'cancelled'],
+          description: 'New status for the item',
+        },
+        priority: {
+          type: 'string',
+          enum: ['critical', 'high', 'medium', 'low'],
+          description: 'Updated priority (optional)',
+        },
+        notes: { type: 'string', description: 'Progress notes, findings, or blockers (appended to existing notes)' },
+        title: { type: 'string', description: 'Updated title (optional)' },
+        description: { type: 'string', description: 'Updated description (optional)' },
+      },
+      required: ['instance_id', 'id'],
+    },
+  },
   {
-    name: 'export_brain',
+    name: 'roadmap_list',
     description:
-      'Export your entire AI Brain as a portable Markdown file. ' +
-      'Includes all lessons (topic, outcome, what worked, severity), context entries (keys + content), ' +
-      'session history, and metadata. Perfect for sharing with teammates, archiving, posting to GitHub, ' +
-      'or importing into a new instance. ' +
-      'Example: export_brain() → returns full markdown string you can save to a .md file.',
+      'List all roadmap items, optionally filtered by status, priority, tag, or milestone. ' +
+      'Returns items sorted by priority then creation date. ' +
+      'Called automatically by session_start to show open work.',
     inputSchema: {
       type: 'object',
       properties: {
         instance_id: { type: 'string', description: 'UUID of the cache instance' },
-        include_context: { type: 'boolean', description: 'Include context entries (default: true)' },
-        max_lessons:    { type: 'number',  description: 'Max lessons to include (default: all)' },
+        status: {
+          type: 'string',
+          enum: ['planned', 'in-progress', 'done', 'blocked', 'cancelled', 'open'],
+          description: 'Filter by status. Use \'open\' to see planned+in-progress+blocked (default: open)',
+        },
+        tag: { type: 'string', description: 'Filter by tag (optional)' },
+        milestone: { type: 'string', description: 'Filter by milestone (optional)' },
+        priority: {
+          type: 'string',
+          enum: ['critical', 'high', 'medium', 'low'],
+          description: 'Filter by minimum priority (optional)',
+        },
       },
       required: ['instance_id'],
     },
   },
   {
-    name: 'invite_link',
+    name: 'roadmap_next',
     description:
-      'Generate a one-click team invite link for your Brain instance. ' +
-      'Share the link (or the npx join command) with a teammate — they run one command and are instantly ' +
-      'connected to the same shared Brain with all your lessons and context. ' +
-      'No dashboard visit, no copy-paste of instance IDs required. ' +
-      'Example: invite_link() → returns "npx @cachly-dev/mcp-server@latest join <token>"',
+      'Get the single most important next actionable roadmap item. ' +
+      'Returns the highest-priority in-progress item first, then planned items, sorted by priority. ' +
+      'Call at session start to immediately know what to work on next.',
     inputSchema: {
       type: 'object',
       properties: {
-        instance_id: { type: 'string', description: 'UUID of the cache instance to share' },
-        label:       { type: 'string', description: 'Optional label shown to the invitee (e.g. "my-api project")' },
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        tag: { type: 'string', description: 'Filter by tag (optional)' },
       },
       required: ['instance_id'],
     },
@@ -1596,12 +2202,16 @@ const TOOLS = [
     name: 'brain_doctor',
     description:
       'Check the health of your AI Brain and get actionable recommendations. ' +
-      'Reports: lesson count, context entries, last session age, open failures, quality score. ' +
+      'Reports: lesson count, context entries, last session age, open failures, quality score, effective IQ boost, stale index. ' +
       'Returns a prioritized list of issues with fix instructions.',
     inputSchema: {
       type: 'object',
       properties: {
         instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        workspace_path: {
+          type: 'string',
+          description: 'Absolute path to workspace root — enables package.json analysis for openclaw cross-promo (optional)',
+        },
       },
       required: ['instance_id'],
     },
@@ -1673,6 +2283,100 @@ const TOOLS = [
       required: ['instance_id', 'framework'],
     },
   },
+  // ── Brain Archaeology + Causal Chain ────────────────────────────────────
+  {
+    name: 'recall_at',
+    description:
+      'Brain Archaeology — see what a lesson looked like at a specific point in time. ' +
+      '"What did we know about deployments 3 months ago?" ' +
+      'Returns the history of a topic filtered to entries before the given date. ' +
+      'Shows how the lesson evolved: failure → partial → success. ' +
+      'Also useful to understand WHY old code decisions were made.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        topic:       { type: 'string', description: 'Topic slug to look up, e.g. "deploy:api"' },
+        date:        { type: 'string', description: 'ISO date string (e.g. "2026-01-15") — returns entries stored BEFORE this date' },
+      },
+      required: ['instance_id', 'topic', 'date'],
+    },
+  },
+  {
+    name: 'trace_dependency',
+    description:
+      'Causal Chain — find all lessons that depend on a given prerequisite. ' +
+      '"What lessons are affected if node version changes?" ' +
+      'When a dependency changes (new version, different provider, new OS), call this to see which lessons need review. ' +
+      'Lessons store dependencies via the depends_on field in learn_from_attempts.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        dependency:  { type: 'string', description: 'Dependency to trace (e.g. "node:>=20", "docker:running", "wireguard:active")' },
+        mark_review: { type: 'boolean', description: 'If true, marks all dependent lessons as needs_review (default: false)' },
+      },
+      required: ['instance_id', 'dependency'],
+    },
+  },
+  // ── Team / Org Management ────────────────────────────────────────────────
+  {
+    name: 'list_orgs',
+    description:
+      'List your Cachly organizations (team/org plans). ' +
+      'Returns each org with plan, seat count, and member info. ' +
+      'Org plans (Team €99, Business €299, Enterprise custom) are billed separately from cache tiers.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: 'create_org',
+    description:
+      'Create a new Cachly organization for team collaboration. ' +
+      'After creation, invite team members with invite_member and upgrade the plan via the billing portal. ' +
+      'Org plans: Team (€99/mo, 10 seats), Business (€299/mo, 50 seats), Enterprise (custom).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Organization display name (e.g. "Acme Engineering")' },
+        slug: { type: 'string', description: 'URL-safe slug (e.g. "acme-eng"). Auto-generated from name if omitted.' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'invite_member',
+    description:
+      'Invite a team member to a Cachly organization by email. ' +
+      'They will receive an invite email and can join via the dashboard. ' +
+      'Roles: owner (full access), admin (manage members + instances), member (read + cache ops).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        org_id: { type: 'string', description: 'UUID of the organization' },
+        email:  { type: 'string', description: 'Email address to invite' },
+        role:   { type: 'string', enum: ['admin', 'member'], description: 'Role for the invited member (default: member)' },
+      },
+      required: ['org_id', 'email'],
+    },
+  },
+  {
+    name: 'get_org_plan',
+    description:
+      'Get the current org plan, seat usage, and billing info for an organization. ' +
+      'Shows: plan name, price, seats used/max, next billing date. ' +
+      'To upgrade: use the billing portal URL returned by this tool.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        org_id: { type: 'string', description: 'UUID of the organization' },
+      },
+      required: ['org_id'],
+    },
+  },
   // ── Legacy / Setup ────────────────────────────────────────────────────────
   {
     name: 'setup_ai_memory',
@@ -1770,10 +2474,50 @@ function buildConnectionString(inst: Instance): string {
   return `${scheme}://${pw}${inst.host}:${inst.port}`;
 }
 
+// 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'
+    : process.env.WINDSURF_SESSION_ID ? 'windsurf'
+    : process.env.GITHUB_COPILOT_WORKSPACE ? 'copilot'
+    : process.env.CLAUDE_CODE_ENTRYPOINT ? 'claude'
+    : 'unknown';
+  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 }),
+      signal: AbortSignal.timeout(3000),
+    });
+  } catch { /* fire-and-forget, never block the user */ }
+}
+
 async function handleTool(name: string, args: Record<string, unknown>): Promise<string> {
-  // Default instance_id from env so tools work even if AI omits it
-  if (!args.instance_id && process.env.CACHLY_BRAIN_INSTANCE_ID) {
-    args = { ...args, instance_id: process.env.CACHLY_BRAIN_INSTANCE_ID };
+  // Guard: if no JWT, return actionable onboarding message instead of HTTP 401
+  if (!JWT) {
+    void sendAnonymousTelemetry(name);
+    return [
+      '🧠 **cachly AI Brain — Setup required**',
+      '',
+      'You have no API credentials configured. Get started in 30 seconds:',
+      '',
+      '**Step 1:** Register for free (no credit card):',
+      '   👉 https://cachly.dev/setup-ai',
+      '',
+      '**Step 2:** Run the setup wizard in your terminal:',
+      '   ```',
+      '   npx @cachly-dev/mcp-server@latest setup',
+      '   ```',
+      '',
+      'The wizard auto-detects your editor (Claude Code, Cursor, Copilot, Windsurf)',
+      'and writes the config file with your credentials.',
+      '',
+      '✨ Free tier includes: 1 Brain instance, persistent memory, semantic search.',
+    ].join('\n');
   }
 
   // Delegate v0.2 bulk/lock/stream tools first
@@ -1794,7 +2538,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       const { name: instName, tier } = args as { name: string; tier: string };
       const res = await apiFetch<CreateResponse>('/api/v1/instances', {
         method: 'POST',
-        body: JSON.stringify({ name: instName, tier }),
+        body: JSON.stringify({ name: instName, tier, created_via: 'api' }),
       });
       if (res.checkout_url) {
         return [
@@ -1854,25 +2598,88 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       return `✅ Instance \`${instance_id}\` has been deleted and all data removed.`;
     }
 
-    // ── Live cache operations ────────────────────────────────────────────
-    case 'cache_get': {
-      const { instance_id, key } = args as { instance_id: string; key: string };
-      const redis = await getConnection(instance_id);
-      const value = await redis.get(key);
-      if (value === null) return `Key \`${key}\` → **not found** (null)`;
-      let pretty = value;
-      try {
-        pretty = JSON.stringify(JSON.parse(value), null, 2);
-      } catch {
-        // not JSON — return raw
-      }
-      return `Key \`${key}\`:\n\`\`\`\n${pretty}\n\`\`\``;
+    // ── Org / Team management ────────────────────────────────────────────
+    case 'list_orgs': {
+      const res = await apiFetch<{ orgs: Array<{ id: string; name: string; slug: string; plan: string; max_members: number; member_count?: number }> }>('/api/v1/orgs');
+      const orgs = res.orgs ?? [];
+      if (orgs.length === 0) return `📭 No organizations yet.\n\nCreate one with \`create_org(name="My Team")\`.\nOrg plans: Team €99/mo (10 seats), Business €299/mo (50 seats), Enterprise custom.`;
+      return [
+        `🏢 **Your organizations (${orgs.length})**\n`,
+        ...orgs.map(o => `• **${o.name}** (\`${o.slug}\`) — plan: ${o.plan} · seats: ${o.member_count ?? '?'}/${o.max_members}\n  ID: \`${o.id}\``),
+        `\n_Manage: \`get_org_plan\`, \`invite_member\`, dashboard → /team_`,
+      ].join('\n');
     }
 
-    case 'cache_set': {
-      const { instance_id, key, value, ttl } = args as {
-        instance_id: string;
-        key: string;
+    case 'create_org': {
+      const { name: orgName, slug } = args as { name: string; slug?: string };
+      const body: Record<string, string> = { name: orgName };
+      if (slug) body.slug = slug;
+      const res = await apiFetch<{ id: string; name: string; slug: string; plan: string }>('/api/v1/orgs', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+      return [
+        `✅ **Organization created:** ${res.name}`,
+        `   ID: \`${res.id}\` · Slug: \`${res.slug}\` · Plan: ${res.plan}`,
+        ``,
+        `**Next steps:**`,
+        `1. Invite team members: \`invite_member(org_id="${res.id}", email="dev@example.com")\``,
+        `2. Upgrade plan: open billing portal via dashboard → /team`,
+        `   Team: €99/mo (10 seats) · Business: €299/mo (50 seats)`,
+      ].join('\n');
+    }
+
+    case 'invite_member': {
+      const { org_id, email, role = 'member' } = args as { org_id: string; email: string; role?: string };
+      await apiFetch(`/api/v1/orgs/${org_id}/members`, {
+        method: 'POST',
+        body: JSON.stringify({ email, role }),
+      });
+      return `✅ Invite sent to **${email}** as \`${role}\` in org \`${org_id}\`.\n\nThey will receive an email to join the organization.`;
+    }
+
+    case 'get_org_plan': {
+      const { org_id } = args as { org_id: string };
+      const org = await apiFetch<{
+        id: string; name: string; plan: string; max_members: number;
+        members: Array<{ role: string; invite_email: string; accepted_at?: string }>;
+        stripe_customer_id?: string;
+      }>(`/api/v1/orgs/${org_id}`);
+      const accepted = (org.members ?? []).filter(m => m.accepted_at).length;
+      const pending = (org.members ?? []).filter(m => !m.accepted_at).length;
+      const planPrice: Record<string, string> = { free: '€0', team: '€99/mo', business: '€299/mo', enterprise: 'custom' };
+      return [
+        `🏢 **${org.name}** — Plan: **${org.plan}** (${planPrice[org.plan] ?? org.plan})`,
+        `   Seats: ${accepted} active + ${pending} pending / ${org.max_members} max`,
+        ``,
+        `**Members:**`,
+        ...(org.members ?? []).map(m => `  • ${m.invite_email} (${m.role})${m.accepted_at ? '' : ' — pending'}`),
+        ``,
+        org.stripe_customer_id
+          ? `💳 Billing: managed via Stripe. Upgrade/cancel: dashboard → /billing`
+          : `💳 No payment method yet. Upgrade: dashboard → /billing → Team Plans`,
+      ].join('\n');
+    }
+
+    // ── Live cache operations ────────────────────────────────────────────
+    case 'cache_get': {
+      const { instance_id, key } = args as { instance_id: string; key: string };
+      const redis = await getConnection(instance_id);
+      const value = await redis.get(key);
+      if (value === null) return `Key \`${key}\` → **not found** (null)`;
+      let pretty = value;
+      try {
+        pretty = JSON.stringify(JSON.parse(value), null, 2);
+      } catch {
+        // not JSON — return raw
+      }
+      return `Key \`${key}\`:\n\`\`\`\n${pretty}\n\`\`\``;
+    }
+
+    case 'cache_set': {
+      const { instance_id, key, value, ttl } = args as {
+        instance_id: string;
+        key: string;
         value: string;
         ttl?: number;
       };
@@ -2280,6 +3087,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       let skipped = 0;
       let errors = 0;
       let semanticIndexed = 0;
+      let unchanged = 0;
       const details: string[] = [];
       const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
       const redis = await getConnection(instance_id);
@@ -2287,15 +3095,31 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       for (const filePath of files) {
         const relPath = relative(dir, filePath);
         let content: string;
+        let fileSize: number;
         try {
           const s = await stat(filePath);
           if (s.size > 200_000) { skipped++; continue; } // skip files >200 KB
+          fileSize = s.size;
           content = await readFile(filePath, 'utf-8');
         } catch {
           errors++;
           continue;
         }
 
+        // ── Smart invalidation: hash-based change detection ──
+        // Compute a simple hash of file content to skip unchanged files
+        const hashKey = `cachly:idx:hash:${relPath}`;
+        const contentHash = `${fileSize}:${content.length}:${simpleHash(content)}`;
+        const existingHash = await redis.get(hashKey);
+        if (existingHash === contentHash) {
+          // File unchanged — refresh TTL but skip re-indexing
+          const idxKey = `cachly:idx:${relPath}`;
+          if (ttl > 0) await redis.expire(idxKey, ttl);
+          if (ttl > 0) await redis.expire(hashKey, ttl);
+          unchanged++;
+          continue;
+        }
+
         const excerpt = content.slice(0, summary_chars).replace(/\s+/g, ' ').trim();
 
         // ── Layer 1: Keyword index in Valkey (always works, no embedding needed) ──
@@ -2306,6 +3130,12 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         } else {
           await redis.set(idxKey, idxValue);
         }
+        // Store content hash for smart invalidation on next run
+        if (ttl > 0) {
+          await redis.set(hashKey, contentHash, 'EX', ttl);
+        } else {
+          await redis.set(hashKey, contentHash);
+        }
         indexed++;
         details.push(`  ✅ ${relPath}`);
 
@@ -2334,7 +3164,8 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         `📂 **index_project Complete** — ${mode}`,
         ``,
         `  📁 Dir:       ${dir}`,
-        `  ✅ Indexed:   **${indexed}** files (keyword-searchable via smart_recall)`,
+        `  ✅ Indexed:   **${indexed}** files (new/changed)`,
+        `  ♻️  Unchanged: ${unchanged} files (hash match — skipped)`,
         ...(canEmbed ? [`  🎯 Semantic:  **${semanticIndexed}** files (vector-searchable)`] : []),
         `  ⏭️  Skipped:   ${skipped} (too large or filtered)`,
         `  ❌ Errors:    ${errors}`,
@@ -2382,8 +3213,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         await redis.set(`${cacheKey}:meta`, meta);
       }
 
-      // Also index semantically for smart_recall (if vector available and embedding is configured)
-      if (EMBED_PROVIDER !== 'none') {
+      // Also index semantically for smart_recall (if vector available)
       const inst = await apiFetch<Instance>(`/api/v1/instances/${instance_id}`);
       if (inst.vector_token) {
         try {
@@ -2407,7 +3237,6 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
           // Embedding optional — continue silently
         }
       }
-      } // end EMBED_PROVIDER !== 'none'
 
       return [
         `🧠 **Context Saved**`,
@@ -2559,6 +3388,8 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         file_paths = [],
         commands = [],
         tags = [],
+        depends_on = [],
+        author = '',
       } = args as {
         instance_id: string;
         topic: string;
@@ -2570,26 +3401,107 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         file_paths?: string[];
         commands?: string[];
         tags?: string[];
+        depends_on?: string[];
+        author?: string;
       };
 
       const redis = await getConnection(instance_id);
       const ts = new Date().toISOString();
 
-      // ── Deduplication: check for existing lesson with same topic ─────────────
+      // ── Structured template hints ──────────────────────────────────────────
+      const category = topic.split(':')[0];
+      const template = STRUCTURED_TEMPLATES[category];
+      const templateWarnings: string[] = [];
+      if (template) {
+        for (const req of template.required) {
+          if (req === 'commands' && commands.length === 0) {
+            templateWarnings.push(`📋 ${template.hint}`);
+          }
+        }
+      }
+
+      // ── Deduplication + audit trail ────────────────────────────────────────
       let isUpdate = false;
       let recallCount = 0;
-      if (outcome === 'success') {
-        const existing = await redis.get(`cachly:lesson:best:${topic}`);
-        if (existing) {
+      let auditTrail: Array<{ ts: string; action: string; prev_outcome?: string }> = [];
+      const existingRaw = await redis.get(`cachly:lesson:best:${topic}`);
+      if (existingRaw) {
+        try {
+          const prev = JSON.parse(existingRaw) as {
+            recall_count?: number;
+            outcome?: string;
+            audit_trail?: Array<{ ts: string; action: string; prev_outcome?: string }>;
+          };
+          recallCount = prev.recall_count ?? 0;
+          auditTrail = prev.audit_trail ?? [];
+          auditTrail.push({ ts, action: 'updated', prev_outcome: prev.outcome });
+          if (auditTrail.length > 20) auditTrail = auditTrail.slice(-20);
+          isUpdate = true;
+
+          // ── Contradiction detection ─────────────────────────────────────────
+          const contradictionWarning: string[] = [];
+          if (prev.outcome === 'success' && outcome === 'failure') {
+            contradictionWarning.push(
+              `⚠️ **Contradiction detected!** Existing lesson has outcome: \`success\`, but you're storing \`failure\`.`,
+              `The existing "success" lesson will be preserved. Only the audit trail is updated.`,
+              `If you meant to mark this as failed permanently, store a new lesson with a distinct topic slug.`,
+            );
+          } else if (prev.outcome === 'failure' && outcome === 'success') {
+            contradictionWarning.push(
+              `✅ **Conflict resolved!** Previous lesson was \`failure\` — now overwriting with \`success\`.`,
+            );
+          }
+          if (contradictionWarning.length > 0) {
+            // Store contradiction audit but don't block
+            auditTrail[auditTrail.length - 1].action = 'contradiction-resolved';
+          }
+        } catch { /* ignore parse error */ }
+      } else {
+        auditTrail = [{ ts, action: 'created' }];
+      }
+
+      // ── "I Was Wrong" Protocol — failure attribution ───────────────────────
+      const iWasWrongWarning: string[] = [];
+      if (outcome === 'failure') {
+        // Search for related success lessons that might have prevented this failure
+        const scanKeys: string[] = [];
+        const scanStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 100 });
+        await new Promise<void>((res, rej) => {
+          scanStream.on('data', (b: string[]) => scanKeys.push(...b));
+          scanStream.on('end', res);
+          scanStream.on('error', rej);
+        });
+        const topicWords = topic.split(/[:\-_]/).filter(w => w.length > 2);
+        for (const k of scanKeys.slice(0, 50)) {
+          const raw = await redis.get(k);
+          if (!raw) continue;
           try {
-            const prev = JSON.parse(existing) as { recall_count?: number };
-            recallCount = (prev.recall_count ?? 0); // preserve existing recall count
-            isUpdate = true;
-          } catch { /* ignore parse error */ }
+            const l = JSON.parse(raw) as { outcome?: string; topic?: string; severity?: string };
+            if (l.outcome !== 'success') continue;
+            const lWords = (l.topic ?? '').split(/[:\-_]/).filter(w => w.length > 2);
+            const overlap = topicWords.filter(w => lWords.includes(w)).length;
+            if (overlap >= 1 && l.topic !== topic) {
+              iWasWrongWarning.push(
+                `⚠️ **"I Was Wrong"**: lesson \`${l.topic}\` (success, ${l.severity ?? 'major'}) might have prevented this failure.`,
+                `   → Use \`recall_best_solution(topic="${l.topic}")\` before next attempt.`,
+                `   → To mark it critical: \`learn_from_attempts(topic="${l.topic}", ..., severity="critical")\``,
+              );
+              break; // only show the most relevant match
+            }
+          } catch { /* skip */ }
         }
       }
 
-      const lesson = JSON.stringify({
+      // ── Register dependency index for causal chain ─────────────────────────
+      for (const dep of depends_on) {
+        const depKey = `cachly:dep:${dep}`;
+        const existing = await redis.get(depKey);
+        const depTopics: string[] = existing ? JSON.parse(existing) : [];
+        if (!depTopics.includes(topic)) depTopics.push(topic);
+        await redis.set(depKey, JSON.stringify(depTopics));
+      }
+
+      const lessonObj = {
         topic,
         outcome,
         what_worked,
@@ -2599,20 +3511,36 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         file_paths,
         commands,
         tags,
+        depends_on,
+        ...(author ? { author } : {}),
         recall_count: recallCount,
         ts,
-        version: 2,
-      });
+        verified_at: outcome === 'success' || outcome === 'partial' ? ts : undefined,
+        confidence: 1.0,
+        audit_trail: auditTrail,
+        version: 3,
+      };
+      const lesson = JSON.stringify(lessonObj);
 
-      // Always append to the history list
+      // Always append to the history list (audit log)
       const listKey = `cachly:lessons:${topic}`;
       await redis.rpush(listKey, lesson);
 
-      // Update best key only for success/partial (not for failures)
+      // Update best key for success/partial; for failure only update if no success exists
       if (outcome === 'success' || outcome === 'partial') {
         await redis.set(`cachly:lesson:best:${topic}`, lesson);
+      } else if (!existingRaw) {
+        await redis.set(`cachly:lesson:best:${topic}`, lesson);
       }
 
+      // Track in decision log for session replay
+      try {
+        const dlKey = 'cachly:session:decision-log';
+        const dlEntry = JSON.stringify({ ts, topic, outcome, what_worked: what_worked.slice(0, 120) });
+        await redis.rpush(dlKey, dlEntry);
+        await redis.ltrim(dlKey, -50, -1);
+      } catch { /* non-critical */ }
+
       const emoji = outcome === 'success' ? '✅' : outcome === 'partial' ? '⚠️' : '❌';
       const sevEmoji = severity === 'critical' ? '🔴' : severity === 'major' ? '🟡' : '🟢';
       const action = isUpdate ? 'updated' : 'stored';
@@ -2627,8 +3555,13 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         tags.length > 0 ? `**Tags:** ${tags.map(t => `#${t}`).join(' ')}` : '',
         ``,
         isUpdate
-          ? `♻️ Updated existing lesson (preserved recall count: ${recallCount})`
+          ? `♻️ Updated (recall count: ${recallCount} · audit entries: ${auditTrail.length})`
           : `💡 Recall later with \`recall_best_solution(topic="${topic}")\``,
+        depends_on.length > 0
+          ? `🔗 Depends on: ${depends_on.map(d => `\`${d}\``).join(', ')} → trace with \`trace_dependency\``
+          : '',
+        ...templateWarnings,
+        ...iWasWrongWarning,
       ].filter(l => l !== '').join('\n');
     }
 
@@ -2639,43 +3572,47 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       // Try exact best-solution key first
       const best = await redis.get(`cachly:lesson:best:${topic}`);
       if (best) {
-        let lesson: {
+        const lesson = JSON.parse(best) as {
           topic: string; outcome: string; what_worked: string; what_failed?: string;
-          context?: string; ts: string; severity?: string; file_paths?: string[];
-          commands?: string[]; tags?: string[]; recall_count?: number;
+          context?: string; ts: string; verified_at?: string; severity?: string;
+          file_paths?: string[]; commands?: string[]; tags?: string[];
+          recall_count?: number; audit_trail?: unknown[];
         };
-        try { lesson = JSON.parse(best); } catch {
-          return `⚠️ Lesson for \`${topic}\` could not be read (corrupted data). Use \`learn_from_attempts\` to overwrite it.`;
-        }
-        // Increment recall_count
-        const updatedLesson = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1 };
-        await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(updatedLesson));
 
-        // Fire-and-forget: track Magic Moment in Plausible + API engagement counter
-        const isFirstRecall = (lesson.recall_count ?? 0) === 0;
-        const recallEvent = isFirstRecall ? 'First Brain Recall' : 'Brain Recall Hit';
-        fetch('https://analytics.cachly.dev/api/event', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json', 'User-Agent': 'cachly-mcp/recall' },
-          body: JSON.stringify({
-            domain: 'cachly.dev', name: recallEvent,
-            url: 'https://cachly.dev/mcp/recall', props: { topic },
-          }),
-        }).catch(() => { /* non-critical */ });
-        if (JWT) {
-          fetch(`${API_URL}/api/v1/telemetry/mcp`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ event: isFirstRecall ? 'first_recall' : 'recall', api_key: JWT }),
-          }).catch(() => { /* non-critical */ });
-        }
+        // ── Confidence decay check ───────────────────────────────────────────
+        const confidence = calculateConfidence(lesson);
+        const ref = lesson.verified_at ?? lesson.ts;
+        const ageDays = (Date.now() - new Date(ref).getTime()) / 86400000;
+        const badge = confidenceBadge(confidence, ageDays);
+
+        // Recall resets verified_at (confidence clock restart)
+        const updatedLesson = {
+          ...lesson,
+          recall_count: (lesson.recall_count ?? 0) + 1,
+          verified_at: new Date().toISOString(),
+          confidence: 1.0,
+        };
+        await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(updatedLesson));
 
         const sevEmoji = lesson.severity === 'critical' ? '🔴' : lesson.severity === 'major' ? '🟡' : lesson.severity ? '🟢' : '';
-        const sessionAgeMs = Date.now() - new Date(lesson.ts).getTime();
-        const sessionAgeDays = Math.round(sessionAgeMs / 86_400_000);
-        const ageLabel = sessionAgeDays === 0 ? 'today' : sessionAgeDays === 1 ? 'yesterday' : `${sessionAgeDays} days ago`;
+        const auditSummary = (lesson.audit_trail ?? []).length > 1
+          ? `_Audit: ${(lesson.audit_trail ?? []).length} changes · stored ${new Date(lesson.ts).toLocaleDateString('de-DE')}_`
+          : '';
+
+        // "Remember when..." — emotional header for lessons > 60 days old
+        const ageFromStoreDays = (Date.now() - new Date(lesson.ts).getTime()) / 86400000;
+        const rememberWhen = ageFromStoreDays > 60
+          ? `💭 _Remember when you solved this ${Math.round(ageFromStoreDays / 30)} months ago? Still works._`
+          : '';
+
+        // "Never Google This Again" — suggest pinning after 3rd recall
+        const suggestPin = updatedLesson.recall_count === 3 && !(lesson as { pinned?: boolean }).pinned
+          ? `📌 **You've looked this up 3 times.** Consider pinning it for instant access: add \`pinned: true\` via \`learn_from_attempts\` to always surface it first.`
+          : '';
+
         return [
-          `✅ **Best solution for \`${topic}\`** ${sevEmoji}${lesson.severity ? ` (${lesson.severity})` : ''} · recalled ${updatedLesson.recall_count}× · stored ${ageLabel}`,
+          rememberWhen,
+          `${badge} **Best solution for \`${topic}\`** ${sevEmoji}${lesson.severity ? ` (${lesson.severity})` : ''} · recalled ${updatedLesson.recall_count}×`,
           ``,
           `**What worked:** ${lesson.what_worked}`,
           lesson.what_failed ? `**What failed (avoid this):** ${lesson.what_failed}` : '',
@@ -2683,8 +3620,8 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
           (lesson.file_paths ?? []).length > 0 ? `**Files:** ${(lesson.file_paths ?? []).map((f: string) => `\`${f}\``).join(', ')}` : '',
           (lesson.commands ?? []).length > 0 ? `**Commands:** ${(lesson.commands ?? []).map((c: string) => `\`${c}\``).join(', ')}` : '',
           (lesson.tags ?? []).length > 0 ? `**Tags:** ${(lesson.tags ?? []).map((t: string) => `#${t}`).join(' ')}` : '',
-          ``,
-          `> 🧠 *Your AI remembered this from ${ageLabel} — persistent memory by [cachly.dev](https://cachly.dev)*`,
+          auditSummary,
+          suggestPin,
         ].filter(l => l !== '').join('\n');
       }
 
@@ -2703,7 +3640,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         const histKey = `cachly:lessons:${topic}`;
         const all = await redis.lrange(histKey, -3, -1);
         if (all.length > 0) {
-          const parsed = all.flatMap(e => { try { return [JSON.parse(e) as { outcome: string; what_worked: string; ts: string }]; } catch { return []; } });
+          const parsed = all.map(e => JSON.parse(e) as { outcome: string; what_worked: string; ts: string });
           const lines = parsed.map(p => `- ${p.outcome === 'success' ? '✅' : '❌'} ${p.what_worked.slice(0, 120)} (${new Date(p.ts).toLocaleDateString('de-DE')})`);
           return `⚠️ No successful solution for \`${topic}\` yet. Last attempts:\n\n${lines.join('\n')}`;
         }
@@ -2715,70 +3652,12 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       for (const k of matching.slice(0, 5)) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        let lesson: { topic: string; what_worked: string; context?: string; ts: string };
-        try { lesson = JSON.parse(raw); } catch { continue; }
+        const lesson = JSON.parse(raw) as { topic: string; what_worked: string; context?: string; ts: string };
         results.push(`**\`${lesson.topic}\`** — ${lesson.what_worked.slice(0, 200)}`);
       }
       return `🔍 **Partial matches for \`${topic}\`:**\n\n${results.join('\n\n')}`;
     }
 
-    case 'list_lessons': {
-      const { instance_id, filter = '' } = args as { instance_id: string; filter?: string };
-      const redis = await getConnection(instance_id);
-      const keys: string[] = [];
-      const stream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
-      await new Promise<void>((resolve, reject) => {
-        stream.on('data', (batch: string[]) => keys.push(...batch));
-        stream.on('end', resolve);
-        stream.on('error', reject);
-      });
-      if (keys.length === 0) return `📭 No lessons stored yet. Use \`learn_from_attempts\` after solving any problem.`;
-
-      const values = await redis.mget(...keys);
-      type LessonMeta = { topic: string; ts: string; severity?: string; recall_count?: number; outcome?: string };
-      const lessons: LessonMeta[] = values.flatMap(raw => {
-        if (!raw) return [];
-        try { return [JSON.parse(raw) as LessonMeta]; } catch { return []; }
-      });
-
-      const filtered = filter
-        ? lessons.filter(l => l.topic.toLowerCase().includes(filter.toLowerCase()))
-        : lessons;
-
-      filtered.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
-
-      if (filtered.length === 0) return `📭 No lessons matching \`${filter}\`.`;
-
-      const sevEmoji = (s?: string) => s === 'critical' ? '🔴' : s === 'major' ? '🟡' : '🟢';
-      const lines = [
-        `🧠 **${filtered.length} lesson${filtered.length === 1 ? '' : 's'}${filter ? ` matching "${filter}"` : ''} in Brain:**`,
-        '',
-        ...filtered.slice(0, 30).map(l => {
-          const age = Math.round((Date.now() - new Date(l.ts).getTime()) / 86400000);
-          const ageStr = age === 0 ? 'today' : age === 1 ? 'yesterday' : `${age}d ago`;
-          const recalls = l.recall_count ? ` · recalled ${l.recall_count}×` : '';
-          return `${sevEmoji(l.severity)} \`${l.topic}\` — ${ageStr}${recalls}`;
-        }),
-        filtered.length > 30 ? `\n_…and ${filtered.length - 30} more. Use filter to narrow down._` : '',
-      ].filter(l => l !== '');
-      return lines.join('\n');
-    }
-
-    case 'forget_lesson': {
-      const { instance_id, topic } = args as { instance_id: string; topic: string };
-      const redis = await getConnection(instance_id);
-      const bestKey = `cachly:lesson:best:${topic}`;
-      const histKey = `cachly:lessons:${topic}`;
-      const [delBest, delHist] = await Promise.all([
-        redis.del(bestKey),
-        redis.del(histKey),
-      ]);
-      if (delBest === 0 && delHist === 0) {
-        return `📭 No lesson found for \`${topic}\` — nothing to delete.`;
-      }
-      return `🗑️ Lesson for \`${topic}\` deleted (best-solution: ${delBest > 0 ? 'removed' : 'not found'}, history: ${delHist > 0 ? 'removed' : 'not found'}). You can now store a corrected lesson with \`learn_from_attempts\`.`;
-    }
-
     case 'smart_recall': {
       const {
         instance_id,
@@ -2893,32 +3772,18 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
 
     // ── get_api_status ────────────────────────────────────────────────────────
     case 'get_api_status': {
-      // Check API health and auth service in parallel
-      const [healthResult, authServiceResult] = await Promise.allSettled([
-        fetch(`${API_URL}/health`, { signal: AbortSignal.timeout(5000) }),
-        fetch(`${AUTH_URL}/.well-known/openid-configuration`, { signal: AbortSignal.timeout(5000) }),
-      ]);
-
+      // Check health
       let healthStatus = 'unknown';
-      if (healthResult.status === 'fulfilled') {
-        const healthRes = healthResult.value;
+      try {
+        const healthRes = await fetch(`${API_URL}/health`);
         if (healthRes.ok) {
-          const body = await healthRes.json().catch(() => ({})) as { status?: string; db?: string };
-          healthStatus = `✅ ${body.status ?? 'ok'}${body.db ? ` (db: ${body.db})` : ''}`;
+          const body = await healthRes.json() as { status?: string; db?: string };
+          healthStatus = `${body.status ?? 'ok'} (db: ${body.db ?? '?'})`;
         } else {
-          healthStatus = `❌ HTTP ${healthRes.status}`;
+          healthStatus = `HTTP ${healthRes.status}`;
         }
-      } else {
-        healthStatus = `❌ unreachable: ${healthResult.reason?.message ?? 'timeout'}`;
-      }
-
-      let authSvcStatus = 'unknown';
-      if (authServiceResult.status === 'fulfilled') {
-        authSvcStatus = authServiceResult.value.ok
-          ? `✅ reachable (${AUTH_URL})`
-          : `❌ HTTP ${authServiceResult.value.status} — auth service may be down`;
-      } else {
-        authSvcStatus = `❌ unreachable: ${authServiceResult.reason?.message ?? 'timeout'} — auth service may be down`;
+      } catch (e) {
+        healthStatus = `unreachable: ${(e as Error).message}`;
       }
 
       // Check JWT / auth
@@ -2926,18 +3791,16 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         return [
           `📡 **cachly API Status**`,
           ``,
-          `  🌐 API:          ${API_URL}`,
-          `  💓 API Health:   ${healthStatus}`,
-          `  🔐 Auth Service: ${authSvcStatus}`,
-          `  🔑 JWT:          ❌ CACHLY_JWT not set`,
+          `  🌐 API:      ${API_URL}`,
+          `  💓 Health:   ${healthStatus}`,
+          `  🔑 Auth:     ❌ CACHLY_JWT not set`,
           ``,
-          `💡 Get your API token at https://cachly.dev/settings`,
+          `💡 Get your API token at https://cachly.dev/instances → Settings → API Token`,
         ].join('\n');
       }
 
       // Decode JWT claims (inspection only, no verification)
       let authInfo = '❌ invalid JWT format';
-      let isExpired = false;
       try {
         const parts = JWT.split('.');
         if (parts.length === 3) {
@@ -2948,44 +3811,33 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
           const iss = payload.iss ?? '(unknown)';
           const provider = iss.includes('keycloak') ? 'Keycloak' : 'OIDC';
           const expTs = payload.exp ? new Date(payload.exp * 1000) : null;
-          isExpired = expTs ? expTs < new Date() : false;
+          const expired = expTs ? expTs < new Date() : false;
           authInfo = [
-            `${isExpired ? '⚠️ ' : '✅'} JWT decoded`,
+            `✅ JWT decoded`,
             `  Sub (user ID): ${sub}`,
             `  Provider:      ${provider}`,
             `  Issuer:        ${iss}`,
-            `  Expires:       ${expTs ? expTs.toISOString() : 'never'} ${isExpired ? '⚠️  EXPIRED' : '✅'}`,
+            `  Expires:       ${expTs ? expTs.toISOString() : 'never'} ${expired ? '⚠️  EXPIRED – get a new token!' : '✅'}`,
           ].join('\n');
         }
       } catch {
         authInfo = '❌ JWT decode failed – check CACHLY_JWT format';
       }
 
-      const lines = [
+      return [
         `📡 **cachly API Status**`,
         ``,
-        `  🌐 API:          ${API_URL}`,
-        `  💓 API Health:   ${healthStatus}`,
-        `  🔐 Auth Service: ${authSvcStatus}`,
+        `  🌐 API:    ${API_URL}`,
+        `  💓 Health: ${healthStatus}`,
         ``,
-        `🔑 **Auth (JWT):**`,
+        `🔑 **Auth:**`,
         authInfo,
-      ];
-
-      if (isExpired) {
-        lines.push(``, `⚠️  Your token is expired — get a new one at https://cachly.dev/settings`);
-      }
-      if (authSvcStatus.startsWith('❌')) {
-        lines.push(``, `⚠️  Auth service appears down. Registration and login on cachly.dev may be unavailable.`);
-        lines.push(`   Contact support@cachly.dev if this persists.`);
-      }
-
-      return lines.join('\n');
+      ].join('\n');
     }
 
     // ── session_start ─────────────────────────────────────────────────────────
     case 'session_start': {
-      const { instance_id, focus = '' } = args as { instance_id: string; focus?: string };
+      const { instance_id, focus = '', author = '', provider = '', workspace_path = '' } = args as { instance_id: string; focus?: string; author?: string; provider?: string; workspace_path?: string };
       const redis = await getConnection(instance_id);
 
       // 1. Scan all best-solution lessons
@@ -3000,16 +3852,14 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       // 2. Fetch all lesson values for recency sorting + focus matching
       type Lesson = {
         topic: string; outcome: string; what_worked: string; what_failed?: string;
-        ts: string; severity?: string; recall_count?: number; tags?: string[];
+        ts: string; verified_at?: string; severity?: string; recall_count?: number;
+        tags?: string[]; confidence?: number; audit_trail?: unknown[];
       };
       const lessons: Lesson[] = [];
-      if (lessonKeys.length > 0) {
-        // Batch fetch all lesson values in one round-trip instead of N sequential gets
-        const values = await redis.mget(...lessonKeys);
-        for (const raw of values) {
-          if (!raw) continue;
-          try { lessons.push(JSON.parse(raw) as Lesson); } catch { /* skip corrupt */ }
-        }
+      for (const k of lessonKeys) {
+        const raw = await redis.get(k);
+        if (!raw) continue;
+        try { lessons.push(JSON.parse(raw) as Lesson); } catch { /* skip corrupt */ }
       }
       lessons.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
 
@@ -3042,14 +3892,138 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
           )
         : [];
 
-      // 6. Save session start marker
+      // 6. Streak tracking
+      let streakDays = 0;
+      let streakRecord = 0;
+      let streakMessage = '';
+      try {
+        const streakRaw = await redis.get('cachly:streak:current');
+        const streak = streakRaw ? JSON.parse(streakRaw) as { days: number; last_date: string; record: number } : null;
+        const today = new Date().toISOString().slice(0, 10);
+        if (streak) {
+          const lastDate = streak.last_date;
+          const yesterday = new Date(Date.now() - 86400000).toISOString().slice(0, 10);
+          if (lastDate === today) {
+            // Already counted today
+            streakDays = streak.days;
+            streakRecord = streak.record;
+          } else if (lastDate === yesterday) {
+            // Continuing streak
+            streakDays = streak.days + 1;
+            streakRecord = Math.max(streakDays, streak.record);
+            await redis.set('cachly:streak:current', JSON.stringify({ days: streakDays, last_date: today, record: streakRecord }));
+          } else {
+            // Streak broken
+            streakDays = 1;
+            streakRecord = streak.record;
+            await redis.set('cachly:streak:current', JSON.stringify({ days: 1, last_date: today, record: streakRecord }));
+          }
+        } else {
+          // First session ever
+          streakDays = 1;
+          streakRecord = 1;
+          await redis.set('cachly:streak:current', JSON.stringify({ days: 1, last_date: today, record: 1 }));
+        }
+        if (streakDays >= 7) streakMessage = `🔥 **${streakDays}-day streak!** ${streakDays === streakRecord ? ' New record!' : `Best: ${streakRecord}d`}`;
+        else if (streakDays > 1) streakMessage = `🔥 ${streakDays}-day streak`;
+      } catch { /* non-critical */ }
+
+      // 7. Save session start marker
       await redis.set('cachly:session:current', JSON.stringify({
         started: new Date().toISOString(),
         focus,
+        provider,
       }), 'EX', 86400); // auto-expire after 24h if session_end never called
 
       // ── Build briefing ──────────────────────────────────────────────────────
-      const lines: string[] = ['🧠 **Session Briefing**', ''];
+      const providerLabel = provider ? ` · ${provider}` : '';
+      const lines: string[] = [`🧠 **Session Briefing**${providerLabel}`, ''];
+      if (streakMessage) lines.push(streakMessage, '');
+
+      // Handoff from previous window (if any)
+      const handoffRaw = await redis.get('cachly:session:handoff');
+      if (handoffRaw) {
+        try {
+          const handoff = JSON.parse(handoffRaw) as {
+            ts: string; completed_tasks: string[]; remaining_tasks: string[];
+            files_changed?: { path: string; status: string; description?: string }[];
+            instructions?: string; context_summary?: string; blocked_on?: string;
+          };
+          const ago = Math.round((Date.now() - new Date(handoff.ts).getTime()) / 60000);
+          const agoStr = ago < 60 ? `${ago}m ago` : ago < 1440 ? `${Math.round(ago / 60)}h ago` : `${Math.round(ago / 1440)}d ago`;
+
+          lines.push(`🤝 **Handoff from previous window** (${agoStr}):`);
+          if (handoff.context_summary) lines.push(`   ${handoff.context_summary}`);
+          if (handoff.remaining_tasks.length > 0) {
+            lines.push(`   ⏳ **Remaining tasks:**`);
+            for (const t of handoff.remaining_tasks) lines.push(`     - ${t}`);
+          }
+          if (handoff.completed_tasks.length > 0) {
+            lines.push(`   ✅ **Already done:** ${handoff.completed_tasks.join(', ')}`);
+          }
+          const brokenFiles = (handoff.files_changed ?? []).filter(f => f.status === 'broken' || f.status === 'partial');
+          if (brokenFiles.length > 0) {
+            lines.push(`   ⚠️ **Needs fix:** ${brokenFiles.map(f => `\`${f.path}\` (${f.status}${f.description ? ': ' + f.description : ''})`).join(', ')}`);
+          }
+          if (handoff.blocked_on) lines.push(`   🚫 **Blocked on:** ${handoff.blocked_on}`);
+          if (handoff.instructions) lines.push(`   📝 **Instructions:** ${handoff.instructions}`);
+          lines.push('');
+        } catch { /* ignore corrupt handoff */ }
+      }
+
+      // ── Last checkpoint (session_ping) — shown when no session_end found ────
+      const checkpointRaw = await redis.get('cachly:session:checkpoint');
+      if (checkpointRaw) {
+        try {
+          const cp = JSON.parse(checkpointRaw) as {
+            ts: string; task: string; files_touched: string[]; next_step?: string; provider?: string;
+          };
+          // Only show checkpoint if it's more recent than last session_end
+          const cpTime = new Date(cp.ts).getTime();
+          const lastSessionTime = lastSession ? new Date(lastSession.ts).getTime() : 0;
+          if (cpTime > lastSessionTime) {
+            const ago = Math.round((Date.now() - cpTime) / 60000);
+            const agoStr = ago < 60 ? `${ago}m ago` : ago < 1440 ? `${Math.round(ago / 60)}h ago` : `${Math.round(ago / 1440)}d ago`;
+            const providerStr = cp.provider ? ` [${cp.provider}]` : '';
+            lines.push(`📌 **Last checkpoint**${providerStr} (${agoStr}): ${cp.task}`);
+            if (cp.files_touched.length > 0) {
+              lines.push(`   Files: ${cp.files_touched.slice(0, 5).map(f => `\`${f}\``).join(', ')}`);
+            }
+            if (cp.next_step) lines.push(`   📍 Next step was: ${cp.next_step}`);
+            if (!lastSession || cpTime - lastSessionTime > 300_000) {
+              lines.push(`   ⚠️ No \`session_end\` found — reconstructed from last checkpoint`);
+            }
+            lines.push('');
+          }
+        } catch { /* ignore */ }
+      }
+
+      // ── Git reconstruction — when no session_end + workspace_path given ─────
+      if (workspace_path && !lastSession) {
+        try {
+          const { execSync } = await import('node:child_process');
+          const gitLog = execSync(
+            `git -C "${workspace_path}" log --oneline --format="%h %s" -15 2>/dev/null`,
+            { encoding: 'utf-8', timeout: 5000 },
+          ).trim();
+          const gitDiff = execSync(
+            `git -C "${workspace_path}" diff --stat HEAD~3 2>/dev/null || git -C "${workspace_path}" diff --stat 2>/dev/null`,
+            { encoding: 'utf-8', timeout: 5000 },
+          ).trim();
+          if (gitLog) {
+            lines.push(`🔍 **Git reconstruction** (no session_end found — reconstructed from git):`);
+            for (const l of gitLog.split('\n').slice(0, 8)) lines.push(`   ${l}`);
+            if (gitDiff) {
+              const diffLines = gitDiff.split('\n').filter(l => l.includes('|') || l.includes('changed'));
+              if (diffLines.length > 0) {
+                lines.push(`   **Recent changes:**`);
+                for (const dl of diffLines.slice(0, 5)) lines.push(`   ${dl.trim()}`);
+              }
+            }
+            lines.push('');
+          }
+        } catch { /* git not available or no repo — silent */ }
+      }
 
       // Last session
       if (lastSession) {
@@ -3063,26 +4037,8 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         lines.push('');
       }
 
-      // Brain health + first-time onboarding hint
-      if (lessons.length === 0 && !lastSession) {
-        lines.push(`🆕 **Brain is empty — first session!**`);
-        lines.push(`After solving anything, call \`learn_from_attempts\` to store the lesson.`);
-        lines.push(`After this session, call \`session_end\` to save a summary.`);
-        lines.push('');
-      } else {
-        const totalRecalls = lessons.reduce((s, l) => s + (l.recall_count ?? 0), 0);
-        const savedMin = totalRecalls * 15;
-        const savedStr = savedMin >= 60
-          ? `~${(savedMin / 60).toFixed(1)}h saved`
-          : savedMin > 0 ? `~${savedMin}min saved` : '';
-        const statsLine = [
-          `${lessons.length} lessons`,
-          ctxCount > 0 ? `${ctxCount} context entries` : '',
-          totalRecalls > 0 ? `${totalRecalls} recalls` : '',
-          savedStr,
-        ].filter(Boolean).join(' · ');
-        lines.push(`📊 **Brain:** ${statsLine}`, '');
-      }
+      // Brain health
+      lines.push(`📊 **Brain:** ${lessons.length} lessons · ${ctxCount} context entries`, '');
 
       // Focus-relevant lessons
       if (focusLessons.length > 0) {
@@ -3119,6 +4075,136 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         lines.push('');
       }
 
+      // ── Stale / low-confidence lessons (confidence decay) ─────────────────
+      const staleSuccessLessons = lessons.filter(l => {
+        if (l.outcome !== 'success' && l.outcome !== 'partial') return false;
+        return calculateConfidence(l) < CONFIDENCE_WARN_VALUE;
+      });
+      if (staleSuccessLessons.length > 0) {
+        lines.push(`🔴 **Stale lessons** (not recalled in >${CONFIDENCE_WARN_DAYS}d — verify before applying):`);
+        for (const l of staleSuccessLessons.slice(0, 4)) {
+          const conf = calculateConfidence(l);
+          const ageDays = Math.round((Date.now() - new Date(l.verified_at ?? l.ts).getTime()) / 86400000);
+          const flag = conf < CONFIDENCE_STALE_VALUE ? '🔴' : '⚠️';
+          lines.push(`  ${flag} \`${l.topic}\` — ${ageDays}d stale, ${(conf * 100).toFixed(0)}% confidence`);
+        }
+        lines.push(`  _Run \`recall_best_solution\` on these to reset their confidence clock._`);
+        lines.push('');
+      }
+
+      // ── Session Replay: show last session's decision log ──────────────────
+      const lastSessionAny = lastSession as unknown as { decision_log?: Array<{ topic: string; outcome: string; what_worked: string }> } | null;
+      if (lastSessionAny?.decision_log?.length) {
+        const dl = lastSessionAny.decision_log;
+        const successes = dl.filter(d => d.outcome === 'success');
+        const failures  = dl.filter(d => d.outcome === 'failure');
+        lines.push(`🎬 **Last session decisions** (${dl.length} lessons stored):`);
+        if (successes.length > 0) lines.push(`  ✅ Worked: ${successes.slice(0, 3).map(d => `\`${d.topic}\``).join(', ')}`);
+        if (failures.length > 0)  lines.push(`  ❌ Failed: ${failures.slice(0, 3).map(d => `\`${d.topic}\``).join(', ')}`);
+        lines.push('');
+      }
+
+      // ── 🔮 Predictive Pre-Warning — intent-based danger detection ────────────
+      // Fires BEFORE work starts. If focus area has known failure patterns → warn loudly.
+      if (focusTerms.length > 0) {
+        type LessonAny = typeof lessons[0] & { author?: string; tags?: string[] };
+        const dangerLessons = (lessons as LessonAny[]).filter(l => {
+          if (l.outcome === 'success') return false;
+          const topicCategory = l.topic.split(':')[0];
+          return focusTerms.some(term =>
+            l.topic.toLowerCase().includes(term) ||
+            topicCategory === term ||
+            (l.tags ?? []).some((t: string) => t.toLowerCase() === term),
+          );
+        });
+        if (dangerLessons.length >= 1) {
+          // Insert warning block right after the title line (index 1 = blank line after title)
+          const warning = [
+            `🚨 **PRE-WARNING** — Read this BEFORE starting:`,
+            `  Known pitfalls for **"${focus}"** (${dangerLessons.length} past failure${dangerLessons.length > 1 ? 's' : ''}):`,
+            ...dangerLessons.slice(0, 3).map(l => `  ❌ \`${l.topic}\` — ${(l.what_failed ?? l.what_worked).slice(0, 80)}`),
+            '',
+          ];
+          lines.splice(2, 0, ...warning); // after '🧠 **Session Briefing**' + empty line
+        }
+      }
+
+      // ── 👥 Team Telepathy — what teammates learned this week ─────────────────
+      if (author) {
+        type LessonAny = typeof lessons[0] & { author?: string };
+        const oneWeekAgo = Date.now() - 7 * 86_400_000;
+        const teamLessons = (lessons as LessonAny[]).filter(l =>
+          l.author && l.author !== author && new Date(l.ts).getTime() > oneWeekAgo,
+        );
+        if (teamLessons.length > 0) {
+          // Group by author
+          const byAuthor = new Map<string, LessonAny[]>();
+          for (const l of teamLessons) {
+            const a = l.author!;
+            if (!byAuthor.has(a)) byAuthor.set(a, []);
+            byAuthor.get(a)!.push(l);
+          }
+          lines.push(`👥 **Team this week** (${teamLessons.length} lesson${teamLessons.length > 1 ? 's' : ''} from teammates):`);
+          for (const [teamAuthor, tls] of byAuthor) {
+            lines.push(`  👤 **${teamAuthor}**:`);
+            for (const l of tls.slice(0, 3)) {
+              const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+              lines.push(`    ${emoji} \`${l.topic}\` — ${l.what_worked.slice(0, 80)}`);
+            }
+            if (tls.length > 3) lines.push(`    … and ${tls.length - 3} more`);
+          }
+          lines.push('');
+        }
+      }
+
+      // ── 💎 Memory Crystal — compressed wisdom from old sessions ──────────────
+      try {
+        const crystalRaw = await redis.get('cachly:crystal:latest');
+        if (crystalRaw) {
+          const crystal = JSON.parse(crystalRaw) as {
+            label: string; ts: string; session_count: number;
+            top_patterns: Array<{ category: string; insight: string; count: number }>;
+          };
+          const crystalAge = Math.round((Date.now() - new Date(crystal.ts).getTime()) / 86_400_000);
+          if (crystalAge <= 90) {
+            lines.push(`💎 **Memory Crystal** (${crystal.label} · ${crystal.session_count} sessions compressed):`);
+            for (const p of crystal.top_patterns.slice(0, 3)) {
+              lines.push(`  • **${p.category}** (${p.count}×): ${p.insight.slice(0, 90)}`);
+            }
+            lines.push('');
+          }
+        }
+      } catch { /* non-critical */ }
+
+      // ── 🗺️ Roadmap — open items at session start ────────────────────────────
+      try {
+        const roadmapAll = await redis.hgetall(`cachly:roadmap:${instance_id}`);
+        if (roadmapAll && Object.keys(roadmapAll).length > 0) {
+          const PRIORITY_ORDER: Record<string, number> = { critical: 0, high: 1, medium: 2, low: 3 };
+          const PRIORITY_ICON: Record<string, string> = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
+          const openStatuses = new Set(['planned', 'in-progress', 'blocked']);
+          const allItems = Object.values(roadmapAll).map(v => JSON.parse(v as string) as Record<string, unknown>);
+          const openItems = allItems
+            .filter(i => openStatuses.has(i.status as string))
+            .sort((a, b) => {
+              if (a.status === 'in-progress' && b.status !== 'in-progress') return -1;
+              if (b.status === 'in-progress' && a.status !== 'in-progress') return 1;
+              return (PRIORITY_ORDER[a.priority as string] ?? 99) - (PRIORITY_ORDER[b.priority as string] ?? 99);
+            });
+          const doneCount = allItems.filter(i => i.status === 'done').length;
+          if (openItems.length > 0) {
+            lines.push(`🗺️ **Roadmap** (${openItems.length} open · ${doneCount} done):`);
+            for (const it of openItems.slice(0, 5)) {
+              const statusIcon = it.status === 'in-progress' ? '⚡' : it.status === 'blocked' ? '🚫' : '📋';
+              lines.push(`  ${statusIcon} ${PRIORITY_ICON[it.priority as string] ?? '⚪'} \`${it.id}\` **${it.title}**`);
+            }
+            if (openItems.length > 5) lines.push(`  … and ${openItems.length - 5} more`);
+            lines.push(`  _Use \`roadmap_next\` for the top priority item · \`roadmap_list\` for full view_`);
+            lines.push('');
+          }
+        }
+      } catch { /* non-critical */ }
+
       return lines.join('\n');
     }
 
@@ -3129,11 +4215,13 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         summary,
         files_changed = [],
         lessons_learned,
+        workspace_path = '',
       } = args as {
         instance_id: string;
         summary: string;
         files_changed?: string[];
         lessons_learned?: number;
+        workspace_path?: string;
       };
 
       const redis = await getConnection(instance_id);
@@ -3149,12 +4237,21 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         } catch { /* ignore */ }
       }
 
+      // ── Session Replay: capture decision log ─────────────────────────────
+      let decisionLog: Array<{ ts: string; topic: string; outcome: string; what_worked: string }> = [];
+      try {
+        const dlEntries = await redis.lrange('cachly:session:decision-log', 0, -1);
+        decisionLog = dlEntries.map(e => JSON.parse(e) as { ts: string; topic: string; outcome: string; what_worked: string });
+        await redis.del('cachly:session:decision-log');
+      } catch { /* non-critical */ }
+
       const sessionRecord = {
         ts: now.toISOString(),
         summary,
         files_changed,
         ...(lessons_learned !== undefined ? { lessons_learned } : {}),
         ...(durationMin !== undefined ? { duration_min: durationMin } : {}),
+        ...(decisionLog.length > 0 ? { decision_log: decisionLog } : {}),
       };
 
       // Save as "last session"
@@ -3168,6 +4265,127 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       // Clean up current session marker
       await redis.del('cachly:session:current');
 
+      // ── AUTO-LEARN from session summary (no manual call needed) ─────────────
+      // Parse the summary for actionable lessons and store them automatically.
+      const autoLearned: string[] = [];
+      try {
+        // Extract key sentences from the summary that contain action verbs
+        const actionVerbs = /\b(fixed|deployed|added|removed|refactored|migrated|updated|resolved|implemented|improved|optimized|configured|created|deleted|disabled|enabled|discovered|found|learned|debugged|patched|upgraded|installed|tested|built|rewrote|moved|renamed|split|merged|extracted)\b/i;
+        const sentences = summary
+          .split(/[.!\n]+/)
+          .map(s => s.trim())
+          .filter(s => s.length > 20 && actionVerbs.test(s));
+
+        for (const sentence of sentences.slice(0, 6)) {
+          // Build a topic slug from the first meaningful words
+          const words = sentence.toLowerCase()
+            .replace(/[^a-z0-9\s]/g, ' ')
+            .split(/\s+/)
+            .filter(w => w.length > 3 && !['that', 'this', 'with', 'from', 'have', 'been', 'were', 'they', 'then', 'when', 'also', 'into', 'will', 'would', 'could', 'should'].includes(w));
+          const slug = words.slice(0, 4).join('-');
+          if (!slug) continue;
+          const topic = `auto:${slug}`;
+          const key = `cachly:lesson:best:${topic}`;
+
+          // Don't overwrite existing successful lessons
+          const existing = await redis.get(key);
+          if (existing) {
+            try {
+              const ex = JSON.parse(existing) as { outcome: string };
+              if (ex.outcome === 'success') continue;
+            } catch { /* ignore */ }
+          }
+
+          const lesson = {
+            topic,
+            outcome: 'success',
+            what_worked: sentence,
+            context: `Auto-learned from session summary. Full summary: ${summary.slice(0, 300)}`,
+            severity: 'minor',
+            ts: now.toISOString(),
+            recall_count: 0,
+            auto_learned: true,
+            session_ts: now.toISOString(),
+            version: 2,
+          };
+          await redis.set(key, JSON.stringify(lesson));
+          // 90-day TTL for auto-learned lessons
+          await redis.expire(key, 90 * 86400);
+          autoLearned.push(topic);
+        }
+
+        // Also store a lesson per changed file area if files were changed
+        if (files_changed.length > 0) {
+          const areas = [...new Set(files_changed.map(f => f.split('/').slice(0, 2).join('/')))].slice(0, 3);
+          for (const area of areas) {
+            const slug = area.replace(/[^a-z0-9]/gi, '-').toLowerCase().replace(/-+/g, '-').slice(0, 30);
+            const topic = `auto:changed:${slug}`;
+            const key = `cachly:lesson:best:${topic}`;
+            const lesson = {
+              topic,
+              outcome: 'success',
+              what_worked: `Files changed in ${area}: ${files_changed.filter(f => f.startsWith(area.split('/')[0])).slice(0, 5).join(', ')}`,
+              context: summary.slice(0, 200),
+              severity: 'minor',
+              ts: now.toISOString(),
+              recall_count: 0,
+              auto_learned: true,
+              version: 2,
+            };
+            await redis.set(key, JSON.stringify(lesson));
+            await redis.expire(key, 90 * 86400);
+            autoLearned.push(topic);
+          }
+        }
+      } catch { /* auto-learn errors must never break session_end */ }
+
+      // ── 🌿 Ambient Git Learning ────────────────────────────────────────────────
+      // Read git commits since session start → auto-learn each meaningful commit.
+      const ambientLearned: string[] = [];
+      if (workspace_path) {
+        try {
+          // Get the session start time (stored by session_start)
+          const sessionStartTs = currentRaw
+            ? (() => { try { return (JSON.parse(currentRaw) as { started?: string }).started ?? ''; } catch { return ''; } })()
+            : '';
+          const sinceArg = sessionStartTs ? `--since="${sessionStartTs}"` : '--since="1 hour ago"';
+          const gitOut = execSync(
+            `git -C "${workspace_path}" log ${sinceArg} --oneline --format="%H|||%s|||%ai"`,
+            { timeout: 5000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+          ).trim();
+          if (gitOut) {
+            const commitActionRe = /\b(fix|add|remove|refactor|migrate|update|resolve|implement|improve|optimize|configure|create|delete|disable|enable|debug|patch|upgrade|build|rewrite|deploy|feat|chore|docs|test|perf|ci)\b/i;
+            for (const line of gitOut.split('\n').slice(0, 10)) {
+              const [hash, msg, dateStr] = line.split('|||');
+              if (!msg || !commitActionRe.test(msg)) continue;
+              const slug = msg
+                .toLowerCase().replace(/^(fix|feat|chore|docs|test|ci|perf|refactor|build|revert)[:(\s]/i, '')
+                .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+              if (!slug) continue;
+              const topic = `git:${slug}`;
+              const key = `cachly:lesson:best:${topic}`;
+              const existing = await redis.get(key);
+              if (existing) continue; // don't overwrite existing
+              const commitLesson = {
+                topic,
+                outcome: 'success' as const,
+                what_worked: msg.slice(0, 200),
+                context: `Auto-learned from git commit ${(hash ?? '').slice(0, 7)} at ${dateStr ?? ''} in ${workspace_path}`,
+                severity: 'minor' as const,
+                ts: now.toISOString(),
+                recall_count: 0,
+                auto_learned: true,
+                source: 'ambient-git',
+                version: 3,
+              };
+              await redis.set(key, JSON.stringify(commitLesson));
+              await redis.expire(key, 60 * 86400); // 60 day TTL for git lessons
+              ambientLearned.push(topic);
+            }
+          }
+        } catch { /* git not available or not a repo — silent skip */ }
+      }
+
       const durationStr = durationMin !== undefined ? ` · ${durationMin} min` : '';
       return [
         `✅ **Session saved**${durationStr}`,
@@ -3175,11 +4393,115 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         `📋 **Summary:** ${summary}`,
         files_changed.length > 0 ? `📁 **Files changed:** ${files_changed.map(f => `\`${f}\``).join(', ')}` : '',
         lessons_learned !== undefined ? `🧠 **Lessons stored:** ${lessons_learned}` : '',
+        autoLearned.length > 0 ? `🤖 **Auto-learned:** ${autoLearned.length} lessons extracted from summary (${autoLearned.slice(0, 3).map(t => `\`${t}\``).join(', ')}${autoLearned.length > 3 ? '…' : ''})` : '',
+        ambientLearned.length > 0 ? `🌿 **Ambient git learning:** ${ambientLearned.length} commit${ambientLearned.length > 1 ? 's' : ''} auto-learned (${ambientLearned.slice(0, 3).map(t => `\`${t}\``).join(', ')}${ambientLearned.length > 3 ? '…' : ''})` : '',
         ``,
         `💡 Next session: \`session_start(focus="...")\` to see this summary.`,
       ].filter(l => l !== '').join('\n');
     }
 
+    // ── session_ping — lightweight checkpoint ─────────────────────────────────
+    case 'session_ping': {
+      const {
+        instance_id,
+        task,
+        files_touched = [],
+        next_step = '',
+        provider = '',
+      } = args as {
+        instance_id: string;
+        task: string;
+        files_touched?: string[];
+        next_step?: string;
+        provider?: string;
+      };
+
+      const redis = await getConnection(instance_id);
+      const checkpoint = {
+        ts: new Date().toISOString(),
+        task,
+        files_touched,
+        next_step,
+        provider,
+      };
+
+      // Store as the latest checkpoint — session_start reads this when no session_end found
+      await redis.set('cachly:session:checkpoint', JSON.stringify(checkpoint), 'EX', 86400 * 3); // 3-day TTL
+
+      // Also keep a short rolling log (last 20 checkpoints for history)
+      await redis.lpush('cachly:session:checkpoint:log', JSON.stringify(checkpoint));
+      await redis.ltrim('cachly:session:checkpoint:log', 0, 19);
+
+      const providerStr = provider ? ` [${provider}]` : '';
+      const filesStr = files_touched.length > 0 ? ` · ${files_touched.length} file${files_touched.length > 1 ? 's' : ''} touched` : '';
+      const nextStr = next_step ? `\n📍 **Next step:** ${next_step}` : '';
+
+      return [
+        `📌 **Checkpoint saved**${providerStr} — ${new Date().toLocaleTimeString()}`,
+        `🔨 **Working on:** ${task}${filesStr}`,
+        nextStr,
+        ``,
+        `💡 If you switch providers, \`session_start\` will show this checkpoint automatically.`,
+      ].filter(l => l !== '').join('\n');
+    }
+
+    // ── session_handoff — cross-window continuity ─────────────────────────────
+    case 'session_handoff': {
+      const {
+        instance_id,
+        completed_tasks = [],
+        remaining_tasks = [],
+        files_changed = [],
+        instructions = '',
+        context_summary = '',
+        blocked_on = '',
+      } = args as {
+        instance_id: string;
+        completed_tasks: string[];
+        remaining_tasks: string[];
+        files_changed?: { path: string; status: string; description?: string }[];
+        instructions?: string;
+        context_summary?: string;
+        blocked_on?: string;
+      };
+
+      const redis = await getConnection(instance_id);
+      const now = new Date();
+
+      const handoff = {
+        ts: now.toISOString(),
+        completed_tasks,
+        remaining_tasks,
+        files_changed,
+        instructions,
+        context_summary,
+        blocked_on,
+      };
+
+      // Store handoff — never expires until next handoff overwrites it
+      await redis.set('cachly:session:handoff', JSON.stringify(handoff));
+
+      // Also append to history
+      await redis.lpush('cachly:session:handoff:history', JSON.stringify(handoff));
+      await redis.ltrim('cachly:session:handoff:history', 0, 19);
+
+      const totalTasks = completed_tasks.length + remaining_tasks.length;
+      const pct = totalTasks > 0 ? Math.round((completed_tasks.length / totalTasks) * 100) : 0;
+      const brokenFiles = files_changed.filter(f => f.status === 'broken' || f.status === 'partial');
+
+      return [
+        `🤝 **Handoff saved** — ${completed_tasks.length}/${totalTasks} tasks done (${pct}%)`,
+        ``,
+        completed_tasks.length > 0 ? `✅ **Completed:**\n${completed_tasks.map(t => `  - ${t}`).join('\n')}` : '',
+        remaining_tasks.length > 0 ? `\n⏳ **Remaining for next window:**\n${remaining_tasks.map(t => `  - ${t}`).join('\n')}` : '',
+        brokenFiles.length > 0 ? `\n⚠️ **Needs attention:** ${brokenFiles.map(f => `\`${f.path}\` (${f.status})`).join(', ')}` : '',
+        blocked_on ? `\n🚫 **Blocked on:** ${blocked_on}` : '',
+        instructions ? `\n📝 **Instructions:** ${instructions}` : '',
+        ``,
+        `💡 The next \`session_start\` will include this handoff automatically.`,
+      ].filter(l => l !== '').join('\n');
+    }
+
     // ── auto_learn_session ────────────────────────────────────────────────────
     case 'auto_learn_session': {
       const { instance_id, observations } = args as {
@@ -3205,8 +4527,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         // Only overwrite if this is a success and existing is failure, or topic is new
         const existing = await redis.get(key);
         if (existing) {
-          let existingLesson: { outcome: string };
-          try { existingLesson = JSON.parse(existing); } catch { existingLesson = { outcome: 'failure' }; }
+          const existingLesson = JSON.parse(existing) as { outcome: string };
           if (existingLesson.outcome === 'success' && obs.outcome !== 'success') {
             skipped.push(topic);
             continue;
@@ -3271,23 +4592,20 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
 
       type Lesson = { topic: string; what_worked: string; outcome: string; file_paths?: string[] };
       const relevant: string[] = [];
-      if (lessonKeys.length > 0) {
-        const values = await redis.mget(...lessonKeys);
-        for (const raw of values) {
-          if (!raw) continue;
-          let lesson: Lesson;
-          try { lesson = JSON.parse(raw) as Lesson; } catch { continue; }
-          // Match by file_paths stored in lesson OR by topic keywords matching file name
-          const topicWords = lesson.topic.toLowerCase().split(/[:\-_]/);
-          const fileMatches = changed_files.some(f => {
-            const fname = f.split('/').pop()?.replace(/\.[^.]+$/, '').toLowerCase() ?? '';
-            return topicWords.some(w => w.length > 3 && fname.includes(w))
-              || (lesson.file_paths ?? []).some(lf => f.includes(lf) || lf.includes(f));
-          });
-          if (fileMatches) {
-            const emoji = lesson.outcome === 'success' ? '✅' : '⚠️';
-            relevant.push(`  ${emoji} \`${lesson.topic}\` — ${lesson.what_worked.slice(0, 80)}`);
-          }
+      for (const k of lessonKeys) {
+        const raw = await redis.get(k);
+        if (!raw) continue;
+        const lesson = JSON.parse(raw) as Lesson;
+        // Match by file_paths stored in lesson OR by topic keywords matching file name
+        const topicWords = lesson.topic.toLowerCase().split(/[:\-_]/);
+        const fileMatches = changed_files.some(f => {
+          const fname = f.split('/').pop()?.replace(/\.[^.]+$/, '').toLowerCase() ?? '';
+          return topicWords.some(w => w.length > 3 && fname.includes(w))
+            || (lesson.file_paths ?? []).some(lf => f.includes(lf) || lf.includes(f));
+        });
+        if (fileMatches) {
+          const emoji = lesson.outcome === 'success' ? '✅' : '⚠️';
+          relevant.push(`  ${emoji} \`${lesson.topic}\` — ${lesson.what_worked.slice(0, 80)}`);
         }
       }
 
@@ -3328,7 +4646,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         file_paths: file_paths ?? [],
         commands: commands ?? [],
         tags: [...(tags ?? []), 'team'],
-        ts: new Date().toISOString(),
+        timestamp: new Date().toISOString(),
         recall_count: 0,
         version: 2,
       };
@@ -3367,12 +4685,10 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         author?: string; tags?: string[];
       };
       let lessons: TeamLesson[] = [];
-      if (lessonKeys.length > 0) {
-        const values = await redis.mget(...lessonKeys);
-        for (const raw of values) {
-          if (!raw) continue;
-          try { lessons.push(JSON.parse(raw) as TeamLesson); } catch { /* skip */ }
-        }
+      for (const k of lessonKeys) {
+        const raw = await redis.get(k);
+        if (!raw) continue;
+        try { lessons.push(JSON.parse(raw) as TeamLesson); } catch { /* skip */ }
       }
 
       // Filter
@@ -3413,306 +4729,153 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       return lines.join('\n');
     }
 
-    // ── brain_stats ───────────────────────────────────────────────────────────
-    case 'brain_stats': {
-      const { instance_id } = args as { instance_id: string };
+    // ── team_synthesize — Team Brain Synthesis ────────────────────────────────
+    case 'team_synthesize': {
+      const { instance_id, topic } = args as { instance_id: string; topic: string };
       const redis = await getConnection(instance_id);
 
-      // Scan all lesson keys
-      const lessonKeys: string[] = [];
-      const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
-      await new Promise<void>((resolve, reject) => {
-        lStream.on('data', (batch: string[]) => lessonKeys.push(...batch));
-        lStream.on('end', resolve);
-        lStream.on('error', reject);
-      });
-
-      type Lesson = { topic: string; outcome: string; recall_count?: number; ts: string; severity?: string; what_worked: string; author?: string };
-      const lessons: Lesson[] = [];
-      if (lessonKeys.length > 0) {
-        const vals = await redis.mget(...lessonKeys);
-        for (const raw of vals) {
-          if (!raw) continue;
-          try { lessons.push(JSON.parse(raw) as Lesson); } catch { /* skip */ }
-        }
+      // Load history list for this topic (all authors' contributions)
+      const listKey = `cachly:lessons:${topic}`;
+      const all = await redis.lrange(listKey, 0, -1);
+      if (all.length < 2) {
+        return `📭 Need at least 2 entries for topic \`${topic}\` to synthesize.\n\nCurrently: ${all.length} entr${all.length === 1 ? 'y' : 'ies'}.\n\nHave team members store lessons via \`learn_from_attempts(topic="${topic}", ...)\`.`;
       }
 
-      // Context count
-      let ctxCount = 0;
-      const ctxStream = redis.scanStream({ match: 'cachly:ctx:*', count: 200 });
-      await new Promise<void>((resolve, reject) => {
-        ctxStream.on('data', (batch: string[]) => { ctxCount += batch.filter((k: string) => !k.endsWith(':meta')).length; });
-        ctxStream.on('end', resolve);
-        ctxStream.on('error', reject);
-      });
-
-      const lastSessionRaw = await redis.get('cachly:session:last');
-      let lastSession: { ts: string; summary: string; duration_min?: number } | null = null;
-      if (lastSessionRaw) { try { lastSession = JSON.parse(lastSessionRaw); } catch { /* ignore */ } }
-
-      const totalRecalls  = lessons.reduce((s, l) => s + (l.recall_count ?? 0), 0);
-      const savedMin      = totalRecalls * 15;
-      const savedHours    = (savedMin / 60).toFixed(1);
-      const successCount  = lessons.filter(l => l.outcome === 'success').length;
-      const failureCount  = lessons.filter(l => l.outcome === 'failure' || l.outcome === 'partial').length;
-      const criticalCount = lessons.filter(l => l.severity === 'critical').length;
-      const majorCount    = lessons.filter(l => l.severity === 'major').length;
-      const authors       = [...new Set(lessons.map(l => l.author).filter(Boolean))];
-      const topByRecall   = [...lessons].sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0)).slice(0, 5);
-      const newestLesson  = [...lessons].sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime())[0];
-
-      // Age of last session
-      let lastSessionStr = 'none yet';
-      if (lastSession) {
-        const ageMin = Math.round((Date.now() - new Date(lastSession.ts).getTime()) / 60000);
-        lastSessionStr = ageMin < 60 ? `${ageMin}m ago`
-          : ageMin < 1440 ? `${Math.round(ageMin / 60)}h ago`
-          : `${Math.round(ageMin / 1440)}d ago`;
-      }
+      type Entry = { outcome: string; what_worked: string; what_failed?: string; author?: string; ts: string; severity?: string };
+      const entries: Entry[] = all.map(r => { try { return JSON.parse(r) as Entry; } catch { return null; } }).filter((e): e is Entry => e !== null);
 
-      const tokensSaved = (totalRecalls * 1200);
-      const tokenStr    = tokensSaved >= 1000 ? `~${(tokensSaved / 1000).toFixed(0)}k tokens` : `~${tokensSaved} tokens`;
-      const costSaved   = (tokensSaved * 0.000003).toFixed(2);
+      // Group by outcome
+      const successes = entries.filter(e => e.outcome === 'success');
+      const failures  = entries.filter(e => e.outcome === 'failure');
+      const partials  = entries.filter(e => e.outcome === 'partial');
 
-      const lines = [
-        `🧠 **Brain Stats — Full Dashboard**`,
-        ``,
-        `╔══════════════════════════════════════╗`,
-        `║  📚 Lessons:       ${String(lessons.length).padEnd(18)}║`,
-        `║  🔄 Total recalls: ${String(totalRecalls).padEnd(18)}║`,
-        `║  🕐 Time saved:    ~${savedHours}h${' '.repeat(Math.max(0, 16 - savedHours.length))}║`,
-        `║  💎 Tokens saved:  ${tokenStr.padEnd(18)}║`,
-        `║  💵 Cost saved:    ~$${costSaved.padEnd(17)}║`,
-        `║  📁 Context keys:  ${String(ctxCount).padEnd(18)}║`,
-        `╚══════════════════════════════════════╝`,
-        ``,
-        `**Lessons breakdown:**`,
-        `  ✅ Success:  ${successCount}   ❌ Failures/partial: ${failureCount}`,
-        `  🔴 Critical: ${criticalCount}   🟡 Major: ${majorCount}`,
-        ``,
-        `**Last session:** ${lastSessionStr}${lastSession?.summary ? ` — ${lastSession.summary.slice(0, 80)}` : ''}`,
-        `**Newest lesson:** ${newestLesson ? `\`${newestLesson.topic}\`` : 'none'}`,
-        ``,
-      ];
+      const authors = [...new Set(entries.map(e => e.author).filter(Boolean))];
+      const hasMultiAuthor = authors.length > 1;
 
-      if (topByRecall.length > 0) {
-        lines.push(`**Top recalled lessons (most reused):**`);
-        for (const l of topByRecall) {
-          const emoji = l.outcome === 'success' ? '✅' : '⚠️';
-          lines.push(`  ${emoji} \`${l.topic}\` — recalled ${l.recall_count ?? 0}× · ${l.what_worked.slice(0, 60)}`);
-        }
-        lines.push('');
-      }
+      // Build canonical merged version
+      // what_worked: pick the most recent success, or longest for most detail
+      const bestSuccess = successes.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime())[0];
+      const whatWorkedCandidates = successes.map(e => e.what_worked).filter(w => w && w.length > 10);
+      const canonicalWorked = whatWorkedCandidates.sort((a, b) => b.length - a.length)[0] ?? bestSuccess?.what_worked ?? '';
 
-      if (authors.length > 0) {
-        lines.push(`**Team contributors (${authors.length}):** ${(authors as string[]).join(', ')}`);
-        lines.push('');
-      }
+      // what_failed: union of all unique failure reasons
+      const allFailed = [...new Set(
+        [...failures, ...partials].map(e => e.what_failed).filter((w): w is string => !!w && w.length > 5)
+      )];
 
-      lines.push(`💡 Share your brain: \`invite_link()\` — generates a one-command team invite.`);
-      lines.push(`📤 Export to Markdown: \`export_brain()\` — portable snapshot you can save or share.`);
+      const severities = entries.map(e => e.severity).filter(Boolean);
+      const canonicalSeverity = severities.includes('critical') ? 'critical' : severities.includes('major') ? 'major' : 'minor';
 
-      return lines.join('\n');
+      const lines = [
+        `🧬 **Team Brain Synthesis: \`${topic}\`**`,
+        `_${entries.length} entries from ${authors.length} author${authors.length === 1 ? '' : 's'}${hasMultiAuthor ? ` (${authors.join(', ')})` : ''} · ${successes.length} success · ${failures.length} failure · ${partials.length} partial_`,
+        '',
+        `**Canonical "what worked":**`,
+        `> ${canonicalWorked}`,
+        '',
+        allFailed.length > 0 ? `**Avoid (combined failures):**` : '',
+        ...allFailed.map(f => `> ❌ ${f}`),
+        allFailed.length > 0 ? '' : '',
+        `**Suggested canonical lesson:**`,
+        '```',
+        `learn_from_attempts(`,
+        `  topic       = "${topic}",`,
+        `  outcome     = "success",`,
+        `  what_worked = "${canonicalWorked.replace(/"/g, "'")}",`,
+        allFailed.length > 0 ? `  what_failed = "${allFailed[0].replace(/"/g, "'")}",` : '',
+        `  severity    = "${canonicalSeverity}",`,
+        `)`,
+        '```',
+        '',
+        hasMultiAuthor
+          ? `💡 _${authors.length} team members contributed to this synthesis. Store the canonical version to replace individual entries._`
+          : `💡 _Single author — more value when multiple team members contribute to the same topic._`,
+      ].filter(l => l !== undefined).join('\n');
+      return lines;
     }
 
-    // ── export_brain ──────────────────────────────────────────────────────────
-    case 'export_brain': {
-      const { instance_id, include_context = true, max_lessons } = args as {
-        instance_id: string;
-        include_context?: boolean;
-        max_lessons?: number;
-      };
+    // ── brain_doctor ──────────────────────────────────────────────────────────
+    // ── memory_crystalize ─────────────────────────────────────────────────────
+    case 'memory_crystalize': {
+      const { instance_id, label: crystalLabel = '' } = args as { instance_id: string; label?: string };
       const redis = await getConnection(instance_id);
-
-      // Scan all lessons
-      const lessonKeys: string[] = [];
-      const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
-      await new Promise<void>((resolve, reject) => {
-        lStream.on('data', (batch: string[]) => lessonKeys.push(...batch));
-        lStream.on('end', resolve);
-        lStream.on('error', reject);
+      const now = new Date();
+      const week = `${now.getFullYear()}-W${String(Math.ceil((now.getDate() - now.getDay() + 10) / 7)).padStart(2, '0')}`;
+      const effectiveLabel = crystalLabel || `${now.toISOString().slice(0, 7)} Crystal`;
+
+      // Read session history
+      const sessionHistory = await redis.lrange('cachly:session:history', 0, 49);
+
+      // Read all auto-learned lessons
+      const allLessonKeys: string[] = [];
+      const ls = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+      await new Promise<void>((res, rej) => {
+        ls.on('data', (b: string[]) => allLessonKeys.push(...b));
+        ls.on('end', res);
+        ls.on('error', rej);
       });
 
-      type FullLesson = {
-        topic: string; outcome: string; what_worked: string; what_failed?: string;
-        severity?: string; ts: string; recall_count?: number; author?: string;
-        file_paths?: string[]; commands?: string[]; tags?: string[];
-      };
-      let lessons: FullLesson[] = [];
-      if (lessonKeys.length > 0) {
-        const vals = await redis.mget(...lessonKeys);
-        for (const raw of vals) {
-          if (!raw) continue;
-          try { lessons.push(JSON.parse(raw) as FullLesson); } catch { /* skip */ }
-        }
-      }
-      lessons.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
-      if (max_lessons && max_lessons > 0) lessons = lessons.slice(0, max_lessons);
-
-      // Last session + crystal
-      const lastSessionRaw = await redis.get('cachly:session:last');
-      let lastSession: { ts: string; summary: string } | null = null;
-      if (lastSessionRaw) { try { lastSession = JSON.parse(lastSessionRaw); } catch { /* ignore */ } }
-
-      const crystalRaw = await redis.get('cachly:crystal');
-      let crystal: { summary: string; created_at: string } | null = null;
-      if (crystalRaw) { try { crystal = JSON.parse(crystalRaw); } catch { /* ignore */ } }
-
-      // Context entries
-      type CtxEntry = { key: string; value: string };
-      const ctxEntries: CtxEntry[] = [];
-      if (include_context) {
-        const ctxKeys: string[] = [];
-        const ctxStream = redis.scanStream({ match: 'cachly:ctx:*', count: 200 });
-        await new Promise<void>((resolve, reject) => {
-          ctxStream.on('data', (batch: string[]) => {
-            ctxKeys.push(...batch.filter((k: string) => !k.endsWith(':meta')));
-          });
-          ctxStream.on('end', resolve);
-          ctxStream.on('error', reject);
-        });
-        if (ctxKeys.length > 0) {
-          const ctxVals = await redis.mget(...ctxKeys);
-          for (let i = 0; i < ctxKeys.length; i++) {
-            const val = ctxVals[i];
-            if (val) ctxEntries.push({ key: ctxKeys[i].replace('cachly:ctx:', ''), value: val });
-          }
-        }
+      type RawLesson = { topic: string; outcome: string; what_worked: string; severity?: string; ts: string; auto_learned?: boolean };
+      const allLessons: RawLesson[] = [];
+      for (const k of allLessonKeys) {
+        const raw = await redis.get(k);
+        if (!raw) continue;
+        try { allLessons.push(JSON.parse(raw) as RawLesson); } catch { /* skip */ }
       }
 
-      const exportedAt = new Date().toISOString();
-      const totalRecalls = lessons.reduce((s, l) => s + (l.recall_count ?? 0), 0);
-      const savedHours = (totalRecalls * 15 / 60).toFixed(1);
-
-      const md: string[] = [
-        `# 🧠 cachly Brain Export`,
-        ``,
-        `> Exported: ${exportedAt}  `,
-        `> Instance: \`${instance_id}\`  `,
-        `> Lessons: ${lessons.length} · Recalls: ${totalRecalls} · Time saved: ~${savedHours}h`,
-        ``,
-      ];
-
-      if (crystal) {
-        md.push(`## 💎 Memory Crystal`, ``, `> ${crystal.summary}`, ``, `_Generated: ${crystal.created_at}_`, ``);
+      // Group lessons by top-level category
+      const categoryMap = new Map<string, RawLesson[]>();
+      for (const l of allLessons) {
+        const cat = l.topic.split(':')[0] || 'misc';
+        if (!categoryMap.has(cat)) categoryMap.set(cat, []);
+        categoryMap.get(cat)!.push(l);
       }
 
-      if (lastSession) {
-        md.push(`## 📅 Last Session`, ``, `**${lastSession.ts.slice(0, 10)}** — ${lastSession.summary}`, ``);
+      // Build top patterns (most frequent categories with a representative insight)
+      const topPatterns: Array<{ category: string; insight: string; count: number }> = [];
+      for (const [cat, catLessons] of [...categoryMap.entries()].sort((a, b) => b[1].length - a[1].length).slice(0, 8)) {
+        const successLessons = catLessons.filter(l => l.outcome === 'success');
+        const best = successLessons[0] ?? catLessons[0];
+        if (!best) continue;
+        topPatterns.push({
+          category: cat,
+          insight: best.what_worked.slice(0, 120),
+          count: catLessons.length,
+        });
       }
 
-      // Group lessons by outcome
-      const successLessons = lessons.filter(l => l.outcome === 'success');
-      const failureLessons = lessons.filter(l => l.outcome !== 'success');
-
-      const formatLesson = (l: FullLesson) => {
-        const sev = l.severity === 'critical' ? ' 🔴' : l.severity === 'major' ? ' 🟡' : '';
-        const lines: string[] = [
-          `### \`${l.topic}\`${sev}`,
-          ``,
-          `**Outcome:** ${l.outcome}  `,
-          `**Recalls:** ${l.recall_count ?? 0}×  `,
-          `**Stored:** ${l.ts.slice(0, 10)}${l.author ? `  \n**Author:** ${l.author}` : ''}`,
-          ``,
-          `**What worked:**  `,
-          l.what_worked,
-        ];
-        if (l.what_failed) { lines.push(``, `**What failed:**  `, l.what_failed); }
-        if ((l.commands ?? []).length > 0) {
-          lines.push(``, `**Commands:**`);
-          for (const cmd of l.commands!) lines.push(`\`\`\`\n${cmd}\n\`\`\``);
-        }
-        if ((l.file_paths ?? []).length > 0) {
-          lines.push(``, `**Files:** ${l.file_paths!.map(f => `\`${f}\``).join(', ')}`);
-        }
-        if ((l.tags ?? []).length > 0) {
-          lines.push(``, `**Tags:** ${l.tags!.map(t => `\`${t}\``).join(', ')}`);
-        }
-        lines.push(``);
-        return lines.join('\n');
+      const crystal = {
+        label: effectiveLabel,
+        ts: now.toISOString(),
+        session_count: sessionHistory.length,
+        lesson_count: allLessons.length,
+        top_patterns: topPatterns,
+        categories: [...categoryMap.keys()],
+        created_from: `${sessionHistory.length} sessions, ${allLessons.length} lessons`,
       };
 
-      if (successLessons.length > 0) {
-        md.push(`## ✅ Successful Solutions (${successLessons.length})`, ``);
-        for (const l of successLessons) md.push(formatLesson(l));
-      }
-
-      if (failureLessons.length > 0) {
-        md.push(`## ⚠️ Open / Partial Issues (${failureLessons.length})`, ``);
-        for (const l of failureLessons) md.push(formatLesson(l));
-      }
-
-      if (ctxEntries.length > 0) {
-        md.push(`## 📁 Context Entries (${ctxEntries.length})`, ``);
-        for (const e of ctxEntries) {
-          md.push(`### \`${e.key}\``, ``, e.value.slice(0, 500) + (e.value.length > 500 ? '\n\n_[truncated]_' : ''), ``);
-        }
-      }
-
-      md.push(
-        `---`,
-        ``,
-        `_Exported from [cachly AI Brain](https://cachly.dev) · Re-import with \`npx @cachly-dev/mcp-server@latest setup\`_`,
-      );
-
-      return md.join('\n');
-    }
-
-    // ── invite_link ───────────────────────────────────────────────────────────
-    case 'invite_link': {
-      const { instance_id, label = '' } = args as { instance_id: string; label?: string };
-
-      // Generate a share token via API
-      let shareToken = '';
-      let inviteUrl  = '';
-      try {
-        const res = await apiFetch<{ token?: string; url?: string }>(
-          `/api/v1/instances/${instance_id}/invite`,
-          { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label }) }
-        );
-        shareToken = res.token ?? '';
-        inviteUrl  = res.url  ?? '';
-      } catch {
-        // API doesn't support invite yet — generate a local share snippet instead
-      }
-
-      // Build the join command
-      const joinCmd = shareToken
-        ? `npx @cachly-dev/mcp-server@latest join ${shareToken}`
-        : `npx @cachly-dev/mcp-server@latest setup`;
+      const crystalJson = JSON.stringify(crystal);
+      await redis.set('cachly:crystal:latest', crystalJson);
+      await redis.expire('cachly:crystal:latest', 90 * 86400);
+      await redis.set(`cachly:crystal:${week}`, crystalJson);
+      await redis.expire(`cachly:crystal:${week}`, 365 * 86400);
 
       const lines = [
-        `🔗 **Team Invite — ${label || instance_id.slice(0, 8) + '…'}**`,
-        ``,
-        `Share this command with your teammate:`,
+        `💎 **Memory Crystal created: ${effectiveLabel}**`,
         ``,
-        `\`\`\`bash`,
-        joinCmd,
-        `\`\`\``,
+        `📊 Compressed: **${sessionHistory.length} sessions** + **${allLessons.length} lessons** → ${topPatterns.length} top patterns`,
         ``,
-        `**What happens when they run it:**`,
-        `  1. Browser opens → they sign in (free, 30 seconds)`,
-        `  2. Their Brain is auto-connected to this shared instance`,
-        `  3. All ${label ? `"${label}" ` : ''}lessons and context are instantly available`,
-        `  4. Editor configs written automatically — no copy-paste`,
+        `**Top patterns by category:**`,
+        ...topPatterns.slice(0, 6).map(p => `  • **${p.category}** (${p.count}×): ${p.insight.slice(0, 90)}`),
         ``,
+        `💡 This crystal will appear in every future \`session_start\` briefing.`,
+        `💡 Re-run \`memory_crystalize\` monthly to keep it fresh.`,
       ];
-
-      if (inviteUrl) {
-        lines.push(`**Or share the link directly:** ${inviteUrl}`, ``);
-      }
-
-      lines.push(
-        `💡 Teammates can also run \`session_start\` immediately to see all your lessons.`,
-        `   Use \`team_learn\` with an \`author\` param so everyone knows who learned what.`,
-      );
-
       return lines.join('\n');
     }
 
-    // ── brain_doctor ──────────────────────────────────────────────────────────
     case 'brain_doctor': {
-      const { instance_id } = args as { instance_id: string };
+      const { instance_id, workspace_path: drWorkspacePath = '' } = args as { instance_id: string; workspace_path?: string };
       const redis = await getConnection(instance_id);
       const issues: string[] = [];
       const checks: string[] = [];
@@ -3737,15 +4900,16 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         ctxStream.on('error', reject);
       });
 
-      // Load lessons for analysis — batch fetch
-      type Lesson = { topic: string; outcome: string; recall_count?: number; ts: string; severity?: string };
-      const lessons: Lesson[] = [];
-      if (lessonKeys.length > 0) {
-        const vals = await redis.mget(...lessonKeys);
-        for (const raw of vals) {
-          if (!raw) continue;
-          try { lessons.push(JSON.parse(raw) as Lesson); } catch { /* skip */ }
-        }
+      // Load lessons for analysis
+      type DrLesson = {
+        topic: string; outcome: string; recall_count?: number; ts: string;
+        verified_at?: string; severity?: string; audit_trail?: unknown[];
+      };
+      const lessons: DrLesson[] = [];
+      for (const k of lessonKeys) {
+        const raw = await redis.get(k);
+        if (!raw) continue;
+        try { lessons.push(JSON.parse(raw) as DrLesson); } catch { /* skip */ }
       }
 
       // Last session
@@ -3761,6 +4925,17 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       const unusedLessons = lessons.filter(l => (l.recall_count ?? 0) === 0);
       // Critical lessons
       const criticalLessons = lessons.filter(l => l.severity === 'critical');
+      // Confidence decay analysis
+      const staleLessons  = lessons.filter(l => l.outcome === 'success' && calculateConfidence(l) < CONFIDENCE_STALE_VALUE);
+      const warnLessons   = lessons.filter(l => l.outcome === 'success' && calculateConfidence(l) >= CONFIDENCE_STALE_VALUE && calculateConfidence(l) < CONFIDENCE_WARN_VALUE);
+      const withAudit     = lessons.filter(l => (l.audit_trail ?? []).length > 1);
+      // Team lessons
+      type DrLessonWithAuthor = DrLesson & { author?: string };
+      const teamLessons = (lessons as DrLessonWithAuthor[]).filter(l => l.author);
+      const uniqueAuthors = new Set((lessons as DrLessonWithAuthor[]).map(l => l.author).filter(Boolean));
+      // Effective IQ boost: total recalls / lessons (how much the brain actually helped)
+      const totalRecalls = lessons.reduce((sum, l) => sum + (l.recall_count ?? 0), 0);
+      const iqBoostPct = lessons.length > 0 ? Math.min(100, Math.round((totalRecalls / lessons.length) * 10)) : 0;
 
       // Quality score (0-100)
       let score = 50;
@@ -3772,12 +4947,67 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       if (openFailures.length === 0) score += 5;
       const unusedRatio = lessons.length > 0 ? unusedLessons.length / lessons.length : 0;
       if (unusedRatio < 0.5)       score += 10;
+      if (staleLessons.length === 0) score += 5;
+      if (uniqueAuthors.size >= 2) score += 5; // team collaboration bonus
 
       const scoreEmoji = score >= 80 ? '🟢' : score >= 50 ? '🟡' : '🔴';
+      const iqEmoji = iqBoostPct >= 50 ? '🚀' : iqBoostPct >= 20 ? '📈' : '💤';
 
       checks.push(`${scoreEmoji} **Brain Quality Score: ${score}/100**`);
-      checks.push(`📚 **Lessons:** ${lessonKeys.length} (${criticalLessons.length} critical)`);
+      checks.push(`${iqEmoji} **Effective IQ Boost: ${iqBoostPct}%** (${totalRecalls} recalls across ${lessons.length} lessons)`);
+      checks.push(`📚 **Lessons:** ${lessonKeys.length} (${criticalLessons.length} critical · ${withAudit.length} with audit trail · ${teamLessons.length} from team)`);
       checks.push(`💾 **Context entries:** ${ctxCount}`);
+      checks.push(`🎯 **Confidence:** ${lessons.length - staleLessons.length - warnLessons.length} fresh · ${warnLessons.length} warn · ${staleLessons.length} stale`);
+      checks.push(`⏱️ **Decay config:** warn after ${CONFIDENCE_WARN_DAYS}d · stale after ${CONFIDENCE_STALE_DAYS}d`);
+      if (uniqueAuthors.size >= 2) {
+        checks.push(`👥 **Team:** ${uniqueAuthors.size} contributors (${[...uniqueAuthors].join(', ')})`);
+      }
+
+      // Stale index detection
+      try {
+        const lastIndexRaw = await redis.get('cachly:index:last_run');
+        if (lastIndexRaw) {
+          const lastIndexAge = Math.round((Date.now() - new Date(lastIndexRaw).getTime()) / 86_400_000);
+          if (lastIndexAge > 7) {
+            issues.push(`🔄 Index is ${lastIndexAge}d stale — run \`index_project\` to re-sync semantic search`);
+          } else {
+            checks.push(`🗂️ **Semantic index:** ${lastIndexAge}d old (fresh)`);
+          }
+        } else {
+          issues.push(`💡 No semantic index — run \`index_project(dir="<your-src>")\` to enable semantic search`);
+        }
+      } catch { /* non-critical */ }
+
+      // Memory crystal status
+      try {
+        const crystalRaw = await redis.get('cachly:crystal:latest');
+        if (crystalRaw) {
+          const crystal = JSON.parse(crystalRaw) as { ts: string; label: string };
+          const crystalAge = Math.round((Date.now() - new Date(crystal.ts).getTime()) / 86_400_000);
+          checks.push(`💎 **Memory Crystal:** ${crystal.label} (${crystalAge}d ago)`);
+          if (crystalAge > 30) issues.push(`💡 Memory Crystal is ${crystalAge}d old — re-run \`memory_crystalize\` to compress new sessions`);
+        } else if (lessonKeys.length >= 10) {
+          issues.push(`💡 ${lessonKeys.length} lessons but no Memory Crystal — run \`memory_crystalize\` to compress wisdom`);
+        }
+      } catch { /* non-critical */ }
+
+      // openclaw cross-promo (check package.json in workspace)
+      if (drWorkspacePath) {
+        try {
+          const pkgPath = drWorkspacePath.replace(/\/$/, '') + '/package.json';
+          const pkgRaw = readFileSync(pkgPath, 'utf-8');
+          const pkg = JSON.parse(pkgRaw) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+          const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+          const hasLLMDep = ['openai', '@anthropic-ai/sdk', '@google/generative-ai', 'mistralai', 'cohere-ai'].some(d => d in allDeps);
+          const hasOpenclaw = '@cachly-dev/openclaw' in allDeps;
+          if (hasLLMDep && !hasOpenclaw) {
+            issues.push(`💡 **openclaw missing:** you use LLM APIs (${Object.keys(allDeps).filter(d => ['openai','@anthropic-ai/sdk'].includes(d)).join(', ')}) but not \`@cachly-dev/openclaw\``);
+            issues.push(`   → \`npm install @cachly-dev/openclaw\` cuts LLM costs 60–90% with 3 lines of code`);
+          } else if (hasOpenclaw) {
+            checks.push(`✅ **@cachly-dev/openclaw installed** (LLM cost caching active)`);
+          }
+        } catch { /* no package.json or unreadable */ }
+      }
 
       if (lastSession) {
         const ageMin = Math.round((Date.now() - new Date(lastSession.ts).getTime()) / 60000);
@@ -3793,6 +5023,10 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         issues.push(`💡 Only ${lessonKeys.length} lessons — add more after each problem solved`);
       }
 
+      if (iqBoostPct === 0 && lessons.length >= 5) {
+        issues.push(`💤 **IQ Boost is 0%** — lessons exist but are never recalled. Use \`recall_best_solution\` BEFORE tasks.`);
+      }
+
       if (ctxCount === 0) {
         issues.push('💡 No context — use `remember_context` to cache architecture docs, ADRs, etc.');
       }
@@ -3801,6 +5035,15 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         issues.push(`⚠️ ${openFailures.length} unresolved failure${openFailures.length > 1 ? 's' : ''}: ${openFailures.slice(0, 3).map(l => `\`${l.topic}\``).join(', ')}`);
       }
 
+      if (staleLessons.length > 0) {
+        issues.push(`🔴 ${staleLessons.length} STALE lesson${staleLessons.length > 1 ? 's' : ''} (>${CONFIDENCE_STALE_DAYS}d, confidence <${CONFIDENCE_STALE_VALUE * 100}%): ${staleLessons.slice(0, 3).map(l => `\`${l.topic}\``).join(', ')}`);
+        issues.push(`   → Re-verify with \`recall_best_solution\` to reset confidence clock`);
+      }
+
+      if (warnLessons.length > 0) {
+        issues.push(`⚠️ ${warnLessons.length} lesson${warnLessons.length > 1 ? 's' : ''} aging (>${CONFIDENCE_WARN_DAYS}d): ${warnLessons.slice(0, 3).map(l => `\`${l.topic}\``).join(', ')}`);
+      }
+
       if (unusedRatio > 0.7 && lessons.length > 5) {
         issues.push(`💡 ${unusedLessons.length} lessons never recalled — verify topics match your workflow`);
       }
@@ -3816,6 +5059,77 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       return lines.join('\n');
     }
 
+    // ── recall_at — Brain Archaeology ────────────────────────────────────────
+    case 'recall_at': {
+      const { instance_id, topic, date } = args as { instance_id: string; topic: string; date: string };
+      const redis = await getConnection(instance_id);
+      const cutoff = new Date(date).getTime();
+      if (isNaN(cutoff)) return `❌ Invalid date "${date}". Use ISO format: "2026-01-15"`;
+
+      const listKey = `cachly:lessons:${topic}`;
+      const all = await redis.lrange(listKey, 0, -1);
+      if (all.length === 0) return `📭 No history found for \`${topic}\`. Lessons are stored via \`learn_from_attempts\`.`;
+
+      const before = all
+        .map(raw => { try { return JSON.parse(raw) as { ts: string; outcome?: string; what_worked?: string; what_failed?: string }; } catch { return null; } })
+        .filter((l): l is NonNullable<typeof l> => l !== null && new Date(l.ts).getTime() <= cutoff)
+        .sort((a, b) => new Date(a.ts).getTime() - new Date(b.ts).getTime());
+
+      if (before.length === 0) return `📭 No entries for \`${topic}\` found before **${date}**. Earliest entry: ${new Date(JSON.parse(all[0]).ts).toLocaleDateString('de-DE')}.`;
+
+      const lines = [
+        `🏺 **Brain Archaeology: \`${topic}\` before ${date}**`,
+        `_${before.length} of ${all.length} total entries shown_`,
+        '',
+      ];
+      for (const l of before.slice(-10)) {
+        const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+        const d = new Date(l.ts).toLocaleDateString('de-DE');
+        lines.push(`**${d}** ${emoji} ${l.outcome}`);
+        if (l.what_worked) lines.push(`  → ${l.what_worked.slice(0, 100)}`);
+        lines.push('');
+      }
+      lines.push(`_Full evolution: ${all.map(r => { try { const l = JSON.parse(r) as { outcome?: string }; return l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌'; } catch { return '?'; } }).join(' → ')}_`);
+      return lines.join('\n');
+    }
+
+    // ── trace_dependency — Causal Chain ──────────────────────────────────────
+    case 'trace_dependency': {
+      const { instance_id, dependency, mark_review = false } = args as { instance_id: string; dependency: string; mark_review?: boolean };
+      const redis = await getConnection(instance_id);
+
+      const depKey = `cachly:dep:${dependency}`;
+      const raw = await redis.get(depKey);
+      if (!raw) return `📭 No lessons found that depend on \`${dependency}\`.\n\nAdd dependencies via: \`learn_from_attempts(..., depends_on=["${dependency}"])\``;
+
+      const topics: string[] = JSON.parse(raw);
+      const lines = [
+        `🔗 **Causal Chain: \`${dependency}\`** — ${topics.length} dependent lesson${topics.length === 1 ? '' : 's'}`,
+        '',
+      ];
+
+      for (const t of topics) {
+        const lessonRaw = await redis.get(`cachly:lesson:best:${t}`);
+        if (!lessonRaw) { lines.push(`  • \`${t}\` _(lesson deleted)_`); continue; }
+        const lesson = JSON.parse(lessonRaw) as { outcome?: string; severity?: string; needs_review?: boolean };
+        const emoji = lesson.outcome === 'success' ? '✅' : lesson.outcome === 'partial' ? '⚠️' : '❌';
+        const reviewBadge = lesson.needs_review ? ' 🔍 **needs_review**' : '';
+        lines.push(`  ${emoji} \`${t}\` (${lesson.severity ?? 'major'})${reviewBadge}`);
+
+        if (mark_review) {
+          const updated = { ...lesson, needs_review: true };
+          await redis.set(`cachly:lesson:best:${t}`, JSON.stringify(updated));
+        }
+      }
+
+      if (mark_review) {
+        lines.push('', `🔍 All ${topics.length} lessons marked as **needs_review** — verify they still work with the changed dependency.`);
+      } else {
+        lines.push('', `_Run with \`mark_review: true\` to flag all dependent lessons for re-verification._`);
+      }
+      return lines.join('\n');
+    }
+
     // ── global_learn ──────────────────────────────────────────────────────────
     case 'global_learn': {
       const { instance_id, topic, lesson, severity = 'minor', tags = [] } = args as {
@@ -4097,65 +5411,148 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       // Generate copilot-instructions.md content
       const tier = inst.tier.toUpperCase();
       const smartRecallNote = hasVector
-        ? '3. Call `smart_recall` with keywords for semantic context search'
-        : '3. Call `recall_context` with relevant key patterns like "arch:*" or "file:*"';
+        ? '- `smart_recall("natural language query")` — semantic search (finds by meaning)'
+        : '- `recall_context("arch:*")` — exact/glob key lookup (upgrade to Speed/Business for smart_recall)';
       const layerNote = hasVector
-        ? `Layer 3 (Semantic): smart_recall uses pgvector HNSW on your ${tier} instance for meaning-based search`
-        : `Layer 3 (Autopilot): This file — upgrade to Speed/Business tier to unlock smart_recall`;
+        ? `Layer 3 (Semantic): smart_recall uses pgvector HNSW on your ${tier} instance`
+        : `Layer 3 (Autopilot): this file — upgrade to Speed/Business tier to unlock smart_recall`;
 
-      const copilotInstructions = `# cachly AI Memory — ${project_description}
+      const copilotInstructions = `# cachly AI Brain — ${project_description}
 
-## 3-Layer AI Memory System
+> AI memory system powered by [cachly.dev](https://cachly.dev). Works with GitHub Copilot, Claude Code, Cursor, Windsurf, Continue.dev, and any MCP-compatible editor.
 
-- **Layer 1 — Storage:** cachly instance \`${inst.name}\` (${tier}) — persistent Valkey brain, survives restarts
-- **Layer 2 — Tools:** learn_from_attempts · recall_best_solution · smart_recall — the memory API
-- **Layer 3 — Autopilot (this file):** instructs the AI to run memory tools automatically
+---
 
-## BEFORE every task — check memory first
+## 🔴 MANDATORY RULES — Always enforced, no exceptions
 
-1. Call \`recall_best_solution\` with the task topic to get known solutions
-   - \`recall_best_solution("deploy:web")\` → returns working deploy command
-   - \`recall_best_solution("debug:redis-tls")\` → returns root cause + fix
-   - If a solution exists, use it — do NOT re-discover from scratch
+### Rule 1 — Session Start (FIRST thing in every window)
+Call \`session_start\` **before reading any source files or making any changes**:
 
-2. Call \`recall_context\` with the area you're working in
-   - \`recall_context("arch:*")\` → cached architecture decisions
-   - \`recall_context("file:src/auth*")\` → cached file summaries
+\`\`\`
+session_start(
+  instance_id = "${instance_id}",
+  focus       = "<what you plan to work on today>",
+)
+\`\`\`
 
-${smartRecallNote}
-   - \`smart_recall("how does authentication work")\` → returns cached auth notes
+Returns: last session summary, handoff from previous window, recent lessons, open failures, brain health.
 
-4. If nothing is found, proceed normally — then save (see below)
+**If \`session_start\` is unavailable**, fall back:
+1. \`smart_recall("recent lessons <topic>")\`
+2. \`recall_best_solution("<topic>")\`
 
-## AFTER every non-trivial task — save to memory
+### Rule 2 — Learn After Every Fix/Deploy/Discovery (AUTOMATIC — no prompting needed)
+After **every** bug fix, deployment, failed attempt, or discovery — call \`learn_from_attempts\` immediately:
 
-1. Call \`learn_from_attempts\` for deploy/debug/fix tasks:
-   - Always set outcome = "success" | "failure" | "partial"
-   - Always include what_failed — it prevents future wasted time
-   - Example: \`learn_from_attempts(topic="deploy:api", outcome="success", what_worked="nohup docker compose up -d --build", what_failed="direct docker compose hangs on SSH timeout")\`
+\`\`\`
+learn_from_attempts(
+  instance_id = "${instance_id}",
+  topic       = "category:keyword",   # deploy:web | fix:auth | debug:db | infra:docker
+  outcome     = "success" | "failure" | "partial",
+  what_worked = "exact approach or command that worked",
+  what_failed = "what did NOT work (prevents future wasted time)",
+  severity    = "critical" | "major" | "minor",
+  commands    = ["exact command that worked"],
+  file_paths  = ["path/to/changed/file"],
+)
+\`\`\`
+
+**These events MUST automatically trigger \`learn_from_attempts\`:**
+- ✅ Successfully deployed → \`topic="deploy:<component>", outcome="success"\`
+- ✅ Fixed a bug → \`topic="fix:<description>", outcome="success"\`
+- ✅ Discovered root cause → \`topic="debug:<area>", outcome="partial"\`
+- ✅ Tried something that failed → \`topic="<area>", outcome="failure", what_failed="..."\`
+- ✅ Found a config quirk → \`topic="infra:<topic>", outcome="success"\`
+- ✅ Ran a working command → store it in \`commands=[...]\`
 
-2. Call \`remember_context\` for code/architecture findings:
-   - \`remember_context("arch:auth", "Uses Keycloak with JWT...", category="architecture")\`
-   - \`remember_context("file:src/index.ts", "Entry point, registers routes...", category="file_summary")\`
+### Rule 3 — Session Handoff (when closing window or task list > 3 items)
+\`\`\`
+session_handoff(
+  instance_id     = "${instance_id}",
+  completed_tasks = ["what was done"],
+  remaining_tasks = ["what is still to do"],
+  files_changed   = [{"path": "src/...", "status": "modified", "description": "what changed"}],
+  instructions    = "IMPORTANT: what the next window MUST know to not break things",
+  context_summary = "current state of the system",
+)
+\`\`\`
+
+The next \`session_start\` automatically includes this handoff. The new window sees exactly what's done, what remains, and what NOT to break.
+
+### Rule 4 — Session End (LAST thing before closing)
+\`\`\`
+session_end(
+  instance_id     = "${instance_id}",
+  summary         = "What was accomplished (2-3 sentences with specifics)",
+  files_changed   = ["list", "of", "changed", "files"],
+  lessons_learned = <number of learn_from_attempts calls made>,
+)
+\`\`\`
+
+> \`session_end\` **automatically extracts and stores lessons** from the summary text — no manual calls needed.
+
+### Rule 5 — Code Index Invalidation (AUTOMATIC)
+- \`index_project\` tracks MD5 hashes per file — **skips unchanged files automatically**
+- After code changes: next \`index_project\` run re-indexes only modified files
+- After delete/rename: run \`index_project\` again to sync
+- No manual invalidation needed
+
+---
+
+## Task-type trigger table
+
+| You're about to... | Call BEFORE | Call AFTER |
+|---|---|---|
+| Deploy anything | \`recall_best_solution("deploy:<component>")\` | \`learn_from_attempts(topic="deploy:...")\` |
+| Fix a bug | \`recall_best_solution("fix:<area>")\` | \`learn_from_attempts(topic="fix:...")\` |
+| Add a feature | \`session_start(focus="feat:<area>")\` | \`learn_from_attempts(topic="feat:...")\` |
+| Infra/server work | \`recall_best_solution("infra:<topic>")\` | \`learn_from_attempts(topic="infra:...")\` |
+| Debug an issue | \`smart_recall("<error message or symptom>")\` | \`learn_from_attempts(topic="debug:...")\` |
+
+---
+
+## Available Brain Tools
+
+| Tool | When to use |
+|------|-------------|
+| \`session_start\` | **FIRST** — mandatory at start of every session |
+| \`session_end\` | **LAST** — mandatory at end, auto-learns from summary |
+| \`session_handoff\` | When closing window with remaining tasks |
+| \`learn_from_attempts\` | **AUTOMATIC** after every fix/deploy/discovery |
+| \`recall_best_solution\` | Before any non-trivial task |
+| \`remember_context\` | After analyzing code — save findings for future sessions |
+${smartRecallNote ? `| \`smart_recall\` | Search brain by meaning/keywords |\n` : ''}\
+| \`recall_context\` | Get exact key (supports glob: \`arch:*\`, \`file:*\`) |
+| \`brain_search\` | BM25+ full-text search over all brain data |
+| \`auto_learn_session\` | Batch-learn from a list of observations (optional) |
+| \`index_project\` | Index source files (smart hash, skips unchanged files) |
+| \`list_remembered\` | See what's cached in the brain |
+| \`forget_context\` | Remove stale context |
+
+---
 
 ## Instance Details
 
-- Instance ID: \`${instance_id}\`
-- Instance name: ${inst.name}
-- Tier: ${tier}
-- ${layerNote}
-- Embedding provider: ${providerArg}
+- **Instance ID:** \`${instance_id}\`
+- **Instance name:** ${inst.name}
+- **Tier:** ${tier}
+- **${layerNote}**
+- **Embedding provider:** ${providerArg}
+
+---
 
-## Quick reference
+## How the 3-layer system works
 
 \`\`\`
-recall_best_solution("topic")        # before task
-smart_recall("natural language")     # find by meaning
-learn_from_attempts(...)             # after task
-remember_context("key", "content")   # save analysis
+Layer 1 — Storage:  Your cachly Valkey instance (${inst.name}) — persists forever
+Layer 2 — Tools:    learn_from_attempts · recall_best_solution · brain_search · session_start/end
+Layer 3 — Autopilot: This file — AI reads it and runs tools automatically every session
 \`\`\`
+
+Result: Your AI **never solves the same problem twice** and always picks up exactly where it left off. 🚀
 `;
 
+
       const lines: string[] = [
         `🧠 **cachly AI Memory Setup Complete**`,
         ``,
@@ -4179,8 +5576,8 @@ remember_context("key", "content")   # save analysis
         `**Step 3 — copilot-instructions.md (Layer 3 Autopilot):**`,
         ``,
         ...(project_dir
-          ? [`Writing to \`${project_dir}/.github/copilot-instructions.md\`…`]
-          : [`Copy this to \`.github/copilot-instructions.md\` in your project:`]),
+          ? [`🔍 Detecting IDEs in \`${project_dir}\`…`]
+          : [`Copy this to \`.github/copilot-instructions.md\` (Copilot), \`CLAUDE.md\` (Claude Code), or \`.cursor/rules\` (Cursor) in your project:`]),
         ``,
         `\`\`\`markdown`,
         copilotInstructions,
@@ -4195,16 +5592,104 @@ remember_context("key", "content")   # save analysis
         `Result: Your AI never solves the same problem twice. 🚀`,
       ];
 
-      // Optionally write the file
+      // ── IDE auto-detection + file writing ────────────────────────────────
       if (project_dir) {
-        const { mkdir, writeFile } = await import('node:fs/promises');
-        const githubDir = join(project_dir, '.github');
-        await mkdir(githubDir, { recursive: true });
-        const filePath = join(githubDir, 'copilot-instructions.md');
-        await writeFile(filePath, copilotInstructions, 'utf-8');
-        lines.splice(lines.indexOf(`Writing to \`${project_dir}/.github/copilot-instructions.md\`…`) + 1, 0,
-          `✅ Written to \`${project_dir}/.github/copilot-instructions.md\``
-        );
+        const { mkdir, writeFile, access } = await import('node:fs/promises');
+        const { constants } = await import('node:fs');
+
+        const exists = async (p: string) => access(p, constants.F_OK).then(() => true).catch(() => false);
+
+        // Detect which IDEs are present based on marker files/dirs
+        interface IdeTarget { ide: string; path: string; content: string }
+        const targets: IdeTarget[] = [];
+        let stopHookWritten = false;
+
+        // GitHub Copilot — always write (universal fallback)
+        targets.push({
+          ide: 'GitHub Copilot',
+          path: join(project_dir, '.github', 'copilot-instructions.md'),
+          content: copilotInstructions,
+        });
+
+        // Claude Code — CLAUDE.md in project root
+        if (await exists(join(project_dir, 'CLAUDE.md')) || await exists(join(project_dir, '.claude'))) {
+          targets.push({
+            ide: 'Claude Code',
+            path: join(project_dir, 'CLAUDE.md'),
+            content: copilotInstructions,
+          });
+
+          // Claude Code Stop-Hook — auto-saves checkpoint when Claude stops responding
+          const claudeDir = join(project_dir, '.claude');
+          await mkdir(claudeDir, { recursive: true });
+          const stopHook = {
+            hooks: {
+              Stop: [
+                {
+                  matcher: '',
+                  hooks: [
+                    {
+                      type: 'command',
+                      command: `npx --yes @cachly-dev/mcp-server@latest checkpoint --instance-id ${instance_id}`,
+                    },
+                  ],
+                },
+              ],
+            },
+          };
+          const settingsPath = join(claudeDir, 'settings.json');
+          let existingSettings: Record<string, unknown> = {};
+          try {
+            const { readFile: rf } = await import('node:fs/promises');
+            existingSettings = JSON.parse(await rf(settingsPath, 'utf-8'));
+          } catch { /* new file */ }
+          const merged = { ...existingSettings, hooks: (stopHook as Record<string, unknown>).hooks };
+          await writeFile(settingsPath, JSON.stringify(merged, null, 2), 'utf-8');
+          stopHookWritten = true;
+        }
+
+        // Cursor — .cursor/rules (new format) or .cursorrules (legacy)
+        if (
+          await exists(join(project_dir, '.cursor')) ||
+          await exists(join(project_dir, '.cursorrules'))
+        ) {
+          const cursorDir = join(project_dir, '.cursor');
+          await mkdir(cursorDir, { recursive: true });
+          targets.push({
+            ide: 'Cursor',
+            path: join(cursorDir, 'rules'),
+            content: copilotInstructions,
+          });
+        }
+
+        // Windsurf — .windsurfrules
+        if (
+          await exists(join(project_dir, '.windsurfrules')) ||
+          await exists(join(project_dir, '.windsurf'))
+        ) {
+          targets.push({
+            ide: 'Windsurf',
+            path: join(project_dir, '.windsurfrules'),
+            content: copilotInstructions,
+          });
+        }
+
+        // VS Code (Copilot) — already covered by .github/copilot-instructions.md above
+        // Continue.dev — .continue/config.json is JSON, not markdown — skip, copilot-instructions handles it
+
+        const written: string[] = [];
+        for (const target of targets) {
+          const dir = target.path.substring(0, target.path.lastIndexOf('/'));
+          await mkdir(dir, { recursive: true });
+          await writeFile(target.path, target.content, 'utf-8');
+          written.push(`✅ [${target.ide}] → \`${target.path.replace(project_dir, '.')}\``);
+        }
+
+        if (stopHookWritten) {
+          written.push(`✅ [Claude Code Stop-Hook] → \`.claude/settings.json\` (auto-checkpoint on stop)`);
+        }
+
+        lines.push(...written);
       }
 
       return lines.join('\n');
@@ -4332,6 +5817,178 @@ async function handleBulkLockStream(name: string, args: Record<string, unknown>)
       );
     }
 
+    // ── Roadmap ──────────────────────────────────────────────────────────────
+
+    case 'roadmap_add': {
+      const {
+        instance_id: rid,
+        title,
+        description: desc = '',
+        priority = 'medium',
+        tags: rtags = [],
+        milestone = '',
+      } = args as {
+        instance_id: string; title: string; description?: string;
+        priority?: string; tags?: string[]; milestone?: string;
+      };
+      const redis = await getConnection(rid);
+      const id = `rm_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+      const item = {
+        id, title, description: desc, priority, tags: rtags, milestone,
+        status: 'planned',
+        created: new Date().toISOString(),
+        updated: new Date().toISOString(),
+        notes: '',
+      };
+      await redis.hset(`cachly:roadmap:${rid}`, id, JSON.stringify(item));
+      const PRIORITY_ICON: Record<string, string> = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
+      return [
+        `📋 **Roadmap item added**`,
+        ``,
+        `  ID:       \`${id}\``,
+        `  Title:    ${title}`,
+        `  Priority: ${PRIORITY_ICON[priority] ?? '⚪'} ${priority}`,
+        `  Status:   planned`,
+        milestone ? `  Milestone: ${milestone}` : '',
+        rtags.length ? `  Tags:     ${rtags.join(', ')}` : '',
+        ``,
+        `💡 Use \`roadmap_update(id: "${id}", status: "in-progress")\` when you start working on it.`,
+      ].filter(Boolean).join('\n');
+    }
+
+    case 'roadmap_update': {
+      const {
+        instance_id: rid,
+        id: itemId,
+        status: newStatus,
+        priority: newPriority,
+        notes: newNotes,
+        title: newTitle,
+        description: newDesc,
+      } = args as {
+        instance_id: string; id: string; status?: string; priority?: string;
+        notes?: string; title?: string; description?: string;
+      };
+      const redis = await getConnection(rid);
+      const raw = await redis.hget(`cachly:roadmap:${rid}`, itemId);
+      if (!raw) return `⚠️ **roadmap_update** – Item \`${itemId}\` not found. Use \`roadmap_list\` to see all items.`;
+      const item = JSON.parse(raw) as Record<string, unknown>;
+      const oldStatus = item.status as string;
+      if (newStatus) item.status = newStatus;
+      if (newPriority) item.priority = newPriority;
+      if (newTitle) item.title = newTitle;
+      if (newDesc) item.description = newDesc;
+      if (newNotes) item.notes = item.notes ? `${item.notes}\n[${new Date().toISOString().slice(0, 10)}] ${newNotes}` : `[${new Date().toISOString().slice(0, 10)}] ${newNotes}`;
+      item.updated = new Date().toISOString();
+      await redis.hset(`cachly:roadmap:${rid}`, itemId, JSON.stringify(item));
+      const statusEmoji: Record<string, string> = { planned: '📋', 'in-progress': '⚡', done: '✅', blocked: '🚫', cancelled: '🗑️' };
+      return [
+        `${statusEmoji[newStatus ?? oldStatus] ?? '📋'} **Roadmap updated** \`${itemId}\``,
+        ``,
+        `  Title:  ${item.title}`,
+        oldStatus !== newStatus ? `  Status: ${oldStatus} → ${newStatus}` : `  Status: ${item.status}`,
+        newNotes ? `  Notes:  ${newNotes}` : '',
+      ].filter(Boolean).join('\n');
+    }
+
+    case 'roadmap_list': {
+      const {
+        instance_id: rid,
+        status: filterStatus = 'open',
+        tag: filterTag,
+        milestone: filterMilestone,
+        priority: filterPriority,
+      } = args as {
+        instance_id: string; status?: string; tag?: string;
+        milestone?: string; priority?: string;
+      };
+      const redis = await getConnection(rid);
+      const all = await redis.hgetall(`cachly:roadmap:${rid}`);
+      if (!all || Object.keys(all).length === 0) {
+        return '📋 **Roadmap is empty.**\n\nUse `roadmap_add` to create your first item.';
+      }
+      const PRIORITY_ORDER: Record<string, number> = { critical: 0, high: 1, medium: 2, low: 3 };
+      const PRIORITY_ICON: Record<string, string> = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
+      const STATUS_ICON: Record<string, string> = { planned: '📋', 'in-progress': '⚡', done: '✅', blocked: '🚫', cancelled: '🗑️' };
+      const openStatuses = new Set(['planned', 'in-progress', 'blocked']);
+      let items = Object.values(all).map(v => JSON.parse(v as string) as Record<string, string | string[]>);
+      // Filter
+      if (filterStatus === 'open') items = items.filter(i => openStatuses.has(i.status as string));
+      else if (filterStatus) items = items.filter(i => i.status === filterStatus);
+      if (filterTag) items = items.filter(i => (i.tags as string[]).includes(filterTag));
+      if (filterMilestone) items = items.filter(i => i.milestone === filterMilestone);
+      if (filterPriority) items = items.filter(i => (PRIORITY_ORDER[i.priority as string] ?? 99) <= (PRIORITY_ORDER[filterPriority] ?? 99));
+      // Sort: priority asc, then created asc
+      items.sort((a, b) => {
+        const pa = PRIORITY_ORDER[a.priority as string] ?? 99;
+        const pb = PRIORITY_ORDER[b.priority as string] ?? 99;
+        return pa !== pb ? pa - pb : (a.created as string).localeCompare(b.created as string);
+      });
+      if (items.length === 0) return `📋 **No roadmap items** match the current filter (status: ${filterStatus}).`;
+      const grouped: Record<string, typeof items> = {};
+      for (const it of items) {
+        const st = it.status as string;
+        if (!grouped[st]) grouped[st] = [];
+        grouped[st].push(it);
+      }
+      const lines: string[] = [`📋 **Roadmap** (${items.length} item${items.length !== 1 ? 's' : ''})`, ''];
+      for (const [st, grp] of Object.entries(grouped)) {
+        lines.push(`**${STATUS_ICON[st] ?? '•'} ${st.toUpperCase()}** (${grp.length})`);
+        for (const it of grp) {
+          const tags = (it.tags as string[]).length ? ` [${(it.tags as string[]).join(', ')}]` : '';
+          const milestone = it.milestone ? ` · ${it.milestone}` : '';
+          lines.push(`  ${PRIORITY_ICON[it.priority as string] ?? '⚪'} \`${it.id}\` **${it.title}**${tags}${milestone}`);
+          if (it.description) lines.push(`      ${(it.description as string).slice(0, 120)}`);
+          if (it.notes) lines.push(`      📝 ${(it.notes as string).split('\n').pop()?.slice(0, 100)}`);
+        }
+        lines.push('');
+      }
+      lines.push(`💡 \`roadmap_update(id, status: "in-progress")\` to start · \`roadmap_next\` for top priority item`);
+      return lines.join('\n');
+    }
+
+    case 'roadmap_next': {
+      const { instance_id: rid, tag: filterTag } = args as { instance_id: string; tag?: string };
+      const redis = await getConnection(rid);
+      const all = await redis.hgetall(`cachly:roadmap:${rid}`);
+      if (!all || Object.keys(all).length === 0) {
+        return '📋 **Roadmap is empty.** Use `roadmap_add` to plan your first task.';
+      }
+      const PRIORITY_ORDER: Record<string, number> = { critical: 0, high: 1, medium: 2, low: 3 };
+      const PRIORITY_ICON: Record<string, string> = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
+      let items = Object.values(all)
+        .map(v => JSON.parse(v as string) as Record<string, unknown>)
+        .filter(i => i.status === 'in-progress' || i.status === 'planned')
+        .filter(i => !filterTag || (i.tags as string[]).includes(filterTag));
+      if (items.length === 0) return '🎉 **No open roadmap items!** All tasks are done (or use `roadmap_list` to check).';
+      // in-progress first, then by priority
+      items.sort((a, b) => {
+        if (a.status === 'in-progress' && b.status !== 'in-progress') return -1;
+        if (b.status === 'in-progress' && a.status !== 'in-progress') return 1;
+        return (PRIORITY_ORDER[a.priority as string] ?? 99) - (PRIORITY_ORDER[b.priority as string] ?? 99);
+      });
+      const next = items[0];
+      const remaining = items.length - 1;
+      const tags = (next.tags as string[]).length ? `\nTags:      ${(next.tags as string[]).join(', ')}` : '';
+      const milestone = next.milestone ? `\nMilestone: ${next.milestone}` : '';
+      const notes = next.notes ? `\nNotes:     ${(next.notes as string).split('\n').pop()?.slice(0, 120)}` : '';
+      return [
+        `${next.status === 'in-progress' ? '⚡' : '📋'} **Next up: ${next.title}**`,
+        ``,
+        `ID:        \`${next.id}\``,
+        `Priority:  ${PRIORITY_ICON[next.priority as string] ?? '⚪'} ${next.priority}`,
+        `Status:    ${next.status}`,
+        next.description ? `\nWhat to do:\n${next.description}` : '',
+        tags, milestone, notes,
+        ``,
+        remaining > 0 ? `(+${remaining} more open item${remaining !== 1 ? 's' : ''} in roadmap)` : '(last open item)',
+        ``,
+        next.status === 'planned'
+          ? `💡 Start with: \`roadmap_update(id: "${next.id}", status: "in-progress")\``
+          : `💡 Finish with: \`roadmap_update(id: "${next.id}", status: "done", notes: "...")\``,
+      ].filter(s => s !== undefined).join('\n');
+    }
+
     default:
       return null;
   }
@@ -4340,14 +5997,81 @@ async function handleBulkLockStream(name: string, args: Record<string, unknown>)
 // ── Server setup ──────────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'cachly-mcp', version: '0.4.0' },
+  { name: 'cachly-mcp', version: CURRENT_VERSION },
   { capabilities: { tools: {} } }
 );
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 
+// ── Auto-session management ───────────────────────────────────────────────────
+// Transparently starts a Brain session on the first tool call of a process
+// and saves a session_end summary on SIGTERM/exit so users never have to call
+// session_start/session_end manually.
+
+let _autoSessionInstanceId: string | null = null;
+let _autoSessionStarted = false;
+let _autoSessionToolCount = 0;
+
+async function autoStartSession(instanceId: string): Promise<void> {
+  if (_autoSessionStarted) return;
+  _autoSessionStarted = true;
+  _autoSessionInstanceId = instanceId;
+  try {
+    await handleTool('session_start', { instance_id: instanceId, focus: 'auto (MCP session)' });
+  } catch { /* non-fatal — session tracking is a best-effort feature */ }
+
+  // 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 {
+    await handleTool('session_end', {
+      instance_id: _autoSessionInstanceId,
+      summary: `Auto-ended after ${_autoSessionToolCount} tool call(s). Session was started automatically.`,
+      files_changed: [],
+      lessons_learned: 0,
+    });
+  } catch { /* non-fatal */ }
+}
+
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
+
+  // 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) {
+    const instanceId = (args as Record<string, unknown>)?.instance_id as string | undefined;
+    if (instanceId) {
+      await autoStartSession(instanceId).catch(() => undefined);
+    }
+  }
+  if (!sessionTools.has(name)) _autoSessionToolCount++;
+
   try {
     const text = await handleTool(name, (args ?? {}) as Record<string, unknown>);
     return { content: [{ type: 'text', text }] };
@@ -4357,8 +6081,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
-// Graceful shutdown – close all Redis connections
+// Graceful shutdown – close all Redis connections + auto-end brain session
 process.on('SIGTERM', async () => {
+  await autoEndSession().catch(() => undefined);
+  for (const [, client] of pool) await client.quit().catch(() => undefined);
+  process.exit(0);
+});
+
+process.on('SIGINT', async () => {
+  await autoEndSession().catch(() => undefined);
   for (const [, client] of pool) await client.quit().catch(() => undefined);
   process.exit(0);
 });
@@ -4379,6 +6110,8 @@ const EDITOR_FILES: Record<string, string> = {
   windsurf: '.windsurf/mcp.json',
   copilot:  '.vscode/mcp.json',
   continue: '.continue/config.json',
+  cline:    '.vscode/mcp.json',              // Cline respects VS Code project MCP config
+  zed:      '.zed/settings.json',            // Zed project-level context_servers
 };
 
 const CLAUDE_MD_MARKER_START = '<!-- cachly-brain-start -->';
@@ -4395,6 +6128,20 @@ function buildMcpConfig(apiKey: string, instanceId: string, editor: string): str
       },
     }, null, 2);
   }
+  if (editor === 'zed') {
+    return JSON.stringify({
+      context_servers: {
+        cachly: {
+          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: {},
+        },
+      },
+    }, null, 2);
+  }
   return JSON.stringify({
     mcpServers: {
       cachly: {
@@ -4408,48 +6155,54 @@ function buildMcpConfig(apiKey: string, instanceId: string, editor: string): str
 
 function buildClaudeMdBlock(instanceId: string): string {
   return `${CLAUDE_MD_MARKER_START}
-## Cachly AI Brain — Persistent Memory
+## Cachly AI Brain
 
-Your AI Brain instance ID: \`${instanceId}\`
+The Cachly MCP server is available as tool \`cachly\`.
+Your instance ID: \`${instanceId}\`
 
-> The Brain gives you persistent memory across sessions. Every lesson you learn,
-> every bug you fix, every architecture decision — recalled instantly next time.
-> instance_id is pre-filled below. Do NOT ask the user for it.
+> **Sessions are fully automatic** (MCP ≥ 0.5.3).
+> The Brain starts tracking when you call any tool for the first time and saves a summary when your editor closes. You never need to call \`session_start\` or \`session_end\` manually.
 
-### MANDATORY: Call at the START of every session
-\`\`\`
-session_start(instance_id="${instanceId}", focus="<what you're working on today>")
-\`\`\`
-This loads your previous context, recent lessons, and open tasks automatically.
+---
 
-### MANDATORY: Call at the END of every session
+### Before editing any file — WIP-registry (prevents half-finished code across sessions):
 \`\`\`
-session_end(instance_id="${instanceId}", summary="<2-3 sentences on what was done>", files_changed=["src/..."], lessons_learned=1)
+remember_context(
+  instance_id = "${instanceId}",
+  key         = "wip-registry",
+  content     = "EDITING: <file:line> — goal: <what you are implementing>",
+  category    = "bug",
+  ttl         = 86400,
+)
 \`\`\`
+After the edit is complete, update \`content\` to \`"DONE: <file> — <what was completed>"\`.
 
-### After fixing ANY bug or solving a hard problem
+### After fixing any bug or solving a tricky problem:
 \`\`\`
 learn_from_attempts(
-  instance_id="${instanceId}",
-  topic="category:keyword",   # e.g. "deploy:web", "bug:redis-timeout", "arch:auth"
-  outcome="success",
-  what_worked="exact solution",
-  what_failed="what didn't work (optional)",
-  commands=["the command that worked"],
-  file_paths=["relevant/file.ts"],
-  severity="critical"|"major"|"minor",
+  instance_id = "${instanceId}",
+  topic       = "category:keyword",
+  outcome     = "success",
+  what_worked = "...",
+  what_failed = "...",
+  severity    = "critical" | "major" | "minor",
+  file_paths  = ["path/to/file"],
+  commands    = ["the command that worked"],
+  tags        = ["tag1"],
 )
 \`\`\`
 
-### Before starting any non-trivial task
+### Before starting any task — recall relevant lessons first:
 \`\`\`
-recall_best_solution(instance_id="${instanceId}", topic="relevant:topic")
+smart_recall(
+  instance_id = "${instanceId}",
+  query       = "<describe what you are about to do>",
+)
 \`\`\`
 
-### If a stored lesson is wrong
-\`\`\`
-forget_lesson(instance_id="${instanceId}", topic="wrong:topic")
-\`\`\`
+### Half-finished code rule:
+Never commit code that does not compile. Run \`tsc --noEmit\` / \`go build ./...\` before every commit.
+If a session ends mid-task, save the WIP-registry entry so the next session picks up exactly where you left off.
 ${CLAUDE_MD_MARKER_END}`;
 }
 
@@ -4540,8 +6293,9 @@ if (process.argv[2] === 'setup') {
     const AUTH_BASE = 'https://auth.cachly.dev/realms/cachly/protocol/openid-connect';
     const CLIENT_ID = 'cachly-cli';
 
-    console.log('Step 1: Sign in to cachly (free — no credit card required)\n');
+    console.log('Step 1: Sign in to cachly (free, no credit card)\n');
 
+    // Start device flow
     let deviceCode = '', userCode = '', verifyUri = '', pollInterval = 5000;
     try {
       const deviceRes = await fetch(`${AUTH_BASE}/auth/device`, {
@@ -4549,92 +6303,91 @@ if (process.argv[2] === 'setup') {
         headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
         body: `client_id=${CLIENT_ID}&scope=openid`,
       });
-      if (!deviceRes.ok) throw new Error(`HTTP ${deviceRes.status}`);
+      if (!deviceRes.ok) throw new Error(`Device flow error: HTTP ${deviceRes.status}`);
       const data = await deviceRes.json() as {
         device_code: string; user_code: string;
         verification_uri_complete: string; interval: number;
       };
-      deviceCode   = data.device_code;
-      userCode     = data.user_code;
-      verifyUri    = data.verification_uri_complete;
-      pollInterval = (data.interval ?? 5) * 1000;
+      deviceCode    = data.device_code;
+      userCode      = data.user_code;
+      verifyUri     = data.verification_uri_complete;
+      pollInterval  = (data.interval ?? 5) * 1000;
     } catch (e) {
-      console.error(`\nCould not reach auth service: ${(e as Error).message}`);
-      console.error('Fallback: sign in at https://cachly.dev and paste your API token.\n');
+      console.error(`\nFailed to start device flow: ${(e as Error).message}`);
+      console.error('Falling back: sign in at https://cachly.dev/setup-ai and paste your API token.\n');
       token = await ask('   Paste API token (cky_live_...): ');
-      if (!token) { console.error('\nToken required. Aborting.\n'); rl.close(); process.exit(1); }
-      deviceCode = '';
+      if (!token) { console.error('\nToken is required. Aborting.\n'); rl.close(); process.exit(1); }
+      console.log('');
+      deviceCode = ''; // mark as fallback so we skip polling
     }
 
-    if (deviceCode) {
-      console.log(`   Code: \x1b[1;33m${userCode}\x1b[0m`);
-      console.log(`   URL:  ${verifyUri}\n`);
+    if (deviceCode!) {
+      // Open browser
+      console.log(`   Code: \x1b[1;33m${userCode!}\x1b[0m`);
+      console.log(`   URL:  ${verifyUri!}\n`);
       try {
         const { execSync } = await import('node:child_process');
         const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-        execSync(`${openCmd} "${verifyUri}"`, { stdio: 'ignore' });
+        execSync(`${openCmd} "${verifyUri!}"`, { stdio: 'ignore' });
         console.log('   ✓  Browser opened — confirm the code above to continue...\n');
       } catch {
-        console.log('   👉  Open the URL above in your browser and confirm the code.\n');
+        console.log('   👉  Open the URL above in your browser and enter the code.\n');
       }
 
+      // Poll for token
       process.stdout.write('   Waiting for authorization');
-      const deadline = Date.now() + 10 * 60 * 1000;
+      const deadline = Date.now() + 10 * 60 * 1000; // 10 min
       while (Date.now() < deadline) {
-        await new Promise(r => setTimeout(r, pollInterval));
+        await new Promise(r => setTimeout(r, pollInterval!));
         process.stdout.write('.');
         try {
           const tokenRes = await fetch(`${AUTH_BASE}/token`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-            body: `client_id=${CLIENT_ID}&grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=${deviceCode}`,
+            body: `client_id=${CLIENT_ID}&grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=${deviceCode!}`,
           });
-          const td = await tokenRes.json() as { access_token?: string; error?: string };
-          if (td.access_token) {
-            token = td.access_token;
+          const tokenData = await tokenRes.json() as { access_token?: string; error?: string };
+          if (tokenData.access_token) {
+            token = tokenData.access_token;
             console.log(' \x1b[32m✓ Authorized!\x1b[0m\n');
             break;
           }
-          if (td.error === 'slow_down') pollInterval = Math.min(pollInterval + 2000, 15000);
-          else if (td.error && td.error !== 'authorization_pending') {
-            console.error(`\nAuth error: ${td.error}. Aborting.\n`);
+          // authorization_pending = keep polling; slow_down = increase interval
+          if (tokenData.error === 'slow_down') pollInterval = Math.min(pollInterval! + 2000, 15000);
+          else if (tokenData.error && tokenData.error !== 'authorization_pending') {
+            console.error(`\nAuth error: ${tokenData.error}. Aborting.\n`);
             rl.close(); process.exit(1);
           }
         } catch { /* network hiccup — keep polling */ }
       }
-      if (!token) { console.error('\nTimed out. Aborting.\n'); rl.close(); process.exit(1); }
+      if (!token) { console.error('\nTimed out waiting for authorization. Aborting.\n'); rl.close(); process.exit(1); }
+      console.log('');
     }
+  }
 
-    // Exchange short-lived Keycloak JWT → long-lived cky_live_ API key
-    if (token.startsWith('eyJ')) {
-      process.stdout.write('⏳ Generating your API key...');
-      try {
-        const keyRes = await fetch(`${API_URL}/api/v1/api-keys`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
-          body: JSON.stringify({ name: 'cachly-mcp-setup', scope: 'read_write' }),
-        });
-        if (!keyRes.ok) throw new Error(`HTTP ${keyRes.status}`);
-        const keyBody = await keyRes.json() as { key?: string };
-        if (keyBody.key) { token = keyBody.key; console.log(' ✓\n'); }
-        else throw new Error('no key in response');
-      } catch (e) {
-        console.log(` (skipped — JWT will be used directly)\n`);
-      }
+  // ── Step 1b: Exchange Keycloak JWT → long-lived cky_live_ API key ──────────
+  // Only do this when the token looks like a Keycloak JWT (starts with "eyJ"),
+  // not when the user already pasted a cky_live_ key directly.
+  if (token.startsWith('eyJ')) {
+    process.stdout.write('⏳ Generating your API key...');
+    try {
+      const keyRes = await fetch(`${API_URL}/api/v1/api-keys`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ name: 'cachly-mcp-setup', scope: 'read_write' }),
+      });
+      if (!keyRes.ok) throw new Error(`HTTP ${keyRes.status}`);
+      const keyBody = await keyRes.json() as { key: string };
+      if (!keyBody.key) throw new Error('no key in response');
+      token = keyBody.key; // swap JWT → cky_live_...
+      console.log(' ✓\n');
+    } catch (e) {
+      console.log(' (skipped)\n');
+      // Non-fatal: fall back to using the Keycloak JWT directly.
+      // It will expire but setup still works for now.
     }
   }
 
-  // ── Step 1b: Auto-provision a Brain instance if none exist ─────────────────
-  // POST /api/v1/instances/auto is idempotent — returns existing or creates free Brain
-  let autoProvisioned = false;
-  try {
-    const autoRes = await fetch(`${API_URL}/api/v1/instances/auto`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
-    });
-    if (autoRes.ok) autoProvisioned = true;
-  } catch { /* non-fatal */ }
-
   // ── Step 2: Fetch & pick instance ─────────────────────────────────────────
   process.stdout.write('⏳ Fetching your instances...');
   let instances: Array<{ id: string; name: string; status: string; tier: string; region: string }> = [];
@@ -4646,31 +6399,62 @@ if (process.argv[2] === 'setup') {
     const body = await res.json() as { data: typeof instances };
     instances = (body.data ?? []).filter(i => i.status === 'running');
   } catch (e) {
-    console.error(`\n\nFailed to fetch instances: ${(e as Error).message}`);
-    console.error('Check your token and try again.\n');
+    const msg = (e as Error).message;
+    console.error(`\n\nFailed to fetch instances: ${msg}`);
+    if (msg.includes('401')) {
+      console.error('Token rejected. Get a valid token at https://cachly.dev/setup-ai\n');
+      try {
+        const { execSync } = await import('node:child_process');
+        const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+        execSync(`${openCmd} https://cachly.dev/setup-ai`, { stdio: 'ignore' });
+      } catch { /* ignore */ }
+    }
     rl.close(); process.exit(1);
   }
   console.log(` found ${instances.length}\n`);
 
   if (instances.length === 0) {
-    if (autoProvisioned) {
-      // Poll up to 10× every 3s (30s total) waiting for the Brain to start
-      process.stdout.write(' waiting for Brain to start');
-      for (let attempt = 0; attempt < 10 && instances.length === 0; attempt++) {
-        await new Promise(r => setTimeout(r, 3000));
-        process.stdout.write('.');
-        try {
-          const retry = await fetch(`${API_URL}/api/v1/instances`, { headers: { Authorization: `Bearer ${token}` } });
-          if (retry.ok) {
-            const b = await retry.json() as { data: typeof instances };
-            instances = (b.data ?? []).filter(i => i.status === 'running');
-          }
-        } catch { /* ignore */ }
+    // Auto-provision a free Brain instance so users don't have to visit the website.
+    process.stdout.write('⏳ Creating your free Brain instance...');
+    try {
+      const autoRes = await fetch(`${API_URL}/api/v1/instances/auto`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      });
+      if (!autoRes.ok) throw new Error(`HTTP ${autoRes.status}`);
+      const autoBody = await autoRes.json() as { instance?: { id: string; name: string; status: string; tier: string; region: string }; instance_id?: string; status?: string; created?: boolean };
+      if (autoBody.instance) {
+        // Returned an existing instance.
+        instances = [autoBody.instance];
+      } else if (autoBody.instance_id) {
+        // Newly created — poll until running or give up after 30 s.
+        const newId = autoBody.instance_id;
+        console.log(` ✓ created (${newId.slice(0, 8)}…)\n`);
+        process.stdout.write('⏳ Waiting for instance to start');
+        for (let attempt = 0; attempt < 15; attempt++) {
+          await new Promise(r => setTimeout(r, 2000));
+          process.stdout.write('.');
+          try {
+            const checkRes = await fetch(`${API_URL}/api/v1/instances/${newId}`, { headers: { Authorization: `Bearer ${token}` } });
+            if (checkRes.ok) {
+              const inst = await checkRes.json() as { id: string; name: string; status: string; tier: string; region: string };
+              if (inst.status === 'running') { instances = [inst]; break; }
+            }
+          } catch { /* keep polling */ }
+        }
+        console.log('');
       }
-      process.stdout.write(instances.length > 0 ? ' ready!\n' : '\n');
+    } catch (e) {
+      console.log(` failed: ${(e as Error).message}\n`);
     }
+
     if (instances.length === 0) {
-      console.error('\nBrain provisioning is taking longer than expected. Run setup again in a minute.\n');
+      console.error('\nCould not create an instance automatically. Opening https://cachly.dev/instances …\n');
+      try {
+        const { execSync } = await import('node:child_process');
+        const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+        execSync(`${openCmd} https://cachly.dev/instances`, { stdio: 'ignore' });
+      } catch { /* ignore */ }
       rl.close(); process.exit(1);
     }
   }
@@ -4690,15 +6474,28 @@ if (process.argv[2] === 'setup') {
   // ── Step 3: Detect editors ────────────────────────────────────────────────
   const cwd = process.cwd();
   const detected: string[] = [];
+  const { homedir } = await import('node:os');
+  const home = homedir();
   // Claude Code: always include (CLAUDE.md is universal)
   detected.push('claude');
   if (existsSync(resolve(cwd, '.cursor')))   detected.push('cursor');
   if (existsSync(resolve(cwd, '.windsurf'))) detected.push('windsurf');
   if (existsSync(resolve(cwd, '.vscode')))   detected.push('copilot');
   if (existsSync(resolve(cwd, '.continue'))) detected.push('continue');
+  // Cline: VS Code extension — detect via globalStorage on the machine
+  const clineGlobalDir = process.platform === 'darwin'
+    ? resolve(home, 'Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev')
+    : resolve(home, '.vscode/extensions');
+  if (existsSync(clineGlobalDir) && !detected.includes('copilot')) detected.push('cline');
+  else if (existsSync(clineGlobalDir)) detected.push('cline'); // both copilot + cline share .vscode/mcp.json — fine
+  // Zed editor — detect via app data dir
+  const zedDir = process.platform === 'darwin'
+    ? resolve(home, 'Library/Application Support/Zed')
+    : resolve(home, '.config/zed');
+  if (existsSync(zedDir)) detected.push('zed');
 
   const editorLabel = (e: string) =>
-    ({ claude: 'Claude Code', cursor: 'Cursor', windsurf: 'Windsurf', copilot: 'GitHub Copilot', continue: 'Continue.dev' })[e] ?? e;
+    ({ claude: 'Claude Code', cursor: 'Cursor', windsurf: 'Windsurf', copilot: 'GitHub Copilot', continue: 'Continue.dev', cline: 'Cline (VSCode)', zed: 'Zed' })[e] ?? e;
 
   console.log(`Step 3: Detected editors: ${detected.map(editorLabel).join(', ')}`);
   const editorsRaw = await ask(`   Configure for which? [all / ${detected.join('/')}] (Enter = all): `);
@@ -4707,7 +6504,21 @@ if (process.argv[2] === 'setup') {
     : editorsRaw.split(/[,\s]+/).map(s => s.toLowerCase()).filter(s => EDITOR_FILES[s]);
   console.log('');
 
-  // ── Step 4: Write editor configs ──────────────────────────────────────────
+  // ── Step 4: Email opt-in ──────────────────────────────────────────────────
+  console.log('Step 4: Stay in the loop (optional)');
+  const email = await ask('   Email for release notes & tips? [Enter to skip]: ');
+  if (email && email.includes('@')) {
+    try {
+      await fetch(`${API_URL}/api/newsletter/subscribe`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email: email.trim().toLowerCase(), source: 'mcp-setup' }),
+        signal: AbortSignal.timeout(5000),
+      });
+      console.log('✅ Subscribed — you\'ll only hear from us when it matters.\n');
+    } catch { console.log('⚠️  Could not subscribe (no internet?). Continuing...\n'); }
+  } else { console.log('   Skipped.\n'); }
+
+  // ── Step 5: Write editor configs ──────────────────────────────────────────
   for (const editor of editorsToSetup) {
     const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
     const configPath = resolve(cwd, configFile);
@@ -4716,7 +6527,7 @@ if (process.argv[2] === 'setup') {
     console.log(`✅ Written: ${configFile}`);
   }
 
-  // ── Step 5: CLAUDE.md (always — idempotent) ───────────────────────────────
+  // ── Step 6: CLAUDE.md (always — idempotent) ───────────────────────────────
   const mdResult = await writeClaudeMd(cwd, instance.id);
   const mdLabel = mdResult === 'updated' ? '✅ Updated' : mdResult === 'appended' ? '✅ Appended to' : '✅ Written';
   console.log(`${mdLabel}: CLAUDE.md`);
@@ -4724,162 +6535,172 @@ if (process.argv[2] === 'setup') {
   rl.close();
   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`);
+
+  // ── Step 7: Show first session_start preview (Aha moment) ────────────────
+  // Fetch brain health from the API to show the user what their agent will see.
+  process.stdout.write('\n⏳ Fetching your Brain health preview...');
+  try {
+    const brainRes = await fetch(`${API_URL}/api/v1/instances/${instance.id}/brain/stats`, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(6000),
+    });
+    if (brainRes.ok) {
+      const brainData = await brainRes.json() as {
+        lesson_count?: number; context_count?: number;
+        open_failures?: number; quality_score?: number;
+      };
+      const lessons = brainData.lesson_count ?? 0;
+      const contexts = brainData.context_count ?? 0;
+      const score = brainData.quality_score ?? 0;
+      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(' ✓\n');
+      console.log('┌──────────────────────────────────────────────────────┐');
+      console.log(`│  🧠  Brain Health Report                            │`);
+      console.log('├──────────────────────────────────────────────────────┤');
+      console.log(`│  Lessons stored    : ${String(lessons).padEnd(6)} │  Level: ${level.padEnd(20)}│`);
+      console.log(`│  Context entries   : ${String(contexts).padEnd(6)} │  Quality score: ${String(Math.round(score * 100)).padEnd(3)}%       │`);
+      if (lessons === 0) {
+        console.log('├──────────────────────────────────────────────────────┤');
+        console.log('│  Your Brain is empty and ready to learn.            │');
+        console.log('│  After your first coding session it will contain:   │');
+        console.log('│    • Lessons from every bug you fixed               │');
+        console.log('│    • Your project\'s indexed files                   │');
+        console.log('│    • A session summary for next time                │');
+      }
+      console.log('└──────────────────────────────────────────────────────┘');
+    } else {
+      console.log(' (skipped)');
+    }
+  } catch { console.log(' (skipped)'); }
+
+  console.log(`\n   Your AI will call session_start automatically when it uses the first tool.`);
+  console.log(`   To see your Brain at any time: https://cachly.dev/instances/${instance.id}\n`);
   process.exit(0);
 }
 
-// ── CLI: cachly join <token> (team invite — zero friction) ────────────────────
-// Usage: npx @cachly-dev/mcp-server join <token>
-//
-// Connects the user to a shared Brain instance via an invite link.
-// Flow: resolve token → show instance info → Device Code auth → write configs.
+// ── CLI: cachly index <dir> ───────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest index [./path/to/project]
+// Indexes the project directory into the Brain — perfect for CI/CD cron jobs.
 
-if (process.argv[2] === 'join') {
-  const { writeFile, mkdir } = await import('node:fs/promises');
-  const { existsSync } = await import('node:fs');
-  const { resolve, dirname } = await import('node:path');
+if (process.argv[2] === 'index') {
+  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 inviteToken = process.argv[3] ?? '';
-  if (!inviteToken) {
-    console.error('\n❌  Usage: npx @cachly-dev/mcp-server@latest join <token>\n');
-    console.error('   Get a token from a teammate: invite_link() in their AI assistant.\n');
+  const dir        = resolve(flag('dir') ?? argv.find(a => !a.startsWith('--')) ?? '.');
+  const instanceId = flag('instance-id') ?? process.env.CACHLY_BRAIN_INSTANCE_ID;
+  const maxFiles   = parseInt(flag('max-files') ?? '500', 10);
+  const namespace  = flag('namespace') ?? 'cachly:sem:code';
+
+  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 index ./my-project\n');
     process.exit(1);
   }
 
-  console.log('\n🧠  cachly AI Brain — Team Join');
-  console.log('──────────────────────────────────\n');
+  console.log(`\n📂  Indexing: ${dir}`);
+  console.log(`    Instance: ${instanceId.slice(0, 8)}…  Max files: ${maxFiles}\n`);
 
-  // Step 1: Resolve the invite token (public, no auth)
-  process.stdout.write('⏳ Resolving invite...');
-  let instanceId = '', instanceName = '', instanceTier = '';
   try {
-    const infoRes = await fetch(`${API_URL}/api/invite/${inviteToken}`, {
-      signal: AbortSignal.timeout(10000),
+    const result = await handleTool('index_project', {
+      instance_id: instanceId,
+      dir,
+      max_files: maxFiles,
+      ttl: 86400 * 7,
+      namespace,
     });
-    if (!infoRes.ok) {
-      console.error(`\n\n❌  Invite not found or expired (HTTP ${infoRes.status}).`);
-      console.error('    Ask your teammate to generate a new one with: invite_link()\n');
-      process.exit(1);
-    }
-    const info = await infoRes.json() as { instance_id: string; instance_name: string; tier: string; label?: string };
-    instanceId   = info.instance_id;
-    instanceName = info.instance_name;
-    instanceTier = info.tier ?? 'free';
-    console.log(` ✓\n`);
-    const label = info.label ? ` ("${info.label}")` : '';
-    console.log(`   Brain instance: \x1b[1m${instanceName}\x1b[0m${label} [${instanceTier}]`);
-    console.log(`   Instance ID:    ${instanceId}\n`);
-  } catch (e) {
-    console.error(`\n\n❌  Could not reach API: ${(e as Error).message}\n`);
+    console.log(result);
+    console.log('\n✅  Indexing complete.\n');
+  } catch (err) {
+    console.error(`\n❌  Indexing failed: ${(err as Error).message}\n`);
     process.exit(1);
   }
+  process.exit(0);
+}
 
-  // Step 2: Authenticate via Device Code Flow
-  const AUTH_BASE = 'https://auth.cachly.dev/realms/cachly/protocol/openid-connect';
-  const CLIENT_ID = 'cachly-cli';
-
-  console.log('Step 1: Sign in to cachly (your own account — free, no credit card)\n');
+// ── Start ─────────────────────────────────────────────────────────────────────
 
-  let token = process.env.CACHLY_JWT ?? '';
-  if (token) {
-    console.log('✓  Using token from CACHLY_JWT env var\n');
-  } else {
-    let deviceCode = '', userCode = '', verifyUri = '', pollInterval = 5000;
-    try {
-      const deviceRes = await fetch(`${AUTH_BASE}/auth/device`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: `client_id=${CLIENT_ID}&scope=openid`,
-        signal: AbortSignal.timeout(10000),
-      });
-      if (!deviceRes.ok) throw new Error(`HTTP ${deviceRes.status}`);
-      const data = await deviceRes.json() as {
-        device_code: string; user_code: string;
-        verification_uri_complete: string; interval: number;
-      };
-      deviceCode   = data.device_code;
-      userCode     = data.user_code;
-      verifyUri    = data.verification_uri_complete;
-      pollInterval = (data.interval ?? 5) * 1000;
-    } catch (e) {
-      console.error(`\n❌  Auth service unreachable: ${(e as Error).message}`);
-      process.exit(1);
-    }
+// 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(
+    '\n' +
+    '╔══════════════════════════════════════════════════════════════════╗\n' +
+    '║  🧠  cachly AI Brain — Setup required                           ║\n' +
+    '╠══════════════════════════════════════════════════════════════════╣\n' +
+    '║                                                                  ║\n' +
+    '║  CACHLY_JWT is not set. Get your free credentials at:           ║\n' +
+    '║                                                                  ║\n' +
+    '║    👉  https://cachly.dev/setup-ai                              ║\n' +
+    '║                                                                  ║\n' +
+    '║  Then run the interactive setup wizard:                         ║\n' +
+    '║                                                                  ║\n' +
+    '║    npx @cachly-dev/mcp-server@latest setup                      ║\n' +
+    '║                                                                  ║\n' +
+    '║  Free tier — no credit card required.                           ║\n' +
+    '╚══════════════════════════════════════════════════════════════════╝\n' +
+    '\n',
+  );
+}
 
-    console.log(`   Code: \x1b[1;33m${userCode}\x1b[0m`);
-    console.log(`   URL:  ${verifyUri}\n`);
+// ── Update nudge (non-blocking, fire-and-forget) ─────────────────────────────
+// Check npm registry once per process start; if outdated, log to stderr so
+// the editor's MCP log shows an actionable one-liner. Skipped if opted out.
+if (!process.env.CACHLY_NO_UPDATE_CHECK) {
+  (async () => {
     try {
-      const { execSync } = await import('node:child_process');
-      const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-      execSync(`${openCmd} "${verifyUri}"`, { stdio: 'ignore' });
-      console.log('   ✓  Browser opened — confirm the code above to continue...\n');
-    } catch {
-      console.log('   👉  Open the URL above in your browser and confirm the code.\n');
-    }
-
-    process.stdout.write('   Waiting for authorization');
-    const deadline = Date.now() + 10 * 60 * 1000;
-    while (Date.now() < deadline) {
-      await new Promise(r => setTimeout(r, pollInterval));
-      process.stdout.write('.');
-      try {
-        const td = await (await fetch(`${AUTH_BASE}/token`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-          body: `client_id=${CLIENT_ID}&grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=${deviceCode}`,
-        })).json() as { access_token?: string; error?: string };
-        if (td.access_token) { token = td.access_token; console.log(' \x1b[32m✓ Authorized!\x1b[0m\n'); break; }
-        if (td.error === 'slow_down') pollInterval = Math.min(pollInterval + 2000, 15000);
-        else if (td.error && td.error !== 'authorization_pending') {
-          console.error(`\n\n❌  Auth error: ${td.error}\n`); process.exit(1);
+      const res = await fetch(
+        `https://registry.npmjs.org/@cachly-dev/mcp-server/latest`,
+        { signal: AbortSignal.timeout(4000) },
+      );
+      if (res.ok) {
+        const data = await res.json() as { version: string };
+        const latest = data?.version ?? '';
+        if (latest && latest !== CURRENT_VERSION) {
+          process.stderr.write(
+            `\n⚡ cachly update available: ${CURRENT_VERSION} → ${latest}\n` +
+            `   Run: npx @cachly-dev/mcp-server@latest setup\n\n`,
+          );
         }
-      } catch { /* hiccup — keep polling */ }
-    }
-    if (!token) { console.error('\n\n❌  Timed out. Run the command again.\n'); process.exit(1); }
+      }
+    } catch { /* ignore – network unavailable or timeout */ }
+  })();
+}
 
-    // Exchange Keycloak JWT → long-lived cky_live_ API key
-    if (token.startsWith('eyJ')) {
-      process.stdout.write('⏳ Generating your API key...');
-      try {
-        const keyBody = await (await fetch(`${API_URL}/api/v1/api-keys`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
-          body: JSON.stringify({ name: 'cachly-mcp-join', scope: 'read_write' }),
-        })).json() as { key?: string };
-        if (keyBody.key) { token = keyBody.key; console.log(' ✓\n'); }
-        else throw new Error('no key in response');
-      } catch { console.log(' (skipped — JWT used directly)\n'); }
+const httpPort = process.env.PORT ? parseInt(process.env.PORT, 10) : undefined;
+
+if (httpPort) {
+  // ── HTTP mode (Streamable HTTP transport) ───────────────────────────────
+  // Used for Smithery URL deployment: PORT=3000 node dist/index.js
+  const { createServer } = await import('node:http');
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+  await server.connect(transport);
+  const httpServer = createServer((req, res) => {
+    const url = new URL(req.url ?? '/', `http://localhost:${httpPort}`);
+    if (url.pathname === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ok', version: CURRENT_VERSION }));
+      return;
     }
-  }
-
-  // Step 3: Detect editors and write configs
-  const cwd = process.cwd();
-  const detected: string[] = ['claude'];
-  if (existsSync(resolve(cwd, '.cursor')))   detected.push('cursor');
-  if (existsSync(resolve(cwd, '.windsurf'))) detected.push('windsurf');
-  if (existsSync(resolve(cwd, '.vscode')))   detected.push('copilot');
-  if (existsSync(resolve(cwd, '.continue'))) detected.push('continue');
-
-  console.log(`Step 2: Writing configs for: ${detected.join(', ')}\n`);
-
-  for (const editor of detected) {
-    const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
-    const configPath = resolve(cwd, configFile);
-    await mkdir(dirname(configPath), { recursive: true });
-    await writeFile(configPath, buildMcpConfig(token, instanceId, editor), 'utf-8');
-    console.log(`✅ Written: ${configFile}`);
-  }
-
-  const mdResult = await writeClaudeMd(cwd, instanceId);
-  const mdLabel = mdResult === 'updated' ? '✅ Updated' : mdResult === 'appended' ? '✅ Appended to' : '✅ Written';
-  console.log(`${mdLabel}: CLAUDE.md`);
-
-  console.log(`\n🧠  Joined! You're now connected to "${instanceName}".`);
-  console.log(`    Restart your editor — all ${instanceName} lessons are now available via session_start.\n`);
-  process.exit(0);
+    if (url.pathname === '/mcp' || url.pathname === '/') {
+      transport.handleRequest(req, res);
+      return;
+    }
+    res.writeHead(404);
+    res.end('not found');
+  });
+  httpServer.listen(httpPort, () => {
+    process.stderr.write(`cachly-mcp HTTP server listening on :${httpPort}\n`);
+  });
+} else {
+  // ── stdio mode (default for local editor use) ───────────────────────────
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
 }
 
-// ── Start ─────────────────────────────────────────────────────────────────────
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-