bilmem 0.1.0 → 0.2.0

package/dist/index.js

@@ -316,7 +316,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()) ?? [])),
@@ -346,6 +346,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
   };
@@ -1710,6 +1715,7 @@ var Retriever = class {
 // src/core/resolver.ts
 var RELATIVE_COSTS = {
   USE_KNOWLEDGE: 1,
+  REVALIDATE: 2,
   INSPECT_TEST: 2,
   INSPECT_FILE: 2,
   INSPECT_SYMBOL: 2.5,
@@ -2050,14 +2056,624 @@ async function resolveEpistemicQuery(options, storage, retriever) {
   };
 }
 
+// src/core/preflight.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import * as path from "path";
+import * as fs from "fs/promises";
+import YAML from "yaml";
+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() ? path.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() ? path.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 = path.isAbsolute(cleanPath) ? cleanPath : path.resolve(rootDir, cleanPath);
+      try {
+        const stat4 = await fs.stat(absPath);
+        if (stat4.mtimeMs > knowledgeTime + 500) {
+          isStale = true;
+          changedDeps.push(cleanPath);
+          staleReason = `Supporting source changed after last validation (${cleanPath})`;
+        }
+      } catch {
+      }
+    }
+    if (isStale) {
+      stale.push({
+        id: k.id,
+        statement: k.statement,
+        reason: staleReason,
+        changedSources: changedDeps.length > 0 ? changedDeps : k.depends_on
+      });
+      continue;
+    }
+    const isConstraint = k.type === "rule" || k.type === "decision" || k.type === "convention" || CONSTRAINT_PATTERN.test(k.statement);
+    if (isConstraint) {
+      constraints.push({
+        id: k.id,
+        statement: k.statement,
+        type: k.type,
+        confidence: k.confidence,
+        confidenceTier: k.confidenceTier,
+        source: k.evidence?.[0]
+      });
+      continue;
+    }
+    const isFailure = k.type === "failure" || k.statement.startsWith("[FAILURE]") || k.statement.startsWith("[REVERT]") || FAILURE_PATTERN.test(k.statement) || k.metrics.failed_outcomes > 0;
+    if (isFailure) {
+      pastFailures.push({
+        id: k.id,
+        statement: k.statement,
+        context: k.context || {
+          positive: k.positive,
+          negative: k.negative
+        },
+        failure: k.statement,
+        lesson: k.lesson || k.reasoning || k.resolves?.[0],
+        evidence: k.evidence
+      });
+      continue;
+    }
+    const isLesson = k.type === "lesson" && (k.id.includes("lesson") || k.tags?.includes("lesson") || k.statement.toLowerCase().includes("lesson")) || k.statement.toLowerCase().startsWith("lesson:") || k.statement.toLowerCase().includes("lesson:");
+    if (isLesson) {
+      lessons.push({
+        id: k.id,
+        statement: k.statement,
+        confidence: k.confidence,
+        domain: k.tags?.[0],
+        evidence: k.evidence
+      });
+      continue;
+    }
+    if (k.status === "active" || k.stage === "active" || k.stage === "probation" || !k.status) {
+      known.push({
+        id: k.id,
+        statement: k.statement,
+        confidence: k.confidence,
+        confidenceTier: k.confidenceTier,
+        stage: k.stage
+      });
+    }
+  }
+  const unknownsFromStorage = await storage.getAllUnknowns();
+  const unknownKnowledge = allKnowledge.filter((k) => k.type === "unknown");
+  const unifiedUnknowns = [];
+  const seenUnknownIds = /* @__PURE__ */ new Set();
+  for (const u of unknownsFromStorage) {
+    seenUnknownIds.add(u.id);
+    unifiedUnknowns.push({
+      id: u.id,
+      statement: u.statement || u.id,
+      reason: u.reason,
+      question: u.question || u.next?.question,
+      next: u.next,
+      blocking: u.blocking,
+      positive: u.positive,
+      negative: u.negative,
+      checked: u.checked
+    });
+  }
+  for (const k of unknownKnowledge) {
+    if (!seenUnknownIds.has(k.id)) {
+      seenUnknownIds.add(k.id);
+      unifiedUnknowns.push({
+        id: k.id,
+        statement: k.statement,
+        reason: k.history?.[0]?.reason,
+        question: k.question || (k.statement.includes("?") ? k.statement : void 0),
+        next: {
+          type: "ask",
+          target: k.id,
+          question: k.question || k.statement
+        },
+        blocking: k.blocking,
+        positive: k.positive,
+        negative: k.negative,
+        checked: k.depends_on || k.evidence
+      });
+    }
+  }
+  const unknowns = [];
+  const missing = [];
+  const rawQuestions = [];
+  for (const u of unifiedUnknowns) {
+    const text = `${u.id} ${u.statement || ""} ${u.question || ""}`.toLowerCase();
+    const overlaps = goalTokens.some((t) => text.includes(t)) || likelyDomains.some((d) => text.includes(d)) || u.positive && u.positive.some((p) => contextualPositive.includes(p));
+    if (u.negative && u.negative.some((n) => contextualPositive.includes(n))) {
+      continue;
+    }
+    if (overlaps) {
+      const { classification, isDecision, reason } = classifyUnknown(u, goalTokens, likelyDomains);
+      const isBlocking = classification === "BLOCKING";
+      unknowns.push({
+        id: u.id,
+        statement: u.statement,
+        question: u.question || u.statement,
+        classification,
+        blocking: isBlocking,
+        reason
+      });
+      if (isDecision) {
+        missing.push({
+          type: "decision",
+          subject: u.id,
+          question: u.question || u.statement,
+          reason
+        });
+      } else {
+        missing.push({
+          type: "evidence",
+          subject: u.id,
+          question: u.question || u.statement,
+          reason
+        });
+      }
+      const qText = u.question || (u.statement && u.statement.includes("?") ? u.statement : void 0);
+      if (qText) {
+        rawQuestions.push({
+          question: qText,
+          reason: `Unknown: ${u.id} (${reason})`,
+          targetTopic: u.id,
+          isBlocking
+        });
+      }
+    }
+  }
+  const questionKnowledge = allKnowledge.filter((k) => k.type === "question");
+  for (const qk of questionKnowledge) {
+    const matchesCues = qk.positive.some((p) => contextualPositive.includes(p));
+    const conflicts = qk.negative.some((n) => negative.includes(n));
+    if (matchesCues && !conflicts && qk.question) {
+      rawQuestions.push({
+        question: qk.question,
+        reason: `Learned question for [${qk.positive.join(", ")}] uncertainty`,
+        targetTopic: qk.resolves?.[0] || qk.id,
+        outcomeScore: (qk.metrics?.successful_outcomes ?? 0) - (qk.metrics?.failed_outcomes ?? 0)
+      });
+    }
+  }
+  const questions = prioritizeQuestions(rawQuestions, unknowns);
+  const receipts = await storage.getAllReceipts();
+  const alreadyInvestigated = [];
+  const investigatedSources = /* @__PURE__ */ new Set();
+  for (const r of receipts) {
+    const qTokens = r.question.toLowerCase().split(/\s+/).filter(Boolean);
+    const overlapsGoal = qTokens.some((t) => goalTokens.includes(t));
+    const overlapsCues = r.positive && r.positive.some((p) => contextualPositive.includes(p));
+    if (overlapsGoal || overlapsCues) {
+      for (const checked of r.checked) {
+        investigatedSources.add(checked.toLowerCase());
+        alreadyInvestigated.push({
+          source: checked,
+          result: r.findings[0] || r.rejected[0]?.reason || "Did not establish requested behavior",
+          nextSuggestion: "ASK_USER"
+        });
+      }
+    }
+  }
+  let readiness = "READY";
+  const totalRelevantKnowledge = known.length + constraints.length + lessons.length + pastFailures.length + stale.length;
+  const hasBlockingUnknown = unknowns.some((u) => u.blocking);
+  const hasMissingDecision = missing.some((m) => m.type === "decision");
+  if (totalRelevantKnowledge === 0 && unknowns.length === 0) {
+    readiness = "INSUFFICIENT_KNOWLEDGE";
+  } else if (conflictedCount > 0) {
+    readiness = "CONFLICTED";
+  } else if (hasBlockingUnknown || hasMissingDecision) {
+    readiness = "NEEDS_CLARIFICATION";
+  } else if (stale.length > 0) {
+    readiness = "NEEDS_REVALIDATION";
+  } else {
+    readiness = "READY";
+  }
+  const next = [];
+  for (const m of missing) {
+    if (m.type === "decision") {
+      next.push({
+        type: "ASK_USER",
+        target: m.subject,
+        reason: m.question || m.reason,
+        relativeCost: 1,
+        expectedInfoGain: 0.95
+      });
+    }
+  }
+  for (const s of stale) {
+    next.push({
+      type: "REVALIDATE",
+      target: s.id,
+      reason: s.reason,
+      relativeCost: 2,
+      expectedInfoGain: 0.85
+    });
+  }
+  for (const m of missing) {
+    if (m.type === "evidence") {
+      const wasChecked = investigatedSources.has(m.subject.toLowerCase()) || alreadyInvestigated.length > 0;
+      if (wasChecked) {
+        if (!next.some((n) => n.type === "ASK_USER")) {
+          next.push({
+            type: "ASK_USER",
+            target: m.subject,
+            reason: `Already investigated (${Array.from(investigatedSources).join(", ")}); did not establish requested behavior. Clarification required.`,
+            relativeCost: 1,
+            expectedInfoGain: 0.9
+          });
+        }
+      } else {
+        const isFilePath = m.subject.includes("/") || m.subject.includes(".");
+        next.push({
+          type: isFilePath ? "INSPECT_FILE" : "SEARCH_REPOSITORY",
+          target: m.subject,
+          reason: m.reason,
+          relativeCost: isFilePath ? 2 : 2.5,
+          expectedInfoGain: 0.8
+        });
+      }
+    }
+  }
+  if (alreadyInvestigated.length > 0 && !next.some((n) => n.type === "ASK_USER")) {
+    next.push({
+      type: "ASK_USER",
+      target: alreadyInvestigated[0].source,
+      reason: `Already investigated ${alreadyInvestigated[0].source}; clarification required`,
+      relativeCost: 1,
+      expectedInfoGain: 0.9
+    });
+  }
+  if (next.length === 0 && known.length > 0) {
+    next.push({
+      type: "USE_KNOWLEDGE",
+      target: known[0].id,
+      reason: "Proceed with implementation using verified knowledge and constraints",
+      relativeCost: 1,
+      expectedInfoGain: 1
+    });
+  }
+  const knowledgeImpact = {
+    relevantKnowledge: totalRelevantKnowledge,
+    validated: known.filter((k) => k.confidenceTier === "high").length + constraints.length,
+    needsRevalidation: stale.length,
+    conflicted: conflictedCount,
+    blockingUnknowns: unknowns.filter((u) => u.blocking).length,
+    relevantFailures: pastFailures.length
+  };
+  const similarWork = [];
+  for (const l of lessons) {
+    similarWork.push({
+      topic: l.domain || l.id,
+      lesson: l.statement
+    });
+  }
+  for (const f of pastFailures) {
+    similarWork.push({
+      topic: f.id,
+      failure: f.statement
+    });
+  }
+  await storage.appendMetricEvent({
+    type: "preflight",
+    goal,
+    readiness,
+    blockingUnknownsCount: knowledgeImpact.blockingUnknowns,
+    staleKnowledgeCount: stale.length,
+    pastFailuresCount: pastFailures.length,
+    questionsCount: questions.length,
+    repeatedChecksAvoidedCount: alreadyInvestigated.length,
+    timestamp: Date.now()
+  });
+  return {
+    goal,
+    readiness,
+    known,
+    constraints,
+    lessons,
+    past_failures: pastFailures,
+    unknowns,
+    stale,
+    missing,
+    questions,
+    likely_domains: likelyDomains,
+    similar_work: similarWork.length > 0 ? similarWork.slice(0, 5) : void 0,
+    already_investigated: alreadyInvestigated.length > 0 ? alreadyInvestigated : void 0,
+    knowledge_impact: knowledgeImpact,
+    next
+  };
+}
+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 YAML.stringify(plainObject);
+}
+
 // src/storage/canonical.ts
