bilmem 0.1.0 → 0.2.0

package/dist/install/index.js

@@ -1,5 +1,5 @@
 // src/install/index.ts
-import * as path17 from "path";
+import * as path19 from "path";
 import * as readline from "readline/promises";
 
 // src/storage/canonical.ts
@@ -829,6 +829,8 @@ function getAgentInstructionText(version = CURRENT_INTEGRATION_VERSION) {
 ## Bilmem Knowledge Runtime
 Bilmem is available through MCP.
 
+Before substantial implementation work, use \`bilmem_preflight\` to surface existing constraints, relevant lessons, stale knowledge, and important unknowns. Do not run it for trivial edits or typo fixes.
+
 Use \`bilmem_resolve\` when:
 - uncertain about project-specific behavior,
 - multiple plausible approaches exist,
@@ -852,6 +854,159 @@ function extractInstructionVersion(content) {
 function hasBilmemInstruction(content) {
   return content.includes(BILMEM_START_MARKER) && content.includes(BILMEM_END_MARKER);
 }
+function getBilmemSkillContent(version = CURRENT_INTEGRATION_VERSION) {
+  return `---
+name: bilmem
+description: >-
+  Epistemic runtime and project knowledge engine. Use when you need to inspect existing constraints or lessons before starting work (bilmem_preflight), resolve epistemic uncertainty or architectural decisions (bilmem_resolve), query verified knowledge (bilmem_lookup), record new observations (bilmem_observe), extract lessons from trajectories (bilmem_learn), track unknowns (bilmem_unknown), or check knowledge reuse and effectiveness (bilmem_stats).
+---
+<!-- bilmem-version: ${version} -->
+
+# Bilmem Epistemic Knowledge Runtime
+
+Bilmem is an epistemic knowledge engine designed to answer:
+> **Do I know enough to act, what do I know does not apply, what am I missing, and what is the cheapest next step to resolve uncertainty?**
+
+Unlike traditional code graphs or vector memory, Bilmem focuses on verified facts, contextual applicability (via JEV positive/negative cues), staged learning from trajectories, and tracking unknowns as first-class citizens.
+
+---
+
+## \u26A1 Core Epistemic Commitments
+
+1. **Cheaper than not knowing:** Querying Bilmem or resolving uncertainty is significantly cheaper than re-investigating, guessing, or recovering from incorrect architectural assumptions.
+2. **Never guess project invariants:** If uncertain whether caching is enabled in production, how auth tokens rotate, or why a specific pattern exists, resolve it through Bilmem instead of guessing.
+3. **No queries on trivial edits:** Do not query Bilmem for simple typo fixes, formatting, or obvious local syntax changes.
+4. **Receipts & Honest Confidence:** Bilmem uses explainable confidence tiers (\`low\`, \`medium\`, \`high\`) and returns receipts explaining why knowledge was accepted or rejected.
+
+---
+
+## \u{1F680} Progressive Disclosure: Tool Runbook
+
+> [!TIP]
+> **Project Directory Target (\`path\` parameter)**:
+> In global MCP environments or multi-workspace IDEs, always pass the \`"path"\` parameter with your project root (e.g. \`"path": "/path/to/project"\` or active workspace directory) to target the proper repository and prevent root filesystem permission issues.
+
+### 1. Before Substantial Implementation: \`bilmem_preflight\`
+Run \`bilmem_preflight\` with your proposed goal before modifying architecture, core logic, or adding features:
+\`\`\`json
+{
+  "path": "/path/to/project",
+  "goal": "Add OAuth login with Google",
+  "positive": ["auth", "oauth", "session"],
+  "negative": ["stateless-jwt"]
+}
+\`\`\`
+**Returns:**
+- Applicable verified constraints & architectural rules.
+- Relevant lessons from past implementations or regressions.
+- Past failures in similar domains.
+- Blocking unknowns that must be investigated first.
+- Stale dependencies that need review.
+- Next recommended investigation actions.
+
+### 2. When Uncertain or Resolving Contradictions: \`bilmem_resolve\`
+Use \`bilmem_resolve\` when encountering ambiguous codebase behavior, multiple plausible paths, or conflicting assumptions:
+\`\`\`json
+{
+  "path": "/path/to/project",
+  "question": "How are user sessions renewed and validated?",
+  "positive": ["server-session", "postgres", "redis"],
+  "negative": ["client-cookie-only"]
+}
+\`\`\`
+**Returns:**
+- \`state\`: \`resolved\` (sufficient facts known), \`needs_investigation\`, or \`contradiction\`.
+- \`known\`: Verified statements applicable to the current context.
+- \`rejected\`: Inapplicable knowledge units filtered out by negative cues.
+- \`missing\`: Critical gaps that need observation before proceeding.
+- \`next\`: The cheapest concrete investigation step.
+
+### 3. Exact Knowledge Retrieval: \`bilmem_lookup\`
+Quickly look up specific conventions, lessons, or rules:
+\`\`\`json
+{
+  "path": "/path/to/project",
+  "query": "session timeout configuration",
+  "limit": 5
+}
+\`\`\`
+
+### 4. Recording Fresh Discoveries: \`bilmem_observe\`
+Record verified discoveries, configuration invariants, or environment realities:
+\`\`\`json
+{
+  "path": "/path/to/project",
+  "claim": "Production session cookies require SameSite=Strict and Secure flags",
+  "source": "file:src/auth/session.ts#L42",
+  "positive": ["production", "cookie", "auth"],
+  "negative": ["development"]
+}
+\`\`\`
+
+### 5. Learning from Corrections & Trajectories: \`bilmem_learn\`
+After resolving a difficult bug, fixing a regression, or receiving a critical user correction, distill the trajectory:
+\`\`\`json
+{
+  "path": "/path/to/project",
+  "goal": "Fix refresh token rotation loop",
+  "outcome": "success",
+  "userCorrection": {
+    "topic": "session-auth",
+    "incorrectAssumption": "Token refresh does not require a concurrent mutex",
+    "correctFact": "Token refresh requires a concurrency mutex to avoid 401 race conditions"
+  }
+}
+\`\`\`
+Bilmem runs staged reconciliation: extracts observations, creates candidate lessons, evaluates polar contradictions, and reconciles into durable knowledge.
+
+### 6. Recording Known Unknowns: \`bilmem_unknown\`
+When you realize critical context is missing, record an unknown instead of making a silent assumption:
+\`\`\`json
+{
+  "path": "/path/to/project",
+  "action": "record",
+  "id": "staging.redis-cache",
+  "question": "Does the staging database share the Redis cache cluster with production?"
+}
+\`\`\`
+
+### 7. Auditing Effectiveness & Reuse: \`bilmem_stats\`
+Verify how well Bilmem is reducing repeated investigation:
+\`\`\`json
+{
+  "path": "/path/to/project",
+  "since": "7d"
+}
+\`\`\`
+
+---
+
+## \u{1F4BB} CLI Quick Reference
+
+All tools are also available directly on the command line:
+
+| Command | Purpose |
+| :--- | :--- |
+| \`bilmem preflight "<goal>"\` | Pre-implementation readiness & constraint analysis |
+| \`bilmem resolve "<question>"\` | Epistemic resolution with context cues & receipts |
+| \`bilmem lookup "<query>"\` | Fast contextual lookup of verified knowledge |
+| \`bilmem observe "<claim>" --source <src>\` | Record verified evidence or invariant |
+| \`bilmem learn --trajectory "<text>"\` | Reconcile candidate lessons into knowledge |
+| \`bilmem scan [--dry-run]\` | Conservative filesystem & convention discovery |
+| \`bilmem stats [--since 7d]\` | Measure knowledge reuse and effectiveness |
+| \`bilmem doctor [--fix]\` | Verify and repair integrations and storage |
+`;
+}
+function hasBilmemSkill(content) {
+  return content.includes("name: bilmem") && content.includes("---");
+}
+function extractSkillVersion(content) {
+  const match = content.match(/<!--\s*bilmem-version:\s*(\d+)\s*-->/);
+  if (match && match[1]) {
+    return parseInt(match[1], 10);
+  }
+  return null;
+}
 
 // src/install/atomic.ts
 async function writeAtomic(filePath, content) {
@@ -1020,6 +1175,42 @@ async function pathExists(p) {
     return false;
   }
 }
+async function updateSkillFile(filePath, content, dryRun = false) {
+  let existingContent = "";
+  let exists = false;
+  try {
+    existingContent = await fs4.readFile(filePath, "utf-8");
+    exists = true;
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  if (exists && existingContent.trim() === content.trim()) {
+    return { changed: false, created: false, originalExisted: true };
+  }
+  if (!dryRun) {
+    await writeAtomic(filePath, content.trimEnd() + "\n");
+  }
+  return { changed: true, created: !exists, originalExisted: exists };
+}
+async function removeSkillFile(filePath, dryRun = false) {
+  try {
+    await fs4.access(filePath);
+  } catch {
+    return { removed: false, fileDeleted: false };
+  }
+  if (!dryRun) {
+    try {
+      await fs4.unlink(filePath);
+      const parentDir = path4.dirname(filePath);
+      const remaining = await fs4.readdir(parentDir);
+      if (remaining.length === 0) {
+        await fs4.rmdir(parentDir);
+      }
+    } catch {
+    }
+  }
+  return { removed: true, fileDeleted: true };
+}
 async function isExecutableInPath(command) {
   const envPath = process.env.PATH;
   if (!envPath) return false;
@@ -1085,6 +1276,7 @@ async function getIntegrationRecord(rootDir, agentId) {
 
 // src/install/adapters/base.ts
 var BaseAgentAdapter = class {
+  aliases;
   supportedScopes = ["project", "global"];
   async inspect(context) {
     const configPath = this.resolveConfigPath(context);
@@ -1098,7 +1290,9 @@ var BaseAgentAdapter = class {
     if (read.exists && !read.error && read.data?.mcpServers?.bilmem) {
       mcpConfigured = true;
       const b = read.data.mcpServers.bilmem;
-      mcpCommandMatches = b.command === targetCommand && Array.isArray(b.args) && b.args.length === targetArgs.length && b.args.every((v, i) => v === targetArgs[i]);
+      const targetMatch = b.command === targetCommand && Array.isArray(b.args) && b.args.length === targetArgs.length && b.args.every((v, i) => v === targetArgs[i]);
+      const wrapperMatch = Array.isArray(b.args) && b.args.some((arg) => typeof arg === "string" && arg.includes("bilmem"));
+      mcpCommandMatches = Boolean(targetMatch || wrapperMatch);
     }
     let instructionInstalled = false;
     let instructionVersion;
@@ -1111,6 +1305,20 @@ var BaseAgentAdapter = class {
       }
     } catch {
     }
+    let skillInstalled = false;
+    let skillVersion;
+    const skillPath = this.resolveSkillPath ? this.resolveSkillPath(context) : void 0;
+    if (skillPath) {
+      try {
+        const skillContent = await fs5.readFile(skillPath, "utf-8");
+        skillInstalled = hasBilmemSkill(skillContent);
+        const extracted = extractSkillVersion(skillContent);
+        if (extracted !== null) {
+          skillVersion = extracted;
+        }
+      } catch {
+      }
+    }
     return {
       id: this.id,
       name: this.name,
@@ -1120,9 +1328,12 @@ var BaseAgentAdapter = class {
       mcpCommandMatches,
       instructionInstalled,
       instructionVersion,
+      skillInstalled: skillPath ? skillInstalled : void 0,
+      skillVersion: skillPath ? skillVersion : void 0,
       currentInstructionVersion: CURRENT_INTEGRATION_VERSION,
       configPath,
       instructionPath,
+      skillPath,
       details: {
         rawConfigExisted: read.exists,
         configError: read.error
@@ -1167,6 +1378,19 @@ var BaseAgentAdapter = class {
     if (instRes.changed) {
       actionsTaken.push(`Installed/updated agent instruction block in ${instructionPath}`);
     }
+    let skillChanged = false;
+    const skillPath = this.resolveSkillPath ? this.resolveSkillPath(context) : void 0;
+    if (skillPath) {
+      const skillRes = await updateSkillFile(
+        skillPath,
+        getBilmemSkillContent(CURRENT_INTEGRATION_VERSION),
+        options.dryRun ?? false
+      );
+      skillChanged = skillRes.changed;
+      if (skillRes.changed) {
+        actionsTaken.push(`Installed/updated Antigravity skill in ${skillPath}`);
+      }
+    }
     if (context.scope === "project") {
       await recordIntegration(
         context.projectDir,
@@ -1177,6 +1401,8 @@ var BaseAgentAdapter = class {
           mcpConfigPath: path6.relative(context.projectDir, configPath),
           instructions: true,
           instructionPath: path6.relative(context.projectDir, instructionPath),
+          skill: skillPath ? true : void 0,
+          skillPath: skillPath ? path6.relative(context.projectDir, skillPath) : void 0,
           version: CURRENT_INTEGRATION_VERSION,
           installedAt: (/* @__PURE__ */ new Date()).toISOString()
         },
@@ -1187,7 +1413,7 @@ var BaseAgentAdapter = class {
     if (!resolvable && !options.dryRun) {
       warnings.push(`Executable "${targetCommand}" is not in system PATH. Ensure it can be run by ${this.name}.`);
     }
-    const changesMade = mcpRes.changed || instRes.changed || projectInitialized;
+    const changesMade = mcpRes.changed || instRes.changed || skillChanged || projectInitialized;
     if (!changesMade) {
       actionsTaken.push("Already up to date");
     }
@@ -1198,6 +1424,8 @@ var BaseAgentAdapter = class {
       scope: options.scope,
       mcpChanged: mcpRes.changed,
       instructionChanged: instRes.changed,
+      skillChanged,
+      skillPath,
       projectInitialized,
       dryRun: options.dryRun,
       actionsTaken,
@@ -1217,10 +1445,19 @@ var BaseAgentAdapter = class {
     if (instRes.removed) {
       actionsTaken.push(`Removed Bilmem instruction block from ${instructionPath}`);
     }
+    let skillRemoved = false;
+    const skillPath = this.resolveSkillPath ? this.resolveSkillPath(context) : void 0;
+    if (skillPath) {
+      const skillRes = await removeSkillFile(skillPath, options.dryRun ?? false);
+      skillRemoved = skillRes.removed;
+      if (skillRes.removed) {
+        actionsTaken.push(`Removed Antigravity skill from ${skillPath}`);
+      }
+    }
     if (context.scope === "project") {
       await removeIntegration(context.projectDir, this.id, options.dryRun ?? false);
     }
-    const anyRemoved = mcpRes.removed || instRes.removed;
+    const anyRemoved = mcpRes.removed || instRes.removed || skillRemoved;
     if (!anyRemoved) {
       actionsTaken.push("No Bilmem configuration found to remove");
     }
@@ -1231,6 +1468,8 @@ var BaseAgentAdapter = class {
       scope: options.scope,
       mcpRemoved: mcpRes.removed,
       instructionRemoved: instRes.removed,
+      skillRemoved,
+      skillPath,
       dryRun: options.dryRun,
       actionsTaken,
       message: anyRemoved ? `Successfully uninstalled Bilmem from ${this.name}` : `No Bilmem configuration found for ${this.name}`
@@ -1242,6 +1481,7 @@ var BaseAgentAdapter = class {
     const recommendations = [];
     let mcpValid = false;
     let instructionValid = false;
+    let skillValid = true;
     if (!state.mcpConfigured) {
       issues.push(`MCP server "bilmem" is not configured in ${state.configPath}`);
       recommendations.push(`Run "bilmem install ${this.id}" to configure MCP`);
@@ -1262,17 +1502,31 @@ var BaseAgentAdapter = class {
     } else {
       instructionValid = true;
     }
+    if (state.skillPath) {
+      if (!state.skillInstalled) {
+        skillValid = false;
+        issues.push(`Skill file missing from ${state.skillPath}`);
+        recommendations.push(`Run "bilmem install ${this.id}" to install the skill`);
+      } else if (state.skillVersion !== CURRENT_INTEGRATION_VERSION) {
+        skillValid = false;
+        issues.push(
+          `Skill file version (${state.skillVersion || "legacy"}) is outdated (current: ${CURRENT_INTEGRATION_VERSION})`
+        );
+        recommendations.push(`Run "bilmem doctor --fix" to update the skill`);
+      }
+    }
     const targetCommand = context.bilmemCommand || "bilmem";
     const commandResolvable = await isExecutableInPath(targetCommand);
     if (!commandResolvable) {
       issues.push(`Command "${targetCommand}" is not found in PATH`);
       recommendations.push(`Ensure "${targetCommand}" is installed globally or in your PATH`);
     }
-    const valid = mcpValid && instructionValid && commandResolvable;
+    const valid = mcpValid && instructionValid && skillValid && commandResolvable;
     return {
       valid,
       mcpValid,
       instructionValid,
+      skillValid,
       commandResolvable,
       issues,
       recommendations
@@ -1479,12 +1733,110 @@ var GeminiAdapter = class extends BaseAgentAdapter {
   }
 };
 
+// src/install/adapters/antigravity.ts
+import * as path11 from "path";
+import * as os5 from "os";
+import * as fs6 from "fs";
+function resolveAntigravityGlobalDir(context) {
+  const home = context.globalDir || os5.homedir();
+  if (path11.basename(home) === "config" && path11.basename(path11.dirname(home)) === ".gemini") {
+    return home;
+  }
+  return path11.join(home, ".gemini", "config");
+}
+var AntigravityAdapter = class extends BaseAgentAdapter {
+  id = "antigravity";
+  name = "Antigravity";
+  resolveConfigPath(context) {
+    if (context.scope === "project") {
+      const rootMcp = path11.join(context.projectDir, "mcp_config.json");
+      if (fs6.existsSync(rootMcp)) {
+        return rootMcp;
+      }
+      return path11.join(context.projectDir, ".agents", "mcp_config.json");
+    }
+    const globalRoot = resolveAntigravityGlobalDir(context);
+    return path11.join(globalRoot, "mcp_config.json");
+  }
+  resolveSkillPath(context) {
+    if (context.scope === "project") {
+      return path11.join(context.projectDir, ".agents", "skills", "bilmem", "SKILL.md");
+    }
+    const globalRoot = resolveAntigravityGlobalDir(context);
+    return path11.join(globalRoot, "skills", "bilmem", "SKILL.md");
+  }
+  resolveInstructionPath(context) {
+    if (context.scope === "project") {
+      const geminiMd = path11.join(context.projectDir, "GEMINI.md");
+      const agentsMd = path11.join(context.projectDir, "AGENTS.md");
+      const rulesBilmem = path11.join(context.projectDir, ".agents", "rules", "bilmem.md");
+      if (fs6.existsSync(rulesBilmem)) {
+        return rulesBilmem;
+      }
+      if (fs6.existsSync(geminiMd)) {
+        return geminiMd;
+      }
+      if (fs6.existsSync(agentsMd)) {
+        return agentsMd;
+      }
+      return path11.join(context.projectDir, ".agents", "rules", "bilmem.md");
+    }
+    const globalRoot = resolveAntigravityGlobalDir(context);
+    return path11.join(globalRoot, "rules", "bilmem.md");
+  }
+  async detect(context) {
+    const reasons = [];
+    const dotAgents = path11.join(context.projectDir, ".agents");
+    const skillsDir = path11.join(context.projectDir, ".agents", "skills");
+    const agentsMcp = path11.join(context.projectDir, ".agents", "mcp_config.json");
+    const rootMcp = path11.join(context.projectDir, "mcp_config.json");
+    const geminiMd = path11.join(context.projectDir, "GEMINI.md");
+    const agentsMd = path11.join(context.projectDir, "AGENTS.md");
+    const hasDotAgents = await pathExists(dotAgents);
+    const hasSkillsDir = await pathExists(skillsDir);
+    const hasAgentsMcp = await pathExists(agentsMcp);
+    const hasRootMcp = await pathExists(rootMcp);
+    const hasGeminiMd = await pathExists(geminiMd);
+    const hasAgentsMd = await pathExists(agentsMd);
+    if (hasDotAgents) reasons.push("Found .agents/ directory");
+    if (hasSkillsDir) reasons.push("Found .agents/skills/ directory");
+    if (hasAgentsMcp) reasons.push("Found .agents/mcp_config.json");
+    if (hasRootMcp) reasons.push("Found mcp_config.json file");
+    if (hasGeminiMd) reasons.push("Found GEMINI.md rule file");
+    if (hasAgentsMd) reasons.push("Found AGENTS.md rule file");
+    const home = context.globalDir || os5.homedir();
+    const globalConfig = resolveAntigravityGlobalDir(context);
+    const globalIde = path11.join(home, ".gemini", "antigravity-ide");
+    const globalCli = path11.join(home, ".gemini", "antigravity-cli");
+    const globalAgy = path11.join(home, ".gemini", "antigravity");
+    const hasGlobalConfig = await pathExists(globalConfig);
+    const hasGlobalIde = await pathExists(globalIde);
+    const hasGlobalCli = await pathExists(globalCli);
+    const hasGlobalAgy = await pathExists(globalAgy);
+    if (hasGlobalConfig) reasons.push(`Found Antigravity global config at ${globalConfig}`);
+    if (hasGlobalIde) reasons.push(`Found Antigravity IDE at ${globalIde}`);
+    if (hasGlobalCli) reasons.push(`Found Antigravity CLI at ${globalCli}`);
+    if (hasGlobalAgy) reasons.push(`Found Antigravity directory at ${globalAgy}`);
+    const hasAgyExec = await isExecutableInPath("agy");
+    if (hasAgyExec) reasons.push('Found "agy" command in PATH');
+    const detected = reasons.length > 0;
+    const confidence = hasDotAgents || hasSkillsDir || hasAgentsMcp || hasRootMcp || hasGeminiMd || hasAgentsMd ? "high" : hasGlobalConfig || hasGlobalIde || hasGlobalCli || hasGlobalAgy || hasAgyExec ? "medium" : "low";
+    return {
+      detected,
+      confidence: detected ? confidence : "low",
+      reasons,
+      supportedScopes: this.supportedScopes
+    };
+  }
+};
+
 // src/install/registry.ts
 var adapters = [
   new CursorAdapter(),
   new ClaudeAdapter(),
   new CodexAdapter(),
-  new GeminiAdapter()
+  new GeminiAdapter(),
+  new AntigravityAdapter()
 ];
 function getAllAdapters() {
   return [...adapters];
@@ -1504,11 +1856,11 @@ async function detectAgents(context) {
 }
 
 // src/install/doctor.ts
-import * as path16 from "path";
+import * as path18 from "path";
 
 // src/mcp/server.ts
 import { McpApp, z } from "mcponce";
-import * as path15 from "path";
+import * as path17 from "path";
 
 // src/search/indexer.ts
 import { create, insert, remove, search } from "@orama/orama";
@@ -1883,6 +2235,7 @@ function formatWhyHistory(knowledge) {
 // src/core/resolver.ts
 var RELATIVE_COSTS = {
   USE_KNOWLEDGE: 1,
+  REVALIDATE: 2,
   INSPECT_TEST: 2,
   INSPECT_FILE: 2,
   INSPECT_SYMBOL: 2.5,
@@ -2223,6 +2576,634 @@ async function resolveEpistemicQuery(options, storage, retriever) {
   };
 }
 
+// src/core/preflight.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import * as path12 from "path";
+import * as fs7 from "fs/promises";
+import YAML2 from "yaml";
+
+// src/core/dependencies.ts
+function normalizeSourceKey(source) {
+  return source.replace(/^(file|code|test|doc):/, "").trim().toLowerCase();
+}
+function checkKnowledgeStaleness(knowledge, changedSources) {
+  const normChanged = new Set(changedSources.map(normalizeSourceKey));
+  const allDeps = [
+    ...(knowledge.depends_on ?? []).map(normalizeSourceKey),
+    ...knowledge.evidence.map(normalizeSourceKey)
+  ];
+  const changed = [];
+  const unchanged = [];
+  for (const dep of allDeps) {
+    if (!dep) continue;
+    const isChanged = normChanged.has(dep) || Array.from(normChanged).some((c) => dep.includes(c) || c.includes(dep));
+    if (isChanged) {
+      changed.push(dep);
+    } else {
+      unchanged.push(dep);
+    }
+  }
+  if (changed.length > 0) {
+    const reason = `Supporting dependency changed: ${changed.join(", ")}. Unchanged evidence: ${unchanged.join(", ") || "none"}`;
+    return {
+      knowledgeId: knowledge.id,
+      affected: true,
+      status: "needs_revalidation",
+      changedSources: changed,
+      unchangedSources: unchanged,
+      reason
+    };
+  }
+  return {
+    knowledgeId: knowledge.id,
+    affected: false,
+    status: knowledge.status,
+    changedSources: [],
+    unchangedSources: allDeps
+  };
+}
+function markStaleKnowledge(knowledgeList, changedSources) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  let affectedCount = 0;
+  const updatedKnowledge = [];
+  for (const k of knowledgeList) {
+    if (k.status === "superseded" || k.status === "invalid" || k.status === "invalidated") {
+      updatedKnowledge.push(k);
+      continue;
+    }
+    const res = checkKnowledgeStaleness(k, changedSources);
+    if (res.affected) {
+      affectedCount++;
+      const history = k.history ?? [];
+      const updated = {
+        ...k,
+        status: "needs_revalidation",
+        updatedAt: now,
+        history: [
+          ...history,
+          {
+            timestamp: now,
+            status: "needs_revalidation",
+            action: "source_changed",
+            reason: res.reason
+          }
+        ]
+      };
+      updatedKnowledge.push(updated);
+    } else {
+      updatedKnowledge.push(k);
+    }
+  }
+  return { updatedKnowledge, affectedCount };
+}
+function checkKnowledgeListStaleness(knowledgeList, changedSources) {
+  const { updatedKnowledge, affectedCount } = markStaleKnowledge(knowledgeList, changedSources);
+  const affectedKnowledge = updatedKnowledge.filter((k) => k.status === "needs_revalidation");
+  return { affectedKnowledge, updatedKnowledge, affectedCount };
+}
+
+// src/core/preflight.ts
+var execFileAsync = promisify(execFile);
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "add",
+  "implement",
+  "create",
+  "support",
+  "with",
+  "the",
+  "a",
+  "an",
+  "for",
+  "in",
+  "to",
+  "and",
+  "of",
+  "on",
+  "from",
+  "using",
+  "via",
+  "into",
+  "by",
+  "our",
+  "new",
+  "use",
+  "make",
+  "allow",
+  "enable",
+  "provide",
+  "setup",
+  "set"
+]);
+var DOMAIN_KEYWORDS = {
+  authentication: ["auth", "oauth", "login", "logout", "session", "jwt", "token", "credential", "sso", "password"],
+  session: ["session", "cookie", "cookies", "expiry", "refresh", "token"],
+  "user-identity": ["user", "account", "profile", "identity", "member", "role", "permission"],
+  database: ["db", "database", "sql", "postgres", "sqlite", "migration", "schema", "table", "query"],
+  storage: ["storage", "s3", "bucket", "file", "upload", "disk", "blob"],
+  api: ["api", "endpoint", "http", "rest", "route", "controller", "middleware", "graphql"],
+  caching: ["cache", "redis", "memcached", "ttl", "invalidation"],
+  billing: ["payment", "stripe", "checkout", "billing", "subscription", "invoice", "credit"],
+  "data-processing": ["import", "export", "csv", "bulk", "batch", "stream", "pipeline"]
+};
+function tokenizeGoal(goal) {
+  return goal.toLowerCase().replace(/[^a-z0-9_-]/g, " ").split(/\s+/).filter((t) => t.length > 2 && !STOP_WORDS.has(t));
+}
+function inferLikelyDomains(tokens, knowledgeTags) {
+  const domains = /* @__PURE__ */ new Set();
+  for (const token of tokens) {
+    for (const [domain, keywords] of Object.entries(DOMAIN_KEYWORDS)) {
+      if (keywords.includes(token) || token.includes(domain)) {
+        domains.add(domain);
+      }
+    }
+  }
+  for (const tag of knowledgeTags) {
+    const norm = tag.toLowerCase().trim();
+    if (DOMAIN_KEYWORDS[norm]) {
+      domains.add(norm);
+    }
+  }
+  return Array.from(domains);
+}
+function classifyUnknown(unknown, goalTokens, domainCues) {
+  const text = `${unknown.id} ${unknown.statement || ""} ${unknown.question || unknown.next?.question || ""}`.toLowerCase();
+  if (unknown.blocking === true) {
+    const isDecision2 = /\b(should|whether|how to handle|what happens when|policy|strategy|linking|collision|merge|choice)\b/i.test(text);
+    return {
+      classification: "BLOCKING",
+      isDecision: isDecision2 || true,
+      reason: unknown.reason || "Blocking unknown identified for this goal"
+    };
+  }
+  if (unknown.blocking === false) {
+    const isDecision2 = /\b(should|whether|how to handle|what happens when|policy|strategy|choice)\b/i.test(text);
+    return {
+      classification: "NON_BLOCKING",
+      isDecision: isDecision2,
+      reason: "Operational or instrumentation detail not blocking core functionality"
+    };
+  }
+  const isNonBlocking = /\b(analytics|telemetry|metric|event name|logging level|log format|button color|styling|theme)\b/i.test(text);
+  if (isNonBlocking) {
+    return {
+      classification: "NON_BLOCKING",
+      isDecision: /\b(should|which name|choice)\b/i.test(text),
+      reason: "Operational or instrumentation detail not blocking core functionality"
+    };
+  }
+  const isDecision = /\b(should|whether|how to handle|what happens when|policy|strategy|linking|collision|merge)\b/i.test(text);
+  const isBlockingCandidate = /\b(link|linking|collision|duplicate|merge|security|permission|storage-engine|protocol|auth-flow|credentials)\b/i.test(text);
+  const overlapsGoal = goalTokens.some((t) => text.includes(t)) || domainCues.some((d) => text.includes(d));
+  if (isBlockingCandidate && (overlapsGoal || unknown.reason === "UNRESOLVABLE_LOCALLY")) {
+    return {
+      classification: "BLOCKING",
+      isDecision: true,
+      reason: "Unresolved architectural or behavioral decision critical to goal implementation"
+    };
+  }
+  return {
+    classification: "IMPORTANT",
+    isDecision,
+    reason: isDecision ? "Product or behavior decision requiring attention" : "Important implementation detail"
+  };
+}
+function prioritizeQuestions(rawQuestions, blockingUnknowns) {
+  const consolidated = /* @__PURE__ */ new Map();
+  for (const rq of rawQuestions) {
+    const qText = rq.question.trim();
+    if (!qText) continue;
+    const topic = rq.targetTopic || qText.toLowerCase().replace(/[^a-z0-9]/g, " ").slice(0, 30);
+    let expectedResolutionValue = 1;
+    if (rq.isBlocking) expectedResolutionValue += 2;
+    if (rq.outcomeScore && rq.outcomeScore > 0) expectedResolutionValue += 1;
+    if (rq.outcomeScore && rq.outcomeScore < 0) expectedResolutionValue -= 0.5;
+    const interactionCost = 1;
+    const priorityScore = Math.max(0.1, expectedResolutionValue) / interactionCost;
+    const existing = consolidated.get(topic);
+    if (!existing || priorityScore > (existing.priorityScore ?? 0)) {
+      consolidated.set(topic, {
+        question: qText,
+        reason: rq.reason,
+        targetTopic: rq.targetTopic,
+        expectedResolutionValue,
+        interactionCost,
+        priorityScore
+      });
+    }
+  }
+  return Array.from(consolidated.values()).sort((a, b) => (b.priorityScore ?? 0) - (a.priorityScore ?? 0));
+}
+async function executePreflight(options, storage, retriever, index) {
+  const goal = options.goal.trim();
+  const explicitPositive = (options.positive ?? []).map((p) => p.trim().toLowerCase());
+  const negative = (options.negative ?? []).map((n) => n.trim().toLowerCase());
+  const scope = options.scope ?? "project";
+  const goalTokens = tokenizeGoal(goal);
+  const allKnowledge = await storage.getAllKnowledge();
+  const allTags = allKnowledge.flatMap((k) => k.tags ?? []);
+  const likelyDomains = inferLikelyDomains(goalTokens, allTags);
+  const contextualPositive = Array.from(/* @__PURE__ */ new Set([...explicitPositive, ...likelyDomains, ...goalTokens]));
+  let candidatePool = [];
+  if (retriever) {
+    const jevCandidates = await retriever.lookup({
+      query: goal,
+      positive: contextualPositive,
+      negative,
+      scope,
+      limit: options.maxCandidates ?? 25,
+      includeRejected: true
+    });
+    for (const r of jevCandidates) {
+      if (r.knowledge) candidatePool.push(r.knowledge);
+    }
+  }
+  if (candidatePool.length === 0) {
+    candidatePool = allKnowledge.filter((k) => k.status !== "invalid" && k.status !== "superseded");
+  } else {
+    for (const k of allKnowledge) {
+      if (!candidatePool.some((c) => c.id === k.id) && k.status !== "invalid" && k.status !== "superseded") {
+        const matchesToken = goalTokens.some((t) => k.id.toLowerCase().includes(t) || k.statement.toLowerCase().includes(t));
+        const matchesCues = k.positive.some((p) => contextualPositive.includes(p));
+        if (matchesToken || matchesCues) {
+          candidatePool.push(k);
+        }
+      }
+    }
+  }
+  const jevResults = rerankCandidates(candidatePool, {
+    query: goal,
+    positive: contextualPositive,
+    negative,
+    scope
+  });
+  const matchingItems = [];
+  const rejectedItems = [];
+  for (const res of jevResults) {
+    if (res.status === "REJECT") {
+      const reason = res.explanation.negativeConflicts.length > 0 ? `Inapplicable: ${res.explanation.negativeConflicts.join(", ")} conflicts with current context` : res.explanation.reasons[0] || "Context mismatch";
+      rejectedItems.push({ id: res.knowledge.id, reason });
+    } else {
+      matchingItems.push(res.knowledge);
+    }
+  }
+  if (options.deep) {
+    try {
+      const { stdout: diffOutput } = await execFileAsync(
+        "git",
+        ["diff", "--name-only", "HEAD~1"],
+        { cwd: storage.getBaseDir() ? path12.dirname(storage.getBaseDir()) : process.cwd() }
+      );
+      const changedFiles = diffOutput.split("\n").map((f) => f.trim()).filter(Boolean);
+      if (changedFiles.length > 0) {
+        const staleness = checkKnowledgeListStaleness(matchingItems, changedFiles);
+        for (const affected of staleness.affectedKnowledge) {
+          const matchIdx = matchingItems.findIndex((m) => m.id === affected.id);
+          if (matchIdx >= 0) {
+            matchingItems[matchIdx] = affected;
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  const constraints = [];
+  const lessons = [];
+  const pastFailures = [];
+  const stale = [];
+  const known = [];
+  let conflictedCount = 0;
+  const CONSTRAINT_PATTERN = /\b(must|must not|never|only|cannot|require|required|boundary|strictly|prohibited|forbidden)\b/i;
+  const FAILURE_PATTERN = /(fail|bug|error|crash|duplicate write|race condition|pressure|leak|revert|timeout)/i;
+  const rootDir = storage.getBaseDir() ? path12.dirname(storage.getBaseDir()) : process.cwd();
+  for (const k of matchingItems) {
+    const matchesContradiction = k.status === "contradicted" || k.contradicts && k.contradicts.some((cid) => matchingItems.some((m) => m.id === cid));
+    if (matchesContradiction) {
+      conflictedCount++;
+    }
+    let isStale = k.status === "needs_revalidation" || k.status === "stale";
+    let staleReason = k.history?.[k.history.length - 1]?.reason || "Supporting source changed after last validation";
+    const changedDeps = [];
+    const candidateDeps = [...k.depends_on ?? [], ...k.evidence ?? []];
+    const timestampStr = k.updated_at ?? k.updatedAt ?? k.createdAt;
+    const knowledgeTime = new Date(timestampStr).getTime();
+    for (const dep of candidateDeps) {
+      const cleanPath = dep.replace(/^(file|code|test|doc):/, "").trim();
+      if (!cleanPath) continue;
+      const absPath = path12.isAbsolute(cleanPath) ? cleanPath : path12.resolve(rootDir, cleanPath);
+      try {
+        const stat4 = await fs7.stat(absPath);
+        if (stat4.mtimeMs > knowledgeTime + 500) {
+          isStale = true;
+          changedDeps.push(cleanPath);
+          staleReason = `Supporting source changed after last validation (${cleanPath})`;
+        }
+      } catch {
+      }
+    }
+    if (isStale) {
+      stale.push({
+        id: k.id,
+        statement: k.statement,
+        reason: staleReason,
+        changedSources: changedDeps.length > 0 ? changedDeps : k.depends_on
+      });
+      continue;
+    }
+    const isConstraint = k.type === "rule" || k.type === "decision" || k.type === "convention" || CONSTRAINT_PATTERN.test(k.statement);
+    if (isConstraint) {
+      constraints.push({
+        id: k.id,
+        statement: k.statement,
+        type: k.type,
+        confidence: k.confidence,
+        confidenceTier: k.confidenceTier,
+        source: k.evidence?.[0]
+      });
+      continue;
+    }
+    const isFailure = k.type === "failure" || k.statement.startsWith("[FAILURE]") || k.statement.startsWith("[REVERT]") || FAILURE_PATTERN.test(k.statement) || k.metrics.failed_outcomes > 0;
+    if (isFailure) {
+      pastFailures.push({
+        id: k.id,
+        statement: k.statement,
+        context: k.context || {
+          positive: k.positive,
+          negative: k.negative
+        },
+        failure: k.statement,
+        lesson: k.lesson || k.reasoning || k.resolves?.[0],
+        evidence: k.evidence
+      });
+      continue;
+    }
+    const isLesson = k.type === "lesson" && (k.id.includes("lesson") || k.tags?.includes("lesson") || k.statement.toLowerCase().includes("lesson")) || k.statement.toLowerCase().startsWith("lesson:") || k.statement.toLowerCase().includes("lesson:");
+    if (isLesson) {
+      lessons.push({
+        id: k.id,
+        statement: k.statement,
+        confidence: k.confidence,
+        domain: k.tags?.[0],
+        evidence: k.evidence
+      });
+      continue;
+    }
+    if (k.status === "active" || k.stage === "active" || k.stage === "probation" || !k.status) {
+      known.push({
+        id: k.id,
+        statement: k.statement,
+        confidence: k.confidence,
+        confidenceTier: k.confidenceTier,
+        stage: k.stage
+      });
+    }
+  }
+  const unknownsFromStorage = await storage.getAllUnknowns();
+  const unknownKnowledge = allKnowledge.filter((k) => k.type === "unknown");
+  const unifiedUnknowns = [];
+  const seenUnknownIds = /* @__PURE__ */ new Set();
+  for (const u of unknownsFromStorage) {
+    seenUnknownIds.add(u.id);
+    unifiedUnknowns.push({
+      id: u.id,
+      statement: u.statement || u.id,
+      reason: u.reason,
+      question: u.question || u.next?.question,
+      next: u.next,
+      blocking: u.blocking,
+      positive: u.positive,
+      negative: u.negative,
+      checked: u.checked
+    });
+  }
+  for (const k of unknownKnowledge) {
+    if (!seenUnknownIds.has(k.id)) {
+      seenUnknownIds.add(k.id);
+      unifiedUnknowns.push({
+        id: k.id,
+        statement: k.statement,
+        reason: k.history?.[0]?.reason,
+        question: k.question || (k.statement.includes("?") ? k.statement : void 0),
+        next: {
+          type: "ask",
+          target: k.id,
+          question: k.question || k.statement
+        },
+        blocking: k.blocking,
+        positive: k.positive,
+        negative: k.negative,
+        checked: k.depends_on || k.evidence
+      });
+    }
+  }
+  const unknowns = [];
+  const missing = [];
+  const rawQuestions = [];
+  for (const u of unifiedUnknowns) {
+    const text = `${u.id} ${u.statement || ""} ${u.question || ""}`.toLowerCase();
+    const overlaps = goalTokens.some((t) => text.includes(t)) || likelyDomains.some((d) => text.includes(d)) || u.positive && u.positive.some((p) => contextualPositive.includes(p));
+    if (u.negative && u.negative.some((n) => contextualPositive.includes(n))) {
+      continue;
+    }
+    if (overlaps) {
+      const { classification, isDecision, reason } = classifyUnknown(u, goalTokens, likelyDomains);
+      const isBlocking = classification === "BLOCKING";
+      unknowns.push({
+        id: u.id,
+        statement: u.statement,
+        question: u.question || u.statement,
+        classification,
+        blocking: isBlocking,
+        reason
+      });
+      if (isDecision) {
+        missing.push({
+          type: "decision",
+          subject: u.id,
+          question: u.question || u.statement,
+          reason
+        });
+      } else {
+        missing.push({
+          type: "evidence",
+          subject: u.id,
+          question: u.question || u.statement,
+          reason
+        });
+      }
+      const qText = u.question || (u.statement && u.statement.includes("?") ? u.statement : void 0);
+      if (qText) {
+        rawQuestions.push({
+          question: qText,
+          reason: `Unknown: ${u.id} (${reason})`,
+          targetTopic: u.id,
+          isBlocking
+        });
+      }
+    }
+  }
+  const questionKnowledge = allKnowledge.filter((k) => k.type === "question");
+  for (const qk of questionKnowledge) {
+    const matchesCues = qk.positive.some((p) => contextualPositive.includes(p));
+    const conflicts = qk.negative.some((n) => negative.includes(n));
+    if (matchesCues && !conflicts && qk.question) {
+      rawQuestions.push({
+        question: qk.question,
+        reason: `Learned question for [${qk.positive.join(", ")}] uncertainty`,
+        targetTopic: qk.resolves?.[0] || qk.id,
+        outcomeScore: (qk.metrics?.successful_outcomes ?? 0) - (qk.metrics?.failed_outcomes ?? 0)
+      });
+    }
+  }
+  const questions = prioritizeQuestions(rawQuestions, unknowns);
+  const receipts = await storage.getAllReceipts();
+  const alreadyInvestigated = [];
+  const investigatedSources = /* @__PURE__ */ new Set();
+  for (const r of receipts) {
+    const qTokens = r.question.toLowerCase().split(/\s+/).filter(Boolean);
+    const overlapsGoal = qTokens.some((t) => goalTokens.includes(t));
+    const overlapsCues = r.positive && r.positive.some((p) => contextualPositive.includes(p));
+    if (overlapsGoal || overlapsCues) {
+      for (const checked of r.checked) {
+        investigatedSources.add(checked.toLowerCase());
+        alreadyInvestigated.push({
+          source: checked,
+          result: r.findings[0] || r.rejected[0]?.reason || "Did not establish requested behavior",
+          nextSuggestion: "ASK_USER"
+        });
+      }
+    }
+  }
+  let readiness = "READY";
+  const totalRelevantKnowledge = known.length + constraints.length + lessons.length + pastFailures.length + stale.length;
+  const hasBlockingUnknown = unknowns.some((u) => u.blocking);
+  const hasMissingDecision = missing.some((m) => m.type === "decision");
+  if (totalRelevantKnowledge === 0 && unknowns.length === 0) {
+    readiness = "INSUFFICIENT_KNOWLEDGE";
+  } else if (conflictedCount > 0) {
+    readiness = "CONFLICTED";
+  } else if (hasBlockingUnknown || hasMissingDecision) {
+    readiness = "NEEDS_CLARIFICATION";
+  } else if (stale.length > 0) {
+    readiness = "NEEDS_REVALIDATION";
+  } else {
+    readiness = "READY";
+  }
+  const next = [];
+  for (const m of missing) {
+    if (m.type === "decision") {
+      next.push({
+        type: "ASK_USER",
+        target: m.subject,
+        reason: m.question || m.reason,
+        relativeCost: 1,
+        expectedInfoGain: 0.95
+      });
+    }
+  }
+  for (const s of stale) {
+    next.push({
+      type: "REVALIDATE",
+      target: s.id,
+      reason: s.reason,
+      relativeCost: 2,
+      expectedInfoGain: 0.85
+    });
+  }
+  for (const m of missing) {
+    if (m.type === "evidence") {
+      const wasChecked = investigatedSources.has(m.subject.toLowerCase()) || alreadyInvestigated.length > 0;
+      if (wasChecked) {
+        if (!next.some((n) => n.type === "ASK_USER")) {
+          next.push({
+            type: "ASK_USER",
+            target: m.subject,
+            reason: `Already investigated (${Array.from(investigatedSources).join(", ")}); did not establish requested behavior. Clarification required.`,
+            relativeCost: 1,
+            expectedInfoGain: 0.9
+          });
+        }
+      } else {
+        const isFilePath = m.subject.includes("/") || m.subject.includes(".");
+        next.push({
+          type: isFilePath ? "INSPECT_FILE" : "SEARCH_REPOSITORY",
+          target: m.subject,
+          reason: m.reason,
+          relativeCost: isFilePath ? 2 : 2.5,
+          expectedInfoGain: 0.8
+        });
+      }
+    }
+  }
+  if (alreadyInvestigated.length > 0 && !next.some((n) => n.type === "ASK_USER")) {
+    next.push({
+      type: "ASK_USER",
+      target: alreadyInvestigated[0].source,
+      reason: `Already investigated ${alreadyInvestigated[0].source}; clarification required`,
+      relativeCost: 1,
+      expectedInfoGain: 0.9
+    });
+  }
+  if (next.length === 0 && known.length > 0) {
+    next.push({
+      type: "USE_KNOWLEDGE",
+      target: known[0].id,
+      reason: "Proceed with implementation using verified knowledge and constraints",
+      relativeCost: 1,
+      expectedInfoGain: 1
+    });
+  }
+  const knowledgeImpact = {
+    relevantKnowledge: totalRelevantKnowledge,
+    validated: known.filter((k) => k.confidenceTier === "high").length + constraints.length,
+    needsRevalidation: stale.length,
+    conflicted: conflictedCount,
+    blockingUnknowns: unknowns.filter((u) => u.blocking).length,
+    relevantFailures: pastFailures.length
+  };
+  const similarWork = [];
+  for (const l of lessons) {
+    similarWork.push({
+      topic: l.domain || l.id,
+      lesson: l.statement
+    });
+  }
+  for (const f of pastFailures) {
+    similarWork.push({
+      topic: f.id,
+      failure: f.statement
+    });
+  }
+  await storage.appendMetricEvent({
+    type: "preflight",
+    goal,
+    readiness,
+    blockingUnknownsCount: knowledgeImpact.blockingUnknowns,
+    staleKnowledgeCount: stale.length,
+    pastFailuresCount: pastFailures.length,
+    questionsCount: questions.length,
+    repeatedChecksAvoidedCount: alreadyInvestigated.length,
+    timestamp: Date.now()
+  });
+  return {
+    goal,
+    readiness,
+    known,
+    constraints,
+    lessons,
+    past_failures: pastFailures,
+    unknowns,
+    stale,
+    missing,
+    questions,
+    likely_domains: likelyDomains,
+    similar_work: similarWork.length > 0 ? similarWork.slice(0, 5) : void 0,
+    already_investigated: alreadyInvestigated.length > 0 ? alreadyInvestigated : void 0,
+    knowledge_impact: knowledgeImpact,
+    next
+  };
+}
+
 // src/core/knowledge.ts
 import { createHash } from "crypto";
 
@@ -2369,7 +3350,7 @@ function createKnowledge(params) {
     type: params.type ?? "lesson",
     status,
     stage: initialStage,
-    statement: params.statement.trim(),
+    statement: (params.statement ?? params.question ?? params.id).trim(),
     positive: Array.from(new Set(params.positive?.map((p) => p.trim().toLowerCase()) ?? [])),
     negative: Array.from(new Set(params.negative?.map((n) => n.trim().toLowerCase()) ?? [])),
     relations: Array.from(new Set(params.relations?.map((r) => r.trim()) ?? [])),
@@ -2399,6 +3380,11 @@ function createKnowledge(params) {
     },
     history,
     value: 0,
+    lesson: params.lesson,
+    failure_details: params.failure_details,
+    context: params.context,
+    contradicts: params.contradicts ? Array.from(new Set(params.contradicts)) : void 0,
+    blocking: params.blocking,
     createdAt: now,
     updatedAt: now
   };
@@ -3177,7 +4163,7 @@ function processUserCorrection(params) {
 }
 
 // src/scanner/engine.ts
-import * as path14 from "path";
+import * as path16 from "path";
 
 // src/core/relations.ts
 var EvidenceGraph = class _EvidenceGraph {
@@ -3268,8 +4254,8 @@ var EvidenceGraph = class _EvidenceGraph {
 };
 
 // src/scanner/filesystem.ts
-import * as fs6 from "fs/promises";
-import * as path11 from "path";
+import * as fs8 from "fs/promises";
+import * as path13 from "path";
 var DEFAULT_IGNORED_DIRS = /* @__PURE__ */ new Set([
   ".git",
   ".bilmem",
@@ -3290,12 +4276,12 @@ var DEFAULT_IGNORED_DIRS = /* @__PURE__ */ new Set([
   "temp"
 ]);
 function normalizeRelPath(rel) {
-  return rel.split(path11.sep).join("/");
+  return rel.split(path13.sep).join("/");
 }
 async function loadGitignorePatterns(rootDir) {
   try {
-    const gitignorePath = path11.join(rootDir, ".gitignore");
-    const content = await fs6.readFile(gitignorePath, "utf-8");
+    const gitignorePath = path13.join(rootDir, ".gitignore");
+    const content = await fs8.readFile(gitignorePath, "utf-8");
     const regexes = [];
     for (const rawLine of content.split("\n")) {
       const line = rawLine.trim();
@@ -3343,7 +4329,7 @@ async function walkDirectory(dir, optionsOrRoot, legacyFileList) {
       return;
     }
     try {
-      const real = await fs6.realpath(currentDir);
+      const real = await fs8.realpath(currentDir);
       if (visitedRealPaths.has(real)) {
         return;
       }
@@ -3353,14 +4339,14 @@ async function walkDirectory(dir, optionsOrRoot, legacyFileList) {
     }
     let entries;
     try {
-      entries = await fs6.readdir(currentDir, { withFileTypes: true });
+      entries = await fs8.readdir(currentDir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
       if (fileList.length >= maxFiles) break;
-      const fullPath = path11.join(currentDir, entry.name);
-      const rawRelPath = path11.relative(root, fullPath);
+      const fullPath = path13.join(currentDir, entry.name);
+      const rawRelPath = path13.relative(root, fullPath);
       const relPath = normalizeRelPath(rawRelPath);
       const lowerName = entry.name.toLowerCase();
       if (gitignoreRules.some((rule) => rule.test(relPath))) {
@@ -3376,16 +4362,16 @@ async function walkDirectory(dir, optionsOrRoot, legacyFileList) {
         if (!includeHidden && entry.name.startsWith(".") && lowerName !== ".env.example") {
           continue;
         }
-        const ext = path11.extname(entry.name).toLowerCase();
+        const ext = path13.extname(entry.name).toLowerCase();
         try {
-          const stat3 = await fs6.stat(fullPath);
+          const stat4 = await fs8.stat(fullPath);
           const fileInfo = {
             path: fullPath,
             relativePath: relPath,
             name: entry.name,
             ext,
-            size: stat3.size,
-            mtimeMs: stat3.mtimeMs,
+            size: stat4.size,
+            mtimeMs: stat4.mtimeMs,
             isDirectory: false
           };
           if (!options.filter || options.filter(fileInfo)) {
@@ -3428,9 +4414,9 @@ var ProjectContext = class {
     if (this.textCache.has(key)) {
       return this.textCache.get(key);
     }
-    const fullPath = path11.resolve(this.rootDir, relativePath);
+    const fullPath = path13.resolve(this.rootDir, relativePath);
     try {
-      const handle = await fs6.open(fullPath, "r");
+      const handle = await fs8.open(fullPath, "r");
       const buffer = Buffer.alloc(maxBytes);
       const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
       await handle.close();
@@ -3856,12 +4842,12 @@ async function analyzeProjectStructure(files, rootDir, registry = defaultRegistr
 }
 
 // src/scanner/markdown.ts
-import * as fs7 from "fs/promises";
-import * as path12 from "path";
-import YAML2 from "yaml";
+import * as fs9 from "fs/promises";
+import * as path14 from "path";
+import YAML3 from "yaml";
 function parseMarkdownDocument(content, filePath, relativePath) {
   const lines = content.split("\n");
-  const baseName = path12.basename(relativePath, ".md").toLowerCase();
+  const baseName = path14.basename(relativePath, ".md").toLowerCase();
   let frontmatter = {};
   const headings = [];
   const alerts = [];
@@ -3890,7 +4876,7 @@ function parseMarkdownDocument(content, filePath, relativePath) {
         bodyStartIndex = i + 1;
         try {
           const yamlText = frontmatterLines.join("\n");
-          const parsed = YAML2.parse(yamlText);
+          const parsed = YAML3.parse(yamlText);
           if (parsed && typeof parsed === "object") {
             frontmatter = parsed;
           }
@@ -4278,8 +5264,8 @@ var BUILTIN_MARKDOWN_EXTRACTORS = [
         if (!target.startsWith("http://") && !target.startsWith("https://") && !target.startsWith("mailto:") && (target.startsWith(".") || target.includes("/") || /\.(md|ts|js|json|ya?ml|toml|rs|go|py)$/i.test(target))) {
           const rawTarget = target.split("#")[0].split("?")[0].trim();
           if (rawTarget) {
-            const dir = path12.dirname(doc.relativePath);
-            const resolved = dir === "." || path12.isAbsolute(rawTarget) ? rawTarget.replace(/^\.\//, "") : path12.normalize(path12.join(dir, rawTarget));
+            const dir = path14.dirname(doc.relativePath);
+            const resolved = dir === "." || path14.isAbsolute(rawTarget) ? rawTarget.replace(/^\.\//, "") : path14.normalize(path14.join(dir, rawTarget));
             relations.push({
               from: doc.relativePath,
               to: resolved,
@@ -4332,7 +5318,7 @@ for (const ext of BUILTIN_MARKDOWN_EXTRACTORS) {
 async function parseMarkdownFile(filePath, relativePath, registry = defaultMarkdownRegistry) {
   let content = "";
   try {
-    content = await fs7.readFile(filePath, "utf-8");
+    content = await fs9.readFile(filePath, "utf-8");
   } catch {
     return { observations: [], relations: [] };
   }
@@ -4341,11 +5327,11 @@ async function parseMarkdownFile(filePath, relativePath, registry = defaultMarkd
 }
 
 // src/scanner/git.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile2);
 async function runGit(args, cwd) {
-  const { stdout } = await execFileAsync("git", args, {
+  const { stdout } = await execFileAsync2("git", args, {
     cwd,
     maxBuffer: 10 * 1024 * 1024
   });
@@ -4539,9 +5525,9 @@ async function scanGitHistory(cwd, options = {}) {
 }
 
 // src/scanner/source.ts
-import * as fs8 from "fs/promises";
+import * as fs10 from "fs/promises";
 import * as fsSync from "fs";
-import * as path13 from "path";
+import * as path15 from "path";
 import { createRequire } from "module";
 import Parser from "web-tree-sitter";
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
@@ -4595,7 +5581,7 @@ function getWasmDir() {
   try {
     const req = createRequire(import.meta.url);
     const pkgJson = req.resolve("tree-sitter-wasms/package.json");
-    const outDir = path13.join(path13.dirname(pkgJson), "out");
+    const outDir = path15.join(path15.dirname(pkgJson), "out");
     if (fsSync.existsSync(outDir)) {
       wasmBaseDir = outDir;
       return wasmBaseDir;
@@ -4603,8 +5589,8 @@ function getWasmDir() {
   } catch {
   }
   const candidateDirs = [
-    path13.resolve(process.cwd(), "node_modules/tree-sitter-wasms/out"),
-    path13.resolve(process.cwd(), "../node_modules/tree-sitter-wasms/out")
+    path15.resolve(process.cwd(), "node_modules/tree-sitter-wasms/out"),
+    path15.resolve(process.cwd(), "../node_modules/tree-sitter-wasms/out")
   ];
   for (const dir of candidateDirs) {
     if (fsSync.existsSync(dir)) {
@@ -4617,7 +5603,7 @@ function getWasmDir() {
 async function getParserForWasm(wasmName) {
   const wasmDir = getWasmDir();
   if (!wasmDir) return null;
-  const wasmPath = path13.join(wasmDir, wasmName);
+  const wasmPath = path15.join(wasmDir, wasmName);
   if (!fsSync.existsSync(wasmPath)) return null;
   try {
     if (!parserInitialized) {
@@ -4976,7 +5962,7 @@ async function analyzeSourceFile(filePath, relativePath) {
   const relations = [];
   let content = "";
   try {
-    content = await fs8.readFile(filePath, "utf-8");
+    content = await fs10.readFile(filePath, "utf-8");
   } catch {
     return { observations, relations };
   }
@@ -4984,8 +5970,8 @@ async function analyzeSourceFile(filePath, relativePath) {
     return { observations, relations };
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  const baseName = path13.basename(relativePath);
-  const ext = path13.extname(relativePath).toLowerCase();
+  const baseName = path15.basename(relativePath);
+  const ext = path15.extname(relativePath).toLowerCase();
   const wasmName = EXT_TO_WASM[ext];
   if (wasmName) {
     try {
@@ -5183,9 +6169,9 @@ async function scanRepository(rootDir = process.cwd(), options = {}) {
   const plannedActions = [];
   const config = dryRun ? await storage.isInitialized() ? await storage.getConfig() : {
     schemaVersion: 1,
-    projectName: path14.basename(rootDir),
+    projectName: path16.basename(rootDir),
     defaultScope: "project",
-    dataDir: path14.join(rootDir, ".bilmem")
+    dataDir: path16.join(rootDir, ".bilmem")
   } : await storage.init();
   const incremental = options.incremental ?? false;
   const lastScanCommit = incremental ? config.lastScanCommit : void 0;
@@ -5258,7 +6244,7 @@ async function scanRepository(rootDir = process.cwd(), options = {}) {
   ];
   for (const o of mdObs) {
     if (o.source.includes(":adr") || o.claim.startsWith("[WARNING]") || o.claim.startsWith("[CAUTION]")) {
-      const id = `decision.${path14.basename(o.provenance.path || "doc", ".md")}.${o.provenance.line || "adr"}`;
+      const id = `decision.${path16.basename(o.provenance.path || "doc", ".md")}.${o.provenance.line || "adr"}`;
       candidateLessons.push({
         id,
         type: "decision",
@@ -5492,8 +6478,34 @@ async function computeStats(storage, events, options) {
     }
   };
   const actions = {};
+  const preflight = {
+    runs: 0,
+    ready: 0,
+    needsClarification: 0,
+    needsRevalidation: 0,
+    conflicted: 0,
+    insufficientKnowledge: 0,
+    blockingUnknownsFound: 0,
+    staleKnowledgeFound: 0,
+    pastFailuresSurfaced: 0,
+    questionsSuggested: 0,
+    repeatedChecksAvoided: 0
+  };
   for (const e of events) {
     switch (e.type) {
+      case "preflight":
+        preflight.runs++;
+        if (e.readiness === "READY") preflight.ready++;
+        else if (e.readiness === "NEEDS_CLARIFICATION") preflight.needsClarification++;
+        else if (e.readiness === "NEEDS_REVALIDATION") preflight.needsRevalidation++;
+        else if (e.readiness === "CONFLICTED") preflight.conflicted++;
+        else if (e.readiness === "INSUFFICIENT_KNOWLEDGE") preflight.insufficientKnowledge++;
+        preflight.blockingUnknownsFound += e.blockingUnknownsCount || 0;
+        preflight.staleKnowledgeFound += e.staleKnowledgeCount || 0;
+        preflight.pastFailuresSurfaced += e.pastFailuresCount || 0;
+        preflight.questionsSuggested += e.questionsCount || 0;
+        preflight.repeatedChecksAvoided += e.repeatedChecksAvoidedCount || 0;
+        break;
       case "knowledge_created":
         learning.new++;
         break;
@@ -5664,7 +6676,8 @@ async function computeStats(storage, events, options) {
       questionResolutionRate,
       jevRejectionRate
     },
-    health
+    health,
+    preflight: preflight.runs > 0 ? preflight : void 0
   };
 }
 async function computeKnowledgeStats(storage, knowledgeId, events) {
@@ -5733,9 +6746,9 @@ async function computeKnowledgeStats(storage, knowledgeId, events) {
 }
 
 // src/stats/filter.ts
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-var execFileAsync2 = promisify2(execFile2);
+import { execFile as execFile3 } from "child_process";
+import { promisify as promisify3 } from "util";
+var execFileAsync3 = promisify3(execFile3);
 async function resolveSinceTimestamp(since, projectDir = process.cwd()) {
   const trimmed = since.trim();
   const durationMatch = trimmed.match(/^(\d+)\s*([smhdw])$/i);
@@ -5767,7 +6780,7 @@ async function resolveSinceTimestamp(since, projectDir = process.cwd()) {
     return parsedDate;
   }
   try {
-    const { stdout } = await execFileAsync2(
+    const { stdout } = await execFileAsync3(
       "git",
       ["log", "-1", "--format=%ct", trimmed],
       { cwd: projectDir }
@@ -5811,17 +6824,56 @@ async function runStats(options = {}) {
 
 // src/mcp/server.ts
 function createBilmemMcpApp(options = {}) {
-  const rootDir = options.rootDir ? path15.resolve(options.rootDir) : process.cwd();
-  const storage = new Storage(rootDir);
-  const index = new SearchIndex();
-  let initialized = false;
-  async function ensureInitialized() {
-    if (!initialized) {
-      await storage.init();
-      const all = await storage.getAllKnowledge();
-      await index.buildIndex(all);
-      initialized = true;
+  const contexts = /* @__PURE__ */ new Map();
+  let lastActiveDir = options.rootDir ? path17.resolve(options.rootDir) : null;
+  function isSystemRoot(dir) {
+    const resolved = path17.resolve(dir);
+    return resolved === "/" || path17.parse(resolved).root === resolved;
+  }
+  function resolveTargetDir(requestedPath) {
+    if (requestedPath && requestedPath.trim()) {
+      const resolved = path17.resolve(requestedPath.trim());
+      lastActiveDir = resolved;
+      return resolved;
+    }
+    if (lastActiveDir) {
+      return lastActiveDir;
+    }
+    if (process.env.BILMEM_PROJECT_DIR) {
+      const envDir = path17.resolve(process.env.BILMEM_PROJECT_DIR);
+      lastActiveDir = envDir;
+      return envDir;
+    }
+    const cwd = process.cwd();
+    if (cwd && !isSystemRoot(cwd)) {
+      lastActiveDir = cwd;
+      return cwd;
+    }
+    throw new Error(
+      `No project directory specified and the MCP server was started in system root ('/'). Please provide the 'path' parameter in your tool call (e.g. { path: "/path/to/project", ... }).`
+    );
+  }
+  async function getProjectContext(requestedPath) {
+    const targetDir = resolveTargetDir(requestedPath);
+    let ctx = contexts.get(targetDir);
+    if (!ctx) {
+      const storage = new Storage(targetDir);
+      const index = new SearchIndex();
+      ctx = {
+        rootDir: targetDir,
+        storage,
+        index,
+        initialized: false
+      };
+      contexts.set(targetDir, ctx);
     }
+    if (!ctx.initialized) {
+      await ctx.storage.init();
+      const all = await ctx.storage.getAllKnowledge();
+      await ctx.index.buildIndex(all);
+      ctx.initialized = true;
+    }
+    return ctx;
   }
   const app = new McpApp({
     name: options.name ?? "bilmem",
@@ -5831,6 +6883,7 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_resolve",
     description: "Determine if enough is known to answer or act, what contextually does not apply, what is missing, and the cheapest next step to resolve uncertainty.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       question: z.string().describe("The question, goal, or uncertainty to resolve"),
       positive: z.array(z.string()).optional().describe("Applicable context cues (e.g. server-session, node, postgres)"),
       negative: z.array(z.string()).optional().describe("Inapplicable context cues (e.g. stateless-jwt, browser, sqlite)"),
@@ -5838,8 +6891,8 @@ function createBilmemMcpApp(options = {}) {
       maxDepth: z.number().optional().describe("Max candidates to inspect (default: 5)")
     },
     handler: async (args) => {
-      await ensureInitialized();
-      const retriever = new Retriever(index, storage);
+      const ctx = await getProjectContext(args.path);
+      const retriever = new Retriever(ctx.index, ctx.storage);
       const res = await resolveEpistemicQuery(
         {
           question: args.question,
@@ -5848,7 +6901,7 @@ function createBilmemMcpApp(options = {}) {
           scope: args.scope,
           maxDepth: args.maxDepth
         },
-        storage,
+        ctx.storage,
         retriever
       );
       return {
@@ -5865,10 +6918,53 @@ function createBilmemMcpApp(options = {}) {
       };
     }
   });
+  app.tool({
+    name: "bilmem_preflight",
+    description: "Determine what must be known before beginning a proposed goal (surfaces constraints, relevant lessons, past failures, stale knowledge, and blocking unknowns).",
+    inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
+      goal: z.string().describe("The proposed goal, feature, or work to analyze before implementation"),
+      positive: z.array(z.string()).optional().describe("Applicable context cues (e.g. authentication, postgres)"),
+      negative: z.array(z.string()).optional().describe("Inapplicable context cues (e.g. browser, sqlite)"),
+      deep: z.boolean().optional().describe("Check targeted git diff / unindexed files for staleness")
+    },
+    handler: async (args) => {
+      const ctx = await getProjectContext(args.path);
+      const retriever = new Retriever(ctx.index, ctx.storage);
+      const res = await executePreflight(
+        {
+          goal: args.goal,
+          positive: args.positive,
+          negative: args.negative,
+          deep: args.deep
+        },
+        ctx.storage,
+        retriever,
+        ctx.index
+      );
+      return {
+        goal: res.goal,
+        readiness: res.readiness,
+        known: res.known.slice(0, 5).map((k) => k.statement),
+        constraints: res.constraints.map((c) => c.statement),
+        lessons: res.lessons.slice(0, 5).map((l) => l.statement),
+        pastFailures: res.past_failures.slice(0, 5).map((f) => f.statement),
+        blockingUnknowns: res.unknowns.filter((u) => u.blocking).map((u) => u.question || u.statement || u.id),
+        stale: res.stale.map((s) => s.id),
+        questions: res.questions.slice(0, 5).map((q) => q.question),
+        next: res.next.slice(0, 3).map((n) => ({
+          type: n.type,
+          target: n.target,
+          reason: n.reason
+        }))
+      };
+    }
+  });
   app.tool({
     name: "bilmem_lookup",
     description: "Lookup reusable knowledge, conventions, and lessons using JEV contextual reranking. Returns compact, highly applicable knowledge units.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       query: z.string().optional().describe("Query text, intent keywords, or problem description"),
       positive: z.array(z.string()).optional().describe("Contextual positive cues (e.g. node, esm, server-session)"),
       negative: z.array(z.string()).optional().describe("Contextual negative cues (e.g. commonjs, browser)"),
@@ -5876,8 +6972,8 @@ function createBilmemMcpApp(options = {}) {
       limit: z.number().optional().describe("Maximum number of results to return (default 5)")
     },
     handler: async (args) => {
-      await ensureInitialized();
-      const retriever = new Retriever(index, storage);
+      const ctx = await getProjectContext(args.path);
+      const retriever = new Retriever(ctx.index, ctx.storage);
       const results = await retriever.lookup({
         query: args.query,
         positive: args.positive,
@@ -5904,6 +7000,7 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_observe",
     description: "Record a new observation from code, git, test execution, or environment. Preserves provenance.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       claim: z.string().describe("What was observed"),
       source: z.string().describe("Source identifier (e.g. file:src/auth.ts#L42, git:commit:81ac23, user:correction)"),
       confidence: z.number().optional().describe("Confidence 0.0 - 1.0 (default: 0.85)"),
@@ -5912,7 +7009,7 @@ function createBilmemMcpApp(options = {}) {
       details: z.record(z.any()).optional().describe("Optional structured metadata")
     },
     handler: async (args) => {
-      await ensureInitialized();
+      const ctx = await getProjectContext(args.path);
       const obs = createObservation({
         source: args.source,
         claim: args.claim,
@@ -5926,10 +7023,10 @@ function createBilmemMcpApp(options = {}) {
         negative: args.negative,
         details: args.details
       });
-      await storage.saveObservation(obs);
+      await ctx.storage.saveObservation(obs);
       const evidence = createEvidence(obs, "supports");
-      await storage.saveEvidence(evidence);
-      const existing = await storage.getAllKnowledge();
+      await ctx.storage.saveEvidence(evidence);
+      const existing = await ctx.storage.getAllKnowledge();
       const rec = reconcileKnowledge(
         {
           statement: obs.claim,
@@ -5950,10 +7047,10 @@ function createBilmemMcpApp(options = {}) {
           evidence: [evidence.id, obs.source]
         },
         existing,
-        storage
+        ctx.storage
       );
-      await storage.saveKnowledge(updatedKnowledge);
-      await index.upsert(updatedKnowledge);
+      await ctx.storage.saveKnowledge(updatedKnowledge);
+      await ctx.index.upsert(updatedKnowledge);
       return {
         observationId: obs.id,
         evidenceId: evidence.id,
@@ -5967,6 +7064,7 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_learn",
     description: "Learn from a completed task trajectory or explicit user correction. Converts experiences into refined, reusable lessons.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       goal: z.string().describe("The task or goal that was pursued"),
       taskId: z.string().optional().describe("Task identifier"),
       outcome: z.enum(["success", "failure", "reverted", "neutral"]).describe("Outcome of the task"),
@@ -5982,16 +7080,16 @@ function createBilmemMcpApp(options = {}) {
       }).optional().describe("Explicit user correction, if any occurred")
     },
     handler: async (args) => {
-      await ensureInitialized();
+      const ctx = await getProjectContext(args.path);
       if (args.userCorrection) {
         const { observation, knowledge } = processUserCorrection(args.userCorrection);
-        await storage.saveObservation(observation);
-        await storage.saveEvidence(createEvidence(observation, "supports"));
-        const existing = await storage.getAllKnowledge();
+        await ctx.storage.saveObservation(observation);
+        await ctx.storage.saveEvidence(createEvidence(observation, "supports"));
+        const existing = await ctx.storage.getAllKnowledge();
         const rec = reconcileKnowledge(knowledge, existing);
-        const { updatedKnowledge } = applyReconciliation(rec, knowledge, existing, storage);
-        await storage.saveKnowledge(updatedKnowledge);
-        await index.upsert(updatedKnowledge);
+        const { updatedKnowledge } = applyReconciliation(rec, knowledge, existing, ctx.storage);
+        await ctx.storage.saveKnowledge(updatedKnowledge);
+        await ctx.index.upsert(updatedKnowledge);
         return {
           type: "user_correction",
           knowledgeId: updatedKnowledge.id,
@@ -6007,20 +7105,20 @@ function createBilmemMcpApp(options = {}) {
           startedAt: (/* @__PURE__ */ new Date()).toISOString(),
           finalOutcome: args.outcome
         };
-        const existing = await storage.getAllKnowledge();
+        const existing = await ctx.storage.getAllKnowledge();
         const learningResult = learnFromTrajectory(trajectory, existing);
         for (const obs of learningResult.observations) {
-          await storage.saveObservation(obs);
+          await ctx.storage.saveObservation(obs);
         }
         for (const ev of learningResult.evidence) {
-          await storage.saveEvidence(ev);
+          await ctx.storage.saveEvidence(ev);
         }
         let updatedKnowledge;
         let action = "NEW";
         for (const item of learningResult.reconciliations) {
           if (item.appliedKnowledge) {
-            await storage.saveKnowledge(item.appliedKnowledge);
-            await index.upsert(item.appliedKnowledge);
+            await ctx.storage.saveKnowledge(item.appliedKnowledge);
+            await ctx.index.upsert(item.appliedKnowledge);
             updatedKnowledge = item.appliedKnowledge;
             action = item.action;
           }
@@ -6032,9 +7130,9 @@ function createBilmemMcpApp(options = {}) {
             result: args.outcome,
             context: { positive: updatedKnowledge.positive, negative: updatedKnowledge.negative }
           });
-          await storage.appendOutcome(out);
+          await ctx.storage.appendOutcome(out);
           applyOutcomeToKnowledge(updatedKnowledge, out);
-          await storage.saveKnowledge(updatedKnowledge);
+          await ctx.storage.saveKnowledge(updatedKnowledge);
           return {
             type: "trajectory_lesson",
             action,
@@ -6056,12 +7154,13 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_explain",
     description: "Explain why a knowledge ID exists: statement, evidence provenance, confidence, support/contradiction history, and applicable context.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       id: z.string().describe("The knowledge ID to explain"),
       history: z.boolean().optional().describe("Whether to format lifecycle transition history (--history)")
     },
     handler: async (args) => {
-      await ensureInitialized();
-      const k = await storage.getKnowledge(args.id);
+      const ctx = await getProjectContext(args.path);
+      const k = await ctx.storage.getKnowledge(args.id);
       if (!k) {
         return { error: `Knowledge not found: "${args.id}"` };
       }
@@ -6095,6 +7194,7 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_unknown",
     description: "Query or record first-class unknowns (NOT_OBSERVED, INSUFFICIENT_EVIDENCE, CONFLICTING_EVIDENCE, UNRESOLVABLE_LOCALLY) to prevent repeating useless investigations.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       action: z.enum(["query", "check", "record", "resolve"]).describe("Action to perform"),
       id: z.string().optional().describe("Unknown ID or query subject"),
       reason: z.enum(["NOT_OBSERVED", "INSUFFICIENT_EVIDENCE", "CONFLICTING_EVIDENCE", "STALE", "UNRESOLVABLE_LOCALLY"]).optional(),
@@ -6103,16 +7203,16 @@ function createBilmemMcpApp(options = {}) {
       question: z.string().optional().describe("Clarifying question for the user or next agent")
     },
     handler: async (args) => {
-      await ensureInitialized();
+      const ctx = await getProjectContext(args.path);
       if (args.action === "query") {
-        const list = await storage.getAllUnknowns();
+        const list = await ctx.storage.getAllUnknowns();
         return {
           count: list.length,
           unknowns: list
         };
       }
       if (args.action === "check") {
-        const list = await storage.getAllUnknowns();
+        const list = await ctx.storage.getAllUnknowns();
         const checkResult = hasBeenInvestigated(list, args.id || "");
         return checkResult;
       }
@@ -6126,12 +7226,12 @@ function createBilmemMcpApp(options = {}) {
           checked: args.checked ?? [],
           next: args.question ? { type: "ask", question: args.question } : void 0
         });
-        await storage.saveUnknown(record);
+        await ctx.storage.saveUnknown(record);
         return { success: true, recorded: record };
       }
       if (args.action === "resolve") {
         if (!args.id) throw new Error("ID is required to resolve an unknown");
-        const deleted = await storage.deleteUnknown(args.id);
+        const deleted = await ctx.storage.deleteUnknown(args.id);
         return { success: deleted, resolvedId: args.id };
       }
       return { error: "Unknown action" };
@@ -6141,16 +7241,16 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_scan",
     description: "Trigger a language-independent scan of the repository filesystem, markdown documentation, and git history.",
     inputSchema: {
-      path: z.string().optional().describe("Root directory to scan (defaults to project root)"),
+      path: z.string().optional().describe("Project root directory to scan (defaults to active workspace or current working directory)"),
       incremental: z.boolean().optional().describe("Whether to scan incrementally from last scanned git commit")
     },
     handler: async (args) => {
-      const targetDir = args.path ? path15.resolve(args.path) : rootDir;
-      const report = await scanRepository(targetDir, {
+      const ctx = await getProjectContext(args.path);
+      const report = await scanRepository(ctx.rootDir, {
         incremental: args.incremental ?? false
       });
-      const all = await storage.getAllKnowledge();
-      await index.buildIndex(all);
+      const all = await ctx.storage.getAllKnowledge();
+      await ctx.index.buildIndex(all);
       return report;
     }
   });
@@ -6158,13 +7258,14 @@ function createBilmemMcpApp(options = {}) {
     name: "bilmem_stats",
     description: "Inspect local-first statistics, knowledge health, and effectiveness metrics (measuring reuse, investigation avoidance, and JEV accuracy). Read-only.",
     inputSchema: {
+      path: z.string().optional().describe("Project root directory (defaults to active workspace or current working directory)"),
       since: z.string().optional().describe("Time window (e.g. 24h, 7d, 30d) or Git revision (e.g. HEAD~20, commit-sha)"),
       knowledgeId: z.string().optional().describe("Specific knowledge ID to inspect single-item lifecycle and diagnostics")
     },
     handler: async (args) => {
-      await ensureInitialized();
+      const ctx = await getProjectContext(args.path);
       const res = await runStats({
-        rootDir,
+        rootDir: ctx.rootDir,
         since: args.since,
         knowledgeId: args.knowledgeId
       });
@@ -6269,6 +7370,26 @@ async function runDoctor(context) {
         canFix = true;
       }
     }
+    let skillStatus = "none";
+    let skillDetails;
+    if (state.skillPath) {
+      if (state.skillInstalled) {
+        if (state.skillVersion === CURRENT_INTEGRATION_VERSION) {
+          skillStatus = "ok";
+        } else {
+          skillStatus = "outdated";
+          skillDetails = `Version ${state.skillVersion || "legacy"} (current: ${CURRENT_INTEGRATION_VERSION})`;
+          issuesCount++;
+          canFix = true;
+        }
+      } else {
+        skillStatus = "missing";
+        if (state.detected) {
+          issuesCount++;
+          canFix = true;
+        }
+      }
+    }
     let cmdStatus = "ok";
     let cmdDetails;
     if (!commandResolvable) {
@@ -6282,9 +7403,11 @@ async function runDoctor(context) {
       scope: context.scope,
       mcp: { status: mcpStatus, details: mcpDetails },
       instructions: { status: instStatus, details: instDetails },
+      skill: state.skillPath ? { status: skillStatus, details: skillDetails } : void 0,
       command: { status: cmdStatus, details: cmdDetails },
       configPath: state.configPath,
-      instructionPath: state.instructionPath
+      instructionPath: state.instructionPath,
+      skillPath: state.skillPath
     });
   }
   if (!core.storage.initialized) {
@@ -6304,18 +7427,19 @@ async function runDoctorFix(context, dryRun = false) {
   const agentsFixed = {};
   if (!await storage.isInitialized()) {
     if (!dryRun) {
-      await storage.init({ projectName: path16.basename(context.projectDir) });
+      await storage.init({ projectName: path18.basename(context.projectDir) });
     }
     coreFixed.push("Initialized .bilmem/ storage repository");
   }
   const adapters2 = getAllAdapters();
   for (const adapter of adapters2) {
     const state = await adapter.inspect(context);
-    const shouldFix = state.detected || state.mcpConfigured || state.instructionInstalled;
+    const shouldFix = state.detected || state.mcpConfigured || state.instructionInstalled || Boolean(state.skillInstalled);
     if (!shouldFix) continue;
     const needsMcpFix = !state.mcpConfigured || !state.mcpCommandMatches;
     const needsInstFix = !state.instructionInstalled || state.instructionVersion !== CURRENT_INTEGRATION_VERSION;
-    if (needsMcpFix || needsInstFix) {
+    const needsSkillFix = Boolean(state.skillPath) && (!state.skillInstalled || state.skillVersion !== CURRENT_INTEGRATION_VERSION);
+    if (needsMcpFix || needsInstFix || needsSkillFix) {
       const fixResult = await adapter.install(context, {
         scope: context.scope,
         dryRun
@@ -6422,6 +7546,10 @@ function formatDoctorReport(report) {
       lines.push(`  MCP           ${mcpMark}${agent.mcp.details ? ` (${agent.mcp.details})` : ""}`);
       const instMark = agent.instructions.status === "ok" ? "\u2713" : agent.instructions.status === "outdated" ? "!" : agent.instructions.status === "missing" ? "\u2717" : "\u25CB";
       lines.push(`  Instructions  ${instMark}${agent.instructions.details ? ` (${agent.instructions.details})` : ""}`);
+      if (agent.skillPath) {
+        const skillMark = agent.skill?.status === "ok" ? "\u2713" : agent.skill?.status === "outdated" ? "!" : agent.skill?.status === "missing" ? "\u2717" : "\u25CB";
+        lines.push(`  Skill         ${skillMark}${agent.skill?.details ? ` (${agent.skill?.details})` : ""}`);
+      }
       const cmdMark = agent.command.status === "ok" ? "\u2713" : "!";
       lines.push(`  Connection    ${cmdMark}${agent.command.details ? ` (${agent.command.details})` : ""}`);
     }
@@ -6466,7 +7594,7 @@ function formatDoctorFixResult(fixed) {
 
 // src/install/index.ts
 function createInstallContext(options) {
-  const projectDir = path17.resolve(options.projectDir || process.cwd());
+  const projectDir = path19.resolve(options.projectDir || process.cwd());
   const scope = options.global || options.scope === "global" ? "global" : "project";
   return {
     projectDir,
@@ -6487,7 +7615,7 @@ async function handleInstallCommand(target, options = {}) {
   if (target) {
     const adapter = getAdapter(target);
     if (!adapter) {
-      const valid = getAllAdapters().map((a) => a.id).join(", ");
+      const valid = [...getAllAdapters().map((a) => a.id), "gemini"].join(", ");
       throw new Error(`Unknown agent/editor target "${target}". Supported targets: ${valid}`);
     }
     const result = await adapter.install(context, installOptions);
@@ -6569,7 +7697,7 @@ async function handleUninstallCommand(target, options = {}) {
   const context = createInstallContext(options);
   const adapter = getAdapter(target);
   if (!adapter) {
-    const valid = getAllAdapters().map((a) => a.id).join(", ");
+    const valid = [...getAllAdapters().map((a) => a.id), "gemini"].join(", ");
     throw new Error(`Unknown agent/editor target "${target}". Supported targets: ${valid}`);
   }
   const uninstallOptions = {
@@ -6590,6 +7718,7 @@ async function handleDoctorCommand(options = {}) {
   return { report };
 }
 export {
+  AntigravityAdapter,
   BILMEM_END_MARKER,
   BILMEM_START_MARKER,
   BaseAgentAdapter,
@@ -6601,6 +7730,7 @@ export {
   createInstallContext,
   detectAgents,
   extractInstructionVersion,
+  extractSkillVersion,
   formatDoctorFixResult,
   formatDoctorReport,
   formatInstallResult,
@@ -6608,12 +7738,14 @@ export {
   getAdapter,
   getAgentInstructionText,
   getAllAdapters,
+  getBilmemSkillContent,
   getIntegrationRecord,
   getIntegrationsFilePath,
   handleDoctorCommand,
   handleInstallCommand,
   handleUninstallCommand,
   hasBilmemInstruction,
+  hasBilmemSkill,
   isExecutableInPath,
   loadIntegrationsMetadata,
   pathExists,
@@ -6621,12 +7753,14 @@ export {
   removeIntegration,
   removeMarkdownInstructionFile,
   removeMcpJsonConfig,
+  removeSkillFile,
   runDoctor,
   runDoctorFix,
   safeReadJson,
   saveIntegrationsMetadata,
   updateMarkdownInstructionFile,
   updateMcpJsonConfig,
+  updateSkillFile,
   writeAtomic
 };
 //# sourceMappingURL=index.js.map