llm-wiki-compiler 0.9.0 → 0.11.0

package/dist/cli.js

@@ -22,7 +22,8 @@ var VALID_PROVENANCE_STATES = /* @__PURE__ */ new Set([
   "extracted",
   "merged",
   "inferred",
-  "ambiguous"
+  "ambiguous",
+  "imported"
 ]);
 function slugify(title) {
   return title.toLowerCase().replace(/['']/g, "").replace(/[^\p{L}\p{N}\s-]/gu, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
@@ -218,6 +219,7 @@ var OLLAMA_DEFAULT_HOST = "http://localhost:11434/v1";
 var COPILOT_BASE_URL = "https://api.githubcopilot.com";
 var OPENAI_DEFAULT_TIMEOUT_MS = 10 * 60 * 1e3;
 var OLLAMA_DEFAULT_TIMEOUT_MS = 30 * 60 * 1e3;
+var EXPORT_DIR = "dist/exports";
 var SOURCES_DIR = "sources";
 var CONCEPTS_DIR = "wiki/concepts";
 var QUERIES_DIR = "wiki/queries";
@@ -280,6 +282,25 @@ async function confinedRegularFile(dir, name) {
   if (real === null || !isInsideDir(real, dir)) return null;
   return real;
 }
+async function confineUnderRoot(target, root, opts) {
+  const realRoot = await safeRealpath(root) ?? path2.resolve(root);
+  const abs = path2.normalize(path2.resolve(realRoot, target));
+  if (!isInsideDir(abs, realRoot)) throw new Error(`path escapes project root: ${target}`);
+  if (opts.mustExist) {
+    const real = await safeRealpath(abs);
+    if (real === null || !isInsideDir(real, realRoot)) throw new Error(`path escapes project root: ${target}`);
+    return real;
+  }
+  for (let cur = abs; ; cur = path2.dirname(cur)) {
+    const real = await safeRealpath(cur);
+    if (real !== null) {
+      if (!isInsideDir(real, realRoot)) throw new Error(`path escapes project root: ${target}`);
+      break;
+    }
+    if (path2.dirname(cur) === cur) break;
+  }
+  return abs;
+}
 
 // src/viewer/path-safety.ts
 import path3 from "path";
@@ -428,6 +449,9 @@ function source(text) {
 }
 var quietMode = false;
 var quietScope = new AsyncLocalStorage();
+function withQuiet(fn) {
+  return quietScope.run(true, fn);
+}
 function isQuiet() {
   return quietScope.getStore() ?? quietMode;
 }
@@ -2642,6 +2666,17 @@ async function moveCandidateToArchive(sourcePath, targetPath) {
 // src/compiler/candidates.ts
 var ID_SUFFIX_BYTES = 4;
 var CANDIDATE_EXT = ".json";
+var DEFAULT_HELD_REASONS = [{ code: "manual-review-requested" }];
+var VALID_REVIEW_MODES = ["policy", "forced", "imported"];
+var VALID_HELD_REASON_CODES = [
+  "low-confidence",
+  "contradicted",
+  "schema-violating",
+  "provenance-violating",
+  "all",
+  "manual-review-requested",
+  "imported-okf"
+];
 function buildCandidateId(slug) {
   const suffix = randomBytes(ID_SUFFIX_BYTES).toString("hex");
   return `${slug}-${suffix}`;
@@ -2653,21 +2688,48 @@ function archivePath(root, id) {
   return path22.join(root, CANDIDATES_ARCHIVE_DIR, `${id}${CANDIDATE_EXT}`);
 }
 async function writeCandidate(root, draft) {
+  const { canonicalId, duplicateIds } = await findSlugDuplicates(root, draft.slug);
   const candidate = {
-    id: buildCandidateId(draft.slug),
+    id: canonicalId ?? buildCandidateId(draft.slug),
     title: draft.title,
     slug: draft.slug,
     summary: draft.summary,
     sources: draft.sources,
     body: draft.body,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    reviewMode: draft.reviewMode ?? "forced",
+    heldReasons: draft.heldReasons ?? DEFAULT_HELD_REASONS,
     ...draft.sourceStates ? { sourceStates: draft.sourceStates } : {},
     ...draft.schemaViolations ? { schemaViolations: draft.schemaViolations } : {},
-    ...draft.provenanceViolations ? { provenanceViolations: draft.provenanceViolations } : {}
+    ...draft.provenanceViolations ? { provenanceViolations: draft.provenanceViolations } : {},
+    ...draft.confidence !== void 0 ? { confidence: draft.confidence } : {},
+    ...draft.contradicted !== void 0 ? { contradicted: draft.contradicted } : {},
+    ...draft.targetDirectory ? { targetDirectory: draft.targetDirectory } : {},
+    ...draft.okfPath ? { okfPath: draft.okfPath } : {}
   };
   await atomicWrite(candidatePath(root, candidate.id), JSON.stringify(candidate, null, 2));
+  await deleteDuplicates(root, duplicateIds);
   return candidate;
 }
+async function findSlugDuplicates(root, slug) {
+  const all = await listCandidates(root);
+  const matching = all.filter((c) => c.slug === slug);
+  if (matching.length === 0) return { canonicalId: null, duplicateIds: [] };
+  const [canonical, ...extras] = matching;
+  return {
+    canonicalId: canonical.id,
+    duplicateIds: extras.map((c) => c.id)
+  };
+}
+async function deleteDuplicates(root, ids) {
+  for (const id of ids) {
+    await deleteCandidate(root, id);
+  }
+}
+async function listPendingCandidateSlugs(root) {
+  const candidates = await listCandidates(root);
+  return new Set(candidates.map((candidate) => candidate.slug));
+}
 function failWithError(message) {
   status("!", error(message));
   process.exitCode = 1;
@@ -2690,12 +2752,51 @@ async function readCandidate(root, id) {
   if (!raw) return null;
   try {
     const parsed = JSON.parse(raw);
-    if (!isValidCandidate(parsed)) return null;
-    return parsed;
+    if (!isValidCandidate(parsed)) {
+      note(`[llmwiki] Skipping malformed candidate file: ${id}.json (missing required fields)`);
+      return null;
+    }
+    return sanitizeCandidate(parsed);
   } catch {
+    note(`[llmwiki] Skipping unparseable candidate file: ${id}.json`);
     return null;
   }
 }
+function sanitizeCandidate(candidate) {
+  const generatedAt = typeof candidate.generatedAt === "string" ? candidate.generatedAt : (/* @__PURE__ */ new Date(0)).toISOString();
+  const reviewMode = VALID_REVIEW_MODES.includes(candidate.reviewMode) ? candidate.reviewMode : "forced";
+  const heldReasons = sanitizeHeldReasons(candidate.heldReasons);
+  const sourceStates = sanitizeSourceStates(candidate.sourceStates);
+  const result = { ...candidate, generatedAt, reviewMode, heldReasons };
+  if (sourceStates !== void 0) result.sourceStates = sourceStates;
+  else delete result.sourceStates;
+  return result;
+}
+function sanitizeHeldReasons(raw) {
+  if (!Array.isArray(raw)) return DEFAULT_HELD_REASONS;
+  const valid = raw.filter(
+    (r) => r !== null && typeof r === "object" && typeof r.code === "string" && VALID_HELD_REASON_CODES.includes(r.code)
+  );
+  return valid.length > 0 ? valid : DEFAULT_HELD_REASONS;
+}
+function isSourceKeysafe(key) {
+  return !key.includes("/") && !key.includes("\\") && !key.includes("..");
+}
+function sanitizeSourceStates(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const result = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (!isSourceKeyValid(key, value)) continue;
+    result[key] = value;
+  }
+  return result;
+}
+function isSourceKeyValid(key, value) {
+  if (!isSourceKeysafe(key)) return false;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const entry = value;
+  return typeof entry.hash === "string" && entry.hash.length > 0 && Array.isArray(entry.concepts) && entry.concepts.every((c) => typeof c === "string") && typeof entry.compiledAt === "string";
+}
 function isValidCandidate(value) {
   if (!value || typeof value !== "object") return false;
   const candidate = value;
@@ -2722,6 +2823,15 @@ async function deleteCandidate(root, id) {
   await unlink2(filePath);
   return true;
 }
+async function deleteCandidateBySlug(root, slug) {
+  const all = await listCandidates(root);
+  const matching = all.filter((c) => c.slug === slug);
+  if (matching.length === 0) return false;
+  for (const candidate of matching) {
+    await deleteCandidate(root, candidate.id);
+  }
+  return true;
+}
 async function archiveCandidate(root, id) {
   return moveCandidateToArchive(candidatePath(root, id), archivePath(root, id));
 }
@@ -3110,11 +3220,11 @@ function registerShutdown(close) {
 }
 
 // src/commands/compile.ts
-import { existsSync as existsSync9 } from "fs";
+import { existsSync as existsSync10 } from "fs";
 
 // src/compiler/index.ts
-import { readFile as readFile23, readdir as readdir13 } from "fs/promises";
-import path37 from "path";
+import { readFile as readFile24, readdir as readdir13 } from "fs/promises";
+import path38 from "path";
 
 // src/compiler/source-state.ts
 import path27 from "path";
@@ -5027,12 +5137,21 @@ function buildPageSlugSet(pages) {
 async function checkBrokenWikilinks(root) {
   const pages = await collectAllPages(root);
   const existingSlugs = buildPageSlugSet(pages);
+  const pendingSlugs = await listPendingCandidateSlugs(root);
   const results = [];
   for (const page of pages) {
     for (const { captured, line: line2 } of findMatchesInContent(page.content, WIKILINK_PATTERN2)) {
       const linkTarget = captured.split("|")[0].trim();
       const linkSlug = slugify(linkTarget);
-      if (!existingSlugs.has(linkSlug)) {
+      if (!existingSlugs.has(linkSlug) && pendingSlugs.has(linkSlug)) {
+        results.push({
+          rule: "pending-target",
+          severity: "info",
+          file: page.filePath,
+          message: `Wikilink [[${captured}]] points to a page awaiting review`,
+          line: line2
+        });
+      } else if (!existingSlugs.has(linkSlug)) {
         results.push({
           rule: "broken-wikilink",
           severity: "error",
@@ -5274,6 +5393,8 @@ async function checkBrokenCitations(root) {
   const results = [];
   const lineCountCache = /* @__PURE__ */ new Map();
   for (const page of pages) {
+    const { meta } = parseFrontmatter(page.content);
+    if (meta.provenanceState === "imported") continue;
     const pageFindings = await checkPageBrokenCitations(
       page.content,
       page.filePath,
@@ -5417,6 +5538,154 @@ async function loadRelatedPages(root, excludeSlug) {
   return contents.join("\n\n---\n\n");
 }
 
+// src/review/config.ts
+import { readFile as readFile23 } from "fs/promises";
+import { existsSync as existsSync9 } from "fs";
+import path37 from "path";
+var PROJECT_CONFIG_FILE = path37.join(LLMWIKI_DIR, "config.json");
+var REVIEW_POLICY_OFF = {
+  hold: [],
+  lowConfidenceThreshold: LOW_CONFIDENCE_THRESHOLD,
+  treatMissingConfidenceAs: "low"
+};
+var ReviewConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ReviewConfigError";
+  }
+};
+var SIGNAL_MODES = [
+  "low-confidence",
+  "contradicted",
+  "schema-violating",
+  "provenance-violating"
+];
+var MODE_VALUES = /* @__PURE__ */ new Set([
+  ...SIGNAL_MODES,
+  "all",
+  "off"
+]);
+async function loadReviewPolicy(root) {
+  const filePath = path37.join(root, PROJECT_CONFIG_FILE);
+  if (!existsSync9(filePath)) return { ...REVIEW_POLICY_OFF };
+  const raw = await readConfigJson(filePath);
+  return normalizeReviewPolicy(raw);
+}
+async function readConfigJson(filePath) {
+  try {
+    return JSON.parse(await readFile23(filePath, "utf-8"));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ReviewConfigError(`Invalid .llmwiki/config.json: ${message}`);
+  }
+}
+function normalizeReviewPolicy(raw) {
+  const config = requireRecord(raw, "config");
+  validateVersion(config.version);
+  const review = config.review;
+  if (review === void 0) return { ...REVIEW_POLICY_OFF };
+  const reviewConfig = requireRecord(review, "review");
+  const hold = normalizeHoldModes(reviewConfig.hold);
+  if (hold.length === 0 || hold.includes("off")) {
+    return { ...REVIEW_POLICY_OFF };
+  }
+  return {
+    hold,
+    lowConfidenceThreshold: normalizeThreshold(reviewConfig.lowConfidenceThreshold),
+    treatMissingConfidenceAs: normalizeMissingConfidence(reviewConfig.treatMissingConfidenceAs)
+  };
+}
+function requireRecord(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ReviewConfigError(`${label} must be a JSON object`);
+  }
+  return value;
+}
+function validateVersion(version2) {
+  if (version2 === 1) return;
+  throw new ReviewConfigError('.llmwiki/config.json requires "version": 1');
+}
+function normalizeHoldModes(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) throw new ReviewConfigError("review.hold must be an array");
+  const modes = value.map(readMode);
+  validateModeCombination(modes);
+  return [...new Set(modes)];
+}
+function readMode(value) {
+  if (typeof value !== "string" || !MODE_VALUES.has(value)) {
+    throw new ReviewConfigError(`Unknown review.hold mode: ${String(value)}`);
+  }
+  return value;
+}
+function validateModeCombination(modes) {
+  if (modes.length <= 1) return;
+  if (modes.includes("off")) {
+    throw new ReviewConfigError('review.hold mode "off" cannot be combined with other modes');
+  }
+  if (modes.includes("all")) {
+    throw new ReviewConfigError('review.hold mode "all" cannot be combined with other modes');
+  }
+}
+function normalizeThreshold(value) {
+  if (value === void 0) return LOW_CONFIDENCE_THRESHOLD;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new ReviewConfigError("review.lowConfidenceThreshold must be a finite number in [0,1]");
+  }
+  return value;
+}
+function normalizeMissingConfidence(value) {
+  if (value === void 0) return "low";
+  if (value === "low" || value === "ok") return value;
+  throw new ReviewConfigError('review.treatMissingConfidenceAs must be "low" or "ok"');
+}
+
+// src/review/policy.ts
+function isPolicyOff(policy) {
+  return policy.hold.length === 0 || policy.hold.includes("off");
+}
+function evaluatePolicy(signals, policy) {
+  if (isPolicyOff(policy)) return [];
+  const reasons = [];
+  for (const mode of policy.hold) {
+    const reason = reasonForMode(mode, signals, policy);
+    if (reason) reasons.push(reason);
+  }
+  return reasons;
+}
+function reasonForMode(mode, signals, policy) {
+  if (mode === "all") return { code: "all" };
+  if (mode === "low-confidence") return lowConfidenceReason(signals, policy);
+  if (mode === "contradicted" && signals.contradicted) return { code: "contradicted" };
+  if (mode === "schema-violating" && signals.schemaViolations.length > 0) {
+    return { code: "schema-violating", detail: summarizeViolations(signals.schemaViolations) };
+  }
+  if (mode === "provenance-violating" && signals.provenanceViolations.length > 0) {
+    return { code: "provenance-violating", detail: summarizeViolations(signals.provenanceViolations) };
+  }
+  return null;
+}
+function lowConfidenceReason(signals, policy) {
+  if (signals.confidence === void 0) {
+    if (policy.treatMissingConfidenceAs === "low") {
+      return { code: "low-confidence", detail: "confidence missing" };
+    }
+    return null;
+  }
+  if (signals.confidence < policy.lowConfidenceThreshold) {
+    return {
+      code: "low-confidence",
+      detail: `confidence ${signals.confidence} < ${policy.lowConfidenceThreshold}`
+    };
+  }
+  return null;
+}
+function summarizeViolations(violations) {
+  const first = violations[0];
+  const suffix = violations.length === 1 ? "" : ` (+${violations.length - 1} more)`;
+  return `${first.rule}${suffix}`;
+}
+
 // src/compiler/index.ts
 import pLimit from "p-limit";
 function emptyCompileResult() {
@@ -5448,33 +5717,70 @@ function bucketChanges(changes) {
     unchanged: changes.filter((c) => c.status === "unchanged")
   };
 }
-async function generatePagesPhase(root, extractions, frozenSlugs, schema, options) {
+async function generatePagesPhase(root, extractions, frozenSlugs, schema, options, policy) {
   const merged = mergeExtractions(extractions, frozenSlugs);
-  const sourceStates = options.review ? await buildExtractionSourceStates(root, extractions) : {};
+  const shouldBuildSourceStates = options.review || !isPolicyOff(policy);
+  const sourceStates = shouldBuildSourceStates ? await buildExtractionSourceStates(root, extractions) : {};
   const limit = pLimit(COMPILE_CONCURRENCY);
-  const errors = [];
-  const candidates = [];
-  const pages = await Promise.all(
+  const outcomes = await Promise.all(
     merged.map((entry) => limit(async () => {
-      const result = await generateMergedPage(root, entry, schema, options, sourceStates);
-      if (result.error) errors.push(result.error);
-      if (result.candidateId) candidates.push(result.candidateId);
-      return entry;
+      const result = await generateMergedPage(root, entry, schema, options, sourceStates, policy);
+      return { entry, result };
     }))
   );
-  return { pages, errors, candidates, seedSlugs: [] };
+  const errors = [];
+  const candidates = [];
+  const review = { held: [], forced: [] };
+  for (const { result } of outcomes) {
+    if (result.error) errors.push(result.error);
+    if (result.candidate) {
+      candidates.push(result.candidate.id);
+      review[result.candidate.mode].push(result.candidate.ref);
+    }
+  }
+  const pages = outcomes.map(({ entry }) => entry);
+  const writtenPages = outcomes.filter(({ result }) => result.wrotePage).map(({ entry }) => entry);
+  return { pages, writtenPages, errors, candidates, review, seedSlugs: [] };
 }
-async function persistExtractionStates(root, extractions) {
+async function persistExtractionStates(root, extractions, writtenPages) {
+  const liveSlugsForSource = buildLiveSlugsForSource(writtenPages);
   for (const result of extractions) {
     if (result.concepts.length === 0) continue;
-    await persistSourceState(root, result.sourcePath, result.sourceFile, result.concepts);
+    const liveSlugs = liveSlugsForSource.get(result.sourceFile) ?? [];
+    await persistSourceStateFiltered(
+      root,
+      result.sourcePath,
+      result.sourceFile,
+      result.concepts,
+      new Set(liveSlugs)
+    );
   }
 }
+function buildLiveSlugsForSource(writtenPages) {
+  const map = /* @__PURE__ */ new Map();
+  for (const page of writtenPages) {
+    for (const sourceFile of page.sourceFiles) {
+      const existing = map.get(sourceFile) ?? [];
+      existing.push(page.slug);
+      map.set(sourceFile, existing);
+    }
+  }
+  return map;
+}
+async function persistSourceStateFiltered(root, sourcePath, sourceFile, concepts, liveSlugs) {
+  const hash = await hashFile(sourcePath);
+  const entry = {
+    hash,
+    concepts: concepts.map((c) => slugify(c.concept)).filter((s) => liveSlugs.has(s)),
+    compiledAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await updateSourceState(root, sourceFile, entry);
+}
 async function listExistingPageIds(root) {
   const ids = /* @__PURE__ */ new Set();
   for (const dir of [CONCEPTS_DIR, QUERIES_DIR]) {
     try {
-      const files = await readdir13(path37.join(root, dir));
+      const files = await readdir13(path38.join(root, dir));
       for (const file of files) {
         if (file.endsWith(".md")) ids.add(`${dir}/${file.slice(0, -3)}`);
       }
@@ -5485,7 +5791,7 @@ async function listExistingPageIds(root) {
 }
 async function logCompile(root, buckets, generation, existingIds) {
   if (buckets.toCompile.length === 0 && buckets.deleted.length === 0) return;
-  const produced = [.../* @__PURE__ */ new Set([...generation.pages.map((entry) => entry.slug), ...generation.seedSlugs])];
+  const produced = [.../* @__PURE__ */ new Set([...generation.writtenPages.map((entry) => entry.slug), ...generation.seedSlugs])];
   const existed = (slug) => existingIds.has(`${CONCEPTS_DIR}/${slug}`);
   const created = produced.filter((slug) => !existed(slug));
   const updated = produced.filter((slug) => existed(slug));
@@ -5504,9 +5810,9 @@ function summarizeCompile(buckets, generation, extractions, options) {
   status("\u2713", success(
     `${buckets.toCompile.length} compiled, ${buckets.unchanged.length} skipped, ${buckets.deleted.length} deleted`
   ));
-  if (options.review && generation.candidates.length > 0) {
+  if (generation.candidates.length > 0) {
     status("?", info(
-      `${generation.candidates.length} candidate(s) awaiting review \u2014 run \`llmwiki review list\``
+      reviewSummaryLine(generation)
     ));
   } else if (buckets.toCompile.length > 0) {
     status("\u2192", dim('Next: llmwiki query "your question here"'));
@@ -5517,7 +5823,7 @@ function summarizeCompile(buckets, generation, extractions, options) {
       errors.push(`No concepts extracted from ${result.sourceFile}`);
     }
   }
-  const conceptSlugs = generation.pages.map((entry) => entry.slug);
+  const conceptSlugs = generation.writtenPages.map((entry) => entry.slug);
   const baseResult = {
     compiled: buckets.toCompile.length,
     skipped: buckets.unchanged.length,
@@ -5526,11 +5832,20 @@ function summarizeCompile(buckets, generation, extractions, options) {
     pages: [...conceptSlugs, ...generation.seedSlugs],
     errors
   };
-  if (options.review) {
+  if (generation.candidates.length > 0) {
     baseResult.candidates = generation.candidates;
+    baseResult.review = generation.review;
   }
   return baseResult;
 }
+function reviewSummaryLine(generation) {
+  const held = generation.review.held.length;
+  const forced = generation.review.forced.length;
+  if (held > 0 && forced === 0) {
+    return `Wrote ${generation.writtenPages.length} page(s), held ${held} for review \u2014 run \`llmwiki review list\``;
+  }
+  return `${generation.candidates.length} candidate(s) awaiting review \u2014 run \`llmwiki review list\``;
+}
 function applyChangeFilter(detected, filter) {
   return filter ? detected.filter(filter) : detected;
 }
@@ -5541,10 +5856,12 @@ async function maybeSeedPages(root, schema, generation, options) {
 }
 async function runCompilePipeline(root, options) {
   const schema = await loadSchema(root);
+  const reviewPolicy = await loadReviewPolicy(root);
   reportSchemaStatus(schema);
   const state = await readState(root);
   const detected = await detectChanges(root, state);
   const changes = applyChangeFilter(detected, options.changeFilter);
+  await markUnchangedPendingSources(root, changes);
   augmentWithAffectedSources(changes, findAffectedSources(state, changes));
   const buckets = bucketChanges(changes);
   if (buckets.toCompile.length === 0 && buckets.deleted.length === 0) {
@@ -5552,12 +5869,14 @@ async function runCompilePipeline(root, options) {
     if (!options.review) {
       const emptyGeneration = {
         pages: [],
+        writtenPages: [],
         errors: [],
         candidates: [],
+        review: { held: [], forced: [] },
         seedSlugs: []
       };
       await maybeSeedPages(root, schema, emptyGeneration, options);
-      await finalizeWiki(root, emptyGeneration.pages, emptyGeneration.seedSlugs);
+      await finalizeWiki(root, emptyGeneration.writtenPages, emptyGeneration.seedSlugs);
       return {
         ...emptyCompileResult(),
         skipped: buckets.unchanged.length,
@@ -5581,19 +5900,46 @@ async function runCompilePipeline(root, options) {
     await freezeFailedExtractions(root, extractions, frozenSlugs);
   }
   const existingIds = await listExistingPageIds(root);
-  const generation = await generatePagesPhase(root, extractions, frozenSlugs, schema, options);
+  const generation = await generatePagesPhase(
+    root,
+    extractions,
+    frozenSlugs,
+    schema,
+    options,
+    reviewPolicy
+  );
   if (!options.review) {
-    await persistExtractionStates(root, extractions);
+    await persistExtractionStates(root, extractions, generation.writtenPages);
     if (frozenSlugs.size > 0) {
       await orphanUnownedFrozenPages(root, frozenSlugs);
     }
     await persistFrozenSlugs(root, frozenSlugs, extractions);
     await maybeSeedPages(root, schema, generation, options);
-    await finalizeWiki(root, generation.pages, generation.seedSlugs);
+    await finalizeWiki(root, generation.writtenPages, generation.seedSlugs);
     await logCompile(root, buckets, generation, existingIds);
   }
   return summarizeCompile(buckets, generation, extractions, options);
 }
+async function markUnchangedPendingSources(root, changes) {
+  const pendingHashes = await collectPendingSourceHashes(root);
+  if (pendingHashes.size === 0) return;
+  for (const change of changes) {
+    if (change.status !== "new" && change.status !== "changed") continue;
+    const pendingHash = pendingHashes.get(change.file);
+    if (!pendingHash) continue;
+    const currentHash = await hashFile(path38.join(root, SOURCES_DIR, change.file));
+    if (currentHash === pendingHash) change.status = "unchanged";
+  }
+}
+async function collectPendingSourceHashes(root) {
+  const hashes = /* @__PURE__ */ new Map();
+  for (const candidate of await listCandidates(root)) {
+    for (const [source2, entry] of Object.entries(candidate.sourceStates ?? {})) {
+      hashes.set(source2, entry.hash);
+    }
+  }
+  return hashes;
+}
 function reportSchemaStatus(schema) {
   if (schema.loadedFrom) {
     status("i", dim(`Schema: ${schema.loadedFrom}`));
@@ -5661,9 +6007,9 @@ function printChangesSummary(changes) {
 }
 async function extractForSource(root, sourceFile) {
   status("*", info(`Extracting: ${sourceFile}`));
-  const sourcePath = path37.join(root, SOURCES_DIR, sourceFile);
-  const sourceContent = await readFile23(sourcePath, "utf-8");
-  const existingIndex = await safeReadFile(path37.join(root, INDEX_FILE));
+  const sourcePath = path38.join(root, SOURCES_DIR, sourceFile);
+  const sourceContent = await readFile24(sourcePath, "utf-8");
+  const existingIndex = await safeReadFile(path38.join(root, INDEX_FILE));
   const concepts = await extractConcepts(sourceContent, existingIndex);
   if (concepts.length > 0) {
     const names = concepts.map((c) => c.concept).join(", ");
@@ -5724,16 +6070,30 @@ function mergeExtractions(extractions, frozenSlugs) {
   }
   return Array.from(bySlug.values());
 }
-async function generateMergedPage(root, entry, schema, options, sourceStates) {
+async function generateMergedPage(root, entry, schema, options, sourceStates, policy) {
   const fullPage = await renderMergedPageContent(root, entry, schema);
+  const diagnostics = await collectReviewDiagnostics(root, entry, fullPage, schema);
+  const signals = buildPolicySignals(fullPage, diagnostics);
+  const reasons = evaluatePolicy(signals, policy);
   if (options.review) {
-    return await persistReviewCandidate(root, entry, fullPage, sourceStates, schema);
+    const heldReasons = [{ code: "manual-review-requested" }, ...reasons];
+    return await persistReviewCandidate(root, entry, fullPage, sourceStates, diagnostics, signals, {
+      reviewMode: "forced",
+      heldReasons
+    });
+  }
+  if (reasons.length > 0) {
+    return await persistReviewCandidate(root, entry, fullPage, sourceStates, diagnostics, signals, {
+      reviewMode: "policy",
+      heldReasons: reasons
+    });
   }
-  const pagePath = path37.join(root, CONCEPTS_DIR, `${entry.slug}.md`);
+  const pagePath = path38.join(root, CONCEPTS_DIR, `${entry.slug}.md`);
   const error2 = await writePageIfValid(pagePath, fullPage, entry.concept.concept);
-  return { error: error2 ?? void 0 };
+  if (!error2) await deleteCandidateBySlug(root, entry.slug);
+  return { error: error2 ?? void 0, wrotePage: !error2 };
 }
-async function persistReviewCandidate(root, entry, fullPage, sourceStates, schema) {
+async function collectReviewDiagnostics(root, entry, fullPage, schema) {
   const virtualPath = `wiki/concepts/${entry.slug}.md`;
   const schemaViolations = checkPageCrossLinks(fullPage, virtualPath, schema);
   const provenanceViolations = await collectCandidateProvenanceViolations(
@@ -5741,6 +6101,19 @@ async function persistReviewCandidate(root, entry, fullPage, sourceStates, schem
     fullPage,
     virtualPath
   );
+  return { schemaViolations, provenanceViolations };
+}
+function buildPolicySignals(fullPage, diagnostics) {
+  const { meta } = parseFrontmatter(fullPage);
+  const provenance = parseProvenanceMetadata(meta);
+  return {
+    confidence: provenance.confidence,
+    contradicted: (provenance.contradictedBy?.length ?? 0) > 0,
+    schemaViolations: diagnostics.schemaViolations,
+    provenanceViolations: diagnostics.provenanceViolations
+  };
+}
+async function persistReviewCandidate(root, entry, fullPage, sourceStates, diagnostics, signals, meta) {
   const candidate = await writeCandidate(root, {
     title: entry.concept.concept,
     slug: entry.slug,
@@ -5748,18 +6121,28 @@ async function persistReviewCandidate(root, entry, fullPage, sourceStates, schem
     sources: entry.sourceFiles,
     body: fullPage,
     sourceStates: pickStatesForSources(sourceStates, entry.sourceFiles),
-    schemaViolations: schemaViolations.length > 0 ? schemaViolations : void 0,
-    provenanceViolations: provenanceViolations.length > 0 ? provenanceViolations : void 0
+    schemaViolations: diagnostics.schemaViolations.length > 0 ? diagnostics.schemaViolations : void 0,
+    provenanceViolations: diagnostics.provenanceViolations.length > 0 ? diagnostics.provenanceViolations : void 0,
+    reviewMode: meta.reviewMode,
+    heldReasons: meta.heldReasons,
+    confidence: signals.confidence,
+    contradicted: signals.contradicted
   });
   status("?", info(`Candidate ready: ${candidate.id} (${entry.slug})`));
-  return { candidateId: candidate.id };
+  return {
+    candidate: {
+      id: candidate.id,
+      mode: meta.reviewMode === "policy" ? "held" : "forced",
+      ref: { id: candidate.id, slug: entry.slug, reasons: meta.heldReasons.map((r) => r.code) }
+    }
+  };
 }
 async function collectCandidateProvenanceViolations(root, fullPage, virtualPath) {
   const malformed = checkPageMalformedCitations(fullPage, virtualPath);
   const broken = await checkPageBrokenCitations(
     fullPage,
     virtualPath,
-    path37.join(root, SOURCES_DIR)
+    path38.join(root, SOURCES_DIR)
   );
   return [...malformed, ...broken];
 }
@@ -5776,7 +6159,7 @@ async function generateSeedPages(root, schema, generation) {
 }
 async function generateSingleSeedPage(root, schema, seed) {
   const slug = slugify(seed.title);
-  const pagePath = path37.join(root, CONCEPTS_DIR, `${slug}.md`);
+  const pagePath = path38.join(root, CONCEPTS_DIR, `${slug}.md`);
   const relatedContent = await loadSeedRelatedPages(root, seed.relatedSlugs ?? []);
   const rule = schema.kinds[seed.kind];
   const system = buildSeedPagePrompt(seed, rule, relatedContent);
@@ -5810,7 +6193,7 @@ async function loadSeedRelatedPages(root, slugs) {
   if (slugs.length === 0) return "";
   const contents = [];
   for (const slug of slugs) {
-    const pagePath = path37.join(root, CONCEPTS_DIR, `${slug}.md`);
+    const pagePath = path38.join(root, CONCEPTS_DIR, `${slug}.md`);
     const content = await safeReadFile(pagePath);
     if (content) contents.push(content);
   }
@@ -5841,19 +6224,10 @@ async function safelyUpdateEmbeddings(root, changedSlugs) {
     status("!", warn(`Skipped embeddings update: ${message}`));
   }
 }
-async function persistSourceState(root, sourcePath, sourceFile, concepts) {
-  const hash = await hashFile(sourcePath);
-  const entry = {
-    hash,
-    concepts: concepts.map((c) => slugify(c.concept)),
-    compiledAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  await updateSourceState(root, sourceFile, entry);
-}
 
 // src/commands/compile.ts
 async function compileCommand(options = {}) {
-  if (!existsSync9(SOURCES_DIR)) {
+  if (!existsSync10(SOURCES_DIR)) {
     status(
       "!",
       warn("No sources found. Run `llmwiki ingest <url>` first.")
@@ -5864,8 +6238,8 @@ async function compileCommand(options = {}) {
 }
 
 // src/commands/query.ts
-import { existsSync as existsSync10 } from "fs";
-import path38 from "path";
+import { existsSync as existsSync11 } from "fs";
+import path39 from "path";
 var PAGE_DIRS = [CONCEPTS_DIR, QUERIES_DIR];
 var PAGE_SELECTION_TOOL = {
   name: "select_pages",
@@ -5922,7 +6296,7 @@ async function selectRelevantPages(root, question, debug) {
     const { pages: rawPages2, reasoning: reasoning2 } = await selectPages(question, filteredIndex);
     return { pages: rawPages2, rawPages: rawPages2, reasoning: reasoning2, chunks: [] };
   }
-  const indexContent = await safeReadFile(path38.join(root, INDEX_FILE));
+  const indexContent = await safeReadFile(path39.join(root, INDEX_FILE));
   const { pages: rawPages, reasoning } = await selectPages(question, indexContent);
   return { pages: rawPages.map((p) => slugify(p)), rawPages, reasoning, chunks: [] };
 }
@@ -6014,7 +6388,7 @@ async function loadSelectedPages(root, slugs) {
   for (const slug of slugs) {
     let content = "";
     for (const dir of PAGE_DIRS) {
-      const candidate = await safeReadFile(path38.join(root, dir, `${slug}.md`));
+      const candidate = await safeReadFile(path39.join(root, dir, `${slug}.md`));
       if (!candidate) continue;
       const { meta } = parseFrontmatter(candidate);
       if (meta.orphaned) continue;
@@ -6065,7 +6439,7 @@ function summarizeAnswer(answer) {
 }
 async function saveQueryPage(root, question, answer) {
   const slug = slugify(question);
-  const filePath = path38.join(root, QUERIES_DIR, `${slug}.md`);
+  const filePath = path39.join(root, QUERIES_DIR, `${slug}.md`);
   const frontmatter = buildFrontmatter({
     title: question,
     summary: summarizeAnswer(answer),
@@ -6091,7 +6465,7 @@ ${answer}
   return slug;
 }
 async function generateAnswer(root, question, options = {}) {
-  if (!existsSync10(path38.join(root, INDEX_FILE))) {
+  if (!existsSync11(path39.join(root, INDEX_FILE))) {
     throw new Error("Wiki index not found. Run `llmwiki compile` first.");
   }
   const selection = await selectRelevantPages(root, question, Boolean(options.debug));
@@ -6122,7 +6496,7 @@ function buildEmptyResult(selection) {
   };
 }
 async function queryCommand(root, question, options) {
-  if (!existsSync10(path38.join(root, INDEX_FILE))) {
+  if (!existsSync11(path39.join(root, INDEX_FILE))) {
     status("!", error("Wiki index not found. Run `llmwiki compile` first."));
     return;
   }
@@ -6172,12 +6546,12 @@ var DEBUG_CHUNK_PREVIEW_CHARS = 120;
 
 // src/commands/watch.ts
 import { watch as chokidarWatch } from "chokidar";
-import { existsSync as existsSync11 } from "fs";
-import path39 from "path";
+import { existsSync as existsSync12 } from "fs";
+import path40 from "path";
 var DEBOUNCE_MS = 500;
 async function watchCommand() {
-  const sourcesPath = path39.resolve(SOURCES_DIR);
-  if (!existsSync11(sourcesPath)) {
+  const sourcesPath = path40.resolve(SOURCES_DIR);
+  if (!existsSync12(sourcesPath)) {
     status(
       "!",
       warn("No sources/ directory found. Run `llmwiki ingest <url>` first.")
@@ -6214,7 +6588,7 @@ async function watchCommand() {
   const scheduleCompile = (eventPath, event) => {
     status(
       "~",
-      dim(`${event}: ${path39.basename(eventPath)}`)
+      dim(`${event}: ${path40.basename(eventPath)}`)
     );
     if (debounceTimer) clearTimeout(debounceTimer);
     debounceTimer = setTimeout(triggerCompile, DEBOUNCE_MS);
@@ -6304,19 +6678,19 @@ async function lintCommand() {
 }
 
 // src/eval/stats.ts
-import { readdir as readdir14, appendFile as appendFile2, mkdir as mkdir7, readFile as readFile24 } from "fs/promises";
-import { existsSync as existsSync12 } from "fs";
-import path40 from "path";
-var HISTORY_DIR = path40.join(".llmwiki", "eval");
-var HISTORY_FILE = path40.join(HISTORY_DIR, "history.jsonl");
+import { readdir as readdir14, appendFile as appendFile2, mkdir as mkdir7, readFile as readFile25 } from "fs/promises";
+import { existsSync as existsSync13 } from "fs";
+import path41 from "path";
+var HISTORY_DIR = path41.join(".llmwiki", "eval");
+var HISTORY_FILE = path41.join(HISTORY_DIR, "history.jsonl");
 async function countFiles(dir) {
-  if (!existsSync12(dir)) return 0;
+  if (!existsSync13(dir)) return 0;
   const entries = await readdir14(dir);
   return entries.filter((e) => e.endsWith(".md")).length;
 }
 async function collectStats(root) {
   const [sourceCount, pages, embeddingStore] = await Promise.all([
-    countFiles(path40.join(root, SOURCES_DIR)),
+    countFiles(path41.join(root, SOURCES_DIR)),
     collectAllPages(root),
     readEmbeddingStore(root)
   ]);
@@ -6340,14 +6714,14 @@ async function collectStats(root) {
   };
 }
 async function appendHistory(root, report) {
-  const historyDir = path40.join(root, HISTORY_DIR);
+  const historyDir = path41.join(root, HISTORY_DIR);
   await mkdir7(historyDir, { recursive: true });
-  await appendFile2(path40.join(root, HISTORY_FILE), JSON.stringify(report) + "\n");
+  await appendFile2(path41.join(root, HISTORY_FILE), JSON.stringify(report) + "\n");
 }
 async function loadHistory(root, n = 10) {
-  const historyPath = path40.join(root, HISTORY_FILE);
-  if (!existsSync12(historyPath)) return [];
-  const content = await readFile24(historyPath, "utf-8");
+  const historyPath = path41.join(root, HISTORY_FILE);
+  if (!existsSync13(historyPath)) return [];
+  const content = await readFile25(historyPath, "utf-8");
   const lines = content.trim().split("\n").filter(Boolean);
   const reports = [];
   for (const line2 of lines.slice(-n)) {
@@ -6359,9 +6733,9 @@ async function loadHistory(root, n = 10) {
   return reports;
 }
 async function readHistoryLines(root) {
-  const historyPath = path40.join(root, HISTORY_FILE);
-  if (!existsSync12(historyPath)) return null;
-  const content = await readFile24(historyPath, "utf-8");
+  const historyPath = path41.join(root, HISTORY_FILE);
+  if (!existsSync13(historyPath)) return null;
+  const content = await readFile25(historyPath, "utf-8");
   return content.trim().split("\n").filter(Boolean);
 }
 async function loadPreviousReport(root) {
@@ -6397,6 +6771,7 @@ var ERROR_RULES = /* @__PURE__ */ new Set([
   "duplicate-concept"
 ]);
 function deductionFor(result) {
+  if (result.rule === "pending-target") return 0;
   if (ERROR_RULES.has(result.rule)) return ERROR_DEDUCTION;
   if (result.rule === "contradicted-page") return CONTRADICTED_DEDUCTION;
   return DEFAULT_DEDUCTION;
@@ -6422,44 +6797,47 @@ function aggregateRules(results) {
 }
 async function evaluateHealth(root) {
   const schema = await loadSchema(root);
-  const allResults = (await Promise.all([
-    checkBrokenWikilinks(root),
-    checkBrokenCitations(root),
-    checkMalformedClaimCitations(root),
-    checkOrphanedPages(root),
-    checkMissingSummaries(root),
-    checkDuplicateConcepts(root),
-    checkEmptyPages(root),
-    checkLowConfidencePages(root),
-    checkContradictedPages(root),
-    checkInferredWithoutCitations(root),
-    checkSchemaCrossLinks(root, schema)
-  ])).flat();
+  const [allResults, pendingReviews] = await Promise.all([
+    Promise.all([
+      checkBrokenWikilinks(root),
+      checkBrokenCitations(root),
+      checkMalformedClaimCitations(root),
+      checkOrphanedPages(root),
+      checkMissingSummaries(root),
+      checkDuplicateConcepts(root),
+      checkEmptyPages(root),
+      checkLowConfidencePages(root),
+      checkContradictedPages(root),
+      checkInferredWithoutCitations(root),
+      checkSchemaCrossLinks(root, schema)
+    ]).then((results) => results.flat()),
+    countCandidates(root).catch(() => 0)
+  ]);
   const rules = aggregateRules(allResults);
   const totalDeduction = rules.reduce((sum, r) => sum + r.deduction, 0);
   const score = Math.max(0, MAX_SCORE - totalDeduction);
-  return { score, maxScore: MAX_SCORE, rules };
+  return { score, maxScore: MAX_SCORE, rules, pendingReviews };
 }
 
 // src/eval/citation-coverage.ts
-import path42 from "path";
+import path43 from "path";
 
 // src/eval/source-path.ts
 import { realpath as realpath5 } from "fs/promises";
-import path41 from "path";
+import path42 from "path";
 function containsParentSegment(file) {
   return file.split(/[/\\]/).some((seg) => seg === "..");
 }
 function isInside(parent, candidate) {
   if (candidate === parent) return true;
-  const parentWithSep = parent.endsWith(path41.sep) ? parent : parent + path41.sep;
+  const parentWithSep = parent.endsWith(path42.sep) ? parent : parent + path42.sep;
   return candidate.startsWith(parentWithSep);
 }
 async function resolveSourceFile(sourcesDir, file) {
-  if (file.length === 0 || path41.isAbsolute(file)) return null;
+  if (file.length === 0 || path42.isAbsolute(file)) return null;
   if (containsParentSegment(file)) return null;
-  const joined = path41.join(sourcesDir, file);
-  if (!isInside(sourcesDir, path41.resolve(joined))) return null;
+  const joined = path42.join(sourcesDir, file);
+  if (!isInside(sourcesDir, path42.resolve(joined))) return null;
   try {
     const realDir = await realpath5(sourcesDir);
     const realFile = await realpath5(joined);
@@ -6497,7 +6875,7 @@ async function evaluatePage(slug, body, sourcesDir) {
 }
 async function evaluateCitationCoverage(root) {
   const pages = await collectAllPages(root);
-  const sourcesDir = path42.join(root, SOURCES_DIR);
+  const sourcesDir = path43.join(root, SOURCES_DIR);
   let totalProse = 0;
   let totalCited = 0;
   let totalCitations = 0;
@@ -6505,7 +6883,7 @@ async function evaluateCitationCoverage(root) {
   const perPage = [];
   for (const { filePath, content } of pages) {
     const { body } = parseFrontmatter(content);
-    const slug = path42.basename(filePath, ".md");
+    const slug = path43.basename(filePath, ".md");
     const stats = await evaluatePage(slug, body, sourcesDir);
     totalProse += stats.proseParagraphs;
     totalCited += stats.citedParagraphs;
@@ -6528,8 +6906,8 @@ async function evaluateCitationCoverage(root) {
 
 // src/eval/source-utilization.ts
 import { readdir as readdir15, lstat as lstat3 } from "fs/promises";
-import { existsSync as existsSync13 } from "fs";
-import path43 from "path";
+import { existsSync as existsSync14 } from "fs";
+import path44 from "path";
 function collectRawCitedFiles(body) {
   const files = /* @__PURE__ */ new Set();
   for (const para of splitProseParagraphs(body)) {
@@ -6541,17 +6919,17 @@ function collectRawCitedFiles(body) {
   return files;
 }
 async function listSourceFiles3(dir) {
-  if (!existsSync13(dir)) return [];
+  if (!existsSync14(dir)) return [];
   const entries = await readdir15(dir);
   return entries.filter((e) => e.endsWith(".md"));
 }
 function pageSlug(filePath) {
-  const dir = path43.basename(path43.dirname(filePath));
-  return dir + "/" + path43.basename(filePath, ".md");
+  const dir = path44.basename(path44.dirname(filePath));
+  return dir + "/" + path44.basename(filePath, ".md");
 }
 async function exclusionReason(sourcesDir, file) {
-  const stat3 = await lstat3(path43.join(sourcesDir, file)).catch(() => null);
-  return stat3?.isSymbolicLink() ? "symlink target missing or outside sources/ (excluded)" : "could not be resolved (excluded)";
+  const stat4 = await lstat3(path44.join(sourcesDir, file)).catch(() => null);
+  return stat4?.isSymbolicLink() ? "symlink target missing or outside sources/ (excluded)" : "could not be resolved (excluded)";
 }
 async function resolveSourceInventory(sourcesDir, sourceFiles) {
   const fileToReal = /* @__PURE__ */ new Map();
@@ -6600,7 +6978,7 @@ function buildPerSource(validFiles, fileToReal, citedRealToPages) {
   return records;
 }
 async function evaluateSourceUtilization(root) {
-  const sourcesDir = path43.join(root, SOURCES_DIR);
+  const sourcesDir = path44.join(root, SOURCES_DIR);
   const rawFiles = await listSourceFiles3(sourcesDir);
   const { validFiles, fileToReal, warnings } = await resolveSourceInventory(sourcesDir, rawFiles);
   const totalSources = validFiles.length;
@@ -6670,11 +7048,11 @@ async function evaluateCitationDepth(root) {
 
 // src/eval/citation-support.ts
 import { createHash as createHash5 } from "crypto";
-import { readFile as readFile25, appendFile as appendFile3, mkdir as mkdir8 } from "fs/promises";
-import { existsSync as existsSync14 } from "fs";
-import path44 from "path";
-var CACHE_DIR = path44.join(".llmwiki", "eval");
-var CACHE_FILE = path44.join(CACHE_DIR, "citation-cache.jsonl");
+import { readFile as readFile26, appendFile as appendFile3, mkdir as mkdir8 } from "fs/promises";
+import { existsSync as existsSync15 } from "fs";
+import path45 from "path";
+var CACHE_DIR = path45.join(".llmwiki", "eval");
+var CACHE_FILE = path45.join(CACHE_DIR, "citation-cache.jsonl");
 var JUDGE_TOOL = {
   name: "judge_citation",
   description: "Rate how well the source excerpt supports the claim.",
@@ -6700,7 +7078,7 @@ function makeCacheKey(contentHash, model) {
   return createHash5("sha256").update(contentHash + JUDGE_CONFIG_HASH + model).digest("hex").slice(0, 16);
 }
 async function readSourceLines(filePath, start, end) {
-  const content = await readFile25(filePath, "utf-8");
+  const content = await readFile26(filePath, "utf-8");
   return content.split("\n").slice(start - 1, end).join("\n");
 }
 function stripCitationMarkers(paragraph) {
@@ -6736,11 +7114,11 @@ async function extractPagePairs(slug, body, sourcesDir) {
 }
 async function extractCitationPairs(root) {
   const pages = await collectAllPages(root);
-  const sourcesDir = path44.join(root, SOURCES_DIR);
+  const sourcesDir = path45.join(root, SOURCES_DIR);
   const all = [];
   for (const { filePath, content } of pages) {
     const { body } = parseFrontmatter(content);
-    const slug = path44.basename(filePath, ".md");
+    const slug = path45.basename(filePath, ".md");
     const pairs = await extractPagePairs(slug, body, sourcesDir);
     all.push(...pairs);
   }
@@ -6758,9 +7136,9 @@ function selectDeterministicSample(pairs, sampleSize, previousHashes = []) {
   return [...retained, ...newPairs].slice(0, sampleSize);
 }
 async function loadCachedJudgements(root) {
-  const cachePath = path44.join(root, CACHE_FILE);
-  if (!existsSync14(cachePath)) return /* @__PURE__ */ new Map();
-  const content = await readFile25(cachePath, "utf-8");
+  const cachePath = path45.join(root, CACHE_FILE);
+  if (!existsSync15(cachePath)) return /* @__PURE__ */ new Map();
+  const content = await readFile26(cachePath, "utf-8");
   const map = /* @__PURE__ */ new Map();
   for (const line2 of content.trim().split("\n").filter(Boolean)) {
     try {
@@ -6772,8 +7150,8 @@ async function loadCachedJudgements(root) {
   return map;
 }
 async function appendCachedJudgement(root, judgement) {
-  await mkdir8(path44.join(root, CACHE_DIR), { recursive: true });
-  await appendFile3(path44.join(root, CACHE_FILE), JSON.stringify(judgement) + "\n");
+  await mkdir8(path45.join(root, CACHE_DIR), { recursive: true });
+  await appendFile3(path45.join(root, CACHE_FILE), JSON.stringify(judgement) + "\n");
 }
 function resolveModel() {
   const provider = process.env.LLMWIKI_PROVIDER ?? DEFAULT_PROVIDER;
@@ -6871,15 +7249,15 @@ function computeDelta(current, previous) {
 }
 
 // src/eval/thresholds.ts
-import { readFile as readFile26 } from "fs/promises";
-import { existsSync as existsSync15 } from "fs";
-import path45 from "path";
+import { readFile as readFile27 } from "fs/promises";
+import { existsSync as existsSync16 } from "fs";
+import path46 from "path";
 import yaml4 from "js-yaml";
-var THRESHOLDS_FILE = path45.join(".llmwiki", "eval", "thresholds.yaml");
+var THRESHOLDS_FILE = path46.join(".llmwiki", "eval", "thresholds.yaml");
 async function loadThresholds(root) {
-  const configPath = path45.join(root, THRESHOLDS_FILE);
-  if (!existsSync15(configPath)) return {};
-  const raw = await readFile26(configPath, "utf-8");
+  const configPath = path46.join(root, THRESHOLDS_FILE);
+  if (!existsSync16(configPath)) return {};
+  const raw = await readFile27(configPath, "utf-8");
   return yaml4.load(raw) ?? {};
 }
 function checkNewThresholds(violations, config, report) {
@@ -7080,6 +7458,9 @@ function formatHealth(report, delta) {
     const row = ruleRow(rule);
     if (row) rows.push(row);
   }
+  if (report.health.pendingReviews > 0) {
+    rows.push(line(`    pending review:  ${report.health.pendingReviews} candidate(s) awaiting approval`));
+  }
   return rows;
 }
 function formatCoverage(report, delta) {
@@ -7263,20 +7644,20 @@ function formatJudgementsDisplay(judgements) {
 }
 
 // src/eval/cache.ts
-import { unlink as unlink4, readFile as readFile27 } from "fs/promises";
-import { existsSync as existsSync16 } from "fs";
-import path46 from "path";
-var CACHE_FILE2 = path46.join(".llmwiki", "eval", "citation-cache.jsonl");
+import { unlink as unlink4, readFile as readFile28 } from "fs/promises";
+import { existsSync as existsSync17 } from "fs";
+import path47 from "path";
+var CACHE_FILE2 = path47.join(".llmwiki", "eval", "citation-cache.jsonl");
 async function clearCitationCache(root) {
-  const cachePath = path46.join(root, CACHE_FILE2);
-  if (!existsSync16(cachePath)) return false;
+  const cachePath = path47.join(root, CACHE_FILE2);
+  if (!existsSync17(cachePath)) return false;
   await unlink4(cachePath);
   return true;
 }
 async function loadCitationCache(root) {
-  const cachePath = path46.join(root, CACHE_FILE2);
-  if (!existsSync16(cachePath)) return [];
-  const content = await readFile27(cachePath, "utf-8");
+  const cachePath = path47.join(root, CACHE_FILE2);
+  if (!existsSync17(cachePath)) return [];
+  const content = await readFile28(cachePath, "utf-8");
   const judgements = [];
   for (const line2 of content.trim().split("\n").filter(Boolean)) {
     try {
@@ -7370,15 +7751,15 @@ async function evalJudgementsCommand(options = {}) {
 }
 
 // src/commands/export.ts
-import path49 from "path";
+import path55 from "path";
 import { createRequire } from "module";
 
 // src/export/collect.ts
-import path48 from "path";
+import path49 from "path";
 
 // src/context/provenance.ts
 import { promises as fs } from "fs";
-import path47 from "path";
+import path48 from "path";
 var MAX_SOURCE_WINDOWS = 20;
 var MAX_LINES_PER_WINDOW = 30;
 var CITATION_KEY_SEPARATOR = " <#> ";
@@ -7430,7 +7811,7 @@ async function readSourceWindow(root, citation) {
   return readClampedWindow(realPath, citation);
 }
 async function resolveSourcesRoot(root) {
-  const candidate = path47.join(root, SOURCES_DIR);
+  const candidate = path48.join(root, SOURCES_DIR);
   try {
     return await fs.realpath(candidate);
   } catch {
@@ -7439,10 +7820,10 @@ async function resolveSourcesRoot(root) {
 }
 async function resolveSafePath(sourcesRoot, file) {
   if (file.length === 0) return null;
-  if (path47.isAbsolute(file)) return null;
+  if (path48.isAbsolute(file)) return null;
   if (containsParentSegment2(file)) return null;
-  const joined = path47.join(sourcesRoot, file);
-  const resolved = path47.resolve(joined);
+  const joined = path48.join(sourcesRoot, file);
+  const resolved = path48.resolve(joined);
   if (!isInside2(sourcesRoot, resolved)) return null;
   try {
     const realPath = await fs.realpath(resolved);
@@ -7458,7 +7839,7 @@ function containsParentSegment2(file) {
 }
 function isInside2(parent, candidate) {
   if (candidate === parent) return true;
-  const normalizedParent = parent.endsWith(path47.sep) ? parent : `${parent}${path47.sep}`;
+  const normalizedParent = parent.endsWith(path48.sep) ? parent : `${parent}${path48.sep}`;
   return candidate.startsWith(normalizedParent);
 }
 async function readClampedWindow(realPath, citation) {
@@ -7505,7 +7886,7 @@ function resolveSourceHashes(sources, lookup) {
 // src/export/collect.ts
 function buildPagePath(pageDirectory, slug) {
   const dir = pageDirectory === "concepts" ? CONCEPTS_DIR : QUERIES_DIR;
-  return path48.posix.join(dir, `${slug}.md`);
+  return path49.posix.join(dir, `${slug}.md`);
 }
 function readStringArray(meta, field) {
   const value = meta[field];
@@ -7520,7 +7901,7 @@ function readAdvisoryConfidence(meta) {
 }
 function readProvenanceState(meta) {
   const value = meta.provenanceState;
-  if (value === "extracted" || value === "merged" || value === "inferred" || value === "ambiguous") {
+  if (value === "extracted" || value === "merged" || value === "inferred" || value === "ambiguous" || value === "imported") {
     return value;
   }
   return void 0;
@@ -7539,6 +7920,18 @@ function readContradictedBy(meta) {
   }
   return refs.length > 0 ? refs : void 0;
 }
+function readXOkf(meta) {
+  const x = meta["x-okf"];
+  if (!x || typeof x !== "object") return void 0;
+  const of = x.originalFrontmatter;
+  if (!of || typeof of !== "object") return void 0;
+  const snap = { originalFrontmatter: of };
+  const t = x.type;
+  if (typeof t === "string") snap.type = t;
+  const p = x.okfPath;
+  if (typeof p === "string") snap.okfPath = p;
+  return snap;
+}
 function readPageKind(meta) {
   const value = meta.kind;
   if (value === "concept" || value === "entity" || value === "comparison" || value === "overview") {
@@ -7567,6 +7960,7 @@ function toExportPage(raw, snapshot, sourceHashes) {
     links: extractWikilinkSlugs(raw.body),
     body: raw.body,
     kind: readPageKind(meta),
+    ...readXOkf(meta) ? { xOkf: readXOkf(meta) } : {},
     advisoryConfidence: readAdvisoryConfidence(meta),
     provenanceState: readProvenanceState(meta),
     contradictedBy: readContradictedBy(meta),
@@ -7827,9 +8221,375 @@ ${pageToSlide(p)}`);
   return [frontmatter, titleSlide, ...slides, ""].join("\n\n");
 }
 
+// src/export/okf/run.ts
+import path54 from "path";
+
+// src/export/okf/bundle.ts
+import { mkdir as mkdir9, copyFile as copyFile2, rm, readFile as readFile29, readdir as readdir16, lstat as lstat4 } from "fs/promises";
+import path53 from "path";
+
+// src/export/okf/mapping.ts
+import { createHash as createHash7 } from "crypto";
+import path50 from "path";
+var DERIVED_CITATIONS = /\n+#\s+Citations\b[\s\S]*$/;
+function canonicalBody(body) {
+  return body.replace(DERIVED_CITATIONS, "").replace(/\s*$/, "") + "\n";
+}
+function hashCanonicalBody(body) {
+  return createHash7("sha256").update(canonicalBody(body), "utf-8").digest("hex");
+}
+function safeRefName(file) {
+  const base = file.replace(/^[./\\]+/, "").replace(/[/\\]+/g, "__").replace(/[^\w.\-]+/g, "_");
+  const hash = createHash7("sha256").update(file).digest("hex").slice(0, 8);
+  const ext = path50.extname(base);
+  const stem = ext ? base.slice(0, -ext.length) : base;
+  return `${stem}-${hash}${ext}`;
+}
+var OPTIONAL_XLLMWIKI_FIELDS = [
+  ["sources", (p) => p.sources],
+  ["confidence", (p) => p.advisoryConfidence],
+  ["provenanceState", (p) => p.provenanceState],
+  ["contradictedBy", (p) => p.contradictedBy],
+  ["freshnessStatus", (p) => p.freshnessStatus],
+  ["aliases", (p) => p.aliases],
+  ["citations", (p) => p.citations]
+];
+function isPresent(value) {
+  if (value === void 0 || value === null) return false;
+  return Array.isArray(value) ? value.length > 0 : true;
+}
+function buildXLlmwiki(page) {
+  const x = {
+    schemaVersion: "0.1",
+    contentHash: hashCanonicalBody(page.body),
+    pageDirectory: page.pageDirectory
+  };
+  for (const [field, read] of OPTIONAL_XLLMWIKI_FIELDS) {
+    const value = read(page);
+    if (isPresent(value)) x[field] = value;
+  }
+  return x;
+}
+var RECONSTRUCT_STRIP = ["type", "title", "description", "tags", "timestamp", "x-llmwiki", "x-okf"];
+function applyStandardFields(fm, page) {
+  if (page.title) fm.title = page.title;
+  if (page.summary) fm.description = page.summary;
+  if (page.tags?.length) fm.tags = page.tags;
+  if (page.updatedAt) fm.timestamp = page.updatedAt;
+}
+function reconstructForeignFrontmatter(page, x) {
+  const of = page.xOkf.originalFrontmatter;
+  const rawType = typeof of.type === "string" && of.type.trim() ? of.type : page.xOkf.type ?? "concept";
+  const extras = { ...of };
+  for (const k of RECONSTRUCT_STRIP) delete extras[k];
+  const fm = { ...extras, type: rawType, "x-llmwiki": x };
+  applyStandardFields(fm, page);
+  return fm;
+}
+function mapPageToOkfFrontmatter(page) {
+  const x = buildXLlmwiki(page);
+  if (page.xOkf) return reconstructForeignFrontmatter(page, x);
+  const fm = { type: page.kind ?? "concept", "x-llmwiki": x };
+  applyStandardFields(fm, page);
+  return fm;
+}
+var WIKILINK = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
+var OKF_LINK = /\[([^\]]+)\]\(\/([^)]+?)\.md\)/g;
+var FENCE = /(```[\s\S]*?```|~~~[\s\S]*?~~~)/g;
+function wikilinksToOkf(body, resolve) {
+  return body.split(FENCE).map(
+    (seg, i) => i % 2 === 1 ? seg : seg.replace(WIKILINK, (match, rawSlug, disp) => {
+      const slug = slugify(rawSlug);
+      const target = resolve(slug);
+      if (!target) return match;
+      return `[${disp ?? target.title}](/${target.path})`;
+    })
+  ).join("");
+}
+function okfLinksToWikilinks(body, resolveLink) {
+  return body.replace(OKF_LINK, (match, text, linkPath) => {
+    const r = resolveLink(linkPath);
+    if (!r) return match;
+    return r.title === text ? `[[${r.slug}]]` : `[[${r.slug}|${text}]]`;
+  });
+}
+
+// src/export/okf/citations.ts
+function renderCitationsSection(citations, refName) {
+  if (citations.length === 0) return "";
+  const lines = citations.map((c, i) => {
+    const span = c.start !== void 0 ? `:${c.start}${c.end !== void 0 ? `-${c.end}` : ""}` : "";
+    const label = `${c.file}${span}`;
+    const name = refName(c.file);
+    return name ? `${i + 1}. [${label}](/references/${name})` : `${i + 1}. ${label}`;
+  });
+  return `
+# Citations
+
+${lines.join("\n")}
+`;
+}
+
+// src/export/okf/render-doc.ts
+function renderOkfDoc(page, resolve, refName) {
+  const fm = mapPageToOkfFrontmatter(page);
+  const canonical = canonicalBody(page.body);
+  const rewritten = wikilinksToOkf(canonical, resolve);
+  const citations = renderCitationsSection(page.citations ?? [], refName);
+  const frontmatter = buildFrontmatter(fm);
+  return `${frontmatter}
+${rewritten}${citations}`;
+}
+
+// src/export/okf/index-log.ts
+function buildOkfIndex(pages, paths) {
+  const entry = (p) => `* [${p.title}](/${paths.get(p)}) - ${p.summary}`;
+  const concepts = pages.filter((p) => p.pageDirectory === "concepts").map(entry);
+  const queries = pages.filter((p) => p.pageDirectory === "queries").map(entry);
+  const sections = [];
+  if (concepts.length) sections.push(`## Concepts
+
+${concepts.join("\n")}`);
+  if (queries.length) sections.push(`## Queries
+
+${queries.join("\n")}`);
+  return `---
+okf_version: "0.1"
+---
+
+# Knowledge Bundle
+
+${sections.join("\n\n")}
+`;
+}
+function buildOkfLog(entries) {
+  const bulletsByDate = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const bullets = bulletsByDate.get(e.date) ?? [];
+    bullets.push(`* **${e.action}** ${e.text}`);
+    bulletsByDate.set(e.date, bullets);
+  }
+  const dates = [...bulletsByDate.keys()].sort((a, b) => a < b ? 1 : -1);
+  const body = dates.map((date) => `## ${date}
+
+${bulletsByDate.get(date).join("\n")}`).join("\n\n");
+  return `# Log
+
+${body}
+`;
+}
+var LOG_HEADING = /^##\s+\[(\d{4}-\d{2}-\d{2})T[^\]]*\]\s+([\w-]+)\s+\|\s+(.*)$/gm;
+function parseLlmwikiLog(content) {
+  const entries = [];
+  for (const m of content.matchAll(LOG_HEADING)) {
+    const [, date, op, text] = m;
+    entries.push({ date, action: op.charAt(0).toUpperCase() + op.slice(1), text: text.trim() });
+  }
+  return entries;
+}
+
+// src/export/okf/references.ts
+import path51 from "path";
+function collectReferenceFiles(pages) {
+  const files = /* @__PURE__ */ new Set();
+  for (const page of pages) for (const c of page.citations ?? []) files.add(c.file);
+  return [...files];
+}
+async function resolveReferences(root, pages) {
+  const resolved = /* @__PURE__ */ new Map();
+  const sourcesDir = await safeRealpath(path51.join(root, SOURCES_DIR)) ?? path51.join(root, SOURCES_DIR);
+  for (const file of collectReferenceFiles(pages)) {
+    const realSrc = await safeRealpath(path51.join(sourcesDir, file));
+    if (!realSrc || !isInsideDir(realSrc, sourcesDir)) continue;
+    resolved.set(file, { srcAbs: realSrc, destName: safeRefName(file) });
+  }
+  return resolved;
+}
+
+// src/export/okf/output-paths.ts
+import path52 from "path";
+function slugPath(p) {
+  return `${p.pageDirectory}/${p.slug}.md`;
+}
+function isSafeOkfPath(okfPath, realOut) {
+  if (typeof okfPath !== "string" || okfPath.length === 0) return false;
+  if (path52.isAbsolute(okfPath)) return false;
+  if (!/^[A-Za-z0-9._/-]+$/.test(okfPath)) return false;
+  const segments = okfPath.split(/[/\\]+/);
+  if (segments.includes("..") || segments.includes(".")) return false;
+  if (!okfPath.endsWith(".md")) return false;
+  if (okfPath === "index.md" || okfPath === "log.md") return false;
+  if (okfPath === "references" || okfPath.startsWith("references/")) return false;
+  return isInsideDir(path52.normalize(path52.join(realOut, okfPath)), realOut);
+}
+function compareForeign(a, b) {
+  const ap = a.xOkf.okfPath, bp = b.xOkf.okfPath;
+  if (ap !== bp) return ap < bp ? -1 : 1;
+  if (a.pageDirectory !== b.pageDirectory) return a.pageDirectory < b.pageDirectory ? -1 : 1;
+  if (a.slug !== b.slug) return a.slug < b.slug ? -1 : 1;
+  return 0;
+}
+function resolveOutputPaths(pages, realOut) {
+  const owner = /* @__PURE__ */ new Map();
+  for (const p of pages) owner.set(slugPath(p), p);
+  const paths = /* @__PURE__ */ new Map();
+  const warnings = [];
+  const used = /* @__PURE__ */ new Set();
+  const foreign = pages.filter((p) => typeof p.xOkf?.okfPath === "string").sort(compareForeign);
+  const native = pages.filter((p) => typeof p.xOkf?.okfPath !== "string");
+  for (const p of foreign) {
+    const okfPath = p.xOkf.okfPath;
+    const ownerOfOkf = owner.get(okfPath);
+    const usable = isSafeOkfPath(okfPath, realOut) && !used.has(okfPath) && (ownerOfOkf === void 0 || ownerOfOkf === p);
+    if (usable) {
+      paths.set(p, okfPath);
+      used.add(okfPath);
+    } else {
+      const sp = slugPath(p);
+      paths.set(p, sp);
+      used.add(sp);
+      warnings.push(`OKF export: ${okfPath} not restorable (unsafe or collides); using ${sp}`);
+    }
+  }
+  for (const p of native) {
+    const sp = slugPath(p);
+    paths.set(p, sp);
+    used.add(sp);
+  }
+  return { paths, warnings };
+}
+
+// src/export/okf/bundle.ts
+var IGNORED_DIR_ENTRIES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db"]);
+function makeResolver(pages, paths) {
+  const map = new Map(pages.map((p) => [p.slug, { path: paths.get(p), title: p.title }]));
+  return (slug) => map.get(slug) ?? null;
+}
+async function writeConfined(out, rel, content) {
+  const abs = await confineUnderRoot(rel, out, { mustExist: false });
+  await atomicWrite(abs, content);
+  return abs;
+}
+async function lexists(p) {
+  try {
+    await lstat4(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveRealTarget(p) {
+  let cur = path53.resolve(p);
+  const suffix = [];
+  for (; ; ) {
+    const real = await safeRealpath(cur);
+    if (real) return suffix.length ? path53.join(real, ...suffix.reverse()) : real;
+    const parent = path53.dirname(cur);
+    if (parent === cur) return path53.resolve(p);
+    suffix.push(path53.basename(cur));
+    cur = parent;
+  }
+}
+async function assertSafeBundleTarget(out, root) {
+  const realRoot = await safeRealpath(root) ?? path53.resolve(root);
+  const target = await resolveRealTarget(out);
+  if (target === path53.parse(target).root) throw new Error("OKF export: refusing to export to the filesystem root");
+  if (target === realRoot) throw new Error("OKF export: refusing to export to the project root");
+  if (isInsideDir(target, path53.join(realRoot, ".git"))) throw new Error("OKF export: refusing to export inside .git");
+}
+async function assertNoTopLevelGit(realOut) {
+  if (await lexists(path53.join(realOut, ".git"))) throw new Error("OKF export: refusing to export to a directory containing .git");
+}
+async function isRecognizedBundle(realOut) {
+  const idx = path53.join(realOut, "index.md");
+  try {
+    if (!(await lstat4(idx)).isFile()) return false;
+  } catch {
+    return false;
+  }
+  const { meta } = parseFrontmatterStatus(await readFile29(idx, "utf-8"));
+  return typeof meta.okf_version !== "undefined";
+}
+async function assertNoNestedGit(realOut) {
+  for (const e of await readdir16(realOut, { withFileTypes: true })) {
+    if (e.name === ".git") throw new Error(`OKF export: refusing to clear ${realOut} \u2014 it contains a nested .git`);
+    if (e.isDirectory()) await assertNoNestedGit(path53.join(realOut, e.name));
+  }
+}
+async function clearContents(realOut) {
+  for (const name of await readdir16(realOut)) await rm(path53.join(realOut, name), { recursive: true, force: true });
+}
+async function buildLog(root, pageCount) {
+  const fallback = [{ date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10), action: "Export", text: `${pageCount} doc(s)` }];
+  const llmwikiLog = await readFile29(path53.join(root, "log.md"), "utf-8").catch(() => null);
+  const parsed = llmwikiLog ? parseLlmwikiLog(llmwikiLog) : [];
+  return buildOkfLog(parsed.length ? parsed : fallback);
+}
+async function copyResolvedReferences(refs, realOut) {
+  const written = [];
+  for (const { srcAbs, destName } of refs.values()) {
+    const dest = await confineUnderRoot(path53.join("references", destName), realOut, { mustExist: false });
+    await mkdir9(path53.dirname(dest), { recursive: true });
+    await copyFile2(srcAbs, dest);
+    written.push(dest);
+  }
+  return written;
+}
+function reportSkippedReferences(pages, refs, onWarn) {
+  const skipped = collectReferenceFiles(pages).filter((f) => !refs.has(f));
+  if (skipped.length === 0) return;
+  onWarn(`OKF export: ${skipped.length} cited source(s) not bundled (missing or outside sources/)`);
+}
+async function buildOkfBundle(root, pages, out, onWarn = (m) => status("!", warn(m))) {
+  await assertSafeBundleTarget(out, root);
+  await mkdir9(out, { recursive: true });
+  const realOut = await safeRealpath(out) ?? path53.normalize(out);
+  await assertNoTopLevelGit(realOut);
+  const empty = (await readdir16(realOut)).filter((e) => !IGNORED_DIR_ENTRIES.has(e)).length === 0;
+  const bundle = empty ? false : await isRecognizedBundle(realOut);
+  if (!empty && !bundle) throw new Error(`OKF export: ${out} is not empty and not an OKF bundle; export into a fresh directory or an existing OKF bundle.`);
+  if (bundle) {
+    await assertNoNestedGit(realOut);
+    await clearContents(realOut);
+  }
+  const { paths, warnings: pathWarnings } = resolveOutputPaths(pages, realOut);
+  const resolve = makeResolver(pages, paths);
+  const refs = await resolveReferences(root, pages);
+  const refName = (file) => refs.get(file)?.destName ?? null;
+  const written = [];
+  written.push(await writeConfined(realOut, "index.md", buildOkfIndex(pages, paths)));
+  for (const p of pages) {
+    const docRel = paths.get(p);
+    written.push(await writeConfined(realOut, docRel, renderOkfDoc(p, resolve, refName)));
+  }
+  written.push(...await copyResolvedReferences(refs, realOut));
+  written.push(await writeConfined(realOut, "log.md", await buildLog(root, pages.length)));
+  reportSkippedReferences(pages, refs, onWarn);
+  for (const w of pathWarnings) onWarn(w);
+  return written;
+}
+
+// src/export/okf/run.ts
+async function runOkfExport(root, opts = {}) {
+  const outDir = opts.out ?? path54.join(root, EXPORT_DIR, "okf");
+  const pages = await collectExportPages(root);
+  const warnings = [];
+  const writtenPaths = await buildOkfBundle(root, pages, outDir, (m) => warnings.push(m));
+  return { outDir, writtenPaths, warnings };
+}
+
 // src/export/types.ts
 var MARP_SOURCES = ["concepts", "queries", "all"];
 var EXPORT_TARGETS = [
+  "llms-txt",
+  "llms-full-txt",
+  "json",
+  "json-ld",
+  "graphml",
+  "marp",
+  "okf"
+];
+var DEFAULT_EXPORT_TARGETS = [
   "llms-txt",
   "llms-full-txt",
   "json",
@@ -7840,18 +8600,20 @@ var EXPORT_TARGETS = [
 
 // src/commands/export.ts
 var require2 = createRequire(import.meta.url);
-var EXPORT_DIR = "dist/exports";
 var TARGET_FILENAMES = {
   "llms-txt": "llms.txt",
   "llms-full-txt": "llms-full.txt",
   json: "wiki.json",
   "json-ld": "wiki.jsonld",
   graphml: "wiki.graphml",
-  marp: "wiki.md"
+  marp: "wiki.md",
+  // okf is a directory target; this entry satisfies the exhaustive Record type
+  // but is never accessed (the OKF branch continues before reaching it).
+  okf: "okf"
 };
 function resolveProjectTitle(root) {
   try {
-    const pkg = require2(path49.join(root, "package.json"));
+    const pkg = require2(path55.join(root, "package.json"));
     return typeof pkg.name === "string" ? pkg.name : "Knowledge Wiki";
   } catch {
     return "Knowledge Wiki";
@@ -7887,6 +8649,8 @@ function buildContent(inputs) {
       return buildGraphml(pages);
     case "marp":
       return buildMarp(pages, projectTitle, marpSource);
+    case "okf":
+      throw new Error("buildContent called for okf \u2014 this is a programming error");
   }
 }
 function computeReportedPageCount(pages, targets, marpSource) {
@@ -7904,8 +8668,15 @@ async function runExport(root, options = {}) {
   const marpSource = resolveMarpSource(options.source);
   const written = [];
   for (const target of targets) {
+    if (target === "okf") {
+      const { outDir, writtenPaths, warnings } = await runOkfExport(root, { out: options.out });
+      written.push(...writtenPaths);
+      for (const w of warnings) status("!", warn(w));
+      status("+", success(`Exported okf bundle \u2192 ${source(outDir)}`));
+      continue;
+    }
     const content = buildContent({ target, pages, projectTitle, marpSource, projectId });
-    const outPath = path49.join(root, EXPORT_DIR, TARGET_FILENAMES[target]);
+    const outPath = path55.join(root, EXPORT_DIR, TARGET_FILENAMES[target]);
     await atomicWrite(outPath, content);
     written.push(outPath);
     status("+", success(`Exported ${target} \u2192 ${source(outPath)}`));
@@ -7913,7 +8684,7 @@ async function runExport(root, options = {}) {
   return { written, pageCount: computeReportedPageCount(pages, targets, marpSource) };
 }
 function resolveTargets(rawTarget) {
-  if (!rawTarget) return [...EXPORT_TARGETS];
+  if (!rawTarget) return [...DEFAULT_EXPORT_TARGETS];
   if (!isValidTarget(rawTarget)) {
     throw new Error(
       `Unknown export target "${rawTarget}". Valid targets: ${EXPORT_TARGETS.join(", ")}`
@@ -7930,19 +8701,342 @@ async function exportCommand(root, options) {
   );
 }
 
+// src/import/run.ts
+import path59 from "path";
+
+// src/import/okf-import.ts
+import path58 from "path";
+
+// src/import/okf-read.ts
+import { readdir as readdir17, readFile as readFile30, stat as stat2 } from "fs/promises";
+import path56 from "path";
+
+// src/import/okf-limits.ts
+var DEFAULT_OKF_LIMITS = {
+  maxFiles: 5e3,
+  maxDocBytes: 2e6,
+  maxTotalBytes: 1e8,
+  // Total directory entries visited during the walk — bounds deep-empty-dir /
+  // many-non-`.md` trees that wouldn't otherwise count toward maxFiles.
+  maxEntries: 1e5
+};
+
+// src/import/okf-read.ts
+var RESERVED = /* @__PURE__ */ new Set(["index.md", "log.md"]);
+async function listMarkdown(root, dir, limits, acc = [], visited = { n: 0 }) {
+  for (const entry of await readdir17(dir, { withFileTypes: true })) {
+    if (++visited.n > limits.maxEntries) throw new Error(`OKF import: bundle exceeds max entry count (> ${limits.maxEntries})`);
+    const abs = path56.join(dir, entry.name);
+    if (entry.isDirectory()) await listMarkdown(root, abs, limits, acc, visited);
+    else if (entry.isFile() && entry.name.endsWith(".md")) {
+      acc.push(path56.relative(root, abs).split(path56.sep).join("/"));
+      if (acc.length > limits.maxFiles) throw new Error(`OKF import: bundle exceeds max file count (> ${limits.maxFiles})`);
+    }
+  }
+  return acc;
+}
+async function confinedInside(realRoot, rel) {
+  const real = await safeRealpath(path56.join(realRoot, rel));
+  return real && isInsideDir(real, realRoot) ? real : null;
+}
+async function readOkfBundle(bundleDir, overrides = {}, onWarn = (m) => status("!", warn(m))) {
+  const limits = { ...DEFAULT_OKF_LIMITS, ...overrides };
+  const realRoot = await safeRealpath(bundleDir);
+  if (!realRoot) throw new Error(`OKF import: bundle not found: ${bundleDir}`);
+  const rels = (await listMarkdown(realRoot, realRoot, limits)).sort();
+  const docs = [];
+  let total = 0;
+  for (const rel of rels) {
+    if (RESERVED.has(rel)) continue;
+    const real = await confinedInside(realRoot, rel);
+    if (!real) {
+      onWarn(`OKF import: skipped path escaping bundle: ${rel}`);
+      continue;
+    }
+    const size = (await stat2(real)).size;
+    total += size;
+    if (size > limits.maxDocBytes || total > limits.maxTotalBytes) throw new Error(`OKF import: bundle exceeds size limit at ${rel}`);
+    const parsed = parseFrontmatterStatus(await readFile30(real, "utf-8"));
+    const type = parsed.meta.type;
+    if (parsed.malformedFrontmatter || typeof type !== "string" || type.trim() === "") {
+      onWarn(`OKF import: skipped doc without a valid type: ${rel}`);
+      continue;
+    }
+    docs.push({ relPath: rel, meta: parsed.meta, body: parsed.body });
+  }
+  return docs;
+}
+
+// src/import/okf-map.ts
+var KNOWN_KINDS = new Set(PAGE_KINDS);
+function slugFromRelPath(relPath) {
+  const noExt = relPath.replace(/\.md$/i, "");
+  const stripped = noExt.replace(/^(concepts|queries)\//, "");
+  return slugify(stripped.replace(/[/\\]+/g, "-"));
+}
+function humanize(slug) {
+  return slug.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function resolveTargetDir(meta, relPath) {
+  const x = meta["x-llmwiki"];
+  if (x?.pageDirectory === "concepts" || x?.pageDirectory === "queries") return x.pageDirectory;
+  return relPath.startsWith("queries/") ? "queries" : "concepts";
+}
+function asStringArray(v) {
+  return Array.isArray(v) ? v.filter((s) => typeof s === "string") : [];
+}
+function pickString(v, fallback) {
+  return typeof v === "string" && v.trim() ? v : fallback;
+}
+function applyXLlmwiki(fields, x) {
+  if (typeof x.confidence === "number") fields.confidence = x.confidence;
+}
+function baseFields(meta, ctx, slug) {
+  const x = meta["x-llmwiki"] ?? {};
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    title: pickString(meta.title, humanize(slug)),
+    summary: typeof meta.description === "string" ? meta.description : "",
+    // Strip any PRIOR `okf:` origin tokens before stamping the current bundle's, so a
+    // repeated export->import->export->import cycle keeps exactly one origin token.
+    sources: Array.from(/* @__PURE__ */ new Set([
+      ...asStringArray(x.sources).filter((s) => !s.startsWith("okf:")),
+      `okf:${ctx.bundleId}`
+    ])),
+    kind: KNOWN_KINDS.has(meta.type) ? meta.type : "concept",
+    // Lossy across an OKF round-trip: `createdAt` is reset to now (OKF carries only
+    // `timestamp`, mapped to `updatedAt`); `modelId`/`promptVersion` are llmwiki-internal
+    // lineage with no OKF representation, so they are not preserved on re-import.
+    createdAt: now,
+    updatedAt: typeof meta.timestamp === "string" ? meta.timestamp : now,
+    provenanceState: "imported"
+  };
+}
+function buildXokf(meta, okfPath) {
+  const rawType = typeof meta.type === "string" ? meta.type : "concept";
+  const known = KNOWN_KINDS.has(rawType);
+  return { ...known ? {} : { type: rawType }, okfPath, originalFrontmatter: meta };
+}
+function buildPageFields(doc, ctx, slug) {
+  const meta = doc.meta;
+  const fields = baseFields(meta, ctx, slug);
+  if (Array.isArray(meta.tags)) fields.tags = asStringArray(meta.tags);
+  applyXLlmwiki(fields, meta["x-llmwiki"] ?? {});
+  fields["x-okf"] = buildXokf(meta, doc.relPath);
+  return fields;
+}
+function okfDocToPage(doc, ctx) {
+  const slug = slugFromRelPath(doc.relPath);
+  const fields = buildPageFields(doc, ctx, slug);
+  const isNative = doc.meta["x-llmwiki"] !== void 0;
+  const resolveLink = (linkPath) => {
+    const linkSlug = slugFromRelPath(linkPath);
+    const title = ctx.titleOf(linkSlug);
+    return title !== null ? { slug: linkSlug, title } : null;
+  };
+  const body = isNative ? okfLinksToWikilinks(canonicalBody(doc.body), resolveLink) : doc.body;
+  const pageBody = `${buildFrontmatter(fields)}
+${body}`;
+  return {
+    slug,
+    title: fields.title,
+    summary: fields.summary,
+    sources: fields.sources,
+    targetDirectory: resolveTargetDir(doc.meta, doc.relPath),
+    okfPath: doc.relPath,
+    body: pageBody
+  };
+}
+
+// src/import/okf-collision.ts
+import { access } from "fs/promises";
+import path57 from "path";
+async function fileExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function filterCollisions(root, pages) {
+  const pendingSlugs = new Set((await listCandidates(root)).map((c) => c.slug));
+  const claimed = /* @__PURE__ */ new Set();
+  const kept = [];
+  const skipped = [];
+  for (const page of pages) {
+    let reason = null;
+    if (claimed.has(page.slug)) reason = "duplicate-in-bundle";
+    else if (pendingSlugs.has(page.slug)) reason = "pending-candidate";
+    else if (await fileExists(path57.join(root, CONCEPTS_DIR, `${page.slug}.md`)) || await fileExists(path57.join(root, QUERIES_DIR, `${page.slug}.md`))) reason = "live-page";
+    if (reason) {
+      skipped.push({ slug: page.slug, okfPath: page.okfPath, reason });
+    } else {
+      claimed.add(page.slug);
+      kept.push(page);
+    }
+  }
+  return { kept, skipped };
+}
+
+// src/import/okf-import.ts
+function bundleIdFor(bundleDir) {
+  return slugify(path58.basename(path58.resolve(bundleDir))) || "bundle";
+}
+function titleResolver(docs) {
+  const map = /* @__PURE__ */ new Map();
+  for (const d of docs) {
+    const slug = slugFromRelPath(d.relPath);
+    if (typeof d.meta.title === "string") map.set(slug, d.meta.title);
+  }
+  return (slug) => map.get(slug) ?? null;
+}
+async function importOkfBundle(bundleDir, root, overrides = {}, onWarn) {
+  const docs = await readOkfBundle(bundleDir, overrides, onWarn);
+  const ctx = { bundleId: bundleIdFor(bundleDir), titleOf: titleResolver(docs) };
+  const mapped = docs.map((d) => okfDocToPage(d, ctx));
+  const { kept, skipped } = await filterCollisions(root, mapped);
+  return { pages: kept, skipped };
+}
+
+// src/commands/import-core.ts
+function isWritable(page) {
+  return page.slug.length > 0 && validateWikiPage(page.body);
+}
+
+// src/import/okf-refresh.ts
+async function safelyUpdateEmbeddings2(root, slugs) {
+  try {
+    await updateEmbeddings(root, slugs);
+  } catch (err) {
+    status("!", warn(`Embeddings update skipped: ${err instanceof Error ? err.message : err}`));
+  }
+}
+async function refreshAfterImport(root, slugs) {
+  await resolveLinks(root, slugs, slugs);
+  await generateIndex(root);
+  await generateMOC(root);
+  await safelyUpdateEmbeddings2(root, slugs);
+}
+
+// src/import/run-errors.ts
+var LockUnavailableError = class extends Error {
+  constructor(message = "Could not acquire lock. Try again later.") {
+    super(message);
+    this.name = "LockUnavailableError";
+  }
+};
+var QueueFullError = class extends Error {
+  constructor(message = "Review queue would exceed the cap; approve/reject pending candidates first.") {
+    super(message);
+    this.name = "QueueFullError";
+  }
+};
+
+// src/import/run.ts
+var toImported = (p) => ({ slug: p.slug, okfPath: p.okfPath, targetDirectory: p.targetDirectory });
+function partition(pages, collisionSkips) {
+  const valid = [];
+  const invalid = [];
+  for (const p of pages) {
+    if (isWritable(p)) valid.push(p);
+    else invalid.push({ slug: p.slug, okfPath: p.okfPath, reason: "invalid-page" });
+  }
+  return { valid, skipped: [...collisionSkips, ...invalid] };
+}
+async function stageAll(root, valid) {
+  for (const page of valid) {
+    await writeCandidate(root, {
+      title: page.title,
+      slug: page.slug,
+      summary: page.summary,
+      sources: page.sources,
+      body: page.body,
+      reviewMode: "imported",
+      heldReasons: [{ code: "imported-okf" }],
+      targetDirectory: page.targetDirectory,
+      okfPath: page.okfPath
+    });
+  }
+}
+async function writeAll(root, valid) {
+  const written = [];
+  try {
+    for (const page of valid) {
+      const dir = page.targetDirectory === "queries" ? QUERIES_DIR : CONCEPTS_DIR;
+      await atomicWrite(path59.join(root, dir, `${page.slug}.md`), page.body);
+      written.push(page.slug);
+    }
+  } finally {
+    if (written.length) await refreshAfterImport(root, written);
+  }
+}
+async function runOkfImport(root, dir, opts = {}) {
+  const warnings = [];
+  if (opts.dryRun) {
+    const { pages, skipped } = await importOkfBundle(dir, root, {}, (m) => warnings.push(m));
+    const { valid, skipped: allSkipped } = partition(pages, skipped);
+    return { mode: "dry-run", pages: valid.map(toImported), skipped: allSkipped, warnings, nextAction: "Re-run without dryRun to apply." };
+  }
+  const locked = await withQuiet(() => acquireLock(root));
+  if (!locked) throw new LockUnavailableError();
+  try {
+    const { pages, skipped } = await importOkfBundle(dir, root, {}, (m) => warnings.push(m));
+    const { valid, skipped: allSkipped } = partition(pages, skipped);
+    if (opts.maxNewCandidates !== void 0 && !opts.trusted) {
+      const pending = (await listCandidates(root)).length;
+      if (pending + valid.length > opts.maxNewCandidates) throw new QueueFullError();
+    }
+    if (opts.trusted) await writeAll(root, valid);
+    else await stageAll(root, valid);
+    return {
+      mode: opts.trusted ? "written" : "staged",
+      pages: valid.map(toImported),
+      skipped: allSkipped,
+      warnings,
+      nextAction: opts.trusted ? `${valid.length} page(s) written live.` : "Review and approve before it goes live: llmwiki review list."
+    };
+  } finally {
+    await releaseLock(root);
+  }
+}
+
+// src/commands/import.ts
+function printReport(report) {
+  for (const w of report.warnings) status("!", warn(w));
+  for (const p of report.pages) status("+", `${p.slug} (${p.targetDirectory}) \u2190 ${p.okfPath}`);
+  for (const s of report.skipped) status("!", warn(`skip ${s.okfPath} \u2014 ${s.reason}`));
+  const verb = report.mode === "written" ? "wrote" : report.mode === "dry-run" ? "would import" : "staged";
+  status("+", success(`OKF import: ${verb} ${report.pages.length} page(s); skipped ${report.skipped.length}.`));
+}
+async function importCommand(root, options) {
+  if (!options.okf) throw new Error("import: --okf <dir> is required");
+  try {
+    const report = await runOkfImport(root, options.okf, { trusted: options.trusted, dryRun: options.dryRun });
+    printReport(report);
+  } catch (err) {
+    if (err instanceof LockUnavailableError) {
+      status("!", error(err.message));
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+}
+
 // src/commands/schema.ts
-import { existsSync as existsSync17 } from "fs";
-import { mkdir as mkdir9, writeFile as writeFile5 } from "fs/promises";
-import path50 from "path";
+import { existsSync as existsSync18 } from "fs";
+import { mkdir as mkdir10, writeFile as writeFile5 } from "fs/promises";
+import path60 from "path";
 async function schemaInitCommand() {
   const root = process.cwd();
   const defaults = buildDefaultSchema();
   const targetPath = defaultSchemaInitPath(root);
-  if (existsSync17(targetPath)) {
+  if (existsSync18(targetPath)) {
     status("!", warn(`Schema file already exists at ${targetPath}`));
     return;
   }
-  await mkdir9(path50.dirname(targetPath), { recursive: true });
+  await mkdir10(path60.dirname(targetPath), { recursive: true });
   const serializable = {
     version: defaults.version,
     defaultKind: defaults.defaultKind,
@@ -7961,6 +9055,12 @@ async function schemaShowCommand() {
 }
 
 // src/commands/review-list.ts
+function formatMode(candidate) {
+  return candidate.reviewMode;
+}
+function formatReasons(candidate) {
+  return candidate.heldReasons.map((r) => r.code).join(", ");
+}
 async function reviewListCommand() {
   header("Pending review candidates");
   const candidates = await listCandidates(process.cwd());
@@ -7970,7 +9070,8 @@ async function reviewListCommand() {
   }
   for (const candidate of candidates) {
     const sources = candidate.sources.join(", ");
-    const meta = dim(`${candidate.generatedAt} | sources: ${sources}`);
+    const mode = `${formatMode(candidate)}: ${formatReasons(candidate)}`;
+    const meta = dim(`${candidate.generatedAt} | ${mode} | sources: ${sources}`);
     status("?", `${info(candidate.id)} \u2192 ${candidate.slug} ${meta}`);
   }
   status(
@@ -7980,6 +9081,31 @@ async function reviewListCommand() {
 }
 
 // src/commands/review-show.ts
+function candidateReasons(candidate) {
+  return candidate.heldReasons.map((reason) => reason.detail ? `${reason.code} (${reason.detail})` : reason.code);
+}
+function printReviewMetadata(candidate) {
+  status("i", dim(`review:    ${candidate.reviewMode}`));
+  status("i", dim(`reasons:   ${candidateReasons(candidate).join(", ")}`));
+  if (candidate.okfPath) {
+    status("i", dim(`okfPath:   ${candidate.okfPath}`));
+  }
+  if (candidate.confidence !== void 0) {
+    status("i", dim(`confidence: ${candidate.confidence}`));
+  }
+  if (candidate.contradicted !== void 0) {
+    status("i", dim(`contradicted: ${candidate.contradicted}`));
+  }
+}
+function printImportedWarning(candidate) {
+  if (candidate.reviewMode !== "imported") return;
+  status(
+    "!",
+    warn(
+      "Imported from an external OKF bundle \u2014 treat the body as UNTRUSTED content (possible prompt injection); provenance is unverified. Review the full body before approving."
+    )
+  );
+}
 async function reviewShowCommand(id) {
   const candidate = await loadCandidateOrFail(process.cwd(), id);
   if (!candidate) return;
@@ -7989,6 +9115,8 @@ async function reviewShowCommand(id) {
   status("i", dim(`summary:    ${candidate.summary}`));
   status("i", dim(`sources:    ${candidate.sources.join(", ")}`));
   status("i", dim(`generated:  ${candidate.generatedAt}`));
+  printReviewMetadata(candidate);
+  printImportedWarning(candidate);
   console.log();
   console.log(candidate.body);
   if (candidate.schemaViolations && candidate.schemaViolations.length > 0) {
@@ -8008,7 +9136,7 @@ async function reviewShowCommand(id) {
 }
 
 // src/commands/review-approve.ts
-import path51 from "path";
+import path61 from "path";
 
 // src/commands/review-helpers.ts
 async function runReviewUnderLock(id, underLock) {
@@ -8040,7 +9168,8 @@ async function approveUnderLock(root, id) {
     process.exitCode = 1;
     return;
   }
-  const pagePath = path51.join(root, CONCEPTS_DIR, `${candidate.slug}.md`);
+  const dir = candidate.targetDirectory === "queries" ? QUERIES_DIR : CONCEPTS_DIR;
+  const pagePath = path61.join(root, dir, `${candidate.slug}.md`);
   await atomicWrite(pagePath, candidate.body);
   status("+", success(`Approved \u2192 ${source(pagePath)}`));
   await persistCandidateSourceStates(root, candidate);
@@ -8051,28 +9180,28 @@ async function approveUnderLock(root, id) {
 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);
+  for (const [sourceFile, candidateEntry] of Object.entries(states)) {
+    await addApprovedSlugToSourceState(root, sourceFile, candidate.slug, candidateEntry.hash);
   }
 }
-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 addApprovedSlugToSourceState(root, sourceFile, approvedSlug, sourceHash) {
+  const currentState = await readState(root);
+  const existing = currentState.sources[sourceFile];
+  const concepts = existing?.concepts ?? [];
+  const merged = Array.from(/* @__PURE__ */ new Set([...concepts, approvedSlug]));
+  await updateSourceState(root, sourceFile, {
+    hash: sourceHash,
+    concepts: merged,
+    compiledAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
 }
 async function refreshWikiAfterApproval(root, slug) {
   await resolveLinks(root, [slug], [slug]);
   await generateIndex(root);
   await generateMOC(root);
-  await safelyUpdateEmbeddings2(root, [slug]);
+  await safelyUpdateEmbeddings3(root, [slug]);
 }
-async function safelyUpdateEmbeddings2(root, slugs) {
+async function safelyUpdateEmbeddings3(root, slugs) {
   try {
     await updateEmbeddings(root, slugs);
   } catch (err) {
@@ -8096,32 +9225,32 @@ async function rejectUnderLock(root, id) {
 }
 
 // src/commands/rules.ts
-import { existsSync as existsSync19 } from "fs";
-import path55 from "path";
+import { existsSync as existsSync20 } from "fs";
+import path65 from "path";
 
 // src/compiler/rule-extractor.ts
-import { readFile as readFile29 } from "fs/promises";
-import path54 from "path";
+import { readFile as readFile32 } from "fs/promises";
+import path64 from "path";
 
 // src/compiler/rule-state.ts
-import { readFile as readFile28, writeFile as writeFile6, rename as rename4, mkdir as mkdir10 } from "fs/promises";
-import { existsSync as existsSync18 } from "fs";
-import path52 from "path";
+import { readFile as readFile31, writeFile as writeFile6, rename as rename4, mkdir as mkdir11 } from "fs/promises";
+import { existsSync as existsSync19 } from "fs";
+import path62 from "path";
 function emptyRuleState() {
   return { version: 1, indexHash: "", sources: {} };
 }
 async function readRuleState(root) {
-  const filePath = path52.join(root, RULE_STATE_FILE);
-  if (!existsSync18(filePath)) return emptyRuleState();
+  const filePath = path62.join(root, RULE_STATE_FILE);
+  if (!existsSync19(filePath)) return emptyRuleState();
   try {
-    return JSON.parse(await readFile28(filePath, "utf-8"));
+    return JSON.parse(await readFile31(filePath, "utf-8"));
   } catch {
     return emptyRuleState();
   }
 }
 async function writeRuleState(root, state) {
-  await mkdir10(path52.join(root, LLMWIKI_DIR), { recursive: true });
-  const filePath = path52.join(root, RULE_STATE_FILE);
+  await mkdir11(path62.join(root, LLMWIKI_DIR), { recursive: true });
+  const filePath = path62.join(root, RULE_STATE_FILE);
   const tmpPath = `${filePath}.tmp`;
   await writeFile6(tmpPath, JSON.stringify(state, null, 2), "utf-8");
   await rename4(tmpPath, filePath);
@@ -8255,15 +9384,15 @@ function parseRules(toolOutput) {
 }
 
 // src/compiler/rule-candidates.ts
-import path53 from "path";
-import { createHash as createHash7 } from "crypto";
+import path63 from "path";
+import { createHash as createHash8 } from "crypto";
 var CONFIDENCE_VALUES = ["low", "medium", "high"];
 var STATUS_VALUES = ["proposed", "approved", "rejected"];
 function ruleCandidatePath(root, id) {
-  return path53.join(root, RULE_CANDIDATES_DIR, `${id}${CANDIDATE_JSON_EXT}`);
+  return path63.join(root, RULE_CANDIDATES_DIR, `${id}${CANDIDATE_JSON_EXT}`);
 }
 function ruleArchivePath(root, id) {
-  return path53.join(root, RULE_CANDIDATES_ARCHIVE_DIR, `${id}${CANDIDATE_JSON_EXT}`);
+  return path63.join(root, RULE_CANDIDATES_ARCHIVE_DIR, `${id}${CANDIDATE_JSON_EXT}`);
 }
 var CATEGORY_CAP = 64;
 var TITLE_CAP = 256;
@@ -8278,7 +9407,7 @@ function sanitizeRuleCategory(raw) {
 }
 function buildRuleSlug(title, contentSignature) {
   const base = slugify(title);
-  const hash = createHash7("sha256").update(contentSignature).digest("hex").slice(0, 8);
+  const hash = createHash8("sha256").update(contentSignature).digest("hex").slice(0, 8);
   return base ? `${base}-${hash}` : `rule-${hash}`;
 }
 function validateRuleCandidate(c) {
@@ -8441,7 +9570,7 @@ async function readRuleCandidate(root, fileId) {
   }
 }
 async function listRuleCandidates(root) {
-  const dir = path53.join(root, RULE_CANDIDATES_DIR);
+  const dir = path63.join(root, RULE_CANDIDATES_DIR);
   const fileIds = await listCandidateFileIds(dir);
   const candidates = [];
   for (const fileId of fileIds) {
@@ -8471,7 +9600,7 @@ async function archiveRuleCandidate(root, fileId) {
 }
 
 // src/compiler/rule-extractor.ts
-import { createHash as createHash8 } from "crypto";
+import { createHash as createHash9 } from "crypto";
 var PROVENANCE_SOURCE = "llm-wiki-compiler";
 function isUrl2(value) {
   return typeof value === "string" && /^https?:\/\//i.test(value);
@@ -8528,9 +9657,9 @@ ${rule.description}`;
   );
 }
 async function extractForSource2(root, sourceFile, provenance, createdAt) {
-  const sourcePath = path54.join(root, SOURCES_DIR, sourceFile);
-  const raw = await readFile29(sourcePath, "utf-8");
-  const hash = createHash8("sha256").update(raw).digest("hex");
+  const sourcePath = path64.join(root, SOURCES_DIR, sourceFile);
+  const raw = await readFile32(sourcePath, "utf-8");
+  const hash = createHash9("sha256").update(raw).digest("hex");
   const { meta } = parseFrontmatter(raw);
   const numbered = budgetAndNumberSource(sourceFile, raw);
   const maxLine = numbered.split("\n").length;
@@ -8600,7 +9729,7 @@ function buildRuleCandidatesJson(candidates) {
 var RULE_EXPORT_PATH = "dist/exports/rule-candidates.json";
 async function rulesExtractCommand() {
   const root = process.cwd();
-  if (!existsSync19(path55.join(root, SOURCES_DIR))) {
+  if (!existsSync20(path65.join(root, SOURCES_DIR))) {
     status("!", warn("No sources found. Run `llmwiki ingest <url>` first."));
     return;
   }
@@ -8663,7 +9792,7 @@ async function rulesExportCommand(options = {}) {
   const root = process.cwd();
   const scope = resolveScope(options.scope);
   const candidates = await collectRuleCandidatesForExport(root, scope);
-  const outPath = path55.join(root, RULE_EXPORT_PATH);
+  const outPath = path65.join(root, RULE_EXPORT_PATH);
   await atomicWrite(outPath, buildRuleCandidatesJson(candidates));
   status(
     "+",
@@ -8748,8 +9877,8 @@ async function runRulesAction(work) {
 }
 
 // src/project/state.ts
-import { stat as stat2, readdir as readdir16, readFile as readFile30 } from "fs/promises";
-import path56 from "path";
+import { stat as stat3, readdir as readdir18, readFile as readFile33 } from "fs/promises";
+import path66 from "path";
 var MARKDOWN_EXT = ".md";
 async function collectProjectState(root) {
   const rootReadable = await isDirectory(root);
@@ -8785,31 +9914,31 @@ function brokenProjectState(root) {
 }
 async function collectDirPresence(root) {
   const [hasSourcesDir, hasWikiDir, hasInternalDir] = await Promise.all([
-    isDirectory(path56.join(root, SOURCES_DIR)),
-    isDirectory(path56.join(root, "wiki")),
-    isDirectory(path56.join(root, LLMWIKI_DIR))
+    isDirectory(path66.join(root, SOURCES_DIR)),
+    isDirectory(path66.join(root, "wiki")),
+    isDirectory(path66.join(root, LLMWIKI_DIR))
   ]);
   return { hasSourcesDir, hasWikiDir, hasInternalDir };
 }
 async function collectPageCounts(root, dirs) {
   const [sourceCount, conceptCount, queryCount, pendingCandidates, hasIndex] = await Promise.all([
-    dirs.hasSourcesDir ? countMarkdownFiles(path56.join(root, SOURCES_DIR)) : 0,
-    dirs.hasWikiDir ? countMarkdownFiles(path56.join(root, CONCEPTS_DIR)) : 0,
-    dirs.hasWikiDir ? countMarkdownFiles(path56.join(root, QUERIES_DIR)) : 0,
+    dirs.hasSourcesDir ? countMarkdownFiles(path66.join(root, SOURCES_DIR)) : 0,
+    dirs.hasWikiDir ? countMarkdownFiles(path66.join(root, CONCEPTS_DIR)) : 0,
+    dirs.hasWikiDir ? countMarkdownFiles(path66.join(root, QUERIES_DIR)) : 0,
     dirs.hasInternalDir ? safeCountCandidates(root) : 0,
-    dirs.hasWikiDir ? isFile(path56.join(root, INDEX_FILE)) : false
+    dirs.hasWikiDir ? isFile(path66.join(root, INDEX_FILE)) : false
   ]);
   return { sourceCount, conceptCount, queryCount, pendingCandidates, hasIndex };
 }
 async function collectMtimes(root, dirs) {
   const [latestWikiMtimeMs, latestSourceMtimeMs] = await Promise.all([
-    dirs.hasWikiDir ? safeMtime(path56.join(root, "wiki")) : Promise.resolve(null),
-    dirs.hasSourcesDir ? safeMtime(path56.join(root, SOURCES_DIR)) : Promise.resolve(null)
+    dirs.hasWikiDir ? safeMtime(path66.join(root, "wiki")) : Promise.resolve(null),
+    dirs.hasSourcesDir ? safeMtime(path66.join(root, SOURCES_DIR)) : Promise.resolve(null)
   ]);
   return { latestWikiMtimeMs, latestSourceMtimeMs };
 }
 async function collectLintCacheStatus(root) {
-  const cachePath = path56.join(root, LAST_LINT_FILE);
+  const cachePath = path66.join(root, LAST_LINT_FILE);
   const exists = await isFile(cachePath);
   if (!exists) return { present: false, entry: null };
   const entry = await readLintCacheEntry(cachePath);
@@ -8818,7 +9947,7 @@ async function collectLintCacheStatus(root) {
 async function readLintCacheEntry(cachePath) {
   let raw;
   try {
-    raw = await readFile30(cachePath, "utf-8");
+    raw = await readFile33(cachePath, "utf-8");
   } catch {
     return null;
   }
@@ -8931,7 +10060,7 @@ function isLintCacheStale(entry, latestWikiMtimeMs) {
 }
 async function isDirectory(target) {
   try {
-    const stats = await stat2(target);
+    const stats = await stat3(target);
     return stats.isDirectory();
   } catch {
     return false;
@@ -8939,7 +10068,7 @@ async function isDirectory(target) {
 }
 async function isFile(target) {
   try {
-    const stats = await stat2(target);
+    const stats = await stat3(target);
     return stats.isFile();
   } catch {
     return false;
@@ -8947,7 +10076,7 @@ async function isFile(target) {
 }
 async function safeMtime(target) {
   try {
-    const stats = await stat2(target);
+    const stats = await stat3(target);
     return stats.mtimeMs;
   } catch {
     return null;
@@ -8955,7 +10084,7 @@ async function safeMtime(target) {
 }
 async function countMarkdownFiles(dir) {
   try {
-    const entries = await readdir16(dir, { withFileTypes: true });
+    const entries = await readdir18(dir, { withFileTypes: true });
     let count = 0;
     for (const entry of entries) {
       if (entry.isFile() && entry.name.endsWith(MARKDOWN_EXT)) count += 1;
@@ -9171,8 +10300,8 @@ function plural(count) {
 }
 
 // src/compiler/refresh-plan.ts
-import { readdir as readdir17 } from "fs/promises";
-import path57 from "path";
+import { readdir as readdir19 } from "fs/promises";
+import path67 from "path";
 function ownersOf2(slug, snapshot) {
   return Object.entries(snapshot.sources).filter(([, s]) => s.concepts.includes(slug)).map(([file, s]) => ({
     file,
@@ -9223,7 +10352,7 @@ async function resolveStaleRefresh(root) {
   }
   const snapshot = await buildFreshnessSnapshot(root, classified);
   const state = classified.state;
-  const pages = await scanWikiPages(path57.join(root, CONCEPTS_DIR));
+  const pages = await scanWikiPages(path67.join(root, CONCEPTS_DIR));
   const c = classifyPages(pages, snapshot);
   return {
     stateStatus: "ok",
@@ -9250,7 +10379,7 @@ function knownAffectedFor(state, changed, deleted) {
 async function listNewSkipped(root, state) {
   let files;
   try {
-    files = (await readdir17(path57.join(root, SOURCES_DIR))).filter((f) => f.endsWith(".md"));
+    files = (await readdir19(path67.join(root, SOURCES_DIR))).filter((f) => f.endsWith(".md"));
   } catch {
     return [];
   }
@@ -9293,7 +10422,7 @@ async function warnOnReviewBypass(root) {
   const pending = await countCandidates(root);
   if (pending > 0) {
     status("!", warn(
-      `refresh --stale writes directly to wiki/ and does not create review candidates (${pending} pending candidate(s) exist).`
+      `${pending} pending review candidate(s) exist \u2014 refresh respects the project review policy; pages tripping policy are held for review, not written directly.`
     ));
   }
 }
@@ -9303,12 +10432,24 @@ function reportCompileOutcome(result, plan) {
     reportNewSkipped(plan.newSkipped);
     return 1;
   }
-  status("\u2713", success(
-    `Refreshed ${plan.recompiledPages.length} page(s); cleaned up ${plan.computedOrphanedPages.length} orphaned page(s).`
-  ));
+  const heldCount = (result.review?.held.length ?? 0) + (result.review?.forced.length ?? 0);
+  const liveRefreshed = plan.recompiledPages.length - heldCount;
+  const orphanedCount = plan.computedOrphanedPages.length;
+  status("\u2713", success(buildRefreshSummary(liveRefreshed, heldCount, orphanedCount)));
   reportNewSkipped(plan.newSkipped);
   return 0;
 }
+function buildRefreshSummary(liveRefreshed, heldCount, orphanedCount) {
+  const parts = [];
+  if (liveRefreshed > 0 || heldCount === 0) {
+    parts.push(`Refreshed ${liveRefreshed} page(s)`);
+  }
+  if (heldCount > 0) {
+    parts.push(`held ${heldCount} for review \u2014 run \`llmwiki review list\``);
+  }
+  parts.push(`cleaned up ${orphanedCount} orphaned page(s)`);
+  return parts.join("; ");
+}
 function maybeEnsureProvider(plan, ensureProvider) {
   const needsLLM = plan.changedOwners.length > 0 || plan.knownAffected.length > 0;
   if (needsLLM) ensureProvider?.();
@@ -9354,7 +10495,7 @@ function planDetailRows(plan) {
 }
 
 // src/commands/quickstart.ts
-import path58 from "path";
+import path68 from "path";
 var QUICKSTART_JSON_VERSION = 1;
 var VIEW_OPEN_ARGS_KEY = "view\0--open";
 var NOOP_RESTORE = () => {
@@ -9421,7 +10562,7 @@ async function runIngestStep(source2) {
   status("*", info(`Ingesting ${source2}`));
   try {
     const result = await ingestSource(process.cwd(), source2);
-    const relPath = path58.join(SOURCES_DIR, result.filename);
+    const relPath = path68.join(SOURCES_DIR, result.filename);
     status("+", success(`Ingested \u2192 ${relPath}`));
     return buildIngestSuccess(result, relPath);
   } catch (err) {
@@ -9670,7 +10811,7 @@ function appendNextLines(lines, next) {
 }
 
 // src/commands/context.ts
-import path59 from "path";
+import path69 from "path";
 
 // src/context/ranking.ts
 var WEIGHT_TITLE_MATCH = 0.5;
@@ -10494,7 +11635,7 @@ function appendPrimaryPages(lines, primary) {
   for (const page of primary) appendPrimaryPage(lines, page);
 }
 function appendPrimaryPage(lines, page) {
-  const pageFile = path59.join("wiki", page.pageDirectory, `${slugFromId(page.id)}.md`);
+  const pageFile = path69.join("wiki", page.pageDirectory, `${slugFromId(page.id)}.md`);
   lines.push(`### ${page.title} (\`${pageFile}\`)`);
   lines.push("");
   lines.push(`Why included: ${page.reasons.join(", ") || "(no signals)"}`);
@@ -10555,8 +11696,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z as z2 } from "zod";
 
 // src/status/collect.ts
-import path60 from "path";
-import { readdir as readdir18 } from "fs/promises";
+import path70 from "path";
+import { readdir as readdir20 } from "fs/promises";
 var MAX_STATUS_LIST = 100;
 function classifyConceptPages(scanned, snapshot) {
   const stalePages = [];
@@ -10577,7 +11718,7 @@ function lastCompileTime(sources) {
 }
 async function listSourceFilesOnDisk(root) {
   try {
-    const entries = await readdir18(path60.join(root, SOURCES_DIR));
+    const entries = await readdir20(path70.join(root, SOURCES_DIR));
     return entries.filter((f) => f.endsWith(".md"));
   } catch {
     return [];
@@ -10605,9 +11746,9 @@ async function collectStatus(root) {
   const classified = await readStateClassified(root);
   const snapshot = await buildFreshnessSnapshot(root, classified);
   const [conceptSummaries, queries, scannedConcepts, pendingCandidates, sourceFilesOnDisk] = await Promise.all([
-    collectPageSummaries(path60.join(root, CONCEPTS_DIR)),
-    collectPageSummaries(path60.join(root, QUERIES_DIR)),
-    scanWikiPages(path60.join(root, CONCEPTS_DIR)),
+    collectPageSummaries(path70.join(root, CONCEPTS_DIR)),
+    collectPageSummaries(path70.join(root, QUERIES_DIR)),
+    scanWikiPages(path70.join(root, CONCEPTS_DIR)),
     countCandidates(root),
     listSourceFilesOnDisk(root)
   ]);
@@ -10629,11 +11770,11 @@ async function collectStatus(root) {
 }
 
 // src/pages/read.ts
-import path61 from "path";
+import path71 from "path";
 var PAGE_DIRS2 = [CONCEPTS_DIR, QUERIES_DIR];
 async function readPageRecord2(root, slug) {
   for (const dir of PAGE_DIRS2) {
-    const content = await safeReadFile(path61.join(root, dir, `${slug}.md`));
+    const content = await safeReadFile(path71.join(root, dir, `${slug}.md`));
     if (!content) continue;
     const { meta, body } = parseFrontmatter(content);
     if (meta.orphaned) continue;
@@ -10648,7 +11789,7 @@ async function readPageRecord2(root, slug) {
 }
 
 // src/search/retrieval.ts
-import path62 from "path";
+import path72 from "path";
 function dedupePreservingOrder(slugs) {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
@@ -10670,7 +11811,7 @@ async function pickSearchSlugs(root, question) {
     if (candidates.length > 0) return candidates.map((c) => c.slug);
   } catch {
   }
-  const indexContent = await safeReadFile(path62.join(root, INDEX_FILE));
+  const indexContent = await safeReadFile(path72.join(root, INDEX_FILE));
   const { pages } = await selectPages(question, indexContent);
   return pages;
 }
@@ -10683,13 +11824,21 @@ async function loadPageRecords(root, slugs) {
   return records;
 }
 
-// src/mcp/tools.ts
+// src/mcp/result.ts
 function jsonResult(payload) {
   return {
     content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
     structuredContent: { result: payload }
   };
 }
+function errorResult(message) {
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true
+  };
+}
+
+// src/mcp/tools.ts
 function registerWikiTools(server, root) {
   registerIngestTool(server, root);
   registerCompileTool(server, root);
@@ -10871,9 +12020,62 @@ function registerEvalTool(server, root) {
   );
 }
 
+// src/mcp/okf-tools.ts
+import { z as z3 } from "zod";
+var MAX_MCP_PENDING_CANDIDATES = 200;
+function registerOkfTools(server, root, maxPending = MAX_MCP_PENDING_CANDIDATES) {
+  server.registerTool(
+    "export_okf",
+    {
+      title: "Export OKF bundle",
+      description: "Export the wiki as an Open Knowledge Format (OKF) v0.1 bundle. `out` defaults to dist/exports/okf and must stay inside the project.",
+      inputSchema: { out: z3.string().optional().describe("Output dir for the bundle (must resolve inside the project root)") }
+    },
+    // withQuiet: the export core can print skipped-reference warnings via output.status;
+    // on the MCP stdio transport those would land on the JSON-RPC stream and corrupt it.
+    async ({ out }) => withQuiet(async () => {
+      try {
+        const dest = await confineUnderRoot(out ?? "dist/exports/okf", root, { mustExist: false });
+        const report = await runOkfExport(root, { out: dest });
+        return jsonResult({ outDir: report.outDir, fileCount: report.writtenPaths.length, files: report.writtenPaths.slice(0, 20), warnings: report.warnings });
+      } catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+      }
+    })
+  );
+  server.registerTool(
+    "import_okf",
+    {
+      title: "Import OKF bundle (staged for review)",
+      description: "Import an OKF bundle from a path INSIDE the project as review candidates. Always staging-only \u2014 imported knowledge requires human review/approval before it enters the wiki. Use dryRun to preview.",
+      inputSchema: {
+        dir: z3.string().describe("Bundle directory (must resolve inside the project root)"),
+        dryRun: z3.boolean().optional().describe("Preview only \u2014 stage nothing")
+      }
+    },
+    // withQuiet: same stdio-stream guard as export_okf (the import core may emit warnings).
+    async ({ dir, dryRun }) => withQuiet(async () => {
+      try {
+        const bundle = await confineUnderRoot(dir, root, { mustExist: true });
+        const report = await runOkfImport(root, bundle, { trusted: false, dryRun, maxNewCandidates: maxPending });
+        return jsonResult({
+          mode: report.mode,
+          imported: report.pages.length,
+          pages: report.pages,
+          skipped: report.skipped,
+          warnings: report.warnings,
+          nextAction: report.mode === "dry-run" ? "Preview only \u2014 re-run without dryRun to stage these as review candidates." : "Imported docs are STAGED as review candidates \u2014 approve them via `llmwiki review` (human gate) before they enter the wiki."
+        });
+      } catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+      }
+    })
+  );
+}
+
 // src/mcp/resources.ts
-import path63 from "path";
-import { readdir as readdir19 } from "fs/promises";
+import path73 from "path";
+import { readdir as readdir21 } from "fs/promises";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 function jsonContent(uri, payload) {
   return {
@@ -10908,7 +12110,7 @@ function registerIndexResource(server, root) {
       mimeType: "text/markdown"
     },
     async (uri) => {
-      const content = await safeReadFile(path63.join(root, INDEX_FILE));
+      const content = await safeReadFile(path73.join(root, INDEX_FILE));
       return { contents: [markdownContent(uri, content)] };
     }
   );
@@ -10975,23 +12177,23 @@ function registerQueryResource(server, root) {
   );
 }
 async function listSources(root) {
-  const sourcesPath = path63.join(root, SOURCES_DIR);
+  const sourcesPath = path73.join(root, SOURCES_DIR);
   let files;
   try {
-    files = await readdir19(sourcesPath);
+    files = await readdir21(sourcesPath);
   } catch {
     return [];
   }
   const records = [];
   for (const file of files.filter((f) => f.endsWith(".md"))) {
-    const content = await safeReadFile(path63.join(sourcesPath, file));
+    const content = await safeReadFile(path73.join(sourcesPath, file));
     const { meta } = parseFrontmatter(content);
     records.push({ filename: file, ...meta });
   }
   return records;
 }
 async function loadPageWithMeta(root, dir, slug) {
-  const filePath = path63.join(root, dir, `${slug}.md`);
+  const filePath = path73.join(root, dir, `${slug}.md`);
   const content = await safeReadFile(filePath);
   if (!content) {
     throw new Error(`Page not found: ${dir}/${slug}.md`);
@@ -11030,10 +12232,10 @@ function registerEvalHistoryResource(server, root) {
   );
 }
 async function listPagesUnder(root, dir, scheme) {
-  const pagesPath = path63.join(root, dir);
+  const pagesPath = path73.join(root, dir);
   let files;
   try {
-    files = await readdir19(pagesPath);
+    files = await readdir21(pagesPath);
   } catch {
     return { resources: [] };
   }
@@ -11051,6 +12253,7 @@ async function startMCPServer(options) {
     instructions: "llmwiki is a knowledge compiler. Use ingest_source to add raw sources, compile_wiki to run the LLM pipeline, query_wiki for grounded answers, search_pages to retrieve relevant pages, and run_eval to score wiki quality. read_page, lint_wiki, wiki_status, and run_eval (fast suite, record: false) work without an API key and do not mutate state."
   });
   registerWikiTools(server, root);
+  registerOkfTools(server, root);
   registerWikiResources(server, root);
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -11248,7 +12451,7 @@ program.command("export").description("Export wiki content to portable formats (
 ).option(
   "--project-id <id>",
   "Bridge identifier embedded in the JSON export envelope. Must match /^[a-z0-9][a-z0-9-]{0,62}$/."
-).action(async (options) => {
+).option("--out <dir>", "Output directory for directory-style targets (e.g. okf)").action(async (options) => {
   try {
     await exportCommand(process.cwd(), options);
   } catch (err) {
@@ -11256,6 +12459,17 @@ program.command("export").description("Export wiki content to portable formats (
     process.exit(1);
   }
 });
+program.command("import").description("Import an OKF bundle as review candidates (default) or live pages (--trusted)").requiredOption("--okf <dir>", "Path to the OKF bundle directory to import").option(
+  "--trusted",
+  "Write mapped pages directly into wiki/ instead of staging for review (you vouch for the bundle's contents and its self-declared provenance)"
+).option("--dry-run", "Report what would be imported (and skipped) without writing anything").action(async (options) => {
+  try {
+    await importCommand(process.cwd(), options);
+  } catch (err) {
+    console.error(`\x1B[31mError:\x1B[0m ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+});
 program.command("next").description("Show the recommended next action for this llmwiki project (read-only)").option("--json", "Emit a stable JSON envelope for agent consumption").action(
   async (options) => runExitCodeCommand(() => nextCommand({ json: options.json }))
 );