bilmem 0.1.0 → 0.2.0

package/dist/cli/index.js

@@ -2,9 +2,9 @@
 
 // src/cli/index.ts
 import { Command } from "commander";
-import * as path18 from "path";
-import * as fs9 from "fs/promises";
-import YAML4 from "yaml";
+import * as path20 from "path";
+import * as fs11 from "fs/promises";
+import YAML5 from "yaml";
 
 // src/storage/canonical.ts
 import * as fs3 from "fs/promises";
@@ -1236,6 +1236,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,
@@ -1576,8 +1577,700 @@ async function resolveEpistemicQuery(options, storage, retriever) {
   };
 }
 
+// src/core/preflight.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import * as path4 from "path";
+import * as fs4 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() ? path4.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() ? path4.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 = path4.isAbsolute(cleanPath) ? cleanPath : path4.resolve(rootDir, cleanPath);
+      try {
+        const stat5 = await fs4.stat(absPath);
+        if (stat5.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
+  };
+}
+function formatPreflightReport(result) {
+  const plainObject = {
+    goal: result.goal,
+    readiness: result.readiness
+  };
+  if (result.known.length > 0) {
+    plainObject.known = result.known.map((k) => ({
+      id: k.id,
+      statement: k.statement,
+      confidence: k.confidenceTier || (typeof k.confidence === "number" ? k.confidence >= 0.9 ? "high" : k.confidence >= 0.7 ? "medium" : "low" : k.confidence)
+    }));
+  }
+  if (result.constraints.length > 0) {
+    plainObject.constraints = result.constraints.map((c) => ({
+      id: c.id,
+      statement: c.statement
+    }));
+  }
+  if (result.lessons.length > 0) {
+    plainObject.lessons = result.lessons.map((l) => ({
+      id: l.id,
+      statement: l.statement
+    }));
+  }
+  if (result.past_failures.length > 0) {
+    plainObject.past_failures = result.past_failures.map((f) => ({
+      id: f.id,
+      statement: f.statement
+    }));
+  }
+  if (result.unknowns.length > 0) {
+    plainObject.unknowns = result.unknowns.map((u) => ({
+      id: u.id,
+      question: u.question || u.statement,
+      blocking: u.blocking
+    }));
+  }
+  if (result.stale.length > 0) {
+    plainObject.stale = result.stale.map((s) => ({
+      id: s.id,
+      reason: s.reason
+    }));
+  }
+  if (result.questions.length > 0) {
+    plainObject.questions = result.questions.map((q) => ({
+      question: q.question,
+      reason: q.reason
+    }));
+  }
+  if (result.likely_domains.length > 0) {
+    plainObject.likely_domains = result.likely_domains;
+  }
+  if (result.already_investigated && result.already_investigated.length > 0) {
+    plainObject.already_investigated = result.already_investigated;
+  }
+  if (result.next.length > 0) {
+    plainObject.next = result.next.map((n) => ({
+      type: n.type,
+      target: n.target,
+      reason: n.reason
+    }));
+  }
+  return YAML2.stringify(plainObject);
+}
+
 // src/scanner/engine.ts
-import * as path7 from "path";
+import * as path8 from "path";
 
 // src/core/knowledge.ts
 import { createHash } from "crypto";
@@ -1725,7 +2418,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()) ?? [])),
@@ -1755,6 +2448,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
   };
@@ -2402,8 +3100,8 @@ var EvidenceGraph = class _EvidenceGraph {
 };
 
 // src/scanner/filesystem.ts
