@swarmvaultai/engine 0.1.22 → 0.1.24

package/dist/index.js

@@ -21,7 +21,7 @@ import {
   uniqueBy,
   writeFileIfChanged,
   writeJsonFile
-} from "./chunk-QMW7OISM.js";
+} from "./chunk-6UPHDGEB.js";
 
 // src/agents.ts
 import fs from "fs/promises";
@@ -192,6 +192,9 @@ function graphPageById(graph) {
 function graphNodeById(graph) {
   return new Map(graph.nodes.map((node) => [node.id, node]));
 }
+function exportHyperedgeNodeId(hyperedge) {
+  return `hyperedge:${hyperedge.id}`;
+}
 function sortedCommunities(graph) {
   const known = (graph.communities ?? []).map((community) => ({
     ...community,
@@ -356,6 +359,11 @@ function renderGraphMl(graph) {
     { id: "n_community", for: "node", name: "communityId", type: "string" },
     { id: "n_degree", for: "node", name: "degree", type: "double" },
     { id: "n_bridge", for: "node", name: "bridgeScore", type: "double" },
+    { id: "n_relation", for: "node", name: "relation", type: "string" },
+    { id: "n_evidence", for: "node", name: "evidenceClass", type: "string" },
+    { id: "n_confidence", for: "node", name: "confidence", type: "double" },
+    { id: "n_source_pages", for: "node", name: "sourcePageIds", type: "string" },
+    { id: "n_why", for: "node", name: "why", type: "string" },
     { id: "e_relation", for: "edge", name: "relation", type: "string" },
     { id: "e_status", for: "edge", name: "status", type: "string" },
     { id: "e_evidence", for: "edge", name: "evidenceClass", type: "string" },
@@ -394,6 +402,21 @@ function renderGraphMl(graph) {
     }
     lines.push("    </node>");
   }
+  for (const hyperedge of [...graph.hyperedges ?? []].sort((left, right) => left.id.localeCompare(right.id))) {
+    lines.push(`    <node id="${xmlEscape(exportHyperedgeNodeId(hyperedge))}">`);
+    for (const [key, value] of [
+      ["n_label", hyperedge.label],
+      ["n_type", "hyperedge"],
+      ["n_relation", hyperedge.relation],
+      ["n_evidence", hyperedge.evidenceClass],
+      ["n_confidence", hyperedge.confidence],
+      ["n_source_pages", hyperedge.sourcePageIds],
+      ["n_why", hyperedge.why]
+    ]) {
+      lines.push(`      <data key="${key}">${xmlEscape(graphMlData(value))}</data>`);
+    }
+    lines.push("    </node>");
+  }
   for (const edge of [...graph.edges].sort((left, right) => left.id.localeCompare(right.id))) {
     lines.push(`    <edge id="${xmlEscape(edge.id)}" source="${xmlEscape(edge.source)}" target="${xmlEscape(edge.target)}">`);
     for (const [key, value] of [
@@ -407,6 +430,23 @@ function renderGraphMl(graph) {
     }
     lines.push("    </edge>");
   }
+  for (const hyperedge of [...graph.hyperedges ?? []].sort((left, right) => left.id.localeCompare(right.id))) {
+    for (const nodeId of hyperedge.nodeIds) {
+      lines.push(
+        `    <edge id="${xmlEscape(`member:${hyperedge.id}:${nodeId}`)}" source="${xmlEscape(exportHyperedgeNodeId(hyperedge))}" target="${xmlEscape(nodeId)}">`
+      );
+      for (const [key, value] of [
+        ["e_relation", "group_member"],
+        ["e_status", "inferred"],
+        ["e_evidence", hyperedge.evidenceClass],
+        ["e_confidence", hyperedge.confidence],
+        ["e_provenance", hyperedge.sourcePageIds]
+      ]) {
+        lines.push(`      <data key="${key}">${xmlEscape(graphMlData(value))}</data>`);
+      }
+      lines.push("    </edge>");
+    }
+  }
   lines.push("  </graph>", "</graphml>", "");
   return lines.join("\n");
 }
@@ -433,13 +473,41 @@ function renderCypher(graph) {
     lines.push(`MERGE (n:SwarmNode {id: '${cypherEscape(node.id)}'}) SET n += { ${props} };`);
   }
   lines.push("");
+  for (const hyperedge of [...graph.hyperedges ?? []].sort((left, right) => left.id.localeCompare(right.id))) {
+    const hyperedgeNodeId = exportHyperedgeNodeId(hyperedge);
+    lines.push(
+      `MERGE (h:SwarmNode {id: '${cypherEscape(hyperedgeNodeId)}'}) SET h += { id: '${cypherEscape(hyperedgeNodeId)}', label: '${cypherEscape(
+        hyperedge.label
+      )}', type: 'hyperedge', relation: '${cypherEscape(hyperedge.relation)}', evidenceClass: '${cypherEscape(
+        hyperedge.evidenceClass
+      )}', confidence: ${hyperedge.confidence}, sourcePageIds: '${cypherEscape(JSON.stringify(hyperedge.sourcePageIds))}', why: '${cypherEscape(
+        hyperedge.why
+      )}' };`
+    );
+  }
+  if ((graph.hyperedges ?? []).length) {
+    lines.push("");
+  }
+  for (const hyperedge of [...graph.hyperedges ?? []].sort((left, right) => left.id.localeCompare(right.id))) {
+    const hyperedgeNodeId = exportHyperedgeNodeId(hyperedge);
+    for (const nodeId of hyperedge.nodeIds) {
+      lines.push(
+        `MATCH (h:SwarmNode {id: '${cypherEscape(hyperedgeNodeId)}'}), (n:SwarmNode {id: '${cypherEscape(nodeId)}'})`,
+        `MERGE (h)-[r:GROUP_MEMBER {id: '${cypherEscape(`member:${hyperedge.id}:${nodeId}`)}'}]->(n)`,
+        `SET r += { relation: 'group_member', status: 'inferred', evidenceClass: '${cypherEscape(
+          hyperedge.evidenceClass
+        )}', confidence: ${hyperedge.confidence}, provenance: '${cypherEscape(JSON.stringify(hyperedge.sourcePageIds))}' };`
+      );
+    }
+  }
+  lines.push("");
   for (const edge of [...graph.edges].sort((left, right) => left.id.localeCompare(right.id))) {
     lines.push(
       `MATCH (a:SwarmNode {id: '${cypherEscape(edge.source)}'}), (b:SwarmNode {id: '${cypherEscape(edge.target)}'})`,
       `MERGE (a)-[r:${relationType(edge.relation)} {id: '${cypherEscape(edge.id)}'}]->(b)`,
       `SET r += { relation: '${cypherEscape(edge.relation)}', status: '${cypherEscape(edge.status)}', evidenceClass: '${cypherEscape(
         edge.evidenceClass
-      )}', confidence: ${edge.confidence}, provenance: '${cypherEscape(JSON.stringify(edge.provenance))}' };`
+      )}', confidence: ${edge.confidence}, provenance: '${cypherEscape(JSON.stringify(edge.provenance))}'${edge.similarityReasons?.length ? `, similarityReasons: '${cypherEscape(JSON.stringify(edge.similarityReasons))}'` : ""} };`
     );
   }
   lines.push("");
@@ -596,6 +664,7 @@ async function uninstallGitHooks(rootDir) {
 import fs9 from "fs/promises";
 import path9 from "path";
 import { Readability } from "@mozilla/readability";
+import matter3 from "gray-matter";
 import ignore from "ignore";
 import { JSDOM } from "jsdom";
 import mime from "mime-types";
@@ -3204,6 +3273,9 @@ async function markPagesStaleForSources(rootDir, sourceIds) {
 var DEFAULT_MAX_ASSET_SIZE = 10 * 1024 * 1024;
 var DEFAULT_MAX_DIRECTORY_FILES = 5e3;
 var BUILT_IN_REPO_IGNORES = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", ".next", "coverage", ".venv", "vendor", "target"]);
+function uniqueStrings(values) {
+  return [...new Set(values.filter(Boolean))];
+}
 function inferKind(mimeType, filePath) {
   if (inferCodeLanguage(filePath, mimeType)) {
     return "code";
@@ -3321,6 +3393,22 @@ function arxivIdFromInput(input) {
     return null;
   }
 }
+function doiFromInput(input) {
+  const trimmed = input.trim();
+  if (/^10\.\S+\/\S+$/i.test(trimmed)) {
+    return trimmed.replace(/\s+/g, "");
+  }
+  try {
+    const url = new URL(trimmed);
+    if (url.hostname === "doi.org" || url.hostname === "dx.doi.org") {
+      const doi = decodeURIComponent(url.pathname.replace(/^\/+/, ""));
+      return /^10\.\S+\/\S+$/i.test(doi) ? doi : null;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
 function isTweetUrl(input) {
   try {
     const url = new URL(input);
@@ -3330,26 +3418,25 @@ function isTweetUrl(input) {
   }
 }
 function markdownFrontmatter(value) {
-  const lines = ["---"];
-  for (const [key, rawValue] of Object.entries(value)) {
-    if (!rawValue) {
-      continue;
-    }
-    lines.push(`${key}: "${rawValue.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
-  }
-  lines.push("---", "");
-  return lines;
+  const normalized = Object.fromEntries(
+    Object.entries(value).filter(
+      ([, rawValue]) => Array.isArray(rawValue) ? rawValue.length > 0 : Boolean(typeof rawValue === "string" ? rawValue.trim() : rawValue)
+    )
+  );
+  return matter3.stringify("", normalized).trimEnd().split("\n").concat([""]);
 }
 function prepareCapturedMarkdownInput(input) {
   return {
     title: input.title,
     originType: "url",
     sourceKind: "markdown",
+    sourceType: input.sourceType,
     url: normalizeOriginUrl(input.url),
     mimeType: "text/markdown",
     storedExtension: ".md",
     payloadBytes: Buffer.from(input.markdown, "utf8"),
     extractedText: input.markdown,
+    attachments: input.attachments,
     logDetails: input.logDetails
   };
 }
@@ -3360,6 +3447,17 @@ async function fetchText(url) {
   }
   return response.text();
 }
+async function fetchResolvedText(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+  }
+  return {
+    text: await response.text(),
+    finalUrl: normalizeOriginUrl(response.url || url),
+    contentType: response.headers.get("content-type")?.split(";")[0]?.trim() || "text/html"
+  };
+}
 function domTextFromHtml(html, baseUrl) {
   const dom = new JSDOM(`<body>${html}</body>`, { url: baseUrl });
   return normalizeWhitespace(dom.window.document.body.textContent ?? "");
@@ -3379,11 +3477,16 @@ async function captureArxivMarkdown(input, options) {
   const authors = [...document.querySelectorAll('meta[name="citation_author"]')].map((node) => node.getAttribute("content")?.trim()).filter((value) => Boolean(value));
   const authorsText = authors.join(", ") || stripLeadingLabel(document.querySelector(".authors")?.textContent?.trim() ?? "", "Authors:");
   const abstract = stripLeadingLabel(document.querySelector("blockquote.abstract")?.textContent?.trim() ?? "", "Abstract:");
+  const categories = [...document.querySelectorAll(".subheader .primary-subject, .metatable .tablecell.subjects")].flatMap((node) => (node.textContent ?? "").split(/;/g)).map((value) => value.trim()).filter(Boolean);
   const capturedAt = (/* @__PURE__ */ new Date()).toISOString();
   const markdown = [
     ...markdownFrontmatter({
-      capture_type: "arxiv",
+      source_type: "arxiv",
       source_url: normalizedUrl,
+      canonical_url: normalizedUrl,
+      title,
+      authors,
+      tags: uniqueStrings(categories),
       arxiv_id: arxivId,
       author: options.author,
       contributor: options.contributor,
@@ -3423,8 +3526,11 @@ async function captureTweetMarkdown(input, options) {
   const capturedAt = (/* @__PURE__ */ new Date()).toISOString();
   const markdown = [
     ...markdownFrontmatter({
-      capture_type: "tweet",
+      source_type: "tweet",
       source_url: normalizedUrl,
+      canonical_url: canonicalUrl,
+      title,
+      authors: postAuthor ? [postAuthor] : void 0,
       author: options.author,
       contributor: options.contributor,
       captured_at: capturedAt
@@ -3446,6 +3552,101 @@ async function captureTweetMarkdown(input, options) {
   ].join("\n");
   return { title, normalizedUrl, markdown };
 }
+function firstMetaContent(document, selectors) {
+  for (const selector of selectors) {
+    const value = document.querySelector(selector)?.getAttribute("content")?.trim();
+    if (value) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function metaContents(document, selectors) {
+  return uniqueStrings(
+    selectors.flatMap(
+      (selector) => [...document.querySelectorAll(selector)].map((node) => node.getAttribute("content")?.trim() ?? "").filter(Boolean)
+    )
+  );
+}
+function splitKeywords(value) {
+  return uniqueStrings(
+    (value ?? "").split(/[;,]/g).map((item) => item.trim()).filter(Boolean)
+  );
+}
+async function captureArticleMarkdown(rootDir, input, options, extra = { sourceType: "article" }) {
+  const resolved = await fetchResolvedText(input);
+  if (!resolved.contentType.includes("html")) {
+    throw new Error(`Unsupported article content type: ${resolved.contentType}`);
+  }
+  const dom = new JSDOM(resolved.text, { url: resolved.finalUrl });
+  const document = dom.window.document;
+  const canonicalHref = document.querySelector('link[rel="canonical"]')?.getAttribute("href")?.trim();
+  const canonicalUrl = canonicalHref ? normalizeOriginUrl(new URL(canonicalHref, resolved.finalUrl).toString()) : resolved.finalUrl;
+  const title = firstMetaContent(document, ['meta[name="citation_title"]', 'meta[property="og:title"]', 'meta[name="twitter:title"]']) ?? (document.title.trim() || canonicalUrl);
+  const authors = uniqueStrings([
+    ...metaContents(document, ['meta[name="citation_author"]']),
+    ...metaContents(document, ['meta[name="author"]', 'meta[property="article:author"]'])
+  ]);
+  const publishedAt = firstMetaContent(document, [
+    'meta[name="citation_publication_date"]',
+    'meta[name="citation_online_date"]',
+    'meta[property="article:published_time"]',
+    'meta[name="pubdate"]'
+  ]);
+  const updatedAt = firstMetaContent(document, ['meta[property="article:modified_time"]', 'meta[name="lastmod"]']);
+  const tags = uniqueStrings([
+    ...metaContents(document, ['meta[property="article:tag"]']),
+    ...splitKeywords(firstMetaContent(document, ['meta[name="keywords"]']))
+  ]);
+  const inferredDoi = extra.doi ?? firstMetaContent(document, ['meta[name="citation_doi"]', 'meta[name="dc.identifier"]'])?.replace(/^doi:\s*/i, "") ?? void 0;
+  const normalizedOptions = normalizeIngestOptions(options);
+  const prepared = await prepareUrlInput(rootDir, canonicalUrl, normalizedOptions);
+  if (prepared.sourceKind !== "markdown" && prepared.sourceKind !== "text") {
+    throw new Error(`Unsupported prepared article kind: ${prepared.sourceKind}`);
+  }
+  const body = prepared.extractedText ?? prepared.payloadBytes.toString("utf8");
+  const capturedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const markdown = [
+    ...markdownFrontmatter({
+      source_type: extra.sourceType,
+      source_url: extra.sourceUrl ?? input,
+      canonical_url: canonicalUrl,
+      title,
+      authors,
+      published_at: publishedAt,
+      updated_at: updatedAt,
+      doi: inferredDoi,
+      tags,
+      author: options.author,
+      contributor: options.contributor,
+      captured_at: capturedAt
+    }),
+    body.trim(),
+    "",
+    "## Source",
+    "",
+    `- URL: ${canonicalUrl}`,
+    ...extra.sourceType === "doi" && inferredDoi ? [`- DOI: ${inferredDoi}`] : [],
+    ""
+  ].join("\n");
+  return {
+    title,
+    normalizedUrl: canonicalUrl,
+    markdown,
+    attachments: prepared.attachments
+  };
+}
+async function captureDoiMarkdown(rootDir, input, options) {
+  const doi = doiFromInput(input);
+  if (!doi) {
+    throw new Error(`Could not determine a DOI from ${input}`);
+  }
+  return captureArticleMarkdown(rootDir, `https://doi.org/${encodeURIComponent(doi)}`, options, {
+    sourceType: "doi",
+    sourceUrl: input,
+    doi
+  });
+}
 function manifestMatchesOrigin(manifest, prepared) {
   if (prepared.originType === "url") {
     return Boolean(prepared.url && manifest.url && normalizeOriginUrl(manifest.url) === normalizeOriginUrl(prepared.url));
@@ -3789,7 +3990,7 @@ async function persistPreparedInput(rootDir, prepared, paths) {
   const extractionHash = prepared.extractionHash ?? buildExtractionHash(prepared.extractedText, prepared.extractionArtifact);
   const existingByOrigin = await readManifestByOrigin(paths.manifestsDir, prepared);
   const existingByHash = existingByOrigin ? null : await readManifestByHash(paths.manifestsDir, contentHash);
-  if (existingByOrigin && existingByOrigin.contentHash === contentHash && existingByOrigin.extractionHash === extractionHash && existingByOrigin.title === prepared.title && existingByOrigin.sourceKind === prepared.sourceKind && existingByOrigin.language === prepared.language && existingByOrigin.mimeType === prepared.mimeType && existingByOrigin.repoRelativePath === prepared.repoRelativePath) {
+  if (existingByOrigin && existingByOrigin.contentHash === contentHash && existingByOrigin.extractionHash === extractionHash && existingByOrigin.title === prepared.title && existingByOrigin.sourceKind === prepared.sourceKind && existingByOrigin.sourceType === prepared.sourceType && existingByOrigin.language === prepared.language && existingByOrigin.mimeType === prepared.mimeType && existingByOrigin.repoRelativePath === prepared.repoRelativePath) {
     return { manifest: existingByOrigin, isNew: false, wasUpdated: false };
   }
   if (existingByHash) {
@@ -3835,6 +4036,7 @@ async function persistPreparedInput(rootDir, prepared, paths) {
     title: prepared.title,
     originType: prepared.originType,
     sourceKind: prepared.sourceKind,
+    sourceType: prepared.sourceType,
     language: prepared.language,
     originalPath: prepared.originalPath,
     repoRelativePath: prepared.repoRelativePath,
@@ -3892,7 +4094,7 @@ function repoSyncWorkspaceIgnorePaths(rootDir, paths, repoRoot) {
   return candidates.map((candidate) => path9.resolve(candidate)).filter((candidate, index, items) => items.indexOf(candidate) === index).filter((candidate) => withinRoot(repoRoot, candidate));
 }
 function preparedMatchesManifest(manifest, prepared, contentHash) {
-  return manifest.contentHash === contentHash && manifest.extractionHash === (prepared.extractionHash ?? buildExtractionHash(prepared.extractedText, prepared.extractionArtifact)) && manifest.title === prepared.title && manifest.sourceKind === prepared.sourceKind && manifest.language === prepared.language && manifest.mimeType === prepared.mimeType && manifest.repoRelativePath === prepared.repoRelativePath;
+  return manifest.contentHash === contentHash && manifest.extractionHash === (prepared.extractionHash ?? buildExtractionHash(prepared.extractedText, prepared.extractionArtifact)) && manifest.title === prepared.title && manifest.sourceKind === prepared.sourceKind && manifest.sourceType === prepared.sourceType && manifest.language === prepared.language && manifest.mimeType === prepared.mimeType && manifest.repoRelativePath === prepared.repoRelativePath;
 }
 function shouldDeferWatchSemanticRefresh(sourceKind) {
   return sourceKind === "markdown" || sourceKind === "text" || sourceKind === "html" || sourceKind === "pdf" || sourceKind === "image";
@@ -4184,7 +4386,8 @@ async function prepareUrlInput(rootDir, input, options) {
   if (!response.ok) {
     throw new Error(`Failed to fetch ${input}: ${response.status} ${response.statusText}`);
   }
-  const inputUrl = new URL(input);
+  const finalUrl = normalizeOriginUrl(response.url || input);
+  const inputUrl = new URL(finalUrl);
   const originalPayloadBytes = Buffer.from(await response.arrayBuffer());
   let payloadBytes = originalPayloadBytes;
   let mimeType = resolveUrlMimeType(input, response);
@@ -4199,13 +4402,13 @@ async function prepareUrlInput(rootDir, input, options) {
   const logDetails = [];
   if (sourceKind === "html" || mimeType.startsWith("text/html")) {
     const html = originalPayloadBytes.toString("utf8");
-    const initialConversion = await convertHtmlToMarkdown(html, input);
+    const initialConversion = await convertHtmlToMarkdown(html, finalUrl);
     title = initialConversion.title;
     let localizedHtml = html;
     let localAssetReplacements;
     if (options.includeAssets) {
       const { attachments: remoteAttachments, skippedCount } = await collectRemoteImageAttachments(
-        extractHtmlImageReferences(html, input),
+        extractHtmlImageReferences(html, finalUrl),
         options
       );
       if (remoteAttachments.length) {
@@ -4215,19 +4418,19 @@ async function prepareUrlInput(rootDir, input, options) {
         localAssetReplacements = new Map(
           remoteAttachments.map((attachment) => [attachment.originalPath ?? "", `../assets/${sourceId}/${attachment.relativePath}`])
         );
-        localizedHtml = rewriteHtmlImageReferences(html, input, localAssetReplacements);
+        localizedHtml = rewriteHtmlImageReferences(html, finalUrl, localAssetReplacements);
         logDetails.push(`remote_assets=${remoteAttachments.length}`);
       }
       if (skippedCount) {
         logDetails.push(`remote_asset_skips=${skippedCount}`);
       }
     }
-    const converted = localizedHtml === html && !attachments?.length ? initialConversion : await convertHtmlToMarkdown(localizedHtml, input);
+    const converted = localizedHtml === html && !attachments?.length ? initialConversion : await convertHtmlToMarkdown(localizedHtml, finalUrl);
     extractedText = converted.markdown;
     extractionArtifact = createHtmlReadabilityExtractionArtifact("markdown", "text/markdown");
     if (localAssetReplacements?.size) {
       const absoluteLocalAssetReplacements = new Map(
-        [...localAssetReplacements.values()].map((replacement) => [new URL(replacement, input).toString(), replacement])
+        [...localAssetReplacements.values()].map((replacement) => [new URL(replacement, finalUrl).toString(), replacement])
       );
       extractedText = rewriteMarkdownImageTargets(extractedText, absoluteLocalAssetReplacements);
     }
@@ -4244,7 +4447,7 @@ async function prepareUrlInput(rootDir, input, options) {
       extractionArtifact = createPlainTextExtractionArtifact(sourceKind, mimeType);
       if (sourceKind === "markdown" && options.includeAssets) {
         const { attachments: remoteAttachments, skippedCount } = await collectRemoteImageAttachments(
-          extractMarkdownImageReferences(extractedText, input),
+          extractMarkdownImageReferences(extractedText, finalUrl),
           options
         );
         if (remoteAttachments.length) {
@@ -4254,7 +4457,7 @@ async function prepareUrlInput(rootDir, input, options) {
           const replacements = new Map(
             remoteAttachments.map((attachment) => [attachment.originalPath ?? "", `../assets/${sourceId}/${attachment.relativePath}`])
           );
-          extractedText = rewriteMarkdownImageReferences(extractedText, input, replacements);
+          extractedText = rewriteMarkdownImageReferences(extractedText, finalUrl, replacements);
           payloadBytes = Buffer.from(extractedText, "utf8");
           logDetails.push(`remote_assets=${remoteAttachments.length}`);
         }
@@ -4282,7 +4485,7 @@ async function prepareUrlInput(rootDir, input, options) {
     originType: "url",
     sourceKind,
     language,
-    url: input,
+    url: finalUrl,
     mimeType,
     storedExtension,
     payloadBytes,
@@ -4395,8 +4598,8 @@ async function ingestInput(rootDir, input, options) {
 }
 async function addInput(rootDir, input, options = {}) {
   const { paths } = await initWorkspace(rootDir);
-  if (!isHttpUrl(input) && !arxivIdFromInput(input)) {
-    throw new Error("`swarmvault add` only supports URLs and bare arXiv ids in the current release.");
+  if (!isHttpUrl(input) && !arxivIdFromInput(input) && !doiFromInput(input)) {
+    throw new Error("`swarmvault add` only supports URLs, bare arXiv ids, and bare DOI strings in the current release.");
   }
   let prepared = null;
   let captureType = "url";
@@ -4409,26 +4612,55 @@ async function addInput(rootDir, input, options = {}) {
         title: captured.title,
         url: captured.normalizedUrl,
         markdown: captured.markdown,
+        sourceType: "arxiv",
         logDetails: ["capture_type=arxiv"]
       });
       captureType = "arxiv";
       normalizedUrl = captured.normalizedUrl;
+    } else if (doiFromInput(input)) {
+      const captured = await captureDoiMarkdown(rootDir, input, options);
+      prepared = prepareCapturedMarkdownInput({
+        title: captured.title,
+        url: captured.normalizedUrl,
+        markdown: captured.markdown,
+        sourceType: "doi",
+        attachments: captured.attachments,
+        logDetails: ["capture_type=doi"]
+      });
+      captureType = "doi";
+      normalizedUrl = captured.normalizedUrl;
     } else if (isTweetUrl(input)) {
       const captured = await captureTweetMarkdown(input, options);
       prepared = prepareCapturedMarkdownInput({
         title: captured.title,
         url: captured.normalizedUrl,
         markdown: captured.markdown,
+        sourceType: "tweet",
         logDetails: ["capture_type=tweet"]
       });
       captureType = "tweet";
       normalizedUrl = captured.normalizedUrl;
+    } else if (isHttpUrl(input)) {
+      const captured = await captureArticleMarkdown(rootDir, input, options, {
+        sourceType: "article",
+        sourceUrl: input
+      });
+      prepared = prepareCapturedMarkdownInput({
+        title: captured.title,
+        url: captured.normalizedUrl,
+        markdown: captured.markdown,
+        sourceType: "article",
+        attachments: captured.attachments,
+        logDetails: ["capture_type=article"]
+      });
+      captureType = "article";
+      normalizedUrl = captured.normalizedUrl;
     }
   } catch {
     fallback = true;
   }
   if (!prepared) {
-    normalizedUrl = arxivIdFromInput(input) ? `https://arxiv.org/abs/${arxivIdFromInput(input)}` : normalizeOriginUrl(input);
+    normalizedUrl = arxivIdFromInput(input) ? `https://arxiv.org/abs/${arxivIdFromInput(input)}` : doiFromInput(input) ? `https://doi.org/${encodeURIComponent(doiFromInput(input) ?? "")}` : normalizeOriginUrl(input);
     return {
       captureType: "url",
       manifest: await ingestInput(rootDir, normalizedUrl, options),
@@ -4684,7 +4916,7 @@ function buildSchemaPrompt(schema, instruction) {
 // src/vault.ts
 import fs15 from "fs/promises";
 import path18 from "path";
-import matter8 from "gray-matter";
+import matter9 from "gray-matter";
 import { z as z7 } from "zod";
 
 // src/analysis.ts
@@ -4991,6 +5223,7 @@ var DEFAULT_BENCHMARK_QUESTIONS = [
   "Where are the biggest knowledge gaps?",
   "What evidence should I read first?"
 ];
+var RESEARCH_BENCHMARK_QUESTION = "Which research sources should I read first, and why?";
 function nodeMap(graph) {
   return new Map(graph.nodes.map((node) => [node.id, node]));
 }
@@ -5040,9 +5273,68 @@ function benchmarkQueryTokens(graph, queryResult, pageContentsById) {
     queryTokens,
     reduction: 0,
     visitedNodeIds: queryResult.visitedNodeIds,
+    visitedEdgeIds: queryResult.visitedEdgeIds,
     pageIds: queryResult.pageIds
   };
 }
+function graphHash(graph) {
+  const hashedPages = graph.pages.filter((page) => page.kind !== "graph_report" && page.kind !== "community_summary");
+  const normalized = JSON.stringify(
+    {
+      nodes: [...graph.nodes].map((node) => ({
+        id: node.id,
+        type: node.type,
+        label: node.label,
+        pageId: node.pageId ?? null,
+        communityId: node.communityId ?? null,
+        degree: node.degree ?? null,
+        bridgeScore: node.bridgeScore ?? null,
+        isGodNode: node.isGodNode ?? false,
+        sourceIds: [...node.sourceIds].sort(),
+        projectIds: [...node.projectIds].sort()
+      })).sort((left, right) => left.id.localeCompare(right.id)),
+      edges: [...graph.edges].map((edge) => ({
+        id: edge.id,
+        source: edge.source,
+        target: edge.target,
+        relation: edge.relation,
+        status: edge.status,
+        evidenceClass: edge.evidenceClass,
+        confidence: edge.confidence,
+        provenance: [...edge.provenance].sort()
+      })).sort((left, right) => left.id.localeCompare(right.id)),
+      pages: [...hashedPages].map((page) => ({
+        id: page.id,
+        path: page.path,
+        kind: page.kind,
+        status: page.status,
+        sourceType: page.sourceType ?? null,
+        sourceIds: [...page.sourceIds].sort(),
+        projectIds: [...page.projectIds].sort(),
+        nodeIds: [...page.nodeIds].sort()
+      })).sort((left, right) => left.id.localeCompare(right.id)),
+      communities: [...graph.communities ?? []].map((community) => ({
+        id: community.id,
+        label: community.label,
+        nodeIds: [...community.nodeIds].sort()
+      })).sort((left, right) => left.id.localeCompare(right.id))
+    },
+    null,
+    0
+  );
+  return sha256(normalized);
+}
+function hasResearchSources(pages) {
+  return pages.some((page) => page.kind === "source" && Boolean(page.sourceType) && page.sourceType !== "url");
+}
+function defaultBenchmarkQuestionsForGraph(graph, maxQuestions = 3) {
+  const normalizedLimit = Math.max(1, Math.min(maxQuestions, DEFAULT_BENCHMARK_QUESTIONS.length));
+  const questions = [...DEFAULT_BENCHMARK_QUESTIONS];
+  if (hasResearchSources(graph.pages)) {
+    questions.unshift(RESEARCH_BENCHMARK_QUESTION);
+  }
+  return uniqueBy(questions, (item) => item).slice(0, normalizedLimit);
+}
 function buildBenchmarkArtifact(input) {
   const corpusTokens = Math.max(1, Math.round(input.corpusWords * (100 / 75)));
   const perQuestion = input.perQuestion.filter((entry) => entry.queryTokens > 0).map((entry) => ({
@@ -5051,8 +5343,18 @@ function buildBenchmarkArtifact(input) {
   }));
   const avgQueryTokens = perQuestion.length ? Math.max(1, Math.round(perQuestion.reduce((total, entry) => total + entry.queryTokens, 0) / perQuestion.length)) : 0;
   const reductionRatio = avgQueryTokens ? Number(Math.max(0, 1 - avgQueryTokens / Math.max(1, corpusTokens)).toFixed(3)) : 0;
+  const uniqueVisitedNodes = new Set(perQuestion.flatMap((entry) => entry.visitedNodeIds)).size;
+  const summary = {
+    questionCount: input.questions.length,
+    uniqueVisitedNodes,
+    finalContextTokens: avgQueryTokens,
+    naiveCorpusTokens: corpusTokens,
+    avgReduction: reductionRatio,
+    reductionRatio
+  };
   return {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    graphHash: graphHash(input.graph),
     corpusWords: input.corpusWords,
     corpusTokens,
     nodes: input.graph.nodes.length,
@@ -5060,7 +5362,9 @@ function buildBenchmarkArtifact(input) {
     avgQueryTokens,
     reductionRatio,
     sampleQuestions: input.questions,
-    perQuestion
+    perQuestion,
+    questionResults: perQuestion,
+    summary
   };
 }
 
@@ -5083,7 +5387,7 @@ function conflictConfidence(claimA, claimB) {
 // src/deep-lint.ts
 import fs11 from "fs/promises";
 import path14 from "path";
-import matter3 from "gray-matter";
+import matter4 from "gray-matter";
 import { z as z5 } from "zod";
 
 // src/findings.ts
@@ -5450,7 +5754,7 @@ async function loadContextPages(rootDir, graph) {
     contextPages.slice(0, 18).map(async (page) => {
       const absolutePath = path14.join(paths.wikiDir, page.path);
       const raw = await fs11.readFile(absolutePath, "utf8").catch(() => "");
-      const parsed = matter3(raw);
+      const parsed = matter4(raw);
       return {
         id: page.id,
         title: page.title,
@@ -5674,6 +5978,331 @@ async function runDeepLint(rootDir, structuralFindings, options = {}) {
   );
 }
 
+// src/graph-enrichment.ts
+var STOPWORDS2 = /* @__PURE__ */ new Set([
+  "about",
+  "after",
+  "also",
+  "among",
+  "and",
+  "around",
+  "because",
+  "been",
+  "being",
+  "between",
+  "both",
+  "does",
+  "from",
+  "into",
+  "just",
+  "like",
+  "many",
+  "more",
+  "most",
+  "much",
+  "note",
+  "only",
+  "other",
+  "over",
+  "same",
+  "such",
+  "than",
+  "that",
+  "their",
+  "them",
+  "there",
+  "these",
+  "this",
+  "through",
+  "under",
+  "very",
+  "what",
+  "when",
+  "where",
+  "which",
+  "while",
+  "with",
+  "would",
+  "your"
+]);
+function normalizeValue(value) {
+  return normalizeWhitespace(value).toLowerCase();
+}
+function addFeature(bucket, reason, value) {
+  if (!value) {
+    return;
+  }
+  const normalized = normalizeValue(value);
+  if (!normalized) {
+    return;
+  }
+  if (!bucket.has(reason)) {
+    bucket.set(reason, /* @__PURE__ */ new Set());
+  }
+  bucket.get(reason)?.add(normalized);
+}
+function themeTokens(value) {
+  return uniqueBy(
+    normalizeValue(value).split(/[^a-z0-9]+/i).filter((token) => token.length >= 4 && !STOPWORDS2.has(token)),
+    (token) => token
+  ).slice(0, 6);
+}
+function pairKey(left, right) {
+  return [left, right].sort((a, b) => a.localeCompare(b)).join("|");
+}
+function hasDistinctScope(left, right) {
+  if (left.pageId && right.pageId && left.pageId !== right.pageId) {
+    return true;
+  }
+  const leftSources = new Set(left.sourceIds);
+  const rightSources = new Set(right.sourceIds);
+  const leftOnly = [...leftSources].some((sourceId) => !rightSources.has(sourceId));
+  const rightOnly = [...rightSources].some((sourceId) => !leftSources.has(sourceId));
+  return leftOnly || rightOnly;
+}
+function supportCount(values) {
+  return values?.size ?? 0;
+}
+function similarityScore(reasons) {
+  const concept = supportCount(reasons.get("shared_concept"));
+  const entity = supportCount(reasons.get("shared_entity"));
+  const symbol = supportCount(reasons.get("shared_symbol"));
+  const rationale = supportCount(reasons.get("shared_rationale_theme"));
+  const sourceType = supportCount(reasons.get("shared_source_type"));
+  const tag = supportCount(reasons.get("shared_tag"));
+  const categoryCount = [...reasons.keys()].length;
+  const weighted = (concept ? 0.46 + Math.min(0.12, (concept - 1) * 0.04) : 0) + (entity ? 0.34 + Math.min(0.1, (entity - 1) * 0.03) : 0) + (symbol ? 0.24 + Math.min(0.08, (symbol - 1) * 0.02) : 0) + (rationale ? 0.18 + Math.min(0.08, (rationale - 1) * 0.03) : 0) + (sourceType ? 0.1 : 0) + (tag ? 0.12 + Math.min(0.04, (tag - 1) * 0.02) : 0);
+  const categoryBonus = categoryCount >= 3 ? 0.08 : categoryCount === 2 ? 0.04 : 0;
+  return Math.min(0.96, weighted + categoryBonus);
+}
+function describeSimilarityReasons(reasons) {
+  if (!reasons?.length) {
+    return "This link is inferred from multiple shared graph features.";
+  }
+  const labels = reasons.map(
+    (reason) => reason === "shared_concept" ? "shared concepts" : reason === "shared_entity" ? "shared entities" : reason === "shared_symbol" ? "shared symbols" : reason === "shared_rationale_theme" ? "shared rationale themes" : reason === "shared_source_type" ? "shared source type" : "shared tags"
+  );
+  return `This link is inferred from ${labels.join(", ")}.`;
+}
+function nodeContexts(nodes, manifests, analyses) {
+  const manifestsBySourceId = new Map(manifests.map((manifest) => [manifest.sourceId, manifest]));
+  const analysesBySourceId = new Map(analyses.map((analysis) => [analysis.sourceId, analysis]));
+  return nodes.filter((node) => node.type !== "symbol" && node.type !== "concept" && node.type !== "entity").map((node) => {
+    const features = /* @__PURE__ */ new Map();
+    if (node.type === "source" || node.type === "module") {
+      for (const sourceId of node.sourceIds) {
+        const analysis = analysesBySourceId.get(sourceId);
+        const manifest = manifestsBySourceId.get(sourceId);
+        if (!analysis) {
+          continue;
+        }
+        for (const concept of analysis.concepts) {
+          addFeature(features, "shared_concept", concept.name);
+        }
+        for (const entity of analysis.entities) {
+          addFeature(features, "shared_entity", entity.name);
+        }
+        if (manifest?.sourceType) {
+          addFeature(features, "shared_source_type", manifest.sourceType);
+        }
+        if (analysis.code) {
+          const exportedSymbols = analysis.code.symbols.filter((symbol) => symbol.exported);
+          for (const symbol of (exportedSymbols.length ? exportedSymbols : analysis.code.symbols).slice(0, 12)) {
+            addFeature(features, "shared_symbol", symbol.name);
+          }
+        }
+        for (const rationale of analysis.rationales) {
+          for (const token of themeTokens(rationale.text)) {
+            addFeature(features, "shared_rationale_theme", token);
+          }
+        }
+      }
+    } else if (node.type === "rationale") {
+      for (const sourceId of node.sourceIds) {
+        const analysis = analysesBySourceId.get(sourceId);
+        const manifest = manifestsBySourceId.get(sourceId);
+        if (manifest?.sourceType) {
+          addFeature(features, "shared_source_type", manifest.sourceType);
+        }
+        const rationale = analysis?.rationales.find((item) => item.id === node.id);
+        for (const token of themeTokens(rationale?.text ?? node.label)) {
+          addFeature(features, "shared_rationale_theme", token);
+        }
+      }
+    }
+    return { node, featureValues: features };
+  }).filter((context) => context.featureValues.size > 0);
+}
+function buildSemanticSimilarityEdges(nodes, edges, manifests, analyses) {
+  const contexts = nodeContexts(nodes, manifests, analyses);
+  const contextsById = new Map(contexts.map((context) => [context.node.id, context]));
+  const directPairs = new Set(edges.map((edge) => pairKey(edge.source, edge.target)));
+  const pairReasons = /* @__PURE__ */ new Map();
+  for (const reason of ["shared_concept", "shared_entity", "shared_symbol", "shared_rationale_theme", "shared_source_type"]) {
+    const buckets = /* @__PURE__ */ new Map();
+    for (const context of contexts) {
+      for (const value of context.featureValues.get(reason) ?? []) {
+        const bucketId = `${context.node.type}:${reason}:${value}`;
+        if (!buckets.has(bucketId)) {
+          buckets.set(bucketId, []);
+        }
+        buckets.get(bucketId)?.push(context.node.id);
+      }
+    }
+    for (const [bucketId, nodeIds] of buckets.entries()) {
+      if (nodeIds.length < 2) {
+        continue;
+      }
+      const value = bucketId.slice(bucketId.indexOf(`${reason}:`) + `${reason}:`.length);
+      const uniqueNodeIds = uniqueBy(nodeIds, (nodeId) => nodeId).sort((left, right) => left.localeCompare(right));
+      for (let index = 0; index < uniqueNodeIds.length; index++) {
+        const left = contextsById.get(uniqueNodeIds[index]);
+        if (!left) {
+          continue;
+        }
+        for (let cursor = index + 1; cursor < uniqueNodeIds.length; cursor++) {
+          const right = contextsById.get(uniqueNodeIds[cursor]);
+          if (!right || !hasDistinctScope(left.node, right.node)) {
+            continue;
+          }
+          const key = pairKey(left.node.id, right.node.id);
+          if (directPairs.has(key)) {
+            continue;
+          }
+          if (!pairReasons.has(key)) {
+            pairReasons.set(key, /* @__PURE__ */ new Map());
+          }
+          if (!pairReasons.get(key)?.has(reason)) {
+            pairReasons.get(key)?.set(reason, /* @__PURE__ */ new Set());
+          }
+          pairReasons.get(key)?.get(reason)?.add(value);
+        }
+      }
+    }
+  }
+  return [...pairReasons.entries()].flatMap(([key, reasons]) => {
+    const [leftId, rightId] = key.split("|");
+    const left = contextsById.get(leftId)?.node;
+    const right = contextsById.get(rightId)?.node;
+    if (!left || !right) {
+      return [];
+    }
+    const confidence = similarityScore(reasons);
+    if (confidence < 0.5) {
+      return [];
+    }
+    return [
+      {
+        id: `similar:${sha256(`${left.id}|${right.id}|${[...reasons.keys()].sort().join(",")}`).slice(0, 16)}`,
+        source: left.id,
+        target: right.id,
+        relation: "semantically_similar_to",
+        status: "inferred",
+        evidenceClass: "inferred",
+        confidence,
+        provenance: uniqueBy(
+          [...left.sourceIds, ...right.sourceIds].sort((a, b) => a.localeCompare(b)),
+          (value) => value
+        ),
+        similarityReasons: [...reasons.keys()].sort((a, b) => a.localeCompare(b))
+      }
+    ];
+  }).sort((left, right) => right.confidence - left.confidence || left.id.localeCompare(right.id));
+}
+function buildTopicHyperedges(graph) {
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const connectedSources = /* @__PURE__ */ new Map();
+  for (const edge of graph.edges) {
+    if (edge.relation !== "mentions" || edge.evidenceClass !== "extracted") {
+      continue;
+    }
+    const sourceNode = nodesById.get(edge.source);
+    const targetNode = nodesById.get(edge.target);
+    if (sourceNode?.type !== "source" || !(targetNode?.type === "concept" || targetNode?.type === "entity")) {
+      continue;
+    }
+    if (!connectedSources.has(targetNode.id)) {
+      connectedSources.set(targetNode.id, []);
+    }
+    connectedSources.get(targetNode.id)?.push(sourceNode.id);
+  }
+  return [...connectedSources.entries()].flatMap(([anchorId, members]) => {
+    const anchor = nodesById.get(anchorId);
+    const uniqueMembers = uniqueBy(members, (member) => member).sort((left, right) => left.localeCompare(right));
+    if (!anchor || uniqueMembers.length < 3) {
+      return [];
+    }
+    const nodeIds = [anchor.id, ...uniqueMembers];
+    const sourcePageIds = uniqueBy(nodeIds.map((nodeId) => nodesById.get(nodeId)?.pageId ?? "").filter(Boolean), (value) => value);
+    return [
+      {
+        id: `hyper:${sha256(`participate_in|${anchor.id}|${uniqueMembers.join("|")}`).slice(0, 16)}`,
+        label: anchor.label,
+        relation: "participate_in",
+        nodeIds,
+        evidenceClass: "extracted",
+        confidence: Math.min(0.96, 0.72 + uniqueMembers.length * 0.06),
+        sourcePageIds,
+        why: `${uniqueMembers.length} source nodes converge on ${anchor.label} through extracted mention edges.`
+      }
+    ];
+  });
+}
+function buildModuleFormHyperedges(graph) {
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const definedSymbols = /* @__PURE__ */ new Map();
+  for (const edge of graph.edges) {
+    if (edge.relation !== "defines" || edge.evidenceClass !== "extracted") {
+      continue;
+    }
+    const moduleNode = nodesById.get(edge.source);
+    const symbolNode = nodesById.get(edge.target);
+    if (moduleNode?.type !== "module" || symbolNode?.type !== "symbol") {
+      continue;
+    }
+    if (!definedSymbols.has(moduleNode.id)) {
+      definedSymbols.set(moduleNode.id, []);
+    }
+    definedSymbols.get(moduleNode.id)?.push(symbolNode.id);
+  }
+  return [...definedSymbols.entries()].flatMap(([moduleId, members]) => {
+    const moduleNode = nodesById.get(moduleId);
+    const uniqueMembers = uniqueBy(members, (member) => member).sort((left, right) => left.localeCompare(right));
+    if (!moduleNode || uniqueMembers.length < 3) {
+      return [];
+    }
+    const nodeIds = [moduleNode.id, ...uniqueMembers];
+    const sourcePageIds = uniqueBy(nodeIds.map((nodeId) => nodesById.get(nodeId)?.pageId ?? "").filter(Boolean), (value) => value);
+    return [
+      {
+        id: `hyper:${sha256(`form|${moduleNode.id}|${uniqueMembers.join("|")}`).slice(0, 16)}`,
+        label: `${moduleNode.label} API`,
+        relation: "form",
+        nodeIds,
+        evidenceClass: "extracted",
+        confidence: Math.min(0.98, 0.78 + uniqueMembers.length * 0.04),
+        sourcePageIds,
+        why: `${moduleNode.label} and ${uniqueMembers.length} defined symbols form one local module surface.`
+      }
+    ];
+  });
+}
+function enrichGraph(graph, manifests, analyses) {
+  const similarityEdges = buildSemanticSimilarityEdges(graph.nodes, graph.edges, manifests, analyses);
+  const enrichedEdges = [...graph.edges, ...similarityEdges].sort((left, right) => left.id.localeCompare(right.id));
+  const hyperedges = uniqueBy(
+    [
+      ...buildTopicHyperedges({ ...graph, edges: enrichedEdges, hyperedges: [] }),
+      ...buildModuleFormHyperedges({ ...graph, edges: enrichedEdges, hyperedges: [] })
+    ].sort((left, right) => right.confidence - left.confidence || left.label.localeCompare(right.label)),
+    (hyperedge) => hyperedge.id
+  );
+  return {
+    edges: enrichedEdges,
+    hyperedges
+  };
+}
+
 // src/graph-tools.ts
 function normalizeTarget(value) {
   return normalizeWhitespace(value).toLowerCase();
@@ -5684,6 +6313,9 @@ function nodeById(graph) {
 function pageById(graph) {
   return new Map(graph.pages.map((page) => [page.id, page]));
 }
+function hyperedgesForNode(graph, nodeId) {
+  return (graph.hyperedges ?? []).filter((hyperedge) => hyperedge.nodeIds.includes(nodeId)).sort((left, right) => right.confidence - left.confidence || left.label.localeCompare(right.label));
+}
 function scoreMatch(query, candidate) {
   const normalizedQuery = normalizeTarget(query);
   const normalizedCandidate = normalizeTarget(candidate);
@@ -5732,6 +6364,14 @@ function nodeMatches(graph, query) {
     score: Math.max(scoreMatch(query, node.label), scoreMatch(query, node.id))
   })).filter((match) => match.score > 0).sort((left, right) => right.score - left.score || left.label.localeCompare(right.label));
 }
+function hyperedgeMatches(graph, query) {
+  return (graph.hyperedges ?? []).map((hyperedge) => ({
+    type: "hyperedge",
+    id: hyperedge.id,
+    label: hyperedge.label,
+    score: Math.max(scoreMatch(query, hyperedge.label), scoreMatch(query, hyperedge.why), scoreMatch(query, hyperedge.relation))
+  })).filter((match) => match.score > 0).sort((left, right) => right.score - left.score || left.label.localeCompare(right.label));
+}
 function graphAdjacency(graph) {
   const adjacency = /* @__PURE__ */ new Map();
   const push = (nodeId, item) => {
@@ -5780,14 +6420,15 @@ function queryGraph(graph, question, searchResults, options) {
   const traversal = options?.traversal ?? "bfs";
   const budget = Math.max(3, Math.min(options?.budget ?? 12, 50));
   const matches = uniqueBy(
-    [...pageSearchMatches(graph, question, searchResults), ...nodeMatches(graph, question)],
+    [...pageSearchMatches(graph, question, searchResults), ...nodeMatches(graph, question), ...hyperedgeMatches(graph, question)],
     (match) => `${match.type}:${match.id}`
   ).sort((left, right) => right.score - left.score || left.label.localeCompare(right.label)).slice(0, 12);
   const pages = pageById(graph);
   const seeds = uniqueBy(
     [
       ...searchResults.flatMap((result) => pages.get(result.pageId)?.nodeIds ?? []),
-      ...matches.filter((match) => match.type === "node").map((match) => match.id)
+      ...matches.filter((match) => match.type === "node").map((match) => match.id),
+      ...matches.filter((match) => match.type === "hyperedge").flatMap((match) => graph.hyperedges.find((hyperedge) => hyperedge.id === match.id)?.nodeIds ?? [])
     ],
     (item) => item
   ).filter(Boolean);
@@ -5828,6 +6469,10 @@ function queryGraph(graph, question, searchResults, options) {
     visitedNodeIds.map((nodeId) => nodes.get(nodeId)?.communityId).filter((communityId) => Boolean(communityId)),
     (item) => item
   );
+  const hyperedgeIds = uniqueBy(
+    (graph.hyperedges ?? []).filter((hyperedge) => hyperedge.nodeIds.some((nodeId) => visitedNodeIds.includes(nodeId))).map((hyperedge) => hyperedge.id),
+    (item) => item
+  );
   return {
     question,
     traversal,
@@ -5838,6 +6483,7 @@ function queryGraph(graph, question, searchResults, options) {
     ),
     visitedNodeIds,
     visitedEdgeIds: [...visitedEdgeIds],
+    hyperedgeIds,
     pageIds,
     communities,
     matches,
@@ -5845,6 +6491,7 @@ function queryGraph(graph, question, searchResults, options) {
       `Seeds: ${seeds.join(", ") || "none"}`,
       `Visited nodes: ${visitedNodeIds.length}`,
       `Visited edges: ${visitedEdgeIds.size}`,
+      `Touched group patterns: ${hyperedgeIds.length}`,
       `Communities: ${communities.join(", ") || "none"}`,
       `Pages: ${pageIds.join(", ") || "none"}`
     ].join("\n")
@@ -5964,11 +6611,13 @@ function explainGraphTarget(graph, target) {
     page,
     community: communityLabel(graph, node.communityId),
     neighbors,
+    hyperedges: hyperedgesForNode(graph, node.id),
     summary: [
       `Node: ${node.label}`,
       `Type: ${node.type}`,
       `Community: ${node.communityId ?? "none"}`,
       `Neighbors: ${neighbors.length}`,
+      `Group patterns: ${hyperedgesForNode(graph, node.id).length}`,
       `Page: ${page?.path ?? "none"}`
     ].join("\n")
   };
@@ -5976,14 +6625,31 @@ function explainGraphTarget(graph, target) {
 function topGodNodes(graph, limit = 10) {
   return graph.nodes.filter((node) => node.isGodNode).sort((left, right) => (right.degree ?? 0) - (left.degree ?? 0)).slice(0, limit);
 }
+function listHyperedges(graph, target, limit = 25) {
+  if (!target) {
+    return [...graph.hyperedges ?? []].sort((left, right) => right.confidence - left.confidence || left.label.localeCompare(right.label)).slice(0, limit);
+  }
+  const node = resolveNode(graph, target);
+  if (node) {
+    return hyperedgesForNode(graph, node.id).slice(0, limit);
+  }
+  const page = graph.pages.find((candidate) => normalizeTarget(candidate.path) === normalizeTarget(target) || candidate.id === target);
+  if (!page) {
+    return [];
+  }
+  return (graph.hyperedges ?? []).filter((hyperedge) => hyperedge.sourcePageIds.includes(page.id) || page.nodeIds.some((nodeId) => hyperedge.nodeIds.includes(nodeId))).sort((left, right) => right.confidence - left.confidence || left.label.localeCompare(right.label)).slice(0, limit);
+}
 
 // src/markdown.ts
-import matter4 from "gray-matter";
-function uniqueStrings(values) {
+import matter5 from "gray-matter";
+function uniqueStrings2(values) {
   return uniqueBy(values.filter(Boolean), (value) => value);
 }
+function safeFrontmatter(value) {
+  return JSON.parse(JSON.stringify(value));
+}
 function decoratedTags(baseTags, decorations) {
-  return uniqueStrings([
+  return uniqueStrings2([
     ...baseTags,
     ...(decorations?.projectIds ?? []).map((projectId) => `project/${projectId}`),
     ...decorations?.extraTags ?? []
@@ -6062,6 +6728,7 @@ function buildSourcePage(manifest, analysis, schemaHash, metadata, relatedOutput
     page_id: pageId,
     kind: "source",
     title: analysis.title,
+    ...manifest.sourceType ? { source_type: manifest.sourceType } : {},
     tags: decoratedTags(analysis.code ? ["source", "code"] : ["source"], decorations),
     source_ids: [manifest.sourceId],
     project_ids: decorations?.projectIds ?? [],
@@ -6084,6 +6751,7 @@ function buildSourcePage(manifest, analysis, schemaHash, metadata, relatedOutput
     "",
     `Source ID: \`${manifest.sourceId}\``,
     manifest.url ? `Source URL: ${manifest.url}` : `Source Path: \`${manifest.originalPath ?? manifest.storedPath}\``,
+    ...manifest.sourceType ? [`Source Type: \`${manifest.sourceType}\``, ""] : [""],
     "",
     "## Summary",
     "",
@@ -6128,6 +6796,7 @@ function buildSourcePage(manifest, analysis, schemaHash, metadata, relatedOutput
       path: relativePath,
       title: analysis.title,
       kind: "source",
+      sourceType: manifest.sourceType,
       sourceIds: [manifest.sourceId],
       projectIds: decorations?.projectIds ?? [],
       nodeIds,
@@ -6145,7 +6814,7 @@ function buildSourcePage(manifest, analysis, schemaHash, metadata, relatedOutput
       compiledFrom: metadata.compiledFrom,
       managedBy: metadata.managedBy
     },
-    content: matter4.stringify(body, frontmatter)
+    content: matter5.stringify(body, safeFrontmatter(frontmatter))
   };
 }
 function buildModulePage(input) {
@@ -6160,7 +6829,7 @@ function buildModulePage(input) {
   const nodeIds = [code.moduleId, ...code.symbols.map((symbol) => symbol.id)];
   const localModuleBacklinks = input.localModules.map((moduleRef) => moduleRef.page.id);
   const relatedOutputs = input.relatedOutputs ?? [];
-  const backlinks = uniqueStrings([sourcePage.id, ...localModuleBacklinks, ...relatedOutputs.map((page) => page.id)]);
+  const backlinks = uniqueStrings2([sourcePage.id, ...localModuleBacklinks, ...relatedOutputs.map((page) => page.id)]);
   const importsSection = code.imports.length ? code.imports.map((item) => {
     const localModule = item.resolvedSourceId ? input.localModules.find((moduleRef) => moduleRef.sourceId === item.resolvedSourceId && moduleRef.reExport === item.reExport) : void 0;
     const importedBits = [
@@ -6206,9 +6875,9 @@ function buildModulePage(input) {
     source_hashes: {
       [manifest.sourceId]: manifest.contentHash
     },
-    related_page_ids: uniqueStrings([sourcePage.id, ...localModuleBacklinks, ...relatedOutputs.map((page) => page.id)]),
+    related_page_ids: uniqueStrings2([sourcePage.id, ...localModuleBacklinks, ...relatedOutputs.map((page) => page.id)]),
     related_node_ids: [],
-    related_source_ids: uniqueStrings([
+    related_source_ids: uniqueStrings2([
       manifest.sourceId,
       ...input.localModules.map((moduleRef) => moduleRef.sourceId),
       ...relatedOutputs.flatMap((page) => page.sourceIds)
@@ -6280,9 +6949,9 @@ function buildModulePage(input) {
       backlinks,
       schemaHash,
       sourceHashes: { [manifest.sourceId]: manifest.contentHash },
-      relatedPageIds: uniqueStrings([sourcePage.id, ...localModuleBacklinks, ...relatedOutputs.map((page) => page.id)]),
+      relatedPageIds: uniqueStrings2([sourcePage.id, ...localModuleBacklinks, ...relatedOutputs.map((page) => page.id)]),
       relatedNodeIds: [],
-      relatedSourceIds: uniqueStrings([
+      relatedSourceIds: uniqueStrings2([
         manifest.sourceId,
         ...input.localModules.map((moduleRef) => moduleRef.sourceId),
         ...relatedOutputs.flatMap((page) => page.sourceIds)
@@ -6292,7 +6961,7 @@ function buildModulePage(input) {
       compiledFrom: metadata.compiledFrom,
       managedBy: metadata.managedBy
     },
-    content: matter4.stringify(body, frontmatter)
+    content: matter5.stringify(body, frontmatter)
   };
 }
 function buildAggregatePage(kind, name, descriptions, sourceAnalyses, sourceHashes, schemaHash, metadata, relativePath, relatedOutputs = [], decorations) {
@@ -6363,7 +7032,7 @@ function buildAggregatePage(kind, name, descriptions, sourceAnalyses, sourceHash
       compiledFrom: metadata.compiledFrom,
       managedBy: metadata.managedBy
     },
-    content: matter4.stringify(body, frontmatter)
+    content: matter5.stringify(body, frontmatter)
   };
 }
 function buildIndexPage(pages, schemaHash, metadata, projectPages = []) {
@@ -6439,7 +7108,7 @@ function buildIndexPage(pages, schemaHash, metadata, projectPages = []) {
 }
 function buildSectionIndex(kind, pages, schemaHash, metadata, projectIds = []) {
   const title = kind.charAt(0).toUpperCase() + kind.slice(1);
-  return matter4.stringify(
+  return matter5.stringify(
     [`# ${title}`, "", ...pages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`), ""].join("\n"),
     {
       page_id: `${kind}:index`,
@@ -6470,38 +7139,219 @@ function nodeSummary(node) {
   const bridge = typeof node.bridgeScore === "number" ? `bridge=${node.bridgeScore}` : "";
   return [node.type, degree, bridge].filter(Boolean).join(", ");
 }
-function crossCommunityEdges(graph) {
+function sourceTypeForNode(node, pagesById) {
+  if (!node?.pageId) {
+    return void 0;
+  }
+  return pagesById.get(node.pageId)?.sourceType;
+}
+function supportingPathDetails(graph, edge) {
+  const path23 = shortestGraphPath(graph, edge.source, edge.target);
+  const edgesById = new Map(graph.edges.map((item) => [item.id, item]));
+  const pathEdges = path23.edgeIds.map((edgeId) => edgesById.get(edgeId)).filter((item) => Boolean(item));
+  return {
+    pathNodeIds: path23.nodeIds,
+    pathEdgeIds: path23.edgeIds,
+    pathRelations: pathEdges.map((item) => item.relation),
+    pathEvidenceClasses: pathEdges.map((item) => item.evidenceClass),
+    pathSummary: path23.summary
+  };
+}
+function surpriseScore(edge, graph, pagesById, hyperedgesByNodeId) {
   const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
-  return graph.edges.filter((edge) => {
-    const source = nodesById.get(edge.source);
-    const target = nodesById.get(edge.target);
-    return source?.communityId && target?.communityId && source.communityId !== target.communityId;
-  }).sort((left, right) => right.confidence - left.confidence || left.relation.localeCompare(right.relation));
+  const source = nodesById.get(edge.source);
+  const target = nodesById.get(edge.target);
+  const reasons = [];
+  let score = edge.confidence * 0.45;
+  if (source?.communityId && target?.communityId && source.communityId !== target.communityId) {
+    score += 0.18;
+    reasons.push(`it crosses communities ${source.communityId} and ${target.communityId}`);
+  }
+  if (source?.pageId && target?.pageId && source.pageId !== target.pageId) {
+    score += 0.12;
+    reasons.push("it spans different canonical pages");
+  }
+  if (source?.type && target?.type && source.type !== target.type) {
+    score += 0.08;
+    reasons.push(`it bridges ${source.type} and ${target.type} nodes`);
+  }
+  const sourceType = sourceTypeForNode(source, pagesById);
+  const targetType = sourceTypeForNode(target, pagesById);
+  if (sourceType && targetType && sourceType !== targetType) {
+    score += 0.07;
+    reasons.push(`it crosses source types (${sourceType} and ${targetType})`);
+  }
+  if ((source?.bridgeScore ?? 0) > 0 || (target?.bridgeScore ?? 0) > 0) {
+    score += 0.08;
+    reasons.push("a bridge node is involved");
+  }
+  if (edge.relation === "semantically_similar_to") {
+    score += 0.12;
+    reasons.push(describeSimilarityReasons(edge.similarityReasons));
+  }
+  if (edge.evidenceClass === "ambiguous") {
+    score += 0.08;
+    reasons.push("the supporting evidence is ambiguous");
+  }
+  const overlappingHyperedges = (hyperedgesByNodeId.get(edge.source) ?? []).filter((hyperedge) => hyperedge.nodeIds.includes(edge.target));
+  if (overlappingHyperedges.length) {
+    score += 0.06;
+    reasons.push(`it also appears in ${overlappingHyperedges.length} group pattern${overlappingHyperedges.length === 1 ? "" : "s"}`);
+  }
+  const why = normalizeWhitespace(reasons.join("; ")) || "it links graph regions that are otherwise weakly connected";
+  const explanation = normalizeWhitespace(`${source?.label ?? edge.source} connects to ${target?.label ?? edge.target} because ${why}.`);
+  return { score: Math.min(0.99, score), why, explanation };
+}
+function topSurprisingConnections(graph, pagesById) {
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const hyperedgesByNodeId = /* @__PURE__ */ new Map();
+  for (const hyperedge of graph.hyperedges ?? []) {
+    for (const nodeId of hyperedge.nodeIds) {
+      if (!hyperedgesByNodeId.has(nodeId)) {
+        hyperedgesByNodeId.set(nodeId, []);
+      }
+      hyperedgesByNodeId.get(nodeId)?.push(hyperedge);
+    }
+  }
+  return uniqueBy(
+    graph.edges.filter((edge) => {
+      const source = nodesById.get(edge.source);
+      const target = nodesById.get(edge.target);
+      return Boolean(
+        source?.communityId && target?.communityId && source.communityId !== target.communityId || edge.relation === "semantically_similar_to" || edge.evidenceClass === "ambiguous" || source?.type && target?.type && source.type !== target.type
+      );
+    }).map((edge) => {
+      const source = nodesById.get(edge.source);
+      const target = nodesById.get(edge.target);
+      const path23 = supportingPathDetails(graph, edge);
+      const scored = surpriseScore(edge, graph, pagesById, hyperedgesByNodeId);
+      return {
+        id: edge.id,
+        sourceNodeId: edge.source,
+        sourceLabel: source?.label ?? edge.source,
+        targetNodeId: edge.target,
+        targetLabel: target?.label ?? edge.target,
+        relation: edge.relation,
+        evidenceClass: edge.evidenceClass,
+        confidence: edge.confidence,
+        pathNodeIds: path23.pathNodeIds,
+        pathEdgeIds: path23.pathEdgeIds,
+        pathRelations: path23.pathRelations,
+        pathEvidenceClasses: path23.pathEvidenceClasses,
+        pathSummary: path23.pathSummary,
+        why: scored.why,
+        explanation: scored.explanation,
+        surpriseScore: scored.score
+      };
+    }).sort(
+      (left, right) => right.surpriseScore - left.surpriseScore || right.confidence - left.confidence || left.id.localeCompare(right.id)
+    ).slice(0, 8),
+    (connection) => connection.id
+  ).map(({ surpriseScore: _surpriseScore, ...connection }) => connection);
+}
+function topGroupPatterns(graph) {
+  return [...graph.hyperedges ?? []].sort(
+    (left, right) => right.confidence - left.confidence || right.nodeIds.length - left.nodeIds.length || left.label.localeCompare(right.label)
+  ).slice(0, 8);
 }
 function suggestedGraphQuestions(graph) {
   const thinCommunities = (graph.communities ?? []).filter((community) => community.nodeIds.length <= 2);
   const bridgeNodes = graph.nodes.filter((node) => (node.bridgeScore ?? 0) > 0).sort((left, right) => (right.bridgeScore ?? 0) - (left.bridgeScore ?? 0)).slice(0, 3);
-  return uniqueStrings([
+  return uniqueStrings2([
     ...thinCommunities.map((community) => `What sources would strengthen community ${community.label}?`),
     ...bridgeNodes.map((node) => `Why does ${node.label} connect multiple communities in the vault?`)
   ]).slice(0, 6);
 }
+function buildGraphReportArtifact(input) {
+  const pagesById = new Map(input.graph.pages.map((page) => [page.id, page]));
+  const godNodes = input.graph.nodes.filter((node) => node.isGodNode).sort((left, right) => (right.degree ?? 0) - (left.degree ?? 0)).slice(0, 8);
+  const bridgeNodes = input.graph.nodes.filter((node) => (node.bridgeScore ?? 0) > 0).sort((left, right) => (right.bridgeScore ?? 0) - (left.bridgeScore ?? 0)).slice(0, 8);
+  const thinCommunities = (input.graph.communities ?? []).filter((community) => community.nodeIds.length <= 2).map((community) => {
+    const page = input.communityPages.find((candidate) => candidate.id === `graph:${community.id}`);
+    return {
+      id: community.id,
+      label: community.label,
+      nodeCount: community.nodeIds.length,
+      pageId: page?.id,
+      path: page?.path,
+      title: page?.title
+    };
+  });
+  const surprisingConnections = topSurprisingConnections(input.graph, pagesById);
+  const groupPatterns = topGroupPatterns(input.graph);
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    graphHash: input.graphHash,
+    overview: {
+      nodes: input.graph.nodes.length,
+      edges: input.graph.edges.length,
+      pages: input.graph.pages.length,
+      communities: input.graph.communities?.length ?? 0
+    },
+    benchmark: input.benchmark ? {
+      generatedAt: input.benchmark.generatedAt,
+      stale: input.benchmarkStale ?? false,
+      summary: input.benchmark.summary,
+      questionCount: input.benchmark.sampleQuestions.length
+    } : void 0,
+    godNodes: godNodes.map((node) => ({
+      nodeId: node.id,
+      label: node.label,
+      pageId: node.pageId,
+      degree: node.degree,
+      bridgeScore: node.bridgeScore
+    })),
+    bridgeNodes: bridgeNodes.map((node) => ({
+      nodeId: node.id,
+      label: node.label,
+      pageId: node.pageId,
+      degree: node.degree,
+      bridgeScore: node.bridgeScore
+    })),
+    thinCommunities,
+    surprisingConnections,
+    groupPatterns,
+    suggestedQuestions: suggestedGraphQuestions(input.graph),
+    communityPages: input.communityPages.map((page) => ({
+      id: page.id,
+      path: page.path,
+      title: page.title
+    })),
+    recentResearchSources: (input.recentResearchSources ?? []).map((page) => ({
+      pageId: page.id,
+      path: page.path,
+      title: page.title,
+      sourceType: page.sourceType,
+      updatedAt: page.updatedAt
+    }))
+  };
+}
 function buildGraphReportPage(input) {
   const pageId = "graph:report";
   const pathValue = pagePathFor("graph_report", "report");
   const pagesById = new Map(input.graph.pages.map((page) => [page.id, page]));
   const nodesById = new Map(input.graph.nodes.map((node) => [node.id, node]));
-  const godNodes = input.graph.nodes.filter((node) => node.isGodNode).sort((left, right) => (right.degree ?? 0) - (left.degree ?? 0)).slice(0, 8);
-  const bridgeNodes = input.graph.nodes.filter((node) => (node.bridgeScore ?? 0) > 0).sort((left, right) => (right.bridgeScore ?? 0) - (left.bridgeScore ?? 0)).slice(0, 8);
-  const surprisingEdges = crossCommunityEdges(input.graph).slice(0, 8);
-  const thinCommunities = (input.graph.communities ?? []).filter((community) => community.nodeIds.length <= 2);
-  const relatedNodeIds = uniqueStrings([...godNodes, ...bridgeNodes].map((node) => node.id));
-  const relatedPageIds = uniqueStrings([
-    ...godNodes.map((node) => node.pageId ?? ""),
-    ...bridgeNodes.map((node) => node.pageId ?? ""),
-    ...input.communityPages.map((page) => page.id)
+  const relatedNodeIds = uniqueStrings2([
+    ...input.report.godNodes.map((node) => node.nodeId),
+    ...input.report.bridgeNodes.map((node) => node.nodeId),
+    ...input.report.surprisingConnections.flatMap((connection) => [
+      connection.sourceNodeId,
+      connection.targetNodeId,
+      ...connection.pathNodeIds
+    ]),
+    ...input.report.groupPatterns.flatMap((hyperedge) => hyperedge.nodeIds)
+  ]);
+  const relatedPageIds = uniqueStrings2([
+    ...input.report.godNodes.map((node) => node.pageId ?? ""),
+    ...input.report.bridgeNodes.map((node) => node.pageId ?? ""),
+    ...input.report.communityPages.map((page) => page.id),
+    ...input.report.recentResearchSources.map((page) => page.pageId),
+    ...input.report.groupPatterns.flatMap((hyperedge) => hyperedge.sourcePageIds)
+  ]);
+  const relatedSourceIds = uniqueStrings2([
+    ...relatedNodeIds.flatMap((nodeId) => nodesById.get(nodeId)?.sourceIds ?? []),
+    ...input.report.recentResearchSources.flatMap((page) => pagesById.get(page.pageId)?.sourceIds ?? [])
   ]);
-  const relatedSourceIds = uniqueStrings(relatedNodeIds.flatMap((nodeId) => nodesById.get(nodeId)?.sourceIds ?? []));
   const frontmatter = {
     page_id: pageId,
     kind: "graph_report",
@@ -6529,47 +7379,73 @@ function buildGraphReportPage(input) {
     "",
     "## Overview",
     "",
-    `- Nodes: ${input.graph.nodes.length}`,
-    `- Edges: ${input.graph.edges.length}`,
-    `- Pages: ${input.graph.pages.length}`,
-    `- Communities: ${input.graph.communities?.length ?? 0}`,
+    `- Nodes: ${input.report.overview.nodes}`,
+    `- Edges: ${input.report.overview.edges}`,
+    `- Pages: ${input.report.overview.pages}`,
+    `- Communities: ${input.report.overview.communities}`,
     "",
-    ...input.benchmark ? [
-      "## Benchmark",
-      "",
-      `- Corpus Tokens: ${input.benchmark.corpusTokens}`,
-      `- Avg Query Tokens: ${input.benchmark.avgQueryTokens}`,
-      `- Reduction Ratio: ${(input.benchmark.reductionRatio * 100).toFixed(1)}%`,
-      `- Sample Questions: ${input.benchmark.sampleQuestions.length}`,
+    "## Benchmark Summary",
+    "",
+    ...input.report.benchmark ? [
+      `- Generated At: ${input.report.benchmark.generatedAt}`,
+      `- Status: ${input.report.benchmark.stale ? "Stale (graph changed since benchmark ran)" : "Fresh"}`,
+      `- Naive Corpus Tokens: ${input.report.benchmark.summary.naiveCorpusTokens}`,
+      `- Final Context Tokens: ${input.report.benchmark.summary.finalContextTokens}`,
+      `- Unique Nodes Considered: ${input.report.benchmark.summary.uniqueVisitedNodes}`,
+      `- Reduction Ratio: ${(input.report.benchmark.summary.reductionRatio * 100).toFixed(1)}%`,
+      `- Questions: ${input.report.benchmark.questionCount}`,
       ""
-    ] : [],
-    "## God Nodes",
+    ] : ["- No benchmark results yet.", ""],
+    "## Top God Nodes",
     "",
-    ...godNodes.length ? godNodes.map((node) => `- ${graphNodeLink(node, pagesById)} (${nodeSummary(node)})`) : ["- No high-connectivity nodes detected."],
+    ...input.report.godNodes.length ? input.report.godNodes.map((node) => {
+      const graphNode = nodesById.get(node.nodeId);
+      return graphNode ? `- ${graphNodeLink(graphNode, pagesById)} (${nodeSummary(graphNode)})` : `- \`${node.nodeId}\``;
+    }) : ["- No high-connectivity nodes detected."],
     "",
-    "## Bridge Nodes",
+    "## Top Bridge Nodes",
     "",
-    ...bridgeNodes.length ? bridgeNodes.map((node) => `- ${graphNodeLink(node, pagesById)} (${nodeSummary(node)})`) : ["- No cross-community bridge nodes detected."],
+    ...input.report.bridgeNodes.length ? input.report.bridgeNodes.map((node) => {
+      const graphNode = nodesById.get(node.nodeId);
+      return graphNode ? `- ${graphNodeLink(graphNode, pagesById)} (${nodeSummary(graphNode)})` : `- \`${node.nodeId}\``;
+    }) : ["- No cross-community bridge nodes detected."],
     "",
     "## Communities",
     "",
-    ...input.communityPages.length ? input.communityPages.map((page) => `- ${pageLink(page)}`) : ["- No community summaries generated yet."],
+    ...input.report.communityPages.length ? input.report.communityPages.map((page) => `- ${pageLink(page)}`) : ["- No community summaries generated yet."],
     "",
-    "## Thin Communities",
+    "## Thin Or Underlinked Areas",
     "",
-    ...thinCommunities.length ? thinCommunities.map((community) => `- ${community.label} (${community.nodeIds.length} node(s))`) : ["- No thin communities detected."],
+    ...input.report.thinCommunities.length ? input.report.thinCommunities.map(
+      (community) => community.path ? `- [[${community.path.replace(/\.md$/, "")}|${community.title ?? community.label}]] (${community.nodeCount} node(s))` : `- ${community.label} (${community.nodeCount} node(s))`
+    ) : ["- No thin communities detected."],
     "",
-    "## Cross-Community Surprises",
+    "## Surprising Connections",
     "",
-    ...surprisingEdges.length ? surprisingEdges.map((edge) => {
-      const source = nodesById.get(edge.source);
-      const target = nodesById.get(edge.target);
-      return `- ${source ? graphNodeLink(source, pagesById) : `\`${edge.source}\``} ${edge.relation} ${target ? graphNodeLink(target, pagesById) : `\`${edge.target}\``} (${edge.evidenceClass}, ${edge.confidence.toFixed(2)})`;
+    ...input.report.surprisingConnections.length ? input.report.surprisingConnections.map((connection) => {
+      const source = nodesById.get(connection.sourceNodeId);
+      const target = nodesById.get(connection.targetNodeId);
+      const sourceLabel = source ? graphNodeLink(source, pagesById) : `\`${connection.sourceNodeId}\``;
+      const targetLabel = target ? graphNodeLink(target, pagesById) : `\`${connection.targetNodeId}\``;
+      return `- ${sourceLabel} ${connection.relation} ${targetLabel} (${connection.evidenceClass}, ${connection.confidence.toFixed(2)}). Why: ${connection.why}. ${connection.explanation} Path: ${connection.pathSummary}.`;
     }) : ["- No cross-community links detected."],
     "",
-    "## Suggested Follow-Up Questions",
+    "## Group Patterns",
+    "",
+    ...input.report.groupPatterns.length ? input.report.groupPatterns.map((hyperedge) => {
+      const linkedNodes = hyperedge.nodeIds.map((nodeId) => nodesById.get(nodeId)).filter((node) => Boolean(node)).map((node) => graphNodeLink(node, pagesById)).join(", ");
+      return `- ${hyperedge.label} (${hyperedge.relation}, ${hyperedge.evidenceClass}, ${hyperedge.confidence.toFixed(2)}). ${hyperedge.why} Members: ${linkedNodes}.`;
+    }) : ["- No multi-node group patterns detected."],
+    "",
+    "## New Research Sources",
+    "",
+    ...input.report.recentResearchSources.length ? input.report.recentResearchSources.map(
+      (page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]] (\`${page.sourceType}\`, updated ${page.updatedAt})`
+    ) : ["- No newly captured research sources since the previous compile."],
+    "",
+    "## Suggested Questions",
     "",
-    ...suggestedGraphQuestions(input.graph).map((question) => `- ${question}`),
+    ...input.report.suggestedQuestions.map((question) => `- ${question}`),
     ""
   ].join("\n");
   return {
@@ -6595,7 +7471,7 @@ function buildGraphReportPage(input) {
       compiledFrom: input.metadata.compiledFrom,
       managedBy: input.metadata.managedBy
     },
-    content: matter4.stringify(body, frontmatter)
+    content: matter5.stringify(body, frontmatter)
   };
 }
 function buildCommunitySummaryPage(input) {
@@ -6604,14 +7480,14 @@ function buildCommunitySummaryPage(input) {
   const nodesById = new Map(input.graph.nodes.map((node) => [node.id, node]));
   const pagesById = new Map(input.graph.pages.map((page) => [page.id, page]));
   const communityNodes = input.community.nodeIds.map((nodeId) => nodesById.get(nodeId)).filter((node) => Boolean(node));
-  const communityPageIds = uniqueStrings(communityNodes.map((node) => node.pageId ?? ""));
+  const communityPageIds = uniqueStrings2(communityNodes.map((node) => node.pageId ?? ""));
   const communityPages = communityPageIds.map((id) => pagesById.get(id)).filter((page) => Boolean(page));
   const externalEdges = input.graph.edges.filter((edge) => {
     const source = nodesById.get(edge.source);
     const target = nodesById.get(edge.target);
     return source?.communityId === input.community.id && target?.communityId && target.communityId !== input.community.id;
   }).slice(0, 8);
-  const relatedSourceIds = uniqueStrings(communityNodes.flatMap((node) => node.sourceIds));
+  const relatedSourceIds = uniqueStrings2(communityNodes.flatMap((node) => node.sourceIds));
   const frontmatter = {
     page_id: pageId,
     kind: "community_summary",
@@ -6630,7 +7506,7 @@ function buildCommunitySummaryPage(input) {
     backlinks: ["graph:report"],
     schema_hash: input.schemaHash,
     source_hashes: {},
-    related_page_ids: uniqueStrings(["graph:report", ...communityPageIds]),
+    related_page_ids: uniqueStrings2(["graph:report", ...communityPageIds]),
     related_node_ids: input.community.nodeIds,
     related_source_ids: relatedSourceIds
   };
@@ -6669,7 +7545,7 @@ function buildCommunitySummaryPage(input) {
       backlinks: ["graph:report"],
       schemaHash: input.schemaHash,
       sourceHashes: {},
-      relatedPageIds: uniqueStrings(["graph:report", ...communityPageIds]),
+      relatedPageIds: uniqueStrings2(["graph:report", ...communityPageIds]),
       relatedNodeIds: input.community.nodeIds,
       relatedSourceIds,
       createdAt: input.metadata.createdAt,
@@ -6677,11 +7553,11 @@ function buildCommunitySummaryPage(input) {
       compiledFrom: input.metadata.compiledFrom,
       managedBy: input.metadata.managedBy
     },
-    content: matter4.stringify(body, frontmatter)
+    content: matter5.stringify(body, frontmatter)
   };
 }
 function buildProjectsIndex(projectPages, schemaHash, metadata) {
-  return matter4.stringify(
+  return matter5.stringify(
     [
       "# Projects",
       "",
@@ -6711,7 +7587,7 @@ function buildProjectsIndex(projectPages, schemaHash, metadata) {
 }
 function buildProjectIndex(input) {
   const title = `Project: ${input.projectId}`;
-  return matter4.stringify(
+  return matter5.stringify(
     [
       `# ${title}`,
       "",
@@ -6824,7 +7700,7 @@ function buildOutputPage(input) {
       outputFormat: input.outputFormat,
       outputAssets
     },
-    content: matter4.stringify(
+    content: matter5.stringify(
       (input.outputFormat === "slides" ? [
         input.answer,
         "",
@@ -6950,7 +7826,7 @@ function buildExploreHubPage(input) {
       outputFormat: input.outputFormat,
       outputAssets
     },
-    content: matter4.stringify(
+    content: matter5.stringify(
       (input.outputFormat === "slides" ? [
         `# ${title}`,
         "",
@@ -7216,12 +8092,12 @@ function buildOutputAssetManifest(input) {
 // src/outputs.ts
 import fs13 from "fs/promises";
 import path16 from "path";
-import matter6 from "gray-matter";
+import matter7 from "gray-matter";
 
 // src/pages.ts
 import fs12 from "fs/promises";
 import path15 from "path";
-import matter5 from "gray-matter";
+import matter6 from "gray-matter";
 function normalizeStringArray(value) {
   return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 }
@@ -7242,6 +8118,9 @@ function normalizePageStatus(value, fallback = "active") {
 function normalizePageManager(value, fallback = "system") {
   return value === "human" || value === "system" ? value : fallback;
 }
+function normalizeSourceType(value) {
+  return value === "arxiv" || value === "doi" || value === "tweet" || value === "article" || value === "url" ? value : void 0;
+}
 function normalizeOutputFormat(value, fallback = "markdown") {
   return value === "report" || value === "slides" || value === "chart" || value === "image" ? value : fallback;
 }
@@ -7293,7 +8172,7 @@ async function loadExistingManagedPageState(absolutePath, defaults = {}) {
     };
   }
   const content = await fs12.readFile(absolutePath, "utf8");
-  const parsed = matter5(content);
+  const parsed = matter6(content);
   return {
     status: normalizePageStatus(parsed.data.status, defaults.status ?? "active"),
     managedBy: normalizePageManager(parsed.data.managed_by, defaults.managedBy ?? "system"),
@@ -7327,7 +8206,7 @@ function inferPageKind(relativePath, explicitKind = void 0) {
   return "index";
 }
 function parseStoredPage(relativePath, content, defaults = {}) {
-  const parsed = matter5(content);
+  const parsed = matter6(content);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const fallbackCreatedAt = defaults.createdAt ?? now;
   const fallbackUpdatedAt = defaults.updatedAt ?? fallbackCreatedAt;
@@ -7347,6 +8226,7 @@ function parseStoredPage(relativePath, content, defaults = {}) {
     path: relativePath,
     title,
     kind,
+    sourceType: normalizeSourceType(parsed.data.source_type),
     sourceIds,
     projectIds,
     nodeIds,
@@ -7379,7 +8259,7 @@ async function loadInsightPages(wikiDir) {
   for (const absolutePath of files) {
     const relativePath = toPosix(path15.relative(wikiDir, absolutePath));
     const content = await fs12.readFile(absolutePath, "utf8");
-    const parsed = matter5(content);
+    const parsed = matter6(content);
     const stats = await fs12.stat(absolutePath);
     const title = typeof parsed.data.title === "string" ? parsed.data.title : path15.basename(absolutePath, ".md");
     const sourceIds = normalizeStringArray(parsed.data.source_ids);
@@ -7464,7 +8344,7 @@ async function loadSavedOutputPages(wikiDir) {
     const relativePath = path16.posix.join("outputs", entry.name);
     const absolutePath = path16.join(outputsDir, entry.name);
     const content = await fs13.readFile(absolutePath, "utf8");
-    const parsed = matter6(content);
+    const parsed = matter7(content);
     const slug = entry.name.replace(/\.md$/, "");
     const title = typeof parsed.data.title === "string" ? parsed.data.title : slug;
     const pageId = typeof parsed.data.page_id === "string" ? parsed.data.page_id : `output:${slug}`;
@@ -7516,7 +8396,7 @@ async function loadSavedOutputPages(wikiDir) {
 // src/search.ts
 import fs14 from "fs/promises";
 import path17 from "path";
-import matter7 from "gray-matter";
+import matter8 from "gray-matter";
 function getDatabaseSync() {
   const builtin = process.getBuiltinModule?.("node:sqlite");
   if (!builtin?.DatabaseSync) {
@@ -7534,6 +8414,9 @@ function normalizeKind(value) {
 function normalizeStatus(value) {
   return value === "draft" || value === "candidate" || value === "active" || value === "archived" ? value : void 0;
 }
+function normalizeSourceType2(value) {
+  return value === "arxiv" || value === "doi" || value === "tweet" || value === "article" || value === "url" ? value : void 0;
+}
 async function rebuildSearchIndex(dbPath, pages, wikiDir) {
   await ensureDir(path17.dirname(dbPath));
   const DatabaseSync = getDatabaseSync();
@@ -7549,6 +8432,7 @@ async function rebuildSearchIndex(dbPath, pages, wikiDir) {
       body TEXT NOT NULL,
       kind TEXT NOT NULL,
       status TEXT NOT NULL,
+      source_type TEXT NOT NULL,
       project_ids TEXT NOT NULL,
       project_key TEXT NOT NULL
     );
@@ -7562,12 +8446,12 @@ async function rebuildSearchIndex(dbPath, pages, wikiDir) {
     DELETE FROM pages;
   `);
   const insertPage = db.prepare(
-    "INSERT INTO pages (id, path, title, body, kind, status, project_ids, project_key) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+    "INSERT INTO pages (id, path, title, body, kind, status, source_type, project_ids, project_key) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
   );
   for (const page of pages) {
     const absolutePath = path17.join(wikiDir, page.path);
     const content = await fs14.readFile(absolutePath, "utf8");
-    const parsed = matter7(content);
+    const parsed = matter8(content);
     insertPage.run(
       page.id,
       page.path,
@@ -7575,6 +8459,7 @@ async function rebuildSearchIndex(dbPath, pages, wikiDir) {
       parsed.content,
       page.kind,
       page.status,
+      typeof parsed.data.source_type === "string" ? parsed.data.source_type : "",
       JSON.stringify(page.projectIds),
       page.projectIds.map((projectId) => `|${projectId}|`).join("")
     );
@@ -7608,6 +8493,10 @@ function searchPages(dbPath, query, limitOrOptions = 5) {
       params.push(`%|${options.project}|%`);
     }
   }
+  if (options.sourceType && options.sourceType !== "all") {
+    clauses.push("pages.source_type = ?");
+    params.push(options.sourceType);
+  }
   const statement = db.prepare(`
     SELECT
       pages.id AS pageId,
@@ -7615,6 +8504,7 @@ function searchPages(dbPath, query, limitOrOptions = 5) {
       pages.title AS title,
       pages.kind AS kind,
       pages.status AS status,
+      pages.source_type AS sourceType,
       pages.project_ids AS projectIds,
       snippet(page_search, 1, '[', ']', '...', 16) AS snippet,
       bm25(page_search) AS rank
@@ -7642,13 +8532,14 @@ function searchPages(dbPath, query, limitOrOptions = 5) {
     title: String(row.title ?? ""),
     kind: normalizeKind(row.kind),
     status: normalizeStatus(row.status),
+    sourceType: normalizeSourceType2(row.sourceType),
     snippet: String(row.snippet ?? ""),
     rank: Number(row.rank ?? 0)
   }));
 }
 
 // src/vault.ts
-function uniqueStrings2(values) {
+function uniqueStrings3(values) {
   return uniqueBy(values.filter(Boolean), (value) => value);
 }
 function normalizeOutputFormat2(format) {
@@ -7809,7 +8700,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-X5PMZTZY.js");
+  const { createProvider: createProvider2 } = await import("./registry-6KZMA3XM.js");
   return createProvider2(preferredProviderId, providerConfig, rootDir);
 }
 async function generateOutputArtifacts(rootDir, input) {
@@ -8013,7 +8904,7 @@ function normalizeProjectRoot(root) {
 function projectEntries(config) {
   return Object.entries(config.projects ?? {}).map(([id, project]) => ({
     id,
-    roots: uniqueStrings2(project.roots.map(normalizeProjectRoot)).filter(Boolean),
+    roots: uniqueStrings3(project.roots.map(normalizeProjectRoot)).filter(Boolean),
     schemaPath: project.schemaPath
   })).sort((left, right) => left.id.localeCompare(right.id));
 }
@@ -8061,11 +8952,11 @@ function resolveSourceProjects(rootDir, manifests, config) {
   return Object.fromEntries(manifests.map((manifest) => [manifest.sourceId, resolveSourceProjectId(rootDir, manifest, config)]));
 }
 function scopedProjectIdsFromSources(sourceIds, sourceProjects) {
-  const projectIds = uniqueStrings2(sourceIds.map((sourceId) => sourceProjects[sourceId] ?? "").filter(Boolean));
+  const projectIds = uniqueStrings3(sourceIds.map((sourceId) => sourceProjects[sourceId] ?? "").filter(Boolean));
   return projectIds.length === 1 ? projectIds : [];
 }
 function schemaProjectIdsFromPages(pageIds, pageMap2) {
-  return uniqueStrings2(
+  return uniqueStrings3(
     pageIds.flatMap((pageId) => pageMap2.get(pageId)?.projectIds ?? []).filter(Boolean).sort((left, right) => left.localeCompare(right))
   );
 }
@@ -8074,7 +8965,7 @@ function categoryTagsForSchema(schema, texts) {
   if (!haystack) {
     return [];
   }
-  return uniqueStrings2(
+  return uniqueStrings3(
     schemaCategoryLabels({ path: "", hash: "", content: schema.content }).filter((label) => haystack.includes(label.toLowerCase())).map((label) => `category/${slugify(label)}`)
   ).slice(0, 3);
 }
@@ -8285,7 +9176,7 @@ async function buildManagedContent(absolutePath, defaults, build) {
   return content;
 }
 function indexCompiledFrom(pages) {
-  return uniqueStrings2(pages.flatMap((page) => page.sourceIds));
+  return uniqueStrings3(pages.flatMap((page) => page.sourceIds));
 }
 function deriveGraphMetrics(nodes, edges) {
   const adjacency = /* @__PURE__ */ new Map();
@@ -8678,17 +9569,42 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
     ...conceptMap.values(),
     ...entityMap.values()
   ];
-  const metrics = deriveGraphMetrics(graphNodes, edges);
+  const enriched = enrichGraph(
+    {
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      nodes: graphNodes,
+      edges,
+      communities: [],
+      sources: manifests,
+      pages
+    },
+    manifests,
+    analyses
+  );
+  const metrics = deriveGraphMetrics(graphNodes, enriched.edges);
   return {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     nodes: metrics.nodes,
-    edges,
+    edges: enriched.edges,
+    hyperedges: enriched.hyperedges,
     communities: metrics.communities,
     sources: manifests,
     pages
   };
 }
-async function buildGraphOrientationPages(graph, paths, schemaHash) {
+function recentResearchSourcePages(graph, previousCompiledAt) {
+  const previousTimestamp = previousCompiledAt ? Date.parse(previousCompiledAt) : Number.NaN;
+  return graph.pages.filter(
+    (page) => page.kind === "source" && Boolean(page.sourceType) && page.sourceType !== "url"
+  ).filter((page) => Number.isNaN(previousTimestamp) || Date.parse(page.updatedAt) > previousTimestamp).sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || left.title.localeCompare(right.title)).slice(0, 8).map((page) => ({
+    id: page.id,
+    path: page.path,
+    title: page.title,
+    updatedAt: page.updatedAt,
+    sourceType: page.sourceType
+  }));
+}
+async function buildGraphOrientationPages(graph, paths, schemaHash, previousCompiledAt) {
   const benchmark = await readJsonFile(paths.benchmarkPath);
   const communityRecords = [];
   for (const community of graph.communities ?? []) {
@@ -8698,7 +9614,7 @@ async function buildGraphOrientationPages(graph, paths, schemaHash) {
         absolutePath,
         {
           managedBy: "system",
-          compiledFrom: uniqueStrings2(
+          compiledFrom: uniqueStrings3(
             community.nodeIds.flatMap((nodeId) => graph.nodes.find((node) => node.id === nodeId)?.sourceIds ?? [])
           ),
           confidence: 1
@@ -8712,23 +9628,33 @@ async function buildGraphOrientationPages(graph, paths, schemaHash) {
       )
     );
   }
+  const report = buildGraphReportArtifact({
+    graph,
+    communityPages: communityRecords.map((record) => record.page),
+    benchmark,
+    benchmarkStale: benchmark ? benchmark.graphHash !== graphHash(graph) : false,
+    recentResearchSources: recentResearchSourcePages(graph, previousCompiledAt),
+    graphHash: graphHash(graph)
+  });
   const reportAbsolutePath = path18.join(paths.wikiDir, "graph", "report.md");
   const reportRecord = await buildManagedGraphPage(
     reportAbsolutePath,
     {
       managedBy: "system",
-      compiledFrom: uniqueStrings2(graph.pages.flatMap((page) => page.sourceIds)),
+      compiledFrom: uniqueStrings3(graph.pages.flatMap((page) => page.sourceIds)),
       confidence: 1
     },
     (metadata) => buildGraphReportPage({
       graph,
       schemaHash,
       metadata,
-      communityPages: communityRecords.map((record) => record.page),
-      benchmark
+      report
     })
   );
-  return [reportRecord, ...communityRecords];
+  return {
+    records: [reportRecord, ...communityRecords],
+    report
+  };
 }
 async function writePage(wikiDir, relativePath, content, changedPages) {
   const absolutePath = path18.resolve(wikiDir, relativePath);
@@ -9025,7 +9951,7 @@ async function syncVaultArtifacts(rootDir, input) {
       const itemKind = kind === "concepts" ? "concept" : "entity";
       const slug = slugify(aggregate.name);
       const pageId = `${itemKind}:${slug}`;
-      const sourceIds = uniqueStrings2(aggregate.sourceAnalyses.map((item) => item.sourceId));
+      const sourceIds = uniqueStrings3(aggregate.sourceAnalyses.map((item) => item.sourceId));
       const projectIds = scopedProjectIdsFromSources(sourceIds, input.sourceProjects);
       const schemaHash = effectiveHashForProject(input.schemas, projectIds[0] ?? null);
       const previousEntry = input.previousState?.candidateHistory?.[pageId];
@@ -9091,9 +10017,9 @@ async function syncVaultArtifacts(rootDir, input) {
   const compiledPages = records.map((record) => record.page);
   const basePages = [...compiledPages, ...input.outputPages, ...input.insightPages];
   const baseGraph = buildGraph(input.manifests, input.analyses, basePages, input.sourceProjects, input.codeIndex);
-  const graphOrientationRecords = await buildGraphOrientationPages(baseGraph, paths, globalSchemaHash);
-  records.push(...graphOrientationRecords);
-  const allPages = [...basePages, ...graphOrientationRecords.map((record) => record.page)];
+  const graphOrientation = await buildGraphOrientationPages(baseGraph, paths, globalSchemaHash, input.previousState?.generatedAt);
+  records.push(...graphOrientation.records);
+  const allPages = [...basePages, ...graphOrientation.records.map((record) => record.page)];
   const graph = {
     ...baseGraph,
     pages: allPages
@@ -9226,7 +10152,7 @@ async function syncVaultArtifacts(rootDir, input) {
   const nextPagePaths = new Set(records.map((record) => record.page.path));
   const obsoleteGraphPaths = (previousGraph?.pages ?? []).filter((page) => page.kind !== "output" && page.kind !== "insight").map((page) => page.path).filter((relativePath) => !nextPagePaths.has(relativePath));
   const existingProjectIndexPaths = (await listFilesRecursive(paths.projectsDir)).filter((absolutePath) => absolutePath.endsWith(".md")).map((absolutePath) => toPosix(path18.relative(paths.wikiDir, absolutePath))).filter((relativePath) => !nextPagePaths.has(relativePath));
-  const obsoletePaths = uniqueStrings2([...obsoleteGraphPaths, ...existingProjectIndexPaths]);
+  const obsoletePaths = uniqueStrings3([...obsoleteGraphPaths, ...existingProjectIndexPaths]);
   const changedFiles = [];
   for (const record of records) {
     const absolutePath = path18.join(paths.wikiDir, record.page.path);
@@ -9258,6 +10184,7 @@ async function syncVaultArtifacts(rootDir, input) {
     await fs15.rm(path18.join(paths.wikiDir, relativePath), { force: true });
   }
   await writeJsonFile(paths.graphPath, graph);
+  await writeJsonFile(path18.join(paths.wikiDir, "graph", "report.json"), graphOrientation.report);
   await writeJsonFile(paths.codeIndexPath, input.codeIndex);
   await writeJsonFile(paths.compileStatePath, {
     generatedAt: graph.generatedAt,
@@ -9283,7 +10210,7 @@ async function syncVaultArtifacts(rootDir, input) {
   return {
     graph,
     allPages,
-    changedPages: uniqueStrings2([...changedPages, ...writeChanges]),
+    changedPages: uniqueStrings3([...changedPages, ...writeChanges]),
     promotedPageIds,
     candidatePageCount: candidatePages.length,
     staged: false
@@ -9292,18 +10219,20 @@ async function syncVaultArtifacts(rootDir, input) {
 async function refreshIndexesAndSearch(rootDir, pages) {
   const { config, paths } = await loadVaultConfig(rootDir);
   const schemas = await loadVaultSchemas(rootDir);
+  const compileState = await readJsonFile(paths.compileStatePath);
   const globalSchemaHash = schemas.effective.global.hash;
   const currentGraph = await readJsonFile(paths.graphPath);
   const basePages = pages.filter((page) => page.kind !== "graph_report" && page.kind !== "community_summary");
-  const graphOrientationRecords = currentGraph ? await buildGraphOrientationPages(
+  const graphOrientation = currentGraph ? await buildGraphOrientationPages(
     {
       ...currentGraph,
       pages: basePages
     },
     paths,
-    globalSchemaHash
-  ) : [];
-  const pagesWithGraph = sortGraphPages([...basePages, ...graphOrientationRecords.map((record) => record.page)]);
+    globalSchemaHash,
+    compileState?.generatedAt
+  ) : { records: [], report: null };
+  const pagesWithGraph = sortGraphPages([...basePages, ...graphOrientation.records.map((record) => record.page)]);
   if (currentGraph) {
     await writeJsonFile(paths.graphPath, {
       ...currentGraph,
@@ -9409,9 +10338,12 @@ async function refreshIndexesAndSearch(rootDir, pages) {
       )
     );
   }
-  for (const record of graphOrientationRecords) {
+  for (const record of graphOrientation.records) {
     await writeFileIfChanged(path18.join(paths.wikiDir, record.page.path), record.content);
   }
+  if (graphOrientation.report) {
+    await writeJsonFile(path18.join(paths.wikiDir, "graph", "report.json"), graphOrientation.report);
+  }
   const existingProjectIndexPaths = (await listFilesRecursive(paths.projectsDir)).filter((absolutePath) => absolutePath.endsWith(".md")).map((absolutePath) => toPosix(path18.relative(paths.wikiDir, absolutePath)));
   const allowedProjectIndexPaths = /* @__PURE__ */ new Set([
     "projects/index.md",
@@ -9421,7 +10353,7 @@ async function refreshIndexesAndSearch(rootDir, pages) {
     existingProjectIndexPaths.filter((relativePath) => !allowedProjectIndexPaths.has(relativePath)).map((relativePath) => fs15.rm(path18.join(paths.wikiDir, relativePath), { force: true }))
   );
   const existingGraphPages = (await listFilesRecursive(path18.join(paths.wikiDir, "graph").replace(/\/$/, "")).catch(() => [])).filter((absolutePath) => absolutePath.endsWith(".md")).map((absolutePath) => toPosix(path18.relative(paths.wikiDir, absolutePath)));
-  const allowedGraphPages = /* @__PURE__ */ new Set(["graph/index.md", ...graphOrientationRecords.map((record) => record.page.path)]);
+  const allowedGraphPages = /* @__PURE__ */ new Set(["graph/index.md", ...graphOrientation.records.map((record) => record.page.path)]);
   await Promise.all(
     existingGraphPages.filter((relativePath) => !allowedGraphPages.has(relativePath)).map((relativePath) => fs15.rm(path18.join(paths.wikiDir, relativePath), { force: true }))
   );
@@ -9438,7 +10370,7 @@ async function prepareOutputPageSave(rootDir, input) {
       status: "active",
       createdAt: now,
       updatedAt: now,
-      compiledFrom: uniqueStrings2(input.relatedSourceIds ?? input.citations),
+      compiledFrom: uniqueStrings3(input.relatedSourceIds ?? input.citations),
       managedBy: "system",
       confidence: 0.74
     }
@@ -9479,7 +10411,7 @@ async function prepareExploreHubSave(rootDir, input) {
       status: "active",
       createdAt: now,
       updatedAt: now,
-      compiledFrom: uniqueStrings2(input.citations),
+      compiledFrom: uniqueStrings3(input.citations),
       managedBy: "system",
       confidence: 0.76
     }
@@ -9542,6 +10474,7 @@ async function stageOutputApprovalBundle(rootDir, stagedPages) {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     nodes: previousGraph?.nodes ?? [],
     edges: previousGraph?.edges ?? [],
+    hyperedges: previousGraph?.hyperedges ?? [],
     sources: previousGraph?.sources ?? [],
     pages: nextPages
   };
@@ -9577,7 +10510,7 @@ async function executeQuery(rootDir, question, format) {
       const absolutePath = path18.join(paths.wikiDir, result.path);
       try {
         const content = await fs15.readFile(absolutePath, "utf8");
-        const parsed = matter8(content);
+        const parsed = matter9(content);
         return `# ${result.title}
 ${truncate(normalizeWhitespace(parsed.content), 1200)}`;
       } catch {
@@ -9850,6 +10783,7 @@ async function acceptApproval(rootDir, approvalId, targets = []) {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     nodes: currentGraph?.nodes ?? bundleGraph?.nodes ?? [],
     edges: currentGraph?.edges ?? bundleGraph?.edges ?? [],
+    hyperedges: currentGraph?.hyperedges ?? bundleGraph?.hyperedges ?? [],
     sources: currentGraph?.sources ?? bundleGraph?.sources ?? [],
     pages: sortGraphPages(nextPages)
   };
@@ -9927,13 +10861,13 @@ async function promoteCandidate(rootDir, target) {
   const graph = await readJsonFile(paths.graphPath);
   const candidate = resolveCandidateTarget(graph?.pages ?? [], target);
   const raw = await fs15.readFile(path18.join(paths.wikiDir, candidate.path), "utf8");
-  const parsed = matter8(raw);
+  const parsed = matter9(raw);
   const nextUpdatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const nextContent = matter8.stringify(parsed.content, {
+  const nextContent = matter9.stringify(parsed.content, {
     ...parsed.data,
     status: "active",
     updated_at: nextUpdatedAt,
-    tags: uniqueStrings2([candidate.kind, ...Array.isArray(parsed.data.tags) ? parsed.data.tags : []]).filter(
+    tags: uniqueStrings3([candidate.kind, ...Array.isArray(parsed.data.tags) ? parsed.data.tags : []]).filter(
       (tag) => tag !== "candidate"
     )
   });
@@ -9950,6 +10884,7 @@ async function promoteCandidate(rootDir, target) {
     generatedAt: nextUpdatedAt,
     nodes: graph?.nodes ?? [],
     edges: graph?.edges ?? [],
+    hyperedges: graph?.hyperedges ?? [],
     sources: graph?.sources ?? [],
     pages: nextPages
   };
@@ -9991,6 +10926,7 @@ async function archiveCandidate(rootDir, target) {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     nodes: graph?.nodes ?? [],
     edges: graph?.edges ?? [],
+    hyperedges: graph?.hyperedges ?? [],
     sources: graph?.sources ?? [],
     pages: nextPages
   };
@@ -10075,7 +11011,7 @@ async function initVault(rootDir, options = {}) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
   await writeFileIfChanged(
     insightsIndexPath,
-    matter8.stringify(
+    matter9.stringify(
       [
         "# Insights",
         "",
@@ -10108,7 +11044,7 @@ async function initVault(rootDir, options = {}) {
   );
   await writeFileIfChanged(
     path18.join(paths.wikiDir, "projects", "index.md"),
-    matter8.stringify(["# Projects", "", "- Run `swarmvault compile` to build project rollups.", ""].join("\n"), {
+    matter9.stringify(["# Projects", "", "- Run `swarmvault compile` to build project rollups.", ""].join("\n"), {
       page_id: "projects:index",
       kind: "index",
       title: "Projects",
@@ -10130,7 +11066,7 @@ async function initVault(rootDir, options = {}) {
   );
   await writeFileIfChanged(
     path18.join(paths.wikiDir, "candidates", "index.md"),
-    matter8.stringify(["# Candidates", "", "- Run `swarmvault compile` to stage candidate pages.", ""].join("\n"), {
+    matter9.stringify(["# Candidates", "", "- Run `swarmvault compile` to stage candidate pages.", ""].join("\n"), {
       page_id: "candidates:index",
       kind: "index",
       title: "Candidates",
@@ -10154,6 +11090,20 @@ async function initVault(rootDir, options = {}) {
     await ensureObsidianWorkspace(rootDir);
   }
 }
+async function runConfiguredBenchmark(rootDir, config) {
+  if (config.benchmark?.enabled === false) {
+    return { ok: true };
+  }
+  try {
+    await benchmarkVault(rootDir);
+    return { ok: true };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
 async function compileVault(rootDir, options = {}) {
   const startedAt = (/* @__PURE__ */ new Date()).toISOString();
   const { config, paths } = await initWorkspace(rootDir);
@@ -10169,7 +11119,7 @@ async function compileVault(rootDir, options = {}) {
   const currentInsightHashes = pageHashes(storedInsightPages);
   const previousState = await readJsonFile(paths.compileStatePath);
   const rootSchemaChanged = !previousState || previousState.rootSchemaHash !== schemas.root.hash;
-  const effectiveSchemaChanged = !previousState || previousGlobalSchemaHash(previousState) !== schemas.effective.global.hash || uniqueStrings2([...Object.keys(previousState?.effectiveSchemaHashes?.projects ?? {}), ...Object.keys(schemas.effective.projects)]).some(
+  const effectiveSchemaChanged = !previousState || previousGlobalSchemaHash(previousState) !== schemas.effective.global.hash || uniqueStrings3([...Object.keys(previousState?.effectiveSchemaHashes?.projects ?? {}), ...Object.keys(schemas.effective.projects)]).some(
     (projectId) => previousProjectSchemaHash(previousState, projectId) !== effectiveHashForProject(schemas, projectId)
   );
   const nextProjectConfigHash = projectConfigHash(config);
@@ -10202,6 +11152,10 @@ async function compileVault(rootDir, options = {}) {
   }
   if (dirty.length === 0 && !rootSchemaChanged && !effectiveSchemaChanged && !projectConfigChanged && !sourcesChanged && !outputsChanged && !insightsChanged && !pendingCandidatePromotion && artifactsExist && !options.approve) {
     const graph = await readJsonFile(paths.graphPath);
+    const benchmark2 = await runConfiguredBenchmark(rootDir, config);
+    if (graph && benchmark2.ok) {
+      await refreshIndexesAndSearch(rootDir, graph.pages);
+    }
     await recordSession(rootDir, {
       operation: "compile",
       title: `Compiled ${manifests.length} source(s)`,
@@ -10219,7 +11173,8 @@ async function compileVault(rootDir, options = {}) {
         `clean=${manifests.length}`,
         `outputs=${outputPages.length}`,
         `insights=${insightPages.length}`,
-        `schema=${schemas.effective.global.hash.slice(0, 12)}`
+        `schema=${schemas.effective.global.hash.slice(0, 12)}`,
+        `benchmark=${benchmark2.ok ? "ok" : `error:${benchmark2.error}`}`
       ]
     });
     return {
@@ -10337,6 +11292,10 @@ async function compileVault(rootDir, options = {}) {
       postPassApprovalDir = staged.approvalDir;
     }
   }
+  const benchmark = options.approve ? { ok: true } : await runConfiguredBenchmark(rootDir, config);
+  if (!options.approve && benchmark.ok) {
+    await refreshIndexesAndSearch(rootDir, sync.allPages);
+  }
   await recordSession(rootDir, {
     operation: "compile",
     title: `Compiled ${manifests.length} source(s)`,
@@ -10358,7 +11317,8 @@ async function compileVault(rootDir, options = {}) {
       `promoted=${sync.promotedPageIds.length}`,
       `staged=${sync.staged}`,
       `postPassApproval=${postPassApprovalId ?? "none"}`,
-      `schema=${schemas.effective.global.hash.slice(0, 12)}`
+      `schema=${schemas.effective.global.hash.slice(0, 12)}`,
+      `benchmark=${benchmark.ok ? "ok" : `error:${benchmark.error}`}`
     ]
   });
   return {
@@ -10628,7 +11588,7 @@ ${orchestrationNotes.join("\n")}
     citations: allCitations,
     format: outputFormat,
     relatedPageCount: stepPages.length,
-    relatedNodeCount: uniqueStrings2(stepPages.flatMap((page) => page.nodeIds)).length,
+    relatedNodeCount: uniqueStrings3(stepPages.flatMap((page) => page.nodeIds)).length,
     projectId: stepPages[0]?.projectIds[0] ?? null
   });
   const hubInput = {
@@ -10638,7 +11598,7 @@ ${orchestrationNotes.join("\n")}
     citations: allCitations,
     schemaHash: composeVaultSchema(
       schemas.root,
-      uniqueStrings2(stepPages.flatMap((page) => page.projectIds).sort((left, right) => left.localeCompare(right))).map((projectId) => schemas.projects[projectId]).filter((schema) => Boolean(schema?.hash))
+      uniqueStrings3(stepPages.flatMap((page) => page.projectIds).sort((left, right) => left.localeCompare(right))).map((projectId) => schemas.projects[projectId]).filter((schema) => Boolean(schema?.hash))
     ).hash,
     outputFormat,
     outputAssets: hubAssetBundle.outputAssets,
@@ -10698,7 +11658,7 @@ ${orchestrationNotes.join("\n")}
     providerId: provider.id,
     success: true,
     relatedSourceIds: [...relatedSourceIds],
-    relatedPageIds: uniqueStrings2([...relatedPageIds, ...stepPages.map((page) => page.id), hubPage.id]),
+    relatedPageIds: uniqueStrings3([...relatedPageIds, ...stepPages.map((page) => page.id), hubPage.id]),
     relatedNodeIds: [...relatedNodeIds],
     citations: allCitations,
     tokenUsage: tokenUsage.inputTokens > 0 || tokenUsage.outputTokens > 0 ? {
@@ -10753,7 +11713,7 @@ async function queryGraphVault(rootDir, question, options = {}) {
   return queryGraph(graph, question, searchResults, options);
 }
 async function benchmarkVault(rootDir, options = {}) {
-  const { paths } = await loadVaultConfig(rootDir);
+  const { config, paths } = await loadVaultConfig(rootDir);
   const graph = await ensureCompiledGraph(rootDir);
   const manifests = await listManifests(rootDir);
   const pageContentsById = /* @__PURE__ */ new Map();
@@ -10769,11 +11729,13 @@ async function benchmarkVault(rootDir, options = {}) {
     if (!await fileExists(absolutePath)) {
       continue;
     }
-    const parsed = matter8(await fs15.readFile(absolutePath, "utf8"));
+    const parsed = matter9(await fs15.readFile(absolutePath, "utf8"));
     pageContentsById.set(page.id, parsed.content);
   }
+  const configuredQuestions = (config.benchmark?.questions ?? []).map((question) => normalizeWhitespace(question)).filter(Boolean);
+  const maxQuestions = Math.max(1, options.maxQuestions ?? config.benchmark?.maxQuestions ?? 3);
   const questions = (options.questions ?? []).map((question) => normalizeWhitespace(question)).filter(Boolean);
-  const sampleQuestions = questions.length ? questions : [...DEFAULT_BENCHMARK_QUESTIONS];
+  const sampleQuestions = (questions.length ? questions : configuredQuestions.length ? configuredQuestions : defaultBenchmarkQuestionsForGraph(graph, maxQuestions)).slice(0, maxQuestions);
   const perQuestion = sampleQuestions.map((question) => {
     const searchResults = searchPages(paths.searchDbPath, question, { limit: 12 });
     const result = queryGraph(graph, question, searchResults, { budget: 12 });
@@ -10783,6 +11745,7 @@ async function benchmarkVault(rootDir, options = {}) {
       queryTokens: metrics.queryTokens,
       reduction: metrics.reduction,
       visitedNodeIds: result.visitedNodeIds,
+      visitedEdgeIds: result.visitedEdgeIds,
       pageIds: result.pageIds
     };
   });
@@ -10804,6 +11767,14 @@ async function explainGraphVault(rootDir, target) {
   const graph = await ensureCompiledGraph(rootDir);
   return explainGraphTarget(graph, target);
 }
+async function listGraphHyperedges(rootDir, target, limit = 25) {
+  const graph = await ensureCompiledGraph(rootDir);
+  return listHyperedges(graph, target, limit);
+}
+async function readGraphReport(rootDir) {
+  const { paths } = await loadVaultConfig(rootDir);
+  return readJsonFile(path18.join(paths.wikiDir, "graph", "report.json"));
+}
 async function listGodNodes(rootDir, limit = 10) {
   const graph = await ensureCompiledGraph(rootDir);
   return topGodNodes(graph, limit);
@@ -10820,7 +11791,7 @@ async function readPage(rootDir, relativePath) {
     return null;
   }
   const raw = await fs15.readFile(absolutePath, "utf8");
-  const parsed = matter8(raw);
+  const parsed = matter9(raw);
   return {
     path: relativePath,
     title: typeof parsed.data.title === "string" ? parsed.data.title : path18.basename(relativePath, path18.extname(relativePath)),
@@ -10947,7 +11918,7 @@ async function lintVault(rootDir, options = {}) {
     providerId: provider?.id,
     success: true,
     relatedPageIds: graph.pages.map((page) => page.id),
-    relatedSourceIds: uniqueStrings2(graph.pages.flatMap((page) => page.sourceIds)),
+    relatedSourceIds: uniqueStrings3(graph.pages.flatMap((page) => page.sourceIds)),
     lintFindingCount: findings.length,
     lines: [`findings=${findings.length}`, `deep=${Boolean(options.deep)}`, `web=${Boolean(options.web)}`]
   });
@@ -10967,7 +11938,7 @@ async function bootstrapDemo(rootDir, input) {
 }
 
 // src/mcp.ts
-var SERVER_VERSION = "0.1.22";
+var SERVER_VERSION = "0.1.24";
 async function createMcpServer(rootDir) {
   const server = new McpServer({
     name: "swarmvault",
@@ -11045,10 +12016,19 @@ async function createMcpServer(rootDir) {
       return asToolText(result);
     }
   );
+  server.registerTool(
+    "graph_report",
+    {
+      description: "Return the machine-readable graph report and trust artifact."
+    },
+    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, and neighbors.",
+      description: "Explain a graph node, its page, community, neighbors, and group patterns.",
       inputSchema: {
         target: z8.string().min(1).describe("Node or page label/id")
       }
@@ -11057,6 +12037,19 @@ async function createMcpServer(rootDir) {
       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")
+      }
+    },
+    async ({ target, limit }) => {
+      return asToolText(await listGraphHyperedges(rootDir, target, limit ?? 25));
+    }
+  );
   server.registerTool(
     "get_neighbors",
     {
@@ -11598,7 +12591,7 @@ import fs18 from "fs/promises";
 import http from "http";
 import path22 from "path";
 import { promisify } from "util";
-import matter9 from "gray-matter";
+import matter10 from "gray-matter";
 import mime2 from "mime-types";
 
 // src/watch.ts
@@ -11999,7 +12992,7 @@ async function readViewerPage(rootDir, relativePath) {
     return null;
   }
   const raw = await fs18.readFile(absolutePath, "utf8");
-  const parsed = matter9(raw);
+  const parsed = matter10(raw);
   return {
     path: relativePath,
     title: typeof parsed.data.title === "string" ? parsed.data.title : path22.basename(relativePath, path22.extname(relativePath)),
@@ -12102,16 +13095,29 @@ async function startGraphServer(rootDir, port) {
       const kind = url.searchParams.get("kind") ?? "all";
       const status = url.searchParams.get("status") ?? "all";
       const project = url.searchParams.get("project") ?? "all";
+      const sourceType = url.searchParams.get("sourceType") ?? "all";
       const results = searchPages(paths.searchDbPath, query, {
         limit: Number.isFinite(limit) ? limit : 10,
         kind,
         status,
-        project
+        project,
+        sourceType
       });
       response.writeHead(200, { "content-type": "application/json" });
       response.end(JSON.stringify(results));
       return;
     }
+    if (url.pathname === "/api/graph-report") {
+      const reportPath = path22.join(paths.wikiDir, "graph", "report.json");
+      if (!await fileExists(reportPath)) {
+        response.writeHead(404, { "content-type": "application/json" });
+        response.end(JSON.stringify({ error: "Graph report artifact not found. Run `swarmvault compile` first." }));
+        return;
+      }
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end(await fs18.readFile(reportPath, "utf8"));
+      return;
+    }
     if (url.pathname === "/api/watch-status") {
       response.writeHead(200, { "content-type": "application/json" });
       response.end(JSON.stringify(await getWatchStatus(rootDir)));
@@ -12241,6 +13247,7 @@ async function exportGraphHtml(rootDir, outputPath) {
         title: loaded.title,
         kind: page.kind,
         status: page.status,
+        sourceType: page.sourceType,
         projectIds: page.projectIds,
         content: loaded.content,
         assets: await Promise.all(
@@ -12262,7 +13269,8 @@ async function exportGraphHtml(rootDir, outputPath) {
   }
   const script = await fs18.readFile(scriptPath, "utf8");
   const style = stylePath && await fileExists(stylePath) ? await fs18.readFile(stylePath, "utf8") : "";
-  const embeddedData = JSON.stringify({ graph, pages: pages.filter(Boolean) }, null, 2).replace(/</g, "\\u003c");
+  const report = await readJsonFile(path22.join(paths.wikiDir, "graph", "report.json"));
+  const embeddedData = JSON.stringify({ graph, pages: pages.filter(Boolean), report }, null, 2).replace(/</g, "\\u003c");
   const html = [
     "<!doctype html>",
     '<html lang="en">',
@@ -12318,6 +13326,7 @@ export {
   listApprovals,
   listCandidates,
   listGodNodes,
+  listGraphHyperedges,
   listManifests,
   listPages,
   listSchedules,
@@ -12331,6 +13340,7 @@ export {
   queryVault,
   readApproval,
   readExtractedText,
+  readGraphReport,
   readPage,
   rejectApproval,
   resolvePaths,