llm-wiki-compiler 0.2.0 → 0.3.0

package/dist/cli.js

@@ -13,6 +13,12 @@ import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
 import { writeFile, rename, readFile, mkdir } from "fs/promises";
 import path from "path";
 import yaml from "js-yaml";
+var VALID_PROVENANCE_STATES = /* @__PURE__ */ new Set([
+  "extracted",
+  "merged",
+  "inferred",
+  "ambiguous"
+]);
 function slugify(title) {
   return title.toLowerCase().replace(/['']/g, "").replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
@@ -50,6 +56,46 @@ async function safeReadFile(filePath) {
     return "";
   }
 }
+function parseConfidence(raw) {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return void 0;
+  if (raw < 0) return 0;
+  if (raw > 1) return 1;
+  return raw;
+}
+function parseProvenanceState(raw) {
+  if (typeof raw !== "string") return void 0;
+  return VALID_PROVENANCE_STATES.has(raw) ? raw : void 0;
+}
+function coerceContradictionEntry(entry) {
+  if (typeof entry === "string" && entry.trim().length > 0) {
+    return { slug: entry.trim() };
+  }
+  if (entry && typeof entry === "object" && "slug" in entry) {
+    const obj = entry;
+    if (typeof obj.slug !== "string" || obj.slug.trim().length === 0) return null;
+    const ref = { slug: obj.slug.trim() };
+    if (typeof obj.reason === "string") ref.reason = obj.reason;
+    return ref;
+  }
+  return null;
+}
+function parseContradictedBy(raw) {
+  if (!Array.isArray(raw)) return void 0;
+  const refs = raw.map(coerceContradictionEntry).filter((ref) => ref !== null);
+  return refs.length > 0 ? refs : void 0;
+}
+function parseInferredParagraphs(raw) {
+  if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) return void 0;
+  return raw;
+}
+function parseProvenanceMetadata(meta) {
+  return {
+    confidence: parseConfidence(meta.confidence),
+    provenanceState: parseProvenanceState(meta.provenanceState),
+    contradictedBy: parseContradictedBy(meta.contradictedBy),
+    inferredParagraphs: parseInferredParagraphs(meta.inferredParagraphs)
+  };
+}
 function validateWikiPage(content) {
   if (!content || content.trim().length === 0) return false;
   const { meta, body } = parseFrontmatter(content);
@@ -83,7 +129,11 @@ var LOCK_FILE = ".llmwiki/lock";
 var INDEX_FILE = "wiki/index.md";
 var MOC_FILE = "wiki/MOC.md";
 var EMBEDDINGS_FILE = ".llmwiki/embeddings.json";
+var CANDIDATES_DIR = ".llmwiki/candidates";
+var CANDIDATES_ARCHIVE_DIR = ".llmwiki/candidates/archive";
 var EMBEDDING_TOP_K = 15;
+var LOW_CONFIDENCE_THRESHOLD = 0.5;
+var MAX_INFERRED_PARAGRAPHS_WITHOUT_CITATIONS = 2;
 var EMBEDDING_MODELS = {
   anthropic: "voyage-3-lite",
   openai: "text-embedding-3-small",
@@ -274,11 +324,11 @@ async function ingest(source2) {
 }
 
 // src/commands/compile.ts
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 
 // src/compiler/index.ts
-import { readFile as readFile8, readdir as readdir6 } from "fs/promises";
-import path13 from "path";
+import { readFile as readFile8 } from "fs/promises";
+import path16 from "path";
 
 // src/utils/state.ts
 import { readFile as readFile3, writeFile as writeFile3, rename as rename2, mkdir as mkdir3, copyFile } from "fs/promises";
@@ -321,6 +371,78 @@ async function removeSourceState(root, sourceFile) {
   await writeState(root, state);
 }
 
+// src/compiler/source-state.ts
+import path6 from "path";
+
+// src/compiler/hasher.ts
+import { createHash } from "crypto";
+import { readFile as readFile4, readdir } from "fs/promises";
+import path5 from "path";
+async function hashFile(filePath) {
+  const content = await readFile4(filePath, "utf-8");
+  return createHash("sha256").update(content).digest("hex");
+}
+async function detectChanges(root, prevState) {
+  const sourcesPath = path5.join(root, SOURCES_DIR);
+  const currentFiles = await listSourceFiles(sourcesPath);
+  const changes = [];
+  for (const file of currentFiles) {
+    const status2 = await classifyFile(root, file, prevState);
+    changes.push({ file, status: status2 });
+  }
+  const deletedChanges = findDeletedFiles(currentFiles, prevState);
+  changes.push(...deletedChanges);
+  return changes;
+}
+async function listSourceFiles(sourcesPath) {
+  try {
+    const entries = await readdir(sourcesPath);
+    return entries.filter((f) => f.endsWith(".md"));
+  } catch {
+    return [];
+  }
+}
+async function classifyFile(root, file, prevState) {
+  const filePath = path5.join(root, SOURCES_DIR, file);
+  const hash = await hashFile(filePath);
+  const prev = prevState.sources[file];
+  if (!prev) return "new";
+  if (prev.hash !== hash) return "changed";
+  return "unchanged";
+}
+function findDeletedFiles(currentFiles, prevState) {
+  const currentSet = new Set(currentFiles);
+  return Object.keys(prevState.sources).filter((file) => !currentSet.has(file)).map((file) => ({ file, status: "deleted" }));
+}
+
+// src/compiler/source-state.ts
+async function buildExtractionSourceStates(root, extractions) {
+  const snapshot = {};
+  const compiledAt = (/* @__PURE__ */ new Date()).toISOString();
+  for (const result of extractions) {
+    if (result.concepts.length === 0) continue;
+    snapshot[result.sourceFile] = await buildEntry(root, result, compiledAt);
+  }
+  return snapshot;
+}
+async function buildEntry(root, result, compiledAt) {
+  const filePath = path6.join(root, SOURCES_DIR, result.sourceFile);
+  const hash = await hashFile(filePath);
+  return {
+    hash,
+    concepts: result.concepts.map((concept) => slugify(concept.concept)),
+    compiledAt
+  };
+}
+function pickStatesForSources(allStates, sourceFiles) {
+  const picked = {};
+  for (const file of sourceFiles) {
+    const entry = allStates[file];
+    if (entry) picked[file] = entry;
+  }
+  return picked;
+}
+
 // src/providers/anthropic.ts
 import Anthropic from "@anthropic-ai/sdk";
 var VOYAGE_EMBEDDINGS_URL = "https://api.voyageai.com/v1/embeddings";
@@ -446,14 +568,18 @@ function translateToolToOpenAI(tool) {
 }
 var OpenAIProvider = class {
   client;
+  embeddingsClient;
   model;
-  constructor(model, baseURL, apiKey) {
+  configuredEmbeddingModel;
+  constructor(model, options = {}) {
     this.model = model;
-    const resolvedKey = apiKey ?? process.env.OPENAI_API_KEY ?? "";
+    this.configuredEmbeddingModel = options.embeddingModel;
+    const resolvedKey = options.apiKey ?? process.env.OPENAI_API_KEY ?? "";
     this.client = new OpenAI({
       apiKey: resolvedKey,
-      ...baseURL ? { baseURL } : {}
+      baseURL: options.baseURL ?? null
     });
+    this.embeddingsClient = options.embeddingsBaseURL ? new OpenAI({ apiKey: resolvedKey, baseURL: options.embeddingsBaseURL }) : this.client;
   }
   /** Send a single non-streaming completion request. */
   async complete(system, messages, maxTokens) {
@@ -502,7 +628,7 @@ var OpenAIProvider = class {
    * Subclasses (e.g. Ollama) override embeddingModel() to pick a different model.
    */
   async embed(text) {
-    const response = await this.client.embeddings.create({
+    const response = await this.embeddingsClient.embeddings.create({
       model: this.embeddingModel(),
       input: text
     });
@@ -514,18 +640,23 @@ var OpenAIProvider = class {
   }
   /** Default embedding model for this provider. Subclasses may override. */
   embeddingModel() {
-    return EMBEDDING_MODELS.openai;
+    return this.configuredEmbeddingModel ?? EMBEDDING_MODELS.openai;
   }
 };
 
 // src/providers/ollama.ts
 var OllamaProvider = class extends OpenAIProvider {
-  constructor(model, baseURL) {
-    super(model, baseURL, "ollama");
+  constructor(model, options) {
+    super(model, {
+      baseURL: options.baseURL,
+      apiKey: "ollama",
+      embeddingsBaseURL: options.embeddingsBaseURL,
+      embeddingModel: options.embeddingModel
+    });
   }
   /** Ollama ships a dedicated embedding model (nomic-embed-text). */
   embeddingModel() {
-    return EMBEDDING_MODELS.ollama;
+    return this.configuredEmbeddingModel ?? EMBEDDING_MODELS.ollama;
   }
 };
 
@@ -533,14 +664,14 @@ var OllamaProvider = class extends OpenAIProvider {
 var MINIMAX_BASE_URL = "https://api.minimax.io/v1";
 var MiniMaxProvider = class extends OpenAIProvider {
   constructor(model, apiKey) {
-    super(model, MINIMAX_BASE_URL, apiKey);
+    super(model, { baseURL: MINIMAX_BASE_URL, apiKey });
   }
 };
 
 // src/utils/claude-settings.ts
 import { readFileSync } from "fs";
 import { homedir } from "os";
-import path5 from "path";
+import path7 from "path";
 var CLAUDE_SETTINGS_PATH_ENV = "LLMWIKI_CLAUDE_SETTINGS_PATH";
 function isRecord(value) {
   return typeof value === "object" && value !== null;
@@ -551,7 +682,7 @@ function normalize(value) {
   return trimmed.length > 0 ? trimmed : void 0;
 }
 function resolveClaudeSettingsPath(env) {
-  return env[CLAUDE_SETTINGS_PATH_ENV] ?? path5.join(homedir(), ".claude", "settings.json");
+  return env[CLAUDE_SETTINGS_PATH_ENV] ?? path7.join(homedir(), ".claude", "settings.json");
 }
 function readClaudeSettingsFile(settingsPath) {
   try {
@@ -640,18 +771,27 @@ function getProvider() {
     case "anthropic":
       return getAnthropicProvider();
     case "openai":
-      return new OpenAIProvider(getModelForProvider("openai"));
+      return new OpenAIProvider(getModelForProvider("openai"), {
+        baseURL: readOptionalEnv("OPENAI_BASE_URL"),
+        embeddingsBaseURL: readOptionalEnv("OPENAI_EMBEDDINGS_BASE_URL"),
+        embeddingModel: readOptionalEnv("LLMWIKI_EMBEDDING_MODEL")
+      });
     case "ollama":
-      return new OllamaProvider(
-        getModelForProvider("ollama"),
-        process.env.OLLAMA_HOST ?? OLLAMA_DEFAULT_HOST
-      );
+      return new OllamaProvider(getModelForProvider("ollama"), {
+        baseURL: readOptionalEnv("OLLAMA_HOST") ?? OLLAMA_DEFAULT_HOST,
+        embeddingsBaseURL: readOptionalEnv("OLLAMA_EMBEDDINGS_HOST"),
+        embeddingModel: readOptionalEnv("LLMWIKI_EMBEDDING_MODEL")
+      });
     case "minimax":
       return getMiniMaxProvider();
     default:
       throw new Error(`Unhandled provider: ${providerName}`);
   }
 }
+function readOptionalEnv(name) {
+  const value = process.env[name]?.trim();
+  return value ? value : void 0;
+}
 function getModelForProvider(providerName) {
   return process.env.LLMWIKI_MODEL ?? PROVIDER_MODELS[providerName];
 }
@@ -715,8 +855,8 @@ async function callClaude(options) {
 }
 
 // src/utils/lock.ts
-import { open, readFile as readFile4, unlink, mkdir as mkdir4 } from "fs/promises";
-import path6 from "path";
+import { open, readFile as readFile5, unlink, mkdir as mkdir4 } from "fs/promises";
+import path8 from "path";
 var RECLAIM_SUFFIX = ".reclaim";
 var MAX_ACQUIRE_ATTEMPTS = 2;
 function isProcessAlive(pid) {
@@ -728,8 +868,8 @@ function isProcessAlive(pid) {
   }
 }
 async function acquireLock(root) {
-  const lockPath = path6.join(root, LOCK_FILE);
-  await mkdir4(path6.join(root, LLMWIKI_DIR), { recursive: true });
+  const lockPath = path8.join(root, LOCK_FILE);
+  await mkdir4(path8.join(root, LLMWIKI_DIR), { recursive: true });
   for (let attempt = 0; attempt < MAX_ACQUIRE_ATTEMPTS; attempt++) {
     const created = await tryCreateLock(lockPath);
     if (created) return true;
@@ -792,7 +932,7 @@ async function tryCreateLock(lockPath) {
 }
 async function isLockStale(lockPath) {
   try {
-    const content = await readFile4(lockPath, "utf-8");
+    const content = await readFile5(lockPath, "utf-8");
     const pid = parseInt(content.trim(), 10);
     if (isNaN(pid)) return true;
     return !isProcessAlive(pid);
@@ -801,7 +941,7 @@ async function isLockStale(lockPath) {
   }
 }
 async function releaseLock(root) {
-  const lockPath = path6.join(root, LOCK_FILE);
+  const lockPath = path8.join(root, LOCK_FILE);
   try {
     await unlink(lockPath);
   } catch {
@@ -809,6 +949,12 @@ async function releaseLock(root) {
 }
 
 // src/compiler/prompts.ts
+var PROVENANCE_STATE_VALUES = [
+  "extracted",
+  "merged",
+  "inferred",
+  "ambiguous"
+];
 var CONCEPT_EXTRACTION_TOOL = {
   name: "extract_concepts",
   description: "Extract knowledge concepts from a source document",
@@ -836,6 +982,31 @@ var CONCEPT_EXTRACTION_TOOL = {
               type: "array",
               items: { type: "string" },
               description: "2-4 categorical tags for organizing this concept (e.g., 'machine-learning', 'optimization')"
+            },
+            confidence: {
+              type: "number",
+              description: "Confidence in this concept on a 0..1 scale (1 = directly stated, 0 = highly speculative)."
+            },
+            provenance_state: {
+              type: "string",
+              enum: PROVENANCE_STATE_VALUES,
+              description: "How this concept was produced: 'extracted' (direct from source), 'merged' (synthesised across sources), 'inferred' (model deduction), or 'ambiguous' (sources disagree)."
+            },
+            contradicted_by: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  slug: { type: "string", description: "Slug of the contradicting concept." },
+                  reason: { type: "string", description: "Brief reason for the contradiction." }
+                },
+                required: ["slug"]
+              },
+              description: "Slugs of other concepts whose evidence contradicts this one."
+            },
+            inferred_paragraphs: {
+              type: "integer",
+              description: "Estimated number of paragraphs in the page that will be inferred rather than directly cited."
             }
           },
           required: ["concept", "summary", "is_new"]
@@ -857,6 +1028,17 @@ ${existingIndex}` : "\n\nNo existing wiki pages yet.";
     "Each concept should be a standalone topic that someone might look up.",
     "Focus on key ideas, techniques, patterns, or entities \u2014 not trivial details.",
     "Use the extract_concepts tool to return your findings.",
+    "",
+    "For every concept, emit provenance metadata so downstream tools can reason",
+    "about reliability:",
+    "  - confidence: 0..1 \u2014 how certain you are the source supports this concept.",
+    "  - provenance_state: 'extracted' if directly stated, 'merged' if synthesised",
+    "    from multiple parts of the source, 'inferred' if reasoned from context,",
+    "    or 'ambiguous' if the source is contradictory or unclear.",
+    "  - contradicted_by: slugs of other concepts (in this batch or the index)",
+    "    whose evidence conflicts with this one.",
+    "  - inferred_paragraphs: estimated number of paragraphs in the resulting",
+    "    page that will be inferred rather than directly citable.",
     indexSection,
     "\n\n--- SOURCE DOCUMENT ---\n\n",
     sourceContent
@@ -885,69 +1067,54 @@ ${relatedPages}` : "";
     "Format: ^[filename.md] for single-source, ^[source-a.md, source-b.md] for multi-source.",
     "Place citations only at the end of prose paragraphs \u2014 not on headings, list items, or code blocks.",
     "Source filenames are visible as `--- SOURCE: filename.md ---` headers in the content below.",
+    "",
+    "If a paragraph is your inference rather than a direct extraction, leave it",
+    "uncited \u2014 downstream lint rules will count uncited paragraphs as 'inferred'",
+    "to compute the page's provenance metadata.",
     existingSection,
     relatedSection,
     "\n\n--- SOURCE MATERIAL ---\n\n",
     sourceContent
   ].join("\n");
 }
-function parseConcepts(toolOutput) {
-  try {
-    const parsed = JSON.parse(toolOutput);
-    const concepts = parsed.concepts ?? [];
-    return concepts.filter(
-      (c) => typeof c.concept === "string" && typeof c.summary === "string" && typeof c.is_new === "boolean" && (c.tags === void 0 || Array.isArray(c.tags))
-    ).map((c) => ({
-      concept: c.concept,
-      summary: c.summary,
-      is_new: c.is_new,
-      tags: Array.isArray(c.tags) ? c.tags : void 0
-    }));
-  } catch {
-    return [];
-  }
-}
-
-// src/compiler/hasher.ts
-import { createHash } from "crypto";
-import { readFile as readFile5, readdir } from "fs/promises";
-import path7 from "path";
-async function hashFile(filePath) {
-  const content = await readFile5(filePath, "utf-8");
-  return createHash("sha256").update(content).digest("hex");
+function isValidRawConcept(c) {
+  return typeof c.concept === "string" && typeof c.summary === "string" && typeof c.is_new === "boolean" && (c.tags === void 0 || Array.isArray(c.tags));
 }
-async function detectChanges(root, prevState) {
-  const sourcesPath = path7.join(root, SOURCES_DIR);
-  const currentFiles = await listSourceFiles(sourcesPath);
-  const changes = [];
-  for (const file of currentFiles) {
-    const status2 = await classifyFile(root, file, prevState);
-    changes.push({ file, status: status2 });
+function coerceContradictedBy(raw) {
+  if (!Array.isArray(raw)) return void 0;
+  const refs = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const obj = entry;
+    if (typeof obj.slug !== "string" || obj.slug.trim().length === 0) continue;
+    const ref = { slug: obj.slug.trim() };
+    if (typeof obj.reason === "string") ref.reason = obj.reason;
+    refs.push(ref);
   }
-  const deletedChanges = findDeletedFiles(currentFiles, prevState);
-  changes.push(...deletedChanges);
-  return changes;
+  return refs.length > 0 ? refs : void 0;
 }
-async function listSourceFiles(sourcesPath) {
+function mapRawConcept(c) {
+  const provenance = typeof c.provenance_state === "string" && PROVENANCE_STATE_VALUES.includes(c.provenance_state) ? c.provenance_state : void 0;
+  return {
+    concept: c.concept,
+    summary: c.summary,
+    is_new: c.is_new,
+    tags: Array.isArray(c.tags) ? c.tags : void 0,
+    confidence: typeof c.confidence === "number" ? c.confidence : void 0,
+    provenanceState: provenance,
+    contradictedBy: coerceContradictedBy(c.contradicted_by),
+    inferredParagraphs: typeof c.inferred_paragraphs === "number" && Number.isInteger(c.inferred_paragraphs) && c.inferred_paragraphs >= 0 ? c.inferred_paragraphs : void 0
+  };
+}
+function parseConcepts(toolOutput) {
   try {
-    const entries = await readdir(sourcesPath);
-    return entries.filter((f) => f.endsWith(".md"));
+    const parsed = JSON.parse(toolOutput);
+    const concepts = parsed.concepts ?? [];
+    return concepts.filter(isValidRawConcept).map(mapRawConcept);
   } catch {
     return [];
   }
 }
-async function classifyFile(root, file, prevState) {
-  const filePath = path7.join(root, SOURCES_DIR, file);
-  const hash = await hashFile(filePath);
-  const prev = prevState.sources[file];
-  if (!prev) return "new";
-  if (prev.hash !== hash) return "changed";
-  return "unchanged";
-}
-function findDeletedFiles(currentFiles, prevState) {
-  const currentSet = new Set(currentFiles);
-  return Object.keys(prevState.sources).filter((file) => !currentSet.has(file)).map((file) => ({ file, status: "deleted" }));
-}
 
 // src/compiler/deps.ts
 function buildConceptToSourcesMap(sources) {
@@ -1095,7 +1262,7 @@ async function freezeFailedExtractions(root, results, frozenSlugs) {
 }
 
 // src/compiler/orphan.ts
-import path8 from "path";
+import path9 from "path";
 async function markOrphaned(root, sourceFile, state) {
   const sourceEntry = state.sources[sourceFile];
   if (!sourceEntry) return;
@@ -1121,7 +1288,7 @@ async function orphanUnownedFrozenPages(root, frozenSlugs) {
   }
 }
 async function orphanPage(root, slug, reason) {
-  const pagePath = path8.join(root, CONCEPTS_DIR, `${slug}.md`);
+  const pagePath = path9.join(root, CONCEPTS_DIR, `${slug}.md`);
   const content = await safeReadFile(pagePath);
   if (!content) return;
   const { meta } = parseFrontmatter(content);
@@ -1133,16 +1300,16 @@ async function orphanPage(root, slug, reason) {
 
 // src/compiler/resolver.ts
 import { readdir as readdir2, readFile as readFile6 } from "fs/promises";
-import path9 from "path";
+import path10 from "path";
 import { existsSync as existsSync2 } from "fs";
 async function buildTitleIndex(root) {
-  const conceptsDir = path9.join(root, CONCEPTS_DIR);
+  const conceptsDir = path10.join(root, CONCEPTS_DIR);
   if (!existsSync2(conceptsDir)) return [];
   const files = await readdir2(conceptsDir);
   const pages = [];
   for (const file of files) {
     if (!file.endsWith(".md")) continue;
-    const filePath = path9.join(conceptsDir, file);
+    const filePath = path10.join(conceptsDir, file);
     const content = await readFile6(filePath, "utf-8");
     const { meta } = parseFrontmatter(content);
     if (meta.title && typeof meta.title === "string" && !meta.orphaned) {
@@ -1252,17 +1419,17 @@ async function linkPage(page, titleIndex) {
 
 // src/compiler/indexgen.ts
 import { readdir as readdir3 } from "fs/promises";
-import path10 from "path";
+import path11 from "path";
 async function generateIndex(root) {
   status("*", info("Generating index..."));
-  const conceptsPath = path10.join(root, CONCEPTS_DIR);
-  const queriesPath = path10.join(root, QUERIES_DIR);
+  const conceptsPath = path11.join(root, CONCEPTS_DIR);
+  const queriesPath = path11.join(root, QUERIES_DIR);
   const concepts = await collectPageSummaries(conceptsPath);
   const queries = await collectPageSummaries(queriesPath);
   concepts.sort((a, b) => a.title.localeCompare(b.title));
   queries.sort((a, b) => a.title.localeCompare(b.title));
   const indexContent = buildIndexContent(concepts, queries);
-  const indexPath = path10.join(root, INDEX_FILE);
+  const indexPath = path11.join(root, INDEX_FILE);
   await atomicWrite(indexPath, indexContent);
   const total = concepts.length + queries.length;
   status("+", success(`Index updated with ${total} pages.`));
@@ -1276,7 +1443,7 @@ async function scanWikiPages(dirPath) {
   }
   const scanned = [];
   for (const file of files.filter((f) => f.endsWith(".md"))) {
-    const content = await safeReadFile(path10.join(dirPath, file));
+    const content = await safeReadFile(path11.join(dirPath, file));
     const { meta } = parseFrontmatter(content);
     scanned.push({ slug: file.replace(/\.md$/, ""), meta });
   }
@@ -1313,7 +1480,7 @@ function buildIndexContent(concepts, queries) {
 
 // src/compiler/obsidian.ts
 import { readdir as readdir4 } from "fs/promises";
-import path11 from "path";
+import path12 from "path";
 var ABBREVIATION_MIN_WORDS = 3;
 var SWAP_CONJUNCTIONS = [" and ", " or "];
 function addObsidianMeta(frontmatter, conceptTitle, tags) {
@@ -1355,11 +1522,11 @@ function generateAbbreviation(title) {
   return abbreviation;
 }
 async function generateMOC(root) {
-  const conceptsPath = path11.join(root, CONCEPTS_DIR);
+  const conceptsPath = path12.join(root, CONCEPTS_DIR);
   const pages = await loadConceptPages(conceptsPath);
   const tagGroups = groupPagesByTag(pages);
   const content = buildMOCContent(tagGroups);
-  await atomicWrite(path11.join(root, MOC_FILE), content);
+  await atomicWrite(path12.join(root, MOC_FILE), content);
 }
 async function loadConceptPages(conceptsPath) {
   let files;
@@ -1371,7 +1538,7 @@ async function loadConceptPages(conceptsPath) {
   const pages = [];
   for (const file of files) {
     if (!file.endsWith(".md")) continue;
-    const content = await safeReadFile(path11.join(conceptsPath, file));
+    const content = await safeReadFile(path12.join(conceptsPath, file));
     if (!content) continue;
     const { meta } = parseFrontmatter(content);
     if (meta.orphaned) continue;
@@ -1423,7 +1590,7 @@ function buildMOCContent(tagGroups) {
 // src/utils/embeddings.ts
 import { readFile as readFile7, readdir as readdir5 } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
-import path12 from "path";
+import path13 from "path";
 function cosineSimilarity(a, b) {
   if (a.length !== b.length || a.length === 0) return 0;
   let dot = 0;
@@ -1446,18 +1613,23 @@ function findTopK(queryVec, store, k) {
   return scored.slice(0, k).map((item) => item.entry);
 }
 async function readEmbeddingStore(root) {
-  const filePath = path12.join(root, EMBEDDINGS_FILE);
+  const filePath = path13.join(root, EMBEDDINGS_FILE);
   if (!existsSync3(filePath)) return null;
   const raw = await readFile7(filePath, "utf-8");
   return JSON.parse(raw);
 }
 async function writeEmbeddingStore(root, store) {
-  const filePath = path12.join(root, EMBEDDINGS_FILE);
+  const filePath = path13.join(root, EMBEDDINGS_FILE);
   await atomicWrite(filePath, JSON.stringify(store, null, 2));
 }
 async function findRelevantPages(root, question) {
   const store = await readEmbeddingStore(root);
   if (!store || store.entries.length === 0) return [];
+  const activeModel = resolveEmbeddingModel();
+  if (store.model !== activeModel) {
+    warnStaleEmbeddingStore(store.model, activeModel);
+    return [];
+  }
   const queryVec = await getProvider().embed(question);
   return findTopK(queryVec, store, EMBEDDING_TOP_K).map((entry) => ({
     slug: entry.slug,
@@ -1468,7 +1640,7 @@ async function findRelevantPages(root, question) {
 async function collectPageRecords(root) {
   const records = [];
   for (const dir of [CONCEPTS_DIR, QUERIES_DIR]) {
-    const absDir = path12.join(root, dir);
+    const absDir = path13.join(root, dir);
     let files;
     try {
       files = await readdir5(absDir);
@@ -1476,7 +1648,7 @@ async function collectPageRecords(root) {
       continue;
     }
     for (const file of files.filter((f) => f.endsWith(".md"))) {
-      const content = await safeReadFile(path12.join(absDir, file));
+      const content = await safeReadFile(path13.join(absDir, file));
       const { meta } = parseFrontmatter(content);
       if (meta.orphaned || typeof meta.title !== "string") continue;
       records.push({
@@ -1510,8 +1682,25 @@ async function embedPages(records, slugsToEmbed) {
   }
   return fresh;
 }
+var warnedStaleModels = /* @__PURE__ */ new Set();
+function warnStaleEmbeddingStore(storedModel, activeModel) {
+  const key = `${storedModel}\u2192${activeModel}`;
+  if (warnedStaleModels.has(key)) return;
+  warnedStaleModels.add(key);
+  status(
+    "!",
+    warn(
+      `Embedding store was built with "${storedModel}" but active embedding model is "${activeModel}". Falling back to full-index selection. Run 'llmwiki compile' to rebuild embeddings.`
+    )
+  );
+}
 function resolveEmbeddingModel() {
-  return EMBEDDING_MODELS[getActiveProviderName()] ?? EMBEDDING_MODELS.anthropic;
+  const providerName = getActiveProviderName();
+  const configuredModel = process.env.LLMWIKI_EMBEDDING_MODEL?.trim();
+  if (configuredModel && (providerName === "openai" || providerName === "ollama")) {
+    return configuredModel;
+  }
+  return EMBEDDING_MODELS[providerName] ?? EMBEDDING_MODELS.anthropic;
 }
 function mergeEntries(existing, fresh, liveSlugs) {
   const bySlug = /* @__PURE__ */ new Map();
@@ -1526,13 +1715,15 @@ function mergeEntries(existing, fresh, liveSlugs) {
 async function updateEmbeddings(root, changedSlugs) {
   const records = await collectPageRecords(root);
   const liveSlugs = new Set(records.map((r) => r.slug));
-  const toEmbed = new Set(changedSlugs.filter((slug) => liveSlugs.has(slug)));
+  const embeddingModel = resolveEmbeddingModel();
   const existingStore = await readEmbeddingStore(root);
-  const previousEntries = existingStore?.entries ?? [];
-  if (!existingStore) {
+  const modelChanged = Boolean(existingStore && existingStore.model !== embeddingModel);
+  const toEmbed = new Set(changedSlugs.filter((slug) => liveSlugs.has(slug)));
+  const previousEntries = modelChanged ? [] : existingStore?.entries ?? [];
+  if (!existingStore || modelChanged) {
     for (const record of records) toEmbed.add(record.slug);
   }
-  if (toEmbed.size === 0 && previousEntries.every((e) => liveSlugs.has(e.slug))) {
+  if (!modelChanged && toEmbed.size === 0 && previousEntries.every((e) => liveSlugs.has(e.slug))) {
     return;
   }
   const freshEntries = await embedPages(records, toEmbed);
@@ -1540,7 +1731,7 @@ async function updateEmbeddings(root, changedSlugs) {
   const dimensions = mergedEntries[0]?.vector.length ?? 0;
   const store = {
     version: 1,
-    model: resolveEmbeddingModel(),
+    model: embeddingModel,
     dimensions,
     entries: mergedEntries
   };
@@ -1548,15 +1739,207 @@ async function updateEmbeddings(root, changedSlugs) {
   status("*", dim(`Embeddings updated (${mergedEntries.length} pages).`));
 }
 
+// src/compiler/candidates.ts
+import { readdir as readdir6, rename as rename3, unlink as unlink2, writeFile as writeFile4, mkdir as mkdir5 } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import path14 from "path";
+import { randomBytes } from "crypto";
+var ID_SUFFIX_BYTES = 4;
+var CANDIDATE_EXT = ".json";
+function buildCandidateId(slug) {
+  const suffix = randomBytes(ID_SUFFIX_BYTES).toString("hex");
+  return `${slug}-${suffix}`;
+}
+function candidatePath(root, id) {
+  return path14.join(root, CANDIDATES_DIR, `${id}${CANDIDATE_EXT}`);
+}
+function archivePath(root, id) {
+  return path14.join(root, CANDIDATES_ARCHIVE_DIR, `${id}${CANDIDATE_EXT}`);
+}
+async function writeCandidate(root, draft) {
+  const candidate = {
+    id: buildCandidateId(draft.slug),
+    title: draft.title,
+    slug: draft.slug,
+    summary: draft.summary,
+    sources: draft.sources,
+    body: draft.body,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...draft.sourceStates ? { sourceStates: draft.sourceStates } : {}
+  };
+  await atomicWrite(candidatePath(root, candidate.id), JSON.stringify(candidate, null, 2));
+  return candidate;
+}
+function failWithError(message) {
+  status("!", error(message));
+  process.exitCode = 1;
+  return null;
+}
+async function loadCandidateOrFail(root, id) {
+  const candidate = await readCandidate(root, id);
+  if (!candidate) return failWithError(`Candidate not found: ${id}`);
+  return candidate;
+}
+async function loadCandidateUnderLockOrFail(root, id) {
+  const candidate = await readCandidate(root, id);
+  if (!candidate) {
+    return failWithError(`Candidate ${id} was removed by another process during review.`);
+  }
+  return candidate;
+}
+async function readCandidate(root, id) {
+  const raw = await safeReadFile(candidatePath(root, id));
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (!isValidCandidate(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function isValidCandidate(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return typeof candidate.id === "string" && typeof candidate.title === "string" && typeof candidate.slug === "string" && typeof candidate.body === "string" && Array.isArray(candidate.sources);
+}
+async function listCandidates(root) {
+  const dir = path14.join(root, CANDIDATES_DIR);
+  if (!existsSync4(dir)) return [];
+  const entries = await readdir6(dir, { withFileTypes: true });
+  const candidates = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(CANDIDATE_EXT)) continue;
+    const id = entry.name.slice(0, -CANDIDATE_EXT.length);
+    const candidate = await readCandidate(root, id);
+    if (candidate) candidates.push(candidate);
+  }
+  candidates.sort((a, b) => a.generatedAt.localeCompare(b.generatedAt));
+  return candidates;
+}
+async function countCandidates(root) {
+  const candidates = await listCandidates(root);
+  return candidates.length;
+}
+async function deleteCandidate(root, id) {
+  const filePath = candidatePath(root, id);
+  if (!existsSync4(filePath)) return false;
+  await unlink2(filePath);
+  return true;
+}
+async function archiveCandidate(root, id) {
+  const sourcePath = candidatePath(root, id);
+  if (!existsSync4(sourcePath)) return false;
+  const target = archivePath(root, id);
+  await mkdir5(path14.dirname(target), { recursive: true });
+  try {
+    await rename3(sourcePath, target);
+  } catch {
+    const raw = await safeReadFile(sourcePath);
+    await writeFile4(target, raw, "utf-8");
+    await unlink2(sourcePath);
+  }
+  return true;
+}
+
+// src/compiler/page-renderer.ts
+import { readdir as readdir7 } from "fs/promises";
+import path15 from "path";
+
+// src/compiler/provenance.ts
+function addProvenanceMeta(fields, concept) {
+  if (typeof concept.confidence === "number") {
+    fields.confidence = concept.confidence;
+  }
+  if (concept.provenanceState) {
+    fields.provenanceState = concept.provenanceState;
+  }
+  if (concept.contradictedBy && concept.contradictedBy.length > 0) {
+    fields.contradictedBy = concept.contradictedBy;
+  }
+  if (typeof concept.inferredParagraphs === "number") {
+    fields.inferredParagraphs = concept.inferredParagraphs;
+  }
+}
+function reportContradictionWarnings(conceptTitle, concept) {
+  const refs = concept.contradictedBy;
+  if (!refs || refs.length === 0) return;
+  const slugs = refs.map((r) => r.slug).join(", ");
+  status(
+    "!",
+    warn(`Contradiction reported on "${conceptTitle}" \u2014 conflicts with: ${slugs}`)
+  );
+}
+
+// src/compiler/page-renderer.ts
+var RELATED_PAGE_CONTEXT_LIMIT = 5;
+async function renderMergedPageContent(root, entry) {
+  const pagePath = path15.join(root, CONCEPTS_DIR, `${entry.slug}.md`);
+  const existingPage = await safeReadFile(pagePath);
+  const relatedPages = await loadRelatedPages(root, entry.slug);
+  const system = buildPagePrompt(
+    entry.concept.concept,
+    entry.combinedContent,
+    existingPage,
+    relatedPages
+  );
+  const pageBody = await callClaude({
+    system,
+    messages: [
+      { role: "user", content: `Write the wiki page for "${entry.concept.concept}".` }
+    ]
+  });
+  const frontmatter = buildMergedFrontmatter(entry, existingPage);
+  reportContradictionWarnings(entry.concept.concept, entry.concept);
+  return `${frontmatter}
+
+${pageBody}
+`;
+}
+function buildMergedFrontmatter(entry, existingPage) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const existing = existingPage ? parseFrontmatter(existingPage) : null;
+  const createdAt = existing?.meta.createdAt && typeof existing.meta.createdAt === "string" ? existing.meta.createdAt : now;
+  const frontmatterFields = {
+    title: entry.concept.concept,
+    summary: entry.concept.summary,
+    sources: entry.sourceFiles,
+    createdAt,
+    updatedAt: now
+  };
+  addObsidianMeta(frontmatterFields, entry.concept.concept, entry.concept.tags ?? []);
+  addProvenanceMeta(frontmatterFields, entry.concept);
+  return buildFrontmatter(frontmatterFields);
+}
+async function loadRelatedPages(root, excludeSlug) {
+  const conceptsPath = path15.join(root, CONCEPTS_DIR);
+  let files;
+  try {
+    files = await readdir7(conceptsPath);
+  } catch {
+    return "";
+  }
+  const related = files.filter((f) => f.endsWith(".md") && f !== `${excludeSlug}.md`).slice(0, RELATED_PAGE_CONTEXT_LIMIT);
+  const contents = [];
+  for (const f of related) {
+    const content = await safeReadFile(path15.join(conceptsPath, f));
+    if (!content) continue;
+    const { meta } = parseFrontmatter(content);
+    if (meta.orphaned) continue;
+    contents.push(content);
+  }
+  return contents.join("\n\n---\n\n");
+}
+
 // src/compiler/index.ts
 import pLimit from "p-limit";
 function emptyCompileResult() {
   return { compiled: 0, skipped: 0, deleted: 0, concepts: [], pages: [], errors: [] };
 }
-async function compile(root) {
-  await compileAndReport(root);
+async function compile(root, options = {}) {
+  await compileAndReport(root, options);
 }
-async function compileAndReport(root) {
+async function compileAndReport(root, options = {}) {
   header("llmwiki compile");
   const locked = await acquireLock(root);
   if (!locked) {
@@ -1567,7 +1950,7 @@ async function compileAndReport(root) {
     };
   }
   try {
-    return await runCompilePipeline(root);
+    return await runCompilePipeline(root, options);
   } finally {
     await releaseLock(root);
   }
@@ -1579,18 +1962,21 @@ function bucketChanges(changes) {
     unchanged: changes.filter((c) => c.status === "unchanged")
   };
 }
-async function generatePagesPhase(root, extractions, frozenSlugs) {
+async function generatePagesPhase(root, extractions, frozenSlugs, options) {
   const merged = mergeExtractions(extractions, frozenSlugs);
+  const sourceStates = options.review ? await buildExtractionSourceStates(root, extractions) : {};
   const limit = pLimit(COMPILE_CONCURRENCY);
   const errors = [];
+  const candidates = [];
   const pages = await Promise.all(
     merged.map((entry) => limit(async () => {
-      const writeError = await generateMergedPage(root, entry);
-      if (writeError) errors.push(writeError);
+      const result = await generateMergedPage(root, entry, options, sourceStates);
+      if (result.error) errors.push(result.error);
+      if (result.candidateId) candidates.push(result.candidateId);
       return entry;
     }))
   );
-  return { pages, errors };
+  return { pages, errors, candidates };
 }
 async function persistExtractionStates(root, extractions) {
   for (const result of extractions) {
@@ -1598,12 +1984,16 @@ async function persistExtractionStates(root, extractions) {
     await persistSourceState(root, result.sourcePath, result.sourceFile, result.concepts);
   }
 }
-function summarizeCompile(buckets, generation, extractions) {
+function summarizeCompile(buckets, generation, extractions, options) {
   header("Compilation complete");
   status("\u2713", success(
     `${buckets.toCompile.length} compiled, ${buckets.unchanged.length} skipped, ${buckets.deleted.length} deleted`
   ));
-  if (buckets.toCompile.length > 0) {
+  if (options.review && generation.candidates.length > 0) {
+    status("?", info(
+      `${generation.candidates.length} candidate(s) awaiting review \u2014 run \`llmwiki review list\``
+    ));
+  } else if (buckets.toCompile.length > 0) {
     status("\u2192", dim('Next: llmwiki query "your question here"'));
   }
   const errors = [...generation.errors];
@@ -1612,7 +2002,7 @@ function summarizeCompile(buckets, generation, extractions) {
       errors.push(`No concepts extracted from ${result.sourceFile}`);
     }
   }
-  return {
+  const baseResult = {
     compiled: buckets.toCompile.length,
     skipped: buckets.unchanged.length,
     deleted: buckets.deleted.length,
@@ -1620,8 +2010,12 @@ function summarizeCompile(buckets, generation, extractions) {
     pages: generation.pages.map((entry) => entry.slug),
     errors
   };
+  if (options.review) {
+    baseResult.candidates = generation.candidates;
+  }
+  return baseResult;
 }
-async function runCompilePipeline(root) {
+async function runCompilePipeline(root, options) {
   const state = await readState(root);
   const changes = await detectChanges(root, state);
   augmentWithAffectedSources(changes, findAffectedSources(state, changes));
@@ -1631,19 +2025,25 @@ async function runCompilePipeline(root) {
     return { ...emptyCompileResult(), skipped: buckets.unchanged.length };
   }
   printChangesSummary(changes);
-  await markDeletedAsOrphaned(root, buckets.deleted, state);
+  if (!options.review) {
+    await markDeletedAsOrphaned(root, buckets.deleted, state);
+  }
   const frozenSlugs = findFrozenSlugs(state, changes);
   reportFrozenSlugs(frozenSlugs);
   const extractions = await runExtractionPhases(root, buckets.toCompile, state, changes);
-  await freezeFailedExtractions(root, extractions, frozenSlugs);
-  const generation = await generatePagesPhase(root, extractions, frozenSlugs);
-  await persistExtractionStates(root, extractions);
-  if (frozenSlugs.size > 0) {
-    await orphanUnownedFrozenPages(root, frozenSlugs);
+  if (!options.review) {
+    await freezeFailedExtractions(root, extractions, frozenSlugs);
+  }
+  const generation = await generatePagesPhase(root, extractions, frozenSlugs, options);
+  if (!options.review) {
+    await persistExtractionStates(root, extractions);
+    if (frozenSlugs.size > 0) {
+      await orphanUnownedFrozenPages(root, frozenSlugs);
+    }
+    await persistFrozenSlugs(root, frozenSlugs, extractions);
+    await finalizeWiki(root, generation.pages);
   }
-  await persistFrozenSlugs(root, frozenSlugs, extractions);
-  await finalizeWiki(root, generation.pages);
-  return summarizeCompile(buckets, generation, extractions);
+  return summarizeCompile(buckets, generation, extractions, options);
 }
 function augmentWithAffectedSources(changes, affected) {
   for (const file of affected) {
@@ -1705,9 +2105,9 @@ function printChangesSummary(changes) {
 }
 async function extractForSource(root, sourceFile) {
   status("*", info(`Extracting: ${sourceFile}`));
-  const sourcePath = path13.join(root, SOURCES_DIR, sourceFile);
+  const sourcePath = path16.join(root, SOURCES_DIR, sourceFile);
   const sourceContent = await readFile8(sourcePath, "utf-8");
-  const existingIndex = await safeReadFile(path13.join(root, INDEX_FILE));
+  const existingIndex = await safeReadFile(path16.join(root, INDEX_FILE));
   const concepts = await extractConcepts(sourceContent, existingIndex);
   if (concepts.length > 0) {
     const names = concepts.map((c) => c.concept).join(", ");
@@ -1715,6 +2115,26 @@ async function extractForSource(root, sourceFile) {
   }
   return { sourceFile, sourcePath, sourceContent, concepts };
 }
+function reconcileConceptMetadata(existing, incoming) {
+  const reconciled = { ...existing };
+  if (typeof incoming.confidence === "number") {
+    reconciled.confidence = typeof existing.confidence === "number" ? Math.min(existing.confidence, incoming.confidence) : incoming.confidence;
+  }
+  reconciled.provenanceState = "merged";
+  const refs = [...existing.contradictedBy ?? []];
+  const seenSlugs = new Set(refs.map((r) => r.slug));
+  for (const ref of incoming.contradictedBy ?? []) {
+    if (!seenSlugs.has(ref.slug)) {
+      refs.push(ref);
+      seenSlugs.add(ref.slug);
+    }
+  }
+  reconciled.contradictedBy = refs.length > 0 ? refs : void 0;
+  if (typeof incoming.inferredParagraphs === "number") {
+    reconciled.inferredParagraphs = typeof existing.inferredParagraphs === "number" ? Math.max(existing.inferredParagraphs, incoming.inferredParagraphs) : incoming.inferredParagraphs;
+  }
+  return reconciled;
+}
 function mergeExtractions(extractions, frozenSlugs) {
   const bySlug = /* @__PURE__ */ new Map();
   for (const result of extractions) {
@@ -1724,6 +2144,7 @@ function mergeExtractions(extractions, frozenSlugs) {
       if (frozenSlugs.has(slug)) continue;
       const existing = bySlug.get(slug);
       if (existing) {
+        existing.concept = reconcileConceptMetadata(existing.concept, concept);
         existing.sourceFiles.push(result.sourceFile);
         existing.combinedContent += `
 
@@ -1744,39 +2165,26 @@ ${result.sourceContent}`
   }
   return Array.from(bySlug.values());
 }
-async function generateMergedPage(root, entry) {
-  const pagePath = path13.join(root, CONCEPTS_DIR, `${entry.slug}.md`);
-  const existingPage = await safeReadFile(pagePath);
-  const relatedPages = await loadRelatedPages(root, entry.slug);
-  const system = buildPagePrompt(
-    entry.concept.concept,
-    entry.combinedContent,
-    existingPage,
-    relatedPages
-  );
-  const pageBody = await callClaude({
-    system,
-    messages: [
-      { role: "user", content: `Write the wiki page for "${entry.concept.concept}".` }
-    ]
-  });
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const existing = existingPage ? parseFrontmatter(existingPage) : null;
-  const createdAt = existing?.meta.createdAt && typeof existing.meta.createdAt === "string" ? existing.meta.createdAt : now;
-  const frontmatterFields = {
+async function generateMergedPage(root, entry, options, sourceStates) {
+  const fullPage = await renderMergedPageContent(root, entry);
+  if (options.review) {
+    return await persistReviewCandidate(root, entry, fullPage, sourceStates);
+  }
+  const pagePath = path16.join(root, CONCEPTS_DIR, `${entry.slug}.md`);
+  const error2 = await writePageIfValid(pagePath, fullPage, entry.concept.concept);
+  return { error: error2 ?? void 0 };
+}
+async function persistReviewCandidate(root, entry, fullPage, sourceStates) {
+  const candidate = await writeCandidate(root, {
     title: entry.concept.concept,
+    slug: entry.slug,
     summary: entry.concept.summary,
     sources: entry.sourceFiles,
-    createdAt,
-    updatedAt: now
-  };
-  addObsidianMeta(frontmatterFields, entry.concept.concept, entry.concept.tags ?? []);
-  const frontmatter = buildFrontmatter(frontmatterFields);
-  const fullPage = `${frontmatter}
-
-${pageBody}
-`;
-  return await writePageIfValid(pagePath, fullPage, entry.concept.concept);
+    body: fullPage,
+    sourceStates: pickStatesForSources(sourceStates, entry.sourceFiles)
+  });
+  status("?", info(`Candidate ready: ${candidate.id} (${entry.slug})`));
+  return { candidateId: candidate.id };
 }
 async function extractConcepts(sourceContent, existingIndex) {
   const system = buildExtractionPrompt(sourceContent, existingIndex);
@@ -1787,25 +2195,6 @@ async function extractConcepts(sourceContent, existingIndex) {
   });
   return parseConcepts(rawOutput);
 }
-async function loadRelatedPages(root, excludeSlug) {
-  const conceptsPath = path13.join(root, CONCEPTS_DIR);
-  let files;
-  try {
-    files = await readdir6(conceptsPath);
-  } catch {
-    return "";
-  }
-  const related = files.filter((f) => f.endsWith(".md") && f !== `${excludeSlug}.md`).slice(0, 5);
-  const contents = [];
-  for (const f of related) {
-    const content = await safeReadFile(path13.join(conceptsPath, f));
-    if (!content) continue;
-    const { meta } = parseFrontmatter(content);
-    if (meta.orphaned) continue;
-    contents.push(content);
-  }
-  return contents.join("\n\n---\n\n");
-}
 async function writePageIfValid(pagePath, content, conceptTitle) {
   if (!validateWikiPage(content)) {
     status("!", warn(`Invalid page for "${conceptTitle}" \u2014 skipped.`));
@@ -1833,20 +2222,20 @@ async function persistSourceState(root, sourcePath, sourceFile, concepts) {
 }
 
 // src/commands/compile.ts
-async function compileCommand() {
-  if (!existsSync4(SOURCES_DIR)) {
+async function compileCommand(options = {}) {
+  if (!existsSync5(SOURCES_DIR)) {
     status(
       "!",
       warn("No sources found. Run `llmwiki ingest <url>` first.")
     );
     return;
   }
-  await compile(process.cwd());
+  await compile(process.cwd(), options);
 }
 
 // src/commands/query.ts
-import { existsSync as existsSync5 } from "fs";
-import path14 from "path";
+import { existsSync as existsSync6 } from "fs";
+import path17 from "path";
 var PAGE_DIRS = [CONCEPTS_DIR, QUERIES_DIR];
 var PAGE_SELECTION_TOOL = {
   name: "select_pages",
@@ -1901,7 +2290,7 @@ async function selectRelevantPages(root, question) {
     const { pages: rawPages2, reasoning: reasoning2 } = await selectPages(question, filteredIndex);
     return { pages: rawPages2, rawPages: rawPages2, reasoning: reasoning2 };
   }
-  const indexContent = await safeReadFile(path14.join(root, INDEX_FILE));
+  const indexContent = await safeReadFile(path17.join(root, INDEX_FILE));
   const { pages: rawPages, reasoning } = await selectPages(question, indexContent);
   return { pages: rawPages.map((p) => slugify(p)), rawPages, reasoning };
 }
@@ -1919,7 +2308,7 @@ async function loadSelectedPages(root, slugs) {
   for (const slug of slugs) {
     let content = "";
     for (const dir of PAGE_DIRS) {
-      const candidate = await safeReadFile(path14.join(root, dir, `${slug}.md`));
+      const candidate = await safeReadFile(path17.join(root, dir, `${slug}.md`));
       if (!candidate) continue;
       const { meta } = parseFrontmatter(candidate);
       if (meta.orphaned) continue;
@@ -1955,7 +2344,7 @@ function summarizeAnswer(answer) {
 }
 async function saveQueryPage(root, question, answer) {
   const slug = slugify(question);
-  const filePath = path14.join(root, QUERIES_DIR, `${slug}.md`);
+  const filePath = path17.join(root, QUERIES_DIR, `${slug}.md`);
   const frontmatter = buildFrontmatter({
     title: question,
     summary: summarizeAnswer(answer),
@@ -1981,7 +2370,7 @@ ${answer}
   return slug;
 }
 async function generateAnswer(root, question, options = {}) {
-  if (!existsSync5(path14.join(root, INDEX_FILE))) {
+  if (!existsSync6(path17.join(root, INDEX_FILE))) {
     throw new Error("Wiki index not found. Run `llmwiki compile` first.");
   }
   const { pages, reasoning } = await selectRelevantPages(root, question);
@@ -1998,7 +2387,7 @@ async function generateAnswer(root, question, options = {}) {
   return { answer, selectedPages: pages, reasoning, saved };
 }
 async function queryCommand(root, question, options) {
-  if (!existsSync5(path14.join(root, INDEX_FILE))) {
+  if (!existsSync6(path17.join(root, INDEX_FILE))) {
     status("!", error("Wiki index not found. Run `llmwiki compile` first."));
     return;
   }
@@ -2026,12 +2415,12 @@ async function queryCommand(root, question, options) {
 
 // src/commands/watch.ts
 import { watch as chokidarWatch } from "chokidar";
-import { existsSync as existsSync6 } from "fs";
-import path15 from "path";
+import { existsSync as existsSync7 } from "fs";
+import path18 from "path";
 var DEBOUNCE_MS = 500;
 async function watchCommand() {
-  const sourcesPath = path15.resolve(SOURCES_DIR);
-  if (!existsSync6(sourcesPath)) {
+  const sourcesPath = path18.resolve(SOURCES_DIR);
+  if (!existsSync7(sourcesPath)) {
     status(
       "!",
       warn("No sources/ directory found. Run `llmwiki ingest <url>` first.")
@@ -2065,7 +2454,7 @@ async function watchCommand() {
   const scheduleCompile = (eventPath, event) => {
     status(
       "~",
-      dim(`${event}: ${path15.basename(eventPath)}`)
+      dim(`${event}: ${path18.basename(eventPath)}`)
     );
     if (debounceTimer) clearTimeout(debounceTimer);
     debounceTimer = setTimeout(triggerCompile, DEBOUNCE_MS);
@@ -2080,9 +2469,9 @@ async function watchCommand() {
 }
 
 // src/linter/rules.ts
-import { readdir as readdir7, readFile as readFile9 } from "fs/promises";
-import { existsSync as existsSync7 } from "fs";
-import path16 from "path";
+import { readdir as readdir8, readFile as readFile9 } from "fs/promises";
+import { existsSync as existsSync8 } from "fs";
+import path19 from "path";
 var MIN_BODY_LENGTH = 50;
 var WIKILINK_PATTERN = /\[\[([^\]]+)\]\]/g;
 var CITATION_PATTERN = /\^\[([^\]]+)\]/g;
@@ -2098,12 +2487,12 @@ function findMatchesInContent(content, pattern) {
   return results;
 }
 async function readMarkdownFiles(dirPath) {
-  if (!existsSync7(dirPath)) return [];
-  const entries = await readdir7(dirPath);
+  if (!existsSync8(dirPath)) return [];
+  const entries = await readdir8(dirPath);
   const mdFiles = entries.filter((f) => f.endsWith(".md"));
   const results = await Promise.all(
     mdFiles.map(async (fileName) => {
-      const filePath = path16.join(dirPath, fileName);
+      const filePath = path19.join(dirPath, fileName);
       const content = await readFile9(filePath, "utf-8");
       return { filePath, content };
     })
@@ -2111,14 +2500,14 @@ async function readMarkdownFiles(dirPath) {
   return results;
 }
 async function collectAllPages(root) {
-  const conceptPages = await readMarkdownFiles(path16.join(root, CONCEPTS_DIR));
-  const queryPages = await readMarkdownFiles(path16.join(root, QUERIES_DIR));
+  const conceptPages = await readMarkdownFiles(path19.join(root, CONCEPTS_DIR));
+  const queryPages = await readMarkdownFiles(path19.join(root, QUERIES_DIR));
   return [...conceptPages, ...queryPages];
 }
 function buildPageSlugSet(pages) {
   const slugs = /* @__PURE__ */ new Set();
   for (const page of pages) {
-    const baseName = path16.basename(page.filePath, ".md");
+    const baseName = path19.basename(page.filePath, ".md");
     slugs.add(baseName.toLowerCase());
   }
   return slugs;
@@ -2221,21 +2610,93 @@ async function checkEmptyPages(root) {
   }
   return results;
 }
+async function checkLowConfidencePages(root) {
+  const pages = await collectAllPages(root);
+  const results = [];
+  for (const page of pages) {
+    const { meta } = parseFrontmatter(page.content);
+    const { confidence } = parseProvenanceMetadata(meta);
+    if (confidence === void 0 || confidence >= LOW_CONFIDENCE_THRESHOLD) continue;
+    results.push({
+      rule: "low-confidence",
+      severity: "warning",
+      file: page.filePath,
+      message: `Page confidence ${confidence.toFixed(2)} is below ${LOW_CONFIDENCE_THRESHOLD}`
+    });
+  }
+  return results;
+}
+async function checkContradictedPages(root) {
+  const pages = await collectAllPages(root);
+  const results = [];
+  for (const page of pages) {
+    const { meta } = parseFrontmatter(page.content);
+    const { contradictedBy } = parseProvenanceMetadata(meta);
+    if (!contradictedBy || contradictedBy.length === 0) continue;
+    const slugs = contradictedBy.map((r) => r.slug).join(", ");
+    results.push({
+      rule: "contradicted-page",
+      severity: "warning",
+      file: page.filePath,
+      message: `Page contradicts: ${slugs}`
+    });
+  }
+  return results;
+}
+async function checkInferredWithoutCitations(root) {
+  const pages = await collectAllPages(root);
+  const results = [];
+  for (const page of pages) {
+    const { meta, body } = parseFrontmatter(page.content);
+    const provenance = parseProvenanceMetadata(meta);
+    const inferred = provenance.inferredParagraphs ?? countUncitedProseParagraphs(body);
+    if (inferred <= MAX_INFERRED_PARAGRAPHS_WITHOUT_CITATIONS) continue;
+    results.push({
+      rule: "excess-inferred-paragraphs",
+      severity: "warning",
+      file: page.filePath,
+      message: `Page has ${inferred} inferred paragraphs without citations (max ${MAX_INFERRED_PARAGRAPHS_WITHOUT_CITATIONS})`
+    });
+  }
+  return results;
+}
+var PROSE_PARAGRAPH_LEAD = /^[A-Za-z]/;
+function countUncitedProseParagraphs(body) {
+  const paragraphs = body.split(/\n\s*\n/);
+  let count = 0;
+  for (const block of paragraphs) {
+    const trimmed = block.trim();
+    if (trimmed.length === 0) continue;
+    if (!PROSE_PARAGRAPH_LEAD.test(trimmed)) continue;
+    if (CITATION_PATTERN.test(trimmed)) {
+      CITATION_PATTERN.lastIndex = 0;
+      continue;
+    }
+    CITATION_PATTERN.lastIndex = 0;
+    count += 1;
+  }
+  return count;
+}
+function splitCitationFilenames(captured) {
+  return captured.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
 async function checkBrokenCitations(root) {
   const pages = await collectAllPages(root);
-  const sourcesDir = path16.join(root, SOURCES_DIR);
+  const sourcesDir = path19.join(root, SOURCES_DIR);
   const results = [];
   for (const page of pages) {
     for (const { captured, line } of findMatchesInContent(page.content, CITATION_PATTERN)) {
-      const citedPath = path16.join(sourcesDir, captured);
-      if (!existsSync7(citedPath)) {
-        results.push({
-          rule: "broken-citation",
-          severity: "error",
-          file: page.filePath,
-          message: `Broken citation ^[${captured}] \u2014 source file not found`,
-          line
-        });
+      for (const filename of splitCitationFilenames(captured)) {
+        const citedPath = path19.join(sourcesDir, filename);
+        if (!existsSync8(citedPath)) {
+          results.push({
+            rule: "broken-citation",
+            severity: "error",
+            file: page.filePath,
+            message: `Broken citation ^[${filename}] \u2014 source file not found`,
+            line
+          });
+        }
       }
     }
   }
@@ -2249,7 +2710,10 @@ var ALL_RULES = [
   checkMissingSummaries,
   checkDuplicateConcepts,
   checkEmptyPages,
-  checkBrokenCitations
+  checkBrokenCitations,
+  checkLowConfidencePages,
+  checkContradictedPages,
+  checkInferredWithoutCitations
 ];
 function countBySeverity(results, severity) {
   return results.filter((r) => r.severity === severity).length;
@@ -2302,12 +2766,133 @@ async function lintCommand() {
   }
 }
 
+// src/commands/review-list.ts
+async function reviewListCommand() {
+  header("Pending review candidates");
+  const candidates = await listCandidates(process.cwd());
+  if (candidates.length === 0) {
+    status("\u2713", success("No pending candidates."));
+    return;
+  }
+  for (const candidate of candidates) {
+    const sources = candidate.sources.join(", ");
+    const meta = dim(`${candidate.generatedAt} | sources: ${sources}`);
+    status("?", `${info(candidate.id)} \u2192 ${candidate.slug} ${meta}`);
+  }
+  status(
+    "\u2192",
+    dim(`Use \`llmwiki review show <id>\` to inspect a candidate.`)
+  );
+}
+
+// src/commands/review-show.ts
+async function reviewShowCommand(id) {
+  const candidate = await loadCandidateOrFail(process.cwd(), id);
+  if (!candidate) return;
+  header(`Candidate ${candidate.id}`);
+  status("i", dim(`title:      ${candidate.title}`));
+  status("i", dim(`slug:       ${candidate.slug}`));
+  status("i", dim(`summary:    ${candidate.summary}`));
+  status("i", dim(`sources:    ${candidate.sources.join(", ")}`));
+  status("i", dim(`generated:  ${candidate.generatedAt}`));
+  console.log();
+  console.log(candidate.body);
+}
+
+// src/commands/review-approve.ts
+import path20 from "path";
+
+// src/commands/review-helpers.ts
+async function runReviewUnderLock(id, underLock) {
+  const root = process.cwd();
+  const preCheck = await loadCandidateOrFail(root, id);
+  if (!preCheck) return;
+  const locked = await acquireLock(root);
+  if (!locked) {
+    status("!", error("Could not acquire lock. Try again later."));
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    await underLock(root, id);
+  } finally {
+    await releaseLock(root);
+  }
+}
+
+// src/commands/review-approve.ts
+async function reviewApproveCommand(id) {
+  await runReviewUnderLock(id, approveUnderLock);
+}
+async function approveUnderLock(root, id) {
+  const candidate = await loadCandidateUnderLockOrFail(root, id);
+  if (!candidate) return;
+  if (!validateWikiPage(candidate.body)) {
+    status("!", error(`Candidate ${id} failed page validation; not approved.`));
+    process.exitCode = 1;
+    return;
+  }
+  const pagePath = path20.join(root, CONCEPTS_DIR, `${candidate.slug}.md`);
+  await atomicWrite(pagePath, candidate.body);
+  status("+", success(`Approved \u2192 ${source(pagePath)}`));
+  await persistCandidateSourceStates(root, candidate);
+  await refreshWikiAfterApproval(root, candidate.slug);
+  await deleteCandidate(root, id);
+  status("\u2713", dim(`Candidate ${id} cleared.`));
+}
+async function persistCandidateSourceStates(root, candidate) {
+  const states = candidate.sourceStates;
+  if (!states) return;
+  const otherSources = await collectOtherCandidateSources(root, candidate.id);
+  for (const [sourceFile, entry] of Object.entries(states)) {
+    if (otherSources.has(sourceFile)) continue;
+    await updateSourceState(root, sourceFile, entry);
+  }
+}
+async function collectOtherCandidateSources(root, approvingId) {
+  const pending = await listCandidates(root);
+  const sources = /* @__PURE__ */ new Set();
+  for (const candidate of pending) {
+    if (candidate.id === approvingId) continue;
+    for (const source2 of candidate.sources) sources.add(source2);
+  }
+  return sources;
+}
+async function refreshWikiAfterApproval(root, slug) {
+  await resolveLinks(root, [slug], [slug]);
+  await generateIndex(root);
+  await generateMOC(root);
+  await safelyUpdateEmbeddings2(root, [slug]);
+}
+async function safelyUpdateEmbeddings2(root, slugs) {
+  try {
+    await updateEmbeddings(root, slugs);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    status("!", warn(`Skipped embeddings update: ${message}`));
+  }
+}
+
+// src/commands/review-reject.ts
+async function reviewRejectCommand(id) {
+  await runReviewUnderLock(id, rejectUnderLock);
+}
+async function rejectUnderLock(root, id) {
+  const candidate = await loadCandidateUnderLockOrFail(root, id);
+  if (!candidate) return;
+  await archiveCandidate(root, id);
+  status(
+    "-",
+    warn(`Rejected candidate ${id} (${candidate.slug}) \u2014 archived, wiki unchanged.`)
+  );
+}
+
 // src/mcp/server.ts
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/mcp/tools.ts
-import path17 from "path";
+import path21 from "path";
 import { z } from "zod";
 
 // src/mcp/provider-check.ts
@@ -2437,7 +3022,7 @@ async function pickSearchSlugs(root, question) {
     if (candidates.length > 0) return candidates.map((c) => c.slug);
   } catch {
   }
-  const indexContent = await safeReadFile(path17.join(root, INDEX_FILE));
+  const indexContent = await safeReadFile(path21.join(root, INDEX_FILE));
   const { pages } = await selectPages(question, indexContent);
   return pages;
 }
@@ -2486,11 +3071,12 @@ function registerStatusTool(server, root) {
   );
 }
 async function collectStatus(root) {
-  const concepts = await collectPageSummaries(path17.join(root, CONCEPTS_DIR));
-  const queries = await collectPageSummaries(path17.join(root, QUERIES_DIR));
+  const concepts = await collectPageSummaries(path21.join(root, CONCEPTS_DIR));
+  const queries = await collectPageSummaries(path21.join(root, QUERIES_DIR));
   const state = await readState(root);
   const changes = await detectChanges(root, state);
   const orphans = await findOrphanedSlugs(root);
+  const pendingCandidates = await countCandidates(root);
   const compileTimes = Object.values(state.sources).map((s) => s.compiledAt);
   const lastCompile = compileTimes.length > 0 ? compileTimes.sort().slice(-1)[0] : null;
   return {
@@ -2498,11 +3084,12 @@ async function collectStatus(root) {
     sources: Object.keys(state.sources).length,
     lastCompiledAt: lastCompile,
     orphanedPages: orphans,
+    pendingCandidates,
     pendingChanges: changes.filter((c) => c.status !== "unchanged").map((c) => ({ file: c.file, status: c.status }))
   };
 }
 async function findOrphanedSlugs(root) {
-  const scanned = await scanWikiPages(path17.join(root, CONCEPTS_DIR));
+  const scanned = await scanWikiPages(path21.join(root, CONCEPTS_DIR));
   return scanned.filter(({ meta }) => meta.orphaned).map(({ slug }) => slug);
 }
 async function loadPageRecords(root, slugs) {
@@ -2515,7 +3102,7 @@ async function loadPageRecords(root, slugs) {
 }
 async function readPage(root, slug) {
   for (const dir of PAGE_DIRS2) {
-    const content = await safeReadFile(path17.join(root, dir, `${slug}.md`));
+    const content = await safeReadFile(path21.join(root, dir, `${slug}.md`));
     if (!content) continue;
     const { meta, body } = parseFrontmatter(content);
     if (meta.orphaned) continue;
@@ -2530,8 +3117,8 @@ async function readPage(root, slug) {
 }
 
 // src/mcp/resources.ts
-import path18 from "path";
-import { readdir as readdir8 } from "fs/promises";
+import path22 from "path";
+import { readdir as readdir9 } from "fs/promises";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 function jsonContent(uri, payload) {
   return {
@@ -2564,7 +3151,7 @@ function registerIndexResource(server, root) {
       mimeType: "text/markdown"
     },
     async (uri) => {
-      const content = await safeReadFile(path18.join(root, INDEX_FILE));
+      const content = await safeReadFile(path22.join(root, INDEX_FILE));
       return { contents: [markdownContent(uri, content)] };
     }
   );
@@ -2631,23 +3218,23 @@ function registerQueryResource(server, root) {
   );
 }
 async function listSources(root) {
-  const sourcesPath = path18.join(root, SOURCES_DIR);
+  const sourcesPath = path22.join(root, SOURCES_DIR);
   let files;
   try {
-    files = await readdir8(sourcesPath);
+    files = await readdir9(sourcesPath);
   } catch {
     return [];
   }
   const records = [];
   for (const file of files.filter((f) => f.endsWith(".md"))) {
-    const content = await safeReadFile(path18.join(sourcesPath, file));
+    const content = await safeReadFile(path22.join(sourcesPath, file));
     const { meta } = parseFrontmatter(content);
     records.push({ filename: file, ...meta });
   }
   return records;
 }
 async function loadPageWithMeta(root, dir, slug) {
-  const filePath = path18.join(root, dir, `${slug}.md`);
+  const filePath = path22.join(root, dir, `${slug}.md`);
   const content = await safeReadFile(filePath);
   if (!content) {
     throw new Error(`Page not found: ${dir}/${slug}.md`);
@@ -2656,10 +3243,10 @@ async function loadPageWithMeta(root, dir, slug) {
   return { slug, meta, body: body.trim() };
 }
 async function listPagesUnder(root, dir, scheme) {
-  const pagesPath = path18.join(root, dir);
+  const pagesPath = path22.join(root, dir);
   let files;
   try {
-    files = await readdir8(pagesPath);
+    files = await readdir9(pagesPath);
   } catch {
     return { resources: [] };
   }
@@ -2695,10 +3282,46 @@ program.command("ingest <source>").description("Ingest a URL or local file into
     process.exit(1);
   }
 });
-program.command("compile").description("Compile sources/ into an interlinked wiki").action(async () => {
+program.command("compile").description("Compile sources/ into an interlinked wiki").option(
+  "--review",
+  "Write generated pages as review candidates under .llmwiki/candidates/ instead of mutating wiki/. Orphan-marking for deleted sources is deferred until the next non-review compile."
+).action(async (options) => {
   try {
     requireProvider();
-    await compileCommand();
+    await compileCommand({ review: options.review });
+  } catch (err) {
+    console.error(`\x1B[31mError:\x1B[0m ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+});
+var reviewCommand = program.command("review").description("Inspect and act on pending compile review candidates");
+reviewCommand.command("list").description("List pending review candidates").action(async () => {
+  try {
+    await reviewListCommand();
+  } catch (err) {
+    console.error(`\x1B[31mError:\x1B[0m ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+});
+reviewCommand.command("show <id>").description("Print a single candidate's metadata and body").action(async (id) => {
+  try {
+    await reviewShowCommand(id);
+  } catch (err) {
+    console.error(`\x1B[31mError:\x1B[0m ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+});
+reviewCommand.command("approve <id>").description("Approve a candidate and promote it into wiki/concepts/").action(async (id) => {
+  try {
+    await reviewApproveCommand(id);
+  } catch (err) {
+    console.error(`\x1B[31mError:\x1B[0m ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+});
+reviewCommand.command("reject <id>").description("Reject a candidate and archive it without touching wiki/").action(async (id) => {
+  try {
+    await reviewRejectCommand(id);
   } catch (err) {
     console.error(`\x1B[31mError:\x1B[0m ${err instanceof Error ? err.message : err}`);
     process.exit(1);