knit-mcp 0.7.0 → 0.8.0

package/dist/{tools-KRPOUYNT.js → tools-GN6GM55U.js}

@@ -1,20 +1,33 @@
+import {
+  KNIT_INSTRUCTIONS
+} from "./chunk-4PFEG4GQ.js";
+import {
+  VERSION
+} from "./chunk-UTVFELXS.js";
 import {
   appendSession,
+  getCachedLatestVersion,
   getRecentSessions,
   installAgentsForProject,
+  isNewerVersion,
+  loadAllSessions,
+  loadScanResult,
+  persistScanResult,
   pruneSessionsByAge,
+  scanIntegrations,
   searchSessions,
   sessionCount
-} from "./chunk-3XR77YJM.js";
+} from "./chunk-N7R4P42P.js";
 import {
   scanProject
-} from "./chunk-7PPC6IG6.js";
+} from "./chunk-JJ367RK5.js";
 import {
   appendGlobalLearning,
   buildGlobalLearning,
   getRecentGlobalLearnings,
+  loadAllGlobalLearnings,
   searchGlobalLearnings
-} from "./chunk-TRZ3LD6B.js";
+} from "./chunk-TSIXVZCT.js";
 import {
   addEntry,
   getFalsePositives,
@@ -35,7 +48,10 @@ import {
   sessionsLogPath,
   teamsPath,
   worktreesRegistryPath
-} from "./chunk-HBMF62U4.js";
+} from "./chunk-SBJMHDBM.js";
+import {
+  notifyToolsListChanged
+} from "./chunk-WMESQUZU.js";
 
 // src/mcp/handlers.ts
 import { writeFileSync as writeFileSync4, readFileSync as readFileSync4, readdirSync, existsSync as existsSync4, renameSync as renameSync2, unlinkSync } from "fs";
