@cachly-dev/mcp-server 0.5.42 → 0.5.44

package/dist/index.js

@@ -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.42
+ * 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,20 +34,20 @@ 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)
  */
 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, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
 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                  │
@@ -63,6 +66,43 @@ 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) {
+    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, ageDays) {
+    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 = {
+    '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) {
+    return createHash('md5').update(text).digest('hex').slice(0, 12);
+}
 function detectEmbedProvider() {
     // Client-side keys first (direct, fast, no server roundtrip)
     if (process.env.OPENAI_API_KEY)
@@ -248,12 +288,17 @@ function embedProviderHint() {
 //   • 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([
@@ -327,14 +372,443 @@ 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 = [
+    // 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(KATA_ROMAJI_TABLE);
+/**
+ * Convert a katakana string to Hepburn romaji.
+ * Handles digraphs, geminate consonants (ッ), and long vowel marks (ー).
+ */
+function katakanaToRomaji(kata) {
+    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) {
+    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([
+    // 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) {
+    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) {
-    return text
-        .toLowerCase()
-        .replace(/[^a-záàâãäåæçéèêëíìîïñóòôõöúùûüýÿßœ0-9:_\-./]/g, ' ')
-        .split(/\s+/)
-        .filter(w => w.length > 1 && !STOPWORDS.has(w));
+    const tokens = [];
+    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 = [];
+    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;
 }
 /**
  * Split a multi-topic query into sub-queries.
@@ -607,27 +1081,13 @@ async function keywordSearch(redis, patterns, query, topK = 10) {
     return sorted.slice(0, topK);
 }
 // ── Exported for testing ──────────────────────────────────────────────────────
-export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp, STOPWORDS };
+export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp, STOPWORDS, katakanaToRomaji, arabicLightStem, expandCrossLingual, CROSS_LINGUAL_MAP };
 // ── 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();
-const POOL_MAX = 20;
 async function getConnection(instance_id) {
-    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(`/api/v1/instances/${instance_id}`);
     if (inst.status !== 'running') {
         throw new McpError(ErrorCode.InvalidRequest, `Instance "${inst.name}" is not running (status: ${inst.status}). ` +
@@ -680,27 +1140,13 @@ async function apiFetch(path, options = {}) {
     }
     const res = await fetch(`${API_URL}${path}`, {
         ...options,
-        signal: AbortSignal.timeout(15000),
         headers: {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${JWT}`,
             ...options.headers,
         },
-    }).catch((err) => {
-        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, `cachly API error ${res.status}: ${body.error ?? res.statusText}`);
     }
@@ -721,8 +1167,8 @@ const TOOLS = [
         name: 'create_instance',
         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: {
@@ -1078,10 +1524,10 @@ const TOOLS = [
     // ── Auth & API-Status ─────────────────────────────────────────────────────
     {
         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.',
+        description: '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) ────────────────────────────
@@ -1167,7 +1613,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',
@@ -1198,6 +1646,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'],
         },
@@ -1206,7 +1663,9 @@ const TOOLS = [
         name: 'recall_best_solution',
         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',
@@ -1217,33 +1676,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: 'Semantically search cached context using natural language. ' +
@@ -1264,7 +1696,8 @@ const TOOLS = [
         name: 'session_start',
         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',
@@ -1274,6 +1707,14 @@ 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.',
+                },
             },
             required: ['instance_id'],
         },
@@ -1283,7 +1724,8 @@ const TOOLS = [
         description: '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: {
@@ -1301,10 +1743,99 @@ 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',
@@ -1392,47 +1923,129 @@ const TOOLS = [
         },
     },
     {
-        name: 'brain_stats',
-        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.',
+        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: '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',
-        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.',
+        name: 'roadmap_list',
+        description: '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',
-        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>"',
+        name: 'roadmap_next',
+        description: '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'],
         },
@@ -1440,12 +2053,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'],
         },
@@ -1513,6 +2130,94 @@ 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',
@@ -1603,10 +2308,52 @@ function buildConnectionString(inst) {
     const pw = inst.password ? `:${inst.password}@` : '@';
     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) {
+    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, args) {
-    // 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
     const bulkResult = await handleBulkLockStream(name, args);
@@ -1625,7 +2372,7 @@ async function handleTool(name, args) {
             const { name: instName, tier } = args;
             const res = await apiFetch('/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 [
@@ -1682,6 +2429,63 @@ async function handleTool(name, args) {
             await apiFetch(`/api/v1/instances/${instance_id}`, { method: 'DELETE' });
             return `✅ Instance \`${instance_id}\` has been deleted and all data removed.`;
         }
+        // ── Org / Team management ────────────────────────────────────────────
+        case 'list_orgs': {
+            const res = await apiFetch('/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 'create_org': {
+            const { name: orgName, slug } = args;
+            const body = { name: orgName };
+            if (slug)
+                body.slug = slug;
+            const res = await apiFetch('/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;
+            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;
+            const org = await apiFetch(`/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 = { 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;
@@ -2004,24 +2808,42 @@ async function handleTool(name, args) {
             let skipped = 0;
             let errors = 0;
             let semanticIndexed = 0;
+            let unchanged = 0;
             const details = [];
             const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
             const redis = await getConnection(instance_id);
             for (const filePath of files) {
                 const relPath = relative(dir, filePath);
                 let content;
+                let fileSize;
                 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) ──
                 const idxKey = `cachly:idx:${relPath}`;
@@ -2032,6 +2854,13 @@ async function handleTool(name, args) {
                 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}`);
                 // ── Layer 2: Semantic vector index (optional, only if embedding available) ──
@@ -2058,7 +2887,8 @@ async function handleTool(name, args) {
                 `📂 **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}`,
@@ -2091,34 +2921,32 @@ async function handleTool(name, args) {
                 await redis.set(cacheKey, content);
                 await redis.set(`${cacheKey}:meta`, meta);
             }
-            // Also index semantically for smart_recall (if vector available and embedding is configured)
-            if (EMBED_PROVIDER !== 'none') {
-                const inst = await apiFetch(`/api/v1/instances/${instance_id}`);
-                if (inst.vector_token) {
-                    try {
-                        const embedding = await computeEmbedding(`${key}: ${content.slice(0, 500)}`);
-                        const vectorUrl = `https://api.cachly.dev/v1/sem/${inst.vector_token}`;
-                        const body = {
-                            id: `ctx:${category}:${key}`,
-                            prompt: key,
-                            namespace: 'cachly:ctx',
-                            embedding,
-                        };
-                        if (ttl && ttl > 0) {
-                            body['expires_at'] = new Date(Date.now() + ttl * 1000).toISOString();
-                        }
-                        await fetch(`${vectorUrl}/entries`, {
-                            method: 'POST',
-                            headers: { 'Content-Type': 'application/json' },
-                            body: JSON.stringify(body),
-                        }).catch(() => undefined);
-                    }
-                    catch {
-                        // Embedding optional — continue silently
+            // Also index semantically for smart_recall (if vector available)
+            const inst = await apiFetch(`/api/v1/instances/${instance_id}`);
+            if (inst.vector_token) {
+                try {
+                    const embedding = await computeEmbedding(`${key}: ${content.slice(0, 500)}`);
+                    const vectorUrl = `https://api.cachly.dev/v1/sem/${inst.vector_token}`;
+                    const body = {
+                        id: `ctx:${category}:${key}`,
+                        prompt: key,
+                        namespace: 'cachly:ctx',
+                        embedding,
+                    };
+                    if (ttl && ttl > 0) {
+                        body['expires_at'] = new Date(Date.now() + ttl * 1000).toISOString();
                     }
-                }
-            } // end EMBED_PROVIDER !== 'none'
-            return [
+                    await fetch(`${vectorUrl}/entries`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify(body),
+                    }).catch(() => undefined);
+                }
+                catch {
+                    // Embedding optional — continue silently
+                }
+            }
+            return [
                 `🧠 **Context Saved**`,
                 ``,
                 `  Key:      \`${key}\``,
@@ -2242,24 +3070,92 @@ async function handleTool(name, args) {
             return `🗑️ **Forgot ${deleted} context entries.**\n\nKeys: ${keys.map(k => `\`${k}\``).join(', ')}`;
         }
         case 'learn_from_attempts': {
-            const { instance_id, topic, outcome, what_worked, what_failed = '', context: ctx = '', severity = 'major', file_paths = [], commands = [], tags = [], } = args;
+            const { instance_id, topic, outcome, what_worked, what_failed = '', context: ctx = '', severity = 'major', file_paths = [], commands = [], tags = [], depends_on = [], author = '', } = args;
             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 = [];
+            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 = [];
+            const existingRaw = await redis.get(`cachly:lesson:best:${topic}`);
+            if (existingRaw) {
+                try {
+                    const prev = JSON.parse(existingRaw);
+                    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 = [];
+                    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 = [];
+            if (outcome === 'failure') {
+                // Search for related success lessons that might have prevented this failure
+                const scanKeys = [];
+                const scanStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 100 });
+                await new Promise((res, rej) => {
+                    scanStream.on('data', (b) => 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);
-                        recallCount = (prev.recall_count ?? 0); // preserve existing recall count
-                        isUpdate = true;
+                        const l = JSON.parse(raw);
+                        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 { /* ignore parse error */ }
+                    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 = existing ? JSON.parse(existing) : [];
+                if (!depTopics.includes(topic))
+                    depTopics.push(topic);
+                await redis.set(depKey, JSON.stringify(depTopics));
+            }
+            const lessonObj = {
                 topic,
                 outcome,
                 what_worked,
@@ -2269,17 +3165,34 @@ async function handleTool(name, args) {
                 file_paths,
                 commands,
                 tags,
+                depends_on,
+                ...(author ? { author } : {}),
                 recall_count: recallCount,
                 ts,
-                version: 2,
-            });
-            // Always append to the history list
+                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 (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';
@@ -2294,8 +3207,13 @@ async function handleTool(name, args) {
                 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');
         }
         case 'recall_best_solution': {
@@ -2304,40 +3222,36 @@ async function handleTool(name, args) {
             // Try exact best-solution key first
             const best = await redis.get(`cachly:lesson:best:${topic}`);
             if (best) {
-                let lesson;
-                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 };
+                const lesson = JSON.parse(best);
+                // ── 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));
-                // 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(() => { });
-                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(() => { });
-                }
                 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.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}` : '',
@@ -2345,8 +3259,8 @@ async function handleTool(name, args) {
                     (lesson.file_paths ?? []).length > 0 ? `**Files:** ${(lesson.file_paths ?? []).map((f) => `\`${f}\``).join(', ')}` : '',
                     (lesson.commands ?? []).length > 0 ? `**Commands:** ${(lesson.commands ?? []).map((c) => `\`${c}\``).join(', ')}` : '',
                     (lesson.tags ?? []).length > 0 ? `**Tags:** ${(lesson.tags ?? []).map((t) => `#${t}`).join(' ')}` : '',
-                    ``,
-                    `> 🧠 *Your AI remembered this from ${ageLabel} — persistent memory by [cachly.dev](https://cachly.dev)*`,
+                    auditSummary,
+                    suggestPin,
                 ].filter(l => l !== '').join('\n');
             }
             // Partial match: scan all lesson keys for topic substring
@@ -2363,12 +3277,7 @@ async function handleTool(name, args) {
                 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)];
-                    }
-                    catch {
-                        return [];
-                    } });
+                    const parsed = all.map(e => JSON.parse(e));
                     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')}`;
                 }
