@swarmvaultai/engine 0.2.0 → 0.2.2

package/dist/index.js

@@ -1764,6 +1764,8 @@ var grammarAssetByLanguage = {
   java: { packageName: TREE_SITTER_RUNTIME_PACKAGE, relativePath: "wasm/tree-sitter-java.wasm" },
   kotlin: { packageName: TREE_SITTER_EXTRA_GRAMMARS_PACKAGE, relativePath: "out/tree-sitter-kotlin.wasm" },
   scala: { packageName: TREE_SITTER_EXTRA_GRAMMARS_PACKAGE, relativePath: "out/tree-sitter-scala.wasm" },
+  lua: { packageName: TREE_SITTER_EXTRA_GRAMMARS_PACKAGE, relativePath: "out/tree-sitter-lua.wasm" },
+  zig: { packageName: TREE_SITTER_EXTRA_GRAMMARS_PACKAGE, relativePath: "out/tree-sitter-zig.wasm" },
   csharp: { packageName: TREE_SITTER_RUNTIME_PACKAGE, relativePath: "wasm/tree-sitter-c-sharp.wasm" },
   c: { packageName: TREE_SITTER_RUNTIME_PACKAGE, relativePath: "wasm/tree-sitter-cpp.wasm" },
   cpp: { packageName: TREE_SITTER_RUNTIME_PACKAGE, relativePath: "wasm/tree-sitter-cpp.wasm" },
@@ -1828,7 +1830,7 @@ function normalizeSymbolReference(value) {
   return lastSegment.replace(/[,:;]+$/g, "").trim();
 }
 function stripCodeExtension(filePath) {
-  return filePath.replace(/\.(?:[cm]?jsx?|tsx?|mts|cts|py|go|rs|java|kt|kts|scala|sc|cs|php|c|cc|cpp|cxx|h|hh|hpp|hxx)$/i, "");
+  return filePath.replace(/\.(?:[cm]?jsx?|tsx?|mts|cts|py|go|rs|java|kt|kts|scala|sc|lua|zig|cs|php|c|cc|cpp|cxx|h|hh|hpp|hxx)$/i, "");
 }
 function manifestModuleName(manifest, language) {
   const repoPath = manifest.repoRelativePath ?? path5.basename(manifest.originalPath ?? manifest.storedPath);
@@ -2112,7 +2114,7 @@ function descendantTypeNames(node) {
   );
 }
 function quotedPath(value) {
-  return value.replace(/^["'<]+|[">]+$/g, "").trim();
+  return value.replace(/^['"<]+|['">]+$/g, "").trim();
 }
 function diagnosticsFromTree(rootNode) {
   if (!rootNode.hasError) {
@@ -2262,6 +2264,43 @@ function parseScalaImport(text) {
     reExport: false
   }));
 }
+function parseLuaRequire(node) {
+  const stringNode = node.descendantsOfType("string").find((item) => item !== null);
+  const identifiers = node.descendantsOfType("identifier").filter((item) => item !== null).map((item) => item.text.trim());
+  if (!stringNode || !identifiers.includes("require")) {
+    return void 0;
+  }
+  const specifier = quotedPath(stringNode.text);
+  if (!specifier) {
+    return void 0;
+  }
+  return {
+    specifier,
+    importedSymbols: [],
+    isExternal: !/^[A-Za-z_][A-Za-z0-9_]*(?:[./][A-Za-z_][A-Za-z0-9_]*)*$/.test(specifier),
+    reExport: false
+  };
+}
+function parseZigImport(node) {
+  if (node.type !== "variable_declaration") {
+    return void 0;
+  }
+  const importCall = findNamedChild(node, "builtin_function");
+  if (!importCall || nodeText(findNamedChild(importCall, "builtin_identifier") ?? importCall.namedChildren.at(0) ?? null) !== "@import") {
+    return void 0;
+  }
+  const stringNode = importCall.descendantsOfType("string_content").find((item) => item !== null);
+  const specifier = stringNode?.text.trim();
+  if (!specifier) {
+    return void 0;
+  }
+  return {
+    specifier,
+    importedSymbols: [],
+    isExternal: !specifier.endsWith(".zig") && !specifier.includes("/") && !specifier.startsWith("."),
+    reExport: false
+  };
+}
 function parseCSharpUsing(text) {
   const aliasMatch = text.trim().match(/^using\s+([A-Za-z_]\w*)\s*=\s*([^;]+);$/);
   if (aliasMatch) {
@@ -2386,6 +2425,28 @@ function scalaDefinitionKind(node) {
   }
   return void 0;
 }
+function luaFunctionName(node) {
+  if (!node) {
+    return void 0;
+  }
+  if (node.type === "identifier") {
+    return node.text.trim();
+  }
+  if (node.type === "variable") {
+    const identifiers = node.descendantsOfType("identifier").filter((item) => item !== null).map((item) => item.text.trim()).filter(Boolean);
+    return identifiers.length > 0 ? identifiers.join(".") : void 0;
+  }
+  return extractIdentifier(node);
+}
+function zigDeclarationKind(node) {
+  if (findNamedChild(node, "struct_declaration")) {
+    return "struct";
+  }
+  if (findNamedChild(node, "enum_declaration")) {
+    return "enum";
+  }
+  return void 0;
+}
 function pythonCodeAnalysis(manifest, rootNode, diagnostics) {
   const imports = [];
   const draftSymbols = [];
@@ -2814,6 +2875,136 @@ function scalaCodeAnalysis(manifest, rootNode, diagnostics) {
     namespace: packageName
   });
 }
+function luaCodeAnalysis(manifest, rootNode, diagnostics) {
+  const imports = [];
+  const draftSymbols = [];
+  const exportLabels = [];
+  for (const child of rootNode.namedChildren) {
+    if (!child) {
+      continue;
+    }
+    if (child.type === "local_variable_declaration" || child.type === "assignment_statement") {
+      const parsed = parseLuaRequire(child);
+      if (parsed) {
+        imports.push(parsed);
+      }
+      continue;
+    }
+    if (!["function_definition_statement", "local_function_definition_statement"].includes(child.type)) {
+      continue;
+    }
+    const name = luaFunctionName(child.childForFieldName("name") ?? child.namedChildren.at(0) ?? null);
+    if (!name) {
+      continue;
+    }
+    draftSymbols.push({
+      name,
+      kind: "function",
+      signature: singleLineSignature(child.text),
+      exported: child.type !== "local_function_definition_statement",
+      callNames: [],
+      extendsNames: [],
+      implementsNames: [],
+      bodyText: nodeText(findNamedChild(child, "block") ?? child.childForFieldName("body")) || child.text
+    });
+    if (child.type !== "local_function_definition_statement") {
+      exportLabels.push(name);
+    }
+  }
+  return finalizeCodeAnalysis(manifest, "lua", imports, draftSymbols, exportLabels, diagnostics);
+}
+function zigCodeAnalysis(manifest, rootNode, diagnostics) {
+  const imports = [];
+  const draftSymbols = [];
+  const exportLabels = [];
+  const pushStructMembers = (structNode, scopeName) => {
+    if (!structNode) {
+      return;
+    }
+    for (const child of structNode.namedChildren) {
+      if (!child || child.type !== "function_declaration") {
+        continue;
+      }
+      const functionName = extractIdentifier(child.childForFieldName("name") ?? findNamedChild(child, "identifier"));
+      if (!functionName) {
+        continue;
+      }
+      const exported = /\bpub\b/.test(child.text);
+      const symbolName = `${scopeName}.${functionName}`;
+      draftSymbols.push({
+        name: symbolName,
+        kind: "function",
+        signature: singleLineSignature(child.text),
+        exported,
+        callNames: [],
+        extendsNames: [],
+        implementsNames: [],
+        bodyText: nodeText(findNamedChild(child, "block") ?? child.childForFieldName("body")) || child.text
+      });
+      if (exported) {
+        exportLabels.push(symbolName);
+      }
+    }
+  };
+  for (const child of rootNode.namedChildren) {
+    if (!child) {
+      continue;
+    }
+    if (child.type === "variable_declaration") {
+      const parsedImport = parseZigImport(child);
+      if (parsedImport) {
+        imports.push(parsedImport);
+        continue;
+      }
+      const name = extractIdentifier(child.childForFieldName("name") ?? findNamedChild(child, "identifier"));
+      const kind = zigDeclarationKind(child);
+      if (!name || !kind) {
+        continue;
+      }
+      const declarationNode = findNamedChild(child, "struct_declaration") ?? findNamedChild(child, "enum_declaration");
+      const exported2 = /\bpub\b/.test(child.text);
+      draftSymbols.push({
+        name,
+        kind,
+        signature: singleLineSignature(child.text),
+        exported: exported2,
+        callNames: [],
+        extendsNames: [],
+        implementsNames: [],
+        bodyText: nodeText(declarationNode) || child.text
+      });
+      if (exported2) {
+        exportLabels.push(name);
+      }
+      if (kind === "struct") {
+        pushStructMembers(declarationNode, name);
+      }
+      continue;
+    }
+    if (child.type !== "function_declaration") {
+      continue;
+    }
+    const functionName = extractIdentifier(child.childForFieldName("name") ?? findNamedChild(child, "identifier"));
+    if (!functionName) {
+      continue;
+    }
+    const exported = /\bpub\b/.test(child.text);
+    draftSymbols.push({
+      name: functionName,
+      kind: "function",
+      signature: singleLineSignature(child.text),
+      exported,
+      callNames: [],
+      extendsNames: [],
+      implementsNames: [],
+      bodyText: nodeText(findNamedChild(child, "block") ?? child.childForFieldName("body")) || child.text
+    });
+    if (exported) {
+      exportLabels.push(functionName);
+    }
+  }
+  return finalizeCodeAnalysis(manifest, "zig", imports, draftSymbols, exportLabels, diagnostics);
+}
 function csharpCodeAnalysis(manifest, rootNode, diagnostics) {
   const imports = [];
   const draftSymbols = [];
@@ -3246,6 +3437,10 @@ async function analyzeTreeSitterCode(manifest, content, language) {
         return { code: kotlinCodeAnalysis(manifest, tree.rootNode, diagnostics), rationales };
       case "scala":
         return { code: scalaCodeAnalysis(manifest, tree.rootNode, diagnostics), rationales };
+      case "lua":
+        return { code: luaCodeAnalysis(manifest, tree.rootNode, diagnostics), rationales };
+      case "zig":
+        return { code: zigCodeAnalysis(manifest, tree.rootNode, diagnostics), rationales };
       case "csharp":
         return { code: csharpCodeAnalysis(manifest, tree.rootNode, diagnostics), rationales };
       case "php":
@@ -3532,7 +3727,7 @@ function makeRationale2(manifest, index, text, kind, symbolName) {
   };
 }
 function stripCodeExtension2(filePath) {
-  return filePath.replace(/\.(?:[cm]?jsx?|tsx?|mts|cts|py|go|rs|java|kt|kts|scala|sc|cs|php|c|cc|cpp|cxx|h|hh|hpp|hxx)$/i, "");
+  return filePath.replace(/\.(?:[cm]?jsx?|tsx?|mts|cts|py|go|rs|java|kt|kts|scala|sc|lua|zig|cs|php|c|cc|cpp|cxx|h|hh|hpp|hxx)$/i, "");
 }
 function manifestModuleName2(manifest, language) {
   const repoPath = manifest.repoRelativePath ?? path6.basename(manifest.originalPath ?? manifest.storedPath);
@@ -3869,6 +4064,12 @@ function inferCodeLanguage(filePath, mimeType = "") {
   if (extension === ".scala" || extension === ".sc") {
     return "scala";
   }
+  if (extension === ".lua") {
+    return "lua";
+  }
+  if (extension === ".zig") {
+    return "zig";
+  }
   if (extension === ".cs") {
     return "csharp";
   }
@@ -3977,6 +4178,10 @@ function candidateExtensionsFor(language) {
       return [".kt", ".kts"];
     case "scala":
       return [".scala", ".sc"];
+    case "lua":
+      return [".lua"];
+    case "zig":
+      return [".zig"];
     case "csharp":
       return [".cs"];
     case "php":
@@ -4049,6 +4254,20 @@ async function buildCodeIndex(rootDir, manifests, analyses) {
           }
         }
         break;
+      case "lua":
+        recordAlias(aliases, basename);
+        if (repoRelativePath) {
+          const repoWithoutExt = stripCodeExtension2(repoRelativePath);
+          recordAlias(aliases, repoWithoutExt.replace(/\//g, "."));
+          if (repoWithoutExt.endsWith("/init")) {
+            recordAlias(aliases, repoWithoutExt.slice(0, -"/init".length));
+            recordAlias(aliases, repoWithoutExt.slice(0, -"/init".length).replace(/\//g, "."));
+          }
+        }
+        break;
+      case "zig":
+        recordAlias(aliases, basename);
+        break;
       case "php":
         if (normalizedNamespace) {
           recordAlias(aliases, `${normalizedNamespace}\\${basename}`);
@@ -4135,6 +4354,16 @@ function resolveRustAliases(manifest, specifier) {
     `crate${currentParts.length > 1 ? `::${currentParts.slice(0, -1).join("::")}` : ""}::${specifier.slice("super::".length)}`.replace(/::+/g, "::").replace(/::$/, "")
   ];
 }
+function luaSpecifierLooksLocal(specifier) {
+  return /^[A-Za-z_][A-Za-z0-9_]*(?:[./][A-Za-z_][A-Za-z0-9_]*)*$/.test(specifier);
+}
+function resolveLuaModuleCandidates(specifier) {
+  const normalized = normalizeAlias(specifier.replace(/\./g, "/"));
+  if (!normalized) {
+    return [];
+  }
+  return uniqueBy([`${normalized}.lua`, path6.posix.join(normalized, "init.lua")], (item) => item);
+}
 function findImportCandidates(manifest, codeImport, lookup) {
   const language = manifest.language ?? inferCodeLanguage(manifest.originalPath ?? manifest.storedPath, manifest.mimeType);
   const repoRelativePath = manifest.repoRelativePath ? normalizeAlias(manifest.repoRelativePath) : void 0;
@@ -4158,6 +4387,10 @@ function findImportCandidates(manifest, codeImport, lookup) {
     case "scala":
     case "csharp":
       return aliasMatches(lookup, codeImport.specifier);
+    case "lua":
+      return luaSpecifierLooksLocal(codeImport.specifier) ? repoPathMatches(lookup, ...resolveLuaModuleCandidates(codeImport.specifier)) : aliasMatches(lookup, codeImport.specifier, codeImport.specifier.replace(/\./g, "/"));
+    case "zig":
+      return repoRelativePath && (!codeImport.isExternal || codeImport.specifier.endsWith(".zig")) ? repoPathMatches(lookup, ...importResolutionCandidates(repoRelativePath, codeImport.specifier, candidateExtensionsFor(language))) : aliasMatches(lookup, codeImport.specifier);
     case "php":
     case "ruby":
     case "powershell":
@@ -4205,6 +4438,10 @@ function importLooksLocal(manifest, codeImport, candidates) {
     case "kotlin":
     case "scala":
       return !codeImport.isExternal;
+    case "lua":
+      return luaSpecifierLooksLocal(codeImport.specifier);
+    case "zig":
+      return !codeImport.isExternal || codeImport.specifier.endsWith(".zig");
     default:
       return false;
   }
@@ -4244,9 +4481,10 @@ async function analyzeCodeSource(manifest, extractedText, schemaHash) {
   const language = manifest.language ?? inferCodeLanguage(manifest.originalPath ?? manifest.storedPath, manifest.mimeType) ?? "typescript";
   const { code, rationales } = language === "javascript" || language === "jsx" || language === "typescript" || language === "tsx" ? analyzeTypeScriptLikeCode(manifest, extractedText) : await analyzeTreeSitterCode(manifest, extractedText, language);
   return {
-    analysisVersion: 6,
+    analysisVersion: 7,
     sourceId: manifest.sourceId,
     sourceHash: manifest.contentHash,
+    semanticHash: manifest.semanticHash,
     extractionHash: manifest.extractionHash,
     schemaHash,
     title: manifest.title,
@@ -4971,6 +5209,17 @@ var HARD_REPO_IGNORES = /* @__PURE__ */ new Set([".git", ".venv"]);
 var PROGRESS_FILE_THRESHOLD = 150;
 var PROGRESS_UPDATE_INTERVAL = 100;
 var RST_HEADING_MARKERS = /* @__PURE__ */ new Set(["=", "-", "~", "^", '"', "#", "*", "+"]);
+var MARKDOWN_SEMANTIC_FRONTMATTER_KEYS = [
+  "title",
+  "summary",
+  "description",
+  "aliases",
+  "tags",
+  "authors",
+  "published_at",
+  "canonical_url",
+  "source_type"
+];
 function uniqueStrings(values) {
   return [...new Set(values.filter(Boolean))];
 }
@@ -5108,6 +5357,65 @@ function extractedTextForPlainSource(filePath, sourceKind, content) {
   }
   return content;
 }
+function normalizeSemanticMarkdownScalar(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalized = normalizeWhitespace(value.trim());
+  return normalized || void 0;
+}
+function normalizeSemanticMarkdownList(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const items = uniqueStrings(
+    value.flatMap((item) => typeof item === "string" ? [normalizeWhitespace(item.trim())] : []).filter(Boolean)
+  );
+  return items.length ? items : void 0;
+}
+function semanticMarkdownTitle(fallback, content, filePath) {
+  const parsed = matter3(content);
+  const frontmatterTitle = normalizeSemanticMarkdownScalar(parsed.data.title);
+  if (frontmatterTitle) {
+    return frontmatterTitle;
+  }
+  return titleFromText(fallback, parsed.content, filePath);
+}
+function semanticMarkdownContent(content) {
+  const parsed = matter3(content);
+  const body = parsed.content.replace(/\r\n?/g, "\n").trim();
+  const semanticFrontmatter = Object.fromEntries(
+    MARKDOWN_SEMANTIC_FRONTMATTER_KEYS.flatMap((key) => {
+      const value = key === "aliases" || key === "tags" || key === "authors" ? normalizeSemanticMarkdownList(parsed.data[key]) : normalizeSemanticMarkdownScalar(parsed.data[key]);
+      return value === void 0 ? [] : [[key, value]];
+    })
+  );
+  const semanticLines = Object.entries(semanticFrontmatter).map(
+    ([key, value]) => `${key}: ${Array.isArray(value) ? value.join(", ") : value}`
+  );
+  const extractedText = [...semanticLines, ...semanticLines.length && body ? [""] : [], body].filter(Boolean).join("\n").trim();
+  return {
+    extractedText,
+    semanticHash: sha256(
+      JSON.stringify({
+        body,
+        frontmatter: semanticFrontmatter
+      })
+    )
+  };
+}
+function finalizePreparedInput(prepared) {
+  if (prepared.sourceKind !== "markdown") {
+    return prepared;
+  }
+  const semantic = semanticMarkdownContent(prepared.payloadBytes.toString("utf8"));
+  return {
+    ...prepared,
+    extractedText: semantic.extractedText,
+    extractionHash: buildExtractionHash(semantic.extractedText, prepared.extractionArtifact),
+    semanticHash: semantic.semanticHash
+  };
+}
 function shouldEmitProgress(totalItems) {
   return totalItems >= PROGRESS_FILE_THRESHOLD && Boolean(process.stderr?.isTTY);
 }
@@ -5274,7 +5582,7 @@ function markdownFrontmatter(value) {
   return matter3.stringify("", normalized).trimEnd().split("\n").concat([""]);
 }
 function prepareCapturedMarkdownInput(input) {
-  return {
+  return finalizePreparedInput({
     title: input.title,
     originType: "url",
     sourceKind: "markdown",
@@ -5286,7 +5594,7 @@ function prepareCapturedMarkdownInput(input) {
     extractedText: input.markdown,
     attachments: input.attachments,
     logDetails: input.logDetails
-  };
+  });
 }
 function isPrivateIp(ip) {
   if (ip === "::1" || ip.startsWith("fc") || ip.startsWith("fd")) return true;
@@ -5649,7 +5957,10 @@ async function readManifestByHash(manifestsDir, contentHash) {
     }
     const manifest = await readJsonFile(path12.join(manifestsDir, entry.name));
     if (manifest?.contentHash === contentHash) {
-      return manifest;
+      return {
+        ...manifest,
+        semanticHash: manifest.semanticHash ?? manifest.contentHash
+      };
     }
   }
   return null;
@@ -5662,7 +5973,10 @@ async function readManifestByOrigin(manifestsDir, prepared) {
     }
     const manifest = await readJsonFile(path12.join(manifestsDir, entry.name));
     if (manifest && manifestMatchesOrigin(manifest, prepared)) {
-      return manifest;
+      return {
+        ...manifest,
+        semanticHash: manifest.semanticHash ?? manifest.contentHash
+      };
     }
   }
   return null;
@@ -5911,10 +6225,11 @@ async function persistPreparedInput(rootDir, prepared, paths) {
   await ensureDir(paths.extractsDir);
   const attachments = prepared.attachments ?? [];
   const contentHash = prepared.contentHash ?? buildCompositeHash(prepared.payloadBytes, attachments);
+  const semanticHash = prepared.semanticHash ?? contentHash;
   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.sourceType === prepared.sourceType && existingByOrigin.sourceClass === prepared.sourceClass && existingByOrigin.language === prepared.language && existingByOrigin.mimeType === prepared.mimeType && existingByOrigin.repoRelativePath === prepared.repoRelativePath) {
+  if (existingByOrigin && existingByOrigin.contentHash === contentHash && existingByOrigin.semanticHash === semanticHash && existingByOrigin.extractionHash === extractionHash && existingByOrigin.title === prepared.title && existingByOrigin.sourceKind === prepared.sourceKind && existingByOrigin.sourceType === prepared.sourceType && existingByOrigin.sourceClass === prepared.sourceClass && existingByOrigin.language === prepared.language && existingByOrigin.mimeType === prepared.mimeType && existingByOrigin.repoRelativePath === prepared.repoRelativePath) {
     return { manifest: existingByOrigin, isNew: false, wasUpdated: false };
   }
   if (existingByHash) {
@@ -5972,6 +6287,7 @@ async function persistPreparedInput(rootDir, prepared, paths) {
     extractionHash,
     mimeType: prepared.mimeType,
     contentHash,
+    semanticHash,
     createdAt: previous?.createdAt ?? now,
     updatedAt: now,
     attachments: manifestAttachments.length ? manifestAttachments : void 0
@@ -6286,14 +6602,15 @@ async function prepareFileInput(rootDir, absoluteInput, repoRoot, sourceClass) {
   let extractedText;
   let extractionArtifact;
   if (sourceKind === "markdown" || sourceKind === "text" || sourceKind === "code") {
-    extractedText = extractedTextForPlainSource(absoluteInput, sourceKind, payloadBytes.toString("utf8"));
-    title = titleFromText(path12.basename(absoluteInput, path12.extname(absoluteInput)), extractedText, absoluteInput);
+    const rawText = payloadBytes.toString("utf8");
+    extractedText = sourceKind === "markdown" ? semanticMarkdownContent(rawText).extractedText : extractedTextForPlainSource(absoluteInput, sourceKind, rawText);
+    title = sourceKind === "markdown" ? semanticMarkdownTitle(path12.basename(absoluteInput, path12.extname(absoluteInput)), rawText, absoluteInput) : titleFromText(path12.basename(absoluteInput, path12.extname(absoluteInput)), extractedText, absoluteInput);
     extractionArtifact = createPlainTextExtractionArtifact(sourceKind, mimeType);
   } else if (sourceKind === "html") {
     const html = payloadBytes.toString("utf8");
     const converted = await convertHtmlToMarkdown(html, pathToFileURL(absoluteInput).toString());
     title = converted.title;
-    extractedText = converted.markdown;
+    extractedText = semanticMarkdownContent(converted.markdown).extractedText;
     extractionArtifact = createHtmlReadabilityExtractionArtifact(sourceKind, mimeType);
   } else if (sourceKind === "pdf") {
     title = path12.basename(absoluteInput, path12.extname(absoluteInput));
@@ -6319,7 +6636,7 @@ async function prepareFileInput(rootDir, absoluteInput, repoRoot, sourceClass) {
   } else {
     title = path12.basename(absoluteInput, path12.extname(absoluteInput));
   }
-  return {
+  return finalizePreparedInput({
     title,
     originType: "file",
     sourceKind,
@@ -6333,7 +6650,7 @@ async function prepareFileInput(rootDir, absoluteInput, repoRoot, sourceClass) {
     extractedText,
     extractionArtifact,
     extractionHash: buildExtractionHash(extractedText, extractionArtifact)
-  };
+  });
 }
 async function prepareUrlInput(rootDir, input, options) {
   await validateUrlSafety(input);
@@ -6397,8 +6714,9 @@ async function prepareUrlInput(rootDir, input, options) {
     const extension = path12.extname(inputUrl.pathname);
     storedExtension = extension || `.${mime.extension(mimeType) || "bin"}`;
     if (sourceKind === "markdown" || sourceKind === "text" || sourceKind === "code") {
-      extractedText = extractedTextForPlainSource(inputUrl.pathname, sourceKind, payloadBytes.toString("utf8"));
-      title = titleFromText(title || inputUrl.hostname, extractedText, inputUrl.pathname);
+      const rawText = payloadBytes.toString("utf8");
+      extractedText = sourceKind === "markdown" ? semanticMarkdownContent(rawText).extractedText : extractedTextForPlainSource(inputUrl.pathname, sourceKind, rawText);
+      title = sourceKind === "markdown" ? semanticMarkdownTitle(title || inputUrl.hostname, rawText, inputUrl.pathname) : titleFromText(title || inputUrl.hostname, extractedText, inputUrl.pathname);
       extractionArtifact = createPlainTextExtractionArtifact(sourceKind, mimeType);
       if (sourceKind === "markdown" && options.includeAssets) {
         const { attachments: remoteAttachments, skippedCount } = await collectRemoteImageAttachments(
@@ -6440,7 +6758,7 @@ async function prepareUrlInput(rootDir, input, options) {
       extractionArtifact = extracted.artifact;
     }
   }
-  return {
+  return finalizePreparedInput({
     title,
     originType: "url",
     sourceKind,
@@ -6455,7 +6773,7 @@ async function prepareUrlInput(rootDir, input, options) {
     attachments,
     contentHash,
     logDetails
-  };
+  });
 }
 async function collectInboxAttachmentRefs(inputDir, files) {
   const refsBySource = /* @__PURE__ */ new Map();
@@ -6529,7 +6847,7 @@ async function prepareInboxMarkdownInput(absolutePath, attachmentRefs) {
   );
   const rewrittenText = rewriteMarkdownReferences(originalText, replacements);
   const extractionArtifact = createPlainTextExtractionArtifact("markdown", "text/markdown");
-  return {
+  return finalizePreparedInput({
     title,
     originType: "file",
     sourceKind: "markdown",
@@ -6542,7 +6860,7 @@ async function prepareInboxMarkdownInput(absolutePath, attachmentRefs) {
     extractionHash: buildExtractionHash(rewrittenText, extractionArtifact),
     attachments,
     contentHash
-  };
+  });
 }
 async function prepareInboxHtmlInput(absolutePath, attachmentRefs) {
   const originalBytes = await fs11.readFile(absolutePath);
@@ -6784,7 +7102,10 @@ async function listManifests(rootDir) {
   const manifests = await Promise.all(
     entries.filter((entry) => entry.endsWith(".json")).map((entry) => readJsonFile(path12.join(paths.manifestsDir, entry)))
   );
-  return manifests.filter((manifest) => Boolean(manifest));
+  return manifests.filter((manifest) => Boolean(manifest)).map((manifest) => ({
+    ...manifest,
+    semanticHash: manifest.semanticHash ?? manifest.contentHash
+  }));
 }
 async function removeManifestBySourceId(rootDir, sourceId) {
   const { paths } = await initWorkspace(rootDir);
@@ -6792,8 +7113,12 @@ async function removeManifestBySourceId(rootDir, sourceId) {
   if (!manifest) {
     return null;
   }
-  await removeManifestArtifacts(rootDir, manifest, paths);
-  return manifest;
+  const normalizedManifest = {
+    ...manifest,
+    semanticHash: manifest.semanticHash ?? manifest.contentHash
+  };
+  await removeManifestArtifacts(rootDir, normalizedManifest, paths);
+  return normalizedManifest;
 }
 async function readExtractedText(rootDir, manifest) {
   if (!manifest.extractedTextPath) {
@@ -6939,7 +7264,7 @@ import { z as z7 } from "zod";
 // src/analysis.ts
 import path14 from "path";
 import { z as z2 } from "zod";
-var ANALYSIS_FORMAT_VERSION = 6;
+var ANALYSIS_FORMAT_VERSION = 7;
 var sourceAnalysisSchema = z2.object({
   title: z2.string().min(1),
   summary: z2.string().min(1),
@@ -7044,6 +7369,7 @@ function heuristicAnalysis(manifest, text, schemaHash) {
     analysisVersion: ANALYSIS_FORMAT_VERSION,
     sourceId: manifest.sourceId,
     sourceHash: manifest.contentHash,
+    semanticHash: manifest.semanticHash,
     extractionHash: manifest.extractionHash,
     schemaHash,
     title: deriveTitle(manifest, text),
@@ -7094,6 +7420,7 @@ ${truncate(text, 18e3)}`
     analysisVersion: ANALYSIS_FORMAT_VERSION,
     sourceId: manifest.sourceId,
     sourceHash: manifest.contentHash,
+    semanticHash: manifest.semanticHash,
     extractionHash: manifest.extractionHash,
     schemaHash: schema.hash,
     title: parsed.title,
@@ -7130,6 +7457,7 @@ function analysisFromVisionExtraction(manifest, extraction, schemaHash) {
     analysisVersion: ANALYSIS_FORMAT_VERSION,
     sourceId: manifest.sourceId,
     sourceHash: manifest.contentHash,
+    semanticHash: manifest.semanticHash,
     extractionHash: manifest.extractionHash,
     schemaHash,
     title: extraction.vision.title?.trim() || manifest.title,
@@ -7168,7 +7496,7 @@ function extractionWarningSummary(manifest, extraction) {
 async function analyzeSource(manifest, extractedText, provider, paths, schema) {
   const cachePath = path14.join(paths.analysesDir, `${manifest.sourceId}.json`);
   const cached = await readJsonFile(cachePath);
-  if (cached && cached.analysisVersion === ANALYSIS_FORMAT_VERSION && cached.sourceHash === manifest.contentHash && cached.extractionHash === manifest.extractionHash && cached.schemaHash === schema.hash) {
+  if (cached && cached.analysisVersion === ANALYSIS_FORMAT_VERSION && (cached.semanticHash ?? cached.sourceHash) === manifest.semanticHash && cached.extractionHash === manifest.extractionHash && cached.schemaHash === schema.hash) {
     return cached;
   }
   const extraction = await readExtractionArtifact(paths.rootDir, manifest);
@@ -7185,6 +7513,7 @@ async function analyzeSource(manifest, extractedText, provider, paths, schema) {
         analysisVersion: ANALYSIS_FORMAT_VERSION,
         sourceId: manifest.sourceId,
         sourceHash: manifest.contentHash,
+        semanticHash: manifest.semanticHash,
         extractionHash: manifest.extractionHash,
         schemaHash: schema.hash,
         title: manifest.title,
@@ -7211,6 +7540,7 @@ async function analyzeSource(manifest, extractedText, provider, paths, schema) {
       analysisVersion: ANALYSIS_FORMAT_VERSION,
       sourceId: manifest.sourceId,
       sourceHash: manifest.contentHash,
+      semanticHash: manifest.semanticHash,
       extractionHash: manifest.extractionHash,
       schemaHash: schema.hash,
       title: manifest.title,
@@ -7994,7 +8324,9 @@ async function resolveEmbeddingProvider(rootDir) {
     }
     const provider2 = await createProvider(explicitProviderId, providerConfig, rootDir);
     if (!provider2.capabilities.has("embeddings") || typeof provider2.embedTexts !== "function") {
-      throw new Error(`Provider ${provider2.id} does not support required capability "embeddings".`);
+      throw new Error(
+        `Provider ${provider2.id} does not support required capability "embeddings". Configure tasks.embeddingProvider to use an embedding-capable backend such as ollama or another openai-compatible embedding service.`
+      );
     }
     return provider2;
   }
@@ -8890,6 +9222,18 @@ function uniqueStrings2(values) {
 function safeFrontmatter(value) {
   return JSON.parse(JSON.stringify(value));
 }
+function sourceHashesForManifest(manifest) {
+  return {
+    sourceHashes: { [manifest.sourceId]: manifest.contentHash },
+    sourceSemanticHashes: { [manifest.sourceId]: manifest.semanticHash }
+  };
+}
+function sourceHashFrontmatter(sourceHashes, sourceSemanticHashes) {
+  return {
+    source_hashes: sourceHashes,
+    source_semantic_hashes: sourceSemanticHashes
+  };
+}
 function decoratedTags(baseTags, decorations) {
   return uniqueStrings2([
     ...baseTags,
@@ -8953,6 +9297,7 @@ function relatedOutputsSection(relatedOutputs) {
 function buildSourcePage(manifest, analysis, schemaHash, metadata, relatedOutputs = [], modulePage, decorations) {
   const relativePath = pagePathFor("source", manifest.sourceId);
   const pageId = `source:${manifest.sourceId}`;
+  const { sourceHashes, sourceSemanticHashes } = sourceHashesForManifest(manifest);
   const moduleNodeIds = analysis.code ? [analysis.code.moduleId, ...analysis.code.symbols.map((symbol) => symbol.id)] : [];
   const nodeIds = [
     `source:${manifest.sourceId}`,
@@ -8985,9 +9330,7 @@ function buildSourcePage(manifest, analysis, schemaHash, metadata, relatedOutput
     managed_by: metadata.managedBy,
     backlinks,
     schema_hash: schemaHash,
-    source_hashes: {
-      [manifest.sourceId]: manifest.contentHash
-    }
+    ...sourceHashFrontmatter(sourceHashes, sourceSemanticHashes)
   };
   const body = [
     `# ${analysis.title}`,
@@ -9050,7 +9393,8 @@ function buildSourcePage(manifest, analysis, schemaHash, metadata, relatedOutput
       confidence: metadata.confidence,
       backlinks,
       schemaHash,
-      sourceHashes: { [manifest.sourceId]: manifest.contentHash },
+      sourceHashes,
+      sourceSemanticHashes,
       relatedPageIds: [...modulePage ? [modulePage.id] : [], ...relatedOutputs.map((page) => page.id)],
       relatedNodeIds: moduleNodeIds,
       relatedSourceIds: [],
@@ -9075,6 +9419,7 @@ function buildModulePage(input) {
   const localModuleBacklinks = input.localModules.map((moduleRef) => moduleRef.page.id);
   const relatedOutputs = input.relatedOutputs ?? [];
   const backlinks = uniqueStrings2([sourcePage.id, ...localModuleBacklinks, ...relatedOutputs.map((page) => page.id)]);
+  const { sourceHashes, sourceSemanticHashes } = sourceHashesForManifest(manifest);
   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 = [
@@ -9118,9 +9463,7 @@ function buildModulePage(input) {
     managed_by: metadata.managedBy,
     backlinks,
     schema_hash: schemaHash,
-    source_hashes: {
-      [manifest.sourceId]: manifest.contentHash
-    },
+    ...sourceHashFrontmatter(sourceHashes, sourceSemanticHashes),
     related_page_ids: uniqueStrings2([sourcePage.id, ...localModuleBacklinks, ...relatedOutputs.map((page) => page.id)]),
     related_node_ids: [],
     related_source_ids: uniqueStrings2([
@@ -9196,7 +9539,8 @@ function buildModulePage(input) {
       confidence: metadata.confidence,
       backlinks,
       schemaHash,
-      sourceHashes: { [manifest.sourceId]: manifest.contentHash },
+      sourceHashes,
+      sourceSemanticHashes,
       relatedPageIds: uniqueStrings2([sourcePage.id, ...localModuleBacklinks, ...relatedOutputs.map((page) => page.id)]),
       relatedNodeIds: [],
       relatedSourceIds: uniqueStrings2([
@@ -9212,7 +9556,7 @@ function buildModulePage(input) {
     content: matter5.stringify(body, frontmatter)
   };
 }
-function buildAggregatePage(kind, name, descriptions, sourceAnalyses, sourceHashes, schemaHash, metadata, relativePath, relatedOutputs = [], decorations) {
+function buildAggregatePage(kind, name, descriptions, sourceAnalyses, sourceHashes, sourceSemanticHashes, schemaHash, metadata, relativePath, relatedOutputs = [], decorations) {
   const slug = slugify(name);
   const pageId = `${kind}:${slug}`;
   const sourceIds = sourceAnalyses.map((item) => item.sourceId);
@@ -9236,7 +9580,7 @@ function buildAggregatePage(kind, name, descriptions, sourceAnalyses, sourceHash
     managed_by: metadata.managedBy,
     backlinks: otherPages,
     schema_hash: schemaHash,
-    source_hashes: sourceHashes
+    ...sourceHashFrontmatter(sourceHashes, sourceSemanticHashes)
   };
   const body = [
     `# ${name}`,
@@ -9274,6 +9618,7 @@ function buildAggregatePage(kind, name, descriptions, sourceAnalyses, sourceHash
       backlinks: otherPages,
       schemaHash,
       sourceHashes,
+      sourceSemanticHashes,
       relatedPageIds: relatedOutputs.map((page) => page.id),
       relatedNodeIds: [],
       relatedSourceIds: [],
@@ -9314,6 +9659,7 @@ function buildIndexPage(pages, schemaHash, metadata, projectPages = []) {
     "backlinks: []",
     `schema_hash: ${schemaHash}`,
     "source_hashes: {}",
+    "source_semantic_hashes: {}",
     "---",
     "",
     "# SwarmVault Index",
@@ -9377,7 +9723,8 @@ function buildSectionIndex(kind, pages, schemaHash, metadata, projectIds = []) {
       managed_by: metadata.managedBy,
       backlinks: [],
       schema_hash: schemaHash,
-      source_hashes: {}
+      source_hashes: {},
+      source_semantic_hashes: {}
     }
   );
 }
@@ -9673,6 +10020,7 @@ function buildGraphReportPage(input) {
     backlinks: [],
     schema_hash: input.schemaHash,
     source_hashes: {},
+    source_semantic_hashes: {},
     related_page_ids: relatedPageIds,
     related_node_ids: relatedNodeIds,
     related_source_ids: relatedSourceIds
@@ -9788,6 +10136,7 @@ function buildGraphReportPage(input) {
       backlinks: [],
       schemaHash: input.schemaHash,
       sourceHashes: {},
+      sourceSemanticHashes: {},
       relatedPageIds,
       relatedNodeIds,
       relatedSourceIds,
@@ -9831,6 +10180,7 @@ function buildCommunitySummaryPage(input) {
     backlinks: ["graph:report"],
     schema_hash: input.schemaHash,
     source_hashes: {},
+    source_semantic_hashes: {},
     related_page_ids: uniqueStrings2(["graph:report", ...communityPageIds]),
     related_node_ids: input.community.nodeIds,
     related_source_ids: relatedSourceIds
@@ -9870,6 +10220,7 @@ function buildCommunitySummaryPage(input) {
       backlinks: ["graph:report"],
       schemaHash: input.schemaHash,
       sourceHashes: {},
+      sourceSemanticHashes: {},
       relatedPageIds: uniqueStrings2(["graph:report", ...communityPageIds]),
       relatedNodeIds: input.community.nodeIds,
       relatedSourceIds,
@@ -9906,7 +10257,8 @@ function buildProjectsIndex(projectPages, schemaHash, metadata) {
       managed_by: metadata.managedBy,
       backlinks: [],
       schema_hash: schemaHash,
-      source_hashes: {}
+      source_hashes: {},
+      source_semantic_hashes: {}
     }
   );
 }
@@ -9958,7 +10310,8 @@ function buildProjectIndex(input) {
       managed_by: input.metadata.managedBy,
       backlinks: [],
       schema_hash: input.schemaHash,
-      source_hashes: {}
+      source_hashes: {},
+      source_semantic_hashes: {}
     }
   );
 }
@@ -9989,6 +10342,7 @@ function buildOutputPage(input) {
     backlinks,
     schema_hash: input.schemaHash,
     source_hashes: {},
+    source_semantic_hashes: {},
     related_page_ids: relatedPageIds,
     related_node_ids: relatedNodeIds,
     related_source_ids: relatedSourceIds,
@@ -10013,6 +10367,7 @@ function buildOutputPage(input) {
       backlinks,
       schemaHash: input.schemaHash,
       sourceHashes: {},
+      sourceSemanticHashes: {},
       relatedPageIds,
       relatedNodeIds,
       relatedSourceIds,
@@ -10115,6 +10470,7 @@ function buildExploreHubPage(input) {
     backlinks,
     schema_hash: input.schemaHash,
     source_hashes: {},
+    source_semantic_hashes: {},
     related_page_ids: relatedPageIds,
     related_node_ids: relatedNodeIds,
     related_source_ids: relatedSourceIds,
@@ -10139,6 +10495,7 @@ function buildExploreHubPage(input) {
       backlinks,
       schemaHash: input.schemaHash,
       sourceHashes: {},
+      sourceSemanticHashes: {},
       relatedPageIds,
       relatedNodeIds,
       relatedSourceIds,
@@ -10437,6 +10794,9 @@ function normalizeSourceHashes(value) {
     Object.entries(value).filter((entry) => typeof entry[0] === "string" && typeof entry[1] === "string")
   );
 }
+function normalizeSourceSemanticHashes(value) {
+  return normalizeSourceHashes(value);
+}
 function normalizePageStatus(value, fallback = "active") {
   return value === "draft" || value === "candidate" || value === "active" || value === "archived" ? value : fallback;
 }
@@ -10565,6 +10925,7 @@ function parseStoredPage(relativePath, content, defaults = {}) {
     backlinks,
     schemaHash: typeof parsed.data.schema_hash === "string" ? parsed.data.schema_hash : "",
     sourceHashes: normalizeSourceHashes(parsed.data.source_hashes),
+    sourceSemanticHashes: normalizeSourceSemanticHashes(parsed.data.source_semantic_hashes),
     relatedPageIds,
     relatedNodeIds,
     relatedSourceIds,
@@ -10618,6 +10979,7 @@ async function loadInsightPages(wikiDir) {
         backlinks,
         schemaHash: typeof parsed.data.schema_hash === "string" ? parsed.data.schema_hash : "",
         sourceHashes: normalizeSourceHashes(parsed.data.source_hashes),
+        sourceSemanticHashes: normalizeSourceSemanticHashes(parsed.data.source_semantic_hashes),
         relatedPageIds,
         relatedNodeIds,
         relatedSourceIds,
@@ -10718,6 +11080,7 @@ async function loadSavedOutputPages(wikiDir) {
           backlinks,
           schemaHash: typeof parsed.data.schema_hash === "string" ? parsed.data.schema_hash : "",
           sourceHashes: normalizeSourceHashes(parsed.data.source_hashes),
+          sourceSemanticHashes: normalizeSourceSemanticHashes(parsed.data.source_semantic_hashes),
           relatedPageIds,
           relatedNodeIds,
           relatedSourceIds,
@@ -12194,11 +12557,13 @@ function aggregateItems(analyses, kind) {
         name: item.name,
         descriptions: [],
         sourceAnalyses: [],
-        sourceHashes: {}
+        sourceHashes: {},
+        sourceSemanticHashes: {}
       };
       existing.descriptions.push(item.description);
       existing.sourceAnalyses.push(analysis);
       existing.sourceHashes[analysis.sourceId] = analysis.sourceHash;
+      existing.sourceSemanticHashes[analysis.sourceId] = analysis.semanticHash;
       grouped.set(key, existing);
     }
   }
@@ -12220,6 +12585,7 @@ function emptyGraphPage(input) {
     backlinks: [],
     schemaHash: input.schemaHash,
     sourceHashes: input.sourceHashes,
+    sourceSemanticHashes: input.sourceSemanticHashes ?? {},
     relatedPageIds: [],
     relatedNodeIds: [],
     relatedSourceIds: [],
@@ -12384,6 +12750,7 @@ async function syncVaultArtifacts(rootDir, input) {
       nodeIds: [analysis.code.moduleId, ...analysis.code.symbols.map((symbol) => symbol.id)],
       schemaHash: sourceSchemaHash,
       sourceHashes: { [manifest.sourceId]: manifest.contentHash },
+      sourceSemanticHashes: { [manifest.sourceId]: manifest.semanticHash },
       confidence: 1
     }) : null;
     const preview = emptyGraphPage({
@@ -12402,6 +12769,7 @@ async function syncVaultArtifacts(rootDir, input) {
       ],
       schemaHash: sourceSchemaHash,
       sourceHashes: { [manifest.sourceId]: manifest.contentHash },
+      sourceSemanticHashes: { [manifest.sourceId]: manifest.semanticHash },
       confidence: 1
     });
     const sourceRecord = await buildManagedGraphPage(
@@ -12518,6 +12886,7 @@ async function syncVaultArtifacts(rootDir, input) {
           aggregate.descriptions,
           aggregate.sourceAnalyses,
           aggregate.sourceHashes,
+          aggregate.sourceSemanticHashes,
           schemaHash,
           metadata,
           relativePath,
@@ -12765,6 +13134,7 @@ async function syncVaultArtifacts(rootDir, input) {
     projectConfigHash: projectConfigHash(config),
     analyses: Object.fromEntries(input.analyses.map((analysis) => [analysis.sourceId, analysisSignature(analysis)])),
     sourceHashes: Object.fromEntries(input.manifests.map((manifest) => [manifest.sourceId, manifest.contentHash])),
+    sourceSemanticHashes: Object.fromEntries(input.manifests.map((manifest) => [manifest.sourceId, manifest.semanticHash])),
     sourceProjects: input.sourceProjects,
     outputHashes: input.outputHashes,
     insightHashes: input.insightHashes,
@@ -13230,6 +13600,7 @@ function emptyCompileState() {
     projectConfigHash: "",
     analyses: {},
     sourceHashes: {},
+    sourceSemanticHashes: {},
     sourceProjects: {},
     outputHashes: {},
     insightHashes: {},
@@ -13659,7 +14030,8 @@ async function initVault(rootDir, options = {}) {
         managed_by: "human",
         backlinks: [],
         schema_hash: "",
-        source_hashes: {}
+        source_hashes: {},
+        source_semantic_hashes: {}
       }
     )
   );
@@ -13682,7 +14054,8 @@ async function initVault(rootDir, options = {}) {
       managed_by: "system",
       backlinks: [],
       schema_hash: "",
-      source_hashes: {}
+      source_hashes: {},
+      source_semantic_hashes: {}
     })
   );
   await writeFileIfChanged(
@@ -13704,7 +14077,8 @@ async function initVault(rootDir, options = {}) {
       managed_by: "system",
       backlinks: [],
       schema_hash: "",
-      source_hashes: {}
+      source_hashes: {},
+      source_semantic_hashes: {}
     })
   );
   if (options.obsidian) {
@@ -13745,7 +14119,7 @@ async function compileVault(rootDir, options = {}) {
   );
   const nextProjectConfigHash = projectConfigHash(config);
   const projectConfigChanged = !previousState || previousState.projectConfigHash !== nextProjectConfigHash;
-  const previousSourceHashes = previousState?.sourceHashes ?? {};
+  const previousSourceHashes = previousState?.sourceSemanticHashes ?? previousState?.sourceHashes ?? {};
   const previousAnalyses = previousState?.analyses ?? {};
   const previousSourceProjects = previousState?.sourceProjects ?? {};
   const previousOutputHashes = previousState?.outputHashes ?? {};
@@ -13760,7 +14134,7 @@ async function compileVault(rootDir, options = {}) {
   const dirty = [];
   const clean = [];
   for (const manifest of manifests) {
-    const hashChanged = previousSourceHashes[manifest.sourceId] !== manifest.contentHash;
+    const hashChanged = previousSourceHashes[manifest.sourceId] !== manifest.semanticHash;
     const noAnalysis = !previousAnalyses[manifest.sourceId];
     const projectId = sourceProjects[manifest.sourceId] ?? null;
     const projectChanged = (previousSourceProjects[manifest.sourceId] ?? null) !== projectId;
@@ -14470,9 +14844,11 @@ function structuralLintFindings(_rootDir, paths, graph, schemas, manifests, sour
           relatedPageIds: [page.id]
         });
       }
-      for (const [sourceId, knownHash] of Object.entries(page.sourceHashes)) {
+      const freshnessHashes = Object.keys(page.sourceSemanticHashes).length ? page.sourceSemanticHashes : page.sourceHashes;
+      for (const [sourceId, knownHash] of Object.entries(freshnessHashes)) {
         const manifest = manifestMap.get(sourceId);
-        if (manifest && manifest.contentHash !== knownHash) {
+        const manifestHash = manifest?.semanticHash ?? manifest?.contentHash;
+        if (manifestHash && manifestHash !== knownHash) {
           findings.push({
             severity: "warning",
             code: "stale_page",
@@ -14611,7 +14987,7 @@ async function bootstrapDemo(rootDir, input) {
 }
 
 // src/mcp.ts
-var SERVER_VERSION = "0.2.0";
+var SERVER_VERSION = "0.2.2";
 async function createMcpServer(rootDir) {
   const server = new McpServer({
     name: "swarmvault",
@@ -15984,6 +16360,124 @@ import { promisify } from "util";
 import matter10 from "gray-matter";
 import mime2 from "mime-types";
 
+// src/graph-presentation.ts
+var OVERVIEW_THRESHOLD = 5e3;
+var OVERVIEW_NODE_BUDGET = 1500;
+function nodePriority(node, pinnedNodeIds) {
+  return [pinnedNodeIds.has(node.id) ? 0 : 1, -(node.degree ?? 0), -(node.bridgeScore ?? 0), node.label, node.id];
+}
+function compareTuples(left, right) {
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftValue = left[index];
+    const rightValue = right[index];
+    if (leftValue === rightValue) {
+      continue;
+    }
+    if (typeof leftValue === "number" && typeof rightValue === "number") {
+      return leftValue - rightValue;
+    }
+    return String(leftValue ?? "").localeCompare(String(rightValue ?? ""));
+  }
+  return 0;
+}
+function survivingHyperedges(hyperedges, sampledNodeIds) {
+  return hyperedges.filter((hyperedge) => hyperedge.nodeIds.filter((nodeId) => sampledNodeIds.has(nodeId)).length >= 2);
+}
+function pinnedNodeIdsForReport(report) {
+  if (!report) {
+    return /* @__PURE__ */ new Set();
+  }
+  return /* @__PURE__ */ new Set([
+    ...report.godNodes.map((node) => node.nodeId),
+    ...report.bridgeNodes.map((node) => node.nodeId),
+    ...report.surprisingConnections.flatMap((connection) => [connection.sourceNodeId, connection.targetNodeId])
+  ]);
+}
+function sampleGraphNodes(graph, report, nodeBudget = OVERVIEW_NODE_BUDGET) {
+  const pinned = pinnedNodeIdsForReport(report);
+  const nodeById2 = new Map(graph.nodes.map((node) => [node.id, node]));
+  const selected = new Set([...pinned].filter((nodeId) => nodeById2.has(nodeId)));
+  const sortedCommunities2 = [...graph.communities ?? []].sort((left, right) => {
+    const leftNodes = left.nodeIds.map((nodeId) => nodeById2.get(nodeId)).filter((node) => Boolean(node));
+    const rightNodes = right.nodeIds.map((nodeId) => nodeById2.get(nodeId)).filter((node) => Boolean(node));
+    const leftFirstParty = leftNodes.filter((node) => node.sourceClass === "first_party").length;
+    const rightFirstParty = rightNodes.filter((node) => node.sourceClass === "first_party").length;
+    return compareTuples(
+      [-leftFirstParty, -leftNodes.length, left.label, left.id],
+      [-rightFirstParty, -rightNodes.length, right.label, right.id]
+    );
+  });
+  for (const community of sortedCommunities2) {
+    const communityNodes = community.nodeIds.map((nodeId) => nodeById2.get(nodeId)).filter((node) => Boolean(node)).sort((left, right) => compareTuples(nodePriority(left, pinned), nodePriority(right, pinned)));
+    for (const node of communityNodes) {
+      if (selected.size >= nodeBudget && !pinned.has(node.id)) {
+        break;
+      }
+      selected.add(node.id);
+    }
+    if (selected.size >= nodeBudget) {
+      break;
+    }
+  }
+  if (selected.size < nodeBudget) {
+    for (const node of [...graph.nodes].sort((left, right) => compareTuples(nodePriority(left, pinned), nodePriority(right, pinned)))) {
+      if (selected.size >= nodeBudget && !pinned.has(node.id)) {
+        break;
+      }
+      selected.add(node.id);
+    }
+  }
+  return selected;
+}
+function buildViewerGraphArtifact(graph, options = {}) {
+  const threshold = options.threshold ?? OVERVIEW_THRESHOLD;
+  const nodeBudget = options.nodeBudget ?? OVERVIEW_NODE_BUDGET;
+  const totalCommunities = graph.communities?.length ?? 0;
+  if (options.full || graph.nodes.length <= threshold) {
+    return {
+      ...graph,
+      presentation: {
+        mode: "full",
+        threshold,
+        nodeBudget,
+        totalNodes: graph.nodes.length,
+        displayedNodes: graph.nodes.length,
+        totalEdges: graph.edges.length,
+        displayedEdges: graph.edges.length,
+        totalCommunities,
+        displayedCommunities: totalCommunities
+      }
+    };
+  }
+  const sampledNodeIds = sampleGraphNodes(graph, options.report, nodeBudget);
+  const nodes = graph.nodes.filter((node) => sampledNodeIds.has(node.id));
+  const edges = graph.edges.filter((edge) => sampledNodeIds.has(edge.source) && sampledNodeIds.has(edge.target));
+  const hyperedges = survivingHyperedges(graph.hyperedges ?? [], sampledNodeIds);
+  const communities = (graph.communities ?? []).map((community) => ({
+    ...community,
+    nodeIds: community.nodeIds.filter((nodeId) => sampledNodeIds.has(nodeId))
+  })).filter((community) => community.nodeIds.length > 0);
+  return {
+    ...graph,
+    nodes,
+    edges,
+    hyperedges,
+    communities,
+    presentation: {
+      mode: "overview",
+      threshold,
+      nodeBudget,
+      totalNodes: graph.nodes.length,
+      displayedNodes: nodes.length,
+      totalEdges: graph.edges.length,
+      displayedEdges: edges.length,
+      totalCommunities,
+      displayedCommunities: communities.length
+    }
+  };
+}
+
 // src/watch.ts
 import path26 from "path";
 import process3 from "process";
@@ -16449,7 +16943,7 @@ async function ensureViewerDist(viewerDistDir) {
     await execFileAsync("pnpm", ["build"], { cwd: viewerProjectDir });
   }
 }
-async function startGraphServer(rootDir, port) {
+async function startGraphServer(rootDir, port, options = {}) {
   const { config, paths } = await loadVaultConfig(rootDir);
   const effectivePort = port ?? config.viewer.port;
   await ensureViewerDist(paths.viewerDistDir);
@@ -16461,8 +16955,16 @@ async function startGraphServer(rootDir, port) {
         response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
         return;
       }
+      const graph = await readJsonFile(paths.graphPath);
+      if (!graph) {
+        response.writeHead(404, { "content-type": "application/json" });
+        response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
+        return;
+      }
+      const reportPath = path27.join(paths.wikiDir, "graph", "report.json");
+      const report = await readJsonFile(reportPath) ?? null;
       response.writeHead(200, { "content-type": "application/json" });
-      response.end(await fs22.readFile(paths.graphPath, "utf8"));
+      response.end(JSON.stringify(buildViewerGraphArtifact(graph, { report, full: options.full ?? false })));
       return;
     }
     if (url.pathname === "/api/graph/query") {
@@ -16638,7 +17140,7 @@ async function startGraphServer(rootDir, port) {
     }
   };
 }
-async function exportGraphHtml(rootDir, outputPath) {
+async function exportGraphHtml(rootDir, outputPath, options = {}) {
   const { paths } = await loadVaultConfig(rootDir);
   const graph = await readJsonFile(paths.graphPath);
   if (!graph) {
@@ -16682,7 +17184,11 @@ async function exportGraphHtml(rootDir, outputPath) {
   const script = await fs22.readFile(scriptPath, "utf8");
   const style = stylePath && await fileExists(stylePath) ? await fs22.readFile(stylePath, "utf8") : "";
   const report = await readJsonFile(path27.join(paths.wikiDir, "graph", "report.json"));
-  const embeddedData = JSON.stringify({ graph, pages: pages.filter(Boolean), report }, null, 2).replace(/</g, "\\u003c");
+  const embeddedData = JSON.stringify(
+    { graph: buildViewerGraphArtifact(graph, { report, full: options.full ?? false }), pages: pages.filter(Boolean), report },
+    null,
+    2
+  ).replace(/</g, "\\u003c");
   const html = [
     "<!doctype html>",
     '<html lang="en">',