@fenglimg/fabric-server 1.8.0-rc.3 → 2.0.0-rc.8

package/dist/{http-PXFWUKCA.js → http-AR26GYEV.js}

@@ -1,21 +1,20 @@
 import {
-  AGENTS_MD_RESOURCE_URI,
   EVENT_LEDGER_PATH,
   LEDGER_PATH,
   LEGACY_LEDGER_PATH,
   appendEventLedgerEvent,
   contextCache,
   getEventLedgerPath,
+  getKnowledge,
   getLedgerPath,
   getLegacyLedgerPath,
-  getRules,
-  invalidateRuleSyncCooldown,
+  invalidateKnowledgeSyncCooldown,
   isNodeError,
   readAgentsMeta,
   readEventLedger,
   runDoctorReport,
   sha256
-} from "./chunk-ZZGARZL5.js";
+} from "./chunk-AR2HV5JT.js";
 
 // src/http.ts
 import { randomUUID as randomUUID2 } from "crypto";
@@ -87,7 +86,6 @@ import { join } from "path";
 import {
   agentsMetaSchema,
   fabricEventSchema,
-  forensicReportSchema,
   ledgerEntrySchema as ledgerEntrySchema2
 } from "@fenglimg/fabric-shared";
 import { eventLedgerEventSchema } from "@fenglimg/fabric-shared";
@@ -132,34 +130,6 @@ async function readLegacyLedger(projectRoot) {
   }
   return raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0).map((line, index) => parseLedgerLine(line, index)).filter((entry) => entry !== null);
 }