-import * as fs4 from "fs/promises";
-import * as path4 from "path";
+import * as fs5 from "fs/promises";
+import * as path5 from "path";
 var DEFAULT_IGNORED_DIRS = /* @__PURE__ */ new Set([
   ".git",
   ".bilmem",
@@ -2424,12 +3122,12 @@ var DEFAULT_IGNORED_DIRS = /* @__PURE__ */ new Set([
   "temp"
 ]);
 function normalizeRelPath(rel) {
-  return rel.split(path4.sep).join("/");
+  return rel.split(path5.sep).join("/");
 }
 async function loadGitignorePatterns(rootDir) {
   try {
-    const gitignorePath = path4.join(rootDir, ".gitignore");
-    const content = await fs4.readFile(gitignorePath, "utf-8");
+    const gitignorePath = path5.join(rootDir, ".gitignore");
+    const content = await fs5.readFile(gitignorePath, "utf-8");
     const regexes = [];
     for (const rawLine of content.split("\n")) {
       const line = rawLine.trim();
@@ -2477,7 +3175,7 @@ async function walkDirectory(dir, optionsOrRoot, legacyFileList) {
       return;
     }
     try {
-      const real = await fs4.realpath(currentDir);
+      const real = await fs5.realpath(currentDir);
       if (visitedRealPaths.has(real)) {
         return;
       }
@@ -2487,14 +3185,14 @@ async function walkDirectory(dir, optionsOrRoot, legacyFileList) {
     }
     let entries;
     try {
-      entries = await fs4.readdir(currentDir, { withFileTypes: true });
+      entries = await fs5.readdir(currentDir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
       if (fileList.length >= maxFiles) break;
-      const fullPath = path4.join(currentDir, entry.name);
-      const rawRelPath = path4.relative(root, fullPath);
+      const fullPath = path5.join(currentDir, entry.name);
+      const rawRelPath = path5.relative(root, fullPath);
       const relPath = normalizeRelPath(rawRelPath);
       const lowerName = entry.name.toLowerCase();
       if (gitignoreRules.some((rule) => rule.test(relPath))) {
@@ -2510,16 +3208,16 @@ async function walkDirectory(dir, optionsOrRoot, legacyFileList) {
         if (!includeHidden && entry.name.startsWith(".") && lowerName !== ".env.example") {
           continue;
         }
-        const ext = path4.extname(entry.name).toLowerCase();
+        const ext = path5.extname(entry.name).toLowerCase();
         try {
-          const stat4 = await fs4.stat(fullPath);
+          const stat5 = await fs5.stat(fullPath);
           const fileInfo = {
             path: fullPath,
             relativePath: relPath,
             name: entry.name,
             ext,
-            size: stat4.size,
-            mtimeMs: stat4.mtimeMs,
+            size: stat5.size,
+            mtimeMs: stat5.mtimeMs,
             isDirectory: false
           };
           if (!options.filter || options.filter(fileInfo)) {
@@ -2562,9 +3260,9 @@ var ProjectContext = class {
     if (this.textCache.has(key)) {
       return this.textCache.get(key);
     }
-    const fullPath = path4.resolve(this.rootDir, relativePath);
+    const fullPath = path5.resolve(this.rootDir, relativePath);
     try {
-      const handle = await fs4.open(fullPath, "r");
+      const handle = await fs5.open(fullPath, "r");
       const buffer = Buffer.alloc(maxBytes);
       const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
       await handle.close();
@@ -2990,12 +3688,12 @@ async function analyzeProjectStructure(files, rootDir, registry = defaultRegistr
 }
 
 // src/scanner/markdown.ts
-import * as fs5 from "fs/promises";
-import * as path5 from "path";
-import YAML2 from "yaml";
+import * as fs6 from "fs/promises";
+import * as path6 from "path";
+import YAML3 from "yaml";
 function parseMarkdownDocument(content, filePath, relativePath) {
   const lines = content.split("\n");
-  const baseName = path5.basename(relativePath, ".md").toLowerCase();
+  const baseName = path6.basename(relativePath, ".md").toLowerCase();
   let frontmatter = {};
   const headings = [];
   const alerts = [];
@@ -3024,7 +3722,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;
           }
@@ -3412,8 +4110,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 = path5.dirname(doc.relativePath);
-            const resolved = dir === "." || path5.isAbsolute(rawTarget) ? rawTarget.replace(/^\.\//, "") : path5.normalize(path5.join(dir, rawTarget));
+            const dir = path6.dirname(doc.relativePath);
+            const resolved = dir === "." || path6.isAbsolute(rawTarget) ? rawTarget.replace(/^\.\//, "") : path6.normalize(path6.join(dir, rawTarget));
             relations.push({
               from: doc.relativePath,
               to: resolved,
@@ -3466,7 +4164,7 @@ for (const ext of BUILTIN_MARKDOWN_EXTRACTORS) {
 async function parseMarkdownFile(filePath, relativePath, registry = defaultMarkdownRegistry) {
   let content = "";
   try {
-    content = await fs5.readFile(filePath, "utf-8");
+    content = await fs6.readFile(filePath, "utf-8");
   } catch {
     return { observations: [], relations: [] };
   }
@@ -3475,11 +4173,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
   });
@@ -3673,9 +4371,9 @@ async function scanGitHistory(cwd, options = {}) {
 }
 
 // src/scanner/source.ts
-import * as fs6 from "fs/promises";
+import * as fs7 from "fs/promises";
 import * as fsSync from "fs";
-import * as path6 from "path";
+import * as path7 from "path";
 import { createRequire } from "module";
 import Parser from "web-tree-sitter";
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
@@ -3729,7 +4427,7 @@ function getWasmDir() {
   try {
     const req = createRequire(import.meta.url);
     const pkgJson = req.resolve("tree-sitter-wasms/package.json");
-    const outDir = path6.join(path6.dirname(pkgJson), "out");
+    const outDir = path7.join(path7.dirname(pkgJson), "out");
     if (fsSync.existsSync(outDir)) {
       wasmBaseDir = outDir;
       return wasmBaseDir;
@@ -3737,8 +4435,8 @@ function getWasmDir() {
   } catch {
   }
   const candidateDirs = [
-    path6.resolve(process.cwd(), "node_modules/tree-sitter-wasms/out"),
-    path6.resolve(process.cwd(), "../node_modules/tree-sitter-wasms/out")
+    path7.resolve(process.cwd(), "node_modules/tree-sitter-wasms/out"),
+    path7.resolve(process.cwd(), "../node_modules/tree-sitter-wasms/out")
   ];
   for (const dir of candidateDirs) {
     if (fsSync.existsSync(dir)) {
@@ -3751,7 +4449,7 @@ function getWasmDir() {
 async function getParserForWasm(wasmName) {
   const wasmDir = getWasmDir();
   if (!wasmDir) return null;
-  const wasmPath = path6.join(wasmDir, wasmName);
+  const wasmPath = path7.join(wasmDir, wasmName);
   if (!fsSync.existsSync(wasmPath)) return null;
   try {
     if (!parserInitialized) {
@@ -4110,7 +4808,7 @@ async function analyzeSourceFile(filePath, relativePath) {
   const relations = [];
   let content = "";
   try {
-    content = await fs6.readFile(filePath, "utf-8");
+    content = await fs7.readFile(filePath, "utf-8");
   } catch {
     return { observations, relations };
   }
@@ -4118,8 +4816,8 @@ async function analyzeSourceFile(filePath, relativePath) {
     return { observations, relations };
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  const baseName = path6.basename(relativePath);
-  const ext = path6.extname(relativePath).toLowerCase();
+  const baseName = path7.basename(relativePath);
+  const ext = path7.extname(relativePath).toLowerCase();
   const wasmName = EXT_TO_WASM[ext];
   if (wasmName) {
     try {
@@ -4317,9 +5015,9 @@ async function scanRepository(rootDir = process.cwd(), options = {}) {
   const plannedActions = [];
   const config = dryRun ? await storage.isInitialized() ? await storage.getConfig() : {
     schemaVersion: 1,
-    projectName: path7.basename(rootDir),
+    projectName: path8.basename(rootDir),
     defaultScope: "project",
-    dataDir: path7.join(rootDir, ".bilmem")
+    dataDir: path8.join(rootDir, ".bilmem")
   } : await storage.init();
   const incremental = options.incremental ?? false;
   const lastScanCommit = incremental ? config.lastScanCommit : void 0;
@@ -4392,7 +5090,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.${path7.basename(o.provenance.path || "doc", ".md")}.${o.provenance.line || "adr"}`;
+      const id = `decision.${path8.basename(o.provenance.path || "doc", ".md")}.${o.provenance.line || "adr"}`;
       candidateLessons.push({
         id,
         type: "decision",
@@ -4696,7 +5394,7 @@ function processUserCorrection(params) {
 }
 
 // src/storage/portable.ts
-import YAML3 from "yaml";
+import YAML4 from "yaml";
 function exportKnowledgeToYaml(items, options = {}) {
   let filtered = items;
   if (options.scope) {
@@ -4727,10 +5425,10 @@ function exportKnowledgeToYaml(items, options = {}) {
       }
     }))
   };
-  return YAML3.stringify(payload, { indent: 2, lineWidth: 100 });
+  return YAML4.stringify(payload, { indent: 2, lineWidth: 100 });
 }
 async function importKnowledgeFromYaml(yamlContent, storage) {
-  const parsed = YAML3.parse(yamlContent);
+  const parsed = YAML4.parse(yamlContent);
   if (!parsed || typeof parsed !== "object") {
     throw new Error("Invalid YAML: root must be an object");
   }
@@ -4789,10 +5487,10 @@ async function dumpToYaml(storage) {
     relations,
     metrics
   };
-  return YAML3.stringify(dump, { indent: 2, lineWidth: 120 });
+  return YAML4.stringify(dump, { indent: 2, lineWidth: 120 });
 }
 async function restoreFromYaml(yamlContent, storage) {
-  const parsed = YAML3.parse(yamlContent);
+  const parsed = YAML4.parse(yamlContent);
   if (!parsed || parsed.schemaVersion !== 1) {
     throw new Error(`Unsupported snapshot schema version: ${parsed?.schemaVersion}`);
   }
@@ -4952,7 +5650,7 @@ async function compact(storage, options = {}) {
 
 // src/mcp/server.ts
 import { McpApp, z } from "mcponce";
-import * as path8 from "path";
+import * as path9 from "path";
 
 // src/core/outcome.ts
 function createOutcome(params) {
@@ -5104,8 +5802,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;
@@ -5276,7 +6000,8 @@ async function computeStats(storage, events, options) {
       questionResolutionRate,
       jevRejectionRate
     },
-    health
+    health,
+    preflight: preflight.runs > 0 ? preflight : void 0
   };
 }
 async function computeKnowledgeStats(storage, knowledgeId, events) {
@@ -5345,9 +6070,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);
@@ -5379,7 +6104,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 }
@@ -5475,6 +6200,23 @@ function formatStatsReport(report) {
   lines.push(padRow("Frequently rejected", report.health.frequentlyRejected));
   lines.push(padRow("Frequently misleading", report.health.frequentlyMisleading));
   lines.push(padRow("Unused", report.health.unused));
+  if (report.preflight && report.preflight.runs > 0) {
+    lines.push("");
+    lines.push("Preflight");
+    lines.push(padRow("Runs", report.preflight.runs));
+    lines.push(padRow("Ready", report.preflight.ready));
+    lines.push(padRow("Needs clarification", report.preflight.needsClarification));
+    lines.push(padRow("Needs revalidation", report.preflight.needsRevalidation));
+    lines.push(padRow("Conflicted", report.preflight.conflicted));
+    lines.push(padRow("Insufficient knowledge", report.preflight.insufficientKnowledge));
+    lines.push("");
+    lines.push("Before implementation");
+    lines.push(padRow("Blocking unknowns found", report.preflight.blockingUnknownsFound));
+    lines.push(padRow("Stale knowledge found", report.preflight.staleKnowledgeFound));
+    lines.push(padRow("Past failures surfaced", report.preflight.pastFailuresSurfaced));
+    lines.push(padRow("Questions suggested", report.preflight.questionsSuggested));
+    lines.push(padRow("Repeated checks avoided", report.preflight.repeatedChecksAvoided));
+  }
   return lines.join("\n");
 }
 function formatKnowledgeStatsReport(report) {
@@ -5544,17 +6286,56 @@ async function runStats(options = {}) {
 
 // src/mcp/server.ts
 function createBilmemMcpApp(options = {}) {
-  const rootDir = options.rootDir ? path8.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 ? path9.resolve(options.rootDir) : null;
+  function isSystemRoot(dir) {
+    const resolved = path9.resolve(dir);
+    return resolved === "/" || path9.parse(resolved).root === resolved;
+  }
+  function resolveTargetDir(requestedPath) {
+    if (requestedPath && requestedPath.trim()) {
+      const resolved = path9.resolve(requestedPath.trim());
+      lastActiveDir = resolved;
+      return resolved;
+    }
+    if (lastActiveDir) {
+      return lastActiveDir;
+    }
+    if (process.env.BILMEM_PROJECT_DIR) {
+      const envDir = path9.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",
@@ -5564,6 +6345,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)"),
@@ -5571,8 +6353,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,
@@ -5581,7 +6363,7 @@ function createBilmemMcpApp(options = {}) {
           scope: args.scope,
           maxDepth: args.maxDepth
         },
-        storage,
+        ctx.storage,
         retriever
       );
       return {
@@ -5598,10 +6380,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)"),
@@ -5609,8 +6434,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,
@@ -5637,6 +6462,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)"),
@@ -5645,7 +6471,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,
@@ -5659,10 +6485,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,
@@ -5683,10 +6509,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,
@@ -5700,6 +6526,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"),
@@ -5715,16 +6542,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,
@@ -5740,20 +6567,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;
           }
@@ -5765,9 +6592,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,
@@ -5789,12 +6616,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}"` };
       }
@@ -5828,6 +6656,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(),
@@ -5836,16 +6665,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;
       }
@@ -5859,12 +6688,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" };
@@ -5874,16 +6703,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 ? path8.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;
     }
   });
@@ -5891,13 +6720,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
       });
@@ -5911,20 +6741,20 @@ function createBilmemMcpApp(options = {}) {
 }
 
 // src/install/index.ts
-import * as path17 from "path";
+import * as path19 from "path";
 import * as readline from "readline/promises";
 
 // src/install/adapters/cursor.ts
-import * as path12 from "path";
+import * as path13 from "path";
 import * as os from "os";
 
 // src/install/adapters/base.ts
-import * as path11 from "path";
-import * as fs8 from "fs/promises";
+import * as path12 from "path";
+import * as fs9 from "fs/promises";
 
 // src/install/atomic.ts
-import * as fs7 from "fs/promises";
-import * as path9 from "path";
+import * as fs8 from "fs/promises";
+import * as path10 from "path";
 
 // src/install/instructions.ts
 var CURRENT_INTEGRATION_VERSION = 1;
@@ -5936,6 +6766,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,
@@ -5959,18 +6791,171 @@ 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) {
-  const dir = path9.dirname(filePath);
-  await fs7.mkdir(dir, { recursive: true });
+  const dir = path10.dirname(filePath);
+  await fs8.mkdir(dir, { recursive: true });
   const tmpPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
   try {
-    await fs7.writeFile(tmpPath, content, "utf-8");
-    await fs7.rename(tmpPath, filePath);
+    await fs8.writeFile(tmpPath, content, "utf-8");
+    await fs8.rename(tmpPath, filePath);
   } catch (err) {
     try {
-      await fs7.unlink(tmpPath);
+      await fs8.unlink(tmpPath);
     } catch {
     }
     throw err;
@@ -5978,7 +6963,7 @@ async function writeAtomic(filePath, content) {
 }
 async function safeReadJson(filePath) {
   try {
-    const raw = await fs7.readFile(filePath, "utf-8");
+    const raw = await fs8.readFile(filePath, "utf-8");
     try {
       const data = JSON.parse(raw);
       return { exists: true, data, raw };
@@ -6058,7 +7043,7 @@ async function updateMarkdownInstructionFile(filePath, desiredBlock = getAgentIn
   let existingContent = "";
   let exists = false;
   try {
-    existingContent = await fs7.readFile(filePath, "utf-8");
+    existingContent = await fs8.readFile(filePath, "utf-8");
     exists = true;
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
@@ -6093,7 +7078,7 @@ async function updateMarkdownInstructionFile(filePath, desiredBlock = getAgentIn
 async function removeMarkdownInstructionFile(filePath, dryRun = false) {
   let content = "";
   try {
-    content = await fs7.readFile(filePath, "utf-8");
+    content = await fs8.readFile(filePath, "utf-8");
   } catch (err) {
     if (err.code === "ENOENT") {
       return { removed: false, fileDeleted: false };
@@ -6108,7 +7093,7 @@ async function removeMarkdownInstructionFile(filePath, dryRun = false) {
   if (stripped.length === 0) {
     if (!dryRun) {
       try {
-        await fs7.unlink(filePath);
+        await fs8.unlink(filePath);
       } catch {
       }
     }
@@ -6121,21 +7106,57 @@ async function removeMarkdownInstructionFile(filePath, dryRun = false) {
 }
 async function pathExists(p) {
   try {
-    await fs7.access(p);
+    await fs8.access(p);
     return true;
   } catch {
     return false;
   }
 }
+async function updateSkillFile(filePath, content, dryRun = false) {
+  let existingContent = "";
+  let exists = false;
+  try {
+    existingContent = await fs8.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 fs8.access(filePath);
+  } catch {
+    return { removed: false, fileDeleted: false };
+  }
+  if (!dryRun) {
+    try {
+      await fs8.unlink(filePath);
+      const parentDir = path10.dirname(filePath);
+      const remaining = await fs8.readdir(parentDir);
+      if (remaining.length === 0) {
+        await fs8.rmdir(parentDir);
+      }
+    } catch {
+    }
+  }
+  return { removed: true, fileDeleted: true };
+}
 async function isExecutableInPath(command) {
   const envPath = process.env.PATH;
   if (!envPath) return false;
-  const dirs = envPath.split(path9.delimiter);
+  const dirs = envPath.split(path10.delimiter);
   for (const dir of dirs) {
     if (!dir) continue;
-    const fullPath = path9.join(dir, command);
+    const fullPath = path10.join(dir, command);
     try {
-      await fs7.access(fullPath, fs7.constants.X_OK);
+      await fs8.access(fullPath, fs8.constants.X_OK);
       return true;
     } catch {
     }
@@ -6144,9 +7165,9 @@ async function isExecutableInPath(command) {
 }
 
 // src/install/ownership.ts
-import * as path10 from "path";
+import * as path11 from "path";
 function getIntegrationsFilePath(rootDir) {
-  return path10.join(rootDir, ".bilmem", "integrations.json");
+  return path11.join(rootDir, ".bilmem", "integrations.json");
 }
 async function loadIntegrationsMetadata(rootDir) {
   const metaPath = getIntegrationsFilePath(rootDir);
@@ -6188,6 +7209,7 @@ async function removeIntegration(rootDir, agentId, dryRun = false) {
 
 // src/install/adapters/base.ts
 var BaseAgentAdapter = class {
+  aliases;
   supportedScopes = ["project", "global"];
   async inspect(context) {
     const configPath = this.resolveConfigPath(context);
@@ -6201,12 +7223,14 @@ 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;
     try {
-      const content = await fs8.readFile(instructionPath, "utf-8");
+      const content = await fs9.readFile(instructionPath, "utf-8");
       instructionInstalled = hasBilmemInstruction(content);
       const extracted = extractInstructionVersion(content);
       if (extracted !== null) {
@@ -6214,6 +7238,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 fs9.readFile(skillPath, "utf-8");
+        skillInstalled = hasBilmemSkill(skillContent);
+        const extracted = extractSkillVersion(skillContent);
+        if (extracted !== null) {
+          skillVersion = extracted;
+        }
+      } catch {
+      }
+    }
     return {
       id: this.id,
       name: this.name,
@@ -6223,9 +7261,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
@@ -6245,7 +7286,7 @@ var BaseAgentAdapter = class {
       const storage = context.storage || new Storage(context.projectDir);
       if (!await storage.isInitialized()) {
         if (!options.dryRun) {
-          await storage.init({ projectName: path11.basename(context.projectDir) });
+          await storage.init({ projectName: path12.basename(context.projectDir) });
         }
         projectInitialized = true;
         actionsTaken.push("Initialized .bilmem/ storage");
@@ -6270,6 +7311,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,
@@ -6277,9 +7331,11 @@ var BaseAgentAdapter = class {
         {
           scope: options.scope,
           mcp: true,
-          mcpConfigPath: path11.relative(context.projectDir, configPath),
+          mcpConfigPath: path12.relative(context.projectDir, configPath),
           instructions: true,
-          instructionPath: path11.relative(context.projectDir, instructionPath),
+          instructionPath: path12.relative(context.projectDir, instructionPath),
+          skill: skillPath ? true : void 0,
+          skillPath: skillPath ? path12.relative(context.projectDir, skillPath) : void 0,
           version: CURRENT_INTEGRATION_VERSION,
           installedAt: (/* @__PURE__ */ new Date()).toISOString()
         },
@@ -6290,7 +7346,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");
     }
@@ -6301,6 +7357,8 @@ var BaseAgentAdapter = class {
       scope: options.scope,
       mcpChanged: mcpRes.changed,
       instructionChanged: instRes.changed,
+      skillChanged,
+      skillPath,
       projectInitialized,
       dryRun: options.dryRun,
       actionsTaken,
@@ -6320,10 +7378,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");
     }
@@ -6334,6 +7401,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}`
@@ -6345,6 +7414,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`);
@@ -6365,17 +7435,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
@@ -6389,23 +7473,23 @@ var CursorAdapter = class extends BaseAgentAdapter {
   name = "Cursor";
   resolveConfigPath(context) {
     if (context.scope === "project") {
-      return path12.join(context.projectDir, ".cursor", "mcp.json");
+      return path13.join(context.projectDir, ".cursor", "mcp.json");
     }
     const home = context.globalDir || os.homedir();
-    return path12.join(home, ".cursor", "mcp.json");
+    return path13.join(home, ".cursor", "mcp.json");
   }
   resolveInstructionPath(context) {
     if (context.scope === "project") {
-      return path12.join(context.projectDir, ".cursorrules");
+      return path13.join(context.projectDir, ".cursorrules");
     }
     const home = context.globalDir || os.homedir();
-    return path12.join(home, ".cursorrules");
+    return path13.join(home, ".cursorrules");
   }
   async detect(context) {
     const reasons = [];
-    const dotCursor = path12.join(context.projectDir, ".cursor");
-    const dotCursorrules = path12.join(context.projectDir, ".cursorrules");
-    const mcpConfig = path12.join(context.projectDir, ".cursor", "mcp.json");
+    const dotCursor = path13.join(context.projectDir, ".cursor");
+    const dotCursorrules = path13.join(context.projectDir, ".cursorrules");
+    const mcpConfig = path13.join(context.projectDir, ".cursor", "mcp.json");
     const hasDotCursor = await pathExists(dotCursor);
     const hasCursorrules = await pathExists(dotCursorrules);
     const hasMcp = await pathExists(mcpConfig);
@@ -6413,7 +7497,7 @@ var CursorAdapter = class extends BaseAgentAdapter {
     if (hasCursorrules) reasons.push("Found .cursorrules file");
     if (hasMcp) reasons.push("Found .cursor/mcp.json file");
     const globalHome = context.globalDir || os.homedir();
-    const globalCursor = path12.join(globalHome, ".cursor");
+    const globalCursor = path13.join(globalHome, ".cursor");
     const hasGlobalCursor = await pathExists(globalCursor);
     if (hasGlobalCursor) reasons.push(`Found global directory at ${globalCursor}`);
     const hasExecutable = await isExecutableInPath("cursor");
@@ -6430,31 +7514,31 @@ var CursorAdapter = class extends BaseAgentAdapter {
 };
 
 // src/install/adapters/claude.ts
-import * as path13 from "path";
+import * as path14 from "path";
 import * as os2 from "os";
 var ClaudeAdapter = class extends BaseAgentAdapter {
   id = "claude";
   name = "Claude Code";
   resolveConfigPath(context) {
     if (context.scope === "project") {
-      return path13.join(context.projectDir, ".claude", "mcp.json");
+      return path14.join(context.projectDir, ".claude", "mcp.json");
     }
     const home = context.globalDir || os2.homedir();
-    return path13.join(home, ".claude", "mcp.json");
+    return path14.join(home, ".claude", "mcp.json");
   }
   resolveInstructionPath(context) {
     if (context.scope === "project") {
-      return path13.join(context.projectDir, "CLAUDE.md");
+      return path14.join(context.projectDir, "CLAUDE.md");
     }
     const home = context.globalDir || os2.homedir();
-    return path13.join(home, ".claude", "CLAUDE.md");
+    return path14.join(home, ".claude", "CLAUDE.md");
   }
   async detect(context) {
     const reasons = [];
-    const dotClaude = path13.join(context.projectDir, ".claude");
-    const claudeMd = path13.join(context.projectDir, "CLAUDE.md");
-    const claudeJson = path13.join(context.projectDir, "claude.json");
-    const mcpConfig = path13.join(context.projectDir, ".claude", "mcp.json");
+    const dotClaude = path14.join(context.projectDir, ".claude");
+    const claudeMd = path14.join(context.projectDir, "CLAUDE.md");
+    const claudeJson = path14.join(context.projectDir, "claude.json");
+    const mcpConfig = path14.join(context.projectDir, ".claude", "mcp.json");
     const hasDotClaude = await pathExists(dotClaude);
     const hasClaudeMd = await pathExists(claudeMd);
     const hasClaudeJson = await pathExists(claudeJson);
@@ -6464,7 +7548,7 @@ var ClaudeAdapter = class extends BaseAgentAdapter {
     if (hasClaudeJson) reasons.push("Found claude.json file");
     if (hasMcp) reasons.push("Found .claude/mcp.json file");
     const globalHome = context.globalDir || os2.homedir();
-    const globalClaude = path13.join(globalHome, ".claude");
+    const globalClaude = path14.join(globalHome, ".claude");
     const hasGlobalClaude = await pathExists(globalClaude);
     if (hasGlobalClaude) reasons.push(`Found global directory at ${globalClaude}`);
     const hasExecutable = await isExecutableInPath("claude");
@@ -6481,31 +7565,31 @@ var ClaudeAdapter = class extends BaseAgentAdapter {
 };
 
 // src/install/adapters/codex.ts
-import * as path14 from "path";
+import * as path15 from "path";
 import * as os3 from "os";
 var CodexAdapter = class extends BaseAgentAdapter {
   id = "codex";
   name = "Codex";
   resolveConfigPath(context) {
     if (context.scope === "project") {
-      return path14.join(context.projectDir, ".codex", "mcp.json");
+      return path15.join(context.projectDir, ".codex", "mcp.json");
     }
     const home = context.globalDir || os3.homedir();
-    return path14.join(home, ".codex", "mcp.json");
+    return path15.join(home, ".codex", "mcp.json");
   }
   resolveInstructionPath(context) {
     if (context.scope === "project") {
-      return path14.join(context.projectDir, "CODEX.md");
+      return path15.join(context.projectDir, "CODEX.md");
     }
     const home = context.globalDir || os3.homedir();
-    return path14.join(home, ".codex", "instructions.md");
+    return path15.join(home, ".codex", "instructions.md");
   }
   async detect(context) {
     const reasons = [];
-    const dotCodex = path14.join(context.projectDir, ".codex");
-    const codexMd = path14.join(context.projectDir, "CODEX.md");
-    const codexJson = path14.join(context.projectDir, "codex.json");
-    const mcpConfig = path14.join(context.projectDir, ".codex", "mcp.json");
+    const dotCodex = path15.join(context.projectDir, ".codex");
+    const codexMd = path15.join(context.projectDir, "CODEX.md");
+    const codexJson = path15.join(context.projectDir, "codex.json");
+    const mcpConfig = path15.join(context.projectDir, ".codex", "mcp.json");
     const hasDotCodex = await pathExists(dotCodex);
     const hasCodexMd = await pathExists(codexMd);
     const hasCodexJson = await pathExists(codexJson);
@@ -6515,7 +7599,7 @@ var CodexAdapter = class extends BaseAgentAdapter {
     if (hasCodexJson) reasons.push("Found codex.json file");
     if (hasMcp) reasons.push("Found .codex/mcp.json file");
     const globalHome = context.globalDir || os3.homedir();
-    const globalCodex = path14.join(globalHome, ".codex");
+    const globalCodex = path15.join(globalHome, ".codex");
     const hasGlobalCodex = await pathExists(globalCodex);
     if (hasGlobalCodex) reasons.push(`Found global directory at ${globalCodex}`);
     const hasExecutable = await isExecutableInPath("codex");
@@ -6532,31 +7616,31 @@ var CodexAdapter = class extends BaseAgentAdapter {
 };
 
 // src/install/adapters/gemini.ts
-import * as path15 from "path";
+import * as path16 from "path";
 import * as os4 from "os";
 var GeminiAdapter = class extends BaseAgentAdapter {
   id = "gemini";
   name = "Gemini CLI";
   resolveConfigPath(context) {
     if (context.scope === "project") {
-      return path15.join(context.projectDir, ".gemini", "settings.json");
+      return path16.join(context.projectDir, ".gemini", "settings.json");
     }
     const home = context.globalDir || os4.homedir();
-    return path15.join(home, ".gemini", "settings.json");
+    return path16.join(home, ".gemini", "settings.json");
   }
   resolveInstructionPath(context) {
     if (context.scope === "project") {
-      return path15.join(context.projectDir, "GEMINI.md");
+      return path16.join(context.projectDir, "GEMINI.md");
     }
     const home = context.globalDir || os4.homedir();
-    return path15.join(home, ".gemini", "GEMINI.md");
+    return path16.join(home, ".gemini", "GEMINI.md");
   }
   async detect(context) {
     const reasons = [];
-    const dotGemini = path15.join(context.projectDir, ".gemini");
-    const geminiMd = path15.join(context.projectDir, "GEMINI.md");
-    const geminiJson = path15.join(context.projectDir, "gemini.json");
-    const settingsJson = path15.join(context.projectDir, ".gemini", "settings.json");
+    const dotGemini = path16.join(context.projectDir, ".gemini");
+    const geminiMd = path16.join(context.projectDir, "GEMINI.md");
+    const geminiJson = path16.join(context.projectDir, "gemini.json");
+    const settingsJson = path16.join(context.projectDir, ".gemini", "settings.json");
     const hasDotGemini = await pathExists(dotGemini);
     const hasGeminiMd = await pathExists(geminiMd);
     const hasGeminiJson = await pathExists(geminiJson);
@@ -6566,7 +7650,7 @@ var GeminiAdapter = class extends BaseAgentAdapter {
     if (hasGeminiJson) reasons.push("Found gemini.json file");
     if (hasSettingsJson) reasons.push("Found .gemini/settings.json file");
     const globalHome = context.globalDir || os4.homedir();
-    const globalGemini = path15.join(globalHome, ".gemini");
+    const globalGemini = path16.join(globalHome, ".gemini");
     const hasGlobalGemini = await pathExists(globalGemini);
     if (hasGlobalGemini) reasons.push(`Found global directory at ${globalGemini}`);
     const hasExecutable = await isExecutableInPath("gemini");
@@ -6582,12 +7666,110 @@ var GeminiAdapter = class extends BaseAgentAdapter {
   }
 };
 
+// src/install/adapters/antigravity.ts
+import * as path17 from "path";
+import * as os5 from "os";
+import * as fs10 from "fs";
+function resolveAntigravityGlobalDir(context) {
+  const home = context.globalDir || os5.homedir();
+  if (path17.basename(home) === "config" && path17.basename(path17.dirname(home)) === ".gemini") {
+    return home;
+  }
+  return path17.join(home, ".gemini", "config");
+}
+var AntigravityAdapter = class extends BaseAgentAdapter {
+  id = "antigravity";
+  name = "Antigravity";
+  resolveConfigPath(context) {
+    if (context.scope === "project") {
+      const rootMcp = path17.join(context.projectDir, "mcp_config.json");
+      if (fs10.existsSync(rootMcp)) {
+        return rootMcp;
+      }
+      return path17.join(context.projectDir, ".agents", "mcp_config.json");
+    }
+    const globalRoot = resolveAntigravityGlobalDir(context);
+    return path17.join(globalRoot, "mcp_config.json");
+  }
+  resolveSkillPath(context) {
+    if (context.scope === "project") {
+      return path17.join(context.projectDir, ".agents", "skills", "bilmem", "SKILL.md");
+    }
+    const globalRoot = resolveAntigravityGlobalDir(context);
+    return path17.join(globalRoot, "skills", "bilmem", "SKILL.md");
+  }
+  resolveInstructionPath(context) {
+    if (context.scope === "project") {
+      const geminiMd = path17.join(context.projectDir, "GEMINI.md");
+      const agentsMd = path17.join(context.projectDir, "AGENTS.md");
+      const rulesBilmem = path17.join(context.projectDir, ".agents", "rules", "bilmem.md");
+      if (fs10.existsSync(rulesBilmem)) {
+        return rulesBilmem;
+      }
+      if (fs10.existsSync(geminiMd)) {
+        return geminiMd;
+      }
+      if (fs10.existsSync(agentsMd)) {
+        return agentsMd;
+      }
+      return path17.join(context.projectDir, ".agents", "rules", "bilmem.md");
+    }
+    const globalRoot = resolveAntigravityGlobalDir(context);
+    return path17.join(globalRoot, "rules", "bilmem.md");
+  }
+  async detect(context) {
+    const reasons = [];
+    const dotAgents = path17.join(context.projectDir, ".agents");
+    const skillsDir = path17.join(context.projectDir, ".agents", "skills");
+    const agentsMcp = path17.join(context.projectDir, ".agents", "mcp_config.json");
+    const rootMcp = path17.join(context.projectDir, "mcp_config.json");
+    const geminiMd = path17.join(context.projectDir, "GEMINI.md");
+    const agentsMd = path17.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 = path17.join(home, ".gemini", "antigravity-ide");
+    const globalCli = path17.join(home, ".gemini", "antigravity-cli");
+    const globalAgy = path17.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];
@@ -6607,7 +7789,7 @@ async function detectAgents(context) {
 }
 
 // src/install/doctor.ts
-import * as path16 from "path";
+import * as path18 from "path";
 async function runDoctor(context) {
   const storage = context.storage || new Storage(context.projectDir);
   let isInit = false;
@@ -6699,6 +7881,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) {
@@ -6712,9 +7914,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) {
@@ -6734,18 +7938,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
@@ -6852,6 +8057,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})` : ""}`);
     }
@@ -6896,7 +8105,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,
@@ -6917,7 +8126,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);
@@ -6999,7 +8208,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 = {
@@ -7031,10 +8240,10 @@ async function getReadyStorage(cwd = process.cwd()) {
   return storage;
 }
 program.command("init [path]").description("Initialize bilmem knowledge repository (.bilmem/)").option("--json", "Output result in JSON format").action(async (targetPath, opts) => {
-  const cwd = targetPath ? path18.resolve(targetPath) : process.cwd();
+  const cwd = targetPath ? path20.resolve(targetPath) : process.cwd();
   const storage = new Storage(cwd);
   const config = await storage.init({
-    projectName: path18.basename(cwd)
+    projectName: path20.basename(cwd)
   });
   if (opts.json) {
     console.log(JSON.stringify({ status: "initialized", config }, null, 2));
@@ -7044,7 +8253,7 @@ program.command("init [path]").description("Initialize bilmem knowledge reposito
   }
 });
 program.command("scan [path]").description("Scan filesystem, markdown, and git history for reusable evidence and knowledge").option("-i, --incremental", "Incremental scan from last scanned git commit").option("--dry-run", "Preview findings and reconciliation actions without saving").option("--json", "Output result in JSON format").action(async (targetPath, opts) => {
-  const cwd = targetPath ? path18.resolve(targetPath) : process.cwd();
+  const cwd = targetPath ? path20.resolve(targetPath) : process.cwd();
   const report = await scanRepository(cwd, {
     incremental: opts.incremental ?? false,
     dryRun: opts.dryRun ?? false
@@ -7120,7 +8329,30 @@ program.command("resolve <question>").description("Resolve an epistemic question
   if (result.fallback) {
     output.fallback = result.fallback;
   }
-  console.log(YAML4.stringify(output).trim());
+  console.log(YAML5.stringify(output).trim());
+});
+program.command("preflight <goal>").description("Analyze existing knowledge, constraints, lessons, and blocking unknowns before starting work").option("-p, --positive <cues...>", "Contextual positive cues (e.g. -p auth server)").option("-n, --negative <cues...>", "Contextual negative cues (e.g. -n client-side)").option("-s, --scope <scope>", "Knowledge scope (defaults to project)").option("--deep", "Perform targeted git diff / file staleness check").option("--json", "Output result in JSON format").action(async (goal, opts) => {
+  const storage = await getReadyStorage();
+  const all = await storage.getAllKnowledge();
+  const index = new SearchIndex();
+  await index.buildIndex(all);
+  const retriever = new Retriever(index, storage);
+  const result = await executePreflight(
+    {
+      goal,
+      positive: opts.positive,
+      negative: opts.negative,
+      scope: opts.scope,
+      deep: opts.deep ?? false
+    },
+    storage,
+    retriever
+  );
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(formatPreflightReport(result).trim());
 });
 program.command("lookup [query]").description("Lookup knowledge using candidate retrieval and JEV contextual reranking").option("-p, --positive <cues...>", "Contextual positive cues (e.g. -p node esm)").option("-n, --negative <cues...>", "Contextual negative cues (e.g. -n commonjs)").option("-s, --scope <scope>", "Query scope (defaults to project)").option("-l, --limit <n>", "Maximum results to return", "5").option("--all", "Include rejected candidates in results").option("--json", "Output result in JSON format").action(async (query, opts) => {
   const storage = await getReadyStorage();
@@ -7221,14 +8453,14 @@ program.command("unknown").description("List first-class unknowns and unresolvab
 });
 program.command("import <targetPath>").description("Smart import knowledge from YAML file or directory with reconciliation").option("--dry-run", "Preview changes without saving").option("--json", "Output result in JSON format").action(async (targetPath, opts) => {
   const storage = await getReadyStorage();
-  const resolvedPath = path18.resolve(targetPath);
-  const stats = await fs9.stat(resolvedPath);
+  const resolvedPath = path20.resolve(targetPath);
+  const stats = await fs11.stat(resolvedPath);
   const filesToImport = [];
   if (stats.isDirectory()) {
-    const files = await fs9.readdir(resolvedPath);
+    const files = await fs11.readdir(resolvedPath);
     for (const f of files) {
       if (f.endsWith(".yml") || f.endsWith(".yaml")) {
-        filesToImport.push(path18.join(resolvedPath, f));
+        filesToImport.push(path20.join(resolvedPath, f));
       }
     }
   } else {
@@ -7238,7 +8470,7 @@ program.command("import <targetPath>").description("Smart import knowledge from
   let totalUpdated = 0;
   const allResults = [];
   for (const filePath of filesToImport) {
-    const content = await fs9.readFile(filePath, "utf-8");
+    const content = await fs11.readFile(filePath, "utf-8");
     const report = await importKnowledgeFromYaml(content, storage);
     totalCreated += report.created.length;
     totalUpdated += report.updated.length;
@@ -7260,7 +8492,7 @@ program.command("export").description("Export active knowledge to human-readable
   const items = await storage.getAllKnowledge();
   const yamlStr = exportKnowledgeToYaml(items, { scope: opts.scope });
   if (opts.out) {
-    await fs9.writeFile(path18.resolve(opts.out), yamlStr, "utf-8");
+    await fs11.writeFile(path20.resolve(opts.out), yamlStr, "utf-8");
     console.log(`Exported ${items.length} items to ${opts.out}`);
   } else {
     process.stdout.write(yamlStr);
@@ -7269,13 +8501,13 @@ program.command("export").description("Export active knowledge to human-readable
 program.command("dump <file>").description("Dump complete portable snapshot sufficient for restoration").action(async (file) => {
   const storage = await getReadyStorage();
   const dumpStr = await dumpToYaml(storage);
-  const dest = path18.resolve(file);
-  await fs9.writeFile(dest, dumpStr, "utf-8");
+  const dest = path20.resolve(file);
+  await fs11.writeFile(dest, dumpStr, "utf-8");
   console.log(`Complete bilmem snapshot dumped to ${dest}`);
 });
 program.command("restore <file>").description("Deterministic restoration from backup dump without reinterpreting").action(async (file) => {
   const storage = await getReadyStorage();
-  const content = await fs9.readFile(path18.resolve(file), "utf-8");
+  const content = await fs11.readFile(path20.resolve(file), "utf-8");
   const result = await restoreFromYaml(content, storage);
   console.log(`Restored ${result.restoredKnowledgeCount} knowledge items and ${result.restoredUnknownsCount} unknowns from ${file}`);
 });
@@ -7297,7 +8529,7 @@ program.command("compact").description("Compact knowledge base: merge duplicates
 });
 program.command("learn <trajectoryFile>").description("Learn from an agent trajectory JSON following the staged pipeline (trajectory -> obs -> candidate -> reconcile -> knowledge)").option("--dry-run", "Preview extracted candidate lessons and planned reconciliation without modifying storage").option("--json", "Output result in JSON format").action(async (trajectoryFile, opts) => {
   const storage = await getReadyStorage();
-  const raw = await fs9.readFile(path18.resolve(trajectoryFile), "utf-8");
+  const raw = await fs11.readFile(path20.resolve(trajectoryFile), "utf-8");
   const trajectory = JSON.parse(raw);
   const existingKnowledge = await storage.getAllKnowledge();
   const result = learnFromTrajectory(trajectory, existingKnowledge, {
@@ -7387,8 +8619,9 @@ program.command("status").description("Display bilmem status, metrics, and summa
     console.log(`- Metrics: ${metrics.knowledgeHits} hits, ${metrics.knowledgeMisses} misses, ${metrics.knowledgeReused} reused, ${metrics.repeatedInvestigationsPrevented} investigations prevented`);
   }
 });
-program.command("mcp").description("Run bilmem MCP server powered by mcponce").allowUnknownOption(true).action(async () => {
-  const app = createBilmemMcpApp();
+program.command("mcp [path]").description("Run bilmem MCP server powered by mcponce").option("-r, --root <path>", "Root project directory for bilmem storage").allowUnknownOption(true).action(async (pathArg, opts) => {
+  const rootDir = opts.root || pathArg;
+  const app = createBilmemMcpApp({ rootDir });
   await app.run();
 });
 var ruleCommand = program.command("rule").alias("rules").description("Manage declarative YAML rule sets and guardrails (.bilmem/rules/*.yml, rules.yml)");
@@ -7447,7 +8680,7 @@ ruleCommand.command("add <statement>").description("Quickly add a rule to a YAML
 ruleCommand.command("validate [file]").description("Validate YAML rule set files for syntax and schema correctness").action(async (targetFile) => {
   const filesToValidate = [];
   if (targetFile) {
-    filesToValidate.push(path18.resolve(targetFile));
+    filesToValidate.push(path20.resolve(targetFile));
   } else {
     const storage = await getReadyStorage();
     const discovered = await findRuleFiles(process.cwd(), storage.getRulesDir());
@@ -7460,7 +8693,7 @@ ruleCommand.command("validate [file]").description("Validate YAML rule set files
   let allValid = true;
   for (const f of filesToValidate) {
     try {
-      const content = await fs9.readFile(f, "utf-8");
+      const content = await fs11.readFile(f, "utf-8");
       const ruleSet = parseRuleSetYaml(content, f);
       console.log(`\u2713 ${f} is valid (${ruleSet.rules.length} rules)`);
     } catch (err) {
@@ -7473,7 +8706,7 @@ ruleCommand.command("validate [file]").description("Validate YAML rule set files
     process.exitCode = 1;
   }
 });
-program.command("install [target]").description("Install Bilmem MCP runtime and instructions into AI coding agents/editors (cursor, claude, codex, gemini)").option("--detected", "Install into detected agents/editors").option("--all", "Attempt installation for all supported integrations").option("-y, --yes", "Automatically confirm prompts without interactive input").option("--global", "Target global configuration instead of project-local").option("--dry-run", "Preview configuration changes without modifying files").option("--json", "Output result in JSON format").action(async (target, opts) => {
+program.command("install [target]").description("Install Bilmem MCP runtime, instructions, and skills into AI coding agents/editors (cursor, claude, codex, gemini, antigravity)").option("--detected", "Install into detected agents/editors").option("--all", "Attempt installation for all supported integrations").option("-y, --yes", "Automatically confirm prompts without interactive input").option("--global", "Target global configuration instead of project-local").option("--dry-run", "Preview configuration changes without modifying files").option("--json", "Output result in JSON format").action(async (target, opts) => {
   try {
     const scope = opts.global ? "global" : "project";
     if (!opts.json) {