@@ -2380,74 +3289,11 @@ async function handleTool(name, args) {
                 const raw = await redis.get(k);
                 if (!raw)
                     continue;
-                let lesson;
-                try {
-                    lesson = JSON.parse(raw);
-                }
-                catch {
-                    continue;
-                }
+                const lesson = JSON.parse(raw);
                 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;
-            const redis = await getConnection(instance_id);
-            const keys = [];
-            const stream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
-            await new Promise((resolve, reject) => {
-                stream.on('data', (batch) => 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);
-            const lessons = values.flatMap(raw => {
-                if (!raw)
-                    return [];
-                try {
-                    return [JSON.parse(raw)];
-                }
-                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) => 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;
-            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, query, threshold = 0.78, } = args;
             const redis = await getConnection(instance_id);
@@ -2542,50 +3388,35 @@ async function handleTool(name, args) {
         }
         // ── 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(() => ({}));
-                    healthStatus = `✅ ${body.status ?? 'ok'}${body.db ? ` (db: ${body.db})` : ''}`;
+                    const body = await healthRes.json();
+                    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.message}`;
             }
             // Check JWT / auth
             if (!JWT) {
                 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) {
@@ -2594,41 +3425,32 @@ async function handleTool(name, args) {
                     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;
+            const { instance_id, focus = '', author = '', provider = '' } = args;
             const redis = await getConnection(instance_id);
             // 1. Scan all best-solution lessons
             const lessonKeys = [];
@@ -2639,17 +3461,14 @@ async function handleTool(name, args) {
                 lStream.on('error', reject);
             });
             const lessons = [];
-            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));
-                    }
-                    catch { /* skip corrupt */ }
+            for (const k of lessonKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                try {
+                    lessons.push(JSON.parse(raw));
                 }
+                catch { /* skip corrupt */ }
             }
             lessons.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
             // 3. Count context entries (filter :meta keys)
@@ -2677,13 +3496,114 @@ async function handleTool(name, args) {
                 ? lessons.filter(l => focusTerms.some(term => l.topic.toLowerCase().includes(term) ||
                     (l.tags ?? []).some((t) => t.toLowerCase().includes(term))))
                 : [];
-            // 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) : 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 = ['🧠 **Session Briefing**', ''];
+            const providerLabel = provider ? ` · ${provider}` : '';
+            const lines = [`🧠 **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);
+                    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);
+                    // 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 */ }
+            }
             // Last session
             if (lastSession) {
                 const ago = Math.round((Date.now() - new Date(lastSession.ts).getTime()) / 60000);
@@ -2696,27 +3616,8 @@ async function handleTool(name, args) {
                 }
                 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) {
                 lines.push(`🎯 **Relevant for "${focus}":**`);
@@ -2750,11 +3651,137 @@ async function handleTool(name, args) {
                 }
                 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;
+            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) {
+                const dangerLessons = lessons.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) => 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) {
+                const oneWeekAgo = Date.now() - 7 * 86_400_000;
+                const teamLessons = lessons.filter(l => l.author && l.author !== author && new Date(l.ts).getTime() > oneWeekAgo);
+                if (teamLessons.length > 0) {
+                    // Group by author
+                    const byAuthor = new Map();
+                    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);
+                    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 = { critical: 0, high: 1, medium: 2, low: 3 };
+                    const PRIORITY_ICON = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
+                    const openStatuses = new Set(['planned', 'in-progress', 'blocked']);
+                    const allItems = Object.values(roadmapAll).map(v => JSON.parse(v));
+                    const openItems = allItems
+                        .filter(i => openStatuses.has(i.status))
+                        .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] ?? 99) - (PRIORITY_ORDER[b.priority] ?? 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] ?? '⚪'} \`${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');
         }
         // ── session_end ───────────────────────────────────────────────────────────
         case 'session_end': {
-            const { instance_id, summary, files_changed = [], lessons_learned, } = args;
+            const { instance_id, summary, files_changed = [], lessons_learned, workspace_path = '', } = args;
             const redis = await getConnection(instance_id);
             const now = new Date();
             // Calculate duration from session_start marker
@@ -2767,12 +3794,21 @@ async function handleTool(name, args) {
                 }
                 catch { /* ignore */ }
             }
+            // ── Session Replay: capture decision log ─────────────────────────────
+            let decisionLog = [];
+            try {
+                const dlEntries = await redis.lrange('cachly:session:decision-log', 0, -1);
+                decisionLog = dlEntries.map(e => JSON.parse(e));
+                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"
             await redis.set('cachly:session:last', JSON.stringify(sessionRecord));
@@ -2782,6 +3818,131 @@ async function handleTool(name, args) {
             await redis.expire('cachly:session:history', 90 * 86400);
             // 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 = [];
+            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);
+                            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 = [];
+            if (workspace_path) {
+                try {
+                    // Get the session start time (stored by session_start)
+                    const sessionStartTs = currentRaw
+                        ? (() => { try {
+                            return JSON.parse(currentRaw).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',
+                                what_worked: msg.slice(0, 200),
+                                context: `Auto-learned from git commit ${(hash ?? '').slice(0, 7)} at ${dateStr ?? ''} in ${workspace_path}`,
+                                severity: 'minor',
+                                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}`,
@@ -2789,10 +3950,73 @@ async function handleTool(name, args) {
                 `📋 **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;
+            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;
+            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;
@@ -2813,13 +4037,7 @@ async function handleTool(name, args) {
                 // 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;
-                    try {
-                        existingLesson = JSON.parse(existing);
-                    }
-                    catch {
-                        existingLesson = { outcome: 'failure' };
-                    }
+                    const existingLesson = JSON.parse(existing);
                     if (existingLesson.outcome === 'success' && obs.outcome !== 'success') {
                         skipped.push(topic);
                         continue;
@@ -2873,29 +4091,21 @@ async function handleTool(name, args) {
                 lStream.on('error', reject);
             });
             const relevant = [];
-            if (lessonKeys.length > 0) {
-                const values = await redis.mget(...lessonKeys);
-                for (const raw of values) {
-                    if (!raw)
-                        continue;
-                    let lesson;
-                    try {
-                        lesson = JSON.parse(raw);
-                    }
-                    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);
+                // 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)}`);
                 }
             }
             const lines = [
@@ -2931,7 +4141,7 @@ async function handleTool(name, args) {
                 file_paths: file_paths ?? [],
                 commands: commands ?? [],
                 tags: [...(tags ?? []), 'team'],
-                ts: new Date().toISOString(),
+                timestamp: new Date().toISOString(),
                 recall_count: 0,
                 version: 2,
             };
@@ -2955,16 +4165,14 @@ async function handleTool(name, args) {
                 lStream.on('error', reject);
             });
             let lessons = [];