-async function appendLedgerEntry(projectRoot, entry) {
-  const nextEntry = createStoredLedgerEntry(entry);
-  for (const affectedPath of nextEntry.affected_paths) {
-    await appendEventLedgerEvent(projectRoot, {
-      event_type: "edit_intent_checked",
-      ts: nextEntry.ts,
-      path: affectedPath,
-      compliant: true,
-      intent: nextEntry.intent,
-      ledger_entry_id: nextEntry.id,
-      ledger_source: nextEntry.source,
-      commit_sha: nextEntry.source === "ai" ? nextEntry.commit_sha : void 0,
-      parent_sha: nextEntry.source === "human" ? nextEntry.parent_sha : void 0,
-      parent_ledger_entry_id: nextEntry.source === "human" ? nextEntry.parent_ledger_entry_id : void 0,
-      diff_stat: nextEntry.source === "human" ? nextEntry.diff_stat : void 0,
-      annotation: nextEntry.source === "human" ? nextEntry.annotation : void 0,
-      matched_rule_context_ts: null,
-      window_ms: 0
-    });
-  }
-  return nextEntry;
-}
-function createStoredLedgerEntry(entry) {
-  return ledgerEntrySchema.parse({
-    ...entry,
-    id: entry.id ?? `ledger:${randomUUID()}`
-  });
-}
 function parseLedgerLine(line, index) {
   try {
     const parsed = JSON.parse(line);
@@ -254,10 +224,8 @@ async function pathExists(path) {
 
 // src/api/events.ts
 var AGENTS_META_PATH = ".fabric/agents.meta.json";
-var FORENSIC_PATH = ".fabric/forensic.json";
 var WATCHED_PATHS = [
   AGENTS_META_PATH,
-  FORENSIC_PATH,
   EVENT_LEDGER_PATH,
   LEDGER_PATH,
   LEGACY_LEDGER_PATH
@@ -438,10 +406,6 @@ async function readEventsForFile(state, projectRoot, relativePath) {
     const event = await readMetaUpdatedEvent(projectRoot);
     return event === null ? [] : [event];
   }
-  if (relativePath === FORENSIC_PATH) {
-    const event = await readDriftDetectedEvent(projectRoot);
-    return event === null ? [] : [event];
-  }
   if (relativePath === EVENT_LEDGER_PATH) {
     return await readEventLedgerAppendedEvents(state, projectRoot);
   }
@@ -462,18 +426,6 @@ async function readMetaUpdatedEvent(projectRoot) {
     payload: parsed
   };
 }
-async function readDriftDetectedEvent(projectRoot) {
-  const filePath = join(projectRoot, FORENSIC_PATH);
-  const raw = await readUtf8File(filePath);
-  if (raw === null) {
-    return null;
-  }
-  const parsed = forensicReportSchema.parse(JSON.parse(raw));
-  return {
-    type: "drift:detected",
-    payload: parsed
-  };
-}
 async function readLedgerAppendedEvents(state, projectRoot) {
   const ledgerState = await resolveLedgerWatchState(projectRoot);
   const ledgerPath = ledgerState.path;
@@ -830,60 +782,6 @@ function registerHistoryApi(app, projectRoot) {
   });
 }
 
-// src/api/intent.ts
-import { annotateIntentRequestSchema } from "@fenglimg/fabric-shared";
-
-// src/services/annotate-intent.ts
-async function annotateIntent(projectRoot, input) {
-  const entries = await readLedger(projectRoot);
-  const parentEntry = entries.find((entry2) => entry2.id === input.ledger_entry_id);
-  if (parentEntry === void 0) {
-    throw new LedgerEntryNotFoundError(`Cannot find ledger entry: ${input.ledger_entry_id}`);
-  }
-  const lastEntry = entries[entries.length - 1];
-  if (lastEntry?.source === "human" && lastEntry.parent_ledger_entry_id === input.ledger_entry_id && lastEntry.annotation === input.annotation) {
-    return {
-      created: false,
-      entry: lastEntry
-    };
-  }
-  const entry = await appendLedgerEntry(projectRoot, createAnnotationEntry(parentEntry, input));
-  return {
-    created: true,
-    entry
-  };
-}
-function createAnnotationEntry(parentEntry, input) {
-  return {
-    ts: Date.now(),
-    source: "human",
-    parent_sha: input.ledger_entry_id,
-    parent_ledger_entry_id: input.ledger_entry_id,
-    intent: input.annotation,
-    annotation: input.annotation,
-    affected_paths: parentEntry.affected_paths,
-    diff_stat: "annotation"
-  };
-}
-
-// src/api/intent.ts
-function registerIntentApi(app, projectRoot) {
-  app.post("/api/intent/annotate", async (req, res) => {
-    const validation = annotateIntentRequestSchema.safeParse(req.body);
-    if (!validation.success) {
-      sendValidationError(res, "Invalid intent annotation payload", validation.error.flatten());
-      return;
-    }
-    try {
-      await readAgentsMeta(projectRoot);
-      const result = await annotateIntent(projectRoot, validation.data);
-      res.status(result.created ? 201 : 200).json(result);
-    } catch (error) {
-      sendUnknownError(res, error);
-    }
-  });
-}
-
 // src/api/ledger.ts
 import { ledgerQuerySchema } from "@fenglimg/fabric-shared";
 function registerLedgerApi(app, projectRoot) {
@@ -905,8 +803,8 @@ function registerLedgerApi(app, projectRoot) {
   });
 }
 
-// src/api/rules.ts
-function registerRulesApi(app, projectRoot) {
+// src/api/knowledge.ts
+function registerKnowledgeApi(app, projectRoot) {
   app.get("/api/rules", async (_req, res) => {
     try {
       res.json(await readAgentsMeta(projectRoot));
@@ -916,8 +814,8 @@ function registerRulesApi(app, projectRoot) {
   });
 }
 
-// src/api/rules-context.ts
-function registerRulesContextApi(app, projectRoot) {
+// src/api/knowledge-context.ts
+function registerKnowledgeContextApi(app, projectRoot) {
   app.get("/api/rules/context", async (req, res) => {
     const path = typeof req.query.path === "string" ? req.query.path.trim() : "";
     if (path.length === 0) {
@@ -929,7 +827,7 @@ function registerRulesContextApi(app, projectRoot) {
       return;
     }
     try {
-      const result = await getRules(projectRoot, { path });
+      const result = await getKnowledge(projectRoot, { path });
       res.json(result.rules);
     } catch (error) {
       sendUnknownError(res, error);
@@ -967,7 +865,7 @@ async function createScanReport(targetInput = process.cwd()) {
   const framework = detectFramework(target);
   const readmeQuality = getReadmeQuality(target);
   const hasContributing = existsSync(join2(target, "CONTRIBUTING.md"));
-  const hasExistingFabric = existsSync(join2(target, ".fabric", "bootstrap", "README.md")) || existsSync(join2(target, ".fabric"));
+  const hasExistingFabric = existsSync(join2(target, ".fabric"));
   const walkResult = walkFiles(target, DEFAULT_IGNORES);
   return {
     target,
@@ -1044,13 +942,13 @@ function toPosixPath(path) {
 function buildRecommendations(input) {
   const recommendations = [];
   if (!input.hasExistingFabric) {
-    recommendations.push("L0: Run fab init to scaffold .fabric/bootstrap/README.md with TODO markers.");
+    recommendations.push("L0: Run `fab init` to scaffold the .fabric/ knowledge layout (decisions, pitfalls, guidelines, models, processes).");
   }
   if (input.readmeQuality === "stub") {
-    recommendations.push("L0: Expand README.md before promoting project facts into Fabric references.");
+    recommendations.push("L0: Expand README.md before promoting project facts into Fabric knowledge entries.");
   }
   if (!input.hasContributing) {
-    recommendations.push("L0: Add CONTRIBUTING.md or leave a bootstrap TODO reference for contribution flow.");
+    recommendations.push("L0: Add CONTRIBUTING.md or capture contribution-flow guidance under .fabric/knowledge/processes/.");
   }
   if (input.framework.kind === "unknown") {
     recommendations.push("L1: Add tech-stack TODOs manually because no framework marker was detected.");
@@ -1060,42 +958,6 @@ function buildRecommendations(input) {
   return recommendations;
 }
 
-// src/api/static.ts
-import { existsSync as existsSync2 } from "fs";
-import { dirname, resolve as resolve2 } from "path";
-import { fileURLToPath } from "url";
-import express from "express";
-var DEFAULT_STATIC_DIR = resolve2(dirname(fileURLToPath(import.meta.url)), "static");
-function registerDashboardStatic(app, options = {}) {
-  if (options.dev ?? process.env.NODE_ENV === "development") {
-    return;
-  }
-  const staticDir = resolve2(options.dashboardDistPath ?? DEFAULT_STATIC_DIR);
-  const indexPath = resolve2(staticDir, "index.html");
-  if (!existsSync2(indexPath)) {
-    warnMissingDashboard(staticDir);
-    app.get("/", (_req, res) => {
-      res.status(404).json({
-        error: {
-          code: "DASHBOARD_DIST_MISSING",
-          message: `Fabric dashboard dist was not found at ${staticDir}. Run pnpm --filter @fenglimg/fabric-dashboard build.`
-        }
-      });
-    });
-    return;
-  }
-  app.use("/", express.static(staticDir, { index: "index.html", fallthrough: true }));
-  app.get(/^\/(?!api(?:\/|$)|mcp(?:\/|$)|events(?:\/|$)).*/, (_req, res) => {
-    res.sendFile(indexPath);
-  });
-}
-function warnMissingDashboard(staticDir) {
-  process.stderr.write(
-    `[fabric-server] dashboard dist missing at ${staticDir}; '/' will return 404 until dashboard assets are built.
-`
-  );
-}
-
 // src/middleware/bearer-auth.ts
 import { createHash, timingSafeEqual } from "crypto";
 function createBearerAuthMiddleware(token) {
@@ -1221,23 +1083,13 @@ function handleCacheWatcherEvent(relativePath, projectRoot, sessions, timers) {
     );
     return;
   }
-  if (normalized === ".fabric/bootstrap/README.md") {
-    contextCache.invalidate("file_watch", projectRoot);
-    clearTimeout(timers.getAgentsMdTimer());
-    timers.setAgentsMdTimer(
-      setTimeout(() => {
-        notifyAllSessions(sessions, "resource_updated", AGENTS_MD_RESOURCE_URI);
-      }, NOTIFY_DEBOUNCE_MS)
-    );
-    return;
-  }
-  if (normalized.startsWith(".fabric/rules/") && normalized.endsWith(".md")) {
+  if (normalized.startsWith(".fabric/knowledge/") && normalized.endsWith(".md")) {
     contextCache.invalidate("file_watch", projectRoot);
-    invalidateRuleSyncCooldown(projectRoot);
+    invalidateKnowledgeSyncCooldown(projectRoot);
   }
 }
 function createFabricHttpApp(options) {
-  const { projectRoot, host = DEFAULT_HOST, authToken, dashboardDistPath, dev } = options;
+  const { projectRoot, host = DEFAULT_HOST, authToken } = options;
   const app = createMcpExpressApp({ host });
   const eventStore = new JsonlEventStore(projectRoot);
   const sessions = /* @__PURE__ */ new Map();
@@ -1245,8 +1097,8 @@ function createFabricHttpApp(options) {
   const cacheWatcher = chokidar2.watch(
     [
       ".fabric/agents.meta.json",
-      ".fabric/bootstrap/README.md",
-      ".fabric/rules/**/*.md"
+      ".fabric/knowledge/**/*.md",
+      ".fabric/knowledge/pending/**/*.md"
     ],
     {
       cwd: projectRoot,
@@ -1291,13 +1143,12 @@ function createFabricHttpApp(options) {
     app.use("/events", bearerAuth);
     app.use("/mcp", bearerAuth);
   }
-  registerRulesApi(app, projectRoot);
-  registerRulesContextApi(app, projectRoot);
+  registerKnowledgeApi(app, projectRoot);
+  registerKnowledgeContextApi(app, projectRoot);
   registerLedgerApi(app, projectRoot);
   registerHistoryApi(app, projectRoot);
   registerScanApi(app, projectRoot);
   registerDoctorApi(app, projectRoot);
-  registerIntentApi(app, projectRoot);
   app.get("/events", createEventsHandler({ projectRoot }));
   app.all("/mcp", async (req, res) => {
     const sessionId = readHeader(req.headers["mcp-session-id"]);
@@ -1317,7 +1168,6 @@ function createFabricHttpApp(options) {
     const session = await createSession(eventStore, sessions);
     await session.transport.handleRequest(req, res, req.body);
   });
-  registerDashboardStatic(app, { dashboardDistPath, dev });
   return app;
 }
 function notifyAllSessions(sessions, kind, uri) {

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { Server } from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { AgentsMeta, RuleTestIndex, AgentsLayer, AgentsTopologyType } from '@fenglimg/fabric-shared';
+import { AgentsMeta, KnowledgeTestIndex, AgentsLayer, AgentsTopologyType, Layer, KnowledgeType, StableId, AgentsMetaCounters, EventLedgerEventInput, EventLedgerEvent, RuleDescriptionIndexItem } from '@fenglimg/fabric-shared';
+import { FabExtractKnowledgeInput, FabExtractKnowledgeOutput, FabReviewInput, FabReviewOutput } from '@fenglimg/fabric-shared/schemas/api-contracts';
 import { IOFabricError } from '@fenglimg/fabric-shared/errors';
 
 interface InFlightTracker {
@@ -76,33 +77,116 @@ type DoctorFixReport = {
     message: string;
     report: DoctorReport;
 };
+type DoctorApplyLintMutationKind = "knowledge_orphan_demote_required" | "knowledge_stale_archive_required" | "knowledge_index_drift" | "knowledge_pending_auto_archive" | "knowledge_session_hints_stale_cleanup";
+type DoctorApplyLintMutation = {
+    kind: DoctorApplyLintMutationKind;
+    path: string;
+    detail: string;
+    applied: boolean;
+    error?: string;
+};
+type DoctorApplyLintReport = {
+    changed: boolean;
+    mutations: DoctorApplyLintMutation[];
+    manual_errors: DoctorIssue[];
+    aborted: boolean;
+    abort_reason?: string;
+    message: string;
+    report: DoctorReport;
+};
 declare function runDoctorReport(target: string): Promise<DoctorReport>;
 declare function runDoctorFix(target: string): Promise<DoctorFixReport>;
+declare function runDoctorApplyLint(target: string): Promise<DoctorApplyLintReport>;
 
-type RuleMetaBuildSource = "doctor_fix" | "sync_meta";
-type RuleMetaBuildResult = {
+type KnowledgeMetaBuildSource = "doctor_fix" | "sync_meta";
+type KnowledgeMetaBuildResult = {
     meta: AgentsMeta;
-    ruleTestIndex: RuleTestIndex;
+    knowledgeTestIndex: KnowledgeTestIndex;
     changed: boolean;
 };
-type WriteRuleMetaOptions = {
-    source: RuleMetaBuildSource;
+type WriteKnowledgeMetaOptions = {
+    source: KnowledgeMetaBuildSource;
 };
-declare function buildRuleMeta(projectRootInput: string): Promise<RuleMetaBuildResult>;
-declare function writeRuleMeta(projectRootInput: string, options: WriteRuleMetaOptions): Promise<RuleMetaBuildResult>;
-declare function computeRulesBasedAgentsMeta(projectRootInput: string, existingMeta?: AgentsMeta): Promise<AgentsMeta>;
-declare function computeRuleTestIndex(projectRootInput: string, computedMeta: AgentsMeta, previousIndex?: RuleTestIndex): Promise<RuleTestIndex>;
-declare function deriveRuleMetaLayer(relativePath: string): AgentsLayer;
-declare function deriveRuleMetaTopologyType(relativePath: string): AgentsTopologyType;
-declare function isSameRuleTestIndex(left: RuleTestIndex, right: RuleTestIndex): boolean;
+declare function buildKnowledgeMeta(projectRootInput: string): Promise<KnowledgeMetaBuildResult>;
+declare function writeKnowledgeMeta(projectRootInput: string, options: WriteKnowledgeMetaOptions): Promise<KnowledgeMetaBuildResult>;
+declare function computeKnowledgeBasedAgentsMeta(projectRootInput: string, existingMeta?: AgentsMeta): Promise<AgentsMeta>;
+declare function computeKnowledgeTestIndex(projectRootInput: string, computedMeta: AgentsMeta, previousIndex?: KnowledgeTestIndex): Promise<KnowledgeTestIndex>;
+declare function deriveKnowledgeMetaLayer(relativePath: string): AgentsLayer;
+declare function deriveKnowledgeMetaTopologyType(relativePath: string): AgentsTopologyType;
+declare function isSameKnowledgeTestIndex(left: KnowledgeTestIndex, right: KnowledgeTestIndex): boolean;
 declare function stableStringify(value: unknown): string;
 
 /**
- * Shared constants used across the server package.
+ * v2.0 KnowledgeIdAllocator
+ *
+ * Wraps the pure `allocateKnowledgeId` allocator with persistence: it reads
+ * `agents.meta.json`, advances the counter for the requested (layer, type)
+ * pair, and writes the updated meta atomically (write-to-tmp + rename) so
+ * concurrent readers always see a consistent file.
+ *
+ * Counters are MONOTONIC across the lifetime of the meta file: deleting a
+ * knowledge entry does NOT free its counter slot, so previously-allocated
+ * stable_ids remain unique even after their files are removed.
+ *
+ * Key invariants:
+ *   - Counters envelope is initialized to zeros if absent (v1.x meta compat).
+ *   - Each allocate() call performs read → mutate → atomic-write in sequence.
+ *   - The returned id is guaranteed to differ from every previously-returned
+ *     id for the same meta path.
  */
-/** MCP resource URI for the project's bootstrap README (L0 rules) file. */
-declare const AGENTS_MD_RESOURCE_URI = "fabric://bootstrap-readme";
+declare class KnowledgeIdAllocator {
+    private readonly metaPath;
+    constructor(metaPath: string);
+    /**
+     * Allocate the next stable_id for the given (layer, type) pair and persist
+     * the advanced counter to `agents.meta.json`.
+     */
+    allocate(layer: Layer, type: KnowledgeType): Promise<StableId>;
+    /**
+     * Returns the current counters envelope, defaulting to all-zero slots when
+     * the meta file is absent or pre-v2.0 (counters key missing).
+     */
+    getCounters(): Promise<AgentsMetaCounters>;
+    private readMeta;
+    private normalizeCounters;
+    private writeMetaAtomic;
+}
+
+/**
+ * Append-evidence-on-collision service for fab_extract_knowledge.
+ *
+ * Idempotency_key = sha256({source_session, type, slug}). When the same
+ * triple hits an existing pending file (verified by frontmatter
+ * `x-fabric-idempotency-key`), the body is preserved and a fresh
+ * `## Evidence (call N)` section is appended — LLM-regenerated summaries
+ * stay observable without overwriting prior context.
+ *
+ * NO `id` frontmatter is written — Q2 late-bind delegates id allocation
+ * to rc.3 fab_review approve. See planning-context.md "NO id frontmatter".
+ */
+declare function extractKnowledge(projectRoot: string, input: FabExtractKnowledgeInput): Promise<FabExtractKnowledgeOutput>;
 
+/**
+ * v2.0 rc.3 fab_review service.
+ *
+ * Pure async dispatcher over a discriminated union of 6 actions (list, approve,
+ * reject, modify, search, defer). All branches are implemented as of TASK-002.
+ *
+ * Approve performs late-bind id allocation (KP-/KT- + type-code + monotonic
+ * counter via KnowledgeIdAllocator), emits 2-phase events (knowledge_promote_started
+ * → knowledge_promoted | knowledge_promote_failed), and uses git mv to preserve
+ * file history when the target lives in the team layer (same repo). Personal
+ * layer files use plain fs.rename because they live under ~/.fabric/ outside
+ * the project's git tree.
+ *
+ * Modify implements the only legal stable_id mutation: layer-flip across
+ * KP/KT counter spaces. Allocates a new id under the target layer, renames
+ * the file across layer roots, emits knowledge_layer_changed.
+ */
+declare function reviewKnowledge(projectRoot: string, input: FabReviewInput): Promise<FabReviewOutput>;
+
+type StoredEventLedgerEvent = EventLedgerEvent;
+declare function appendEventLedgerEvent(projectRoot: string, event: EventLedgerEventInput): Promise<StoredEventLedgerEvent>;
 /**
  * Synchronously fsync the event ledger file to ensure OS page-cache buffers are
  * flushed to durable storage. Must be called AFTER in-flight drain but BEFORE
@@ -113,22 +197,79 @@ declare const AGENTS_MD_RESOURCE_URI = "fabric://bootstrap-readme";
  */
 declare function flushAndSyncEventLedger(projectRoot: string): void;
 
+type PlanContextInput = {
+    paths: string[];
+    intent?: string;
+    known_tech?: string[];
+    detected_entities?: Record<string, string[]>;
+    client_hash?: string;
+    correlation_id?: string;
+    session_id?: string;
+    target_paths?: string[];
+};
+type RequirementProfile = {
+    target_path: string;
+    path_segments: string[];
+    extension: string;
+    known_tech: string[];
+    user_intent: string;
+    detected_entities: string[];
+};
+type PlanContextEntry = {
+    path: string;
+    requirement_profile: RequirementProfile;
+    description_index: RuleDescriptionIndexItem[];
+};
+type PlanContextResult = {
+    revision_hash: string;
+    stale: boolean;
+    selection_token: string;
+    entries: PlanContextEntry[];
+    shared: {
+        description_index: RuleDescriptionIndexItem[];
+        preflight_diagnostics: Array<{
+            code: "missing_description";
+            severity: "warn";
+            message: string;
+            stable_ids?: string[];
+            path?: string;
+        }>;
+    };
+};
+type SelectionTokenState = {
+    token: string;
+    revision_hash: string;
+    target_paths: string[];
+    required_stable_ids: string[];
+    ai_selectable_stable_ids: string[];
+    created_at: number;
+    expires_at: number;
+};
+declare function planContext(projectRoot: string, input: PlanContextInput): Promise<PlanContextResult>;
+declare function readSelectionToken(token: string, now?: number): SelectionTokenState | undefined;
+
+/**
+ * Shared constants used across the server package.
+ */
+/** MCP resource URI for the project's bootstrap README (L0 rules) file. */
+declare const AGENTS_MD_RESOURCE_URI = "fabric://bootstrap-readme";
+
 /**
- * rule-sync.ts — Rule-sync orchestrator framework (R28, TASK-011)
+ * knowledge-sync.ts — Rule-sync orchestrator framework (R28, TASK-011)
  *
- * Public surface: ensureRulesFresh, reconcileRules + exported types.
+ * Public surface: ensureKnowledgeFresh, reconcileKnowledge + exported types.
  * Internal helpers are co-located in this file.
  * Does NOT wire any consumers (MCP tools, doctor, watchers).
  *
  * Distinction between the two public entry points:
  *
- * - `ensureRulesFresh`: detects drift, emits ledger events, invalidates cache.
+ * - `ensureKnowledgeFresh`: detects drift, emits ledger events, invalidates cache.
  *   Does NOT rewrite agents.meta.json. Optimised for hot-path consumers (MCP tools).
  *
- * - `reconcileRules`: full scan + rewrites agents.meta.json (via rule-meta-builder)
+ * - `reconcileKnowledge`: full scan + rewrites agents.meta.json (via knowledge-meta-builder)
  *   + emits ledger events. Used by startup (TASK-022) and doctor repair (TASK-023).
  */
-interface RuleSyncOptions {
+interface KnowledgeSyncOptions {
     mode?: "incremental" | "full";
     /** When true, invalid frontmatter throws RuleValidationError (default: false — collect as warning). */
     throwOnInvalidFrontmatter?: boolean;
@@ -140,23 +281,23 @@ interface StructuredWarning {
     action_hint: string;
 }
 /**
- * Granular ledger event shape for rule-sync operations.
- * These are returned in RuleSyncReport and also appended to the event ledger
- * using the nearest available ledger event type (rule_drift_detected /
- * baseline_synced). The shape below is what callers receive in `.events`.
+ * Granular ledger event shape for knowledge-sync operations.
+ * These are returned in KnowledgeSyncReport and also appended to the event ledger
+ * using the nearest available ledger event type (knowledge_drift_detected).
+ * The shape below is what callers receive in `.events`.
  */
-interface RuleSyncLedgerEvent {
+interface KnowledgeSyncLedgerEvent {
     type: "rule_content_changed" | "rule_added" | "rule_removed";
     stable_id: string;
     path: string;
     prev_hash: string | null;
     new_hash: string | null;
     changed_fields: string[];
-    source: "ensureRulesFresh" | "reconcileRules";
+    source: "ensureKnowledgeFresh" | "reconcileKnowledge";
 }
 /** Alias so the public API says LedgerEvent (as documented). */
-type LedgerEvent = RuleSyncLedgerEvent;
-interface RuleSyncReport {
+type LedgerEvent = KnowledgeSyncLedgerEvent;
+interface KnowledgeSyncReport {
     status: "fresh" | "reconciled" | "errors";
     events: LedgerEvent[];
     warnings: StructuredWarning[];
@@ -167,8 +308,8 @@ interface RuleSyncReport {
  * invalidates the cache. Does NOT rewrite agents.meta.json. Optimised for
  * hot-path consumers (MCP tools).
  */
-declare function ensureRulesFresh(projectRoot: string, opts?: RuleSyncOptions): Promise<RuleSyncReport>;
-interface ReconcileRulesOptions {
+declare function ensureKnowledgeFresh(projectRoot: string, opts?: KnowledgeSyncOptions): Promise<KnowledgeSyncReport>;
+interface ReconcileKnowledgeOptions {
     /** Identifies who triggered the reconcile; controls which summary ledger event is written. */
     trigger?: "startup" | "doctor" | "manual";
 }
@@ -181,7 +322,7 @@ interface ReconcileRulesOptions {
  * ledger event is appended after per-file drift events. Other trigger values
  * append a `meta_reconciled` event. Omitting the trigger skips the summary.
  */
-declare function reconcileRules(projectRoot: string, opts?: ReconcileRulesOptions): Promise<RuleSyncReport>;
+declare function reconcileKnowledge(projectRoot: string, opts?: ReconcileKnowledgeOptions): Promise<KnowledgeSyncReport>;
 
 declare class ServeLockHeldError extends IOFabricError {
     readonly code = "SERVE_LOCK_HELD";
@@ -239,8 +380,6 @@ declare function startHttpServer(options: {
     projectRoot: string;
     host?: string;
     authToken?: string;
-    dashboardDistPath?: string;
-    dev?: boolean;
 }): Promise<Server>;
 
-export { AGENTS_MD_RESOURCE_URI, type AcquireOptions, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type InFlightTracker, LEDGER_PATH, LEGACY_LEDGER_PATH, type LedgerEvent, type LockState, type ReconcileRulesOptions, type RuleMetaBuildResult, type RuleMetaBuildSource, type RuleSyncLedgerEvent, type RuleSyncOptions, type RuleSyncReport, ServeLockHeldError, type ShutdownHandlerDeps, type StructuredWarning, type WriteRuleMetaOptions, acquireLock, buildRuleMeta, checkLockOrThrow, computeRuleTestIndex, computeRulesBasedAgentsMeta, createFabricServer, createInFlightTracker, createShutdownHandler, deriveRuleMetaLayer, deriveRuleMetaTopologyType, ensureRulesFresh, flushAndSyncEventLedger, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, isSameRuleTestIndex, readLockState, reconcileRules, releaseLock, runDoctorFix, runDoctorReport, stableStringify, startHttpServer, startStdioServer, writeRuleMeta };
+export { AGENTS_MD_RESOURCE_URI, type AcquireOptions, type DoctorApplyLintMutation, type DoctorApplyLintMutationKind, type DoctorApplyLintReport, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type InFlightTracker, KnowledgeIdAllocator, type KnowledgeMetaBuildResult, type KnowledgeMetaBuildSource, type KnowledgeSyncLedgerEvent, type KnowledgeSyncOptions, type KnowledgeSyncReport, LEDGER_PATH, LEGACY_LEDGER_PATH, type LedgerEvent, type LockState, type PlanContextInput, type PlanContextResult, type ReconcileKnowledgeOptions, type RequirementProfile, type SelectionTokenState, ServeLockHeldError, type ShutdownHandlerDeps, type StructuredWarning, type WriteKnowledgeMetaOptions, acquireLock, appendEventLedgerEvent, buildKnowledgeMeta, checkLockOrThrow, computeKnowledgeBasedAgentsMeta, computeKnowledgeTestIndex, createFabricServer, createInFlightTracker, createShutdownHandler, deriveKnowledgeMetaLayer, deriveKnowledgeMetaTopologyType, ensureKnowledgeFresh, extractKnowledge, flushAndSyncEventLedger, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, isSameKnowledgeTestIndex, planContext, readLockState, readSelectionToken, reconcileKnowledge, releaseLock, reviewKnowledge, runDoctorApplyLint, runDoctorFix, runDoctorReport, stableStringify, startHttpServer, startStdioServer, writeKnowledgeMeta };