@@ -723,11 +739,12 @@ var TOOL_REGISTRY = [
   // ── Tier 1 — Protocol Guard config (2) ──────────────────────────
   { tool: "knit_set_protocol_strictness", tier: 1, category: "protocol-config", rationale: "Universal \u2014 every install ships Protocol Guard" },
   { tool: "knit_get_protocol_strictness", tier: 1, category: "protocol-config", rationale: "Universal" },
-  // ── Tier 1 — Diagnostics + meta (4) ─────────────────────────────
+  // ── Tier 1 — Diagnostics + meta (5) ─────────────────────────────
   { tool: "knit_brain_status", tier: 1, category: "diagnostics", rationale: "Health + token-accounting; universal" },
   { tool: "knit_list_features", tier: 1, category: "diagnostics", rationale: "The discoverability escape hatch itself" },
   { tool: "knit_enable_feature", tier: 1, category: "diagnostics", rationale: "Flip on a Tier-2/3 feature flag \u2014 must always be reachable so hidden tools are recoverable" },
   { tool: "knit_disable_feature", tier: 1, category: "diagnostics", rationale: "Flip off a previously-enabled feature flag" },
+  { tool: "knit_scan_integrations", tier: 1, category: "diagnostics", rationale: "Re-detect existing user workflow frameworks (Ruflo, gstack, CodeTour, custom CLAUDE.md) so Knit can integrate rather than overlap" },
   // ── Tier 2 — Team worktrees (9) ─────────────────────────────────
   { tool: "knit_spawn_team_worktree", tier: 2, category: "teams", rationale: "Multi-domain parallel write orchestration", enable_via: 'knit_enable_feature("teams") or auto-exposed when \u22653 domains detected' },
   { tool: "knit_finalize_team_worktree", tier: 2, category: "teams", rationale: "Merge/discard a team worktree", enable_via: 'knit_enable_feature("teams")' },
@@ -796,6 +813,225 @@ function isEnableableFeature(name) {
   return name === "teams" || name === "subagents" || name === "admin";
 }
 
+// src/engine/retrieval/bm25.ts
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "by",
+  "for",
+  "from",
+  "has",
+  "have",
+  "i",
+  "in",
+  "is",
+  "it",
+  "its",
+  "of",
+  "on",
+  "or",
+  "that",
+  "the",
+  "this",
+  "to",
+  "was",
+  "were",
+  "will",
+  "with",
+  "s",
+  "t"
+  // possessives + contraction remnants after tokenization
+]);
+function defaultTokenize(text) {
+  if (!text) return [];
+  const lower = text.toLowerCase();
+  const tokens = lower.split(/[^a-z0-9_]+/);
+  const out = [];
+  for (const t of tokens) {
+    if (t.length < 2) continue;
+    if (STOPWORDS.has(t)) continue;
+    out.push(t);
+  }
+  return out;
+}
+var BM25Index = class {
+  k1;
+  b;
+  tokenize;
+  docs = [];
+  /** Per-document token frequency map: docId → token → count. */
+  termFreq = /* @__PURE__ */ new Map();
+  /** Document lengths in tokens, indexed by docId. */
+  docLengths = /* @__PURE__ */ new Map();
+  /** Document frequency: token → number of docs containing it. */
+  docFreq = /* @__PURE__ */ new Map();
+  avgDocLength = 0;
+  constructor(documents = [], options = {}) {
+    this.k1 = options.k1 ?? 1.5;
+    this.b = options.b ?? 0.75;
+    this.tokenize = options.tokenize ?? defaultTokenize;
+    for (const doc of documents) this.addInternal(doc);
+    this.recomputeAvgDocLength();
+  }
+  /** Add a document. Triggers an avgDocLength recompute. For bulk additions
+   *  during initial indexing, prefer constructor — same end state, single recompute. */
+  add(document) {
+    this.addInternal(document);
+    this.recomputeAvgDocLength();
+  }
+  /** Search the corpus. Returns up to `limit` documents ranked by BM25 score.
+   *  Documents with zero score (no query terms match) are omitted entirely. */
+  search(query, limit = 10) {
+    const queryTerms = this.tokenize(query);
+    if (queryTerms.length === 0 || this.docs.length === 0) return [];
+    const scores = /* @__PURE__ */ new Map();
+    const N = this.docs.length;
+    for (const term of queryTerms) {
+      const df = this.docFreq.get(term) ?? 0;
+      if (df === 0) continue;
+      const idf = Math.log((N - df + 0.5) / (df + 0.5) + 1);
+      for (const doc of this.docs) {
+        const tf = this.termFreq.get(doc.id)?.get(term) ?? 0;
+        if (tf === 0) continue;
+        const docLen = this.docLengths.get(doc.id) ?? 0;
+        const denom = tf + this.k1 * (1 - this.b + this.b * (docLen / (this.avgDocLength || 1)));
+        const tfNorm = tf * (this.k1 + 1) / denom;
+        scores.set(doc.id, (scores.get(doc.id) ?? 0) + idf * tfNorm);
+      }
+    }
+    const ranked = [];
+    for (const doc of this.docs) {
+      const score = scores.get(doc.id);
+      if (score === void 0 || score <= 0) continue;
+      ranked.push({ id: doc.id, score, document: doc });
+    }
+    ranked.sort((a, b) => b.score - a.score);
+    return ranked.slice(0, limit);
+  }
+  /** Number of indexed documents. */
+  size() {
+    return this.docs.length;
+  }
+  /** Number of unique tokens across the corpus — useful for diagnostics. */
+  vocabularySize() {
+    return this.docFreq.size;
+  }
+  // ── Internals ─────────────────────────────────────────────────
+  addInternal(doc) {
+    if (this.termFreq.has(doc.id)) {
+      this.removeInternal(doc.id);
+    }
+    this.docs.push(doc);
+    const tokens = this.tokenize(doc.text);
+    this.docLengths.set(doc.id, tokens.length);
+    const tfMap = /* @__PURE__ */ new Map();
+    for (const t of tokens) {
+      tfMap.set(t, (tfMap.get(t) ?? 0) + 1);
+    }
+    this.termFreq.set(doc.id, tfMap);
+    for (const t of tfMap.keys()) {
+      this.docFreq.set(t, (this.docFreq.get(t) ?? 0) + 1);
+    }
+  }
+  removeInternal(docId) {
+    const tfMap = this.termFreq.get(docId);
+    if (!tfMap) return;
+    for (const t of tfMap.keys()) {
+      const df = this.docFreq.get(t) ?? 0;
+      if (df <= 1) this.docFreq.delete(t);
+      else this.docFreq.set(t, df - 1);
+    }
+    this.termFreq.delete(docId);
+    this.docLengths.delete(docId);
+    const idx = this.docs.findIndex((d) => d.id === docId);
+    if (idx !== -1) this.docs.splice(idx, 1);
+  }
+  recomputeAvgDocLength() {
+    if (this.docs.length === 0) {
+      this.avgDocLength = 0;
+      return;
+    }
+    let total = 0;
+    for (const len of this.docLengths.values()) total += len;
+    this.avgDocLength = total / this.docs.length;
+  }
+};
+
+// src/engine/retrieval/rrf.ts
+function rrfFuse(rankings, options = {}) {
+  const k = options.k ?? 60;
+  const acc = /* @__PURE__ */ new Map();
+  for (let rankerIdx = 0; rankerIdx < rankings.length; rankerIdx++) {
+    const ranking = rankings[rankerIdx];
+    for (const result of ranking) {
+      const contribution = 1 / (k + result.rank);
+      const entry = acc.get(result.id) ?? { score: 0, ranks: {} };
+      entry.score += contribution;
+      entry.ranks[rankerIdx] = result.rank;
+      acc.set(result.id, entry);
+    }
+  }
+  const fused = [];
+  for (const [id, { score, ranks }] of acc) {
+    fused.push({ id, score, ranks });
+  }
+  fused.sort((a, b) => b.score - a.score);
+  return options.limit !== void 0 ? fused.slice(0, options.limit) : fused;
+}
+function toRankedResults(scored) {
+  return scored.map((s, i) => ({ id: s.id, rank: i + 1 }));
+}
+
+// src/engine/retrieval/index.ts
+function buildLearningsIndex(entries) {
+  const docs = entries.map((e) => ({
+    id: e.id,
+    text: [e.summary, e.lesson, e.approach ?? "", (e.tags ?? []).join(" "), (e.domains ?? []).join(" ")].filter(Boolean).join(" "),
+    metadata: { entry: e }
+  }));
+  return new BM25Index(docs);
+}
+function buildGlobalLearningsIndex(entries) {
+  const docs = entries.map((e) => ({
+    id: e.id,
+    text: [e.summary, e.lesson, (e.tags ?? []).join(" "), e.projectName ?? ""].filter(Boolean).join(" "),
+    metadata: { entry: e }
+  }));
+  return new BM25Index(docs);
+}
+function buildSessionsIndex(sessions) {
+  const docs = sessions.map((s) => ({
+    id: s.id,
+    text: [
+      s.summary ?? "",
+      (s.tags ?? []).join(" "),
+      s.branch ?? "",
+      s.commits ?? "",
+      (s.domainsTouched ?? []).join(" ")
+    ].filter(Boolean).join(" "),
+    metadata: { session: s }
+  }));
+  return new BM25Index(docs);
+}
+function diversifyByBranch(results, maxPerBranch = 2) {
+  const counts = /* @__PURE__ */ new Map();
+  const out = [];
+  for (const r of results) {
+    const session = r.document.metadata?.session;
+    const branch = session?.branch ?? "(no-branch)";
+    const c = counts.get(branch) ?? 0;
+    if (c >= maxPerBranch) continue;
+    counts.set(branch, c + 1);
+    out.push(r);
+  }
+  return out;
+}
+
 // src/engine/teams.ts
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, statSync, existsSync as existsSync2, mkdirSync as mkdirSync2 } from "fs";
 import { dirname as dirname2 } from "path";
