@swarmvaultai/engine 0.4.0 → 0.5.0

package/dist/index.js

@@ -21,7 +21,7 @@ import {
   uniqueBy,
   writeFileIfChanged,
   writeJsonFile
-} from "./chunk-CWLDFLH2.js";
+} from "./chunk-B3FC4J3P.js";
 
 // src/agents.ts
 import crypto from "crypto";
@@ -12885,7 +12885,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-2REAPKPO.js");
+  const { createProvider: createProvider2 } = await import("./registry-KVJAO5DF.js");
   return createProvider2(preferredProviderId, providerConfig, rootDir);
 }
 async function generateOutputArtifacts(rootDir, input) {
@@ -13263,6 +13263,8 @@ function approvalSummary(manifest) {
   return {
     approvalId: manifest.approvalId,
     createdAt: manifest.createdAt,
+    bundleType: manifest.bundleType,
+    title: manifest.title,
     entryCount: manifest.entries.length,
     pendingCount: manifest.entries.filter((entry) => entry.status === "pending").length,
     acceptedCount: manifest.entries.filter((entry) => entry.status === "accepted").length,
@@ -13374,6 +13376,9 @@ async function buildDashboardRecords(paths, graph, schemaHash, report) {
   const sourcePages = graph.pages.filter((page) => page.kind === "source");
   const reviewPages = graph.pages.filter((page) => page.kind === "output" && page.path.startsWith("outputs/source-reviews/"));
   const briefPages = graph.pages.filter((page) => page.kind === "output" && page.path.startsWith("outputs/source-briefs/"));
+  const guidePages = graph.pages.filter((page) => page.kind === "output" && page.path.startsWith("outputs/source-guides/"));
+  const conceptPages = graph.pages.filter((page) => page.kind === "concept" && page.status !== "candidate").slice(0, 16);
+  const entityPages = graph.pages.filter((page) => page.kind === "entity" && page.status !== "candidate").slice(0, 16);
   const manifests = graph.sources;
   const manifestBySourceId = new Map(manifests.map((manifest) => [manifest.sourceId, manifest]));
   const timelineManifests = manifests.filter((manifest) => manifestDetailValue(manifest, "occurred_at")).sort((left, right) => (manifestDetailValue(right, "occurred_at") ?? "").localeCompare(manifestDetailValue(left, "occurred_at") ?? "")).slice(0, 25);
@@ -13382,6 +13387,9 @@ async function buildDashboardRecords(paths, graph, schemaHash, report) {
   const openQuestions = uniqueStrings3(
     analyses.flatMap((analysis) => analysis.questions.map((question) => `${analysis.title}: ${question}`))
   ).slice(0, 20);
+  const stagedGuideBundles = (await Promise.all(
+    (await fs18.readdir(paths.approvalsDir, { withFileTypes: true }).catch(() => [])).filter((entry) => entry.isDirectory()).map(async (entry) => await readJsonFile(approvalManifestPath(paths, entry.name)))
+  )).filter((manifest) => Boolean(manifest)).filter((manifest) => manifest.bundleType === "guided_source").sort((left, right) => right.createdAt.localeCompare(left.createdAt)).slice(0, 12);
   const dashboards = [
     {
       relativePath: "dashboards/index.md",
@@ -13391,7 +13399,10 @@ async function buildDashboardRecords(paths, graph, schemaHash, report) {
           "# Dashboards",
           "",
           "- [[dashboards/recent-sources|Recent Sources]]",
+          "- [[dashboards/reading-log|Reading Log]]",
           "- [[dashboards/timeline|Timeline]]",
+          "- [[dashboards/source-guides|Source Guides]]",
+          "- [[dashboards/research-map|Research Map]]",
           "- [[dashboards/contradictions|Contradictions]]",
           "- [[dashboards/open-questions|Open Questions]]",
           "",
@@ -13464,6 +13475,49 @@ async function buildDashboardRecords(paths, graph, schemaHash, report) {
         }
       )
     },
+    {
+      relativePath: "dashboards/reading-log.md",
+      title: "Reading Log",
+      content: (metadata) => matter9.stringify(
+        [
+          "# Reading Log",
+          "",
+          ...timelineManifests.length ? timelineManifests.map((manifest) => {
+            const occurredAt = manifestDetailValue(manifest, "occurred_at") ?? manifest.updatedAt;
+            const participants = manifestDetailValue(manifest, "participants");
+            return `- ${occurredAt}: ${manifest.title}${participants ? ` (${participants})` : ""}`;
+          }) : recentSourcePages.map((page) => `- ${page.updatedAt}: [[${page.path.replace(/\.md$/, "")}|${page.title}]]`),
+          "",
+          "```dataview",
+          "TABLE occurred_at, source_type, participants, container_title",
+          'FROM "sources"',
+          "SORT occurred_at desc",
+          "LIMIT 25",
+          "```",
+          ""
+        ].join("\n"),
+        {
+          page_id: "dashboards:reading-log",
+          kind: "index",
+          title: "Reading Log",
+          tags: ["index", "dashboard", "reading-log"],
+          source_ids: timelineManifests.map((manifest) => manifest.sourceId),
+          project_ids: [],
+          node_ids: [],
+          freshness: "fresh",
+          status: metadata.status,
+          confidence: 1,
+          created_at: metadata.createdAt,
+          updated_at: metadata.updatedAt,
+          compiled_from: timelineManifests.map((manifest) => manifest.sourceId),
+          managed_by: metadata.managedBy,
+          backlinks: [],
+          schema_hash: schemaHash,
+          source_hashes: {},
+          source_semantic_hashes: {}
+        }
+      )
+    },
     {
       relativePath: "dashboards/timeline.md",
       title: "Timeline",
@@ -13507,6 +13561,112 @@ async function buildDashboardRecords(paths, graph, schemaHash, report) {
         }
       )
     },
+    {
+      relativePath: "dashboards/source-guides.md",
+      title: "Source Guides",
+      content: (metadata) => matter9.stringify(
+        [
+          "# Source Guides",
+          "",
+          ...guidePages.length ? guidePages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`) : ["- No accepted source guides yet."],
+          "",
+          "## Pending Guided Bundles",
+          "",
+          ...stagedGuideBundles.length ? stagedGuideBundles.map(
+            (bundle) => `- ${bundle.createdAt}: \`${bundle.approvalId}\`${bundle.title ? ` ${bundle.title}` : ""} (${bundle.entries.length} staged entr${bundle.entries.length === 1 ? "y" : "ies"})`
+          ) : ["- No staged guided bundles right now."],
+          "",
+          "```dataview",
+          'LIST FROM "outputs/source-guides"',
+          "SORT file.mtime desc",
+          "```",
+          ""
+        ].join("\n"),
+        {
+          page_id: "dashboards:source-guides",
+          kind: "index",
+          title: "Source Guides",
+          tags: ["index", "dashboard", "source-guides"],
+          source_ids: uniqueStrings3([
+            ...guidePages.flatMap((page) => page.sourceIds),
+            ...stagedGuideBundles.flatMap((bundle) => bundle.entries.flatMap((entry) => entry.sourceIds))
+          ]),
+          project_ids: [],
+          node_ids: [],
+          freshness: "fresh",
+          status: metadata.status,
+          confidence: 1,
+          created_at: metadata.createdAt,
+          updated_at: metadata.updatedAt,
+          compiled_from: uniqueStrings3([
+            ...guidePages.flatMap((page) => page.sourceIds),
+            ...stagedGuideBundles.flatMap((bundle) => bundle.entries.flatMap((entry) => entry.sourceIds))
+          ]),
+          managed_by: metadata.managedBy,
+          backlinks: [],
+          schema_hash: schemaHash,
+          source_hashes: {},
+          source_semantic_hashes: {}
+        }
+      )
+    },
+    {
+      relativePath: "dashboards/research-map.md",
+      title: "Research Map",
+      content: (metadata) => matter9.stringify(
+        [
+          "# Research Map",
+          "",
+          "## Canonical Concept Pages",
+          "",
+          ...conceptPages.length ? conceptPages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`) : ["- No concept pages yet."],
+          "",
+          "## Canonical Entity Pages",
+          "",
+          ...entityPages.length ? entityPages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`) : ["- No entity pages yet."],
+          "",
+          "## Recently Guided Sources",
+          "",
+          ...guidePages.length ? guidePages.slice(0, 8).map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`) : ["- No accepted source guides yet."],
+          ...report?.suggestedQuestions?.length ? ["", "## Suggested Questions", "", ...report.suggestedQuestions.slice(0, 8).map((question) => `- ${question}`)] : [],
+          "",
+          "```dataview",
+          'TABLE file.folder, file.mtime FROM "concepts" OR "entities"',
+          "SORT file.mtime desc",
+          "LIMIT 30",
+          "```",
+          ""
+        ].join("\n"),
+        {
+          page_id: "dashboards:research-map",
+          kind: "index",
+          title: "Research Map",
+          tags: ["index", "dashboard", "research-map"],
+          source_ids: uniqueStrings3([
+            ...conceptPages.flatMap((page) => page.sourceIds),
+            ...entityPages.flatMap((page) => page.sourceIds),
+            ...guidePages.flatMap((page) => page.sourceIds)
+          ]),
+          project_ids: [],
+          node_ids: [],
+          freshness: "fresh",
+          status: metadata.status,
+          confidence: 1,
+          created_at: metadata.createdAt,
+          updated_at: metadata.updatedAt,
+          compiled_from: uniqueStrings3([
+            ...conceptPages.flatMap((page) => page.sourceIds),
+            ...entityPages.flatMap((page) => page.sourceIds),
+            ...guidePages.flatMap((page) => page.sourceIds)
+          ]),
+          managed_by: metadata.managedBy,
+          backlinks: [],
+          schema_hash: schemaHash,
+          source_hashes: {},
+          source_semantic_hashes: {}
+        }
+      )
+    },
     {
       relativePath: "dashboards/contradictions.md",
       title: "Contradictions",
@@ -13520,14 +13680,14 @@ async function buildDashboardRecords(paths, graph, schemaHash, report) {
             return `- ${left} / ${right}: ${contradiction.claimA} <> ${contradiction.claimB}`;
           }) : ["- No contradictions are currently flagged."],
           "",
-          ...reviewPages.length || briefPages.length ? [
+          ...reviewPages.length || briefPages.length || guidePages.length ? [
             "## Related Reviews",
             "",
-            ...[...reviewPages, ...briefPages].slice(0, 12).map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`),
+            ...[...guidePages, ...reviewPages, ...briefPages].slice(0, 12).map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`),
             ""
           ] : [],
           "```dataview",
-          'LIST FROM "outputs/source-reviews"',
+          'LIST FROM "outputs/source-reviews" OR "outputs/source-guides"',
           "SORT file.mtime desc",
           "```",
           ""
@@ -13564,7 +13724,7 @@ async function buildDashboardRecords(paths, graph, schemaHash, report) {
           ...openQuestions.length ? openQuestions.map((question) => `- ${question}`) : ["- No open questions are currently extracted."],
           "",
           "```dataview",
-          'LIST FROM "outputs/source-briefs" OR "outputs/source-reviews"',
+          'LIST FROM "outputs/source-briefs" OR "outputs/source-reviews" OR "outputs/source-guides"',
           "SORT file.mtime desc",
           "```",
           ""
@@ -14338,7 +14498,7 @@ async function writeApprovalManifest(paths, manifest) {
   await fs18.writeFile(approvalManifestPath(paths, manifest.approvalId), `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
 }
-async function buildApprovalEntries(paths, changedFiles, deletedPaths, previousGraph, graph) {
+async function buildApprovalEntries(paths, changedFiles, deletedPaths, previousGraph, graph, labelsByPath = /* @__PURE__ */ new Map()) {
   const previousPagesById = new Map((previousGraph?.pages ?? []).map((page) => [page.id, page]));
   const previousPagesByPath = new Map((previousGraph?.pages ?? []).map((page) => [page.path, page]));
   const nextPagesByPath = new Map(graph.pages.map((page) => [page.path, page]));
@@ -14360,7 +14520,8 @@ async function buildApprovalEntries(paths, changedFiles, deletedPaths, previousG
         status: "pending",
         sourceIds: nextPage.sourceIds,
         nextPath: nextPage.path,
-        previousPath: previousPage.path
+        previousPath: previousPage.path,
+        label: labelsByPath.get(nextPage.path) ?? labelsByPath.get(previousPage.path)
       });
       handledDeletedPaths.add(previousPage.path);
       continue;
@@ -14373,7 +14534,8 @@ async function buildApprovalEntries(paths, changedFiles, deletedPaths, previousG
       status: "pending",
       sourceIds: nextPage.sourceIds,
       nextPath: nextPage.path,
-      previousPath: previousPage?.path
+      previousPath: previousPage?.path,
+      label: labelsByPath.get(nextPage.path) ?? (previousPage?.path ? labelsByPath.get(previousPage.path) : void 0)
     });
   }
   for (const deletedPath of deletedPaths.sort((left, right) => left.localeCompare(right))) {
@@ -14388,7 +14550,8 @@ async function buildApprovalEntries(paths, changedFiles, deletedPaths, previousG
       changeType: "delete",
       status: "pending",
       sourceIds: previousPage?.sourceIds ?? [],
-      previousPath: deletedPath
+      previousPath: deletedPath,
+      label: labelsByPath.get(deletedPath)
     });
   }
   return uniqueBy(entries, (entry) => `${entry.pageId}:${entry.changeType}:${entry.nextPath ?? ""}:${entry.previousPath ?? ""}`);
@@ -14408,6 +14571,8 @@ async function stageApprovalBundle(paths, changedFiles, deletedPaths, previousGr
   await writeApprovalManifest(paths, {
     approvalId,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    bundleType: "compile",
+    title: "Compile Approval",
     entries: await buildApprovalEntries(paths, changedFiles, deletedPaths, previousGraph, graph)
   });
   return { approvalId, approvalDir };
@@ -15123,7 +15288,7 @@ async function persistExploreHub(rootDir, input) {
   }
   return { page: prepared.page, savedPath: prepared.savedPath, outputAssets: prepared.outputAssets };
 }
-async function stageOutputApprovalBundle(rootDir, stagedPages) {
+async function stageOutputApprovalBundle(rootDir, stagedPages, options = {}) {
   const { paths } = await loadVaultConfig(rootDir);
   const previousGraph = await readJsonFile(paths.graphPath);
   const changedFiles = stagedPages.flatMap((item) => [
@@ -15134,6 +15299,7 @@ async function stageOutputApprovalBundle(rootDir, stagedPages) {
       binary: typeof assetFile.content !== "string"
     }))
   ]);
+  const labelsByPath = new Map(stagedPages.filter((item) => item.label).map((item) => [item.page.path, item.label]));
   const approvalId = `schedule-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`;
   const approvalDir = path22.join(paths.approvalsDir, approvalId);
   await ensureDir(approvalDir);
@@ -15164,18 +15330,21 @@ async function stageOutputApprovalBundle(rootDir, stagedPages) {
   await writeApprovalManifest(paths, {
     approvalId,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    bundleType: options.bundleType ?? "generated_output",
+    title: options.title,
     entries: await buildApprovalEntries(
       paths,
       stagedPages.map((item) => ({ relativePath: item.page.path, content: item.content })),
       [],
       previousGraph ?? null,
-      graph
+      graph,
+      labelsByPath
     )
   });
   return { approvalId, approvalDir };
 }
-async function stageGeneratedOutputPages(rootDir, stagedPages) {
-  return await stageOutputApprovalBundle(rootDir, stagedPages);
+async function stageGeneratedOutputPages(rootDir, stagedPages, options = {}) {
+  return await stageOutputApprovalBundle(rootDir, stagedPages, options);
 }
 async function executeQuery(rootDir, question, format) {
   const { paths } = await loadVaultConfig(rootDir);
@@ -15748,14 +15917,24 @@ async function ensureObsidianWorkspace(rootDir) {
   ]);
 }
 async function initVault(rootDir, options = {}) {
-  const { paths } = await initWorkspace(rootDir);
+  const profile = options.profile ?? "default";
+  const { paths } = await initWorkspace(rootDir, { profile });
   await installConfiguredAgents(rootDir);
   const insightsIndexPath = path22.join(paths.wikiDir, "insights", "index.md");
   const now = (/* @__PURE__ */ new Date()).toISOString();
   await writeFileIfChanged(
     insightsIndexPath,
     matter9.stringify(
-      [
+      (profile === "personal-research" ? [
+        "# Insights",
+        "",
+        "Human-authored research notes live here.",
+        "",
+        "- Use this folder for thesis notes, reading reflections, synthesis drafts, and decisions you want to keep explicitly human-authored.",
+        "- Guided ingest can propose updates elsewhere, but SwarmVault does not rewrite files inside `wiki/insights/` after initialization.",
+        "- Treat these pages as the human judgment layer for your vault.",
+        ""
+      ] : [
         "# Insights",
         "",
         "Human-authored notes live here.",
@@ -15763,7 +15942,7 @@ async function initVault(rootDir, options = {}) {
         "- SwarmVault can read these pages during compile and query.",
         "- SwarmVault does not rewrite files inside `wiki/insights/` after initialization.",
         ""
-      ].join("\n"),
+      ]).join("\n"),
       {
         page_id: "insights:index",
         kind: "index",
@@ -15835,6 +16014,42 @@ async function initVault(rootDir, options = {}) {
   if (options.obsidian) {
     await ensureObsidianWorkspace(rootDir);
   }
+  if (profile === "personal-research") {
+    await writeFileIfChanged(
+      path22.join(paths.wikiDir, "insights", "research-playbook.md"),
+      matter9.stringify(
+        [
+          "# Personal Research Playbook",
+          "",
+          "- Add one source at a time with `swarmvault ingest <input> --guide` or `swarmvault source add <input> --guide`.",
+          "- Review `wiki/outputs/source-briefs/`, `wiki/outputs/source-reviews/`, and `wiki/outputs/source-guides/` before accepting staged updates.",
+          "- Keep unresolved questions visible in `wiki/dashboards/open-questions.md`.",
+          "- Use `swarmvault review list` and `swarmvault review show --diff` to decide what becomes canonical.",
+          ""
+        ].join("\n"),
+        {
+          page_id: "insights:research-playbook",
+          kind: "insight",
+          title: "Personal Research Playbook",
+          tags: ["insight", "research", "playbook"],
+          source_ids: [],
+          project_ids: [],
+          node_ids: [],
+          freshness: "fresh",
+          status: "active",
+          confidence: 1,
+          created_at: now,
+          updated_at: now,
+          compiled_from: [],
+          managed_by: "human",
+          backlinks: [],
+          schema_hash: "",
+          source_hashes: {},
+          source_semantic_hashes: {}
+        }
+      )
+    );
+  }
 }
 async function runConfiguredBenchmark(rootDir, config) {
   if (config.benchmark?.enabled === false) {
@@ -16748,7 +16963,7 @@ async function bootstrapDemo(rootDir, input) {
 }
 
 // src/mcp.ts
-var SERVER_VERSION = "0.4.0";
+var SERVER_VERSION = "0.5.0";
 async function createMcpServer(rootDir) {
   const server = new McpServer({
     name: "swarmvault",
@@ -17927,7 +18142,7 @@ function renderDeterministicSourceBrief(input) {
     ""
   ].join("\n");
 }
-async function generateSourceBriefMarkdown(rootDir, source) {
+async function generateSourceBriefMarkdownForScope(rootDir, source) {
   const { paths } = await loadVaultConfig(rootDir);
   const graph = await readJsonFile(paths.graphPath);
   if (!graph) {
@@ -17964,7 +18179,7 @@ Entities: ${analysis.entities.map((entity) => entity.name).join(", ") || "none"}
       ),
       prompt: [
         `Source title: ${source.title}`,
-        `Source kind: ${source.kind}`,
+        `Source kind: ${source.kind ?? "source"}`,
         `Tracked source ids: ${source.sourceIds.join(", ") || "none"}`,
         "",
         "Pages:",
@@ -17982,12 +18197,12 @@ Entities: ${analysis.entities.map((entity) => entity.name).join(", ") || "none"}
     return fallback;
   }
 }
-async function writeSourceBrief(rootDir, source) {
+async function writeSourceBriefForScope(rootDir, source) {
   if (!source.sourceIds.length) {
     return null;
   }
   const { paths } = await loadVaultConfig(rootDir);
-  const markdown = await generateSourceBriefMarkdown(rootDir, source);
+  const markdown = await generateSourceBriefMarkdownForScope(rootDir, source);
   if (!markdown) {
     return null;
   }
@@ -18025,6 +18240,9 @@ async function writeSourceBrief(rootDir, source) {
   await fs21.writeFile(absolutePath, output.content, "utf8");
   return absolutePath;
 }
+async function writeSourceBrief(rootDir, source) {
+  return await writeSourceBriefForScope(rootDir, scopeFromManagedSource(source));
+}
 async function generateBriefsForSources(rootDir, sources) {
   const briefPaths = /* @__PURE__ */ new Map();
   for (const source of sources) {
@@ -18137,7 +18355,7 @@ Entities: ${analysis.entities.map((entity) => entity.name).join(", ") || "none"}
     return fallback;
   }
 }
-async function stageSourceReviewForScope(rootDir, scope) {
+async function buildSourceReviewStagedPage(rootDir, scope) {
   const { paths } = await loadVaultConfig(rootDir);
   const markdown = await generateSourceReviewMarkdown(rootDir, scope);
   if (!markdown) {
@@ -18172,7 +18390,176 @@ async function stageSourceReviewForScope(rootDir, scope) {
       confidence: 0.79
     }
   });
-  const approval = await stageGeneratedOutputPages(rootDir, [{ page: output.page, content: output.content }]);
+  return { page: output.page, content: output.content };
+}
+function classifySourceGuidePageBuckets(sourcePages, scopeSourceIds) {
+  const scopeSet = new Set(scopeSourceIds);
+  const canonicalPages = sourcePages.filter((page) => page.kind === "source" || page.kind === "concept" || page.kind === "entity").slice(0, 12);
+  const newPages = canonicalPages.filter((page) => page.sourceIds.every((sourceId) => scopeSet.has(sourceId))).slice(0, 6);
+  const reinforcingPages = canonicalPages.filter((page) => page.sourceIds.some((sourceId) => !scopeSet.has(sourceId))).slice(0, 6);
+  return { canonicalPages, newPages, reinforcingPages };
+}
+function renderDeterministicSourceGuide(input) {
+  const { canonicalPages, newPages, reinforcingPages } = classifySourceGuidePageBuckets(input.sourcePages, input.scope.sourceIds);
+  const modulePages = input.sourcePages.filter((page) => page.kind === "module").slice(0, 6);
+  const takeaways = uniqueStrings4(
+    input.analyses.flatMap((analysis) => [
+      analysis.summary,
+      ...analysis.concepts.map((concept) => concept.description),
+      ...analysis.entities.map((entity) => entity.description)
+    ]).filter(Boolean).map((value) => normalizeWhitespace(value))
+  ).slice(0, 7).map((value) => truncate(value, 180));
+  const questions = uniqueStrings4(input.analyses.flatMap((analysis) => analysis.questions)).slice(0, 6);
+  const contradictions = input.report?.contradictions.filter(
+    (contradiction) => input.scope.sourceIds.includes(contradiction.sourceIdA) || input.scope.sourceIds.includes(contradiction.sourceIdB)
+  ) ?? [];
+  return [
+    `# Source Guide: ${input.scope.title}`,
+    "",
+    "## What This Source Is",
+    "",
+    takeaways.length ? takeaways[0] : `${input.scope.title} has been compiled into the vault and is ready for guided review.`,
+    "",
+    "## Key Takeaways",
+    "",
+    ...takeaways.length ? takeaways.map((takeaway) => `- ${takeaway}`) : ["- No takeaways are available until the source is compiled."],
+    "",
+    "## Proposed Canonical Pages To Update",
+    "",
+    ...canonicalPages.length ? canonicalPages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`) : ["- No likely canonical pages were identified yet."],
+    "",
+    "## New, Reinforcing, And Conflicting Claims",
+    "",
+    ...newPages.length ? ["New or source-local pages:", ...newPages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`), ""] : [],
+    ...reinforcingPages.length ? ["Reinforcing existing pages:", ...reinforcingPages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`), ""] : [],
+    ...contradictions.length ? ["Conflicts to judge:", ...contradictions.map((contradiction) => `- ${contradiction.claimA} / ${contradiction.claimB}`), ""] : ["Conflicts to judge:", "- No contradictions are currently flagged for this source scope.", ""],
+    "## What Should Probably Stay Out For Now",
+    "",
+    ...modulePages.length ? ["- Avoid promoting narrow implementation details unless they matter to your thesis or recurring questions."] : ["- Avoid promoting incidental details that are not yet supported by multiple sources or clear research goals."],
+    ...contradictions.length ? ["- Keep contested claims provisional until you review the conflicting evidence side by side."] : [],
+    "",
+    "## Needs Human Judgment",
+    "",
+    ...questions.length ? questions.map((question) => `- ${question}`) : ["- Decide which proposed canonical pages deserve durable summary updates."],
+    "",
+    "## Suggested Follow-up Questions",
+    "",
+    ...questions.length ? questions.map((question) => `- ${question}`) : ["- What changed in your understanding after reading this source?"],
+    ""
+  ].join("\n");
+}
+async function generateSourceGuideMarkdown(rootDir, scope) {
+  const { paths } = await loadVaultConfig(rootDir);
+  let graph = await readJsonFile(paths.graphPath);
+  if (!graph) {
+    await compileVault(rootDir, {});
+    graph = await readJsonFile(paths.graphPath);
+  }
+  if (!graph) {
+    return null;
+  }
+  const sourcePages = scopedSourcePages(graph, scope.sourceIds);
+  const analyses = await loadSourceAnalyses(rootDir, scope.sourceIds);
+  const report = await readGraphReport(rootDir);
+  const fallback = renderDeterministicSourceGuide({
+    scope,
+    sourcePages,
+    analyses,
+    report
+  });
+  const provider = await getProviderForTask(rootDir, "queryProvider");
+  if (provider.type === "heuristic") {
+    return fallback;
+  }
+  try {
+    const schemas = await loadVaultSchemas(rootDir);
+    const { canonicalPages, newPages, reinforcingPages } = classifySourceGuidePageBuckets(sourcePages, scope.sourceIds);
+    const pageContext = sourcePages.slice(0, 12).map((page) => `- ${page.title} (${page.kind}) -> ${page.path}`).join("\n");
+    const analysisContext = analyses.slice(0, 8).map(
+      (analysis) => `# ${analysis.title}
+Summary: ${analysis.summary}
+Questions: ${analysis.questions.join(" | ") || "none"}
+Concepts: ${analysis.concepts.map((concept) => concept.name).join(", ") || "none"}
+Entities: ${analysis.entities.map((entity) => entity.name).join(", ") || "none"}`
+    ).join("\n\n---\n\n");
+    const response = await provider.generateText({
+      system: buildSchemaPrompt(
+        schemas.effective.global,
+        "Write a concise markdown source guide with sections: What This Source Is, Key Takeaways, Proposed Canonical Pages To Update, New Reinforcing And Conflicting Claims, What Should Probably Stay Out For Now, Needs Human Judgment, Suggested Follow-up Questions. Focus on helping a human integrate one source into an evolving research wiki."
+      ),
+      prompt: [
+        `Source scope: ${scope.title}`,
+        `Scope id: ${scope.id}`,
+        `Tracked source ids: ${scope.sourceIds.join(", ") || "none"}`,
+        `Current brief path: ${scope.briefPath ?? "none"}`,
+        "",
+        "Likely canonical pages:",
+        canonicalPages.length ? canonicalPages.map((page) => `- ${page.title} -> ${page.path}`).join("\n") : "- none",
+        "",
+        "Likely source-local pages:",
+        newPages.length ? newPages.map((page) => `- ${page.title} -> ${page.path}`).join("\n") : "- none",
+        "",
+        "Likely reinforcing pages:",
+        reinforcingPages.length ? reinforcingPages.map((page) => `- ${page.title} -> ${page.path}`).join("\n") : "- none",
+        "",
+        "Pages:",
+        pageContext || "- 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 { 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 relatedPages = graph ? scopedSourcePages(graph, scope.sourceIds) : [];
+  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: graph?.generatedAt ?? "",
+    outputFormat: "report",
+    relatedPageIds,
+    relatedNodeIds,
+    relatedSourceIds: scope.sourceIds,
+    projectIds,
+    extraTags: ["source-guide", "guided-ingest"],
+    origin: "query",
+    slug: `source-guides/${scope.id}`,
+    metadata: {
+      status: "draft",
+      createdAt: now,
+      updatedAt: now,
+      compiledFrom: scope.sourceIds,
+      managedBy: "system",
+      confidence: 0.8
+    }
+  });
+  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,
@@ -18182,16 +18569,55 @@ async function stageSourceReviewForScope(rootDir, scope) {
     approvalDir: approval.approvalDir
   };
 }
+async function stageSourceGuideForScope(rootDir, scope) {
+  const briefPath = scope.briefPath ?? await writeSourceBriefForScope(rootDir, scope) ?? void 0;
+  if (briefPath) {
+    await refreshVaultAfterOutputSave(rootDir);
+  }
+  const reviewOutput = await buildSourceReviewStagedPage(rootDir, scope);
+  const guideOutput = await buildSourceGuideStagedPage(rootDir, {
+    ...scope,
+    briefPath
+  });
+  const approval = await stageGeneratedOutputPages(
+    rootDir,
+    [
+      { page: reviewOutput.page, content: reviewOutput.content, label: "source-review" },
+      { page: guideOutput.page, content: guideOutput.content, label: "source-guide" }
+    ],
+    {
+      bundleType: "guided_source",
+      title: `Guided Source: ${scope.title}`
+    }
+  );
+  await refreshVaultAfterOutputSave(rootDir);
+  return {
+    sourceId: scope.id,
+    pageId: guideOutput.page.id,
+    guidePath: path25.join(approval.approvalDir, "wiki", guideOutput.page.path),
+    reviewPageId: reviewOutput.page.id,
+    reviewPath: path25.join(approval.approvalDir, "wiki", reviewOutput.page.path),
+    briefPath,
+    staged: true,
+    approvalId: approval.approvalId,
+    approvalDir: approval.approvalDir
+  };
+}
 function scopeFromManagedSource(source) {
   return {
     id: source.id,
     title: source.title,
-    sourceIds: source.sourceIds
+    sourceIds: source.sourceIds,
+    kind: source.kind,
+    briefPath: source.briefPath
   };
 }
 async function reviewSourceScope(rootDir, scope) {
   return await stageSourceReviewForScope(rootDir, scope);
 }
+async function guideSourceScope(rootDir, scope) {
+  return await stageSourceGuideForScope(rootDir, scope);
+}
 async function reviewManagedSource(rootDir, id) {
   const managedSources = await loadManagedSources(rootDir);
   const managedSource = managedSources.find((source) => source.id === id);
@@ -18201,14 +18627,37 @@ async function reviewManagedSource(rootDir, id) {
     }
     return await stageSourceReviewForScope(rootDir, scopeFromManagedSource(managedSource));
   }
-  const manifest = (await listManifests(rootDir)).find((candidate) => candidate.sourceId === id);
+  const manifests = await listManifests(rootDir);
+  const manifest = manifests.find((candidate) => candidate.sourceId === id);
   if (!manifest) {
     throw new Error(`Managed source or source id not found: ${id}`);
   }
   return await stageSourceReviewForScope(rootDir, {
-    id: manifest.sourceId,
-    title: manifest.title,
-    sourceIds: [manifest.sourceId]
+    id: manifest.sourceGroupId ?? manifest.sourceId,
+    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 guideManagedSource(rootDir, id) {
+  const managedSources = await loadManagedSources(rootDir);
+  const managedSource = managedSources.find((source) => source.id === id);
+  if (managedSource) {
+    if (!await loadVaultConfig(rootDir).then(({ paths }) => fileExists(paths.graphPath))) {
+      await compileVault(rootDir, {});
+    }
+    return await stageSourceGuideForScope(rootDir, scopeFromManagedSource(managedSource));
+  }
+  const manifests = await listManifests(rootDir);
+  const manifest = manifests.find((candidate) => candidate.sourceId === id);
+  if (!manifest) {
+    throw new Error(`Managed source or source id not found: ${id}`);
+  }
+  return await stageSourceGuideForScope(rootDir, {
+    id: manifest.sourceGroupId ?? manifest.sourceId,
+    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 shouldCompile(changedSources, graphExists, compileRequested) {
@@ -18220,8 +18669,9 @@ async function listManagedSourceRecords(rootDir) {
 }
 async function addManagedSource(rootDir, input, options = {}) {
   const compileRequested = options.compile ?? true;
-  const briefRequested = options.brief ?? true;
-  const reviewRequested = options.review ?? false;
+  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));
@@ -18262,17 +18712,23 @@ async function addManagedSource(rootDir, input, options = {}) {
   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
+  }) : void 0;
   return {
     source: nextSource,
     compile,
     briefGenerated,
-    review
+    review,
+    guide
   };
 }
 async function reloadManagedSources(rootDir, options = {}) {
   const compileRequested = options.compile ?? true;
-  const briefRequested = options.brief ?? true;
-  const reviewRequested = options.review ?? false;
+  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) {
@@ -18311,11 +18767,20 @@ async function reloadManagedSources(rootDir, options = {}) {
   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
+      })
+    )
+  ) : [];
   return {
     sources: nextSources.filter((source) => selected.some((candidate) => candidate.id === source.id)),
     compile,
     briefPaths: [...briefPaths.values()],
-    reviews
+    reviews,
+    guides
   };
 }
 async function deleteManagedSource(rootDir, id) {
@@ -19216,6 +19681,8 @@ export {
   getWatchStatus,
   getWebSearchAdapterForTask,
   getWorkspaceInfo,
+  guideManagedSource,
+  guideSourceScope,
   importInbox,
   ingestDirectory,
   ingestInput,