-            if (lessonKeys.length > 0) {
-                const values = await redis.mget(...lessonKeys);
-                for (const raw of values) {
-                    if (!raw)
-                        continue;
-                    try {
-                        lessons.push(JSON.parse(raw));
-                    }
-                    catch { /* skip */ }
+            for (const k of lessonKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                try {
+                    lessons.push(JSON.parse(raw));
                 }
+                catch { /* skip */ }
             }
             // Filter
             if (topic) {
@@ -2998,278 +4206,142 @@ async function handleTool(name, args) {
             }
             return lines.join('\n');
         }
-        // ── brain_stats ───────────────────────────────────────────────────────────
-        case 'brain_stats': {
-            const { instance_id } = args;
-            const redis = await getConnection(instance_id);
-            // Scan all lesson keys
-            const lessonKeys = [];
-            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
-            await new Promise((resolve, reject) => {
-                lStream.on('data', (batch) => lessonKeys.push(...batch));
-                lStream.on('end', resolve);
-                lStream.on('error', reject);
-            });
-            const lessons = [];
-            if (lessonKeys.length > 0) {
-                const vals = await redis.mget(...lessonKeys);
-                for (const raw of vals) {
-                    if (!raw)
-                        continue;
-                    try {
-                        lessons.push(JSON.parse(raw));
-                    }
-                    catch { /* skip */ }
-                }
-            }
-            // Context count
-            let ctxCount = 0;
-            const ctxStream = redis.scanStream({ match: 'cachly:ctx:*', count: 200 });
-            await new Promise((resolve, reject) => {
-                ctxStream.on('data', (batch) => { ctxCount += batch.filter((k) => !k.endsWith(':meta')).length; });
-                ctxStream.on('end', resolve);
-                ctxStream.on('error', reject);
-            });
-            const lastSessionRaw = await redis.get('cachly:session:last');
-            let lastSession = 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`;
-            }
-            const tokensSaved = (totalRecalls * 1200);
-            const tokenStr = tokensSaved >= 1000 ? `~${(tokensSaved / 1000).toFixed(0)}k tokens` : `~${tokensSaved} tokens`;
-            const costSaved = (tokensSaved * 0.000003).toFixed(2);
-            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'}`,
-                ``,
-            ];
-            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('');
-            }
-            if (authors.length > 0) {
-                lines.push(`**Team contributors (${authors.length}):** ${authors.join(', ')}`);
-                lines.push('');
-            }
-            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.`);
-            return lines.join('\n');
-        }
-        // ── export_brain ──────────────────────────────────────────────────────────
-        case 'export_brain': {
-            const { instance_id, include_context = true, max_lessons } = args;
-            const redis = await getConnection(instance_id);
-            // Scan all lessons
-            const lessonKeys = [];
-            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
-            await new Promise((resolve, reject) => {
-                lStream.on('data', (batch) => lessonKeys.push(...batch));
-                lStream.on('end', resolve);
-                lStream.on('error', reject);
-            });
-            let lessons = [];
-            if (lessonKeys.length > 0) {
-                const vals = await redis.mget(...lessonKeys);
-                for (const raw of vals) {
-                    if (!raw)
-                        continue;
-                    try {
-                        lessons.push(JSON.parse(raw));
-                    }
-                    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 = null;
-            if (lastSessionRaw) {
-                try {
-                    lastSession = JSON.parse(lastSessionRaw);
-                }
-                catch { /* ignore */ }
-            }
-            const crystalRaw = await redis.get('cachly:crystal');
-            let crystal = null;
-            if (crystalRaw) {
-                try {
-                    crystal = JSON.parse(crystalRaw);
-                }
-                catch { /* ignore */ }
-            }
-            const ctxEntries = [];
-            if (include_context) {
-                const ctxKeys = [];
-                const ctxStream = redis.scanStream({ match: 'cachly:ctx:*', count: 200 });
-                await new Promise((resolve, reject) => {
-                    ctxStream.on('data', (batch) => {
-                        ctxKeys.push(...batch.filter((k) => !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 });
-                    }
-                }
-            }
-            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 = [
-                `# 🧠 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}_`, ``);
-            }
-            if (lastSession) {
-                md.push(`## 📅 Last Session`, ``, `**${lastSession.ts.slice(0, 10)}** — ${lastSession.summary}`, ``);
-            }
-            // Group lessons by outcome
-            const successLessons = lessons.filter(l => l.outcome === 'success');
-            const failureLessons = lessons.filter(l => l.outcome !== 'success');
-            const formatLesson = (l) => {
-                const sev = l.severity === 'critical' ? ' 🔴' : l.severity === 'major' ? ' 🟡' : '';
-                const lines = [
-                    `### \`${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');
-            };
-            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]_' : ''), ``);
-                }
+        // ── team_synthesize — Team Brain Synthesis ────────────────────────────────
+        case 'team_synthesize': {
+            const { instance_id, topic } = args;
+            const redis = await getConnection(instance_id);
+            // 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}", ...)\`.`;
             }
-            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;
-            // Generate a share token via API
-            let shareToken = '';
-            let inviteUrl = '';
-            try {
-                const res = await apiFetch(`/api/v1/instances/${instance_id}/invite`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label }) });
-                shareToken = res.token ?? '';
-                inviteUrl = res.url ?? '';
+            const entries = all.map(r => { try {
+                return JSON.parse(r);
             }
             catch {
-                // API doesn't support invite yet — generate a local share snippet instead
+                return null;
+            } }).filter((e) => e !== null);
+            // 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 authors = [...new Set(entries.map(e => e.author).filter(Boolean))];
+            const hasMultiAuthor = authors.length > 1;
+            // 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 ?? '';
+            // what_failed: union of all unique failure reasons
+            const allFailed = [...new Set([...failures, ...partials].map(e => e.what_failed).filter((w) => !!w && w.length > 5))];
+            const severities = entries.map(e => e.severity).filter(Boolean);
+            const canonicalSeverity = severities.includes('critical') ? 'critical' : severities.includes('major') ? 'major' : 'minor';
+            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;
+        }
+        // ── brain_doctor ──────────────────────────────────────────────────────────
+        // ── memory_crystalize ─────────────────────────────────────────────────────
+        case 'memory_crystalize': {
+            const { instance_id, label: crystalLabel = '' } = args;
+            const redis = await getConnection(instance_id);
+            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 = [];
+            const ls = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+            await new Promise((res, rej) => {
+                ls.on('data', (b) => allLessonKeys.push(...b));
+                ls.on('end', res);
+                ls.on('error', rej);
+            });
+            const allLessons = [];
+            for (const k of allLessonKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                try {
+                    allLessons.push(JSON.parse(raw));
+                }
+                catch { /* skip */ }
+            }
+            // Group lessons by top-level category
+            const categoryMap = new Map();
+            for (const l of allLessons) {
+                const cat = l.topic.split(':')[0] || 'misc';
+                if (!categoryMap.has(cat))
+                    categoryMap.set(cat, []);
+                categoryMap.get(cat).push(l);
             }
-            // Build the join command
-            const joinCmd = shareToken
-                ? `npx @cachly-dev/mcp-server@latest join ${shareToken}`
-                : `npx @cachly-dev/mcp-server@latest setup`;
+            // Build top patterns (most frequent categories with a representative insight)
+            const topPatterns = [];
+            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,
+                });
+            }
+            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`,
+            };
+            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;
+            const { instance_id, workspace_path: drWorkspacePath = '' } = args;
             const redis = await getConnection(instance_id);
             const issues = [];
             const checks = [];
@@ -3316,6 +4388,15 @@ async function handleTool(name, args) {
             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);
+            const teamLessons = lessons.filter(l => l.author);
+            const uniqueAuthors = new Set(lessons.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;
             if (lessonKeys.length >= 5)
@@ -3333,10 +4414,72 @@ async function handleTool(name, args) {
             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);
+                    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);
+                    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);
                 const ageStr = ageMin < 60 ? `${ageMin}m` : ageMin < 1440 ? `${Math.round(ageMin / 60)}h` : `${Math.round(ageMin / 1440)}d`;
@@ -3351,12 +4494,22 @@ async function handleTool(name, args) {
             else if (lessonKeys.length < 5) {
                 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.');
             }
             if (openFailures.length > 0) {
                 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`);
             }