@@ -1107,12 +1343,47 @@ function handleFindFanout(params, brain) {
 }
 function handleSearchLearnings(params, brain) {
   const domains = (params.domains || "").split(",").map((d) => d.trim()).filter(Boolean);
-  if (domains.length === 0) return JSON.stringify({ error: "domains parameter is required", query: [], results: [], count: 0 });
-  const results = queryByDomains(brain.knowledgeBase, domains);
-  if (results.length > 0) recordCacheHit(brain.knowledgeBase);
+  const query = (params.query || "").trim();
+  const limit = Math.max(1, Math.min(50, parseInt(params.limit || "10", 10) || 10));
+  if (!query && domains.length === 0) {
+    return JSON.stringify({
+      error: "Provide either query (BM25 free-text) or domains (tag filter), or both. query=auth domains=#api filters BM25 results to entries tagged #api.",
+      query: [],
+      results: [],
+      count: 0
+    });
+  }
+  if (!query) {
+    const results = queryByDomains(brain.knowledgeBase, domains);
+    if (results.length > 0) recordCacheHit(brain.knowledgeBase);
+    return JSON.stringify(buildLearningsResponse(results, domains, []));
+  }
+  const index = buildLearningsIndex(brain.knowledgeBase.entries);
+  const bm25Hits = index.search(query, Math.min(limit * 3, 50));
+  const fused = rrfFuse([toRankedResults(bm25Hits)], { k: 60 });
+  const entryById = /* @__PURE__ */ new Map();
+  for (const e of brain.knowledgeBase.entries) entryById.set(e.id, e);
+  let entries = [];
+  for (const f of fused) {
+    const entry = entryById.get(f.id);
+    if (!entry) continue;
+    entries.push(entry);
+  }
+  if (domains.length > 0) {
+    entries = entries.filter(
+      (e) => e.tags.some((t) => domains.includes(t)) || e.domains.some((d) => domains.includes(d))
+    );
+  }
+  entries = entries.slice(0, limit);
+  if (entries.length > 0) recordCacheHit(brain.knowledgeBase);
+  return JSON.stringify(buildLearningsResponse(entries, domains, [query]));
+}
+function buildLearningsResponse(results, domains, freeText) {
   const hasFailures = results.some((r) => r.outcome === "failure");
-  return JSON.stringify({
-    query: domains,
+  const queryParts = [...freeText, ...domains];
+  return {
+    query: queryParts,
+    retriever: freeText.length > 0 ? "bm25" : "tag-filter",
     results: results.map((r) => ({
       summary: r.summary,
       lesson: r.lesson,
@@ -1122,8 +1393,8 @@ function handleSearchLearnings(params, brain) {
       access_count: r.accessCount
     })),
     count: results.length,
-    instruction: results.length > 0 ? hasFailures ? `Found ${results.length} past learnings including FAILURES. Read the lessons carefully \u2014 avoid repeating past mistakes.` : `Found ${results.length} past learnings. Apply these lessons to your current task.` : "No past learnings for these domains. This is new territory \u2014 be thorough and record what you learn."
-  });
+    instruction: results.length > 0 ? hasFailures ? `Found ${results.length} past learnings including FAILURES. Read the lessons carefully \u2014 avoid repeating past mistakes.` : `Found ${results.length} past learnings. Apply these lessons to your current task.` : freeText.length > 0 ? "No past learnings match this query. Try broader terms, or call knit_search_global_learnings to search across all your projects." : "No past learnings for these domains. This is new territory \u2014 be thorough and record what you learn."
+  };
 }
 function handleGetFalsePositives(_params, brain) {
   const fps = getFalsePositives(brain.knowledgeBase);
@@ -1133,6 +1404,27 @@ function handleGetFalsePositives(_params, brain) {
     instruction: "Include these in review agent prompts as DO NOT FLAG items."
   });
 }
