@swarmvaultai/engine 0.7.30 → 0.7.31

package/dist/index.js

@@ -22,7 +22,7 @@ import {
   uniqueBy,
   writeFileIfChanged,
   writeJsonFile
-} from "./chunk-N56FAH4N.js";
+} from "./chunk-NECZ4MUE.js";
 import {
   estimatePageTokens,
   estimateTokens,
@@ -492,6 +492,100 @@ async function autoCommitWikiChanges(rootDir, operation, detail, options) {
   return message;
 }
 
+// src/candidate-promotion.ts
+var DEFAULT_PROMOTION_CONFIG = {
+  enabled: false,
+  minSources: 3,
+  minConfidence: 0.8,
+  minAgreement: 0.7,
+  minDegree: 2,
+  minAgeHours: 24,
+  maxPerRun: 25,
+  dryRun: false
+};
+function jaccard(left, right) {
+  if (left.length === 0 && right.length === 0) return 1;
+  const leftSet = new Set(left);
+  const rightSet = new Set(right);
+  const union = /* @__PURE__ */ new Set([...leftSet, ...rightSet]);
+  if (union.size === 0) return 1;
+  let intersection = 0;
+  for (const item of leftSet) {
+    if (rightSet.has(item)) intersection++;
+  }
+  return intersection / union.size;
+}
+function hoursSince(iso, now) {
+  const then = new Date(iso).getTime();
+  if (!Number.isFinite(then)) return 0;
+  return Math.max(0, (now - then) / (1e3 * 60 * 60));
+}
+function maxDegreeFor(graph, nodeIds) {
+  let best = 0;
+  const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+  for (const nodeId of nodeIds) {
+    const node = byId.get(nodeId);
+    if (node && (node.degree ?? 0) > best) best = node.degree ?? 0;
+  }
+  return best;
+}
+function describeGate(result) {
+  const verb = result.passed ? ">=" : "<";
+  return `${result.gate} ${result.value.toFixed(2)} ${verb} ${result.threshold.toFixed(2)}`;
+}
+function evaluateCandidateForPromotion(page, graph, history, config, now = Date.now()) {
+  const historical = history?.[page.id];
+  const historicalSources = historical?.sourceIds ?? [];
+  const agreement = historicalSources.length ? jaccard(historicalSources, page.sourceIds) : 0;
+  const degree = maxDegreeFor(graph, page.nodeIds);
+  const ageHours = hoursSince(page.createdAt, now);
+  const gates = [
+    { gate: "sources", value: page.sourceIds.length, threshold: config.minSources, passed: page.sourceIds.length >= config.minSources },
+    { gate: "confidence", value: page.confidence, threshold: config.minConfidence, passed: page.confidence >= config.minConfidence },
+    { gate: "agreement", value: agreement, threshold: config.minAgreement, passed: agreement >= config.minAgreement },
+    { gate: "degree", value: degree, threshold: config.minDegree, passed: degree >= config.minDegree },
+    { gate: "age", value: ageHours, threshold: config.minAgeHours, passed: ageHours >= config.minAgeHours }
+  ];
+  const passedCount = gates.filter((gate) => gate.passed).length;
+  const promote = gates.every((gate) => gate.passed);
+  const score = passedCount / gates.length;
+  return {
+    pageId: page.id,
+    title: page.title,
+    kind: page.kind,
+    promote,
+    score,
+    gates,
+    reasons: gates.map(describeGate)
+  };
+}
+function sortDecisionsForPromotion(decisions) {
+  return [...decisions].sort((left, right) => {
+    if (left.promote !== right.promote) return left.promote ? -1 : 1;
+    if (right.score !== left.score) return right.score - left.score;
+    return left.pageId.localeCompare(right.pageId);
+  });
+}
+function renderPromotionSessionMarkdown(decisions, promotedPageIds, options) {
+  const lines = [];
+  lines.push(`# Auto-Promotion Run`);
+  lines.push("");
+  lines.push(`- started: ${options.startedAt}`);
+  lines.push(`- finished: ${options.finishedAt}`);
+  lines.push(`- mode: ${options.dryRun ? "dry-run" : "applied"}`);
+  lines.push(`- promoted: ${promotedPageIds.length}`);
+  lines.push(`- evaluated: ${decisions.length}`);
+  lines.push("");
+  lines.push(`| page | decision | score | reasons |`);
+  lines.push(`| --- | --- | --- | --- |`);
+  for (const decision of sortDecisionsForPromotion(decisions)) {
+    const decided = decision.promote ? promotedPageIds.includes(decision.pageId) ? "promoted" : "promote (dry-run)" : "skipped";
+    lines.push(`| ${decision.pageId} | ${decided} | ${decision.score.toFixed(2)} | ${decision.reasons.join("; ")} |`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
 // src/graph-export.ts
 import { readFileSync } from "fs";
 import fs2 from "fs/promises";
@@ -7803,7 +7897,7 @@ function tsconfigPathAliasesForFile(repoRelativePath, config) {
         );
         const patternBase = pattern.replace("*", "");
         for (const candidate of [stripped, indexStripped]) {
-          if (candidate && candidate.startsWith(targetPrefix)) {
+          if (candidate?.startsWith(targetPrefix)) {
             aliases.push(patternBase + candidate.slice(targetPrefix.length));
           }
         }
@@ -7816,11 +7910,11 @@ function tsconfigPathAliasesForFile(repoRelativePath, config) {
     }
   }
   if (config.baseUrl !== ".") {
-    const basePrefix = normalizeAlias(config.baseUrl) + "/";
+    const basePrefix = `${normalizeAlias(config.baseUrl)}/`;
     if (stripped.startsWith(basePrefix)) {
       aliases.push(stripped.slice(basePrefix.length));
     }
-    if (indexStripped && indexStripped.startsWith(basePrefix)) {
+    if (indexStripped?.startsWith(basePrefix)) {
       aliases.push(indexStripped.slice(basePrefix.length));
     }
   }
@@ -10995,6 +11089,37 @@ var MARKDOWN_SEMANTIC_FRONTMATTER_KEYS = [
 function uniqueStrings(values) {
   return [...new Set(values.filter(Boolean))];
 }
+function ingestRunStatePath(stateDir, runId) {
+  return path12.join(stateDir, "ingest-runs", `${runId}.json`);
+}
+function buildIngestRunId() {
+  return `ingest-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${Math.random().toString(36).slice(2, 8)}`;
+}
+async function loadIngestRunState(stateDir, runId) {
+  if (!runId) return null;
+  const absolute = ingestRunStatePath(stateDir, runId);
+  if (!await fileExists(absolute)) {
+    throw new Error(`Ingest run state not found: ${runId}`);
+  }
+  const loaded = await readJsonFile(absolute);
+  if (!loaded) {
+    throw new Error(`Ingest run state is empty or unreadable: ${runId}`);
+  }
+  return loaded;
+}
+async function saveIngestRunState(stateDir, state) {
+  const absolute = ingestRunStatePath(stateDir, state.runId);
+  await ensureDir(path12.dirname(absolute));
+  await writeJsonFile(absolute, state);
+  return absolute;
+}
+async function clearIngestRunState(stateDir, runId) {
+  const absolute = ingestRunStatePath(stateDir, runId);
+  try {
+    await fs11.rm(absolute, { force: true });
+  } catch {
+  }
+}
 function inferKind(mimeType, filePath, detectionOptions = {}) {
   if (inferCodeLanguage(filePath, mimeType, detectionOptions)) {
     return "code";
@@ -11447,7 +11572,8 @@ function normalizeIngestOptions(options) {
     exclude: (options?.exclude ?? []).map((pattern) => pattern.trim()).filter(Boolean),
     maxFiles: Math.max(1, Math.floor(options?.maxFiles ?? DEFAULT_MAX_DIRECTORY_FILES)),
     gitignore: options?.gitignore ?? true,
-    extractClasses: options?.extractClasses ?? ["first_party"]
+    extractClasses: options?.extractClasses ?? ["first_party"],
+    resume: options?.resume
   };
 }
 async function resolveRepoIngestOptions(rootDir, options) {
@@ -13489,37 +13615,73 @@ async function ingestDirectory(rootDir, inputDir, options) {
       skipped: result.skipped
     };
   }
-  const { files, skipped } = await collectDirectoryFiles(rootDir, absoluteInputDir, repoRoot, normalizedOptions);
+  const collected = await collectDirectoryFiles(rootDir, absoluteInputDir, repoRoot, normalizedOptions);
+  const skipped = collected.skipped;
+  let files = collected.files;
+  const resumeState = await loadIngestRunState(paths.stateDir, normalizedOptions.resume);
+  if (resumeState) {
+    const failedSet = new Set(resumeState.failed.map((entry) => entry.absolutePath));
+    files = files.filter((absolutePath) => failedSet.has(absolutePath));
+  }
+  const runId = resumeState?.runId ?? buildIngestRunId();
   const imported = [];
   const updated = [];
+  const failed = [];
+  const failedRecords = [];
   const progress = createProgressReporter("ingest", files.length);
   for (const absolutePath of files) {
+    const relativeForLog = toPosix(path12.relative(rootDir, absolutePath));
     const relativePath = repoRelativePathFor(absolutePath, repoRoot) ?? toPosix(path12.relative(repoRoot, absolutePath));
-    const preparedInputs = await prepareFileInputs(
-      rootDir,
-      absolutePath,
-      repoRoot,
-      sourceClassForRelativePath(relativePath, normalizedOptions)
-    );
-    const result = await persistPreparedInputs(rootDir, absolutePath, preparedInputs, paths);
-    if (result.created.length) {
-      imported.push(...result.created);
-    }
-    if (result.updated.length) {
-      updated.push(...result.updated);
+    let preparedInputs;
+    try {
+      preparedInputs = await prepareFileInputs(
+        rootDir,
+        absolutePath,
+        repoRoot,
+        sourceClassForRelativePath(relativePath, normalizedOptions)
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      failed.push({ path: relativeForLog, error: message, stage: "prepare" });
+      failedRecords.push({ absolutePath, path: relativeForLog, error: message, stage: "prepare" });
+      progress.tick();
+      continue;
     }
-    if (!result.created.length && !result.updated.length && !result.removed.length) {
-      skipped.push({ path: toPosix(path12.relative(rootDir, absolutePath)), reason: "duplicate_content" });
+    try {
+      const result = await persistPreparedInputs(rootDir, absolutePath, preparedInputs, paths);
+      if (result.created.length) imported.push(...result.created);
+      if (result.updated.length) updated.push(...result.updated);
+      if (!result.created.length && !result.updated.length && !result.removed.length) {
+        skipped.push({ path: relativeForLog, reason: "duplicate_content" });
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      failed.push({ path: relativeForLog, error: message, stage: "persist" });
+      failedRecords.push({ absolutePath, path: relativeForLog, error: message, stage: "persist" });
     }
     progress.tick();
   }
-  progress.finish(`imported=${imported.length}, updated=${updated.length}, skipped=${skipped.length}`);
+  progress.finish(`imported=${imported.length}, updated=${updated.length}, skipped=${skipped.length}, failed=${failed.length}`);
+  let statePath;
+  if (failed.length) {
+    statePath = await saveIngestRunState(paths.stateDir, {
+      runId,
+      inputDir: absoluteInputDir,
+      repoRoot,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      failed: failedRecords
+    });
+  } else if (resumeState) {
+    await clearIngestRunState(paths.stateDir, resumeState.runId);
+  }
   await appendLogEntry(rootDir, "ingest_directory", toPosix(path12.relative(rootDir, absoluteInputDir)) || ".", [
     `repo_root=${toPosix(path12.relative(rootDir, repoRoot)) || "."}`,
+    `run_id=${runId}`,
     `scanned=${files.length}`,
     `imported=${imported.length}`,
     `updated=${updated.length}`,
-    `skipped=${skipped.length}`
+    `skipped=${skipped.length}`,
+    `failed=${failed.length}`
   ]);
   return {
     inputDir: absoluteInputDir,
@@ -13527,7 +13689,10 @@ async function ingestDirectory(rootDir, inputDir, options) {
     scannedCount: files.length,
     imported,
     updated,
-    skipped
+    skipped,
+    failed,
+    runId,
+    statePath
   };
 }
 async function importInbox(rootDir, inputDir) {
@@ -13643,7 +13808,7 @@ async function readExtractionArtifact(rootDir, manifest) {
 
 // src/mcp.ts
 import fs20 from "fs/promises";
-import path24 from "path";
+import path25 from "path";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z as z8 } from "zod";
@@ -18056,7 +18221,7 @@ async function resolveImageGenerationProvider(rootDir) {
   if (!providerConfig) {
     throw new Error(`No provider configured with id "${preferredProviderId}" for task "imageProvider".`);
   }
-  const { createProvider: createProvider2 } = await import("./registry-SYCRRA65.js");
+  const { createProvider: createProvider2 } = await import("./registry-4C55ZCPL.js");
   return createProvider2(preferredProviderId, providerConfig, rootDir);
 }
 async function generateOutputArtifacts(rootDir, input) {
@@ -20877,10 +21042,9 @@ function updateCandidateHistory(compileState, page, deleted = false) {
 function sortGraphPages(pages) {
   return [...pages].sort((left, right) => left.path.localeCompare(right.path) || left.title.localeCompare(right.title));
 }
-function computeUnifiedDiff(current, staged, label) {
+function diffLines(current, staged) {
   const currentLines = current.split("\n");
   const stagedLines = staged.split("\n");
-  const output = [`--- a/${label}`, `+++ b/${label}`];
   const n = currentLines.length;
   const m = stagedLines.length;
   const dp = Array.from({ length: n + 1 }, () => Array(m + 1).fill(0));
@@ -20889,23 +21053,107 @@ function computeUnifiedDiff(current, staged, label) {
       dp[i2][j2] = currentLines[i2] === stagedLines[j2] ? dp[i2 + 1][j2 + 1] + 1 : Math.max(dp[i2 + 1][j2], dp[i2][j2 + 1]);
     }
   }
+  const lines = [];
   let i = 0;
   let j = 0;
   while (i < n || j < m) {
     if (i < n && j < m && currentLines[i] === stagedLines[j]) {
-      output.push(` ${currentLines[i]}`);
+      lines.push({ type: "context", value: currentLines[i] });
       i++;
       j++;
     } else if (j < m && (i >= n || dp[i][j + 1] >= dp[i + 1][j])) {
-      output.push(`+${stagedLines[j]}`);
+      lines.push({ type: "add", value: stagedLines[j] });
       j++;
     } else {
-      output.push(`-${currentLines[i]}`);
+      lines.push({ type: "remove", value: currentLines[i] });
       i++;
     }
   }
+  return lines;
+}
+function computeUnifiedDiff(current, staged, label) {
+  const output = [`--- a/${label}`, `+++ b/${label}`];
+  for (const line of diffLines(current, staged)) {
+    const prefix = line.type === "add" ? "+" : line.type === "remove" ? "-" : " ";
+    output.push(`${prefix}${line.value}`);
+  }
   return output.join("\n");
 }
+var PROTECTED_FRONTMATTER_FIELDS = /* @__PURE__ */ new Set([
+  "page_id",
+  "source_ids",
+  "node_ids",
+  "freshness",
+  "source_hashes",
+  "source_semantic_hashes",
+  "schema_hash"
+]);
+function stableSerialize(value) {
+  if (value === void 0) return "undefined";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableSerialize).join(",")}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableSerialize(value[key])}`).join(",")}}`;
+}
+function compareFrontmatter(currentData, stagedData) {
+  const keys = /* @__PURE__ */ new Set([...Object.keys(currentData), ...Object.keys(stagedData)]);
+  const changes = [];
+  for (const key of keys) {
+    const before = currentData[key];
+    const after = stagedData[key];
+    if (stableSerialize(before) === stableSerialize(after)) continue;
+    changes.push({
+      key,
+      before,
+      after,
+      protected: PROTECTED_FRONTMATTER_FIELDS.has(key)
+    });
+  }
+  return changes.sort((left, right) => left.key.localeCompare(right.key));
+}
+function computeStructuredDiff(current, staged, isBinaryAsset) {
+  if (isBinaryAsset) {
+    return {
+      hunks: [],
+      addedLines: 0,
+      removedLines: 0,
+      frontmatterChanges: []
+    };
+  }
+  if (!current && !staged) return void 0;
+  let currentData = {};
+  let stagedData = {};
+  let currentBody = current ?? "";
+  let stagedBody = staged ?? "";
+  if (current) {
+    const parsed = matter10(current);
+    currentData = parsed.data ?? {};
+    currentBody = parsed.content;
+  }
+  if (staged) {
+    const parsed = matter10(staged);
+    stagedData = parsed.data ?? {};
+    stagedBody = parsed.content;
+  }
+  const lines = diffLines(currentBody, stagedBody);
+  const addedLines = lines.filter((line) => line.type === "add").length;
+  const removedLines = lines.filter((line) => line.type === "remove").length;
+  const hunks = lines.length ? [
+    {
+      oldStart: 1,
+      oldLines: currentBody.split("\n").length,
+      newStart: 1,
+      newLines: stagedBody.split("\n").length,
+      lines
+    }
+  ] : [];
+  return {
+    hunks,
+    addedLines,
+    removedLines,
+    frontmatterChanges: compareFrontmatter(currentData, stagedData)
+  };
+}
 function computeChangeSummary(current, staged, changeType) {
   if (changeType === "create") return "New page";
   if (changeType === "delete") return "Removed page";
@@ -20956,7 +21204,16 @@ async function readApproval(rootDir, approvalId, options) {
         stagedContent
       };
       detail.changeSummary = computeChangeSummary(detail.currentContent, detail.stagedContent, detail.changeType);
-      if (options?.diff && detail.currentContent && detail.stagedContent) {
+      const isBinaryAsset = detail.kind === "output";
+      const structured = computeStructuredDiff(detail.currentContent, detail.stagedContent, isBinaryAsset);
+      if (structured) {
+        detail.structuredDiff = structured;
+        const protectedChanges = structured.frontmatterChanges.filter((change) => change.protected);
+        if (protectedChanges.length) {
+          detail.warnings = ["protected_frontmatter_changed"];
+        }
+      }
+      if (options?.diff && detail.currentContent && detail.stagedContent && !isBinaryAsset) {
         detail.diff = computeUnifiedDiff(detail.currentContent, detail.stagedContent, detail.nextPath ?? detail.pageId);
       }
       return detail;
@@ -21167,6 +21424,86 @@ async function promoteCandidate(rootDir, target) {
     updatedAt: nextPage.updatedAt
   };
 }
+function resolvePromotionConfig(config) {
+  const overrides = config.candidate?.autoPromote ?? {};
+  return { ...DEFAULT_PROMOTION_CONFIG, ...overrides };
+}
+function promotionSessionTitle(promotionConfig) {
+  return promotionConfig.dryRun ? "auto-promote-dry-run" : "auto-promote";
+}
+async function runAutoPromotion(rootDir, options = {}) {
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const { config, paths } = await loadVaultConfig(rootDir);
+  const base = resolvePromotionConfig(config);
+  const promotionConfig = { ...base, dryRun: options.dryRun ?? base.dryRun };
+  const graph = await readJsonFile(paths.graphPath);
+  const compileState = await readJsonFile(paths.compileStatePath) ?? emptyCompileState();
+  const candidates = (graph?.pages ?? []).filter(
+    (page) => page.status === "candidate" && (page.kind === "concept" || page.kind === "entity")
+  );
+  const now = Date.now();
+  const decisions = candidates.map(
+    (page) => evaluateCandidateForPromotion(page, graph, compileState.candidateHistory, promotionConfig, now)
+  );
+  const sorted = sortDecisionsForPromotion(decisions);
+  const acceptedIds = sorted.filter((decision) => decision.promote).slice(0, promotionConfig.maxPerRun).map((d) => d.pageId);
+  const skippedIds = sorted.filter((decision) => !acceptedIds.includes(decision.pageId)).map((d) => d.pageId);
+  const promotedPageIds = [];
+  if (!promotionConfig.dryRun) {
+    for (const pageId of acceptedIds) {
+      try {
+        await promoteCandidate(rootDir, pageId);
+        promotedPageIds.push(pageId);
+      } catch {
+      }
+    }
+  }
+  const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const sessionBody = renderPromotionSessionMarkdown(decisions, promotedPageIds, {
+    dryRun: promotionConfig.dryRun,
+    startedAt,
+    finishedAt
+  });
+  const { sessionPath } = await recordSession(rootDir, {
+    operation: "candidate",
+    title: promotionSessionTitle(promotionConfig),
+    startedAt,
+    finishedAt,
+    success: true,
+    relatedPageIds: decisions.map((decision) => decision.pageId),
+    changedPages: promotedPageIds,
+    lines: [
+      `mode=${promotionConfig.dryRun ? "dry-run" : "applied"}`,
+      `evaluated=${decisions.length}`,
+      `promoted=${promotedPageIds.length}`,
+      ...sessionBody.split("\n")
+    ]
+  });
+  return {
+    startedAt,
+    finishedAt,
+    dryRun: promotionConfig.dryRun,
+    promotedPageIds,
+    skippedPageIds: skippedIds,
+    decisions: sorted,
+    sessionPath
+  };
+}
+async function previewCandidatePromotions(rootDir) {
+  const { config, paths } = await loadVaultConfig(rootDir);
+  const promotionConfig = resolvePromotionConfig(config);
+  const graph = await readJsonFile(paths.graphPath);
+  const compileState = await readJsonFile(paths.compileStatePath) ?? emptyCompileState();
+  const candidates = (graph?.pages ?? []).filter(
+    (page) => page.status === "candidate" && (page.kind === "concept" || page.kind === "entity")
+  );
+  const now = Date.now();
+  return sortDecisionsForPromotion(
+    candidates.map(
+      (page) => evaluateCandidateForPromotion(page, graph, compileState.candidateHistory, promotionConfig, now)
+    )
+  );
+}
 async function archiveCandidate(rootDir, target) {
   const startedAt = (/* @__PURE__ */ new Date()).toISOString();
   const { paths } = await loadVaultConfig(rootDir);
@@ -21713,6 +22050,19 @@ async function compileVault(rootDir, options = {}) {
       pagesDropped: budgetResult.dropped.length
     };
   }
+  let autoPromotionSummary;
+  const promotionConfig = resolvePromotionConfig(config);
+  const promotedFromAuto = [];
+  if (promotionConfig.enabled && !options.approve) {
+    const autoRun = await runAutoPromotion(rootDir, { dryRun: promotionConfig.dryRun });
+    autoPromotionSummary = {
+      evaluated: autoRun.decisions.length,
+      promoted: autoRun.promotedPageIds.length,
+      dryRun: autoRun.dryRun,
+      sessionPath: autoRun.sessionPath
+    };
+    promotedFromAuto.push(...autoRun.promotedPageIds);
+  }
   return {
     graphPath: paths.graphPath,
     pageCount: sync.allPages.length,
@@ -21723,8 +22073,9 @@ async function compileVault(rootDir, options = {}) {
     approvalDir: sync.approvalDir,
     postPassApprovalId,
     postPassApprovalDir,
-    promotedPageIds: sync.promotedPageIds,
+    promotedPageIds: [...sync.promotedPageIds, ...promotedFromAuto],
     candidatePageCount: sync.candidatePageCount,
+    autoPromotion: autoPromotionSummary,
     tokenStats
   };
 }
@@ -22475,128 +22826,619 @@ async function bootstrapDemo(rootDir, input) {
   };
 }
 
-// src/mcp.ts
-var SERVER_VERSION = "0.7.30";
-async function createMcpServer(rootDir) {
-  const server = new McpServer({
-    name: "swarmvault",
-    version: SERVER_VERSION,
-    websiteUrl: "https://www.swarmvault.ai"
-  });
-  server.registerTool(
-    "workspace_info",
-    {
-      description: "Return the current SwarmVault workspace paths and high-level counts."
-    },
-    safeHandler(async () => {
-      const info = await getWorkspaceInfo(rootDir);
-      return asToolText(info);
-    })
-  );
-  server.registerTool(
-    "search_pages",
-    {
-      description: "Search compiled wiki pages using the local full-text index.",
-      inputSchema: {
-        query: z8.string().min(1).describe("Search query"),
-        limit: z8.number().int().min(1).max(25).optional().describe("Maximum number of results")
-      }
-    },
-    safeHandler(async ({ query, limit }) => {
-      const results = await searchVault(rootDir, query, limit ?? 5);
-      return asToolText(results);
-    })
-  );
-  server.registerTool(
-    "read_page",
-    {
-      description: "Read a generated wiki page by its path relative to wiki/.",
-      inputSchema: {
-        path: z8.string().min(1).describe("Path relative to wiki/, for example sources/example.md")
-      }
-    },
-    safeHandler(async ({ path: relativePath }) => {
-      const page = await readPage(rootDir, relativePath);
-      if (!page) {
-        return asToolError(`Page not found: ${relativePath}`);
-      }
-      return asToolText(page);
-    })
-  );
-  server.registerTool(
-    "list_sources",
-    {
-      description: "List source manifests in the current workspace.",
-      inputSchema: {
-        limit: z8.number().int().min(1).max(100).optional().describe("Maximum number of manifests to return")
-      }
-    },
-    safeHandler(async ({ limit }) => {
-      const manifests = await listManifests(rootDir);
-      return asToolText(limit ? manifests.slice(0, limit) : manifests);
-    })
-  );
-  server.registerTool(
-    "query_graph",
-    {
-      description: "Traverse the local graph from search seeds without calling a model provider.",
-      inputSchema: {
-        question: z8.string().min(1).describe("Question or graph search seed"),
-        traversal: z8.enum(["bfs", "dfs"]).optional().describe("Traversal strategy"),
-        budget: z8.number().int().min(3).max(50).optional().describe("Maximum nodes to summarize")
-      }
-    },
-    safeHandler(async ({ question, traversal, budget }) => {
-      const result = await queryGraphVault(rootDir, question, {
-        traversal,
-        budget
-      });
-      return asToolText(result);
-    })
-  );
-  server.registerTool(
-    "graph_report",
-    {
-      description: "Return the machine-readable graph report and trust artifact."
-    },
-    safeHandler(async () => {
-      return asToolText(await readGraphReport(rootDir) ?? { error: "Graph report not found. Run `swarmvault compile` first." });
-    })
-  );
-  server.registerTool(
-    "get_node",
-    {
-      description: "Explain a graph node, its page, community, neighbors, and group patterns.",
-      inputSchema: {
-        target: z8.string().min(1).describe("Node or page label/id")
-      }
-    },
-    safeHandler(async ({ target }) => {
-      return asToolText(await explainGraphVault(rootDir, target));
-    })
-  );
-  server.registerTool(
-    "get_hyperedges",
-    {
-      description: "List graph hyperedges, optionally filtered to a node or page target.",
-      inputSchema: {
-        target: z8.string().optional().describe("Optional node/page label or id to filter by"),
-        limit: z8.number().int().min(1).max(50).optional().describe("Maximum hyperedges to return")
-      }
-    },
-    safeHandler(async ({ target, limit }) => {
-      return asToolText(await listGraphHyperedges(rootDir, target, limit ?? 25));
-    })
-  );
-  server.registerTool(
-    "get_neighbors",
-    {
-      description: "Return the neighbors of a graph node or page target.",
-      inputSchema: {
-        target: z8.string().min(1).describe("Node or page label/id")
-      }
-    },
-    safeHandler(async ({ target }) => {
+// src/watch.ts
+import path24 from "path";
+import process3 from "process";
+import chokidar from "chokidar";
+var MAX_BACKOFF_MS = 3e4;
+var BACKOFF_THRESHOLD = 3;
+var CRITICAL_THRESHOLD = 10;
+var REPO_WATCH_IGNORES = /* @__PURE__ */ new Set([".git", ".venv"]);
+var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+  ".rs",
+  ".java",
+  ".kt",
+  ".kts",
+  ".scala",
+  ".sc",
+  ".dart",
+  ".lua",
+  ".zig",
+  ".cs",
+  ".php",
+  ".rb",
+  ".swift",
+  ".c",
+  ".h",
+  ".cpp",
+  ".cc",
+  ".cxx",
+  ".hpp",
+  ".hxx",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".ps1",
+  ".psm1",
+  ".ex",
+  ".exs",
+  ".jl",
+  ".r",
+  ".R"
+]);
+var FILE_CHANGE_RE = /^(?:add|change|unlink):(.+)$/;
+function isCodeOnlyChange(reasons) {
+  for (const reason of reasons) {
+    const match = reason.match(FILE_CHANGE_RE);
+    if (!match) return false;
+    const ext = path24.extname(match[1]).toLowerCase();
+    if (!ext || !CODE_EXTENSIONS.has(ext)) return false;
+  }
+  return reasons.size > 0;
+}
+function hasNonCodeChanges(reasons) {
+  for (const reason of reasons) {
+    const match = reason.match(FILE_CHANGE_RE);
+    if (!match) return true;
+    const ext = path24.extname(match[1]).toLowerCase();
+    if (!ext || !CODE_EXTENSIONS.has(ext)) return true;
+  }
+  return false;
+}
+function collectNonCodePaths(reasons) {
+  const result = [];
+  for (const reason of reasons) {
+    const match = reason.match(FILE_CHANGE_RE);
+    if (!match) {
+      result.push(reason);
+      continue;
+    }
+    const ext = path24.extname(match[1]).toLowerCase();
+    if (!ext || !CODE_EXTENSIONS.has(ext)) result.push(match[1]);
+  }
+  return result;
+}
+function hasIgnoredRepoSegment(baseDir, targetPath) {
+  const relativePath = path24.relative(baseDir, targetPath);
+  if (!relativePath || relativePath.startsWith("..")) {
+    return false;
+  }
+  return relativePath.split(path24.sep).some((segment) => REPO_WATCH_IGNORES.has(segment));
+}
+function workspaceIgnoreRoots(rootDir, paths) {
+  return [
+    paths.rawDir,
+    paths.wikiDir,
+    paths.stateDir,
+    paths.agentDir,
+    paths.inboxDir,
+    path24.join(rootDir, ".claude"),
+    path24.join(rootDir, ".cursor"),
+    path24.join(rootDir, ".obsidian")
+  ].map((candidate) => path24.resolve(candidate));
+}
+async function resolveWatchTargets(rootDir, paths, options) {
+  const targets = /* @__PURE__ */ new Set([path24.resolve(paths.inboxDir)]);
+  if (options.repo) {
+    for (const repoRoot of await listTrackedRepoRoots(rootDir)) {
+      targets.add(path24.resolve(repoRoot));
+    }
+  }
+  return [...targets].sort((left, right) => left.localeCompare(right));
+}
+async function performWatchCycle(rootDir, paths, options, codeOnly = false) {
+  const imported = await importInbox(rootDir, paths.inboxDir);
+  const repoSync = options.repo ? await syncTrackedReposForWatch(rootDir) : null;
+  const compile = await compileVault(rootDir, { codeOnly });
+  const pendingSemanticRefresh = repoSync ? await mergePendingSemanticRefresh(rootDir, repoSync.pendingSemanticRefresh) : await readPendingSemanticRefresh(rootDir);
+  const stalePagePaths = await markPagesStaleForSources(
+    rootDir,
+    pendingSemanticRefresh.map((entry) => entry.sourceId).filter((sourceId) => Boolean(sourceId))
+  );
+  const lintFindingCount = options.lint ? (await lintVault(rootDir)).length : void 0;
+  return {
+    watchedRepoRoots: repoSync?.repoRoots ?? [],
+    importedCount: imported.imported.length,
+    scannedCount: imported.scannedCount,
+    attachmentCount: imported.attachmentCount,
+    repoImportedCount: repoSync?.imported.length ?? 0,
+    repoUpdatedCount: repoSync?.updated.length ?? 0,
+    repoRemovedCount: repoSync?.removed.length ?? 0,
+    repoScannedCount: repoSync?.scannedCount ?? 0,
+    pendingSemanticRefreshCount: pendingSemanticRefresh.length,
+    pendingSemanticRefreshPaths: pendingSemanticRefresh.map((entry) => entry.path),
+    changedPages: [.../* @__PURE__ */ new Set([...compile.changedPages, ...stalePagePaths])],
+    lintFindingCount
+  };
+}
+async function runWatchCycle(rootDir, options = {}) {
+  const { paths } = await initWorkspace(rootDir);
+  const startedAt = /* @__PURE__ */ new Date();
+  let success = true;
+  let error;
+  let result = {
+    watchedRepoRoots: [],
+    importedCount: 0,
+    scannedCount: 0,
+    attachmentCount: 0,
+    repoImportedCount: 0,
+    repoUpdatedCount: 0,
+    repoRemovedCount: 0,
+    repoScannedCount: 0,
+    pendingSemanticRefreshCount: 0,
+    pendingSemanticRefreshPaths: [],
+    changedPages: []
+  };
+  try {
+    result = await performWatchCycle(rootDir, paths, options, options.codeOnly ?? false);
+    return result;
+  } catch (caught) {
+    success = false;
+    error = caught instanceof Error ? caught.message : String(caught);
+    throw caught;
+  } finally {
+    const finishedAt = /* @__PURE__ */ new Date();
+    await recordSession(rootDir, {
+      operation: "watch",
+      title: `Watch cycle for ${paths.inboxDir}${options.repo ? " and tracked repos" : ""}`,
+      startedAt: startedAt.toISOString(),
+      finishedAt: finishedAt.toISOString(),
+      success,
+      error,
+      changedPages: result.changedPages,
+      lintFindingCount: result.lintFindingCount,
+      lines: [
+        "reasons=once",
+        `imported=${result.importedCount}`,
+        `scanned=${result.scannedCount}`,
+        `attachments=${result.attachmentCount}`,
+        `repo_scanned=${result.repoScannedCount}`,
+        `repo_imported=${result.repoImportedCount}`,
+        `repo_updated=${result.repoUpdatedCount}`,
+        `repo_removed=${result.repoRemovedCount}`,
+        `pending_semantic_refresh=${result.pendingSemanticRefreshCount}`,
+        `lint=${result.lintFindingCount ?? 0}`
+      ]
+    });
+    await appendWatchRun(rootDir, {
+      startedAt: startedAt.toISOString(),
+      finishedAt: finishedAt.toISOString(),
+      durationMs: finishedAt.getTime() - startedAt.getTime(),
+      inputDir: paths.inboxDir,
+      reasons: ["once"],
+      importedCount: result.importedCount + result.repoImportedCount + result.repoUpdatedCount,
+      scannedCount: result.scannedCount + result.repoScannedCount,
+      attachmentCount: result.attachmentCount,
+      changedPages: result.changedPages,
+      repoImportedCount: result.repoImportedCount,
+      repoUpdatedCount: result.repoUpdatedCount,
+      repoRemovedCount: result.repoRemovedCount,
+      repoScannedCount: result.repoScannedCount,
+      pendingSemanticRefreshCount: result.pendingSemanticRefreshCount,
+      pendingSemanticRefreshPaths: result.pendingSemanticRefreshPaths,
+      lintFindingCount: result.lintFindingCount,
+      success,
+      error
+    });
+    await writeWatchStatusArtifact(rootDir, {
+      generatedAt: finishedAt.toISOString(),
+      watchedRepoRoots: result.watchedRepoRoots,
+      lastRun: {
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        inputDir: paths.inboxDir,
+        reasons: ["once"],
+        importedCount: result.importedCount + result.repoImportedCount + result.repoUpdatedCount,
+        scannedCount: result.scannedCount + result.repoScannedCount,
+        attachmentCount: result.attachmentCount,
+        changedPages: result.changedPages,
+        repoImportedCount: result.repoImportedCount,
+        repoUpdatedCount: result.repoUpdatedCount,
+        repoRemovedCount: result.repoRemovedCount,
+        repoScannedCount: result.repoScannedCount,
+        pendingSemanticRefreshCount: result.pendingSemanticRefreshCount,
+        pendingSemanticRefreshPaths: result.pendingSemanticRefreshPaths,
+        lintFindingCount: result.lintFindingCount,
+        success,
+        error
+      },
+      pendingSemanticRefresh: await readPendingSemanticRefresh(rootDir)
+    });
+  }
+}
+async function watchVault(rootDir, options = {}) {
+  const { paths } = await initWorkspace(rootDir);
+  const baseDebounceMs = options.debounceMs ?? 900;
+  const ignoredRoots = workspaceIgnoreRoots(rootDir, paths);
+  const inboxWatchRoot = path24.resolve(paths.inboxDir);
+  let watchTargets = await resolveWatchTargets(rootDir, paths, options);
+  let timer;
+  let running = false;
+  let pending = false;
+  let closed = false;
+  let consecutiveFailures = 0;
+  let currentDebounceMs = baseDebounceMs;
+  const reasons = /* @__PURE__ */ new Set();
+  let activeCycle = null;
+  const watcher = chokidar.watch(watchTargets, {
+    ignoreInitial: true,
+    usePolling: true,
+    interval: 100,
+    ignored: (targetPath) => {
+      const absolutePath = path24.resolve(targetPath);
+      const primaryTarget = watchTargets.filter((watchTarget) => isPathWithin(watchTarget, absolutePath)).sort((left, right) => right.length - left.length)[0] ?? null;
+      if (!primaryTarget) {
+        return false;
+      }
+      if (primaryTarget !== inboxWatchRoot && ignoredRoots.some((ignoreRoot) => isPathWithin(ignoreRoot, absolutePath))) {
+        return true;
+      }
+      return hasIgnoredRepoSegment(primaryTarget, absolutePath);
+    },
+    awaitWriteFinish: {
+      stabilityThreshold: Math.max(250, Math.floor(baseDebounceMs / 2)),
+      pollInterval: 100
+    }
+  });
+  const syncWatchTargets = async () => {
+    const nextTargets = await resolveWatchTargets(rootDir, paths, options);
+    const nextSet = new Set(nextTargets);
+    const currentSet = new Set(watchTargets);
+    const toRemove = watchTargets.filter((target) => !nextSet.has(target));
+    const toAdd = nextTargets.filter((target) => !currentSet.has(target));
+    if (toRemove.length > 0) {
+      await watcher.unwatch(toRemove);
+    }
+    if (toAdd.length > 0) {
+      await watcher.add(toAdd);
+    }
+    watchTargets = nextTargets;
+  };
+  const schedule = (reason) => {
+    if (closed) {
+      return;
+    }
+    reasons.add(reason);
+    pending = true;
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      const cycle = runCycle();
+      activeCycle = cycle.finally(() => {
+        if (activeCycle === cycle) {
+          activeCycle = null;
+        }
+      });
+    }, currentDebounceMs);
+  };
+  const runCycle = async () => {
+    if (running || closed || !pending) {
+      return;
+    }
+    pending = false;
+    running = true;
+    const startedAt = /* @__PURE__ */ new Date();
+    const detectedCodeOnly = isCodeOnlyChange(reasons);
+    const hasDeferredNonCode = !detectedCodeOnly && hasNonCodeChanges(reasons);
+    const codeOnlyChange = options.codeOnly || detectedCodeOnly || hasDeferredNonCode;
+    const runReasons = [...reasons];
+    reasons.clear();
+    if (hasDeferredNonCode) {
+      const nonCodePaths = collectNonCodePaths(new Set(runReasons));
+      process3.stderr.write(
+        `[swarmvault watch] Non-code changes detected (${nonCodePaths.length} file(s)) \u2014 run \`swarmvault compile\` to include LLM re-analysis.
+`
+      );
+    } else if (codeOnlyChange) {
+      process3.stderr.write("[swarmvault watch] Code-only changes detected \u2014 skipping LLM re-analysis.\n");
+    }
+    let importedCount = 0;
+    let scannedCount = 0;
+    let attachmentCount = 0;
+    let repoImportedCount = 0;
+    let repoUpdatedCount = 0;
+    let repoRemovedCount = 0;
+    let repoScannedCount = 0;
+    let watchedRepoRoots = [];
+    let pendingSemanticRefreshCount = 0;
+    let pendingSemanticRefreshPaths = [];
+    let changedPages = [];
+    let lintFindingCount;
+    let success = true;
+    let error;
+    try {
+      const result = await performWatchCycle(rootDir, paths, options, codeOnlyChange);
+      importedCount = result.importedCount;
+      scannedCount = result.scannedCount;
+      attachmentCount = result.attachmentCount;
+      repoImportedCount = result.repoImportedCount;
+      repoUpdatedCount = result.repoUpdatedCount;
+      repoRemovedCount = result.repoRemovedCount;
+      repoScannedCount = result.repoScannedCount;
+      watchedRepoRoots = result.watchedRepoRoots;
+      pendingSemanticRefreshCount = result.pendingSemanticRefreshCount;
+      pendingSemanticRefreshPaths = result.pendingSemanticRefreshPaths;
+      changedPages = result.changedPages;
+      lintFindingCount = result.lintFindingCount;
+      consecutiveFailures = 0;
+      currentDebounceMs = baseDebounceMs;
+      await syncWatchTargets();
+    } catch (caught) {
+      success = false;
+      error = caught instanceof Error ? caught.message : String(caught);
+      consecutiveFailures++;
+      pending = true;
+      if (consecutiveFailures >= CRITICAL_THRESHOLD) {
+        process3.stderr.write(
+          `[swarmvault watch] ${consecutiveFailures} consecutive failures. Check vault state. Continuing at max backoff.
+`
+        );
+      }
+      if (consecutiveFailures >= BACKOFF_THRESHOLD) {
+        const multiplier = 2 ** (consecutiveFailures - BACKOFF_THRESHOLD);
+        currentDebounceMs = Math.min(baseDebounceMs * multiplier, MAX_BACKOFF_MS);
+      }
+    } finally {
+      const finishedAt = /* @__PURE__ */ new Date();
+      try {
+        await recordSession(rootDir, {
+          operation: "watch",
+          title: `Watch cycle for ${paths.inboxDir}${options.repo ? " and tracked repos" : ""}`,
+          startedAt: startedAt.toISOString(),
+          finishedAt: finishedAt.toISOString(),
+          success,
+          error,
+          changedPages,
+          lintFindingCount,
+          lines: [
+            `reasons=${runReasons.join(",") || "none"}`,
+            `code_only=${codeOnlyChange}`,
+            `imported=${importedCount}`,
+            `scanned=${scannedCount}`,
+            `attachments=${attachmentCount}`,
+            `repo_scanned=${repoScannedCount}`,
+            `repo_imported=${repoImportedCount}`,
+            `repo_updated=${repoUpdatedCount}`,
+            `repo_removed=${repoRemovedCount}`,
+            `lint=${lintFindingCount ?? 0}`
+          ]
+        });
+      } catch {
+        process3.stderr.write("[swarmvault watch] Failed to record session log.\n");
+      }
+      try {
+        await appendWatchRun(rootDir, {
+          startedAt: startedAt.toISOString(),
+          finishedAt: finishedAt.toISOString(),
+          durationMs: finishedAt.getTime() - startedAt.getTime(),
+          inputDir: paths.inboxDir,
+          reasons: runReasons,
+          importedCount: importedCount + repoImportedCount + repoUpdatedCount,
+          scannedCount: scannedCount + repoScannedCount,
+          attachmentCount,
+          changedPages,
+          repoImportedCount,
+          repoUpdatedCount,
+          repoRemovedCount,
+          repoScannedCount,
+          pendingSemanticRefreshCount,
+          pendingSemanticRefreshPaths,
+          lintFindingCount,
+          success,
+          error
+        });
+      } catch {
+        process3.stderr.write("[swarmvault watch] Failed to append watch run.\n");
+      }
+      try {
+        await writeWatchStatusArtifact(rootDir, {
+          generatedAt: finishedAt.toISOString(),
+          watchedRepoRoots,
+          lastRun: {
+            startedAt: startedAt.toISOString(),
+            finishedAt: finishedAt.toISOString(),
+            durationMs: finishedAt.getTime() - startedAt.getTime(),
+            inputDir: paths.inboxDir,
+            reasons: runReasons,
+            importedCount: importedCount + repoImportedCount + repoUpdatedCount,
+            scannedCount: scannedCount + repoScannedCount,
+            attachmentCount,
+            changedPages,
+            repoImportedCount,
+            repoUpdatedCount,
+            repoRemovedCount,
+            repoScannedCount,
+            pendingSemanticRefreshCount,
+            pendingSemanticRefreshPaths,
+            lintFindingCount,
+            success,
+            error
+          },
+          pendingSemanticRefresh: await readPendingSemanticRefresh(rootDir)
+        });
+      } catch {
+        process3.stderr.write("[swarmvault watch] Failed to write watch status artifact.\n");
+      }
+      running = false;
+      if (pending && !closed) {
+        schedule("queued");
+      }
+    }
+  };
+  const reasonForPath = (targetPath) => {
+    const baseDir = watchTargets.filter((watchTarget) => isPathWithin(watchTarget, path24.resolve(targetPath))).sort((left, right) => right.length - left.length)[0] ?? paths.inboxDir;
+    return path24.relative(baseDir, targetPath) || ".";
+  };
+  watcher.on("add", (filePath) => schedule(`add:${reasonForPath(filePath)}`)).on("change", (filePath) => schedule(`change:${reasonForPath(filePath)}`)).on("unlink", (filePath) => schedule(`unlink:${reasonForPath(filePath)}`)).on("addDir", (dirPath) => schedule(`addDir:${reasonForPath(dirPath)}`)).on("unlinkDir", (dirPath) => schedule(`unlinkDir:${reasonForPath(dirPath)}`)).on("error", (caught) => schedule(`error:${caught instanceof Error ? caught.message : String(caught)}`));
+  await new Promise((resolve, reject) => {
+    const handleReady = () => {
+      watcher.off("error", handleError);
+      resolve();
+    };
+    const handleError = (caught) => {
+      watcher.off("ready", handleReady);
+      reject(caught);
+    };
+    watcher.once("ready", handleReady);
+    watcher.once("error", handleError);
+  });
+  return {
+    close: async () => {
+      closed = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      await watcher.close();
+      await activeCycle;
+    }
+  };
+}
+async function getWatchStatus(rootDir) {
+  const persisted = await readWatchStatusArtifact(rootDir);
+  const watchedRepoRoots = await listTrackedRepoRoots(rootDir);
+  const pendingSemanticRefresh = await readPendingSemanticRefresh(rootDir);
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    watchedRepoRoots,
+    lastRun: persisted?.lastRun,
+    pendingSemanticRefresh
+  };
+}
+
+// src/mcp.ts
+var SERVER_VERSION = "0.7.31";
+async function createMcpServer(rootDir) {
+  const server = new McpServer({
+    name: "swarmvault",
+    version: SERVER_VERSION,
+    websiteUrl: "https://www.swarmvault.ai"
+  });
+  server.registerTool(
+    "workspace_info",
+    {
+      description: "Return the current SwarmVault workspace paths and high-level counts."
+    },
+    safeHandler(async () => {
+      const info = await getWorkspaceInfo(rootDir);
+      return asToolText(info);
+    })
+  );
+  server.registerTool(
+    "search_pages",
+    {
+      description: "Search compiled wiki pages using the local full-text index.",
+      inputSchema: {
+        query: z8.string().min(1).describe("Search query"),
+        limit: z8.number().int().min(1).max(25).optional().describe("Maximum number of results")
+      }
+    },
+    safeHandler(async ({ query, limit }) => {
+      const results = await searchVault(rootDir, query, limit ?? 5);
+      return asToolText(results);
+    })
+  );
+  server.registerTool(
+    "read_page",
+    {
+      description: "Read a generated wiki page by its path relative to wiki/.",
+      inputSchema: {
+        path: z8.string().min(1).describe("Path relative to wiki/, for example sources/example.md")
+      }
+    },
+    safeHandler(async ({ path: relativePath }) => {
+      const page = await readPage(rootDir, relativePath);
+      if (!page) {
+        return asToolError(`Page not found: ${relativePath}`);
+      }
+      return asToolText(page);
+    })
+  );
+  server.registerTool(
+    "list_sources",
+    {
+      description: "List source manifests in the current workspace.",
+      inputSchema: {
+        limit: z8.number().int().min(1).max(100).optional().describe("Maximum number of manifests to return")
+      }
+    },
+    safeHandler(async ({ limit }) => {
+      const manifests = await listManifests(rootDir);
+      return asToolText(limit ? manifests.slice(0, limit) : manifests);
+    })
+  );
+  server.registerTool(
+    "query_graph",
+    {
+      description: "Traverse the local graph from search seeds without calling a model provider.",
+      inputSchema: {
+        question: z8.string().min(1).describe("Question or graph search seed"),
+        traversal: z8.enum(["bfs", "dfs"]).optional().describe("Traversal strategy"),
+        budget: z8.number().int().min(3).max(50).optional().describe("Maximum nodes to summarize")
+      }
+    },
+    safeHandler(async ({ question, traversal, budget }) => {
+      const result = await queryGraphVault(rootDir, question, {
+        traversal,
+        budget
+      });
+      return asToolText(result);
+    })
+  );
+  server.registerTool(
+    "graph_report",
+    {
+      description: "Return the machine-readable graph report and trust artifact."
+    },
+    safeHandler(async () => {
+      return asToolText(await readGraphReport(rootDir) ?? { error: "Graph report not found. Run `swarmvault compile` first." });
+    })
+  );
+  server.registerTool(
+    "get_node",
+    {
+      description: "Explain a graph node, its page, community, neighbors, and group patterns.",
+      inputSchema: {
+        target: z8.string().min(1).describe("Node or page label/id")
+      }
+    },
+    safeHandler(async ({ target }) => {
+      return asToolText(await explainGraphVault(rootDir, target));
+    })
+  );
+  server.registerTool(
+    "get_hyperedges",
+    {
+      description: "List graph hyperedges, optionally filtered to a node or page target.",
+      inputSchema: {
+        target: z8.string().optional().describe("Optional node/page label or id to filter by"),
+        limit: z8.number().int().min(1).max(50).optional().describe("Maximum hyperedges to return")
+      }
+    },
+    safeHandler(async ({ target, limit }) => {
+      return asToolText(await listGraphHyperedges(rootDir, target, limit ?? 25));
+    })
+  );
+  server.registerTool(
+    "get_neighbors",
+    {
+      description: "Return the neighbors of a graph node or page target.",
+      inputSchema: {
+        target: z8.string().min(1).describe("Node or page label/id")
+      }
+    },
+    safeHandler(async ({ target }) => {
       const explanation = await explainGraphVault(rootDir, target);
       return asToolText(explanation.neighbors);
     })
@@ -22695,6 +23537,106 @@ async function createMcpServer(rootDir) {
       return asToolText(findings);
     })
   );
+  server.registerTool(
+    "list_approvals",
+    {
+      description: "List staged approval bundles awaiting review."
+    },
+    safeHandler(async () => {
+      const approvals = await listApprovals(rootDir);
+      return asToolText(approvals);
+    })
+  );
+  server.registerTool(
+    "read_approval",
+    {
+      description: "Read the details and structured diffs for an approval bundle.",
+      inputSchema: {
+        approvalId: z8.string().min(1).describe("Approval bundle id"),
+        diff: z8.boolean().optional().describe("Include the textual unified diff alongside the structured diff")
+      }
+    },
+    safeHandler(async ({ approvalId, diff }) => {
+      const result = await readApproval(rootDir, approvalId, { diff: diff ?? true });
+      return asToolText(result);
+    })
+  );
+  server.registerTool(
+    "promote_candidate",
+    {
+      description: "Promote a staged candidate into its active concept or entity page.",
+      inputSchema: {
+        target: z8.string().min(1).describe("Candidate page id or wiki/candidates path")
+      }
+    },
+    safeHandler(async ({ target }) => {
+      const result = await promoteCandidate(rootDir, target);
+      return asToolText(result);
+    })
+  );
+  server.registerTool(
+    "archive_candidate",
+    {
+      description: "Archive a staged candidate without promoting it.",
+      inputSchema: {
+        target: z8.string().min(1).describe("Candidate page id or wiki/candidates path")
+      }
+    },
+    safeHandler(async ({ target }) => {
+      const result = await archiveCandidate(rootDir, target);
+      return asToolText(result);
+    })
+  );
+  server.registerTool(
+    "preview_candidate_scores",
+    {
+      description: "Score staged candidates against the configured auto-promotion rules without promoting."
+    },
+    safeHandler(async () => {
+      const decisions = await previewCandidatePromotions(rootDir);
+      return asToolText(decisions);
+    })
+  );
+  server.registerTool(
+    "auto_promote_candidates",
+    {
+      description: "Apply configured auto-promotion rules to staged candidates. Requires candidate.autoPromote.enabled in config.",
+      inputSchema: {
+        dryRun: z8.boolean().optional().describe("Score candidates without moving files")
+      }
+    },
+    safeHandler(async ({ dryRun }) => {
+      const result = await runAutoPromotion(rootDir, { dryRun: dryRun ?? false });
+      return asToolText(result);
+    })
+  );
+  server.registerTool(
+    "review_decision",
+    {
+      description: "Accept or reject approval bundle entries from a staged compile.",
+      inputSchema: {
+        approvalId: z8.string().min(1).describe("Approval bundle id as reported by list_approvals or read_approval"),
+        decision: z8.enum(["accept", "reject"]).describe("Action to apply to the selected entries"),
+        targets: z8.array(z8.string()).optional().describe("Specific entry page ids to act on (defaults to all pending)"),
+        notes: z8.string().optional().describe("Free-form reviewer notes, surfaced in the session log")
+      }
+    },
+    safeHandler(async ({ approvalId, decision, targets, notes }) => {
+      const apply = decision === "accept" ? acceptApproval : rejectApproval;
+      const result = await apply(rootDir, approvalId, targets ?? []);
+      return asToolText({ ...result, notes });
+    })
+  );
+  server.registerTool(
+    "watch_status",
+    {
+      description: "Return the current watch-mode status: watched repos, last run summary, and pending semantic refreshes."
+    },
+    safeHandler(async () => {
+      const status = await getWatchStatus(rootDir);
+      return asToolText(status);
+    })
+  );
   server.registerResource(
     "swarmvault-config",
     "swarmvault://config",
@@ -22761,7 +23703,7 @@ async function createMcpServer(rootDir) {
     },
     async () => {
       const { paths } = await loadVaultConfig(rootDir);
-      const files = (await listFilesRecursive(paths.sessionsDir)).filter((filePath) => filePath.endsWith(".md")).map((filePath) => toPosix(path24.relative(paths.sessionsDir, filePath))).sort();
+      const files = (await listFilesRecursive(paths.sessionsDir)).filter((filePath) => filePath.endsWith(".md")).map((filePath) => toPosix(path25.relative(paths.sessionsDir, filePath))).sort();
       return asTextResource("swarmvault://sessions", JSON.stringify(files, null, 2));
     }
   );
@@ -22794,7 +23736,7 @@ async function createMcpServer(rootDir) {
         return asTextResource(`swarmvault://pages/${encodedPath}`, `Page not found: ${relativePath}`);
       }
       const { paths } = await loadVaultConfig(rootDir);
-      const absolutePath = path24.resolve(paths.wikiDir, relativePath);
+      const absolutePath = path25.resolve(paths.wikiDir, relativePath);
       return asTextResource(`swarmvault://pages/${encodedPath}`, await fs20.readFile(absolutePath, "utf8"));
     }
   );
@@ -22803,11 +23745,11 @@ async function createMcpServer(rootDir) {
     new ResourceTemplate("swarmvault://sessions/{path}", {
       list: async () => {
         const { paths } = await loadVaultConfig(rootDir);
-        const files = (await listFilesRecursive(paths.sessionsDir)).filter((filePath) => filePath.endsWith(".md")).map((filePath) => toPosix(path24.relative(paths.sessionsDir, filePath))).sort();
+        const files = (await listFilesRecursive(paths.sessionsDir)).filter((filePath) => filePath.endsWith(".md")).map((filePath) => toPosix(path25.relative(paths.sessionsDir, filePath))).sort();
         return {
           resources: files.map((relativePath) => ({
             uri: `swarmvault://sessions/${encodeURIComponent(relativePath)}`,
-            name: path24.basename(relativePath, ".md"),
+            name: path25.basename(relativePath, ".md"),
             title: relativePath,
             description: "SwarmVault session artifact",
             mimeType: "text/markdown"
@@ -22824,7 +23766,7 @@ async function createMcpServer(rootDir) {
       const { paths } = await loadVaultConfig(rootDir);
       const encodedPath = typeof variables.path === "string" ? variables.path : "";
       const relativePath = decodeURIComponent(encodedPath);
-      const absolutePath = path24.resolve(paths.sessionsDir, relativePath);
+      const absolutePath = path25.resolve(paths.sessionsDir, relativePath);
       if (!isPathWithin(paths.sessionsDir, absolutePath) || !await fileExists(absolutePath)) {
         return asTextResource(`swarmvault://sessions/${encodedPath}`, `Session not found: ${relativePath}`);
       }
@@ -22888,12 +23830,12 @@ function asTextResource(uri, text) {
 
 // src/schedule.ts
 import fs21 from "fs/promises";
-import path25 from "path";
+import path26 from "path";
 function scheduleStatePath(schedulesDir, jobId) {
-  return path25.join(schedulesDir, `${encodeURIComponent(jobId)}.json`);
+  return path26.join(schedulesDir, `${encodeURIComponent(jobId)}.json`);
 }
 function scheduleLockPath(schedulesDir, jobId) {
-  return path25.join(schedulesDir, `${encodeURIComponent(jobId)}.lock`);
+  return path26.join(schedulesDir, `${encodeURIComponent(jobId)}.lock`);
 }
 function parseEveryDuration(value) {
   const match = value.trim().match(/^(\d+)(m|h|d)$/i);
@@ -23160,7 +24102,7 @@ async function serveSchedules(rootDir, pollMs = 3e4) {
 // src/sources.ts
 import { spawn as spawn2 } from "child_process";
 import fs22 from "fs/promises";
-import path26 from "path";
+import path27 from "path";
 import matter11 from "gray-matter";
 import { JSDOM as JSDOM3 } from "jsdom";
 var DEFAULT_CRAWL_MAX_PAGES = 12;
@@ -23206,24 +24148,24 @@ function emptyManagedSourceSyncCounts() {
   };
 }
 function withinRoot2(rootPath, targetPath) {
-  const relative = path26.relative(rootPath, targetPath);
-  return relative === "" || !relative.startsWith("..") && !path26.isAbsolute(relative);
+  const relative = path27.relative(rootPath, targetPath);
+  return relative === "" || !relative.startsWith("..") && !path27.isAbsolute(relative);
 }
 async function findNearestGitRoot3(startPath) {
-  let current = path26.resolve(startPath);
+  let current = path27.resolve(startPath);
   try {
     const stat = await fs22.stat(current);
     if (!stat.isDirectory()) {
-      current = path26.dirname(current);
+      current = path27.dirname(current);
     }
   } catch {
-    current = path26.dirname(current);
+    current = path27.dirname(current);
   }
   while (true) {
-    if (await fileExists(path26.join(current, ".git"))) {
+    if (await fileExists(path27.join(current, ".git"))) {
       return current;
     }
-    const parent = path26.dirname(current);
+    const parent = path27.dirname(current);
     if (parent === current) {
       return null;
     }
@@ -23297,7 +24239,7 @@ function isAllowedDocsCandidate(candidate, startUrl) {
   if (candidate.origin !== startUrl.origin) {
     return false;
   }
-  const extension = path26.extname(candidate.pathname).toLowerCase();
+  const extension = path27.extname(candidate.pathname).toLowerCase();
   if (extension && extension !== ".html" && extension !== ".htm" && extension !== ".md") {
     return false;
   }
@@ -23386,12 +24328,12 @@ function matchesManagedSourceSpec(existing, input) {
     return false;
   }
   if (input.kind === "directory" || input.kind === "file") {
-    return path26.resolve(existing.path ?? "") === path26.resolve(input.path);
+    return path27.resolve(existing.path ?? "") === path27.resolve(input.path);
   }
   return (existing.url ?? "") === input.url;
 }
 async function resolveManagedSourceInput(rootDir, input) {
-  const absoluteInput = path26.resolve(rootDir, input);
+  const absoluteInput = path27.resolve(rootDir, input);
   if (!(input.startsWith("http://") || input.startsWith("https://"))) {
     const stat = await fs22.stat(absoluteInput).catch(() => null);
     if (!stat) {
@@ -23401,7 +24343,7 @@ async function resolveManagedSourceInput(rootDir, input) {
       return {
         kind: "file",
         path: absoluteInput,
-        title: path26.basename(absoluteInput, path26.extname(absoluteInput)) || absoluteInput
+        title: path27.basename(absoluteInput, path27.extname(absoluteInput)) || absoluteInput
       };
     }
     if (!stat.isDirectory()) {
@@ -23413,7 +24355,7 @@ async function resolveManagedSourceInput(rootDir, input) {
       kind: "directory",
       path: absoluteInput,
       repoRoot,
-      title: path26.basename(absoluteInput) || absoluteInput
+      title: path27.basename(absoluteInput) || absoluteInput
     };
   }
   const github = normalizeGitHubRepoRootUrl(input);
@@ -23436,16 +24378,16 @@ async function resolveManagedSourceInput(rootDir, input) {
   };
 }
 function directorySourceIdsFor(manifests, inputPath) {
-  return manifests.filter((manifest) => manifest.originalPath && withinRoot2(path26.resolve(inputPath), path26.resolve(manifest.originalPath))).map((manifest) => manifest.sourceId).sort((left, right) => left.localeCompare(right));
+  return manifests.filter((manifest) => manifest.originalPath && withinRoot2(path27.resolve(inputPath), path27.resolve(manifest.originalPath))).map((manifest) => manifest.sourceId).sort((left, right) => left.localeCompare(right));
 }
 function fileSourceIdsFor(manifests, inputPath) {
-  const absoluteInput = path26.resolve(inputPath);
-  return manifests.filter((manifest) => manifest.originalPath && path26.resolve(manifest.originalPath) === absoluteInput).map((manifest) => manifest.sourceId).sort((left, right) => left.localeCompare(right));
+  const absoluteInput = path27.resolve(inputPath);
+  return manifests.filter((manifest) => manifest.originalPath && path27.resolve(manifest.originalPath) === absoluteInput).map((manifest) => manifest.sourceId).sort((left, right) => left.localeCompare(right));
 }
 async function syncDirectorySource(rootDir, inputPath, repoRoot) {
   const manifestsBefore = await listManifests(rootDir);
   const previousInScope = manifestsBefore.filter(
-    (manifest) => manifest.originalPath && withinRoot2(path26.resolve(inputPath), path26.resolve(manifest.originalPath))
+    (manifest) => manifest.originalPath && withinRoot2(path27.resolve(inputPath), path27.resolve(manifest.originalPath))
   );
   const result = await ingestDirectory(rootDir, inputPath, { repoRoot });
   const removed = [];
@@ -23453,7 +24395,7 @@ async function syncDirectorySource(rootDir, inputPath, repoRoot) {
     if (!manifest.originalPath) {
       continue;
     }
-    if (await fileExists(path26.resolve(manifest.originalPath))) {
+    if (await fileExists(path27.resolve(manifest.originalPath))) {
       continue;
     }
     const removedManifest = await removeManifestBySourceId(rootDir, manifest.sourceId);
@@ -23463,7 +24405,7 @@ async function syncDirectorySource(rootDir, inputPath, repoRoot) {
   }
   const manifestsAfter = await listManifests(rootDir);
   return {
-    title: path26.basename(inputPath) || inputPath,
+    title: path27.basename(inputPath) || inputPath,
     sourceIds: directorySourceIdsFor(manifestsAfter, inputPath),
     counts: {
       scannedCount: result.scannedCount,
@@ -23479,7 +24421,7 @@ async function syncFileSource(rootDir, inputPath) {
   const result = await ingestInputDetailed(rootDir, inputPath);
   const manifestsAfter = await listManifests(rootDir);
   return {
-    title: path26.basename(inputPath, path26.extname(inputPath)) || inputPath,
+    title: path27.basename(inputPath, path27.extname(inputPath)) || inputPath,
     sourceIds: fileSourceIdsFor(manifestsAfter, inputPath),
     counts: {
       scannedCount: result.scannedCount,
@@ -23513,7 +24455,7 @@ async function runGitCommand(cwd, args) {
 }
 async function syncGitHubRepoSource(rootDir, entry) {
   const workingDir = await managedSourceWorkingDir(rootDir, entry.id);
-  const checkoutDir = path26.join(workingDir, "checkout");
+  const checkoutDir = path27.join(workingDir, "checkout");
   await fs22.rm(checkoutDir, { recursive: true, force: true });
   await ensureDir(workingDir);
   if (!entry.url) {
@@ -23644,7 +24586,7 @@ function scopedNodeIds(graph, sourceIds) {
 async function loadSourceAnalyses(rootDir, sourceIds) {
   const { paths } = await loadVaultConfig(rootDir);
   const analyses = await Promise.all(
-    sourceIds.map(async (sourceId) => await readJsonFile(path26.join(paths.analysesDir, `${sourceId}.json`)))
+    sourceIds.map(async (sourceId) => await readJsonFile(path27.join(paths.analysesDir, `${sourceId}.json`)))
   );
   return analyses.filter((analysis) => Boolean(analysis?.sourceId));
 }
@@ -23805,8 +24747,8 @@ async function writeSourceBriefForScope(rootDir, source) {
       confidence: 0.82
     }
   });
-  const absolutePath = path26.join(paths.wikiDir, output.page.path);
-  await ensureDir(path26.dirname(absolutePath));
+  const absolutePath = path27.join(paths.wikiDir, output.page.path);
+  await ensureDir(path27.dirname(absolutePath));
   await fs22.writeFile(absolutePath, output.content, "utf8");
   return absolutePath;
 }
@@ -24095,7 +25037,7 @@ function selectGuidedTargetPages(scope, sourcePages, questions) {
   return (matchedTargets.length ? matchedTargets : canonicalPages).slice(0, 6);
 }
 function insightRelativePathForTarget(page, scope) {
-  const basename = path26.basename(page.path);
+  const basename = path27.basename(page.path);
   if (page.kind === "concept") {
     return `insights/concepts/${basename}`;
   }
@@ -24251,191 +25193,36 @@ Entities: ${analysis.entities.map((entity) => entity.name).join(", ") || "none"}
         "",
         "Analyses:",
         analysisContext || "No analysis context available.",
-        "",
-        "Deterministic fallback draft:",
-        fallback
-      ].join("\n")
-    });
-    return response.text?.trim() ? response.text.trim() : fallback;
-  } catch {
-    return fallback;
-  }
-}
-async function buildSourceGuideStagedPage(rootDir, scope) {
-  const { config, paths } = await loadVaultConfig(rootDir);
-  const markdown = await generateSourceGuideMarkdown(rootDir, scope);
-  if (!markdown) {
-    throw new Error(`Could not generate a source guide for ${scope.id}.`);
-  }
-  const graph = await readJsonFile(paths.graphPath);
-  const schemas = await loadVaultSchemas(rootDir);
-  const scopeManifests = manifestsForScope(graph, scope);
-  const relatedPages = graph ? scopedSourcePages(graph, scope.sourceIds) : [];
-  const contradictions = findContradictionsForScope(scope, await readGraphReport(rootDir));
-  const selectedTargets = selectGuidedTargetPages(scope, relatedPages, defaultGuidedSessionQuestions());
-  const relatedPageIds = relatedPages.slice(0, 18).map((page) => page.id);
-  const relatedNodeIds = graph ? scopedNodeIds(graph, scope.sourceIds).slice(0, 28) : [];
-  const projectIds = uniqueStrings4(relatedPages.flatMap((page) => page.projectIds));
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const output = buildOutputPage({
-    title: `Source Guide: ${scope.title}`,
-    question: `Guide ${scope.title}`,
-    answer: markdown,
-    citations: scope.sourceIds,
-    schemaHash: sourceOutputSchemaHash(schemas, projectIds),
-    outputFormat: "report",
-    relatedPageIds,
-    relatedNodeIds,
-    relatedSourceIds: scope.sourceIds,
-    projectIds,
-    extraTags: ["source-guide", "guided-ingest"],
-    origin: "source_guide",
-    slug: `source-guides/${scope.id}`,
-    metadata: {
-      status: "draft",
-      createdAt: now,
-      updatedAt: now,
-      compiledFrom: scope.sourceIds,
-      managedBy: "system",
-      confidence: 0.8
-    },
-    frontmatter: {
-      profile_presets: config.profile.presets,
-      source_type: scopeSourceType(scope, scopeManifests),
-      occurred_at: scopeOccurredAt(scopeManifests),
-      participants: scopeParticipants(scopeManifests),
-      container_title: scopeContainerTitle(scopeManifests),
-      conversation_id: scopeConversationId(scopeManifests),
-      question_state: "answered",
-      canonical_targets: selectedTargets.map((page) => page.path),
-      evidence_state: contradictions.length ? "conflicting" : selectedTargets.some((page) => page.sourceIds.some((sourceId) => !scope.sourceIds.includes(sourceId))) ? "reinforcing" : selectedTargets.length ? "new" : "needs_judgment"
-    }
-  });
-  return { page: output.page, content: output.content };
-}
-async function stageSourceReviewForScope(rootDir, scope) {
-  const output = await buildSourceReviewStagedPage(rootDir, scope);
-  const approval = await stageGeneratedOutputPages(rootDir, [{ page: output.page, content: output.content, label: "source-review" }], {
-    bundleType: "source-review",
-    title: `Source Review: ${scope.title}`
-  });
-  return {
-    sourceId: scope.id,
-    pageId: output.page.id,
-    reviewPath: path26.join(approval.approvalDir, "wiki", output.page.path),
-    staged: true,
-    approvalId: approval.approvalId,
-    approvalDir: approval.approvalDir
-  };
-}
-function nextGuidedSourceSessionId(scope) {
-  return `source-session-${slugify(scope.id)}-${sha256(`${scope.id}:${(/* @__PURE__ */ new Date()).toISOString()}`).slice(0, 8)}`;
-}
-function shouldReuseGuidedSourceSession(session) {
-  return Boolean(session && session.status === "awaiting_input");
-}
-function questionAnswer(questions, id, fallback) {
-  return normalizeGuidedAnswerValue(questions.find((question) => question.id === id)?.answer) ?? fallback;
-}
-async function prepareGuidedSourceSession(rootDir, scope, answers) {
-  const existing = await findLatestGuidedSourceSessionByScope(rootDir, scope.id);
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const session = shouldReuseGuidedSourceSession(existing) ? {
-    ...existing,
-    scopeTitle: scope.title,
-    sourceIds: scope.sourceIds,
-    kind: scope.kind,
-    questions: mergeGuidedSessionQuestions(existing.questions, answers),
-    updatedAt: now
-  } : {
-    sessionId: nextGuidedSourceSessionId(scope),
-    scopeId: scope.id,
-    scopeTitle: scope.title,
-    sourceIds: scope.sourceIds,
-    kind: scope.kind,
-    status: "awaiting_input",
-    createdAt: now,
-    updatedAt: now,
-    questions: mergeGuidedSessionQuestions(defaultGuidedSessionQuestions(), answers),
-    briefPath: scope.briefPath,
-    targetedPagePaths: [],
-    stagedUpdatePaths: []
-  };
-  const statePath = await guidedSourceSessionStatePath(rootDir, session.sessionId);
-  return { session, statePath };
-}
-async function buildSourceSessionSavedPage(rootDir, scope, session) {
-  const { config, paths } = await loadVaultConfig(rootDir);
-  let graph = await readJsonFile(paths.graphPath);
-  if (!graph) {
-    await compileVault(rootDir, {});
-    graph = await readJsonFile(paths.graphPath);
-  }
-  const schemas = await loadVaultSchemas(rootDir);
-  const scopeManifests = manifestsForScope(graph, scope);
-  const sourcePages = graph ? scopedSourcePages(graph, scope.sourceIds) : [];
-  const analyses = await loadSourceAnalyses(rootDir, scope.sourceIds);
-  const report = await readGraphReport(rootDir);
-  const contradictions = findContradictionsForScope(scope, report);
-  const relatedPageIds = uniqueStrings4([
-    ...sourcePages.slice(0, 18).map((page) => page.id),
-    ...session.targetedPagePaths.map((relativePath) => {
-      const page = graph?.pages.find((candidate) => candidate.path === relativePath);
-      return page?.id ?? "";
-    })
-  ]);
-  const relatedNodeIds = graph ? scopedNodeIds(graph, scope.sourceIds).slice(0, 28) : [];
-  const projectIds = uniqueStrings4(sourcePages.flatMap((page) => page.projectIds));
-  const evidenceState = contradictions.length > 0 ? "conflicting" : session.targetedPagePaths.some(
-    (targetPath) => sourcePages.some((page) => page.path === targetPath && page.sourceIds.some((sourceId) => !scope.sourceIds.includes(sourceId)))
-  ) ? "reinforcing" : session.targetedPagePaths.length ? "new" : "needs_judgment";
-  const relativeBriefPath = session.briefPath && path26.isAbsolute(session.briefPath) ? path26.relative(paths.wikiDir, session.briefPath) : session.briefPath;
-  const sessionMarkdown = [
-    `# Guided Session: ${scope.title}`,
-    "",
-    `Status: \`${session.status}\``,
-    `Session ID: \`${session.sessionId}\``,
-    ...session.approvalId ? [`Approval Bundle: \`${session.approvalId}\``] : [],
-    ...relativeBriefPath ? [`Brief: \`${relativeBriefPath}\``] : [],
-    "",
-    "## What This Source Is",
-    "",
-    ...analyses.length ? analyses.slice(0, 6).map((analysis) => `- ${analysis.title}: ${analysis.summary}`) : ["- Awaiting compile context."],
-    "",
-    "## Guided Questions",
-    "",
-    ...session.questions.flatMap((question) => [`### ${question.prompt}`, "", question.answer ?? "_Awaiting input._", ""]),
-    "## Proposed Wiki Targets",
-    "",
-    ...session.targetedPagePaths.length ? session.targetedPagePaths.map((targetPath) => `- [[${targetPath.replace(/\.md$/, "")}]]`) : ["- No canonical update targets selected yet."],
-    "",
-    "## Conflicts And Judgment Calls",
-    "",
-    ...contradictions.length ? contradictions.map((contradiction) => `- ${contradiction.claimA} / ${contradiction.claimB}`) : ["- No contradictions are currently flagged for this source scope."],
-    "",
-    "## Follow-up Questions",
-    "",
-    ...(() => {
-      const followups = questionAnswer(session.questions, "followups", "");
-      if (followups) {
-        return followups.split(/\n+/).map((line) => line.trim()).filter(Boolean).map((line) => `- ${line.replace(/^-+\s*/, "")}`);
-      }
-      const analysisQuestions = uniqueStrings4(analyses.flatMap((analysis) => analysis.questions)).slice(0, 6);
-      return analysisQuestions.length ? analysisQuestions.map((question) => `- ${question}`) : ["- No follow-up questions recorded yet."];
-    })(),
-    "",
-    "## Related Artifacts",
-    "",
-    `- [[outputs/source-briefs/${scope.id}|Source Brief]]`,
-    `- [[outputs/source-reviews/${scope.id}|Source Review]]`,
-    `- [[outputs/source-guides/${scope.id}|Source Guide]]`,
-    ""
-  ].join("\n");
+        "",
+        "Deterministic fallback draft:",
+        fallback
+      ].join("\n")
+    });
+    return response.text?.trim() ? response.text.trim() : fallback;
+  } catch {
+    return fallback;
+  }
+}
+async function buildSourceGuideStagedPage(rootDir, scope) {
+  const { config, paths } = await loadVaultConfig(rootDir);
+  const markdown = await generateSourceGuideMarkdown(rootDir, scope);
+  if (!markdown) {
+    throw new Error(`Could not generate a source guide for ${scope.id}.`);
+  }
+  const graph = await readJsonFile(paths.graphPath);
+  const schemas = await loadVaultSchemas(rootDir);
+  const scopeManifests = manifestsForScope(graph, scope);
+  const relatedPages = graph ? scopedSourcePages(graph, scope.sourceIds) : [];
+  const contradictions = findContradictionsForScope(scope, await readGraphReport(rootDir));
+  const selectedTargets = selectGuidedTargetPages(scope, relatedPages, defaultGuidedSessionQuestions());
+  const relatedPageIds = relatedPages.slice(0, 18).map((page) => page.id);
+  const relatedNodeIds = graph ? scopedNodeIds(graph, scope.sourceIds).slice(0, 28) : [];
+  const projectIds = uniqueStrings4(relatedPages.flatMap((page) => page.projectIds));
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const output = buildOutputPage({
-    title: `Guided Session: ${scope.title}`,
-    question: `Guided Session ${scope.title}`,
-    answer: sessionMarkdown,
+    title: `Source Guide: ${scope.title}`,
+    question: `Guide ${scope.title}`,
+    answer: markdown,
     citations: scope.sourceIds,
     schemaHash: sourceOutputSchemaHash(schemas, projectIds),
     outputFormat: "report",
@@ -24443,1123 +25230,787 @@ async function buildSourceSessionSavedPage(rootDir, scope, session) {
     relatedNodeIds,
     relatedSourceIds: scope.sourceIds,
     projectIds,
-    extraTags: ["source-session", "guided-session"],
-    origin: "source_session",
-    slug: `source-sessions/${scope.id}`,
+    extraTags: ["source-guide", "guided-ingest"],
+    origin: "source_guide",
+    slug: `source-guides/${scope.id}`,
     metadata: {
-      status: "active",
+      status: "draft",
       createdAt: now,
       updatedAt: now,
       compiledFrom: scope.sourceIds,
       managedBy: "system",
-      confidence: 0.81
-    },
-    frontmatter: {
-      profile_presets: config.profile.presets,
-      source_type: scopeSourceType(scope, scopeManifests),
-      occurred_at: scopeOccurredAt(scopeManifests),
-      participants: scopeParticipants(scopeManifests),
-      container_title: scopeContainerTitle(scopeManifests),
-      conversation_id: scopeConversationId(scopeManifests),
-      session_status: session.status,
-      question_state: questionStateForSession(session),
-      canonical_targets: session.targetedPagePaths,
-      evidence_state: evidenceState
-    }
-  });
-  return { page: output.page, content: output.content };
-}
-async function persistSourceSessionPage(rootDir, scope, session) {
-  const { paths } = await loadVaultConfig(rootDir);
-  const output = await buildSourceSessionSavedPage(rootDir, scope, session);
-  const absolutePath = path26.join(paths.wikiDir, output.page.path);
-  await ensureDir(path26.dirname(absolutePath));
-  await fs22.writeFile(absolutePath, output.content, "utf8");
-  return { pageId: output.page.id, sessionPath: absolutePath };
-}
-async function buildGuidedUpdatePages(rootDir, scope, session) {
-  const { config, paths } = await loadVaultConfig(rootDir);
-  let graph = await readJsonFile(paths.graphPath);
-  if (!graph) {
-    await compileVault(rootDir, {});
-    graph = await readJsonFile(paths.graphPath);
-  }
-  if (!graph) {
-    return [];
-  }
-  const sourcePages = scopedSourcePages(graph, scope.sourceIds);
-  const scopeManifests = manifestsForScope(graph, scope);
-  const analyses = await loadSourceAnalyses(rootDir, scope.sourceIds);
-  const report = await readGraphReport(rootDir);
-  const contradictions = findContradictionsForScope(scope, report);
-  const selectedTargets = selectGuidedTargetPages(scope, sourcePages, session.questions);
-  const useCanonicalTargets = config.profile.guidedSessionMode === "canonical_review" && selectedTargets.length > 0;
-  const targetPages = useCanonicalTargets ? selectedTargets : [selectedTargets[0] ?? null];
-  session.targetedPagePaths = uniqueStrings4(
-    useCanonicalTargets ? selectedTargets.map((page) => page.path) : selectedTargets.length ? selectedTargets.map((page) => page.path) : session.targetedPagePaths
-  );
-  return await Promise.all(
-    targetPages.map(async (targetPage) => {
-      const evidenceState = classifyGuidedEvidenceState(scope, targetPage, contradictions);
-      const relativePath = useCanonicalTargets && targetPage ? targetPage.path : targetPage ? insightRelativePathForTarget(targetPage, scope) : `insights/topics/${slugify(scope.title)}.md`;
-      const absolutePath = path26.join(paths.wikiDir, relativePath);
-      const existingContent = await fileExists(absolutePath) ? await fs22.readFile(absolutePath, "utf8") : "";
-      const parsed = existingContent ? matter11(existingContent) : { data: {}, content: "" };
-      const existingData = parsed.data;
-      const existingSourceIds = Array.isArray(existingData.source_ids) ? existingData.source_ids.filter((value) => typeof value === "string") : [];
-      const existingProjectIds = Array.isArray(existingData.project_ids) ? existingData.project_ids.filter((value) => typeof value === "string") : [];
-      const existingNodeIds = Array.isArray(existingData.node_ids) ? existingData.node_ids.filter((value) => typeof value === "string") : [];
-      const existingBacklinks = Array.isArray(existingData.backlinks) ? existingData.backlinks.filter((value) => typeof value === "string") : [];
-      const createdAt = typeof existingData.created_at === "string" && existingData.created_at.trim() ? existingData.created_at : (/* @__PURE__ */ new Date()).toISOString();
-      const title = typeof existingData.title === "string" && existingData.title.trim() || (useCanonicalTargets && targetPage ? targetPage.title : targetPage ? insightTitleForTarget(targetPage, scope) : `${scope.title} Notes`);
-      const baseBody = parsed.content.trim() ? parsed.content.trim() : [
-        `# ${title}`,
-        "",
-        useCanonicalTargets ? "Canonical page maintained by SwarmVault. Guided sessions stage replaceable update blocks here for approval." : "Human-curated insight page. Guided sessions stage replaceable update blocks here.",
-        ""
-      ].join("\n");
-      const importance = questionAnswer(
-        session.questions,
-        "importance",
-        "Capture the most important new ideas from this source before treating them as canonical."
-      );
-      const exclude = questionAnswer(
-        session.questions,
-        "exclude",
-        "Keep uncertain or incidental details provisional until they matter to the research thread."
-      );
-      const conflictNotes = questionAnswer(
-        session.questions,
-        "conflicts",
-        contradictions.length ? "Review the conflicting evidence before accepting any canonical summary changes." : "No explicit conflicts were called out."
-      );
-      const followups = questionAnswer(session.questions, "followups", "Track follow-up questions on the source session page.");
-      const updateBlock = [
-        `## Guided Session Update: ${scope.title}`,
-        "",
-        `Evidence State: \`${evidenceState}\``,
-        `Session: [[outputs/source-sessions/${scope.id}|Guided Session]]`,
-        `Source Guide: [[outputs/source-guides/${scope.id}|Source Guide]]`,
-        "",
-        "### What Matters Now",
-        "",
-        importance,
-        "",
-        "### Proposed Integration",
-        "",
-        targetPage ? `- Fold the strongest source-backed takeaways into [[${targetPage.path.replace(/\.md$/, "")}|${targetPage.title}]].` : `- Start a durable topic note for ${scope.title}.`,
-        ...analyses.slice(0, 5).map((analysis) => `- ${truncate(normalizeWhitespace(analysis.summary), 180)}`),
-        "",
-        "### Keep Provisional Or Out",
-        "",
-        exclude,
-        "",
-        "### Reinforcing Or Conflicting Notes",
-        "",
-        conflictNotes,
-        ...contradictions.length ? ["", ...contradictions.slice(0, 4).map((contradiction) => `- ${contradiction.claimA} / ${contradiction.claimB}`)] : [],
-        "",
-        "### Follow-up Questions",
-        "",
-        followups,
-        ""
-      ].join("\n");
-      const nextBody = replaceMarkedSection(baseBody, scope.id, updateBlock);
-      const content = matter11.stringify(
-        `${nextBody.trimEnd()}
-`,
-        JSON.parse(
-          JSON.stringify({
-            ...existingData,
-            page_id: typeof existingData.page_id === "string" && existingData.page_id.trim() || (useCanonicalTargets && targetPage ? targetPage.id : `insight:${slugify(relativePath.replace(/\.md$/, ""))}`),
-            kind: useCanonicalTargets && targetPage ? targetPage.kind : "insight",
-            title,
-            tags: uniqueStrings4([
-              ...Array.isArray(existingData.tags) ? existingData.tags.filter((value) => typeof value === "string") : [],
-              ...useCanonicalTargets ? ["guided-session", `guided/${targetPage?.kind ?? "page"}`] : insightTagsForTarget(targetPage)
-            ]),
-            source_ids: uniqueStrings4([...existingSourceIds, ...scope.sourceIds]),
-            project_ids: uniqueStrings4([...existingProjectIds, ...targetPage?.projectIds ?? []]),
-            node_ids: uniqueStrings4([...existingNodeIds, ...targetPage?.nodeIds ?? []]),
-            freshness: "fresh",
-            status: existingData.status === "archived" ? "archived" : "active",
-            confidence: 0.83,
-            created_at: createdAt,
-            updated_at: (/* @__PURE__ */ new Date()).toISOString(),
-            compiled_from: uniqueStrings4([
-              ...Array.isArray(existingData.compiled_from) ? existingData.compiled_from.filter((value) => typeof value === "string") : [],
-              ...scope.sourceIds
-            ]),
-            managed_by: typeof existingData.managed_by === "string" && (existingData.managed_by === "human" || existingData.managed_by === "system") ? existingData.managed_by : useCanonicalTargets ? "system" : "human",
-            backlinks: uniqueStrings4([
-              ...existingBacklinks,
-              ...targetPage ? [targetPage.id] : [],
-              `output:source-sessions/${scope.id}`,
-              `output:source-guides/${scope.id}`
-            ]),
-            schema_hash: typeof existingData.schema_hash === "string" ? existingData.schema_hash : "",
-            source_hashes: existingData.source_hashes && typeof existingData.source_hashes === "object" ? existingData.source_hashes : {},
-            source_semantic_hashes: existingData.source_semantic_hashes && typeof existingData.source_semantic_hashes === "object" ? existingData.source_semantic_hashes : {},
-            profile_presets: config.profile.presets,
-            source_type: scopeSourceType(scope, scopeManifests),
-            occurred_at: scopeOccurredAt(scopeManifests),
-            participants: scopeParticipants(scopeManifests),
-            container_title: scopeContainerTitle(scopeManifests),
-            conversation_id: scopeConversationId(scopeManifests),
-            session_status: session.status,
-            question_state: questionStateForSession(session),
-            canonical_targets: useCanonicalTargets ? selectedTargets.map((page2) => page2.path) : [],
-            evidence_state: evidenceState
-          })
-        )
-      );
-      const page = parseStoredPage(relativePath, content, {
-        createdAt,
-        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-      });
-      if (!useCanonicalTargets && !selectedTargets.length) {
-        session.targetedPagePaths = uniqueStrings4([...session.targetedPagePaths, relativePath]);
-      }
-      return { page, content, label: "guided-update" };
-    })
-  );
-}
-async function stageSourceGuideForScope(rootDir, scope, options = {}) {
-  const { session, statePath } = await prepareGuidedSourceSession(rootDir, scope, options.answers);
-  const briefPath = scope.briefPath ?? session.briefPath ?? await writeSourceBriefForScope(rootDir, scope) ?? void 0;
-  session.briefPath = briefPath;
-  if (briefPath) {
-    await refreshVaultAfterOutputSave(rootDir);
-  }
-  if (answeredGuidedSessionQuestions(session.questions).length === 0) {
-    session.status = "awaiting_input";
-    const persisted2 = await persistSourceSessionPage(rootDir, scope, session);
-    session.sessionPath = persisted2.sessionPath;
-    await writeGuidedSourceSession(rootDir, session);
-    await refreshVaultAfterOutputSave(rootDir);
-    return {
-      sourceId: scope.id,
-      sessionId: session.sessionId,
-      sessionPath: persisted2.sessionPath,
-      sessionStatePath: statePath,
-      status: session.status,
-      questions: session.questions,
-      awaitingInput: true,
-      targetedPagePaths: session.targetedPagePaths,
-      stagedUpdatePaths: session.stagedUpdatePaths,
-      briefPath,
-      staged: false
-    };
-  }
-  session.status = "ready_to_stage";
-  await writeGuidedSourceSession(rootDir, session);
-  const reviewOutput = await buildSourceReviewStagedPage(rootDir, scope);
-  const guideOutput = await buildSourceGuideStagedPage(rootDir, {
-    ...scope,
-    briefPath
-  });
-  const guidedUpdates = await buildGuidedUpdatePages(rootDir, scope, session);
-  session.stagedUpdatePaths = guidedUpdates.map((item) => item.page.path);
-  const approval = await stageGeneratedOutputPages(
-    rootDir,
-    [
-      { page: reviewOutput.page, content: reviewOutput.content, label: "source-review" },
-      { page: guideOutput.page, content: guideOutput.content, label: "source-guide" },
-      ...guidedUpdates
-    ],
-    {
-      bundleType: "guided-session",
-      title: `Guided Session: ${scope.title}`,
-      sourceSessionId: session.sessionId
+      confidence: 0.8
+    },
+    frontmatter: {
+      profile_presets: config.profile.presets,
+      source_type: scopeSourceType(scope, scopeManifests),
+      occurred_at: scopeOccurredAt(scopeManifests),
+      participants: scopeParticipants(scopeManifests),
+      container_title: scopeContainerTitle(scopeManifests),
+      conversation_id: scopeConversationId(scopeManifests),
+      question_state: "answered",
+      canonical_targets: selectedTargets.map((page) => page.path),
+      evidence_state: contradictions.length ? "conflicting" : selectedTargets.some((page) => page.sourceIds.some((sourceId) => !scope.sourceIds.includes(sourceId))) ? "reinforcing" : selectedTargets.length ? "new" : "needs_judgment"
     }
-  );
-  session.status = "staged";
-  session.reviewPath = path26.join(approval.approvalDir, "wiki", reviewOutput.page.path);
-  session.guidePath = path26.join(approval.approvalDir, "wiki", guideOutput.page.path);
-  session.approvalId = approval.approvalId;
-  session.approvalDir = approval.approvalDir;
-  const persisted = await persistSourceSessionPage(rootDir, scope, session);
-  session.sessionPath = persisted.sessionPath;
-  await writeGuidedSourceSession(rootDir, session);
-  await refreshVaultAfterOutputSave(rootDir);
+  });
+  return { page: output.page, content: output.content };
+}
+async function stageSourceReviewForScope(rootDir, scope) {
+  const output = await buildSourceReviewStagedPage(rootDir, scope);
+  const approval = await stageGeneratedOutputPages(rootDir, [{ page: output.page, content: output.content, label: "source-review" }], {
+    bundleType: "source-review",
+    title: `Source Review: ${scope.title}`
+  });
   return {
     sourceId: scope.id,
-    pageId: guideOutput.page.id,
-    guidePath: session.guidePath,
-    reviewPageId: reviewOutput.page.id,
-    reviewPath: session.reviewPath,
-    sessionId: session.sessionId,
-    sessionPath: persisted.sessionPath,
-    sessionStatePath: statePath,
-    status: session.status,
-    questions: session.questions,
-    targetedPagePaths: session.targetedPagePaths,
-    stagedUpdatePaths: session.stagedUpdatePaths,
-    briefPath,
+    pageId: output.page.id,
+    reviewPath: path27.join(approval.approvalDir, "wiki", output.page.path),
     staged: true,
     approvalId: approval.approvalId,
     approvalDir: approval.approvalDir
   };
 }
-function scopeFromManagedSource(source) {
-  return {
-    id: source.id,
-    title: source.title,
-    sourceIds: source.sourceIds,
-    kind: source.kind,
-    briefPath: source.briefPath
-  };
-}
-function scopeFromManifest(manifest, manifests) {
-  const groupId = manifest.sourceGroupId ?? manifest.sourceId;
-  return {
-    id: groupId,
-    title: manifest.sourceGroupTitle ?? manifest.title,
-    sourceIds: manifest.sourceGroupId ? manifests.filter((candidate) => candidate.sourceGroupId === manifest.sourceGroupId).map((candidate) => candidate.sourceId) : [manifest.sourceId],
-    kind: manifest.sourceKind
-  };
-}
-async function resolveSourceScope(rootDir, id) {
-  const managedSources = await loadManagedSources(rootDir);
-  const managedSource = managedSources.find((source) => source.id === id);
-  if (managedSource) {
-    return scopeFromManagedSource(managedSource);
-  }
-  const latestSession = await findLatestGuidedSourceSessionByScope(rootDir, id);
-  if (latestSession) {
-    return {
-      id: latestSession.scopeId,
-      title: latestSession.scopeTitle,
-      sourceIds: latestSession.sourceIds
-    };
-  }
-  const manifests = await listManifests(rootDir);
-  const manifest = manifests.find((candidate) => candidate.sourceId === id) ?? manifests.find((candidate) => candidate.sourceGroupId === id);
-  if (!manifest) {
-    return null;
-  }
-  return scopeFromManifest(manifest, manifests);
-}
-async function reviewSourceScope(rootDir, scope) {
-  return await stageSourceReviewForScope(rootDir, scope);
-}
-async function guideSourceScope(rootDir, scope, options = {}) {
-  return await stageSourceGuideForScope(rootDir, scope, options);
-}
-async function reviewManagedSource(rootDir, id) {
-  const scope = await resolveSourceScope(rootDir, id);
-  if (!scope) {
-    throw new Error(`Managed source or source id not found: ${id}`);
-  }
-  if (!await loadVaultConfig(rootDir).then(({ paths }) => fileExists(paths.graphPath))) {
-    await compileVault(rootDir, {});
-  }
-  return await stageSourceReviewForScope(rootDir, scope);
-}
-async function guideManagedSource(rootDir, id, options = {}) {
-  const scope = await resolveSourceScope(rootDir, id);
-  if (!scope) {
-    throw new Error(`Managed source or source id not found: ${id}`);
-  }
-  if (!await loadVaultConfig(rootDir).then(({ paths }) => fileExists(paths.graphPath))) {
-    await compileVault(rootDir, {});
-  }
-  return await stageSourceGuideForScope(rootDir, scope, options);
-}
-async function resumeSourceSession(rootDir, id, options = {}) {
-  const existingSession = await readGuidedSourceSession(rootDir, id);
-  if (existingSession) {
-    return await stageSourceGuideForScope(
-      rootDir,
-      {
-        id: existingSession.scopeId,
-        title: existingSession.scopeTitle,
-        sourceIds: existingSession.sourceIds,
-        kind: existingSession.kind,
-        briefPath: existingSession.briefPath
-      },
-      options
-    );
-  }
-  const scope = await resolveSourceScope(rootDir, id);
-  if (!scope) {
-    throw new Error(`Managed source, source scope, or guided session not found: ${id}`);
-  }
-  return await stageSourceGuideForScope(rootDir, scope, options);
-}
-function shouldCompile(changedSources, graphExists, compileRequested) {
-  return compileRequested && (!graphExists || changedSources.length > 0);
+function nextGuidedSourceSessionId(scope) {
+  return `source-session-${slugify(scope.id)}-${sha256(`${scope.id}:${(/* @__PURE__ */ new Date()).toISOString()}`).slice(0, 8)}`;
 }
-async function shouldRefreshBriefForManagedSource(source, options) {
-  if (options.compilePerformed || options.changed) {
-    return true;
-  }
-  if (!source.briefPath) {
-    return true;
-  }
-  return !await fileExists(source.briefPath);
+function shouldReuseGuidedSourceSession(session) {
+  return Boolean(session && session.status === "awaiting_input");
 }
-async function listManagedSourceRecords(rootDir) {
-  await ensureManagedSourcesArtifact(rootDir);
-  return await loadManagedSources(rootDir);
+function questionAnswer(questions, id, fallback) {
+  return normalizeGuidedAnswerValue(questions.find((question) => question.id === id)?.answer) ?? fallback;
 }
-async function addManagedSource(rootDir, input, options = {}) {
-  const compileRequested = options.compile ?? true;
-  const guideRequested = options.guide ?? false;
-  const briefRequested = guideRequested ? true : options.brief ?? true;
-  const reviewRequested = guideRequested ? false : options.review ?? false;
-  const sources = await loadManagedSources(rootDir);
-  const resolved = await resolveManagedSourceInput(rootDir, input);
-  const existing = sources.find((candidate) => matchesManagedSourceSpec(candidate, resolved));
+async function prepareGuidedSourceSession(rootDir, scope, answers) {
+  const existing = await findLatestGuidedSourceSessionByScope(rootDir, scope.id);
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  const source = existing ?? {
-    id: resolved.kind === "directory" || resolved.kind === "file" ? stableManagedSourceId(resolved.kind, path26.resolve(resolved.path), resolved.title) : stableManagedSourceId(resolved.kind, resolved.url, resolved.title),
-    kind: resolved.kind,
-    title: resolved.title,
-    path: resolved.kind === "directory" || resolved.kind === "file" ? resolved.path : void 0,
-    repoRoot: resolved.kind === "directory" ? resolved.repoRoot : void 0,
-    url: resolved.kind === "directory" || resolved.kind === "file" ? void 0 : resolved.url,
+  const session = shouldReuseGuidedSourceSession(existing) ? {
+    ...existing,
+    scopeTitle: scope.title,
+    sourceIds: scope.sourceIds,
+    kind: scope.kind,
+    questions: mergeGuidedSessionQuestions(existing.questions, answers),
+    updatedAt: now
+  } : {
+    sessionId: nextGuidedSourceSessionId(scope),
+    scopeId: scope.id,
+    scopeTitle: scope.title,
+    sourceIds: scope.sourceIds,
+    kind: scope.kind,
+    status: "awaiting_input",
     createdAt: now,
     updatedAt: now,
-    status: "ready",
-    sourceIds: []
+    questions: mergeGuidedSessionQuestions(defaultGuidedSessionQuestions(), answers),
+    briefPath: scope.briefPath,
+    targetedPagePaths: [],
+    stagedUpdatePaths: []
   };
-  const synced = await syncManagedSource(rootDir, source, options);
-  if (synced.lastSyncStatus === "error") {
-    throw new Error(synced.lastError ?? `Failed to add managed source ${synced.id}.`);
-  }
-  const graphExists = await loadVaultConfig(rootDir).then(({ paths }) => fileExists(paths.graphPath));
-  let compile;
-  if (shouldCompile(synced.changed ? [synced] : [], graphExists, compileRequested)) {
-    compile = await compileVault(rootDir, {});
-  }
-  let briefGenerated = false;
-  let briefPath;
-  if (compileRequested && briefRequested && synced.status === "ready" && await shouldRefreshBriefForManagedSource(synced, {
-    compilePerformed: Boolean(compile),
-    changed: synced.changed
-  })) {
-    const briefs = await generateBriefsForSources(rootDir, [synced]);
-    briefPath = briefs.get(synced.id);
-    briefGenerated = Boolean(briefPath);
+  const statePath = await guidedSourceSessionStatePath(rootDir, session.sessionId);
+  return { session, statePath };
+}
+async function buildSourceSessionSavedPage(rootDir, scope, session) {
+  const { config, paths } = await loadVaultConfig(rootDir);
+  let graph = await readJsonFile(paths.graphPath);
+  if (!graph) {
+    await compileVault(rootDir, {});
+    graph = await readJsonFile(paths.graphPath);
   }
-  const nextSource = {
-    ...synced,
-    briefPath: briefPath ?? synced.briefPath,
-    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  const nextSources = existing ? sources.map((candidate) => candidate.id === nextSource.id ? nextSource : candidate) : [...sources, nextSource];
-  await saveManagedSources(rootDir, nextSources);
-  const review = reviewRequested && nextSource.status === "ready" ? await stageSourceReviewForScope(rootDir, scopeFromManagedSource(nextSource)) : void 0;
-  const guide = guideRequested && nextSource.status === "ready" ? await stageSourceGuideForScope(
-    rootDir,
-    {
-      ...scopeFromManagedSource(nextSource),
-      briefPath: nextSource.briefPath
+  const schemas = await loadVaultSchemas(rootDir);
+  const scopeManifests = manifestsForScope(graph, scope);
+  const sourcePages = graph ? scopedSourcePages(graph, scope.sourceIds) : [];
+  const analyses = await loadSourceAnalyses(rootDir, scope.sourceIds);
+  const report = await readGraphReport(rootDir);
+  const contradictions = findContradictionsForScope(scope, report);
+  const relatedPageIds = uniqueStrings4([
+    ...sourcePages.slice(0, 18).map((page) => page.id),
+    ...session.targetedPagePaths.map((relativePath) => {
+      const page = graph?.pages.find((candidate) => candidate.path === relativePath);
+      return page?.id ?? "";
+    })
+  ]);
+  const relatedNodeIds = graph ? scopedNodeIds(graph, scope.sourceIds).slice(0, 28) : [];
+  const projectIds = uniqueStrings4(sourcePages.flatMap((page) => page.projectIds));
+  const evidenceState = contradictions.length > 0 ? "conflicting" : session.targetedPagePaths.some(
+    (targetPath) => sourcePages.some((page) => page.path === targetPath && page.sourceIds.some((sourceId) => !scope.sourceIds.includes(sourceId)))
+  ) ? "reinforcing" : session.targetedPagePaths.length ? "new" : "needs_judgment";
+  const relativeBriefPath = session.briefPath && path27.isAbsolute(session.briefPath) ? path27.relative(paths.wikiDir, session.briefPath) : session.briefPath;
+  const sessionMarkdown = [
+    `# Guided Session: ${scope.title}`,
+    "",
+    `Status: \`${session.status}\``,
+    `Session ID: \`${session.sessionId}\``,
+    ...session.approvalId ? [`Approval Bundle: \`${session.approvalId}\``] : [],
+    ...relativeBriefPath ? [`Brief: \`${relativeBriefPath}\``] : [],
+    "",
+    "## What This Source Is",
+    "",
+    ...analyses.length ? analyses.slice(0, 6).map((analysis) => `- ${analysis.title}: ${analysis.summary}`) : ["- Awaiting compile context."],
+    "",
+    "## Guided Questions",
+    "",
+    ...session.questions.flatMap((question) => [`### ${question.prompt}`, "", question.answer ?? "_Awaiting input._", ""]),
+    "## Proposed Wiki Targets",
+    "",
+    ...session.targetedPagePaths.length ? session.targetedPagePaths.map((targetPath) => `- [[${targetPath.replace(/\.md$/, "")}]]`) : ["- No canonical update targets selected yet."],
+    "",
+    "## Conflicts And Judgment Calls",
+    "",
+    ...contradictions.length ? contradictions.map((contradiction) => `- ${contradiction.claimA} / ${contradiction.claimB}`) : ["- No contradictions are currently flagged for this source scope."],
+    "",
+    "## Follow-up Questions",
+    "",
+    ...(() => {
+      const followups = questionAnswer(session.questions, "followups", "");
+      if (followups) {
+        return followups.split(/\n+/).map((line) => line.trim()).filter(Boolean).map((line) => `- ${line.replace(/^-+\s*/, "")}`);
+      }
+      const analysisQuestions = uniqueStrings4(analyses.flatMap((analysis) => analysis.questions)).slice(0, 6);
+      return analysisQuestions.length ? analysisQuestions.map((question) => `- ${question}`) : ["- No follow-up questions recorded yet."];
+    })(),
+    "",
+    "## Related Artifacts",
+    "",
+    `- [[outputs/source-briefs/${scope.id}|Source Brief]]`,
+    `- [[outputs/source-reviews/${scope.id}|Source Review]]`,
+    `- [[outputs/source-guides/${scope.id}|Source Guide]]`,
+    ""
+  ].join("\n");
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const output = buildOutputPage({
+    title: `Guided Session: ${scope.title}`,
+    question: `Guided Session ${scope.title}`,
+    answer: sessionMarkdown,
+    citations: scope.sourceIds,
+    schemaHash: sourceOutputSchemaHash(schemas, projectIds),
+    outputFormat: "report",
+    relatedPageIds,
+    relatedNodeIds,
+    relatedSourceIds: scope.sourceIds,
+    projectIds,
+    extraTags: ["source-session", "guided-session"],
+    origin: "source_session",
+    slug: `source-sessions/${scope.id}`,
+    metadata: {
+      status: "active",
+      createdAt: now,
+      updatedAt: now,
+      compiledFrom: scope.sourceIds,
+      managedBy: "system",
+      confidence: 0.81
     },
-    { answers: options.guideAnswers }
-  ) : void 0;
-  return {
-    source: nextSource,
-    compile,
-    briefGenerated,
-    review,
-    guide
-  };
-}
-async function reloadManagedSources(rootDir, options = {}) {
-  const compileRequested = options.compile ?? true;
-  const guideRequested = options.guide ?? false;
-  const briefRequested = guideRequested ? true : options.brief ?? true;
-  const reviewRequested = guideRequested ? false : options.review ?? false;
-  const sources = await loadManagedSources(rootDir);
-  const selected = options.all || !options.id ? sources : sources.filter((source) => source.id === options.id);
-  if (!selected.length) {
-    throw new Error(options.id ? `Managed source not found: ${options.id}` : "No managed sources registered.");
-  }
-  const syncedSources = [];
-  const changedSources = [];
-  for (const source of selected) {
-    const synced = await syncManagedSource(rootDir, source, options);
-    syncedSources.push(synced);
-    if (synced.changed) {
-      changedSources.push(synced);
-    }
-  }
-  const graphExists = await loadVaultConfig(rootDir).then(({ paths }) => fileExists(paths.graphPath));
-  let compile;
-  if (shouldCompile(changedSources, graphExists, compileRequested)) {
-    compile = await compileVault(rootDir, {});
-  }
-  const briefPaths = compileRequested && briefRequested ? await generateBriefsForSources(
-    rootDir,
-    syncedSources.filter((source) => source.status === "ready")
-  ) : /* @__PURE__ */ new Map();
-  const nextSources = sources.map((source) => {
-    const synced = syncedSources.find((candidate) => candidate.id === source.id);
-    if (!synced) {
-      return source;
+    frontmatter: {
+      profile_presets: config.profile.presets,
+      source_type: scopeSourceType(scope, scopeManifests),
+      occurred_at: scopeOccurredAt(scopeManifests),
+      participants: scopeParticipants(scopeManifests),
+      container_title: scopeContainerTitle(scopeManifests),
+      conversation_id: scopeConversationId(scopeManifests),
+      session_status: session.status,
+      question_state: questionStateForSession(session),
+      canonical_targets: session.targetedPagePaths,
+      evidence_state: evidenceState
     }
-    return {
-      ...synced,
-      briefPath: briefPaths.get(synced.id) ?? synced.briefPath,
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
   });
-  await saveManagedSources(rootDir, nextSources);
-  const reviews = reviewRequested ? await Promise.all(
-    nextSources.filter((source) => selected.some((candidate) => candidate.id === source.id)).filter((source) => source.status === "ready").map(async (source) => await stageSourceReviewForScope(rootDir, scopeFromManagedSource(source)))
-  ) : [];
-  const guides = guideRequested ? await Promise.all(
-    nextSources.filter((source) => selected.some((candidate) => candidate.id === source.id)).filter((source) => source.status === "ready").map(
-      async (source) => await stageSourceGuideForScope(
-        rootDir,
-        {
-          ...scopeFromManagedSource(source),
-          briefPath: source.briefPath
-        },
-        { answers: options.guideAnswers }
-      )
-    )
-  ) : [];
-  return {
-    sources: nextSources.filter((source) => selected.some((candidate) => candidate.id === source.id)),
-    compile,
-    briefPaths: [...briefPaths.values()],
-    reviews,
-    guides
-  };
+  return { page: output.page, content: output.content };
 }
-async function deleteManagedSource(rootDir, id) {
-  const sources = await loadManagedSources(rootDir);
-  const target = sources.find((source) => source.id === id);
-  if (!target) {
-    throw new Error(`Managed source not found: ${id}`);
+async function persistSourceSessionPage(rootDir, scope, session) {
+  const { paths } = await loadVaultConfig(rootDir);
+  const output = await buildSourceSessionSavedPage(rootDir, scope, session);
+  const absolutePath = path27.join(paths.wikiDir, output.page.path);
+  await ensureDir(path27.dirname(absolutePath));
+  await fs22.writeFile(absolutePath, output.content, "utf8");
+  return { pageId: output.page.id, sessionPath: absolutePath };
+}
+async function buildGuidedUpdatePages(rootDir, scope, session) {
+  const { config, paths } = await loadVaultConfig(rootDir);
+  let graph = await readJsonFile(paths.graphPath);
+  if (!graph) {
+    await compileVault(rootDir, {});
+    graph = await readJsonFile(paths.graphPath);
   }
-  await saveManagedSources(
-    rootDir,
-    sources.filter((source) => source.id !== id)
+  if (!graph) {
+    return [];
+  }
+  const sourcePages = scopedSourcePages(graph, scope.sourceIds);
+  const scopeManifests = manifestsForScope(graph, scope);
+  const analyses = await loadSourceAnalyses(rootDir, scope.sourceIds);
+  const report = await readGraphReport(rootDir);
+  const contradictions = findContradictionsForScope(scope, report);
+  const selectedTargets = selectGuidedTargetPages(scope, sourcePages, session.questions);
+  const useCanonicalTargets = config.profile.guidedSessionMode === "canonical_review" && selectedTargets.length > 0;
+  const targetPages = useCanonicalTargets ? selectedTargets : [selectedTargets[0] ?? null];
+  session.targetedPagePaths = uniqueStrings4(
+    useCanonicalTargets ? selectedTargets.map((page) => page.path) : selectedTargets.length ? selectedTargets.map((page) => page.path) : session.targetedPagePaths
+  );
+  return await Promise.all(
+    targetPages.map(async (targetPage) => {
+      const evidenceState = classifyGuidedEvidenceState(scope, targetPage, contradictions);
+      const relativePath = useCanonicalTargets && targetPage ? targetPage.path : targetPage ? insightRelativePathForTarget(targetPage, scope) : `insights/topics/${slugify(scope.title)}.md`;
+      const absolutePath = path27.join(paths.wikiDir, relativePath);
+      const existingContent = await fileExists(absolutePath) ? await fs22.readFile(absolutePath, "utf8") : "";
+      const parsed = existingContent ? matter11(existingContent) : { data: {}, content: "" };
+      const existingData = parsed.data;
+      const existingSourceIds = Array.isArray(existingData.source_ids) ? existingData.source_ids.filter((value) => typeof value === "string") : [];
+      const existingProjectIds = Array.isArray(existingData.project_ids) ? existingData.project_ids.filter((value) => typeof value === "string") : [];
+      const existingNodeIds = Array.isArray(existingData.node_ids) ? existingData.node_ids.filter((value) => typeof value === "string") : [];
+      const existingBacklinks = Array.isArray(existingData.backlinks) ? existingData.backlinks.filter((value) => typeof value === "string") : [];
+      const createdAt = typeof existingData.created_at === "string" && existingData.created_at.trim() ? existingData.created_at : (/* @__PURE__ */ new Date()).toISOString();
+      const title = typeof existingData.title === "string" && existingData.title.trim() || (useCanonicalTargets && targetPage ? targetPage.title : targetPage ? insightTitleForTarget(targetPage, scope) : `${scope.title} Notes`);
+      const baseBody = parsed.content.trim() ? parsed.content.trim() : [
+        `# ${title}`,
+        "",
+        useCanonicalTargets ? "Canonical page maintained by SwarmVault. Guided sessions stage replaceable update blocks here for approval." : "Human-curated insight page. Guided sessions stage replaceable update blocks here.",
+        ""
+      ].join("\n");
+      const importance = questionAnswer(
+        session.questions,
+        "importance",
+        "Capture the most important new ideas from this source before treating them as canonical."
+      );
+      const exclude = questionAnswer(
+        session.questions,
+        "exclude",
+        "Keep uncertain or incidental details provisional until they matter to the research thread."
+      );
+      const conflictNotes = questionAnswer(
+        session.questions,
+        "conflicts",
+        contradictions.length ? "Review the conflicting evidence before accepting any canonical summary changes." : "No explicit conflicts were called out."
+      );
+      const followups = questionAnswer(session.questions, "followups", "Track follow-up questions on the source session page.");
+      const updateBlock = [
+        `## Guided Session Update: ${scope.title}`,
+        "",
+        `Evidence State: \`${evidenceState}\``,
+        `Session: [[outputs/source-sessions/${scope.id}|Guided Session]]`,
+        `Source Guide: [[outputs/source-guides/${scope.id}|Source Guide]]`,
+        "",
+        "### What Matters Now",
+        "",
+        importance,
+        "",
+        "### Proposed Integration",
+        "",
+        targetPage ? `- Fold the strongest source-backed takeaways into [[${targetPage.path.replace(/\.md$/, "")}|${targetPage.title}]].` : `- Start a durable topic note for ${scope.title}.`,
+        ...analyses.slice(0, 5).map((analysis) => `- ${truncate(normalizeWhitespace(analysis.summary), 180)}`),
+        "",
+        "### Keep Provisional Or Out",
+        "",
+        exclude,
+        "",
+        "### Reinforcing Or Conflicting Notes",
+        "",
+        conflictNotes,
+        ...contradictions.length ? ["", ...contradictions.slice(0, 4).map((contradiction) => `- ${contradiction.claimA} / ${contradiction.claimB}`)] : [],
+        "",
+        "### Follow-up Questions",
+        "",
+        followups,
+        ""
+      ].join("\n");
+      const nextBody = replaceMarkedSection(baseBody, scope.id, updateBlock);
+      const content = matter11.stringify(
+        `${nextBody.trimEnd()}
+`,
+        JSON.parse(
+          JSON.stringify({
+            ...existingData,
+            page_id: typeof existingData.page_id === "string" && existingData.page_id.trim() || (useCanonicalTargets && targetPage ? targetPage.id : `insight:${slugify(relativePath.replace(/\.md$/, ""))}`),
+            kind: useCanonicalTargets && targetPage ? targetPage.kind : "insight",
+            title,
+            tags: uniqueStrings4([
+              ...Array.isArray(existingData.tags) ? existingData.tags.filter((value) => typeof value === "string") : [],
+              ...useCanonicalTargets ? ["guided-session", `guided/${targetPage?.kind ?? "page"}`] : insightTagsForTarget(targetPage)
+            ]),
+            source_ids: uniqueStrings4([...existingSourceIds, ...scope.sourceIds]),
+            project_ids: uniqueStrings4([...existingProjectIds, ...targetPage?.projectIds ?? []]),
+            node_ids: uniqueStrings4([...existingNodeIds, ...targetPage?.nodeIds ?? []]),
+            freshness: "fresh",
+            status: existingData.status === "archived" ? "archived" : "active",
+            confidence: 0.83,
+            created_at: createdAt,
+            updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+            compiled_from: uniqueStrings4([
+              ...Array.isArray(existingData.compiled_from) ? existingData.compiled_from.filter((value) => typeof value === "string") : [],
+              ...scope.sourceIds
+            ]),
+            managed_by: typeof existingData.managed_by === "string" && (existingData.managed_by === "human" || existingData.managed_by === "system") ? existingData.managed_by : useCanonicalTargets ? "system" : "human",
+            backlinks: uniqueStrings4([
+              ...existingBacklinks,
+              ...targetPage ? [targetPage.id] : [],
+              `output:source-sessions/${scope.id}`,
+              `output:source-guides/${scope.id}`
+            ]),
+            schema_hash: typeof existingData.schema_hash === "string" ? existingData.schema_hash : "",
+            source_hashes: existingData.source_hashes && typeof existingData.source_hashes === "object" ? existingData.source_hashes : {},
+            source_semantic_hashes: existingData.source_semantic_hashes && typeof existingData.source_semantic_hashes === "object" ? existingData.source_semantic_hashes : {},
+            profile_presets: config.profile.presets,
+            source_type: scopeSourceType(scope, scopeManifests),
+            occurred_at: scopeOccurredAt(scopeManifests),
+            participants: scopeParticipants(scopeManifests),
+            container_title: scopeContainerTitle(scopeManifests),
+            conversation_id: scopeConversationId(scopeManifests),
+            session_status: session.status,
+            question_state: questionStateForSession(session),
+            canonical_targets: useCanonicalTargets ? selectedTargets.map((page2) => page2.path) : [],
+            evidence_state: evidenceState
+          })
+        )
+      );
+      const page = parseStoredPage(relativePath, content, {
+        createdAt,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      if (!useCanonicalTargets && !selectedTargets.length) {
+        session.targetedPagePaths = uniqueStrings4([...session.targetedPagePaths, relativePath]);
+      }
+      return { page, content, label: "guided-update" };
+    })
   );
-  const workingDir = await managedSourceWorkingDir(rootDir, id);
-  await fs22.rm(workingDir, { recursive: true, force: true });
-  return { removed: target };
-}
-
-// src/viewer.ts
-import { execFile as execFile2 } from "child_process";
-import fs23 from "fs/promises";
-import http from "http";
-import path28 from "path";
-import { promisify as promisify2 } from "util";
-import matter12 from "gray-matter";
-import mime2 from "mime-types";
-
-// src/graph-presentation.ts
-var OVERVIEW_THRESHOLD = 5e3;
-var OVERVIEW_NODE_BUDGET = 1500;
-function nodePriority(node, pinnedNodeIds) {
-  return [pinnedNodeIds.has(node.id) ? 0 : 1, -(node.degree ?? 0), -(node.bridgeScore ?? 0), node.label, node.id];
-}
-function compareTuples(left, right) {
-  const length = Math.max(left.length, right.length);
-  for (let index = 0; index < length; index += 1) {
-    const leftValue = left[index];
-    const rightValue = right[index];
-    if (leftValue === rightValue) {
-      continue;
-    }
-    if (typeof leftValue === "number" && typeof rightValue === "number") {
-      return leftValue - rightValue;
-    }
-    return String(leftValue ?? "").localeCompare(String(rightValue ?? ""));
-  }
-  return 0;
 }
-function survivingHyperedges(hyperedges, sampledNodeIds) {
-  return hyperedges.filter((hyperedge) => hyperedge.nodeIds.filter((nodeId) => sampledNodeIds.has(nodeId)).length >= 2);
-}
-function pinnedNodeIdsForReport(report) {
-  if (!report) {
-    return /* @__PURE__ */ new Set();
-  }
-  return /* @__PURE__ */ new Set([
-    ...report.godNodes.map((node) => node.nodeId),
-    ...report.bridgeNodes.map((node) => node.nodeId),
-    ...report.surprisingConnections.flatMap((connection) => [connection.sourceNodeId, connection.targetNodeId])
-  ]);
-}
-function sampleGraphNodes(graph, report, nodeBudget = OVERVIEW_NODE_BUDGET) {
-  const pinned = pinnedNodeIdsForReport(report);
-  const nodeById2 = new Map(graph.nodes.map((node) => [node.id, node]));
-  const selected = new Set([...pinned].filter((nodeId) => nodeById2.has(nodeId)));
-  const sortedCommunities2 = [...graph.communities ?? []].sort((left, right) => {
-    const leftNodes = left.nodeIds.map((nodeId) => nodeById2.get(nodeId)).filter((node) => Boolean(node));
-    const rightNodes = right.nodeIds.map((nodeId) => nodeById2.get(nodeId)).filter((node) => Boolean(node));
-    const leftFirstParty = leftNodes.filter((node) => node.sourceClass === "first_party").length;
-    const rightFirstParty = rightNodes.filter((node) => node.sourceClass === "first_party").length;
-    return compareTuples(
-      [-leftFirstParty, -leftNodes.length, left.label, left.id],
-      [-rightFirstParty, -rightNodes.length, right.label, right.id]
-    );
-  });
-  for (const community of sortedCommunities2) {
-    const communityNodes = community.nodeIds.map((nodeId) => nodeById2.get(nodeId)).filter((node) => Boolean(node)).sort((left, right) => compareTuples(nodePriority(left, pinned), nodePriority(right, pinned)));
-    for (const node of communityNodes) {
-      if (selected.size >= nodeBudget && !pinned.has(node.id)) {
-        break;
-      }
-      selected.add(node.id);
-    }
-    if (selected.size >= nodeBudget) {
-      break;
-    }
-  }
-  if (selected.size < nodeBudget) {
-    for (const node of [...graph.nodes].sort((left, right) => compareTuples(nodePriority(left, pinned), nodePriority(right, pinned)))) {
-      if (selected.size >= nodeBudget && !pinned.has(node.id)) {
-        break;
-      }
-      selected.add(node.id);
-    }
+async function stageSourceGuideForScope(rootDir, scope, options = {}) {
+  const { session, statePath } = await prepareGuidedSourceSession(rootDir, scope, options.answers);
+  const briefPath = scope.briefPath ?? session.briefPath ?? await writeSourceBriefForScope(rootDir, scope) ?? void 0;
+  session.briefPath = briefPath;
+  if (briefPath) {
+    await refreshVaultAfterOutputSave(rootDir);
   }
-  return selected;
-}
-function buildViewerGraphArtifact(graph, options = {}) {
-  const threshold = options.threshold ?? OVERVIEW_THRESHOLD;
-  const nodeBudget = options.nodeBudget ?? OVERVIEW_NODE_BUDGET;
-  const totalCommunities = graph.communities?.length ?? 0;
-  if (options.full || graph.nodes.length <= threshold) {
+  if (answeredGuidedSessionQuestions(session.questions).length === 0) {
+    session.status = "awaiting_input";
+    const persisted2 = await persistSourceSessionPage(rootDir, scope, session);
+    session.sessionPath = persisted2.sessionPath;
+    await writeGuidedSourceSession(rootDir, session);
+    await refreshVaultAfterOutputSave(rootDir);
     return {
-      ...graph,
-      presentation: {
-        mode: "full",
-        threshold,
-        nodeBudget,
-        totalNodes: graph.nodes.length,
-        displayedNodes: graph.nodes.length,
-        totalEdges: graph.edges.length,
-        displayedEdges: graph.edges.length,
-        totalCommunities,
-        displayedCommunities: totalCommunities
-      }
+      sourceId: scope.id,
+      sessionId: session.sessionId,
+      sessionPath: persisted2.sessionPath,
+      sessionStatePath: statePath,
+      status: session.status,
+      questions: session.questions,
+      awaitingInput: true,
+      targetedPagePaths: session.targetedPagePaths,
+      stagedUpdatePaths: session.stagedUpdatePaths,
+      briefPath,
+      staged: false
     };
   }
-  const sampledNodeIds = sampleGraphNodes(graph, options.report, nodeBudget);
-  const nodes = graph.nodes.filter((node) => sampledNodeIds.has(node.id));
-  const edges = graph.edges.filter((edge) => sampledNodeIds.has(edge.source) && sampledNodeIds.has(edge.target));
-  const hyperedges = survivingHyperedges(graph.hyperedges ?? [], sampledNodeIds);
-  const communities = (graph.communities ?? []).map((community) => ({
-    ...community,
-    nodeIds: community.nodeIds.filter((nodeId) => sampledNodeIds.has(nodeId))
-  })).filter((community) => community.nodeIds.length > 0);
-  return {
-    ...graph,
-    nodes,
-    edges,
-    hyperedges,
-    communities,
-    presentation: {
-      mode: "overview",
-      threshold,
-      nodeBudget,
-      totalNodes: graph.nodes.length,
-      displayedNodes: nodes.length,
-      totalEdges: graph.edges.length,
-      displayedEdges: edges.length,
-      totalCommunities,
-      displayedCommunities: communities.length
-    }
-  };
-}
-
-// src/watch.ts
-import path27 from "path";
-import process3 from "process";
-import chokidar from "chokidar";
-var MAX_BACKOFF_MS = 3e4;
-var BACKOFF_THRESHOLD = 3;
-var CRITICAL_THRESHOLD = 10;
-var REPO_WATCH_IGNORES = /* @__PURE__ */ new Set([".git", ".venv"]);
-var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".ts",
-  ".tsx",
-  ".mts",
-  ".cts",
-  ".js",
-  ".jsx",
-  ".mjs",
-  ".cjs",
-  ".py",
-  ".go",
-  ".rs",
-  ".java",
-  ".kt",
-  ".kts",
-  ".scala",
-  ".sc",
-  ".dart",
-  ".lua",
-  ".zig",
-  ".cs",
-  ".php",
-  ".rb",
-  ".swift",
-  ".c",
-  ".h",
-  ".cpp",
-  ".cc",
-  ".cxx",
-  ".hpp",
-  ".hxx",
-  ".sh",
-  ".bash",
-  ".zsh",
-  ".ps1",
-  ".psm1",
-  ".ex",
-  ".exs",
-  ".jl",
-  ".r",
-  ".R"
-]);
-var FILE_CHANGE_RE = /^(?:add|change|unlink):(.+)$/;
-function isCodeOnlyChange(reasons) {
-  for (const reason of reasons) {
-    const match = reason.match(FILE_CHANGE_RE);
-    if (!match) return false;
-    const ext = path27.extname(match[1]).toLowerCase();
-    if (!ext || !CODE_EXTENSIONS.has(ext)) return false;
-  }
-  return reasons.size > 0;
+  session.status = "ready_to_stage";
+  await writeGuidedSourceSession(rootDir, session);
+  const reviewOutput = await buildSourceReviewStagedPage(rootDir, scope);
+  const guideOutput = await buildSourceGuideStagedPage(rootDir, {
+    ...scope,
+    briefPath
+  });
+  const guidedUpdates = await buildGuidedUpdatePages(rootDir, scope, session);
+  session.stagedUpdatePaths = guidedUpdates.map((item) => item.page.path);
+  const approval = await stageGeneratedOutputPages(
+    rootDir,
+    [
+      { page: reviewOutput.page, content: reviewOutput.content, label: "source-review" },
+      { page: guideOutput.page, content: guideOutput.content, label: "source-guide" },
+      ...guidedUpdates
+    ],
+    {
+      bundleType: "guided-session",
+      title: `Guided Session: ${scope.title}`,
+      sourceSessionId: session.sessionId
+    }
+  );
+  session.status = "staged";
+  session.reviewPath = path27.join(approval.approvalDir, "wiki", reviewOutput.page.path);
+  session.guidePath = path27.join(approval.approvalDir, "wiki", guideOutput.page.path);
+  session.approvalId = approval.approvalId;
+  session.approvalDir = approval.approvalDir;
+  const persisted = await persistSourceSessionPage(rootDir, scope, session);
+  session.sessionPath = persisted.sessionPath;
+  await writeGuidedSourceSession(rootDir, session);
+  await refreshVaultAfterOutputSave(rootDir);
+  return {
+    sourceId: scope.id,
+    pageId: guideOutput.page.id,
+    guidePath: session.guidePath,
+    reviewPageId: reviewOutput.page.id,
+    reviewPath: session.reviewPath,
+    sessionId: session.sessionId,
+    sessionPath: persisted.sessionPath,
+    sessionStatePath: statePath,
+    status: session.status,
+    questions: session.questions,
+    targetedPagePaths: session.targetedPagePaths,
+    stagedUpdatePaths: session.stagedUpdatePaths,
+    briefPath,
+    staged: true,
+    approvalId: approval.approvalId,
+    approvalDir: approval.approvalDir
+  };
 }
-function hasNonCodeChanges(reasons) {
-  for (const reason of reasons) {
-    const match = reason.match(FILE_CHANGE_RE);
-    if (!match) return true;
-    const ext = path27.extname(match[1]).toLowerCase();
-    if (!ext || !CODE_EXTENSIONS.has(ext)) return true;
-  }
-  return false;
+function scopeFromManagedSource(source) {
+  return {
+    id: source.id,
+    title: source.title,
+    sourceIds: source.sourceIds,
+    kind: source.kind,
+    briefPath: source.briefPath
+  };
 }
-function collectNonCodePaths(reasons) {
-  const result = [];
-  for (const reason of reasons) {
-    const match = reason.match(FILE_CHANGE_RE);
-    if (!match) {
-      result.push(reason);
-      continue;
-    }
-    const ext = path27.extname(match[1]).toLowerCase();
-    if (!ext || !CODE_EXTENSIONS.has(ext)) result.push(match[1]);
-  }
-  return result;
+function scopeFromManifest(manifest, manifests) {
+  const groupId = manifest.sourceGroupId ?? manifest.sourceId;
+  return {
+    id: groupId,
+    title: manifest.sourceGroupTitle ?? manifest.title,
+    sourceIds: manifest.sourceGroupId ? manifests.filter((candidate) => candidate.sourceGroupId === manifest.sourceGroupId).map((candidate) => candidate.sourceId) : [manifest.sourceId],
+    kind: manifest.sourceKind
+  };
 }
-function hasIgnoredRepoSegment(baseDir, targetPath) {
-  const relativePath = path27.relative(baseDir, targetPath);
-  if (!relativePath || relativePath.startsWith("..")) {
-    return false;
+async function resolveSourceScope(rootDir, id) {
+  const managedSources = await loadManagedSources(rootDir);
+  const managedSource = managedSources.find((source) => source.id === id);
+  if (managedSource) {
+    return scopeFromManagedSource(managedSource);
+  }
+  const latestSession = await findLatestGuidedSourceSessionByScope(rootDir, id);
+  if (latestSession) {
+    return {
+      id: latestSession.scopeId,
+      title: latestSession.scopeTitle,
+      sourceIds: latestSession.sourceIds
+    };
+  }
+  const manifests = await listManifests(rootDir);
+  const manifest = manifests.find((candidate) => candidate.sourceId === id) ?? manifests.find((candidate) => candidate.sourceGroupId === id);
+  if (!manifest) {
+    return null;
   }
-  return relativePath.split(path27.sep).some((segment) => REPO_WATCH_IGNORES.has(segment));
+  return scopeFromManifest(manifest, manifests);
 }
-function workspaceIgnoreRoots(rootDir, paths) {
-  return [
-    paths.rawDir,
-    paths.wikiDir,
-    paths.stateDir,
-    paths.agentDir,
-    paths.inboxDir,
-    path27.join(rootDir, ".claude"),
-    path27.join(rootDir, ".cursor"),
-    path27.join(rootDir, ".obsidian")
-  ].map((candidate) => path27.resolve(candidate));
+async function reviewSourceScope(rootDir, scope) {
+  return await stageSourceReviewForScope(rootDir, scope);
 }
-async function resolveWatchTargets(rootDir, paths, options) {
-  const targets = /* @__PURE__ */ new Set([path27.resolve(paths.inboxDir)]);
-  if (options.repo) {
-    for (const repoRoot of await listTrackedRepoRoots(rootDir)) {
-      targets.add(path27.resolve(repoRoot));
-    }
+async function guideSourceScope(rootDir, scope, options = {}) {
+  return await stageSourceGuideForScope(rootDir, scope, options);
+}
+async function reviewManagedSource(rootDir, id) {
+  const scope = await resolveSourceScope(rootDir, id);
+  if (!scope) {
+    throw new Error(`Managed source or source id not found: ${id}`);
   }
-  return [...targets].sort((left, right) => left.localeCompare(right));
+  if (!await loadVaultConfig(rootDir).then(({ paths }) => fileExists(paths.graphPath))) {
+    await compileVault(rootDir, {});
+  }
+  return await stageSourceReviewForScope(rootDir, scope);
 }
-async function performWatchCycle(rootDir, paths, options, codeOnly = false) {
-  const imported = await importInbox(rootDir, paths.inboxDir);
-  const repoSync = options.repo ? await syncTrackedReposForWatch(rootDir) : null;
-  const compile = await compileVault(rootDir, { codeOnly });
-  const pendingSemanticRefresh = repoSync ? await mergePendingSemanticRefresh(rootDir, repoSync.pendingSemanticRefresh) : await readPendingSemanticRefresh(rootDir);
-  const stalePagePaths = await markPagesStaleForSources(
-    rootDir,
-    pendingSemanticRefresh.map((entry) => entry.sourceId).filter((sourceId) => Boolean(sourceId))
-  );
-  const lintFindingCount = options.lint ? (await lintVault(rootDir)).length : void 0;
-  return {
-    watchedRepoRoots: repoSync?.repoRoots ?? [],
-    importedCount: imported.imported.length,
-    scannedCount: imported.scannedCount,
-    attachmentCount: imported.attachmentCount,
-    repoImportedCount: repoSync?.imported.length ?? 0,
-    repoUpdatedCount: repoSync?.updated.length ?? 0,
-    repoRemovedCount: repoSync?.removed.length ?? 0,
-    repoScannedCount: repoSync?.scannedCount ?? 0,
-    pendingSemanticRefreshCount: pendingSemanticRefresh.length,
-    pendingSemanticRefreshPaths: pendingSemanticRefresh.map((entry) => entry.path),
-    changedPages: [.../* @__PURE__ */ new Set([...compile.changedPages, ...stalePagePaths])],
-    lintFindingCount
-  };
+async function guideManagedSource(rootDir, id, options = {}) {
+  const scope = await resolveSourceScope(rootDir, id);
+  if (!scope) {
+    throw new Error(`Managed source or source id not found: ${id}`);
+  }
+  if (!await loadVaultConfig(rootDir).then(({ paths }) => fileExists(paths.graphPath))) {
+    await compileVault(rootDir, {});
+  }
+  return await stageSourceGuideForScope(rootDir, scope, options);
 }
-async function runWatchCycle(rootDir, options = {}) {
-  const { paths } = await initWorkspace(rootDir);
-  const startedAt = /* @__PURE__ */ new Date();
-  let success = true;
-  let error;
-  let result = {
-    watchedRepoRoots: [],
-    importedCount: 0,
-    scannedCount: 0,
-    attachmentCount: 0,
-    repoImportedCount: 0,
-    repoUpdatedCount: 0,
-    repoRemovedCount: 0,
-    repoScannedCount: 0,
-    pendingSemanticRefreshCount: 0,
-    pendingSemanticRefreshPaths: [],
-    changedPages: []
-  };
-  try {
-    result = await performWatchCycle(rootDir, paths, options, options.codeOnly ?? false);
-    return result;
-  } catch (caught) {
-    success = false;
-    error = caught instanceof Error ? caught.message : String(caught);
-    throw caught;
-  } finally {
-    const finishedAt = /* @__PURE__ */ new Date();
-    await recordSession(rootDir, {
-      operation: "watch",
-      title: `Watch cycle for ${paths.inboxDir}${options.repo ? " and tracked repos" : ""}`,
-      startedAt: startedAt.toISOString(),
-      finishedAt: finishedAt.toISOString(),
-      success,
-      error,
-      changedPages: result.changedPages,
-      lintFindingCount: result.lintFindingCount,
-      lines: [
-        "reasons=once",
-        `imported=${result.importedCount}`,
-        `scanned=${result.scannedCount}`,
-        `attachments=${result.attachmentCount}`,
-        `repo_scanned=${result.repoScannedCount}`,
-        `repo_imported=${result.repoImportedCount}`,
-        `repo_updated=${result.repoUpdatedCount}`,
-        `repo_removed=${result.repoRemovedCount}`,
-        `pending_semantic_refresh=${result.pendingSemanticRefreshCount}`,
-        `lint=${result.lintFindingCount ?? 0}`
-      ]
-    });
-    await appendWatchRun(rootDir, {
-      startedAt: startedAt.toISOString(),
-      finishedAt: finishedAt.toISOString(),
-      durationMs: finishedAt.getTime() - startedAt.getTime(),
-      inputDir: paths.inboxDir,
-      reasons: ["once"],
-      importedCount: result.importedCount + result.repoImportedCount + result.repoUpdatedCount,
-      scannedCount: result.scannedCount + result.repoScannedCount,
-      attachmentCount: result.attachmentCount,
-      changedPages: result.changedPages,
-      repoImportedCount: result.repoImportedCount,
-      repoUpdatedCount: result.repoUpdatedCount,
-      repoRemovedCount: result.repoRemovedCount,
-      repoScannedCount: result.repoScannedCount,
-      pendingSemanticRefreshCount: result.pendingSemanticRefreshCount,
-      pendingSemanticRefreshPaths: result.pendingSemanticRefreshPaths,
-      lintFindingCount: result.lintFindingCount,
-      success,
-      error
-    });
-    await writeWatchStatusArtifact(rootDir, {
-      generatedAt: finishedAt.toISOString(),
-      watchedRepoRoots: result.watchedRepoRoots,
-      lastRun: {
-        startedAt: startedAt.toISOString(),
-        finishedAt: finishedAt.toISOString(),
-        durationMs: finishedAt.getTime() - startedAt.getTime(),
-        inputDir: paths.inboxDir,
-        reasons: ["once"],
-        importedCount: result.importedCount + result.repoImportedCount + result.repoUpdatedCount,
-        scannedCount: result.scannedCount + result.repoScannedCount,
-        attachmentCount: result.attachmentCount,
-        changedPages: result.changedPages,
-        repoImportedCount: result.repoImportedCount,
-        repoUpdatedCount: result.repoUpdatedCount,
-        repoRemovedCount: result.repoRemovedCount,
-        repoScannedCount: result.repoScannedCount,
-        pendingSemanticRefreshCount: result.pendingSemanticRefreshCount,
-        pendingSemanticRefreshPaths: result.pendingSemanticRefreshPaths,
-        lintFindingCount: result.lintFindingCount,
-        success,
-        error
+async function resumeSourceSession(rootDir, id, options = {}) {
+  const existingSession = await readGuidedSourceSession(rootDir, id);
+  if (existingSession) {
+    return await stageSourceGuideForScope(
+      rootDir,
+      {
+        id: existingSession.scopeId,
+        title: existingSession.scopeTitle,
+        sourceIds: existingSession.sourceIds,
+        kind: existingSession.kind,
+        briefPath: existingSession.briefPath
       },
-      pendingSemanticRefresh: await readPendingSemanticRefresh(rootDir)
-    });
+      options
+    );
+  }
+  const scope = await resolveSourceScope(rootDir, id);
+  if (!scope) {
+    throw new Error(`Managed source, source scope, or guided session not found: ${id}`);
+  }
+  return await stageSourceGuideForScope(rootDir, scope, options);
+}
+function shouldCompile(changedSources, graphExists, compileRequested) {
+  return compileRequested && (!graphExists || changedSources.length > 0);
+}
+async function shouldRefreshBriefForManagedSource(source, options) {
+  if (options.compilePerformed || options.changed) {
+    return true;
+  }
+  if (!source.briefPath) {
+    return true;
   }
+  return !await fileExists(source.briefPath);
 }
-async function watchVault(rootDir, options = {}) {
-  const { paths } = await initWorkspace(rootDir);
-  const baseDebounceMs = options.debounceMs ?? 900;
-  const ignoredRoots = workspaceIgnoreRoots(rootDir, paths);
-  const inboxWatchRoot = path27.resolve(paths.inboxDir);
-  let watchTargets = await resolveWatchTargets(rootDir, paths, options);
-  let timer;
-  let running = false;
-  let pending = false;
-  let closed = false;
-  let consecutiveFailures = 0;
-  let currentDebounceMs = baseDebounceMs;
-  const reasons = /* @__PURE__ */ new Set();
-  let activeCycle = null;
-  const watcher = chokidar.watch(watchTargets, {
-    ignoreInitial: true,
-    usePolling: true,
-    interval: 100,
-    ignored: (targetPath) => {
-      const absolutePath = path27.resolve(targetPath);
-      const primaryTarget = watchTargets.filter((watchTarget) => isPathWithin(watchTarget, absolutePath)).sort((left, right) => right.length - left.length)[0] ?? null;
-      if (!primaryTarget) {
-        return false;
-      }
-      if (primaryTarget !== inboxWatchRoot && ignoredRoots.some((ignoreRoot) => isPathWithin(ignoreRoot, absolutePath))) {
-        return true;
-      }
-      return hasIgnoredRepoSegment(primaryTarget, absolutePath);
-    },
-    awaitWriteFinish: {
-      stabilityThreshold: Math.max(250, Math.floor(baseDebounceMs / 2)),
-      pollInterval: 100
-    }
-  });
-  const syncWatchTargets = async () => {
-    const nextTargets = await resolveWatchTargets(rootDir, paths, options);
-    const nextSet = new Set(nextTargets);
-    const currentSet = new Set(watchTargets);
-    const toRemove = watchTargets.filter((target) => !nextSet.has(target));
-    const toAdd = nextTargets.filter((target) => !currentSet.has(target));
-    if (toRemove.length > 0) {
-      await watcher.unwatch(toRemove);
-    }
-    if (toAdd.length > 0) {
-      await watcher.add(toAdd);
-    }
-    watchTargets = nextTargets;
-  };
-  const schedule = (reason) => {
-    if (closed) {
-      return;
-    }
-    reasons.add(reason);
-    pending = true;
-    if (timer) {
-      clearTimeout(timer);
-    }
-    timer = setTimeout(() => {
-      const cycle = runCycle();
-      activeCycle = cycle.finally(() => {
-        if (activeCycle === cycle) {
-          activeCycle = null;
-        }
-      });
-    }, currentDebounceMs);
+async function listManagedSourceRecords(rootDir) {
+  await ensureManagedSourcesArtifact(rootDir);
+  return await loadManagedSources(rootDir);
+}
+async function addManagedSource(rootDir, input, options = {}) {
+  const compileRequested = options.compile ?? true;
+  const guideRequested = options.guide ?? false;
+  const briefRequested = guideRequested ? true : options.brief ?? true;
+  const reviewRequested = guideRequested ? false : options.review ?? false;
+  const sources = await loadManagedSources(rootDir);
+  const resolved = await resolveManagedSourceInput(rootDir, input);
+  const existing = sources.find((candidate) => matchesManagedSourceSpec(candidate, resolved));
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const source = existing ?? {
+    id: resolved.kind === "directory" || resolved.kind === "file" ? stableManagedSourceId(resolved.kind, path27.resolve(resolved.path), resolved.title) : stableManagedSourceId(resolved.kind, resolved.url, resolved.title),
+    kind: resolved.kind,
+    title: resolved.title,
+    path: resolved.kind === "directory" || resolved.kind === "file" ? resolved.path : void 0,
+    repoRoot: resolved.kind === "directory" ? resolved.repoRoot : void 0,
+    url: resolved.kind === "directory" || resolved.kind === "file" ? void 0 : resolved.url,
+    createdAt: now,
+    updatedAt: now,
+    status: "ready",
+    sourceIds: []
   };
-  const runCycle = async () => {
-    if (running || closed || !pending) {
-      return;
-    }
-    pending = false;
-    running = true;
-    const startedAt = /* @__PURE__ */ new Date();
-    const detectedCodeOnly = isCodeOnlyChange(reasons);
-    const hasDeferredNonCode = !detectedCodeOnly && hasNonCodeChanges(reasons);
-    const codeOnlyChange = options.codeOnly || detectedCodeOnly || hasDeferredNonCode;
-    const runReasons = [...reasons];
-    reasons.clear();
-    if (hasDeferredNonCode) {
-      const nonCodePaths = collectNonCodePaths(new Set(runReasons));
-      process3.stderr.write(
-        `[swarmvault watch] Non-code changes detected (${nonCodePaths.length} file(s)) \u2014 run \`swarmvault compile\` to include LLM re-analysis.
-`
-      );
-    } else if (codeOnlyChange) {
-      process3.stderr.write("[swarmvault watch] Code-only changes detected \u2014 skipping LLM re-analysis.\n");
-    }
-    let importedCount = 0;
-    let scannedCount = 0;
-    let attachmentCount = 0;
-    let repoImportedCount = 0;
-    let repoUpdatedCount = 0;
-    let repoRemovedCount = 0;
-    let repoScannedCount = 0;
-    let watchedRepoRoots = [];
-    let pendingSemanticRefreshCount = 0;
-    let pendingSemanticRefreshPaths = [];
-    let changedPages = [];
-    let lintFindingCount;
-    let success = true;
-    let error;
-    try {
-      const result = await performWatchCycle(rootDir, paths, options, codeOnlyChange);
-      importedCount = result.importedCount;
-      scannedCount = result.scannedCount;
-      attachmentCount = result.attachmentCount;
-      repoImportedCount = result.repoImportedCount;
-      repoUpdatedCount = result.repoUpdatedCount;
-      repoRemovedCount = result.repoRemovedCount;
-      repoScannedCount = result.repoScannedCount;
-      watchedRepoRoots = result.watchedRepoRoots;
-      pendingSemanticRefreshCount = result.pendingSemanticRefreshCount;
-      pendingSemanticRefreshPaths = result.pendingSemanticRefreshPaths;
-      changedPages = result.changedPages;
-      lintFindingCount = result.lintFindingCount;
-      consecutiveFailures = 0;
-      currentDebounceMs = baseDebounceMs;
-      await syncWatchTargets();
-    } catch (caught) {
-      success = false;
-      error = caught instanceof Error ? caught.message : String(caught);
-      consecutiveFailures++;
-      pending = true;
-      if (consecutiveFailures >= CRITICAL_THRESHOLD) {
-        process3.stderr.write(
-          `[swarmvault watch] ${consecutiveFailures} consecutive failures. Check vault state. Continuing at max backoff.
-`
-        );
-      }
-      if (consecutiveFailures >= BACKOFF_THRESHOLD) {
-        const multiplier = 2 ** (consecutiveFailures - BACKOFF_THRESHOLD);
-        currentDebounceMs = Math.min(baseDebounceMs * multiplier, MAX_BACKOFF_MS);
-      }
-    } finally {
-      const finishedAt = /* @__PURE__ */ new Date();
-      try {
-        await recordSession(rootDir, {
-          operation: "watch",
-          title: `Watch cycle for ${paths.inboxDir}${options.repo ? " and tracked repos" : ""}`,
-          startedAt: startedAt.toISOString(),
-          finishedAt: finishedAt.toISOString(),
-          success,
-          error,
-          changedPages,
-          lintFindingCount,
-          lines: [
-            `reasons=${runReasons.join(",") || "none"}`,
-            `code_only=${codeOnlyChange}`,
-            `imported=${importedCount}`,
-            `scanned=${scannedCount}`,
-            `attachments=${attachmentCount}`,
-            `repo_scanned=${repoScannedCount}`,
-            `repo_imported=${repoImportedCount}`,
-            `repo_updated=${repoUpdatedCount}`,
-            `repo_removed=${repoRemovedCount}`,
-            `lint=${lintFindingCount ?? 0}`
-          ]
-        });
-      } catch {
-        process3.stderr.write("[swarmvault watch] Failed to record session log.\n");
-      }
-      try {
-        await appendWatchRun(rootDir, {
-          startedAt: startedAt.toISOString(),
-          finishedAt: finishedAt.toISOString(),
-          durationMs: finishedAt.getTime() - startedAt.getTime(),
-          inputDir: paths.inboxDir,
-          reasons: runReasons,
-          importedCount: importedCount + repoImportedCount + repoUpdatedCount,
-          scannedCount: scannedCount + repoScannedCount,
-          attachmentCount,
-          changedPages,
-          repoImportedCount,
-          repoUpdatedCount,
-          repoRemovedCount,
-          repoScannedCount,
-          pendingSemanticRefreshCount,
-          pendingSemanticRefreshPaths,
-          lintFindingCount,
-          success,
-          error
-        });
-      } catch {
-        process3.stderr.write("[swarmvault watch] Failed to append watch run.\n");
-      }
-      try {
-        await writeWatchStatusArtifact(rootDir, {
-          generatedAt: finishedAt.toISOString(),
-          watchedRepoRoots,
-          lastRun: {
-            startedAt: startedAt.toISOString(),
-            finishedAt: finishedAt.toISOString(),
-            durationMs: finishedAt.getTime() - startedAt.getTime(),
-            inputDir: paths.inboxDir,
-            reasons: runReasons,
-            importedCount: importedCount + repoImportedCount + repoUpdatedCount,
-            scannedCount: scannedCount + repoScannedCount,
-            attachmentCount,
-            changedPages,
-            repoImportedCount,
-            repoUpdatedCount,
-            repoRemovedCount,
-            repoScannedCount,
-            pendingSemanticRefreshCount,
-            pendingSemanticRefreshPaths,
-            lintFindingCount,
-            success,
-            error
-          },
-          pendingSemanticRefresh: await readPendingSemanticRefresh(rootDir)
-        });
-      } catch {
-        process3.stderr.write("[swarmvault watch] Failed to write watch status artifact.\n");
-      }
-      running = false;
-      if (pending && !closed) {
-        schedule("queued");
-      }
-    }
+  const synced = await syncManagedSource(rootDir, source, options);
+  if (synced.lastSyncStatus === "error") {
+    throw new Error(synced.lastError ?? `Failed to add managed source ${synced.id}.`);
+  }
+  const graphExists = await loadVaultConfig(rootDir).then(({ paths }) => fileExists(paths.graphPath));
+  let compile;
+  if (shouldCompile(synced.changed ? [synced] : [], graphExists, compileRequested)) {
+    compile = await compileVault(rootDir, {});
+  }
+  let briefGenerated = false;
+  let briefPath;
+  if (compileRequested && briefRequested && synced.status === "ready" && await shouldRefreshBriefForManagedSource(synced, {
+    compilePerformed: Boolean(compile),
+    changed: synced.changed
+  })) {
+    const briefs = await generateBriefsForSources(rootDir, [synced]);
+    briefPath = briefs.get(synced.id);
+    briefGenerated = Boolean(briefPath);
+  }
+  const nextSource = {
+    ...synced,
+    briefPath: briefPath ?? synced.briefPath,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  const reasonForPath = (targetPath) => {
-    const baseDir = watchTargets.filter((watchTarget) => isPathWithin(watchTarget, path27.resolve(targetPath))).sort((left, right) => right.length - left.length)[0] ?? paths.inboxDir;
-    return path27.relative(baseDir, targetPath) || ".";
+  const nextSources = existing ? sources.map((candidate) => candidate.id === nextSource.id ? nextSource : candidate) : [...sources, nextSource];
+  await saveManagedSources(rootDir, nextSources);
+  const review = reviewRequested && nextSource.status === "ready" ? await stageSourceReviewForScope(rootDir, scopeFromManagedSource(nextSource)) : void 0;
+  const guide = guideRequested && nextSource.status === "ready" ? await stageSourceGuideForScope(
+    rootDir,
+    {
+      ...scopeFromManagedSource(nextSource),
+      briefPath: nextSource.briefPath
+    },
+    { answers: options.guideAnswers }
+  ) : void 0;
+  return {
+    source: nextSource,
+    compile,
+    briefGenerated,
+    review,
+    guide
   };
-  watcher.on("add", (filePath) => schedule(`add:${reasonForPath(filePath)}`)).on("change", (filePath) => schedule(`change:${reasonForPath(filePath)}`)).on("unlink", (filePath) => schedule(`unlink:${reasonForPath(filePath)}`)).on("addDir", (dirPath) => schedule(`addDir:${reasonForPath(dirPath)}`)).on("unlinkDir", (dirPath) => schedule(`unlinkDir:${reasonForPath(dirPath)}`)).on("error", (caught) => schedule(`error:${caught instanceof Error ? caught.message : String(caught)}`));
-  await new Promise((resolve, reject) => {
-    const handleReady = () => {
-      watcher.off("error", handleError);
-      resolve();
-    };
-    const handleError = (caught) => {
-      watcher.off("ready", handleReady);
-      reject(caught);
+}
+async function reloadManagedSources(rootDir, options = {}) {
+  const compileRequested = options.compile ?? true;
+  const guideRequested = options.guide ?? false;
+  const briefRequested = guideRequested ? true : options.brief ?? true;
+  const reviewRequested = guideRequested ? false : options.review ?? false;
+  const sources = await loadManagedSources(rootDir);
+  const selected = options.all || !options.id ? sources : sources.filter((source) => source.id === options.id);
+  if (!selected.length) {
+    throw new Error(options.id ? `Managed source not found: ${options.id}` : "No managed sources registered.");
+  }
+  const syncedSources = [];
+  const changedSources = [];
+  for (const source of selected) {
+    const synced = await syncManagedSource(rootDir, source, options);
+    syncedSources.push(synced);
+    if (synced.changed) {
+      changedSources.push(synced);
+    }
+  }
+  const graphExists = await loadVaultConfig(rootDir).then(({ paths }) => fileExists(paths.graphPath));
+  let compile;
+  if (shouldCompile(changedSources, graphExists, compileRequested)) {
+    compile = await compileVault(rootDir, {});
+  }
+  const briefPaths = compileRequested && briefRequested ? await generateBriefsForSources(
+    rootDir,
+    syncedSources.filter((source) => source.status === "ready")
+  ) : /* @__PURE__ */ new Map();
+  const nextSources = sources.map((source) => {
+    const synced = syncedSources.find((candidate) => candidate.id === source.id);
+    if (!synced) {
+      return source;
+    }
+    return {
+      ...synced,
+      briefPath: briefPaths.get(synced.id) ?? synced.briefPath,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    watcher.once("ready", handleReady);
-    watcher.once("error", handleError);
   });
+  await saveManagedSources(rootDir, nextSources);
+  const reviews = reviewRequested ? await Promise.all(
+    nextSources.filter((source) => selected.some((candidate) => candidate.id === source.id)).filter((source) => source.status === "ready").map(async (source) => await stageSourceReviewForScope(rootDir, scopeFromManagedSource(source)))
+  ) : [];
+  const guides = guideRequested ? await Promise.all(
+    nextSources.filter((source) => selected.some((candidate) => candidate.id === source.id)).filter((source) => source.status === "ready").map(
+      async (source) => await stageSourceGuideForScope(
+        rootDir,
+        {
+          ...scopeFromManagedSource(source),
+          briefPath: source.briefPath
+        },
+        { answers: options.guideAnswers }
+      )
+    )
+  ) : [];
   return {
-    close: async () => {
-      closed = true;
-      if (timer) {
-        clearTimeout(timer);
+    sources: nextSources.filter((source) => selected.some((candidate) => candidate.id === source.id)),
+    compile,
+    briefPaths: [...briefPaths.values()],
+    reviews,
+    guides
+  };
+}
+async function deleteManagedSource(rootDir, id) {
+  const sources = await loadManagedSources(rootDir);
+  const target = sources.find((source) => source.id === id);
+  if (!target) {
+    throw new Error(`Managed source not found: ${id}`);
+  }
+  await saveManagedSources(
+    rootDir,
+    sources.filter((source) => source.id !== id)
+  );
+  const workingDir = await managedSourceWorkingDir(rootDir, id);
+  await fs22.rm(workingDir, { recursive: true, force: true });
+  return { removed: target };
+}
+
+// src/viewer.ts
+import { execFile as execFile2 } from "child_process";
+import fs23 from "fs/promises";
+import http from "http";
+import path28 from "path";
+import { promisify as promisify2 } from "util";
+import matter12 from "gray-matter";
+import mime2 from "mime-types";
+
+// src/graph-presentation.ts
+var OVERVIEW_THRESHOLD = 5e3;
+var OVERVIEW_NODE_BUDGET = 1500;
+function nodePriority(node, pinnedNodeIds) {
+  return [pinnedNodeIds.has(node.id) ? 0 : 1, -(node.degree ?? 0), -(node.bridgeScore ?? 0), node.label, node.id];
+}
+function compareTuples(left, right) {
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftValue = left[index];
+    const rightValue = right[index];
+    if (leftValue === rightValue) {
+      continue;
+    }
+    if (typeof leftValue === "number" && typeof rightValue === "number") {
+      return leftValue - rightValue;
+    }
+    return String(leftValue ?? "").localeCompare(String(rightValue ?? ""));
+  }
+  return 0;
+}
+function survivingHyperedges(hyperedges, sampledNodeIds) {
+  return hyperedges.filter((hyperedge) => hyperedge.nodeIds.filter((nodeId) => sampledNodeIds.has(nodeId)).length >= 2);
+}
+function pinnedNodeIdsForReport(report) {
+  if (!report) {
+    return /* @__PURE__ */ new Set();
+  }
+  return /* @__PURE__ */ new Set([
+    ...report.godNodes.map((node) => node.nodeId),
+    ...report.bridgeNodes.map((node) => node.nodeId),
+    ...report.surprisingConnections.flatMap((connection) => [connection.sourceNodeId, connection.targetNodeId])
+  ]);
+}
+function sampleGraphNodes(graph, report, nodeBudget = OVERVIEW_NODE_BUDGET) {
+  const pinned = pinnedNodeIdsForReport(report);
+  const nodeById2 = new Map(graph.nodes.map((node) => [node.id, node]));
+  const selected = new Set([...pinned].filter((nodeId) => nodeById2.has(nodeId)));
+  const sortedCommunities2 = [...graph.communities ?? []].sort((left, right) => {
+    const leftNodes = left.nodeIds.map((nodeId) => nodeById2.get(nodeId)).filter((node) => Boolean(node));
+    const rightNodes = right.nodeIds.map((nodeId) => nodeById2.get(nodeId)).filter((node) => Boolean(node));
+    const leftFirstParty = leftNodes.filter((node) => node.sourceClass === "first_party").length;
+    const rightFirstParty = rightNodes.filter((node) => node.sourceClass === "first_party").length;
+    return compareTuples(
+      [-leftFirstParty, -leftNodes.length, left.label, left.id],
+      [-rightFirstParty, -rightNodes.length, right.label, right.id]
+    );
+  });
+  for (const community of sortedCommunities2) {
+    const communityNodes = community.nodeIds.map((nodeId) => nodeById2.get(nodeId)).filter((node) => Boolean(node)).sort((left, right) => compareTuples(nodePriority(left, pinned), nodePriority(right, pinned)));
+    for (const node of communityNodes) {
+      if (selected.size >= nodeBudget && !pinned.has(node.id)) {
+        break;
       }
-      await watcher.close();
-      await activeCycle;
+      selected.add(node.id);
     }
-  };
+    if (selected.size >= nodeBudget) {
+      break;
+    }
+  }
+  if (selected.size < nodeBudget) {
+    for (const node of [...graph.nodes].sort((left, right) => compareTuples(nodePriority(left, pinned), nodePriority(right, pinned)))) {
+      if (selected.size >= nodeBudget && !pinned.has(node.id)) {
+        break;
+      }
+      selected.add(node.id);
+    }
+  }
+  return selected;
 }
-async function getWatchStatus(rootDir) {
-  const persisted = await readWatchStatusArtifact(rootDir);
-  const watchedRepoRoots = await listTrackedRepoRoots(rootDir);
-  const pendingSemanticRefresh = await readPendingSemanticRefresh(rootDir);
+function buildViewerGraphArtifact(graph, options = {}) {
+  const threshold = options.threshold ?? OVERVIEW_THRESHOLD;
+  const nodeBudget = options.nodeBudget ?? OVERVIEW_NODE_BUDGET;
+  const totalCommunities = graph.communities?.length ?? 0;
+  if (options.full || graph.nodes.length <= threshold) {
+    return {
+      ...graph,
+      presentation: {
+        mode: "full",
+        threshold,
+        nodeBudget,
+        totalNodes: graph.nodes.length,
+        displayedNodes: graph.nodes.length,
+        totalEdges: graph.edges.length,
+        displayedEdges: graph.edges.length,
+        totalCommunities,
+        displayedCommunities: totalCommunities
+      }
+    };
+  }
+  const sampledNodeIds = sampleGraphNodes(graph, options.report, nodeBudget);
+  const nodes = graph.nodes.filter((node) => sampledNodeIds.has(node.id));
+  const edges = graph.edges.filter((edge) => sampledNodeIds.has(edge.source) && sampledNodeIds.has(edge.target));
+  const hyperedges = survivingHyperedges(graph.hyperedges ?? [], sampledNodeIds);
+  const communities = (graph.communities ?? []).map((community) => ({
+    ...community,
+    nodeIds: community.nodeIds.filter((nodeId) => sampledNodeIds.has(nodeId))
+  })).filter((community) => community.nodeIds.length > 0);
   return {
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    watchedRepoRoots,
-    lastRun: persisted?.lastRun,
-    pendingSemanticRefresh
+    ...graph,
+    nodes,
+    edges,
+    hyperedges,
+    communities,
+    presentation: {
+      mode: "overview",
+      threshold,
+      nodeBudget,
+      totalNodes: graph.nodes.length,
+      displayedNodes: nodes.length,
+      totalEdges: graph.edges.length,
+      displayedEdges: edges.length,
+      totalCommunities,
+      displayedCommunities: communities.length
+    }
   };
 }
 
@@ -25771,7 +26222,7 @@ async function startGraphServer(rootDir, port, options = {}) {
           response.end(JSON.stringify({ error: "Missing approval id." }));
           return;
         }
-        const approval = await readApproval(rootDir, approvalId);
+        const approval = await readApproval(rootDir, approvalId, { diff: true });
         response.writeHead(200, { "content-type": "application/json" });
         response.end(JSON.stringify(approval));
         return;
@@ -25962,6 +26413,7 @@ async function exportGraphHtml(rootDir, outputPath, options = {}) {
   return path28.resolve(outputPath);
 }
 export {
+  DEFAULT_PROMOTION_CONFIG,
   acceptApproval,
   addInput,
   addManagedSource,
@@ -25981,6 +26433,7 @@ export {
   deleteManagedSource,
   estimatePageTokens,
   estimateTokens,
+  evaluateCandidateForPromotion,
   explainGraphVault,
   exploreVault,
   exportGraphFormat,
@@ -26019,6 +26472,7 @@ export {
   loadVaultSchema,
   loadVaultSchemas,
   pathGraphVault,
+  previewCandidatePromotions,
   promoteCandidate,
   pushGraphNeo4j,
   queryGraphVault,
@@ -26033,6 +26487,7 @@ export {
   resumeSourceSession,
   reviewManagedSource,
   reviewSourceScope,
+  runAutoPromotion,
   runSchedule,
   runWatchCycle,
   searchVault,