@@ -3372,6 +4525,86 @@ async function handleTool(name, args) {
             }
             return lines.join('\n');
         }
+        // ── recall_at — Brain Archaeology ────────────────────────────────────────
+        case 'recall_at': {
+            const { instance_id, topic, date } = args;
+            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);
+            }
+            catch {
+                return null;
+            } })
+                .filter((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);
+                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;
+            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 = 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);
+                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;
@@ -3607,62 +4840,144 @@ async function handleTool(name, args) {
             // 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`;
-            const copilotInstructions = `# cachly AI Memory — ${project_description}
+                ? `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 Brain — ${project_description}
+
+> 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.
+
+---
+
+## 🔴 MANDATORY RULES — Always enforced, no exceptions
+
+### Rule 1 — Session Start (FIRST thing in every window)
+Call \`session_start\` **before reading any source files or making any changes**:
+
+\`\`\`
+session_start(
+  instance_id = "${instance_id}",
+  focus       = "<what you plan to work on today>",
+)
+\`\`\`
+
+Returns: last session summary, handoff from previous window, recent lessons, open failures, brain health.
+
+**If \`session_start\` is unavailable**, fall back:
+1. \`smart_recall("recent lessons <topic>")\`
+2. \`recall_best_solution("<topic>")\`
+
+### 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:
+
+\`\`\`
+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"],
+)
+\`\`\`
 
-## 3-Layer AI Memory System
+**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=[...]\`
 
-- **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
+### 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>,
+)
+\`\`\`
 
-## BEFORE every task — check memory first
+> \`session_end\` **automatically extracts and stores lessons** from the summary text — no manual calls needed.
 
-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 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
 
-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
+---
 
-${smartRecallNote}
-   - \`smart_recall("how does authentication work")\` → returns cached auth notes
+## Task-type trigger table
 
-4. If nothing is found, proceed normally — then save (see below)
+| 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:...")\` |
 
-## AFTER every non-trivial task — save to memory
+---
 
-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")\`
+## Available Brain Tools
 
-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")\`
+| 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 = [
                 `🧠 **cachly AI Memory Setup Complete**`,
@@ -3687,8 +5002,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,
@@ -3702,14 +5017,88 @@ 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) => access(p, constants.F_OK).then(() => true).catch(() => false);
+                const targets = [];
+                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 = {};
+                    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.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 = [];
+                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');
         }
@@ -3833,15 +5222,236 @@ async function handleBulkLockStream(name, args) {
             return (`✅ **cache_stream_get** – ${len} chunk(s) retrieved for \`${key}\`.\n\n` +
                 `**Preview** (first 500 chars):\n\`\`\`\n${preview}${preview.length < chunks.join('').length ? '…' : ''}\n\`\`\``);
         }