+var TOKEN_BUDGETS = {
+  /** Generated CLAUDE.md block. v0.7 trim landed at ~2KB on typical projects;
+   *  6.5KB target allows for projects with many domains / large project map. */
+  claude_md_bytes: 6500,
+  /** Tier-gated tools/list response. v0.7 typical: 26 active × ~280 bytes ≈ 7.3KB.
+   *  8.5KB target allows Tier-2 team tools to come online on ≥3-domain projects
+   *  without crossing into warn. Full 38-tool exposure (everything enabled)
+   *  sits in warn range, surfacing the bloat without blocking it. */
+  tool_registry_bytes: 8500,
+  /** MCP server `instructions` field — sent at handshake. v0.7 ships at ~2KB. */
+  instructions_bytes: 2500,
+  /** Sum of the three above — the per-session fixed cost Knit imposes.
+   *  v0.7 typical: ~12KB; 17.5KB target covers the union with slack. */
+  per_session_overhead_bytes: 17500
+};
+function verdict(actual, target) {
+  if (actual <= target) return "healthy";
+  if (actual <= target * 1.25) return "warn";
+  return "over-budget";
+}
+var CHARS_PER_TOKEN = 4;
 function handleBrainStatus(_params, brain) {
   const summary = getKBSummary(brain.knowledgeBase);
   const claudeMdBytes = (() => {
@@ -1142,8 +1434,51 @@ function handleBrainStatus(_params, brain) {
       return 0;
     }
   })();
+  const shape = detectProjectShape(brain);
+  const listing = computeFeatureListing(shape);
+  const activeToolCount = listing.totals.active;
+  const totalToolCount = listing.totals.total;
+  const AVG_TOOL_DEF_BYTES = 280;
+  const toolRegistryBytes = activeToolCount * AVG_TOOL_DEF_BYTES;
+  const instructionsBytes = KNIT_INSTRUCTIONS.length;
+  const perSessionOverheadBytes = claudeMdBytes + toolRegistryBytes + instructionsBytes;
   const totalSessions = sessionCount(brain.rootPath);
   const hitRate = summary.totalEntries > 0 ? Math.round(summary.accessedEntries / summary.totalEntries * 100) : 0;
+  const budgets = {
+    claude_md: {
+      bytes: claudeMdBytes,
+      kb: Math.round(claudeMdBytes / 1024 * 10) / 10,
+      target_bytes: TOKEN_BUDGETS.claude_md_bytes,
+      verdict: verdict(claudeMdBytes, TOKEN_BUDGETS.claude_md_bytes)
+    },
+    tool_registry: {
+      active_tool_count: activeToolCount,
+      total_tool_count: totalToolCount,
+      bytes: toolRegistryBytes,
+      target_bytes: TOKEN_BUDGETS.tool_registry_bytes,
+      verdict: verdict(toolRegistryBytes, TOKEN_BUDGETS.tool_registry_bytes)
+    },
+    instructions: {
+      bytes: instructionsBytes,
+      target_bytes: TOKEN_BUDGETS.instructions_bytes,
+      verdict: verdict(instructionsBytes, TOKEN_BUDGETS.instructions_bytes)
+    },
+    per_session_overhead: {
+      bytes: perSessionOverheadBytes,
+      kb: Math.round(perSessionOverheadBytes / 1024 * 10) / 10,
+      tokens_estimate: Math.round(perSessionOverheadBytes / CHARS_PER_TOKEN),
+      target_bytes: TOKEN_BUDGETS.per_session_overhead_bytes,
+      verdict: verdict(perSessionOverheadBytes, TOKEN_BUDGETS.per_session_overhead_bytes)
+    }
+  };
+  const verdicts = [budgets.claude_md.verdict, budgets.tool_registry.verdict, budgets.instructions.verdict, budgets.per_session_overhead.verdict];
+  const overall = verdicts.includes("over-budget") ? "over-budget" : verdicts.includes("warn") ? "warn" : "healthy";
+  const compounding = {
+    session_count: totalSessions,
+    total_learnings: summary.totalEntries,
+    learnings_hit_rate_pct: hitRate,
+    note: totalSessions === 0 ? "Fresh brain \u2014 no sessions yet. Compounding kicks in around session 3." : hitRate >= 30 ? "Strong compounding \u2014 learnings are getting reused across sessions." : hitRate < 20 && summary.totalEntries > 10 ? "Low hit rate \u2014 many learnings unused. Consider pruning stale entries." : "Compounding building up."
+  };
   return JSON.stringify({
     ...summary,
     knowledge_index: {
@@ -1152,14 +1487,45 @@ function handleBrainStatus(_params, brain) {
       import_edges: Object.keys(brain.knowledge.importGraph).length,
       exports_mapped: Object.keys(brain.knowledge.exports).length
     },
+    // Back-compat: the flat token_accounting shape from pre-v0.7.2 is kept so
+    // anything that hard-coded those field names still works.
     token_accounting: {
       claude_md_bytes: claudeMdBytes,
-      claude_md_kb: Math.round(claudeMdBytes / 1024 * 10) / 10,
+      claude_md_kb: budgets.claude_md.kb,
       session_count: totalSessions,
       learnings_hit_rate_pct: hitRate,
-      note: claudeMdBytes > 3e4 ? "CLAUDE.md is large \u2014 consider trimming. Tax exceeds typical savings." : hitRate < 20 && summary.totalEntries > 10 ? "Low hit rate \u2014 many learnings unused. Consider pruning stale entries." : "Healthy."
+      note: budgets.per_session_overhead.verdict === "over-budget" ? "Per-session overhead exceeds budget \u2014 see token_budget for the offending surface." : compounding.note
+    },
+    // v0.7.2 — structured per-surface budget with target ceilings + verdicts.
+    token_budget: {
+      budgets,
+      overall_verdict: overall,
+      compounding
     },
     cache_age_ms: Date.now() - brain.loadedAt,
+    ...(() => {
+      const latest = getCachedLatestVersion();
+      if (!latest || !isNewerVersion(latest, VERSION)) return {};
+      return {
+        update_available: {
+          current: VERSION,
+          latest,
+          upgrade: 'Restart Claude Code to spawn a fresh MCP \u2014 npx will auto-fetch the new version. If your ~/.claude.json pins a specific version, change it to "knit-mcp@latest".',
+          changelog: "https://github.com/PDgit12/knit/blob/main/CHANGELOG.md"
+        }
+      };
+    })(),
+    ...(() => {
+      const integrations = loadScanResult(brain.rootPath);
+      if (!integrations) return {};
+      return {
+        integrations: {
+          scanned_at: integrations.scannedAt,
+          detected: integrations.detected,
+          summary: integrations.summary
+        }
+      };
+    })(),
     instruction: "Brain is ready. Next: call knit_classify_task with the files you plan to touch to get your tier and phases."
   });
 }
@@ -1199,7 +1565,7 @@ function saveEnabledFeatures(rootPath, enabled) {
 function detectProjectShape(brain) {
   return {
     hasAnalyzableCode: brain.knowledge.summary.totalFiles >= 10,
-    domainCount: brain.config.domains?.length ?? 0,
+    domainCount: brain.config?.domains?.length ?? 0,
     hasInstalledSubagents: existsSync4(projectAgentsDir(brain.rootPath)),
     sessionCount: sessionCount(brain.rootPath),
     enabledFeatures: loadEnabledFeatures(brain.rootPath)
@@ -1233,14 +1599,31 @@ function handleEnableFeature(params, brain) {
   enabled.add(feature);
   if (!wasAlreadyOn) {
     saveEnabledFeatures(brain.rootPath, enabled);
+    notifyToolsListChanged();
   }
   return JSON.stringify({
     status: wasAlreadyOn ? "already-enabled" : "enabled",
     feature,
     enabled_features: [...enabled].sort(),
-    instruction: "New tools may now appear in tools/list on the next request. Call knit_list_features to confirm."
+    instruction: wasAlreadyOn ? "Already enabled. Call knit_list_features to see the active tool list." : "Tools list updated for this session. The newly-enabled tools should be available immediately \u2014 call knit_list_features to confirm."
   });
 }
+function handleScanIntegrations(_params, brain) {
+  try {
+    const result = scanIntegrations(brain.rootPath, { knitVersion: VERSION });
+    persistScanResult(brain.rootPath, result);
+    return JSON.stringify({
+      status: "scanned",
+      ...result,
+      instruction: result.detected.ruflo.present || result.detected.gstack.present || result.detected.codetour.present || result.detected.conductor.present ? "Existing frameworks detected. v0.7.2 surfaces them under knit_brain_status; v0.8 will tailor server instructions to defer to them where appropriate." : "No existing workflow frameworks detected. Knit operates in full-protocol mode."
+    });
+  } catch (err) {
+    return JSON.stringify({
+      status: "error",
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
 function handleDisableFeature(params, brain) {
   const feature = (params.feature || "").trim().toLowerCase();
   if (!isEnableableFeature(feature)) {
@@ -1253,12 +1636,13 @@ function handleDisableFeature(params, brain) {
   const wasOn = enabled.delete(feature);
   if (wasOn) {
     saveEnabledFeatures(brain.rootPath, enabled);
+    notifyToolsListChanged();
   }
   return JSON.stringify({
     status: wasOn ? "disabled" : "already-disabled",
     feature,
     enabled_features: [...enabled].sort(),
-    instruction: "Disabled tools will be filtered out of tools/list on the next request."
+    instruction: wasOn ? "Tools list updated for this session. Opt-in-only tools for this feature are no longer visible." : "Already disabled. Auto-exposed tools (e.g. teams when \u22653 domains) stay visible regardless of this flag."
   });
 }
 function detectsInquiryIntent(description) {
@@ -1715,9 +2099,28 @@ function handleSearchGlobalLearnings(params, _brain) {
   if (!query) {
     return JSON.stringify({ error: "query is required", results: [] });
   }
-  const matches = searchGlobalLearnings(query, limit);
+  const entries = loadAllGlobalLearnings();
+  let matches = [];
+  let retriever = "bm25";
+  if (entries.length > 0) {
+    const index = buildGlobalLearningsIndex(entries);
+    const bm25Hits = index.search(query, Math.min(limit * 3, 50));
+    const fused = rrfFuse([toRankedResults(bm25Hits)], { k: 60 });
+    const byId = /* @__PURE__ */ new Map();
+    for (const e of entries) byId.set(e.id, e);
+    for (const f of fused) {
+      const entry = byId.get(f.id);
+      if (entry) matches.push(entry);
+      if (matches.length >= limit) break;
+    }
+  }
+  if (matches.length === 0) {
+    matches = searchGlobalLearnings(query, limit);
+    if (matches.length > 0) retriever = "substring-fallback";
+  }
   return JSON.stringify({
     query,
+    retriever,
     count: matches.length,
     results: matches.map((m) => ({
       id: m.id,
@@ -1965,14 +2368,33 @@ function handleFinalizeTeamWorktree(params, brain) {
   }
 }
 function handleSearchSessions(params, brain) {
-  const query = params.query || "";
+  const query = (params.query || "").trim();
   const limit = Math.max(1, Math.min(50, parseInt(params.limit || "10", 10) || 10));
-  if (!query.trim()) {
+  if (!query) {
     return JSON.stringify({ error: "query is required", results: [] });
   }
-  const matches = searchSessions(brain.rootPath, query, limit);
+  const sessions = loadAllSessions(brain.rootPath);
+  let matches = [];
+  let retriever = "bm25";
+  if (sessions.length > 0) {
+    const index = buildSessionsIndex(sessions);
+    const bm25Hits = index.search(query, Math.min(limit * 5, 50));
+    const diversified = diversifyByBranch(bm25Hits, 2);
+    const byId = /* @__PURE__ */ new Map();
+    for (const s of sessions) byId.set(s.id, s);
+    for (const r of diversified) {
+      const session = byId.get(r.id);
+      if (session) matches.push(session);
+      if (matches.length >= limit) break;
+    }
+  }
+  if (matches.length === 0) {
+    matches = searchSessions(brain.rootPath, query, limit);
+    if (matches.length > 0) retriever = "substring-fallback";
+  }
   return JSON.stringify({
     query,
+    retriever,
     count: matches.length,
     results: matches.map((s) => ({
       id: s.id,
@@ -2035,8 +2457,15 @@ function getToolDefinitions() {
     },
     {
       name: "knit_search_learnings",
-      description: "Search learnings by domain tag.",
-      inputSchema: { type: "object", properties: { domains: { type: "string", description: "Comma-separated domain tags." } }, required: ["domains"] }
+      description: 'BM25 free-text + tag filter. Pass query="text" for BM25, domains="#tag" for tag filter, or both to combine.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "BM25 free-text query over summary/lesson/approach/tags." },
+          domains: { type: "string", description: "Comma-separated tag filter; combines with query when both passed." },
+          limit: { type: "string", description: "Max results (default 10, max 50)." }
+        }
+      }
     },
     {
       name: "knit_get_false_positives",
@@ -2292,6 +2721,11 @@ function getToolDefinitions() {
         properties: { feature: { type: "string", description: "One of: teams, subagents, admin." } },
         required: ["feature"]
       }
+    },
+    {
+      name: "knit_scan_integrations",
+      description: "Re-scan host for existing workflow frameworks (Ruflo, gstack, CodeTour). Runs implicitly at autoInit; this is the manual re-trigger.",
+      inputSchema: { type: "object", properties: {} }
     }
   ];
 }
@@ -2344,7 +2778,8 @@ var handlers = {
   knit_get_protocol_strictness: handleGetProtocolStrictness,
   knit_list_features: handleListFeatures,
   knit_enable_feature: handleEnableFeature,
-  knit_disable_feature: handleDisableFeature
+  knit_disable_feature: handleDisableFeature,
+  knit_scan_integrations: handleScanIntegrations
 };
 function handleToolCall(toolName, params, brain) {
   if (params.file_path) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knit-mcp",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Knit — second brain for Claude Code. MCP server giving any AI agent project-scoped memory, tiered workflow protocol, and parallel team worktrees.",
   "type": "module",
   "bin": {