-import * as fs3 from "fs/promises";
-import * as path3 from "path";
+import * as fs4 from "fs/promises";
+import * as path4 from "path";
 
 // src/rules/loader.ts
-import YAML from "yaml";
-import * as fs from "fs/promises";
-import * as path from "path";
+import YAML2 from "yaml";
+import * as fs2 from "fs/promises";
+import * as path2 from "path";
 function validateRuleDefinition(rule, index = 0) {
   const errors = [];
   if (!rule || typeof rule !== "object") {
@@ -2126,7 +2742,7 @@ function validateRuleSet(data) {
 function parseRuleSetYaml(content, sourcePath = "inline.yml") {
   let parsed;
   try {
-    parsed = YAML.parse(content);
+    parsed = YAML2.parse(content);
   } catch (err) {
     throw new Error(`YAML syntax error in ${sourcePath}: ${err.message}`);
   }
@@ -2137,7 +2753,7 @@ function parseRuleSetYaml(content, sourcePath = "inline.yml") {
   }
   if (Array.isArray(parsed)) {
     return {
-      name: path.basename(sourcePath, path.extname(sourcePath)),
+      name: path2.basename(sourcePath, path2.extname(sourcePath)),
       rules: parsed
     };
   }
@@ -2149,7 +2765,7 @@ function parseRuleSetYaml(content, sourcePath = "inline.yml") {
   }
   const set = parsed;
   return {
-    name: set.name ?? path.basename(sourcePath, path.extname(sourcePath)),
+    name: set.name ?? path2.basename(sourcePath, path2.extname(sourcePath)),
     version: set.version ?? 1,
     scope: set.scope ?? "project",
     description: set.description,
@@ -2178,36 +2794,36 @@ function stringifyRuleSetYaml(ruleSet) {
     if (r.details && Object.keys(r.details).length > 0) ruleObj.details = r.details;
     return ruleObj;
   });
-  return YAML.stringify(payload, { indent: 2, lineWidth: 100 });
+  return YAML2.stringify(payload, { indent: 2, lineWidth: 100 });
 }
 async function loadRuleSetFile(filePath) {
-  const content = await fs.readFile(filePath, "utf-8");
+  const content = await fs2.readFile(filePath, "utf-8");
   return parseRuleSetYaml(content, filePath);
 }
 async function findRuleFiles(rootDir, storageRulesDir) {
   const candidates = [];
-  const rulesDir = storageRulesDir || path.resolve(rootDir, ".bilmem", "rules");
+  const rulesDir = storageRulesDir || path2.resolve(rootDir, ".bilmem", "rules");
   try {
-    const entries = await fs.readdir(rulesDir, { withFileTypes: true });
+    const entries = await fs2.readdir(rulesDir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isFile() && (entry.name.endsWith(".yml") || entry.name.endsWith(".yaml"))) {
-        candidates.push(path.join(rulesDir, entry.name));
+        candidates.push(path2.join(rulesDir, entry.name));
       }
     }
   } catch {
   }
   for (const name of ["rules.yml", "rules.yaml"]) {
-    const p = path.resolve(rootDir, ".bilmem", name);
+    const p = path2.resolve(rootDir, ".bilmem", name);
     try {
-      const st = await fs.stat(p);
+      const st = await fs2.stat(p);
       if (st.isFile()) candidates.push(p);
     } catch {
     }
   }
   for (const name of ["bilmem.rules.yml", "bilmem.rules.yaml", "rules.yml", "rules.yaml"]) {
-    const p = path.resolve(rootDir, name);
+    const p = path2.resolve(rootDir, name);
     try {
-      const st = await fs.stat(p);
+      const st = await fs2.stat(p);
       if (st.isFile()) candidates.push(p);
     } catch {
     }
@@ -2231,17 +2847,17 @@ async function loadAllProjectRuleSets(rootDir, storageRulesDir) {
 }
 
 // src/stats/events.ts
-import * as fs2 from "fs/promises";
-import * as path2 from "path";
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
 function getEventsFilePath(rootDir) {
-  return path2.join(rootDir, ".bilmem", "events.jsonl");
+  return path3.join(rootDir, ".bilmem", "events.jsonl");
 }
 async function appendMetricEvent(rootDir, event) {
   const filePath = getEventsFilePath(rootDir);
   try {
-    await fs2.mkdir(path2.dirname(filePath), { recursive: true });
+    await fs3.mkdir(path3.dirname(filePath), { recursive: true });
     const line = JSON.stringify(event) + "\n";
-    await fs2.appendFile(filePath, line, "utf-8");
+    await fs3.appendFile(filePath, line, "utf-8");
   } catch {
   }
 }
@@ -2249,7 +2865,7 @@ async function readMetricEvents(rootDir, filter) {
   const filePath = getEventsFilePath(rootDir);
   let raw;
   try {
-    raw = await fs2.readFile(filePath, "utf-8");
+    raw = await fs3.readFile(filePath, "utf-8");
   } catch (err) {
     if (err.code === "ENOENT") {
       return [];
@@ -2288,8 +2904,8 @@ async function readMetricEvents(rootDir, filter) {
 async function resetMetricEvents(rootDir) {
   const filePath = getEventsFilePath(rootDir);
   try {
-    await fs2.mkdir(path2.dirname(filePath), { recursive: true });
-    await fs2.writeFile(filePath, "", "utf-8");
+    await fs3.mkdir(path3.dirname(filePath), { recursive: true });
+    await fs3.writeFile(filePath, "", "utf-8");
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
@@ -2326,62 +2942,62 @@ var Storage = class {
   receiptsJsonlFile;
   eventsFile;
   constructor(rootDir = process.cwd()) {
-    this.baseDir = path3.resolve(rootDir, ".bilmem");
-    this.knowledgeDir = path3.join(this.baseDir, "knowledge");
-    this.evidenceDir = path3.join(this.baseDir, "evidence");
-    this.observationDir = path3.join(this.baseDir, "observations");
-    this.unknownDir = path3.join(this.baseDir, "unknowns");
-    this.rulesDir = path3.join(this.baseDir, "rules");
-    this.receiptsDir = path3.join(this.baseDir, "receipts");
-    this.configFile = path3.join(this.baseDir, "config.json");
-    this.relationsFile = path3.join(this.baseDir, "relations.json");
-    this.outcomesFile = path3.join(this.baseDir, "outcomes.jsonl");
-    this.metricsFile = path3.join(this.baseDir, "metrics.json");
-    this.revisionsFile = path3.join(this.baseDir, "revisions.jsonl");
-    this.knowledgeJsonlFile = path3.join(this.baseDir, "knowledge.jsonl");
-    this.evidenceJsonlFile = path3.join(this.baseDir, "evidence.jsonl");
-    this.observationJsonlFile = path3.join(this.baseDir, "observations.jsonl");
-    this.unknownsJsonlFile = path3.join(this.baseDir, "unknowns.jsonl");
-    this.receiptsJsonlFile = path3.join(this.baseDir, "receipts.jsonl");
-    this.eventsFile = path3.join(this.baseDir, "events.jsonl");
+    this.baseDir = path4.resolve(rootDir, ".bilmem");
+    this.knowledgeDir = path4.join(this.baseDir, "knowledge");
+    this.evidenceDir = path4.join(this.baseDir, "evidence");
+    this.observationDir = path4.join(this.baseDir, "observations");
+    this.unknownDir = path4.join(this.baseDir, "unknowns");
+    this.rulesDir = path4.join(this.baseDir, "rules");
+    this.receiptsDir = path4.join(this.baseDir, "receipts");
+    this.configFile = path4.join(this.baseDir, "config.json");
+    this.relationsFile = path4.join(this.baseDir, "relations.json");
+    this.outcomesFile = path4.join(this.baseDir, "outcomes.jsonl");
+    this.metricsFile = path4.join(this.baseDir, "metrics.json");
+    this.revisionsFile = path4.join(this.baseDir, "revisions.jsonl");
+    this.knowledgeJsonlFile = path4.join(this.baseDir, "knowledge.jsonl");
+    this.evidenceJsonlFile = path4.join(this.baseDir, "evidence.jsonl");
+    this.observationJsonlFile = path4.join(this.baseDir, "observations.jsonl");
+    this.unknownsJsonlFile = path4.join(this.baseDir, "unknowns.jsonl");
+    this.receiptsJsonlFile = path4.join(this.baseDir, "receipts.jsonl");
+    this.eventsFile = path4.join(this.baseDir, "events.jsonl");
   }
   getBaseDir() {
     return this.baseDir;
   }
   async isInitialized() {
     try {
-      await fs3.access(this.configFile);
+      await fs4.access(this.configFile);
       return true;
     } catch {
       return false;
     }
   }
   async init(options = {}) {
-    await fs3.mkdir(this.knowledgeDir, { recursive: true });
-    await fs3.mkdir(this.evidenceDir, { recursive: true });
-    await fs3.mkdir(this.observationDir, { recursive: true });
-    await fs3.mkdir(this.unknownDir, { recursive: true });
-    await fs3.mkdir(this.rulesDir, { recursive: true });
-    await fs3.mkdir(this.receiptsDir, { recursive: true });
+    await fs4.mkdir(this.knowledgeDir, { recursive: true });
+    await fs4.mkdir(this.evidenceDir, { recursive: true });
+    await fs4.mkdir(this.observationDir, { recursive: true });
+    await fs4.mkdir(this.unknownDir, { recursive: true });
+    await fs4.mkdir(this.rulesDir, { recursive: true });
+    await fs4.mkdir(this.receiptsDir, { recursive: true });
     let config;
     if (await this.isInitialized()) {
       config = await this.getConfig();
     } else {
       config = {
         schemaVersion: 1,
-        projectName: options.projectName ?? path3.basename(path3.dirname(this.baseDir)) ?? "project",
+        projectName: options.projectName ?? path4.basename(path4.dirname(this.baseDir)) ?? "project",
         defaultScope: options.defaultScope ?? "project",
         dataDir: this.baseDir
       };
       await this.saveConfig(config);
     }
     try {
-      await fs3.access(this.relationsFile);
+      await fs4.access(this.relationsFile);
     } catch {
-      await fs3.writeFile(this.relationsFile, JSON.stringify([], null, 2), "utf-8");
+      await fs4.writeFile(this.relationsFile, JSON.stringify([], null, 2), "utf-8");
     }
     try {
-      await fs3.access(this.metricsFile);
+      await fs4.access(this.metricsFile);
     } catch {
       const defaultMetrics = {
         knowledgeHits: 0,
@@ -2395,17 +3011,17 @@ var Storage = class {
         knowledgePromoted: 0,
         knowledgeSuperseded: 0
       };
-      await fs3.writeFile(this.metricsFile, JSON.stringify(defaultMetrics, null, 2), "utf-8");
+      await fs4.writeFile(this.metricsFile, JSON.stringify(defaultMetrics, null, 2), "utf-8");
     }
     return config;
   }
   // --- Config ---
   async getConfig() {
-    const raw = await fs3.readFile(this.configFile, "utf-8");
+    const raw = await fs4.readFile(this.configFile, "utf-8");
     return JSON.parse(raw);
   }
   async saveConfig(config) {
-    await fs3.writeFile(this.configFile, JSON.stringify(config, null, 2), "utf-8");
+    await fs4.writeFile(this.configFile, JSON.stringify(config, null, 2), "utf-8");
   }
   async updateConfig(updates) {
     const current = await this.getConfig();
@@ -2415,17 +3031,17 @@ var Storage = class {
   }
   // --- Knowledge ---
   async saveKnowledge(knowledge) {
-    await fs3.mkdir(this.knowledgeDir, { recursive: true });
+    await fs4.mkdir(this.knowledgeDir, { recursive: true });
     const filename = `${sanitizeFileName(knowledge.id)}.json`;
-    const filePath = path3.join(this.knowledgeDir, filename);
-    await fs3.writeFile(filePath, JSON.stringify(knowledge, null, 2), "utf-8");
-    await fs3.appendFile(this.knowledgeJsonlFile, JSON.stringify(knowledge) + "\n", "utf-8");
+    const filePath = path4.join(this.knowledgeDir, filename);
+    await fs4.writeFile(filePath, JSON.stringify(knowledge, null, 2), "utf-8");
+    await fs4.appendFile(this.knowledgeJsonlFile, JSON.stringify(knowledge) + "\n", "utf-8");
   }
   async getKnowledge(id) {
     const filename = `${sanitizeFileName(id)}.json`;
-    const filePath = path3.join(this.knowledgeDir, filename);
+    const filePath = path4.join(this.knowledgeDir, filename);
     try {
-      const raw = await fs3.readFile(filePath, "utf-8");
+      const raw = await fs4.readFile(filePath, "utf-8");
       return JSON.parse(raw);
     } catch {
       return void 0;
@@ -2433,11 +3049,11 @@ var Storage = class {
   }
   async getAllKnowledge() {
     try {
-      const files = await fs3.readdir(this.knowledgeDir);
+      const files = await fs4.readdir(this.knowledgeDir);
       const items = [];
       for (const file of files) {
         if (!file.endsWith(".json")) continue;
-        const raw = await fs3.readFile(path3.join(this.knowledgeDir, file), "utf-8");
+        const raw = await fs4.readFile(path4.join(this.knowledgeDir, file), "utf-8");
         try {
           items.push(JSON.parse(raw));
         } catch {
@@ -2450,9 +3066,9 @@ var Storage = class {
   }
   async deleteKnowledge(id) {
     const filename = `${sanitizeFileName(id)}.json`;
-    const filePath = path3.join(this.knowledgeDir, filename);
+    const filePath = path4.join(this.knowledgeDir, filename);
     try {
-      await fs3.unlink(filePath);
+      await fs4.unlink(filePath);
       return true;
     } catch {
       return false;
@@ -2460,17 +3076,17 @@ var Storage = class {
   }
   // --- Evidence ---
   async saveEvidence(evidence) {
-    await fs3.mkdir(this.evidenceDir, { recursive: true });
+    await fs4.mkdir(this.evidenceDir, { recursive: true });
     const filename = `${sanitizeFileName(evidence.id)}.json`;
-    const filePath = path3.join(this.evidenceDir, filename);
-    await fs3.writeFile(filePath, JSON.stringify(evidence, null, 2), "utf-8");
-    await fs3.appendFile(this.evidenceJsonlFile, JSON.stringify(evidence) + "\n", "utf-8");
+    const filePath = path4.join(this.evidenceDir, filename);
+    await fs4.writeFile(filePath, JSON.stringify(evidence, null, 2), "utf-8");
+    await fs4.appendFile(this.evidenceJsonlFile, JSON.stringify(evidence) + "\n", "utf-8");
   }
   async getEvidence(id) {
     const filename = `${sanitizeFileName(id)}.json`;
-    const filePath = path3.join(this.evidenceDir, filename);
+    const filePath = path4.join(this.evidenceDir, filename);
     try {
-      const raw = await fs3.readFile(filePath, "utf-8");
+      const raw = await fs4.readFile(filePath, "utf-8");
       return JSON.parse(raw);
     } catch {
       return void 0;
@@ -2478,11 +3094,11 @@ var Storage = class {
   }
   async getAllEvidence() {
     try {
-      const files = await fs3.readdir(this.evidenceDir);
+      const files = await fs4.readdir(this.evidenceDir);
       const items = [];
       for (const file of files) {
         if (!file.endsWith(".json")) continue;
-        const raw = await fs3.readFile(path3.join(this.evidenceDir, file), "utf-8");
+        const raw = await fs4.readFile(path4.join(this.evidenceDir, file), "utf-8");
         try {
           items.push(JSON.parse(raw));
         } catch {
@@ -2495,17 +3111,17 @@ var Storage = class {
   }
   // --- Observations ---
   async saveObservation(obs) {
-    await fs3.mkdir(this.observationDir, { recursive: true });
+    await fs4.mkdir(this.observationDir, { recursive: true });
     const filename = `${sanitizeFileName(obs.id)}.json`;
-    const filePath = path3.join(this.observationDir, filename);
-    await fs3.writeFile(filePath, JSON.stringify(obs, null, 2), "utf-8");
-    await fs3.appendFile(this.observationJsonlFile, JSON.stringify(obs) + "\n", "utf-8");
+    const filePath = path4.join(this.observationDir, filename);
+    await fs4.writeFile(filePath, JSON.stringify(obs, null, 2), "utf-8");
+    await fs4.appendFile(this.observationJsonlFile, JSON.stringify(obs) + "\n", "utf-8");
   }
   async getObservation(id) {
     const filename = `${sanitizeFileName(id)}.json`;
-    const filePath = path3.join(this.observationDir, filename);
+    const filePath = path4.join(this.observationDir, filename);
     try {
-      const raw = await fs3.readFile(filePath, "utf-8");
+      const raw = await fs4.readFile(filePath, "utf-8");
       return JSON.parse(raw);
     } catch {
       return void 0;
@@ -2513,11 +3129,11 @@ var Storage = class {
   }
   async getAllObservations() {
     try {
-      const files = await fs3.readdir(this.observationDir);
+      const files = await fs4.readdir(this.observationDir);
       const items = [];
       for (const file of files) {
         if (!file.endsWith(".json")) continue;
-        const raw = await fs3.readFile(path3.join(this.observationDir, file), "utf-8");
+        const raw = await fs4.readFile(path4.join(this.observationDir, file), "utf-8");
         try {
           items.push(JSON.parse(raw));
         } catch {
@@ -2530,9 +3146,9 @@ var Storage = class {
   }
   async deleteObservation(id) {
     const filename = `${sanitizeFileName(id)}.json`;
-    const filePath = path3.join(this.observationDir, filename);
+    const filePath = path4.join(this.observationDir, filename);
     try {
-      await fs3.unlink(filePath);
+      await fs4.unlink(filePath);
       return true;
     } catch {
       return false;
@@ -2540,17 +3156,17 @@ var Storage = class {
   }
   // --- Unknowns ---
   async saveUnknown(record) {
-    await fs3.mkdir(this.unknownDir, { recursive: true });
+    await fs4.mkdir(this.unknownDir, { recursive: true });
     const filename = `${sanitizeFileName(record.id)}.json`;
-    const filePath = path3.join(this.unknownDir, filename);
-    await fs3.writeFile(filePath, JSON.stringify(record, null, 2), "utf-8");
-    await fs3.appendFile(this.unknownsJsonlFile, JSON.stringify(record) + "\n", "utf-8");
+    const filePath = path4.join(this.unknownDir, filename);
+    await fs4.writeFile(filePath, JSON.stringify(record, null, 2), "utf-8");
+    await fs4.appendFile(this.unknownsJsonlFile, JSON.stringify(record) + "\n", "utf-8");
   }
   async getUnknown(id) {
     const filename = `${sanitizeFileName(id)}.json`;
-    const filePath = path3.join(this.unknownDir, filename);
+    const filePath = path4.join(this.unknownDir, filename);
     try {
-      const raw = await fs3.readFile(filePath, "utf-8");
+      const raw = await fs4.readFile(filePath, "utf-8");
       return JSON.parse(raw);
     } catch {
       return void 0;
@@ -2558,11 +3174,11 @@ var Storage = class {
   }
   async getAllUnknowns() {
     try {
-      const files = await fs3.readdir(this.unknownDir);
+      const files = await fs4.readdir(this.unknownDir);
       const items = [];
       for (const file of files) {
         if (!file.endsWith(".json")) continue;
-        const raw = await fs3.readFile(path3.join(this.unknownDir, file), "utf-8");
+        const raw = await fs4.readFile(path4.join(this.unknownDir, file), "utf-8");
         try {
           items.push(JSON.parse(raw));
         } catch {
@@ -2575,9 +3191,9 @@ var Storage = class {
   }
   async deleteUnknown(id) {
     const filename = `${sanitizeFileName(id)}.json`;
-    const filePath = path3.join(this.unknownDir, filename);
+    const filePath = path4.join(this.unknownDir, filename);
     try {
-      await fs3.unlink(filePath);
+      await fs4.unlink(filePath);
       return true;
     } catch {
       return false;
@@ -2586,7 +3202,7 @@ var Storage = class {
   // --- Outcomes (Append-oriented log) ---
   async appendOutcome(outcome) {
     const line = JSON.stringify(outcome) + "\n";
-    await fs3.appendFile(this.outcomesFile, line, "utf-8");
+    await fs4.appendFile(this.outcomesFile, line, "utf-8");
     if (outcome.knowledgeId) {
       await this.appendMetricEvent({
         type: "outcome",
@@ -2605,7 +3221,7 @@ var Storage = class {
   }
   async getAllOutcomes() {
     try {
-      const raw = await fs3.readFile(this.outcomesFile, "utf-8");
+      const raw = await fs4.readFile(this.outcomesFile, "utf-8");
       const lines = raw.split("\n").filter((l) => l.trim().length > 0);
       return lines.map((l) => JSON.parse(l));
     } catch {
@@ -2615,30 +3231,30 @@ var Storage = class {
   // --- Metric Events (Append-only local log) ---
   async appendMetricEvent(event) {
     try {
-      await fs3.mkdir(this.baseDir, { recursive: true });
-      await fs3.appendFile(this.eventsFile, JSON.stringify(event) + "\n", "utf-8");
+      await fs4.mkdir(this.baseDir, { recursive: true });
+      await fs4.appendFile(this.eventsFile, JSON.stringify(event) + "\n", "utf-8");
     } catch {
     }
   }
   async getMetricEvents(filter) {
-    return readMetricEvents(path3.dirname(this.baseDir), filter);
+    return readMetricEvents(path4.dirname(this.baseDir), filter);
   }
   async resetMetricEvents() {
-    return resetMetricEvents(path3.dirname(this.baseDir));
+    return resetMetricEvents(path4.dirname(this.baseDir));
   }
   // --- Investigation Receipts ---
   async saveReceipt(receipt) {
-    await fs3.mkdir(this.receiptsDir, { recursive: true });
+    await fs4.mkdir(this.receiptsDir, { recursive: true });
     const filename = `${sanitizeFileName(receipt.id)}.json`;
-    const filePath = path3.join(this.receiptsDir, filename);
-    await fs3.writeFile(filePath, JSON.stringify(receipt, null, 2), "utf-8");
-    await fs3.appendFile(this.receiptsJsonlFile, JSON.stringify(receipt) + "\n", "utf-8");
+    const filePath = path4.join(this.receiptsDir, filename);
+    await fs4.writeFile(filePath, JSON.stringify(receipt, null, 2), "utf-8");
+    await fs4.appendFile(this.receiptsJsonlFile, JSON.stringify(receipt) + "\n", "utf-8");
   }
   async getReceipt(id) {
     const filename = `${sanitizeFileName(id)}.json`;
-    const filePath = path3.join(this.receiptsDir, filename);
+    const filePath = path4.join(this.receiptsDir, filename);
     try {
-      const raw = await fs3.readFile(filePath, "utf-8");
+      const raw = await fs4.readFile(filePath, "utf-8");
       return JSON.parse(raw);
     } catch {
       return void 0;
@@ -2646,11 +3262,11 @@ var Storage = class {
   }
   async getAllReceipts() {
     try {
-      const files = await fs3.readdir(this.receiptsDir);
+      const files = await fs4.readdir(this.receiptsDir);
       const items = [];
       for (const file of files) {
         if (!file.endsWith(".json")) continue;
-        const raw = await fs3.readFile(path3.join(this.receiptsDir, file), "utf-8");
+        const raw = await fs4.readFile(path4.join(this.receiptsDir, file), "utf-8");
         try {
           items.push(JSON.parse(raw));
         } catch {
@@ -2664,19 +3280,19 @@ var Storage = class {
   // --- Relations ---
   async getRelations() {
     try {
-      const raw = await fs3.readFile(this.relationsFile, "utf-8");
+      const raw = await fs4.readFile(this.relationsFile, "utf-8");
       return JSON.parse(raw);
     } catch {
       return [];
     }
   }
   async saveRelations(relations) {
-    await fs3.writeFile(this.relationsFile, JSON.stringify(relations, null, 2), "utf-8");
+    await fs4.writeFile(this.relationsFile, JSON.stringify(relations, null, 2), "utf-8");
   }
   // --- Metrics ---
   async getMetrics() {
     try {
-      const raw = await fs3.readFile(this.metricsFile, "utf-8");
+      const raw = await fs4.readFile(this.metricsFile, "utf-8");
       return JSON.parse(raw);
     } catch {
       return {
@@ -2694,14 +3310,14 @@ var Storage = class {
     }
   }
   async saveMetrics(metrics) {
-    await fs3.writeFile(this.metricsFile, JSON.stringify(metrics, null, 2), "utf-8");
+    await fs4.writeFile(this.metricsFile, JSON.stringify(metrics, null, 2), "utf-8");
   }
   // --- Rules ---
   getRulesDir() {
     return this.rulesDir;
   }
   async loadRuleSets() {
-    const files = await findRuleFiles(path3.dirname(this.baseDir), this.rulesDir);
+    const files = await findRuleFiles(path4.dirname(this.baseDir), this.rulesDir);
     const sets = [];
     for (const f of files) {
       try {
@@ -2712,23 +3328,23 @@ var Storage = class {
     return sets;
   }
   async saveRuleSet(ruleSet, fileName = "default.yml") {
-    await fs3.mkdir(this.rulesDir, { recursive: true });
+    await fs4.mkdir(this.rulesDir, { recursive: true });
     const cleanName = fileName.endsWith(".yml") || fileName.endsWith(".yaml") ? fileName : `${fileName}.yml`;
-    const targetPath = path3.join(this.rulesDir, cleanName);
+    const targetPath = path4.join(this.rulesDir, cleanName);
     const yaml = stringifyRuleSetYaml(ruleSet);
-    await fs3.writeFile(targetPath, yaml, "utf-8");
+    await fs4.writeFile(targetPath, yaml, "utf-8");
     return targetPath;
   }
   async addRule(rule, fileName = "default.yml") {
-    await fs3.mkdir(this.rulesDir, { recursive: true });
+    await fs4.mkdir(this.rulesDir, { recursive: true });
     const cleanName = fileName.endsWith(".yml") || fileName.endsWith(".yaml") ? fileName : `${fileName}.yml`;
-    const targetPath = path3.join(this.rulesDir, cleanName);
+    const targetPath = path4.join(this.rulesDir, cleanName);
     let existingSet;
     try {
       existingSet = await loadRuleSetFile(targetPath);
     } catch {
       existingSet = {
-        name: path3.basename(cleanName, path3.extname(cleanName)),
+        name: path4.basename(cleanName, path4.extname(cleanName)),
         rules: []
       };
     }
@@ -2739,17 +3355,17 @@ var Storage = class {
       existingSet.rules.push(rule);
     }
     const yaml = stringifyRuleSetYaml(existingSet);
-    await fs3.writeFile(targetPath, yaml, "utf-8");
+    await fs4.writeFile(targetPath, yaml, "utf-8");
     return targetPath;
   }
   // --- Revisions & Incremental Learning Diff ---
   async appendRevision(snapshot) {
     const line = JSON.stringify(snapshot) + "\n";
-    await fs3.appendFile(this.revisionsFile, line, "utf-8");
+    await fs4.appendFile(this.revisionsFile, line, "utf-8");
   }
   async getRevisions() {
     try {
-      const raw = await fs3.readFile(this.revisionsFile, "utf-8");
+      const raw = await fs4.readFile(this.revisionsFile, "utf-8");
       const lines = raw.split("\n").filter((l) => l.trim().length > 0);
       return lines.map((l) => JSON.parse(l));
     } catch {
@@ -2888,7 +3504,7 @@ function formatKnowledgeDiff(diff) {
 }
 
 // src/storage/portable.ts
-import YAML2 from "yaml";
+import YAML3 from "yaml";
 function exportKnowledgeToYaml(items, options = {}) {
   let filtered = items;
   if (options.scope) {
@@ -2919,10 +3535,10 @@ function exportKnowledgeToYaml(items, options = {}) {
       }
     }))
   };
-  return YAML2.stringify(payload, { indent: 2, lineWidth: 100 });
+  return YAML3.stringify(payload, { indent: 2, lineWidth: 100 });
 }
 async function importKnowledgeFromYaml(yamlContent, storage) {
-  const parsed = YAML2.parse(yamlContent);
+  const parsed = YAML3.parse(yamlContent);
   if (!parsed || typeof parsed !== "object") {
     throw new Error("Invalid YAML: root must be an object");
   }
@@ -2981,10 +3597,10 @@ async function dumpToYaml(storage) {
     relations,
     metrics
   };
-  return YAML2.stringify(dump, { indent: 2, lineWidth: 120 });
+  return YAML3.stringify(dump, { indent: 2, lineWidth: 120 });
 }
 async function restoreFromYaml(yamlContent, storage) {
-  const parsed = YAML2.parse(yamlContent);
+  const parsed = YAML3.parse(yamlContent);
   if (!parsed || parsed.schemaVersion !== 1) {
     throw new Error(`Unsupported snapshot schema version: ${parsed?.schemaVersion}`);
   }
@@ -3143,8 +3759,8 @@ async function compact(storage, options = {}) {
 }
 
 // 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",
@@ -3165,12 +3781,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();
@@ -3218,7 +3834,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;
       }
@@ -3228,14 +3844,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))) {
@@ -3251,16 +3867,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 stat3 = await fs4.stat(fullPath);
+          const stat4 = await fs5.stat(fullPath);
           const fileInfo = {
             path: fullPath,
             relativePath: relPath,
             name: entry.name,
             ext,
-            size: stat3.size,
-            mtimeMs: stat3.mtimeMs,
+            size: stat4.size,
+            mtimeMs: stat4.mtimeMs,
             isDirectory: false
           };
           if (!options.filter || options.filter(fileInfo)) {
@@ -3303,9 +3919,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();
@@ -3734,12 +4350,12 @@ async function analyzeProjectStructure(files, rootDir, registry = defaultRegistr
 }
 
 // src/scanner/markdown.ts
-import * as fs5 from "fs/promises";
-import * as path5 from "path";
-import YAML3 from "yaml";
+import * as fs6 from "fs/promises";
+import * as path6 from "path";
+import YAML4 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 = [];
@@ -3768,7 +4384,7 @@ function parseMarkdownDocument(content, filePath, relativePath) {
         bodyStartIndex = i + 1;
         try {
           const yamlText = frontmatterLines.join("\n");
-          const parsed = YAML3.parse(yamlText);
+          const parsed = YAML4.parse(yamlText);
           if (parsed && typeof parsed === "object") {
             frontmatter = parsed;
           }
@@ -4156,8 +4772,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,
@@ -4213,7 +4829,7 @@ function registerMarkdownExtractor(extractor) {
 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: [] };
   }
@@ -4222,11 +4838,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
   });
@@ -4420,9 +5036,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([
@@ -4476,7 +5092,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;
@@ -4484,8 +5100,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)) {
@@ -4498,7 +5114,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) {
@@ -4857,7 +5473,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 };
   }
@@ -4865,8 +5481,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 {
@@ -4892,7 +5508,7 @@ async function analyzeSourceFile(filePath, relativePath) {
 }
 
 // src/scanner/engine.ts
-import * as path7 from "path";
+import * as path8 from "path";
 
 // src/rules/evaluator.ts
 function globToRegex(glob) {
@@ -5074,9 +5690,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;
@@ -5149,7 +5765,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",
@@ -5262,7 +5878,7 @@ async function scanRepository(rootDir = process.cwd(), options = {}) {
 
 // src/mcp/server.ts
 import { McpApp, z } from "mcponce";
-import * as path8 from "path";
+import * as path9 from "path";
 
 // src/stats/aggregator.ts
 function formatPercentage(ratio) {
@@ -5387,8 +6003,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;
@@ -5559,7 +6201,8 @@ async function computeStats(storage, events, options) {
       questionResolutionRate,
       jevRejectionRate
     },
-    health
+    health,
+    preflight: preflight.runs > 0 ? preflight : void 0
   };
 }
 async function computeKnowledgeStats(storage, knowledgeId, events) {
@@ -5628,9 +6271,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);
@@ -5662,7 +6305,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 }
@@ -5758,6 +6401,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) {
@@ -5827,17 +6487,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",
@@ -5847,6 +6546,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)"),
@@ -5854,8 +6554,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,
@@ -5864,7 +6564,7 @@ function createBilmemMcpApp(options = {}) {
           scope: args.scope,
           maxDepth: args.maxDepth
         },
-        storage,
+        ctx.storage,
         retriever
       );
       return {
@@ -5881,10 +6581,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)"),
@@ -5892,8 +6635,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,
@@ -5920,6 +6663,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)"),
@@ -5928,7 +6672,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,
@@ -5942,10 +6686,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,
@@ -5966,10 +6710,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,
@@ -5983,6 +6727,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"),
@@ -5998,16 +6743,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,
@@ -6023,20 +6768,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;
           }
@@ -6048,9 +6793,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,
@@ -6072,12 +6817,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}"` };
       }
@@ -6111,6 +6857,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(),
@@ -6119,16 +6866,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;
       }
@@ -6142,12 +6889,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" };
@@ -6157,16 +6904,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;
     }
   });
@@ -6174,13 +6921,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
       });
@@ -6194,20 +6942,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;
@@ -6219,6 +6967,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,
@@ -6242,18 +6992,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;
@@ -6261,7 +7164,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 };
@@ -6341,7 +7244,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;
@@ -6376,7 +7279,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 };
@@ -6391,7 +7294,7 @@ async function removeMarkdownInstructionFile(filePath, dryRun = false) {
   if (stripped.length === 0) {
     if (!dryRun) {
       try {
-        await fs7.unlink(filePath);
+        await fs8.unlink(filePath);
       } catch {
       }
     }
@@ -6404,21 +7307,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 {
     }
@@ -6427,9 +7366,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);
@@ -6475,6 +7414,7 @@ async function getIntegrationRecord(rootDir, agentId) {
 
 // src/install/adapters/base.ts
 var BaseAgentAdapter = class {
+  aliases;
   supportedScopes = ["project", "global"];
   async inspect(context) {
     const configPath = this.resolveConfigPath(context);
@@ -6488,12 +7428,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) {
@@ -6501,6 +7443,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,
@@ -6510,9 +7466,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
@@ -6532,7 +7491,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");
@@ -6557,6 +7516,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,
@@ -6564,9 +7536,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()
         },
@@ -6577,7 +7551,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");
     }
@@ -6588,6 +7562,8 @@ var BaseAgentAdapter = class {
       scope: options.scope,
       mcpChanged: mcpRes.changed,
       instructionChanged: instRes.changed,
+      skillChanged,
+      skillPath,
       projectInitialized,
       dryRun: options.dryRun,
       actionsTaken,
@@ -6607,10 +7583,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");
     }
@@ -6621,6 +7606,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}`
@@ -6632,6 +7619,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`);
@@ -6652,17 +7640,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
@@ -6676,23 +7678,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);
@@ -6700,7 +7702,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");
@@ -6717,31 +7719,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);
@@ -6751,7 +7753,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");
@@ -6768,31 +7770,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);
@@ -6802,7 +7804,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");
@@ -6819,31 +7821,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);
@@ -6853,7 +7855,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");
@@ -6869,12 +7871,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];
@@ -6894,7 +7994,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;
@@ -6986,6 +8086,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) {
@@ -6999,9 +8119,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) {
@@ -7021,18 +8143,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
@@ -7139,6 +8262,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})` : ""}`);
     }
@@ -7183,7 +8310,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,
@@ -7204,7 +8331,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);
@@ -7286,7 +8413,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 = {
@@ -7308,7 +8435,7 @@ async function handleDoctorCommand(options = {}) {
 }
 
 // src/runtime.ts
-import * as path18 from "path";
+import * as path20 from "path";
 var Bilmem = class {
   rootDir;
   storage;
@@ -7316,7 +8443,7 @@ var Bilmem = class {
   retriever;
   initialized = false;
   constructor(options = {}) {
-    this.rootDir = options.rootDir ? path18.resolve(options.rootDir) : process.cwd();
+    this.rootDir = options.rootDir ? path20.resolve(options.rootDir) : process.cwd();
     this.storage = new Storage(this.rootDir);
     this.index = new SearchIndex();
     this.retriever = new Retriever(this.index, this.storage);
@@ -7491,6 +8618,15 @@ ${item.result.reason}`
     await this.ensureInitialized();
     return resolveEpistemicQuery(options, this.storage, this.retriever);
   }
+  /**
+   * Preflight analysis:
+   * Answers "What must I know before I start this work?"
+   * Analyzes existing constraints, relevant lessons, stale knowledge, and important unknowns.
+   */
+  async preflight(options) {
+    await this.ensureInitialized();
+    return executePreflight(options, this.storage, this.retriever, this.index);
+  }
   /**
    * Check knowledge staleness based on changed source files.
    */
@@ -7629,6 +8765,7 @@ function createBilmem(options) {
   return new Bilmem(options);
 }
 export {
+  AntigravityAdapter,
   BILMEM_END_MARKER,
   BILMEM_START_MARKER,
   BUILTIN_DETECTORS,
@@ -7663,6 +8800,7 @@ export {
   checkKnowledgeListStaleness,
   checkKnowledgeStaleness,
   classifyKnowledgeHealth,
+  classifyUnknown,
   compact,
   computeKnowledgeStats,
   computeStats,
@@ -7688,8 +8826,10 @@ export {
   evaluatePromotion,
   evaluateRule,
   evaluateRuleSet,
+  executePreflight,
   exportKnowledgeToYaml,
   extractInstructionVersion,
+  extractSkillVersion,
   findRuleFiles,
   formatDoctorFixResult,
   formatDoctorReport,
@@ -7697,6 +8837,7 @@ export {
   formatJevExplanation,
   formatKnowledgeDiff,
   formatKnowledgeStatsReport,
+  formatPreflightReport,
   formatStatsReport,
   formatUninstallResult,
   formatWhyExplanation,
@@ -7704,6 +8845,7 @@ export {
   getAdapter,
   getAgentInstructionText,
   getAllAdapters,
+  getBilmemSkillContent,
   getEventsFilePath,
   getIntegrationRecord,
   getIntegrationsFilePath,
@@ -7712,8 +8854,10 @@ export {
   handleUninstallCommand,
   hasBeenInvestigated,
   hasBilmemInstruction,
+  hasBilmemSkill,
   hashString,
   importKnowledgeFromYaml,
+  inferLikelyDomains,
   isExecutableInPath,
   isGitRepository,
   isSourceFile,
@@ -7727,6 +8871,7 @@ export {
   parseMarkdownFile,
   parseRuleSetYaml,
   pathExists,
+  prioritizeQuestions,
   processUserCorrection,
   readMetricEvents,
   reconcileKnowledge,
@@ -7737,6 +8882,7 @@ export {
   removeIntegration,
   removeMarkdownInstructionFile,
   removeMcpJsonConfig,
+  removeSkillFile,
   rerankCandidates,
   resetMetricEvents,
   resolveEpistemicQuery,
@@ -7754,8 +8900,10 @@ export {
   scanRepository,
   stringifyRuleSetYaml,
   tierToConfidence,
+  tokenizeGoal,
   updateMarkdownInstructionFile,
   updateMcpJsonConfig,
+  updateSkillFile,
   updateUnknown,
   validateRuleDefinition,
   validateRuleSet,