+        // ── Roadmap ──────────────────────────────────────────────────────────────
+        case 'roadmap_add': {
+            const { instance_id: rid, title, description: desc = '', priority = 'medium', tags: rtags = [], milestone = '', } = args;
+            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 = { 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;
+            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);
+            const oldStatus = item.status;
+            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 = { 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;
+            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 = { critical: 0, high: 1, medium: 2, low: 3 };
+            const PRIORITY_ICON = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
+            const STATUS_ICON = { planned: '📋', 'in-progress': '⚡', done: '✅', blocked: '🚫', cancelled: '🗑️' };
+            const openStatuses = new Set(['planned', 'in-progress', 'blocked']);
+            let items = Object.values(all).map(v => JSON.parse(v));
+            // Filter
+            if (filterStatus === 'open')
+                items = items.filter(i => openStatuses.has(i.status));
+            else if (filterStatus)
+                items = items.filter(i => i.status === filterStatus);
+            if (filterTag)
+                items = items.filter(i => i.tags.includes(filterTag));
+            if (filterMilestone)
+                items = items.filter(i => i.milestone === filterMilestone);
+            if (filterPriority)
+                items = items.filter(i => (PRIORITY_ORDER[i.priority] ?? 99) <= (PRIORITY_ORDER[filterPriority] ?? 99));
+            // Sort: priority asc, then created asc
+            items.sort((a, b) => {
+                const pa = PRIORITY_ORDER[a.priority] ?? 99;
+                const pb = PRIORITY_ORDER[b.priority] ?? 99;
+                return pa !== pb ? pa - pb : a.created.localeCompare(b.created);
+            });
+            if (items.length === 0)
+                return `📋 **No roadmap items** match the current filter (status: ${filterStatus}).`;
+            const grouped = {};
+            for (const it of items) {
+                const st = it.status;
+                if (!grouped[st])
+                    grouped[st] = [];
+                grouped[st].push(it);
+            }
+            const lines = [`📋 **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.length ? ` [${it.tags.join(', ')}]` : '';
+                    const milestone = it.milestone ? ` · ${it.milestone}` : '';
+                    lines.push(`  ${PRIORITY_ICON[it.priority] ?? '⚪'} \`${it.id}\` **${it.title}**${tags}${milestone}`);
+                    if (it.description)
+                        lines.push(`      ${it.description.slice(0, 120)}`);
+                    if (it.notes)
+                        lines.push(`      📝 ${it.notes.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;
+            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 = { critical: 0, high: 1, medium: 2, low: 3 };
+            const PRIORITY_ICON = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
+            let items = Object.values(all)
+                .map(v => JSON.parse(v))
+                .filter(i => i.status === 'in-progress' || i.status === 'planned')
+                .filter(i => !filterTag || i.tags.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] ?? 99) - (PRIORITY_ORDER[b.priority] ?? 99);
+            });
+            const next = items[0];
+            const remaining = items.length - 1;
+            const tags = next.tags.length ? `\nTags:      ${next.tags.join(', ')}` : '';
+            const milestone = next.milestone ? `\nMilestone: ${next.milestone}` : '';
+            const notes = next.notes ? `\nNotes:     ${next.notes.split('\n').pop()?.slice(0, 120)}` : '';
+            return [
+                `${next.status === 'in-progress' ? '⚡' : '📋'} **Next up: ${next.title}**`,
+                ``,
+                `ID:        \`${next.id}\``,
+                `Priority:  ${PRIORITY_ICON[next.priority] ?? '⚪'} ${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;
     }
 }
 // ── Server setup ──────────────────────────────────────────────────────────────
-const server = new Server({ name: 'cachly-mcp', version: '0.4.0' }, { capabilities: { tools: {} } });
+const server = new Server({ 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 = null;
+let _autoSessionStarted = false;
+let _autoSessionToolCount = 0;
+async function autoStartSession(instanceId) {
+    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() {
+    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?.instance_id;
+        if (instanceId) {
+            await autoStartSession(instanceId).catch(() => undefined);
+        }
+    }
+    if (!sessionTools.has(name))
+        _autoSessionToolCount++;
     try {
         const text = await handleTool(name, (args ?? {}));
         return { content: [{ type: 'text', text }] };
@@ -3852,8 +5462,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         throw new McpError(ErrorCode.InternalError, err.message);
     }
 });
-// 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);
@@ -3872,6 +5489,8 @@ const EDITOR_FILES = {
     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 -->';
 const CLAUDE_MD_MARKER_END = '<!-- cachly-brain-end -->';
@@ -3886,6 +5505,20 @@ function buildMcpConfig(apiKey, instanceId, editor) {
             },
         }, 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: {
@@ -3898,48 +5531,54 @@ function buildMcpConfig(apiKey, instanceId, editor) {
 }
 function buildClaudeMdBlock(instanceId) {
     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}`;
 }
 async function writeClaudeMd(projectDir, instanceId) {
@@ -4011,7 +5650,8 @@ if (process.argv[2] === 'setup') {
     else {
         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`, {
@@ -4020,7 +5660,7 @@ if (process.argv[2] === 'setup') {
                 body: `client_id=${CLIENT_ID}&scope=openid`,
             });
             if (!deviceRes.ok)
-                throw new Error(`HTTP ${deviceRes.status}`);
+                throw new Error(`Device flow error: HTTP ${deviceRes.status}`);
             const data = await deviceRes.json();
             deviceCode = data.device_code;
             userCode = data.user_code;
@@ -4028,17 +5668,19 @@ if (process.argv[2] === 'setup') {
             pollInterval = (data.interval ?? 5) * 1000;
         }
         catch (e) {
-            console.error(`\nCould not reach auth service: ${e.message}`);
-            console.error('Fallback: sign in at https://cachly.dev and paste your API token.\n');
+            console.error(`\nFailed to start device flow: ${e.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');
+                console.error('\nToken is required. Aborting.\n');
                 rl.close();
                 process.exit(1);
             }
-            deviceCode = '';
+            console.log('');
+            deviceCode = ''; // mark as fallback so we skip polling
         }
         if (deviceCode) {
+            // Open browser
             console.log(`   Code: \x1b[1;33m${userCode}\x1b[0m`);
             console.log(`   URL:  ${verifyUri}\n`);
             try {
@@ -4048,10 +5690,11 @@ if (process.argv[2] === 'setup') {
                 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));
                 process.stdout.write('.');
@@ -4061,16 +5704,17 @@ if (process.argv[2] === 'setup') {
                         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}`,
                     });
-                    const td = await tokenRes.json();
-                    if (td.access_token) {
-                        token = td.access_token;
+                    const tokenData = await tokenRes.json();
+                    if (tokenData.access_token) {
+                        token = tokenData.access_token;
                         console.log(' \x1b[32m✓ Authorized!\x1b[0m\n');
                         break;
                     }
-                    if (td.error === 'slow_down')
+                    // authorization_pending = keep polling; slow_down = increase interval
+                    if (tokenData.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`);
+                    else if (tokenData.error && tokenData.error !== 'authorization_pending') {
+                        console.error(`\nAuth error: ${tokenData.error}. Aborting.\n`);
                         rl.close();
                         process.exit(1);
                     }
@@ -4078,47 +5722,38 @@ if (process.argv[2] === 'setup') {
                 catch { /* network hiccup — keep polling */ }
             }
             if (!token) {
-                console.error('\nTimed out. Aborting.\n');
+                console.error('\nTimed out waiting for authorization. Aborting.\n');
                 rl.close();
                 process.exit(1);
             }
-        }
-        // 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();
-                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`);
-            }
+            console.log('');
         }
     }
-    // ── 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;
+    // ── 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();
+            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.
+        }
     }
-    catch { /* non-fatal */ }
     // ── Step 2: Fetch & pick instance ─────────────────────────────────────────
     process.stdout.write('⏳ Fetching your instances...');
     let instances = [];
@@ -4132,32 +5767,70 @@ if (process.argv[2] === 'setup') {
         instances = (body.data ?? []).filter(i => i.status === 'running');
     }
     catch (e) {
-        console.error(`\n\nFailed to fetch instances: ${e.message}`);
-        console.error('Check your token and try again.\n');
+        const msg = e.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();
-                        instances = (b.data ?? []).filter(i => i.status === 'running');
+        // 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();
+            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();
+                            if (inst.status === 'running') {
+                                instances = [inst];
+                                break;
+                            }
+                        }
                     }
+                    catch { /* keep polling */ }
                 }
-                catch { /* ignore */ }
+                console.log('');
             }
-            process.stdout.write(instances.length > 0 ? ' ready!\n' : '\n');
+        }
+        catch (e) {
+            console.log(` failed: ${e.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);
         }
@@ -4174,6 +5847,8 @@ if (process.argv[2] === 'setup') {
     // ── Step 3: Detect editors ────────────────────────────────────────────────
     const cwd = process.cwd();
     const detected = [];
+    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')))
@@ -4184,14 +5859,47 @@ if (process.argv[2] === 'setup') {
         detected.push('copilot');
     if (existsSync(resolve(cwd, '.continue')))
         detected.push('continue');
-    const editorLabel = (e) => ({ claude: 'Claude Code', cursor: 'Cursor', windsurf: 'Windsurf', copilot: 'GitHub Copilot', continue: 'Continue.dev' })[e] ?? e;
+    // 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) => ({ 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): `);
     const editorsToSetup = !editorsRaw || editorsRaw.toLowerCase() === 'all'
         ? detected
         : 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);
@@ -4199,16 +5907,163 @@ if (process.argv[2] === 'setup') {
         await writeFile(configPath, buildMcpConfig(token, instance.id, editor), 'utf-8');
         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`);
     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();
+            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 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] === 'index') {
+    const { resolve } = await import('node:path');
+    const argv = process.argv.slice(3);
+    const flag = (name) => { const i = argv.indexOf(`--${name}`); return i !== -1 ? argv[i + 1] : undefined; };
+    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📂  Indexing: ${dir}`);
+    console.log(`    Instance: ${instanceId.slice(0, 8)}…  Max files: ${maxFiles}\n`);
+    try {
+        const result = await handleTool('index_project', {
+            instance_id: instanceId,
+            dir,
+            max_files: maxFiles,
+            ttl: 86400 * 7,
+            namespace,
+        });
+        console.log(result);
+        console.log('\n✅  Indexing complete.\n');
+    }
+    catch (err) {
+        console.error(`\n❌  Indexing failed: ${err.message}\n`);
+        process.exit(1);
+    }
     process.exit(0);
 }
 // ── Start ─────────────────────────────────────────────────────────────────────
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// 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');
+}
+// ── 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 res = await fetch(`https://registry.npmjs.org/@cachly-dev/mcp-server/latest`, { signal: AbortSignal.timeout(4000) });
+            if (res.ok) {
+                const data = await res.json();
+                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 { /* ignore – network unavailable or timeout */ }
+    })();
+}
+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;
+        }
+        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);
+}
 //# sourceMappingURL=index.js.map